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/AGENTS.md
+++ b/AGENTS.md
@@ -101,6 +101,136 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \

 ---

+## Local Developer Workflow
+
+This repository is currently documentation-only. There is no package manifest,
+runtime application, build system, executable test suite, or formatter/linter
+configuration checked in.
+
+### Install
+
+No install step is required for normal repository work.
+
+### Build
+
+No build step exists. Treat Markdown, YAML, and workplan edits as source
+artifacts.
+
+### Test / lint
+
+There is no project test runner or markdown linter configured yet. Use these
+checks before closing a change:
+
+```bash
+# Confirm the repository file inventory still looks intentional
+rg --files
+
+# Catch whitespace errors in tracked and staged diffs
+git diff --check
+```
+
+When workplan files change, sync ADR-001 file state into State Hub:
+
+```bash
+curl -s -X POST "http://127.0.0.1:8000/repos/reuse-surface/sync?fix=true" \
+  | python3 -m json.tool
+```
+
+If the HTTP sync endpoint is unavailable, run the consistency script from the
+State Hub checkout:
+
+```bash
+cd ~/state-hub
+.venv/bin/python scripts/consistency_check.py --repo reuse-surface --fix
+.venv/bin/python scripts/consistency_check.py --repo reuse-surface
+```
+
+The generated instruction in older workplans says `make fix-consistency
+REPO=reuse-surface`; that is still valid when `uv` is installed and on PATH.
+On this workstation, the `.venv/bin/python` fallback has been verified.
+
+### Run
+
+There is no local service to run from this repository.
+
+### Documentation Review Checklist
+
+- Keep `INTENT.md`, `SCOPE.md`, and `specs/` aligned on the registry-first
+  reuse boundary.
+- Keep maturity definitions in `specs/CapabilityMaturityStandard.md` consistent
+  with `INTENT.md` and `specs/ProductRequirementsDocument.md`.
+- Keep registry entries, indexes, and schemas in `registry/`, `schemas/`, and
+  `templates/` current when capabilities change.
+- Record implementation ideas in workplans, not as premature runtime code in
+  this repository.
+
+---
+
+## Capability Registry
+
+Before building or documenting a new reusable behavior, query the registry to
+avoid duplication and to select the best existing capability for planning or
+implementation reuse.
+
+### Orient
+
+```bash
+# Fast discovery surface — read this first
+cat registry/indexes/capabilities.yaml
+
+# Authoring template and schema
+cat templates/capability-entry.template.md
+cat schemas/capability.schema.yaml
+
+# Validation and search guidance
+cat registry/README.md
+cat tools/README.md
+```
+
+### Query workflow
+
+1. Read `registry/indexes/capabilities.yaml`.
+2. Filter by `vector`, `tags`, `consumption_modes`, `domain`, or `summary`.
+3. Open only matching files under `registry/capabilities/`.
+4. Compare candidates using `discovery`, `external_evidence`, `availability`,
+   and `relations` from the entry front matter.
+5. Prefer planning reuse when discovery is strong (`D3+`, especially `D5+`).
+6. Prefer implementation reuse only when availability is consumable (`A2+` code,
+   `A3+` CLI, `A4+` API/SDK).
+
+### Add a new capability
+
+1. Search the index for overlap (UC-RS-015) before creating a new entry.
+2. Copy `templates/capability-entry.template.md` to
+   `registry/capabilities/capability.<domain>.<name>.md`.
+3. Start at `D0 / A0 / C0 / R0` when evidence is minimal; keep gaps explicit.
+4. Add the entry to `registry/indexes/capabilities.yaml`.
+5. Run the manual validation checklist in `registry/README.md`.
+
+### Promote a capability
+
+1. Attach evidence required by `specs/CapabilityMaturityStandard.md` for the
+   target level.
+2. Update `maturity` for discovery/availability and `external_evidence` for
+   completeness/reliability separately.
+3. Refresh the index `vector` and record rationale in the entry body.
+4. Do not treat higher availability as proof of reliability or completeness.
+
+### MVP acceptance mapping
+
+| Acceptance criterion | Registry surface |
+|---|---|
+| Add D0/A0/C0/R0 with minimal friction | template + index + registry README |
+| Promote through discovery levels | entry front matter + maturity standard |
+| Identify current consumption mode | `availability` + index `consumption_modes` |
+| Record expectations and broken expectations | `external_evidence.completeness` |
+| Record reliability evidence | `external_evidence.reliability` |
+| Search by maturity and availability | `indexes/capabilities.yaml` filters |
+| Compare candidates | entry vectors + relations + README guidance |
+| Avoid duplicate capabilities | index search before add |
+
+---
+
 ## Workplan Convention (ADR-001)

 Work items originate as files in this repo — not in the hub. The hub is a
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -1,32 +1,53 @@
 # SCOPE

-> This file was generated by `statehub register`. Refine it as the repository
-> boundaries become clearer.
-
 ## One-liner

 Capability registry for planning and implementation reuse based on discovery and delivery maturity.

 ## Core Idea

-reuse-surface exists to provide the capability described in INTENT.md.
+`reuse-surface` provides a registry-centric reuse layer for capabilities. It
+makes capabilities visible, comparable, assessable, and reusable for planning,
+implementation, and operation. A capability that is not registered is invisible
+for reuse within this product boundary.

 ## In Scope

- Maintain the repository's primary implementation.
- Keep docs, tests, and operational metadata current.
+- Maintain the capability maturity model, standards, schemas, registry formats,
+  examples, indexes, validation guidance, and agent instructions.
+- Keep `INTENT.md`, `specs/`, registry artifacts, and State Hub workplans
+  aligned on the registry-first reuse boundary.
+- Support humans and agents as registry consumers through Markdown-first
+  authoring and machine-readable metadata.
+- Record decisions, progress, and workplan status through State Hub.
+- Verify changes with documentation review, `git diff --check`, and ADR-001
+  consistency checks.

 ## Out of Scope

- Own unrelated adjacent systems.
- Make irreversible operational decisions without human approval.
+- Host or operate the registered capabilities themselves.
+- Replace package registries, service catalogs, issue trackers, or project
+  management systems.
+- Judge internal code quality as capability maturity.
+- Own unrelated adjacent systems or make irreversible operational decisions
+  without human approval.

 ## Current State

- Status: active; implementation and stability should be verified by the repo agent.
+- Status: active specification scaffold.
+- The repository is currently documentation-only. It has no package manifest,
+  build system, runtime app, or executable test suite.
+- `specs/` contains the product requirements, use case catalog, and capability
+  maturity standard. `INTENT.md` defines the registry model and guiding
+  principles.
+- `registry/`, `schemas/`, `templates/`, and `tools/` contain the MVP registry
+  foundation seeded by `REUSE-WP-0002`.

 ## Getting Oriented

 - Start with: INTENT.md
+- Product requirements: specs/ProductRequirementsDocument.md
+- Use cases: specs/UseCaseCatalog.md
+- Maturity standard: specs/CapabilityMaturityStandard.md
 - Agent instructions: AGENTS.md
- Workplans: workplans/
+- Workplans: workplans/
--- 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]
--- a/schemas/capability.schema.yaml
+++ b/schemas/capability.schema.yaml
@@ -0,0 +1,247 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://reuse-surface.local/schemas/capability.schema.yaml
+title: Capability Registry Entry
+description: >
+  JSON Schema for YAML front matter in Markdown capability entries under
+  registry/capabilities/. Aligns with specs/CapabilityMaturityStandard.md.
+type: object
+additionalProperties: false
+required:
+  - id
+  - name
+  - summary
+  - owner
+  - status
+  - maturity
+  - external_evidence
+properties:
+  id:
+    type: string
+    pattern: '^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$'
+    description: Stable reverse-domain capability identifier.
+  name:
+    type: string
+    minLength: 1
+  summary:
+    type: string
+    minLength: 1
+  owner:
+    type: string
+    minLength: 1
+  status:
+    type: string
+    enum: [draft, reviewed, approved, deprecated]
+  domain:
+    type: string
+    description: Optional domain or product scope for filtering.
+  tags:
+    type: array
+    items:
+      type: string
+  maturity:
+    type: object
+    additionalProperties: false
+    required: [discovery, availability]
+    properties:
+      discovery:
+        $ref: '#/$defs/internalMaturityDimension'
+      availability:
+        $ref: '#/$defs/internalMaturityDimension'
+  external_evidence:
+    type: object
+    additionalProperties: false
+    required: [completeness, reliability]
+    properties:
+      completeness:
+        $ref: '#/$defs/completenessEvidence'
+      reliability:
+        $ref: '#/$defs/reliabilityEvidence'
+  discovery:
+    type: object
+    additionalProperties: false
+    properties:
+      intent:
+        type: string
+      includes:
+        type: array
+        items:
+          type: string
+      excludes:
+        type: array
+        items:
+          type: string
+      assumptions:
+        type: array
+        items:
+          type: string
+      use_cases:
+        type: array
+        items:
+          type: string
+      research_memos:
+        type: array
+        items:
+          type: string
+  availability:
+    type: object
+    additionalProperties: false
+    properties:
+      current_level:
+        $ref: '#/$defs/availabilityLevel'
+      target_level:
+        $ref: '#/$defs/availabilityLevel'
+      current_artifacts:
+        type: array
+        items:
+          type: string
+      target_artifacts:
+        type: array
+        items:
+          type: string
+      consumption_modes:
+        type: array
+        items:
+          type: string
+  relations:
+    type: object
+    additionalProperties: false
+    properties:
+      depends_on:
+        $ref: '#/$defs/capabilityIdList'
+      supports:
+        $ref: '#/$defs/capabilityIdList'
+      used_by:
+        $ref: '#/$defs/capabilityIdList'
+      related_to:
+        $ref: '#/$defs/capabilityIdList'
+      specializes:
+        $ref: '#/$defs/capabilityIdList'
+      generalizes:
+        $ref: '#/$defs/capabilityIdList'
+      replaces:
+        $ref: '#/$defs/capabilityIdList'
+      wraps:
+        $ref: '#/$defs/capabilityIdList'
+  evidence:
+    type: object
+    additionalProperties: false
+    properties:
+      documentation:
+        type: array
+        items:
+          type: string
+      tests:
+        type: array
+        items:
+          type: string
+      consumer_feedback:
+        type: array
+        items:
+          type: string
+      bug_reports:
+        type: array
+        items:
+          type: string
+      incidents:
+        type: array
+        items:
+          type: string
+  consumer_guidance:
+    type: object
+    additionalProperties: false
+    properties:
+      recommended_for:
+        type: array
+        items:
+          type: string
+      not_recommended_for:
+        type: array
+        items:
+          type: string
+      known_limitations:
+        type: array
+        items:
+          type: string
+$defs:
+  confidence:
+    type: string
+    enum: [low, medium, high]
+  discoveryLevel:
+    type: string
+    enum: [D0, D1, D2, D3, D4, D5, D6, D7]
+  availabilityLevel:
+    type: string
+    enum: [A0, A1, A2, A3, A4, A5, A6, A7]
+  completenessLevel:
+    type: string
+    enum: [C0, C1, C2, C3, C4, C5, C6]
+  reliabilityLevel:
+    type: string
+    enum: [R0, R1, R2, R3, R4, R5, R6]
+  capabilityIdList:
+    type: array
+    items:
+      type: string
+      pattern: '^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$'
+  internalMaturityDimension:
+    type: object
+    additionalProperties: false
+    required: [current, target]
+    properties:
+      current:
+        oneOf:
+          - $ref: '#/$defs/discoveryLevel'
+          - $ref: '#/$defs/availabilityLevel'
+      target:
+        oneOf:
+          - $ref: '#/$defs/discoveryLevel'
+          - $ref: '#/$defs/availabilityLevel'
+      confidence:
+        $ref: '#/$defs/confidence'
+      rationale:
+        type: string
+  completenessEvidence:
+    type: object
+    additionalProperties: false
+    required: [level]
+    properties:
+      level:
+        $ref: '#/$defs/completenessLevel'
+      name:
+        type: string
+      confidence:
+        $ref: '#/$defs/confidence'
+      basis:
+        type: string
+      satisfied_expectations:
+        type: array
+        items:
+          type: string
+      broken_expectations:
+        type: array
+        items:
+          type: string
+      out_of_scope_expectations:
+        type: array
+        items:
+          type: string
+  reliabilityEvidence:
+    type: object
+    additionalProperties: false
+    required: [level]
+    properties:
+      level:
+        $ref: '#/$defs/reliabilityLevel'
+      name:
+        type: string
+      confidence:
+        $ref: '#/$defs/confidence'
+      basis:
+        type: string
+      evidence:
+        type: object
+        additionalProperties: true
+      known_reliability_risks:
+        type: array
+        items:
+          type: string
--- a/templates/capability-entry.template.md
+++ b/templates/capability-entry.template.md
@@ -0,0 +1,119 @@
+---
+# Copy this file to registry/capabilities/<id-with-dots-as-hyphens>.md
+# Replace placeholder values. Keep external_evidence separate from maturity.
+id: capability.domain.example
+name: Example Capability
+summary: One sentence describing what this capability enables.
+owner: team-or-person
+status: draft
+domain: helix_forge
+tags:
+  - example
+
+maturity:
+  discovery:
+    current: D0
+    target: D5
+    confidence: low
+    rationale: >
+      Explain why the current discovery level is defensible and what evidence
+      is still missing for promotion.
+  availability:
+    current: A0
+    target: A3
+    confidence: low
+    rationale: >
+      Explain the current consumption mode and the natural target availability.
+
+external_evidence:
+  completeness:
+    level: C0
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations: []
+    broken_expectations: []
+    out_of_scope_expectations: []
+  reliability:
+    level: R0
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks: []
+
+discovery:
+  intent: >
+    What this capability is meant to make possible for planners and consumers.
+  includes:
+    - behavior that belongs inside the capability
+  excludes:
+    - behavior explicitly outside the capability
+  assumptions:
+    - assumptions shaping the capability boundary
+  use_cases: []
+  research_memos: []
+
+availability:
+  current_level: A0
+  target_level: A3
+  current_artifacts: []
+  target_artifacts: []
+  consumption_modes:
+    - informational
+
+relations:
+  depends_on: []
+  supports: []
+  related_to: []
+
+evidence:
+  documentation: []
+  tests: []
+  consumer_feedback: []
+  bug_reports: []
+  incidents: []
+
+consumer_guidance:
+  recommended_for:
+    - describe suitable reuse scenarios
+  not_recommended_for:
+    - describe unsafe or weak reuse scenarios
+  known_limitations:
+    - list known gaps, risks, or missing evidence
+---
+
+# Example Capability
+
+## Overview
+
+Describe the capability in plain language for human readers. The YAML front
+matter above is the machine-readable source of truth for maturity, evidence,
+relations, and consumer guidance.
+
+## Assessment notes
+
+### Discovery
+
+Record why the selected discovery level is defensible. Link research memos,
+use cases, and scope boundaries that support promotion.
+
+### Availability
+
+Record how consumers can access the capability today and what artifact would
+raise availability to the target level.
+
+### Completeness
+
+Compare declared intent, current scope, and consumer expectations. Record broken
+expectations explicitly rather than hiding them.
+
+### Reliability
+
+Record consumer-relevant quality evidence. Do not confuse reliability with
+completeness or internal code quality.
+
+## Promotion checklist
+
+- [ ] ID follows `capability.<domain>.<name>` pattern
+- [ ] Maturity enums match `specs/CapabilityMaturityStandard.md`
+- [ ] `external_evidence` is populated separately from `maturity`
+- [ ] Relations reference valid capability IDs
+- [ ] Index entry added or updated in `registry/indexes/capabilities.yaml`
--- a/tools/README.md
+++ b/tools/README.md
@@ -0,0 +1,55 @@
+# Registry Tools
+
+Reference tooling for the capability registry. The MVP is document-first; this
+directory documents validation and query workflows until executable tools land.
+
+## Current MVP workflows
+
+| Workflow | Location | Mode |
+|---|---|---|
+| Add capability | `templates/capability-entry.template.md` | manual |
+| Discover capabilities | `registry/indexes/capabilities.yaml` | manual / agent |
+| Validate entry shape | `registry/README.md` checklist | manual |
+| Schema reference | `schemas/capability.schema.yaml` | manual |
+| Maturity definitions | `specs/CapabilityMaturityStandard.md` | manual |
+
+## Manual validation procedure
+
+1. Open the capability entry Markdown file.
+2. Compare YAML front matter against `schemas/capability.schema.yaml`.
+3. Run the checklist in `registry/README.md`.
+4. Confirm the index entry exists and the `vector` is current.
+5. Confirm relation targets exist or are intentionally external.
+
+## Planned tools (out of MVP scope)
+
+Future CLI commands may include:
+
+```bash
+# validate one entry or the whole registry
+reuse-surface validate registry/capabilities/
+
+# query by planning need, availability, or vector
+reuse-surface query --discovery-min D4 --tag identity
+
+# export machine-readable registry bundle
+reuse-surface export --format yaml
+```
+
+These are documented here as targets only. Do not assume they exist yet.
+
+## Agent query pattern
+
+Agents should start with the index, not individual entry files:
+
+1. Read `registry/indexes/capabilities.yaml`.
+2. Filter by `vector`, `tags`, `consumption_modes`, or `summary`.
+3. Open only the candidate entry paths.
+4. Before creating a new capability, search for overlap using the duplicate
+   guidance in `registry/README.md`.
+
+## Related use cases
+
+- UC-RS-013 — Use registry metadata in agentic coding
+- UC-RS-019 — Publish a machine-readable registry export
+- UC-RS-023 — Validate registry entries against schema
--- a/workplans/REUSE-WP-0001-statehub-bootstrap.md
+++ b/workplans/REUSE-WP-0001-statehub-bootstrap.md
@@ -4,11 +4,11 @@ type: workplan
 title: "Bootstrap State Hub integration"
 domain: helix_forge
 repo: reuse-surface
-status: ready
+status: finished
 owner: codex
 topic_slug: helix-forge
 created: "2026-06-14"
-updated: "2026-06-14"
+updated: "2026-06-15"
 state_hub_workstream_id: "293ef16d-c15b-41cc-9258-4a3a233f4bf2"
 ---

@@ -20,7 +20,7 @@ Capability registry for planning and implementation reuse based on discovery and

 ```task
 id: REUSE-WP-0001-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "18c811c8-f9f6-4452-b3f0-b713c91918a4"
 ```
@@ -28,11 +28,17 @@ state_hub_task_id: "18c811c8-f9f6-4452-b3f0-b713c91918a4"
 Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
 Replace generated placeholders with repo-specific facts where needed.

+Completed by reviewing the generated integration files, preserving
+`.custodian-brief.md` as generated output, and refining `SCOPE.md` to the
+actual registry-first repository boundary. `INTENT.md` already contained
+repo-specific intent and maturity model content; no placeholder replacement was
+needed there.
+
 ## Verify Local Developer Workflow

 ```task
 id: REUSE-WP-0001-T02
-status: todo
+status: done
 priority: high
 state_hub_task_id: "0877cf67-6abe-48c3-b76c-df552620d678"
 ```
@@ -41,11 +47,16 @@ Identify the repo's install, test, lint, build, and run commands. Add or refine
 those commands in the agent instructions so future coding sessions can verify
 changes confidently.

+Completed by adding the local developer workflow to `AGENTS.md`. The repository
+is documentation-only: no install, build, runtime service, package manifest, or
+configured test runner exists. Current verification is `rg --files`, `git diff
+--check`, and State Hub ADR-001 consistency sync after workplan changes.
+
 ## Seed First Real Workplan

 ```task
 id: REUSE-WP-0001-T03
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "f480aa11-f7e1-45fe-bf0b-4a3c164eb85b"
 ```
@@ -56,3 +67,7 @@ next change. After workplan file updates, run from `~/state-hub`:
 ```bash
 make fix-consistency REPO=reuse-surface
 ```
+
+Completed by `REUSE-WP-0002`, which seeds the MVP registry foundation:
+schema, templates, sample capabilities, index, validation guidance, and agent
+registry instructions.
--- a/workplans/REUSE-WP-0002-mvp-registry-foundation.md
+++ b/workplans/REUSE-WP-0002-mvp-registry-foundation.md
@@ -0,0 +1,129 @@
+---
+id: REUSE-WP-0002
+type: workplan
+title: "MVP registry foundation"
+domain: helix_forge
+repo: reuse-surface
+status: finished
+owner: codex
+topic_slug: helix-forge
+created: "2026-06-15"
+updated: "2026-06-15"
+state_hub_workstream_id: "32e0f249-65dd-4401-831c-736b229c5865"
+---
+
+# MVP registry foundation
+
+This workplan implements the first registry artifacts required by
+`specs/ProductRequirementsDocument.md` section 15 (MVP Requirements) and section
+16 (MVP Acceptance Criteria). The repository already has `INTENT.md`, the
+product requirements, use case catalog, and capability maturity standard under
+`specs/`. The remaining MVP work is to make the registry usable by humans and
+agents.
+
+## Design decisions
+
+- **Canonical format:** Markdown capability entries with YAML front matter under
+  `registry/capabilities/`. The index at `registry/indexes/capabilities.yaml`
+  is the machine-readable discovery surface for agents.
+- **Schema alignment:** Follow `INTENT.md` and `specs/CapabilityMaturityStandard.md`
+  section 10. Internal maturity uses `maturity.discovery` and
+  `maturity.availability`. Consumer evidence uses `external_evidence.completeness`
+  and `external_evidence.reliability` — not nested under `maturity`.
+- **Sample capabilities:** Seed three helix_forge entries illustrating different
+  vectors: registry meta (`capability.registry.register`), implementation-ready
+  feature control (`capability.feature-control.evaluate`), and research-heavy
+  identity canon (`capability.identity.vocabulary-canonicalize`).
+- **Validation:** Document manual validation rules in `registry/README.md` and
+  `tools/README.md` for MVP. Automated CLI validation is out of scope here.
+
+## Define Capability Schema
+
+```task
+id: REUSE-WP-0002-T01
+status: done
+priority: high
+state_hub_task_id: "431edb19-2166-4715-bb3d-4428149aa2bc"
+```
+
+Create `schemas/capability.schema.yaml` as a JSON Schema draft (YAML syntax)
+for registry entry front matter. Cover stable IDs, `maturity` (discovery and
+availability only), `external_evidence`, discovery scope fields, availability
+artifacts, relations, evidence references, and consumer guidance. Enum values
+must match `specs/CapabilityMaturityStandard.md`.
+
+## Create Capability Entry Template
+
+```task
+id: REUSE-WP-0002-T02
+status: done
+priority: high
+state_hub_task_id: "a4763385-954f-4141-9f16-a85e96704f46"
+```
+
+Create `templates/capability-entry.template.md` as the Markdown-first authoring
+template. Include YAML front matter with required fields, commented guidance
+for assessors, and placeholders for evidence, relations, and consumer guidance.
+The template must be consistent with the schema from T01.
+
+## Seed Sample Registry Entries
+
+```task
+id: REUSE-WP-0002-T03
+status: done
+priority: high
+state_hub_task_id: "96078fbb-f2cc-4d4f-ac7c-6a1744c33e0b"
+```
+
+Create three sample entries under `registry/capabilities/`:
+
+- `capability.registry.register.md` — D3/A0, meta registry capability
+- `capability.feature-control.evaluate.md` — D5/A4, implementation-ready example
+- `capability.identity.vocabulary-canonicalize.md` — D4/A0, research/planning example
+
+Each entry must conform to the schema and illustrate distinct maturity vectors.
+Include relations between entries where appropriate.
+
+## Build Capability Index
+
+```task
+id: REUSE-WP-0002-T04
+status: done
+priority: medium
+state_hub_task_id: "19e0d200-fe1f-4273-9f47-abdf4a67b517"
+```
+
+Create `registry/indexes/capabilities.yaml` as a manually maintained index.
+Include IDs, names, summaries, compact maturity vectors, domain, and paths to
+entry files. The index must list all three sample capabilities from T03.
+
+## Add Validation And Search Guidance
+
+```task
+id: REUSE-WP-0002-T05
+status: done
+priority: medium
+state_hub_task_id: "bf0dd838-9c13-480e-93b9-47d4ae5edc82"
+```
+
+Create `registry/README.md` and `tools/README.md` documenting:
+
+- Required and recommended fields
+- Manual validation checklist (schema enums, relation ID format, broken references)
+- Search/filter guidance for UC-RS-004, UC-RS-005, UC-RS-006, and UC-RS-015
+- How to add a D0/A0/C0/R0 entry with minimal friction (MVP acceptance criteria)
+
+## Extend Agent Registry Instructions
+
+```task
+id: REUSE-WP-0002-T06
+status: done
+priority: medium
+state_hub_task_id: "a78fc037-b432-4af3-a068-132690344bb2"
+```
+
+Add a **Capability Registry** section to `AGENTS.md` explaining how coding
+agents should orient to the registry, query the index, add or promote entries
+using the template, validate manually, and avoid duplicating existing
+capabilities. Reference paths created in earlier tasks and map guidance to MVP
+acceptance criteria in `specs/ProductRequirementsDocument.md` section 16.