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

REUSE-WP-0019-T04: reuse telemetry store and recording
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 10s
Details
ci / validate-registry (push) Has been cancelled
Details
Build and Publish Container Image / build-and-push (push) Successful in 1m16s
Details

Browse source 
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>
This commit is contained in:
tegwick 2026-07-07 22:32:19 +02:00
parent 2fcc91f2aa
commit d181043717
12 changed files with 562 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

28
tools/README.md
View file

@ -70,11 +70,14 @@ 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).
(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.
@ -84,6 +87,19 @@ 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).
@ -262,6 +278,8 @@ Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).
| 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` |
## Related use cases