coulomb/reuse-surface
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions 1 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
- Maintain the capability maturity model, standards, schemas, registry formats,
sample entries, indexes, validation guidance, CLI tooling, and agent
instructions.
sample entries, indexes, validation guidance, CLI tooling, hub service, and
agent instructions.
- Keep `INTENT.md`, `specs/`, registry artifacts, and State Hub workplans
aligned on the registry-first reuse boundary.
- Support humans and agents as registry consumers through Markdown-first
@@ -26,7 +26,8 @@ for reuse within this product boundary.
## 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
management systems.
- Judge internal code quality as capability maturity.
@@ -35,15 +36,15 @@ for reuse within this product boundary.
## What Is Possible Now
The MVP registry foundation plus CLI tooling (REUSE-WP-0003) is in place. Humans
and agents can:
The MVP registry foundation, CLI tooling (REUSE-WP-0003), federation stack
(WP-0005/0010), and hosted hub (WP-0011) are in place. Humans and agents can:
- **Discover capabilities** via `registry/indexes/capabilities.yaml` or
`reuse-surface query`
- **Discover capabilities** via `registry/indexes/capabilities.yaml`,
`reuse-surface query`, or `GET https://reuse.coulomb.social/v1/federated`
- **Add a new capability** at D0/A0/C0/R0 using
`templates/capability-entry.template.md`
- **Promote capabilities** with evidence, optional `promotion_history`, and index
vector updates
- **Promote capabilities** with evidence, `promotion_history`, and index vector
updates
- **Compare candidates** using maturity vectors, scope, relations, and consumer
guidance
- **Record expectations** through `external_evidence.completeness` and
@@ -52,47 +53,58 @@ and agents can:
- **Export a machine-readable bundle** with `reuse-surface export`
- **Detect overlap candidates** with `reuse-surface overlaps`
- **Generate a human-readable catalog** with `reuse-surface catalog`
- **Browse a searchable catalog** at `docs/catalog/search.html` (client-side
filter over `registry.json`)
- **Browse a searchable catalog** at `docs/catalog/search.html`
- **Compose federated indexes** with `reuse-surface federation compose`
(local paths and remote HTTP URLs with cache)
- **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`
- **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
still documentation-first for authoring; consumption combines Markdown entries,
the index, and CLI automation.
Registry **tooling** availability is **A4** (CLI plus hosted hub HTTP API).
Registry **authoring** remains Markdown-first; consumption combines entries, the
index, CLI automation, and the production hub.
## What Is Not Possible Yet
- Automatic polling/webhooks to refresh hub registrations (compose is on-demand)
- Packaged releases beyond local `pip install -e .`, container image, and Gitea CI
- **`reuse-surface hub sync`** — materialize local `sources.yaml` from hub state
- **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.
## Current State
- Status: active MVP registry with CLI tooling.
- Twelve helix_forge capabilities are registered in `registry/capabilities/`.
- `reuse-surface` CLI provides `validate`, `query`, and `export` via
`pyproject.toml` and `reuse_surface/`.
- `docs/CapabilityRegistryConcept.md` and `docs/IntentScopeGapAnalysis.md`
document onboarding and intent-scope tracking.
- CI validates the registry and composes federation on push/PR.
- Federated index: `registry/indexes/federated.yaml`.
- Relation graph: `docs/graph/capability-graph.mmd` and explorer at
`docs/graph/index.html`.
- Searchable catalog: `docs/catalog/search.html`.
- Test suite: `tests/` (pytest).
- Remote federation: HTTP URL sources with cache in `registry/federation/cache/`.
- Hosted federation hub: `https://reuse.coulomb.social` (REUSE-WP-0011, image
`gitea.coulomb.social/coulomb/reuse-surface`).
- Finished workplans: `REUSE-WP-0001` through `REUSE-WP-0011` (hub archived
2026-06-15).
- **Self-assessed vector:** `D5 / A3 / C4 / R3` (see gap analysis).
- **Status:** active MVP registry with CLI, federation, and production hub.
- **Capabilities:** 20 helix_forge entries in `registry/capabilities/`.
- **CLI / service:** `reuse_surface/` — validate, query, export, overlaps,
catalog, federation, graph, hub client, `serve` (FastAPI hub).
- **Production hub:** `https://reuse.coulomb.social` on Railiance01
(`92.205.62.239`); image `gitea.coulomb.social/coulomb/reuse-surface:cb7a6e4`;
TLS live; dogfood registration for `reuse-surface` (12 capabilities composed
on `/v1/federated`).
- **Specs:** `specs/FederationHubAPI.md`, `schemas/hub-registration.schema.yaml`.
- **Docs:** `docs/CapabilityRegistryConcept.md`, `docs/RegistryFederation.md`,
`docs/IntentScopeGapAnalysis.md`, deploy guide `docs/deploy/reuse-kubernetes.md`.
- **CI:** `.gitea/workflows/ci.yml` — validate, federation compose, catalog,
graph, pytest (20 tests).
- **Federated index:** `registry/indexes/federated.yaml` (local compose).
- **Relation graph:** `docs/graph/capability-graph.mmd`, `docs/graph/index.html`.
- **Searchable catalog:** `docs/catalog/search.html`.
- **Workplans:** REUSE-WP-0001 through REUSE-WP-0011 finished; WP-0011 archived
`workplans/archived/260615-REUSE-WP-0011-*.md`.
- **Self-assessed vector:** `D5 / A4 / C4 / R3` (see `docs/IntentScopeGapAnalysis.md`).
## Repository Layout
@@ -102,14 +114,19 @@ reuse-surface/
├── SCOPE.md
├── AGENTS.md
├── pyproject.toml
├── reuse_surface/
├── Dockerfile
├── reuse_surface/ # CLI, hub service, federation, graph, catalog
├── specs/
├── schemas/
├── templates/
├── registry/
│ ├── capabilities/ # per-entry Markdown
│ ├── indexes/ # capabilities.yaml, federated.yaml
│ └── federation/ # sources.yaml, cache/
├── docs/
├── tools/
└── workplans/
└── archived/
```
## Getting Oriented
@@ -120,11 +137,13 @@ reuse-surface/
- Product requirements: specs/ProductRequirementsDocument.md
- Use cases: specs/UseCaseCatalog.md
- Maturity standard: specs/CapabilityMaturityStandard.md
- Hub API: specs/FederationHubAPI.md
- Registry index: registry/indexes/capabilities.yaml
- Registry guidance: registry/README.md
- Federation guide: docs/RegistryFederation.md
- Hub deployment: docs/deploy/reuse-kubernetes.md
- Generated catalog: docs/CapabilityCatalog.md
- Searchable catalog: docs/catalog/search.html
- Federation guide: docs/RegistryFederation.md
- Relation graph: docs/graph/capability-graph.mmd
- Graph explorer: docs/graph/index.html
- CLI reference: tools/README.md

381
docs/IntentScopeGapAnalysis.md
View File

@@ -3,7 +3,7 @@
**Repository:** `reuse-surface`
**Artifact:** `docs/IntentScopeGapAnalysis.md`
**Status:** Living analysis
**Created:** 2026-06-15
**Updated:** 2026-06-15
**Purpose:** Record alignment, drift, and open gaps between declared intent and
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
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.
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.
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:
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.
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.
**Remaining gaps** are no longer “build the registry” but **scale and harden**
reuse across repos:
**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 |
|---|---|---|---|
| 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 |
| 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 at MVP level; analytics weak | Partial |
| Repository layout in INTENT | `standards/`, JSON schema, single yaml | `specs/`, YAML schema, per-entry MD | Drift |
| 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
## 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 |
|---|---|---|
| "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 |
| 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` returns 12 capabilities from 1 repo | Sibling repos lack published indexes |
**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.
**Impact:** Hub infrastructure is live; **membership and index publishing** are
the bottleneck, not registry tooling.
**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)
| 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 |
| Plan prototype/MVP/enhancement/platform work | Manual compare via query/catalog | No gap reports or roadmap views |
| Identify gaps, duplicates, overlaps, standardization | `overlaps` command (35 candidates on 20 entries) | No aggregation workflow or standardization tracker |
| 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
tooling or disciplined manual process.
**Impact:** Planning reuse works for small registries; portfolio-scale decisions
still need disciplined manual process or new reports.
**Suggested follow-up:** Index views for "D5+/A0-A1" planning candidates and
"D5+/A4+" implementation candidates; promotion history field or log.
**Suggested follow-up:** Workplan for maturity cohort exports (`D5+/A0–A1`
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 |
|---|---|---|
| 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.
| 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** | Guidance + manual tools; no 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 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 |
| 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 |
| 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 + production hub; 1 member | C3 |
| Agent instructions | Expected | AGENTS.md + tools README | C4 |
| Technical consumption | A3+ for tools | CLI A3, hub A4 | C4 |
| Planning analytics | Success criteria | Not present | C2 |
| Documentation canon | Concept + assessment | Concept doc; assessment via README | C4 |
**Overall completeness vs INTENT:** **C3 (Functional Core)** — the central
registry MVP works manually, but variants, tooling, evidence, and conceptual
docs remain incomplete.
**Overall completeness vs INTENT:** **C4 (Broadly Covered)** — core registry,
tooling, and hub work; federation membership and planning analytics remain
bounded gaps.
---
@@ -236,60 +194,42 @@ docs remain incomplete.
| 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 |
| Automated tests | 20 pytest tests (registry, federation, hub) |
| 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 (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).
**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
| 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) |
### Closed (WP-0001 – WP-0011)
### 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) |
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 |
|---|---|---|---|
| 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
- 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.
- Prefer updating `SCOPE.md` for delivery truth and `INTENT.md` for product
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 |
|---|---|
| 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) |
| 2026-06-15 | REUSE-WP-0011 closed priority 17; hub live at reuse.coulomb.social (TLS pending DNS) |
| 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 |