reuse-surface/docs/IntentScopeGapAnalysis.md

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:

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