From 80bccc4bbb4a0f0a30cd41cc06c7dc5a58288f25 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 15 Jun 2026 01:09:53 +0200 Subject: [PATCH] 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. --- SCOPE.md | 85 +++++- docs/IntentScopeGapAnalysis.md | 288 ++++++++++++++++++ .../REUSE-WP-0003-intent-scope-gap-closure.md | 189 ++++++++++++ 3 files changed, 553 insertions(+), 9 deletions(-) create mode 100644 docs/IntentScopeGapAnalysis.md create mode 100644 workplans/REUSE-WP-0003-intent-scope-gap-closure.md diff --git a/SCOPE.md b/SCOPE.md index 1554b9c..1ef8466 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -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/ \ No newline at end of file diff --git a/docs/IntentScopeGapAnalysis.md b/docs/IntentScopeGapAnalysis.md new file mode 100644 index 0000000..388dfc9 --- /dev/null +++ b/docs/IntentScopeGapAnalysis.md @@ -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 | \ No newline at end of file diff --git a/workplans/REUSE-WP-0003-intent-scope-gap-closure.md b/workplans/REUSE-WP-0003-intent-scope-gap-closure.md new file mode 100644 index 0000000..dee6e37 --- /dev/null +++ b/workplans/REUSE-WP-0003-intent-scope-gap-closure.md @@ -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 \ No newline at end of file