testguard-cli 0.10.4 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,91 @@ 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`.
+
+### 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.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.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.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
@@ -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,104 @@ 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.
+
+#### 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
@@ -481,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.10.4
+- 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.10.4/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
 ```
 
@@ -514,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
@@ -824,7 +949,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.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

@@ -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,60 @@ 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})` });
+    // 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);
+    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,310 @@
+{
+  "$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": [
+        "mode",
+        "changed",
+        "targets",
+        "swept"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "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"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "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"
+      ],
+      "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"
+      }
+    }
+  }
+}