generated from coulomb/repo-seed
tegwick
0dbef6d1a3
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.
189 lines
6.3 KiB
Markdown
189 lines
6.3 KiB
Markdown
---
|
||
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 |