generated from coulomb/repo-seed
tegwick
29c77ff1f7
Some checks failed
ci / validate-registry (push) Has been cancelled
Refresh federated index (20 capabilities, 0 duplicate warnings). Update workplan, SCOPE, gap analysis, and tests for 59/60 publish pass. Mark T04/T06 done; T01 remains on tegwick-control repo creation. Note: production hub whynot URLs still need REUSE_SURFACE_TOKEN update.
109 lines
5.5 KiB
Markdown
109 lines
5.5 KiB
Markdown
# 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`.
|