testguard-cli 0.15.1__tar.gz → 0.16.0__tar.gz

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/.github/scripts/install-smoke.mjs

@@ -61,8 +61,18 @@ try {
     '-e',
     `import { pathToFileURL } from 'node:url'; import { readFileSync } from 'node:fs';
      const { validate } = await import(pathToFileURL(process.argv[1]));
-     const result = validate('evidence', JSON.parse(readFileSync(process.argv[2], 'utf8')));
+     const candidate = JSON.parse(readFileSync(process.argv[2], 'utf8'));
+     for (const r of candidate.records) {
+       r.defenders.selectionSource = r.defenders.requested.length ? 'claim' : 'discovery';
+       if (!r.defenders.requested.length) r.defenders.discovered = true;
+     }
+     const result = validate('evidence', candidate);
      if (!result.ok) throw new Error(result.errors.map((error) => \`${'${error.path}: ${error.message}'}\`).join('; '));
+     const claims = JSON.parse(readFileSync(process.argv[4], 'utf8'));
+     claims.claims[0].faults[0].defendedBy = [];
+     if (!validate('claims', claims).ok) throw new Error('installed package rejected a fault discovery override');
+     claims.claims[0].faults[0].defendedBy = ['test/unit.test.mjs'];
+     if (!validate('claims', claims).ok) throw new Error('installed package rejected a fault defender override');
      const gate = JSON.parse(readFileSync(process.argv[3], 'utf8'));
      gate.nested = [{ project: 'backend', files: ['backend/src/guard.mjs'] }]; gate.changed++;
      const nestedResult = validate('gate', gate);
@@ -71,6 +81,7 @@ try {
     installedValidator,
     candidateEvidence,
     join(root, 'spec', 'conformance', 'examples', 'gate.json'),
+    join(root, 'spec', 'conformance', 'examples', 'claims.json'),
   ], consumer).trim();
   if (!draft.claims?.length) throw new Error('scaffold produced no claims from the installed tarball');
   if (!/^\d+\.\d+\.\d+/.test(version)) throw new Error(`unexpected --version output: ${version}`);

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-09-30
+
+Automated weekly release — everything merged since `v0.15.1`.
+
+### Changed
+
+- feat: fault-specific defenders, provenance and cost reporting (#184)
+- Add advisory AI update guidance and stabilize cleanup regression (#183)
+- chore(homebrew): sha256 for v0.15.1 (#182)
+
+
+### Added
+
+- Fault-specific `defendedBy` overrides, with explicit empty-list discovery,
+  evidence selection provenance, per-fault cost reporting and prior-kill
+  narrowing warnings (#90). Selection changes invalidate reuse and status;
+  admission and changed-file coverage use the actual selected defenders.
+
+### Changed
+
+- New AI integrations include permission-aware, once-per-session update advice
+  that identifies the actual CLI and requests approval before any upgrade.
+  CLI commands and session-start hooks remain offline. Existing customized
+  instructions remain untouched; safe manual refresh is documented.
+
+### Fixed
+
+- The daemon-cleanup regression test now requires explicit startup and
+  post-cleanup release signals instead of assuming a detached process starts
+  and writes within fixed sleeps. Timeout and cleanup semantics are unchanged.
+
 ## [0.15.1] - 2026-09-30
 
 Automated weekly release — everything merged since `v0.15.0`.

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.15.1
+Version: 0.16.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.15.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.16.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.15.1/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.16.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
@@ -245,6 +245,14 @@ npx testguard-cli admit test/x.test.ts --claim X   # is this test green on HEAD
    the evidence records them as `repo.ignoredDirty`, so the run says what it
    did not look at. Every summary names the commit probed.
 
+   A fault may declare its own `defendedBy` to override the claim's set.
+   Omit the fault field to inherit; set it to `[]` to request discovery rather
+   than inheritance. Evidence names the selection origin and selected files.
+   Changing either invalidates reuse and makes status stale. A narrowed fault
+   set after a prior kill is warned about by `claims`; re-probe before trusting
+   it. For example, a unit-level fault can select `["test/unit.test.mjs"]`
+   while an integration fault inherits the claim's broader set.
+
    A claim with no `defendedBy` has its defenders **discovered**: the test
    files that import the fault's target, by relative path or resolved alias
    (tsconfig `paths`, through `extends` and `references`, vite/vitest
@@ -352,6 +360,34 @@ npx testguard-cli admit test/x.test.ts --claim X   # is this test green on HEAD
    offline. The brief's first line says which install answered
    (`local install` or `global`), so a stale one is visible.
 
+### Advisory updates for AI sessions
+
+New integrations created by `testguard init` tell the AI to identify the actual
+CLI (project-local before global) and, once per session when network policy
+permits, read the registry's stable version:
+
+```bash
+npm view testguard-cli dist-tags.latest --json --fetch-retries=0 --fetch-timeout=5000
+```
+
+This is an optional check performed by the AI, not by TestGuard's CLI or hook.
+A newer stable version produces a suggestion and a request for approval, never
+an automatic install. Project pins and the original package manager still
+apply; prereleases and development checkouts are not replaced. Offline or
+failed checks do not change verdicts, evidence or exit codes, and do not prove
+that an installation is current. AI instructions are guidance, not a guarantee
+that every harness performs the check.
+
+Upgrading the package does **not** refresh an existing copied skill or an
+existing managed section already listing the project. Compare the upgraded
+package's `src/init/templates/SKILL.md` with
+`.claude/skills/testguard/SKILL.md` and merge approved changes, preserving local
+customizations. For an existing `AGENTS.md` section, add the same advisory
+policy after reviewing it. `testguard init --force` replaces the whole skill
+but does not refresh an already-listed managed section; use it only with
+explicit overwrite approval and review the diff. No new automatic refresh
+mechanism is introduced.
+
 ### Would this suite have caught the bugs that already escaped?
 
 An injected fault is a fault somebody thought of. A bug that actually shipped
@@ -701,12 +737,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.15.1
+- uses: raccioly/testguard@v0.16.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.15.1/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.16.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
 ```
 
@@ -979,19 +1015,23 @@ most expensive claims
     4m 58s  TG-FAULT-EDIT-VISIBLE              1 fault  · 6 runs
 
 defender files, by the time of the runs that included them
-  (a claim runs its whole defender set at once, so these overlap and do not sum to the total)
+  (a fault runs its selected defender set at once, so these overlap and do not sum to the total)
     24m 3s  test/probe.fixture.test.mjs                  5 claims
 
-shared defenders — each claim pays the file's full cost again
+shared defenders — each fault selects the file; durations include recorded baseline sharing
     24m 3s  test/probe.fixture.test.mjs
-            named by TG-ESCALATION-N-RUNS, TG-FAULT-EDIT-VISIBLE, …
+            named by TG-ESCALATION-N-RUNS/F1, TG-FAULT-EDIT-VISIBLE/F1, …
 ```
 
 Every number is read back out of the `durationMs` the probe already records.
 `--cost` re-measures nothing, spawns nothing, and costs the price of reading
 one JSON file.
 
-**The per-file figures overlap.** A run executes a claim's whole defender set
+Cost output also lists individual faults, their selected defenders and selection
+origin. Sharing is counted across distinct fault identities, including siblings
+within one claim; repeated confirmation runs alone are not sharing.
+
+**The per-file figures overlap.** A run executes a fault's whole defender set
 at once, so the runner never says how much of it belonged to which file. A
 file's `ms` is the time of every run that *included* it: an upper bound on
 what removing it could save, which is the decision you are making. Only

{testguard_cli-0.15.1 → testguard_cli-0.16.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.15.1` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.16.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.15.1/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.16.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
@@ -221,6 +221,14 @@ npx testguard-cli admit test/x.test.ts --claim X   # is this test green on HEAD
    the evidence records them as `repo.ignoredDirty`, so the run says what it
    did not look at. Every summary names the commit probed.
 
+   A fault may declare its own `defendedBy` to override the claim's set.
+   Omit the fault field to inherit; set it to `[]` to request discovery rather
+   than inheritance. Evidence names the selection origin and selected files.
+   Changing either invalidates reuse and makes status stale. A narrowed fault
+   set after a prior kill is warned about by `claims`; re-probe before trusting
+   it. For example, a unit-level fault can select `["test/unit.test.mjs"]`
+   while an integration fault inherits the claim's broader set.
+
    A claim with no `defendedBy` has its defenders **discovered**: the test
    files that import the fault's target, by relative path or resolved alias
    (tsconfig `paths`, through `extends` and `references`, vite/vitest
@@ -328,6 +336,34 @@ npx testguard-cli admit test/x.test.ts --claim X   # is this test green on HEAD
    offline. The brief's first line says which install answered
    (`local install` or `global`), so a stale one is visible.
 
+### Advisory updates for AI sessions
+
+New integrations created by `testguard init` tell the AI to identify the actual
+CLI (project-local before global) and, once per session when network policy
+permits, read the registry's stable version:
+
+```bash
+npm view testguard-cli dist-tags.latest --json --fetch-retries=0 --fetch-timeout=5000
+```
+
+This is an optional check performed by the AI, not by TestGuard's CLI or hook.
+A newer stable version produces a suggestion and a request for approval, never
+an automatic install. Project pins and the original package manager still
+apply; prereleases and development checkouts are not replaced. Offline or
+failed checks do not change verdicts, evidence or exit codes, and do not prove
+that an installation is current. AI instructions are guidance, not a guarantee
+that every harness performs the check.
+
+Upgrading the package does **not** refresh an existing copied skill or an
+existing managed section already listing the project. Compare the upgraded
+package's `src/init/templates/SKILL.md` with
+`.claude/skills/testguard/SKILL.md` and merge approved changes, preserving local
+customizations. For an existing `AGENTS.md` section, add the same advisory
+policy after reviewing it. `testguard init --force` replaces the whole skill
+but does not refresh an already-listed managed section; use it only with
+explicit overwrite approval and review the diff. No new automatic refresh
+mechanism is introduced.
+
 ### Would this suite have caught the bugs that already escaped?
 
 An injected fault is a fault somebody thought of. A bug that actually shipped
@@ -677,12 +713,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.15.1
+- uses: raccioly/testguard@v0.16.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.15.1/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.16.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
 ```
 
@@ -955,19 +991,23 @@ most expensive claims
     4m 58s  TG-FAULT-EDIT-VISIBLE              1 fault  · 6 runs
 
 defender files, by the time of the runs that included them
-  (a claim runs its whole defender set at once, so these overlap and do not sum to the total)
+  (a fault runs its selected defender set at once, so these overlap and do not sum to the total)
     24m 3s  test/probe.fixture.test.mjs                  5 claims
 
-shared defenders — each claim pays the file's full cost again
+shared defenders — each fault selects the file; durations include recorded baseline sharing
     24m 3s  test/probe.fixture.test.mjs
-            named by TG-ESCALATION-N-RUNS, TG-FAULT-EDIT-VISIBLE, …
+            named by TG-ESCALATION-N-RUNS/F1, TG-FAULT-EDIT-VISIBLE/F1, …
 ```
 
 Every number is read back out of the `durationMs` the probe already records.
 `--cost` re-measures nothing, spawns nothing, and costs the price of reading
 one JSON file.
 
-**The per-file figures overlap.** A run executes a claim's whole defender set
+Cost output also lists individual faults, their selected defenders and selection
+origin. Sharing is counted across distinct fault identities, including siblings
+within one claim; repeated confirmation runs alone are not sharing.
+
+**The per-file figures overlap.** A run executes a fault's whole defender set
 at once, so the runner never says how much of it belonged to which file. A
 file's `ms` is the time of every run that *included* it: an upper bound on
 what removing it could save, which is the decision you are making. Only

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/action.yml

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

{testguard_cli-0.15.1 → testguard_cli-0.16.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.15.1 · MIT</div>
+    <div class="meta">Technical Brief · v0.16.0 · MIT</div>
   </div>
 
   <h1>Your tests pass. That is not the same as your tests working.</h1>

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/docs-canonical/DATA-MODEL.md

@@ -1,8 +1,8 @@
 # Data Model
 
-<!-- docguard:version 1.0.0 -->
+<!-- docguard:version 1.1.0 -->
 <!-- docguard:status approved -->
-<!-- docguard:last-reviewed 2026-09-19 -->
+<!-- docguard:last-reviewed 2026-09-30 -->
 <!-- docguard:owner @raccioly -->
 <!-- docguard:quality negation-load off — the data model is largely a set of prohibitions (no database, no server state, fingerprints never derived from fault text). -->
 <!-- docguard:quality passive-voice off — this document describes what happens to documents as they flow through validation, where the artifact is the subject and the actor is irrelevant. -->
@@ -60,12 +60,23 @@ be told from a mechanically derived one.
 `{find, replace}` against one file, with `expectHits` and `occurrence` so the
 anchor is exact. `faultClass` is one of thirteen values and exists so that
 calibration (fault class → real-bug predictiveness) can be computed later.
+An optional fault-level `defendedBy` overrides the claim's declaration.
+Presence matters: `[]` requests discovery, while absence inherits a non-empty
+claim list or discovers when the claim has none.
 
 ### Evidence record
 
 The verdict plus everything it rests on: every baseline run, every probe run,
 the resolved defenders, which of them merely mock the subject, the input
 hashes that make verdict reuse sound, and the rank.
+New records carry `defenders.selectionSource` (`fault`, `claim`, `discovery`)
+alongside requested and resolved selections. Empty selections carry
+`discovered: true`. Origin or selection changes invalidate reuse and status;
+the field remains optional so new readers can validate legacy evidence.
+
+Status cost reports include per-fault recorded durations and the selected
+defenders. File-level entries list distinct `claimId/faultId` identities;
+multiple confirmation runs for one fault do not constitute sharing.
 
 ### Verdict
 
@@ -78,7 +89,7 @@ Closed set of seven. Only `killed` is a pass:
 ```
 claims.json ──1:N──> claim ──1:N──> fault ──1:1──> evidence record
                        │                              │
-                       └── defendedBy ──> test files ─┘
+                       └── default defendedBy ─> fault selection ─> test files
                                                       │
 baseline.json ──suppresses by fingerprint────────────┘
                                                       │
@@ -107,9 +118,11 @@ target file to importing tests for defender discovery.
 The contract is versioned by `schemaVersion` inside every document and by the
 `urn:claimspec:v1:` identifier on every schema.
 
-- **Additive change** (a new optional field): no migration; older readers
-  ignore it, and `additionalProperties: false` means the field must be added to
-  the schema in the same change that emits it.
+- **Additive change** (a new optional field): new readers accept old documents
+  without migration. Older strict readers may reject the new field because
+  schemas use `additionalProperties: false`; upgrade those consumers before
+  asking them to validate new-format artifacts. Add the field to the schema
+  in the same change that emits it.
 - **Semantic change** (a new verdict, a new fault class, a changed rule): a
   spec change. The schema, `GATE-SEMANTICS.md`, the validator's semantic rules,
   a conformance example, a must-reject document and the known-answer fixture
@@ -125,4 +138,5 @@ The contract is versioned by `schemaVersion` inside every document and by the
 
 | Version | Date | Change | Author |
 |---|---|---|---|
+| 1.1.0 | 2026-09-30 | Fault defender overrides, selection provenance and per-fault costs; clarify strict-reader compatibility | @raccioly |
 | 1.0.0 | 2026-09-18 | First canonical data model, written against v0.6.0 | @raccioly |

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/docs-canonical/REQUIREMENTS.md

@@ -1,8 +1,8 @@
 # Requirements
 
-<!-- docguard:version 1.1.0 -->
+<!-- docguard:version 1.2.0 -->
 <!-- docguard:status approved -->
-<!-- docguard:last-reviewed 2026-09-19 -->
+<!-- docguard:last-reviewed 2026-09-30 -->
 <!-- docguard:owner @raccioly -->
 <!-- docguard:quality passive-voice off — requirements are written in the standard "the system shall ..." register, where the agent is the system throughout. -->
 
@@ -28,6 +28,7 @@
 | FR-14 | Serve the read-only operating loop over MCP so the loop survives a change of agent harness | P3 |
 | FR-15 | Validate every exact fault anchor and the syntax of supported in-memory replacements before starting a test runner (`claims --check-anchors`), without guessing repairs | P1 |
 | FR-16 | Preserve every repeated or comma-separated `probe --claim` selection in first-seen order, collapse duplicates, and report requested versus probed scope without allowing an empty selection to pass | P1 |
+| FR-17 | Select defenders per fault: an explicit override takes precedence, an empty override requests discovery, and absence inherits the claim. Record the origin, invalidate stale/reused selections, report per-fault costs and warn on narrowing after a prior kill | P1 |
 
 ## Non-Functional Requirements
 
@@ -103,6 +104,7 @@ fails the pull request naming the unclaimed file, and `status` reports
 | FR-14 | `src/mcp/` | `test/mcp.test.mjs` |
 | FR-15 | `src/claims/anchors.mjs`, `src/commands/claims.mjs`, `src/status/status.mjs` | `test/claims-anchors.test.mjs`, `test/status.test.mjs`, `TG-ANCHOR-PREFLIGHT-FAILS-FAST` |
 | FR-16 | `src/cli.mjs`, `src/commands/probe.mjs`, `src/probe/probe.mjs`, `src/commands/scaffold.mjs`, `src/commands/admit.mjs` | `test/claim-selection.test.mjs`, `test/probe.fixture.test.mjs`, `TG-REPEATED-CLAIMS-ARE-ALL-PROBED` |
+| FR-17 | `src/probe/attribution.mjs`, `src/probe/probe.mjs`, `src/commands/claims.mjs`, `src/status/status.mjs`, `src/probe/cost.mjs` | `test/fault-defenders.test.mjs`, `test/attribution.test.mjs`, `test/status.test.mjs`, `test/cost.test.mjs`, `TG-FAULT-DEFENDER-SELECTION`, `TG-FAULT-DEFENDER-ORCHESTRATION` |
 | NFR-01 | `src/init/init.mjs`, runner resolution | `TG-INIT-HOOK-NO-NETWORK`, `TG-README-HOOK-MATCHES-THE-CODE` (every surface, not only the README), `TG-GITIGNORE-ADVICE-IS-ONE-LIST` |
 | NFR-02 | `package.json` | `npm run test:install` in CI |
 | NFR-03 | `src/probe/inject.mjs`, `src/probe/probe.mjs` | `TG-DIRTY-DEFENDERS-REFUSED`, `TG-IGNORED-DIRTY-RECORDED`, `TG-IN-PLACE-STILL-RAISES-A-MISSING-TARGET`, `TG-CONTROL-RESTORES-THE-SUBJECT` |
@@ -116,5 +118,6 @@ fails the pull request naming the unclaimed file, and `status` reports
 
 | Version | Date | Change | Author |
 |---|---|---|---|
+| 1.2.0 | 2026-09-30 | Approved fault-specific defender selection and attributable costs | @raccioly |
 | 1.1.0 | 2026-09-19 | Require lossless, visible partial claim selection | @raccioly |
 | 1.0.0 | 2026-09-18 | First canonical requirements, written against v0.6.0 | @raccioly |

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/docs-canonical/TEST-SPEC.md

@@ -1,8 +1,8 @@
 # Test Specification
 
-<!-- docguard:version 1.0.0 -->
+<!-- docguard:version 1.1.0 -->
 <!-- docguard:status approved -->
-<!-- docguard:last-reviewed 2026-09-22 -->
+<!-- docguard:last-reviewed 2026-09-30 -->
 <!-- docguard:owner @raccioly -->
 <!-- docguard:quality negation-load off — the governing rule is a prohibition (a test that would pass with the behaviour broken is not a test), and the verdict rules are defined by what does not count as detection. -->
 
@@ -21,7 +21,7 @@ the test that defends it, and CI fails if any injected fault survives.
 | Conformance | `spec/conformance/` | Every valid example validates; every must-reject document is rejected for the defect its filename names | ~1 s |
 | Anchor preflight | `test/claims-anchors.test.mjs` | Exact anchors still locate, supported replacements parse, the check stays below one second, and CI reaches it before self-probe | <1 s |
 | Fixture acceptance | `test/probe.fixture.test.mjs`, `test/probe.jest.test.mjs`, `test/probe.playwright.test.mjs` | The whole pipeline reproduces a known-answer oracle, one per runner. The Playwright fixture carries its own dependencies: without `npm ci --prefix fixtures/known-answer-playwright` that file skips, and a skipped acceptance is not a passing one | 10–50 s each |
-| Self-verification | `testguard.claims.json`, run by `npm run self:probe` | The tool's own invariants survive fault injection | **20.2 min** cold (measured by the v0.10.1 release job on 2026-09-19 at `70e9d61`: 154 faults, 924 defender runs, 1210 s); seconds when verdicts are reused, which is why PR CI restores previous evidence from cache. Budgeted at 1440 s in `testguard.cost-budget.json` for the additional four-fault live-tap claim and **gated** in CI — cost growth is reviewed instead of disappearing into a passing log |
+| Self-verification | `testguard.claims.json`, run by `npm run self:probe` | The tool's own invariants survive fault injection | Historical cold measurement: **20.2 min** in the v0.10.1 release job on 2026-09-19 at `70e9d61` (154 faults, 924 defender runs, 1210 s). PR CI restores previous evidence for reuse. Current committed ceilings in `testguard.cost-budget.json`: 2250 s total and 100 s per claim; both gate CI, and neither changes for fault-specific selection |
 | Install smoke | `.github/scripts/install-smoke.mjs` | The **packed tarball** runs with production dependencies only | ~20 s |
 | Runtime budget | `ci.yml` | The suite has not silently started walking the wrong tree | gate, not a test |
 
@@ -31,7 +31,7 @@ the test that defends it, and CI fails if any injected fault survives.
 `durationMs` already on every run in an evidence document. They re-measure
 nothing.
 
-A probe's wall clock is, per claim,
+A probe's historical wall-clock model, before fault-specific selection, was per claim:
 `(baseline runs + faults × --confirm) × the cost of that claim's defender
 SET`. One slow acceptance test named by several claims is therefore paid for
 once per claim, which is what made the gate take 24 minutes: a single 49.5 s
@@ -39,8 +39,15 @@ fixture test defended five claims. Those claims now point at pure functions
 with unit-test defenders (issue #67), and the gate measures **9.6 minutes**
 from scratch, serially, for 68 faults.
 
+Fault-specific selection runs each fault's selected set. Baselines are cached
+by that set, not claim identity; per-fault cost records expose which files
+actually ran. Repeated confirmations alone are not shared-defender usage.
+`test/fault-defenders.test.mjs` covers inheritance, overrides, explicit-empty
+discovery, origin-sensitive reuse, dirty-input refusal, runner ownership,
+narrowing warnings and admission through the actual selected set.
+
 Per-file cost figures are an **upper bound, not a share**: a run executes a
-claim's whole defender set at once, so the runner never attributes time to
+fault's whole selected defender set at once, so the runner never attributes time to
 one file. They overlap and do not sum to the total.
 
 ## Coverage Rules
@@ -69,7 +76,7 @@ What is gated instead:
 | `src/probe/classify.mjs` | `test/classify.test.mjs`, `test/negative-control.test.mjs` |
 | `src/probe/inject.mjs` | `test/inject.test.mjs` |
 | `src/claims/anchors.mjs` | `test/claims-anchors.test.mjs` |
-| `src/probe/probe.mjs` | `test/probe.fixture.test.mjs`, `test/probe-preconditions.test.mjs`, `test/probe-error.test.mjs` |
+| `src/probe/probe.mjs` | `test/probe.fixture.test.mjs`, `test/probe-preconditions.test.mjs`, `test/probe-error.test.mjs`, `test/fault-defenders.test.mjs` |
 | `src/probe/discover.mjs`, `src/probe/mocks.mjs` | `test/discover.test.mjs`, `test/mocks.test.mjs` |
 | `src/probe/rank.mjs` | `test/rank-aliases.test.mjs`, `test/discover.test.mjs` |
 | `src/probe/runners/` | `test/runner-vitest.test.mjs`, `test/runner-command.test.mjs`, `test/runner-playwright.test.mjs` |

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/package-lock.json

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

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.15.1",
+  "version": "0.16.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.15.1 → testguard_cli-0.16.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.15.1/packaging/gitlab/testguard.gitlab-ci.yml'
+#     - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.16.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.15.1"
+      default: "0.16.0"
     dir:
       description: directory whose test runner is invoked (where testguard.claims.json lives)
       default: "."

{testguard_cli-0.15.1 → testguard_cli-0.16.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.15.1.tgz"
-  sha256 "357f37905e99bf2d1a7487374bc2fc2b97983fd8d355b2e77d72e03fb0f2f8c7"
+  url "https://registry.npmjs.org/testguard-cli/-/testguard-cli-0.16.0.tgz"
+  sha256 "f352a8092263cbc949d41af3453e57e90882eebceb04658c1848564246ee18d7"
   license "MIT"
 
   depends_on "node"

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "testguard-cli"
-version = "0.15.1"
+version = "0.16.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.15.1 → testguard_cli-0.16.0}/spec/GATE-SEMANTICS.md

@@ -1,5 +1,26 @@
 # Gate semantics
 
+## Fault-specific defender selection
+
+A fault's `defendedBy`, when present, overrides its claim's declaration.
+An explicit empty fault list requests discovery and never falls back to the
+claim. Without a fault override, a non-empty claim list is inherited; otherwise
+defenders are discovered. New evidence records `defenders.selectionSource` as
+`fault`, `claim`, or `discovery`, alongside the actual requested and resolved
+sets. Empty requests use discovery and carry `discovered: true`, including an
+explicit empty fault override. Non-empty requests are never marked discovered.
+Dirty-input preflight, runner ownership, mock-awareness, input hashing and
+baseline caching all operate on each fault's selected defender set.
+
+Changing requested globs, resolved files or selection origin invalidates verdict
+reuse. Legacy evidence remains readable but cannot authorize a new fault-level
+override. A strict resolved subset after a previous kill is reported by `claims`
+as a narrowing warning and requires re-probing; it is not a new verdict.
+Cost reports include per-fault recorded run durations and selection origin.
+Shared defenders identify the actual fault records that selected each file,
+including multiple faults within one claim. File costs remain overlapping upper
+bounds, not additive shares. Existing total/per-claim budget ceilings are unchanged.
+
 How a Guard-spec tool decides whether CI goes red. Shared by every tool that
 adopts the spec; each tool may add stricter rules, never looser ones.
 

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/spec/conformance/schemas.test.mjs

@@ -8,11 +8,55 @@ import { dirname, join, basename } from 'node:path';
 import { validate, KINDS } from '../lib/validate.mjs';
 import { fingerprint } from '../lib/fingerprint.mjs';
 import { probit, zCandidates, wilsonInterval, roundTo } from '../lib/wilson.mjs';
+import { costReport } from '../../src/probe/cost.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const load = (dir, f) => JSON.parse(readFileSync(join(here, dir, f), 'utf8'));
 
 describe('claimspec v1 — conformance', () => {
+  it('admits per-fault cost output in status and rejects invalid selection origins', () => {
+    const status = load('examples', 'status.json');
+    const evidence = load('examples', 'evidence.json');
+    status.cost = costReport(evidence.records);
+    expect(validate('status', status).errors).toEqual([]);
+    status.cost.faults[0].selectionSource = 'fault';
+    expect(validate('status', status).errors).toEqual([]);
+    status.cost.faults[0].selectionSource = 'guessed';
+    expect(validate('status', status).ok).toBe(false);
+    delete status.cost.faults;
+    for (const d of [...status.cost.defenders, ...status.cost.sharedDefenders]) delete d.faults;
+    expect(validate('status', status).errors).toEqual([]);
+  });
+  it('admits fault overrides and rejects duplicate or malformed defender declarations', () => {
+    const claims = load('examples', 'claims.json');
+    const fault = claims.claims[0].faults[0];
+    fault.defendedBy = ['test/unit.test.mjs'];
+    expect(validate('claims', claims).errors).toEqual([]);
+    fault.defendedBy = [];
+    expect(validate('claims', claims).errors).toEqual([]);
+    fault.defendedBy = ['same', 'same'];
+    expect(validate('claims', claims).ok).toBe(false);
+    fault.defendedBy = [42];
+    expect(validate('claims', claims).ok).toBe(false);
+  });
+
+  it('validates defender selection origin without rejecting legacy evidence', () => {
+    const evidence = load('examples', 'evidence.json');
+    const d = evidence.records[0].defenders;
+    delete d.selectionSource;
+    expect(validate('evidence', evidence).errors).toEqual([]);
+    d.selectionSource = 'discovery';
+    d.discovered = false;
+    expect(validate('evidence', evidence).ok).toBe(false);
+    d.selectionSource = 'claim'; d.requested = []; delete d.discovered;
+    expect(validate('evidence', evidence).ok).toBe(false);
+    d.selectionSource = 'fault'; d.discovered = true;
+    expect(validate('evidence', evidence).errors).toEqual([]);
+    d.requested = ['test/unit.test.mjs'];
+    expect(validate('evidence', evidence).ok).toBe(false);
+    delete d.discovered;
+    expect(validate('evidence', evidence).errors).toEqual([]);
+  });
   it('accounts for descendant-project delegation without calling it coverage or double-counting it', () => {
     const gate = load('examples', 'gate.json');
     gate.nested = [{ project: 'backend', files: ['backend/src/guard.mjs'] }];

{testguard_cli-0.15.1 → testguard_cli-0.16.0}/spec/lib/validate.mjs

@@ -146,6 +146,15 @@ const semantic = {
       if (r.detail.undeclaredKillers && r.detail.reason !== 'killed-by-undeclared-tests') {
         errors.push({ path: `${p}/detail/undeclaredKillers`, message: 'undeclaredKillers is only meaningful with reason killed-by-undeclared-tests' });
       }
+      if (r.defenders.selectionSource) {
+        const empty = r.defenders.requested.length === 0;
+        if ((r.defenders.selectionSource === 'discovery' && !empty)
+          || (r.defenders.selectionSource === 'claim' && empty)
+          || (empty && r.defenders.discovered !== true)
+          || (!empty && r.defenders.discovered === true)) {
+          errors.push({ path: `${p}/defenders/selectionSource`, message: 'defender selection origin, requested set and discovery flag disagree' });
+        }
+      }
       if (r.defenders.byRunner) {
         const resolved = new Set(r.defenders.resolved);
         for (const [runner, files] of Object.entries(r.defenders.byRunner)) for (const f of files) if (!resolved.has(f)) errors.push({ path: `${p}/defenders/byRunner/${runner}`, message: `${f} ran under ${runner} but is not a resolved defender` });