tegwick
00b7eab154
reuse_surface/forge_host.py: parse/derive/rewrite raw index URLs across Gitea and Forgejo (handles both the legacy /raw/<branch>/... form and the canonical /raw/branch/<branch>/... form both forges serve without a 303 redirect). migrate_source_host() verifies the new URL resolves via HTTP HEAD before writing -- refuses to point a repo at a host it hasn't actually migrated to. New CLI: reuse-surface federation migrate-host --repo <slug> --to <base-url> [--from <check>] [--dry-run] [--no-verify] [--update-hub]. Inventory: cross-referenced sources.yaml against each repo's actual git origin. 11/61 repos already on Forgejo; found 2 with stale sources.yaml entries (activity-core, state-hub) despite having migrated. Fixed for real: local sources.yaml + production hub registration (hub update), verified against GET /v1/federated post-migration. config-atlas's WP-0017-T06 303 confirmed NOT a host-transition symptom (already diagnosed there as something else). Also fixed two host-agnostic gaps found while inventorying: registry_update.py and maintain_llm.py only recognized .gitea/workflows/, missing repos already on .forgejo/workflows/. Fixed a stale copy-paste example (state-hub's now-wrong old URL) in docs/RegistryFederation.md, and a pre-existing unrelated port typo (8088 vs the real llm-connect default 8080) in tools/README.md and registry/README.md. 17 new pytest cases (tests/test_forge_host.py), 106 total pass. Recomposed federated.yaml post-migration: still 61 capabilities. Co-Authored-By: Claude Sonnet 5 <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
plan-check
Query-before-build check (REUSE-WP-0018): match a draft workplan or a free
intent against the federated capability index before starting new work.
Deterministic token matching against registry/indexes/federated.yaml;
advisory only — never blocks workplan creation. See specs/PlanCheck.md.
reuse-surface plan-check workplans/XXX-WP-0042-something.md
reuse-surface plan-check --intent "parse invoices and file evidence"
reuse-surface plan-check --intent "..." --format json
reuse-surface plan-check --intent "..." --record-outcome reused
reuse-surface plan-check --intent "..." --file-request --requesting-domain infotech
export LLM_CONNECT_URL=http://127.0.0.1:8080 # optional, enables semantic rerank
reuse-surface plan-check --intent "..." --no-llm # skip the rerank pass
reuse-surface plan-check --intent "..." --llm-url http://127.0.0.1:8080
reuse|extend|new verdict from --reuse-threshold/--extend-threshold
(defaults 0.45/0.22). --record-outcome appends to
registry/telemetry/plan-check-events.jsonl (schema shared with
REUSE-WP-0019's reuse telemetry). --file-request files a State Hub
capability request on a new verdict (requires the hub reachable at
127.0.0.1:8000; degrades gracefully offline).
When LLM_CONNECT_URL is set, an optional rerank pass sends the top
deterministic candidates to llm-connect for a semantic confidence score.
Per design, this never reorders or replaces the deterministic result —
LLM-scored entries are appended after as separately-labeled [llm] matches,
so the trusted base result is identical whether or not the rerank runs.
Malformed/non-JSON LLM responses are rejected and reported as a note, never
silently guessed at; missing LLM_CONNECT_URL degrades the same way.
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
reuse-surface report gaps --check-capability-requests
--check-capability-requests (REUSE-WP-0018-T04) also lists open State Hub
capability requests with no matching federated capability; requires the hub
reachable at 127.0.0.1:8000 and degrades gracefully (prints "skipped") when
it isn't. Off by default so report gaps stays fast and offline-safe.
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:8080
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:8080 # 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