docs(conventions): harden detector-findings with the rule-id to severity crosswalk

[kyle-sexton]

Phase 4 of the boris-routines-adoption plan. Depends on #2680; blocks the first new detector.

Written from what the pilot observed. Must land before the second detector adopts the convention.

What this closes

Acceptance criterion 2 of the plan's Brief: "Every detector emits machine-computed severity, not prose routed through an LLM crosswalk. No crosswalk row exists for a deterministic surface today; that is contract work."

The trap: plugins/review/context/severity.md:7 defines tiers by tests, not examples — "The test decides the tier". CRITICAL is "you can name a concrete input, caller, or subsequent otherwise-correct change that the defect makes produce a wrong result". A bare threshold cannot evaluate that predicate, so a threshold-to-tier table without the test is nominal closure, not real.

Work items

• Rule-id to severity-tier crosswalk, with the test each mapping asserts. A rule whose tier cannot be argued from the test is not admitted.
• Rule/threshold vocabulary: every finding names the rule id and the threshold that fired, so severity is auditable without re-reading the code.
• Bind suppression to docs/conventions/finding-suppression/ — including its derived finding_id — rather than inventing a second suppression surface.
• Cite REVIEW.md as the consumer-precedence override over severity.md:3; the plugin file is the fallback baseline.
• Record the gating consequence: a finding is auto-appliable only when single-file, high-confidence, and not architectural-judgment-shaped (fix-pass-mode.md:58). Layering and abstraction detectors are therefore designed to inform a human, not to feed an autonomous apply loop — the contract's intent, not a limitation to engineer around.
• Decide the shared-emitter question. Emitting a conforming file requires resolving memory_dir with its fallback ladder, computing <branch-slug>, running the self-ignore guard, relativizing paths, escaping cells, and formatting a colon-free UTC timestamp. feat(mutation-testing): persist survivors as a conforming findings file behind a flag #2680 is the second implementation; the detector phase would be the third. Either declare a shared-source cluster in scripts/cross-plugin-source-registry.txt (drift-checked by scripts/check-cross-plugin-source-drift.sh, registered at PLUGIN-PHILOSOPHY.md:479), or record why three implementations are accepted and how drift is caught.

Sanity checks

• grep -c "finding-suppression" docs/conventions/detector-findings/README.md >= 1 and grep -c "REVIEW.md" .../README.md >= 1.
• No crosswalk row has an empty test cell — awk -F'|' '/^\| rule-/ { gsub(/ /,"",$4); if ($4=="") exit 1 }' docs/conventions/detector-findings/README.md exits 0, and the count of ^| rule- rows equals the rule count. (A bare grep -c "^| .* | .* |" also matches header and separator rows, so it can never equal the rule count.)
• scripts/check-cross-plugin-source-drift.sh exits 0, whichever branch of the shared-emitter decision was taken.

Related

• Depends on feat(mutation-testing): persist survivors as a conforming findings file behind a flag #2680; hardens docs(conventions): add the detector-findings owner doc (stub) #2679

[kyle-sexton]

Empirical input for this phase — the scope fence has no disposition for a finding whose remediation is elsewhere

Found by running the #2680 pilot's two-producer merge for real, not by reading the contract. Recording
it here because this issue is explicitly "written from what the pilot observed", and this is the
sharpest thing the pilot observed.

The situation

A mutation-testing:audit survivor finding is located at the production script that the surviving
mutant lives in. Its remediation is in the test file — you fix a survivor by strengthening the
test, not by editing the code under test. So Location and the remediation site are different files,
by the nature of the detector.

Why that is unresolvable under the current consumer contract

Three facts compose into a dead end:

1. fix-pass-mode.md Step 4 fences each fix to its finding's Location — "touch only that file
   for that finding". Location names the production script.
2. The findings table has no remediation-target column. The 7-column shape (Rank, Tier,
   Confidence, Location, Surface(s), Finding, Action) cannot express "detected here, fix
   there". The fence structurally cannot read the Action cell.
3. The "surface instead of auto-applying" escape does not fire. Its three triggers are
   low-confidence, needs-architectural-judgment, and high-blast-radius. The pilot's three rows are
   high-confidence, mechanically contained, and low blast radius — none of them fire. So the clause
   does not authorize surfacing on fence-conflict grounds.

A fixer executing Step 4 is therefore left choosing between breaching its own fence and
inventing a justification to surface. Neither is a disposition the contract offers.

Naming the remediation site in the Action prose — which the pilot tried — does not fix this. It
converts an ambiguity into an explicit contradiction: the cell now instructs the fixer, in prose, to
violate its governing rule. Verified that the named targets exist and are not phantom paths
(scripts/check-changelog-parity.test.sh, scripts/check-skill-leaf-names.test.sh,
scripts/check-docs-only.test.sh), so this is not a quality problem with the producer's output.

Why it belongs to this phase rather than to #2680 or #2690

The remedy is in the consumer contract, not in producer prose — either a remediation-target
column, or a rule that Location names the file to be edited with the detection site recorded
elsewhere. Both are contract changes with fleet-wide blast radius, and both want the crosswalk work
this issue already owns. #2680 should not invent a column; #2690 is closing on the coexistence
defect it was opened for.

This also generalizes past mutation testing. Any detector whose finding site and fix site differ hits
it — a coverage gap, a missing test for a changed function, a contract violation detected at the
caller but fixed at the callee. The can't-fail test detector in #2684 is the next one to land on it.

Related, from the same pilot run

• The two-producer merge works: S = 2, five findings merged across both producers, the plan names
  both files with per-file tier:, and emits the Surfaces (union) line. feat(review): merge findings across producers and mark consumption explicitly (ADR 0010) #2678's gate is proven in
  situ rather than by fixture.
• A separate contradiction — the coverage fields are "required" in default-mode.md and omittable in
  fix-pass-mode.md Step 1 — is routed to feat(review): merge findings across producers and mark consumption explicitly #2690, which owns both files.
• A producer rewriting a findings file in place (same name, same date:, different content) would
  be silently subtracted under name-based matching. feat(review): merge findings across producers and mark consumption explicitly #2690's content-digest identity closes this; the
  pilot was testing an older base.

[kyle-sexton]

Second empirical input from the pilot — an equivalence disposition has nowhere structured to live

Also found by running #2680's pilot for real, and it is adjacent to the crosswalk this issue owns.

What happened

The pilot's mutation run produced two survivors. One was productive (a genuine oracle gap — the
test suite never exercises the argument parser, so the mutant survives and the proposed test kills
it). The other was judged equivalent with cited differential evidence (break-removal from a
side-effect-free match loop: eight differential cases identical on stdout, exit and stderr;
$prefix dead after the loop; no iteration counter; matched=1 idempotent).

The equivalent one correctly emits no ## Findings row — an equivalent mutant is not a defect,
and a row would route it into fix-pass-mode.md Step 4 for a remediation that must not be written.
So the disposition was recorded in ## Surfaces prose instead.

The gap

"Equivalent" has no structured field anywhere in the findings shape. The 7-column table has
Rank, Tier, Confidence, Location, Surface(s), Finding, Action — none of which can carry
"examined, judged not-a-defect, here is the evidence". So the disposition lives in free prose in a
reconciliation line, with three consequences:

1. It can never be machine-checked. A gate cannot verify that an equivalence claim carries
   evidence, which is exactly the discipline the pilot imposed on itself voluntarily
   (equivalence-without-evidence stays unclassified and emits a row). A rule nothing can check is
   a rule the next producer may quietly drop.
2. It inflates ## Surfaces. The union across producers already carries ran/returned-nothing
   per surface; folding per-mutant equivalence rationales into it makes the plan header long and
   mixes two different kinds of statement.
3. It is invisible to trend gating. Equivalent-mutant rate is a real signal about a detector's
   precision over time, and it currently cannot be extracted from a conforming file.

Why it belongs to this phase

This issue already owns the rule/threshold vocabulary — "every finding names the rule id and the
threshold that fired, so severity is auditable without re-reading the code". A disposition
vocabulary is the same shape of problem one step along: the crosswalk says how a rule maps to a
tier, and this asks how a non-finding is recorded conformantly.

It also generalizes past mutation testing. Any detector with an examined-but-not-reportable outcome
hits it — a suppressed finding, a rule that fired below threshold, a candidate the detector
deliberately declined. docs/conventions/finding-suppression/ (which this issue already binds) is
the nearest existing surface and may be where the answer lives rather than in a new field.

Deliberately not fixed in the pilot

#2680 was told not to invent a field. Its ## Surfaces placement was independently reviewed and
judged correct given the current shape — the section's own clause is "Returned no result: [...]
(with cause when known)", and no consumer mishandles it (the fix action derives its finding count
from parsed rows, never from a survivor count). So this is a shape limitation surfaced by the pilot,
not a defect in the pilot.

Related

• feat(mutation-testing): persist survivors as a conforming findings file behind a flag #2680 — the pilot that surfaced it
• The scope-fence gap recorded in this issue's earlier comment, from the same run
• docs/conventions/finding-suppression/ — candidate home for the answer