reuse-surface/workplans/REUSE-WP-0003-intent-scope-gap-closure.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
REUSE-WP-0003	workplan	Close intent-scope gaps: docs, tooling, and registry growth	helix_forge	reuse-surface	ready	codex	helix-forge	2026-06-15	2026-06-15	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

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

id: REUSE-WP-0003-T01
status: todo
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

id: REUSE-WP-0003-T02
status: todo
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

id: REUSE-WP-0003-T03
status: todo
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

id: REUSE-WP-0003-T04
status: todo
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

id: REUSE-WP-0003-T05
status: todo
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

id: REUSE-WP-0003-T06
status: todo
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

id: REUSE-WP-0003-T07
status: todo
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

id: REUSE-WP-0003-T08
status: todo
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