# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

**reuse-surface** is a capability registry for planning and implementation reuse,
graded by discovery and delivery maturity. It is documentation-first: the source
of truth is Markdown/YAML under `registry/`, `specs/`, `schemas/`, and
`workplans/`. The Python package `reuse_surface/` is a thin CLI + optional
federation service that validates, queries, and exports that data. There is no
long-running app to run for normal work.

`AGENTS.md` is the authoritative operational playbook (State Hub integration,
session protocol, registry authoring/promotion workflow, ADR-001 workplan
convention). Read it for anything beyond the build/test mechanics below; this
file does not duplicate it.

## Commands

```bash
# Install (editable, into the repo's own venv)
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

# Core checks — these mirror CI (.gitea/workflows/ci.yml)
.venv/bin/reuse-surface validate --relations --fail-on-warnings   # schema + index drift + relation cycles
.venv/bin/reuse-surface federation compose                        # rebuild registry/indexes/federated.yaml
.venv/bin/reuse-surface catalog                                   # regen docs catalog
.venv/bin/reuse-surface graph --check --fail-on-warnings          # relation graph + cycle check

# Tests
.venv/bin/pytest -q
.venv/bin/pytest -q tests/test_registry.py                # single file
.venv/bin/pytest -q tests/test_registry.py::test_name     # single test

# Discovery / reporting (read-only)
.venv/bin/reuse-surface query --discovery-min D4 --availability-min A2
.venv/bin/reuse-surface overlaps          # potential duplicate capabilities
.venv/bin/reuse-surface stats             # maturity + federation coverage
.venv/bin/reuse-surface export --format yaml
```

CI runs `validate` on every push/PR to `main`; the catalog, graph, stats, and
report steps also run. Keep `validate --relations --fail-on-warnings` green — it
is the gate.

## Maturity vector — the core data model

Every capability carries a four-dimension vector `D / A / C / R`:

- **Discovery (D0–D7)** and **Availability (A0–A7)** — *internal* maturity, stored
  under `maturity.discovery.current` / `maturity.availability.current` in entry
  front matter.
- **Completeness (C0–C6)** and **Reliability (R0–R6)** — *external consumer
  evidence*, stored under `external_evidence.completeness.level` /
  `external_evidence.reliability.level`.

Level orderings live in `reuse_surface/registry.py` (`LEVEL_ORDERS`). The split is
deliberate: **discovery strength gates planning reuse** (prefer D3+, ideally D5+);
**availability gates implementation reuse** (A2+ code, A3+ CLI, A4+ API/SDK).
Higher availability is *not* evidence of completeness or reliability — keep the
dimensions independent. The maturity standard is `specs/CapabilityMaturityStandard.md`.

## Architecture

The CLI (`reuse_surface/cli.py`) is the single entry point (`reuse-surface`
console script → `cli:main`); each subcommand maps to a `cmd_*` function that
delegates to a focused module:

- `registry.py` — front-matter parsing, vector parsing, level comparison, the
  canonical `ROOT`/path resolution that everything else builds on.
- `establish.py` — `establish` command: scaffold a registry into another repo,
  `--publish-check` (verify a repo's index is fetchable), `--discover` (draft
  entries, optionally LLM-assisted).
- `registry_update.py` — `update` command: deterministic + LLM-suggested maturity
  refreshes from repo/git signals.
- `overlaps.py` — token-similarity dedup candidates.
- `federation.py` / `hub_sync.py` — compose the cross-repo `federated.yaml` from
  `registry/federation/sources.yaml`; sync that manifest from hub registrations.
- `catalog.py` / `graph.py` — generate human-readable catalog + Mermaid relation
  graph into `docs/`.
- `reports.py` / `stats.py` — cohort/gap reports and maturity/federation stats,
  including roster-based (`registry/federation/local-repo-roster.yaml`) views.
- `hub/` — optional FastAPI **federation service** (`reuse-surface serve`):
  registers remote repo index URLs and composes a federated index across them.
  State lives in SQLite (`REUSE_SURFACE_DB`); writes require `REUSE_SURFACE_TOKEN`.
  This is distinct from the **Custodian State Hub** (see AGENTS.md), reached over
  plain HTTP REST.
- `hub_client.py` / `llm_bridge.py` — HTTP clients for the federation service and
  for `llm-connect` respectively.

Data layout: capability entries are `registry/capabilities/capability.<domain>.<name>.md`
(YAML front matter validated against `schemas/capability.schema.yaml`), indexed in
`registry/indexes/capabilities.yaml`. **Index and files must stay in sync** —
`validate` reports drift in both directions. New entries copy
`templates/capability-entry.template.md`; see AGENTS.md for the full add/promote
workflow (always search `overlaps`/the index before adding).

## Workplans & State Hub (brief)

Work items are files: `workplans/REUSE-WP-NNNN-<slug>.md` (ADR-001 — the hub is a
read/cache layer that rebuilds from files, never the source of truth). Do not
hand-edit `state_hub_workstream_id` / `state_hub_task_id` frontmatter — those are
written by the consistency sync. After editing workplan files, the custodian
operator runs `make fix-consistency REPO=reuse-surface` (or the `.venv/bin/python
scripts/consistency_check.py` fallback) from `~/state-hub`. Full protocol,
HTTP-REST hub calls, and required session-close progress logging are in `AGENTS.md`.