testguard-cli 0.15.1 → 0.16.0

package/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`.

package/README.md

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

package/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",

package/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.
 

package/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` });

package/spec/schemas/claims.schema.json

@@ -121,6 +121,12 @@
         "faultClass": {
           "$ref": "urn:claimspec:v1:common#/$defs/faultClass"
         },
+        "defendedBy": {
+          "description": "Overrides this fault's claim-level defenders when present. An explicit empty list requests discovery; absence inherits the claim. Selection changes require re-probing, never assumed detection.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
         "file": {
           "$ref": "urn:claimspec:v1:common#/$defs/repoPath"
         },

package/spec/schemas/evidence.schema.json

@@ -520,6 +520,10 @@
             "nocover"
           ],
           "properties": {
+            "selectionSource": {
+              "description": "Origin of the requested defender selection: explicit fault override, inherited non-empty claim declaration, or automatic discovery. Optional only for legacy evidence; a changed origin invalidates reuse.",
+              "enum": ["fault", "claim", "discovery"]
+            },
             "requested": {
               "type": "array",
               "items": {

package/spec/schemas/status.schema.json

@@ -195,6 +195,24 @@
         "totalRuns": { "type": "integer", "minimum": 0 },
         "reusedRecords": { "type": "integer", "minimum": 0 },
         "records": { "type": "integer", "minimum": 0 },
+        "faults": {
+          "description": "Recorded costs and selected defenders per fault; optional for legacy reports.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["claimId", "faultId", "ms", "runs", "reused", "defenders"],
+            "properties": {
+              "claimId": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" },
+              "faultId": { "$ref": "urn:claimspec:v1:common#/$defs/identifier" },
+              "ms": { "type": "number", "minimum": 0 },
+              "runs": { "type": "integer", "minimum": 0 },
+              "reused": { "type": "boolean" },
+              "selectionSource": { "enum": ["fault", "claim", "discovery"] },
+              "defenders": { "type": "array", "uniqueItems": true, "items": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" } }
+            },
+            "additionalProperties": false
+          }
+        },
         "claims": {
           "type": "array",
           "items": {
@@ -483,6 +501,13 @@
         "file": { "$ref": "urn:claimspec:v1:common#/$defs/repoPath" },
         "ms": { "type": "number", "minimum": 0 },
         "runs": { "type": "integer", "minimum": 0 },
+        "faults": {
+          "description": "Distinct claimId/faultId identities selecting this file, not confirmation runs.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
         "claims": {
           "type": "array",
           "minItems": 1,

package/src/commands/admit.mjs

@@ -5,6 +5,7 @@ import { probe } from '../probe/probe.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
+import { defenderSelection } from '../probe/attribution.mjs';
 import { PreconditionError } from '../probe/worktree.mjs';
 import { hintFor } from '../brief/brief.mjs';
 import { formatVerdict, PROVISIONAL_WARNING } from '../render.mjs';
@@ -62,11 +63,15 @@ export async function admitCommand({ file, values, version }, io) {
 
   // The named test must be a defender of the claim, declared or discovered;
   // otherwise `killed` below would be someone else's test doing the work.
-  const declared = claim.defendedBy?.length ? resolveDefenders(projectDir, claim.defendedBy) : null;
-  const isDefender = declared ? declared.includes(testRel) : faults.some((f) => discoverDefenders(projectDir, f.file).includes(testRel));
+  const selections = faults.map((f) => {
+    const { requested } = defenderSelection(claim, f);
+    return { requested, resolved: requested.length ? resolveDefenders(projectDir, requested) : discoverDefenders(projectDir, f.file) };
+  });
+  const declared = selections.every((s) => s.requested.length) ? selections[0].requested : null;
+  const isDefender = selections.some((s) => s.resolved.includes(testRel));
   if (!isDefender) {
     io.err(declared
-      ? `${testRel} is not a defender of ${claimId}. Add it: "defendedBy": [${[...claim.defendedBy, testRel].map((d) => JSON.stringify(d)).join(', ')}] in testguard.claims.json, then run admit again.`
+      ? `${testRel} is not a defender of ${claimId}. Add it: "defendedBy": [${[...declared, testRel].map((d) => JSON.stringify(d)).join(', ')}] on the selected fault or its inherited claim in testguard.claims.json, then run admit again.`
       : `${testRel} does not import ${[...new Set(faults.map((f) => f.file))].join(' or ')}, so it cannot be discovered as a defender of ${claimId}. Import the module under test, or declare "defendedBy": ["${testRel}"] on the claim.`);
     return 3;
   }

package/src/commands/claims.mjs

@@ -10,6 +10,27 @@ import { costReport, renderCost } from '../probe/cost.mjs';
 import { readSpecDoc } from '../evidence/writer.mjs';
 import { existsSync } from 'node:fs';
 import { checkAnchors, renderAnchorChecks } from '../claims/anchors.mjs';
+import { defenderSelection } from '../probe/attribution.mjs';
+
+/** A selection warning is not a verdict: only a fresh probe can defend it. */
+export function defenderNarrowing(projectDir, claims, records) {
+  const prior = new Map(records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]));
+  const warnings = [];
+  for (const c of claims.claims) {
+    const inherited = c.defendedBy?.length ? resolveDefenders(projectDir, c.defendedBy) : [];
+    for (const f of c.faults) {
+      const record = prior.get(`${c.id}/${f.id}`);
+      if (!Object.hasOwn(f, 'defendedBy') || record?.verdict !== 'killed') continue;
+      const { requested } = defenderSelection(c, f);
+      const resolved = requested.length ? resolveDefenders(projectDir, requested) : discoverDefendersDetailed(projectDir, f.file).canDetect;
+      if (record.defenders.selectionSource === 'fault' && JSON.stringify(record.defenders.requested) === JSON.stringify(requested) && JSON.stringify([...record.defenders.resolved].sort()) === JSON.stringify([...resolved].sort())) continue;
+      if (resolved.length < inherited.length && resolved.every((d) => inherited.includes(d))) {
+        warnings.push({ claimId: c.id, faultId: f.id, inherited, resolved });
+      }
+    }
+  }
+  return warnings;
+}
 
 export async function claimsCommand({ projectDir, values, version }, io) {
   const path = values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir);
@@ -28,14 +49,17 @@ export async function claimsCommand({ projectDir, values, version }, io) {
 
   // Cost is read back out of evidence the probe already wrote; it never runs a test.
   let cost;
+  const ev = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
+  const hasOverrides = claims.claims.some((c) => c.faults.some((f) => Object.hasOwn(f, 'defendedBy')));
+  const prior = (values.cost || hasOverrides) && existsSync(ev) ? readSpecDoc('evidence', ev) : undefined;
+  const narrowedDefenders = hasOverrides && prior ? defenderNarrowing(projectDir, claims, prior.records) : [];
   if (values.cost) {
-    const ev = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
-    cost = existsSync(ev) ? costReport(readSpecDoc('evidence', ev).records) : undefined;
+    cost = prior ? costReport(prior.records) : undefined;
     if (!cost && !values.json) io.err(`no evidence at ${ev} — run \`testguard probe\` first; cost is derived from the run durations it records`);
   }
 
   if (values.json) {
-    io.out(JSON.stringify({ path, claims, annotations, drift, ...(anchorChecks ? { anchorChecks } : {}), ...(removed ? { removed } : {}), ...(cost ? { cost } : {}) }, null, 2));
+    io.out(JSON.stringify({ path, claims, annotations, drift, ...(hasOverrides ? { narrowedDefenders } : {}), ...(anchorChecks ? { anchorChecks } : {}), ...(removed ? { removed } : {}), ...(cost ? { cost } : {}) }, null, 2));
   } else {
     const annotated = new Set(drift.annotated);
     io.out(`${claims.claims.length} claims in ${path} — ${annotated.size} carry a @claim annotation in source (test files are not scanned)`);
@@ -45,7 +69,18 @@ export async function claimsCommand({ projectDir, values, version }, io) {
       const declared = c.defendedBy?.length > 0;
       const targets = [...new Set(c.faults.map((f) => f.file))];
       let cover;
-      if (declared) {
+      if (c.faults.some((f) => Object.hasOwn(f, 'defendedBy'))) {
+        const selected = new Set();
+        for (const f of c.faults) {
+          const selection = defenderSelection(c, f);
+          const defenders = selection.requested.length ? resolveDefenders(projectDir, selection.requested) : discoverDefendersDetailed(projectDir, f.file).canDetect;
+          defenders.forEach((d) => selected.add(d));
+          const m = classifyDefenders(projectDir, f.file, defenders);
+          for (const s of m.signals) signalLines.push({ claim: c.id, target: f.file, ...s });
+          io.out(`  ${c.id}/${f.id}: ${selection.selectionSource}${selection.requested.length ? '' : ' (discovery)'} — ${defenders.join(', ') || 'NO DEFENDER'}`);
+        }
+        cover = `${selected.size} selected defender${selected.size === 1 ? '' : 's'}`;
+      } else if (declared) {
         const defenders = resolveDefenders(projectDir, c.defendedBy);
         const mocking = new Set();
         for (const t of targets) { const m = classifyDefenders(projectDir, t, defenders); m.mocking.forEach((f) => mocking.add(f)); for (const s of m.signals) signalLines.push({ claim: c.id, target: t, ...s }); }
@@ -70,6 +105,7 @@ export async function claimsCommand({ projectDir, values, version }, io) {
     if (drift.undeclared.length || drift.stale.length) io.out('');
     for (const a of drift.undeclared) io.out(`UNDECLARED   @claim ${a.id} at ${a.file}:${a.line} has no entry in the claims file — a claim with no fault model`);
     for (const c of drift.stale) io.out(`STALE        ${c.id} is annotation-sourced but no source file carries @claim ${c.id}`);
+    for (const w of narrowedDefenders) io.out(`NARROWED-DEFENDERS  ${w.claimId}/${w.faultId} selects ${w.resolved.length} of ${w.inherited.length} inherited defenders after a prior kill — re-probe; the old kill does not prove the narrower selection.`);
     if (removed) {
       io.out('');
       io.out(renderRemoved(removed));

package/src/gate/changed.mjs

@@ -5,6 +5,7 @@ import { loadClaims, defaultClaimsPath, ClaimsError } from '../claims/load.mjs';
 import { readSpecDoc } from '../evidence/writer.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
+import { defenderSelection } from '../probe/attribution.mjs';
 import { IS_PY_TEST } from '../probe/pyimports.mjs';
 import { globToRegExp } from '../util/glob.mjs';
 
@@ -228,7 +229,10 @@ export function computeChangedGate({ projectDir, ref, includeDirty = false, excl
   const defenderFiles = new Map(); // test file → claimIds
   for (const c of claims.claims) {
     for (const f of c.faults) faultFiles.set(f.file, [...new Set([...(faultFiles.get(f.file) ?? []), c.id])]);
-    const defenders = c.defendedBy?.length ? resolveDefenders(projectDir, c.defendedBy) : [...new Set(c.faults.flatMap((f) => discoverDefenders(projectDir, f.file)))];
+    const defenders = [...new Set(c.faults.flatMap((f) => {
+      const { requested } = defenderSelection(c, f);
+      return requested.length ? resolveDefenders(projectDir, requested) : discoverDefenders(projectDir, f.file);
+    }))];
     for (const d of defenders) defenderFiles.set(d, [...new Set([...(defenderFiles.get(d) ?? []), c.id])]);
   }
 

package/src/init/init.mjs

@@ -56,6 +56,12 @@ Before writing or changing tests, run \`testguard status --json [dir]\` and foll
 The full operating loop and the verdict table are in \`.claude/skills/testguard/SKILL.md\`.
 Never make a fault die by editing \`testguard.claims.json\`; write the test. Claim edits are recorded in the evidence.
 
+Once per AI session, identify the exact CLI used (project-local first, then repository-root, then PATH) and read its \`--version\`.
+If network policy permits, check \`npm view testguard-cli dist-tags.latest --json --fetch-retries=0 --fetch-timeout=5000\` once; this is optional AI advice, not a CLI or hook network call.
+Compare stable versions numerically by SemVer; do not downgrade or replace a prerelease/development checkout. If a newer stable version exists, suggest it and ask before updating, respecting pins and the original package manager.
+Never install automatically or alter lockfiles/CI pins without approval. On an unavailable check, continue without claiming up-to-date; keep advice separate from evidence, verdicts and exit codes. Do not repeat a declined suggestion this session.
+Existing copied skills and sections are preserved by ordinary init; review and merge template changes manually, or use \`init --force\` only with approval to overwrite the skill.
+
 ${lines.join('\n')}
 ${AGENTS_END}`;
 }

package/src/init/templates/SKILL.md

@@ -9,6 +9,49 @@ TestGuard injects the faults a project's claims forbid and reports every one
 the tests fail to detect. It is a **claim verifier**, not a test generator.
 You operate it through one loop and one source of truth.
 
+## Update advice (once per session, never an automatic install)
+
+Before the operating loop, identify the CLI you will actually run: prefer the
+project's installed `node_modules/.bin/testguard`, then the repository-root
+install for a nested project, then `testguard` on PATH. Run that exact CLI with
+`--version`, and use the same executable for verification. Do not use `npx` to
+discover a version: it can fetch or install a different tool. When developing
+TestGuard itself, use `node cli/testguard.mjs`; do not replace a source checkout
+with a published version to make validation pass.
+
+If the user's network policy permits registry access, make one bounded,
+read-only check per session (not per command or project):
+
+```bash
+npm view testguard-cli dist-tags.latest --json --fetch-retries=0 --fetch-timeout=5000
+```
+
+Compare valid stable versions by numeric SemVer major, minor, then patch, not
+lexicographically and not merely for inequality. Do not recommend a downgrade
+or replacing a prerelease/development checkout. If the registry result is
+missing, malformed, unavailable, or network access is prohibited, continue the
+operating loop without claiming the installation is up to date. No retries or
+repeated prompts after the user declines within this session.
+
+For a newer stable version, say: "Using TestGuard X from <resolved executable>;
+Y is available. Would you like to update?" Respect project pins, compatibility,
+company policy and the original package manager; a registry's `latest` tag is
+not proof that an upgrade is safe. Never install automatically, modify a
+lockfile or CI pin, or switch between local and global installs without approval.
+After an approved update, verify the same executable's version again.
+
+Keep this advice in the AI conversation, separate from CLI JSON, evidence,
+verdicts and exit codes. The CLI and session-start hook remain offline; the AI
+performs this optional check, not TestGuard. Instructions cannot guarantee that
+every AI checks for updates.
+
+Package upgrades do not refresh an existing copied skill. Preserve customized
+instructions: compare this file with the upgraded package's
+`src/init/templates/SKILL.md` and merge approved changes. Use `testguard init
+--force` only with explicit permission to replace the whole skill; review the
+diff afterward. An ordinary `init` preserves existing skills and managed
+sections already listing this project.
+
 ## The one source of truth
 
 ```bash

package/src/probe/attribution.mjs

@@ -109,11 +109,20 @@ export function subjectOf(fault, sha256) {
  * The cost of re-measuring is a run; the cost of the other direction is a
  * verdict nobody measured.
  */
+/** Select declarations without resolving globs or running discovery. */
+export function defenderSelection(claim, fault) {
+  if (Object.hasOwn(fault, 'defendedBy')) return { requested: [...fault.defendedBy], selectionSource: 'fault' };
+  if (claim.defendedBy?.length) return { requested: [...claim.defendedBy], selectionSource: 'claim' };
+  return { requested: [], selectionSource: 'discovery' };
+}
+
 export function isReusable(prior, current) {
   if (!prior || !prior.subject?.contentHash) return false;
   // A record that exists because the probe threw is a statement about the run,
   // not about the code. Reusing it would make one disturbed run permanent.
   if (prior.detail?.reason === 'probe-error') return false;
+  const origin = prior.defenders.selectionSource ?? (prior.defenders.requested.length ? 'claim' : 'discovery');
+  if (current.selectionSource && origin !== current.selectionSource) return false;
   const same = (x, y) => JSON.stringify(x) === JSON.stringify(y);
   return prior.inputs.targetHash === current.inputs.targetHash
     && same(prior.inputs.defenderHashes, current.inputs.defenderHashes)

package/src/probe/cost.mjs

@@ -12,7 +12,7 @@
  * already recorded. Nothing re-measures, nothing spawns, nothing guesses: a
  * cost report costs the price of reading one JSON file.
  *
- * ATTRIBUTION, HONESTLY. Runs execute a claim's whole defender set together,
+ * ATTRIBUTION, HONESTLY. Runs execute a fault's selected defender set together,
  * so the runner never says how much of a run belonged to which file. Per-file
  * `ms` is therefore the time of every run that *included* that file: an upper
  * bound on what removing it could save, and, when a claim names several
@@ -70,15 +70,16 @@ export function defenderCosts(records) {
   for (const r of records) {
     const c = recordCost(r);
     for (const file of r.defenders?.resolved ?? []) {
-      const e = by.get(file) ?? { file, ms: 0, runs: 0, claims: new Set() };
+      const e = by.get(file) ?? { file, ms: 0, runs: 0, claims: new Set(), faults: new Set() };
       e.ms += c.ms;
       e.runs += c.runs;
       e.claims.add(r.claim.id);
+      e.faults.add(`${r.claim.id}/${r.subject.id}`);
       by.set(file, e);
     }
   }
   return [...by.values()]
-    .map((e) => ({ ...e, claims: [...e.claims].sort() }))
+    .map((e) => ({ ...e, claims: [...e.claims].sort(), faults: [...e.faults].sort() }))
     .sort((a, b) => b.ms - a.ms || a.file.localeCompare(b.file));
 }
 
@@ -86,7 +87,7 @@ export function defenderCosts(records) {
  * The whole cost model for one evidence document.
  *
  * `sharedDefenders` is the actionable part: a file named by more than one
- * claim, whose cost is multiplied by every claim that names it. Splitting the
+ * fault identity, including siblings within one claim. Splitting the
  * behaviour it defends into a unit test that runs in milliseconds is what
  * turns a twenty-four-minute gate into a one-minute one, and until a report
  * names the file nobody knows which test to split.
@@ -100,8 +101,10 @@ export function costReport(records) {
     reusedRecords: records.filter((r) => r.reusedFrom).length,
     records: records.length,
     claims,
+    faults: records.map((r) => ({ claimId: r.claim.id, faultId: r.subject.id, ...recordCost(r), defenders: [...(r.defenders?.resolved ?? [])], ...(r.defenders?.selectionSource ? { selectionSource: r.defenders.selectionSource } : {}) }))
+      .sort((a, b) => b.ms - a.ms || a.claimId.localeCompare(b.claimId) || a.faultId.localeCompare(b.faultId)),
     defenders,
-    sharedDefenders: defenders.filter((d) => d.claims.length > 1),
+    sharedDefenders: defenders.filter((d) => d.faults.length > 1),
   };
 }
 
@@ -123,19 +126,24 @@ export function renderCost(report, { limit = 10 } = {}) {
     out.push(`  ${secs(c.ms).padStart(7)}  ${c.claimId.padEnd(34)} ${c.faults} fault${c.faults === 1 ? ' ' : 's'} · ${c.runs} runs${c.reused ? ` · ${c.reused} reused` : ''}`);
   }
   if (report.claims.length > limit) out.push(`  … ${report.claims.length - limit} more`);
+  if (report.faults?.length) {
+    out.push('', 'most expensive faults');
+    for (const f of report.faults.slice(0, limit)) out.push(`  ${secs(f.ms).padStart(7)}  ${f.claimId}/${f.faultId} · ${f.runs} runs${f.selectionSource ? ` · ${f.selectionSource}` : ''} · ${f.defenders.join(', ') || 'no defenders'}`);
+    if (report.faults.length > limit) out.push(`  … ${report.faults.length - limit} more`);
+  }
   out.push('');
   out.push('defender files, by the time of the runs that included them');
-  out.push('  (a claim runs its whole defender set at once, so these overlap and do not sum to the total)');
+  out.push('  (a fault runs its selected defender set at once, so these overlap and do not sum to the total)');
   for (const d of report.defenders.slice(0, limit)) {
     out.push(`  ${secs(d.ms).padStart(7)}  ${d.file.padEnd(44)} ${d.claims.length} claim${d.claims.length === 1 ? '' : 's'}`);
   }
   if (report.defenders.length > limit) out.push(`  … ${report.defenders.length - limit} more`);
   if (report.sharedDefenders.length) {
     out.push('');
-    out.push('shared defenders — each claim pays the file\'s full cost again');
+    out.push('shared defenders — each fault selects the file; durations include recorded baseline sharing');
     for (const d of report.sharedDefenders.slice(0, limit)) {
       out.push(`  ${secs(d.ms).padStart(7)}  ${d.file}`);
-      out.push(`           named by ${d.claims.join(', ')}`);
+      out.push(`           named by ${d.faults.join(', ')}`);
     }
     out.push('');
     out.push('  To make a probe cheaper, split the behaviour a shared defender proves into a');

package/src/probe/probe.mjs

@@ -13,7 +13,7 @@ import { selectRunner, discoverRunnerManifest, RUNNERS, OWNED_RUNNERS, partition
 import { classify, shouldStopEarly } from './classify.mjs';
 import { blastRadius, rank } from './rank.mjs';
 import { classifyIndependence } from './independence.mjs';
-import { escalationStart, foldEscalationRun, escalationResult, flakeRate, killersFromRuns, subjectOf, isReusable } from './attribution.mjs';
+import { escalationStart, foldEscalationRun, escalationResult, flakeRate, killersFromRuns, subjectOf, isReusable, defenderSelection } from './attribution.mjs';
 import { hashFile, sha256 } from '../util/hash.mjs';
 import { fingerprint } from '../../spec/lib/fingerprint.mjs';
 import { persistenceSignalsFor } from '../supply/persistence.mjs';
@@ -154,11 +154,14 @@ export async function probe({
         }
       }
       for (const claim of scopedClaims) {
-        const discovered = claim.defendedBy?.length ? null : claim.faults.map((fault) => discoverDefendersDetailed(projectDir, fault.file, configuredFiles));
-        const declared = claim.defendedBy?.length ? resolveDefenders(projectDir, claim.defendedBy) : discovered.flatMap((detail) => detail.canDetect);
-        for (const d of declared) watched.add(relative(root, join(projectDir, d)));
-        for (const dependency of discovered?.flatMap((detail) => detail.dependencies) ?? []) watched.add(relative(root, join(projectDir, dependency)));
-        for (const g of claim.defendedBy ?? []) if (!g.includes('*')) watched.add(relative(root, join(projectDir, g)));
+        for (const fault of claim.faults) {
+          const { requested } = defenderSelection(claim, fault);
+          const discovered = requested.length ? null : discoverDefendersDetailed(projectDir, fault.file, configuredFiles);
+          const declared = requested.length ? resolveDefenders(projectDir, requested) : discovered.canDetect;
+          for (const d of declared) watched.add(relative(root, join(projectDir, d)));
+          for (const dependency of discovered?.dependencies ?? []) watched.add(relative(root, join(projectDir, dependency)));
+          for (const g of requested) if (!g.includes('*')) watched.add(relative(root, join(projectDir, g)));
+        }
       }
       for (const config of [
         'package.json', 'pnpm-workspace.yaml', 'pnpm-workspace.yml', 'lerna.json', 'nx.json', 'turbo.json', 'rush.json', 'workspace.json',
@@ -315,20 +318,21 @@ export async function probe({
 
     for (const claim of scopedClaims) {
       commandBudget?.assertOpen();
-      const declared = claim.defendedBy?.length ? resolveDefenders(iso.projectDir, claim.defendedBy) : null;
-      if (declared && !commandTemplate) {
-        const excluded = declared.filter((file) => !ownerByFile.has(file));
-        for (const file of excluded) {
-          const expectedOwner = owned.find((candidate) => candidate.owns?.(iso.projectDir, file));
-          const check = expectedOwner && ownedChecked.get(expectedOwner);
-          if (expectedOwner && check && !check.ok) {
-            throw new PreconditionError(`${file} is a ${expectedOwner.name} test (${expectedOwner.name === 'python' ? 'it is a .py file' : `it lives under ${expectedOwner.name}'s testDir`}) but ${expectedOwner.name} is not resolvable for the ${mode === 'worktree' ? 'scratch worktree' : 'project'} (${check.message}).`);
-          }
-        }
-        if (excluded.length) throw new PreconditionError(`${claim.id}: defendedBy resolves to ${excluded.join(', ')}, but the configured runners do not collect ${excluded.length === 1 ? 'that file' : 'those files'}`);
-      }
       for (const fault of claim.faults) {
         commandBudget?.assertOpen();
+        const { requested } = defenderSelection(claim, fault);
+        const declared = requested.length ? resolveDefenders(iso.projectDir, requested) : null;
+        if (declared && !commandTemplate) {
+          const excluded = declared.filter((file) => !ownerByFile.has(file));
+          for (const file of excluded) {
+            const expectedOwner = owned.find((candidate) => candidate.owns?.(iso.projectDir, file));
+            const check = expectedOwner && ownedChecked.get(expectedOwner);
+            if (expectedOwner && check && !check.ok) {
+              throw new PreconditionError(`${file} is a ${expectedOwner.name} test (${expectedOwner.name === 'python' ? 'it is a .py file' : `it lives under ${expectedOwner.name}'s testDir`}) but ${expectedOwner.name} is not resolvable for the ${mode === 'worktree' ? 'scratch worktree' : 'project'} (${check.message}).`);
+            }
+          }
+          if (excluded.length) throw new PreconditionError(`${claim.id}/${fault.id}: defendedBy resolves to ${excluded.join(', ')}, but the configured runners do not collect ${excluded.length === 1 ? 'that file' : 'those files'}`);
+        }
         // Mock-awareness: a discovered file that mocks the target is not a
         // defender; a declared one that mocks it stays (the author named it)
         // but is listed, because a declared defender that mocks the subject
@@ -413,7 +417,7 @@ export function errorRecord({ claim, fault, defenders, discovered, byRunner, moc
     subject: subjectOf(fault, sha256),
     verdict: 'unverifiable',
     detail: { baselineRuns: [], probeRuns: [], reason: 'probe-error', message },
-    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
+    defenders: { ...defenderSelection(claim, fault), resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
     inputs,
   };
 }
@@ -428,7 +432,7 @@ export function discoveryIndeterminateRecord({ claim, fault, defenders, discover
     subject: subjectOf(fault, sha256),
     verdict: 'unverifiable',
     detail: { baselineRuns: [], probeRuns: [], reason: 'defender-discovery-indeterminate', message },
-    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: false, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
+    defenders: { ...defenderSelection(claim, fault), resolved: defenders, nocover: false, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
     inputs,
   };
 }
@@ -516,8 +520,8 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, is
   const subject = subjectOf(fault, sha256);
 
   // Same source, same defenders, same N, same fault: the verdict cannot have changed.
-  if (isReusable(prior, { inputs, requested: claim.defendedBy ?? [], resolved: defenders, contentHash: subject.contentHash })) {
-    return { ...prior, reusedFrom: prior.reusedFrom ?? priorRunId };
+  if (isReusable(prior, { inputs, ...defenderSelection(claim, fault), resolved: defenders, contentHash: subject.contentHash })) {
+    return { ...prior, defenders: { ...prior.defenders, ...defenderSelection(claim, fault) }, reusedFrom: prior.reusedFrom ?? priorRunId };
   }
 
   const detail = { baselineRuns: [], probeRuns: [] };
@@ -655,7 +659,7 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, is
     subject,
     verdict,
     detail,
-    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(allSignals.length ? { signals: allSignals } : {}) },
+    defenders: { ...defenderSelection(claim, fault), resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(allSignals.length ? { signals: allSignals } : {}) },
     inputs,
     rank: rank({ severity: claim.severity, sourceKind: claim.source.kind, blast, independence: detail.independence?.class }),
   };

package/src/status/status.mjs

@@ -6,6 +6,7 @@ import { gate } from '../baseline/baseline.mjs';
 import { hashFile, sha256 } from '../util/hash.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
+import { defenderSelection } from '../probe/attribution.mjs';
 import { coAuthorshipWarning, sortForReport } from '../render.mjs';
 import { computeChangedGate, defaultIgnorePath } from '../gate/changed.mjs';
 import { headSha, isAncestor } from '../git.mjs';
@@ -171,7 +172,12 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     }
     const target = join(projectDir, cur.fault.file);
     if (existsSync(target) && hashFile(target) !== r.inputs.targetHash) doc.stale.push(`${cur.fault.file} changed since ${key} was probed`);
-    const defenders = cur.claim.defendedBy?.length ? resolveDefenders(projectDir, cur.claim.defendedBy) : discoverDefenders(projectDir, cur.fault.file);
+    const selection = defenderSelection(cur.claim, cur.fault);
+    const defenders = selection.requested.length ? resolveDefenders(projectDir, selection.requested) : discoverDefenders(projectDir, cur.fault.file);
+    const priorOrigin = r.defenders.selectionSource ?? (r.defenders.requested.length ? 'claim' : 'discovery');
+    if (priorOrigin !== selection.selectionSource || JSON.stringify(r.defenders.requested) !== JSON.stringify(selection.requested) || JSON.stringify([...r.defenders.resolved].sort()) !== JSON.stringify([...defenders].sort())) {
+      doc.stale.push(`defender selection for ${key} changed since it was probed`);
+    }
     for (const d of defenders) {
       const h = r.inputs.defenderHashes[d];
       if (!h) doc.stale.push(`${d} now defends ${key} but was not probed`);
@@ -224,7 +230,8 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   if (top) {
     doc.state = 'unproven';
     const cur = faultIndex.get(`${top.claimId}/${top.subjectId}`);
-    const defenders = cur.claim.defendedBy?.length ? resolveDefenders(projectDir, cur.claim.defendedBy) : discoverDefenders(projectDir, cur.fault.file);
+    const { requested } = defenderSelection(cur.claim, cur.fault);
+    const defenders = requested.length ? resolveDefenders(projectDir, requested) : discoverDefenders(projectDir, cur.fault.file);
     const where = defenders[0] ?? `a new test file that imports ${cur.fault.file}`;
     const whyByVerdict = {
       survived: `${top.claimId}/${top.subjectId} (${top.severity}) survived: "${cur.claim.statement}" can be false with the suite green.`,