reuse-surface/CLAUDE.md

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

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