---
id: REUSE-WP-0003
type: workplan
title: "Close intent-scope gaps: docs, tooling, and registry growth"
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: "302ea071-68ab-43e4-97ce-8cf1fb805aaa"
---

# Close intent-scope gaps: docs, tooling, and registry growth

Follow-up to `docs/IntentScopeGapAnalysis.md` section 8 (Priority Gap Closure
Order). `REUSE-WP-0002` delivered the MVP registry foundation at A0. This
workplan closes the highest-priority gaps between `INTENT.md` and `SCOPE.md` by
aligning documentation, raising availability toward A3, and strengthening
registry coverage and evidence.

**Target vector after completion:** `D5 / A3 / C4 / R2` for reuse-surface as a
registry product.

## Suggested execution order

```text
T01, T04  (documentation — parallel)
  → T05    (schema: promotion history)
  → T02    (validate CLI)
  → T06, T07 (query + export — parallel after T02)
  → T03    (expand registry entries)
  → T08    (dogfood evidence + gap analysis refresh)
```

## Align INTENT With Delivered Layout

```task
id: REUSE-WP-0003-T01
status: done
priority: high
state_hub_task_id: "51c58b43-7b0f-4737-bf48-51efd6f50ead"
```

Close gap analysis item 1. Update `INTENT.md`:

- Replace the stale "Initial Repository Role" tree with the layout in `SCOPE.md`
- Fix the registry entry example to use `external_evidence.*.level` (not
  `current`) to match `schemas/capability.schema.yaml`
- Add a short pointer to `docs/IntentScopeGapAnalysis.md` and
  `docs/CapabilityRegistryConcept.md` (once T04 lands)
- Keep product intent unchanged; only correct delivery drift

## Add Automated Registry Validation

```task
id: REUSE-WP-0003-T02
status: done
priority: high
state_hub_task_id: "570a036a-d310-4cb7-9812-594a7f4de904"
```

Close gap analysis item 2 and UC-RS-023. Add a minimal Python CLI under
`tools/` that validates capability entry front matter against
`schemas/capability.schema.yaml`. Requirements:

- Validate one file or all files under `registry/capabilities/`
- Check required fields, enum values, and capability ID format
- Warn on index drift (entry exists but missing from
  `registry/indexes/capabilities.yaml`, or vice versa)
- Document usage in `tools/README.md` and `AGENTS.md`
- Add `pyproject.toml` with minimal dependencies if needed for packaging

## Expand helix_forge Registry Coverage

```task
id: REUSE-WP-0003-T03
status: done
priority: medium
state_hub_task_id: "2c59041d-6c27-4610-afc0-c83873e18b9b"
```

Close gap analysis item 3. Register at least three additional helix_forge
capabilities beyond the MVP samples. Candidates to evaluate:

- `state-hub` — workstream/task coordination
- `feature-control` siblings (rollout, visibility) if distinct from evaluate
- `identity-canon` — subject resolution or other canon primitives
- Adjacent helix_forge repos with clear bounded capabilities

Each new entry must pass the validator from T02, appear in the index, and
illustrate a different planning or consumption profile than existing entries.

## Add Capability Registry Concept Guide

```task
id: REUSE-WP-0003-T04
status: done
priority: high
state_hub_task_id: "70077cfe-f5ca-4a61-97b2-81829a6b4565"
```

Close gap analysis item 4. Create `docs/CapabilityRegistryConcept.md` distilled
from `INTENT.md` for human onboarding. Cover:

- Registry-first boundary and reuse-over-inventory principle
- Four maturity dimensions and when to use each
- Planning reuse vs implementation reuse
- How entries, index, schema, and template fit together
- What remains manual vs what tooling provides (cross-link `SCOPE.md`)

Do not duplicate the full maturity standard — link to `specs/` instead.

## Add Promotion History Support

```task
id: REUSE-WP-0003-T05
status: done
priority: medium
state_hub_task_id: "22a3db94-21c7-44d6-8d77-5235f9f10537"
```

Close gap analysis item 5. Extend the registry model to track maturity changes
over time (UC-RS-022). Requirements:

- Add optional `promotion_history` to `schemas/capability.schema.yaml`
- Update `templates/capability-entry.template.md` with an example history block
- Document when and how to append history in `registry/README.md`
- Backfill at least one sample entry (e.g. `capability.registry.register`) with
  a plausible promotion record
- Extend the validator from T02 to check history entry shape when present

## Add CLI Query And Filter

```task
id: REUSE-WP-0003-T06
status: done
priority: medium
state_hub_task_id: "1958f555-a3a6-46a8-84cd-c570d6706cb3"
```

Close gap analysis item 6 and UC-RS-004/005. Extend the `tools/` CLI with a
`query` command that reads `registry/indexes/capabilities.yaml` and filters by:

- Discovery minimum (e.g. `--discovery-min D4`)
- Availability minimum (e.g. `--availability-min A3`)
- Tags, domain, consumption mode, and summary keyword

Output a concise candidate list with vectors and entry paths. Document example
queries in `registry/README.md` and `AGENTS.md`.

## Add Registry Export Bundle

```task
id: REUSE-WP-0003-T07
status: done
priority: medium
state_hub_task_id: "6e595b66-ce73-4867-af79-5d0a43a0056d"
```

Close gap analysis item 7 and UC-RS-019. Extend the `tools/` CLI with an
`export` command that produces a machine-readable bundle (YAML or JSON) combining
the index and parsed front matter from all capability entries. Requirements:

- Stable IDs and maturity fields in export output
- Document export format in `tools/README.md`
- Export must pass a smoke check: all index entries resolve to readable front matter

## Dogfood Reliability Evidence And Refresh Gap Analysis

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

Close gap analysis item 8. Record consumer-relevant friction from building T02–T07
as reliability evidence for `capability.registry.register` (and optionally a
meta-entry for reuse-surface itself). Requirements:

- Update `external_evidence.reliability` with honest R1–R3 assessment and known
  risks (manual index maintenance, validator gaps, etc.)
- Refresh `docs/IntentScopeGapAnalysis.md`: close resolved gaps, update the
  self-assessment vector, add a change-log entry referencing REUSE-WP-0003
- Update `SCOPE.md` "What Is Possible Now / Not Possible Yet" to reflect new CLI
  capabilities
- Promote `capability.registry.register` availability to A3 if CLI ships