testguard-cli 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-09-17
+
+From a field report on a real codebase (63 test files, 458 tests, 39 faults).
+
+### Fixed
+
+- **A runner that cannot be resolved was reported as `FLAKY-DEFENDER`.** In
+  the scratch worktree, a symlinked `node_modules` (the sibling/auto-worktree
+  layout) was invisible, vitest failed to load, and the load error was
+  classified as flaky tests — blaming the wrong party. Symlinked
+  `node_modules` are now linked to their resolved target; the runner is
+  checked before any verdict and an unresolvable one is a precondition
+  failure (exit 2) with the fix in the message; defenders that fail to
+  *load* during a baseline are `UNVERIFIABLE` (`defenders-failed-to-load`),
+  never flaky.
+- **Blast radius ignored path aliases.** `tsconfig`/`jsconfig` `paths` (with
+  `baseUrl` and relative `extends`) and `package.json#imports` are resolved,
+  so a module imported 83 times via `@/…` no longer ranks as if nothing
+  imported it. Bare package specifiers remain ignored, as documented.
+- Summary said "N unproven claims" when N counted faults; it now reports
+  unproven faults *and* the distinct claims they belong to.
+- `testguard claims` never showed which claims carry a `@claim` annotation;
+  it now reports the count and marks each annotated row.
+- Piping output to a closed reader (`testguard claims | head`) no longer
+  crashes with an `EPIPE` stack trace.
+
+### Added
+
+- `--claim <ID,ID>` probes only the named claims and writes
+  `.testguard/evidence-partial.json`, keeping the canonical evidence intact —
+  turns a fix-loop iteration from minutes into seconds.
+- `--runner-cmd "<cmd>"` with `{files}` and `{out}` placeholders for
+  monorepos, custom configs and other package managers.
+- `--node-modules <dir>` (or `TESTGUARD_NODE_MODULES`) to link a specific
+  `node_modules` into the scratch worktree.
+
+### Changed
+
+- The `--in-place` precondition message says what it means: only fault
+  target files must be clean; test files may be dirty.
+- `testguard baseline` prints the two `.gitignore` lines for the regenerated
+  files instead of leaving it to the README.
+- With no baseline, the ranked block is not printed a second time under the
+  per-fault stream.
+- `--quiet` is documented precisely.
+- Staged Homebrew formula carries the sha256 of the published 0.1.1 tarball.
+
+## [0.1.1] - 2026-09-17
+
+### Fixed
+
+- **0.1.0 did not run when installed.** `ajv`, which validates every document
+  against the spec, was declared as a devDependency, so `testguard` crashed on
+  startup from npm, `npx`, `pip` and Homebrew. It is now an exact-pinned
+  runtime dependency — the project's one dependency.
+- CI and the release job now pack the tarball, install it into a scratch
+  project with production dependencies only, and run the CLI from there
+  (`npm run test:install`). The suite alone runs from the checkout and could
+  not see this class of defect.
+
+### Changed
+
+- Homebrew formula carries the sha256 of the published tarball; description
+  shortened to satisfy `brew audit --strict`.
+
 ## [0.1.0] - 2026-09-17
 
 First release. A claim verifier, not a test generator.

package/README.md

@@ -5,7 +5,7 @@
 [![PyPI](https://img.shields.io/pypi/v/testguard-cli.svg)](https://pypi.org/project/testguard-cli/)
 [![node](https://img.shields.io/node/v/testguard-cli.svg)](https://nodejs.org)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
-[![zero deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](./package.json)
+[![deps](https://img.shields.io/badge/runtime%20deps-1%20pinned-brightgreen.svg)](./package.json)
 
 > Proves that a test suite actually defends the claims a project makes — by
 > injecting the faults those claims say cannot happen, and reporting every
@@ -35,6 +35,15 @@ on known-broken code. The largest gap was a compliance-critical path with
 100% coverage, where the one assertion that mattered used
 `expect.objectContaining({...})` and omitted the field carrying the data.
 
+A second, independent run on a different AI-authored codebase (63 test
+files, 458 tests, 24 hand-written security claims, 39 faults): **21 of 39
+faults survived a fully green suite — 9 of them critical.** Super-admin
+gating, membership checks, cookie flags and the whole authorization callback
+could be disabled without a single test noticing. One test file had
+re-implemented the authorization logic *inside the test* and asserted
+against the copy: fifteen green tests, zero detection. After wrapper-level
+tests were written against the survivors, 39/39 were killed.
+
 ## Install
 
 | How | Command |
@@ -43,7 +52,7 @@ on known-broken code. The largest gap was a compliance-critical path with
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.1.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.1.2` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
 
 ## How it works
@@ -60,7 +69,7 @@ npx testguard-cli brief       # tell the agent where the suite is blind, before
    deterministic source change that would make the statement false. Every
    claim and every fault records who produced it. `testguard claims`
    validates the file and reports drift against `@claim <ID>` annotations in
-   source.
+   source. Test files are deliberately not scanned — a claim asserted by a test is the authorship trap the tool exists for — and annotation ids must contain a hyphen so prose is never mistaken for one.
 2. **Probe** confirms the defenders are green N times unmodified, applies
    each fault in a scratch git worktree (your tree is never touched), runs
    the defenders N times, re-runs survivors against the whole suite with
@@ -77,8 +86,18 @@ npx testguard-cli brief       # tell the agent where the suite is blind, before
    | `FLAKY-DEFENDER` | the defenders are not reliably green, or disagreed across runs |
 
    Never a single score. Findings are ranked by severity, claim provenance
-   and blast radius, and written to `.testguard/evidence.json` — validated
-   against the spec before it is written.
+   and blast radius (relative imports, `tsconfig` path aliases and
+   `package.json#imports` are resolved; bare package names are not), and
+   written to `.testguard/evidence.json` — validated against the spec before
+   it is written.
+
+   Practical loop: first pass `--no-escalate` (escalation re-runs the whole
+   suite N times per survivor); iterate on one claim with
+   `--claim <ID> --in-place` — only the files faults are applied to must be
+   committed, test files may be dirty; final pass with defaults. A custom
+   runner (`pnpm --filter`, a specific config) goes in
+   `--runner-cmd "<cmd> {files} … {out}"`; if the scratch worktree cannot
+   see your `node_modules`, pass `--node-modules <dir>`.
 3. **Baseline** freezes every non-passing fingerprint. Later probes suppress
    what was already known and exit non-zero only on what is new. Claims whose
    source and defenders are unchanged reuse their prior verdict, so a probe
@@ -123,7 +142,7 @@ through every verdict.
 
 **v0.1.** Four commands, vitest runner, hand-authored faults. The contract
 spine — six JSON Schemas shared with the other Guard tools — is under
-[`spec/`](spec/). Zero runtime dependencies; Node ≥ 20.
+[`spec/`](spec/). One exact-pinned runtime dependency (`ajv`, for schema validation); Node ≥ 20.
 
 Not yet: test generation (the two-gate acceptance loop), other runners,
 mechanical fault producers, and calibration of fault classes against real

package/cli/testguard.mjs

@@ -1,6 +1,14 @@
 #!/usr/bin/env node
 import { main } from '../src/cli.mjs';
 
+// `testguard … | head` closes stdout early; that is not an error worth a stack trace.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', (err) => {
+    if (err.code === 'EPIPE') process.exit(0);
+    throw err;
+  });
+}
+
 main(process.argv.slice(2)).then((code) => {
   process.exitCode = code;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Proves a test suite defends the claims a project makes: injects the faults those claims forbid and reports every one the tests fail to detect.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,8 @@
     "test:spec": "vitest run spec/conformance",
     "self:probe": "node cli/testguard.mjs probe . --budget 180000",
     "release:sync": "node .github/scripts/sync-release-version.mjs",
-    "prepublishOnly": "node cli/testguard.mjs --version && node .github/scripts/sync-release-version.mjs --check"
+    "prepublishOnly": "node cli/testguard.mjs --version && node .github/scripts/sync-release-version.mjs --check",
+    "test:install": "node .github/scripts/install-smoke.mjs"
   },
   "keywords": [
     "testing",
@@ -45,7 +46,6 @@
     "quality-gate"
   ],
   "devDependencies": {
-    "ajv": "^8.20.0",
     "vitest": "^5.0.1"
   },
   "bin": {
@@ -62,5 +62,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "ajv": "8.20.0"
   }
 }

package/spec/GATE-SEMANTICS.md

@@ -12,7 +12,7 @@ The verdict set is closed. Only one value is a pass.
 | `killed` | Fault applied; every one of N probe runs failed with a genuine assertion failure, on a defender set that was green N/N unmodified. | no |
 | `survived` | Fault applied; every one of N probe runs passed. The claim is **unproven**. | **yes** |
 | `nocover` | No defending test exists: the declared globs resolve to nothing, or no test imports the subject. Worse than `survived` — nothing was even tried. | **yes** |
-| `unverifiable` | The fault could not be applied: anchor missing or ambiguous. Carries a `reason`. This is a loud, gating verdict — a claim that cannot be probed is not "skipped", it is undefended until someone re-authors the fault. | **yes** |
+| `unverifiable` | The claim could not be probed: the fault's anchor is missing or ambiguous, or its defenders failed to load (`defenders-failed-to-load`). Carries a `reason`. A loud, gating verdict — a claim that cannot be probed is not "skipped", it is undefended until someone fixes the fault or the defenders. Never confused with `flaky-defender`, which requires tests that *ran*. | **yes** |
 | `timeout` | Probe run exceeded its budget. Not counted as a kill; the pessimistic reading is the safe one because flakiness biases the metric optimistically. | **yes** |
 | `fault-invalid` | The replacement does not load or compile. A bad fault, not a detection. | **yes** |
 | `flaky-defender` | Defenders were not green N/N on unmodified source (`defenders-not-green`), or the N probe runs disagreed with each other (`inconsistent-probe`). Either way no verdict about the fault can be trusted; fix the defenders first. | **yes** |
@@ -81,7 +81,7 @@ evidence; they simply do not turn CI red.
 |---|---|
 | `0` | No new gating findings at or above the severity floor. |
 | `1` | At least one new gating finding. |
-| `2` | Precondition failed: defenders not green, working tree dirty for a target file, runner not found, claims file invalid. Nothing was probed. |
+| `2` | Precondition failed: test runner not resolvable (e.g. no `node_modules` linked into the scratch worktree), working tree dirty for a fault target file, claims file invalid, no commits. Nothing was probed. |
 | `3` | Usage or configuration error. |
 
 A tool must never exit `0` because it had nothing to check. If the claims

package/spec/schemas/common.schema.json

@@ -31,7 +31,7 @@
       "enum": ["critical", "high", "medium", "low"]
     },
     "verdict": {
-      "description": "Closed set. Only `killed` is a pass. Every other verdict gates by default (see GATE-SEMANTICS.md).",
+      "description": "Closed set. Only `killed` is a pass. Every other verdict gates by default (see GATE-SEMANTICS.md). `unverifiable` covers a fault that could not be applied (anchor missing/ambiguous) and a claim whose defenders failed to load (`defenders-failed-to-load`).",
       "enum": [
         "killed",
         "survived",

package/src/cli.mjs

@@ -28,10 +28,13 @@ probe
   --baseline <path>    baseline to gate against (default: <dir>/.testguard/baseline.json if present)
   --severity <level>   gate only at or above   (default: low)
   --ref <commit>       probe this commit in the scratch worktree (default: HEAD)
+  --claim <ID,ID>      probe only these claims; writes .testguard/evidence-partial.json
+  --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)
   --in-place           mutate the working tree instead of a scratch worktree
   --no-escalate        do not re-run survivors against the whole suite
   --no-reuse           re-probe claims whose inputs have not changed
-  --quiet              summary only
+  --quiet              suppress the per-fault stream and ranked block; print only the summary and evidence path
 
 claims     --json
 baseline   --evidence <path>  --out <path>
@@ -58,6 +61,9 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         severity: { type: 'string', default: 'low' },
         max: { type: 'string', default: '20' },
         ref: { type: 'string', default: 'HEAD' },
+        claim: { type: 'string' },
+        'runner-cmd': { type: 'string' },
+        'node-modules': { type: 'string' },
         'in-place': { type: 'boolean', default: false },
         'no-escalate': { type: 'boolean', default: false },
         'no-reuse': { type: 'boolean', default: false },

package/src/commands/baseline.mjs

@@ -16,6 +16,8 @@ export async function baselineCommand({ projectDir, values }, io) {
   writeSpecDoc('baseline', outPath, baseline);
   const n = Object.values(baseline.fingerprints).reduce((a, b) => a + b, 0);
   io.out(`baseline: ${n} unproven finding${n === 1 ? '' : 's'} frozen at ${baseline.head.slice(0, 12)} → ${outPath}`);
-  io.out('Commit this file. From now on only new findings gate.');
+  io.out('Commit this file; from now on only new findings gate. Ignore the regenerated ones — add to .gitignore:');
+  io.out('  .testguard/evidence.json');
+  io.out('  .testguard/brief.json');
   return 0;
 }

package/src/commands/claims.mjs

@@ -12,12 +12,13 @@ export async function claimsCommand({ projectDir, values }, io) {
   if (values.json) {
     io.out(JSON.stringify({ path, claims, annotations, drift }, null, 2));
   } else {
-    io.out(`${claims.claims.length} claims in ${path}`);
+    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)`);
     io.out('');
     for (const c of claims.claims) {
       const defenders = resolveDefenders(projectDir, c.defendedBy);
       const cover = defenders.length ? `${defenders.length} defender${defenders.length === 1 ? '' : 's'}` : 'NO DEFENDER';
-      io.out(`${c.id.padEnd(14)} ${c.severity.padEnd(8)} ${c.source.kind.padEnd(10)} ${String(c.faults.length).padStart(2)} fault${c.faults.length === 1 ? ' ' : 's'}  ${cover.padEnd(12)}  ${c.statement}`);
+      io.out(`${annotated.has(c.id) ? '@ ' : '  '}${c.id.padEnd(14)} ${c.severity.padEnd(8)} ${c.source.kind.padEnd(10)} ${String(c.faults.length).padStart(2)} fault${c.faults.length === 1 ? ' ' : 's'}  ${cover.padEnd(12)}  ${c.statement}`);
     }
     if (drift.undeclared.length || drift.stale.length) io.out('');
     for (const a of drift.undeclared) io.out(`UNDECLARED   @claim ${a.id} at ${a.file}:${a.line} has no entry in the claims file — a claim with no fault model`);

package/src/commands/probe.mjs

@@ -21,7 +21,9 @@ export async function probeCommand({ projectDir, values, version }, io) {
     io.err('claims file declares no claims; nothing to verify');
     return 2;
   }
-  const outPath = values.out ? resolve(values.out) : evidencePath(projectDir);
+  const only = values.claim ? values.claim.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+  // A --claim run is partial evidence; keep it away from the canonical file unless --out says otherwise.
+  const outPath = values.out ? resolve(values.out) : only ? join(projectDir, '.testguard', 'evidence-partial.json') : evidencePath(projectDir);
   const previous = !values['no-reuse'] && existsSync(outPath) ? readSpecDoc('evidence', outPath) : undefined;
   const basePath = values.baseline ? resolve(values.baseline) : baselinePath(projectDir);
   const baseline = existsSync(basePath) ? readSpecDoc('baseline', basePath) : undefined;
@@ -34,6 +36,9 @@ export async function probeCommand({ projectDir, values, version }, io) {
     budgetMs,
     mode: values['in-place'] ? 'in-place' : 'worktree',
     ref: values.ref,
+    runnerCommand: values['runner-cmd'],
+    nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    only,
     escalate: !values['no-escalate'],
     toolVersion: version,
     onProgress: values.quiet ? undefined : (r) => io.out(renderRecord(r) + (r.reusedFrom ? '  (reused)' : '')),
@@ -41,13 +46,13 @@ export async function probeCommand({ projectDir, values, version }, io) {
   writeSpecDoc('evidence', outPath, evidence);
 
   const g = gate(evidence.records, baseline, { severityFloor: values.severity });
-  if (!values.quiet) {
+  if (!values.quiet && baseline) {
     io.out('');
     const tag = (r) => (g.new.includes(r) ? '[NEW]      ' : g.baselined.includes(r) ? '[baseline] ' : '[below floor] ');
     for (const r of sortForReport(evidence.records).filter((x) => x.verdict !== 'killed')) io.out('  ' + tag(r) + renderRecord(r));
   }
   io.out('');
   io.out(renderSummary(evidence.records) + (baseline ? ` ${g.new.length} new since baseline, ${g.baselined.length} baselined.` : ' No baseline.'));
-  io.out(`evidence: ${outPath}`);
+  io.out(`evidence: ${outPath}${only ? ` (partial: --claim ${only.join(',')}; not the canonical evidence file)` : ''}`);
   return g.new.length > 0 ? 1 : 0;
 }

package/src/probe/probe.mjs

@@ -12,7 +12,7 @@ import { fingerprint } from '../../spec/lib/fingerprint.mjs';
 
 const isKill = (r) => r.outcome === 'fail' && r.assertionFailures > 0;
 
-function runnerVersion(projectDir) {
+function readRunnerVersion(projectDir) {
   try {
     return JSON.parse(readFileSync(createRequire(join(projectDir, 'noop.js')).resolve('vitest/package.json'), 'utf8')).version;
   } catch {
@@ -31,6 +31,9 @@ export async function probe({
   mode = 'worktree',
   ref = 'HEAD',
   budgetMs = 120_000,
+  runnerCommand,
+  nodeModules,
+  only,
   escalate = true,
   scratchBase,
   toolVersion = '0.0.0',
@@ -45,21 +48,39 @@ export async function probe({
 
   const targets = [...new Set(claims.claims.flatMap((c) => c.faults.map((f) => relative(root, join(projectDir, f.file)))))];
   if (mode === 'in-place' && isDirty(root, targets)) {
-    throw new PreconditionError(`uncommitted changes in target files (${targets.join(', ')}); commit or stash first, or drop --in-place`);
+    throw new PreconditionError(`uncommitted changes in fault target files (${targets.join(', ')}); commit or stash them, or drop --in-place. Only the files faults are applied to must be clean — test files may be dirty, which is what makes --in-place usable while writing tests.`);
+  }
+  const selected = only ? new Set(only) : null;
+  if (selected) {
+    const known = new Set(claims.claims.map((c) => c.id));
+    const unknown = [...selected].filter((id) => !known.has(id));
+    if (unknown.length) throw new PreconditionError(`--claim: unknown claim id(s) ${unknown.join(', ')}`);
   }
 
   const startedAt = new Date().toISOString();
-  const iso = mode === 'worktree' ? createScratch({ repoRoot: root, projectDir, ref, scratchBase }) : inPlace({ repoRoot: root, projectDir });
+  const iso = mode === 'worktree' ? createScratch({ repoRoot: root, projectDir, ref, scratchBase, nodeModules }) : inPlace({ repoRoot: root, projectDir });
   const records = [];
+  let runnerVersion;
   try {
+    const commandTemplate = runnerCommand ? vitest.parseCommandTemplate(runnerCommand) : undefined;
+    if (!commandTemplate) {
+      // An unresolvable runner is a precondition failure, not a flaky defender.
+      const check = await vitest.checkRunner({ projectDir: iso.projectDir });
+      if (!check.ok) {
+        throw new PreconditionError(`test runner is not resolvable in the ${mode === 'worktree' ? 'scratch worktree' : 'project'} (${check.message}). ` +
+          (mode === 'worktree' ? 'No usable node_modules was linked: pass --node-modules <path>, or run with --in-place.' : 'Install dependencies first.'));
+      }
+      runnerVersion = check.version;
+    }
     const allTests = vitest.listTestFiles(iso.projectDir);
     const baselineCache = new Map();
     const prior = previous && previous.run.confirmRuns === confirmRuns
       ? new Map(previous.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]))
       : new Map();
-    const runDefenders = (files) => vitest.runVitest({ projectDir: iso.projectDir, files, budgetMs });
+    const runDefenders = (files) => vitest.runVitest({ projectDir: iso.projectDir, files, budgetMs, commandTemplate });
 
     for (const claim of claims.claims) {
+      if (selected && !selected.has(claim.id)) continue;
       const defenders = vitest.resolveDefenders(iso.projectDir, claim.defendedBy);
       for (const fault of claim.faults) {
         const record = await probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, escalate, baselineCache, runDefenders, prior: prior.get(`${claim.id}/${fault.id}`), priorRunId: previous?.run.id });
@@ -79,7 +100,7 @@ export async function probe({
       startedAt,
       finishedAt: new Date().toISOString(),
       repo: { head, dirty: isDirty(root) },
-      runner: { name: vitest.name, ...(runnerVersion(projectDir) ? { version: runnerVersion(projectDir) } : {}) },
+      runner: { name: vitest.name, ...((runnerVersion ?? readRunnerVersion(projectDir)) ? { version: runnerVersion ?? readRunnerVersion(projectDir) } : {}) },
       confirmRuns,
       mode,
     },
@@ -111,14 +132,24 @@ async function probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, e
       const key = defenders.join('\n');
       if (!baselineCache.has(key)) {
         const runs = [];
+        let loadMessage;
         for (let i = 0; i < confirmRuns; i++) {
-          const { run } = await runDefenders(defenders);
-          runs.push(run);
-          if (run.outcome !== 'pass') break;
+          const res = await runDefenders(defenders);
+          runs.push(res.run);
+          if (res.run.outcome !== 'pass') {
+            loadMessage = res.loadMessage;
+            break;
+          }
         }
-        baselineCache.set(key, runs);
+        baselineCache.set(key, { runs, loadMessage });
+      }
+      const baseline = baselineCache.get(key);
+      detail.baselineRuns = baseline.runs;
+      if (baseline.runs.some((r) => r.outcome === 'error')) {
+        // The defenders did not load. That is not flakiness and not a verdict
+        // about the fault; the claim cannot be probed until they do.
+        anchor = { status: 'defenders-failed-to-load', hits: anchor.hits, expected: anchor.expected, message: baseline.loadMessage };
       }
-      detail.baselineRuns = baselineCache.get(key);
 
       if (detail.baselineRuns.every((r) => r.outcome === 'pass') && detail.baselineRuns.length === confirmRuns) {
         const mutation = applyFault(iso.projectDir, fault);

package/src/probe/rank.mjs

@@ -1,7 +1,78 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { dirname, join, resolve, extname } from 'node:path';
 import { walk } from '../util/glob.mjs';
 
+const aliasCache = new Map();
+
+/** Minimal JSONC: strip comments and trailing commas, as tsconfig allows. */
+function parseJsonc(text) {
+  return JSON.parse(text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '').replace(/,(\s*[}\]])/g, '$1'));
+}
+
+/**
+ * Alias rules for a project: tsconfig/jsconfig `compilerOptions.paths` (with
+ * `baseUrl`, following a relative `extends` a few levels) and package.json
+ * `imports`. Bare specifiers that match no rule are ignored, as documented.
+ */
+export function loadAliases(projectDir) {
+  if (aliasCache.has(projectDir)) return aliasCache.get(projectDir);
+  const rules = [];
+  const toRule = (pattern, targets, base) => {
+    const [prefix, suffix = ''] = pattern.split('*');
+    rules.push({ prefix, suffix, wildcard: pattern.includes('*'), targets: targets.map((t) => resolve(base, t)) });
+  };
+
+  let cfgPath = ['tsconfig.json', 'jsconfig.json'].map((f) => join(projectDir, f)).find(existsSync);
+  let baseUrl;
+  let paths;
+  for (let hop = 0; cfgPath && hop < 5; hop++) {
+    let cfg;
+    try {
+      cfg = parseJsonc(readFileSync(cfgPath, 'utf8'));
+    } catch {
+      break;
+    }
+    const co = cfg.compilerOptions ?? {};
+    if (baseUrl === undefined && co.baseUrl !== undefined) baseUrl = resolve(dirname(cfgPath), co.baseUrl);
+    if (paths === undefined && co.paths !== undefined) paths = { dir: dirname(cfgPath), map: co.paths };
+    const ext = typeof cfg.extends === 'string' && cfg.extends.startsWith('.') ? cfg.extends : null;
+    cfgPath = ext ? resolve(dirname(cfgPath), ext.endsWith('.json') ? ext : ext + '.json') : null;
+  }
+  if (paths) {
+    const base = baseUrl ?? paths.dir;
+    for (const [pattern, targets] of Object.entries(paths.map)) if (Array.isArray(targets)) toRule(pattern, targets, base);
+  }
+
+  const pkgPath = join(projectDir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const imports = JSON.parse(readFileSync(pkgPath, 'utf8')).imports ?? {};
+      for (const [pattern, target] of Object.entries(imports)) {
+        const t = typeof target === 'string' ? target : target?.default ?? target?.import ?? target?.node;
+        if (typeof t === 'string' && t.startsWith('.')) toRule(pattern, [t], projectDir);
+      }
+    } catch {}
+  }
+  aliasCache.set(projectDir, rules);
+  return rules;
+}
+
+/** Absolute candidate bases an aliased specifier could mean, or [] if it matches no rule. */
+function aliasCandidates(specifier, rules) {
+  const out = [];
+  for (const r of rules) {
+    if (r.wildcard) {
+      if (specifier.startsWith(r.prefix) && specifier.endsWith(r.suffix) && specifier.length >= r.prefix.length + r.suffix.length) {
+        const star = specifier.slice(r.prefix.length, specifier.length - r.suffix.length);
+        for (const t of r.targets) out.push(t.replace('*', star));
+      }
+    } else if (specifier === r.prefix) {
+      out.push(...r.targets);
+    }
+  }
+  return out;
+}
+
 const SOURCE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx']);
 const IMPORT_RE = /(?:from\s*|import\s*\(?\s*|require\s*\(\s*)['"]([^'"]+)['"]/g;
 const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
@@ -11,18 +82,26 @@ const SEVERITY_WEIGHT = { critical: 8, high: 4, medium: 2, low: 1 };
 // independent evidence than one from a human-governed spec.
 const SOURCE_WEIGHT = { spec: 1, adr: 1, manual: 0.9, annotation: 0.75, comment: 0.75 };
 
-function resolvesTo(fromFile, specifier, targetAbs) {
-  if (!specifier.startsWith('.')) return false;
-  const base = resolve(dirname(fromFile), specifier);
+function expandBase(base) {
   const candidates = [base, ...[...SOURCE_EXT].map((e) => base + e), ...[...SOURCE_EXT].map((e) => join(base, 'index' + e))];
   const stripped = base.replace(/\.(js|mjs|cjs)$/, '');
   candidates.push(stripped + '.ts', stripped + '.mts', stripped + '.tsx');
-  return candidates.includes(targetAbs);
+  return candidates;
+}
+
+function resolvesTo(fromFile, specifier, targetAbs, aliases) {
+  const bases = specifier.startsWith('.') ? [resolve(dirname(fromFile), specifier)] : aliasCandidates(specifier, aliases);
+  return bases.some((b) => expandBase(b).includes(targetAbs));
 }
 
-/** Number of non-test source files that import `targetRel` (direct imports only, documented as such). */
+/**
+ * Number of non-test source files that import `targetRel`: relative specifiers,
+ * tsconfig/jsconfig `paths` aliases and package.json `imports` are resolved;
+ * bare package specifiers are not. Direct imports only.
+ */
 export function blastRadius(projectDir, targetRel) {
   const targetAbs = resolve(projectDir, targetRel);
+  const aliases = loadAliases(projectDir);
   let count = 0;
   for (const rel of walk(projectDir)) {
     if (!SOURCE_EXT.has(extname(rel)) || TEST_RE.test(rel) || rel === targetRel) continue;
@@ -34,7 +113,7 @@ export function blastRadius(projectDir, targetRel) {
       continue;
     }
     for (const m of src.matchAll(IMPORT_RE)) {
-      if (resolvesTo(abs, m[1], targetAbs)) {
+      if (resolvesTo(abs, m[1], targetAbs, aliases)) {
         count++;
         break;
       }

package/src/probe/runner-vitest.mjs

@@ -10,6 +10,63 @@ const TEST_GLOBS = ['**/*.test.js', '**/*.test.mjs', '**/*.test.cjs', '**/*.test
 
 export const name = 'vitest';
 
+/**
+ * Split a runner command template into argv. Supports double and single
+ * quotes; `{files}` expands to the test files (one argv entry each) and
+ * `{out}` to the JSON report path. Everything else is passed through.
+ */
+export function parseCommandTemplate(template) {
+  const words = [];
+  let cur = '';
+  let quote = null;
+  let has = false;
+  for (const ch of template) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else cur += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      has = true;
+    } else if (/\s/.test(ch)) {
+      if (has || cur) words.push(cur);
+      cur = '';
+      has = false;
+    } else {
+      cur += ch;
+    }
+  }
+  if (has || cur) words.push(cur);
+  if (quote) throw new RangeError('unterminated quote in --runner-cmd');
+  if (!words.includes('{files}') || !words.some((w) => w.includes('{out}'))) throw new RangeError('--runner-cmd must contain {files} (as its own word) and {out}');
+  return words;
+}
+
+/** `{files}` must be a word of its own (one argv entry per file); `{out}` may be embedded, e.g. `--outputFile={out}`. */
+export const expandCommand = (words, files, outFile) => words.flatMap((w) => (w === '{files}' ? files : [w.replaceAll('{out}', outFile)]));
+
+/**
+ * Can the runner be resolved at all from this directory? Run before any
+ * verdict is attempted: an unresolvable runner is a precondition failure,
+ * never a statement about the tests.
+ */
+export function checkRunner({ projectDir, budgetMs = 60_000, env = process.env }) {
+  const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+  return new Promise((resolve) => {
+    const child = spawn(npx, ['--no-install', 'vitest', '--version'], { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], env: { ...env, CI: '1' } });
+    let out = '';
+    let err = '';
+    child.on('error', (e) => resolve({ ok: false, message: e.message }));
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    const timer = setTimeout(() => child.kill('SIGKILL'), budgetMs);
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const version = out.trim().replace(/^vitest\//, '');
+      resolve(code === 0 && version ? { ok: true, version } : { ok: false, message: (err || out).trim().split('\n').filter(Boolean).slice(-1)[0] ?? `exit ${code}` });
+    });
+  });
+}
+
 /** Defender globs → existing files. Empty result is the `nocover` signal. */
 export const resolveDefenders = (projectDir, globs) => matchGlobs(projectDir, globs ?? []);
 
@@ -47,16 +104,18 @@ export function parseReport(report, durationMs) {
  * The budget matters because a synchronous infinite loop is immune to
  * vitest's own test timeout; only killing the process ends it.
  */
-export function runVitest({ projectDir, files, budgetMs = 120_000, command }) {
+export function runVitest({ projectDir, files, budgetMs = 120_000, command, commandTemplate }) {
   const outFile = join(tmpdir(), `testguard-vitest-${randomBytes(6).toString('hex')}.json`);
   const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-  const [cmd, ...args] = command ?? [npx, 'vitest', 'run', ...files, '--reporter=json', `--outputFile=${outFile}`];
+  const [cmd, ...args] = command
+    ?? (commandTemplate ? expandCommand(commandTemplate, files, outFile) : [npx, 'vitest', 'run', ...files, '--reporter=json', `--outputFile=${outFile}`]);
   const started = Date.now();
 
   return new Promise((resolve) => {
     const child = spawn(cmd, args, { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, CI: '1', FORCE_COLOR: '0' } });
     let stderr = '';
     child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', (e) => (stderr += e.message));
     let killed = false;
     const timer = setTimeout(() => {
       killed = true;

package/src/probe/worktree.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdtempSync, readdirSync, symlinkSync, mkdirSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, readdirSync, symlinkSync, mkdirSync, statSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, relative, dirname } from 'node:path';
 import { addWorktree, removeWorktree, headSha } from '../git.mjs';
@@ -7,10 +7,21 @@ export class PreconditionError extends Error {}
 
 /**
  * Find every node_modules directory in the main tree (to a shallow depth) so
- * the scratch worktree can borrow them instead of reinstalling.
+ * the scratch worktree can borrow them instead of reinstalling. A symlinked
+ * node_modules — the layout a sibling or auto-created worktree produces — is
+ * a directory for this purpose, and is linked to its resolved target.
  */
-function findNodeModules(root, depth = 3) {
+export function findNodeModules(root, depth = 3) {
   const found = [];
+  const isDir = (dir, e) => {
+    if (e.isDirectory()) return true;
+    if (!e.isSymbolicLink()) return false;
+    try {
+      return statSync(join(dir, e.name)).isDirectory();
+    } catch {
+      return false;
+    }
+  };
   const visit = (dir, rel, d) => {
     let entries;
     try {
@@ -19,10 +30,10 @@ function findNodeModules(root, depth = 3) {
       return;
     }
     for (const e of entries) {
-      if (!e.isDirectory()) continue;
+      if (!isDir(dir, e)) continue;
       const relPath = rel ? `${rel}/${e.name}` : e.name;
       if (e.name === 'node_modules') {
-        found.push(relPath);
+        found.push({ rel: relPath, target: realpathSync(join(dir, e.name)) });
       } else if (d < depth && e.name !== '.git' && !e.name.startsWith('.')) {
         visit(join(dir, e.name), relPath, d + 1);
       }
@@ -36,18 +47,24 @@ function findNodeModules(root, depth = 3) {
  * A scratch git worktree at HEAD, with the main tree's node_modules linked in.
  * Faults are applied here; the user's tree is never touched.
  */
-export function createScratch({ repoRoot, projectDir, ref = 'HEAD', scratchBase = tmpdir() }) {
+export function createScratch({ repoRoot, projectDir, ref = 'HEAD', scratchBase = tmpdir(), nodeModules }) {
   const sha = headSha(repoRoot, ref);
   if (!sha) {
     throw new PreconditionError(ref === 'HEAD' ? 'repository has no commits; commit first, or run with --in-place' : `ref ${ref} does not resolve to a commit`);
   }
   const dest = mkdtempSync(join(scratchBase, 'testguard-'));
   addWorktree(repoRoot, dest, sha);
-  for (const rel of findNodeModules(repoRoot)) {
-    const target = join(dest, rel);
-    if (existsSync(target)) continue;
-    mkdirSync(dirname(target), { recursive: true });
-    symlinkSync(join(repoRoot, rel), target, 'dir');
+  const links = findNodeModules(repoRoot);
+  if (nodeModules) {
+    // Explicit override: link it where the probed project expects it.
+    const rel = join(relative(repoRoot, projectDir), 'node_modules');
+    links.unshift({ rel, target: realpathSync(nodeModules) });
+  }
+  for (const { rel, target } of links) {
+    const at = join(dest, rel);
+    if (existsSync(at)) continue;
+    mkdirSync(dirname(at), { recursive: true });
+    symlinkSync(target, at, 'dir');
   }
   return {
     mode: 'worktree',

package/src/render.mjs

@@ -18,8 +18,9 @@ export function summarize(records) {
 export function renderSummary(records) {
   const byVerdict = summarize(records);
   const parts = ORDER.filter((v) => byVerdict[v]).map((v) => `${byVerdict[v]} ${formatVerdict(v)}`);
-  const gating = records.filter((r) => r.verdict !== 'killed').length;
-  return `${records.length} faults probed: ${parts.join(', ')}. ${gating} unproven claim${gating === 1 ? '' : 's'}.`;
+  const unproven = records.filter((r) => r.verdict !== 'killed');
+  const claims = new Set(unproven.map((r) => r.claim.id)).size;
+  return `${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.`;
 }
 
 /** Survivors first, then by rank score; killed last. */