Bootstrap and first implementation

2026-06-15 01:04:30 +02:00
parent ae89e76264
commit a28a79956b
12 changed files with 1313 additions and 15 deletions
--- a/registry/README.md
+++ b/registry/README.md
@@ -0,0 +1,136 @@
+# Capability Registry
+
+Markdown-first registry for reusable capabilities in the helix_forge domain.
+
+## Layout
+
+```text
+registry/
+├── README.md
+├── capabilities/
+│   └── capability.<domain>.<name>.md
+└── indexes/
+    └── capabilities.yaml
+```
+
+- **Entries** live in `capabilities/` as Markdown files with YAML front matter.
+- **Index** at `indexes/capabilities.yaml` is the fast discovery surface for
+  humans and agents.
+- **Schema** at `schemas/capability.schema.yaml` defines required front matter.
+- **Template** at `templates/capability-entry.template.md` is the authoring
+  starting point.
+
+## Add a new capability (D0/A0/C0/R0)
+
+1. Copy `templates/capability-entry.template.md` to
+   `registry/capabilities/capability.<domain>.<name>.md`.
+2. Set `id`, `name`, `summary`, `owner`, and `status: draft`.
+3. Initialize all four dimensions explicitly:
+   - `maturity.discovery.current: D0`
+   - `maturity.availability.current: A0`
+   - `external_evidence.completeness.level: C0`
+   - `external_evidence.reliability.level: R0`
+4. Add the entry to `registry/indexes/capabilities.yaml`.
+5. Run the manual validation checklist below.
+
+Missing evidence is acceptable in the MVP when it is explicit rather than hidden.
+
+## Manual validation checklist
+
+Use this checklist until an automated CLI validator exists.
+
+### Required fields
+
+- [ ] `id` matches `^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$`
+- [ ] `name`, `summary`, `owner`, and `status` are present
+- [ ] `maturity.discovery` and `maturity.availability` include `current` and `target`
+- [ ] `external_evidence.completeness.level` and `external_evidence.reliability.level` are present
+- [ ] Completeness and reliability are **not** nested under `maturity`
+
+### Enum checks
+
+Discovery levels: `D0`–`D7`  
+Availability levels: `A0`–`A7`  
+Completeness levels: `C0`–`C6`  
+Reliability levels: `R0`–`R6`  
+Entry status: `draft`, `reviewed`, `approved`, `deprecated`  
+Confidence: `low`, `medium`, `high`
+
+Definitions live in `specs/CapabilityMaturityStandard.md`.
+
+### Relation checks
+
+- [ ] Every relation target uses a valid capability ID format
+- [ ] Referenced capabilities exist in the index or are explicitly marked as external/planned
+- [ ] Cycles in `depends_on` are intentional and documented
+
+### Index checks
+
+- [ ] New entry appears in `indexes/capabilities.yaml`
+- [ ] `path` points to the correct Markdown file
+- [ ] `vector` matches the entry's current maturity levels
+
+## Search and filter guidance
+
+### UC-RS-004 — Search by planning need
+
+1. Read `indexes/capabilities.yaml` and scan `summary`, `tags`, and `vector`.
+2. Open candidate entries and review `discovery.intent`, `discovery.use_cases`,
+   and `discovery.includes`.
+3. Prefer entries with discovery `D3+` for roadmap work and `D5+` for MVP
+   selection.
+
+Example filter:
+
+```yaml
+discovery:
+  minimum: D4
+tags:
+  - identity
+```
+
+### UC-RS-005 — Search by consumption mode
+
+1. Filter the index by `consumption_modes` or availability level.
+2. Open entries and inspect `availability.current_artifacts`.
+3. Treat `A0` entries as planning-only; require `A2+` for code reuse and `A3+`
+   for automation.
+
+Example filter:
+
+```yaml
+availability:
+  minimum: A3
+consumption_modes:
+  - cli
+```
+
+### UC-RS-006 — Compare capability candidates
+
+Compare vectors side by side and read:
+
+- `discovery.includes` / `discovery.excludes` for overlap
+- `external_evidence.completeness` for expectation fit
+- `external_evidence.reliability` for consumer risk
+- `relations` for dependency and duplication signals
+
+### UC-RS-015 — Detect duplicate or overlapping capabilities
+
+Check for overlap in:
+
+- similar `name` or `summary`
+- shared `discovery.includes`
+- `relations.related_to` without clear specialization
+- duplicate tags and consumption modes with weak boundary differences
+
+When overlap is real, link entries with `relations.related_to`, `specializes`,
+or `generalizes` rather than creating silent duplicates.
+
+## Promote a capability
+
+1. Attach evidence appropriate to the target level in
+   `specs/CapabilityMaturityStandard.md`.
+2. Update `maturity` and/or `external_evidence` with rationale and confidence.
+3. Update `availability.current_artifacts` when a new consumption mode appears.
+4. Refresh the index `vector` and run the validation checklist.
+5. Set `status: reviewed` or `approved` when an assessor validates the entry.
--- a/registry/capabilities/capability.feature-control.evaluate.md
+++ b/registry/capabilities/capability.feature-control.evaluate.md
@@ -0,0 +1,138 @@
+---
+id: capability.feature-control.evaluate
+name: Feature Availability Evaluation
+summary: Evaluate whether a feature is active, hidden, disabled, or unavailable for a subject in context.
+owner: feature-control
+status: draft
+domain: helix_forge
+tags:
+  - feature-control
+  - evaluation
+  - sdk
+
+maturity:
+  discovery:
+    current: D5
+    target: D7
+    confidence: medium
+    rationale: >
+      Concrete use cases and research references are documented in the maturity
+      standard example and feature-control domain work.
+  availability:
+    current: A4
+    target: A6
+    confidence: medium
+    rationale: >
+      SDK and service API artifacts exist in the feature-control repository.
+      Managed platform operation is the natural target for multi-tenant reuse.
+
+external_evidence:
+  completeness:
+    level: C3
+    name: Functional Core
+    confidence: medium
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - tenant-level feature evaluation
+      - user-level feature evaluation
+      - machine-readable decision result
+    broken_expectations:
+      - no agent-specific rule simulation
+      - no bulk import/export of rules
+    out_of_scope_expectations:
+      - billing entitlement ownership
+      - authorization policy enforcement
+  reliability:
+    level: R3
+    name: Usable
+    confidence: medium
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - unclear timeout behavior under heavy load
+      - limited diagnostics for complex tenant rule conflicts
+
+discovery:
+  intent: >
+    Support controlled feature availability across installations, tenants,
+    domains, groups, users, and agents.
+  includes:
+    - feature decision evaluation
+    - context-aware targeting
+    - explainable decision result
+  excludes:
+    - user authorization
+    - billing entitlement ownership
+    - UI rendering
+  assumptions:
+    - subject and tenant context can be resolved by adjacent capabilities
+  use_cases:
+    - ucc.feature-control.tenant-toggle
+    - ucc.feature-control.agent-disable
+    - ucc.feature-control.domain-rollout
+  research_memos:
+    - specs/CapabilityMaturityStandard.md
+
+availability:
+  current_level: A4
+  target_level: A6
+  current_artifacts:
+    - feature-control/packages/feature-control-sdk
+    - feature-control/services/feature-control-api
+  target_artifacts:
+    - feature-control/charts/feature-control
+    - feature-control/platform/feature-control-service
+  consumption_modes:
+    - SDK
+    - service API
+    - managed platform service
+
+relations:
+  depends_on:
+    - capability.identity.vocabulary-canonicalize
+  supports:
+    - capability.registry.register
+  related_to:
+    - capability.feature-control.rollout
+    - capability.feature-control.visibility
+
+evidence:
+  documentation:
+    - specs/CapabilityMaturityStandard.md
+  tests: []
+  consumer_feedback: []
+  bug_reports: []
+  incidents: []
+
+consumer_guidance:
+  recommended_for:
+    - application integration through SDK or service API
+    - tenant-aware feature gating in helix_forge products
+  not_recommended_for:
+    - authorization decisions
+    - billing entitlement ownership
+    - assuming agent-specific simulation without checking current scope
+  known_limitations:
+    - bulk rule management is not yet covered
+    - agent-specific simulation remains a known gap
+---
+
+# Feature Availability Evaluation
+
+## Overview
+
+This capability evaluates whether a feature should be available for a subject in
+a given context. It is the primary implementation-ready example in the sample
+registry and demonstrates a D5/A4/C3/R3 vector.
+
+## Current reuse mode
+
+Consumers can integrate through SDK or service API artifacts in the
+feature-control repository. This is implementation reuse (A4), not just planning
+metadata.
+
+## Comparison notes
+
+Compared with `capability.registry.register`, this entry is far stronger on
+availability and external evidence. Compared with
+`capability.identity.vocabulary-canonicalize`, it is stronger on delivery mode
+and weaker on cross-domain generalization.
--- a/registry/capabilities/capability.identity.vocabulary-canonicalize.md
+++ b/registry/capabilities/capability.identity.vocabulary-canonicalize.md
@@ -0,0 +1,136 @@
+---
+id: capability.identity.vocabulary-canonicalize
+name: Identity Vocabulary Canonicalization
+summary: Define and maintain an implementation-neutral vocabulary for identity-related concepts across overlapping domains.
+owner: identity-canon
+status: draft
+domain: helix_forge
+tags:
+  - identity
+  - terminology
+  - research
+
+maturity:
+  discovery:
+    current: D4
+    target: D6
+    confidence: medium
+    rationale: >
+      identity-canon has researched overlapping terminology across IAM,
+      directory, federation, and authorization domains, but use-case saturation
+      is not yet demonstrated.
+  availability:
+    current: A0
+    target: A2
+    confidence: medium
+    rationale: >
+      The capability is available as research and canon documentation only.
+      Future source modules or libraries could raise availability to A2.
+
+external_evidence:
+  completeness:
+    level: C2
+    name: Partial
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - draft canonical glossary exists
+      - terminology conflict map exists
+      - conceptual model and scenario tests exist
+    broken_expectations:
+      - individual source notes are not fully backfilled
+      - many mappings remain candidate rather than finalized
+    out_of_scope_expectations:
+      - operating identity providers
+      - provisioning or authorization engines
+  reliability:
+    level: R0
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - draft canon terms may change as source evidence is backfilled
+
+discovery:
+  intent: >
+    Provide a reusable planning primitive for identity vocabulary so architects
+    and agents can compare overlapping terms consistently without collapsing
+    product-specific meanings into one ambiguous label.
+  includes:
+    - canonical glossary maintenance
+    - terminology conflict mapping
+    - conceptual model and scenario tests
+    - research corpus indexing
+  excludes:
+    - identity provider implementation
+    - account lifecycle services
+    - authorization policy enforcement
+  assumptions:
+    - external product mappings remain separate from canonical definitions
+  use_cases:
+    - UC-RS-004
+    - UC-RS-006
+  research_memos:
+    - identity-canon/ResearchProposal.md
+    - identity-canon/canon/CanonicalGlossary.md
+
+availability:
+  current_level: A0
+  target_level: A2
+  current_artifacts:
+    - identity-canon/canon/CanonicalGlossary.md
+    - identity-canon/terminology/TerminologyConflictMap.md
+    - identity-canon/model/ConceptualModel.md
+  target_artifacts:
+    - identity-canon/packages/identity-vocabulary
+  consumption_modes:
+    - informational
+    - markdown research artifacts
+
+relations:
+  depends_on: []
+  supports:
+    - capability.feature-control.evaluate
+    - capability.registry.register
+  related_to:
+    - capability.identity.subject-resolution
+
+evidence:
+  documentation:
+    - identity-canon/INTENT.md
+    - identity-canon/canon/CanonicalGlossary.md
+  tests: []
+  consumer_feedback: []
+  bug_reports: []
+  incidents: []
+
+consumer_guidance:
+  recommended_for:
+    - architecture and planning conversations involving overloaded identity terms
+    - comparing IAM, directory, and authorization vocabulary without forcing one product model
+  not_recommended_for:
+    - runtime identity resolution
+    - assuming draft canon entries are finalized standards
+  known_limitations:
+    - source-note backfill is incomplete
+    - mappings may remain candidate until evidence review completes
+---
+
+# Identity Vocabulary Canonicalization
+
+## Overview
+
+This capability makes identity vocabulary reusable for planning across adjacent
+domains. It is intentionally research-heavy and informational, illustrating a
+D4/A0/C2/R0 vector that contrasts with implementation-ready entries.
+
+## Current reuse mode
+
+Consumers read canon, terminology, and model artifacts in the identity-canon
+repository. The value is planning reuse through shared vocabulary, not runtime
+integration.
+
+## Relation to adjacent capabilities
+
+Feature-control evaluation depends on consistent subject and tenant concepts.
+This capability supports that planning layer without providing runtime identity
+services itself.
--- a/registry/capabilities/capability.registry.register.md
+++ b/registry/capabilities/capability.registry.register.md
@@ -0,0 +1,134 @@
+---
+id: capability.registry.register
+name: Capability Registration
+summary: Register a new capability so it becomes visible for planning and implementation reuse.
+owner: reuse-surface
+status: draft
+domain: helix_forge
+tags:
+  - registry
+  - governance
+  - meta
+
+maturity:
+  discovery:
+    current: D3
+    target: D5
+    confidence: medium
+    rationale: >
+      Core use case UC-RS-001 is documented in specs/UseCaseCatalog.md and the
+      registry model is bounded in INTENT.md, but concrete promotion workflows
+      are not yet grounded in registry artifacts.
+  availability:
+    current: A0
+    target: A3
+    confidence: medium
+    rationale: >
+      Registration is currently manual through Markdown entries and the index.
+      A CLI validator/query tool would raise availability to A3.
+
+external_evidence:
+  completeness:
+    level: C1
+    name: Fragmentary
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - capability IDs can be assigned in registry entries
+      - maturity vectors can be recorded at registration time
+    broken_expectations:
+      - no automated duplicate detection yet
+      - no promotion history tracking yet
+    out_of_scope_expectations:
+      - hosting registered capabilities
+      - enforcing implementation architecture
+  reliability:
+    level: R0
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - registry consistency depends on manual index maintenance
+
+discovery:
+  intent: >
+    Make a capability candidate visible in the registry so humans and agents can
+    discover, assess, compare, and reuse it instead of rebuilding it in isolation.
+  includes:
+    - stable capability ID assignment
+    - initial discovery and availability classification
+    - explicit completeness and reliability placeholders
+    - evidence and relation references
+  excludes:
+    - implementing the registered capability
+    - certifying implementation quality
+    - operating runtime services for registered capabilities
+  assumptions:
+    - unregistered capabilities are invisible for registry-driven reuse
+    - low-maturity entries are acceptable when evidence gaps are explicit
+  use_cases:
+    - UC-RS-001
+  research_memos:
+    - specs/UseCaseCatalog.md
+    - specs/ProductRequirementsDocument.md
+
+availability:
+  current_level: A0
+  target_level: A3
+  current_artifacts:
+    - templates/capability-entry.template.md
+    - registry/indexes/capabilities.yaml
+  target_artifacts:
+    - tools/validate-registry
+    - tools/query-registry
+  consumption_modes:
+    - informational
+    - markdown authoring
+
+relations:
+  depends_on: []
+  supports:
+    - capability.feature-control.evaluate
+    - capability.identity.vocabulary-canonicalize
+  related_to:
+    - capability.registry.validate
+
+evidence:
+  documentation:
+    - INTENT.md
+    - specs/UseCaseCatalog.md
+  tests: []
+  consumer_feedback: []
+  bug_reports: []
+  incidents: []
+
+consumer_guidance:
+  recommended_for:
+    - making a new capability visible at D0/A0/C0/R0 with minimal friction
+    - seeding planning discussions before implementation exists
+  not_recommended_for:
+    - treating registry presence as proof of implementation readiness
+    - skipping explicit evidence for maturity promotion
+  known_limitations:
+    - manual index updates are required after adding an entry
+    - duplicate detection is guidance-only in the MVP
+---
+
+# Capability Registration
+
+## Overview
+
+Registration is the entry point for reuse visibility. A capability that is not
+registered cannot be discovered through the registry surface, even if code or
+documentation exists elsewhere.
+
+## Current reuse mode
+
+Humans and agents add Markdown entries under `registry/capabilities/` and update
+`registry/indexes/capabilities.yaml`. This is informational reuse (A0): read,
+plan, and author entries.
+
+## Next promotion steps
+
+1. Attach concrete use cases and actors to reach D5.
+2. Add a CLI validator to reach A3.
+3. Record consumer expectations and broken expectations as external evidence.
--- a/registry/indexes/capabilities.yaml
+++ b/registry/indexes/capabilities.yaml
@@ -0,0 +1,38 @@
+# Manually maintained capability index for humans and agents.
+# Update this file whenever a capability is added, promoted, or deprecated.
+version: 1
+updated: "2026-06-15"
+domain: helix_forge
+capabilities:
+  - id: capability.registry.register
+    name: Capability Registration
+    summary: Register a new capability so it becomes visible for planning and implementation reuse.
+    vector: D3 / A0 / C1 / R0
+    domain: helix_forge
+    status: draft
+    owner: reuse-surface
+    path: registry/capabilities/capability.registry.register.md
+    tags: [registry, governance, meta]
+    consumption_modes: [informational, markdown authoring]
+
+  - id: capability.feature-control.evaluate
+    name: Feature Availability Evaluation
+    summary: Evaluate whether a feature is active, hidden, disabled, or unavailable for a subject in context.
+    vector: D5 / A4 / C3 / R3
+    domain: helix_forge
+    status: draft
+    owner: feature-control
+    path: registry/capabilities/capability.feature-control.evaluate.md
+    tags: [feature-control, evaluation, sdk]
+    consumption_modes: [SDK, service API]
+
+  - id: capability.identity.vocabulary-canonicalize
+    name: Identity Vocabulary Canonicalization
+    summary: Define and maintain an implementation-neutral vocabulary for identity-related concepts across overlapping domains.
+    vector: D4 / A0 / C2 / R0
+    domain: helix_forge
+    status: draft
+    owner: identity-canon
+    path: registry/capabilities/capability.identity.vocabulary-canonicalize.md
+    tags: [identity, terminology, research]
+    consumption_modes: [informational]