testguard-cli 0.14.2 → 0.15.1

package/CHANGELOG.md

@@ -7,6 +7,77 @@ 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`.
+
+### Changed
+
+- feat: harden discovery, replay, and command budgets (#174)
+- chore(homebrew): sha256 for v0.14.2 (#173)
+
+
+### Added
+
+- Runner-native test discovery for Vitest, Jest, and Playwright, with bounded
+  output, path validation, immutable universe manifests, exact mixed-runner
+  routing, and configuration-closure hashes (including workspace configs,
+  package helpers, setup files, and Python collection hooks) that prevent stale
+  evidence reuse.
+- Symbol-aware JavaScript/TypeScript defender discovery through named,
+  default, namespace, CommonJS, and barrel re-exports. Ambiguity and bounded
+  resolver exhaustion fail closed as `defender-discovery-indeterminate`.
+- `probe`, `sweep`, and `replay` accept `--command-budget <ms>` as a
+  cooperative measurement deadline distinct from the existing per-run
+  `--budget`. It caps asynchronous children and is checked at stage and write
+  boundaries; synchronous setup may overrun but cannot publish a partial
+  result, so an unattempted suffix can never be reported as clean.
+
+### Fixed
+
+- Runner timeouts now hard-kill the original process group and descendants
+  still attributable at timeout. Diagnostics explicitly say cleanup is
+  unverified because a previously reparented daemon requires external OS or
+  container containment.
+- Generated CommonJS export mutations and unresolved symbol/configuration
+  paths fail closed instead of allowing a false `nocover` result.
+- Dirty-tree preflight now resolves the same full primary-plus-owned runner
+  universe as measurement, including custom Playwright names and imported
+  configuration helpers; discovery failure blocks rather than hiding edits.
+
 ## [0.14.2] - 2026-09-28
 
 Automated weekly release — everything merged since `v0.14.1`.
@@ -15,7 +86,6 @@ Automated weekly release — everything merged since `v0.14.1`.
 
 - chore(homebrew): sha256 for v0.14.1 (#171)
 
-
 ## [0.14.1] - 2026-09-27
 
 Automated weekly release — everything merged since `v0.14.0`.

package/README.md

@@ -127,9 +127,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.14.2` — 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.14.2/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.14.2
+- 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.14.2/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
 ```
 
@@ -694,6 +708,18 @@ talks to the network; only the job posts, and only when told to.
 - **Never optimistic.** A timeout, a load failure, a mixed N-run result, a
   flaky defender or a missing anchor is reported as unproven, never rounded
   toward green. The one pass is `killed`; everything else gates.
+- **Per-run and whole-command time are separate.** `--budget` limits each
+  runner invocation. `--command-budget` is a cooperative deadline for the
+  complete `probe`, `sweep`, or `replay` measurement: asynchronous children
+  receive only the remaining time, and stage/write boundaries re-check it.
+  Synchronous setup may overrun the nominal deadline, but once expiry is
+  observed TestGuard exits `2` and writes no new result document; a completed
+  prefix is not presented as though the unattempted suffix were clean.
+- **Configured discovery is evidence.** Vitest, Jest, and Playwright enumerate
+  their own configured files; TestGuard validates and hashes that immutable
+  universe instead of guessing with filename globs. Automatic JavaScript and
+  TypeScript discovery follows the imported symbol through barrels. Ambiguous
+  or unbounded resolution is `unverifiable`, never a flattering `nocover`.
 - **One exact-pinned runtime dependency** (`ajv`), Node ≥ 20, MIT.
 
 ### Prior art, and what was taken from where

package/package.json

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

@@ -12,7 +12,7 @@ The verdict set is closed. Only one value is a pass.
 | `killed` | Fault applied; every one of N probe runs failed with a genuine assertion failure, on a defender set that was green N/N unmodified. | no |
 | `survived` | Fault applied; every one of N probe runs passed. The claim is **unproven**. | **yes** |
 | `nocover` | No defending test exists: the declared globs resolve to nothing, or no test imports the subject. Worse than `survived` — nothing was even tried. | **yes** |
-| `unverifiable` | The claim could not be probed: the fault's anchor is missing or ambiguous, its defenders failed to load (`defenders-failed-to-load`), probing it threw (`probe-error`), or the defenders do not execute the subject at all (`subject-not-executed`). Carries a `reason`. A loud, gating verdict — a claim that cannot be probed is not "skipped", it is undefended until someone fixes the fault or the defenders. Never confused with `flaky-defender`, which requires tests that *ran*. | **yes** |
+| `unverifiable` | The claim could not be probed: the fault's anchor is missing or ambiguous, configured or symbol-level defender discovery was indeterminate (`defender-discovery-indeterminate`), its defenders failed to load (`defenders-failed-to-load`), probing it threw (`probe-error`), or the defenders do not execute the subject at all (`subject-not-executed`). Carries a `reason`. A loud, gating verdict — a claim that cannot be probed is not "skipped", it is undefended until someone fixes the fault or the defenders. Never confused with `flaky-defender`, which requires tests that *ran*. | **yes** |
 | `timeout` | Probe run exceeded its budget. Not counted as a kill; the pessimistic reading is the safe one because flakiness biases the metric optimistically. | **yes** |
 | `fault-invalid` | The replacement does not load or compile. A bad fault, not a detection. | **yes** |
 | `flaky-defender` | Defenders were not green N/N on unmodified source (`defenders-not-green`), or the N probe runs disagreed with each other (`inconsistent-probe`). Either way no verdict about the fault can be trusted; fix the defenders first. | **yes** |
@@ -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
@@ -151,7 +155,48 @@ Rules that follow from the table:
    can name the file the interpreter loaded) answers the same question more
    precisely for one language; where both are present they must agree.
 
-13. **Fault injection is one method, not the definition.** A claim declares
+13. **The configured runner defines the test universe.** For JavaScript and
+   TypeScript, defender discovery, baseline runs and escalation use the exact
+   file set returned by the resolved runner's native listing protocol. A
+   resolvable runner whose configuration cannot load, whose listing times out
+   or is malformed, or whose reported paths escape the project is a
+   precondition failure. It never falls back to built-in filename globs and
+   never becomes `nocover`. An explicitly selected runner that lists zero
+   files is also a precondition failure; `auto` may continue past a successful
+   empty listing, but must fail when every eligible runner is empty.
+   `inputs.testUniverseHash` binds the normalized file set, runner identity,
+   and hashed configuration dependencies. Those dependencies include absent
+   root candidates, nested workspace configs, Python collection hooks, and the
+   bounded static closure of local or package-imported config helpers and setup
+   files; creating or editing any of them forces remeasurement. Evidence that
+   predates this hash, or whose hash
+   changed, is readable but never reusable for a current native discovery run.
+   When several configured runners list defenders, exact manifest membership
+   assigns each file. An owned runner takes precedence over the project runner;
+   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
+   not defend every file the barrel exports. Renames, explicit exports and
+   star exports are resolved deterministically; type-only paths do not count.
+   Ambiguous origins, unsupported runtime-generated exports, graph-limit
+   exhaustion, and originless cycles are `unverifiable` with reason
+   `defender-discovery-indeterminate`, never `nocover`. A declared
+   `defendedBy` remains authoritative. `inputs.discoveryHashes` binds every
+   candidate test, intermediate barrel, and resolver-configuration file
+   consulted by automatic discovery. Negative candidates are dependencies too:
+   editing a previously unrelated test so it begins importing the target must
+   invalidate an earlier `nocover`. Absent or changed dependencies force
+   remeasurement.
+
+15. **Fault injection is one method, not the definition.** A claim declares
    what must be true; a probe declares how a tool would try to make it false,
    and `method` says which way. `fault-injection` — mutate the source, run the
    claim's defenders, confirm over N runs — is the only method specified in
@@ -184,6 +229,32 @@ Rules that follow from the table:
    The verdict set stays closed and shared. What each method may legitimately
    report is part of defining it.
 
+## Per-run and whole-command budgets are different
+
+`--budget` remains the wall-clock ceiling for one runner invocation. An
+optional `--command-budget` is a cooperative deadline for the complete
+`probe`, `sweep`, or `replay` measurement. Every asynchronous child runner and
+discovery process is given no more than the command's remaining time, and the
+deadline is checked again at stage boundaries and immediately before any
+result is written. Synchronous filesystem, Git, parsing, and cleanup work is
+not preemptible in portable Node.js and may finish after the nominal deadline;
+that overrun grants no authority to publish a result.
+
+Exhausting the whole-command budget is not a test verdict and is never a
+successful partial measurement. The command exits `2` and writes no new
+result document; any previous document remains untouched. Cleanup may finish
+after the deadline, but no record from the incomplete operation becomes
+evidence. This is deliberately stricter than a per-run timeout: publishing
+the completed prefix would let the unattempted suffix look clean.
+
+Timeout cleanup is best effort, not portable process containment. TestGuard
+hard-kills the runner's original process group and every descendant still
+attributable through the process table. A daemon that detached, reparented,
+and disappeared from that ancestry before timeout may survive, so timeout
+diagnostics state `cleanup-unverified`. Such a run remains a timeout and never
+becomes evidence of detection. Daemonizing or untrusted commands require an
+OS or container boundary that TestGuard does not claim to provide.
+
 ## Replay reports; it never gates
 
 A replayed bug is history. It escaped, by definition, which means the suite
@@ -198,7 +269,7 @@ Its verdicts mirror the probe's, for the same reasons:
 | `caught` | a remaining test failed **by assertion** on the reverted source, every run. The suite knew. |
 | `blind` | the suite stayed green on known-broken code. |
 | `nocover` | no test imports the reverted files, **and at least one test file remained to ask**. Worse than `blind`: nothing was even tried. |
-| `unverifiable` | the revert did not apply, the suite failed to load, it timed out, or removing the fix's own test left **no test file at all** (`the-fix-shipped-the-only-test-file`). Carries a `reason`. |
+| `unverifiable` | the revert did not apply, configured or symbol-level defender discovery was indeterminate (`defender-discovery-indeterminate`), the suite failed to load, it timed out, or removing the fix's own test left **no test file at all** (`the-fix-shipped-the-only-test-file`). Carries a `reason`. |
 | `flaky` | the runs disagreed. A flaky failure reads as "the suite caught it", so flakiness biases this metric **optimistically** — mixed runs are never `caught`. |
 
 Two rules that follow:
@@ -432,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
@@ -486,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/README.md

@@ -39,6 +39,13 @@ Shared definitions (verdicts, fault classes, provenance, annotations) live in
 which verdicts turn CI red, baseline and delta rules, exit codes — is in
 [`GATE-SEMANTICS.md`](GATE-SEMANTICS.md).
 
+Operational completeness is contractual too. `--budget` bounds one runner
+invocation; `--command-budget` is a cooperative deadline for a complete probe,
+sweep, or replay measurement. It caps asynchronous child processes, is checked
+at stage and write boundaries, and produces no document once observed expired.
+Synchronous setup may overrun but cannot authorize a partial result. The exact
+rule is in `GATE-SEMANTICS.md`.
+
 Schemas are JSON Schema 2020-12 and identified as `urn:claimspec:v1:<kind>`.
 
 ## Conformance

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

@@ -641,6 +641,20 @@
               "additionalProperties": {
                 "$ref": "urn:claimspec:v1:common#/$defs/sha256"
               }
+            },
+            "testUniverseHash": {
+              "description": "Canonical hash of the runner-native test universe and the configuration files that produced it. Optional for backward compatibility; current probes emit it, and evidence without it is never reusable against a configured discovery run.",
+              "$ref": "urn:claimspec:v1:common#/$defs/sha256"
+            },
+            "discoveryHashes": {
+              "description": "Content hashes of candidate tests, intermediate barrels, and resolver-configuration files consulted by automatic defender discovery. This includes negative candidates: a test edited to begin importing the target must invalidate an earlier `nocover`. Optional for backward compatibility; a changed or absent dependency forces remeasurement.",
+              "type": "object",
+              "propertyNames": {
+                "$ref": "urn:claimspec:v1:common#/$defs/repoPath"
+              },
+              "additionalProperties": {
+                "$ref": "urn:claimspec:v1:common#/$defs/sha256"
+              }
             }
           },
           "additionalProperties": false

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

@@ -44,6 +44,7 @@ probe
   --claims <path>      claims file             (default: <dir>/testguard.claims.json)
   --confirm <n>        runs per verdict        (default: 3)
   --budget <ms>        wall clock per run      (default: 120000)
+  --command-budget <ms> cooperative measurement deadline for probe, sweep, or replay. Caps async children; expiry exits 2 and writes no partial result
   --out <path>         evidence file           (default: <dir>/.testguard/evidence.json)
   --baseline <path>    baseline to gate against (default: <dir>/.testguard/baseline.json if present)
   --severity <level>   gate only at or above   (default: low)
@@ -74,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)
 
@@ -84,7 +86,7 @@ sweep      --changed <ref> (required unless --save-paths; CI bases and a safe lo
            --save-paths      sweep every file that WRITES TO STORAGE instead of the diff, and report the surface as the
                              denominator: "120 writes across 38 files, swept 12". A clean sweep over an unstated
                              denominator is a sample of unknown size, not a guarantee that saving works
-           --include-dirty  --exclude <glob>  --confirm <n>  --budget <ms>  --max <n>  --out <path>  --json
+           --include-dirty  --exclude <glob>  --confirm <n>  --budget <ms>  --command-budget <ms>  --max <n>  --out <path>  --json
            the cold start: no claim and no concern needed. Everything it proposes is a DRAFT — it never writes testguard.claims.json,
            and its evidence never replaces .testguard/evidence.json. exit 1 on a fault that survived, or a file no test imports
            shapes: if-guard → if (false) · single-line guard/mutation removed · return <check> → return true
@@ -96,6 +98,7 @@ mcp        no options. JSON-RPC 2.0 over stdio; five READ-ONLY tools (status, br
 replay     --since <range>   commit range to search for fix commits (HEAD~50..HEAD, a tag, origin/main..HEAD)
            --max <n>         replay at most n fixes (they are slow: one worktree and N runs each)
            --confirm <n>     runs per verdict (default 3); a flaky failure reads as "the suite caught it", so mixed runs are never caught
+           --command-budget <ms> cooperative measurement deadline; expiry writes neither replay nor calibration, so an unmeasured suffix cannot look clean
            --out <path>       replay document (default: <dir>/.testguard/replay.json); the calibration goes beside it
            reports, never gates: a bug that escaped is history, not a regression in this change
                    · one-line JSX element removed · on<Event> handler prop dropped
@@ -132,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 {
@@ -142,6 +166,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         claims: { type: 'string' },
         confirm: { type: 'string', default: '3' },
         budget: { type: 'string', default: '120000' },
+        'command-budget': { type: 'string' },
         out: { type: 'string' },
         evidence: { type: 'string' },
         baseline: { type: 'string' },
@@ -177,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 },
@@ -199,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) {
@@ -209,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/command-budget.mjs

@@ -0,0 +1,52 @@
+import { PreconditionError } from './probe/worktree.mjs';
+import { performance } from 'node:perf_hooks';
+
+/**
+ * A cooperative measurement deadline shared by every stage of one command.
+ *
+ * Per-run budgets answer "how long may this runner invocation take?". This
+ * deadline answers the different question "may the whole command still
+ * produce a result?". Async child processes receive no more than the
+ * remaining time; synchronous setup can overrun because JavaScript cannot
+ * preempt it, so every stage boundary and every write boundary checks again.
+ * Expiry is deliberately not a verdict: a partial result would make the
+ * unattempted suffix look clean.
+ */
+export class CommandBudget {
+  constructor(limitMs, { now = () => performance.now() } = {}) {
+    if (!Number.isInteger(limitMs) || limitMs < 1) throw new TypeError('command budget must be a positive integer');
+    this.limitMs = limitMs;
+    this.now = now;
+    this.startedAtMs = now();
+  }
+
+  elapsedMs() {
+    return Math.max(0, this.now() - this.startedAtMs);
+  }
+
+  remainingMs() {
+    return Math.max(0, this.limitMs - this.elapsedMs());
+  }
+
+  assertOpen() {
+    if (this.remainingMs() === 0) {
+      throw new PreconditionError(`command budget of ${this.limitMs}ms exhausted; no partial result was written`);
+    }
+  }
+
+  /** Never let a child process outlive the command's remaining measurement window. */
+  runBudget(perRunMs) {
+    this.assertOpen();
+    return Math.max(1, Math.min(perRunMs, Math.floor(this.remainingMs())));
+  }
+}
+
+export function createCommandBudget(limitMs, options) {
+  return limitMs === undefined ? undefined : new CommandBudget(limitMs, options);
+}
+
+export function parseCommandBudget(value) {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= 1000 ? parsed : null;
+}