testguard-cli 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-22
+
+Automated weekly release — everything merged since `v0.12.0`.
+
+### Changed
+
+- chore(homebrew): sha256 for v0.12.0 (#159)
+- feat: persistence provability, and an ordering that learns from this project's own verdicts (#157)
+
+
 ## [0.12.0] - 2026-09-22
 
 Automated weekly release — everything merged since `v0.11.0`.
@@ -18,6 +28,53 @@ Automated weekly release — everything merged since `v0.11.0`.
 - chore(homebrew): sha256 for v0.11.0 (#153)
 
 
+### Added
+
+- **Concerns** — one sentence a human writes that generates faults across a
+  whole surface, the rung between writing nothing and writing a claim per
+  behaviour. A concern says *where* to look and *which shapes of break* are
+  relevant: `"every write persists the data it was given"` targets the write
+  sites and applies the payload producers. `testguard concerns` lists them,
+  `sweep --concern <ID>` aims a sweep by one, and `--save-paths` is now sugar
+  for the built-in `SAVE-PERSISTS`.
+  - Two built-ins ship, and only two: an authorization concern would need a
+    heuristic for "which files check permissions", and a guess there is the
+    non-actionable noise that gets a check switched off. A project that knows
+    its own auth layer says so with a `glob` target in three lines.
+  - A project concern with the same id **replaces** a built-in, so a team can
+    retune `SAVE-PERSISTS` for an ORM this tool does not recognise without
+    forking anything. The replacement is reported, never silent.
+  - `urn:claimspec:v1:concerns`, with rules that refuse a glob target naming no
+    globs (it would match nothing and report clean) and an empty fault-class
+    list (a typo for "every class", every time).
+  - **No model is required, deliberately.** A concern's useful core is a named
+    scope plus a producer selection, which the mechanical producers already
+    satisfy — so every verifying command stays offline and NFR-01 is unchanged.
+    An LLM can later propose faults a line-oriented producer cannot see, as an
+    additional source for a concern that already works.
+
+### Added
+
+- A save-path sweep now reports **what its defenders could prove**, before it
+  reports what they did: per file, whether every defender mocks the persistence
+  layer (call shape only), at least one does not (a real write is possible), or
+  there is no defender at all. When nothing is unmocked the report says so
+  outright — a clean probe there is not evidence of persistence, it is evidence
+  that nothing could have measured it. Measured on a real AI-authored
+  application: of 37 files that write to storage, 32 were defended only by
+  mocking tests.
+- `scope.provability` on the sweep document, with a validator rule that every
+  target is classified exactly once.
+- The candidate ordering now **learns from this project's own probed verdicts**
+  instead of only the shipped productivity prior. Every evidence record already
+  carries a `faultClass` and a `verdict`, so "how often does a fault of this
+  class survive *here*" is a tally rather than a new thing to capture. A sweep
+  persists its own evidence to `.testguard/sweep-evidence.json` — beside the
+  canonical one, never replacing it — so the next run learns from
+  machine-proposed faults, the same distribution the ranker orders. The sweep
+  document records `ordering.observed` and `ordering.sources`, because an
+  ordering nobody can trace is a number nobody should trust.
+
 ### Added
 
 - `sweep --save-paths` — sweep every file that writes to storage instead of the

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.12.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.13.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.12.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.13.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
@@ -451,6 +451,14 @@ Three rules make it safe to run on a repository that has never seen this tool:
   is reported and never gates — a tool that fails because its own guess was bad
   is a tool people switch off.
 
+The ordering **learns from your own runs**. Every evidence record already
+carries a fault class and a verdict, so "how often does a fault of this class
+survive here" is a tally, not a new thing to collect — a sweep persists its
+evidence and the next one reads it. A project with no evidence falls back to
+the shipped prior and says so; one with its own records overrides it in
+proportion to how many it has. The report names which, because an ordering
+nobody can trace is a number nobody should trust.
+
 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
@@ -466,6 +474,60 @@ 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.
 
+#### Concerns: one sentence, two hundred screens
+
+A claim names one promise precisely, which is why a repository with two hundred
+screens never finishes writing them. A **concern** names a *kind* of promise and
+says where to look for it:
+
+```bash
+npx testguard-cli concerns                      # what this project can be swept by
+npx testguard-cli sweep --concern ADMIN-GUARDS  # aim a sweep at one
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "concerns": [
+    {
+      "id": "ADMIN-GUARDS",
+      "statement": "Every admin route refuses a caller without the admin role.",
+      "severity": "critical",
+      "targets": { "kind": "glob", "globs": ["src/app/api/admin/**"] },
+      "faultClasses": ["guard-removed", "condition-forced", "return-altered"]
+    }
+  ]
+}
+```
+
+Five lines, and the sweep reports:
+
+```
+concern ADMIN-GUARDS matches 24 files. Swept 23.
+  158 further proposals were outside this concern's fault classes.
+
+SURVIVED   src/app/api/admin/claims/[id]/route.ts
+  [line 41] Guard never triggers: `if (!membership || (membership.role !== 'owner'
+  && membership.role !== 'manager'))` becomes `if (false)`.
+```
+
+The idea is Meta's: ACH has an engineer describe an area of concern in plain
+text and gates every generated step by execution. What is taken here is the
+**unit** — the concern as the thing a human writes — not their generator, and
+**no model is required**. A concern's useful core is a named scope plus a
+producer selection, which the mechanical producers already satisfy, so every
+verifying command stays offline.
+
+Two concerns ship built in, and only two. An authorization concern would need a
+heuristic for *"which files check permissions"*, and a guess there is exactly
+the noise that gets a check switched off — so `SAVE-PERSISTS` and
+`CHANGED-CODE` are the defaults, and a project that knows its own auth layer
+says so in three lines. Declaring a concern with a built-in's id replaces it,
+and the replacement is reported rather than silent.
+
+A concern is **not** a claim and never becomes one by itself. It says where to
+look; the probe says what it found; a human states the sentence worth defending.
+
 #### Sweeping the save surface instead of the diff
 
 A diff cannot answer *"when the user clicks save, does it actually save?"* — it
@@ -494,10 +556,26 @@ denominator comes first and the document carries `writeSites` and
 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)).
+It also states, before any verdict, **what the defenders could prove at all**:
+
+```
+of those 37 files: 32 defended only by tests that mock the persistence layer,
+1 with an unmocked defender, 4 with no defender at all.
+```
+
+That line is the read-back answer. A test that replaced the database can prove
+the *call shape* and nothing beyond it — a `where` that matches no rows, a
+rolled-back transaction and a rejected constraint all pass against a mock that
+recorded the arguments and returned a plausible object. So rather than pretend
+to measure persistence, TestGuard states the limit, the same way `nocover` says
+"no test imports this" instead of guessing.
+
+When every defender mocks the layer, the report says so outright: *nothing in
+this suite can prove a write reached storage*. A clean probe there is not
+evidence of persistence — it is evidence that nothing could have measured it.
+
+`unmocked` is deliberately weaker than "proves persistence": a test that does
+not replace the database may simply never reach it. Possible is the honest word.
 
 ### Every change needs a claim
 
@@ -580,12 +658,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.12.0
+- uses: raccioly/testguard@v0.13.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.12.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.13.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
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.12.0",
+  "version": "0.13.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', 'sweep']);
+export const KINDS = Object.freeze(['claims', 'evidence', 'baseline', 'ignore', 'calibration', 'brief', 'status', 'gate', 'replay', 'sweep', 'concerns']);
 /**
  * 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,29 @@ const semantic = {
     return errors;
   },
 
+  concerns(doc) {
+    const errors = [];
+    const seen = new Set();
+    doc.concerns.forEach((c, i) => {
+      if (seen.has(c.id)) errors.push({ path: `/concerns/${i}/id`, message: `duplicate concern id "${c.id}"` });
+      seen.add(c.id);
+      // A glob target with no globs matches nothing, which reads as "this
+      // concern found no problems" rather than "this concern was never aimed".
+      if (c.targets?.kind === 'glob' && !(c.targets.globs?.length > 0)) {
+        errors.push({ path: `/concerns/${i}/targets/globs`, message: `concern "${c.id}" targets a glob but names none; it would match nothing and report clean` });
+      }
+      if (c.targets?.kind !== 'glob' && c.targets?.globs) {
+        errors.push({ path: `/concerns/${i}/targets/globs`, message: `concern "${c.id}" names globs but does not target them` });
+      }
+      // An empty list is not "every class"; it is a concern that can never
+      // propose anything, which is a typo for `null` every time.
+      if (Array.isArray(c.faultClasses) && c.faultClasses.length === 0) {
+        errors.push({ path: `/concerns/${i}/faultClasses`, message: `concern "${c.id}" allows no fault class; omit the field for every class` });
+      }
+    });
+    return errors;
+  },
+
   sweep(doc) {
     const errors = [];
     const s = doc.selection;
@@ -318,10 +341,17 @@ const semantic = {
     // 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']) {
+    for (const k of ['writeSites', 'payloadFields', 'provability']) {
       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.provability) {
+      const pv = doc.scope.provability;
+      const total = pv.mocked + pv.unmocked + pv.none;
+      // Every target is classified exactly once. A surface whose provability
+      // does not account for all of it has a bucket nobody looked in.
+      if (total !== doc.scope.targets) errors.push({ path: '/scope/provability', message: `provability accounts for ${total} files; targets is ${doc.scope.targets}` });
+    }
     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` });
     }
@@ -343,6 +373,12 @@ const semantic = {
     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` });
 
+    // An ordering that claims to have learned from something must name it.
+    if (doc.ordering) {
+      if (doc.ordering.observed > 0 && doc.ordering.sources.length === 0) errors.push({ path: '/ordering/sources', message: 'an ordering learned from evidence must name the documents it was learned from' });
+      if (doc.ordering.observed === 0 && doc.ordering.sources.length > 0) errors.push({ path: '/ordering/observed', message: 'sources are named but nothing was observed; the ordering used the shipped prior' });
+    }
+
     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' });

package/spec/schemas/concerns.schema.json

@@ -0,0 +1,41 @@
+{
+  "$id": "urn:claimspec:v1:concerns",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "claimspec v1 — concerns",
+  "description": "A concern is one sentence a human writes that generates faults across a whole surface: it says WHERE to look and WHICH shapes of break are relevant. It is the rung between writing nothing and writing a claim per behaviour. A concern is never a claim and never becomes one by itself — it says where to look, the probe says what it found, and a human states the sentence worth defending. Nothing in this document is a promise about the code; only a claim is that.",
+  "type": "object",
+  "required": ["schemaVersion", "concerns"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "concerns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "statement"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "$ref": "urn:claimspec:v1:common#/$defs/identifier", "description": "Declaring an id that matches a built-in REPLACES it, which is how a project retunes a default for an ORM or a layout this tool does not recognise. The replacement is reported, never silent." },
+          "statement": { "type": "string", "minLength": 1, "description": "The sentence, in plain language. It describes a KIND of promise, not one behaviour: \"every write persists the data it was given\", not \"the register action stores password_hash\". The second is a claim." },
+          "severity": { "$ref": "urn:claimspec:v1:common#/$defs/severity" },
+          "targets": {
+            "type": "object",
+            "required": ["kind"],
+            "additionalProperties": false,
+            "description": "Where this concern applies. `write-sites` asks the write enumerator. `glob` matches paths. `changed` defers to whatever diff the caller is already measuring — a concern does not re-derive what the gate computed.",
+            "properties": {
+              "kind": { "enum": ["write-sites", "glob", "changed"] },
+              "globs": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+            }
+          },
+          "faultClasses": {
+            "type": ["array", "null"],
+            "items": { "$ref": "urn:claimspec:v1:common#/$defs/faultClass" },
+            "description": "Which producers are relevant. `null` or absent means every class, the honest default for a concern with no shape to narrow by. Narrowing is what makes one sentence useful across two hundred files: a persistence concern that also reported every altered return value would bury the payload findings it exists to surface."
+          }
+        }
+      }
+    }
+  }
+}

package/spec/schemas/sweep.schema.json

@@ -62,6 +62,10 @@
           ],
           "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."
         },
+        "concern": {
+          "$ref": "urn:claimspec:v1:common#/$defs/identifier",
+          "description": "The concern this sweep was aimed by, when one was. A concern narrows both the targets and the fault classes, so the same surface swept under two concerns is two different questions."
+        },
         "changed": {
           "type": "integer",
           "minimum": 0,
@@ -107,6 +111,30 @@
           "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."
+        },
+        "provability": {
+          "type": "object",
+          "required": [
+            "mocked",
+            "unmocked",
+            "none"
+          ],
+          "additionalProperties": false,
+          "description": "save-paths only: what the defenders of this surface are CAPABLE of proving, before anything is probed. `mocked` — every defender replaces the persistence layer, so it can prove the call shape and never that the row landed. `unmocked` — at least one does not, so a real write is at least possible (not a promise that one happens). `none` — no defender at all. On a surface that is entirely `mocked`, a clean probe is not evidence of persistence; it is evidence that nothing could have measured it.",
+          "properties": {
+            "mocked": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "unmocked": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "none": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
         }
       }
     },
@@ -165,6 +193,11 @@
               }
             }
           }
+        },
+        "outOfScope": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Proposals the concern's fault classes excluded. Reported so a narrow concern cannot look like a quiet one: the producers found these, and this concern is not about them."
         }
       }
     },
@@ -305,6 +338,29 @@
       "items": {
         "type": "object"
       }
+    },
+    "ordering": {
+      "type": "object",
+      "required": [
+        "observed",
+        "sources"
+      ],
+      "additionalProperties": false,
+      "description": "Where the candidate ordering came from. `observed` is how many of this project's OWN probed faults informed it; 0 means the shipped productivity prior was used unchanged. An ordering nobody can trace is a number nobody should trust.",
+      "properties": {
+        "observed": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sources": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "The evidence documents the counts were read from."
+        }
+      }
     }
   }
 }

package/src/cli.mjs

@@ -19,6 +19,7 @@ import { replayCommand } from './commands/replay.mjs';
 import { mcpCommand } from './commands/mcp.mjs';
 import { admitCommand } from './commands/admit.mjs';
 import { sweepCommand } from './commands/sweep.mjs';
+import { concernsCommand } from './commands/concerns.mjs';
 
 const VERSION = JSON.parse(readFileSync(join(fileURLToPath(import.meta.url), '..', '..', 'package.json'), 'utf8')).version;
 const ISSUES = 'https://github.com/raccioly/testguard/issues';
@@ -34,6 +35,7 @@ export const USAGE = `testguard ${VERSION} — proves a test suite defends the c
   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 concerns [dir]   the one-sentence scopes a sweep can be aimed by: where to look, and which shapes of break are relevant
   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?
@@ -77,6 +79,8 @@ probe
 
 scaffold   --claim <ID> (put every proposal under this claim; copies it if it exists)  --out <path>  --json
 sweep      --changed <ref> (required unless --save-paths; CI bases and a safe local default are detected)  --cap <n>
+           --concern <ID>    aim the sweep by one of this project's concerns: its targets and its fault classes.
+                             testguard concerns lists them. --save-paths is sugar for the built-in SAVE-PERSISTS
            --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
@@ -126,7 +130,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, sweep: sweepCommand };
+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, concerns: concernsCommand };
 
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
   let parsed;
@@ -154,6 +158,8 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         exclude: { type: 'string', multiple: true },
         cap: { type: 'string' },
         'save-paths': { type: 'boolean', default: false },
+        concern: { type: 'string' },
+        concerns: { type: 'string' },
         strict: { type: 'boolean', default: false },
         explain: { type: 'boolean', default: false },
         ignore: { type: 'string' },

package/src/commands/concerns.mjs

@@ -0,0 +1,32 @@
+import { resolve } from 'node:path';
+import { loadConcerns, renderConcerns } from '../supply/concerns.mjs';
+import { validate } from '../../spec/lib/validate.mjs';
+
+/**
+ * `testguard concerns [dir]`: the one-sentence scopes a sweep can be aimed by.
+ *
+ * A concern says WHERE to look and WHICH shapes of break are relevant. It is
+ * never a promise about the code — only a claim is that — so this command
+ * validates and lists, and has no exit code that means "something is wrong
+ * with your project". Exit 2 is a malformed concerns file, which is wrong with
+ * the FILE.
+ */
+export async function concernsCommand({ projectDir, values, version }, io) {
+  const path = values.concerns ? resolve(values.concerns) : undefined;
+  const loaded = loadConcerns(projectDir, { path });
+
+  if (loaded.source) {
+    const result = validate('concerns', { schemaVersion: 1, concerns: loaded.raw });
+    if (!result.ok) {
+      io.err(`${loaded.source} does not conform to the spec:`);
+      for (const e of result.errors) io.err(`  ${e.path}: ${e.message}`);
+      return 2;
+    }
+  }
+  if (values.json) {
+    io.out(JSON.stringify({ schemaVersion: 1, tool: { name: 'testguard', version }, source: loaded.source, shadowed: loaded.shadowed, concerns: loaded.concerns }, null, 2));
+  } else {
+    io.out(renderConcerns(loaded));
+  }
+  return 0;
+}

package/src/commands/sweep.mjs

@@ -1,9 +1,17 @@
 import { join, resolve } from 'node:path';
-import { sweep, renderSweep } from '../sweep/sweep.mjs';
+import { sweep, renderSweep, ConcernError } from '../sweep/sweep.mjs';
 import { resolveChangedRef } from '../gate/changed.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 
 export const sweepPath = (projectDir) => join(projectDir, '.testguard', 'sweep.json');
+/**
+ * A sweep's own evidence, beside the canonical one and never replacing it.
+ * The next sweep reads it to learn which fault classes are productive HERE,
+ * which is the feedback half of the selection Google reports taking from 15%
+ * to 89% productive. Machine-proposed faults, so it is the closest observation
+ * of the distribution the ranker actually orders.
+ */
+export const sweepEvidencePath = (projectDir) => join(projectDir, '.testguard', 'sweep-evidence.json');
 
 /**
  * `testguard sweep [dir] --changed <ref>`: propose faults for the changed
@@ -21,11 +29,14 @@ export const sweepPath = (projectDir) => join(projectDir, '.testguard', 'sweep.j
  */
 export async function sweepCommand({ projectDir, values, version }, io) {
   const mode = values['save-paths'] ? 'save-paths' : 'changed';
+  // A concern that aims at the write surface or at a glob needs no diff, the
+  // same as --save-paths. Only a concern that defers to the gate does.
+  const aimed = Boolean(values.concern) || mode === 'save-paths';
   // `--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);
+    ?? (aimed ? { ref: 'HEAD', from: values.concern ? `concern ${values.concern}` : '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. Or sweep the write surface instead with --save-paths.');
     return 3;
@@ -46,34 +57,52 @@ export async function sweepCommand({ projectDir, values, version }, io) {
   }
   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,
-    confirmRuns,
-    budgetMs,
-    runnerCommand: values['runner-cmd'],
-    runnerName: values.runner,
-    nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
-    toolVersion: version,
-    claimsPath: values.claims ? resolve(values.claims) : undefined,
-    ignorePath: values.ignore ? resolve(values.ignore) : undefined,
-    onStage: !values.quiet && !values.json && process.stderr.isTTY
+  let doc;
+  try {
+    doc = await sweep({
+      projectDir,
+      ref: resolved.ref,
+      mode,
+      concern: values.concern,
+      concernsPath: values.concerns ? resolve(values.concerns) : undefined,
+      includeDirty: values['include-dirty'],
+      exclude: values.exclude ?? [],
+      cap,
+      confirmRuns,
+      budgetMs,
+      runnerCommand: values['runner-cmd'],
+      runnerName: values.runner,
+      nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+      toolVersion: version,
+      claimsPath: values.claims ? resolve(values.claims) : undefined,
+      ignorePath: values.ignore ? resolve(values.ignore) : undefined,
+      onStage: !values.quiet && !values.json && process.stderr.isTTY
       ? ({ claimId, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${claimId}/${faultId} ${stage} ${i}/${n}`)
       : undefined,
-    onWarn: (m) => { if (!values.quiet) io.err(`warning: ${m}`); },
-  });
+      onWarn: (m) => { if (!values.quiet) io.err(`warning: ${m}`); },
+    });
+  } catch (e) {
+    // A concern named on the command line that this project does not declare
+    // is a usage error, not a precondition failure: nothing about the
+    // repository is wrong.
+    if (e instanceof ConcernError) {
+      io.err(e.message);
+      return 3;
+    }
+    throw e;
+  }
   if (process.stderr.isTTY && !values.quiet && !values.json) process.stderr.write('\r\x1b[K');
 
+  const { evidence, ...document } = doc;
   const outPath = values.out ? resolve(values.out) : sweepPath(projectDir);
-  writeSpecDoc('sweep', outPath, doc);
+  writeSpecDoc('sweep', outPath, document);
+  // Written only when something was actually probed: an empty document would
+  // teach the next run that every class is unproductive.
+  if (evidence?.records?.length) writeSpecDoc('evidence', sweepEvidencePath(projectDir), evidence);
   if (values.json) {
-    io.out(JSON.stringify(doc, null, 2));
+    io.out(JSON.stringify(document, null, 2));
   } else {
-    io.out(renderSweep(doc, { limit: Number(values.max) || 20 }));
+    io.out(renderSweep(document, { limit: Number(values.max) || 20 }));
     if (!values.quiet) io.out(`\nsweep: ${outPath}`);
   }
   return doc.exitCode;

package/src/supply/concerns.mjs

@@ -0,0 +1,162 @@
+/**
+ * A concern: one sentence a human writes, that generates faults across a whole
+ * surface.
+ *
+ * The rung between "nothing written" and "a claim per behaviour". A claim names
+ * one promise and the faults that would break it; that is precise and it is why
+ * a repository with two hundred screens never finishes writing them. A concern
+ * names a KIND of promise — "every write persists the data it was given" — and
+ * says where to look for it and which shapes of break are relevant. One
+ * sentence, two hundred screens.
+ *
+ * The idea is Meta's. ACH has an engineer describe an area of concern in plain
+ * text, generates faults specific to it, and gates every step by execution
+ * ("Mutation-Guided LLM-based Test Generation at Meta", Foster et al., FSE
+ * 2025). What is taken here is the UNIT — the concern as the thing a human
+ * writes — not their generator.
+ *
+ * NO MODEL IS REQUIRED, and that is deliberate. A concern's useful core is a
+ * named scope plus a producer selection, both of which the mechanical
+ * producers already satisfy. An LLM can later propose faults a line-oriented
+ * producer cannot see, as an ADDITIONAL source for a concern that already
+ * works — rather than as the thing the rung depends on. That keeps every
+ * verifying command offline, which is the property this tool is least willing
+ * to trade.
+ *
+ * A concern is NOT a claim and never becomes one by itself. It says where to
+ * look; the probe says what it found; a human states the sentence worth
+ * defending. Nothing here is written to `testguard.claims.json`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { saveSurface } from './savepath.mjs';
+import { globToRegExp, walk } from '../util/glob.mjs';
+
+export const defaultConcernsPath = (projectDir) => join(projectDir, 'testguard.concerns.json');
+
+/**
+ * The concerns every project gets without writing anything.
+ *
+ * Two, because two are the ones whose targets can be enumerated honestly. An
+ * authorization concern would need a heuristic for "which files check
+ * permissions", and a guess there produces exactly the non-actionable noise
+ * that gets a check switched off. A project that knows its own auth layer can
+ * say so with a `glob` target in three lines; this file will not guess for it.
+ */
+export const BUILTIN_CONCERNS = Object.freeze([
+  Object.freeze({
+    id: 'SAVE-PERSISTS',
+    statement: 'Every write to storage persists the data it was given.',
+    severity: 'high',
+    targets: { kind: 'write-sites' },
+    // The shapes that break a persisted payload. Measured on a real
+    // application: 12 of 12 surviving faults on the persistence path were a
+    // field dropped from the payload, so the list leads with that.
+    faultClasses: ['field-dropped', 'call-removed', 'statement-deleted', 'literal-changed'],
+    builtin: true,
+  }),
+  Object.freeze({
+    id: 'CHANGED-CODE',
+    statement: 'Code changed in this branch is defended by something.',
+    severity: 'medium',
+    targets: { kind: 'changed' },
+    // Everything: a diff has no shape to narrow by.
+    faultClasses: null,
+    builtin: true,
+  }),
+]);
+
+/**
+ * Load the project's concerns, with the built-ins behind them.
+ *
+ * A project concern with the same id as a built-in REPLACES it, so a team can
+ * retune `SAVE-PERSISTS` for an ORM this tool does not recognise without
+ * forking anything. Shadowing is recorded rather than silent: a concern that
+ * quietly replaced a default would be the kind of surprise that costs an
+ * afternoon.
+ */
+export function loadConcerns(projectDir, { path } = {}) {
+  const p = path ?? defaultConcernsPath(projectDir);
+  let project = [];
+  let source = null;
+  if (existsSync(p)) {
+    const doc = JSON.parse(readFileSync(p, 'utf8'));
+    project = doc.concerns ?? [];
+    source = p;
+  }
+  const overridden = new Set(project.map((c) => c.id));
+  const concerns = [
+    ...project.map((c) => ({ ...c, builtin: false })),
+    ...BUILTIN_CONCERNS.filter((c) => !overridden.has(c.id)),
+  ];
+  return {
+    concerns,
+    // The project's own entries, exactly as written. Validation runs against
+    // these: the enriched objects above carry a `builtin` marker this tool
+    // added, and a schema that refuses unknown properties is right to reject
+    // them. Validating what we constructed instead of what the user wrote
+    // would report OUR bug as THEIR malformed file.
+    raw: project.map(({ builtin, ...c }) => c),
+    source,
+    shadowed: BUILTIN_CONCERNS.filter((c) => overridden.has(c.id)).map((c) => c.id),
+  };
+}
+
+/** One concern by id, or null. Ids are matched exactly: a near-miss is a typo, not an intention. */
+export const concernById = (concerns, id) => concerns.find((c) => c.id === id) ?? null;
+
+/**
+ * The files a concern applies to.
+ *
+ * `write-sites` asks the enumerator; `glob` matches the project's own paths;
+ * `changed` returns null, meaning "the caller's diff decides" — a concern does
+ * not get to re-derive what the gate already computed.
+ */
+export function targetsFor(projectDir, concern, { changedFiles } = {}) {
+  const t = concern.targets ?? { kind: 'changed' };
+  if (t.kind === 'write-sites') return saveSurface(projectDir).files.map((f) => f.file);
+  if (t.kind === 'glob') {
+    // Against the whole project, never the diff. A concern like "every admin
+    // route refuses an unauthorised caller" is about the admin routes, not
+    // about the ones that happened to change today — and pooling from the diff
+    // made such a concern report clean on a clean branch, which is the exact
+    // false reassurance a concern exists to prevent.
+    const res = (t.globs ?? []).map(globToRegExp);
+    return walk(projectDir).filter((f) => res.some((re) => re.test(f)));
+  }
+  return changedFiles ?? null;
+}
+
+/**
+ * Keep only the faults whose class this concern cares about.
+ *
+ * `faultClasses: null` means every class — the honest default for a concern
+ * with no shape to narrow by. Narrowing is what makes one sentence useful
+ * across two hundred files: a persistence concern that also reported every
+ * altered return value would bury the payload findings it exists to surface.
+ */
+export function filterByConcern(candidates, concern) {
+  if (!concern?.faultClasses) return candidates;
+  const keep = new Set(concern.faultClasses);
+  return candidates.filter((c) => keep.has(c.fault.faultClass));
+}
+
+/** The concerns as text, for someone deciding which to sweep. */
+export function renderConcerns({ concerns, source, shadowed }) {
+  const out = [];
+  out.push(source ? `${concerns.length} concern${concerns.length === 1 ? '' : 's'} (${source}, plus the built-ins)` : `${concerns.length} built-in concern${concerns.length === 1 ? '' : 's'} — none declared in this project.`);
+  out.push('');
+  for (const c of concerns) {
+    const shape = c.targets?.kind === 'glob' ? `glob ${(c.targets.globs ?? []).join(', ')}` : c.targets?.kind ?? 'changed';
+    out.push(`  ${c.id}${c.builtin ? '  (built-in)' : ''}`);
+    out.push(`    ${c.statement}`);
+    out.push(`    targets: ${shape} · faults: ${c.faultClasses ? c.faultClasses.join(', ') : 'every class'}`);
+    out.push('');
+  }
+  if (shadowed.length) out.push(`This project replaces the built-in ${shadowed.join(', ')}.`);
+  if (!source) {
+    out.push('Declare your own in testguard.concerns.json. A concern is one sentence and a');
+    out.push('scope: it says where to look, never what is true. Only a claim does that.');
+  }
+  return out.join('\n');
+}

package/src/supply/feedback.mjs

@@ -0,0 +1,146 @@
+/**
+ * What this project's own runs say about which faults are worth proposing.
+ *
+ * `select.mjs` ships a productivity prior measured on one real application.
+ * That is a reasonable starting point and a poor stopping point: the classes
+ * that survive a Next.js suite are not the classes that survive a Python one,
+ * and Google's mutation service got from a 15% productive rate to 89% on
+ * exactly this — feedback, accumulated over years, refining which candidates
+ * are worth a developer's attention ("Practical Mutation Testing at Scale",
+ * Petrović et al., 2021). The static table is the part of that idea this tool
+ * had not yet taken.
+ *
+ * THE FEEDBACK IS ALREADY ON DISK. Every evidence record carries a
+ * `faultClass` and a `verdict`, so "how often does a fault of this class
+ * survive here" is a tally, not a new thing to capture. There is no click to
+ * collect and no state to maintain: a project that has probed anything has
+ * already said what its own productive classes are.
+ *
+ * WHY THIS ESTIMATOR AND NOT A BETTER-SOUNDING ONE. The combination below is a
+ * Beta-Binomial posterior mean, and a posterior mean is what minimises Brier
+ * and log score in expectation — it is a STRICTLY PROPER estimate, which is
+ * the only kind that cannot be improved by reporting something other than an
+ * honest probability. Optimising the ordering for accuracy or F1 instead would
+ * maximise the number of survivors found while destroying the calibration of
+ * the number attached to each, which is the documented failure mode of naive
+ * optimisation and the reason Laya trains against proper scoring rules. If
+ * this file is ever changed to rank by anything but an honest probability,
+ * that is the invariant being broken.
+ *
+ * Pure apart from reading the documents it is given.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { MEASURED_PRODUCTIVITY } from './select.mjs';
+
+/** The evidence a project may have produced, in the order they are most relevant. */
+export const EVIDENCE_PATHS = Object.freeze([
+  // A sweep probes MACHINE-proposed faults, the same distribution the ranker
+  // orders, so it is the closest observation available.
+  '.testguard/sweep-evidence.json',
+  // The canonical probe is human-authored faults: a real observation of the
+  // same classes, drawn slightly differently, and still worth counting.
+  '.testguard/evidence.json',
+]);
+
+/**
+ * Survival counts per fault class from one evidence document.
+ *
+ * Only `killed` and `survived` are counted. `nocover`, `unverifiable`,
+ * `fault-invalid`, `timeout` and `flaky-defender` say nothing about whether a
+ * fault of that class would be NOTICED — they say the question could not be
+ * asked — and folding them in either direction would be inventing data.
+ */
+export function tallyEvidence(doc) {
+  const by = {};
+  for (const r of doc?.records ?? []) {
+    const cls = r.subject?.faultClass;
+    if (!cls) continue;
+    if (r.verdict !== 'killed' && r.verdict !== 'survived') continue;
+    const e = (by[cls] ??= { survived: 0, n: 0 });
+    e.n += 1;
+    if (r.verdict === 'survived') e.survived += 1;
+  }
+  return by;
+}
+
+/** Merge tallies from several documents. Counts add; nothing is averaged twice. */
+export function mergeTallies(tallies) {
+  const by = {};
+  for (const t of tallies) {
+    for (const [cls, e] of Object.entries(t)) {
+      const m = (by[cls] ??= { survived: 0, n: 0 });
+      m.survived += e.survived;
+      m.n += e.n;
+    }
+  }
+  return by;
+}
+
+/**
+ * The productivity table to rank with: this project's own observations, with
+ * the shipped measurement as the prior they are shrunk toward.
+ *
+ * The shipped numbers become pseudo-counts rather than a competing estimate —
+ * `n` of them, so a class measured on twelve faults elsewhere carries the
+ * weight of twelve observations here and no more. A project with its own
+ * hundred records therefore overrides the shipping default; a project with
+ * three nudges it.
+ *
+ * `shipped` is injectable so the combination can be tested without depending
+ * on whatever the current measurement happens to be.
+ */
+export function combinedProductivity(local, shipped = MEASURED_PRODUCTIVITY) {
+  const out = {};
+  for (const cls of new Set([...Object.keys(shipped), ...Object.keys(local)])) {
+    const s = shipped[cls];
+    const l = local[cls];
+    const priorSurvived = s ? s.p * s.n : 0;
+    const priorN = s ? s.n : 0;
+    const n = priorN + (l?.n ?? 0);
+    if (n === 0) continue;
+    const survived = priorSurvived + (l?.survived ?? 0);
+    out[cls] = { p: survived / n, n, observed: l?.n ?? 0 };
+  }
+  return out;
+}
+
+/** Read whichever evidence documents this project has. Missing or malformed ones are skipped, never guessed at. */
+export function readEvidence(projectDir, paths = EVIDENCE_PATHS) {
+  const docs = [];
+  for (const rel of paths) {
+    const p = join(projectDir, rel);
+    if (!existsSync(p)) continue;
+    try {
+      docs.push({ path: rel, doc: JSON.parse(readFileSync(p, 'utf8')) });
+    } catch {
+      // A document this tool cannot parse is not evidence of anything. It is
+      // skipped rather than defaulted, because a ranking built on a guess
+      // about a corrupt file is worse than one built on the shipped prior.
+    }
+  }
+  return docs;
+}
+
+/**
+ * The learned table plus what it was learned from, so a report can say whether
+ * an ordering came from this project or from the shipping default. An ordering
+ * nobody can trace is a number nobody should trust.
+ */
+export function learnedProductivity(projectDir, { paths, shipped } = {}) {
+  const docs = readEvidence(projectDir, paths);
+  const local = mergeTallies(docs.map((d) => tallyEvidence(d.doc)));
+  const observed = Object.values(local).reduce((a, e) => a + e.n, 0);
+  return {
+    table: combinedProductivity(local, shipped),
+    sources: docs.map((d) => d.path),
+    observed,
+    classes: Object.keys(local).sort(),
+  };
+}
+
+/** One line for a report: where the ordering came from. */
+export function renderLearned(learned) {
+  if (learned.observed === 0) return 'ordering: the shipped productivity prior — this project has no probed evidence yet.';
+  return `ordering: ${learned.observed} probed fault${learned.observed === 1 ? '' : 's'} of this project's own, across ${learned.classes.length} class${learned.classes.length === 1 ? '' : 'es'} (${learned.sources.join(', ')}), shrunk toward the shipped prior.`;
+}

package/src/supply/persistence.mjs

@@ -171,3 +171,56 @@ export function persistenceHint(signal, faultLine) {
   const field = /^\s*([A-Za-z_$][\w$]*)\s*(?::|,\s*$)/.exec(faultLine ?? '')?.[1];
   return `${signal.file} ${signal.reason} Assert the whole object written by the call this fault changes${field ? `, including \`${field}\`` : ''} — or read the record back and assert on what was stored.`;
 }
+
+/**
+ * What this claim's defenders are CAPABLE of proving about a write.
+ *
+ * The read-back question — "did the row actually land?" — cannot be answered by
+ * a test that replaced the database with a mock. Such a test can prove the call
+ * shape and nothing beyond it: the `where` may match no rows, the transaction
+ * may roll back, a constraint may reject the write, and every one of those
+ * passes against a mock that recorded the arguments and returned a plausible
+ * object.
+ *
+ * So rather than pretend to measure persistence, this states the LIMIT. It is
+ * the same discipline as `nocover` — which says "no test imports this" instead
+ * of guessing — one level finer: these tests exist, they run, and there is a
+ * class of failure they structurally cannot see.
+ *
+ *   `mocked`   every defender replaces the persistence layer. Call shape only.
+ *   `unmocked` at least one does not, so a real write is at least possible.
+ *              NOT a promise that one happens: a test may simply never reach
+ *              the database. Possible is the honest word.
+ *   `none`     no defender at all; `nocover` already covers this.
+ *
+ * Measured on a real AI-authored application: of 37 files that write to
+ * storage, 32 were defended only by mocking tests, 4 had no defender, and 1
+ * had an unmocked defender — a mailer, not a database write. Nothing in that
+ * suite could prove any save persisted.
+ */
+export function persistenceProvability(projectDir, defenders) {
+  if (!defenders || defenders.length === 0) return { class: 'none', mocking: [], unmocked: [] };
+  const mocking = [];
+  const unmocked = [];
+  for (const d of defenders) (analyzePersistence(projectDir, d) ? mocking : unmocked).push(d);
+  return { class: unmocked.length ? 'unmocked' : 'mocked', mocking, unmocked };
+}
+
+/**
+ * The provability of a whole surface, as counts. The headline a save-path
+ * report opens with, because "how many of these could be proven at all" is a
+ * different question from "how many were probed" and a far more alarming one.
+ */
+export function provabilitySummary(projectDir, targets, defendersOf) {
+  const counts = { mocked: 0, unmocked: 0, none: 0 };
+  for (const file of targets) {
+    let defenders = [];
+    try {
+      defenders = defendersOf(file);
+    } catch {
+      defenders = [];
+    }
+    counts[persistenceProvability(projectDir, defenders).class] += 1;
+  }
+  return counts;
+}

package/src/sweep/sweep.mjs

@@ -35,9 +35,12 @@ 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 { learnedProductivity } from '../supply/feedback.mjs';
+import { loadConcerns, concernById, targetsFor, filterByConcern } from '../supply/concerns.mjs';
 import { saveSurface } from '../supply/savepath.mjs';
-import { persistenceSignals, persistenceHint } from '../supply/persistence.mjs';
+import { persistenceSignals, persistenceHint, provabilitySummary } from '../supply/persistence.mjs';
 import { probe } from '../probe/probe.mjs';
+import { discoverDefenders } from '../probe/discover.mjs';
 import { hintFor } from '../brief/brief.mjs';
 
 /**
@@ -106,6 +109,9 @@ export function sortFindings(findings) {
 /** How many findings a sweep is willing to fail on. */
 export const gatingCount = (findings) => findings.filter((f) => GATING.has(f.verdict)).length;
 
+/** A concern named on the command line that this project does not declare. */
+export class ConcernError extends Error {}
+
 /** Rebuild claim documents from a flat selection, keeping each claim's own faults together. */
 function claimsFromSelection(selected) {
   const byClaim = new Map();
@@ -128,6 +134,8 @@ export async function sweep({
   projectDir,
   ref,
   mode = 'changed',
+  concern: concernId,
+  concernsPath,
   includeDirty = false,
   exclude = [],
   cap,
@@ -154,10 +162,23 @@ export async function sweep({
   //
   // 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 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);
+  // `--save-paths` is sugar for the built-in SAVE-PERSISTS concern: the same
+  // targets and the same producer selection, named so a project can retune it
+  // for an ORM this tool does not recognise without forking anything.
+  const loaded = loadConcerns(projectDir, { path: concernsPath });
+  const concern = concernId
+    ? concernById(loaded.concerns, concernId)
+    : mode === 'save-paths' ? concernById(loaded.concerns, 'SAVE-PERSISTS') : null;
+  if (concernId && !concern) {
+    throw new ConcernError(`unknown concern ${concernId}. Declared: ${loaded.concerns.map((c) => c.id).join(', ')}`);
+  }
+  const changedTargets = gate.uncovered.filter((u) => u.kind === 'source').map((u) => u.file);
+  // A concern whose targets are the diff defers to the gate rather than
+  // re-deriving what it already computed.
+  const concernTargets = concern ? targetsFor(projectDir, concern, { changedFiles: changedTargets }) : null;
+  const usesSurface = concern?.targets?.kind === 'write-sites' || mode === 'save-paths';
+  const surface = usesSurface ? saveSurface(projectDir) : null;
+  const targets = concernTargets ?? changedTargets;
 
   const cPath = claimsPath ?? defaultClaimsPath(projectDir);
   const existingClaims = existsSync(cPath) ? loadClaims(cPath) : { claims: [] };
@@ -184,8 +205,27 @@ export async function sweep({
     for (const claim of result.doc.claims) for (const fault of claim.faults) candidates.push({ claim, fault });
   }
 
+  // What the defenders of this surface are CAPABLE of proving, before anything
+  // is probed. A test that replaced the database can prove the call shape and
+  // never that the row landed, and that limit is a property of the suite rather
+  // than of any verdict — so it is measured once, over the whole surface, and
+  // reported whether or not a single fault survives.
+  const provability = surface
+    ? provabilitySummary(projectDir, targets, (f) => discoverDefenders(projectDir, f))
+    : null;
+
+  // Order by what THIS project's own runs have shown, not only by what was
+  // measured elsewhere. A project that has probed nothing falls back to the
+  // shipped prior; one with its own records overrides it in proportion to how
+  // many it has. This is the feedback half of Google's 15%-to-89%, using data
+  // the project already produced rather than a new thing to collect.
+  const learned = learnedProductivity(projectDir);
+  // Narrowing is what makes one sentence useful across two hundred files: a
+  // persistence concern that also reported every altered return value would
+  // bury the payload findings it exists to surface.
+  const relevant = filterByConcern(candidates, concern);
   const limit = cap ?? capFor(targets.length);
-  const selection = selectFaults(candidates, { cap: limit });
+  const selection = selectFaults(relevant, { cap: limit, table: learned.table });
   const claims = claimsFromSelection(selection.selected);
 
   let evidence = { records: [] };
@@ -234,20 +274,28 @@ export async function sweep({
     includeDirty,
     scope: {
       mode,
+      ...(concern ? { concern: concern.id } : {}),
       changed: gate.changed,
-      ...(surface ? { writeSites: surface.siteCount, payloadFields: surface.keyCount } : {}),
+      ...(surface ? { writeSites: surface.siteCount, payloadFields: surface.keyCount, provability } : {}),
       targets: targets.length,
       swept: drafts.length,
       ...(skipped.length ? { skipped } : {}),
     },
     selection: {
-      proposed: candidates.length,
+      proposed: relevant.length,
+      ...(candidates.length !== relevant.length ? { outOfScope: candidates.length - relevant.length } : {}),
       selected: selection.selected.length,
       deferred: selection.deferred.length,
       cap: selection.cap,
       byClass: selection.byClass,
     },
     counts,
+    ordering: { observed: learned.observed, sources: learned.sources },
+    // Carried, not written here: the caller owns I/O. Persisting it is what
+    // closes the feedback loop — the next sweep learns from these verdicts,
+    // which are MACHINE-proposed faults and so the closest observation of the
+    // distribution the ranker orders.
+    evidence,
     findings: ordered,
     exitCode: gating > 0 ? 1 : 0,
     drafts,
@@ -262,16 +310,44 @@ export function renderSweep(doc, { limit = 20 } = {}) {
   if (scope.targets === 0) {
     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.`);
+      : scope.concern
+        ? `sweep: concern ${scope.concern} matches no file 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');
   }
   // The denominator first. A report that lists findings without saying how much
   // was looked at invites the reader to assume the rest is fine.
+  // Say how the sweep was aimed. A glob concern that reports "unclaimed changed
+  // files" is describing a diff it never looked at.
   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}.`);
+    : scope.concern
+      ? `concern ${scope.concern} matches ${scope.targets} file${scope.targets === 1 ? '' : 's'}. Swept ${scope.swept}.`
+      : `swept ${scope.swept} of ${scope.targets} unclaimed changed file${scope.targets === 1 ? '' : 's'} against ${doc.ref}.`);
+  if (saves && scope.provability) {
+    // The limit, before any verdict. A test that replaced the database can
+    // prove the call shape and never that the row landed, so on a surface
+    // defended entirely by such tests a clean probe is not evidence of
+    // persistence — it is evidence that nothing could have measured it.
+    const { mocked, unmocked, none } = scope.provability;
+    out.push(`  of those ${scope.targets} file${scope.targets === 1 ? '' : 's'}: ${mocked} defended only by tests that mock the persistence layer, ${unmocked} with an unmocked defender, ${none} with no defender at all.`);
+    if (unmocked === 0 && mocked > 0) {
+      out.push('  Nothing in this suite can prove a write reached storage. A mocked test proves the');
+      out.push('  call shape; a where-clause that matches nothing, a rolled-back transaction and a');
+      out.push('  rejected constraint all pass against it.');
+    }
+  }
   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${saves ? '.' : ', or sweep a smaller change.'}`);
+  if (selection.deferred) out.push(`  The ${selection.deferred} deferred are not a verdict: raise --cap${saves || scope.concern ? '.' : ', or sweep a smaller change.'}`);
+  // A narrow concern must not look like a quiet one: the producers found these,
+  // and this concern is not about them.
+  if (selection.outOfScope) out.push(`  ${selection.outOfScope} further proposal${selection.outOfScope === 1 ? ' was' : 's were'} outside this concern's fault classes.`);
+  // An ordering nobody can trace is a number nobody should trust.
+  if (doc.ordering) {
+    out.push(doc.ordering.observed === 0
+      ? '  ordering: the shipped productivity prior — this project has no probed evidence yet.'
+      : `  ordering: ${doc.ordering.observed} probed fault${doc.ordering.observed === 1 ? '' : 's'} of this project's own (${doc.ordering.sources.join(', ')}), shrunk toward the shipped prior.`);
+  }
   for (const s of scope.skipped ?? []) out.push(`  skipped ${s.file}: ${s.reason}`);
   out.push('');