generated from coulomb/repo-seed
Add intent-scope gap analysis and REUSE-WP-0003 workplan
Document gaps between INTENT.md and SCOPE.md, refresh SCOPE with current MVP capabilities, and seed the follow-up workplan for documentation alignment, registry CLI tooling, and coverage growth.
This commit is contained in:
189
workplans/REUSE-WP-0003-intent-scope-gap-closure.md
Normal file
189
workplans/REUSE-WP-0003-intent-scope-gap-closure.md
Normal file
@@ -0,0 +1,189 @@
|
||||
---
|
||||
id: REUSE-WP-0003
|
||||
type: workplan
|
||||
title: "Close intent-scope gaps: docs, tooling, and registry growth"
|
||||
domain: helix_forge
|
||||
repo: reuse-surface
|
||||
status: ready
|
||||
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: 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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
Reference in New Issue
Block a user