testguard-cli 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,103 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-09-22
+
+Automated weekly release — everything merged since `v0.13.0`.
+
+### Changed
+
+- fix: three defects the arid measurement found, presentational JSX set aside, and the claimspec signal bump (#164)
+- docs: carry the 0.12 and 0.13 results into the brief and the prior-art record (#162)
+- chore(homebrew): sha256 for v0.13.0 (#161)
+
+
+### Added
+
+- **claimspec v1 evidence admits `persistence-payload-unasserted`** to
+  `defenders.signals`, the enum shared with every claimspec consumer. The
+  signal had lived only in the sweep document, so `probe` could not surface
+  why a save-path survivor was missed. Now a `survived` record whose fault
+  sits on the write path carries it for each resolved defender that mocks the
+  persistence layer, with the mocked `specifiers` and the file's assertion
+  `counts` (exact, partial, argument-free). The validator refuses it on any
+  other verdict, on a file that is not a resolved defender, or without its
+  reason — the same rule the sweep document already enforced on its
+  findings, and the sweep now repeats what the record says rather than
+  re-deriving it. Conformance carries a valid example and three invalid
+  cases. No consumer outside this repository validates claimspec evidence
+  today; DocGuard's adoption (docguard#420) is notified rather than broken.
+- `sweep` sets aside a purely presentational JSX element — an icon, or a
+  static wrapper with no expression and no handler — instead of spending a
+  probe run on it, and says so: `selection.presentational` in the document, a
+  line in the report, and the remainder arithmetic now proves
+  proposed = probed + deferred + set aside. Measured on a 14-file UI diff:
+  150 of 510 proposals, 29 of 30 probe slots and 7 of 10 survivors were of
+  this shape — Google's definition of an arid node, in a syntax Google never
+  mutated. Because the ordering learns from survival, those survivors were
+  also teaching it to rank the class higher; set-aside proposals never enter
+  the evidence, so they no longer can. Google's own five arid categories were
+  measured at under 1% of proposals and are not suppressed.
+
+### Fixed
+
+- Python defender discovery lost the last name on an import line that ends in
+  a comment: `from pkg import cli, demo  # noqa: E402` found only `cli`, and
+  `import pkg.demo  # noqa` found nothing. On a real suite where `# noqa` is
+  the idiom of every src-layout test, 12 of 30 probed faults were reported
+  NOCOVER for modules whose tests import them — a gating verdict in the
+  forbidden direction. Comments are now stripped before names are read.
+- File walking descended into `.claude/`, so a nested agent worktree under
+  `.claude/worktrees/` contributed another branch's tests as defenders of this
+  tree — files the scratch worktree cannot even contain, because the directory
+  is gitignored. `.claude` joins the tool-directory skip list, and the claim
+  that promised this now names it.
+- The Python `statement-deleted` producer proposed on lines inside a bracket
+  opened earlier — `help="…")` inside an `add_argument(` — and none of those
+  faults compiled: 81 of 600 proposals on a real CLI (13.5%). The producer now
+  tracks bracket depth across lines (triple-quoted strings included, so a
+  docstring's parentheses cannot leave the rest of the file "inside") and
+  refuses the `pass` shapes there; dict entries and call arguments keep their
+  own producers. Re-measured: 7 of 526 (1.3%).
+
+### Changed
+
+- The self-probe cost budget is 1650 s, from 1440. Six new claims (85 s on
+  the Node 22 PR leg, worst 22 s, all under the 100 s per-claim ceiling) took
+  that leg from 1367 s to 1457 s, over by 17 s. The v0.13.0 release job
+  measured 1113 s from scratch, but the PR leg runs the same claims 25-30%
+  slower and is where the ceiling is checked, so 1650 restores ~13% headroom
+  over the leg that binds. The per-claim ceiling is unchanged.
+- The technical brief carries the 0.12 and 0.13 results it was missing: the
+  whole-surface provability measurement (32 of 37 files that write are defended
+  only by tests that mock the database) replaces the sample-level number in
+  Fig. 7; the ladder's second rung is now a shipped verb with a real finding
+  (a five-line concern found an admin route whose owner/manager check can be
+  forced to `false` with no test failing) rather than a description of intent;
+  and the first rung says its ordering learns from the project's own runs.
+  Re-rendered; still eight sheets from eight pages.
+- `docs-canonical/PRIOR-ART.md` records the arid-node measurement instead of
+  a promise: every proposal from four sweeps over two of the maintainer's
+  repositories was classified by hand against Google's five arid categories,
+  and they account for under 1% of what the producers propose. No suppressor
+  is built for them. The same pass found what IS material — presentational
+  JSX taking 29 of 30 probe slots on a UI diff, and 13.5% of Python proposals
+  that cannot compile — and lists both as open, with numbers.
+- `docs-canonical/PRIOR-ART.md` no longer lists the feedback loop and concerns
+  as unbuilt. The two gaps that remain are restated precisely: the loop learns
+  from verdicts rather than explicit developer clicks, and concerns have no
+  model-backed producer.
+
+## [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 +115,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.14.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.14.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
@@ -234,6 +234,10 @@ npx testguard-cli admit test/x.test.ts --claim X   # is this test green on HEAD
    static signal `mocked-never-asserted` — the cheapest blind-spot signal
    there is, and the exact signature of one escaped bug in the field
    reports. Silence it, visibly, with `// unasserted: <why>` above the mock.
+   Its sibling `persistence-payload-unasserted` is attached to a **survivor
+   on a write path** whose defender mocks the database: the test can prove
+   the call shape and never that the row landed, and the signal names the
+   mocked layer and the file's assertion mix (exact, partial, argument-free).
 
    Runners: **vitest**, **jest**, **Playwright** and **Python** (`--runner
    auto` picks the first of vitest, jest, python that resolves). A JavaScript
@@ -423,8 +427,9 @@ 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.
+proposed 510 faults, probed 10 (cap 10), deferred 350.
+  The 350 deferred are not a verdict: raise --cap, or sweep a smaller change.
+  150 presentational elements (icons, static wrappers) set aside: nobody writes a test for those, and a survivor there would teach the ordering the wrong lesson.
 
 9 findings — a deliberate break that no test noticed:
 
@@ -451,6 +456,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 +479,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 +561,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 +663,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.14.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.14.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
 ```
 
@@ -903,7 +986,8 @@ parameter-derived argument swapped for `None`, a key dropped from a payload
 `dict` or an allow-list. Two differences are deliberate. A statement is
 removed by replacing it with `pass`, never by deleting the line, because a
 block whose only statement is gone is an `IndentationError`; and a line that
-leaves a bracket open (`COLOURS = {`) is never removed at all. Both exist
+leaves a bracket open (`COLOURS = {`), or sits inside one opened on an earlier
+line (`help="…"` in an `add_argument(`), is never removed at all. Both exist
 because a fault that cannot compile is a `fault-invalid` verdict — a probe run
 spent saying nothing about the tests. The two JSX shapes (`element-removed`,
 `handler-dropped`) have no Python meaning and are absent rather than faked.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.12.0",
+  "version": "0.14.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/GATE-SEMANTICS.md

@@ -343,6 +343,14 @@ the suppress-up-to-count semantics are identical.
   tool then records `unasserted-annotated` with the reason — silenced, never
   hidden. A file that mocks the subject is never a discovered defender: a
   mock cannot detect a fault in what it replaced.
+  `persistence-payload-unasserted`: a resolved defender mocks the persistence
+  layer, so it can prove the call shape and never that a row landed; the
+  reason names the layer and the file's assertion mix. It is attached only to
+  a **survived** record whose fault sits on the write path — a field of a
+  persisted payload or the write call itself — because there it says why the
+  survivor was missed, and anywhere else it says nothing. A conforming
+  document never carries it on another verdict, on a file that is not a
+  resolved defender, or without its reason.
 
 ## Claimed source surface
 

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
@@ -144,6 +144,16 @@ const semantic = {
         if (s.signal === 'target-attribute-patched') {
           if (!s.reason) errors.push({ path: `${p}/defenders/signals`, message: `target-attribute-patched on ${s.file} requires the patched attributes as its reason` });
           if (!r.defenders.resolved.includes(s.file)) errors.push({ path: `${p}/defenders/signals`, message: `${s.file} patches attributes of the subject but is not a resolved defender` });
+        } else if (s.signal === 'persistence-payload-unasserted') {
+          // The same rule the sweep document enforces on its findings: the
+          // signal explains a SURVIVOR on the write path. A record does not
+          // carry the fault's line, so the write-path half is the producer's
+          // to keep (`persistenceSignalsFor`); the verdict half is checked here.
+          // The file mocks the persistence layer, not the subject, so it is a
+          // resolved defender and never a mocking one.
+          if (!s.reason) errors.push({ path: `${p}/defenders/signals`, message: `persistence-payload-unasserted on ${s.file} requires the mocked layer and assertion mix as its reason` });
+          if (r.verdict !== 'survived') errors.push({ path: `${p}/defenders/signals`, message: `persistence-payload-unasserted explains a survivor; on a ${r.verdict} record it explains nothing` });
+          if (!r.defenders.resolved.includes(s.file)) errors.push({ path: `${p}/defenders/signals`, message: `${s.file} mocks the persistence layer but is not a resolved defender` });
         } else if (!(r.defenders.mocking ?? []).includes(s.file)) {
           errors.push({ path: `${p}/defenders/signals`, message: `${s.file} carries a mock signal but is not listed in defenders.mocking` });
         }
@@ -305,12 +315,36 @@ 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;
     // 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})` });
+    const setAside = s.presentational ?? 0;
+    if (s.proposed !== s.selected + s.deferred + setAside) errors.push({ path: '/selection/proposed', message: `proposed (${s.proposed}) must equal selected (${s.selected}) + deferred (${s.deferred})${setAside ? ` + presentational (${setAside})` : ''}` });
     if (s.selected > s.cap) errors.push({ path: '/selection/selected', message: `selected (${s.selected}) exceeds the cap (${s.cap})` });
     if (doc.scope.swept > doc.scope.targets) errors.push({ path: '/scope/swept', message: `swept (${doc.scope.swept}) cannot exceed targets (${doc.scope.targets})` });
     // The counters that only mean something in one mode must not appear in the
@@ -318,10 +352,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 +384,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/evidence.schema.json

@@ -547,7 +547,7 @@
               }
             },
             "signals": {
-              "description": "Static, annotation-grade signals about the defenders. They never change a verdict. `mocked-never-asserted`: the file mocks the subject and never asserts on anything imported from it. `unasserted-annotated`: the same, but the author annotated the mock with a reason (`// unasserted: <why>`), recorded here \u2014 silenced, never hidden. `target-attribute-patched`: a Python defender that patches individual attributes of the subject (`patch(\"pkg.mod.fn\")`) rather than the module. Unlike a JavaScript module mock it does NOT disqualify the file \u2014 a fault anywhere else in the module is still detectable \u2014 so the file stays in `resolved`; `reason` names the patched attributes, which are where that test is least likely to notice anything.",
+              "description": "Static, annotation-grade signals about the defenders. They never change a verdict. `mocked-never-asserted`: the file mocks the subject and never asserts on anything imported from it. `unasserted-annotated`: the same, but the author annotated the mock with a reason (`// unasserted: <why>`), recorded here \u2014 silenced, never hidden. `target-attribute-patched`: a Python defender that patches individual attributes of the subject (`patch(\"pkg.mod.fn\")`) rather than the module. Unlike a JavaScript module mock it does NOT disqualify the file \u2014 a fault anywhere else in the module is still detectable \u2014 so the file stays in `resolved`; `reason` names the patched attributes, which are where that test is least likely to notice anything. `persistence-payload-unasserted`: a resolved defender that mocks the persistence layer (`vi.mock('@/lib/prisma')`) and so can prove the call shape but never that a row landed; `reason` names the mocked layer and the file's assertion mix (exact, partial, argument-free), `counts` carries the mix as numbers and `specifiers` the mocked module paths. It belongs only to a `survived` record whose fault sits on the write path \u2014 a field of a persisted payload, or the write call itself \u2014 because there it explains why the survivor was missed and anywhere else it explains nothing. Measured on a real application: 12 of 12 survivors on the save path were a dropped payload field, and every one of their defenders asserted with a partial matcher.",
               "type": "array",
               "items": {
                 "type": "object",
@@ -563,13 +563,46 @@
                     "enum": [
                       "mocked-never-asserted",
                       "unasserted-annotated",
-                      "target-attribute-patched"
+                      "target-attribute-patched",
+                      "persistence-payload-unasserted"
                     ]
                   },
                   "reason": {
                     "type": "string",
                     "minLength": 1,
                     "maxLength": 512
+                  },
+                  "specifiers": {
+                    "description": "persistence-payload-unasserted only: the persistence-layer module specifiers the file mocks.",
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "counts": {
+                    "description": "persistence-payload-unasserted only: the file's call-shape assertions by kind. `exact` is the only kind a dropped field can fail.",
+                    "type": "object",
+                    "required": [
+                      "exact",
+                      "partial",
+                      "argless"
+                    ],
+                    "additionalProperties": false,
+                    "properties": {
+                      "exact": {
+                        "type": "integer",
+                        "minimum": 0
+                      },
+                      "partial": {
+                        "type": "integer",
+                        "minimum": 0
+                      },
+                      "argless": {
+                        "type": "integer",
+                        "minimum": 0
+                      }
+                    }
                   }
                 },
                 "additionalProperties": false

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,16 @@
               }
             }
           }
+        },
+        "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."
+        },
+        "presentational": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Proposals set aside because they remove a purely presentational JSX element — an icon, or a static wrapper with no expression and no handler. Nobody writes a test for those, and a survivor on one would teach the survival-learned ordering to prefer the class. Counted in `proposed` and in `byClass`; never probed, never a finding. Absent when zero."
         }
       }
     },
@@ -305,6 +343,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."
+        }
+      }
     }
   }
 }