Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage

Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
parent 80bccc4bbb
commit 0dbef6d1a3
20 changed files with 1051 additions and 165 deletions
--- a/.claude/ralph-loop.local.md
+++ b/.claude/ralph-loop.local.md
@@ -0,0 +1,21 @@
+---
+active: true
+iteration: 1
+session_id: 
+max_iterations: 20
+completion_promise: "HEUREKA"
+workplan_id: REUSE-WP-0003
+workplan_file: /home/worsch/reuse-surface/workplans/REUSE-WP-0003-intent-scope-gap-closure.md
+started_at: "2026-06-14T23:09:59Z"
+---
+
+Read the workplan at `/home/worsch/reuse-surface/workplans/REUSE-WP-0003-intent-scope-gap-closure.md`.
+
+If every task has `status: done` AND frontmatter `status: done`:
+run `rm -f .claude/ralph-loop.local.md` first (deactivates the loop so the stop hook exits cleanly),
+then output <promise>HEUREKA</promise>.
+
+Otherwise implement the next `todo` task as described in the workplan.
+Set task `in_progress` when starting, `done` when complete.
+When all tasks are done set frontmatter `status: done`.
+
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -103,29 +103,29 @@ 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.
+The repository is primarily documentation-first with a small Python CLI for
+registry validate, query, and export. There is no long-running service.

 ### Install

-No install step is required for normal repository work.
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```

 ### Build

-No build step exists. Treat Markdown, YAML, and workplan edits as source
+No separate build step. 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
+# Registry validation (schema + index drift)
+.venv/bin/reuse-surface validate

-# Catch whitespace errors in tracked and staged diffs
+# Repository hygiene
+rg --files
 git diff --check
 ```

@@ -178,6 +178,10 @@ implementation reuse.
 # Fast discovery surface — read this first
 cat registry/indexes/capabilities.yaml

+# CLI discovery and export
+.venv/bin/reuse-surface query --discovery-min D4
+.venv/bin/reuse-surface export --format yaml
+
 # Authoring template and schema
 cat templates/capability-entry.template.md
 cat schemas/capability.schema.yaml
@@ -189,7 +193,7 @@ cat tools/README.md

 ### Query workflow

-1. Read `registry/indexes/capabilities.yaml`.
+1. Run `.venv/bin/reuse-surface query` with filters, or read the index directly.
 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`,
@@ -205,7 +209,7 @@ cat tools/README.md
   `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`.
+5. Run `.venv/bin/reuse-surface validate`.

 ### Promote a capability

@@ -225,7 +229,7 @@ cat tools/README.md
 | 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 |
+| Search by maturity and availability | `reuse-surface query` or index filters |
 | Compare candidates | entry vectors + relations + README guidance |
 | Avoid duplicate capabilities | index search before add |

--- a/INTENT.md
+++ b/INTENT.md
@@ -205,10 +205,10 @@ maturity:

 external_evidence:
  completeness:
-    current: C1
+    level: C1
    confidence: low
  reliability:
-    current: R0
+    level: R0
    confidence: low

 discovery:
@@ -239,28 +239,40 @@ evidence:

 ## Initial Repository Role

-The initial role of `reuse-surface` is to define and maintain the capability registry model, standards, schemas, examples, and reference tooling.
+The initial role of `reuse-surface` is to define and maintain the capability
+registry model, standards, schemas, examples, and reference tooling.

-Likely early repository contents:
+Current repository layout (authoritative for delivery):

 ```text
 reuse-surface/
 ├── INTENT.md
-├── README.md
-├── standards/
+├── SCOPE.md
+├── AGENTS.md
+├── specs/
+│   ├── ProductRequirementsDocument.md
+│   ├── UseCaseCatalog.md
 │   └── CapabilityMaturityStandard.md
-├── registry/
-│   ├── capabilities.yaml
-│   └── examples/
 ├── schemas/
-│   └── capability.schema.json
+│   └── capability.schema.yaml
+├── templates/
+│   └── capability-entry.template.md
+├── registry/
+│   ├── README.md
+│   ├── capabilities/
+│   └── indexes/
+│       └── capabilities.yaml
 ├── docs/
 │   ├── CapabilityRegistryConcept.md
-│   └── CapabilityAssessmentGuide.md
+│   └── IntentScopeGapAnalysis.md
 └── tools/
    └── README.md
 ```

+See `SCOPE.md` for what is possible now versus planned. See
+`docs/IntentScopeGapAnalysis.md` for tracked gaps between intent and delivered
+scope.
+
 ## Success Criteria

 `reuse-surface` is successful when it helps humans and agents:
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -14,13 +14,14 @@ for reuse within this product boundary.
 ## In Scope

 - Maintain the capability maturity model, standards, schemas, registry formats,
-  sample entries, indexes, validation guidance, and agent instructions.
+  sample entries, indexes, validation guidance, CLI tooling, 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
+- Verify changes with `reuse-surface validate`, `git diff --check`, and ADR-001
  consistency checks.

 ## Out of Scope
@@ -34,53 +35,47 @@ for reuse within this product boundary.

 ## What Is Possible Now

-The MVP registry foundation is in place. Humans and agents can:
+The MVP registry foundation plus CLI tooling (REUSE-WP-0003) is in place. Humans
+and agents can:

- **Discover capabilities** via `registry/indexes/capabilities.yaml`
+- **Discover capabilities** via `registry/indexes/capabilities.yaml` or
+  `reuse-surface query`
 - **Add a new capability** at D0/A0/C0/R0 using
  `templates/capability-entry.template.md`
- **Promote capabilities** by updating front matter with evidence-backed
-  discovery, availability, completeness, and reliability levels
+- **Promote capabilities** with evidence, optional `promotion_history`, and index
+  vector updates
 - **Compare candidates** using maturity vectors, scope, relations, and consumer
-  guidance in entry files
+  guidance
 - **Record expectations** through `external_evidence.completeness` and
-  `external_evidence.reliability` fields
- **Validate entries manually** using the checklist in `registry/README.md`
-  against `schemas/capability.schema.yaml`
- **Avoid duplicates** by searching the index before creating new entries
+  `external_evidence.reliability`
+- **Validate entries automatically** with `reuse-surface validate`
+- **Export a machine-readable bundle** with `reuse-surface export`
+- **Avoid duplicates** by querying the index before creating new entries

-These workflows satisfy the MVP acceptance criteria in
-`specs/ProductRequirementsDocument.md` section 16 through manual, Git-friendly
-authoring. There is no CLI, API, or automated validator yet.
+Registry tooling availability is **A3** (CLI). The registry product itself is
+still documentation-first for authoring; consumption combines Markdown entries,
+the index, and CLI automation.

 ## What Is Not Possible Yet

- Automated schema validation or registry export
- CLI query/filter commands
 - Generated human-readable catalog site
 - Capability graph visualization
- Promotion history tracking or review workflows in tooling
+- Automated duplicate/overlap detection
 - Federation across repositories or organizations
+- CI integration or packaged releases beyond local `pip install -e .`

-See `tools/README.md` for planned tooling that remains out of scope for the
-current MVP.
+See `tools/README.md` for command reference.

 ## Current State

- Status: active MVP registry (documentation-only, A0 availability).
- The repository has no package manifest, build system, runtime app, or
-  executable test suite. Registry consumption is informational: read, author,
-  compare, and plan.
- Three sample capabilities are registered in `registry/capabilities/`:
-  - `capability.registry.register` — D3 / A0 / C1 / R0
-  - `capability.feature-control.evaluate` — D5 / A4 / C3 / R3
-  - `capability.identity.vocabulary-canonicalize` — D4 / A0 / C2 / R0
- `specs/` holds the product requirements, use case catalog, and maturity
-  standard. `schemas/`, `templates/`, `registry/`, and `tools/` hold the
-  registry authoring and validation surfaces.
- Bootstrap work (`REUSE-WP-0001`) and MVP registry foundation
-  (`REUSE-WP-0002`) are finished. The next work should expand registry coverage,
-  tighten validation, or add CLI tooling through new workplans.
+- Status: active MVP registry with CLI tooling.
+- Six helix_forge capabilities are registered in `registry/capabilities/`.
+- `reuse-surface` CLI provides `validate`, `query`, and `export` via
+  `pyproject.toml` and `reuse_surface/`.
+- `docs/CapabilityRegistryConcept.md` and `docs/IntentScopeGapAnalysis.md`
+  document onboarding and intent-scope tracking.
+- Finished workplans: `REUSE-WP-0001`, `REUSE-WP-0002`, `REUSE-WP-0003`.
+- **Self-assessed vector:** `D5 / A3 / C4 / R2` (see gap analysis).

 ## Repository Layout

@@ -89,32 +84,27 @@ reuse-surface/
 ├── INTENT.md
 ├── SCOPE.md
 ├── AGENTS.md
+├── pyproject.toml
+├── reuse_surface/
 ├── specs/
-│   ├── ProductRequirementsDocument.md
-│   ├── UseCaseCatalog.md
-│   └── CapabilityMaturityStandard.md
 ├── schemas/
-│   └── capability.schema.yaml
 ├── templates/
-│   └── capability-entry.template.md
 ├── registry/
-│   ├── README.md
-│   ├── capabilities/
-│   └── indexes/
-│       └── capabilities.yaml
+├── docs/
 ├── tools/
-│   └── README.md
 └── workplans/
 ```

 ## Getting Oriented

 - Start with: INTENT.md
+- Registry concept: docs/CapabilityRegistryConcept.md
 - Intent vs scope gaps: docs/IntentScopeGapAnalysis.md
 - Product requirements: specs/ProductRequirementsDocument.md
 - Use cases: specs/UseCaseCatalog.md
 - Maturity standard: specs/CapabilityMaturityStandard.md
 - Registry index: registry/indexes/capabilities.yaml
 - Registry guidance: registry/README.md
+- CLI reference: tools/README.md
 - Agent instructions: AGENTS.md
 - Workplans: workplans/
--- a/docs/CapabilityRegistryConcept.md
+++ b/docs/CapabilityRegistryConcept.md
@@ -0,0 +1,129 @@
+# Capability Registry Concept
+
+**Repository:** `reuse-surface`  
+**Audience:** Humans onboarding to the registry  
+**Companion docs:** `INTENT.md`, `SCOPE.md`, `specs/CapabilityMaturityStandard.md`
+
+---
+
+## 1. What problem this solves
+
+Reusable capabilities are often scattered across repositories, documents,
+prototypes, and services. Without a registry, teams and agents rediscover,
+duplicate, and inconsistently assess the same behaviors.
+
+`reuse-surface` makes capabilities **visible**, **comparable**, and **reusable**
+for planning and implementation through a registry-first reuse layer.
+
+> A capability that is not registered is invisible for registry-driven reuse.
+
+---
+
+## 2. Core principles
+
+### Registry first
+
+The registry is the boundary of practical reuse awareness. Analysis starts with
+what is registered, not with everything that might exist informally.
+
+### Reuse over inventory
+
+The goal is capability reuse, not a complete inventory of all work products.
+
+### Planning and implementation are different
+
+- **Planning reuse** feeds primarily on **Discovery** maturity (D0–D7).
+- **Implementation reuse** feeds primarily on **Availability** maturity (A0–A7).
+
+A capability may be well researched (D5) but only informational (A0). Another
+may be deployable (A4) but weakly bounded (D2). Compare both dimensions.
+
+### Internal and external evidence stay separate
+
+| Type | Dimensions | Question |
+|---|---|---|
+| Internal registry assessment | Discovery, Availability | How reusable is it for planning? How consumable is it? |
+| External consumer evidence | Completeness, Reliability | Does scope satisfy intent? Does it behave well in use? |
+
+Do not treat availability as reliability, or research depth as completeness.
+
+---
+
+## 3. Maturity vector
+
+A compact summary:
+
+```text
+D5 / A4 / C3 / R3
+```
+
+Vectors are descriptive, not grades. A research vocabulary capability may
+naturally target `D5 / A0 / C4 / R3`. A CLI tool may target `D5 / A3 / C5 / R5`.
+
+Canonical level definitions: `specs/CapabilityMaturityStandard.md`.
+
+---
+
+## 4. How the artifacts fit together
+
+```text
+templates/capability-entry.template.md   → authoring starting point
+registry/capabilities/*.md               → canonical entries (YAML front matter)
+registry/indexes/capabilities.yaml       → fast discovery index for agents
+schemas/capability.schema.yaml           → machine-readable entry contract
+registry/README.md                       → validation and search guidance
+tools/                                   → CLI validate, query, export
+```
+
+**Authoring flow**
+
+1. Search the index for overlap.
+2. Copy the template to `registry/capabilities/`.
+3. Fill maturity and evidence fields explicitly.
+4. Add an index row.
+5. Validate with `reuse-surface validate`.
+
+**Consumption flow**
+
+1. Read `registry/indexes/capabilities.yaml`.
+2. Filter by vector, tags, or consumption mode.
+3. Open candidate entry files for scope, relations, and guidance.
+4. Prefer planning reuse at D3+ and implementation reuse at A2+.
+
+---
+
+## 5. What is manual vs automated today
+
+See `SCOPE.md` for the live boundary. In summary:
+
+| Activity | Mode |
+|---|---|
+| Discover capabilities | Index + `reuse-surface query` |
+| Add or promote entries | Markdown authoring + index update |
+| Validate shape | `reuse-surface validate` |
+| Export for agents | `reuse-surface export` |
+| Promotion history | Optional `promotion_history` in entries |
+| Graph visualization, federation, CI gates | Not yet available |
+
+---
+
+## 6. When to register a capability
+
+Register when a bounded reusable behavior should be:
+
+- discoverable for roadmap or architecture planning
+- comparable to adjacent capabilities
+- consumable through known artifacts (now or later)
+- assessed with explicit evidence over time
+
+Do not register one-off features, tickets, or internal code modules unless they
+represent a reusable capability boundary.
+
+---
+
+## 7. Further reading
+
+- Product requirements: `specs/ProductRequirementsDocument.md`
+- Use cases: `specs/UseCaseCatalog.md`
+- Intent vs delivered scope: `docs/IntentScopeGapAnalysis.md`
+- Agent workflows: `AGENTS.md`
--- a/docs/IntentScopeGapAnalysis.md
+++ b/docs/IntentScopeGapAnalysis.md
@@ -13,25 +13,21 @@ current delivered scope so future workplans can close them deliberately.

 `INTENT.md` describes the long-term capability registry product: a reuse surface
 that makes capabilities visible, assessable, and consumable across planning and
-implementation. `SCOPE.md` describes what the repository actually delivers today:
-an MVP registry foundation at **A0 availability** with manual, Markdown-first
-workflows.
+implementation. `SCOPE.md` describes what the repository actually delivers today: an MVP registry
+with **A3 CLI tooling** (`validate`, `query`, `export`) atop Markdown-first
+authoring.

 The two documents are **directionally aligned** on registry-first reuse, four
-maturity dimensions, and human/agent consumers. The main gaps are:
+maturity dimensions, and human/agent consumers. REUSE-WP-0003 closed the
+priority gaps from section 8. Remaining gaps are primarily scale, automation,
+and presentation concerns:

-1. **Delivery depth** — INTENT promises eventual technical foundation and broad
-   planning/implementation support; SCOPE delivers informational tooling only.
-2. **Structural drift** — INTENT's expected repository layout and entry shape
-   differ from the implemented layout and schema in small but important ways.
-3. **Evidence and operations** — INTENT emphasizes consumer evidence and
-   progress tracking; SCOPE has no reliability evidence, promotion history, or
-   automated validation yet.
-4. **Document cross-coverage** — SCOPE operationalizes State Hub, MVP acceptance
-   criteria, and helix_forge domain context that INTENT does not mention; INTENT
-   carries success criteria and conceptual depth that SCOPE does not restate.
+1. **Planning analytics** — no gap reports, overlap detection, or catalog site.
+2. **Reliability depth** — registry product dogfood evidence is early (R2).
+3. **Document cross-coverage** — SCOPE still carries operational detail INTENT
+   omits; INTENT success criteria are not fully enumerated in SCOPE.

-**Current reuse-surface vector (self-assessment):** `D4 / A0 / C3 / R0`
+**Current reuse-surface vector (self-assessment):** `D5 / A3 / C4 / R2`

 ---

@@ -256,18 +252,25 @@ own evidence (e.g. feature-control at R3).

 ## 8. Priority Gap Closure Order

-Recommended sequence for future workplans:
+| Priority | Gap | Outcome | Status |
+|---|---|---|---|
+| 1 | INTENT layout stale | INTENT layout aligned to delivered structure | Closed (WP-0003) |
+| 2 | No automated validation | `reuse-surface validate` | Closed (WP-0003) |
+| 3 | Thin registry coverage | Six helix_forge entries | Closed (WP-0003) |
+| 4 | Missing concept docs | `docs/CapabilityRegistryConcept.md` | Closed (WP-0003) |
+| 5 | No promotion history | `promotion_history` in schema/template | Closed (WP-0003) |
+| 6 | Search/filter manual only | `reuse-surface query` | Closed (WP-0003) |
+| 7 | No registry export | `reuse-surface export` | Closed (WP-0003) |
+| 8 | Self-reliability evidence | `capability.registry.register` at R2; friction recorded | Closed (WP-0003) |
+
+### Next recommended work

 | Priority | Gap | Suggested outcome |
 |---|---|---|
-| 1 | INTENT layout stale | Update INTENT "Initial Repository Role" to match `SCOPE.md` layout |
-| 2 | No automated validation | CLI or script: validate entries against schema |
-| 3 | Thin registry coverage | Register additional helix_forge capabilities beyond 3 samples |
-| 4 | Missing concept docs | Add `docs/CapabilityRegistryConcept.md` distilled from INTENT |
-| 5 | No promotion history | Add `promotion_history` to schema or separate changelog |
-| 6 | Search/filter manual only | CLI `query` with discovery/availability filters |
-| 7 | No registry export | YAML/JSON bundle export for agents (UC-RS-019) |
-| 8 | Self-reliability evidence | Dogfood registry; record friction as reliability evidence |
+| 9 | Catalog site | Static browsable capability catalog (UC-RS-018) |
+| 10 | Overlap detection | CLI or report for duplicate/overlapping capabilities |
+| 11 | CI validation | Run `reuse-surface validate` in CI on registry changes |
+| 12 | Registry federation | Cross-repo capability index composition |

 ---

@@ -286,3 +289,4 @@ Recommended sequence for future workplans:
 | Date | Change |
 |---|---|
 | 2026-06-15 | Initial analysis after REUSE-WP-0002 completion |
+| 2026-06-15 | REUSE-WP-0003 closed priority gaps 1–8; vector updated to D5/A3/C4/R2 |
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reuse-surface"
+version = "0.1.0"
+description = "Capability registry tooling for reuse-surface"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "jsonschema>=4.0",
+  "pyyaml>=6.0",
+]
+
+[project.scripts]
+reuse-surface = "reuse_surface.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["reuse_surface*"]
--- a/registry/README.md
+++ b/registry/README.md
@@ -74,7 +74,8 @@ Definitions live in `specs/CapabilityMaturityStandard.md`.

 ### UC-RS-004 — Search by planning need

-1. Read `indexes/capabilities.yaml` and scan `summary`, `tags`, and `vector`.
+1. Run `reuse-surface query --discovery-min D4` or read the index 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
@@ -131,6 +132,8 @@ or `generalizes` rather than creating silent duplicates.
 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.
+3. Append a `promotion_history` record with `date`, `dimension`, `from`, `to`,
+   and `rationale` (optional `author`).
+4. Update `availability.current_artifacts` when a new consumption mode appears.
+5. Refresh the index `vector` and run `reuse-surface validate`.
+6. Set `status: reviewed` or `approved` when an assessor validates the entry.
--- a/registry/capabilities/capability.feature-control.rollout.md
+++ b/registry/capabilities/capability.feature-control.rollout.md
@@ -0,0 +1,111 @@
+---
+id: capability.feature-control.rollout
+name: Feature Rollout Control
+summary: Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules and staged availability.
+owner: feature-control
+status: draft
+domain: helix_forge
+tags:
+  - feature-control
+  - rollout
+  - planning
+
+maturity:
+  discovery:
+    current: D4
+    target: D6
+    confidence: medium
+    rationale: >
+      Rollout is a distinct bounded behavior from single-point evaluation, with
+      research references in the feature-control domain and maturity standard.
+  availability:
+    current: A2
+    target: A4
+    confidence: low
+    rationale: >
+      Rollout logic may exist in source modules but is not yet consistently
+      exposed as a standalone SDK or API surface distinct from evaluate.
+
+external_evidence:
+  completeness:
+    level: C2
+    name: Partial
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - rollout concepts documented adjacent to feature evaluation
+    broken_expectations:
+      - no dedicated rollout artifact called out separately from evaluate
+      - percentage and cohort rollout variants not indexed independently
+    out_of_scope_expectations:
+      - billing-driven entitlements
+  reliability:
+    level: R1
+    name: Fragile
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - rollout behavior may be conflated with evaluate in consumer mental models
+
+discovery:
+  intent: >
+    Control how features become available over time and across cohorts without
+    conflating rollout policy with authorization or billing.
+  includes:
+    - staged rollout rules
+    - cohort and context targeting for rollout
+    - explainable rollout state
+  excludes:
+    - one-time feature evaluation only
+    - authorization decisions
+    - billing entitlements
+  assumptions:
+    - feature evaluation capability exists for final availability decisions
+  use_cases:
+    - ucc.feature-control.domain-rollout
+  research_memos:
+    - specs/CapabilityMaturityStandard.md
+
+availability:
+  current_level: A2
+  target_level: A4
+  current_artifacts:
+    - feature-control/packages/feature-control-sdk
+  target_artifacts:
+    - feature-control/services/feature-control-api
+  consumption_modes:
+    - source module
+    - SDK
+
+relations:
+  depends_on:
+    - capability.feature-control.evaluate
+  supports: []
+  related_to:
+    - capability.feature-control.visibility
+
+evidence:
+  documentation:
+    - specs/CapabilityMaturityStandard.md
+  tests: []
+  consumer_feedback: []
+  bug_reports: []
+  incidents: []
+
+consumer_guidance:
+  recommended_for:
+    - planning staged feature exposure separate from binary evaluation
+  not_recommended_for:
+    - simple on/off evaluation without rollout semantics
+    - entitlement or billing ownership
+  known_limitations:
+    - distinguish carefully from capability.feature-control.evaluate
+---
+
+# Feature Rollout Control
+
+## Overview
+
+Rollout governs how availability changes over time and across cohorts. It
+complements evaluation, which answers whether a feature is available for a
+subject in a context right now.
--- a/registry/capabilities/capability.identity.subject-resolution.md
+++ b/registry/capabilities/capability.identity.subject-resolution.md
@@ -0,0 +1,115 @@
+---
+id: capability.identity.subject-resolution
+name: Identity Subject Resolution
+summary: Resolve who or what is acting in a context by mapping principals, accounts, actors, and identifiers to a stable subject model.
+owner: identity-canon
+status: draft
+domain: helix_forge
+tags:
+  - identity
+  - subject
+  - architecture
+
+maturity:
+  discovery:
+    current: D3
+    target: D5
+    confidence: medium
+    rationale: >
+      Subject/principal terminology is explored in identity-canon conflict maps
+      and conceptual model, but dedicated use-case grounding is incomplete.
+  availability:
+    current: A0
+    target: A4
+    confidence: low
+    rationale: >
+      Canon and research artifacts exist; no standalone resolver service or SDK
+      is registered yet.
+
+external_evidence:
+  completeness:
+    level: C1
+    name: Fragmentary
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - overloaded subject and principal terms are mapped as candidates
+    broken_expectations:
+      - no runtime resolver artifact
+      - canonical subject model not finalized across all actor types
+    out_of_scope_expectations:
+      - authentication protocol implementation
+      - credential storage
+  reliability:
+    level: R0
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - draft terminology may change during source-note backfill
+
+discovery:
+  intent: >
+    Give planners and implementers a consistent subject concept for authorization,
+    feature control, tenancy, and agent workflows without collapsing product-specific
+    identity models.
+  includes:
+    - subject vs principal vs account distinctions
+    - actor type modeling
+    - identifier resolution concepts
+  excludes:
+    - authentication execution
+    - credential issuance
+    - directory provisioning
+  assumptions:
+    - vocabulary canonicalization supports but does not replace subject resolution
+  use_cases:
+    - UC-RS-004
+  research_memos:
+    - identity-canon/terminology/TerminologyConflictMap.md
+    - identity-canon/model/ConceptualModel.md
+
+availability:
+  current_level: A0
+  target_level: A4
+  current_artifacts:
+    - identity-canon/model/ConceptualModel.md
+    - identity-canon/canon/CanonicalGlossary.md
+  target_artifacts:
+    - identity-canon/packages/subject-resolution-sdk
+  consumption_modes:
+    - informational
+
+relations:
+  depends_on:
+    - capability.identity.vocabulary-canonicalize
+  supports:
+    - capability.feature-control.evaluate
+    - capability.statehub.workstream-coordinate
+  related_to: []
+
+evidence:
+  documentation:
+    - identity-canon/canon/CanonicalGlossary.md
+    - identity-canon/scenarios/ScenarioTests.md
+  tests: []
+  consumer_feedback: []
+  bug_reports: []
+  incidents: []
+
+consumer_guidance:
+  recommended_for:
+    - architecture planning where subject/principal/account terms overlap
+  not_recommended_for:
+    - runtime authentication or token validation
+    - treating draft canon as finalized resolver behavior
+  known_limitations:
+    - resolver artifacts are not yet available
+---
+
+# Identity Subject Resolution
+
+## Overview
+
+Subject resolution defines how actors and identifiers map to a stable subject
+concept for downstream capabilities such as feature evaluation and coordination.
+Today this capability is planning-heavy (D3/A0).
--- a/registry/capabilities/capability.registry.register.md
+++ b/registry/capabilities/capability.registry.register.md
@@ -20,34 +20,38 @@ maturity:
      registry model is bounded in INTENT.md, but concrete promotion workflows
      are not yet grounded in registry artifacts.
  availability:
-    current: A0
+    current: A3
    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.
+      Registration and maintenance are automatable through the reuse-surface CLI
+      for validate, query, and export workflows.

 external_evidence:
  completeness:
-    level: C1
-    name: Fragmentary
-    confidence: low
+    level: C2
+    name: Partial
+    confidence: medium
    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
+      - CLI validate, query, and export support registry workflows
+      - promotion history can be recorded in entries
    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
+    level: R2
+    name: Tolerable
+    confidence: medium
    basis: consumer_quality_signals
    known_reliability_risks:
-      - registry consistency depends on manual index maintenance
+      - index drift still possible if authors skip validate
+      - CLI requires local venv install
+      - schema ID pattern required a fix during WP-0003 dogfooding

 discovery:
  intent: >
@@ -72,17 +76,17 @@ discovery:
    - specs/ProductRequirementsDocument.md

 availability:
-  current_level: A0
+  current_level: A3
  target_level: A3
  current_artifacts:
    - templates/capability-entry.template.md
    - registry/indexes/capabilities.yaml
-  target_artifacts:
-    - tools/validate-registry
-    - tools/query-registry
+    - reuse_surface/cli.py
+  target_artifacts: []
  consumption_modes:
    - informational
    - markdown authoring
+    - cli

 relations:
  depends_on: []
@@ -111,6 +115,26 @@ consumer_guidance:
  known_limitations:
    - manual index updates are required after adding an entry
    - duplicate detection is guidance-only in the MVP
+
+promotion_history:
+  - date: "2026-06-14"
+    dimension: discovery
+    from: D0
+    to: D1
+    rationale: Added name, summary, and registry-first intent from INTENT.md.
+    author: reuse-surface
+  - date: "2026-06-15"
+    dimension: discovery
+    from: D1
+    to: D3
+    rationale: Bounded scope with UC-RS-001 and MVP registry artifacts in specs/.
+    author: reuse-surface
+  - date: "2026-06-15"
+    dimension: availability
+    from: A0
+    to: A3
+    rationale: reuse-surface CLI shipped validate, query, and export commands.
+    author: reuse-surface
 ---

 # Capability Registration
--- a/registry/capabilities/capability.statehub.workstream-coordinate.md
+++ b/registry/capabilities/capability.statehub.workstream-coordinate.md
@@ -0,0 +1,117 @@
+---
+id: capability.statehub.workstream-coordinate
+name: Workstream And Task Coordination
+summary: Track active workstreams, tasks, progress, and consistency across domain repositories through a local-first coordination service.
+owner: state-hub
+status: draft
+domain: helix_forge
+tags:
+  - state-hub
+  - coordination
+  - workplans
+
+maturity:
+  discovery:
+    current: D4
+    target: D5
+    confidence: medium
+    rationale: >
+      State Hub intent, scope, and ADR-001 workplan conventions are documented;
+      concrete agent workflows are still being standardized across repos.
+  availability:
+    current: A4
+    target: A6
+    confidence: medium
+    rationale: >
+      Consumers integrate through the State Hub HTTP API and custodian scripts.
+      Managed platform operation is the natural target for multi-repo agents.
+
+external_evidence:
+  completeness:
+    level: C3
+    name: Functional Core
+    confidence: medium
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - workstream and task tracking via HTTP API
+      - workplan file to database consistency sync
+      - progress event logging
+    broken_expectations:
+      - no native MCP server for all agent environments
+    out_of_scope_expectations:
+      - replacing git-backed workplan canon
+      - identity authority
+  reliability:
+    level: R2
+    name: Tolerable
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - depends on local hub availability and operator maintenance
+
+discovery:
+  intent: >
+    Give agents and operators a live, queryable memory of work across domains
+    without replacing file-backed workplans and governance canon.
+  includes:
+    - workstream and task indexing
+    - progress and decision events
+    - repo consistency synchronization
+    - inbox and human-review flags
+  excludes:
+    - canon ownership
+    - task factory for all work origins
+    - identity authority
+  assumptions:
+    - workplans remain authoritative in git for ADR-001 repos
+  use_cases:
+    - UC-RS-013
+  research_memos:
+    - state-hub/INTENT.md
+
+availability:
+  current_level: A4
+  target_level: A6
+  current_artifacts:
+    - state-hub/api/
+    - state-hub/scripts/consistency_check.py
+  target_artifacts:
+    - state-hub/platform/state-hub-service
+  consumption_modes:
+    - service API
+    - HTTP REST
+
+relations:
+  depends_on: []
+  supports:
+    - capability.registry.register
+  related_to:
+    - capability.statehub.progress-log
+
+evidence:
+  documentation:
+    - state-hub/INTENT.md
+    - state-hub/AGENTS.md
+  tests: []
+  consumer_feedback: []
+  bug_reports: []
+  incidents: []
+
+consumer_guidance:
+  recommended_for:
+    - cross-repo agent orientation and task status sync
+    - logging progress after workplan changes
+  not_recommended_for:
+    - storing canonical requirements or architecture canon
+    - assuming hub state overrides git workplan files
+  known_limitations:
+    - requires running State Hub locally or via tunnel
+---
+
+# Workstream And Task Coordination
+
+## Overview
+
+State Hub provides live coordination for helix_forge repositories while
+workplans remain file-backed. This entry represents the service/API consumption
+mode for cross-repo agent work.
--- a/registry/indexes/capabilities.yaml
+++ b/registry/indexes/capabilities.yaml
@@ -7,13 +7,13 @@ 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
+    vector: D3 / A3 / C2 / R2
    domain: helix_forge
    status: draft
    owner: reuse-surface
    path: registry/capabilities/capability.registry.register.md
    tags: [registry, governance, meta]
-    consumption_modes: [informational, markdown authoring]
+    consumption_modes: [informational, markdown authoring, cli]

  - id: capability.feature-control.evaluate
    name: Feature Availability Evaluation
@@ -26,6 +26,17 @@ capabilities:
    tags: [feature-control, evaluation, sdk]
    consumption_modes: [SDK, service API]

+  - id: capability.feature-control.rollout
+    name: Feature Rollout Control
+    summary: Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules and staged availability.
+    vector: D4 / A2 / C2 / R1
+    domain: helix_forge
+    status: draft
+    owner: feature-control
+    path: registry/capabilities/capability.feature-control.rollout.md
+    tags: [feature-control, rollout, planning]
+    consumption_modes: [source module, SDK]
+
  - id: capability.identity.vocabulary-canonicalize
    name: Identity Vocabulary Canonicalization
    summary: Define and maintain an implementation-neutral vocabulary for identity-related concepts across overlapping domains.
@@ -36,3 +47,25 @@ capabilities:
    path: registry/capabilities/capability.identity.vocabulary-canonicalize.md
    tags: [identity, terminology, research]
    consumption_modes: [informational]
+
+  - id: capability.identity.subject-resolution
+    name: Identity Subject Resolution
+    summary: Resolve who or what is acting in a context by mapping principals, accounts, actors, and identifiers to a stable subject model.
+    vector: D3 / A0 / C1 / R0
+    domain: helix_forge
+    status: draft
+    owner: identity-canon
+    path: registry/capabilities/capability.identity.subject-resolution.md
+    tags: [identity, subject, architecture]
+    consumption_modes: [informational]
+
+  - id: capability.statehub.workstream-coordinate
+    name: Workstream And Task Coordination
+    summary: Track active workstreams, tasks, progress, and consistency across domain repositories through a local-first coordination service.
+    vector: D4 / A4 / C3 / R2
+    domain: helix_forge
+    status: draft
+    owner: state-hub
+    path: registry/capabilities/capability.statehub.workstream-coordinate.md
+    tags: [state-hub, coordination, workplans]
+    consumption_modes: [service API, HTTP REST]
--- a/reuse_surface/init.py
+++ b/reuse_surface/init.py
@@ -0,0 +1 @@
+"""Registry CLI for reuse-surface."""
--- a/reuse_surface/cli.py
+++ b/reuse_surface/cli.py
@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import Draft202012Validator
+
+from reuse_surface.registry import (
+    CAPABILITIES_DIR,
+    INDEX_PATH,
+    ROOT,
+    capability_paths,
+    level_at_least,
+    load_index,
+    load_schema,
+    parse_front_matter,
+    parse_vector,
+)
+
+
+def _check_index_drift(entry_paths: list[Path], index: dict[str, Any]) -> list[str]:
+    warnings: list[str] = []
+    indexed_paths = {item["path"] for item in index.get("capabilities", [])}
+    file_paths = {str(path.relative_to(ROOT)) for path in entry_paths}
+    for path in sorted(file_paths - indexed_paths):
+        warnings.append(f"index drift: entry file not indexed: {path}")
+    for path in sorted(indexed_paths - file_paths):
+        warnings.append(f"index drift: index references missing file: {path}")
+    return warnings
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    schema = load_schema()
+    validator = Draft202012Validator(schema)
+    target = Path(args.path) if args.path else None
+    paths = capability_paths(target)
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    for path in paths:
+        try:
+            data = parse_front_matter(path)
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        for error in sorted(validator.iter_errors(data), key=lambda e: e.path):
+            location = ".".join(str(part) for part in error.path) or "<root>"
+            errors.append(f"{path}: {location}: {error.message}")
+
+    if not target:
+        index = load_index()
+        warnings.extend(_check_index_drift(paths, index))
+
+    for warning in warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+    for error in errors:
+        print(f"error: {error}", file=sys.stderr)
+
+    if errors:
+        return 1
+    print(f"ok: validated {len(paths)} capability entr{'y' if len(paths) == 1 else 'ies'}")
+    return 0
+
+
+def _matches_query(item: dict[str, Any], args: argparse.Namespace) -> bool:
+    vector = parse_vector(item["vector"])
+    if args.discovery_min and not level_at_least(
+        "discovery", vector["discovery"], args.discovery_min
+    ):
+        return False
+    if args.availability_min and not level_at_least(
+        "availability", vector["availability"], args.availability_min
+    ):
+        return False
+    if args.domain and item.get("domain") != args.domain:
+        return False
+    if args.tag and args.tag not in item.get("tags", []):
+        return False
+    if args.consumption_mode:
+        modes = [mode.lower() for mode in item.get("consumption_modes", [])]
+        if args.consumption_mode.lower() not in modes:
+            return False
+    if args.keyword:
+        haystack = " ".join(
+            [
+                item.get("id", ""),
+                item.get("name", ""),
+                item.get("summary", ""),
+                " ".join(item.get("tags", [])),
+            ]
+        ).lower()
+        if args.keyword.lower() not in haystack:
+            return False
+    return True
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    index = load_index()
+    matches = [
+        item for item in index.get("capabilities", []) if _matches_query(item, args)
+    ]
+    if not matches:
+        print("no matches")
+        return 0
+    for item in matches:
+        print(
+            f"{item['id']}  {item['vector']}  {item['path']}\n"
+            f"  {item['summary']}"
+        )
+    print(f"\n{len(matches)} match{'es' if len(matches) != 1 else ''}")
+    return 0
+
+
+def cmd_export(args: argparse.Namespace) -> int:
+    index = load_index()
+    bundle: dict[str, Any] = {
+        "version": index.get("version", 1),
+        "domain": index.get("domain"),
+        "updated": index.get("updated"),
+        "capabilities": [],
+    }
+    errors: list[str] = []
+
+    for item in index.get("capabilities", []):
+        path = ROOT / item["path"]
+        try:
+            front_matter = parse_front_matter(path)
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        bundle["capabilities"].append(
+            {
+                "index": item,
+                "entry": front_matter,
+            }
+        )
+
+    if errors:
+        for error in errors:
+            print(f"error: {error}", file=sys.stderr)
+        return 1
+
+    if args.format == "json":
+        print(json.dumps(bundle, indent=2, sort_keys=True))
+    else:
+        print(yaml.safe_dump(bundle, sort_keys=False))
+    print(
+        f"# exported {len(bundle['capabilities'])} capabilities",
+        file=sys.stderr,
+    )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="reuse-surface")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate = subparsers.add_parser("validate", help="validate capability entries")
+    validate.add_argument(
+        "path",
+        nargs="?",
+        help="optional capability markdown file; defaults to all entries",
+    )
+    validate.set_defaults(func=cmd_validate)
+
+    query = subparsers.add_parser("query", help="query capability index")
+    query.add_argument("--discovery-min")
+    query.add_argument("--availability-min")
+    query.add_argument("--domain")
+    query.add_argument("--tag")
+    query.add_argument("--consumption-mode")
+    query.add_argument("--keyword")
+    query.set_defaults(func=cmd_query)
+
+    export = subparsers.add_parser("export", help="export registry bundle")
+    export.add_argument(
+        "--format",
+        choices=["yaml", "json"],
+        default="yaml",
+    )
+    export.set_defaults(func=cmd_export)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
--- a/reuse_surface/registry.py
+++ b/reuse_surface/registry.py
@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+CAPABILITIES_DIR = ROOT / "registry" / "capabilities"
+INDEX_PATH = ROOT / "registry" / "indexes" / "capabilities.yaml"
+SCHEMA_PATH = ROOT / "schemas" / "capability.schema.yaml"
+
+LEVEL_ORDERS = {
+    "discovery": ["D0", "D1", "D2", "D3", "D4", "D5", "D6", "D7"],
+    "availability": ["A0", "A1", "A2", "A3", "A4", "A5", "A6", "A7"],
+    "completeness": ["C0", "C1", "C2", "C3", "C4", "C5", "C6"],
+    "reliability": ["R0", "R1", "R2", "R3", "R4", "R5", "R6"],
+}
+
+
+def load_schema() -> dict[str, Any]:
+    with SCHEMA_PATH.open(encoding="utf-8") as handle:
+        return yaml.safe_load(handle)
+
+
+def parse_front_matter(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    match = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
+    if not match:
+        raise ValueError(f"{path}: missing YAML front matter")
+    data = yaml.safe_load(match.group(1))
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: front matter must be a mapping")
+    return data
+
+
+def capability_paths(target: Path | None = None) -> list[Path]:
+    if target is not None:
+        return [target]
+    return sorted(CAPABILITIES_DIR.glob("*.md"))
+
+
+def load_index() -> dict[str, Any]:
+    with INDEX_PATH.open(encoding="utf-8") as handle:
+        return yaml.safe_load(handle)
+
+
+def parse_vector(vector: str) -> dict[str, str]:
+    parts = [part.strip() for part in vector.split("/")]
+    if len(parts) != 4:
+        raise ValueError(f"invalid vector: {vector}")
+    return {
+        "discovery": parts[0],
+        "availability": parts[1],
+        "completeness": parts[2],
+        "reliability": parts[3],
+    }
+
+
+def level_at_least(dimension: str, current: str, minimum: str) -> bool:
+    order = LEVEL_ORDERS[dimension]
+    return order.index(current) >= order.index(minimum)
--- a/schemas/capability.schema.yaml
+++ b/schemas/capability.schema.yaml
@@ -17,7 +17,7 @@ required:
 properties:
  id:
    type: string
-    pattern: '^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$'
+    pattern: '^capability(\.[a-z][a-z0-9-]*)+$'
    description: Stable reverse-domain capability identifier.
  name:
    type: string
@@ -162,6 +162,10 @@ properties:
        type: array
        items:
          type: string
+  promotion_history:
+    type: array
+    items:
+      $ref: '#/$defs/promotionRecord'
 $defs:
  confidence:
    type: string
@@ -182,7 +186,7 @@ $defs:
    type: array
    items:
      type: string
-      pattern: '^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$'
+      pattern: '^capability(\.[a-z][a-z0-9-]*)+$'
  internalMaturityDimension:
    type: object
    additionalProperties: false
@@ -245,3 +249,24 @@ $defs:
        type: array
        items:
          type: string
+  promotionDimension:
+    type: string
+    enum: [discovery, availability, completeness, reliability]
+  promotionRecord:
+    type: object
+    additionalProperties: false
+    required: [date, dimension, from, to, rationale]
+    properties:
+      date:
+        type: string
+        pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'
+      dimension:
+        $ref: '#/$defs/promotionDimension'
+      from:
+        type: string
+      to:
+        type: string
+      rationale:
+        type: string
+      author:
+        type: string
--- a/templates/capability-entry.template.md
+++ b/templates/capability-entry.template.md
@@ -78,6 +78,15 @@ consumer_guidance:
    - describe unsafe or weak reuse scenarios
  known_limitations:
    - list known gaps, risks, or missing evidence
+
+# Optional: append a row when a maturity dimension is promoted with evidence.
+promotion_history: []
+#  - date: "2026-06-15"
+#    dimension: discovery
+#    from: D0
+#    to: D1
+#    rationale: Added intent, summary, and basic actors.
+#    author: capability-owner
 ---

 # Example Capability
--- a/tools/README.md
+++ b/tools/README.md
@@ -1,52 +1,64 @@
 # Registry Tools

-Reference tooling for the capability registry. The MVP is document-first; this
-directory documents validation and query workflows until executable tools land.
+CLI tooling for the capability registry, implemented in `reuse_surface/`.

-## 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:
+## Install

 ```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
+python3 -m venv .venv
+.venv/bin/pip install -e .
 ```

-These are documented here as targets only. Do not assume they exist yet.
+## Commands

-## Agent query pattern
+### validate

-Agents should start with the index, not individual entry files:
+Validate one entry or the full registry against `schemas/capability.schema.yaml`
+and warn on index drift.

-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`.
+```bash
+reuse-surface validate
+reuse-surface validate registry/capabilities/capability.registry.register.md
+```
+
+### query
+
+Filter the capability index by maturity, tags, domain, consumption mode, or keyword.
+
+```bash
+reuse-surface query --discovery-min D4
+reuse-surface query --availability-min A3
+reuse-surface query --tag identity
+reuse-surface query --consumption-mode cli
+reuse-surface query --keyword rollout
+```
+
+### export
+
+Export a machine-readable bundle combining index rows and parsed entry front matter.
+
+```bash
+reuse-surface export
+reuse-surface export --format json
+```
+
+## Export format
+
+The export bundle includes:
+
+- `version`, `domain`, `updated` from the index
+- `capabilities[]` with `{ index, entry }` pairs
+
+Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).
+
+## Workflows
+
+| Workflow | Command |
+|---|---|
+| Add capability | template + index update + `reuse-surface validate` |
+| Discover capabilities | `reuse-surface query` or read the index |
+| Validate entry shape | `reuse-surface validate` |
+| Export for agents | `reuse-surface export --format json` |

 ## Related use cases

--- a/workplans/REUSE-WP-0003-intent-scope-gap-closure.md
+++ b/workplans/REUSE-WP-0003-intent-scope-gap-closure.md
@@ -4,7 +4,7 @@ type: workplan
 title: "Close intent-scope gaps: docs, tooling, and registry growth"
 domain: helix_forge
 repo: reuse-surface
-status: ready
+status: finished
 owner: codex
 topic_slug: helix-forge
 created: "2026-06-15"
@@ -38,7 +38,7 @@ T01, T04  (documentation — parallel)

 ```task
 id: REUSE-WP-0003-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "51c58b43-7b0f-4737-bf48-51efd6f50ead"
 ```
@@ -56,7 +56,7 @@ Close gap analysis item 1. Update `INTENT.md`:

 ```task
 id: REUSE-WP-0003-T02
-status: todo
+status: done
 priority: high
 state_hub_task_id: "570a036a-d310-4cb7-9812-594a7f4de904"
 ```
@@ -76,7 +76,7 @@ Close gap analysis item 2 and UC-RS-023. Add a minimal Python CLI under

 ```task
 id: REUSE-WP-0003-T03
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "2c59041d-6c27-4610-afc0-c83873e18b9b"
 ```
@@ -96,7 +96,7 @@ illustrate a different planning or consumption profile than existing entries.

 ```task
 id: REUSE-WP-0003-T04
-status: todo
+status: done
 priority: high
 state_hub_task_id: "70077cfe-f5ca-4a61-97b2-81829a6b4565"
 ```
@@ -116,7 +116,7 @@ Do not duplicate the full maturity standard — link to `specs/` instead.

 ```task
 id: REUSE-WP-0003-T05
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "22a3db94-21c7-44d6-8d77-5235f9f10537"
 ```
@@ -135,7 +135,7 @@ over time (UC-RS-022). Requirements:

 ```task
 id: REUSE-WP-0003-T06
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "1958f555-a3a6-46a8-84cd-c570d6706cb3"
 ```
@@ -154,7 +154,7 @@ queries in `registry/README.md` and `AGENTS.md`.

 ```task
 id: REUSE-WP-0003-T07
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "6e595b66-ce73-4867-af79-5d0a43a0056d"
 ```
@@ -171,7 +171,7 @@ the index and parsed front matter from all capability entries. Requirements:

 ```task
 id: REUSE-WP-0003-T08
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "d876f449-68e3-4785-ba3c-7d91c4abbafc"
 ```