testguard-cli 0.15.0 → 0.15.1

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.15.1` — 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.15.1/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
@@ -407,6 +407,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 +677,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.15.1
   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.15.1/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
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "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

@@ -36,7 +36,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 +176,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 +503,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 +569,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) {
@@ -243,6 +261,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 +334,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/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/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",
@@ -392,6 +392,7 @@
         "expired"
       ],
       "properties": {
+        "nested": { "type": "array", "items": { "$ref": "urn:claimspec:v1:common#/$defs/nestedProject" } },
         "ref": {
           "type": "string",
           "minLength": 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/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,7 +1,7 @@
-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';
@@ -49,6 +49,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
@@ -212,7 +239,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 +291,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 +307,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/templates/SKILL.md

@@ -20,7 +20,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/probe.mjs

@@ -202,7 +202,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;

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

@@ -64,6 +64,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 +91,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 });
 
@@ -281,6 +286,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) {