reuse-surface/docs/IntentScopeGapAnalysis.md

INTENT ↔ SCOPE Gap Analysis

Repository: reuse-surface
Artifact: docs/IntentScopeGapAnalysis.md
Status: Living analysis
Updated: 2026-06-16
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 after REUSE-WP-0012 are operational scale items:

1. Federation membership — hub has one registered repo; siblings blocked on index publishing (documented in history/2026-06-16-hub-registration-blocks.md).
2. Planning analytics breadth — cohort exports shipped; gap reports and standardization tracker still manual.
3. Hub automation — hub sync shipped; polling/webhooks still absent.
4. Managed platform posture — A5 container documented; A6/Postgres deferred.

Current reuse-surface product vector (self-assessment): D5 / A4 / C5 / 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; cohort reports added	Partial
Repository layout in INTENT	standards/, JSON schema, single yaml	Aligned in WP-0012	Aligned
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 (Medium — blocked on siblings)

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 from 1 repo	Sibling indexes not published (303)

Status (WP-0012): Publish contract in docs/RegistryFederation.md; blocks documented in history/2026-06-16-hub-registration-blocks.md. Registration unblocks when sibling repos ship raw indexes.

3.2 Planning support breadth (Low–Medium)

INTENT claim	Current SCOPE reality	Gap
Plan prototype/MVP/enhancement/platform work	report cohorts, query, catalog	No gap reports or roadmap views
Identify gaps, duplicates, overlaps, standardization	overlaps command	No standardization tracker
Track progress to generalized capabilities (D7)	promotion_history per entry	No cross-entry D7 pipeline view

Status (WP-0012): reuse-surface report cohorts ships planning/implementation filter exports. Broader portfolio analytics remain future work.

3.3 Hub operations (Low–Medium)

INTENT claim	Current SCOPE reality	Gap
Offline federation manifest sync	hub sync with --merge / --replace	Shipped
Operational reuse	Production hub; hardening doc	No polling/webhooks; SQLite single-replica

Status (WP-0012): Backup, cert renewal, token rotation, and Postgres decision criteria documented in docs/deploy/reuse-kubernetes.md. Multi-replica implementation deferred.

3.4 Consumer reliability evidence (Low–Medium)

INTENT claim	Current SCOPE reality	Gap
Reliability from consumer signals	Schema + checklist in registry/README.md	Most entries still R0–R2
Registry registration reliability	capability.registry.register at R3	Broader catalog evidence thin

Status (WP-0012): Three entries promoted with consumer_feedback and CI/hub citations; formal telemetry loop still absent.

---

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	report cohorts + query/catalog; no gap 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 + hub sync + production hub; 1 member	C4
Agent instructions	Expected	AGENTS.md + tools README	C4
Technical consumption	A3+ for tools	CLI A3, hub A4	C4
Planning analytics	Success criteria	report cohorts	C3
Documentation canon	Concept + assessment	Concept doc; assessment via README	C4

Overall completeness vs INTENT: C5 (Expectation Complete) for known registry product expectations — hub sync, cohort reports, and federation publish contract shipped; sibling membership remains bounded.

---

7. Reliability Assessment (SCOPE vs INTENT)

Signal	State
Automated tests	pytest (registry, federation, hub, hub_sync, reports)
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	Deferred — blocks documented; awaiting sibling indexes
19	hub sync	Write sources.yaml from hub state	Closed (WP-0012)
20	Planning cohort reports	Export/filter views for D5+/A4+ candidates	Closed (WP-0012)
21	INTENT layout sync	Update INTENT.md tree and example entry shape	Closed (WP-0012)
22	Hub hardening	Postgres option, backup, documented SLO (A5→A6 path)	Closed (doc; implementation deferred)
23	External evidence program	Raise catalog R levels with consumer_feedback	Closed (checklist + 3 entries; telemetry deferred)

Workplan: REUSE-WP-0012 (finished). Assessment snapshots: history/2026-06-15-intent-scope-assessment.md, history/2026-06-16-hub-registration-blocks.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
2026-06-16	REUSE-WP-0012 closed priorities 19–23; priority 18 deferred on sibling index blocks; vector C5