coulomb/reuse-surface
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Add intent-scope gap analysis and REUSE-WP-0003 workplan

Browse Source 
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:
Bernd Worsch
2026-06-15 01:09:53 +02:00
parent 3e022f4963
commit 80bccc4bbb
3 changed files with 553 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
SCOPE.md
View File

@@ -14,7 +14,7 @@ for reuse within this product boundary.
## In Scope
- Maintain the capability maturity model, standards, schemas, registry formats,
examples, indexes, validation guidance, and agent instructions.
sample entries, indexes, validation guidance, 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
@@ -32,22 +32,89 @@ for reuse within this product boundary.
- Own unrelated adjacent systems or make irreversible operational decisions
without human approval.
## What Is Possible Now
The MVP registry foundation is in place. Humans and agents can:
- **Discover capabilities** via `registry/indexes/capabilities.yaml`
- **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
- **Compare candidates** using maturity vectors, scope, relations, and consumer
guidance in entry files
- **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
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.
## 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
- Federation across repositories or organizations
See `tools/README.md` for planned tooling that remains out of scope for the
current MVP.
## Current State
- Status: active specification scaffold.
- The repository is currently documentation-only. It has no package manifest,
build system, runtime app, or executable test suite.
- `specs/` contains the product requirements, use case catalog, and capability
maturity standard. `INTENT.md` defines the registry model and guiding
principles.
- `registry/`, `schemas/`, `templates/`, and `tools/` contain the MVP registry
foundation seeded by `REUSE-WP-0002`.
- 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.
## Repository Layout
```text
reuse-surface/
├── INTENT.md
├── SCOPE.md
├── AGENTS.md
├── specs/
│ ├── ProductRequirementsDocument.md
│ ├── UseCaseCatalog.md
│ └── CapabilityMaturityStandard.md
├── schemas/
│ └── capability.schema.yaml
├── templates/
│ └── capability-entry.template.md
├── registry/
│ ├── README.md
│ ├── capabilities/
│ └── indexes/
│ └── capabilities.yaml
├── tools/
│ └── README.md
└── workplans/
```
## Getting Oriented
- Start with: INTENT.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
- Agent instructions: AGENTS.md
- Workplans: workplans/

288
docs/IntentScopeGapAnalysis.md Normal file
View File

@@ -0,0 +1,288 @@
# INTENT ↔ SCOPE Gap Analysis
**Repository:** `reuse-surface`
**Artifact:** `docs/IntentScopeGapAnalysis.md`
**Status:** Living analysis
**Created:** 2026-06-15
**Purpose:** Record alignment, drift, and open gaps between declared intent and
current delivered scope so future workplans can close them deliberately.
---
## 1. Summary
`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.
The two documents are **directionally aligned** on registry-first reuse, four
maturity dimensions, and human/agent consumers. The main gaps are:
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.
**Current reuse-surface vector (self-assessment):** `D4 / A0 / C3 / R0`
---
## 2. Alignment Matrix
| Topic | INTENT.md | SCOPE.md | Status |
|---|---|---|---|
| Registry-first boundary | Unregistered capabilities are invisible | Same | Aligned |
| Four maturity dimensions | D, A, C, R with separate internal/external evidence | Same model in use | Aligned |
| Human and agent consumers | Registry formats for both | Markdown + YAML index | Aligned |
| Reuse over inventory | Explicit principle | Implicit in workflows | Aligned |
| Planning vs implementation reuse | Distinct dimensions | Reflected in query guidance | Aligned |
| No internal code quality as maturity | Out of scope | Out of scope | Aligned |
| No hosting registered capabilities | Implied | Explicit out of scope | Aligned |
| Target maturity vectors | Expected per capability | Supported in entry schema | Aligned |
| Broken expectations as evidence | Guiding principle | Supported in schema/entries | Aligned |
| Technical foundation | "Eventually technical" | A0 only, no CLI/API | Gap |
| Success criteria | Eight outcomes listed | Partially met, not enumerated | Gap |
| Repository layout | `standards/`, `docs/`, JSON schema | `specs/`, `docs/` missing, YAML schema | Drift |
| State Hub / workplans | Not mentioned | In scope and current state | SCOPE-only |
| MVP acceptance criteria | Not mentioned | Claimed satisfied manually | SCOPE-only |
| Domain scope | Cross-repo/product/org | helix_forge sample registry | Narrower delivery |
---
## 3. INTENT → SCOPE Gaps
What INTENT declares that SCOPE does not yet deliver.
### 3.1 Technical foundation (High)
| INTENT claim | Current SCOPE reality | Gap |
|---|---|---|
| "Conceptual, structural, and **eventually technical** foundation" | Documentation-only repo, A0 availability | No CLI, validator, exporter, or API |
| Implementation support through discoverable consumption modes | Manual index filtering only | No machine-assisted query or export |
| Reference tooling | `tools/README.md` documents planned commands | Executable tools do not exist |
**Impact:** Implementation reuse still depends on humans/agents reading files.
INTENT's "available enough to build with" mantra is only partially true for
registry metadata itself.
**Suggested follow-up:** Workplan for CLI validate/query/export (PRD section 17).
### 3.2 Planning support breadth (Medium)
| INTENT claim | Current SCOPE reality | Gap |
|---|---|---|
| Planning support for prototype, MVP, enhancement, platform decisions | Manual compare/search guidance | No gap reports, roadmap views, or platformization filters |
| Identify capability gaps, duplicates, overlaps, standardization candidates | Duplicate guidance only | No overlap detection, gap aggregation, or standardization workflow |
| Track progress from named ideas to generalized capabilities | Promotion via front matter edits | No promotion history or changelog |
**Impact:** Planning reuse works for small registries; does not scale without
tooling or disciplined manual process.
**Suggested follow-up:** Index views for "D5+/A0-A1" planning candidates and
"D5+/A4+" implementation candidates; promotion history field or log.
### 3.3 Success criteria coverage (Medium)
INTENT success criteria vs current delivery:
| Success criterion | Met today? | Notes |
|---|---|---|
| Find reusable capabilities before rebuilding | Partial | Index + 3 samples; coverage is thin |
| Compare maturity consistently | Yes | Vectors and schema enums |
| Distinguish conceptual readiness from delivery | Yes | D vs A separation |
| Distinguish internal assessment from external evidence | Yes | `maturity` vs `external_evidence` |
| Plan prototype/MVP/enhancement/platform work | Partial | Guidance only, no reports |
| Identify gaps, duplicates, overlaps, standardization candidates | Partial | Manual duplicate check only |
| Track progress to generalized capabilities | No | No history or timeline |
| Make reuse normal in product/architecture work | Partial | Agent instructions exist; tooling weak |
### 3.4 Expected repository layout (Low–Medium)
INTENT "Initial Repository Role" layout differs from delivered layout:
| INTENT path | Delivered path | Drift |
|---|---|---|
| `standards/CapabilityMaturityStandard.md` | `specs/CapabilityMaturityStandard.md` | Renamed directory |
| `registry/capabilities.yaml` | `registry/capabilities/*.md` + `registry/indexes/capabilities.yaml` | Split canonical entries and index |
| `registry/examples/` | `registry/capabilities/` (samples inline) | Different organization |
| `schemas/capability.schema.json` | `schemas/capability.schema.yaml` | Format and location differ |
| `docs/CapabilityRegistryConcept.md` | Missing | Not authored |
| `docs/CapabilityAssessmentGuide.md` | Partially covered by `registry/README.md` | Concept guide missing |
**Impact:** New contributors reading INTENT first will look for paths that do
not exist. SCOPE layout is authoritative for operations; INTENT layout is stale.
**Suggested follow-up:** Update INTENT "Initial Repository Role" to match
delivered structure, or add redirect notes.
### 3.5 Registry entry shape drift (Low)
INTENT example uses:
```yaml
external_evidence:
completeness:
current: C1
reliability:
current: R0
```
Implemented schema and entries use `level` instead of `current` under
`external_evidence`, matching `specs/CapabilityMaturityStandard.md` section 10.
**Impact:** Minor authoring confusion between INTENT and schema/template.
**Suggested follow-up:** Align INTENT example to `level` or document the alias.
### 3.6 Consumer reliability evidence (Medium)
INTENT requires reliability from bugs, tickets, incidents, ratings, adoption.
SCOPE supports recording fields but:
- No sample entry has reliability above R0 except the feature-control example
(R3 with thin evidence)
- reuse-surface itself has **R0** — no consumer feedback loop for the registry
**Impact:** External evidence dimension is structurally present but weakly
populated.
---
## 4. SCOPE → INTENT Gaps
What SCOPE asserts that INTENT does not declare.
### 4.1 Operational integration (Low)
SCOPE includes State Hub workplans, ADR-001 consistency sync, and session
protocol. INTENT is product-conceptual and omits custodian workflow entirely.
**Assessment:** Not a product conflict. SCOPE correctly adds repository
operations. INTENT may optionally reference workplan-driven evolution.
### 4.2 MVP framing (Low)
SCOPE maps deliverables to `specs/ProductRequirementsDocument.md` sections 15–16
and claims MVP acceptance criteria are met manually. INTENT does not define MVP
boundaries or acceptance tests.
**Assessment:** SCOPE is more precise about current phase. INTENT remains the
north star; SCOPE is the phase boundary.
### 4.3 Domain anchoring (Low)
SCOPE inventories three **helix_forge** sample capabilities. INTENT describes
cross-repo, product, and organizational reuse generically.
**Assessment:** Expected at MVP stage. INTENT target of D7 generalized primitives
is not contradicted — sample scope is intentionally narrow.
### 4.4 Verification commands (Low)
SCOPE documents `rg --files`, `git diff --check`, and fix-consistency. INTENT
has no verification or change-management guidance.
**Assessment:** SCOPE appropriately operationalizes delivery discipline.
---
## 5. Contradictions and Broken Expectations
Explicit mismatches a consumer might reasonably assume from reading both files:
| Expectation | Source | Reality | Severity |
|---|---|---|---|
| "Eventually technical foundation" is underway | INTENT scope section | No package, CLI, or API | Medium |
| Maturity standard lives under `standards/` | INTENT layout | Lives under `specs/` | Low |
| Single `capabilities.yaml` registry file | INTENT layout | Per-entry Markdown + separate index | Low |
| JSON schema file exists | INTENT layout | YAML JSON Schema instead | Low |
| Concept and assessment guides exist under `docs/` | INTENT layout | Only this gap analysis so far | Medium |
| Registry can be searched by maturity automatically | INTENT success + SCOPE "possible now" | Manual index scan only | Medium |
| Implementation reuse is supported | INTENT in-scope bullet | Only for entries with A2+ artifacts elsewhere | Medium |
No direct logical contradiction on registry-first boundary or maturity model
separation was found.
---
## 6. Completeness Assessment (SCOPE vs INTENT)
Using INTENT's own completeness framing for the **reuse-surface product**:
| Area | INTENT expectation | Current SCOPE delivery | Level |
|---|---|---|---|
| Registry model and principles | Full | `INTENT.md` + `specs/` | C4 |
| Maturity standard | Full | `specs/CapabilityMaturityStandard.md` | C5 |
| Entry authoring | Full for MVP | Template + schema + README | C4 |
| Sample registry | Examples expected | 3 helix_forge entries | C3 |
| Discovery surface | Machine-readable | YAML index | C3 |
| Validation | Implied tooling | Manual checklist | C2 |
| Search/filter | Supported | Documented manual patterns | C2 |
| Agent instructions | Expected | `AGENTS.md` registry section | C4 |
| Technical consumption of registry | A3+ target natural for tools | A0 | C1 |
| Consumer evidence for registry itself | Should be recorded | None (R0) | C1 |
| Planning reports and gap analytics | Success criteria | Not present | C1 |
| Documentation canon | Concept + assessment guides | Partial | C2 |
**Overall completeness vs INTENT:** **C3 (Functional Core)** — the central
registry MVP works manually, but variants, tooling, evidence, and conceptual
docs remain incomplete.
---
## 7. Reliability Assessment (SCOPE vs INTENT)
| Signal | State |
|---|---|
| Automated tests | None |
| Schema validation in CI | None |
| Consumer feedback on registry workflows | None |
| Production or repeated agent usage evidence | None |
| Known friction | Manual index maintenance; schema/INTENT field naming drift |
**Overall reliability vs INTENT consumer-evidence framing:** **R0 (Unknown)** for
the registry product itself. Individual registered capabilities may carry their
own evidence (e.g. feature-control at R3).
---
## 8. Priority Gap Closure Order
Recommended sequence for future workplans:
| 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. Document Maintenance Rules
- Re-run this analysis when either `INTENT.md` or `SCOPE.md` changes materially.
- When a gap closes, update section 3–5 and adjust the self-assessment vector.
- New workplans that close gaps should reference the relevant row in section 8.
- Prefer updating `SCOPE.md` for delivery truth and `INTENT.md` for product
truth; use this file to track delta between them.
---
## 10. Change Log
| Date | Change |
|---|---|
| 2026-06-15 | Initial analysis after REUSE-WP-0002 completion |

189
workplans/REUSE-WP-0003-intent-scope-gap-closure.md Normal file
View 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