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 with A3 CLI tooling (validate, query, export) atop Markdown-first authoring.

The two documents are directionally aligned on registry-first reuse, four maturity dimensions, and human/agent consumers. REUSE-WP-0003 through REUSE-WP-0010 closed the priority gaps from section 8. Remaining gaps are primarily document cross-coverage and operational polish:

1. Document cross-coverage — SCOPE still carries operational detail INTENT omits; INTENT success criteria are not fully enumerated in SCOPE.
2. Live federation sync — on-demand HTTP fetch only; no polling or webhooks.

Current reuse-surface vector (self-assessment): D5 / A3 / C4 / R3

---

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	tests/ — pytest covers validate, query, export, overlaps, federation, graph, catalog
Schema validation in CI	.gitea/workflows/ci.yml — validate, federation, catalog, graph, pytest
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: R3 (Proven in Development) for registry CLI tooling — pytest suite and CI gates exercise core commands. Individual registered capabilities may carry their own evidence (e.g. feature-control at R3).

---

8. Priority Gap Closure Order

Priority	Gap	Outcome	Status
1	INTENT layout stale	INTENT layout aligned to delivered structure	Closed (WP-0003)
2	No automated validation	reuse-surface validate	Closed (WP-0003)
3	Thin registry coverage	Six helix_forge entries	Closed (WP-0003)
4	Missing concept docs	docs/CapabilityRegistryConcept.md	Closed (WP-0003)
5	No promotion history	promotion_history in schema/template	Closed (WP-0003)
6	Search/filter manual only	reuse-surface query	Closed (WP-0003)
7	No registry export	reuse-surface export	Closed (WP-0003)
8	Self-reliability evidence	capability.registry.register at R2; friction recorded	Closed (WP-0003)

Next recommended work

Priority	Gap	Outcome	Status
9	Catalog site	reuse-surface catalog → MD + HTML	Closed (WP-0004)
10	Overlap detection	reuse-surface overlaps	Closed (WP-0004)
11	CI validation	.gitea/workflows/ci.yml	Closed (WP-0004)
12	Registry federation	federation compose + federated index	Closed (WP-0005)
14	Graph visualization	reuse-surface graph Mermaid output	Closed (WP-0005)

Priority	Gap	Outcome	Status
13	Interactive catalog	docs/catalog/search.html + registry.json	Closed (WP-0007)
15	Network federation	HTTP URL sources + cache in federation compose	Closed (WP-0010)
16	Graph UI	docs/graph/index.html explorer	Closed (WP-0008)

Proposed next work

Priority	Gap	Suggested outcome	Status
17	Hosted federation hub	Hub service on railiance01 + reuse-surface hub CLI	Active (WP-0011)

---

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
2026-06-15	REUSE-WP-0003 closed priority gaps 1–8; vector updated to D5/A3/C4/R2
2026-06-15	REUSE-WP-0004 closed priorities 9–11 (catalog, overlaps, CI)
2026-06-15	REUSE-WP-0005 closed priorities 12 and 14 (federation, relation graphs)
2026-06-15	REUSE-WP-0006 expanded registry to 12 capabilities; relation hygiene clean
2026-06-15	REUSE-WP-0007 closed priority 13 (searchable catalog UI)
2026-06-15	REUSE-WP-0008 closed priority 16 (graph explorer)
2026-06-15	REUSE-WP-0009 added pytest suite and CI fail-on-warnings; vector R3
2026-06-15	REUSE-WP-0010 closed priority 15 (HTTP remote federation + cache)
2026-06-15	REUSE-WP-0011 proposed for priority 17 (hosted hub on railiance01)