2026-06-15 01:04:30 +02:00
|
|
|
# Registry Tools
|
|
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
CLI tooling for the capability registry, implemented in `reuse_surface/`.
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
## Install
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
```bash
|
|
|
|
|
python3 -m venv .venv
|
|
|
|
|
.venv/bin/pip install -e .
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Commands
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
### validate
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
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
|
|
|
|
|
```
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
### query
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
Filter the capability index by maturity, tags, domain, consumption mode, or keyword.
|
2026-06-15 01:04:30 +02:00
|
|
|
|
|
|
|
|
```bash
|
2026-06-15 01:12:09 +02:00
|
|
|
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
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
Export a machine-readable bundle combining index rows and parsed entry front matter.
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
```bash
|
|
|
|
|
reuse-surface export
|
|
|
|
|
reuse-surface export --format json
|
2026-06-15 01:04:30 +02:00
|
|
|
```
|
|
|
|
|
|
2026-06-15 01:20:31 +02:00
|
|
|
### overlaps
|
|
|
|
|
|
|
|
|
|
Detect potential duplicate or overlapping capabilities (UC-RS-015).
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
reuse-surface overlaps
|
|
|
|
|
reuse-surface overlaps --threshold 0.35
|
|
|
|
|
```
|
|
|
|
|
|
REUSE-WP-0018 T01/T02/T04/T06: plan-check deterministic matching + State Hub bridge
T01: specs/PlanCheck.md design doc, plan-check-result.schema.json and
reuse-event.schema.json (the latter shared with WP-0019's reuse telemetry).
T02: reuse_surface/plan_check.py + 'reuse-surface plan-check' CLI command.
Deterministic token-Jaccard matching against registry/indexes/federated.yaml
(reuses overlaps.py's TOKEN_RE rather than a second scoring method), with
reuse/extend/new verdicts, markdown and --format json output, staleness
warning, and --record-outcome JSONL telemetry.
T04: reuse_surface/statehub_bridge.py bridges plan-check 'new' verdicts to
State Hub capability requests (--file-request) and surfaces open requests
with no matching capability (report gaps --check-capability-requests, opt-in
to stay offline-safe). Verified against the live local State Hub API;
status field (not catalog_entry_id presence) is the correct open/closed
signal, and the list endpoint needs a longer timeout than the health check
(~7s observed with 5 rows).
T06: docs (tools/README.md, RegistryFederation.md, SCOPE.md,
IntentScopeGapAnalysis.md priority 29) and an informational CI smoke step.
T03 (LLM rerank) not started -- llm-connect isn't running on this
workstation. T05 (ecosystem rollout) remains blocked: WP-0017 has drafted
entries for all 61 repos but they're still local-only pending its own T05
push/publish pass, so the federated index isn't yet worth rolling out
plan-check as ecosystem convention.
16 new tests, all mocked -- no network calls in the default test run.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 00:57:18 +02:00
|
|
|
### 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
|
2026-07-07 17:27:39 +02:00
|
|
|
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-WP-0018 T01/T02/T04/T06: plan-check deterministic matching + State Hub bridge
T01: specs/PlanCheck.md design doc, plan-check-result.schema.json and
reuse-event.schema.json (the latter shared with WP-0019's reuse telemetry).
T02: reuse_surface/plan_check.py + 'reuse-surface plan-check' CLI command.
Deterministic token-Jaccard matching against registry/indexes/federated.yaml
(reuses overlaps.py's TOKEN_RE rather than a second scoring method), with
reuse/extend/new verdicts, markdown and --format json output, staleness
warning, and --record-outcome JSONL telemetry.
T04: reuse_surface/statehub_bridge.py bridges plan-check 'new' verdicts to
State Hub capability requests (--file-request) and surfaces open requests
with no matching capability (report gaps --check-capability-requests, opt-in
to stay offline-safe). Verified against the live local State Hub API;
status field (not catalog_entry_id presence) is the correct open/closed
signal, and the list endpoint needs a longer timeout than the health check
(~7s observed with 5 rows).
T06: docs (tools/README.md, RegistryFederation.md, SCOPE.md,
IntentScopeGapAnalysis.md priority 29) and an informational CI smoke step.
T03 (LLM rerank) not started -- llm-connect isn't running on this
workstation. T05 (ecosystem rollout) remains blocked: WP-0017 has drafted
entries for all 61 repos but they're still local-only pending its own T05
push/publish pass, so the federated index isn't yet worth rolling out
plan-check as ecosystem convention.
16 new tests, all mocked -- no network calls in the default test run.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 00:57:18 +02:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`reuse|extend|new` verdict from `--reuse-threshold`/`--extend-threshold`
|
REUSE-WP-0019-T04: reuse telemetry store and recording
Implements the hub side of the shared reuse-event schema (already drafted
in WP-0018-T01, schemas/reuse-event.schema.json): a SQLite reuse_events
table, POST /v1/reuse-events (token-auth), GET /v1/reuse-events?capability_id=
(read-only).
reuse_surface/plan_check.py: refactored record_outcome around a new
shared post_or_fallback_reuse_event() helper -- tries the hub first, falls
back to the local JSONL only on failure/unreachability, never both. New
record_manual_reuse_event() backs a new CLI command, reuse-surface
record-reuse, for retroactive facts recorded outside plan-check.
Privacy/scope (repo slugs and capability ids only, no code, no secrets) is
enforced structurally via the schema's additionalProperties: false, not
just by convention.
21 new pytest cases, 145 total pass. Live-verified against a real running
hub instance: POST/GET /v1/reuse-events directly, record-reuse and
plan-check --record-outcome both posting successfully to the hub, and --
after actually killing the hub process -- confirmed the fallback path
writes correctly to the local JSONL instead of erroring.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 22:32:19 +02:00
|
|
|
(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).
|
REUSE-WP-0018 T01/T02/T04/T06: plan-check deterministic matching + State Hub bridge
T01: specs/PlanCheck.md design doc, plan-check-result.schema.json and
reuse-event.schema.json (the latter shared with WP-0019's reuse telemetry).
T02: reuse_surface/plan_check.py + 'reuse-surface plan-check' CLI command.
Deterministic token-Jaccard matching against registry/indexes/federated.yaml
(reuses overlaps.py's TOKEN_RE rather than a second scoring method), with
reuse/extend/new verdicts, markdown and --format json output, staleness
warning, and --record-outcome JSONL telemetry.
T04: reuse_surface/statehub_bridge.py bridges plan-check 'new' verdicts to
State Hub capability requests (--file-request) and surfaces open requests
with no matching capability (report gaps --check-capability-requests, opt-in
to stay offline-safe). Verified against the live local State Hub API;
status field (not catalog_entry_id presence) is the correct open/closed
signal, and the list endpoint needs a longer timeout than the health check
(~7s observed with 5 rows).
T06: docs (tools/README.md, RegistryFederation.md, SCOPE.md,
IntentScopeGapAnalysis.md priority 29) and an informational CI smoke step.
T03 (LLM rerank) not started -- llm-connect isn't running on this
workstation. T05 (ecosystem rollout) remains blocked: WP-0017 has drafted
entries for all 61 repos but they're still local-only pending its own T05
push/publish pass, so the federated index isn't yet worth rolling out
plan-check as ecosystem convention.
16 new tests, all mocked -- no network calls in the default test run.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 00:57:18 +02:00
|
|
|
|
2026-07-07 17:27:39 +02:00
|
|
|
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.
|
|
|
|
|
|
REUSE-WP-0019-T04: reuse telemetry store and recording
Implements the hub side of the shared reuse-event schema (already drafted
in WP-0018-T01, schemas/reuse-event.schema.json): a SQLite reuse_events
table, POST /v1/reuse-events (token-auth), GET /v1/reuse-events?capability_id=
(read-only).
reuse_surface/plan_check.py: refactored record_outcome around a new
shared post_or_fallback_reuse_event() helper -- tries the hub first, falls
back to the local JSONL only on failure/unreachability, never both. New
record_manual_reuse_event() backs a new CLI command, reuse-surface
record-reuse, for retroactive facts recorded outside plan-check.
Privacy/scope (repo slugs and capability ids only, no code, no secrets) is
enforced structurally via the schema's additionalProperties: false, not
just by convention.
21 new pytest cases, 145 total pass. Live-verified against a real running
hub instance: POST/GET /v1/reuse-events directly, record-reuse and
plan-check --record-outcome both posting successfully to the hub, and --
after actually killing the hub process -- confirmed the fallback path
writes correctly to the local JSONL instead of erroring.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 22:32:19 +02:00
|
|
|
### 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
|
|
|
|
|
```
|
|
|
|
|
|
2026-06-15 01:20:31 +02:00
|
|
|
### catalog
|
|
|
|
|
|
|
|
|
|
Generate human-readable catalog artifacts (UC-RS-018).
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
reuse-surface catalog
|
|
|
|
|
```
|
|
|
|
|
|
2026-06-15 02:24:20 +02:00
|
|
|
Writes `docs/CapabilityCatalog.md`, `docs/catalog/index.html`,
|
|
|
|
|
`docs/catalog/registry.json`, and `docs/catalog/search.html`.
|
2026-06-15 01:20:31 +02:00
|
|
|
|
2026-06-15 01:43:02 +02:00
|
|
|
### federation compose
|
|
|
|
|
|
|
|
|
|
Compose a federated index from `registry/federation/sources.yaml`.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
reuse-surface federation compose
|
2026-06-15 02:28:44 +02:00
|
|
|
reuse-surface federation compose --refresh
|
2026-06-15 01:43:02 +02:00
|
|
|
```
|
|
|
|
|
|
2026-06-15 02:28:44 +02:00
|
|
|
Composes local and remote HTTP index sources. Writes
|
|
|
|
|
`registry/indexes/federated.yaml` with `source_repo` attribution. Remote indexes
|
|
|
|
|
cache under `registry/federation/cache/`.
|
2026-06-15 01:43:02 +02:00
|
|
|
|
|
|
|
|
### graph
|
|
|
|
|
|
|
|
|
|
Generate a Mermaid relation graph from capability entry relations.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
reuse-surface graph
|
|
|
|
|
reuse-surface graph --check
|
|
|
|
|
reuse-surface graph --stdout
|
|
|
|
|
```
|
|
|
|
|
|
2026-06-15 02:24:20 +02:00
|
|
|
Writes `docs/graph/capability-graph.mmd` and `docs/graph/index.html`.
|
|
|
|
|
|
2026-06-15 08:48:06 +02:00
|
|
|
### hub
|
|
|
|
|
|
|
|
|
|
Client for the federation hub service (REUSE-WP-0011).
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-06-15 09:02:02 +02:00
|
|
|
export REUSE_SURFACE_URL=https://reuse.coulomb.social
|
|
|
|
|
export REUSE_SURFACE_TOKEN=<write-token>
|
2026-06-15 08:48:06 +02:00
|
|
|
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
|
2026-06-16 00:42:50 +02:00
|
|
|
reuse-surface hub sync --merge
|
|
|
|
|
reuse-surface hub sync --dry-run
|
2026-06-15 08:48:06 +02:00
|
|
|
```
|
|
|
|
|
|
2026-06-15 09:02:02 +02:00
|
|
|
Run the service locally: `REUSE_SURFACE_TOKEN=dev-token reuse-surface serve`
|
2026-06-15 08:48:06 +02:00
|
|
|
|
2026-06-16 02:22:17 +02:00
|
|
|
### 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-WP-0018 T01/T02/T04/T06: plan-check deterministic matching + State Hub bridge
T01: specs/PlanCheck.md design doc, plan-check-result.schema.json and
reuse-event.schema.json (the latter shared with WP-0019's reuse telemetry).
T02: reuse_surface/plan_check.py + 'reuse-surface plan-check' CLI command.
Deterministic token-Jaccard matching against registry/indexes/federated.yaml
(reuses overlaps.py's TOKEN_RE rather than a second scoring method), with
reuse/extend/new verdicts, markdown and --format json output, staleness
warning, and --record-outcome JSONL telemetry.
T04: reuse_surface/statehub_bridge.py bridges plan-check 'new' verdicts to
State Hub capability requests (--file-request) and surfaces open requests
with no matching capability (report gaps --check-capability-requests, opt-in
to stay offline-safe). Verified against the live local State Hub API;
status field (not catalog_entry_id presence) is the correct open/closed
signal, and the list endpoint needs a longer timeout than the health check
(~7s observed with 5 rows).
T06: docs (tools/README.md, RegistryFederation.md, SCOPE.md,
IntentScopeGapAnalysis.md priority 29) and an informational CI smoke step.
T03 (LLM rerank) not started -- llm-connect isn't running on this
workstation. T05 (ecosystem rollout) remains blocked: WP-0017 has drafted
entries for all 61 repos but they're still local-only pending its own T05
push/publish pass, so the federated index isn't yet worth rolling out
plan-check as ecosystem convention.
16 new tests, all mocked -- no network calls in the default test run.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 00:57:18 +02:00
|
|
|
reuse-surface report gaps --check-capability-requests
|
2026-06-16 02:22:17 +02:00
|
|
|
```
|
|
|
|
|
|
REUSE-WP-0018 T01/T02/T04/T06: plan-check deterministic matching + State Hub bridge
T01: specs/PlanCheck.md design doc, plan-check-result.schema.json and
reuse-event.schema.json (the latter shared with WP-0019's reuse telemetry).
T02: reuse_surface/plan_check.py + 'reuse-surface plan-check' CLI command.
Deterministic token-Jaccard matching against registry/indexes/federated.yaml
(reuses overlaps.py's TOKEN_RE rather than a second scoring method), with
reuse/extend/new verdicts, markdown and --format json output, staleness
warning, and --record-outcome JSONL telemetry.
T04: reuse_surface/statehub_bridge.py bridges plan-check 'new' verdicts to
State Hub capability requests (--file-request) and surfaces open requests
with no matching capability (report gaps --check-capability-requests, opt-in
to stay offline-safe). Verified against the live local State Hub API;
status field (not catalog_entry_id presence) is the correct open/closed
signal, and the list endpoint needs a longer timeout than the health check
(~7s observed with 5 rows).
T06: docs (tools/README.md, RegistryFederation.md, SCOPE.md,
IntentScopeGapAnalysis.md priority 29) and an informational CI smoke step.
T03 (LLM rerank) not started -- llm-connect isn't running on this
workstation. T05 (ecosystem rollout) remains blocked: WP-0017 has drafted
entries for all 61 repos but they're still local-only pending its own T05
push/publish pass, so the federated index isn't yet worth rolling out
plan-check as ecosystem convention.
16 new tests, all mocked -- no network calls in the default test run.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 00:57:18 +02:00
|
|
|
`--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.
|
|
|
|
|
|
2026-06-16 02:22:17 +02:00
|
|
|
Workstation roster report: publish blockers, empty scaffolds, seed-ready repos,
|
|
|
|
|
and local index owner stubs pending dedup.
|
|
|
|
|
|
REUSE-WP-0019-T05: reuse telemetry aggregation into R-axis evidence
reuse_surface/reports.py: collect_reuse_events() merges the hub's
GET /v1/reuse-events (if reachable) with this repo's local JSONL fallback,
deduped. collect_reuse_report() aggregates per-capability consumer counts,
outcome breakdown, and last-used. collect_reused_by_suggestions() proposes
evidence-gated relation_add patches -- only for capabilities this repo
owns, only for consumer repos not already listed -- reusing the existing
patches.py:apply_patches mechanism (relation_add already isn't in
SAFE_DETERMINISTIC_KINDS, so it was already never auto-applied by
maintain --auto).
New CLI: reuse-surface report reuse [--capability-id] [--format]
[--suggest-relations] [--apply]. --apply requires --suggest-relations and
is the only thing that writes -- nothing happens automatically from
telemetry alone.
schemas/capability.schema.yaml: added relations.reused_by as a new
repoSlugList type, distinct from the existing capability-id relations,
since reused-by targets are consumer repo slugs.
specs/CapabilityMaturityStandard.md Sec8.9: what observed-reuse evidence
counts toward R2->R3 (single corroborating consumer) vs R3->R4+ (multiple
independent consumers) and what it never substitutes for.
19 new pytest cases, 162 total pass. Live-verified with synthetic local
events against a real capability entry: --suggest-relations --apply
correctly wrote relations.reused_by via the real apply_patches path
(reverted after, since it was a smoke test).
Deliberately deferred: surfacing consumer counts in the catalog/graph --
graph.py's relation model is capability-to-capability edges, a different
namespace than repo-slug reused_by targets; catalog.py doesn't currently
parse full front matter per entry. Left for a follow-up.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 22:47:51 +02:00
|
|
|
### 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.
|
|
|
|
|
|
2026-06-16 01:21:01 +02:00
|
|
|
### 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
|
2026-06-16 02:09:57 +02:00
|
|
|
reuse-surface stats --roster registry/federation/local-repo-roster.yaml --federation-ready
|
REUSE-WP-0019-T06: hub freshness monitoring, docs, close workplan
reuse_surface/stats.py: _hub_summary() now reports composed_at, stale,
age_days, freshness_threshold_days (REUSE_SURFACE_FRESHNESS_DAYS env,
default 7), and a computed stale_warning. New hub_client.hub_federated()
backs it. format_stats_markdown surfaces a STALE marker when triggered.
.forgejo/workflows/ci.yml: new informational (non-failing) hub freshness
check against the live production hub on every push -- prints a
::warning:: annotation when stale, never fails the build.
docs/RegistryFederation.md: new section tying together the webhook (T02),
scheduled fallback (T03), and freshness visibility (T06) into one
explanation. docs/deploy/reuse-kubernetes.md: updated for the T03 Forgejo
migration and the now-automated image.yaml build; image promotion
checklist updated for the known /health ingress bug (verify via
/v1/repos or /v1/federated instead).
14 new pytest cases, 173 total pass. Live-verified against production:
reuse-surface stats correctly showed composed_at/age_days for the real
federated index. Separately discovered and confirmed (via a live signed
webhook test) that reuse-surface-env moving to ExternalSecret/OpenBao
custody (railiance-apps commit 706f6c7, found while updating these docs)
did not break the T02/T03 webhook -- the synced value still matches what
the hub actually uses.
REUSE-WP-0019 is now fully complete (T01-T06). SCOPE.md and
docs/IntentScopeGapAnalysis.md updated to reflect closure.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-08 00:09:58 +02:00
|
|
|
export REUSE_SURFACE_URL=https://reuse.coulomb.social
|
|
|
|
|
reuse-surface stats # hub section gains composed_at/stale/age_days/stale_warning
|
2026-06-16 01:21:01 +02:00
|
|
|
```
|
|
|
|
|
|
REUSE-WP-0019-T06: hub freshness monitoring, docs, close workplan
reuse_surface/stats.py: _hub_summary() now reports composed_at, stale,
age_days, freshness_threshold_days (REUSE_SURFACE_FRESHNESS_DAYS env,
default 7), and a computed stale_warning. New hub_client.hub_federated()
backs it. format_stats_markdown surfaces a STALE marker when triggered.
.forgejo/workflows/ci.yml: new informational (non-failing) hub freshness
check against the live production hub on every push -- prints a
::warning:: annotation when stale, never fails the build.
docs/RegistryFederation.md: new section tying together the webhook (T02),
scheduled fallback (T03), and freshness visibility (T06) into one
explanation. docs/deploy/reuse-kubernetes.md: updated for the T03 Forgejo
migration and the now-automated image.yaml build; image promotion
checklist updated for the known /health ingress bug (verify via
/v1/repos or /v1/federated instead).
14 new pytest cases, 173 total pass. Live-verified against production:
reuse-surface stats correctly showed composed_at/age_days for the real
federated index. Separately discovered and confirmed (via a live signed
webhook test) that reuse-surface-env moving to ExternalSecret/OpenBao
custody (railiance-apps commit 706f6c7, found while updating these docs)
did not break the T02/T03 webhook -- the synced value still matches what
the hub actually uses.
REUSE-WP-0019 is now fully complete (T01-T06). SCOPE.md and
docs/IntentScopeGapAnalysis.md updated to reflect closure.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-08 00:09:58 +02:00
|
|
|
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.
|
|
|
|
|
|
2026-06-16 01:21:01 +02:00
|
|
|
### 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
|
2026-07-07 18:14:30 +02:00
|
|
|
export LLM_CONNECT_URL=http://127.0.0.1:8080
|
2026-06-16 01:21:01 +02:00
|
|
|
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
|
2026-06-18 04:00:39 +02:00
|
|
|
reuse-surface update --capability capability.registry.register
|
2026-06-16 01:21:01 +02:00
|
|
|
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.
|
|
|
|
|
|
2026-06-18 04:00:39 +02:00
|
|
|
### maintain
|
|
|
|
|
|
|
|
|
|
Interactive or automated registry maintenance (REUSE-WP-0016). Preferred entry
|
|
|
|
|
point for sibling repo operators.
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-07-07 18:14:30 +02:00
|
|
|
export LLM_CONNECT_URL=http://127.0.0.1:8080 # optional
|
2026-06-18 04:00:39 +02:00
|
|
|
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`.
|
|
|
|
|
|
2026-06-16 00:42:50 +02:00
|
|
|
### 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.
|
|
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
## Export format
|
|
|
|
|
|
|
|
|
|
The export bundle includes:
|
|
|
|
|
|
|
|
|
|
- `version`, `domain`, `updated` from the index
|
|
|
|
|
- `capabilities[]` with `{ index, entry }` pairs
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
## Workflows
|
2026-06-15 01:04:30 +02:00
|
|
|
|
2026-06-15 01:12:09 +02:00
|
|
|
| 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` |
|
2026-06-15 01:20:31 +02:00
|
|
|
| Detect overlap | `reuse-surface overlaps` |
|
|
|
|
|
| Publish catalog | `reuse-surface catalog` |
|
2026-06-15 01:43:02 +02:00
|
|
|
| Compose federation | `reuse-surface federation compose` |
|
2026-06-16 00:42:50 +02:00
|
|
|
| Sync federation manifest from hub | `reuse-surface hub sync` |
|
2026-06-16 01:21:01 +02:00
|
|
|
| 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` |
|
2026-06-18 04:00:39 +02:00
|
|
|
| Interactive registry maintain | `reuse-surface maintain` |
|
2026-06-16 00:42:50 +02:00
|
|
|
| Planning cohort export | `reuse-surface report cohorts` |
|
2026-06-15 01:43:02 +02:00
|
|
|
| Relation graph | `reuse-surface graph` |
|
REUSE-WP-0019-T04: reuse telemetry store and recording
Implements the hub side of the shared reuse-event schema (already drafted
in WP-0018-T01, schemas/reuse-event.schema.json): a SQLite reuse_events
table, POST /v1/reuse-events (token-auth), GET /v1/reuse-events?capability_id=
(read-only).
reuse_surface/plan_check.py: refactored record_outcome around a new
shared post_or_fallback_reuse_event() helper -- tries the hub first, falls
back to the local JSONL only on failure/unreachability, never both. New
record_manual_reuse_event() backs a new CLI command, reuse-surface
record-reuse, for retroactive facts recorded outside plan-check.
Privacy/scope (repo slugs and capability ids only, no code, no secrets) is
enforced structurally via the schema's additionalProperties: false, not
just by convention.
21 new pytest cases, 145 total pass. Live-verified against a real running
hub instance: POST/GET /v1/reuse-events directly, record-reuse and
plan-check --record-outcome both posting successfully to the hub, and --
after actually killing the hub process -- confirmed the fallback path
writes correctly to the local JSONL instead of erroring.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 22:32:19 +02:00
|
|
|
| Query before building | `reuse-surface plan-check --intent "..."` |
|
|
|
|
|
| Record a reuse fact retroactively | `reuse-surface record-reuse` |
|
REUSE-WP-0019-T05: reuse telemetry aggregation into R-axis evidence
reuse_surface/reports.py: collect_reuse_events() merges the hub's
GET /v1/reuse-events (if reachable) with this repo's local JSONL fallback,
deduped. collect_reuse_report() aggregates per-capability consumer counts,
outcome breakdown, and last-used. collect_reused_by_suggestions() proposes
evidence-gated relation_add patches -- only for capabilities this repo
owns, only for consumer repos not already listed -- reusing the existing
patches.py:apply_patches mechanism (relation_add already isn't in
SAFE_DETERMINISTIC_KINDS, so it was already never auto-applied by
maintain --auto).
New CLI: reuse-surface report reuse [--capability-id] [--format]
[--suggest-relations] [--apply]. --apply requires --suggest-relations and
is the only thing that writes -- nothing happens automatically from
telemetry alone.
schemas/capability.schema.yaml: added relations.reused_by as a new
repoSlugList type, distinct from the existing capability-id relations,
since reused-by targets are consumer repo slugs.
specs/CapabilityMaturityStandard.md Sec8.9: what observed-reuse evidence
counts toward R2->R3 (single corroborating consumer) vs R3->R4+ (multiple
independent consumers) and what it never substitutes for.
19 new pytest cases, 162 total pass. Live-verified with synthetic local
events against a real capability entry: --suggest-relations --apply
correctly wrote relations.reused_by via the real apply_patches path
(reverted after, since it was a smoke test).
Deliberately deferred: surfacing consumer counts in the catalog/graph --
graph.py's relation model is capability-to-capability edges, a different
namespace than repo-slug reused_by targets; catalog.py doesn't currently
parse full front matter per entry. Left for a follow-up.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-07 22:47:51 +02:00
|
|
|
| Aggregate reuse telemetry into evidence | `reuse-surface report reuse --suggest-relations` |
|
2026-06-15 01:04:30 +02:00
|
|
|
|
|
|
|
|
## 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
|