testguard-cli 0.10.4__tar.gz → 0.11.0__tar.gz

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/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`.

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.10.4
+Version: 0.11.0
 Summary: 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. Ships the Node.js CLI (requires Node.js 20+).
 Project-URL: Homepage, https://github.com/raccioly/testguard
 Project-URL: Documentation, https://github.com/raccioly/testguard#readme
@@ -151,9 +151,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
@@ -171,6 +171,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
@@ -424,6 +425,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
@@ -505,12 +571,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
 ```
 
@@ -848,7 +914,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

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/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

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/action.yml

@@ -46,7 +46,7 @@ inputs:
   version:
     description: 'testguard-cli version to run'
     required: false
-    default: '0.10.4'
+    default: '0.11.0'
   node-version:
     description: 'Node.js version (20+)'
     required: false

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/docs/testguard-explained.html

@@ -144,7 +144,7 @@
 <div class="page">
   <div class="masthead">
     <div class="wordmark">Test<span class="mark">Guard</span></div>
-    <div class="meta">Technical Brief · v0.10.4 · MIT</div>
+    <div class="meta">Technical Brief · v0.11.0 · MIT</div>
   </div>
 
   <h1>Your tests pass. That is not the same as your tests working.</h1>

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/docs-canonical/ARCHITECTURE.md

@@ -49,6 +49,8 @@ code were wrong, would anything fail?*
 | Cost | What a probe spent, per claim and per defender file, derived from evidence | `src/probe/cost.mjs` |
 | Progress | How a running probe reports itself, per reader: tty, plain, ndjson | `src/probe/progress.mjs` |
 | Change gate | Claim coverage of a diff | `src/gate/changed.mjs` |
+| Sweep | The cold start: propose faults for changed files that carry no claim, probe a bounded selection, report what nothing noticed | `src/sweep/sweep.mjs` |
+| Claim supply | Which proposals are worth probing, and why a survivor on a write path was missed | `src/supply/select.mjs`, `src/supply/persistence.mjs` |
 | Baseline | Freeze debt; gate the delta; re-stamp | `src/baseline/baseline.mjs` |
 | Status | The single state machine every rendering derives from | `src/status/status.mjs` |
 | Brief | The agent's session-start blind-spot block | `src/brief/brief.mjs` |
@@ -68,7 +70,8 @@ never the layers above.
 |---|---|---|
 | `cli.mjs` | commands | engine modules directly |
 | `src/commands/` | engine modules, `spec/lib` | other commands |
-| Engine (`probe`, `gate`, `baseline`, `status`, `brief`, `admit`, `replay`) | `spec/lib`, `src/util`, `src/git.mjs`, runners | commands, `cli.mjs` |
+| Engine (`probe`, `gate`, `baseline`, `status`, `brief`, `admit`, `replay`, `sweep`) | `spec/lib`, `src/util`, `src/git.mjs`, runners, `src/supply` | commands, `cli.mjs` |
+| Claim supply (`src/supply/`) | `src/util` | the probe orchestrator, commands, `cli.mjs` |
 | `src/probe/runners/` | `src/util`, `shared.mjs` | the probe orchestrator |
 | `spec/lib/` | nothing in `src/` | all of `src/` |
 

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "testguard-cli",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "testguard-cli",
-      "version": "0.10.4",
+      "version": "0.11.0",
       "license": "MIT",
       "dependencies": {
         "ajv": "8.20.0"

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/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",

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/packaging/gitlab/testguard.gitlab-ci.yml

@@ -3,7 +3,7 @@
 # Include it from a project's .gitlab-ci.yml, pinned to a release:
 #
 #   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            # where testguard.claims.json lives (default ".")
 #         post_note: true         # post the brief as a merge-request note (needs TESTGUARD_GITLAB_TOKEN, api scope)
@@ -29,7 +29,7 @@ spec:
   inputs:
     version:
       description: testguard-cli version to run
-      default: "0.10.4"
+      default: "0.11.0"
     dir:
       description: directory whose test runner is invoked (where testguard.claims.json lives)
       default: "."

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/packaging/homebrew/testguard.rb

@@ -15,8 +15,8 @@
 class Testguard < Formula
   desc "Proves a test suite defends the claims a project makes"
   homepage "https://github.com/raccioly/testguard"
-  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.10.4.tgz"
-  sha256 "b0b73956e7d5c51b0ad40dcb1333a5e18b599e990e707d7ac90a87ce66156178"
+  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.11.0.tgz"
+  sha256 "c2e36e07108e8d40197aa37cf8d23589c38dc265fddd589a4c890e4c6377cac4"
   license "MIT"
 
   depends_on "node"

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 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. Ships the Node.js CLI (requires Node.js 20+)."
 readme = "README.md"
 license = { text = "MIT" }

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/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' });

testguard_cli-0.11.0/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" }
+    }
+  }
+}

{testguard_cli-0.10.4 → testguard_cli-0.11.0}/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' },