testguard-cli 0.5.0 → 0.7.0

package/src/scaffold/producers.python.mjs

@@ -0,0 +1,209 @@
+/**
+ * Mechanical fault producers for Python. Deterministic, line-oriented, no AST,
+ * no LLM — the same contract as `producers.mjs`, expressed in the syntax the
+ * file is actually written in.
+ *
+ * The fault classes are the ones the spec already closes over; none is new.
+ * The two JSX shapes (`element-removed`, `handler-dropped`) have no Python
+ * meaning and are absent rather than faked.
+ *
+ * One deliberate difference from JavaScript: a statement is removed by
+ * replacing it with `pass`, not by deleting the line. A block whose only
+ * statement is deleted is an IndentationError in Python, and a fault that
+ * cannot compile is a `fault-invalid` verdict — a wasted probe run that says
+ * nothing about the tests. `pass` removes the behaviour and always parses.
+ */
+
+const COMMENT = /^\s*#/;
+
+// `if <cond>:` and `elif <cond>:`, with an optional same-line body.
+const IF_LINE = /^(\s*)(el)?if\s+(.+?)\s*:\s*(\S.*)?$/;
+const GUARD_BODY = /\braise\b|\breturn\b|\babort\b|\bsys\.exit\b|\bFalse\b|\bNone\b|\bHTTPException\b|\b4\d\d\b/;
+const RETURN_CHECK = /^(\s*)return\s+(.+?)\s*$/;
+const CHECK_EXPR = /(==|!=|\bin\b|\bis\b|\bnot\b|\band\b|\bor\b|\.startswith\(|\.endswith\(|\.match\(|\.search\(|\.fullmatch\(|isinstance\(|\.issubset\(|>=|<=|>|<)/;
+const CHECK_CALL = /^\s*(?:await\s+)?(?:[\w.]+\.)?(verify|validate|assert|check|require|ensure|authoriz|authentic|rate_limit|throttle|enforce|guard|sanitiz|escape|audit)\w*\s*\(.*\)\s*$/i;
+const MUTATION = /^\s*(?!(?:return|if|elif|else|for|while|with|try|except|finally|raise|assert|import|from|def|class|yield|pass|global|nonlocal)\b)[\w.\[\]'"]+\s*(=|\+=|-=|\|=|&=)\s*(?!=)\S.*$/;
+
+const FLAG_TRUE = /\b(verify|secure|httponly|check_hostname|require_tls|validate_certs|strict|signed|use_tls|ssl)\s*=\s*True\b/i;
+const SAME_SITE = /\b(samesite)\s*=\s*(['"])(strict|lax)\2/i;
+const COST_NUM = /\b(\w*(?:cost|rounds|iterations|work_factor)\w*)\s*=\s*(\d+)\b/i;
+const WINDOW_NUM = /\b(\w*(?:ttl|expir|tolerance|window|max_age|maxage|timeout|limit|attempts|length|min_length|clock_skew|skew|leeway)\w*)\s*=\s*(\d+)\b/i;
+
+const DEF_LINE = /^(\s*)(?:async\s+)?def\s+([\w]+)\s*\(/;
+// A definition is not a call site and not a statement: `def f(x)` must never
+// be read as `f(x)` with a swappable argument.
+const DEFINITION = /^\s*(?:async\s+)?(?:def|class)\b/;
+
+/**
+ * Does this line leave a bracket open, or continue onto the next?
+ *
+ * `COLOURS = {` is an assignment by every regex here, but replacing it with
+ * `pass` orphans the lines below it and the file stops parsing. Python has no
+ * statement terminator to lean on the way the JavaScript producers lean on
+ * `;`, so the balance is counted instead. A fault that cannot compile is a
+ * `fault-invalid` verdict: a probe run spent saying nothing about the tests.
+ */
+function isIncomplete(line) {
+  const code = line.replace(/#.*$/, '');
+  if (/\\\s*$/.test(code)) return true;
+  let depth = 0;
+  let quote = null;
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i];
+    if (quote) {
+      if (ch === '\\') i++;
+      else if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") quote = ch;
+    else if (ch === '(' || ch === '[' || ch === '{') depth++;
+    else if (ch === ')' || ch === ']' || ch === '}') depth--;
+  }
+  return depth > 0;
+}
+
+/** The function a `def` line opens, or null. */
+export function functionHead(line) {
+  const m = DEF_LINE.exec(line);
+  return m ? m[2] : null;
+}
+
+/** The indentation of a line, in characters. Blank lines have none. */
+export const indentOf = (line) => (line.trim() ? line.length - line.trimStart().length : null);
+
+/** Parameter names of a `def` line, without `self`/`cls`, defaults or annotations. */
+export function functionParams(line) {
+  const m = /^\s*(?:async\s+)?def\s+\w+\s*\(([^)]*)\)/.exec(line);
+  if (!m) return [];
+  return m[1]
+    .split(',')
+    .map((p) => p.trim().replace(/^[*]+/, '').split(/[:=]/)[0].trim())
+    .filter((p) => /^\w+$/.test(p) && p !== 'self' && p !== 'cls');
+}
+
+export const isComment = (line) => COMMENT.test(line);
+
+/** Does this `if` guard something — does its body reject, raise or return? */
+function isGuard(sameLineBody, lines, i) {
+  if (sameLineBody) return GUARD_BODY.test(sameLineBody);
+  const next = lines[i + 1] ?? '';
+  return GUARD_BODY.test(next);
+}
+
+// ── field-dropped ─────────────────────────────────────────────────────────
+// A dict literal counts as a payload when its opening line says so: it is
+// returned, assigned to a payload-ish name, or passed to a persistence or
+// transport call. A TypedDict or a class body is never a payload — dropping a
+// key there changes a type, not a behaviour.
+const PAYLOAD_OPENER = /(\breturn\s*\{\s*$|\b(?:body|payload|input|item|params|data|record|row|attrs|attributes|values|fields|patch|update|updates|changes|doc|document|entity|dto|request|response|options|args|props|config|settings|message|event|entry|audit|claims|headers|context)\w*\s*=\s*\{\s*$|\.(?:save|update|put|patch|post|send|write|insert|upsert|create|set|publish|emit|dispatch|persist|store|log|audit|record|track|notify|write_audit)\w*\s*\(\s*(?:[^,{]*,\s*)*\{\s*$)/i;
+const DICT_ENTRY = /^(\s*)(['"])([\w.-]+)\2\s*:\s*(.+?),\s*$/;
+const ALLOWLIST_OPENER = /\b\w*(?:fields|keys|allowed|writable|columns|attributes|props|allowlist|whitelist|editable|mutable|updatable|permitted|required|scopes|roles)\w*\s*=\s*[\[({]\s*$/i;
+const STRING_ENTRY = /^\s*(['"])[^'"]+\1\s*,\s*$/;
+
+function fieldDropProposals(lines, i) {
+  const line = lines[i];
+  const entry = DICT_ENTRY.exec(line);
+  const isStringEntry = STRING_ENTRY.test(line);
+  if (!entry && !isStringEntry) return [];
+  const lineIndent = indentOf(line);
+  for (let j = i - 1; j >= 0 && j >= i - 40; j--) {
+    const opener = lines[j];
+    if (!opener.trim() || COMMENT.test(opener)) continue;
+    const openerIndent = indentOf(opener);
+    // The first line above that is less indented opens the literal this entry
+    // belongs to. Anything at the same indentation is a sibling entry.
+    if (openerIndent !== null && lineIndent !== null && openerIndent < lineIndent) {
+      if (entry && PAYLOAD_OPENER.test(opener)) {
+        return [{ faultClass: 'field-dropped', description: `Field dropped: \`${entry[3]}\` no longer appears in the object built at line ${j + 1}.`, replace: '' }];
+      }
+      if (isStringEntry && ALLOWLIST_OPENER.test(opener)) {
+        return [{ faultClass: 'field-dropped', description: `Entry removed from the list at line ${j + 1}: \`${line.trim().replace(/,$/, '')}\`.`, replace: '' }];
+      }
+      return [];
+    }
+  }
+  return [];
+}
+
+// ── argument-swapped ──────────────────────────────────────────────────────
+// A call is kept and one parameter-derived argument is swapped for a trivial
+// value, so the call still happens and still proves nothing.
+const CALL_WITH_ARGS = /\b([\w.]+)\s*\(([^()]*)\)/g;
+
+function argumentSwapProposals(lines, i, params) {
+  const line = lines[i];
+  if (!params.size || COMMENT.test(line)) return [];
+  const out = [];
+  for (const m of line.matchAll(CALL_WITH_ARGS)) {
+    const args = m[2];
+    if (!args.trim()) continue;
+    const parts = args.split(',').map((a) => a.trim());
+    for (let n = 0; n < parts.length; n++) {
+      const arg = parts[n];
+      const named = /^(\w+)\s*=\s*(\w+)$/.exec(arg);
+      const bare = /^\w+$/.test(arg) ? arg : null;
+      const value = named ? named[2] : bare;
+      if (!value || !params.has(value)) continue;
+      const trivial = named ? `${named[1]}=None` : 'None';
+      const swapped = [...parts.slice(0, n), trivial, ...parts.slice(n + 1)].join(', ');
+      out.push({
+        faultClass: 'argument-swapped',
+        description: `Call kept, argument neutralised: \`${m[1]}(…)\` receives ${trivial} in place of \`${arg}\`.`,
+        replace: line.replace(m[0], `${m[1]}(${swapped})`),
+      });
+      break; // one proposal per call is enough for a human to judge
+    }
+  }
+  return out;
+}
+
+/**
+ * Every fault this line supports. `ctx.params` is the enclosing function's
+ * parameter names; `ctx.fieldDrops` disables payload shapes in files where a
+ * dict literal is data rather than something the product sends.
+ */
+export function proposalsForLine(lines, i, ctx = {}) {
+  const out = [];
+  const line = lines[i];
+  if (!line.trim() || COMMENT.test(line) || DEFINITION.test(line)) return out;
+  const params = ctx.params ?? new Set();
+  const indent = ' '.repeat(indentOf(line) ?? 0);
+
+  const ifm = IF_LINE.exec(line);
+  if (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` });
+    } else {
+      out.push({ faultClass: 'condition-forced', description: `Guard never triggers: \`${ifm[2] ?? ''}if ${ifm[3].trim()}\` becomes \`${ifm[2] ?? ''}if False\`.`, replace: `${ifm[1]}${ifm[2] ?? ''}if False:` });
+    }
+    return out; // an `if` line is not also a mutation, a return or a call
+  }
+
+  const rm = RETURN_CHECK.exec(line);
+  if (rm && CHECK_EXPR.test(rm[2]) && !/^(await|yield)\b/.test(rm[2])) {
+    out.push({ faultClass: 'return-altered', description: `Check always passes: \`return ${rm[2]}\` becomes \`return True\`.`, replace: `${rm[1]}return True` });
+  }
+
+  const complete = !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)) {
+    out.push({ faultClass: 'statement-deleted', description: `State change removed: \`${line.trim()}\` no longer runs.`, replace: `${indent}pass` });
+  }
+
+  let m;
+  if ((m = FLAG_TRUE.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `Security flag flipped: \`${m[1]}=True\` becomes \`${m[1]}=False\`.`, replace: line.replace(m[0], `${m[1]}=False`) });
+  }
+  if ((m = SAME_SITE.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `samesite weakened: \`${m[3]}\` becomes \`none\`.`, replace: line.replace(m[0], `${m[1]}=${m[2]}none${m[2]}`) });
+  }
+  if ((m = COST_NUM.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `Work factor collapsed: \`${m[1]}\` ${m[2]} becomes 1.`, replace: line.replace(m[0], `${m[1]}=1`) });
+  } else if ((m = WINDOW_NUM.exec(line))) {
+    out.push({ faultClass: 'literal-changed', description: `Window widened ×1000: \`${m[1]}\` ${m[2]} becomes ${Number(m[2]) * 1000}.`, replace: line.replace(m[0], `${m[1]}=${Number(m[2]) * 1000}`) });
+  }
+
+  if (ctx.fieldDrops !== false) out.push(...fieldDropProposals(lines, i));
+  out.push(...argumentSwapProposals(lines, i, params));
+  return out;
+}

package/src/scaffold/scaffold.mjs

@@ -1,14 +1,100 @@
 import { readFileSync } from 'node:fs';
 import { basename, extname, join } from 'node:path';
-import { proposalsForLine, functionHead } from './producers.mjs';
+import { proposalsForLine, functionHead, functionParams } from './producers.mjs';
+import * as py from './producers.python.mjs';
 import { locate } from '../probe/inject.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
 import { validate } from '../../spec/lib/validate.mjs';
 
 const ANNOTATION = /@claim\s+([A-Za-z0-9]+(?:[._]?[A-Za-z0-9]+)*-[A-Za-z0-9._-]*[A-Za-z0-9])\b/;
+// field-dropped is never proposed inside tests, fixtures or migrations: an
+// object literal there is data, not a payload the product writes.
+const NO_FIELD_DROPS = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(__tests__|__fixtures__|__mocks__|fixtures|migrations)\//;
+// Python names its tests by file rather than by a dotted suffix, so the JS
+// rule would not recognise one. Kept separate so adding Python cannot quietly
+// change which proposals a JavaScript file gets.
+const NO_FIELD_DROPS_PY = /(^|\/)(test[^/]*\.py|[^/]*_test\.py|conftest\.py)$|(^|\/)(tests?|__fixtures__|fixtures|migrations)\//;
 
 const idPart = (s) => s.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').toUpperCase();
 
+const isPython = (file) => file.endsWith('.py');
+
+/**
+ * JavaScript line scan: enclosing function tracked by brace depth, `@claim`
+ * annotations read from `//` and `/* *\u002f` comments.
+ */
+function scanJs({ source, lines, fieldDrops, keep, anchor }) {
+  const proposals = [];
+  let offset = 0;
+  let fn = null;
+  let fnDepth = 0;
+  let params = new Set();
+  let depth = 0;
+  let pendingAnnotation = null;
+  lines.forEach((line, i) => {
+    const ann = ANNOTATION.exec(line);
+    if (ann && /^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = ann[1];
+
+    const head = functionHead(line);
+    if (head) {
+      fn = head;
+      fnDepth = depth;
+      params = new Set(functionParams(line));
+    }
+
+    for (const p of proposalsForLine(lines, i, { params, fieldDrops })) {
+      const { hits, occurrence } = anchor(line, offset);
+      const fault = { ...p, find: line, replace: p.replace, expectHits: hits, occurrence, line: i + 1, fn, annotation: pendingAnnotation };
+      if (keep(fault)) proposals.push(fault); // never propose an anchor that would be unverifiable
+    }
+
+    depth += (line.match(/\{/g) ?? []).length - (line.match(/\}/g) ?? []).length;
+    if (fn && depth <= fnDepth && !head) { fn = null; params = new Set(); }
+    if (pendingAnnotation && !ann && !head && line.trim() && !/^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = null;
+    offset += line.length + 1;
+  });
+  return proposals;
+}
+
+/**
+ * Python line scan. Scope is indentation, not braces, and it must be read
+ * BEFORE the line is attributed: a line dedented out of a function belongs to
+ * whatever follows, not to the function that just ended. `@claim` annotations
+ * are read from `#` comments.
+ */
+function scanPython({ source, lines, fieldDrops, keep, anchor }) {
+  const proposals = [];
+  let offset = 0;
+  let fn = null;
+  let fnIndent = 0;
+  let params = new Set();
+  let pendingAnnotation = null;
+  lines.forEach((line, i) => {
+    const indent = py.indentOf(line);
+    if (fn !== null && indent !== null && indent <= fnIndent) { fn = null; params = new Set(); }
+
+    const ann = ANNOTATION.exec(line);
+    if (ann && py.isComment(line)) pendingAnnotation = ann[1];
+
+    const head = py.functionHead(line);
+    if (head) {
+      fn = head;
+      fnIndent = indent ?? 0;
+      params = new Set(py.functionParams(line));
+    }
+
+    for (const p of py.proposalsForLine(lines, i, { params, fieldDrops })) {
+      const { hits, occurrence } = anchor(line, offset);
+      const fault = { ...p, find: line, replace: p.replace, expectHits: hits, occurrence, line: i + 1, fn, annotation: pendingAnnotation };
+      if (keep(fault)) proposals.push(fault);
+    }
+
+    if (pendingAnnotation && !ann && !head && line.trim() && !py.isComment(line)) pendingAnnotation = null;
+    offset += line.length + 1;
+  });
+  return proposals;
+}
+
 /** How many times `find` occurs, and which occurrence the line at `offset` is. */
 function anchorFor(source, find, offset) {
   let hits = 0;
@@ -40,35 +126,9 @@ export function scaffoldFile({ projectDir, file, claimId, existingClaims, toolVe
     return groups.get(key);
   };
 
-  let offset = 0;
-  let fn = null;
-  let fnDepth = 0;
-  let depth = 0;
-  let pendingAnnotation = null;
-  const proposals = [];
-  lines.forEach((line, i) => {
-    const ann = ANNOTATION.exec(line);
-    if (ann && /^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = ann[1];
-
-    const head = functionHead(line);
-    if (head) {
-      fn = head;
-      fnDepth = depth;
-    }
-
-    for (const p of proposalsForLine(lines, i)) {
-      const find = line;
-      const { hits, occurrence } = anchorFor(source, find, offset);
-      const fault = { ...p, find, replace: p.replace, expectHits: hits, occurrence, line: i + 1, fn, annotation: pendingAnnotation };
-      if (locate(source, fault).status !== 'ok') continue; // never propose an anchor that would be unverifiable
-      proposals.push(fault);
-    }
-
-    depth += (line.match(/\{/g) ?? []).length - (line.match(/\}/g) ?? []).length;
-    if (fn && depth <= fnDepth && !head) fn = null;
-    if (pendingAnnotation && !ann && !head && line.trim() && !/^\s*(\/\/|\*|\/\*)/.test(line)) pendingAnnotation = null;
-    offset += line.length + 1;
-  });
+  const fieldDrops = !(isPython(file) ? NO_FIELD_DROPS_PY : NO_FIELD_DROPS).test(file);
+  const scan = isPython(file) ? scanPython : scanJs;
+  const proposals = scan({ source, lines, fieldDrops, keep: (fault) => locate(source, fault).status === 'ok', anchor: (find, offset) => anchorFor(source, find, offset) });
 
   const existing = new Map((existingClaims?.claims ?? []).map((c) => [c.id, c]));
   const usedIds = new Set();

package/src/status/status.mjs

@@ -8,6 +8,7 @@ import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
 import { sortForReport } from '../render.mjs';
 import { computeChangedGate, defaultIgnorePath } from '../gate/changed.mjs';
+import { headSha, isAncestor } from '../git.mjs';
 
 export const faultContentHash = (fault) => sha256(`${fault.find}\n${fault.replace}`);
 
@@ -23,7 +24,13 @@ const P = (projectDir) => ({
  * Reads the claims file, evidence, baseline and the working tree; never
  * trusts a cached verdict whose inputs have changed.
  */
-export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt = new Date().toISOString(), paths = P(projectDir), max = 20, changedRef, includeDirty = false }) {
+/**
+ * `evidence` overrides the project's own evidence file: a document taken on
+ * ANOTHER commit (CI's, fetched as an artifact) is legitimate input. Staleness
+ * is computed from the recorded input hashes exactly as for a local run, so a
+ * foreign document is trusted only for the faults whose inputs still match.
+ */
+export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt = new Date().toISOString(), paths = P(projectDir), max = 20, changedRef, includeDirty = false, evidence: evidenceOverride }) {
   const rel = (p) => relative(projectDir, p) || '.';
   const doc = {
     schemaVersion: 1,
@@ -36,6 +43,7 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     stale: [],
     changedFaults: [],
     findings: [],
+    notes: [],
     paths: {},
   };
   // ── Claim coverage of the change, when a reference is known ──
@@ -79,7 +87,8 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     return doc;
   }
 
-  const hasEvidence = existsSync(paths.evidence);
+  const evidenceFile = evidenceOverride ?? paths.evidence;
+  const hasEvidence = existsSync(evidenceFile);
   const hasProvisional = existsSync(paths.provisional);
   if (hasProvisional) doc.paths.provisionalEvidence = rel(paths.provisional);
   if (!hasEvidence) {
@@ -93,11 +102,29 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     }
     return doc;
   }
-  doc.paths.evidence = rel(paths.evidence);
-  const evidence = readSpecDoc('evidence', paths.evidence);
+  doc.paths.evidence = rel(evidenceFile);
+  doc.evidenceSource = evidenceOverride ? 'provided' : 'local';
+  const evidence = readSpecDoc('evidence', evidenceFile);
+  // A verdict is about a commit. When the evidence describes a different one,
+  // say both: "looks right and is not" is the failure mode this prevents.
+  doc.evidenceHead = evidence.run.repo.snapshot ?? evidence.run.repo.head;
+  const localHead = (() => { try { return headSha(projectDir); } catch { return null; } })();
+  if (localHead) doc.head = localHead;
+
   const baseline = existsSync(paths.baseline) ? readSpecDoc('baseline', paths.baseline) : undefined;
   if (baseline) doc.paths.baseline = rel(paths.baseline);
 
+  // ── Baseline provenance: informational, never a state. A baseline frozen
+  // from a snapshot or a dirty tree names the PARENT of the commit that carries
+  // its tests; once HEAD moved on, say so and name the way to re-stamp. ──
+  if (baseline?.head) {
+    const head = headSha(projectDir);
+    if (head && head !== baseline.head) {
+      if (baseline.snapshot || baseline.dirty) doc.notes.push(`baseline was frozen from a ${baseline.snapshot ? 'working-tree snapshot' : 'dirty tree'} at ${baseline.head.slice(0, 7)}; HEAD is ${head.slice(0, 7)} — it predates the commit that carries its tests. After a clean probe of HEAD reproduces the same fingerprints: testguard baseline --restamp`);
+      else if (!isAncestor(projectDir, baseline.head, head)) doc.notes.push(`baseline head ${baseline.head.slice(0, 7)} is not an ancestor of HEAD ${head.slice(0, 7)} (rewritten or foreign history); re-probe and re-baseline if the fingerprints changed`);
+    }
+  }
+
   // ── Staleness: does the evidence still describe this claims file and this tree? ──
   const probed = new Map(evidence.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]));
   for (const key of faultIndex.keys()) if (!probed.has(key)) doc.stale.push(`fault ${key} has never been probed`);
@@ -124,6 +151,14 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   const counts = {};
   for (const r of evidence.records) counts[r.verdict] = (counts[r.verdict] ?? 0) + 1;
   doc.counts.byVerdict = counts;
+  // L3 independence and observed flakiness, as numbers rather than adjectives.
+  const kills = evidence.records.filter((r) => r.verdict === 'killed');
+  if (kills.length) doc.counts.killedCoAuthored = kills.filter((r) => r.detail.independence?.class === 'co-authored').length;
+  const flaky = evidence.records.filter((r) => r.detail.flakeRate?.failures > 0);
+  if (flaky.length) {
+    doc.counts.flakyDefenderSets = new Set(flaky.map((r) => r.defenders.resolved.join('\n'))).size;
+    doc.counts.worstFlakeRate = Math.max(...flaky.map((r) => r.detail.flakeRate.failures / r.detail.flakeRate.runs));
+  }
   doc.counts.new = g.new.length + g.belowFloor.length;
   doc.counts.baselined = g.baselined.length;
   const ranked = sortForReport([...g.new, ...g.belowFloor, ...g.baselined]);
@@ -170,7 +205,7 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
       action: fixClaim ? 'probe' : 'write-test',
       command: fixClaim
         ? `edit ${top.claimId}/${top.subjectId} in testguard.claims.json, then: testguard probe --claim ${top.claimId} --include-dirty`
-        : `write a test in ${where} that fails on ${top.claimId}/${top.subjectId} and passes on HEAD, then: testguard probe --claim ${top.claimId} --include-dirty`,
+        : `write a test in ${where} that fails on ${top.claimId}/${top.subjectId} and passes on HEAD, then: testguard admit ${defenders[0] ?? '<that test file>'} --claim ${top.claimId}`,
       why: whyByVerdict[top.verdict] ?? `${top.claimId}/${top.subjectId} is ${top.verdict}.`,
       target: { claimId: top.claimId, subjectId: top.subjectId, ...(top.file ? { file: top.file } : {}), verdict: top.verdict },
     };
@@ -187,7 +222,12 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
 }
 
 export function renderStatus(doc) {
-  const lines = [`state: ${doc.state}${doc.provisional ? ' (provisional)' : ''} — ${doc.counts.claims} claims / ${doc.counts.faults} faults` + (doc.counts.byVerdict ? `; ${Object.entries(doc.counts.byVerdict).map(([k, v]) => `${v} ${k}`).join(', ')}; ${doc.counts.new ?? 0} new, ${doc.counts.baselined ?? 0} baselined` : '')];
+  const lines = [];
+  if (doc.evidenceSource === 'provided') {
+    lines.push(`evidence: ${doc.paths.evidence} (provided)` + (doc.evidenceHead ? ` describes ${doc.evidenceHead.slice(0, 7)}` : '') + (doc.head && doc.evidenceHead && doc.head !== doc.evidenceHead ? `; this tree is ${doc.head.slice(0, 7)}` : ''));
+  }
+  lines.push(`state: ${doc.state}${doc.provisional ? ' (provisional)' : ''} — ${doc.counts.claims} claims / ${doc.counts.faults} faults` + (doc.counts.byVerdict ? `; ${Object.entries(doc.counts.byVerdict).map(([k, v]) => `${v} ${k}`).join(', ')}; ${doc.counts.new ?? 0} new, ${doc.counts.baselined ?? 0} baselined` : '')
+  );
   if (doc.changes) {
     const c = doc.changes;
     lines.push(`changes:  ${c.changed} file${c.changed === 1 ? '' : 's'} since ${c.ref}; ${c.evaluated} evaluated, ${c.excluded} excluded, ${c.uncovered.length} unclaimed`);
@@ -197,6 +237,7 @@ export function renderStatus(doc) {
   }
   for (const c of doc.changedFaults) lines.push(`CHANGED   ${c.claimId}/${c.subjectId} edited since it ${c.previousVerdict} (${c.file})`);
   for (const s of doc.stale.slice(0, 8)) lines.push(`stale     ${s}`);
+  for (const n of doc.notes ?? []) lines.push(`note      ${n}`);
   lines.push(`next:     [${doc.next.action}] ${doc.next.command}`);
   lines.push(`why:      ${doc.next.why}`);
   return lines.join('\n');

package/src/util/glob.mjs

@@ -1,7 +1,13 @@
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
-const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.testguard']);
+// Dependency and tool directories. The Python entries are not cosmetic: a
+// virtualenv inside the project holds thousands of `test_*.py` files belonging
+// to installed packages, and without skipping it every one of them would be
+// collected as a test file of the project under probe.
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.testguard',
+  '__pycache__', '.venv', 'venv', 'site-packages', '.tox', '.nox',
+  '.pytest_cache', '.mypy_cache', '.ruff_cache', '.eggs']);
 
 /** Translate a minimal glob (`**`, `*`, `?`) into an anchored RegExp over posix paths. */
 export function globToRegExp(glob) {