reuse-surface/docs/IntentScopeGapAnalysis.md

# INTENT ↔ SCOPE Gap Analysis

**Repository:** `reuse-surface`  
**Artifact:** `docs/IntentScopeGapAnalysis.md`  
**Status:** Living analysis  
**Created:** 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 actually delivers today: an MVP registry
with **A3 CLI tooling** (`validate`, `query`, `export`) atop Markdown-first
authoring.

The two documents are **directionally aligned** on registry-first reuse, four
maturity dimensions, and human/agent consumers. REUSE-WP-0003 through REUSE-WP-0010 closed the priority gaps from section 8.
Remaining gaps are primarily document cross-coverage and operational polish:

1. **Document cross-coverage** — SCOPE still carries operational detail INTENT
   omits; INTENT success criteria are not fully enumerated in SCOPE.
2. **Live federation sync** — on-demand HTTP fetch only; no polling or webhooks.

**Current reuse-surface vector (self-assessment):** `D5 / A3 / C4 / R3`

---

## 2. Alignment Matrix

| Topic | INTENT.md | SCOPE.md | Status |
|---|---|---|---|
| Registry-first boundary | Unregistered capabilities are invisible | Same | Aligned |
| Four maturity dimensions | D, A, C, R with separate internal/external evidence | Same model in use | Aligned |
| Human and agent consumers | Registry formats for both | Markdown + YAML index | Aligned |
| Reuse over inventory | Explicit principle | Implicit in workflows | Aligned |
| Planning vs implementation reuse | Distinct dimensions | Reflected in query guidance | Aligned |
| No internal code quality as maturity | Out of scope | Out of scope | Aligned |
| No hosting registered capabilities | Implied | Explicit out of scope | Aligned |
| Target maturity vectors | Expected per capability | Supported in entry schema | Aligned |
| Broken expectations as evidence | Guiding principle | Supported in schema/entries | Aligned |
| Technical foundation | "Eventually technical" | A0 only, no CLI/API | Gap |
| Success criteria | Eight outcomes listed | Partially met, not enumerated | Gap |
| Repository layout | `standards/`, `docs/`, JSON schema | `specs/`, `docs/` missing, YAML schema | Drift |
| State Hub / workplans | Not mentioned | In scope and current state | SCOPE-only |
| MVP acceptance criteria | Not mentioned | Claimed satisfied manually | SCOPE-only |
| Domain scope | Cross-repo/product/org | helix_forge sample registry | Narrower delivery |

---

## 3. INTENT → SCOPE Gaps

What INTENT declares that SCOPE does not yet deliver.

### 3.1 Technical foundation (High)

| INTENT claim | Current SCOPE reality | Gap |
|---|---|---|
| "Conceptual, structural, and **eventually technical** foundation" | Documentation-only repo, A0 availability | No CLI, validator, exporter, or API |
| Implementation support through discoverable consumption modes | Manual index filtering only | No machine-assisted query or export |
| Reference tooling | `tools/README.md` documents planned commands | Executable tools do not exist |

**Impact:** Implementation reuse still depends on humans/agents reading files.
INTENT's "available enough to build with" mantra is only partially true for
registry metadata itself.

**Suggested follow-up:** Workplan for CLI validate/query/export (PRD section 17).

### 3.2 Planning support breadth (Medium)

| INTENT claim | Current SCOPE reality | Gap |
|---|---|---|
| Planning support for prototype, MVP, enhancement, platform decisions | Manual compare/search guidance | No gap reports, roadmap views, or platformization filters |
| Identify capability gaps, duplicates, overlaps, standardization candidates | Duplicate guidance only | No overlap detection, gap aggregation, or standardization workflow |
| Track progress from named ideas to generalized capabilities | Promotion via front matter edits | No promotion history or changelog |

**Impact:** Planning reuse works for small registries; does not scale without
tooling or disciplined manual process.

**Suggested follow-up:** Index views for "D5+/A0-A1" planning candidates and
"D5+/A4+" implementation candidates; promotion history field or log.

### 3.3 Success criteria coverage (Medium)

INTENT success criteria vs current delivery:

| Success criterion | Met today? | Notes |
|---|---|---|
| Find reusable capabilities before rebuilding | Partial | Index + 3 samples; coverage is thin |
| Compare maturity consistently | Yes | Vectors and schema enums |
| 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 only, no reports |
| Identify gaps, duplicates, overlaps, standardization candidates | Partial | Manual duplicate check only |
| Track progress to generalized capabilities | No | No history or timeline |
| Make reuse normal in product/architecture work | Partial | Agent instructions exist; tooling weak |

### 3.4 Expected repository layout (Low–Medium)

INTENT "Initial Repository Role" layout differs from delivered layout:

| INTENT path | Delivered path | Drift |
|---|---|---|
| `standards/CapabilityMaturityStandard.md` | `specs/CapabilityMaturityStandard.md` | Renamed directory |
| `registry/capabilities.yaml` | `registry/capabilities/*.md` + `registry/indexes/capabilities.yaml` | Split canonical entries and index |
| `registry/examples/` | `registry/capabilities/` (samples inline) | Different organization |
| `schemas/capability.schema.json` | `schemas/capability.schema.yaml` | Format and location differ |
| `docs/CapabilityRegistryConcept.md` | Missing | Not authored |
| `docs/CapabilityAssessmentGuide.md` | Partially covered by `registry/README.md` | Concept guide missing |

**Impact:** New contributors reading INTENT first will look for paths that do
not exist. SCOPE layout is authoritative for operations; INTENT layout is stale.

**Suggested follow-up:** Update INTENT "Initial Repository Role" to match
delivered structure, or add redirect notes.

### 3.5 Registry entry shape drift (Low)

INTENT example uses:

```yaml
external_evidence:
  completeness:
    current: C1
  reliability:
    current: R0
```

Implemented schema and entries use `level` instead of `current` under
`external_evidence`, matching `specs/CapabilityMaturityStandard.md` section 10.

**Impact:** Minor authoring confusion between INTENT and schema/template.

**Suggested follow-up:** Align INTENT example to `level` or document the alias.

### 3.6 Consumer reliability evidence (Medium)

INTENT requires reliability from bugs, tickets, incidents, ratings, adoption.
SCOPE supports recording fields but:

- No sample entry has reliability above R0 except the feature-control example
  (R3 with thin evidence)
- reuse-surface itself has **R0** — no consumer feedback loop for the registry

**Impact:** External evidence dimension is structurally present but weakly
populated.

---

## 4. SCOPE → INTENT Gaps

What SCOPE asserts that INTENT does not declare.

### 4.1 Operational integration (Low)

SCOPE includes State Hub workplans, ADR-001 consistency sync, and session
protocol. INTENT is product-conceptual and omits custodian workflow entirely.

**Assessment:** Not a product conflict. SCOPE correctly adds repository
operations. INTENT may optionally reference workplan-driven evolution.

### 4.2 MVP framing (Low)

SCOPE maps deliverables to `specs/ProductRequirementsDocument.md` sections 15–16
and claims MVP acceptance criteria are met manually. INTENT does not define MVP
boundaries or acceptance tests.

**Assessment:** SCOPE is more precise about current phase. INTENT remains the
north star; SCOPE is the phase boundary.

### 4.3 Domain anchoring (Low)

SCOPE inventories three **helix_forge** sample capabilities. INTENT describes
cross-repo, product, and organizational reuse generically.

**Assessment:** Expected at MVP stage. INTENT target of D7 generalized primitives
is not contradicted — sample scope is intentionally narrow.

### 4.4 Verification commands (Low)

SCOPE documents `rg --files`, `git diff --check`, and fix-consistency. INTENT
has no verification or change-management guidance.

**Assessment:** SCOPE appropriately operationalizes delivery discipline.

---

## 5. Contradictions and Broken Expectations

Explicit mismatches a consumer might reasonably assume from reading both files:

| Expectation | Source | Reality | Severity |
|---|---|---|---|
| "Eventually technical foundation" is underway | INTENT scope section | No package, CLI, or API | Medium |
| Maturity standard lives under `standards/` | INTENT layout | Lives under `specs/` | Low |
| Single `capabilities.yaml` registry file | INTENT layout | Per-entry Markdown + separate index | Low |
| JSON schema file exists | INTENT layout | YAML JSON Schema instead | Low |
| Concept and assessment guides exist under `docs/` | INTENT layout | Only this gap analysis so far | Medium |
| Registry can be searched by maturity automatically | INTENT success + SCOPE "possible now" | Manual index scan only | Medium |
| Implementation reuse is supported | INTENT in-scope bullet | Only for entries with A2+ artifacts elsewhere | Medium |

No direct logical contradiction on registry-first boundary or maturity model
separation was found.

---

## 6. Completeness Assessment (SCOPE vs INTENT)

Using INTENT's own completeness framing for the **reuse-surface product**:

| Area | INTENT expectation | Current SCOPE delivery | Level |
|---|---|---|---|
| Registry model and principles | Full | `INTENT.md` + `specs/` | C4 |
| Maturity standard | Full | `specs/CapabilityMaturityStandard.md` | C5 |
| Entry authoring | Full for MVP | Template + schema + README | C4 |
| Sample registry | Examples expected | 3 helix_forge entries | C3 |
| Discovery surface | Machine-readable | YAML index | C3 |
| Validation | Implied tooling | Manual checklist | C2 |
| Search/filter | Supported | Documented manual patterns | C2 |
| Agent instructions | Expected | `AGENTS.md` registry section | C4 |
| Technical consumption of registry | A3+ target natural for tools | A0 | C1 |
| Consumer evidence for registry itself | Should be recorded | None (R0) | C1 |
| Planning reports and gap analytics | Success criteria | Not present | C1 |
| Documentation canon | Concept + assessment guides | Partial | C2 |

**Overall completeness vs INTENT:** **C3 (Functional Core)** — the central
registry MVP works manually, but variants, tooling, evidence, and conceptual
docs remain incomplete.

---

## 7. Reliability Assessment (SCOPE vs INTENT)

| Signal | State |
|---|---|
| Automated tests | `tests/` — pytest covers validate, query, export, overlaps, federation, graph, catalog |
| Schema validation in CI | `.gitea/workflows/ci.yml` — validate, federation, catalog, graph, pytest |
| Consumer feedback on registry workflows | None |
| Production or repeated agent usage evidence | None |
| Known friction | Manual index maintenance; schema/INTENT field naming drift |

**Overall reliability vs INTENT consumer-evidence framing:** **R3 (Proven in
Development)** for registry CLI tooling — pytest suite and CI gates exercise
core commands. Individual registered capabilities may carry their own evidence
(e.g. feature-control at R3).

---

## 8. Priority Gap Closure Order

| Priority | Gap | Outcome | Status |
|---|---|---|---|
| 1 | INTENT layout stale | INTENT layout aligned to delivered structure | Closed (WP-0003) |
| 2 | No automated validation | `reuse-surface validate` | Closed (WP-0003) |
| 3 | Thin registry coverage | Six helix_forge entries | Closed (WP-0003) |
| 4 | Missing concept docs | `docs/CapabilityRegistryConcept.md` | Closed (WP-0003) |
| 5 | No promotion history | `promotion_history` in schema/template | Closed (WP-0003) |
| 6 | Search/filter manual only | `reuse-surface query` | Closed (WP-0003) |
| 7 | No registry export | `reuse-surface export` | Closed (WP-0003) |
| 8 | Self-reliability evidence | `capability.registry.register` at R2; friction recorded | Closed (WP-0003) |

### Next recommended work

| Priority | Gap | Outcome | Status |
|---|---|---|---|
| 9 | Catalog site | `reuse-surface catalog` → MD + HTML | Closed (WP-0004) |
| 10 | Overlap detection | `reuse-surface overlaps` | Closed (WP-0004) |
| 11 | CI validation | `.gitea/workflows/ci.yml` | Closed (WP-0004) |
| 12 | Registry federation | `federation compose` + federated index | Closed (WP-0005) |
| 14 | Graph visualization | `reuse-surface graph` Mermaid output | Closed (WP-0005) |

| Priority | Gap | Outcome | Status |
|---|---|---|---|
| 13 | Interactive catalog | `docs/catalog/search.html` + `registry.json` | Closed (WP-0007) |
| 15 | Network federation | HTTP URL sources + cache in `federation compose` | Closed (WP-0010) |
| 16 | Graph UI | `docs/graph/index.html` explorer | Closed (WP-0008) |

### Proposed next work

| Priority | Gap | Suggested outcome | Status |
|---|---|---|---|
| 17 | Hosted federation hub | Hub service on `railiance01` + `reuse-surface hub` CLI | Proposed (WP-0011) |

---

## 9. Document Maintenance Rules

- Re-run this analysis when either `INTENT.md` or `SCOPE.md` changes materially.
- When a gap closes, update section 3–5 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 priority gaps 1–8; vector updated to D5/A3/C4/R2 |
| 2026-06-15 | REUSE-WP-0004 closed priorities 9–11 (catalog, overlaps, CI) |
| 2026-06-15 | REUSE-WP-0005 closed priorities 12 and 14 (federation, relation graphs) |
| 2026-06-15 | REUSE-WP-0006 expanded registry to 12 capabilities; relation hygiene clean |
| 2026-06-15 | REUSE-WP-0007 closed priority 13 (searchable catalog UI) |
| 2026-06-15 | REUSE-WP-0008 closed priority 16 (graph explorer) |
| 2026-06-15 | REUSE-WP-0009 added pytest suite and CI fail-on-warnings; vector R3 |
| 2026-06-15 | REUSE-WP-0010 closed priority 15 (HTTP remote federation + cache) |
| 2026-06-15 | REUSE-WP-0011 proposed for priority 17 (hosted hub on railiance01) |