reuse-surface/SCOPE.md

SCOPE

One-liner

Capability registry for planning and implementation reuse based on discovery and delivery maturity.

Core Idea

reuse-surface provides a registry-centric reuse layer for capabilities. It makes capabilities visible, comparable, assessable, and reusable for planning, implementation, and operation. A capability that is not registered is invisible for reuse within this product boundary.

In Scope

• Maintain the capability maturity model, standards, schemas, registry formats, 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 authoring and machine-readable metadata.
• Record decisions, progress, and workplan status through State Hub.
• Verify changes with reuse-surface validate, git diff --check, and ADR-001 consistency checks.

Out of Scope

• 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.
• 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

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]

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]

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 (WP-0005/0010), and hosted hub (WP-0011) are in place. Humans and agents can:

• 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, promotion_history, and index vector updates
• Compare candidates using maturity vectors, scope, relations, and consumer guidance
• Record expectations through external_evidence.completeness and external_evidence.reliability
• Validate entries automatically with reuse-surface validate
• 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
• 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
• Sync local federation manifest from hub with reuse-surface hub sync
• Export planning cohorts with reuse-surface report cohorts
• Report registry gaps with reuse-surface report gaps (roster blockers, empty scaffolds, dedup stubs)
• Bootstrap a sibling registry with reuse-surface establish --scaffold
• Verify index publish readiness with reuse-surface establish --publish-check
• View registry stats with reuse-surface stats (per-repo or --roster registry/federation/local-repo-roster.yaml --federation-ready)
• Draft or refresh entries with reuse-surface establish --discover and reuse-surface update (optional llm-connect backend)
• Maintain registry interactively or automatically with reuse-surface maintain (TTY prompts, --auto, optional llm-connect, --publish chain)
• 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
• Check before building with reuse-surface plan-check (REUSE-WP-0018) — match a draft workplan or free-text intent against the federated index and get a reuse/extend/new verdict; --file-request bridges a new verdict to a State Hub capability request; report gaps --check-capability-requests surfaces open requests with no matching capability
• Get automatic hub refresh (REUSE-WP-0019-T02/T03) — a Forgejo push webhook (POST /v1/webhooks/forgejo, HMAC-signed) recomposes the hub's federated index when a registered repo's registry/indexes/ changes, with composed_at/stale visibility on GET /v1/federated and a scheduled fallback recompose if a webhook delivery is ever missed
• Record reuse telemetry (REUSE-WP-0019-T04) — plan-check --record-outcome and reuse-surface record-reuse post facts to POST /v1/reuse-events when the hub is reachable, falling back to registry/telemetry/plan-check-events.jsonl otherwise (same schema either way); GET /v1/reuse-events?capability_id= aggregates them
• Aggregate reuse telemetry into R-axis evidence (REUSE-WP-0019-T05) — reuse-surface report reuse shows per-capability consumer counts, outcomes, and last-used; --suggest-relations proposes evidence-gated relations.reused_by patches (via the same apply_patches mechanism maintain uses), applied only with an explicit --apply — never automatic. specs/CapabilityMaturityStandard.md §8.9 documents what observed-reuse evidence does (and doesn't) count toward R2/R3+

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

• Multi-domain federation — all indexed capabilities remain helix_forge
• Planning analytics breadth — report gaps shipped (REUSE-WP-0015-T03); no roadmap views or standardization tracker beyond overlaps and compose collision warnings
• Managed platform posture — hub runs as a container (A5 artifact) without implemented SLO, multi-replica, or Postgres backing (criteria documented)
• 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 registry with CLI, federation, production hub, and workstation-wide coverage campaign complete (REUSE-WP-0017 finished 2026-07-07).
• Capabilities (reuse-surface): 2 helix_forge meta-registry entries in registry/capabilities/.
• Workstation roster: 62 local git repos at ~/<slug>/ tracked in registry/federation/local-repo-roster.yaml — all established, 62/62 hub-registered (inter-hub registration disabled on hub), 62/62 publish-check pass, 62/62 capability coverage (has or explicit none).
• Federation: registry/federation/sources.yaml — 61 enabled sources; registry/indexes/federated.yaml — 61 composed capability rows (inter-hub excluded; core-hub included; 0 duplicate-ID warnings at last compose).
• CLI / service: reuse_surface/ — validate, query, export, overlaps, catalog, federation, graph, hub client, establish/update/stats, serve (FastAPI hub).
• Production hub: https://reuse.coulomb.social — 61 enabled repo registrations; GET /v1/federated serves 61 capabilities from published raw URLs (compose refreshed 2026-07-07).
• 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: .forgejo/workflows/ci.yml — validate, federation compose, catalog, graph, pytest, informational report cohorts, stats --roster, report gaps (migrated from Gitea 2026-07-07, REUSE-WP-0019-T03). Also .forgejo/workflows/image.yaml (container build/push) and recompose-fallback.yaml (scheduled hub recompose, webhook backstop).
• Relation graph: docs/graph/capability-graph.mmd, docs/graph/index.html.
• Searchable catalog: docs/catalog/search.html.
• Workplans: REUSE-WP-0001 through REUSE-WP-0015 finished (archived); REUSE-WP-0017 capability coverage campaign finished (2026-07-07); REUSE-WP-0018 plan-check consumption loop finished (2026-07-07); REUSE-WP-0019 Forgejo automation and reuse telemetry finished (2026-07-08, all six tasks T01–T06).
• Assessment history: history/ — intent/scope assessments, rollout milestone, dedup plan, per-repo follow-up.
• Self-assessed vector: D5 / A4 / C5 / R3 (see docs/IntentScopeGapAnalysis.md).

Repository Layout

reuse-surface/
├── INTENT.md
├── SCOPE.md
├── AGENTS.md
├── pyproject.toml
├── 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, local-repo-roster.yaml, cache/
├── docs/
├── tools/
└── workplans/
    └── archived/

Getting Oriented

• Start with: INTENT.md
• Registry concept: docs/CapabilityRegistryConcept.md
• Intent vs scope gaps: docs/IntentScopeGapAnalysis.md
• Assessment snapshots: history/
• 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
• Relation graph: docs/graph/capability-graph.mmd
• Graph explorer: docs/graph/index.html
• CLI reference: tools/README.md
• Agent instructions: AGENTS.md
• Workplans: workplans/