generated from coulomb/repo-seed
tegwick
41f7a2b53a
Some checks failed
ci / validate-registry (push) Has been cancelled
Persist intent-scope snapshot (priorities 25–27). Workplan covers Gitea publish remediation, owner dedup, planning analytics, and compose acceptance.
11 KiB
11 KiB
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.
Canon: Product truth in INTENT.md; delivery truth in SCOPE.md.
1. Summary
INTENT.md defines the long-term capability registry product: a reuse surface
that makes capabilities visible, assessable, and consumable for planning and
implementation across repos and organizations.
SCOPE.md (refreshed post–WP-0014) describes current delivery:
| Dimension | Delivered today |
|---|---|
| Registry product | 20 helix_forge entries in reuse-surface; maturity model, schema, validation |
| Tooling | CLI A3+; hosted hub HTTP API A4 at https://reuse.coulomb.social |
| Federation | 60 hub registrations; 60 URL sources; 37 composed federated rows |
| Workstation rollout | 60/60 local repos established (local-repo-roster.yaml) |
| Authoring aids | establish, update, stats, optional llm-connect discover |
| Observability | report cohorts, catalog/graph UIs, pytest + CI gates |
REUSE-WP-0001 through REUSE-WP-0014 closed the MVP, federation hub, intent alignment, registry bootstrap, and local workstation registry rollout. The documents remain directionally aligned on registry-first reuse, four maturity dimensions, and human/agent consumers.
Open gaps (operator or follow-on workplans):
- Gitea publish visibility — 13/60 repos fail raw URL probe (federation fetch).
- Index deduplication — 16 duplicate IDs (reuse-surface vs owner repos).
- Planning analytics breadth — no gap reports, roadmap views, or standardization tracker.
- Hub automation — no polling/webhooks for federated refresh.
- Managed platform posture — A6/Postgres/multi-replica not implemented.
- Consumer reliability evidence — catalog mostly R0–R2; thin telemetry loop.
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; internal vs external evidence | Same in entries and schema | Aligned |
| Human and agent consumers | Registry formats for both | Markdown + YAML + CLI + hub API | Aligned |
| Reuse over inventory | Explicit principle | Query, overlaps, federation, dedup plan | Aligned |
| Planning vs implementation reuse | Distinct dimensions | Query, vectors, consumption_modes |
Aligned |
| Technical foundation | Eventually technical | CLI A3, hub A4, container A5 artifact | Aligned |
| Cross-repo capability visibility | Reuse across repos/products/orgs | 60 repos scaffolded; 37 federated caps | Partial |
| Generalized primitives (D7) | Beyond single repo/domain | helix_forge only; no D7 pipeline view | Partial |
| Success criteria (8 outcomes) | See §5 | Most met; analytics + normalization partial | Partial |
| Repository layout | Tree in INTENT §Initial Repository Role | Matches SCOPE; roster artifact added | Aligned |
| State Hub / workplans | Not in INTENT | ADR-001 sync; delivery process | SCOPE-only (OK) |
| Hosting capabilities | Out of scope | Hub stores metadata/URLs only | Aligned |
3. INTENT → SCOPE Gaps (Open)
What INTENT.md still expects beyond current SCOPE.md delivery.
3.1 Cross-repo federation fetch and namespace (Medium)
| INTENT claim | SCOPE reality | Gap |
|---|---|---|
| Capabilities reusable across repos, products, orgs | 60 repos on hub; 37 federated rows | Single domain (helix_forge) |
| Find capabilities before rebuilding at network scale | Hub + compose + roster | 13 indexes not HTTP-fetchable |
| Identify duplicates (success criterion) | overlaps + compose warn |
16 duplicate IDs unresolved in indexes |
Follow-up: history/2026-06-16-wp0014-remaining-work-by-repo.md (Gitea);
history/2026-06-16-federation-deduplication-plan.md (reuse-surface dedup).
3.2 Planning support breadth (Low–Medium)
| INTENT claim | SCOPE reality | Gap |
|---|---|---|
| Plan prototype/MVP/enhancement/platform work | report cohorts, query, catalog |
No portfolio gap reports |
| Identify gaps, overlaps, standardization candidates | overlaps |
No standardization workflow |
| Track progress to generalized capabilities (D7) | Per-entry promotion_history |
No cross-entry D7 pipeline |
3.3 Hub operations (Low–Medium)
| INTENT claim | SCOPE reality | Gap |
|---|---|---|
| Operational federation | Production hub; hub sync |
On-demand compose; no webhooks |
| Dependable platform consumption (R4+) | Container deploy doc | SQLite single-replica; no SLO enforcement |
3.4 Consumer reliability evidence (Low–Medium)
| INTENT claim | SCOPE reality | Gap |
|---|---|---|
| Reliability from consumer signals | Schema + README checklist | Most entries R0–R2 |
| Trust for important workflows (R4+) | CI + hub smoke | No formal consumer_feedback loop |
3.5 Owner-repo capability depth (Low — ongoing)
| INTENT claim | SCOPE reality | Gap |
|---|---|---|
| Rich registry across organization | 60 scaffolds; 8 seeded | 47 repos at capability_count 0 |
| Discover mature capabilities network-wide | 37 federated rows | Growth is per-repo, optional |
4. Closed Gaps (Historical)
| Workplan / milestone | Gap closed | Evidence |
|---|---|---|
| WP-0003 – WP-0011 | MVP CLI, validation, catalog, federation, hub | Archived workplans; pytest |
| WP-0012 | hub sync, cohort reports, INTENT layout, hub hardening doc |
hub_sync.py, docs/deploy/ |
| WP-0013 | Registry bootstrap in sibling repos | establish, update, stats |
| WP-0014 | Workstation registry rollout; hub 60 registrations | local-repo-roster.yaml; milestone history |
| Priority 18 | Sibling / workstation hub membership | 60/60 hub list |
| Priority 19–24 | See §8 | WP-0012/0013 deliveries |
5. INTENT Success Criteria vs SCOPE Delivery
From INTENT.md §Success Criteria:
| # | Criterion | Met? | SCOPE evidence | Remaining gap |
|---|---|---|---|---|
| 1 | Find reusable capabilities before rebuilding | Yes | Index, query, catalog, hub /v1/federated, federation compose |
13 sources not fetchable |
| 2 | Compare maturity consistently | Yes | Vectors, schema, graph relations | — |
| 3 | Distinguish conceptual readiness from delivery | Yes | D vs A in model and index | — |
| 4 | Distinguish internal assessment from external evidence | Yes | maturity vs external_evidence |
— |
| 5 | Plan prototype/MVP/enhancement/platform work | Partial | report cohorts, query |
No gap/roadmap reports |
| 6 | Identify gaps, duplicates, overlaps, standardization | Partial | overlaps, compose collision warnings |
Dedup + standardization tracker |
| 7 | Track progress to generalized capabilities (D7) | Partial | promotion_history per entry |
No org-wide D7 view |
| 8 | Make reuse normal in architecture work | Partial | AGENTS.md, 60-repo rollout | Publish + dedup polish |
Score: 4 fully met, 4 partial — consistent with C5 product completeness for known registry expectations, not yet saturated (C6).
6. Completeness Assessment (SCOPE vs INTENT)
| Area | INTENT expectation | Current delivery | Level |
|---|---|---|---|
| Registry model and principles | Full | INTENT + specs | C5 |
| Maturity standard | Full | CapabilityMaturityStandard.md |
C5 |
| Entry authoring | Full for MVP | Template + schema + README | C5 |
| Seed registry (reuse-surface) | Examples + meta | 20 entries | C4 |
| Discovery surface | Machine-readable | Index, query, export, hub API, federated | C5 |
| Validation | Tooling | validate + CI |
C5 |
| Search / filter | Supported | query, catalog HTML | C4 |
| Federation membership | Cross-repo | 60 hub members; compose + sync | C5 |
| Federation fetch reliability | Published indexes | 47/60 publish pass | C3 |
| Workstation bootstrap | Org-wide visibility | Roster + establish tooling | C4 |
| Agent instructions | Expected | AGENTS.md, tools README | C4 |
| Technical consumption | A3+ tools | CLI A3, hub A4 | C4 |
| Planning analytics | Success criteria | report cohorts |
C3 |
| Documentation canon | Concept + living delta | Concept doc + this file | C4 |
Overall completeness vs INTENT: C5 for reuse-surface product scope; C3 for end-to-end fetchable federation until Gitea blockers clear.
7. Reliability Assessment (SCOPE vs INTENT)
| Signal | State |
|---|---|
| Automated tests | pytest (registry, federation, hub, hub_sync, stats, reports) |
| CI gates | validate, federation compose, catalog, graph, pytest |
| Production hub | reuse.coulomb.social — TLS, 60 registrations |
| Workstation rollout | Deterministic establish/validate; roster tracked |
| Consumer feedback | Informal; 3 entries with structured consumer_feedback |
| Known friction | 13 Gitea 404; 16 duplicate IDs; hub SQLite single-replica |
Overall reliability vs INTENT consumer-evidence framing: R3 (Usable) — CI and production paths support normal agent/operator workflows with documented limitations. R4 (Dependable) blocked on SLO, backup automation, and consumer telemetry.
8. Priority Gap Closure Order
Closed (priorities 1–24)
See §4 and archived workplans workplans/archived/.
Proposed next (priorities 25–27)
| Priority | Gap | Suggested outcome | Status |
|---|---|---|---|
| 25 | Gitea publish visibility (13 repos) | Raw URL HTTP 200 for all roster rows | REUSE-WP-0015-T01 |
| 26 | Federated ID deduplication | Per-owner removal from reuse-surface index | REUSE-WP-0015-T02 |
| 27 | Planning analytics + standardization | Gap report or standardization tracker | REUSE-WP-0015-T03 |
Workplan: workplans/REUSE-WP-0015-federation-polish-and-planning-analytics.md
Assessment: history/2026-06-16-intent-scope-assessment.md
Follow-up docs:
history/2026-06-16-wp0014-remaining-work-by-repo.mdhistory/2026-06-16-federation-deduplication-plan.mdregistry/federation/local-repo-roster.yaml
9. Document Maintenance Rules
- Re-run this analysis when
INTENT.mdorSCOPE.mdchanges materially. - When a gap closes, update §3–§8 and adjust the self-assessment vector in
SCOPE.md. - New workplans should reference priority rows from §8.
- Prefer
SCOPE.mdfor delivery truth;INTENT.mdfor product truth.
10. Change Log
| Date | Change |
|---|---|
| 2026-06-15 | Initial analysis after REUSE-WP-0002 |
| 2026-06-15 | WP-0003–0011 progress; vector milestones |
| 2026-06-16 | WP-0012 closed priorities 19–23 |
| 2026-06-17 | WP-0013 closed priority 24 |
| 2026-06-16 | WP-0014 closed priority 18; 60 workstation repos |
| 2026-06-16 | SCOPE refresh + full INTENT success-criteria mapping; priorities 25–27 proposed |
| 2026-06-16 | Assessment persisted; REUSE-WP-0015 created for priorities 25–27 |