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

```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
(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

```text
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/