plan(v0.35): REQ-308 — verify advances on evidence existence, not sufficiency (#838)

[avrabe]

Triages #838 into the plan. Reported from varve, and reproduced in rivet's own
v0.34.0 cut the same day — which is why this is a filed requirement rather than
an acknowledgement.

The gap

rivet verify REQ-X refuses correctly when there is no evidence. When a
verifies marker exists it advances unconditionally, and a marker costs one
comment line above one #[test].

The structural problem is granularity: a requirement is a set of clauses; a
marker attaches to the requirement. The evidence link is coarser than the
claim, so a shortfall has no representation. That produces a graph that looks
complete — worse than one that looks incomplete, because readers stop reading
the requirement text once the status says verified.

Our own instance, from yesterday

REQ-298 was flipped to verified during the v0.34.0 release with its third
clause knowingly undischarged — "tighten the top-level command list so the
common path is legible", still 52 flat top-level commands. Meanwhile:

rivet coverage --tests   →   REQ-298  1 test marker

Indistinguishable from full discharge. The residual was hand-carried into
REQ-307 plus commit prose — the issue's option (3), improvised manually. The
trace graph does not carry that caveat, so the caveat is not traceable, which
is precisely the property this tool exists to provide.

Degenerate variant, also found yesterday

A marker that matches nothing reports as neither present nor broken. The
scanner accepts only word characters and hyphens after verifies, so an issue
number silently is not a marker:

'/// rivet: verifies REQ-294'  →  REQ-294
'/// rivet: verifies #808'     →  NO MATCH

Six were in that state against 593 valid ones. So there are two silent states
today: a marker covering only some clauses, and a marker covering nothing while
looking correct in source.

Where I differ from the issue's ordering

The issue lists three options by cost. I'd reorder the first two:

Option (2) — make partially-verifies BLOCK — should land before option (1).
It needs no schema change and converts the common case ("I know clause 3 is
open") into a refusal verify won't advance past. Option (1), per-clause
markers, is the real fix but requires clauses to become addressable — today
they are prose inside description, so that is a schema migration across every
existing artifact. The cheap win shouldn't wait on it.

One caution on option (3): --clauses-discharged "1,2,4" is only meaningful
if clause numbering is stable, and prose clauses renumber whenever someone edits
the description. Record the clause text alongside the index, or do (1) first —
otherwise the record silently drifts.

Verification

rivet validate exit 0 · rivet docs check exit 0 · YAML parses, 278
artifacts, no duplicate ids.

(The first draft of this artifact broke the file — \w is an invalid escape in
a double-quoted YAML scalar. Caught by validating before pushing rather than in
CI.)

[github-actions]

📐 Rivet artifact delta

Change	Count
Added	1
Removed	0
Modified	0
Downstream impacted (depth ≤ 5)	0

Graph

graph LR
  REQ_308["REQ-308"]:::added
  classDef added fill:#d4edda,stroke:#28a745,color:#155724
  classDef removed fill:#f8d7da,stroke:#dc3545,color:#721c24
  classDef modified fill:#fff3cd,stroke:#ffc107,color:#856404
  classDef overflow fill:#e2e3e5,stroke:#6c757d,color:#495057,stroke-dasharray: 3 3

Loading

Added

• REQ-308

📎 Full HTML dashboard attached as workflow artifact rivet-delta-pr-840 — download from the workflow run.

_{Posted by rivet-delta workflow. The graph shows only changed artifacts; open the HTML dashboard (above) for full context.}

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Rivet Criterion Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: fc3605d	Previous: b3bc0d3	Ratio
validate/10000	1298652091 ns/iter (± 9970316)	1081910995 ns/iter (± 19388520)	1.20
traceability_matrix/1000	66021 ns/iter (± 449)	45538 ns/iter (± 180)	1.45
query/10000	326834 ns/iter (± 3577)	257844 ns/iter (± 2205)	1.27

This comment was automatically generated by workflow using github-action-benchmark.