reuse-surface/docs/IntentScopeGapAnalysis.md

INTENT ↔ SCOPE Gap Analysis

Repository: reuse-surface
Artifact: docs/IntentScopeGapAnalysis.md
Status: Living analysis
Updated: 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 delivers today: an active MVP with 20 helix_forge capabilities, A3 CLI tooling, a hosted federation hub at A4 (https://reuse.coulomb.social), federation compose, catalog/graph UIs, pytest + CI gates, and Markdown-first authoring.

REUSE-WP-0001 through REUSE-WP-0011 closed the original MVP and federation roadmap. The documents are directionally aligned on registry-first reuse, four maturity dimensions, and human/agent consumers.

Remaining gaps are no longer “build the registry” but scale and harden reuse across repos:

1. Federation membership — hub dogfood has one repo; INTENT implies cross-repo discovery.
2. Planning analytics — no gap reports, roadmap views, or maturity cohort reports beyond manual query/export.
3. Hub automation — on-demand compose only; no hub sync, polling, or webhooks.
4. INTENT document drift — INTENT.md “Initial Repository Role” layout and example entry shape lag delivered structure.
5. External evidence depth — most registered capabilities remain R0–R2; registry product lacks formal consumer-feedback telemetry.

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

---

2. Alignment Matrix

Topic	INTENT.md	SCOPE.md	Status
Registry-first boundary	Unregistered capabilities invisible	Same	Aligned
Four maturity dimensions	D, A, C, R with separate internal/external evidence	Same model in entries and schema	Aligned
Human and agent consumers	Registry formats for both	Markdown + YAML index + CLI + hub API	Aligned
Reuse over inventory	Explicit principle	Workflows, overlaps, federation	Aligned
Planning vs implementation reuse	Distinct dimensions	Query, vectors, consumption_modes	Aligned
Technical foundation	“Eventually technical”	CLI A3, hub API A4, container A5 artifact	Aligned (MVP met)
Implementation consumption modes	Discoverable modes per capability	Supported in schema and index	Aligned
Cross-repo / org reuse	D7 generalized primitives	helix_forge domain; hub ready, thin membership	Partial
Success criteria	Eight outcomes	Most met at MVP level; analytics weak	Partial
Repository layout in INTENT	standards/, JSON schema, single yaml	specs/, YAML schema, per-entry MD	Drift
State Hub / workplans	Not in INTENT	In scope; ADR-001 sync	SCOPE-only (OK)
Hosting registered capabilities	Out of scope	Hub hosts metadata/URLs only	Aligned

---

3. INTENT → SCOPE Gaps (Open)

What INTENT still expects beyond current SCOPE delivery.

3.1 Cross-repo federation breadth (High)

INTENT claim	Current SCOPE reality	Gap
Capabilities reusable across repos, products, orgs	20 entries, all helix_forge	No multi-domain federation yet
Find capabilities before rebuilding (network scale)	Hub /v1/federated returns 12 capabilities from 1 repo	Sibling repos lack published indexes

Impact: Hub infrastructure is live; membership and index publishing are the bottleneck, not registry tooling.

Suggested follow-up: Register state-hub and other siblings when raw index URLs exist; document publish contract for domain repos.

3.2 Planning support breadth (Medium)

INTENT claim	Current SCOPE reality	Gap
Plan prototype/MVP/enhancement/platform work	Manual compare via query/catalog	No gap reports or roadmap views
Identify gaps, duplicates, overlaps, standardization	overlaps command (35 candidates on 20 entries)	No aggregation workflow or standardization tracker
Track progress to generalized capabilities (D7)	promotion_history per entry	No cross-entry timeline or D7 pipeline view

Impact: Planning reuse works for small registries; portfolio-scale decisions still need disciplined manual process or new reports.

Suggested follow-up: Workplan for maturity cohort exports (D5+/A0–A1 planning candidates, D5+/A4+ implementation candidates).

3.3 Hub operations and client sync (Medium)

INTENT claim	Current SCOPE reality	Gap
Implementation support through consumption modes	Hub API + CLI for register/list/compose	No hub sync to local sources.yaml
Operational reuse	Production hub on Railiance01	No polling/webhooks; SQLite single-replica

Impact: Agents on offline machines still maintain local federation manifests by hand unless they call the hub API directly.

Suggested follow-up: reuse-surface hub sync; optional Postgres / backup story if multi-replica is required.

3.4 INTENT document drift (Low–Medium)

INTENT section	Delivered reality	Gap
“Initial Repository Role” tree	Missing reuse_surface/, Dockerfile, hub specs, workplans/archived/	Stale onboarding map
Example external_evidence uses current:	Schema uses level: per maturity standard	Authoring confusion
Implies docs/CapabilityAssessmentGuide.md	Covered by registry/README.md + maturity standard	Missing dedicated guide

Impact: Contributors reading INTENT first may look for paths that differ from operations. SCOPE layout is authoritative for delivery.

Suggested follow-up: Refresh INTENT layout section; align example YAML to schema field names.

3.5 Consumer reliability evidence (Medium)

INTENT claim	Current SCOPE reality	Gap
Reliability from bugs, tickets, incidents, adoption	Schema supports evidence fields	Most entries R0–R2; thin consumer_feedback
Registry product should be evidenced enough to trust	CI + 20 pytest tests + production hub smoke	No production telemetry or user feedback loop

Impact: External evidence dimension is structurally present but lightly populated across the catalog.

---

4. Closed Gaps (Historical)

Previously high-severity gaps now delivered (REUSE-WP-0003 through WP-0011):

Area	Delivery
Automated validation	reuse-surface validate + CI
Query / export	query, export
Catalog and overlaps	catalog, overlaps, searchable HTML
Federation compose	Local + HTTP URL sources + cache
Network federation	Remote fetch in compose
Relation graphs	graph, Mermaid, HTML explorer
Hosted hub	reuse-surface serve, hub CLI, reuse.coulomb.social
Test suite	20 pytest tests, fail-on-warnings in CI
Concept docs	docs/CapabilityRegistryConcept.md
Registry coverage	20 capabilities (from 3 initial samples)

---

5. Success Criteria vs Delivery

INTENT success criteria after WP-0011:

Success criterion	Met today?	Notes
Find reusable capabilities before rebuilding	Yes (MVP)	Index, query, catalog, hub /v1/federated
Compare maturity consistently	Yes	Vectors, schema enums, graph relations
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 + manual tools; no reports
Identify gaps, duplicates, overlaps, standardization	Partial	Overlaps command; no standardization workflow
Track progress to generalized capabilities	Partial	Per-entry promotion_history; no D7 pipeline
Make reuse normal in product/architecture work	Partial	AGENTS.md, hub live; federation membership thin

---

6. Completeness Assessment (SCOPE vs INTENT)

Using INTENT's completeness framing for the reuse-surface product:

Area	INTENT expectation	Current delivery	Level
Registry model and principles	Full	INTENT + specs	C5
Maturity standard	Full	specs/CapabilityMaturityStandard.md	C5
Entry authoring	Full for MVP	Template + schema + README	C5
Sample / seed registry	Examples	20 helix_forge entries	C4
Discovery surface	Machine-readable	Index, query, export, hub API	C5
Validation	Tooling	validate + CI	C5
Search / filter	Supported	query, catalog HTML	C4
Federation	Cross-repo	Compose + production hub; 1 member	C3
Agent instructions	Expected	AGENTS.md + tools README	C4
Technical consumption	A3+ for tools	CLI A3, hub A4	C4
Planning analytics	Success criteria	Not present	C2
Documentation canon	Concept + assessment	Concept doc; assessment via README	C4

Overall completeness vs INTENT: C4 (Broadly Covered) — core registry, tooling, and hub work; federation membership and planning analytics remain bounded gaps.

---

7. Reliability Assessment (SCOPE vs INTENT)

Signal	State
Automated tests	20 pytest tests (registry, federation, hub)
Schema validation in CI	validate, federation, catalog, graph, pytest
Production hub	reuse.coulomb.social — TLS, health, dogfood registration
Consumer feedback on registry workflows	None formal
Known friction	Sibling index publishing; INTENT layout drift; hub single-replica SQLite

Overall reliability vs INTENT consumer-evidence framing: R3 (Usable) — CI and production smoke support normal agent/operator workflows with known limitations. Not yet R4 Dependable without SLO, backup, and feedback data.

---

8. Priority Gap Closure Order

Closed (WP-0001 – WP-0011)

Priorities 1–17 from the original roadmap are closed. See section 4 and archived workplans under workplans/archived/.

Proposed next work

Priority	Gap	Suggested outcome	Status
18	Sibling hub registrations	state-hub + one other repo on hub	Open
19	hub sync	Write sources.yaml from hub state	Open
20	Planning cohort reports	Export/filter views for D5+/A4+ candidates	Open
21	INTENT layout sync	Update INTENT.md tree and example entry shape	Open
22	Hub hardening	Postgres option, backup, documented SLO (A5→A6 path)	Open
23	External evidence program	Raise catalog R levels with consumer_feedback	Open

Workplan: REUSE-WP-0012 (ready). Assessment snapshot: history/2026-06-15-intent-scope-assessment.md.

---

9. Document Maintenance Rules

• Re-run this analysis when either INTENT.md or SCOPE.md changes materially.
• When a gap closes, update sections 3–8 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 priorities 1–8; vector D5/A3/C4/R2
2026-06-15	REUSE-WP-0004 closed priorities 9–11
2026-06-15	REUSE-WP-0005 closed priorities 12 and 14
2026-06-15	REUSE-WP-0006 expanded registry to 12 capabilities
2026-06-15	REUSE-WP-0007–0010 closed catalog UI, graph UI, pytest, network federation
2026-06-15	REUSE-WP-0011 closed priority 17; hub live at reuse.coulomb.social
2026-06-15	Post-WP-0011 refresh: 20 capabilities, vector D5/A4/C4/R3, priorities 18–23 proposed
2026-06-15	REUSE-WP-0012 proposed; assessment archived in history/2026-06-15-intent-scope-assessment.md