generated from coulomb/repo-seed
tegwick
270065ff58
Some checks failed
ci / validate-registry (push) Has been cancelled
Add hub sync and report cohorts CLI commands with pytest coverage, document sibling index publish contract and hub hardening path, align INTENT layout, raise external evidence on three registry entries, and close gap priorities 19-23 (priority 18 deferred on sibling index blocks).
230 lines
11 KiB
Markdown
230 lines
11 KiB
Markdown
# 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 | |