testguard-cli 0.12.0__tar.gz → 0.13.0__tar.gz

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/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

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.12.0
+Version: 0.13.0
 Summary: Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest. Ships the Node.js CLI (requires Node.js 20+).
 Project-URL: Homepage, https://github.com/raccioly/testguard
 Project-URL: Documentation, https://github.com/raccioly/testguard#readme
@@ -151,9 +151,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.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
@@ -475,6 +475,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
@@ -490,6 +498,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
@@ -518,10 +580,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
 
@@ -604,12 +682,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
 ```
 

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/README.md

@@ -127,9 +127,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.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
 ```
 

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/action.yml

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

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/docs/testguard-explained.html

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

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/docs-canonical/ARCHITECTURE.md

@@ -50,7 +50,7 @@ code were wrong, would anything fail?*
 | Progress | How a running probe reports itself, per reader: tty, plain, ndjson | `src/probe/progress.mjs` |
 | Change gate | Claim coverage of a diff | `src/gate/changed.mjs` |
 | Sweep | The cold start: propose faults for changed files that carry no claim, probe a bounded selection, report what nothing noticed | `src/sweep/sweep.mjs` |
-| Claim supply | Which proposals are worth probing, where this project writes to storage, and why a survivor on a write path was missed | `src/supply/select.mjs`, `src/supply/savepath.mjs`, `src/supply/persistence.mjs` |
+| Claim supply | The concerns a sweep can be aimed by, which proposals are worth probing, what this project's own runs say about that, where it writes to storage, and why a survivor on a write path was missed | `src/supply/concerns.mjs`, `src/supply/select.mjs`, `src/supply/feedback.mjs`, `src/supply/savepath.mjs`, `src/supply/persistence.mjs` |
 | Baseline | Freeze debt; gate the delta; re-stamp | `src/baseline/baseline.mjs` |
 | Status | The single state machine every rendering derives from | `src/status/status.mjs` |
 | Brief | The agent's session-start blind-spot block | `src/brief/brief.mjs` |
@@ -105,6 +105,7 @@ appears here but not on disk, or on disk but not here, is drift.
 | `action.yml` | The GitHub Action surface; `version` input synced from `package.json` | consumers' workflows |
 | `packaging/gitlab/testguard.gitlab-ci.yml` | The GitLab component; tag and `TESTGUARD_VERSION` synced | consumers' pipelines |
 | `packaging/homebrew/testguard.rb` | The staged Homebrew formula; tarball URL and registry-derived hash synced, then copied byte-for-byte | `raccioly/homebrew-tap` |
+| `testguard.concerns.json` | The one-sentence scopes a sweep can be aimed by; optional, with two built-ins behind it | `testguard concerns`, `sweep --concern` |
 | `.docguard.json`, `.docguardignore` | Which canonical documents exist and which validators run | DocGuard, in CI and pre-commit |
 | `.npmrc`, `.npmignore`, `.gitattributes` | Packaging and line-ending hygiene | npm, git |
 

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/package-lock.json

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

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/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",

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/packaging/gitlab/testguard.gitlab-ci.yml

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

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/packaging/homebrew/testguard.rb

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

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/pyproject.toml

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

{testguard_cli-0.12.0 → testguard_cli-0.13.0}/spec/lib/validate.mjs

@@ -7,7 +7,7 @@ import { reproduces, decimals, MAX_PLACES } from './wilson.mjs';
 
 const schemaDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'schemas');
 
-export const KINDS = Object.freeze(['claims', 'evidence', 'baseline', 'ignore', 'calibration', 'brief', 'status', 'gate', 'replay', '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' });

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