testguard-cli 0.10.4 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-09-21
+
+Automated weekly release — everything merged since `v0.10.4`.
+
+### Changed
+
+- feat(sweep): findings on a repository that has no claims yet (#151)
+- chore(homebrew): sha256 for v0.10.4 (#149)
+
+
+### Added
+
+- `testguard sweep [dir] --changed <ref>` — the cold start. Proposes faults for
+  the changed source files that carry no claim, probes a bounded selection, and
+  reports what a green suite did not notice. Never writes
+  `testguard.claims.json`; its evidence never replaces
+  `.testguard/evidence.json`; only `survived` and `nocover` exit 1, so a
+  proposal the tool could not anchor or compile is reported and never gates.
+  Offline, like every other verifying command.
+- Selection follows Google's mutation service: at most 7 × |files| candidates,
+  spread round-robin across files, ordered on the measured productivity of the
+  fault class and shrunk toward a neutral prior so one observation never
+  dominates (`src/supply/select.mjs`).
+- `persistence-payload-unasserted` — why a survivor on a write path was missed:
+  the defender mocks the persistence layer and the file's call assertions never
+  name an exact payload, so a field dropped from a write cannot fail them.
+  Descriptive, never predictive; attached only to a survivor on a write path
+  (`src/supply/persistence.mjs`).
+- `urn:claimspec:v1:sweep` — the sweep document, with semantic rules that check
+  a cap never hides its own remainder.
+- Five self-claims (8 faults) covering the cap arithmetic, the exit-code rule,
+  where the persistence signal may be attached, per-file cap fairness, and that
+  one assertion's arguments are read without reading the next one's.
+
 ## [0.10.4] - 2026-09-21
 
 Automated weekly release — everything merged since `v0.10.3`.

package/README.md

@@ -127,9 +127,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | 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.10.4` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.11.0` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.10.4/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.11.0/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
 less than that many days ago (`ENOVERSIONS`); install that one with
@@ -147,6 +147,7 @@ npx testguard-cli probe                     # try to falsify each claim; report
 npx testguard-cli admit test/auth.test.ts --claim AUTH-ADMIN   # does this test satisfy the two-gate rule?
 npx testguard-cli baseline                  # freeze today's unproven findings; only new ones gate
 npx testguard-cli gate --changed origin/main # fail when a changed source file carries no claim
+npx testguard-cli sweep --changed origin/main # no claims yet? propose faults for the changed files and report what nothing noticed
 npx testguard-cli brief --text              # tell the agent where the suite is blind, before it writes
 npx testguard-cli replay --since v1.0..HEAD # would this suite have caught the bugs that escaped?
 npx testguard-cli mcp                       # serve the read-only loop over MCP, on stdio
@@ -400,6 +401,71 @@ on-demand helper, not a hook**: the session-start hook never touches the
 network, and the helper exits 0 with a message when the CLI or the artifact
 is missing. TestGuard itself still makes no network calls.
 
+### Starting from zero claims
+
+`gate` names the changed files that carry no claim, and stops there —
+correctly, because stating a claim is a human act. But a project adopting this
+tool reads that list, has nothing to compare it against, and closes the tab.
+The bottleneck was never verification; it is **oracle supply**.
+
+`sweep` is the lowest rung of that supply. No claim, no concern, nothing
+written by anybody:
+
+```bash
+npx testguard-cli sweep --changed origin/main          # propose, probe a bounded selection, report
+npx testguard-cli sweep --changed HEAD --include-dirty --cap 20
+```
+
+It takes the files `gate` just called uncovered, proposes faults with the same
+mechanical producers `scaffold` uses, probes a bounded selection, and reports
+what a green suite did not notice. A fault that survives needs no claim to be
+alarming: something was deliberately broken and not one test failed.
+
+```
+swept 13 of 14 unclaimed changed files against origin/main.
+proposed 510 faults, probed 10 (cap 10), deferred 500.
+  The 500 deferred are not a verdict: raise --cap, or sweep a smaller change.
+
+9 findings — a deliberate break that no test noticed:
+
+  SURVIVED      src/app/actions/register.ts:118  [write path]
+    [line 118] Field dropped: `password_hash` is no longer written.
+    src/tests/actions/register.test.ts mocks @/lib/prisma; 1 exact, 8 partial,
+    31 argument-free call assertions in the file. A field dropped from the write
+    payload fails only against an assertion that names that field exactly.
+    Assert the whole object written by the call this fault changes, including
+    `password_hash` — or read the record back and assert on what was stored.
+```
+
+Three rules make it safe to run on a repository that has never seen this tool:
+
+- **It never writes `testguard.claims.json`**, and never will. A claim is a
+  sentence someone is willing to stand behind; a sentence nobody wrote is not
+  one. Its drafts land beside the evidence to keep or drop.
+- **Its evidence never replaces `.testguard/evidence.json`.** A sweep probes
+  faults nobody stated, under TODO statements; folding that into the document
+  `status` and `baseline` read would corrupt the record of what the project
+  actually claims.
+- **It does not fail on its own bad guess.** Only `survived` and `nocover`
+  exit 1. A proposal that would not compile, or an anchor that did not locate,
+  is reported and never gates — a tool that fails because its own guess was bad
+  is a tool people switch off.
+
+The cap and the ordering are Google's: their mutation service surfaces at most
+7 × |files| mutants per change and orders candidates on the measured
+productivity of their operator in similar context, which took their productive
+rate from 15% to 89%
+([Petrović et al., *Practical Mutation Testing at Scale*, 2021](https://arxiv.org/abs/2102.11378)).
+TestGuard's ordering prior is measured the same way — from probed faults on a
+real AI-authored codebase — and shrunk toward a neutral value, so one
+observation of a class surviving never dominates a sweep. The cap is spread
+across files: a single file with many candidates cannot make the others look
+clean.
+
+A sweep is weaker evidence than a probe, and says so. Nobody stated that the
+behaviour mattered. It is stronger than nothing, which is what a repository
+with no claims has — and the survivors worth defending become the first claims.
+
 ### Every change needs a claim
 
 `probe` can only verify claims that exist. Every escaped defect in the field
@@ -481,12 +547,12 @@ detected base that does not resolve is a warning for `status` and `brief`
 # GitHub Actions
 - uses: actions/checkout@v4
   with: { fetch-depth: 0 }
-- uses: raccioly/testguard@v0.10.4
+- uses: raccioly/testguard@v0.11.0
   with: { command: gate }
 
 # GitLab CI — the component-shaped template: gate + probe, brief as an artifact and, opted in, as a merge-request note
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.10.4/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.11.0/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs: { dir: backend, post_note: true }   # post_note needs TESTGUARD_GITLAB_TOKEN (api scope); one note, updated in place
 ```
 
@@ -824,7 +890,7 @@ verdicts.
 ## Status
 
 **v0.5.** Eleven commands (`status`, `init`, `claims`, `probe`, `admit`,
-`replay`, `baseline`, `brief`, `gate`, `scaffold`, `mcp`), vitest, jest,
+`replay`, `baseline`, `brief`, `gate`, `scaffold`, `sweep`, `mcp`), vitest, jest,
 Playwright and Python (pytest / stdlib unittest) runners, hand-authored faults
 plus a mechanical scaffold for JavaScript and Python, an agent operating layer
 (`status`, `init`) and a change gate (`gate`). The contract spine — eight JSON

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "description": "Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest.",
   "type": "module",
   "license": "MIT",

package/spec/lib/validate.mjs

@@ -7,7 +7,7 @@ import { reproduces, decimals, MAX_PLACES } from './wilson.mjs';
 
 const schemaDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'schemas');
 
-export const KINDS = Object.freeze(['claims', 'evidence', 'baseline', 'ignore', 'calibration', 'brief', 'status', 'gate', 'replay']);
+export const KINDS = Object.freeze(['claims', 'evidence', 'baseline', 'ignore', 'calibration', 'brief', 'status', 'gate', 'replay', 'sweep']);
 /**
  * How a document says it tried to falsify its claims. Absent means
  * `fault-injection`, so every document written before the field existed is
@@ -305,6 +305,48 @@ const semantic = {
     return errors;
   },
 
+  sweep(doc) {
+    const errors = [];
+    const s = doc.selection;
+    // A cap that hides its remainder is a coverage claim nobody made, so the
+    // arithmetic that proves nothing was dropped is checked, not trusted.
+    if (s.proposed !== s.selected + s.deferred) errors.push({ path: '/selection/proposed', message: `proposed (${s.proposed}) must equal selected (${s.selected}) + deferred (${s.deferred})` });
+    if (s.selected > s.cap) errors.push({ path: '/selection/selected', message: `selected (${s.selected}) exceeds the cap (${s.cap})` });
+    if (doc.scope.swept > doc.scope.targets) errors.push({ path: '/scope/swept', message: `swept (${doc.scope.swept}) cannot exceed targets (${doc.scope.targets})` });
+
+    const byClass = Object.values(s.byClass);
+    const proposedByClass = byClass.reduce((a, c) => a + c.proposed, 0);
+    const selectedByClass = byClass.reduce((a, c) => a + c.selected, 0);
+    if (proposedByClass !== s.proposed) errors.push({ path: '/selection/byClass', message: `byClass proposed sums to ${proposedByClass}; selection.proposed is ${s.proposed}` });
+    if (selectedByClass !== s.selected) errors.push({ path: '/selection/byClass', message: `byClass selected sums to ${selectedByClass}; selection.selected is ${s.selected}` });
+    for (const [k, c] of Object.entries(s.byClass)) {
+      if (c.selected > c.proposed) errors.push({ path: `/selection/byClass/${k}`, message: `selected (${c.selected}) exceeds proposed (${c.proposed})` });
+      if (c.writePath > c.proposed) errors.push({ path: `/selection/byClass/${k}`, message: `writePath (${c.writePath}) exceeds proposed (${c.proposed})` });
+    }
+
+    const probed = Object.values(doc.counts).reduce((a, n) => a + n, 0);
+    if (probed > s.selected) errors.push({ path: '/counts', message: `${probed} verdicts recorded for ${s.selected} selected faults` });
+    // Findings are every record that was not killed. Stating that here keeps a
+    // document from quietly reporting fewer findings than it reached verdicts.
+    const notKilled = probed - (doc.counts.killed ?? 0);
+    if (doc.findings.length !== notKilled) errors.push({ path: '/findings', message: `${doc.findings.length} findings for ${notKilled} records that were not killed; findings are every non-killed record` });
+
+    const gating = doc.findings.filter((f) => f.verdict === 'survived' || f.verdict === 'nocover').length;
+    if (gating > 0 && doc.exitCode !== 1) errors.push({ path: '/exitCode', message: 'a survived or nocover finding must exit 1; a sweep never passes over a deliberate break nothing noticed' });
+    if (gating === 0 && doc.exitCode !== 0) errors.push({ path: '/exitCode', message: 'exit 1 requires a survived or nocover finding; a sweep does not fail on its own unanchorable proposal' });
+
+    doc.findings.forEach((f, i) => {
+      if (f.verdict === 'killed') errors.push({ path: `/findings/${i}/verdict`, message: 'a killed fault is not a finding' });
+      // The signal explains why a defender could not notice a changed payload.
+      // On any other verdict, or off the write path, it explains nothing and
+      // would be exactly the non-actionable noise that gets a check ignored.
+      if (f.signals && !(f.verdict === 'survived' && f.writePath)) {
+        errors.push({ path: `/findings/${i}/signals`, message: 'signals belong to a survived finding on the write path' });
+      }
+    });
+    return errors;
+  },
+
   brief(doc) {
     const errors = [];
     if (!doc.text.startsWith(doc.heading)) errors.push({ path: '/text', message: 'text must begin with heading' });

package/spec/schemas/sweep.schema.json

@@ -0,0 +1,127 @@
+{
+  "$id": "urn:claimspec:v1:sweep",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "claimspec v1 — sweep",
+  "description": "What a sweep proposed and what survived it. A sweep probes faults NOBODY STATED: it takes the changed source files that carry no claim, proposes faults with the mechanical producers, and reports the ones a green suite did not notice. Its findings are therefore weaker evidence than a probe's — no human said the behaviour mattered — and stronger than nothing, which is what a repository with no claims has. The drafts it carries are proposals for a human to keep or drop; they are not claims, and nothing here belongs in a claims file until someone states the sentence it defends.",
+  "type": "object",
+  "required": ["schemaVersion", "tool", "generatedAt", "ref", "base", "head", "includeDirty", "scope", "selection", "counts", "findings", "exitCode"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "tool": { "$ref": "urn:claimspec:v1:common#/$defs/tool" },
+    "generatedAt": { "$ref": "urn:claimspec:v1:common#/$defs/isoDateTime" },
+    "ref": { "type": "string", "description": "The reference the change was measured against." },
+    "base": { "$ref": "urn:claimspec:v1:common#/$defs/gitSha" },
+    "head": { "$ref": "urn:claimspec:v1:common#/$defs/gitSha" },
+    "includeDirty": { "type": "boolean" },
+    "scope": {
+      "type": "object",
+      "required": ["changed", "targets", "swept"],
+      "additionalProperties": false,
+      "properties": {
+        "changed": { "type": "integer", "minimum": 0, "description": "Files in the change, before any filter." },
+        "targets": { "type": "integer", "minimum": 0, "description": "Changed SOURCE files carrying no claim — what the gate calls uncovered. A sweep proposes against these and nothing else." },
+        "swept": { "type": "integer", "minimum": 0, "description": "Targets that yielded at least one proposal. Never more than `targets`: a file the producers cannot touch is skipped, not swept." },
+        "skipped": {
+          "type": "array",
+          "description": "Targets that produced nothing, and why. Recorded rather than dropped: a file that silently yielded no proposal reads as a file with no findings.",
+          "items": {
+            "type": "object",
+            "required": ["file", "reason"],
+            "additionalProperties": false,
+            "properties": {
+              "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "selection": {
+      "type": "object",
+      "description": "What was proposed and what was probed. A sweep is capped — past a few findings per file nobody reads them, and the runner is spent either way — so the count NOT probed is reported beside the count that was. A cap that hides its own remainder is a coverage claim nobody made.",
+      "required": ["proposed", "selected", "deferred", "cap", "byClass"],
+      "additionalProperties": false,
+      "properties": {
+        "proposed": { "type": "integer", "minimum": 0 },
+        "selected": { "type": "integer", "minimum": 0 },
+        "deferred": { "type": "integer", "minimum": 0, "description": "Proposed and not probed. Not a verdict of any kind." },
+        "cap": { "type": "integer", "minimum": 1 },
+        "byClass": {
+          "type": "object",
+          "description": "Per fault class: how many were proposed, how many probed, and how many sat on a write payload.",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["proposed", "selected", "writePath"],
+            "additionalProperties": false,
+            "properties": {
+              "proposed": { "type": "integer", "minimum": 0 },
+              "selected": { "type": "integer", "minimum": 0 },
+              "writePath": { "type": "integer", "minimum": 0 }
+            }
+          }
+        }
+      }
+    },
+    "counts": {
+      "type": "object",
+      "description": "Every verdict the probe reached, including `killed`. A sweep whose faults were all caught is a real result and must be readable as one.",
+      "additionalProperties": { "type": "integer", "minimum": 0 },
+      "propertyNames": { "$ref": "urn:claimspec:v1:common#/$defs/verdict" }
+    },
+    "findings": {
+      "type": "array",
+      "description": "Every record that was not killed, most actionable first. `survived` and `nocover` are statements about the test suite; the rest are statements about the PROPOSAL and do not gate, because a sweep's faults are machine-made and a tool that fails on its own bad guess gets switched off.",
+      "items": {
+        "type": "object",
+        "required": ["file", "claimId", "faultId", "faultClass", "verdict", "description", "writePath", "hint"],
+        "additionalProperties": false,
+        "properties": {
+          "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
+          "line": { "type": "integer", "minimum": 1 },
+          "claimId": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" },
+          "faultId": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" },
+          "faultClass": { "$ref": "urn:claimspec:v1:common#/$defs/faultClass" },
+          "verdict": { "$ref": "urn:claimspec:v1:common#/$defs/verdict" },
+          "reason": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "writePath": { "type": "boolean", "description": "The fault sits on a database write or the payload of one. Every surviving fault in the measurement that prompted this field was such a line." },
+          "hint": { "type": "string", "minLength": 1, "description": "One line naming the mechanism, never only the verdict." },
+          "signals": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Static, annotation-grade signals about the defenders of a SURVIVOR on the write path. They never change a verdict. `persistence-payload-unasserted`: the defender mocks the persistence layer and the file's call assertions never name an exact payload, so a field dropped from a write cannot fail them. Descriptive, never predictive: no threshold on the assertion mix separates the files whose payload faults survive from the files whose do not.",
+            "items": {
+              "type": "object",
+              "required": ["file", "signal", "reason"],
+              "additionalProperties": false,
+              "properties": {
+                "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
+                "signal": { "enum": ["persistence-payload-unasserted"] },
+                "reason": { "type": "string", "minLength": 1 },
+                "specifiers": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+                "counts": {
+                  "type": "object",
+                  "required": ["exact", "partial", "argless"],
+                  "additionalProperties": false,
+                  "properties": {
+                    "exact": { "type": "integer", "minimum": 0 },
+                    "partial": { "type": "integer", "minimum": 0 },
+                    "argless": { "type": "integer", "minimum": 0 }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "exitCode": { "enum": [0, 1] },
+    "drafts": {
+      "type": "array",
+      "description": "The draft claims documents the proposals came from, carried so a human can keep one without re-running the sweep. Drafts, never claims: every statement is a TODO nobody has written yet.",
+      "items": { "type": "object" }
+    }
+  }
+}

package/src/cli.mjs

@@ -18,6 +18,7 @@ import { gateCommand } from './commands/gate.mjs';
 import { replayCommand } from './commands/replay.mjs';
 import { mcpCommand } from './commands/mcp.mjs';
 import { admitCommand } from './commands/admit.mjs';
+import { sweepCommand } from './commands/sweep.mjs';
 
 const VERSION = JSON.parse(readFileSync(join(fileURLToPath(import.meta.url), '..', '..', 'package.json'), 'utf8')).version;
 const ISSUES = 'https://github.com/raccioly/testguard/issues';
@@ -32,6 +33,7 @@ export const USAGE = `testguard ${VERSION} — proves a test suite defends the c
   testguard brief [dir]      emit the blind-spot block for an agent's session-start context
   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 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?
@@ -74,6 +76,10 @@ probe
   --json               the status document plus this run's result (records, newSinceBaseline, exitCode)
 
 scaffold   --claim <ID> (put every proposal under this claim; copies it if it exists)  --out <path>  --json
+sweep      --changed <ref> (required; CI bases and a safe local default are detected)  --cap <n> (default 7 x unclaimed files)
+           --include-dirty  --exclude <glob>  --confirm <n>  --budget <ms>  --max <n>  --out <path>  --json
+           the cold start: no claim and no concern needed. Everything it proposes is a DRAFT — it never writes testguard.claims.json,
+           and its evidence never replaces .testguard/evidence.json. exit 1 on a fault that survived, or a file no test imports
            shapes: if-guard → if (false) · single-line guard/mutation removed · return <check> → return true
                    · security flag/window/cost literal weakened · verify/validate/check call removed
                    · field dropped from a payload/allow-list/schema/merge · parameter-derived argument swapped for undefined/{}
@@ -117,7 +123,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 };
+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 };
 
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
   let parsed;
@@ -143,6 +149,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         changed: { type: 'string' },
         since: { type: 'string' },
         exclude: { type: 'string', multiple: true },
+        cap: { type: 'string' },
         strict: { type: 'boolean', default: false },
         explain: { type: 'boolean', default: false },
         ignore: { type: 'string' },

package/src/commands/sweep.mjs

@@ -0,0 +1,74 @@
+import { join, resolve } from 'node:path';
+import { sweep, renderSweep } 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');
+
+/**
+ * `testguard sweep [dir] --changed <ref>`: propose faults for the changed
+ * source files that carry no claim, probe a bounded selection, and report what
+ * a green suite did not notice.
+ *
+ * Exit 0 nothing survived · 1 a survivor or an untested file · 2 cannot
+ * evaluate · 3 no reference.
+ *
+ * The sweep document goes to `.testguard/sweep.json` and NEVER to
+ * `.testguard/evidence.json`. The canonical evidence is the record of what the
+ * project claims; a sweep probes faults nobody stated, under TODO statements,
+ * and folding one into the other would corrupt what `status` and `baseline`
+ * read.
+ */
+export async function sweepCommand({ projectDir, values, version }, io) {
+  const resolved = resolveChangedRef({ explicit: values.changed, projectDir });
+  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.');
+    return 3;
+  }
+  const confirmRuns = Number(values.confirm);
+  const budgetMs = Number(values.budget);
+  if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
+    io.err('--confirm must be a positive integer and --budget at least 1000');
+    return 3;
+  }
+  let cap;
+  if (values.cap !== undefined) {
+    cap = Number(values.cap);
+    if (!Number.isInteger(cap) || cap < 1) {
+      io.err('--cap must be a positive integer');
+      return 3;
+    }
+  }
+  if (!resolved.required && !values.json && !values.quiet) io.err(`sweep: comparing against ${resolved.ref} (${resolved.from})`);
+
+  const doc = await sweep({
+    projectDir,
+    ref: resolved.ref,
+    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}`); },
+  });
+  if (process.stderr.isTTY && !values.quiet && !values.json) process.stderr.write('\r\x1b[K');
+
+  const outPath = values.out ? resolve(values.out) : sweepPath(projectDir);
+  writeSpecDoc('sweep', outPath, doc);
+  if (values.json) {
+    io.out(JSON.stringify(doc, null, 2));
+  } else {
+    io.out(renderSweep(doc, { limit: Number(values.max) || 20 }));
+    if (!values.quiet) io.out(`\nsweep: ${outPath}`);
+  }
+  return doc.exitCode;
+}

package/src/supply/persistence.mjs

@@ -0,0 +1,173 @@
+/**
+ * The save-button signal: why a fault on the persistence path survived.
+ *
+ * `mocks.mjs` answers "does this test replace the SUBJECT?", and a file that
+ * does cannot detect any fault in it. This is the other half, and it is the
+ * one that explains a green suite over a save that does not save. Such a test
+ * does NOT mock the subject — it mocks the persistence layer underneath it —
+ * so it is a legitimate defender and stays one. It can catch a deleted write.
+ * What it cannot catch is a wrong PAYLOAD, and only because of how it asserts.
+ *
+ * Measured on a real AI-authored Next.js application (2026-09-21): 10 of 10
+ * server-action tests mocked `@/lib/prisma`, and 12 of 12 surviving faults on
+ * the persistence path were a field dropped from a `data` / `where` object.
+ * The assertion that should have caught them was `toHaveBeenCalledWith(
+ * expect.objectContaining({...}))` naming every field except the one carrying
+ * the data — the pathology this project's README reports from the field.
+ *
+ * DESCRIPTIVE, NOT PREDICTIVE — and that is a correction the measurement
+ * forced. The first version of this file silenced itself when a test contained
+ * any exact payload assertion. On the same 26 probed faults that rule fired on
+ * 1 of 10 files while 4 had survivors, because a file asserts many calls and
+ * the one exact assertion is usually about something else:
+ * `identity-password-recovery.test.ts` has one exact assertion among forty and
+ * every one of its payload faults survived, while `contact.test.ts` has the
+ * same one exact assertion and none did. No file-level threshold separates
+ * those two, so this reports the SHAPE and refuses to score it.
+ *
+ * It is therefore attached to a verdict the probe already reached, never used
+ * to predict one or to select what gets probed. The probe says a fault
+ * survived; this says the structural reason and what to write instead.
+ *
+ * Line- and regex-oriented, like the scaffold producers: no AST, no type
+ * information, and an honest miss rather than a confident wrong claim. In
+ * particular there is no read-back detection here. A regex for "the test asked
+ * for the row again" matched every file that mocks `findUnique` and asserts
+ * anything, including files whose payload faults all survived, so it measured
+ * nothing and was removed rather than shipped as a silencer.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Module specifiers that mean "the database". A project-local path counts when
+ * it names one of these — `@/lib/prisma`, `../db`, `~/server/drizzle` — which
+ * is how these layers are named in practice.
+ */
+const PERSISTENCE_SPECIFIER = /(?:^|[/@~.])(?:prisma|db|database|knex|sequelize|mongoose|typeorm|drizzle|supabase|pg|mysql2?|sqlite3?|dynamodb|mongodb)(?:$|[/.])/i;
+
+/** `vi.mock('x')` / `jest.mock('x')` — the same call shapes mocks.mjs reads. */
+const MOCK_CALL = /\b(?:vi|jest)\.(?:mock|doMock|unstable_mockModule)\(\s*(['"])([^'"]+)\1/g;
+
+/** Partial matchers: true of a subset, so a dropped field outside the subset passes. */
+const PARTIAL_MATCHER = /expect\.(?:objectContaining|arrayContaining|any|anything|stringContaining|stringMatching)\s*\(/;
+
+/** The persistence specifiers this source mocks, with line numbers. */
+export function persistenceMocks(source) {
+  const out = [];
+  source.split('\n').forEach((text, i) => {
+    for (const m of text.matchAll(MOCK_CALL)) {
+      if (PERSISTENCE_SPECIFIER.test(m[2])) out.push({ specifier: m[2], line: i + 1 });
+    }
+  });
+  return out;
+}
+
+/**
+ * The text between an open parenthesis at `open` and its match, so one
+ * assertion's arguments are read without reading the next one's.
+ *
+ * A fixed-width window cannot do this: two assertions on adjacent lines put the
+ * second one's `expect.objectContaining` inside the first one's window, and
+ * every exact assertion in a dense test file is reported as partial. Measured —
+ * the first version of this scored a file with one exact and one partial
+ * assertion as two partials.
+ *
+ * Quotes are tracked because a parenthesis inside a string is not a
+ * parenthesis; anything unbalanced returns what it read, which errs toward
+ * reporting a partial matcher that is really there.
+ */
+function balancedArgs(source, open) {
+  let depth = 0;
+  let quote = null;
+  for (let i = open; i < source.length; i++) {
+    const c = source[i];
+    if (quote) {
+      if (c === '\\') i += 1;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') quote = c;
+    else if (c === '(') depth += 1;
+    else if (c === ')') {
+      depth -= 1;
+      if (depth === 0) return source.slice(open + 1, i);
+    }
+  }
+  return source.slice(open + 1);
+}
+
+/**
+ * How this source asserts on its mocks: how many assertions name the exact
+ * arguments, how many name them only partially, and how many assert that a
+ * call happened without saying with what.
+ *
+ * Counting rather than deciding. The counts go into the reason string so a
+ * reader can disagree with the inference instead of only with a verdict.
+ */
+export function payloadAssertions(source) {
+  let exact = 0;
+  let partial = 0;
+  let argless = 0;
+  for (const m of source.matchAll(/\.toHaveBeenCalledWith\s*\(/g)) {
+    const open = m.index + m[0].length - 1;
+    if (PARTIAL_MATCHER.test(balancedArgs(source, open))) partial += 1;
+    else exact += 1;
+  }
+  for (const _ of source.matchAll(/\.(?:toHaveBeenCalled|toHaveBeenCalledTimes|toHaveBeenCalledOnce)\s*\(/g)) argless += 1;
+  return { exact, partial, argless };
+}
+
+/**
+ * The shape of one defender's relationship to the persistence layer, or null
+ * when it does not mock one. Shaped like the records `mocks.mjs` produces so a
+ * caller can merge the two lists without reshaping either.
+ */
+export function analyzePersistence(projectDir, testRel) {
+  let source;
+  try {
+    source = readFileSync(join(projectDir, testRel), 'utf8');
+  } catch {
+    return null;
+  }
+  const mocks = persistenceMocks(source);
+  if (mocks.length === 0) return null;
+  const counts = payloadAssertions(source);
+  const specifiers = [...new Set(mocks.map((m) => m.specifier))].sort();
+  const shape = [
+    counts.exact ? `${counts.exact} exact` : '',
+    counts.partial ? `${counts.partial} partial` : '',
+    counts.argless ? `${counts.argless} argument-free` : '',
+  ].filter(Boolean).join(', ') || 'no';
+  return {
+    file: testRel,
+    signal: 'persistence-payload-unasserted',
+    reason: `mocks ${specifiers.join(', ')}; ${shape} call assertion${counts.exact + counts.partial + counts.argless === 1 ? '' : 's'} in the file. A field dropped from the write payload fails only against an assertion that names that field exactly.`,
+    counts,
+    specifiers,
+  };
+}
+
+/**
+ * The signal for a claim's defenders. Only ever consulted for a SURVIVOR whose
+ * fault is on the persistence path: on a kill it explains nothing, and on any
+ * other line a loose mock assertion is not evidence of anything. Reporting it
+ * everywhere would be the non-actionable noise that gets a check switched off.
+ */
+export function persistenceSignals(projectDir, defenders) {
+  return defenders.map((d) => analyzePersistence(projectDir, d)).filter(Boolean);
+}
+
+/**
+ * One line an agent can act on, in the register `hintFor()` uses.
+ *
+ * The field name is read from either property form. Shorthand is not an edge
+ * case here: every surviving payload fault measured on the register action was
+ * shorthand — `email,` `username,` `password_hash,` — so a pattern that only
+ * matched `name: value` would fail to name the field in exactly the cases that
+ * prompted this signal.
+ */
+export function persistenceHint(signal, faultLine) {
+  const field = /^\s*([A-Za-z_$][\w$]*)\s*(?::|,\s*$)/.exec(faultLine ?? '')?.[1];
+  return `${signal.file} ${signal.reason} Assert the whole object written by the call this fault changes${field ? `, including \`${field}\`` : ''} — or read the record back and assert on what was stored.`;
+}

package/src/supply/select.mjs

@@ -0,0 +1,168 @@
+/**
+ * Which drafted faults are worth probing, and in what order.
+ *
+ * `scaffold` proposes mechanically and proposes a lot: eight source files of a
+ * real application yielded 238 proposals. Probing all of them is the cost model
+ * the tool already refuses — `(baseline + faults x N) x defender-set cost`,
+ * per claim — so a sweep that probes everything is a sweep nobody runs twice.
+ *
+ * Google's mutation service solved the same problem by never surfacing more
+ * than 7 x |files| mutants per change and by ordering candidates on the
+ * measured productivity of their operator in similar context, which took their
+ * productive rate from 15% to 89% ("Practical Mutation Testing at Scale",
+ * Petrovic et al., 2021). This module is that idea at this tool's scale.
+ *
+ * TWO THINGS IT MUST NOT DO. It must not drop a candidate silently — a cap
+ * that hides work is a coverage claim nobody made, so everything not selected
+ * is returned as `deferred` and the caller is expected to say so. And it must
+ * not be nondeterministic: the same drafts in the same repository must select
+ * the same faults in the same order, or a sweep's output stops being evidence.
+ * Every tie therefore breaks on file, then line, then id.
+ *
+ * Pure: drafts in, a selection out. Nothing here reads a file or runs anything.
+ */
+
+/**
+ * P(a fault of this class survives a green suite), measured — not guessed.
+ *
+ * From 56 probed faults across 12 modules of a real AI-authored Next.js
+ * application (2026-09-21). Survival is the right prior for ordering because a
+ * fault that dies everywhere teaches nobody anything: the whole output of a
+ * sweep is the faults that lived.
+ *
+ * `n` is carried so a reader can see which of these is one observation and
+ * which is twelve, and so a later feedback pass can weight them honestly
+ * instead of treating 100%-of-one as certainty.
+ */
+export const MEASURED_PRODUCTIVITY = Object.freeze({
+  'element-removed': { p: 1.0, n: 1 },
+  'call-removed': { p: 0.67, n: 3 },
+  'field-dropped': { p: 0.5, n: 12 },
+  'statement-deleted': { p: 0.33, n: 12 },
+  'literal-changed': { p: 0.33, n: 3 },
+  'condition-forced': { p: 0.1, n: 10 },
+  'argument-swapped': { p: 0.09, n: 11 },
+  'return-altered': { p: 0.0, n: 4 },
+});
+
+/**
+ * A class nobody measured is worth more attention than the worst measured one
+ * and less than the best. Ranking it last would make every new producer
+ * invisible until someone hand-edited this table; ranking it first would let a
+ * new producer crowd out everything known to be productive.
+ */
+const UNMEASURED = 0.4;
+
+/**
+ * Shrink a small sample toward the unmeasured prior. One observation of
+ * `element-removed` is not evidence that it always survives, and ordering the
+ * whole sweep on it would be exactly the overconfidence this tool exists to
+ * refuse. m is the pseudo-count: at n = m the measurement and the prior weigh
+ * the same.
+ */
+const M = 4;
+export function priorFor(faultClass, table = MEASURED_PRODUCTIVITY) {
+  const hit = table[faultClass];
+  if (!hit) return UNMEASURED;
+  return (hit.p * hit.n + UNMEASURED * M) / (hit.n + M);
+}
+
+/**
+ * The write payload of a persisted record is where this project's own
+ * measurement found every survivor: 12 of 12 were a field dropped from a
+ * `data` / `where` / `update` object reaching a database call. A fault on such
+ * a line is worth more than its class alone says, because the assertion that
+ * would have to catch it is the one tests most often write loosely
+ * (`expect.objectContaining({...})` naming everything except the field that
+ * carried the data).
+ *
+ * Deliberately a line-shape test, not a type-aware one: the scaffold producers
+ * are line-oriented and this must not become the one part of the pipeline that
+ * needs an AST.
+ */
+const PERSISTENCE_CALL = /\b(?:prisma|db|tx|trx|knex|sequelize|mongoose|supabase|drizzle)\b\s*[.[]|\.(?:create|createMany|update|updateMany|upsert|insert|save|delete|deleteMany|destroy)\s*\(/;
+const PAYLOAD_KEY = /^\s*(?:data|where|update|create|select|set|values)\s*:/;
+
+/** Is this fault on the persistence path — a write call, or a field of its payload? */
+export function onWritePath(fault) {
+  const line = fault.find ?? '';
+  return PERSISTENCE_CALL.test(line) || PAYLOAD_KEY.test(line) || PERSISTENCE_CALL.test(fault.description ?? '');
+}
+
+/** The boost a write-path fault gets. Additive, not multiplicative: it must not be able to overtake a measured 1.0. */
+const WRITE_PATH_BONUS = 0.25;
+
+/** What one draft is worth probing, in [0, 1.25]. Exported so a test can pin the ordering rule rather than the order. */
+export function scoreOf(fault, { table } = {}) {
+  return priorFor(fault.faultClass, table) + (onWritePath(fault) ? WRITE_PATH_BONUS : 0);
+}
+
+/**
+ * Google surfaces at most 7 x |files| mutants per change. The number is theirs
+ * and the reason is general: past it the reader stops reading, and a finding
+ * nobody reads is worse than no finding, because it also spends the runner.
+ */
+export const capFor = (fileCount, perFile = 7) => Math.max(perFile, fileCount * perFile);
+
+/**
+ * Order every candidate and take the cap.
+ *
+ * `candidates` are `{ claim, fault }` pairs — the claim is carried so the
+ * caller can rebuild a claims document from the selection without a second
+ * lookup. Returns the selection, everything deferred, and the per-class tally
+ * a report needs to explain itself.
+ */
+export function selectFaults(candidates, { cap, table } = {}) {
+  const limit = Number.isInteger(cap) && cap > 0 ? cap : capFor(new Set(candidates.map((c) => c.fault.file)).size);
+  const ranked = candidates
+    .map((c) => ({ ...c, score: scoreOf(c.fault, { table }), writePath: onWritePath(c.fault) }))
+    // Deterministic to the last tie: score, then file, then line, then id.
+    // Two runs of the same sweep on the same tree are the same sweep.
+    .sort((a, b) =>
+      b.score - a.score
+      || (a.fault.file ?? '').localeCompare(b.fault.file ?? '')
+      || (a.fault.line ?? 0) - (b.fault.line ?? 0)
+      || `${a.claim.id}/${a.fault.id}`.localeCompare(`${b.claim.id}/${b.fault.id}`));
+
+  // ── Spread the cap across FILES, best-first within each. ──
+  // Taking the global top N looks right and is not: a file with many
+  // high-scoring lines takes the whole budget and every other changed file is
+  // reported as having no findings, which is indistinguishable from having
+  // none. Measured — the first sweep of a 14-file change spent all six slots
+  // on one page component and said nothing about the other twelve.
+  // The cap is already expressed per file (7 x |files|), so this is what that
+  // number was always supposed to mean.
+  const byFile = new Map();
+  for (const r of ranked) {
+    const key = r.fault.file ?? '';
+    if (!byFile.has(key)) byFile.set(key, []);
+    byFile.get(key).push(r);
+  }
+  // Files in the order of their best candidate, so a round that cannot serve
+  // everyone still serves the most promising files first. Ties on file name.
+  const queues = [...byFile.entries()]
+    .sort((a, b) => b[1][0].score - a[1][0].score || a[0].localeCompare(b[0]))
+    .map(([, q]) => q);
+
+  const selected = [];
+  for (let round = 0; selected.length < limit; round++) {
+    let served = false;
+    for (const q of queues) {
+      if (q.length <= round) continue;
+      selected.push(q[round]);
+      served = true;
+      if (selected.length >= limit) break;
+    }
+    if (!served) break;
+  }
+  const taken = new Set(selected);
+  const deferred = ranked.filter((r) => !taken.has(r));
+  const byClass = {};
+  for (const r of ranked) {
+    const e = (byClass[r.fault.faultClass] ??= { proposed: 0, selected: 0, writePath: 0 });
+    e.proposed += 1;
+    if (r.writePath) e.writePath += 1;
+  }
+  for (const r of selected) byClass[r.fault.faultClass].selected += 1;
+  return { selected, deferred, cap: limit, byClass };
+}

package/src/sweep/sweep.mjs

@@ -0,0 +1,274 @@
+/**
+ * The cold start: findings on a repository that has no claims yet.
+ *
+ * `gate --changed` already says which changed source files carry no claim, and
+ * stops there — correctly, because stating a claim is a human act. But a
+ * project adopting this tool reads that list, has nothing to compare it
+ * against, and closes the tab. Every escaped defect reported from the field so
+ * far was a claim gap, not a probe miss, so the bottleneck was never
+ * verification. It is oracle SUPPLY.
+ *
+ * Sweep is the lowest rung of that supply: no concern, no statement, nothing
+ * written by anybody. It takes the files the gate just called uncovered,
+ * proposes faults mechanically with the existing scaffold producers, probes a
+ * bounded selection of them, and reports what survived. A fault that survives
+ * needs no claim to be alarming: the code changed, something was deliberately
+ * broken, and not one test noticed.
+ *
+ * WHAT IT IS NOT. It does not write `testguard.claims.json`, and it never
+ * will — a claim is a sentence a human is willing to stand behind, and a
+ * sentence nobody wrote is not one. Its drafts land beside the evidence for a
+ * human to keep or drop, exactly as `scaffold` already works. It does not
+ * overwrite the canonical `.testguard/evidence.json` either: a sweep probes
+ * machine-proposed faults under TODO statements, and folding that into the
+ * document `status` and `baseline` read from would corrupt the record of what
+ * the project actually claims.
+ *
+ * The cap and the ordering come from Google's mutation service, which surfaces
+ * at most 7 x |files| mutants per change and orders candidates on the measured
+ * productivity of their operator, taking their productive rate from 15% to 89%
+ * ("Practical Mutation Testing at Scale", Petrovic et al., 2021). See
+ * `src/supply/select.mjs`.
+ */
+import { existsSync } from 'node:fs';
+import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
+import { computeChangedGate } from '../gate/changed.mjs';
+import { scaffoldFile } from '../scaffold/scaffold.mjs';
+import { selectFaults, onWritePath, capFor } from '../supply/select.mjs';
+import { persistenceSignals, persistenceHint } from '../supply/persistence.mjs';
+import { probe } from '../probe/probe.mjs';
+import { hintFor } from '../brief/brief.mjs';
+
+/**
+ * Findings first, in the order a reader should act on them. The same order
+ * `brief` uses, minus the verdicts a sweep does not gate on.
+ */
+const FINDING_ORDER = ['survived', 'nocover', 'timeout', 'flaky-defender', 'unverifiable', 'fault-invalid'];
+
+/**
+ * Which verdicts are a finding ABOUT THE PROJECT, and so decide the exit code.
+ *
+ * `survived` and `nocover` are statements about the test suite: something was
+ * broken and nothing failed, or nothing imports the file at all. The rest are
+ * statements about the PROPOSAL — an anchor that did not locate, a replacement
+ * that does not compile — and a sweep's proposals are machine-made and thrown
+ * away. Gating on them would make the tool fail because its own guess was bad,
+ * which is the fastest way to get a check switched off. They are still
+ * reported; they just do not gate.
+ */
+export const GATING = new Set(['survived', 'nocover']);
+
+/**
+ * Turn one evidence record into a finding, or null when it is not one.
+ *
+ * Pure, and exported, for the reason `classify.mjs` gives about itself: the
+ * only thing that could otherwise falsify these rules is a full fixture sweep,
+ * which is a minutes-long acceptance test standing in for a decision you can
+ * state in four lines. Self-probing this file found exactly that gap — the
+ * schema was guarded and the engine that fills it was not.
+ *
+ * `signalsFor` is injected so the rule about WHEN a signal applies can be
+ * tested without a filesystem; the default in `sweep()` reads the defenders.
+ */
+export function findingFrom(record, fault, signalsFor = () => []) {
+  if (record.verdict === 'killed') return null;
+  const writePath = fault ? onWritePath(fault) : false;
+  // The persistence signal explains a survivor on the write path and nothing
+  // else. On a kill it explains nothing, and on any other line a loose mock
+  // assertion is not evidence — reporting it everywhere is the
+  // non-actionable noise that gets a check switched off.
+  const signals = record.verdict === 'survived' && writePath ? signalsFor(record) : [];
+  return {
+    file: record.subject.file,
+    ...(fault?.line ? { line: fault.line } : {}),
+    claimId: record.claim.id,
+    faultId: record.subject.id,
+    faultClass: record.subject.faultClass,
+    verdict: record.verdict,
+    ...(record.detail?.reason ? { reason: record.detail.reason } : {}),
+    description: record.subject.description,
+    writePath,
+    hint: signals.length ? persistenceHint(signals[0], fault?.find) : hintFor(record),
+    ...(signals.length ? { signals } : {}),
+  };
+}
+
+/** Findings in the order a reader should act on them. Pure; deterministic to the last tie. */
+export function sortFindings(findings) {
+  return [...findings].sort((a, b) =>
+    FINDING_ORDER.indexOf(a.verdict) - FINDING_ORDER.indexOf(b.verdict)
+    || Number(b.writePath) - Number(a.writePath)
+    || a.file.localeCompare(b.file)
+    || (a.line ?? 0) - (b.line ?? 0));
+}
+
+/** How many findings a sweep is willing to fail on. */
+export const gatingCount = (findings) => findings.filter((f) => GATING.has(f.verdict)).length;
+
+/** Rebuild claim documents from a flat selection, keeping each claim's own faults together. */
+function claimsFromSelection(selected) {
+  const byClaim = new Map();
+  for (const { claim, fault } of selected) {
+    if (!byClaim.has(claim.id)) byClaim.set(claim.id, { ...claim, faults: [] });
+    byClaim.get(claim.id).faults.push(fault);
+  }
+  // Deterministic: the probe's own ordering, and the evidence it writes, must
+  // not depend on the order a Map happened to be filled in.
+  return [...byClaim.values()]
+    .map((c) => ({ ...c, faults: [...c.faults].sort((a, b) => a.id.localeCompare(b.id)) }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Run a sweep. Returns the sweep document; the caller owns writing and exit
+ * codes, as every other engine module in this tool does.
+ */
+export async function sweep({
+  projectDir,
+  ref,
+  includeDirty = false,
+  exclude = [],
+  cap,
+  confirmRuns = 3,
+  budgetMs = 120_000,
+  runnerCommand,
+  runnerName,
+  nodeModules,
+  toolVersion = '0.0.0',
+  generatedAt = new Date().toISOString(),
+  claimsPath,
+  ignorePath,
+  onStage,
+  onWarn = () => {},
+}) {
+  const gate = computeChangedGate({ projectDir, ref, includeDirty, exclude, toolVersion, claimsPath, ignorePath });
+  // A test file with no claim is a different problem — it has nothing to
+  // falsify — and the gate already names it. Sweep proposes against source.
+  const targets = gate.uncovered.filter((u) => u.kind === 'source').map((u) => u.file);
+
+  const cPath = claimsPath ?? defaultClaimsPath(projectDir);
+  const existingClaims = existsSync(cPath) ? loadClaims(cPath) : { claims: [] };
+
+  const candidates = [];
+  const skipped = [];
+  const drafts = [];
+  for (const file of targets) {
+    let result;
+    try {
+      result = scaffoldFile({ projectDir, file, existingClaims, toolVersion });
+    } catch (e) {
+      // One unscaffoldable file must not take the sweep with it: the other
+      // files' findings are still true, and a reader needs to know which file
+      // produced nothing and why.
+      skipped.push({ file, reason: e.message.split('\n')[0].slice(0, 200) });
+      continue;
+    }
+    if (result.stats.proposals === 0) {
+      skipped.push({ file, reason: 'no line in this file matches a fault producer' });
+      continue;
+    }
+    drafts.push(result.doc);
+    for (const claim of result.doc.claims) for (const fault of claim.faults) candidates.push({ claim, fault });
+  }
+
+  const limit = cap ?? capFor(targets.length);
+  const selection = selectFaults(candidates, { cap: limit });
+  const claims = claimsFromSelection(selection.selected);
+
+  let evidence = { records: [] };
+  if (claims.length > 0) {
+    evidence = await probe({
+      projectDir,
+      claims: { schemaVersion: 1, claims },
+      confirmRuns,
+      budgetMs,
+      mode: 'worktree',
+      includeDirty,
+      // A proposed fault has no declared defenders to be missing from, so the
+      // question escalation answers — "did something UNDECLARED catch it?" —
+      // has no meaning here, and it is the most expensive thing the probe does.
+      escalate: false,
+      runnerCommand,
+      runnerName,
+      nodeModules,
+      toolVersion,
+      onStage,
+      onWarn,
+    });
+  }
+
+  // Index the selection so a record can find the fault it came from without a
+  // second scan; `line` and `find` live on the draft, not on the evidence.
+  const draftOf = new Map(selection.selected.map(({ claim, fault }) => [`${claim.id}/${fault.id}`, fault]));
+
+  const signalsFor = (r) => persistenceSignals(projectDir, r.defenders?.resolved ?? []);
+  const counts = {};
+  const findings = [];
+  for (const r of evidence.records) {
+    counts[r.verdict] = (counts[r.verdict] ?? 0) + 1;
+    const f = findingFrom(r, draftOf.get(`${r.claim.id}/${r.subject.id}`), signalsFor);
+    if (f) findings.push(f);
+  }
+  const ordered = sortFindings(findings);
+  const gating = gatingCount(ordered);
+  return {
+    schemaVersion: 1,
+    tool: { name: 'testguard', version: toolVersion },
+    generatedAt,
+    ref,
+    base: gate.base,
+    head: gate.head,
+    includeDirty,
+    scope: {
+      changed: gate.changed,
+      targets: targets.length,
+      swept: drafts.length,
+      ...(skipped.length ? { skipped } : {}),
+    },
+    selection: {
+      proposed: candidates.length,
+      selected: selection.selected.length,
+      deferred: selection.deferred.length,
+      cap: selection.cap,
+      byClass: selection.byClass,
+    },
+    counts,
+    findings: ordered,
+    exitCode: gating > 0 ? 1 : 0,
+    drafts,
+  };
+}
+
+/** The sweep as text, for someone who ran it in a terminal or reads it in a CI log. */
+export function renderSweep(doc, { limit = 20 } = {}) {
+  const out = [];
+  const { scope, selection } = doc;
+  if (scope.targets === 0) {
+    out.push(`sweep: no changed source file is without a claim against ${doc.ref}. Nothing to propose.`);
+    return out.join('\n');
+  }
+  out.push(`swept ${scope.swept} of ${scope.targets} unclaimed changed file${scope.targets === 1 ? '' : 's'} against ${doc.ref}.`);
+  out.push(`proposed ${selection.proposed} fault${selection.proposed === 1 ? '' : 's'}, probed ${selection.selected} (cap ${selection.cap})${selection.deferred ? `, deferred ${selection.deferred}` : ''}.`);
+  if (selection.deferred) out.push(`  The ${selection.deferred} deferred are not a verdict: raise --cap, or sweep a smaller change.`);
+  for (const s of scope.skipped ?? []) out.push(`  skipped ${s.file}: ${s.reason}`);
+  out.push('');
+
+  const gating = doc.findings.filter((f) => GATING.has(f.verdict));
+  if (gating.length === 0) {
+    out.push(`No fault survived. ${doc.counts.killed ?? 0} of ${selection.selected} probed faults were caught.`);
+  } else {
+    out.push(`${gating.length} finding${gating.length === 1 ? '' : 's'} — a deliberate break that no test noticed:`);
+    out.push('');
+    for (const f of doc.findings.slice(0, limit)) {
+      const where = f.line ? `${f.file}:${f.line}` : f.file;
+      out.push(`  ${f.verdict.toUpperCase().padEnd(13)} ${where}${f.writePath ? '  [write path]' : ''}`);
+      out.push(`    ${f.description}`);
+      out.push(`    ${f.hint}`);
+      out.push('');
+    }
+    if (doc.findings.length > limit) out.push(`  … ${doc.findings.length - limit} more in the sweep document`);
+  }
+  out.push('These are PROPOSALS, not claims. Keep the ones worth defending: state the');
+  out.push('claim, copy its fault into testguard.claims.json, and probe it from then on.');
+  return out.join('\n');
+}