testguard-cli 0.15.0 → 0.16.0

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.15.0",
+  "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.
 
@@ -36,7 +57,11 @@ Rules that follow from the table:
    that failed and then passed on retry (Playwright's `flaky`) is a
    **non-green run** even when the runner exits 0, and a test the runner
    reports as timed out (`timedOut`) is a timeout, never an assertion
-   failure. Python is read the same way: an `AssertionError` and any other
+   failure. Jest-compatible timeout messages are recognized by native runner
+   error headers or structured timeout identity, not by words quoted in an
+   assertion, stack frame, or source excerpt. Structured assertion identity
+   does not hide a separate timeout in the same failed test.
+   Python is read the same way: an `AssertionError` and any other
    exception raised by the test body both count, because both are the suite
    rejecting the behaviour; a collection error — a module that will not
    import, which is what a replacement that does not parse looks like from
@@ -172,6 +197,11 @@ Rules that follow from the table:
    competing owned runners or a declared defender absent from every manifest
    are precondition failures, never heuristic routing decisions.
 
+   Static string literals are conservative dependency candidates, not proof
+   of a filesystem dependency. Missing candidates and ordinary directories
+   (including `/` in URL bases and string separators) are ignored. An existing
+   candidate file outside the project, or a candidate symlink, is rejected.
+
 14. **Barrel resolution follows symbols, not module reachability.** Automatic
    discovery may traverse a re-export chain only for the binding the test
    actually imports. Importing an unrelated symbol from a broad barrel does
@@ -494,10 +524,22 @@ Rules:
    `unclaimed-changes` and its next action is to write the claim, before any
    `unproven` finding is surfaced. The brief renders them first. The claim is
    written before more code.
-
-Exit codes: `0` every changed source file is claimed or excused (or nothing
-changed); `1` at least one uncovered file (or strict mode over an
-all-excluded change); `2` the change cannot be evaluated (unresolvable
+7. **A descendant claims file defines a separate project.** The first
+   descendant directory on a changed file's path with a valid, regular,
+   non-symlinked `testguard.claims.json` owns that subtree. Invalid or unreadable
+   markers fail evaluation; they cannot hide unclaimed files. Parent gate and
+   status report the delegation as optional `nested` entries with project and
+   file paths relative to the parent, and instruct the operator to run that
+   project's gate. Delegation is not coverage, an ignore reliance, or proof
+   that the child passed. Parent source-surface counts omit these subtrees.
+   Removing the marker restores parent evaluation. The accounting identity is
+   `changed = evaluated + excluded.length + sum(nested[].files.length)`;
+   `--strict` still fails a non-empty change with zero parent evaluation.
+
+Exit codes: `0` every changed parent-owned source file is claimed or excused
+(or nothing changed); delegated projects still require separate child gates.
+`1` at least one uncovered file (or strict mode over an
+all-excluded or all-delegated change); `2` the change cannot be evaluated (unresolvable
 reference, invalid claims or ignore file, no repository); `3` no reference.
 
 ## Anchor preflight
@@ -548,3 +590,11 @@ evidence; they simply do not turn CI red.
 A tool must never exit `0` because it had nothing to check. If the claims
 file is empty or every claim is out of scope, that is reported explicitly and
 the exit code is `2`.
+
+`probe --allow-empty` is an explicit adoption exception for a valid claims
+file containing zero claims, with no `--claim` selection. It exits `0`, says
+that verification was skipped, and writes no evidence or baseline. Its JSON
+output is the existing `no-claims` status document, without run metadata;
+it never reports a clean measurement. Missing or invalid claims still fail,
+and selected claims cannot be silently skipped. Run `gate` separately to
+enforce coverage of changed files during adoption. Integrations must opt in.

package/spec/lib/validate.mjs

@@ -28,6 +28,24 @@ const schemaFor = (kind) => {
   return v;
 };
 
+const nestedErrors = (nested = [], prefix = '/nested', occupied = []) => {
+  const errors = [];
+  const projects = new Set();
+  const files = new Set(occupied);
+  for (const [i, entry] of nested.entries()) {
+    const p = `${prefix}/${i}`;
+    if (entry.project.split('/').some((part) => !part || part === '.' || part === '..') || entry.project.includes('\\')) errors.push({ path: `${p}/project`, message: 'nested project must be a canonical descendant directory' });
+    if (projects.has(entry.project)) errors.push({ path: `${p}/project`, message: 'nested project is duplicated' });
+    projects.add(entry.project);
+    for (const file of entry.files) {
+      if (!file.startsWith(`${entry.project}/`) || file.split('/').some((part) => !part || part === '.' || part === '..') || file.includes('\\')) errors.push({ path: `${p}/files`, message: 'nested file must remain beneath its canonical project directory' });
+      if (files.has(file)) errors.push({ path: `${p}/files`, message: 'nested file is counted in more than one bucket' });
+      files.add(file);
+    }
+  }
+  return errors;
+};
+
 // Rules JSON Schema cannot express. Each returns an array of {path, message}.
 const semantic = {
   claims(doc) {
@@ -128,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` });
@@ -243,6 +270,11 @@ const semantic = {
 
   status(doc) {
     const errors = [];
+    if (doc.changes?.nested) {
+      errors.push(...nestedErrors(doc.changes.nested, '/changes/nested', doc.changes.uncovered.map((file) => file.file)));
+      const nestedCount = doc.changes.nested.reduce((count, entry) => count + entry.files.length, 0);
+      if (doc.changes.changed !== doc.changes.evaluated + doc.changes.excluded + nestedCount) errors.push({ path: '/changes/changed', message: 'changed must account for evaluated, excluded, and nested files' });
+    }
     if (['write-test', 'review-fault-change', 'repair-fault'].includes(doc.next.action) && !doc.next.target) errors.push({ path: '/next/target', message: `${doc.next.action} requires a target` });
     if (doc.next.action === 'claim' && !doc.next.file) errors.push({ path: '/next/file', message: 'claim requires the file the claim is about' });
     if (doc.state === 'no-claims' && doc.counts.claims !== 0) errors.push({ path: '/counts/claims', message: 'no-claims with a non-zero claim count' });
@@ -311,8 +343,10 @@ const semantic = {
 
   gate(doc) {
     const errors = [];
+    const nestedCount = (doc.nested ?? []).reduce((count, entry) => count + entry.files.length, 0);
+    errors.push(...nestedErrors(doc.nested, '/nested', [...doc.covered, ...doc.uncovered, ...doc.excluded].map((entry) => entry.file)));
     if (doc.evaluated !== doc.covered.length + doc.uncovered.length) errors.push({ path: '/evaluated', message: `evaluated (${doc.evaluated}) must equal covered (${doc.covered.length}) + uncovered (${doc.uncovered.length})` });
-    if (doc.changed !== doc.evaluated + doc.excluded.length) errors.push({ path: '/changed', message: `changed (${doc.changed}) must equal evaluated (${doc.evaluated}) + excluded (${doc.excluded.length})` });
+    if (doc.changed !== doc.evaluated + doc.excluded.length + nestedCount) errors.push({ path: '/changed', message: `changed (${doc.changed}) must equal evaluated (${doc.evaluated}) + excluded (${doc.excluded.length}) + nested (${nestedCount})` });
     if (doc.uncovered.length > 0 && doc.exitCode !== 1) errors.push({ path: '/exitCode', message: 'an uncovered changed file must exit 1; the gate never passes over unclaimed code' });
     if (doc.uncovered.length === 0 && doc.exitCode === 1 && !(doc.strict && doc.changed > 0 && doc.evaluated === 0)) errors.push({ path: '/exitCode', message: 'exit 1 without uncovered files is only valid under --strict when a non-empty change evaluated nothing' });
     doc.covered.forEach((c, i) => {

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/common.schema.json

@@ -4,6 +4,16 @@
   "title": "claimspec v1 \u2014 shared definitions",
   "description": "Definitions shared by every Guard-spec format. Referenced as urn:claimspec:v1:common#/$defs/<name>.",
   "$defs": {
+    "nestedProject": {
+      "description": "Changed files delegated to a separately validated descendant TestGuard project. This is not coverage or evidence; run that project's gate separately.",
+      "type": "object",
+      "required": ["project", "files"],
+      "properties": {
+        "project": { "$ref": "#/$defs/repoPath" },
+        "files": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/repoPath" } }
+      },
+      "additionalProperties": false
+    },
     "sha256": {
       "type": "string",
       "pattern": "^[a-f0-9]{64}$"

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/gate.schema.json

@@ -17,6 +17,7 @@
     "strict": { "description": "True when a non-empty change with zero evaluated files fails instead of passing with a note.", "type": "boolean" },
     "changed": { "description": "Files changed inside the project directory, deletions excluded.", "type": "integer", "minimum": 0 },
     "evaluated": { "description": "covered + uncovered: the changed files that are source and not excluded.", "type": "integer", "minimum": 0 },
+    "nested": { "description": "Optional descendant-project delegations; absence means none. These files are neither covered nor evaluated by the parent.", "type": "array", "items": { "$ref": "urn:claimspec:v1:common#/$defs/nestedProject" } },
     "excluded": {
       "type": "array",
       "items": {

package/spec/schemas/status.schema.json

@@ -26,7 +26,7 @@
       "$ref": "urn:claimspec:v1:common#/$defs/isoDateTime"
     },
     "state": {
-      "description": "no-claims: no claims file. unclaimed-changes: the change measured against a reference touches source files that carry no claim and no excusing ignore entry (only computed when a reference is known; it precedes every evidence state because the claim is written before more code). invalid-anchors: one or more exact fault anchors are missing or ambiguous, so probing would be unable to apply them. unprobed: claims but no confirmed evidence. evidence-stale: evidence exists but a claim, fault, target or defender changed since. provisional-only: only sub-N evidence exists. unproven: current evidence has findings not covered by the baseline. clean: every finding is killed or baselined.",
+      "description": "no-claims: no claims file or a valid empty claims file. unclaimed-changes: the change measured against a reference touches source files that carry no claim and no excusing ignore entry (only computed when a reference is known; it precedes every evidence state because the claim is written before more code). invalid-anchors: one or more exact fault anchors are missing or ambiguous, so probing would be unable to apply them. unprobed: claims but no confirmed evidence. evidence-stale: evidence exists but a claim, fault, target or defender changed since. provisional-only: only sub-N evidence exists. unproven: current evidence has findings not covered by the baseline. clean: every finding is killed or baselined.",
       "enum": [
         "no-claims",
         "unclaimed-changes",
@@ -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": {
@@ -392,6 +410,7 @@
         "expired"
       ],
       "properties": {
+        "nested": { "type": "array", "items": { "$ref": "urn:claimspec:v1:common#/$defs/nestedProject" } },
         "ref": {
           "type": "string",
           "minLength": 1,
@@ -482,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/cli.mjs

@@ -75,6 +75,7 @@ probe
   --in-place           mutate the working tree instead of a scratch worktree
   --no-escalate        do not re-run survivors against the whole suite
   --no-reuse           re-probe claims whose inputs have not changed
+  --allow-empty        adoption only: skip a valid empty claims file; writes no evidence; run gate separately
   --quiet              suppress the per-fault stream and ranked block; print only the summary and evidence path
   --json               the status document plus this run's result (records, newSinceBaseline, exitCode)
 
@@ -134,6 +135,27 @@ exit codes: 0 nothing new to prove · 1 unproven claims (or claim drift, or uncl
 
 const COMMANDS = { mcp: mcpCommand, replay: replayCommand, probe: probeCommand, claims: claimsCommand, baseline: baselineCommand, brief: briefCommand, scaffold: scaffoldCommand, status: statusCommand, init: initCommand, gate: gateCommand, admit: admitCommand, sweep: sweepCommand, concerns: concernsCommand };
 
+/** Derive command help from the same option descriptions as the overview. */
+export function commandUsage(command) {
+  const lines = USAGE.split('\n');
+  const overview = lines.find((line) => line.startsWith(`  testguard ${command} `)) ?? `  testguard ${command}`;
+  const sections = [];
+  let selected = false;
+  for (const line of lines) {
+    const heading = /^([a-z]+)(?:\s|$)/.exec(line)?.[1];
+    if (heading && Object.hasOwn(COMMANDS, heading)) selected = heading === command;
+    else if (line.startsWith('every command ') || line.startsWith('exit codes:')) selected = false;
+    if (selected) sections.push(line);
+  }
+  if (command === 'concerns') sections.push('concerns   --concerns <path>  read a custom concerns file; --json prints the validated inventory');
+  const examples = {
+    probe: 'probe . --confirm 3', gate: 'gate . --changed origin/main',
+    scaffold: 'scaffold src/example.mjs --json', replay: 'replay . --since HEAD~10..HEAD --max 3',
+    admit: 'admit test/example.test.mjs --claim EXAMPLE-001', sweep: 'sweep . --changed origin/main --cap 10',
+  };
+  return `${lines[0]}\n\n${overview}\n\n${sections.join('\n').trim()}\n\nCommon: --json, --help, --version\nExample: testguard ${examples[command] ?? `${command}${command === 'mcp' ? '' : ' .'}`}\n`;
+}
+
 export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') }) {
   let parsed;
   try {
@@ -180,6 +202,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         'in-place': { type: 'boolean', default: false },
         'no-escalate': { type: 'boolean', default: false },
         'no-reuse': { type: 'boolean', default: false },
+        'allow-empty': { type: 'boolean', default: false },
         quiet: { type: 'boolean', default: false },
         json: { type: 'boolean', default: false },
         text: { type: 'boolean', default: false },
@@ -202,9 +225,9 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     return 0;
   }
   const [command, dirArg] = positionals;
-  if (values.help || !command) {
-    io.out(USAGE);
-    return command ? 0 : 3;
+  if (!command) {
+    io.out(USAGE + "\nRun 'testguard <command> --help' for that command's options.");
+    return values.help ? 0 : 3;
   }
   const handler = COMMANDS[command];
   if (!handler) {
@@ -212,6 +235,10 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     io.err(USAGE);
     return 3;
   }
+  if (values.help) {
+    io.out(commandUsage(command));
+    return 0;
+  }
   if (![...RUNNER_NAMES, 'auto'].includes(values.runner)) {
     io.err(`--runner must be one of ${RUNNER_NAMES.join(', ')} or auto`);
     return 3;

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/commands/probe.mjs

@@ -57,6 +57,19 @@ export async function probeCommand({ projectDir, values, version }, io) {
   const stageOut = stageReporter(progress, (s) => progressTo.write(s));
   const claims = loadClaims(values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir));
   if (claims.claims.length === 0) {
+    if (values['allow-empty'] && values.claim === undefined) {
+      io.err('claims file declares no claims; verification skipped (--allow-empty); run gate to check changed-file coverage');
+      if (values.json) {
+        const doc = computeStatus({ projectDir, toolVersion: version, paths: {
+          claims: values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir),
+          evidence: evidencePath(projectDir), provisional: provisionalEvidencePath(projectDir), baseline: baselinePath(projectDir),
+        } });
+        const result = validate('status', doc);
+        if (!result.ok) throw new Error(`empty probe JSON document does not conform: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
+        io.out(JSON.stringify(doc, null, 2));
+      }
+      return 0;
+    }
     io.err('claims file declares no claims; nothing to verify');
     return 2;
   }

package/src/gate/changed.mjs

@@ -1,10 +1,11 @@
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, realpathSync, lstatSync } from 'node:fs';
 import { extname, join, relative, resolve, dirname } from 'node:path';
 import { git, repoRoot, headSha, GitError } from '../git.mjs';
-import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
+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';
 
@@ -49,6 +50,33 @@ export const isDefaultExcluded = (file) => DEFAULT_EXCLUDE_RES.some((re) => re.t
 
 export const defaultIgnorePath = (projectDir) => join(projectDir, 'testguard.ignore.json');
 
+/** Cache validated descendant boundaries for one measurement, never across runs. */
+export function nestedProjectResolver(projectDir) {
+  const root = realpathSync(resolve(projectDir));
+  const markers = new Map();
+  return (file) => {
+    const parts = file.split('/').slice(0, -1);
+    for (let i = 1; i <= parts.length; i++) {
+      const project = parts.slice(0, i).join('/');
+      if (!markers.has(project)) {
+        const marker = join(root, project, 'testguard.claims.json');
+        let stat;
+        try { stat = lstatSync(marker); }
+        catch (error) {
+          if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw new ClaimsError(`cannot inspect nested claims file ${marker}: ${error.message}`);
+        }
+        if (stat) {
+          if (!stat.isFile() || stat.isSymbolicLink() || realpathSync(marker) !== marker) throw new ClaimsError(`nested claims file must be a regular file without symlink traversal: ${marker}`);
+          loadClaims(marker);
+        }
+        markers.set(project, Boolean(stat));
+      }
+      if (markers.get(project)) return project;
+    }
+    return null;
+  };
+}
+
 /**
  * The reference the change is measured against. Environment overrides and CI
  * bases are handled here; local Git discovery is separate because it needs a
@@ -201,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])]);
   }
 
@@ -212,7 +243,15 @@ export function computeChangedGate({ projectDir, ref, includeDirty = false, excl
   const excluded = [];
   const covered = [];
   const uncovered = [];
+  const nested = new Map();
+  const ownerOf = nestedProjectResolver(projectDir);
   for (const file of changed) {
+    const owner = ownerOf(file);
+    if (owner) {
+      if (!nested.has(owner)) nested.set(owner, []);
+      nested.get(owner).push(file);
+      continue;
+    }
     if (!SOURCE_EXT.has(extname(file))) { excluded.push({ file, by: 'non-source' }); continue; }
     const ux = userExcludes.find((x) => x.re.test(file));
     if (ux) { excluded.push({ file, by: `exclude:${ux.glob}` }); continue; }
@@ -256,6 +295,7 @@ export function computeChangedGate({ projectDir, ref, includeDirty = false, excl
     changed: changed.length,
     evaluated,
     excluded,
+    ...(nested.size ? { nested: [...nested].map(([project, files]) => ({ project, files })) } : {}),
     covered,
     uncovered,
     reliedOn,
@@ -271,7 +311,8 @@ export function renderGate(doc) {
   for (const u of doc.uncovered) lines.push(`UNCLAIMED  ${u.file}  (${u.kind}${u.nearestClaimId ? `, nearest claim ${u.nearestClaimId}` : ''})\n           → ${u.suggestion}`);
   for (const r of doc.reliedOn) lines.push(`excused    ${r.files.join(', ')}  by ignore "${r.pattern}": ${r.reason}${r.expires ? ` (expires ${r.expires})` : ''}`);
   for (const e of doc.expired) lines.push(`EXPIRED    ignore "${e.pattern}" (expired ${e.expires}) no longer excuses ${e.files.join(', ')}`);
-  if (doc.changed > 0 && doc.evaluated === 0) lines.push(`note: every changed file was excluded (${[...new Set(doc.excluded.map((x) => x.by))].join(', ')}); 0 evaluated${doc.strict ? ' — --strict makes this a failure' : ''}`);
+  for (const n of doc.nested ?? []) lines.push(`delegated  ${n.files.length} file(s) belong to the TestGuard project at ${n.project}/; run testguard gate ${n.project} --changed ${doc.ref}${doc.includeDirty ? ' --include-dirty' : ''}; child coverage has not been evaluated here`);
+  if (doc.changed > 0 && doc.evaluated === 0) lines.push(`note: every changed file was excluded or delegated (${[...new Set(doc.excluded.map((x) => x.by))].join(', ')}); 0 evaluated${doc.strict ? ' — --strict makes this a failure' : ''}`);
   if (doc.changed === 0) lines.push(`no changes since ${doc.ref}; nothing to claim`);
   if (doc.uncovered.length === 0 && doc.exitCode === 0 && doc.evaluated > 0) lines.push('every changed source file carries a claim or an excusing ignore entry');
   return lines.join('\n');

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
@@ -20,7 +63,7 @@ which files exist. `state` is one of:
 
 | state | meaning | you do |
 |---|---|---|
-| `no-claims` | no `testguard.claims.json` | `testguard scaffold <file>` for a file with guards; replace every `TODO:` statement with what the code guarantees; keep or drop each proposal; move the claims into `testguard.claims.json` |
+| `no-claims` | missing or empty `testguard.claims.json` | `testguard scaffold <file>` for a file with guards; replace every `TODO:` statement with the intended guarantee from a spec, ticket, or past bug; keep or drop each proposal; move the claims into `testguard.claims.json` |
 | `unclaimed-changes` | files you changed carry no claim (when a reference is explicit, supplied by CI, or safely inferred from local Git's remote default/upstream metadata) | `next.file` names the first; `testguard scaffold <file>` and state the claim, or add a `testguard.ignore.json` path entry with a reason a reviewer will accept. **Before** writing more code. |
 | `invalid-anchors` | an exact fault anchor moved or became ambiguous | run `testguard claims --check-anchors`; repair `next.target` in the claims file without changing what the fault means, then re-probe. Never guess or auto-fix an anchor. |
 | `unprobed` | claims never probed | `testguard probe` |

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',
@@ -202,7 +205,7 @@ export async function probe({
       commandBudget?.assertOpen();
       if (sel.error) {
         throw new PreconditionError(`test runner is not resolvable in the ${mode === 'worktree' ? 'scratch worktree' : 'project'} (${sel.error}). ` +
-          (mode === 'worktree' ? 'No usable node_modules was linked: pass --node-modules <path>, or run with --in-place.' : 'Install dependencies first.'));
+          (mode === 'worktree' ? 'If dependencies are missing, pass --node-modules <path>, or run with --in-place. Otherwise fix the discovery error above.' : 'If dependencies are missing, install them first. Otherwise fix the discovery error above.'));
       }
       runner = sel.runner;
       runnerVersion = sel.version;
@@ -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/probe/runners/discovery.mjs

@@ -275,7 +275,6 @@ const inside = (root, path) => {
 const relativeConfigPath = (root, path) => relative(root, path).split(sep).join('/');
 
 const existingConfigCandidate = (root, path) => {
-  if (!inside(root, path)) throw new DiscoveryError(`discovery config dependency resolves outside the project: ${path}`);
   let stat;
   try {
     stat = lstatSync(path);
@@ -285,6 +284,7 @@ const existingConfigCandidate = (root, path) => {
   }
   if (stat.isSymbolicLink()) throw new DiscoveryError(`discovery config dependency is not readable: symbolic links are not allowed`);
   if (!stat.isFile()) return null;
+  if (!inside(root, path)) throw new DiscoveryError(`discovery config dependency resolves outside the project: ${path}`);
   return path;
 };
 
@@ -305,7 +305,9 @@ const resolveConfigReference = (root, fromPath, rawReference) => {
 
   const resolved = new Set();
   for (const base of bases) {
-    if (!inside(root, base)) throw new DiscoveryError(`discovery config dependency resolves outside the project: ${rawReference}`);
+    // Strings in executable configs also describe URLs and separators. Only
+    // existing file candidates are dependencies; the boundary check follows
+    // that distinction, while symlinks remain refused even when dangling.
     const candidates = extname(base)
       ? [base]
       : [base, ...RESOLVABLE_CONFIG_EXTENSIONS.map((extension) => `${base}${extension}`),

package/src/probe/runners/shared.mjs

@@ -184,6 +184,21 @@ export function firstInformativeLine(message) {
   return lines.find((l) => /error|syntax|unexpected|expected .+ but found|cannot find|failed to parse|transform failed/i.test(l) && !/^●/.test(l)) ?? lines[0] ?? '';
 }
 
+function isRunnerTimeout(test) {
+  if (test.failureType === 'testTimeoutFailure') return true;
+  const details = test.failureDetails ?? [];
+  if (details.some((error) => error?.failureType === 'testTimeoutFailure')) return true;
+  return (test.failureMessages ?? []).some((message, index) => {
+    const error = details[index];
+    // Assertion text may quote a timeout header verbatim. Inspect only the
+    // error header, never stack frames, source excerpts, or expected values.
+    if (error?.name === 'AssertionError' || error?.code === 'ERR_ASSERTION' || error?.operator !== undefined) return false;
+    const header = String(message).replace(/\x1b\[[0-9;]*m/g, '').trimStart().split('\n')[0].trimEnd();
+    return /^(?:Error:\s*)?(?:thrown:\s*")?(?:Exceeded timeout of \d+(?:\.\d+)?\s*ms for a (?:test|hook)\b|(?:Test|Hook) timed out in \d+(?:\.\d+)?ms\b|test timed out after \d+(?:\.\d+)?ms\b)/i.test(header)
+      || /^(?:(?:Error|AroundHookSetupError|AroundHookTeardownError):\s*)?The (?:setup|teardown) phase of "around(?:Each|All)" hook timed out after \d+(?:\.\d+)?ms\b/.test(header);
+  });
+}
+
 export function parseReport(report, durationMs) {
   // A report that parsed as JSON but carries no `testResults` is not a suite
   // that ran zero tests — it is a report of a shape this parser does not
@@ -195,7 +210,7 @@ export function parseReport(report, durationMs) {
   const files = report.testResults ?? [];
   const loadFailed = files.some((f) => f.status === 'failed' && (f.assertionResults?.length ?? 0) === 0);
   const results = files.flatMap((f) => (f.assertionResults ?? []).map((t) => ({ ...t, id: `${f.name}::${t.fullName ?? t.title ?? ''}` }))).filter((t) => t.status === 'failed');
-  const timeouts = results.filter((t) => (t.failureMessages ?? []).some((m) => /timed out|exceeded timeout/i.test(m))).length;
+  const timeouts = results.filter(isRunnerTimeout).length;
   const failedTests = results.map((t) => t.id);
   const assertionFailures = results.length - timeouts;
   const tests = { total: report.numTotalTests ?? 0, passed: report.numPassedTests ?? 0, failed: report.numFailedTests ?? 0 };

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';
@@ -64,6 +65,7 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   if (ref) {
     const g = computeChangedGate({ projectDir, ref, includeDirty, toolVersion });
     changes = { ref: g.ref, base: g.base, includeDirty: g.includeDirty, changed: g.changed, evaluated: g.evaluated, excluded: g.excluded.length, uncovered: g.uncovered, reliedOn: g.reliedOn, expired: g.expired };
+    if (g.nested?.length) changes.nested = g.nested;
     doc.changes = changes;
     if (existsSync(defaultIgnorePath(projectDir))) doc.paths.ignore = rel(defaultIgnorePath(projectDir));
   }
@@ -90,6 +92,10 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   doc.counts.claims = claims.claims.length;
   doc.counts.faults = claims.claims.reduce((n, c) => n + c.faults.length, 0);
   doc.surface = computeClaimedSurface({ projectDir, claims });
+  if (claims.claims.length === 0 && !changes?.uncovered.length) {
+    doc.next = { action: 'scaffold', command: 'testguard scaffold <source-file>', why: 'No claims have been declared; no verification was performed. State a claim before probing.' };
+    return doc;
+  }
   const faultIndex = new Map();
   for (const c of claims.claims) for (const f of c.faults) faultIndex.set(`${c.id}/${f.id}`, { claim: c, fault: f });
 
@@ -166,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`);
@@ -219,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.`,
@@ -281,6 +293,7 @@ export function renderStatus(doc) {
     for (const u of c.uncovered) lines.push(`UNCLAIMED ${u.file} (${u.kind}) → ${u.suggestion}`);
     for (const r of c.reliedOn) lines.push(`excused   ${r.files.join(', ')} by ignore "${r.pattern}": ${r.reason}`);
     for (const e of c.expired) lines.push(`EXPIRED   ignore "${e.pattern}" no longer excuses ${e.files.join(', ')}`);
+    for (const n of c.nested ?? []) lines.push(`delegated ${n.files.length} file(s) belong to ${n.project}/; run testguard gate ${n.project} --changed ${c.ref}${c.includeDirty ? ' --include-dirty' : ''}; child coverage has not been evaluated here`);
   }
   for (const c of doc.changedFaults) lines.push(`CHANGED   ${c.claimId}/${c.subjectId} edited since it ${c.previousVerdict} (${c.file})`);
   for (const f of doc.invalidFaults ?? []) lines.push(`INVALID   ${f.claimId}/${f.subjectId} ${f.reason}: ${f.hits} hits, expected ${f.expected} (${f.file})`);

package/src/status/surface.mjs

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { extname, join } from 'node:path';
 import { git } from '../git.mjs';
-import { SOURCE_EXT, isDefaultExcluded, isTestFile } from '../gate/changed.mjs';
+import { SOURCE_EXT, isDefaultExcluded, isTestFile, nestedProjectResolver } from '../gate/changed.mjs';
 import { walk } from '../util/glob.mjs';
 
 export const HISTORY_COMMITS = 200;
@@ -24,11 +24,12 @@ function listedFiles(projectDir) {
 }
 
 function claimableModules(projectDir) {
+  const ownerOf = nestedProjectResolver(projectDir);
   return listedFiles(projectDir).filter((file) =>
     existsSync(join(projectDir, file)) &&
     SOURCE_EXT.has(extname(file)) &&
     !isTestFile(file) &&
-    !isDefaultExcluded(file));
+    !isDefaultExcluded(file) && !ownerOf(file));
 }
 
 function recentChanges(projectDir, sourceModules) {