tegwick
b24ec507aa
Closes the registry maintenance loop from inside each domain repo: interactive prompting for judgment calls, full automation for safe and high-confidence changes, both backed by the llm-connect HTTP bridge. - New modules: maintain.py, maintain_llm.py, patches.py, interactive.py - Schema: schemas/registry-patch.schema.json - CLI: reuse-surface maintain; establish --scaffold --hook - Sibling templates: Makefile fragment, pre-commit hook - Deterministic signal collectors extended; validate cwd auto-detect - Docs, gap priority 28, SCOPE update - Tests: test_maintain.py, test_interactive.py (59 pytest total) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Registry Tools
CLI tooling for the capability registry, implemented in reuse_surface/.
Install
python3 -m venv .venv
.venv/bin/pip install -e .
Commands
validate
Validate one entry or the full registry against schemas/capability.schema.yaml
and warn on index drift.
reuse-surface validate
reuse-surface validate registry/capabilities/capability.registry.register.md
query
Filter the capability index by maturity, tags, domain, consumption mode, or keyword.
reuse-surface query --discovery-min D4
reuse-surface query --availability-min A3
reuse-surface query --tag identity
reuse-surface query --consumption-mode cli
reuse-surface query --keyword rollout
export
Export a machine-readable bundle combining index rows and parsed entry front matter.
reuse-surface export
reuse-surface export --format json
overlaps
Detect potential duplicate or overlapping capabilities (UC-RS-015).
reuse-surface overlaps
reuse-surface overlaps --threshold 0.35
catalog
Generate human-readable catalog artifacts (UC-RS-018).
reuse-surface catalog
Writes docs/CapabilityCatalog.md, docs/catalog/index.html,
docs/catalog/registry.json, and docs/catalog/search.html.
federation compose
Compose a federated index from registry/federation/sources.yaml.
reuse-surface federation compose
reuse-surface federation compose --refresh
Composes local and remote HTTP index sources. Writes
registry/indexes/federated.yaml with source_repo attribution. Remote indexes
cache under registry/federation/cache/.
graph
Generate a Mermaid relation graph from capability entry relations.
reuse-surface graph
reuse-surface graph --check
reuse-surface graph --stdout
Writes docs/graph/capability-graph.mmd and docs/graph/index.html.
hub
Client for the federation hub service (REUSE-WP-0011).
export REUSE_SURFACE_URL=https://reuse.coulomb.social
export REUSE_SURFACE_TOKEN=<write-token>
reuse-surface hub status
reuse-surface hub list
reuse-surface hub register --repo state-hub --url https://.../capabilities.yaml
reuse-surface hub update --repo state-hub --enabled true
reuse-surface hub sync --merge
reuse-surface hub sync --dry-run
Run the service locally: REUSE_SURFACE_TOKEN=dev-token reuse-surface serve
report gaps
reuse-surface report gaps
reuse-surface report gaps --format json
reuse-surface report gaps --roster registry/federation/local-repo-roster.yaml
Workstation roster report: publish blockers, empty scaffolds, seed-ready repos, and local index owner stubs pending dedup.
stats
Registry maturity aggregates and federation readiness.
reuse-surface stats
reuse-surface stats --format json
reuse-surface stats --federation-ready --raw-url https://.../capabilities.yaml
reuse-surface stats --roster registry/federation/local-repo-roster.yaml --federation-ready
establish
Bootstrap or discover a capability registry in the current or target repo.
reuse-surface establish --scaffold --domain helix_forge
reuse-surface establish --scaffold --path ../state-hub
reuse-surface establish --publish-check --raw-url https://.../capabilities.yaml
export LLM_CONNECT_URL=http://127.0.0.1:8088
reuse-surface establish --discover --dry-run
reuse-surface establish --discover --apply
--scaffold creates registry/ layout. --publish-check probes raw URL and
local index YAML. --discover drafts capabilities via llm-connect (optional).
update
Refresh registry metadata from repo drift signals.
reuse-surface update --capability capability.registry.register
reuse-surface update --all --from-git-since HEAD~5 --apply
reuse-surface update --capability capability.registry.register --suggest-maturity
Deterministic patches (vector_drift, new tests/ citations) apply with
--apply. LLM suggestions use --suggest-maturity and remain review-only.
maintain
Interactive or automated registry maintenance (REUSE-WP-0016). Preferred entry point for sibling repo operators.
export LLM_CONNECT_URL=http://127.0.0.1:8088 # optional
reuse-surface maintain --all --from-git-since origin/main
reuse-surface maintain --capability capability.registry.register
reuse-surface maintain --all --auto --no-llm
reuse-surface maintain --all --auto --from-git-since HEAD~3
reuse-surface maintain --publish --raw-url https://.../capabilities.yaml --all --auto --no-llm
| Mode | Flags | Behavior |
|---|---|---|
| Interactive (TTY) | (default) | Prompt per patch: apply / skip / edit / quit |
| Full automation | --auto or --yes |
Safe deterministic + gated LLM patches |
| Deterministic only | --auto --no-llm |
No llm-connect required |
| Publish chain | --publish --raw-url |
maintain → validate → publish-check |
Templates: templates/Makefile.registry.fragment, templates/git-hook.pre-commit.registry.
Install hook: reuse-surface establish --scaffold --hook.
report cohorts
Export capability cohorts for planning or implementation reuse decisions.
reuse-surface report cohorts
reuse-surface report cohorts --planning-min D5 --availability-max A1
reuse-surface report cohorts --implementation-min A4
reuse-surface report cohorts --format json
Planning preset (--planning-min) sets discovery minimum and defaults
availability-max to A1. Implementation preset (--implementation-min) sets
availability minimum. Output is Markdown (default) or JSON.
Export format
The export bundle includes:
version,domain,updatedfrom the indexcapabilities[]with{ index, entry }pairs
Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).
Workflows
| Workflow | Command |
|---|---|
| Add capability | template + index update + reuse-surface validate |
| Discover capabilities | reuse-surface query or read the index |
| Validate entry shape | reuse-surface validate |
| Export for agents | reuse-surface export --format json |
| Detect overlap | reuse-surface overlaps |
| Publish catalog | reuse-surface catalog |
| Compose federation | reuse-surface federation compose |
| Sync federation manifest from hub | reuse-surface hub sync |
| Registry stats | reuse-surface stats |
| Bootstrap sibling registry | reuse-surface establish --scaffold |
| Verify index publish URL | reuse-surface establish --publish-check |
| Draft capabilities (LLM) | reuse-surface establish --discover |
| Refresh entry metadata | reuse-surface update |
| Interactive registry maintain | reuse-surface maintain |
| Planning cohort export | reuse-surface report cohorts |
| Relation graph | reuse-surface graph |
Related use cases
- UC-RS-013 — Use registry metadata in agentic coding
- UC-RS-019 — Publish a machine-readable registry export
- UC-RS-023 — Validate registry entries against schema