tegwick
70a5003f6e
Add stats, establish (scaffold, publish-check, discover), and update CLI commands with optional llm-connect bridge, validate --root for sibling repos, pytest coverage, and documentation for sibling registry onboarding.
11 KiB
INTENT ↔ SCOPE Gap Analysis
Repository: reuse-surface
Artifact: docs/IntentScopeGapAnalysis.md
Status: Living analysis
Updated: 2026-06-17
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:
- Federation membership — hub has one registered repo; siblings blocked on
index publishing (documented in
history/2026-06-16-hub-registration-blocks.md). - Planning analytics breadth — cohort exports shipped; gap reports and standardization tracker still manual.
- Hub automation —
hub syncshipped; polling/webhooks still absent. - Managed platform posture — A5 container documented; A6/Postgres deferred.
- Registry bootstrap in sibling repos —
establish/update/statsshipped; sibling adoption still operator-driven.
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) |
| 24 | Registry bootstrap tooling | establish, update, stats for sibling repos |
Closed (WP-0013) |
Workplan: REUSE-WP-0013 (finished). Prior: 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.mdorSCOPE.mdchanges 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.mdfor delivery truth andINTENT.mdfor 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 |
| 2026-06-17 | REUSE-WP-0013 closed priority 24; establish/update/stats + optional llm-connect assist |