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

testguard_cli-0.16.0/.github/scripts/install-smoke.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Prove the package works AS INSTALLED, not as checked out: pack it, install
+ * the tarball into a scratch project with production dependencies only, and
+ * run the CLI from there. This is the gate that would have caught 0.1.0,
+ * which shipped with its schema validator's dependency declared as a
+ * devDependency and crashed on startup for every npm/npx/pip/brew user.
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, cpSync, readdirSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const root = resolve(process.argv[1], '..', '..', '..');
+const run = (cmd, args, cwd) => execFileSync(cmd, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'] });
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+const scratch = mkdtempSync(join(tmpdir(), 'testguard-install-smoke-'));
+try {
+  const packDir = join(scratch, 'pack');
+  mkdirSync(packDir);
+  run(npm, ['pack', '--pack-destination', packDir, '--ignore-scripts'], root);
+  const tgz = join(packDir, readdirSync(packDir).find((f) => f.endsWith('.tgz')));
+
+  const consumer = join(scratch, 'consumer');
+  cpSync(join(root, 'fixtures', 'known-answer'), consumer, { recursive: true, filter: (s) => !/node_modules|\.flake-counter|\.testguard/.test(s) });
+  run(npm, ['init', '-y'], consumer);
+  run(npm, ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', tgz], consumer);
+
+  const bin = join(consumer, 'node_modules', '.bin', process.platform === 'win32' ? 'testguard.cmd' : 'testguard');
+  const version = run(bin, ['--version'], consumer).trim();
+  const emptyProject = join(scratch, 'empty-adoption');
+  mkdirSync(emptyProject);
+  writeFileSync(join(emptyProject, 'testguard.claims.json'), JSON.stringify({ schemaVersion: 1, claims: [] }));
+  const emptyStatus = JSON.parse(run(bin, ['probe', emptyProject, '--allow-empty', '--json'], consumer));
+  if (emptyStatus.state !== 'no-claims' || emptyStatus.run || existsSync(join(emptyProject, '.testguard', 'evidence.json'))) throw new Error('installed empty-adoption probe invented verification evidence');
+  const replayHelp = run(bin, ['replay', '--help'], consumer);
+  if (!replayHelp.includes('--since') || replayHelp.includes('--node-modules')) throw new Error('installed command help is not command-specific');
+  writeFileSync(join(emptyProject, 'vite.config.mjs'), "export default { base: '/', plugins: [{ configureServer(s) { s.middlewares.use('/__rooms', () => {}); const parts = '/__room'.split('/'); } }] };\n");
+  const installedDiscovery = join(consumer, 'node_modules', 'testguard-cli', 'src', 'probe', 'runners', 'discovery.mjs');
+  run(process.execPath, ['--input-type=module', '-e',
+    "import { pathToFileURL } from 'node:url'; const { hashDiscoveryConfigs } = await import(pathToFileURL(process.argv[1])); hashDiscoveryConfigs(process.argv[2], ['vite.config.mjs']);",
+    installedDiscovery, emptyProject,
+  ], consumer);
+  const installedRunner = join(consumer, 'node_modules', 'testguard-cli', 'src', 'probe', 'runners', 'shared.mjs');
+  run(process.execPath, ['--input-type=module', '-e',
+    `import { pathToFileURL } from 'node:url'; const { parseReport } = await import(pathToFileURL(process.argv[1]));
+     const result = parseReport({ success: false, numTotalTests: 2, numFailedTests: 2, testResults: [{ name: 'test.mjs', status: 'failed', assertionResults: [
+       { status: 'failed', failureMessages: ['AssertionError: expected /specify timed out/'] },
+       { status: 'failed', failureMessages: ['Error: Test timed out in 1000ms.'] },
+     ] }] }, 1);
+     if (result.timeouts !== 1 || result.run.assertionFailures !== 1) throw new Error('installed runner confuses assertion text with timeout identity');`,
+    installedRunner,
+  ], consumer);
+  const claims = run(bin, ['claims', '.'], consumer);
+  const draft = JSON.parse(run(bin, ['scaffold', 'src/redact.mjs', '--json'], consumer));
+  const installedValidator = join(consumer, 'node_modules', 'testguard-cli', 'spec', 'lib', 'validate.mjs');
+  const candidateEvidence = join(root, 'spec', 'conformance', 'examples', 'evidence.json');
+  const validatesCandidateEvidence = run(process.execPath, [
+    '--input-type=module',
+    '-e',
+    `import { pathToFileURL } from 'node:url'; import { readFileSync } from 'node:fs';
+     const { validate } = await import(pathToFileURL(process.argv[1]));
+     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);
+     if (!nestedResult.ok) throw new Error('installed package rejected the nested-project gate contract');
+     process.stdout.write('ok');`,
+    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}`);
+  if (!/^\d+ claims in /.test(claims)) throw new Error(`claims did not list the fixture:\n${claims}`);
+  if (validatesCandidateEvidence !== 'ok') throw new Error('installed package did not validate candidate-format evidence');
+  const deps = Object.keys(JSON.parse(run(npm, ['ls', '--omit=dev', '--json', '--depth=0'], consumer)).dependencies ?? {});
+  console.log(`install smoke OK — testguard ${version} runs from the installed tarball; consumer deps: ${deps.join(', ')}`);
+} finally {
+  rmSync(scratch, { recursive: true, force: true });
+}

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

@@ -7,6 +7,70 @@ 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`.
+
+### Changed
+
+- fix: runner timeout identity and reported adoption regressions (#180)
+- chore(homebrew): sha256 for v0.15.0 (#177)
+
+
+### Fixed
+
+- Assertion messages quoting "timed out" no longer become runner timeouts.
+  Native timeout headers and structured timeout failures remain non-detections
+  (#179).
+- Configuration dependency hashing no longer rejects harmless absolute-looking
+  strings such as Vite URL bases, middleware routes, or `split('/')`. Existing
+  outside-project file dependencies and symlinks still fail closed (#178).
+- Discovery failures no longer assert that dependencies are missing when the
+  runner resolved successfully but its configuration could not be discovered.
+- Each subcommand's `--help` now shows its own options and an example; global
+  `--help` exits successfully and points to command-specific help (#120).
+- Parent gates, status change reports, and claimed-surface counts respect valid
+  nested TestGuard project boundaries. Delegated files are explicitly reported
+  and require a separate child gate; invalid or symlinked markers fail (#150).
+
+### Added
+
+- Explicit `probe --allow-empty` adoption mode, also available as an opt-in
+  GitHub Action input. A valid empty claims file skips verification without
+  writing evidence; JSON keeps the `no-claims` state. Default empty probes,
+  invalid claims, and explicit claim selections still fail (#176).
+
 ## [0.15.0] - 2026-09-29
 
 Automated weekly release — everything merged since `v0.14.2`.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: testguard-cli
-Version: 0.15.0
+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.0` — 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.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.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
@@ -431,6 +467,20 @@ is missing. TestGuard itself still makes no network calls.
 
 ### Starting from zero claims
 
+During gradual adoption, use `testguard probe --allow-empty` to skip a valid
+empty claims file without blocking a push. It explicitly reports that no
+verification was performed and writes no evidence; `--json` retains the
+`no-claims` state. Missing or invalid claims files still fail. Run `gate`
+separately to enforce changed-file coverage. For the pre-commit probe hook,
+set `args: [--allow-empty]`; for the GitHub Action, set `allow-empty: 'true'`.
+The default probe still exits 2 when no claims exist.
+
+In a monorepo, a valid nested `testguard.claims.json` marks a separate project.
+The parent gate reports its changed files as delegated and does not count them
+as parent coverage. Run `gate` in each child project as well; a passing parent
+gate does not establish that child coverage passed. Invalid child claims fail
+evaluation instead of hiding files.
+
 `gate` names the changed files that carry no claim, and stops there —
 correctly, because stating a claim is a human act. But a project adopting this
 tool reads that list, has nothing to compare it against, and closes the tab.
@@ -687,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.0
+- 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.0/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
 ```
 
@@ -965,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.0 → 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.0` — 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.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.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
@@ -407,6 +443,20 @@ is missing. TestGuard itself still makes no network calls.
 
 ### Starting from zero claims
 
+During gradual adoption, use `testguard probe --allow-empty` to skip a valid
+empty claims file without blocking a push. It explicitly reports that no
+verification was performed and writes no evidence; `--json` retains the
+`no-claims` state. Missing or invalid claims files still fail. Run `gate`
+separately to enforce changed-file coverage. For the pre-commit probe hook,
+set `args: [--allow-empty]`; for the GitHub Action, set `allow-empty: 'true'`.
+The default probe still exits 2 when no claims exist.
+
+In a monorepo, a valid nested `testguard.claims.json` marks a separate project.
+The parent gate reports its changed files as delegated and does not count them
+as parent coverage. Run `gate` in each child project as well; a passing parent
+gate does not establish that child coverage passed. Invalid child claims fail
+evaluation instead of hiding files.
+
 `gate` names the changed files that carry no claim, and stops there —
 correctly, because stating a claim is a human act. But a project adopting this
 tool reads that list, has nothing to compare it against, and closes the tab.
@@ -663,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.0
+- 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.0/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
 ```
 
@@ -941,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.0 → testguard_cli-0.16.0}/action.yml

@@ -35,6 +35,10 @@ inputs:
     description: 'Skip re-running survivors against the whole suite'
     required: false
     default: 'false'
+  allow-empty:
+    description: 'probe only: explicitly skip a valid empty claims file during adoption; writes no evidence. Run gate separately.'
+    required: false
+    default: 'false'
   changed-ref:
     description: 'gate only: the reference the change is measured against (default: origin/<base branch> of the pull request). Check out with fetch-depth: 0 so it resolves.'
     required: false
@@ -46,7 +50,7 @@ inputs:
   version:
     description: 'testguard-cli version to run'
     required: false
-    default: '0.15.0'
+    default: '0.16.0'
   node-version:
     description: 'Node.js version (20+)'
     required: false
@@ -82,6 +86,7 @@ runs:
         if [ "${{ inputs.command }}" = "probe" ]; then
           ARGS+=(--severity "${{ inputs.severity }}" --confirm "${{ inputs.confirm }}" --budget "${{ inputs.budget }}")
           [ "${{ inputs.no-escalate }}" = "true" ] && ARGS+=(--no-escalate)
+          [ "${{ inputs.allow-empty }}" = "true" ] && ARGS+=(--allow-empty)
           [ "${{ inputs.runner }}" != "auto" ] && ARGS+=(--runner "${{ inputs.runner }}")
           [ -n "${{ inputs.python }}" ] && ARGS+=(--python "${{ inputs.python }}")
         fi

{testguard_cli-0.15.0 → 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.0 · 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.0 → 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.0 → 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.0 → 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.0 → testguard_cli-0.16.0}/package-lock.json

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