generated from coulomb/repo-seed
tegwick
c366fc4a4e
Some checks failed
ci / validate-registry (push) Has been cancelled
Add Gitea CI workflow for registry validation, reuse-surface overlaps and catalog commands, generated catalog artifacts, and documentation updates closing gap analysis priorities 9-11.
299 lines
13 KiB
Markdown
299 lines
13 KiB
Markdown
# 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 closed the
|
||
priority gaps from section 8. Remaining gaps are primarily scale, automation,
|
||
and presentation concerns:
|
||
|
||
1. **Planning analytics** — no gap reports, overlap detection, or catalog site.
|
||
2. **Reliability depth** — registry product dogfood evidence is early (R2).
|
||
3. **Document cross-coverage** — SCOPE still carries operational detail INTENT
|
||
omits; INTENT success criteria are not fully enumerated in SCOPE.
|
||
|
||
**Current reuse-surface vector (self-assessment):** `D5 / A3 / C4 / R2`
|
||
|
||
---
|
||
|
||
## 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 | None |
|
||
| Schema validation in CI | None |
|
||
| 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:** **R0 (Unknown)** for
|
||
the registry product itself. 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 | Cross-repo capability index composition | Open |
|
||
|
||
| Priority | Gap | Suggested outcome |
|
||
|---|---|---|
|
||
| 13 | Interactive catalog | Searchable catalog UI beyond static HTML |
|
||
| 14 | Graph visualization | Capability relation graphs |
|
||
| 15 | Federation | Compose indexes across repositories |
|
||
|
||
---
|
||
|
||
## 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) | |