control-arm 0.1.0

package/src/verdict.mjs

@@ -0,0 +1,168 @@
+/**
+ * The decision. Pure functions only — no git, no filesystem, no subprocesses.
+ *
+ * This file is deliberately the only place a verdict is decided, and deliberately
+ * has no I/O, because it is the part that has to be exhaustively tested. Everything
+ * else in this tool is plumbing that produces its two inputs.
+ *
+ * THE FIVE VERDICTS
+ *
+ *   CAUGHT              the case ran on the broken code and DISAGREED with it (assertion)
+ *   NON-DISCRIMINATING  the case ran and was fine with it  (case level — a fact, not a fault)
+ *   BLIND               NO case in the commit discriminated (commit level — a judgement)
+ *   INCONCLUSIVE  the case did not run, or we cannot prove what it ran against
+ *   FLAKY         repeated runs disagreed with each other
+ *   SKIPPED       there was nothing to judge
+ *
+ * WHY EXIT CODE IS NOT THE SIGNAL. A test that "fails" at the parent commit with
+ * `SyntaxError: does not provide an export named 'TITLE_SEPARATOR'` — because the fix
+ * ADDED that export — has a non-zero exit and has told you nothing: it never ran. Read
+ * exit code only and you report CAUGHT, and the tool's headline number is inflated
+ * garbage. Observed on a real fix commit whose new export the parent did not have.
+ *
+ * WHY A FALSE `BLIND` IS THE WORST OUTPUT. CAUGHT and INCONCLUSIVE are both survivable
+ * — one is good news, the other is an honest shrug. BLIND accuses an engineer of having
+ * written a test that cannot fail. Get that wrong and nobody trusts the tool again. So
+ * every ambiguity resolves AWAY from BLIND, never toward it.
+ */
+
+export const CAUGHT = 'CAUGHT';
+/**
+ * CASE level. The case ran on the broken code and was fine with it.
+ *
+ * NOT a synonym for "bad test", and renamed from BLIND on 2026-09-23 after the first real
+ * run said this about a commit whose fix added a separator class:
+ *
+ *     ✗ BLIND   CONTROL ARM: the old pattern really does split one phrase in two
+ *     ✗ BLIND   the prefix rule survives the wider separator class
+ *     ✗ BLIND   the labels the separator change must not touch
+ *
+ * All three are REGRESSION GUARDS. They are supposed to be green on both arms — that is
+ * their entire job. Calling them blind is a false accusation of a careful engineer, which
+ * is the one output that destroys trust in this tool.
+ *
+ * Red/green cannot distinguish "meant to catch this bug and failed" from "meant to stay
+ * green". That is INTENT, and the tool cannot read it. So the case level states the FACT
+ * (it did not discriminate) and the judgement is made only where it is safe: at the
+ * commit, where a fix in which NOTHING discriminates shipped no test that could catch its
+ * own bug, whatever each case was for.
+ */
+export const NON_DISCRIMINATING = 'NON-DISCRIMINATING';
+/** COMMIT level only: every case ran, and not one of them discriminated. */
+export const BLIND = 'BLIND';
+export const INCONCLUSIVE = 'INCONCLUSIVE';
+export const FLAKY = 'FLAKY';
+export const SKIPPED = 'SKIPPED';
+
+/**
+ * Did this failure come from the test DISAGREEING, or from it being unable to run?
+ *
+ * node:test TAP puts `name: 'AssertionError'` / `code: 'ERR_ASSERTION'` on the first and
+ * a real error name (ReferenceError, SyntaxError, TypeError) on the second. Other runners
+ * differ; `runners/*.mjs` maps them onto this same shape, which is why this predicate
+ * takes a normalised case and not raw output.
+ */
+export function isDisagreement(caseResult) {
+    if (!caseResult || caseResult.status !== 'fail') return false;
+    if (caseResult.code === 'ERR_ASSERTION') return true;
+    if (caseResult.errorName === 'AssertionError') return true;
+    // Assertion libraries that are not node:assert. Narrow on purpose: an unknown error
+    // name must fall through to INCONCLUSIVE, not be guessed into CAUGHT.
+    return ['JestAssertionError', 'ExpectationFailed', 'AssertionFailedError'].includes(caseResult.errorName);
+}
+
+/**
+ * One case, one run. `armA` is the case on the FIXED code, `armB` the same case
+ * transplanted onto the BROKEN (parent) code.
+ *
+ * `identity` is the proof that armB actually loaded the parent's modules. It is a hard
+ * gate before anything else, because without it a BLIND is indistinguishable from a
+ * harness that silently resolved the fixed code — which is exactly what happened on the
+ * first real run of this tool.
+ */
+export function classify({ armA, armB, identity }) {
+    if (identity && identity.proven === false) {
+        return { verdict: INCONCLUSIVE, reason: `module identity unproven: ${identity.reason}` };
+    }
+    if (!armA) return { verdict: SKIPPED, reason: 'case not present on the fix' };
+
+    // A case the runner SKIPPED tells us nothing and is not a failure of anything. It gets
+    // its own bucket rather than inflating INCONCLUSIVE — 257 of 1,185 cases in the first
+    // 300-commit audit were `skip`, almost all DB-gated tests with no TEST_DATABASE_URL.
+    // Folding those into "could not be judged" hides the fact that they are judgeable, by
+    // anyone who runs the audit with a database.
+    if (armA.status === 'skip') {
+        return { verdict: SKIPPED, reason: 'the runner skipped this case on the fix (gated on an env var or a service?)' };
+    }
+    // The fix must be green, or there is no "before and after" to compare. A red case on
+    // the fix means the commit does not stand on its own — not that the test is bad.
+    if (armA.status !== 'pass') {
+        return { verdict: INCONCLUSIVE, reason: `case is not green on the fix (${armA.errorName || armA.status})` };
+    }
+    // The case exists on the fix but never reported on the parent: the file failed to
+    // load, or the runner died before reaching it.
+    if (!armB) {
+        return { verdict: INCONCLUSIVE, reason: 'case did not report on the parent (file failed to load?)' };
+    }
+    if (armB.status === 'pass') {
+        return { verdict: NON_DISCRIMINATING, reason: 'green on the broken code (a regression guard looks identical here)' };
+    }
+    if (isDisagreement(armB)) {
+        return { verdict: CAUGHT, reason: armB.message || 'assertion failed on the broken code' };
+    }
+    return {
+        verdict: INCONCLUSIVE,
+        reason: `case errored rather than failed on the parent (${armB.errorName || armB.code || 'unknown'}) — it never ran`,
+    };
+}
+
+/**
+ * N runs of the same case. Disagreement between runs is its own verdict: a case that is
+ * CAUGHT twice and BLIND once has told you nothing about the fix and something important
+ * about the test.
+ *
+ * INCONCLUSIVE does not outvote a real result — an infra hiccup on run 2 should not erase
+ * a clean CAUGHT from runs 1 and 3 — but a CAUGHT/BLIND split is FLAKY, always.
+ */
+export function reduceRuns(results) {
+    if (results.length === 0) return { verdict: SKIPPED, reason: 'no runs' };
+    const decided = results.filter(r => r.verdict === CAUGHT || r.verdict === NON_DISCRIMINATING);
+    if (decided.length === 0) return results[0];
+
+    const distinct = new Set(decided.map(r => r.verdict));
+    if (distinct.size > 1) {
+        const tally = decided.map(r => r.verdict).join(', ');
+        return { verdict: FLAKY, reason: `runs disagreed: ${tally}` };
+    }
+    if (decided.length < results.length) {
+        const d = decided[0];
+        return { ...d, reason: `${d.reason} (${results.length - decided.length} of ${results.length} runs inconclusive)` };
+    }
+    return decided[0];
+}
+
+/**
+ * Commit-level roll-up. A commit is CAUGHT if ANY of its cases discriminates.
+ *
+ * BLIND requires that EVERY case actually RAN. A commit with one skipped case and three
+ * non-discriminating ones is INCONCLUSIVE, not BLIND — the skipped case might have been
+ * the discriminating one, and nothing here can know.
+ *
+ * Earned on a commit fixing a null-limit bug in a metering module. All four
+ * tests it shipped are `{ skip: SKIP }`, gated on TEST_DATABASE_URL, which the audit host
+ * did not set. The older cases in the same file ran and did not discriminate, so an
+ * earlier version of this function called the commit BLIND — on the strength of the tests
+ * that were NOT written for the bug, while the four that were sat unexecuted. Run the
+ * audit with a database and the same commit may well be CAUGHT.
+ *
+ * Same principle as everywhere else here: ambiguity resolves AWAY from BLIND.
+ */
+export function rollUp(caseVerdicts) {
+    if (caseVerdicts.length === 0) return SKIPPED;
+    const has = v => caseVerdicts.some(c => c.verdict === v);
+    if (has(CAUGHT)) return CAUGHT;
+    if (has(FLAKY)) return FLAKY;
+    if (has(INCONCLUSIVE) || has(SKIPPED)) return INCONCLUSIVE;
+    if (caseVerdicts.every(c => c.verdict === NON_DISCRIMINATING)) return BLIND;
+    return INCONCLUSIVE;
+}

package/src/verify.mjs

@@ -0,0 +1,322 @@
+/**
+ * Orchestration: two arms, one commit.
+ *
+ *   ARM A   worktree @ FIX     + the fix's own test   -> must be GREEN, or there is no
+ *                                                        before/after to compare
+ *   ARM B   worktree @ PARENT  + the fix's test TRANSPLANTED onto the old source
+ *
+ * The transplant is the whole idea. You do NOT run the parent's tests — the parent does
+ * not have this test. You take the new test and ask it about the old code.
+ */
+
+import path from 'node:path';
+import { git, ensureWorktree, linkDependencies, linkEnvFiles, transplant } from './worktree.mjs';
+import { proveIdentity } from './identity.mjs';
+import { nodeTest } from './runner.mjs';
+import { analyseCase } from './assertions.mjs';
+import { vitest, jest } from './runner-json.mjs';
+import { selectRunner } from './select-runner.mjs';
+
+const RUNNERS = { node: nodeTest, vitest, jest };
+import { classify, reduceRuns, rollUp, isDisagreement, BLIND, NON_DISCRIMINATING, SKIPPED, INCONCLUSIVE } from './verdict.mjs';
+
+/**
+ * Documentation, and nothing else, is "not source".
+ *
+ * This used to be an ALLOWLIST of `.js/.ts/.tsx/.mjs`, and it made the tool decline the
+ * one kind of change it should be best at judging. A real PR wired a mutation-testing
+ * gate: it changed a tool config and a CI workflow, and shipped a test asserting that
+ * wiring. Zero JS changed, so the commit read as "test-only — no source change to be
+ * blind to" and got no verdict.
+ *
+ * That is backwards. A guard that is installed but wired to nothing is the dominant defect
+ * class in many repos — three instances found in one afternoon — and the test proving a
+ * gate is armed is precisely a test that should be shown to fail without the wiring.
+ * Config, CI YAML and shell ARE the source for those.
+ *
+ * So: deny-list the docs, accept the rest. A commit that changes only Markdown genuinely
+ * has nothing to be blind to; everything else might.
+ */
+const DOC_RE = /\.(md|mdx|txt|rst|adoc)$/i;
+
+/**
+ * Files no unit test can exercise, however good the suite is.
+ *
+ * A `fix(ios):` commit repairing an aborted CocoaPods install came back as a still-open
+ * BLIND. It is not a finding. A dependency-resolution failure is caught by a BUILD, and
+ * asking whether a unit test would have caught it is a category error. Reporting it as a gap teaches the reader that the tool does not know
+ * what a test is for.
+ *
+ * Deliberately narrow: only manifests and project files for toolchains that build rather
+ * than run. A .json or .yml can absolutely be under test — a CI-wiring test asserts a
+ * workflow file — so those are NOT here.
+ */
+const BUILD_ONLY_RE = /(^|\/)(Podfile(\.lock)?|Gemfile(\.lock)?|Cartfile.*|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|.*\.pbxproj|.*\.xcworkspacedata|.*\.xcscheme|.*\.gradle(\.kts)?|gradle\.properties|.*\.plist|.*\.podspec|.*\.lock)$/i;
+
+/**
+ * KNOWN LIMIT, stated rather than papered over: build-time JAVASCRIPT is not detectable
+ * by filename. One such commit changed `apps/mobile/plugins/withModularHeaders.js` — an
+ * Expo config plugin that runs at BUILD time, spelled exactly like runtime source. Webpack/vite/rollup configs and codegen
+ * scripts are the same shape.
+ *
+ * A heuristic wide enough to catch those (path contains "plugins", "scripts", "config")
+ * would also exclude real application code, and a FALSE EXCLUSION is worse than a false
+ * inclusion here: it hides a finding silently, where a category error is at least visible
+ * and arguable. So these reach a verdict and need human triage. The audit's subject
+ * filter catches most of them in practice, because they are usually scoped fix(ios),
+ * fix(build) or similar.
+ */
+
+/**
+ * What counts as a test file.
+ *
+ * TWO independent signals, because projects pick one or the other and a tool that demands
+ * both measures nothing:
+ *
+ *   1. a `.test.` / `.spec.` suffix anywhere      (most application repos)
+ *   2. living under a test directory              (undici, node core, most library repos)
+ *
+ * This used to require BOTH — a file under `tests/` AND a `.test.` suffix. Run against
+ * nodejs/undici, whose tests are `test/client-request.js` with no suffix, the tool
+ * reported "284 commits matched, 0 ship both a test and a source change" and produced an
+ * entirely empty audit. Not a wrong answer: NO answer, on a repo with 261 fix commits
+ * that ship tests.
+ *
+ * Found the first time it was pointed at a codebase its author did not write, which is
+ * the whole argument for doing that before believing any number it prints.
+ */
+const TEST_DIR_RE = /(^|\/)(tests?|__tests__|spec|specs)\//i;
+const TEST_SUFFIX_RE = /\.(test|spec)\.(m?[jt]sx?)$/i;
+const CODE_RE = /\.(m?[jt]sx?)$/i;
+const TEST_RE = (f) => CODE_RE.test(f) && (TEST_SUFFIX_RE.test(f) || TEST_DIR_RE.test(f));
+
+/**
+ * IS THIS A REPAIR, OR IS IT NEW CODE? — and why the answer changes what CAUGHT means.
+ *
+ * On a BUG FIX the base is the broken code, so a test that fails there genuinely
+ * discriminates: it would have caught the bug. That is the case this tool was built for.
+ *
+ * On a FEATURE the base is code where the thing does not exist yet. Essentially ANY test
+ * touching the new code fails there — the import is missing, the field is absent, a count
+ * is zero. `expected 0 to be greater than 0` is a real AssertionError, correctly
+ * classified, and says nothing whatever about whether the test is well aimed. A test
+ * asserting `expect(1).toBe(1)` in the same file would NOT have been CAUGHT; essentially
+ * any test reading the new field would. The signal comes from the field's existence, not
+ * from the test's design.
+ *
+ * This is the mirror of the INCONCLUSIVE rule. That one says a red test that never RAN
+ * proves nothing; this one says a red test that ran against ABSENT CODE proves nearly as
+ * little. Counting them together lets the headline drift upward for free on a
+ * feature-heavy week, and a number that drifts for free is one people stop reading.
+ *
+ * MEASURED, because both signals are proxies and only one is any good:
+ *   conventional prefix   1,213 fix / 988 feat in one real corpus — used consistently
+ *   source additions-only  9 of 28 feat commits, but also 1 of 35 fix commits —
+ *                          specific, not sensitive; a supporting hint, never the verdict
+ *
+ * So this labels the CLAIM and never silently reclassifies a verdict. CAUGHT on a feature
+ * is still CAUGHT — it just does not get to say "this would have caught the bug", because
+ * there was no bug.
+ */
+export function commitKind(subject, sourceAddedOnly) {
+    const m = String(subject).match(/^\s*([a-z]+)\s*(\([^)]*\))?\s*!?:/i);
+    const prefix = m ? m[1].toLowerCase() : null;
+    if (prefix === 'fix' || prefix === 'bug' || prefix === 'perf') {
+        // A fix that only ADDED source is worth flagging: its test may be reading
+        // something that simply was not there, exactly like a feature's.
+        return { kind: 'fix', newCode: !!sourceAddedOnly, prefix };
+    }
+    if (prefix === 'feat' || prefix === 'feature') return { kind: 'feature', newCode: true, prefix };
+    if (prefix) return { kind: 'other', newCode: !!sourceAddedOnly, prefix };
+    return { kind: 'unknown', newCode: !!sourceAddedOnly, prefix: null };
+}
+
+/**
+ * `withDiffStat` is OFF by default, and that default is load-bearing.
+ *
+ * The additions-only signal needs `git show --numstat` — one subprocess per commit. The
+ * audit calls commitInfo on EVERY candidate just to test eligibility (1,178 of them on one
+ * real corpus), so computing it unconditionally pushed the selection pass past 70 minutes
+ * BEFORE a single commit was judged. Measured, not estimated: that run was killed at 72.
+ *
+ * Only the commits actually verified need it, so verifyCommit asks and the eligibility
+ * pass does not. A regression introduced by the fix for issue #3, and caught by noticing a
+ * run sit in "selecting commits" for over an hour rather than by any test.
+ */
+export async function commitInfo(repo, sha, against = null, withDiffStat = false) {
+    const out = await git(repo, ['show', '--no-patch', '--format=%H%n%s%n%ad', '--date=short', sha]);
+    const [full, subject, date] = out.trim().split('\n');
+    // With a base, the changed set is the WHOLE branch, not just the tip commit — a PR's
+    // test may have arrived in commit 1 and its source change in commit 3.
+    const files = against
+        ? (await git(repo, ['diff', '--name-only', `${(await git(repo, ['merge-base', against, sha])).trim()}...${sha}`])).trim().split('\n').filter(Boolean)
+        : (await git(repo, ['show', '--name-only', '--format=', sha])).trim().split('\n').filter(Boolean);
+    // Deletions in non-test source: a repair usually changes lines, new code only adds.
+    const numstat = !withDiffStat ? '' : against
+        ? await git(repo, ['diff', '--numstat', `${(await git(repo, ['merge-base', against, sha])).trim()}...${sha}`])
+        : await git(repo, ['show', '--numstat', '--format=', sha]);
+    let srcDeletions = 0;
+    for (const line of numstat.trim().split('\n')) {
+        const [, del, file] = line.split(/\t/).length === 3 ? ['', ...line.split(/\t/).slice(1)] : [];
+        const parts = line.split(/\t/);
+        if (parts.length !== 3) continue;
+        const [, d, f] = parts;
+        if (TEST_RE(f) || DOC_RE.test(f)) continue;
+        if (/^\d+$/.test(d)) srcDeletions += Number(d);
+    }
+    const kindInfo = commitKind(subject, srcDeletions === 0);
+
+    return {
+        sha: full, short: full.slice(0, 8), subject, date,
+        ...kindInfo, srcDeletions,
+        files,
+        testFiles: files.filter(f => TEST_RE(f)),
+        sourceFiles: files.filter(f => !TEST_RE(f) && !DOC_RE.test(f)),
+    };
+}
+
+/**
+ * `against` turns this from a commit check into a PR check, and the distinction matters.
+ *
+ * By default the "broken" side is the commit's own parent — right for auditing history,
+ * where each fix is judged against the bug it fixed.
+ *
+ * A PR is different. A real PR landed a follow-up commit whose parent ALREADY contained
+ * the change under test — so commit-vs-parent compares the branch to itself and every
+ * case reads non-discriminating, and a sound PR looks unproven. The question a PR gate asks is
+ * "does this test fail WITHOUT THIS BRANCH", so the base is the MERGE BASE of the branch
+ * and its target, never the target's tip: develop moves, and diffing against a moved tip
+ * drags in everyone else's changes and attributes them here.
+ */
+export async function verifyCommit({ repo, workDir, sha, against = null, runs = 1, timeoutMs = 120_000, onStep = () => {} }) {
+    const info = await commitInfo(repo, sha, against, true);
+    const result = { ...info, cases: [], verdict: SKIPPED, note: null };
+
+    if (info.testFiles.length === 0) { result.note = 'no test file in the commit'; return result; }
+    if (info.sourceFiles.length === 0) { result.note = 'test-only commit — no source change to be blind to'; return result; }
+    if (info.sourceFiles.every(f => BUILD_ONLY_RE.test(f))) {
+        result.note = 'build-only change (lockfiles / project files) — a build catches this, not a unit test';
+        return result;
+    }
+
+    const parent = against
+        ? (await git(repo, ['merge-base', against, sha])).trim()
+        : (await git(repo, ['rev-parse', `${sha}^`])).trim();
+
+    // --- ARM A -------------------------------------------------------------------------
+    onStep('arm A');
+    const fixDir = await ensureWorktree(repo, workDir, 'fix', sha);
+    await linkDependencies(repo, fixDir);
+    await linkEnvFiles(repo, fixDir);
+
+    // --- ARM B -------------------------------------------------------------------------
+    onStep('arm B');
+    const parentDir = await ensureWorktree(repo, workDir, 'parent', parent);
+    await linkDependencies(repo, parentDir);
+    await linkEnvFiles(repo, parentDir);
+
+    const perFile = [];
+    for (const rel of info.testFiles) {
+        // Chosen from the FIX worktree: the parent may predate the config file entirely,
+        // and the question is which runner the test was written for.
+        const { flavour, pkgDir } = await selectRunner(fixDir, rel);
+        const runner = RUNNERS[flavour];
+        const opts = { relTestPath: rel, pkgDir, timeoutMs };
+
+        const a = await runner.execute({ worktreeDir: fixDir, ...opts });
+        if (!a.ok) { perFile.push({ file: rel, runner: flavour, pkgDir, skip: `arm A did not run (${flavour}): ${a.loadFailure}` }); continue; }
+
+        const dest = await transplant(repo, sha, rel, parentDir);
+        const identity = await proveIdentity({ worktreeRoot: parentDir, repoRoot: repo, testFilePath: dest });
+
+        const runsOut = [];
+        for (let i = 0; i < runs; i++) {
+            const b = await runner.execute({ worktreeDir: parentDir, ...opts });
+            runsOut.push({ b, identity });
+        }
+        perFile.push({ file: rel, runner: flavour, pkgDir, armA: a, runs: runsOut, identity });
+    }
+
+    // --- verdicts ----------------------------------------------------------------------
+    // The fix's own copy of each test file, read ONCE per file rather than once per case:
+    // the assertion analysis needs the source, and a 40-case file would otherwise re-read
+    // it forty times.
+    const sourceOf = new Map();
+    for (const f of perFile) {
+        if (f.skip) continue;
+        try { sourceOf.set(f.file, await git(repo, ['show', `${sha}:${f.file}`])); } catch { /* unreadable */ }
+    }
+
+    for (const f of perFile) {
+        if (f.skip) { result.cases.push({ file: f.file, name: '(file)', verdict: INCONCLUSIVE, reason: f.skip }); continue; }
+        for (const aCase of f.armA.cases) {
+            const perRun = f.runs.map(({ b, identity }) => {
+                if (!b.ok) return { verdict: INCONCLUSIVE, reason: `did not run on the parent: ${b.loadFailure}` };
+                const bCase = b.cases.find(c => c.name === aCase.name) || null;
+                return classify({ armA: aCase, armB: bCase, identity });
+            });
+            const final = reduceRuns(perRun);
+            // WHY is this case weak — attached only where the answer is useful. A CAUGHT
+            // case needs no explanation (it did its job) and an INCONCLUSIVE one already
+            // carries its reason, so the note goes on the cases a reader would otherwise
+            // have to open the file to understand.
+            let why = null;
+            const src = sourceOf.get(f.file);
+            if (src && final.verdict === NON_DISCRIMINATING) {
+                const a = analyseCase(src, aCase.name);
+                if (a.verdict === 'weak' && a.findings.length) why = a.findings[0].note;
+                else if (a.verdict === 'suspect' && a.findings.length) why = `${a.findings[0].note} — but it also asserts an exact value, so it may still be sound`;
+                else if (a.verdict === 'strong') why = 'asserts an exact expected value — most likely a deliberate regression guard';
+            }
+            result.cases.push({ file: f.file, name: aCase.name, ...final, ...(why ? { why } : {}) });
+        }
+    }
+    result.verdict = rollUp(result.cases);
+
+    // --- ARM C: is this BLIND finding still open? ---------------------------------------
+    if (result.verdict === BLIND) {
+        result.stillOpen = await armC({ repo, parentDir, perFile, timeoutMs });
+    }
+    return result;
+}
+
+/**
+ * ARM C — the current test against the historical bug.
+ *
+ * WHY THIS EXISTS, and it is the most important caveat in the tool.
+ *
+ * Arms A and B answer "did the test SHIPPED WITH THIS COMMIT catch its own bug". That is a
+ * fact about the past and it stays true forever. It does NOT mean there is a gap today:
+ * the repo may have repaired it since, and a BLIND verdict reported as an open defect is a
+ * redundant ticket handed to a colleague.
+ *
+ * Earned by doing exactly that. A commit shipped a property-based test whose loop stepped
+ * over the very date its own comment named as the bug, so it could not fail on the code it
+ * was written for. True — and the one-character fix was recommended to a colleague who was
+ * about to open a PR for it. The stride had already been corrected three months earlier,
+ * by MUTATION TESTING, which deleted the loop body and saw nothing fail. A different
+ * instrument had found the same defect from the opposite direction.
+ *
+ * So: take the CURRENT version of the test file, put it on the parent's broken code, and
+ * run it. If it fails now, the gap was repaired and the finding is history, not a ticket.
+ */
+async function armC({ repo, parentDir, perFile, timeoutMs }) {
+    const files = perFile.filter(f => !f.skip);
+    if (files.length === 0) return { status: 'unknown', reason: 'no runnable test file' };
+
+    for (const f of files) {
+        let dest;
+        try { dest = await transplant(repo, 'HEAD', f.file, parentDir); }
+        catch { return { status: 'unknown', reason: `${f.file} does not exist at HEAD (renamed or deleted)` }; }
+
+        const runner = RUNNERS[f.runner] || nodeTest;
+        const r = await runner.execute({ worktreeDir: parentDir, relTestPath: f.file, pkgDir: f.pkgDir, timeoutMs });
+        if (!r.ok) return { status: 'unknown', reason: `current test could not run on the parent: ${r.loadFailure}` };
+
+        const killer = r.cases.find(c => isDisagreement(c));
+        if (killer) {
+            return { status: 'repaired', reason: `the CURRENT "${killer.name}" fails on this bug — the gap was closed after this commit`, by: killer.name, file: f.file };
+        }
+    }
+    return { status: 'open', reason: 'even the CURRENT tests are green on this bug — still unguarded today' };
+}