testguard-cli 0.6.0 → 0.8.0

package/spec/schemas/status.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:guard-spec:v1:status",
-  "title": "Guard spec v1 \u2014 status",
+  "$id": "urn:claimspec:v1:status",
+  "title": "claimspec v1 \u2014 status",
   "description": "The single machine-readable answer to 'where is this project and what should happen next'. Every human rendering (CLI text, agent brief, skill instructions) derives from this document so they cannot disagree. Computed from the claims file, the evidence, the baseline and the current working tree; never from a cached verdict alone.",
   "type": "object",
   "required": [
@@ -20,10 +20,10 @@
       "const": 1
     },
     "tool": {
-      "$ref": "urn:guard-spec:v1:common#/$defs/tool"
+      "$ref": "urn:claimspec:v1:common#/$defs/tool"
     },
     "generatedAt": {
-      "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime"
+      "$ref": "urn:claimspec:v1:common#/$defs/isoDateTime"
     },
     "state": {
       "description": "no-claims: no claims file. unclaimed-changes: the change measured against a reference touches source files that carry no claim and no excusing ignore entry (only computed when a reference is known; it precedes every evidence state because the claim is written before more code). unprobed: claims but no confirmed evidence. evidence-stale: evidence exists but a claim, fault, target or defender changed since. provisional-only: only sub-N evidence exists. unproven: current evidence has findings not covered by the baseline. clean: every finding is killed or baselined.",
@@ -69,7 +69,7 @@
         },
         "file": {
           "description": "For claim (and for scaffold when a change is known): the first uncovered changed file the action is about.",
-          "$ref": "urn:guard-spec:v1:common#/$defs/repoPath"
+          "$ref": "urn:claimspec:v1:common#/$defs/repoPath"
         },
         "target": {
           "description": "For write-test / review-fault-change: the finding the action is about.",
@@ -80,16 +80,16 @@
           ],
           "properties": {
             "claimId": {
-              "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+              "$ref": "urn:claimspec:v1:common#/$defs/identifier"
             },
             "subjectId": {
-              "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+              "$ref": "urn:claimspec:v1:common#/$defs/identifier"
             },
             "file": {
-              "$ref": "urn:guard-spec:v1:common#/$defs/repoPath"
+              "$ref": "urn:claimspec:v1:common#/$defs/repoPath"
             },
             "verdict": {
-              "$ref": "urn:guard-spec:v1:common#/$defs/verdict"
+              "$ref": "urn:claimspec:v1:common#/$defs/verdict"
             }
           },
           "additionalProperties": false
@@ -173,16 +173,16 @@
         ],
         "properties": {
           "claimId": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+            "$ref": "urn:claimspec:v1:common#/$defs/identifier"
           },
           "subjectId": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+            "$ref": "urn:claimspec:v1:common#/$defs/identifier"
           },
           "previousVerdict": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/verdict"
+            "$ref": "urn:claimspec:v1:common#/$defs/verdict"
           },
           "file": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/repoPath"
+            "$ref": "urn:claimspec:v1:common#/$defs/repoPath"
           }
         },
         "additionalProperties": false
@@ -204,26 +204,26 @@
         ],
         "properties": {
           "fingerprint": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/sha256"
+            "$ref": "urn:claimspec:v1:common#/$defs/sha256"
           },
           "claimId": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+            "$ref": "urn:claimspec:v1:common#/$defs/identifier"
           },
           "subjectId": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/identifier"
+            "$ref": "urn:claimspec:v1:common#/$defs/identifier"
           },
           "verdict": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/verdict"
+            "$ref": "urn:claimspec:v1:common#/$defs/verdict"
           },
           "reason": {
             "type": "string",
             "maxLength": 256
           },
           "severity": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/severity"
+            "$ref": "urn:claimspec:v1:common#/$defs/severity"
           },
           "file": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/repoPath"
+            "$ref": "urn:claimspec:v1:common#/$defs/repoPath"
           },
           "rank": {
             "type": "number"
@@ -255,7 +255,7 @@
           "maxLength": 256
         },
         "base": {
-          "$ref": "urn:guard-spec:v1:common#/$defs/gitSha"
+          "$ref": "urn:claimspec:v1:common#/$defs/gitSha"
         },
         "includeDirty": {
           "type": "boolean"
@@ -275,19 +275,19 @@
         "uncovered": {
           "type": "array",
           "items": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/uncoveredFile"
+            "$ref": "urn:claimspec:v1:common#/$defs/uncoveredFile"
           }
         },
         "reliedOn": {
           "type": "array",
           "items": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/ignoreReliance"
+            "$ref": "urn:claimspec:v1:common#/$defs/ignoreReliance"
           }
         },
         "expired": {
           "type": "array",
           "items": {
-            "$ref": "urn:guard-spec:v1:common#/$defs/ignoreReliance"
+            "$ref": "urn:claimspec:v1:common#/$defs/ignoreReliance"
           }
         }
       },
@@ -323,11 +323,11 @@
     },
     "evidenceHead": {
       "description": "The commit the evidence describes (its snapshot when the working tree was probed). Present whenever evidence was read.",
-      "$ref": "urn:guard-spec:v1:common#/$defs/gitSha"
+      "$ref": "urn:claimspec:v1:common#/$defs/gitSha"
     },
     "head": {
       "description": "HEAD of the working tree the status was computed in, when resolvable. Differs from evidenceHead when the evidence came from elsewhere.",
-      "$ref": "urn:guard-spec:v1:common#/$defs/gitSha"
+      "$ref": "urn:claimspec:v1:common#/$defs/gitSha"
     }
   },
   "additionalProperties": false

package/src/cli.mjs

@@ -4,6 +4,7 @@ import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ClaimsError } from './claims/load.mjs';
 import { PreconditionError } from './probe/worktree.mjs';
+import { RUNNER_NAMES } from './probe/runners/index.mjs';
 import { GitError } from './git.mjs';
 import { SpecDocError } from './evidence/writer.mjs';
 import { probeCommand } from './commands/probe.mjs';
@@ -48,12 +49,22 @@ probe
   --include-dirty      probe the working tree (a snapshot commit) instead of HEAD; uncommitted tests count
                        (without it, a dirty defender/target with the implicit HEAD is refused: the silent-mismatch trap)
   --verbose            also print each killed fault (default: only unproven ones, plus a count)
+  --cost               (probe, claims) report what the defenders cost, per claim and per defender file
+  --progress <mode>    auto|tty|plain|ndjson|none. auto rewrites one line at a terminal and prints
+                       append-only lines everywhere else, so a redirected log and CI see progress
+                       instead of twenty silent minutes. Always on stderr; ndjson also streams verdicts
                        --confirm below 3 is PROVISIONAL: verdicts print with "?", evidence goes to .testguard/evidence-provisional.json
-  --runner <name>      vitest | jest | playwright | auto (default: auto — first of vitest, jest that resolves; a defender under
-                       playwright's testDir always runs under playwright, whatever the project runner)
+  --runner <name>      vitest | jest | playwright | python | pytest | unittest | auto
+                       (default: auto — first of vitest, jest, python that resolves. A defender under playwright's testDir
+                       always runs under playwright, and a .py defender always under python, whatever the project runner.
+                       python picks pytest when the interpreter can import it and stdlib unittest otherwise; pytest and
+                       unittest pin that choice and fail rather than fall back. The engine that ran is what the evidence records.)
   --runner-cmd "<cmd>" custom runner; must contain {files} and {out}, e.g. "pnpm vitest run {files} --reporter=json --outputFile={out}"
   --node-modules <dir> node_modules to link into the scratch worktree (or TESTGUARD_NODE_MODULES)
-  --serial             run one test file at a time (vitest --no-file-parallelism, jest --runInBand, playwright --workers=1);
+  --python <path>      Python interpreter for .py defenders (or TESTGUARD_PYTHON; default: $VIRTUAL_ENV, then the project's
+                       .venv/venv, then python3 on PATH). Resolved against your working tree, never the scratch worktree.
+  --serial             run one test file at a time (vitest --no-file-parallelism, jest --runInBand, playwright --workers=1,
+                       pytest -p no:xdist);
                        use it when another test runner is already running — probe warns and records the contention either way
   --in-place           mutate the working tree instead of a scratch worktree
   --no-escalate        do not re-run survivors against the whole suite
@@ -93,6 +104,7 @@ init       --force (replace an existing skill file)  --here (keep the agent laye
            --mcp             print the MCP server config for Claude Code, Cursor and Codex (printed, never written: a harness config is yours)
 every command accepts --json; probe/baseline emit the status document plus their own result
 claims     --json
+           --cost            what the last probe spent, per claim and per defender file, read back from the recorded run durations. Names the files more than one claim pays for, which is where a slow gate comes from
            --since <ref>     report every claim and fault that existed at <ref> and does not now; a claim entry in testguard.ignore.json (with a reason) excuses one. exit 1 on any unexcused removal
 baseline   --evidence <path>  --out <path>  --allow-provisional (freeze unconfirmed evidence; normally refused)
            --restamp          move head to the commit of a later CLEAN probe that reproduced the same fingerprints
@@ -139,6 +151,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         here: { type: 'boolean', default: false },
         verbose: { type: 'boolean', default: false },
         'runner-cmd': { type: 'string' },
+        python: { type: 'string' },
         runner: { type: 'string', default: 'auto' },
         'node-modules': { type: 'string' },
         'in-place': { type: 'boolean', default: false },
@@ -148,6 +161,8 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         json: { type: 'boolean', default: false },
         text: { type: 'boolean', default: false },
         markdown: { type: 'boolean', default: false },
+        cost: { type: 'boolean', default: false },
+        progress: { type: 'string' },
         help: { type: 'boolean', short: 'h', default: false },
         version: { type: 'boolean', short: 'v', default: false },
       },
@@ -173,8 +188,8 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     io.err(USAGE);
     return 3;
   }
-  if (!['vitest', 'jest', 'playwright', 'auto'].includes(values.runner)) {
-    io.err('--runner must be vitest, jest, playwright or auto');
+  if (![...RUNNER_NAMES, 'auto'].includes(values.runner)) {
+    io.err(`--runner must be one of ${RUNNER_NAMES.join(', ')} or auto`);
     return 3;
   }
   if (!['critical', 'high', 'medium', 'low'].includes(values.severity)) {

package/src/commands/claims.mjs

@@ -6,6 +6,9 @@ import { discoverDefendersDetailed } from '../probe/discover.mjs';
 import { classifyDefenders } from '../probe/mocks.mjs';
 import { computeRemovedClaims, renderRemoved } from '../claims/removed.mjs';
 import { evidencePath } from './probe.mjs';
+import { costReport, renderCost } from '../probe/cost.mjs';
+import { readSpecDoc } from '../evidence/writer.mjs';
+import { existsSync } from 'node:fs';
 
 export async function claimsCommand({ projectDir, values, version }, io) {
   const path = values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir);
@@ -19,8 +22,16 @@ export async function claimsCommand({ projectDir, values, version }, io) {
     ? computeRemovedClaims({ projectDir, ref: values.since, claimsPath: path, current: claims, ignorePath: values.ignore ? resolve(values.ignore) : undefined, evidencePath: evidencePath(projectDir), toolVersion: version })
     : undefined;
 
+  // Cost is read back out of evidence the probe already wrote; it never runs a test.
+  let cost;
+  if (values.cost) {
+    const ev = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
+    cost = existsSync(ev) ? costReport(readSpecDoc('evidence', ev).records) : undefined;
+    if (!cost && !values.json) io.err(`no evidence at ${ev} — run \`testguard probe\` first; cost is derived from the run durations it records`);
+  }
+
   if (values.json) {
-    io.out(JSON.stringify({ path, claims, annotations, drift, ...(removed ? { removed } : {}) }, null, 2));
+    io.out(JSON.stringify({ path, claims, annotations, drift, ...(removed ? { removed } : {}), ...(cost ? { cost } : {}) }, null, 2));
   } else {
     const annotated = new Set(drift.annotated);
     io.out(`${claims.claims.length} claims in ${path} — ${annotated.size} carry a @claim annotation in source (test files are not scanned)`);
@@ -44,7 +55,12 @@ export async function claimsCommand({ projectDir, values, version }, io) {
     }
     if (signalLines.length) io.out('');
     for (const s of signalLines) {
-      if (s.signal === 'mocked-never-asserted') io.out(`MOCKED-NEVER-ASSERTED  ${s.file} mocks ${s.target} and never asserts on it (${s.claim}) — assert on the mocked call, drive the real module, or annotate the mock \`// unasserted: <why>\``);
+      // The annotation's comment marker is the probed file's, not JavaScript's.
+      const marker = s.file.endsWith('.py') ? '#' : '//';
+      if (s.signal === 'mocked-never-asserted') io.out(`MOCKED-NEVER-ASSERTED  ${s.file} mocks ${s.target} and never asserts on it (${s.claim}) — assert on the mocked call, drive the real module, or annotate the mock \`${marker} unasserted: <why>\``);
+      // An attribute patch does not remove a defender; saying it "mocks" the
+      // module would tell the author the opposite of what happened.
+      else if (s.signal === 'target-attribute-patched') io.out(`attribute-patched  ${s.file} defends ${s.target} but replaces ${s.reason} (${s.claim}) — a fault in those attributes is where it is least likely to notice`);
       else io.out(`unasserted (annotated)  ${s.file} mocks ${s.target}: ${s.reason} (${s.claim})`);
     }
     if (drift.undeclared.length || drift.stale.length) io.out('');
@@ -54,6 +70,10 @@ export async function claimsCommand({ projectDir, values, version }, io) {
       io.out('');
       io.out(renderRemoved(removed));
     }
+    if (cost) {
+      io.out('');
+      io.out(renderCost(cost));
+    }
   }
   return drift.undeclared.length || drift.stale.length || (removed?.removed.length ?? 0) > 0 ? 1 : 0;
 }

package/src/commands/probe.mjs

@@ -7,6 +7,8 @@ import { gate } from '../baseline/baseline.mjs';
 import { renderRecord, renderSummary, sortForReport, PROVISIONAL_WARNING } from '../render.mjs';
 import { computeStatus } from '../status/status.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
+import { costReport, renderCost } from '../probe/cost.mjs';
+import { progressMode, stageReporter, clearStageLine, recordEvent, isProgressMode, progressStream } from '../probe/progress.mjs';
 export const provisionalEvidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence-provisional.json');
 
 export const evidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence.json');
@@ -19,6 +21,14 @@ export async function probeCommand({ projectDir, values, version }, io) {
     io.err('--confirm must be a positive integer and --budget at least 1000');
     return 3;
   }
+  if (values.progress && !isProgressMode(values.progress)) {
+    io.err(`--progress must be one of auto, tty, plain, ndjson, none (got ${values.progress})`);
+    return 3;
+  }
+  // Progress always goes to stderr, so --json keeps stdout parseable.
+  const progress = progressMode({ explicit: values.progress, isTTY: process.stderr.isTTY, quiet: values.quiet, json: values.json });
+  const progressTo = progressStream(process);
+  const stageOut = stageReporter(progress, (s) => progressTo.write(s));
   const claims = loadClaims(values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir));
   if (claims.claims.length === 0) {
     io.err('claims file declares no claims; nothing to verify');
@@ -50,13 +60,18 @@ export async function probeCommand({ projectDir, values, version }, io) {
     runnerCommand: values['runner-cmd'],
     runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    python: values.python ? resolve(values.python) : undefined,
     only,
     escalate: !values['no-escalate'],
     toolVersion: version,
     includeDirty: values['include-dirty'],
-    onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ claimId, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${claimId}/${faultId} ${stage} ${i}/${n}`) : undefined,
-    onProgress: values.quiet || values.json ? undefined : (r) => {
-      if (process.stderr.isTTY) process.stderr.write('\r\x1b[K');
+    onStage: stageOut,
+    onProgress: (r) => {
+      // ndjson streams verdicts as they land; a watcher sees them without
+      // waiting for the document at the end.
+      if (progress === 'ndjson') progressTo.write(recordEvent(r));
+      if (values.quiet || values.json) return;
+      progressTo.write(clearStageLine(progress));
       // The discovery note is a property of the claim, not of each fault: say it once.
       const firstOfClaim = !discoveryNoted.has(r.claim.id);
       if (r.defenders.discovered) discoveryNoted.add(r.claim.id);
@@ -68,7 +83,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
   const g = gate(evidence.records, baseline, { severityFloor: values.severity });
   if (values.json) {
     const status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: outPath }), io.err);
-    io.out(JSON.stringify({ ...status, run: { id: evidence.run.id, evidence: outPath, provisional, records: evidence.records.length, newSinceBaseline: g.new.length, exitCode: g.new.length > 0 ? 1 : 0 } }, null, 2));
+    io.out(JSON.stringify({ ...status, run: { id: evidence.run.id, evidence: outPath, provisional, records: evidence.records.length, newSinceBaseline: g.new.length, exitCode: g.new.length > 0 ? 1 : 0 }, ...(values.cost ? { cost: costReport(evidence.records) } : {}) }, null, 2));
     return g.new.length > 0 ? 1 : 0;
   }
   if (!values.quiet && baseline) {
@@ -82,6 +97,11 @@ export async function probeCommand({ projectDir, values, version }, io) {
     if (killed) io.out(`  ${killed} killed (not listed; --verbose to see them)`);
   }
   io.out(renderSummary(evidence.records, evidence.run) + (baseline ? ` ${g.new.length} new since baseline, ${g.baselined.length} baselined.` : ' No baseline.'));
+  if (values.cost) {
+    io.out('');
+    io.out(renderCost(costReport(evidence.records)));
+    io.out('');
+  }
   io.out(`evidence: ${outPath}${only ? ` (partial: --claim ${only.join(',')}; not the canonical evidence file)` : provisional ? ' (provisional; not the canonical evidence file)' : ''}`);
   if (provisional && !values.quiet) io.err(PROVISIONAL_WARNING(confirmRuns));
   return g.new.length > 0 ? 1 : 0;

package/src/commands/replay.mjs

@@ -50,7 +50,7 @@ export async function replayCommand({ projectDir, values, version }, io) {
     io.out(renderReplay(doc));
     io.out('');
     for (const [cls, b] of Object.entries(calibration.buckets).sort((a, b2) => b2[1].n - a[1].n)) {
-      io.out(`  ${cls.padEnd(22)} blind ${String(b.positives).padStart(3)}/${String(b.n).padEnd(3)}  p=${b.p.toFixed(2)}  ci [${b.ci[0].toFixed(2)}, ${b.ci[1].toFixed(2)}]`);
+      io.out(`  ${cls.padEnd(22)} missed ${String(b.positives).padStart(3)}/${String(b.n).padEnd(3)}  p=${b.p === null ? ' n/a' : b.p.toFixed(2)}  ci [${b.ci[0].toFixed(2)}, ${b.ci[1].toFixed(2)}]`);
     }
     if (Object.keys(calibration.buckets).length === 0) io.out('  no measurable bug in this range: nothing to calibrate from yet.');
     io.out('');

package/src/gate/changed.mjs

@@ -5,6 +5,7 @@ import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { readSpecDoc } from '../evidence/writer.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
+import { IS_PY_TEST } from '../probe/pyimports.mjs';
 import { globToRegExp } from '../util/glob.mjs';
 
 /**
@@ -20,8 +21,14 @@ import { globToRegExp } from '../util/glob.mjs';
  * the smallest unit the rest of the contract already understands.
  */
 
-export const SOURCE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx']);
+// `.py` belongs here for the same reason every other extension does: a file
+// the gate does not recognise as source is excluded as `non-source`, which
+// means a changed Python file could never be reported as uncovered and the
+// gate would pass while saying nothing.
+export const SOURCE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py']);
 const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+// Python names tests by file, not by a dotted suffix: `test_foo.py`, `foo_test.py`.
+const isTestFile = (f) => TEST_RE.test(f) || IS_PY_TEST.test(f);
 
 /** Files that are source by extension but never carry claims. Printed by --explain. */
 export const DEFAULT_EXCLUDES = Object.freeze([
@@ -163,7 +170,7 @@ export function computeChangedGate({ projectDir, ref, includeDirty = false, excl
     const dx = defaultExcludes.find((x) => x.re.test(file));
     if (dx) { excluded.push({ file, by: `default:${dx.glob}` }); continue; }
 
-    const isTest = TEST_RE.test(file);
+    const isTest = isTestFile(file);
     if (faultFiles.has(file)) { covered.push({ file, by: 'fault', claimIds: faultFiles.get(file) }); continue; }
     if (isTest && defenderFiles.has(file)) { covered.push({ file, by: 'defender', claimIds: defenderFiles.get(file) }); continue; }
     const active = pathEntries.find((p) => !p.expired && p.re.test(file));

package/src/probe/attribution.mjs

@@ -0,0 +1,123 @@
+/**
+ * The decisions escalation and flake measurement make, as pure functions.
+ *
+ * These used to live inline in `probeOne`, which meant the only thing that
+ * could falsify them was a full fixture probe — a 50-second acceptance test
+ * standing in for a rule you can state in three lines. `classify()` has always
+ * been pure for this reason: the order of its checks *is* the spec, and every
+ * branch is unit-testable without a runner. Same principle here.
+ *
+ * Nothing in this file runs a test, touches the filesystem, or knows what a
+ * worktree is. Everything it needs is passed in.
+ */
+
+const isKill = (r) => r.outcome === 'fail' && (r.assertionFailures ?? 0) > 0;
+
+/**
+ * Fold one escalation run into the running attribution state.
+ *
+ * A test is an undeclared killer only if it fails in **every** run: a single
+ * run cannot say, because a test that is flaky elsewhere in the suite would
+ * take the credit. So the killer set is an intersection, seeded by the first
+ * run rather than by the empty set.
+ *
+ * Once the intersection is empty no further run can name a killer, so the
+ * caller may stop early. Stopping can only fail to *name* a killer, never
+ * upgrade a verdict, which is the pessimistic side and therefore the safe one.
+ */
+export function foldEscalationRun(state, { run, failedTests }) {
+  const runs = [...state.runs, run];
+  const killers = state.killers === null ? new Set(failedTests) : new Set([...state.killers].filter((t) => failedTests.includes(t)));
+  return { runs, killers, stoppedEarly: killers.size === 0 ? 'no-common-failure' : undefined };
+}
+
+/** The initial attribution state, before any escalation run. */
+export const escalationStart = () => ({ runs: [], killers: null, stoppedEarly: undefined });
+
+/**
+ * What escalation concluded. `undeclaredKillers` is named only when a test
+ * failed in all N runs AND every run was a genuine kill (an assertion
+ * failure). A suite that errored or timed out proves nothing about the fault,
+ * so it never earns an attribution.
+ */
+export function escalationResult(state, confirmRuns) {
+  const complete = state.runs.length === confirmRuns;
+  const attributable = state.killers !== null && state.killers.size > 0 && complete && state.runs.every(isKill);
+  return {
+    escalated: true,
+    escalationRuns: state.runs,
+    ...(state.stoppedEarly ? { escalationStoppedEarly: state.stoppedEarly } : {}),
+    ...(attributable ? { reason: 'killed-by-undeclared-tests', undeclaredKillers: [...state.killers].sort() } : {}),
+  };
+}
+
+/**
+ * The defenders' flake rate on unmodified source.
+ *
+ * Only runs that **actually ran** carry information. A load error or a timeout
+ * measures the environment, not the suite's stability, and counting either as
+ * a "failure" would invent flakiness that was never observed. Returns
+ * `undefined` when nothing was measurable, so the caller omits the field
+ * rather than recording a rate of zero it cannot support.
+ */
+export function flakeRate(runs) {
+  const measured = runs.filter((r) => r.outcome === 'pass' || r.outcome === 'fail');
+  if (!measured.length) return undefined;
+  return { runs: measured.length, failures: measured.filter((r) => r.outcome === 'fail').length };
+}
+
+/**
+ * The tests that actually failed on the fault, by file. Only these are its
+ * killers; everything else in a run is noise for attribution purposes.
+ */
+export function killersFromRuns(probeRuns) {
+  return [...new Set(probeRuns.flatMap((r) => r.failedTests ?? []).map((t) => t.split('::')[0]).filter(Boolean))];
+}
+
+/**
+ * The `subject` of an evidence record. `contentHash` is what makes a fault edit
+ * visible: weakening a fault after it survived changes this hash, and `status`
+ * reports the change with the verdict the fault used to have. It is deliberately
+ * NOT part of the fingerprint — repairing a rotted anchor must not churn the
+ * baseline — which is exactly why it has to be recorded separately.
+ */
+export function subjectOf(fault, sha256) {
+  return {
+    kind: 'fault',
+    id: fault.id,
+    description: fault.description,
+    file: fault.file,
+    faultClass: fault.faultClass,
+    producedBy: fault.producedBy,
+    contentHash: sha256(`${fault.find}\n${fault.replace}`),
+  };
+}
+
+/**
+ * May a prior record stand in for this one, or must the fault be probed again?
+ *
+ * Same source, same defenders, same N — and the SAME FAULT. The last is not a
+ * refinement: a verdict is an answer about one specific `find`/`replace`, and
+ * once those change the old answer is not an answer to the new question.
+ * Without it, weakening a fault that survived keeps its old verdict, and
+ * repairing a rotted anchor keeps `unverifiable` — the evidence reporting a
+ * result that was never measured against the fault the file now contains.
+ * `status` flags the changed hash afterwards, but by then the evidence has
+ * already said something untrue.
+ *
+ * A prior that predates `contentHash` cannot be compared, so it is re-probed.
+ * The cost of re-measuring is a run; the cost of the other direction is a
+ * verdict nobody measured.
+ */
+export function isReusable(prior, current) {
+  if (!prior || !prior.subject?.contentHash) return false;
+  // A record that exists because the probe threw is a statement about the run,
+  // not about the code. Reusing it would make one disturbed run permanent.
+  if (prior.detail?.reason === 'probe-error') return false;
+  const same = (x, y) => JSON.stringify(x) === JSON.stringify(y);
+  return prior.inputs.targetHash === current.inputs.targetHash
+    && same(prior.inputs.defenderHashes, current.inputs.defenderHashes)
+    && same(prior.defenders.requested, current.requested)
+    && same(prior.defenders.resolved, current.resolved)
+    && prior.subject.contentHash === current.contentHash;
+}

package/src/probe/classify.mjs

@@ -6,8 +6,13 @@
  * encodes GATE-SEMANTICS.md: nothing to run → nocover; nothing to apply →
  * unverifiable; defenders not green → flaky-defender; then, and only then,
  * does the fault's own result count.
+ *
+ * `subjectReached` is the negative control's answer and is consulted at one
+ * point only: a would-be `survived`. It is never asked about a kill — a kill
+ * already proves the defenders reached the code — and `undefined` (the control
+ * was not run) never changes a verdict.
  */
-export function classify({ defenders, anchor, baselineRuns, probeRuns, confirmRuns }) {
+export function classify({ defenders, anchor, baselineRuns, probeRuns, confirmRuns, subjectReached }) {
   if (defenders.length === 0) return { verdict: 'nocover' };
   if (anchor && anchor.status !== 'ok') return { verdict: 'unverifiable', reason: anchor.status };
   if (baselineRuns.length === 0 || baselineRuns.some((r) => r.outcome !== 'pass')) {
@@ -24,7 +29,18 @@ export function classify({ defenders, anchor, baselineRuns, probeRuns, confirmRu
   const killedRuns = probeRuns.filter((r) => r.outcome === 'fail' && r.assertionFailures > 0);
   const passedRuns = probeRuns.filter((r) => r.outcome === 'pass');
   if (probeRuns.length === confirmRuns && killedRuns.length === confirmRuns) return { verdict: 'killed' };
-  if (probeRuns.length === confirmRuns && passedRuns.length === confirmRuns) return { verdict: 'survived' };
+  if (probeRuns.length === confirmRuns && passedRuns.length === confirmRuns) {
+    // The negative control. A green baseline proves the defenders can PASS; it
+    // says nothing about whether they can fail because of THIS file. If the
+    // subject was replaced with something that cannot compile and the
+    // defenders still went green, they never execute it — and then `survived`
+    // is a statement about their reach, not their assertions, and reads as a
+    // devastating audit finding while being entirely false.
+    // `undefined` means the control was not run, which is not evidence either
+    // way and leaves the verdict alone.
+    if (subjectReached === false) return { verdict: 'unverifiable', reason: 'subject-not-executed' };
+    return { verdict: 'survived' };
+  }
   // Some runs killed, some passed: the defenders' response to this fault is
   // nondeterministic. Reporting it as killed would be the optimistic bias
   // the research warned about; reporting survived would be a lie the other way.