coulomb/reuse-surface
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add standard SCOPE.md sections and capability blocks (REUSE-WP-0020-T07)

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-08-21 03:21:45 +02:00
parent 2a3fc70172
commit 823ce9e120
2 changed files with 114 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

113
SCOPE.md
View file

@ -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

2
WORK-RECORDS.md
View file

@ -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 |