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

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

View file

@ -807,6 +807,38 @@ reliability_evidence:
- consumer workarounds
```
#### Observed-reuse evidence (REUSE-WP-0019-T05)
`reuse-surface`'s own reuse telemetry (`registry/telemetry/plan-check-events.jsonl`
locally, `GET /v1/reuse-events` on the hub — see `specs/PlanCheck.md` and
`specs/FederationHubAPI.md`) is a form of `integration_evidence` /
`consumer_feedback`: a `reuse` verdict acted on (`outcome: reused` or
`extended`) is a real consumer choosing to build on the capability rather
than duplicate it.
What it counts toward, and what it doesn't:
- **Toward R2 → R3:** a single distinct consumer repo with a recorded
`reused`/`extended` outcome is corroborating evidence that the capability
"works reliably for normal use" for at least one real consumer — combine
with existing test/CI evidence, don't promote on telemetry alone.
- **Toward R3 → R4+:** requires **multiple independent consumer repos**
(`reuse-surface report reuse` shows `consumer_count`), not just repeated
events from the same one, plus no contradicting `bug_reports`/`incidents`
evidence for the same period. One repo reusing a capability five times
is still one data point, not five.
- **Never sufficient alone:** telemetry records that a decision was made
and (optionally) an outcome — it is not a substitute for `bug_reports`,
`operational_evidence`, or `incident` evidence, and a `reused_by` relation
(`report reuse --suggest-relations --apply`) documents *who* reused a
capability, not that the reuse *went well*. A capability can be reused
by five repos and still be R2 if the outcome evidence includes
`outcome: skipped` or recorded incidents.
- Promotion must still cite evidence explicitly in `promotion_history`
(§ maturity promotion convention) — `reuse-surface maintain`'s
`maturity_promote` patch kind is LLM-suggested and review-gated, never
auto-applied from telemetry counts alone.
---
## 9. Relationship Between Dimensions