generated from coulomb/repo-seed
tegwick
3cbf2109d3
Some checks failed
ci / validate-registry (push) Has been cancelled
Archive INTENT↔SCOPE assessment in history/ and map gap priorities 18–23 to follow-up tasks for federation scale and intent alignment.
254 lines
12 KiB
Markdown
254 lines
12 KiB
Markdown
# 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` | |