testguard-cli 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-22
+
+Automated weekly release — everything merged since `v0.11.0`.
+
+### Changed
+
+- feat(sweep): --save-paths, and the denominator a save report is read against (#156)
+- docs: make the brief describe what the tool actually does, and record the prior art (#155)
+- chore(homebrew): sha256 for v0.11.0 (#153)
+
+
+### Added
+
+- `sweep --save-paths` — sweep every file that writes to storage instead of the
+  diff, and report the surface as the denominator the findings are read
+  against. A diff cannot answer how many save paths exist, and a clean report
+  over an unstated denominator is a sample of unknown size. The sweep document
+  gains `scope.mode`, `scope.writeSites` and `scope.payloadFields`, and the
+  validator refuses a save-paths sweep that omits its surface.
+- `src/supply/savepath.mjs` — the write-site enumerator: which calls put data
+  into storage, and which payload keys sit on their own line (the ones a
+  `field-dropped` fault can anchor to). Measured on a real AI-authored
+  application: 119 writes across 37 files carrying 226 payload fields.
+
+### Fixed
+
+- `walk()` skipped `dist` and `coverage` but not `.next`, `build`, `out`,
+  `.svelte-kit`, `.turbo` and their siblings, while the claim above it already
+  promised that a build's test files cannot be picked up. A scan of a real
+  Next.js application counted 104 files instead of 32, because `.next/` carries
+  compiled copies of the application — its writes and its tests. The claim was
+  right; the list was short.
+
+### Added
+
+- `docs-canonical/PRIOR-ART.md` — the canonical record of what was taken from
+  Google's and Meta's mutation-testing programmes, what was deliberately not
+  taken, the measured reason no model decides a verdict, and the known gaps in
+  what was borrowed. Registered with DocGuard.
+- README prior-art section pointing at it.
+
+### Changed
+
+- The technical brief now describes what the tool actually does. A new
+  *Starting from zero* page carries Field report C (the persistence-path
+  measurement: 12 of 26 faults survived a green suite, all of them a dropped
+  payload field) and the claim-supply ladder; prior art names Google and Meta
+  and what each solved; the decision-model result is stated as a measurement
+  rather than a design assertion; and a *what it deliberately is not* section
+  closes it. `sweep` added to the verb table. Six pages to eight, re-rendered.
+
 ## [0.11.0] - 2026-09-21
 
 Automated weekly release — everything merged since `v0.10.4`.

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.11.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.12.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.11.0/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.12.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
@@ -466,6 +466,39 @@ 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.
 
+#### Sweeping the save surface instead of the diff
+
+A diff cannot answer *"when the user clicks save, does it actually save?"* — it
+only knows what changed today. `--save-paths` points the same sweep at every
+file that writes to storage:
+
+```bash
+npx testguard-cli sweep --save-paths --cap 20
+```
+
+```
+119 writes to storage across 37 files, carrying 226 payload fields. Swept 36.
+proposed 762 faults, probed 20 (cap 20), deferred 742.
+
+SURVIVED   src/app/actions/register.ts  [write path]
+  [line 59] 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.
+```
+
+The first line is the point. A report that lists findings without saying how
+much surface it looked at invites you to assume the rest is fine, so the
+denominator comes first and the document carries `writeSites` and
+`payloadFields` whether or not anything survived. Measured on a real
+AI-authored application: **12 of 26 probed persistence faults survived a fully
+green suite, and all 12 were a dropped payload field.**
+
+This is a *sample* of the surface, and says so. It does not yet prove a write
+reached storage — only that a test would notice if the payload changed.
+Read-back oracles are the next rung
+([#154](https://github.com/raccioly/testguard/issues/154)).
+
 ### Every change needs a claim
 
 `probe` can only verify claims that exist. Every escaped defect in the field
@@ -547,12 +580,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.11.0
+- uses: raccioly/testguard@v0.12.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.11.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.12.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
 ```
 
@@ -580,6 +613,32 @@ talks to the network; only the job posts, and only when told to.
   toward green. The one pass is `killed`; everything else gates.
 - **One exact-pinned runtime dependency** (`ajv`), Node ≥ 20, MIT.
 
+### Prior art, and what was taken from where
+
+Breaking code to test the tests is mutation testing, and it dates to the 1970s.
+Two industrial programmes solved the parts that make it usable, and this tool
+takes from both.
+
+**Google** made it affordable: mutate only *changed* lines, cap what is
+surfaced at seven per file, and order candidates by the measured productivity
+of the operator in similar context — developer feedback took their productive
+rate from 15% to 89%
+([Petrović et al., 2021](https://arxiv.org/abs/2102.11378)). `sweep`'s diff
+scope, its cap and its ordering are theirs; the productivity prior here is
+measured on real probed faults rather than assumed.
+
+**Meta** made it specific: an engineer writes a *concern* in plain text, a
+model drafts faults for it, and every step is gated by execution before a
+human ever sees it — 73% of the resulting tests were accepted
+([Foster et al., FSE 2025](https://arxiv.org/abs/2501.12862)). The rule that
+nothing a model proposes reaches the claims file without passing `probe` and a
+human keep is theirs.
+
+What neither does is bind a fault to a **stated promise**, which is what this
+tool is for. The full record — including what was deliberately *not* taken, the
+measured reason no model decides a verdict, and the gaps in what we borrowed —
+is in [`docs-canonical/PRIOR-ART.md`](docs-canonical/PRIOR-ART.md).
+
 ### What TestGuard is not
 
 - **Not a test generator.** It judges a test the agent wrote (`admit`); the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.11.0",
+  "version": "0.12.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

@@ -313,6 +313,18 @@ const semantic = {
     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})` });
+    // The counters that only mean something in one mode must not appear in the
+    // other: `writeSites` on a diff sweep would be a denominator nobody
+    // measured, and its absence on a save-paths sweep hides the denominator
+    // entirely — which is the whole reason that mode exists.
+    const saves = doc.scope.mode === 'save-paths';
+    for (const k of ['writeSites', 'payloadFields']) {
+      if (saves && doc.scope[k] === undefined) errors.push({ path: `/scope/${k}`, message: `a save-paths sweep must report ${k}: the surface is the denominator its findings are read against` });
+      if (!saves && doc.scope[k] !== undefined) errors.push({ path: `/scope/${k}`, message: `${k} belongs to a save-paths sweep; a changed sweep did not measure the write surface` });
+    }
+    if (saves && doc.scope.writeSites !== undefined && doc.scope.targets > doc.scope.writeSites) {
+      errors.push({ path: '/scope/targets', message: `targets (${doc.scope.targets}) exceeds writeSites (${doc.scope.writeSites}); every target is a file with at least one write` });
+    }
 
     const byClass = Object.values(s.byClass);
     const proposedByClass = byClass.reduce((a, c) => a + c.proposed, 0);

package/spec/schemas/sweep.schema.json

@@ -4,61 +4,165 @@
   "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"],
+  "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" },
+    "$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"],
+      "required": [
+        "mode",
+        "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." },
+        "mode": {
+          "enum": [
+            "changed",
+            "save-paths"
+          ],
+          "description": "What the sweep was pointed at. `changed` proposes for the changed source files that carry no claim. `save-paths` proposes for every file that writes to storage, because a diff cannot answer how many save paths exist — and a clean report over an unstated denominator is a sample of unknown size, not a guarantee."
+        },
+        "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"],
+            "required": [
+              "file",
+              "reason"
+            ],
             "additionalProperties": false,
             "properties": {
-              "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
-              "reason": { "type": "string", "minLength": 1 }
+              "file": {
+                "$ref": "urn:claimspec:v1:common#/$defs/repoPath"
+              },
+              "reason": {
+                "type": "string",
+                "minLength": 1
+              }
             }
           }
+        },
+        "writeSites": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "save-paths only: calls that write to storage across the whole surface, not only the ones probed."
+        },
+        "payloadFields": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "save-paths only: payload keys sitting on their own line, which is what a field-dropped fault can anchor to."
         }
       }
     },
     "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"],
+      "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 },
+        "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"],
+            "required": [
+              "proposed",
+              "selected",
+              "writePath"
+            ],
             "additionalProperties": false,
             "properties": {
-              "proposed": { "type": "integer", "minimum": 0 },
-              "selected": { "type": "integer", "minimum": 0 },
-              "writePath": { "type": "integer", "minimum": 0 }
+              "proposed": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "selected": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "writePath": {
+                "type": "integer",
+                "minimum": 0
+              }
             }
           }
         }
@@ -67,48 +171,120 @@
     "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" }
+      "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"],
+        "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." },
+          "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"],
+              "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 } },
+                "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"],
+                  "required": [
+                    "exact",
+                    "partial",
+                    "argless"
+                  ],
                   "additionalProperties": false,
                   "properties": {
-                    "exact": { "type": "integer", "minimum": 0 },
-                    "partial": { "type": "integer", "minimum": 0 },
-                    "argless": { "type": "integer", "minimum": 0 }
+                    "exact": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "partial": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "argless": {
+                      "type": "integer",
+                      "minimum": 0
+                    }
                   }
                 }
               }
@@ -117,11 +293,18 @@
         }
       }
     },
-    "exitCode": { "enum": [0, 1] },
+    "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" }
+      "items": {
+        "type": "object"
+      }
     }
   }
 }

package/src/cli.mjs

@@ -76,7 +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)
+sweep      --changed <ref> (required unless --save-paths; CI bases and a safe local default are detected)  --cap <n>
+           --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
            --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
@@ -150,6 +153,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         since: { type: 'string' },
         exclude: { type: 'string', multiple: true },
         cap: { type: 'string' },
+        'save-paths': { type: 'boolean', default: false },
         strict: { type: 'boolean', default: false },
         explain: { type: 'boolean', default: false },
         ignore: { type: 'string' },

package/src/commands/sweep.mjs

@@ -20,9 +20,14 @@ export const sweepPath = (projectDir) => join(projectDir, '.testguard', 'sweep.j
  * read.
  */
 export async function sweepCommand({ projectDir, values, version }, io) {
-  const resolved = resolveChangedRef({ explicit: values.changed, projectDir });
+  const mode = values['save-paths'] ? 'save-paths' : 'changed';
+  // `--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);
   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.');
+    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;
   }
   const confirmRuns = Number(values.confirm);
@@ -39,11 +44,12 @@ export async function sweepCommand({ projectDir, values, version }, io) {
       return 3;
     }
   }
-  if (!resolved.required && !values.json && !values.quiet) io.err(`sweep: comparing against ${resolved.ref} (${resolved.from})`);
+  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,

package/src/supply/savepath.mjs

@@ -0,0 +1,216 @@
+/**
+ * Where this project writes to storage, and what it writes.
+ *
+ * A probe answers "would a test notice if this were wrong". It cannot answer
+ * "how many places write to the database, and how many of those has anyone
+ * looked at" — and on an application with two hundred screens that second
+ * question is the one that decides whether a clean report means anything. A
+ * verdict with no denominator is not a guarantee; it is a sample of unknown
+ * size.
+ *
+ * So this enumerates the surface. Measured on a real AI-authored Next.js
+ * application: 115 write sites across 34 source files, of which 46% of the
+ * probed persistence faults survived a fully green suite, and every survivor
+ * was a field dropped from the payload. The faults are already produced by
+ * `field-dropped` and already ranked up by `onWritePath`; what was missing was
+ * the list of places to point them at.
+ *
+ * DELIBERATELY SHALLOW. This finds call sites, not data flow. It does not know
+ * whether a write is reachable, whether two writes are the same transaction,
+ * or whether a helper wraps one. A site it cannot see is reported as nothing
+ * at all rather than as an absence of risk — the same rule the scaffold
+ * producers follow, and the reason `skipped` exists on a sweep. Its output is
+ * a denominator and a set of targets, never a verdict.
+ */
+import { readFileSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { walk } from '../util/glob.mjs';
+
+/**
+ * A call that puts data into storage.
+ *
+ * The receiver is matched by NAME because that is how these layers are bound
+ * in practice — `prisma.user.create`, `tx.invitation.upsert`, `db.orders.insertOne`.
+ * Matching by import would be more correct and would miss the common case
+ * where the client is a module-scope singleton imported under a project alias.
+ *
+ * `delete` is included: a save path that stops deleting is as broken as one
+ * that stops writing, and account deletion is where that matters most.
+ */
+const WRITE_CALL = /\b(prisma|tx|trx|db|database|knex|sequelize|mongoose|supabase|drizzle|client|conn)\s*\.\s*(?:([A-Za-z_$][\w$]*)\s*\.\s*)?(create|createMany|createOne|update|updateMany|updateOne|upsert|insert|insertOne|insertMany|save|delete|deleteMany|deleteOne|destroy|remove|set|put)\s*\(/g;
+
+/**
+ * Raw SQL that writes. A template literal or a string argument, either way.
+ *
+ * Two regexes for one pattern, deliberately. A `g`-flagged RegExp carries
+ * `lastIndex` across calls, so `WRITE_SQL.test(a)` followed by
+ * `WRITE_SQL.test(b)` answers the second question from where the first one
+ * stopped — which makes a scan's result depend on the order the files were
+ * read. `matchAll` needs the flag; the cheap reject must not have it.
+ */
+const WRITE_SQL = /\b(INSERT\s+INTO|UPDATE\s+[A-Za-z_"`[]|DELETE\s+FROM|UPSERT\s+INTO)\b/gi;
+const HAS_SQL = new RegExp(WRITE_SQL.source, 'i');
+
+/**
+ * Every operation name the call pattern accepts, as one alternation. Derived
+ * rather than written twice: the cheap reject below used a shorter list, and a
+ * `deleteMany(` call matched the full pattern while failing the reject, so
+ * every file whose only write was a `...Many` or `...One` call was dropped
+ * from the surface before it was ever scanned.
+ */
+const OPERATIONS = 'create|createMany|createOne|update|updateMany|updateOne|upsert|insert|insertOne|insertMany|save|delete|deleteMany|deleteOne|destroy|remove|set|put';
+const HAS_WRITE_CALL = new RegExp(`\\b(?:${OPERATIONS})\\s*\\(`);
+
+/**
+ * Files that contain writes but are never the product's own save path.
+ *
+ * Seed and migration scripts write, and a real run surfaced
+ * `prisma/seed-badges.ts` as NOCOVER — true, and not a finding: nobody tests a
+ * seed script, and reporting it teaches the reader to skim. The directory
+ * forms are matched as well as the file stems, because a seed lives in
+ * `prisma/seed.ts` as often as in `seeds/`.
+ */
+const NOT_SOURCE = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(tests?|__tests__|__mocks__|__fixtures__|fixtures|migrations|seeds?|scripts?|prisma|drizzle)\/|(^|\/)seeds?[.-][^/]*$|(^|\/)seeds?\.[cm]?[jt]sx?$/;
+
+const SOURCE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx']);
+
+/**
+ * The text of one call's arguments, from its open parenthesis to the matching
+ * close, with quotes tracked so a parenthesis inside a string is not counted.
+ *
+ * The same scan `payloadAssertions` uses, and for the same reason: a
+ * fixed-width window reads into the NEXT call, and on a file with several
+ * writes in a row that silently attributes one write's payload to another.
+ */
+export 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 { start: open + 1, end: i, text: source.slice(open + 1, i) };
+    }
+  }
+  return { start: open + 1, end: source.length, text: source.slice(open + 1) };
+}
+
+/**
+ * The keys of a write's payload, each with the line it sits on.
+ *
+ * Both property forms, because shorthand is not an edge case here: every
+ * surviving payload fault measured on the register action was shorthand
+ * (`email,` `username,` `password_hash,`). A pattern requiring a colon would
+ * miss exactly the fields this exists to find.
+ *
+ * Keys are read only where they sit on their own line, which is what the
+ * `field-dropped` producer can anchor to. A single-line write like
+ * `update({ where, data })` therefore reports no keys — correctly, because
+ * there is no line to delete.
+ */
+export function payloadKeys(argsText, firstLine) {
+  const keys = [];
+  argsText.split('\n').forEach((line, i) => {
+    const m = /^\s*(?:['"`])?([A-Za-z_$][\w$]*)(?:['"`])?\s*(?::|,\s*$)/.exec(line);
+    if (m) keys.push({ key: m[1], line: firstLine + i });
+  });
+  return keys;
+}
+
+/** Line number (1-based) of an index into a source string. */
+const lineAt = (source, index) => source.slice(0, index).split('\n').length;
+
+/**
+ * Every write this file performs. Pure apart from the read; exported so the
+ * shape can be tested against a string without a project on disk.
+ */
+export function writeSitesIn(source, file) {
+  const sites = [];
+  for (const m of source.matchAll(WRITE_CALL)) {
+    const open = m.index + m[0].length - 1;
+    const args = balancedArgs(source, open);
+    const line = lineAt(source, m.index);
+    sites.push({
+      file,
+      line,
+      endLine: lineAt(source, args.end),
+      receiver: m[1],
+      model: m[2] ?? null,
+      operation: m[3],
+      keys: payloadKeys(args.text, lineAt(source, args.start)),
+    });
+  }
+  for (const m of source.matchAll(WRITE_SQL)) {
+    sites.push({
+      file,
+      line: lineAt(source, m.index),
+      endLine: lineAt(source, m.index),
+      receiver: 'sql',
+      model: null,
+      operation: m[1].split(/\s+/)[0].toLowerCase(),
+      keys: [],
+    });
+  }
+  // Deterministic: a surface that reorders between runs is not a denominator.
+  return sites.sort((a, b) => a.line - b.line || a.operation.localeCompare(b.operation));
+}
+
+/** Is this path part of the product's own save surface? */
+export const isSaveSource = (rel) => SOURCE_EXT.has(extname(rel)) && !NOT_SOURCE.test(rel);
+
+/**
+ * The project's whole write surface: every source file that writes, and every
+ * write in it.
+ *
+ * `files` may be given to scope the scan (a diff, a directory); the default is
+ * every source file the glob walker can see.
+ */
+export function saveSurface(projectDir, { files } = {}) {
+  const candidates = (files ?? walk(projectDir)).filter(isSaveSource);
+  const byFile = [];
+  let siteCount = 0;
+  let keyCount = 0;
+  for (const rel of candidates) {
+    let source;
+    try {
+      source = readFileSync(join(projectDir, rel), 'utf8');
+    } catch {
+      continue;
+    }
+    // Cheap reject before the balanced scan: most files never write.
+    if (!HAS_WRITE_CALL.test(source) && !HAS_SQL.test(source)) continue;
+    const sites = writeSitesIn(source, rel);
+    if (!sites.length) continue;
+    byFile.push({ file: rel, sites });
+    siteCount += sites.length;
+    keyCount += sites.reduce((a, s) => a + s.keys.length, 0);
+  }
+  byFile.sort((a, b) => a.file.localeCompare(b.file));
+  return { files: byFile, fileCount: byFile.length, siteCount, keyCount };
+}
+
+/**
+ * The surface as text — the denominator, said out loud.
+ *
+ * A report that lists findings without saying how much was looked at invites
+ * the reader to assume the rest is fine, which is the assumption this whole
+ * tool exists to remove.
+ */
+export function renderSurface(surface, { limit = 10 } = {}) {
+  if (surface.fileCount === 0) return 'no write to storage found in this project.';
+  const out = [`${surface.siteCount} write${surface.siteCount === 1 ? '' : 's'} to storage across ${surface.fileCount} file${surface.fileCount === 1 ? '' : 's'}, carrying ${surface.keyCount} payload field${surface.keyCount === 1 ? '' : 's'} on their own lines.`];
+  const ranked = [...surface.files].sort((a, b) => b.sites.length - a.sites.length || a.file.localeCompare(b.file));
+  for (const f of ranked.slice(0, limit)) {
+    const ops = [...new Set(f.sites.map((s) => s.operation))].sort().join(', ');
+    out.push(`  ${String(f.sites.length).padStart(3)}  ${f.file}  (${ops})`);
+  }
+  if (ranked.length > limit) out.push(`  … ${ranked.length - limit} more files`);
+  return out.join('\n');
+}

package/src/sweep/sweep.mjs

@@ -35,6 +35,7 @@ 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 { saveSurface } from '../supply/savepath.mjs';
 import { persistenceSignals, persistenceHint } from '../supply/persistence.mjs';
 import { probe } from '../probe/probe.mjs';
 import { hintFor } from '../brief/brief.mjs';
@@ -126,6 +127,7 @@ function claimsFromSelection(selected) {
 export async function sweep({
   projectDir,
   ref,
+  mode = 'changed',
   includeDirty = false,
   exclude = [],
   cap,
@@ -142,9 +144,20 @@ export async function sweep({
   onWarn = () => {},
 }) {
   const gate = computeChangedGate({ projectDir, ref, includeDirty, exclude, toolVersion, claimsPath, ignorePath });
+
+  // ── What the sweep is pointed at. ──
+  // `changed` asks "what did this change leave unclaimed". `save-paths` asks a
+  // question the diff cannot: "of every place this project writes to storage,
+  // how many would notice if the write stopped carrying a field". The second
+  // needs the whole surface, because a clean report over an unstated
+  // denominator is a sample of unknown size, not a guarantee.
+  //
   // 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 surface = mode === 'save-paths' ? saveSurface(projectDir) : null;
+  const targets = surface
+    ? surface.files.map((f) => f.file)
+    : gate.uncovered.filter((u) => u.kind === 'source').map((u) => u.file);
 
   const cPath = claimsPath ?? defaultClaimsPath(projectDir);
   const existingClaims = existsSync(cPath) ? loadClaims(cPath) : { claims: [] };
@@ -220,7 +233,9 @@ export async function sweep({
     head: gate.head,
     includeDirty,
     scope: {
+      mode,
       changed: gate.changed,
+      ...(surface ? { writeSites: surface.siteCount, payloadFields: surface.keyCount } : {}),
       targets: targets.length,
       swept: drafts.length,
       ...(skipped.length ? { skipped } : {}),
@@ -243,13 +258,20 @@ export async function sweep({
 export function renderSweep(doc, { limit = 20 } = {}) {
   const out = [];
   const { scope, selection } = doc;
+  const saves = scope.mode === 'save-paths';
   if (scope.targets === 0) {
-    out.push(`sweep: no changed source file is without a claim against ${doc.ref}. Nothing to propose.`);
+    out.push(saves
+      ? 'sweep: no write to storage found in this project. Nothing to propose.'
+      : `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}.`);
+  // The denominator first. A report that lists findings without saying how much
+  // was looked at invites the reader to assume the rest is fine.
+  out.push(saves
+    ? `${scope.writeSites} write${scope.writeSites === 1 ? '' : 's'} to storage across ${scope.targets} file${scope.targets === 1 ? '' : 's'}, carrying ${scope.payloadFields} payload field${scope.payloadFields === 1 ? '' : 's'}. Swept ${scope.swept}.`
+    : `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.`);
+  if (selection.deferred) out.push(`  The ${selection.deferred} deferred are not a verdict: raise --cap${saves ? '.' : ', or sweep a smaller change.'}`);
   for (const s of scope.skipped ?? []) out.push(`  skipped ${s.file}: ${s.reason}`);
   out.push('');
 
@@ -268,6 +290,12 @@ export function renderSweep(doc, { limit = 20 } = {}) {
     }
     if (doc.findings.length > limit) out.push(`  … ${doc.findings.length - limit} more in the sweep document`);
   }
+  if (saves) {
+    out.push('');
+    out.push(`This is a sample of the write surface, not a verdict over it: ${selection.selected} of`);
+    out.push(`${selection.proposed} proposed faults were probed. The ${scope.writeSites} writes above are the`);
+    out.push('denominator — a clean sweep says nothing about the ones nobody pointed a fault at.');
+  }
   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');

package/src/util/glob.mjs

@@ -5,7 +5,15 @@ import { join } from 'node:path';
 // 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.
+// `dist` and `coverage` were here from the start; the framework build outputs
+// were not, and the claim above them already promised that "a build's test
+// files" are not this project's. A Next.js `.next/` carries compiled copies of
+// the application — including its writes and its tests — so a surface scan of a
+// real app counted the same code twice and a defender glob could match a
+// compiled chunk. The promise was right and the list was short.
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.testguard',
+  '.next', '.nuxt', '.svelte-kit', '.output', '.turbo', '.parcel-cache', '.angular', '.astro',
+  'build', 'out', '.cache', '.vercel', '.netlify',
   '__pycache__', '.venv', 'venv', 'site-packages', '.tox', '.nox',
   '.pytest_cache', '.mypy_cache', '.ruff_cache', '.eggs']);