From 823ce9e1206125c80a75f718c36101fdba350ea1 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 21 Aug 2026 03:21:45 +0200 Subject: [PATCH] Add standard SCOPE.md sections and capability blocks (REUSE-WP-0020-T07) Clears the hub scope check's C5b/C5c warnings: Relevant When, Not Relevant When, How It Fits, Terminology, Related / Overlapping, and Provided Capabilities were all missing, along with any fenced capability block. The Terminology section calls out something this workplan ran into for real: the fenced `capability` blocks in SCOPE.md (type/title/description/keywords) look like index rows in registry/indexes/capabilities.yaml but are a different shape and are not validated. evidence-binder copied the SCOPE block shape into its index, which is why it had no `id` and broke federation composition. Co-Authored-By: Claude Opus 5 --- SCOPE.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++ WORK-RECORDS.md | 2 +- 2 files changed, 114 insertions(+), 1 deletion(-) diff --git a/SCOPE.md b/SCOPE.md index 9f8f3bb..d5835b9 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -34,6 +34,119 @@ for reuse within this product boundary. - Own unrelated adjacent systems or make irreversible operational decisions without human approval. +## Relevant When + +- Deciding whether a capability already exists before planning or building one + (`reuse-surface plan-check`). +- Registering a new capability so it becomes visible for reuse. +- Promoting a capability along the D/A/C/R maturity axes with evidence. +- Comparing candidate capabilities by maturity, scope, relations, and consumer + guidance. +- Detecting overlap or duplication between capabilities across repos. +- Adding a sibling repo to the federation, or debugging why its index does not + appear in the federated view. +- Recording or interpreting reuse telemetry as R-axis evidence. + +--- + +## Not Relevant When + +- Hosting, running, or operating the capabilities themselves — the registry + describes capabilities, it does not execute them. +- Looking for a package registry, service catalog, issue tracker, or project + management system. Those are different tools with different guarantees. +- Judging internal code quality. Maturity here is about discovery and delivery, + not about how the implementation is written. +- Deploying the hub. The Kubernetes release lives in `railiance-apps` + (`charts/reuse-surface/`); this repo owns the image and the deploy guide only. +- Routing credentials. See `.claude/rules/credential-routing.md` — ops-warden + issues SSH certificates, OpenBao holds secrets. + +--- + +## How It Fits + +`reuse-surface` sits between planning and implementation. A workplan or intent +is checked against the federated index before work starts; the verdict is +reuse, extend, or new. Capabilities registered by sibling repos flow in through +federation, and observed reuse flows back as maturity evidence. + +- **Upstream:** each sibling repo publishes `registry/indexes/capabilities.yaml` + from its own checkout. The repo owns its entries; this registry never edits + them. +- **Here:** the federation composer merges member indexes into + `registry/indexes/federated.yaml`, and the hosted hub serves the same view at + `GET /v1/federated`. +- **Downstream:** humans and agents query the index, the CLI, or the hub before + building. `plan-check --record-outcome` returns telemetry that feeds the + R axis. + +State Hub is the coordination layer, not the registry: workplans and decisions +live there, capability descriptions live here. + +--- + +## Terminology + +| Term | Meaning | +|---|---| +| **Capability** | A reusable unit of function, described by a registry entry. Not a package, not a service — either can implement one. | +| **Maturity vector** | `D / A / C / R` — Discovery, Availability, Consumability, Reliability. See `specs/CapabilityMaturityStandard.md`. | +| **Registry entry** | Markdown with YAML front matter under `registry/capabilities/`, validated against `schemas/capability.schema.yaml`. | +| **Index** | `registry/indexes/capabilities.yaml` — one row per entry, the discovery surface for this repo. | +| **Federated index** | The composed view across all member repos. | +| **Member / source** | A repo registered in `registry/federation/sources.yaml` or on the hub. | +| **Hub** | The hosted service at `https://reuse.coulomb.social` that composes and serves the federated index. | +| **Promotion** | Raising a maturity axis, backed by evidence and recorded in `promotion_history`. | + +**Note on two similar formats.** The fenced `capability` blocks in a repo's +`SCOPE.md` (`type` / `title` / `description` / `keywords`) are *not* the same +shape as index rows in `registry/indexes/capabilities.yaml` +(`id` / `name` / `summary` / `vector` / `domain` / `status` / `owner` / `path` / +`tags` / `consumption_modes`). SCOPE blocks are a prose-level advertisement; +index rows are validated registry data and require an `id`. Copying one shape +into the other is a real and observed failure mode — it silently breaks +federation for that member. + +--- + +## Related / Overlapping + +| Repo / system | Relationship | +|---|---| +| **State Hub** (`~/state-hub`) | Coordination read model: workplans, tasks, decisions, progress. Complementary — it tracks *work*, this tracks *capabilities*. | +| **railiance-apps** | Owns the Kubernetes release for the hub (`charts/reuse-surface/`, RAILIANCE-WP-0007). Deploys what this repo builds. | +| **ops-warden** | Credential and access routing. Explicitly out of scope here. | +| **Sibling domain repos** | Federation members. Each owns its own entries and index; this repo owns only composition and the standard. | +| **Package registries** (PyPI, npm, OCI) | Distribute artifacts. This registry describes capabilities and may reference artifacts, but does not host them. | + +--- + +## Provided Capabilities + +```capability +type: registry +title: Capability registration and maturity assessment +description: Register capabilities as validated Markdown entries with D/A/C/R maturity vectors, promotion history, and evidence, so they become discoverable and comparable for planning and implementation reuse. +keywords: [registry, capability, maturity, discovery, promotion, reuse, governance] +``` + +```capability +type: service +title: Capability index federation +description: Compose capability indexes published by many repos into one federated view, served locally by CLI and in production by a hosted hub with webhook-driven refresh and staleness visibility. +keywords: [federation, index, compose, hub, webhook, capabilities, cross-repo] +``` + +```capability +type: tooling +title: Pre-build reuse check +description: Match a draft workplan or free-text intent against the federated capability index and return a reuse, extend, or new verdict, bridging a new verdict to a State Hub capability request and recording the outcome as reuse telemetry. +keywords: [plan-check, reuse, verdict, planning, telemetry, capability-request] +``` + +--- + ## What Is Possible Now The MVP registry foundation, CLI tooling (REUSE-WP-0003), federation stack diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 58ba7aa..9af5d30 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -74,7 +74,7 @@ | task | REUSE-WP-0020-T02 | done | — | workplans/REUSE-WP-0020-coulombcore-retirement-cutover.md | | task | REUSE-WP-0020-T03 | wait | — | workplans/REUSE-WP-0020-coulombcore-retirement-cutover.md | | task | REUSE-WP-0020-T04 | wait | — | workplans/REUSE-WP-0020-coulombcore-retirement-cutover.md | -| task | REUSE-WP-0020-T05 | progress | — | workplans/REUSE-WP-0020-coulombcore-retirement-cutover.md | +| task | REUSE-WP-0020-T05 | done | — | workplans/REUSE-WP-0020-coulombcore-retirement-cutover.md | | task | REUSE-WP-0020-T06 | todo | — | workplans/REUSE-WP-0020-coulombcore-retirement-cutover.md | | task | REUSE-WP-0020-T07 | todo | — | workplans/REUSE-WP-0020-coulombcore-retirement-cutover.md | | task | REUSE-WP-0020-T08 | done | — | workplans/REUSE-WP-0020-coulombcore-retirement-cutover.md |