testguard-cli 0.12.0 → 0.14.0

package/src/cli.mjs

@@ -19,6 +19,7 @@ import { replayCommand } from './commands/replay.mjs';
 import { mcpCommand } from './commands/mcp.mjs';
 import { admitCommand } from './commands/admit.mjs';
 import { sweepCommand } from './commands/sweep.mjs';
+import { concernsCommand } from './commands/concerns.mjs';
 
 const VERSION = JSON.parse(readFileSync(join(fileURLToPath(import.meta.url), '..', '..', 'package.json'), 'utf8')).version;
 const ISSUES = 'https://github.com/raccioly/testguard/issues';
@@ -34,6 +35,7 @@ export const USAGE = `testguard ${VERSION} — proves a test suite defends the c
   testguard gate [dir]       fail when a changed source file carries no claim and no excusing ignore entry
   testguard scaffold <file>  propose faults mechanically for one source file, as a draft claims document
   testguard sweep [dir]      propose faults for the changed source files that carry no claim, probe a bounded selection, and report what nothing noticed
+  testguard concerns [dir]   the one-sentence scopes a sweep can be aimed by: where to look, and which shapes of break are relevant
   testguard mcp              serve the read-only status/brief/claims/evidence tools over MCP on stdio, so the loop works in any agent harness
   testguard replay [dir]     would this suite have caught the bugs that already escaped? Replays real fix commits and calibrates fault classes against them
   testguard admit <test> --claim <ID>   the two-gate rule as one verb: is this test green on HEAD and does it fail on every fault of the claim?
@@ -77,6 +79,8 @@ probe
 
 scaffold   --claim <ID> (put every proposal under this claim; copies it if it exists)  --out <path>  --json
 sweep      --changed <ref> (required unless --save-paths; CI bases and a safe local default are detected)  --cap <n>
+           --concern <ID>    aim the sweep by one of this project's concerns: its targets and its fault classes.
+                             testguard concerns lists them. --save-paths is sugar for the built-in SAVE-PERSISTS
            --save-paths      sweep every file that WRITES TO STORAGE instead of the diff, and report the surface as the
                              denominator: "120 writes across 38 files, swept 12". A clean sweep over an unstated
                              denominator is a sample of unknown size, not a guarantee that saving works
@@ -126,7 +130,7 @@ brief      --evidence <path>  --baseline <path>  --max <n>  --text (print only;
 exit codes: 0 nothing new to prove · 1 unproven claims (or claim drift, or unclaimed changes) · 2 precondition failed · 3 usage
 `;
 
-const COMMANDS = { mcp: mcpCommand, replay: replayCommand, probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand, gate: gateCommand, admit: admitCommand, sweep: sweepCommand };
+const COMMANDS = { mcp: mcpCommand, replay: replayCommand, probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand, gate: gateCommand, admit: admitCommand, sweep: sweepCommand, concerns: concernsCommand };
 
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
   let parsed;
@@ -154,6 +158,8 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         exclude: { type: 'string', multiple: true },
         cap: { type: 'string' },
         'save-paths': { type: 'boolean', default: false },
+        concern: { type: 'string' },
+        concerns: { type: 'string' },
         strict: { type: 'boolean', default: false },
         explain: { type: 'boolean', default: false },
         ignore: { type: 'string' },

package/src/commands/concerns.mjs

@@ -0,0 +1,32 @@
+import { resolve } from 'node:path';
+import { loadConcerns, renderConcerns } from '../supply/concerns.mjs';
+import { validate } from '../../spec/lib/validate.mjs';
+
+/**
+ * `testguard concerns [dir]`: the one-sentence scopes a sweep can be aimed by.
+ *
+ * A concern says WHERE to look and WHICH shapes of break are relevant. It is
+ * never a promise about the code — only a claim is that — so this command
+ * validates and lists, and has no exit code that means "something is wrong
+ * with your project". Exit 2 is a malformed concerns file, which is wrong with
+ * the FILE.
+ */
+export async function concernsCommand({ projectDir, values, version }, io) {
+  const path = values.concerns ? resolve(values.concerns) : undefined;
+  const loaded = loadConcerns(projectDir, { path });
+
+  if (loaded.source) {
+    const result = validate('concerns', { schemaVersion: 1, concerns: loaded.raw });
+    if (!result.ok) {
+      io.err(`${loaded.source} does not conform to the spec:`);
+      for (const e of result.errors) io.err(`  ${e.path}: ${e.message}`);
+      return 2;
+    }
+  }
+  if (values.json) {
+    io.out(JSON.stringify({ schemaVersion: 1, tool: { name: 'testguard', version }, source: loaded.source, shadowed: loaded.shadowed, concerns: loaded.concerns }, null, 2));
+  } else {
+    io.out(renderConcerns(loaded));
+  }
+  return 0;
+}

package/src/commands/sweep.mjs

@@ -1,9 +1,17 @@
 import { join, resolve } from 'node:path';
-import { sweep, renderSweep } from '../sweep/sweep.mjs';
+import { sweep, renderSweep, ConcernError } from '../sweep/sweep.mjs';
 import { resolveChangedRef } from '../gate/changed.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 
 export const sweepPath = (projectDir) => join(projectDir, '.testguard', 'sweep.json');
+/**
+ * A sweep's own evidence, beside the canonical one and never replacing it.
+ * The next sweep reads it to learn which fault classes are productive HERE,
+ * which is the feedback half of the selection Google reports taking from 15%
+ * to 89% productive. Machine-proposed faults, so it is the closest observation
+ * of the distribution the ranker actually orders.
+ */
+export const sweepEvidencePath = (projectDir) => join(projectDir, '.testguard', 'sweep-evidence.json');
 
 /**
  * `testguard sweep [dir] --changed <ref>`: propose faults for the changed
@@ -21,11 +29,14 @@ export const sweepPath = (projectDir) => join(projectDir, '.testguard', 'sweep.j
  */
 export async function sweepCommand({ projectDir, values, version }, io) {
   const mode = values['save-paths'] ? 'save-paths' : 'changed';
+  // A concern that aims at the write surface or at a glob needs no diff, the
+  // same as --save-paths. Only a concern that defers to the gate does.
+  const aimed = Boolean(values.concern) || mode === 'save-paths';
   // `--save-paths` scans the whole write surface, so it needs no diff. The gate
   // is still computed underneath (the document reports `changed`), and HEAD is
   // a reference every repository has.
   const resolved = resolveChangedRef({ explicit: values.changed, projectDir })
-    ?? (mode === 'save-paths' ? { ref: 'HEAD', from: 'save-paths', required: false } : null);
+    ?? (aimed ? { ref: 'HEAD', from: values.concern ? `concern ${values.concern}` : 'save-paths', required: false } : null);
   if (!resolved) {
     io.err('sweep needs a reference to measure the change against: --changed <ref> (e.g. origin/main), or set TESTGUARD_CHANGED_REF. CI bases and a safe local remote default or differently named upstream are detected automatically. Or sweep the write surface instead with --save-paths.');
     return 3;
@@ -46,34 +57,52 @@ export async function sweepCommand({ projectDir, values, version }, io) {
   }
   if (mode === 'changed' && !resolved.required && !values.json && !values.quiet) io.err(`sweep: comparing against ${resolved.ref} (${resolved.from})`);
 
-  const doc = await sweep({
-    projectDir,
-    ref: resolved.ref,
-    mode,
-    includeDirty: values['include-dirty'],
-    exclude: values.exclude ?? [],
-    cap,
-    confirmRuns,
-    budgetMs,
-    runnerCommand: values['runner-cmd'],
-    runnerName: values.runner,
-    nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
-    toolVersion: version,
-    claimsPath: values.claims ? resolve(values.claims) : undefined,
-    ignorePath: values.ignore ? resolve(values.ignore) : undefined,
-    onStage: !values.quiet && !values.json && process.stderr.isTTY
+  let doc;
+  try {
+    doc = await sweep({
+      projectDir,
+      ref: resolved.ref,
+      mode,
+      concern: values.concern,
+      concernsPath: values.concerns ? resolve(values.concerns) : undefined,
+      includeDirty: values['include-dirty'],
+      exclude: values.exclude ?? [],
+      cap,
+      confirmRuns,
+      budgetMs,
+      runnerCommand: values['runner-cmd'],
+      runnerName: values.runner,
+      nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+      toolVersion: version,
+      claimsPath: values.claims ? resolve(values.claims) : undefined,
+      ignorePath: values.ignore ? resolve(values.ignore) : undefined,
+      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,
-    onWarn: (m) => { if (!values.quiet) io.err(`warning: ${m}`); },
-  });
+      onWarn: (m) => { if (!values.quiet) io.err(`warning: ${m}`); },
+    });
+  } catch (e) {
+    // A concern named on the command line that this project does not declare
+    // is a usage error, not a precondition failure: nothing about the
+    // repository is wrong.
+    if (e instanceof ConcernError) {
+      io.err(e.message);
+      return 3;
+    }
+    throw e;
+  }
   if (process.stderr.isTTY && !values.quiet && !values.json) process.stderr.write('\r\x1b[K');
 
+  const { evidence, ...document } = doc;
   const outPath = values.out ? resolve(values.out) : sweepPath(projectDir);
-  writeSpecDoc('sweep', outPath, doc);
+  writeSpecDoc('sweep', outPath, document);
+  // Written only when something was actually probed: an empty document would
+  // teach the next run that every class is unproductive.
+  if (evidence?.records?.length) writeSpecDoc('evidence', sweepEvidencePath(projectDir), evidence);
   if (values.json) {
-    io.out(JSON.stringify(doc, null, 2));
+    io.out(JSON.stringify(document, null, 2));
   } else {
-    io.out(renderSweep(doc, { limit: Number(values.max) || 20 }));
+    io.out(renderSweep(document, { limit: Number(values.max) || 20 }));
     if (!values.quiet) io.out(`\nsweep: ${outPath}`);
   }
   return doc.exitCode;

package/src/probe/probe.mjs

@@ -16,6 +16,7 @@ import { classifyIndependence } from './independence.mjs';
 import { escalationStart, foldEscalationRun, escalationResult, flakeRate, killersFromRuns, subjectOf, isReusable } from './attribution.mjs';
 import { hashFile, sha256 } from '../util/hash.mjs';
 import { fingerprint } from '../../spec/lib/fingerprint.mjs';
+import { persistenceSignalsFor } from '../supply/persistence.mjs';
 
 
 /** Is `child` the same file as `root`, or under it? Both must already be real paths. */
@@ -485,13 +486,19 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, is
     detail.independence = classifyIndependence({ dir: historyDir, ref: historyRef, targetFile: toRepoPath(fault.file), defenders: (killers.length ? killers : defenders).map(toRepoPath) });
   }
 
+  // Why a survivor on a write path was missed: each defender that mocks the
+  // persistence layer, with its assertion mix. Descriptive, never predictive —
+  // it is attached to a verdict already reached and selects nothing. The sweep
+  // document carried this alone until claimspec v1 admitted it to the evidence.
+  const allSignals = [...signals, ...persistenceSignalsFor({ verdict, fault, defenders, projectDir: iso.projectDir })];
+
   return {
     fingerprint: fingerprint({ claimId: claim.id, subjectId: fault.id, file: fault.file, verdict }),
     claim: { id: claim.id, statement: claim.statement, severity: claim.severity, source: claim.source, producedBy: claim.producedBy },
     subject,
     verdict,
     detail,
-    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
+    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(allSignals.length ? { signals: allSignals } : {}) },
     inputs,
     rank: rank({ severity: claim.severity, sourceKind: claim.source.kind, blast, independence: detail.independence?.class }),
   };

package/src/probe/pyimports.mjs

@@ -49,11 +49,18 @@ export function pyModuleName(projectDir, rel) {
  * `from x import (a, b)` collapsed onto one line so the names are visible.
  */
 function logicalLines(source) {
-  const raw = source.split('\n');
+  // A trailing comment is stripped from every physical line BEFORE anything
+  // is joined or split. An import statement carries no string literal, so a
+  // `#` on one always starts a comment — and `from pkg import cli, demo  # noqa: E402`
+  // is the idiom of every src-layout test that inserts into sys.path before
+  // importing. Measured on a real suite: the comment was kept inside the LAST
+  // name, which then failed the identifier test, so `demo` was never seen and
+  // its tests were reported as no cover. 72 import lines in one suite.
+  const raw = source.split('\n').map((l) => l.replace(/#.*$/, ''));
   const out = [];
   for (let i = 0; i < raw.length; i++) {
     let line = raw[i];
-    if (COMMENT.test(line)) continue;
+    if (!line.trim()) continue;
     while (/\\\s*$/.test(line) && i + 1 < raw.length) line = line.replace(/\\\s*$/, ' ') + raw[++i];
     if (/^\s*from\s/.test(line) && line.includes('(') && !line.includes(')')) {
       // Bounded: a malformed file must not make this loop to the end of a large source.

package/src/scaffold/producers.python.mjs

@@ -60,6 +60,54 @@ function isIncomplete(line) {
   return depth > 0;
 }
 
+/**
+ * The bracket depth at the START of every line, for the whole file.
+ *
+ * `isIncomplete()` answers "does this line leave a bracket open"; this answers
+ * the other half, "does this line sit inside one opened above it". Measured on
+ * a real Python CLI: 77 of 600 proposals were a `statement-deleted` on a
+ * continuation line — `help="...")` inside an `add_argument(` — and none of
+ * them compiled. The tokenizer's exact depth agreed on 74 of the 77 and
+ * flagged no valid proposal: a dict entry or a call argument is inside a
+ * bracket by definition and keeps its own producer.
+ *
+ * Line-oriented, no AST: triple-quoted strings are tracked across lines so a
+ * docstring's parentheses cannot leave the rest of the file "inside" forever,
+ * and single-line strings and comments are skipped. Memoised per `lines`
+ * array because the scaffold calls the producer once per line.
+ */
+const DEPTHS = new WeakMap();
+export function depthBefore(lines) {
+  if (DEPTHS.has(lines)) return DEPTHS.get(lines);
+  const out = new Array(lines.length);
+  let depth = 0;
+  let triple = null;
+  for (let i = 0; i < lines.length; i++) {
+    out[i] = depth;
+    const line = lines[i];
+    for (let j = 0; j < line.length;) {
+      if (triple) {
+        if (line.startsWith(triple, j)) { triple = null; j += 3; } else j += line[j] === '\\' ? 2 : 1;
+        continue;
+      }
+      const ch = line[j];
+      if (ch === '#') break;
+      if (line.startsWith('"""', j) || line.startsWith("'''", j)) { triple = line.slice(j, j + 3); j += 3; continue; }
+      if (ch === '"' || ch === "'") {
+        let k = j + 1;
+        while (k < line.length && line[k] !== ch) k += line[k] === '\\' ? 2 : 1;
+        j = k + 1; // an unterminated string runs to the end of the line
+        continue;
+      }
+      if (ch === '(' || ch === '[' || ch === '{') depth++;
+      else if (ch === ')' || ch === ']' || ch === '}') depth = Math.max(0, depth - 1);
+      j++;
+    }
+  }
+  DEPTHS.set(lines, out);
+  return out;
+}
+
 /** The function a `def` line opens, or null. */
 export function functionHead(line) {
   const m = DEF_LINE.exec(line);
@@ -166,9 +214,13 @@ export function proposalsForLine(lines, i, ctx = {}) {
   if (!line.trim() || COMMENT.test(line) || DEFINITION.test(line)) return out;
   const params = ctx.params ?? new Set();
   const indent = ' '.repeat(indentOf(line) ?? 0);
+  // A line inside a bracket opened above it is an argument or an entry, never
+  // a statement: `pass` there does not parse. The shapes that keep their own
+  // producers on such a line (a dropped field, a swapped argument) are below.
+  const inside = depthBefore(lines)[i] > 0;
 
   const ifm = IF_LINE.exec(line);
-  if (ifm && isGuard(ifm[4], lines, i)) {
+  if (!inside && ifm && isGuard(ifm[4], lines, i)) {
     if (ifm[4]) {
       // `if not allowed: raise …` — the whole guard is this one line.
       out.push({ faultClass: 'statement-deleted', description: `Guard removed: \`${line.trim()}\` no longer runs.`, replace: `${indent}pass` });
@@ -183,7 +235,7 @@ export function proposalsForLine(lines, i, ctx = {}) {
     out.push({ faultClass: 'return-altered', description: `Check always passes: \`return ${rm[2]}\` becomes \`return True\`.`, replace: `${rm[1]}return True` });
   }
 
-  const complete = !isIncomplete(line);
+  const complete = !inside && !isIncomplete(line);
   if (complete && CHECK_CALL.test(line)) {
     out.push({ faultClass: 'call-removed', description: `Check call removed: \`${line.trim()}\` no longer runs.`, replace: `${indent}pass` });
   } else if (complete && MUTATION.test(line)) {

package/src/supply/concerns.mjs

@@ -0,0 +1,162 @@
+/**
+ * A concern: one sentence a human writes, that generates faults across a whole
+ * surface.
+ *
+ * The rung between "nothing written" and "a claim per behaviour". A claim names
+ * one promise and the faults that would break it; that is precise and it is why
+ * a repository with two hundred screens never finishes writing them. A concern
+ * names a KIND of promise — "every write persists the data it was given" — and
+ * says where to look for it and which shapes of break are relevant. One
+ * sentence, two hundred screens.
+ *
+ * The idea is Meta's. ACH has an engineer describe an area of concern in plain
+ * text, generates faults specific to it, and gates every step by execution
+ * ("Mutation-Guided LLM-based Test Generation at Meta", Foster et al., FSE
+ * 2025). What is taken here is the UNIT — the concern as the thing a human
+ * writes — not their generator.
+ *
+ * NO MODEL IS REQUIRED, and that is deliberate. A concern's useful core is a
+ * named scope plus a producer selection, both of which the mechanical
+ * producers already satisfy. An LLM can later propose faults a line-oriented
+ * producer cannot see, as an ADDITIONAL source for a concern that already
+ * works — rather than as the thing the rung depends on. That keeps every
+ * verifying command offline, which is the property this tool is least willing
+ * to trade.
+ *
+ * A concern is NOT a claim and never becomes one by itself. It says where to
+ * look; the probe says what it found; a human states the sentence worth
+ * defending. Nothing here is written to `testguard.claims.json`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { saveSurface } from './savepath.mjs';
+import { globToRegExp, walk } from '../util/glob.mjs';
+
+export const defaultConcernsPath = (projectDir) => join(projectDir, 'testguard.concerns.json');
+
+/**
+ * The concerns every project gets without writing anything.
+ *
+ * Two, because two are the ones whose targets can be enumerated honestly. An
+ * authorization concern would need a heuristic for "which files check
+ * permissions", and a guess there produces exactly the non-actionable noise
+ * that gets a check switched off. A project that knows its own auth layer can
+ * say so with a `glob` target in three lines; this file will not guess for it.
+ */
+export const BUILTIN_CONCERNS = Object.freeze([
+  Object.freeze({
+    id: 'SAVE-PERSISTS',
+    statement: 'Every write to storage persists the data it was given.',
+    severity: 'high',
+    targets: { kind: 'write-sites' },
+    // The shapes that break a persisted payload. Measured on a real
+    // application: 12 of 12 surviving faults on the persistence path were a
+    // field dropped from the payload, so the list leads with that.
+    faultClasses: ['field-dropped', 'call-removed', 'statement-deleted', 'literal-changed'],
+    builtin: true,
+  }),
+  Object.freeze({
+    id: 'CHANGED-CODE',
+    statement: 'Code changed in this branch is defended by something.',
+    severity: 'medium',
+    targets: { kind: 'changed' },
+    // Everything: a diff has no shape to narrow by.
+    faultClasses: null,
+    builtin: true,
+  }),
+]);
+
+/**
+ * Load the project's concerns, with the built-ins behind them.
+ *
+ * A project concern with the same id as a built-in REPLACES it, so a team can
+ * retune `SAVE-PERSISTS` for an ORM this tool does not recognise without
+ * forking anything. Shadowing is recorded rather than silent: a concern that
+ * quietly replaced a default would be the kind of surprise that costs an
+ * afternoon.
+ */
+export function loadConcerns(projectDir, { path } = {}) {
+  const p = path ?? defaultConcernsPath(projectDir);
+  let project = [];
+  let source = null;
+  if (existsSync(p)) {
+    const doc = JSON.parse(readFileSync(p, 'utf8'));
+    project = doc.concerns ?? [];
+    source = p;
+  }
+  const overridden = new Set(project.map((c) => c.id));
+  const concerns = [
+    ...project.map((c) => ({ ...c, builtin: false })),
+    ...BUILTIN_CONCERNS.filter((c) => !overridden.has(c.id)),
+  ];
+  return {
+    concerns,
+    // The project's own entries, exactly as written. Validation runs against
+    // these: the enriched objects above carry a `builtin` marker this tool
+    // added, and a schema that refuses unknown properties is right to reject
+    // them. Validating what we constructed instead of what the user wrote
+    // would report OUR bug as THEIR malformed file.
+    raw: project.map(({ builtin, ...c }) => c),
+    source,
+    shadowed: BUILTIN_CONCERNS.filter((c) => overridden.has(c.id)).map((c) => c.id),
+  };
+}
+
+/** One concern by id, or null. Ids are matched exactly: a near-miss is a typo, not an intention. */
+export const concernById = (concerns, id) => concerns.find((c) => c.id === id) ?? null;
+
+/**
+ * The files a concern applies to.
+ *
+ * `write-sites` asks the enumerator; `glob` matches the project's own paths;
+ * `changed` returns null, meaning "the caller's diff decides" — a concern does
+ * not get to re-derive what the gate already computed.
+ */
+export function targetsFor(projectDir, concern, { changedFiles } = {}) {
+  const t = concern.targets ?? { kind: 'changed' };
+  if (t.kind === 'write-sites') return saveSurface(projectDir).files.map((f) => f.file);
+  if (t.kind === 'glob') {
+    // Against the whole project, never the diff. A concern like "every admin
+    // route refuses an unauthorised caller" is about the admin routes, not
+    // about the ones that happened to change today — and pooling from the diff
+    // made such a concern report clean on a clean branch, which is the exact
+    // false reassurance a concern exists to prevent.
+    const res = (t.globs ?? []).map(globToRegExp);
+    return walk(projectDir).filter((f) => res.some((re) => re.test(f)));
+  }
+  return changedFiles ?? null;
+}
+
+/**
+ * Keep only the faults whose class this concern cares about.
+ *
+ * `faultClasses: null` means every class — the honest default for a concern
+ * with no shape to narrow by. Narrowing is what makes one sentence useful
+ * across two hundred files: a persistence concern that also reported every
+ * altered return value would bury the payload findings it exists to surface.
+ */
+export function filterByConcern(candidates, concern) {
+  if (!concern?.faultClasses) return candidates;
+  const keep = new Set(concern.faultClasses);
+  return candidates.filter((c) => keep.has(c.fault.faultClass));
+}
+
+/** The concerns as text, for someone deciding which to sweep. */
+export function renderConcerns({ concerns, source, shadowed }) {
+  const out = [];
+  out.push(source ? `${concerns.length} concern${concerns.length === 1 ? '' : 's'} (${source}, plus the built-ins)` : `${concerns.length} built-in concern${concerns.length === 1 ? '' : 's'} — none declared in this project.`);
+  out.push('');
+  for (const c of concerns) {
+    const shape = c.targets?.kind === 'glob' ? `glob ${(c.targets.globs ?? []).join(', ')}` : c.targets?.kind ?? 'changed';
+    out.push(`  ${c.id}${c.builtin ? '  (built-in)' : ''}`);
+    out.push(`    ${c.statement}`);
+    out.push(`    targets: ${shape} · faults: ${c.faultClasses ? c.faultClasses.join(', ') : 'every class'}`);
+    out.push('');
+  }
+  if (shadowed.length) out.push(`This project replaces the built-in ${shadowed.join(', ')}.`);
+  if (!source) {
+    out.push('Declare your own in testguard.concerns.json. A concern is one sentence and a');
+    out.push('scope: it says where to look, never what is true. Only a claim does that.');
+  }
+  return out.join('\n');
+}

package/src/supply/feedback.mjs

@@ -0,0 +1,146 @@
+/**
+ * What this project's own runs say about which faults are worth proposing.
+ *
+ * `select.mjs` ships a productivity prior measured on one real application.
+ * That is a reasonable starting point and a poor stopping point: the classes
+ * that survive a Next.js suite are not the classes that survive a Python one,
+ * and Google's mutation service got from a 15% productive rate to 89% on
+ * exactly this — feedback, accumulated over years, refining which candidates
+ * are worth a developer's attention ("Practical Mutation Testing at Scale",
+ * Petrović et al., 2021). The static table is the part of that idea this tool
+ * had not yet taken.
+ *
+ * THE FEEDBACK IS ALREADY ON DISK. Every evidence record carries a
+ * `faultClass` and a `verdict`, so "how often does a fault of this class
+ * survive here" is a tally, not a new thing to capture. There is no click to
+ * collect and no state to maintain: a project that has probed anything has
+ * already said what its own productive classes are.
+ *
+ * WHY THIS ESTIMATOR AND NOT A BETTER-SOUNDING ONE. The combination below is a
+ * Beta-Binomial posterior mean, and a posterior mean is what minimises Brier
+ * and log score in expectation — it is a STRICTLY PROPER estimate, which is
+ * the only kind that cannot be improved by reporting something other than an
+ * honest probability. Optimising the ordering for accuracy or F1 instead would
+ * maximise the number of survivors found while destroying the calibration of
+ * the number attached to each, which is the documented failure mode of naive
+ * optimisation and the reason Laya trains against proper scoring rules. If
+ * this file is ever changed to rank by anything but an honest probability,
+ * that is the invariant being broken.
+ *
+ * Pure apart from reading the documents it is given.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { MEASURED_PRODUCTIVITY } from './select.mjs';
+
+/** The evidence a project may have produced, in the order they are most relevant. */
+export const EVIDENCE_PATHS = Object.freeze([
+  // A sweep probes MACHINE-proposed faults, the same distribution the ranker
+  // orders, so it is the closest observation available.
+  '.testguard/sweep-evidence.json',
+  // The canonical probe is human-authored faults: a real observation of the
+  // same classes, drawn slightly differently, and still worth counting.
+  '.testguard/evidence.json',
+]);
+
+/**
+ * Survival counts per fault class from one evidence document.
+ *
+ * Only `killed` and `survived` are counted. `nocover`, `unverifiable`,
+ * `fault-invalid`, `timeout` and `flaky-defender` say nothing about whether a
+ * fault of that class would be NOTICED — they say the question could not be
+ * asked — and folding them in either direction would be inventing data.
+ */
+export function tallyEvidence(doc) {
+  const by = {};
+  for (const r of doc?.records ?? []) {
+    const cls = r.subject?.faultClass;
+    if (!cls) continue;
+    if (r.verdict !== 'killed' && r.verdict !== 'survived') continue;
+    const e = (by[cls] ??= { survived: 0, n: 0 });
+    e.n += 1;
+    if (r.verdict === 'survived') e.survived += 1;
+  }
+  return by;
+}
+
+/** Merge tallies from several documents. Counts add; nothing is averaged twice. */
+export function mergeTallies(tallies) {
+  const by = {};
+  for (const t of tallies) {
+    for (const [cls, e] of Object.entries(t)) {
+      const m = (by[cls] ??= { survived: 0, n: 0 });
+      m.survived += e.survived;
+      m.n += e.n;
+    }
+  }
+  return by;
+}
+
+/**
+ * The productivity table to rank with: this project's own observations, with
+ * the shipped measurement as the prior they are shrunk toward.
+ *
+ * The shipped numbers become pseudo-counts rather than a competing estimate —
+ * `n` of them, so a class measured on twelve faults elsewhere carries the
+ * weight of twelve observations here and no more. A project with its own
+ * hundred records therefore overrides the shipping default; a project with
+ * three nudges it.
+ *
+ * `shipped` is injectable so the combination can be tested without depending
+ * on whatever the current measurement happens to be.
+ */
+export function combinedProductivity(local, shipped = MEASURED_PRODUCTIVITY) {
+  const out = {};
+  for (const cls of new Set([...Object.keys(shipped), ...Object.keys(local)])) {
+    const s = shipped[cls];
+    const l = local[cls];
+    const priorSurvived = s ? s.p * s.n : 0;
+    const priorN = s ? s.n : 0;
+    const n = priorN + (l?.n ?? 0);
+    if (n === 0) continue;
+    const survived = priorSurvived + (l?.survived ?? 0);
+    out[cls] = { p: survived / n, n, observed: l?.n ?? 0 };
+  }
+  return out;
+}
+
+/** Read whichever evidence documents this project has. Missing or malformed ones are skipped, never guessed at. */
+export function readEvidence(projectDir, paths = EVIDENCE_PATHS) {
+  const docs = [];
+  for (const rel of paths) {
+    const p = join(projectDir, rel);
+    if (!existsSync(p)) continue;
+    try {
+      docs.push({ path: rel, doc: JSON.parse(readFileSync(p, 'utf8')) });
+    } catch {
+      // A document this tool cannot parse is not evidence of anything. It is
+      // skipped rather than defaulted, because a ranking built on a guess
+      // about a corrupt file is worse than one built on the shipped prior.
+    }
+  }
+  return docs;
+}
+
+/**
+ * The learned table plus what it was learned from, so a report can say whether
+ * an ordering came from this project or from the shipping default. An ordering
+ * nobody can trace is a number nobody should trust.
+ */
+export function learnedProductivity(projectDir, { paths, shipped } = {}) {
+  const docs = readEvidence(projectDir, paths);
+  const local = mergeTallies(docs.map((d) => tallyEvidence(d.doc)));
+  const observed = Object.values(local).reduce((a, e) => a + e.n, 0);
+  return {
+    table: combinedProductivity(local, shipped),
+    sources: docs.map((d) => d.path),
+    observed,
+    classes: Object.keys(local).sort(),
+  };
+}
+
+/** One line for a report: where the ordering came from. */
+export function renderLearned(learned) {
+  if (learned.observed === 0) return 'ordering: the shipped productivity prior — this project has no probed evidence yet.';
+  return `ordering: ${learned.observed} probed fault${learned.observed === 1 ? '' : 's'} of this project's own, across ${learned.classes.length} class${learned.classes.length === 1 ? '' : 'es'} (${learned.sources.join(', ')}), shrunk toward the shipped prior.`;
+}