coulomb/reuse-surface
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reuse-surface/tools/README.md
tegwick 2621cf2752 Use explicit fresh hosted capability snapshots for plan checks 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a07ff8-19d0-7820-b4d0-1353833cb7fc
2026-09-08 12:10:17 +02:00

344 lines
12 KiB
Markdown
Raw Blame History

# Registry Tools
CLI tooling for the capability registry, implemented in `reuse_surface/`.
## Install
```bash
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.
```bash
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.
```bash
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.
```bash
reuse-surface export
reuse-surface export --format json
```
### overlaps
Detect potential duplicate or overlapping capabilities (UC-RS-015).
```bash
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`.
```bash
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` records a reuse event
(REUSE-WP-0019-T04): `POST /v1/reuse-events` if the hub is reachable
(`REUSE_SURFACE_URL`/`REUSE_SURFACE_TOKEN` set), else appends to
`registry/telemetry/plan-check-events.jsonl` — never both, and the schema
(`schemas/reuse-event.schema.json`) is identical either way.
`--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.
### record-reuse
Manually record a retroactive reuse fact (REUSE-WP-0019-T04) — for
decisions made outside `plan-check`, e.g. discovered during a review.
Same hub-first-then-local-fallback behavior as `plan-check --record-outcome`.
```bash
reuse-surface record-reuse --consumer-repo some-repo \
--capability-id capability.infotech.issue-tracking \
--verdict reuse --outcome reused
reuse-surface record-reuse --consumer-repo some-repo --verdict new --format json
```
### catalog
Generate human-readable catalog artifacts (UC-RS-018).
```bash
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`.
```bash
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.
```bash
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).
```bash
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
```bash
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.
### report reuse
Reuse telemetry aggregation (REUSE-WP-0019-T05): per-capability consumer
counts, outcome breakdown, last-used, merged from the hub's
`GET /v1/reuse-events` (if reachable) and this repo's local
`registry/telemetry/plan-check-events.jsonl` fallback, deduped.
```bash
reuse-surface report reuse
reuse-surface report reuse --capability-id capability.infotech.issue-tracking
reuse-surface report reuse --format json
reuse-surface report reuse --suggest-relations
reuse-surface report reuse --suggest-relations --apply
```
`--suggest-relations` lists evidence-gated `relations.reused_by` suggestions
for capabilities this repo owns (skips consumer repos already listed).
`--apply` applies them via the same `apply_patches` mechanism `maintain`
uses for `relation_add` patches — requires `--suggest-relations`, and never
runs without it: nothing is written unless real observed-reuse events exist
*and* an operator explicitly passes `--apply`. See
`specs/CapabilityMaturityStandard.md` §8.9 for what observed-reuse evidence
does (and doesn't) count toward R-axis promotion.
### stats
Registry maturity aggregates and federation readiness.
```bash
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
export REUSE_SURFACE_URL=https://reuse.coulomb.social
reuse-surface stats # hub section gains composed_at/stale/age_days/stale_warning
```
Hub freshness (REUSE-WP-0019-T06): when `REUSE_SURFACE_URL` is configured,
`stats`'s `hub` section reports the federated index's `composed_at`, `stale`
flag, `age_days`, and a computed `stale_warning` (age beyond
`REUSE_SURFACE_FRESHNESS_DAYS`, default 7, or the hub's own `stale` flag).
CI runs this as an informational (non-failing) check on every push.
### establish
Bootstrap or discover a capability registry in the current or target repo.
```bash
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.
```bash
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.
```bash
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.
```bash
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`, `updated` from the index
- `capabilities[]` 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` |
| Query before building | `reuse-surface plan-check --intent "..."` |
| Record a reuse fact retroactively | `reuse-surface record-reuse` |
| Aggregate reuse telemetry into evidence | `reuse-surface report reuse --suggest-relations` |
## 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
### Hosted query-before-build
The default `plan-check` still uses the local composed index. To consult the
hosted registry explicitly:
```bash
reuse-surface plan-check --intent "tender document evidence" \
--hub-url https://reuse.coulomb.social --no-llm --format json
```
Hosted mode fetches the public `GET /v1/federated`; it does not send the query or
a mutation token. It requires a nonempty usable collection, `stale: false`, no
`X-Federation-Warnings`, and a timezone-aware composition no older than 24 hours
(overridable with positive finite `--max-index-age-hours`). Malformed, oversized,
unavailable, stale and partial responses exit **2** with no verdict or opt-in
outcome/request side effects. There is no automatic local fallback.
`index_source` records URL, capability count, composition/retrieval times and
SHA-256 of the response bytes. This is evidence about the accepted hub snapshot;
it does not certify every upstream repository's publication freshness. The
matching verdict is lexical advice; review candidates and owner contracts before
building, including when the verdict is `new`. `--no-llm` makes the check free of
additional model inference. Vergabe-teilnahme consumes it through `make plan-check`.
Reference in a new issue View git blame Copy permalink