control-arm 0.1.0

package/src/worktree.mjs

@@ -0,0 +1,197 @@
+/**
+ * Worktree + dependency plumbing.
+ *
+ * TWO HARD RULES.
+ *
+ * 1. NEVER touch the user's working tree. No `git stash`, no `git checkout` in their
+ *    clone, no writes outside the work dir. A validation tool that can lose somebody's
+ *    uncommitted work is dead on arrival, and this one runs over hundreds of commits
+ *    unattended. Everything happens in detached worktrees under `.ca-work/`.
+ *
+ * 2. Worktrees are REUSED across commits. `git worktree add` copies the whole tree
+ *    (~3,000 files in a mid-sized repo, ~20s); checking out a new commit inside an existing
+ *    worktree only touches what differs. Over 300 commits that is the difference between
+ *    a coffee and an afternoon.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, rm, symlink, lstat, readlink, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const exec = promisify(execFile);
+
+export async function git(repo, args, opts = {}) {
+    const { stdout } = await exec('git', ['-C', repo, ...args], { maxBuffer: 64 << 20, ...opts });
+    return stdout;
+}
+
+export async function ensureWorktree(repo, workDir, name, sha) {
+    const dir = path.join(workDir, name);
+    let exists = false;
+    try { await lstat(path.join(dir, '.git')); exists = true; } catch { /* first use */ }
+
+    if (!exists) {
+        await mkdir(workDir, { recursive: true });
+        await rm(dir, { recursive: true, force: true });
+        await git(repo, ['worktree', 'add', '--detach', '--force', dir, sha]);
+    } else {
+        // Reset hard, not checkout: a previous run transplanted a test file in here, and
+        // a dirty tree would make the next checkout fail or, worse, silently keep it.
+        await git(dir, ['checkout', '--detach', '--force', sha]);
+        await git(dir, ['reset', '--hard', sha]);
+        await git(dir, ['clean', '-fdq', '-e', 'node_modules']);
+    }
+    return dir;
+}
+
+/**
+ * Build a node_modules inside the worktree.
+ *
+ * Third-party packages are symlinked straight to the target repo's copies — they are
+ * version-pinned content and sharing them saves an install per commit. WORKSPACE packages
+ * are NOT: those are symlinks into the repo's own source, and following them is exactly
+ * how arm B ends up loading today's code. Those get re-pointed at the worktree.
+ *
+ * `identity.mjs` verifies the result rather than trusting it, because this function is a
+ * heuristic over somebody else's directory layout and will eventually be wrong.
+ */
+/**
+ * Every node_modules directory in the repo, as paths relative to the root.
+ *
+ * npm workspaces HOIST most packages to the root — but not all. Anything with a native
+ * or version-conflicting dependency stays in its own workspace, and there is no way to
+ * know which from the outside.
+ *
+ * Earned in practice: a React Native workspace held 25 entries including `jest-expo`.
+ * Mirroring only the root gave every mobile commit
+ *
+ *     ● Validation Error: Preset jest-expo not found.
+ *
+ * which the tool reported as INCONCLUSIVE for 25 cases. The fail-safe held — nothing was
+ * mislabelled BLIND — but a whole surface silently went unmeasured, which is its own kind
+ * of wrong answer.
+ *
+ * Discovered rather than configured: a hardcoded workspace list would be right for this
+ * repo and wrong for the next one.
+ */
+async function findNodeModulesDirs(repoRoot, maxDepth = 3) {
+    const found = [];
+    const walk = async (rel, depth) => {
+        const abs = path.join(repoRoot, rel);
+        let entries;
+        try { entries = await readdir(abs, { withFileTypes: true }); } catch { return; }
+        if (entries.some(e => e.name === 'node_modules')) found.push(rel);
+        if (depth >= maxDepth) return;
+        for (const e of entries) {
+            if (!e.isDirectory()) continue;
+            // Never descend INTO node_modules — its own nested copies belong to it.
+            if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+            await walk(path.join(rel, e.name), depth + 1);
+        }
+    };
+    await walk('', 0);
+    return found;
+}
+
+export async function linkDependencies(repoRoot, worktreeDir, { force = false } = {}) {
+    const dirs = await findNodeModulesDirs(repoRoot);
+    let total = { linked: 0, repointed: 0, trees: 0 };
+    for (const rel of dirs) {
+        const r = await linkOneTree(path.join(repoRoot, rel), path.join(worktreeDir, rel), repoRoot, worktreeDir, force);
+        total.linked += r.linked; total.repointed += r.repointed; total.trees += r.linked ? 1 : 0;
+    }
+    return total;
+}
+
+async function linkOneTree(srcParent, dstParent, repoRoot, worktreeDir, force) {
+    const src = path.join(srcParent, 'node_modules');
+    const dst = path.join(dstParent, 'node_modules');
+    try { await lstat(src); } catch { return { linked: 0, repointed: 0, note: 'no node_modules here' }; }
+
+    // Worktrees are reused across commits and node_modules is excluded from `git clean`,
+    // so this only has to run once per worktree. Rebuilding ~1,300 symlinks per commit
+    // dominated the audit's runtime and changed nothing.
+    if (!force) { try { await lstat(dst); return { linked: 0, repointed: 0, note: 'reused' }; } catch { /* build it */ } }
+
+    await rm(dst, { recursive: true, force: true });
+    await mkdir(dst, { recursive: true });
+
+    let linked = 0, repointed = 0;
+    const repoReal = path.resolve(repoRoot);
+
+    const link = async (relEntry) => {
+        const from = path.join(src, relEntry);
+        const to = path.join(dst, relEntry);
+        let target = from;
+        try {
+            const st = await lstat(from);
+            if (st.isSymbolicLink()) {
+                const raw = await readlink(from);
+                const abs = path.resolve(path.dirname(from), raw);
+                if (abs.startsWith(repoReal + path.sep)) {
+                    // A workspace package. Point it at the SAME relative path inside the worktree.
+                    target = path.join(worktreeDir, path.relative(repoReal, abs));
+                    repointed++;
+                }
+            }
+        } catch { return; }
+        await mkdir(path.dirname(to), { recursive: true });
+        await symlink(target, to).catch(() => {});
+        linked++;
+    };
+
+    for (const entry of await readdir(src)) {
+        if (entry.startsWith('@')) {
+            for (const scoped of await readdir(path.join(src, entry)).catch(() => [])) {
+                await link(path.join(entry, scoped));
+            }
+        } else {
+            await link(entry);
+        }
+    }
+    return { linked, repointed };
+}
+
+/**
+ * Link the repo's gitignored env files into the worktree.
+ *
+ * `git worktree add` checks out TRACKED files only, so `.env` — gitignored by design —
+ * is absent. Every DB-backed test then sees no TEST_DATABASE_URL and skips, which is why
+ * 955 of 5,956 cases in a 300-commit audit reported SKIPPED even with a database
+ * running. The tool was measuring a subset of the suite and correctly saying so, but the
+ * subset was an artifact of the harness rather than of the repo.
+ *
+ * SYMLINKED, never copied. The file holds live credentials; a copy would leave a second
+ * one on disk in a temp directory whose cleanup is not guaranteed. A symlink gives the
+ * child process the same bytes and leaves nothing behind when the worktree is removed.
+ */
+export async function linkEnvFiles(repoRoot, worktreeDir) {
+    const linked = [];
+    for (const name of ['.env', '.env.local', '.env.test', '.env.test.local']) {
+        const src = path.join(repoRoot, name);
+        try { await lstat(src); } catch { continue; }
+        const dst = path.join(worktreeDir, name);
+        await rm(dst, { force: true }).catch(() => {});
+        await symlink(src, dst).catch(() => {});
+        linked.push(name);
+    }
+    return linked;
+}
+
+/** Put the fix's version of a test file onto the parent tree. The transplant. */
+export async function transplant(repo, sha, relPath, worktreeDir) {
+    const content = await git(repo, ['show', `${sha}:${relPath}`]);
+    const dest = path.join(worktreeDir, relPath);
+    await mkdir(path.dirname(dest), { recursive: true });
+    await writeFile(dest, content);
+    return dest;
+}
+
+export async function removeWorktrees(repo, workDir) {
+    for (const name of ['fix', 'parent']) {
+        await git(repo, ['worktree', 'remove', '--force', path.join(workDir, name)]).catch(() => {});
+    }
+    await git(repo, ['worktree', 'prune']).catch(() => {});
+    await rm(workDir, { recursive: true, force: true }).catch(() => {});
+}

package/test/assertions.test.mjs

@@ -0,0 +1,130 @@
+/**
+ * Case extraction, pinned against the four shapes that actually broke it.
+ *
+ * Each of these was measured on a real corpus of 400 test cases, and each one alone
+ * accounted for a double-digit share of "could not analyse". Together they took the
+ * unresolvable pile from 64% to 1.3%. None would be caught by a suite that only fed the
+ * analyser well-formed input, which is why they are here with the messy input attached.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractCase, analyseCase } from '../src/assertions.mjs';
+
+test('nested suites: the runner reports the CONCATENATED name, the source holds the inner one', () => {
+    const src = `
+describe('auction client', () => {
+  it('AUCWEB-001 calls GET /auction/:vin', () => { assert.equal(a, 1); });
+});`;
+    // Reported by the runner as describe-title + space + it-title.
+    const body = extractCase(src, 'auction client AUCWEB-001 calls GET /auction/:vin');
+    assert.ok(body, 'progressive reduction must find the inner title');
+    assert.match(body, /assert\.equal\(a, 1\)/);
+});
+
+test('an APOSTROPHE in the title: source holds a backslash the reported name does not', () => {
+    const src = `it('METER-038: usage on the user\\'s LOCAL today is counted', () => { assert.equal(n, 3); });`;
+    const body = extractCase(src, "METER-038: usage on the user's LOCAL today is counted");
+    assert.ok(body, "an escaped quote inside the literal must still match the unescaped reported name");
+    assert.match(body, /assert\.equal\(n, 3\)/);
+});
+
+test('JSX: a closing tag is NOT a regex literal', () => {
+    // `</div>` puts a slash after `<`. The usual "slash after a non-expression starts a
+    // regex" heuristic swallows the rest of the component, and the body is never found.
+    const src = `
+it('hero renders', () => {
+  render(<div className="x">{name}</div>);
+  expect(screen.getByText('hi')).toBeTruthy();
+});`;
+    const body = extractCase(src, 'hero renders');
+    assert.ok(body, 'a JSX body must brace-match cleanly');
+    assert.match(body, /getByText/);
+});
+
+test('braces inside strings and regexes do not unbalance the scan', () => {
+    const src = `
+it('handles braces', () => {
+  const s = '{';
+  const re = /[{}]/;
+  assert.equal(f(s, re), '}');
+});`;
+    const body = extractCase(src, 'handles braces');
+    assert.ok(body, 'a brace inside a string or a character class is not structure');
+    assert.match(body, /assert\.equal\(f\(s, re\)/);
+});
+
+test('template-literal titles: every generated case resolves to the shared body', () => {
+    const src = `
+for (const rel of PAGES) {
+  it(\`\${rel}: no internal repo paths\`, () => { expect(md).not.toMatch(BAD); });
+}`;
+    const a = extractCase(src, 'app/page.tsx: no internal repo paths');
+    const b = extractCase(src, 'app/pricing/page.tsx: no internal repo paths');
+    assert.ok(a && b, 'a parameterised title must match by pattern, not by equality');
+    assert.equal(a, b, 'all generated cases share one body — that is correct, not a bug');
+});
+
+test('a wrong body is worse than none: a short remainder is refused', () => {
+    const src = `
+it('alpha returns null', () => { assert.equal(x, null); });
+it('beta returns null',  () => { assert.equal(y, 0); });`;
+    // "returns null" alone is ambiguous between the two — reduction must not take it.
+    const body = extractCase(src, 'some suite that does not exist returns null');
+    assert.equal(body, null, 'an ambiguous short suffix must not resolve to an arbitrary case');
+});
+
+test('CONTROL ARM: naive equality-only extraction fails every one of these', () => {
+    // The implementation this replaced. Asserted to still get them wrong.
+    const naive = (src, name) => {
+        const esc = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(`\\b(?:test|it)\\s*\\(\\s*(['"\`])${esc}\\1`).test(src);
+    };
+    assert.equal(naive(`it('a b c', () => {});`, 'suite a b c'), false);   // nested
+    assert.equal(naive(`it('u\\'s v', () => {});`, "u's v"), false);        // apostrophe
+    assert.equal(naive('it(`${r}: x`, () => {});', 'p.tsx: x'), false);    // template
+});
+
+test('the analyser reports UNKNOWN rather than a clean bill when it cannot tell', () => {
+    const r = analyseCase(`it('odd', () => { somethingEntirelyUnrecognised(); });`, 'odd');
+    assert.notEqual(r.verdict, 'strong', 'an unrecognised body must never read as strong');
+});
+
+test('a short helper name must not be accused of stubbing the unit under test', () => {
+    // FOUND ON A REAL RUN. The stub check substring-matched the name against every import
+    // path, so a two-letter helper `at` matched '@acme/core' — "acme" contains "at" — and
+    // every case in that file was reported as testing a stub. A wrong explanation is worse
+    // than none: it sends the reader to look at code that is fine.
+    const src = `
+import { computeTier } from '@acme/core/tiers.js';
+const at = (arr, i) => arr[i];
+it('TIER-001: the tier changes the money', () => {
+    assert.equal(at(computeTier(x), 0), 1200);
+});`;
+    const r = analyseCase(src, 'TIER-001: the tier changes the money');
+    assert.ok(!r.findings.some(f => f.id === 'stubbed-subject'),
+        'a local helper whose name merely appears inside an import path is not a stub');
+});
+
+test('a REAL stub is still caught — the tightening must not blind the check', () => {
+    const src = `
+import { SLA_HOURS } from '../src/priority.mjs';
+const priority = () => 1;
+it('p is 1', () => { assert.equal(priority('HIGH-PRIORITY'), 1); });`;
+    const r = analyseCase(src, 'p is 1');
+    assert.ok(r.findings.some(f => f.id === 'stubbed-subject'),
+        'a stub matching the imported module basename must still be reported');
+    assert.equal(r.verdict, 'weak');
+});
+
+test('a declined commit produces NO pr comment — silence, not an accusation', async () => {
+    // It briefly posted "SKIPPED · No case in this branch fails without the change" onto a
+    // workflow-only PR. Technically true and completely misleading: that PR has no tests,
+    // so of course none discriminate. A comment reading as an accusation on a PR doing
+    // nothing wrong is worse than no comment.
+    const { prComment } = await import('../src/markdown-report.mjs');
+    const declined = { short: 'abc12345', verdict: 'SKIPPED', cases: [], note: 'no test file in the commit' };
+    assert.equal(prComment(declined), '', 'a noted (declined) result must render as empty');
+
+    const real = { short: 'abc12345', verdict: 'CAUGHT', cases: [{ verdict: 'CAUGHT', name: 'x', reason: 'y' }] };
+    assert.notEqual(prComment(real), '', 'a real verdict must still render');
+});

package/test/fixtures.test.mjs

@@ -0,0 +1,41 @@
+/**
+ * The tool's control arm. Eight repos where the right answer is known by construction.
+ *
+ * A green run here is the only reason to believe a verdict this tool prints about
+ * anybody else's code. It is also the thing that would catch the failure mode that
+ * matters most — a FALSE BLIND — because 01 and 07 must never come back BLIND.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { buildFixtures } from '../fixtures/build.mjs';
+import { verifyCommit } from '../src/verify.mjs';
+import { removeWorktrees } from '../src/worktree.mjs';
+
+const fixtures = buildFixtures();
+
+for (const [name, f] of Object.entries(fixtures)) {
+    test(`${name} -> ${f.expect}  (${f.why})`, async () => {
+        const workDir = path.join(f.dir, '.ca-work');
+        try {
+            const r = await verifyCommit({ repo: f.dir, workDir, sha: f.sha, runs: 1, timeoutMs: 30_000 });
+            assert.equal(r.verdict, f.expect,
+                `expected ${f.expect}, got ${r.verdict}\n` +
+                r.cases.map(c => `    ${c.verdict}  ${c.name}  — ${c.reason}`).join('\n') +
+                (r.note ? `\n    note: ${r.note}` : ''));
+        } finally {
+            await removeWorktrees(f.dir, workDir);
+        }
+    });
+}
+
+test('a FALSE BLIND is the failure that matters: no discriminating fixture may read BLIND', async () => {
+    for (const name of ['01-caught-value', '07-caught-mixed']) {
+        const f = fixtures[name];
+        const workDir = path.join(f.dir, '.ca-work-fb');
+        try {
+            const r = await verifyCommit({ repo: f.dir, workDir, sha: f.sha, runs: 1, timeoutMs: 30_000 });
+            assert.notEqual(r.verdict, 'BLIND', `${name} was accused of being blind — this is the output that destroys trust in the tool`);
+        } finally { await removeWorktrees(f.dir, workDir); }
+    }
+});

package/test/runner-json.test.mjs

@@ -0,0 +1,69 @@
+/**
+ * The vitest/jest adapter, at the level where it can actually be wrong.
+ *
+ * WHAT THIS DOES AND DOES NOT COVER — stated because the gap matters.
+ *
+ * The node:test path has 9 end-to-end fixtures: real git repos, both arms, known verdict.
+ * These two runners do NOT, because a fixture would have to `npm install` vitest or jest
+ * per repo — slow, network-dependent, and version-drifting. The full two-arm path for
+ * each is verified on ONE real commit apiece — a vitest component commit and a jest
+ * React Native commit — which is a smoke test, not a control arm.
+ *
+ * So this file covers the part that is BOTH untested end-to-end AND most likely to be
+ * wrong: the text-matching in `classifyMessages`. node:test hands over `ERR_ASSERTION`;
+ * these two give formatted strings, so the adapter has to read prose. Every string below
+ * is a real shape emitted by vitest or jest, not an invented one.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { classifyMessages } from '../src/runner-json.mjs';
+
+const isDisagreement = m => classifyMessages(m).code === 'ERR_ASSERTION';
+const isCannotRun = m => classifyMessages(m).code === 'ERR_TEST_FAILURE';
+const isUnknown = m => classifyMessages(m).code === null;
+
+test('vitest/chai disagreement is read as an assertion', () => {
+    assert.ok(isDisagreement(["AssertionError: expected 'Urgent' to deeply equal 'Normal'"]));
+    assert.ok(isDisagreement(['AssertionError: expected 40 to be 65 // Object.is equality']));
+});
+
+test('jest/expect disagreement is read as an assertion', () => {
+    assert.ok(isDisagreement(['expect(received).toBe(expected) // Object.is equality\n\nExpected: "Normal"\nReceived: "Urgent"']));
+    assert.ok(isDisagreement(['Error: expect(received).toEqual(expected)\n\n- Expected\n+ Received']));
+});
+
+test('a module that could not load is NOT an assertion', () => {
+    assert.ok(isCannotRun(["Error: Cannot find module '../src/newHelper' from 'lib/__tests__/x.test.tsx'"]));
+    assert.ok(isCannotRun(["SyntaxError: The requested module './bucket.js' does not provide an export named 'SEP'"]));
+    assert.ok(isCannotRun(['Error: Failed to resolve import "./notYet" from "lib/x.test.tsx". Does the file exist?']));
+    assert.ok(isCannotRun(['TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".tsx"']));
+});
+
+test('CANNOT-RUN WINS when both shapes appear — the ordering that matters', () => {
+    // A failed module load frequently ALSO prints an expect() frame from the stack. If
+    // the disagreement patterns were checked first, this would read CAUGHT, and a commit
+    // whose test never ran would be credited with catching its bug.
+    const both = ['SyntaxError: does not provide an export named \'SEP\'\n  at expect(received).toBe(expected)\n  expected \'a\' to be \'b\''];
+    assert.ok(isCannotRun(both), 'a load failure that also prints an expect() frame must not read as a disagreement');
+    assert.notEqual(classifyMessages(both).code, 'ERR_ASSERTION');
+});
+
+test('an UNRECOGNISED message is unknown — never guessed into an assertion', () => {
+    // This is the design: an unrecognised shape costs COVERAGE (it reads INCONCLUSIVE),
+    // it cannot manufacture a finding. A drifting regex must fail safe, not fail loud.
+    assert.ok(isUnknown(['Something entirely unexpected happened in a custom matcher']));
+    assert.ok(isUnknown([]));
+    assert.ok(isUnknown(['']));
+    assert.notEqual(classifyMessages(['whatever']).code, 'ERR_ASSERTION');
+});
+
+test('CONTROL ARM: a naive "any failure is a disagreement" classifier gets these wrong', () => {
+    // TEST-001 — run the broken implementation and assert it still reproduces the bug.
+    const naive = msgs => (msgs && msgs.length ? 'ERR_ASSERTION' : null);
+    const loadFail = ["Error: Cannot find module '../src/newHelper'"];
+    assert.equal(naive(loadFail), 'ERR_ASSERTION');              // the naive one says CAUGHT
+    assert.equal(classifyMessages(loadFail).code, 'ERR_TEST_FAILURE');  // ours says it never ran
+    const weird = ['custom matcher blew up'];
+    assert.equal(naive(weird), 'ERR_ASSERTION');
+    assert.equal(classifyMessages(weird).code, null);
+});

package/test/select-runner.test.mjs

@@ -0,0 +1,78 @@
+/**
+ * Runner selection, over synthetic trees.
+ *
+ * Picking the WRONG runner is a silent failure: vitest run from the repo root finds no
+ * config and reports "No test files found", which reads INCONCLUSIVE — a whole surface
+ * disappears without ever saying why. So the walk-up has to be pinned.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { selectRunner } from '../src/select-runner.mjs';
+
+function tree(spec) {
+    const root = mkdtempSync(path.join(tmpdir(), 'ca-sel-'));
+    for (const [rel, content] of Object.entries(spec)) {
+        const p = path.join(root, rel);
+        mkdirSync(path.dirname(p), { recursive: true });
+        writeFileSync(p, content);
+    }
+    return root;
+}
+
+test('a vitest config in the workspace wins, and names that workspace as cwd', async () => {
+    const root = tree({
+        'package.json': '{"workspaces":["apps/*"]}',
+        'apps/web/vitest.config.ts': 'export default {}',
+        'apps/web/lib/__tests__/x.test.tsx': '',
+    });
+    try {
+        const r = await selectRunner(root, 'apps/web/lib/__tests__/x.test.tsx');
+        assert.equal(r.flavour, 'vitest');
+        assert.equal(r.pkgDir, 'apps/web', 'must run FROM apps/web — vitest resolves config relative to cwd');
+    } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('a jest config in the workspace wins', async () => {
+    const root = tree({ 'package.json': '{}', 'apps/mobile/jest.config.js': '', 'apps/mobile/__tests__/y.test.ts': '' });
+    try {
+        const r = await selectRunner(root, 'apps/mobile/__tests__/y.test.ts');
+        assert.equal(r.flavour, 'jest');
+        assert.equal(r.pkgDir, 'apps/mobile');
+    } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('root tests fall to node:test when nothing else claims them', async () => {
+    const root = tree({ 'package.json': '{"scripts":{"test":"node --test tests/*.test.js"}}', 'tests/a.test.js': '' });
+    try {
+        const r = await selectRunner(root, 'tests/a.test.js');
+        assert.equal(r.flavour, 'node');
+        assert.equal(r.pkgDir, '');
+    } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('a repo that declares NOTHING falls through to node:test, not to a guess', async () => {
+    // The safe default: node:test either works, or reports a load failure, which reads
+    // INCONCLUSIVE. Guessing vitest here would produce "No test files found" — the same
+    // silent disappearance this test exists to prevent.
+    const root = tree({ 'tests/a.test.js': '' });
+    try {
+        assert.equal((await selectRunner(root, 'tests/a.test.js')).flavour, 'node');
+    } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('a workspace config beats a root test script — the nearest owner wins', async () => {
+    // The root script often delegates (`npm run test --workspaces`), while the config
+    // that actually governs the file sits in the package. Nearest wins, walking up.
+    const root = tree({
+        'package.json': '{"scripts":{"test":"node --test"}}',
+        'apps/web/vitest.config.ts': '',
+        'apps/web/x.test.tsx': '',
+    });
+    try {
+        const r = await selectRunner(root, 'apps/web/x.test.tsx');
+        assert.equal(r.flavour, 'vitest');
+    } finally { rmSync(root, { recursive: true, force: true }); }
+});

package/test/verdict.test.mjs

@@ -0,0 +1,113 @@
+/**
+ * The decision logic, exhaustively, with no git and no subprocesses.
+ *
+ * Every case here is a shape observed in a real run, not an invented one.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { classify, reduceRuns, rollUp, isDisagreement, CAUGHT, BLIND, NON_DISCRIMINATING, INCONCLUSIVE, FLAKY, SKIPPED } from '../src/verdict.mjs';
+
+const pass = { status: 'pass' };
+const assertFail = { status: 'fail', code: 'ERR_ASSERTION', errorName: 'AssertionError', message: "expected 1, got 2" };
+const errFail = { status: 'fail', code: 'ERR_TEST_FAILURE', errorName: 'SyntaxError', message: "does not provide an export named 'TITLE_SEPARATOR'" };
+
+test('CAUGHT: green on the fix, assertion-red on the parent', () => {
+    assert.equal(classify({ armA: pass, armB: assertFail }).verdict, CAUGHT);
+});
+
+test('NON-DISCRIMINATING: green on the fix AND green on the parent', () => {
+    assert.equal(classify({ armA: pass, armB: pass }).verdict, NON_DISCRIMINATING);
+});
+
+test('a case green on both arms is never called BLIND — a regression guard is indistinguishable', () => {
+    // Observed in practice: 3 of one commit's 4 cases were deliberate regression guards.
+    assert.notEqual(classify({ armA: pass, armB: pass }).verdict, BLIND);
+});
+
+test('a non-assertion failure on the parent is INCONCLUSIVE, never CAUGHT — the test never ran', () => {
+    const r = classify({ armA: pass, armB: errFail });
+    assert.equal(r.verdict, INCONCLUSIVE);
+    assert.match(r.reason, /never ran/);
+});
+
+test('exit code alone would have gotten that wrong', () => {
+    // Both of these are "the process exited non-zero". Only one is a verdict.
+    assert.equal(classify({ armA: pass, armB: assertFail }).verdict, CAUGHT);
+    assert.equal(classify({ armA: pass, armB: errFail }).verdict, INCONCLUSIVE);
+});
+
+test('unproven module identity withholds the verdict even when arm B passed', () => {
+    // THE false-BLIND guard. Arm B green + identity unproven is precisely the symlink
+    // trap that made this tool report a false BLIND before it had an identity gate.
+    const r = classify({ armA: pass, armB: pass, identity: { proven: false, reason: 'resolved OUTSIDE the worktree' } });
+    assert.equal(r.verdict, INCONCLUSIVE);
+    assert.notEqual(r.verdict, BLIND);
+});
+
+test('a case that is red on the fix is INCONCLUSIVE — the commit does not stand up', () => {
+    assert.equal(classify({ armA: assertFail, armB: assertFail }).verdict, INCONCLUSIVE);
+});
+
+test('a case missing from the parent run is INCONCLUSIVE, not BLIND', () => {
+    assert.equal(classify({ armA: pass, armB: null }).verdict, INCONCLUSIVE);
+});
+
+test('isDisagreement is narrow: an unknown error name is not guessed into CAUGHT', () => {
+    assert.equal(isDisagreement({ status: 'fail', errorName: 'WeirdCustomError' }), false);
+    assert.equal(isDisagreement({ status: 'fail', errorName: 'JestAssertionError' }), true);
+});
+
+test('FLAKY: runs that disagree between CAUGHT and BLIND', () => {
+    const r = reduceRuns([{ verdict: CAUGHT }, { verdict: NON_DISCRIMINATING }, { verdict: CAUGHT }]);
+    assert.equal(r.verdict, FLAKY);
+});
+
+test('an INCONCLUSIVE run does not erase a decided one, but is disclosed', () => {
+    const r = reduceRuns([{ verdict: CAUGHT, reason: 'assertion' }, { verdict: INCONCLUSIVE, reason: 'timeout' }, { verdict: CAUGHT, reason: 'assertion' }]);
+    assert.equal(r.verdict, CAUGHT);
+    assert.match(r.reason, /1 of 3 runs inconclusive/);
+});
+
+test('rollUp: one discriminating case carries the commit, guards and all', () => {
+    assert.equal(rollUp([{ verdict: NON_DISCRIMINATING }, { verdict: NON_DISCRIMINATING }, { verdict: CAUGHT }]), CAUGHT);
+});
+
+test('rollUp: a SKIPPED case blocks BLIND — it might have been the discriminating one', () => {
+    // Observed: all four tests written FOR a bug were { skip: SKIP } on a host with no
+    // TEST_DATABASE_URL, while older cases in the same file ran and did not discriminate.
+    // Calling that blind judges the commit on the tests NOT written for it.
+    assert.equal(rollUp([{ verdict: NON_DISCRIMINATING }, { verdict: SKIPPED }]), INCONCLUSIVE);
+    assert.equal(rollUp([{ verdict: NON_DISCRIMINATING }, { verdict: NON_DISCRIMINATING }, { verdict: SKIPPED }]), INCONCLUSIVE);
+});
+
+test('rollUp: BLIND only when every case ran and NOT ONE discriminated', () => {
+    assert.equal(rollUp([{ verdict: NON_DISCRIMINATING }, { verdict: NON_DISCRIMINATING }]), BLIND);
+    // one case could not be judged -> the commit cannot be called blind
+    assert.equal(rollUp([{ verdict: NON_DISCRIMINATING }, { verdict: INCONCLUSIVE }]), INCONCLUSIVE);
+});
+
+test('CONTROL ARM: a verdict engine that only read exit codes fails these', () => {
+    // TEST-001 — the old, naive implementation, executed here, asserted to still be wrong.
+    const naive = ({ armB }) => (armB && armB.status === 'fail' ? CAUGHT : BLIND);
+    assert.equal(naive({ armB: errFail }), CAUGHT);                       // it says CAUGHT...
+    assert.equal(classify({ armA: pass, armB: errFail }).verdict, INCONCLUSIVE);  // ...we say no
+    assert.equal(naive({ armB: pass }), BLIND);   // and calls every regression guard blind                            // and it cannot see
+    assert.equal(classify({ armA: pass, armB: pass, identity: { proven: false, reason: 'x' } }).verdict, INCONCLUSIVE);
+});
+
+test('a CAUGHT on new code is still CAUGHT — the verdict does not lie, the CLAIM narrows', async () => {
+    // Issue #3. On a feature the base lacks the code entirely, so essentially any test
+    // touching it fails there — `expected 0 to be greater than 0` is a real AssertionError
+    // that says nothing about whether the test is well aimed. Reclassifying it would be
+    // dishonest (it IS a disagreement); counting it as evidence would be worse.
+    const { commitKind } = await import('../src/verify.mjs');
+
+    assert.equal(commitKind('feat(web): add seoTitle', false).newCode, true,
+        'a feature is new code whatever its diff looks like');
+    assert.equal(commitKind('fix(core): a hyphen decided a title', false).newCode, false,
+        'a fix that changes lines is a repair, and its CAUGHT is strong evidence');
+    assert.equal(commitKind('fix(api): add a missing export', true).newCode, true,
+        'a fix whose source diff only ADDS may still be reading something that was absent');
+    assert.equal(commitKind('no conventional prefix at all', false).kind, 'unknown',
+        'an unrecognised subject must not be guessed into fix or feature');
+});