compose primitives: ship the maintainer combos as commands (validated: cross-PR collision prediction)

[JordanCoin]

Companion to #133. That issue proposes one composite; this one argues the category, and gives a second validated example.

The pattern

Over a long maintenance session on this repo I kept hand-assembling the same small command chains. None of them are hard. All of them are things a user has to know to do, and the ones that matter most are the ones nobody runs.

The recurring combos:

1. Answer + trust — --importers plus language-scoped coverage. Proposed in compose primitives: 'codemap check <file>' should answer AND say whether to believe the answer #133.
2. Cross-PR collision prediction — which open PRs touch the same files, before merging.
3. Noise-floor check — run a new diagnostic against this repo and count output; a signal that fires hundreds of times is not a signal. This caught an implementation that emitted 887 false positives on codemap itself.
4. Grader calibration — before trusting a check, run it against a known-bad baseline and confirm it fails. This caught a rubric of mine that passed the buggy baseline, i.e. tested nothing.

Validated example: collision prediction

Four PRs (#124-#127) each passed CI independently. I found out they were mutually exclusive by creating six worktrees, merging each pair, and building — about fifteen minutes of wall time.

A prototype composing gh pr view --json files with a shared-file intersection reproduces that in one command:

  SHARED FILES (each = a merge-order hazard):
    4 PRs   scanner/astgrep.go        <- #124, #125, #126, #127
    4 PRs   scanner/rustgraph.go      <- #124, #125, #126, #127
    3 PRs   scanner/sg-rules/rust.yml <- #125, #126, #127

  PREDICTED COLLIDING PAIRS:
    #124 + #125  ->  2 shared file(s)
    #124 + #126  ->  2 shared file(s)
    #124 + #127  ->  2 shared file(s)
    #125 + #126  ->  3 shared file(s)
    #125 + #127  ->  3 shared file(s)
    #126 + #127  ->  3 shared file(s)

Against the empirically measured matrix: 6 of 6 pairs correct, including the 2-vs-3 distinction (the extra file being the shared sg-rules edit among #125/#126/#127).

This matters because CI structurally cannot see it — every PR is built against main, never against its siblings. That blind spot already produced a real miscompile here: #117 and #118 were both green and did not compile together, because one changed discoverCargoManifests' signature and the other added a caller using the old one.

Honest scoping caveat: the file-intersection half needs no graph at all, so it is not obviously codemap's job. What is codemap's job is the weighting — "these PRs collide on a file with 23 importers" is a different severity from "they collide on a test fixture", and only codemap knows which. If this ships, the graph-aware ranking is the part that belongs here; the rest is glue.

Design principle worth writing down

From validating #133: a composite inherits the honesty of its primitives and states it with more authority. The same prototype said TRUST HIGH on shipped codemap and TRUST LOW on a build with honest coverage — same file, same code path, opposite verdicts, and the shipped one was wrong.

So composites are not a way around primitive defects, they amplify them. Any combo shipped should refuse to render a confident verdict when its inputs report degraded coverage.

Suggested order

1. coverage is reported at scan granularity but consumed at query granularity #111 / honest issues[] — the primitives get truthful
2. compose primitives: 'codemap check <file>' should answer AND say whether to believe the answer #133 codemap check <file> — the combo most likely to prevent a wrong action
3. collision prediction, graph-weighted
4. a self-check / noise-floor mode, useful mainly to codemap's own contributors when adding a diagnostic

Related: #133, #111, #132, #130, #131.