From 5fcca428790a1db86b6551bb531ac60d73ef719b Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 16 Jun 2026 00:30:53 +0200 Subject: [PATCH] Refresh SCOPE and INTENT gap analysis after WP-0011 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- SCOPE.md | 95 ++++---- docs/IntentScopeGapAnalysis.md | 381 ++++++++++++++------------------- 2 files changed, 216 insertions(+), 260 deletions(-) diff --git a/SCOPE.md b/SCOPE.md index dfc78e8..c2ad9db 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -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 diff --git a/docs/IntentScopeGapAnalysis.md b/docs/IntentScopeGapAnalysis.md index d8119aa..d821c28 100644 --- a/docs/IntentScopeGapAnalysis.md +++ b/docs/IntentScopeGapAnalysis.md @@ -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) | \ No newline at end of file +| 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 | \ No newline at end of file