coulomb/reuse-surface
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reuse-surface/tools/README.md

270 lines
8.9 KiB
Markdown
Raw Normal View History

Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
# Registry Tools
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
CLI tooling for the capability registry, implemented in `reuse_surface/`.
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
## Install
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
```bash
python3 -m venv .venv
.venv/bin/pip install -e .
```
## Commands
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
### validate
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
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
```
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
### query
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
Filter the capability index by maturity, tags, domain, consumption mode, or keyword.
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
```bash
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
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
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
Export a machine-readable bundle combining index rows and parsed entry front matter.
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
```bash
reuse-surface export
reuse-surface export --format json
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
```
Complete REUSE-WP-0004: CI, overlap detection, and catalog generation Add Gitea CI workflow for registry validation, reuse-surface overlaps and catalog commands, generated catalog artifacts, and documentation updates closing gap analysis priorities 9-11.
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
REUSE-WP-0018-T03: LLM semantic rerank for plan-check llm-connect came up locally (mock provider, 127.0.0.1:8080), unblocking this task. reuse_surface/plan_check.py: build_rerank_prompt/request_rerank/apply_rerank, reusing llm_bridge.execute_prompt/extract_json_object (same pattern as maintain_llm.py's request_maintain_patches). New schema schemas/plan-check-rerank.schema.json rejects malformed responses (missing fields, non-JSON, invented candidate ids outside the input set) rather than guessing. Per design principle 3 (deterministic matches always rank first), apply_rerank appends LLM-scored entries after the deterministic list (kind: 'llm') instead of reordering it -- the trusted base result is identical with or without the rerank pass. Graceful skip via a 'notes' field when LLM_CONNECT_URL is unset or the response is malformed, mirroring maintain.py's no_llm/skip pattern. New --llm-url/--no-llm CLI flags. Also extended plan-check-result.schema.json for 'notes' and the (pre-existing, previously unschema'd) 'filed_capability_request' field. 9 new pytest cases; 89 total pass. Live-verified against the running llm-connect instance: it correctly rejected the mock provider's non-JSON response and surfaced the skip note, with the deterministic verdict and match order completely unaffected. REUSE-WP-0018 is now fully done (T01-T06). Updated docs/IntentScopeGapAnalysis.md priority 29 to Closed and the workplan's own frontmatter status to finished. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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`
(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).
REUSE-WP-0018-T03: LLM semantic rerank for plan-check llm-connect came up locally (mock provider, 127.0.0.1:8080), unblocking this task. reuse_surface/plan_check.py: build_rerank_prompt/request_rerank/apply_rerank, reusing llm_bridge.execute_prompt/extract_json_object (same pattern as maintain_llm.py's request_maintain_patches). New schema schemas/plan-check-rerank.schema.json rejects malformed responses (missing fields, non-JSON, invented candidate ids outside the input set) rather than guessing. Per design principle 3 (deterministic matches always rank first), apply_rerank appends LLM-scored entries after the deterministic list (kind: 'llm') instead of reordering it -- the trusted base result is identical with or without the rerank pass. Graceful skip via a 'notes' field when LLM_CONNECT_URL is unset or the response is malformed, mirroring maintain.py's no_llm/skip pattern. New --llm-url/--no-llm CLI flags. Also extended plan-check-result.schema.json for 'notes' and the (pre-existing, previously unschema'd) 'filed_capability_request' field. 9 new pytest cases; 89 total pass. Live-verified against the running llm-connect instance: it correctly rejected the mock provider's non-JSON response and surfaced the skip note, with the deterministic verdict and match order completely unaffected. REUSE-WP-0018 is now fully done (T01-T06). Updated docs/IntentScopeGapAnalysis.md priority 29 to Closed and the workplan's own frontmatter status to finished. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.
Complete REUSE-WP-0004: CI, overlap detection, and catalog generation Add Gitea CI workflow for registry validation, reuse-surface overlaps and catalog commands, generated catalog artifacts, and documentation updates closing gap analysis priorities 9-11.
2026-06-15 01:20:31 +02:00
### catalog
Generate human-readable catalog artifacts (UC-RS-018).
```bash
reuse-surface catalog
```
Complete WP-0006 through WP-0009: registry expansion, catalog, graph, tests Register six new capabilities (12 total), add searchable catalog UI and graph explorer, introduce pytest suite with CI fail-on-warnings, and close gap analysis priorities 13 and 16. WP-0010 remains backlog for network federation.
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`.
Complete REUSE-WP-0004: CI, overlap detection, and catalog generation Add Gitea CI workflow for registry validation, reuse-surface overlaps and catalog commands, generated catalog artifacts, and documentation updates closing gap analysis priorities 9-11.
2026-06-15 01:20:31 +02:00
Complete REUSE-WP-0005: registry federation and relation graphs Add federation manifest and schema, federation compose and graph CLI commands, relation cycle/reference checks, federated index and Mermaid graph artifacts, RegistryFederation guide, and CI validation updates.
2026-06-15 01:43:02 +02:00
### federation compose
Compose a federated index from `registry/federation/sources.yaml`.
```bash
reuse-surface federation compose
Complete WP-0010: HTTP remote federation with cache Extend federation manifest schema for url sources with auth and TTL metadata. Fetch remote capability indexes over HTTP(S), cache under registry/federation/cache/, and fall back to stale cache on fetch failure. Add --refresh flag, seven federation tests, and updated federation docs.
2026-06-15 02:28:44 +02:00
reuse-surface federation compose --refresh
Complete REUSE-WP-0005: registry federation and relation graphs Add federation manifest and schema, federation compose and graph CLI commands, relation cycle/reference checks, federated index and Mermaid graph artifacts, RegistryFederation guide, and CI validation updates.
2026-06-15 01:43:02 +02:00
```
Complete WP-0010: HTTP remote federation with cache Extend federation manifest schema for url sources with auth and TTL metadata. Fetch remote capability indexes over HTTP(S), cache under registry/federation/cache/, and fall back to stale cache on fetch failure. Add --refresh flag, seven federation tests, and updated federation docs.
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/`.
Complete REUSE-WP-0005: registry federation and relation graphs Add federation manifest and schema, federation compose and graph CLI commands, relation cycle/reference checks, federated index and Mermaid graph artifacts, RegistryFederation guide, and CI validation updates.
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
```
Complete WP-0006 through WP-0009: registry expansion, catalog, graph, tests Register six new capabilities (12 total), add searchable catalog UI and graph explorer, introduce pytest suite with CI fail-on-warnings, and close gap analysis priorities 13 and 16. WP-0010 remains backlog for network federation.
2026-06-15 02:24:20 +02:00
Writes `docs/graph/capability-graph.mmd` and `docs/graph/index.html`.
Implement WP-0011 hub service, CLI, and deployment artifacts Add FederationHubAPI spec, hub registration schema, FastAPI hub with SQLite persistence, reuse-surface hub CLI client, Dockerfile, and hub tests. Activate workplan; T05 deploy and T06 ops docs remain open pending railiance01 cutover.
2026-06-15 08:48:06 +02:00
### hub
Client for the federation hub service (REUSE-WP-0011).
```bash
Align naming with coulomb.social reuse-surface conventions Use reuse.coulomb.social, REUSE_SURFACE_URL/TOKEN env vars, reuse-surface image and reuse-surface-env secret. Replace reuse-surface-hub entrypoint with reuse-surface serve; CLI uses --base-url.
2026-06-15 09:02:02 +02:00
export REUSE_SURFACE_URL=https://reuse.coulomb.social
export REUSE_SURFACE_TOKEN=<write-token>
Implement WP-0011 hub service, CLI, and deployment artifacts Add FederationHubAPI spec, hub registration schema, FastAPI hub with SQLite persistence, reuse-surface hub CLI client, Dockerfile, and hub tests. Activate workplan; T05 deploy and T06 ops docs remain open pending railiance01 cutover.
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
Implement REUSE-WP-0012 federation scale and intent alignment Add hub sync and report cohorts CLI commands with pytest coverage, document sibling index publish contract and hub hardening path, align INTENT layout, raise external evidence on three registry entries, and close gap priorities 19-23 (priority 18 deferred on sibling index blocks).
2026-06-16 00:42:50 +02:00
reuse-surface hub sync --merge
reuse-surface hub sync --dry-run
Implement WP-0011 hub service, CLI, and deployment artifacts Add FederationHubAPI spec, hub registration schema, FastAPI hub with SQLite persistence, reuse-surface hub CLI client, Dockerfile, and hub tests. Activate workplan; T05 deploy and T06 ops docs remain open pending railiance01 cutover.
2026-06-15 08:48:06 +02:00
```
Align naming with coulomb.social reuse-surface conventions Use reuse.coulomb.social, REUSE_SURFACE_URL/TOKEN env vars, reuse-surface image and reuse-surface-env secret. Replace reuse-surface-hub entrypoint with reuse-surface serve; CLI uses --base-url.
2026-06-15 09:02:02 +02:00
Run the service locally: `REUSE_SURFACE_TOKEN=dev-token reuse-surface serve`
Implement WP-0011 hub service, CLI, and deployment artifacts Add FederationHubAPI spec, hub registration schema, FastAPI hub with SQLite persistence, reuse-surface hub CLI client, Dockerfile, and hub tests. Activate workplan; T05 deploy and T06 ops docs remain open pending railiance01 cutover.
2026-06-15 08:48:06 +02:00
REUSE-WP-0015: dedup owner entries, add report gaps (T02/T03/T05) Remove 17 owner-migrated capabilities from reuse-surface index (keep activity-core stub). Add report gaps CLI, roster stats + gaps CI steps. T01 remains operator-blocked on Gitea publish.
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
REUSE-WP-0015: dedup owner entries, add report gaps (T02/T03/T05) Remove 17 owner-migrated capabilities from reuse-surface index (keep activity-core stub). Add report gaps CLI, roster stats + gaps CI steps. T01 remains operator-blocked on Gitea publish.
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.
REUSE-WP-0015: dedup owner entries, add report gaps (T02/T03/T05) Remove 17 owner-migrated capabilities from reuse-surface index (keep activity-core stub). Add report gaps CLI, roster stats + gaps CI steps. T01 remains operator-blocked on Gitea publish.
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.
Implement REUSE-WP-0013 registry establish, update, and stats Add stats, establish (scaffold, publish-check, discover), and update CLI commands with optional llm-connect bridge, validate --root for sibling repos, pytest coverage, and documentation for sibling registry onboarding.
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
REUSE-WP-0014: T11 docs, roster stats, workplan finished Link local-repo-roster in RegistryFederation; rollout milestone history; update IntentScopeGapAnalysis (60 hub members). Add stats --roster --federation-ready for workstation federation readiness.
2026-06-16 02:09:57 +02:00
reuse-surface stats --roster registry/federation/local-repo-roster.yaml --federation-ready
Implement REUSE-WP-0013 registry establish, update, and stats Add stats, establish (scaffold, publish-check, discover), and update CLI commands with optional llm-connect bridge, validate --root for sibling repos, pytest coverage, and documentation for sibling registry onboarding.
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
REUSE-WP-0019-T01: forge host abstraction + URL migration inventory 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>
2026-07-07 18:14:30 +02:00
export LLM_CONNECT_URL=http://127.0.0.1:8080
Implement REUSE-WP-0013 registry establish, update, and stats Add stats, establish (scaffold, publish-check, discover), and update CLI commands with optional llm-connect bridge, validate --root for sibling repos, pytest coverage, and documentation for sibling registry onboarding.
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
WP-0016 finished: interactive registry maintain with llm-connect automation 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>
2026-06-18 04:00:39 +02:00
reuse-surface update --capability capability.registry.register
Implement REUSE-WP-0013 registry establish, update, and stats Add stats, establish (scaffold, publish-check, discover), and update CLI commands with optional llm-connect bridge, validate --root for sibling repos, pytest coverage, and documentation for sibling registry onboarding.
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.
WP-0016 finished: interactive registry maintain with llm-connect automation 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>
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
REUSE-WP-0019-T01: forge host abstraction + URL migration inventory 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>
2026-07-07 18:14:30 +02:00
export LLM_CONNECT_URL=http://127.0.0.1:8080 # optional
WP-0016 finished: interactive registry maintain with llm-connect automation 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>
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`.
Implement REUSE-WP-0012 federation scale and intent alignment Add hub sync and report cohorts CLI commands with pytest coverage, document sibling index publish contract and hub hardening path, align INTENT layout, raise external evidence on three registry entries, and close gap priorities 19-23 (priority 18 deferred on sibling index blocks).
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.
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
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
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
2026-06-15 01:12:09 +02:00
## Workflows
Bootstrap and first implementation
2026-06-15 01:04:30 +02:00
Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
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` |
Complete REUSE-WP-0004: CI, overlap detection, and catalog generation Add Gitea CI workflow for registry validation, reuse-surface overlaps and catalog commands, generated catalog artifacts, and documentation updates closing gap analysis priorities 9-11.
2026-06-15 01:20:31 +02:00
| Detect overlap | `reuse-surface overlaps` |
| Publish catalog | `reuse-surface catalog` |
Complete REUSE-WP-0005: registry federation and relation graphs Add federation manifest and schema, federation compose and graph CLI commands, relation cycle/reference checks, federated index and Mermaid graph artifacts, RegistryFederation guide, and CI validation updates.
2026-06-15 01:43:02 +02:00
| Compose federation | `reuse-surface federation compose` |
Implement REUSE-WP-0012 federation scale and intent alignment Add hub sync and report cohorts CLI commands with pytest coverage, document sibling index publish contract and hub hardening path, align INTENT layout, raise external evidence on three registry entries, and close gap priorities 19-23 (priority 18 deferred on sibling index blocks).
2026-06-16 00:42:50 +02:00
| Sync federation manifest from hub | `reuse-surface hub sync` |
Implement REUSE-WP-0013 registry establish, update, and stats Add stats, establish (scaffold, publish-check, discover), and update CLI commands with optional llm-connect bridge, validate --root for sibling repos, pytest coverage, and documentation for sibling registry onboarding.
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` |
WP-0016 finished: interactive registry maintain with llm-connect automation 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>
2026-06-18 04:00:39 +02:00
| Interactive registry maintain | `reuse-surface maintain` |
Implement REUSE-WP-0012 federation scale and intent alignment Add hub sync and report cohorts CLI commands with pytest coverage, document sibling index publish contract and hub hardening path, align INTENT layout, raise external evidence on three registry entries, and close gap priorities 19-23 (priority 18 deferred on sibling index blocks).
2026-06-16 00:42:50 +02:00
| Planning cohort export | `reuse-surface report cohorts` |
Complete REUSE-WP-0005: registry federation and relation graphs Add federation manifest and schema, federation compose and graph CLI commands, relation cycle/reference checks, federated index and Mermaid graph artifacts, RegistryFederation guide, and CI validation updates.
2026-06-15 01:43:02 +02:00
| Relation graph | `reuse-surface graph` |
Bootstrap and first implementation
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
Reference in a new issue Copy permalink