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

REUSE-WP-0019-T05: reuse telemetry aggregation into R-axis evidence
Some checks failed
CI Smoke / host-smoke (push) Successful in 1s
Details
CI Smoke / container-smoke (push) Successful in 2s
Details
ci / validate-registry (push) Has been cancelled
Details
Build and Publish Container Image / build-and-push (push) Successful in 1m23s
Details

Browse source 
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>
This commit is contained in:
tegwick 2026-07-07 22:47:51 +02:00
parent e6e275ce79
commit bca7165e02
8 changed files with 576 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

25
tools/README.md
View file

@ -170,6 +170,30 @@ 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.
@ -280,6 +304,7 @@ Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).
| 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