# 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-0014 rollout are **operational polish** items:

1. **Gitea publish visibility** — 60/60 workstation repos established and hub
   registered; **13/60** still fail Gitea raw URL probe (operator action). Roster:
   `registry/federation/local-repo-roster.yaml`.
2. **Index deduplication** — 16 duplicate IDs across reuse-surface and owner repos;
   removal plan in `history/2026-06-16-federation-deduplication-plan.md`.
3. **Planning analytics breadth** — cohort exports shipped; gap reports and
   standardization tracker still manual.
4. **Hub automation** — `hub sync` shipped; polling/webhooks still absent.
5. **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; hub 60 repos; 37 federated caps | 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 — polish remaining)

| INTENT claim | Current SCOPE reality | Gap |
|---|---|---|
| Capabilities reusable across repos, products, orgs | 20 reuse-surface entries + 17 owner rows; 37 federated | No multi-domain federation yet |
| Find capabilities before rebuilding (network scale) | Hub **60** registrations; compose **37** capabilities | 13 repos Gitea raw 404; 16 duplicate IDs |

**Status (WP-0014):** All workstation repos (`~/<slug>/`) established with
registry scaffolds. `hub sync --merge` materializes 60 URL sources. Operator
must fix Gitea visibility for 13 slugs (see roster). Deduplicate owner-migrated
entries per `history/2026-06-16-federation-deduplication-plan.md`.

### 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 60 repos; publish/dedup polish |

---

## 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; 60 hub members; 37 federated caps | C5 |
| 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 — workstation rollout (60 repos), hub sync,
cohort reports, and federation compose shipped; Gitea publish and dedup remain.

---

## 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 | 13 Gitea raw 404 repos; 16 federated duplicate IDs; hub SQLite single-replica |

**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 | Workstation repos on hub | **Closed** (WP-0014) — 60/60 registered; 13 publish blocked |
| 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-0014` (finished). Prior: `REUSE-WP-0013`, `REUSE-WP-0012`.
**Assessment snapshots:**
`history/2026-06-15-intent-scope-assessment.md`,
`history/2026-06-16-hub-registration-blocks.md`,
`history/2026-06-16-local-repo-registry-rollout-complete.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 |
| 2026-06-17 | REUSE-WP-0013 closed priority 24; establish/update/stats + optional llm-connect assist |
| 2026-06-16 | REUSE-WP-0014 closed priority 18; 60 workstation repos; roster + federation compose |