coulomb/reuse-surface
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refresh SCOPE and INTENT gap analysis after WP-0011
Some checks failed
ci / validate-registry (push) Has been cancelled
Details

Browse Source 
SCOPE reflects 20 capabilities, production hub (A4), and current limits.
Gap analysis closes historical MVP gaps and proposes priorities 18–23.
Self-assessed product vector: D5 / A4 / C4 / R3.
This commit is contained in:
Bernd Worsch
2026-06-16 00:30:53 +02:00
parent 218959b113
commit 5fcca42879
2 changed files with 216 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
SCOPE.md
View File

@@ -14,8 +14,8 @@ for reuse within this product boundary.
## In Scope ## In Scope
- Maintain the capability maturity model, standards, schemas, registry formats, - Maintain the capability maturity model, standards, schemas, registry formats,
sample entries, indexes, validation guidance, CLI tooling, and agent sample entries, indexes, validation guidance, CLI tooling, hub service, and
instructions. agent instructions.
- Keep `INTENT.md`, `specs/`, registry artifacts, and State Hub workplans - Keep `INTENT.md`, `specs/`, registry artifacts, and State Hub workplans
aligned on the registry-first reuse boundary. aligned on the registry-first reuse boundary.
- Support humans and agents as registry consumers through Markdown-first - Support humans and agents as registry consumers through Markdown-first
@@ -26,7 +26,8 @@ for reuse within this product boundary.
## Out of Scope ## Out of Scope
- Host or operate the registered capabilities themselves. - Host or operate the registered capabilities themselves (except the federation
hub coordinator, which stores repo metadata and index URLs only).
- Replace package registries, service catalogs, issue trackers, or project - Replace package registries, service catalogs, issue trackers, or project
management systems. management systems.
- Judge internal code quality as capability maturity. - Judge internal code quality as capability maturity.
@@ -35,15 +36,15 @@ for reuse within this product boundary.
## What Is Possible Now ## What Is Possible Now
The MVP registry foundation plus CLI tooling (REUSE-WP-0003) is in place. Humans The MVP registry foundation, CLI tooling (REUSE-WP-0003), federation stack
and agents can: (WP-0005/0010), and hosted hub (WP-0011) are in place. Humans and agents can:
- **Discover capabilities** via `registry/indexes/capabilities.yaml` or - **Discover capabilities** via `registry/indexes/capabilities.yaml`,
`reuse-surface query` `reuse-surface query`, or `GET https://reuse.coulomb.social/v1/federated`
- **Add a new capability** at D0/A0/C0/R0 using - **Add a new capability** at D0/A0/C0/R0 using
`templates/capability-entry.template.md` `templates/capability-entry.template.md`
- **Promote capabilities** with evidence, optional `promotion_history`, and index - **Promote capabilities** with evidence, `promotion_history`, and index vector
vector updates updates
- **Compare candidates** using maturity vectors, scope, relations, and consumer - **Compare candidates** using maturity vectors, scope, relations, and consumer
guidance guidance
- **Record expectations** through `external_evidence.completeness` and - **Record expectations** through `external_evidence.completeness` and
@@ -52,47 +53,58 @@ and agents can:
- **Export a machine-readable bundle** with `reuse-surface export` - **Export a machine-readable bundle** with `reuse-surface export`
- **Detect overlap candidates** with `reuse-surface overlaps` - **Detect overlap candidates** with `reuse-surface overlaps`
- **Generate a human-readable catalog** with `reuse-surface catalog` - **Generate a human-readable catalog** with `reuse-surface catalog`
- **Browse a searchable catalog** at `docs/catalog/search.html` (client-side - **Browse a searchable catalog** at `docs/catalog/search.html`
filter over `registry.json`)
- **Compose federated indexes** with `reuse-surface federation compose` - **Compose federated indexes** with `reuse-surface federation compose`
(local paths and remote HTTP URLs with cache) (local paths and remote HTTP URLs with cache)
- **Register federation sources on the hosted hub** with `reuse-surface hub` - **Register federation sources on the hosted hub** with `reuse-surface hub`
against `https://reuse.coulomb.social` (`GET /v1/federated` for discovery) against `https://reuse.coulomb.social`
- **Run the hub locally or in a container** with `reuse-surface serve`
- **Generate relation graphs** with `reuse-surface graph` - **Generate relation graphs** with `reuse-surface graph`
- **Explore relations interactively** at `docs/graph/index.html` - **Explore relations interactively** at `docs/graph/index.html`
- **Avoid duplicates** by querying the index and checking overlaps before adding entries - **Avoid duplicates** by querying the index and checking overlaps before adding
entries
Registry tooling availability is **A3** (CLI). The registry product itself is Registry **tooling** availability is **A4** (CLI plus hosted hub HTTP API).
still documentation-first for authoring; consumption combines Markdown entries, Registry **authoring** remains Markdown-first; consumption combines entries, the
the index, and CLI automation. index, CLI automation, and the production hub.
## What Is Not Possible Yet ## What Is Not Possible Yet
- Automatic polling/webhooks to refresh hub registrations (compose is on-demand) - **`reuse-surface hub sync`** — materialize local `sources.yaml` from hub state
- Packaged releases beyond local `pip install -e .`, container image, and Gitea CI - **Automatic hub refresh** — federated compose is on-demand; no polling or
webhooks
- **Cross-repo federation at scale** — hub has one registered repo; sibling
domains must publish capability indexes before registration
- **Planning analytics** — no gap reports, roadmap views, or maturity-filter
reports beyond manual query/export
- **Managed platform posture** — hub runs as a container (A5 artifact) without
documented SLO, multi-replica, or Postgres backing
- **Formal consumer feedback loop** for registry workflows (reliability evidence
is mostly structural: CI/tests, not production telemetry)
See `tools/README.md` for command reference. See `tools/README.md` for command reference.
## Current State ## Current State
- Status: active MVP registry with CLI tooling. - **Status:** active MVP registry with CLI, federation, and production hub.
- Twelve helix_forge capabilities are registered in `registry/capabilities/`. - **Capabilities:** 20 helix_forge entries in `registry/capabilities/`.
- `reuse-surface` CLI provides `validate`, `query`, and `export` via - **CLI / service:** `reuse_surface/` — validate, query, export, overlaps,
`pyproject.toml` and `reuse_surface/`. catalog, federation, graph, hub client, `serve` (FastAPI hub).
- `docs/CapabilityRegistryConcept.md` and `docs/IntentScopeGapAnalysis.md` - **Production hub:** `https://reuse.coulomb.social` on Railiance01
document onboarding and intent-scope tracking. (`92.205.62.239`); image `gitea.coulomb.social/coulomb/reuse-surface:cb7a6e4`;
- CI validates the registry and composes federation on push/PR. TLS live; dogfood registration for `reuse-surface` (12 capabilities composed
- Federated index: `registry/indexes/federated.yaml`. on `/v1/federated`).
- Relation graph: `docs/graph/capability-graph.mmd` and explorer at - **Specs:** `specs/FederationHubAPI.md`, `schemas/hub-registration.schema.yaml`.
`docs/graph/index.html`. - **Docs:** `docs/CapabilityRegistryConcept.md`, `docs/RegistryFederation.md`,
- Searchable catalog: `docs/catalog/search.html`. `docs/IntentScopeGapAnalysis.md`, deploy guide `docs/deploy/reuse-kubernetes.md`.
- Test suite: `tests/` (pytest). - **CI:** `.gitea/workflows/ci.yml` — validate, federation compose, catalog,
- Remote federation: HTTP URL sources with cache in `registry/federation/cache/`. graph, pytest (20 tests).
- Hosted federation hub: `https://reuse.coulomb.social` (REUSE-WP-0011, image - **Federated index:** `registry/indexes/federated.yaml` (local compose).
`gitea.coulomb.social/coulomb/reuse-surface`). - **Relation graph:** `docs/graph/capability-graph.mmd`, `docs/graph/index.html`.
- Finished workplans: `REUSE-WP-0001` through `REUSE-WP-0011` (hub archived - **Searchable catalog:** `docs/catalog/search.html`.
2026-06-15). - **Workplans:** REUSE-WP-0001 through REUSE-WP-0011 finished; WP-0011 archived
- **Self-assessed vector:** `D5 / A3 / C4 / R3` (see gap analysis). `workplans/archived/260615-REUSE-WP-0011-*.md`.
- **Self-assessed vector:** `D5 / A4 / C4 / R3` (see `docs/IntentScopeGapAnalysis.md`).
## Repository Layout ## Repository Layout
@@ -102,14 +114,19 @@ reuse-surface/
├── SCOPE.md ├── SCOPE.md
├── AGENTS.md ├── AGENTS.md
├── pyproject.toml ├── pyproject.toml
├── reuse_surface/ ├── Dockerfile
├── reuse_surface/ # CLI, hub service, federation, graph, catalog
├── specs/ ├── specs/
├── schemas/ ├── schemas/
├── templates/ ├── templates/
├── registry/ ├── registry/
│ ├── capabilities/ # per-entry Markdown
│ ├── indexes/ # capabilities.yaml, federated.yaml
│ └── federation/ # sources.yaml, cache/
├── docs/ ├── docs/
├── tools/ ├── tools/
└── workplans/ └── workplans/
└── archived/
``` ```
## Getting Oriented ## Getting Oriented
@@ -120,11 +137,13 @@ reuse-surface/
- Product requirements: specs/ProductRequirementsDocument.md - Product requirements: specs/ProductRequirementsDocument.md
- Use cases: specs/UseCaseCatalog.md - Use cases: specs/UseCaseCatalog.md
- Maturity standard: specs/CapabilityMaturityStandard.md - Maturity standard: specs/CapabilityMaturityStandard.md
- Hub API: specs/FederationHubAPI.md
- Registry index: registry/indexes/capabilities.yaml - Registry index: registry/indexes/capabilities.yaml
- Registry guidance: registry/README.md - Registry guidance: registry/README.md
- Federation guide: docs/RegistryFederation.md
- Hub deployment: docs/deploy/reuse-kubernetes.md
- Generated catalog: docs/CapabilityCatalog.md - Generated catalog: docs/CapabilityCatalog.md
- Searchable catalog: docs/catalog/search.html - Searchable catalog: docs/catalog/search.html
- Federation guide: docs/RegistryFederation.md
- Relation graph: docs/graph/capability-graph.mmd - Relation graph: docs/graph/capability-graph.mmd
- Graph explorer: docs/graph/index.html - Graph explorer: docs/graph/index.html
- CLI reference: tools/README.md - CLI reference: tools/README.md

381
docs/IntentScopeGapAnalysis.md
View File

@@ -3,7 +3,7 @@
**Repository:** `reuse-surface` **Repository:** `reuse-surface`
**Artifact:** `docs/IntentScopeGapAnalysis.md` **Artifact:** `docs/IntentScopeGapAnalysis.md`
**Status:** Living analysis **Status:** Living analysis
**Created:** 2026-06-15 **Updated:** 2026-06-15
**Purpose:** Record alignment, drift, and open gaps between declared intent and **Purpose:** Record alignment, drift, and open gaps between declared intent and
current delivered scope so future workplans can close them deliberately. current delivered scope so future workplans can close them deliberately.
@@ -13,19 +13,30 @@ current delivered scope so future workplans can close them deliberately.
`INTENT.md` describes the long-term capability registry product: a reuse surface `INTENT.md` describes the long-term capability registry product: a reuse surface
that makes capabilities visible, assessable, and consumable across planning and that makes capabilities visible, assessable, and consumable across planning and
implementation. `SCOPE.md` describes what the repository actually delivers today: an MVP registry implementation. `SCOPE.md` describes what the repository delivers today: an
with **A3 CLI tooling** (`validate`, `query`, `export`) atop Markdown-first **active MVP** with **20 helix_forge capabilities**, **A3 CLI tooling**, a
authoring. **hosted federation hub at A4** (`https://reuse.coulomb.social`), federation
compose, catalog/graph UIs, pytest + CI gates, and Markdown-first authoring.
The two documents are **directionally aligned** on registry-first reuse, four REUSE-WP-0001 through REUSE-WP-0011 closed the original MVP and federation
maturity dimensions, and human/agent consumers. REUSE-WP-0003 through REUSE-WP-0010 closed the priority gaps from section 8. roadmap. The documents are **directionally aligned** on registry-first reuse,
Remaining gaps are primarily document cross-coverage and operational polish: four maturity dimensions, and human/agent consumers.
1. **Document cross-coverage** — SCOPE still carries operational detail INTENT **Remaining gaps** are no longer “build the registry” but **scale and harden**
omits; INTENT success criteria are not fully enumerated in SCOPE. reuse across repos:
2. **Live federation sync** — on-demand HTTP fetch only; no polling or webhooks.
**Current reuse-surface vector (self-assessment):** `D5 / A3 / C4 / R3` 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`
--- ---
@@ -33,202 +44,149 @@ Remaining gaps are primarily document cross-coverage and operational polish:
| Topic | INTENT.md | SCOPE.md | Status | | Topic | INTENT.md | SCOPE.md | Status |
|---|---|---|---| |---|---|---|---|
| Registry-first boundary | Unregistered capabilities are invisible | Same | Aligned | | Registry-first boundary | Unregistered capabilities invisible | Same | Aligned |
| Four maturity dimensions | D, A, C, R with separate internal/external evidence | Same model in use | 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 | Aligned | | Human and agent consumers | Registry formats for both | Markdown + YAML index + CLI + hub API | Aligned |
| Reuse over inventory | Explicit principle | Implicit in workflows | Aligned | | Reuse over inventory | Explicit principle | Workflows, overlaps, federation | Aligned |
| Planning vs implementation reuse | Distinct dimensions | Reflected in query guidance | Aligned | | Planning vs implementation reuse | Distinct dimensions | Query, vectors, consumption_modes | Aligned |
| No internal code quality as maturity | Out of scope | Out of scope | Aligned | | Technical foundation | “Eventually technical” | CLI A3, hub API A4, container A5 artifact | Aligned (MVP met) |
| No hosting registered capabilities | Implied | Explicit out of scope | Aligned | | Implementation consumption modes | Discoverable modes per capability | Supported in schema and index | Aligned |
| Target maturity vectors | Expected per capability | Supported in entry schema | Aligned | | Cross-repo / org reuse | D7 generalized primitives | helix_forge domain; hub ready, thin membership | Partial |
| Broken expectations as evidence | Guiding principle | Supported in schema/entries | Aligned | | Success criteria | Eight outcomes | Most met at MVP level; analytics weak | Partial |
| Technical foundation | "Eventually technical" | A0 only, no CLI/API | Gap | | Repository layout in INTENT | `standards/`, JSON schema, single yaml | `specs/`, YAML schema, per-entry MD | Drift |
| Success criteria | Eight outcomes listed | Partially met, not enumerated | Gap | | State Hub / workplans | Not in INTENT | In scope; ADR-001 sync | SCOPE-only (OK) |
| Repository layout | `standards/`, `docs/`, JSON schema | `specs/`, `docs/` missing, YAML schema | Drift | | Hosting registered capabilities | Out of scope | Hub hosts metadata/URLs only | Aligned |
| 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 ## 3. INTENT → SCOPE Gaps (Open)
What INTENT declares that SCOPE does not yet deliver. What INTENT still expects beyond current SCOPE delivery.
### 3.1 Technical foundation (High) ### 3.1 Cross-repo federation breadth (High)
| INTENT claim | Current SCOPE reality | Gap | | INTENT claim | Current SCOPE reality | Gap |
|---|---|---| |---|---|---|
| "Conceptual, structural, and **eventually technical** foundation" | Documentation-only repo, A0 availability | No CLI, validator, exporter, or API | | Capabilities reusable across repos, products, orgs | 20 entries, all `helix_forge` | No multi-domain federation yet |
| Implementation support through discoverable consumption modes | Manual index filtering only | No machine-assisted query or export | | Find capabilities before rebuilding (network scale) | Hub `/v1/federated` returns 12 capabilities from 1 repo | Sibling repos lack published indexes |
| Reference tooling | `tools/README.md` documents planned commands | Executable tools do not exist |
**Impact:** Implementation reuse still depends on humans/agents reading files. **Impact:** Hub infrastructure is live; **membership and index publishing** are
INTENT's "available enough to build with" mantra is only partially true for the bottleneck, not registry tooling.
registry metadata itself.
**Suggested follow-up:** Workplan for CLI validate/query/export (PRD section 17). **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) ### 3.2 Planning support breadth (Medium)
| INTENT claim | Current SCOPE reality | Gap | | 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 | | Plan prototype/MVP/enhancement/platform work | Manual compare via query/catalog | No gap reports or roadmap views |
| Identify capability gaps, duplicates, overlaps, standardization candidates | Duplicate guidance only | No overlap detection, gap aggregation, or standardization workflow | | Identify gaps, duplicates, overlaps, standardization | `overlaps` command (35 candidates on 20 entries) | No aggregation workflow or standardization tracker |
| Track progress from named ideas to generalized capabilities | Promotion via front matter edits | No promotion history or changelog | | 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; does not scale without **Impact:** Planning reuse works for small registries; portfolio-scale decisions
tooling or disciplined manual process. still need disciplined manual process or new reports.
**Suggested follow-up:** Index views for "D5+/A0-A1" planning candidates and **Suggested follow-up:** Workplan for maturity cohort exports (`D5+/A0–A1`
"D5+/A4+" implementation candidates; promotion history field or log. planning candidates, `D5+/A4+` implementation candidates).
### 3.3 Success criteria coverage (Medium) ### 3.3 Hub operations and client sync (Medium)
INTENT success criteria vs current delivery: | 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 | | Success criterion | Met today? | Notes |
|---|---|---| |---|---|---|
| Find reusable capabilities before rebuilding | Partial | Index + 3 samples; coverage is thin | | Find reusable capabilities before rebuilding | **Yes (MVP)** | Index, query, catalog, hub `/v1/federated` |
| Compare maturity consistently | Yes | Vectors and schema enums | | Compare maturity consistently | **Yes** | Vectors, schema enums, graph relations |
| Distinguish conceptual readiness from delivery | Yes | D vs A separation | | Distinguish conceptual readiness from delivery | **Yes** | D vs A separation |
| Distinguish internal assessment from external evidence | Yes | `maturity` vs `external_evidence` | | Distinguish internal assessment from external evidence | **Yes** | `maturity` vs `external_evidence` |
| Plan prototype/MVP/enhancement/platform work | Partial | Guidance only, no reports | | Plan prototype/MVP/enhancement/platform work | **Partial** | Guidance + manual tools; no reports |
| Identify gaps, duplicates, overlaps, standardization candidates | Partial | Manual duplicate check only | | Identify gaps, duplicates, overlaps, standardization | **Partial** | Overlaps command; no standardization workflow |
| Track progress to generalized capabilities | No | No history or timeline | | Track progress to generalized capabilities | **Partial** | Per-entry `promotion_history`; no D7 pipeline |
| Make reuse normal in product/architecture work | Partial | Agent instructions exist; tooling weak | | Make reuse normal in product/architecture work | **Partial** | AGENTS.md, hub live; federation membership thin |
### 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) ## 6. Completeness Assessment (SCOPE vs INTENT)
Using INTENT's own completeness framing for the **reuse-surface product**: Using INTENT's completeness framing for the **reuse-surface product**:
| Area | INTENT expectation | Current SCOPE delivery | Level | | Area | INTENT expectation | Current delivery | Level |
|---|---|---|---| |---|---|---|---|
| Registry model and principles | Full | `INTENT.md` + `specs/` | C4 | | Registry model and principles | Full | INTENT + specs | C5 |
| Maturity standard | Full | `specs/CapabilityMaturityStandard.md` | C5 | | Maturity standard | Full | `specs/CapabilityMaturityStandard.md` | C5 |
| Entry authoring | Full for MVP | Template + schema + README | C4 | | Entry authoring | Full for MVP | Template + schema + README | C5 |
| Sample registry | Examples expected | 3 helix_forge entries | C3 | | Sample / seed registry | Examples | 20 helix_forge entries | C4 |
| Discovery surface | Machine-readable | YAML index | C3 | | Discovery surface | Machine-readable | Index, query, export, hub API | C5 |
| Validation | Implied tooling | Manual checklist | C2 | | Validation | Tooling | `validate` + CI | C5 |
| Search/filter | Supported | Documented manual patterns | C2 | | Search / filter | Supported | query, catalog HTML | C4 |
| Agent instructions | Expected | `AGENTS.md` registry section | C4 | | Federation | Cross-repo | Compose + production hub; 1 member | C3 |
| Technical consumption of registry | A3+ target natural for tools | A0 | C1 | | Agent instructions | Expected | AGENTS.md + tools README | C4 |
| Consumer evidence for registry itself | Should be recorded | None (R0) | C1 | | Technical consumption | A3+ for tools | CLI A3, hub A4 | C4 |
| Planning reports and gap analytics | Success criteria | Not present | C1 | | Planning analytics | Success criteria | Not present | C2 |
| Documentation canon | Concept + assessment guides | Partial | C2 | | Documentation canon | Concept + assessment | Concept doc; assessment via README | C4 |
**Overall completeness vs INTENT:** **C3 (Functional Core)** — the central **Overall completeness vs INTENT:** **C4 (Broadly Covered)** — core registry,
registry MVP works manually, but variants, tooling, evidence, and conceptual tooling, and hub work; federation membership and planning analytics remain
docs remain incomplete. bounded gaps.
--- ---
@@ -236,60 +194,42 @@ docs remain incomplete.
| Signal | State | | Signal | State |
|---|---| |---|---|
| Automated tests | `tests/` — pytest covers validate, query, export, overlaps, federation, graph, catalog | | Automated tests | 20 pytest tests (registry, federation, hub) |
| Schema validation in CI | `.gitea/workflows/ci.yml` — validate, federation, catalog, graph, pytest | | Schema validation in CI | validate, federation, catalog, graph, pytest |
| Consumer feedback on registry workflows | None | | Production hub | `reuse.coulomb.social` — TLS, health, dogfood registration |
| Production or repeated agent usage evidence | None | | Consumer feedback on registry workflows | None formal |
| Known friction | Manual index maintenance; schema/INTENT field naming drift | | Known friction | Sibling index publishing; INTENT layout drift; hub single-replica SQLite |
**Overall reliability vs INTENT consumer-evidence framing:** **R3 (Proven in **Overall reliability vs INTENT consumer-evidence framing:** **R3 (Usable)** —
Development)** for registry CLI tooling — pytest suite and CI gates exercise CI and production smoke support normal agent/operator workflows with known
core commands. Individual registered capabilities may carry their own evidence limitations. Not yet **R4 Dependable** without SLO, backup, and feedback data.
(e.g. feature-control at R3).
--- ---
## 8. Priority Gap Closure Order ## 8. Priority Gap Closure Order
| Priority | Gap | Outcome | Status | ### Closed (WP-0001 – WP-0011)
|---|---|---|---|
| 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 Priorities 1–17 from the original roadmap are **closed**. See section 4 and
archived workplans under `workplans/archived/`.
| 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 ### Proposed next work
| Priority | Gap | Suggested outcome | Status | | Priority | Gap | Suggested outcome | Status |
|---|---|---|---| |---|---|---|---|
| 17 | Hosted federation hub | Hub service on `railiance01` + `reuse-surface hub` CLI | Closed (WP-0011) | | 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 |
--- ---
## 9. Document Maintenance Rules ## 9. Document Maintenance Rules
- Re-run this analysis when either `INTENT.md` or `SCOPE.md` changes materially. - 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. - 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. - 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 - Prefer updating `SCOPE.md` for delivery truth and `INTENT.md` for product
truth; use this file to track delta between them. truth; use this file to track delta between them.
@@ -301,13 +241,10 @@ core commands. Individual registered capabilities may carry their own evidence
| Date | Change | | Date | Change |
|---|---| |---|---|
| 2026-06-15 | Initial analysis after REUSE-WP-0002 completion | | 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-0003 closed priorities 1–8; vector D5/A3/C4/R2 |
| 2026-06-15 | REUSE-WP-0004 closed priorities 9–11 (catalog, overlaps, CI) | | 2026-06-15 | REUSE-WP-0004 closed priorities 9–11 |
| 2026-06-15 | REUSE-WP-0005 closed priorities 12 and 14 (federation, relation graphs) | | 2026-06-15 | REUSE-WP-0005 closed priorities 12 and 14 |
| 2026-06-15 | REUSE-WP-0006 expanded registry to 12 capabilities; relation hygiene clean | | 2026-06-15 | REUSE-WP-0006 expanded registry to 12 capabilities |
| 2026-06-15 | REUSE-WP-0007 closed priority 13 (searchable catalog UI) | | 2026-06-15 | REUSE-WP-0007–0010 closed catalog UI, graph UI, pytest, network federation |
| 2026-06-15 | REUSE-WP-0008 closed priority 16 (graph explorer) | | 2026-06-15 | REUSE-WP-0011 closed priority 17; hub live at reuse.coulomb.social |
| 2026-06-15 | REUSE-WP-0009 added pytest suite and CI fail-on-warnings; vector R3 | | 2026-06-15 | Post-WP-0011 refresh: 20 capabilities, vector D5/A4/C4/R3, priorities 18–23 proposed |
| 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) |
| 2026-06-15 | REUSE-WP-0011 closed priority 17; hub live at reuse.coulomb.social (TLS pending DNS) |