tdd-cli 0.6.0__tar.gz → 0.8.0__tar.gz

{tdd_cli-0.6.0 → tdd_cli-0.8.0}/CHANGELOG.md

@@ -4,6 +4,84 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.8.0] - 2026-08-28
+
+### Added
+
+- **`--reuse-baselines` caches baseline probes by content hash.** `run start`
+  can skip re-probing a project whose tree is unchanged: a probe result is
+  cached keyed by `(project, tree_hash, config_sha)` — where `tree_hash` folds in
+  every upstream producer root — and an identical rerun emits `baseline_reused`
+  instead of `baseline_captured`, reusing the cached failing set and collection
+  snapshot rather than re-running the suite. Provenance is recorded on the
+  baseline row (`source`), and `--reuse-max-age` re-probes any entry older than
+  the given age. Off by default; the cache stays empty unless the flag is passed
+  (#45, #59).
+
+- **`--baseline-jobs` parallelizes baseline probing.** `run start` probes each
+  project's baseline under a bounded `ThreadPoolExecutor` when `--baseline-jobs`
+  is greater than 1 (default 1, must be >= 1). The `baseline_captured` heartbeat
+  survives the pool, and a worker probe that raises becomes an attributed failure
+  that aborts cleanly and frees the worktree rather than wedging it (#46, #62).
+
+- **Plan-level `ancillary_files`.** A top-level front-matter key declaring
+  cross-project or companion paths a plan touches (README, generated fixtures,
+  sibling-project files). Declared ancillary paths are bucketed into their own
+  staging bucket, committed with the cycle, and fire no `undeclared_file_touched`
+  event. Validated as a list of strings at registration and persisted to the
+  ledger via a v5→v6 migration (#70, #80).
+
+- **Run-close gate on undeclared touched paths.** `run close` now blocks when a
+  path previously flagged as `undeclared_file_touched` is still dirty in the
+  worktree, so undeclared changes cannot slip through at the end of a run. A
+  flagged path that was since committed does not block; one that has vanished is
+  reported via a new `undeclared_file_dropped` event rather than blocking (#69,
+  #81).
+
+- **Reserved per-cycle `meta:` passthrough.** A cycle may carry an authored
+  `meta:` mapping in the plan front-matter; it round-trips through storage
+  unchanged and is available for plan-time metadata. A non-mapping `meta:`
+  hard-fails registration with a `ContractError` (#58, #65).
+
+### Fixed
+
+- `undeclared_file_touched` is deduplicated within a cycle, so a path touched
+  across multiple phases no longer floods the cycle with repeated events (#55,
+  #61).
+- vitest test ids are normalised on the describe/test separator before matching,
+  so a formatting-only difference between a declared target and the observed
+  verdict is no longer reported as a spurious `declared_test_mismatch` (#57,
+  #63).
+- The `stale_artifact` event is suppressed when the tool auto-regenerates the
+  artifact and commits it, so a successful regeneration no longer also emits a
+  staleness warning (#64).
+
+## [0.7.0] - 2026-08-23
+
+### Fixed
+
+- **Concurrent `tdd advance` no longer corrupts a run.** Two `advance` processes
+  racing on the same worktree could both close the same cycle row. Because
+  `close_cycle` unconditionally opened the next ordinal, a double-close forked the
+  run into two parallel cycle chains; every remaining cycle ran twice, the run
+  "completed" with one chain's last row permanently open, and the doubling was
+  invisible from the agent's perspective. `close_cycle` now re-reads `closed_at`
+  before acting; if the row is already closed it returns the currently-open cycle
+  without transitioning or opening anything. `open_cycle` returns the existing open
+  row for an ordinal rather than inserting a duplicate.
+
+### Added
+
+- **Per-worktree advance claim.** `tdd advance` now acquires a `advance_claim` row
+  before dispatching. A second concurrent `advance` is refused immediately with
+  `ok: false`, `reason: "advance_in_flight"`, and metadata (`pid`, `started_at`,
+  `elapsed_s`) that lets the agent confirm the holder is still alive. The claim is
+  released in a `finally` so a raising handler cannot wedge the worktree; a claim
+  held by a dead pid is reclaimed automatically on the next call. Schema version
+  bumped to 3.
+
 ## [0.6.0] - 2026-08-19
 
 ### Added

{tdd_cli-0.6.0 → tdd_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.6.0
+Version: 0.8.0
 Summary: Ledger-backed TDD process controller for autonomous coding agents
 Project-URL: Homepage, https://github.com/geuben/tdd-cli
 Project-URL: Repository, https://github.com/geuben/tdd-cli
@@ -227,6 +227,8 @@ cycles:
     stub_expected: ["app/exception_map.py"]
     commit_red: "test: unmapped exception is not swallowed"
     commit_green: "feat: domain exception map skeleton"
+    meta:                           # optional authored-at-plan-time metadata; opaque to the tool
+      covers: ["B1", "B2"]         # any mapping is valid; contents are tool-opaque
   - n: 8
     project: backend
     pin_cycle: true                 # characterisation; passes on arrival by design
@@ -238,9 +240,51 @@ cycles:
       - "backend::tests/test_openapi.py::test_upload_body_schema"
       - "frontend::services/__tests__/upload.test.ts > matches contract"
 annotation_keys: ["literal_detail_handlers_kept"]
+ancillary_files:
+  - frontend/src/api/registerClient.ts   # type-break from regenerated client
+  - docs/INVARIANTS.md                   # companion doc read at runtime by cycle 7's test
 ---
 ```
 
+**Top-level keys:**
+
+`annotation_keys` — a list of judgement-annotation keys the plan requires; the run close
+gate checks that every key is present before the plan can be marked complete.
+
+`ancillary_files` — a plan-level list of repo-root-relative paths the plan is known to
+touch outside any registered project root (cross-project ripples, companion documents).
+Paths are hash-frozen with the plan blob like all other front-matter. A changed path that
+matches the list is classified as *declared* — no `undeclared_file_touched` event fires —
+and is staged into the GREEN/REFACTOR phase commit alongside the cycle's own files. A path
+not on the list still fires `undeclared_file_touched` exactly as today. This is a
+plan-level list only; per-cycle overrides are a planned follow-up.
+
+### Run-close gate for undeclared file touches
+
+When the last declared cycle closes, the tool gathers every path that appeared in any
+`undeclared_file_touched` event across the run and checks the worktree:
+
+- **Still dirty/untracked** → a typed blocker `undeclared_file_uncommitted` is inserted,
+  the run outcome is set to `blocked`, and `next_action.verb` is `"blocked"`. Resolution:
+  commit the files, then `tdd resume --unblock --note "committed notes.md"`, or discard
+  and record a justification with `tdd resume --unblock --note "discarding scratch file"`.
+- **Committed during the run** → clean; the run completes normally.
+- **Vanished without being committed** → an `undeclared_file_dropped` integrity event is
+  emitted (visible in `tdd metrics` and the friction log) and the run completes. The event
+  makes a silent drop visible without blocking, since the file is already gone.
+
+The gate composes with `ancillary_files`: declared paths never fire `undeclared_file_touched`,
+so they are never seen by the gate.
+
+**Per-cycle keys:** `n` (ordinal), `project`/`projects`, `test`/`tests`, `title`, `files`,
+`stub_expected`, `modifies_tests`, `commit_red`, `commit_green`, `commit_refactor`,
+`commit_pin`, `pin_cycle`, `contract_cycle`, `refactor_cycle`, and `meta`.
+`meta` is a reserved passthrough mapping: its *shape* is validated (must be a mapping),
+but its *contents* are opaque to the tool — any key/value pairs are accepted and
+round-tripped intact through `cycles_to_json`/`cycles_from_json`. Use it for
+authored-at-plan-time metadata that external tooling (e.g. a behaviour-coverage checker)
+needs to read back. Other unknown per-cycle keys are silently ignored.
+
 Absent front-matter is legitimate — the run proceeds as `undeclared` with
 `--allow-undeclared`, and fidelity metrics are unavailable. **Malformed** front-matter
 hard-fails registration: it is almost always a defect in the planning process, and that
@@ -314,6 +358,34 @@ test_paths   = ["src/test/"]
 test_command = "./gradlew testDebugUnitTest"
 ```
 
+The `xctest` adapter drives Swift and Objective-C projects through `xcodebuild`. Test ids
+use xcodebuild's own `-only-testing:` format — `BundleName/ClassName/testMethodName` — so
+a single XCTest can be driven through RED → GREEN without any id translation. Collection
+prefers `xcodebuild test -enumerate-tests` (Xcode 16+) and falls back to grepping
+`class Foo: XCTestCase` / `func testBar()` out of the Swift sources under `test_paths`,
+deriving the bundle name from `-scheme`. As with gradle, a *build* failure maps to
+`not_collected` rather than `failed`, so a stub referencing a missing symbol is not
+mistaken for RED.
+
+`test_command` is required here — the adapter cannot guess the scheme, destination, or
+derived-data path. It appends `-only-testing:` for targeted runs and `-enumerate-tests`
+for collection, and changes nothing else. Simulator runs are serial in practice: give
+them a `lease` so two projects don't drive the same simulator at once.
+
+```toml
+[project.native-ios]
+root         = "native-ios"
+adapter      = "xctest"
+test_paths   = ["AppTests/"]
+test_command = """xcodebuild test \
+  -project App.xcodeproj \
+  -scheme AppTests \
+  -destination 'platform=iOS Simulator,name=App-Unit' \
+  -derivedDataPath /tmp/app-unit-dd"""
+lease        = "ios-simulator"
+timeout      = 900
+```
+
 Third-party adapters register under the
 `tddcli.adapters` entry-point group:
 
@@ -375,14 +447,93 @@ and is never reclassified as a pin.
 | `tdd metrics` | fidelity, attempts, violations, interventions |
 | `tdd fleet [--json]` | all active runs across every worktree; read-only |
 
+## Scoped baseline capture (R9.5c)
+
+`run start` probes only the projects the plan can actually reach: the declared cycle projects
+plus the transitive `consumed_by` closure of artifacts whose producer is in that set. Projects
+outside the reachable set never run during the plan, so their baseline is never subtracted from
+anything — probing them is pure overhead. A `baseline_scoped` integrity event records which
+projects were skipped, so the scoping is auditable.
+
+Pass `--baseline-all` to probe every project in `tdd.toml` regardless:
+
+    tdd run start --plan tasks/plan.md --baseline-all
+
+Use this when a cycle may edit files outside the predicted reachable set and you want every
+project baselined up front rather than hitting the `no_baseline_for_project` escape hatch later.
+
+### Reusing baselines across runs (R9.5e)
+
+On repos where runs are frequent and most projects change rarely, re-probing unchanged suites
+wastes time. Pass `--reuse-baselines` to cache probe results and skip re-probing on the next run
+when nothing in the project changed:
+
+    tdd run start --plan tasks/plan.md --reuse-baselines
+
+The cache key is `(project, tree_hash(project root ∪ upstream producer roots), config_sha)`.
+If the key matches a previous entry, the cached failing set and collection snapshot are used —
+no suite is run — and a `baseline_reused` heartbeat appears on stderr. The baseline row carries
+`source = "reused"` for auditability, and a `baseline_reused` integrity event lists which
+projects were skipped. Without the flag, the cache is neither read nor written.
+
+A stale or wrong reused baseline is always recoverable via `resume --unblock --accept-failures`
+(see below) — reuse is loud by design, never silent.
+
+To limit how old a cached entry may be, pass `--reuse-max-age <seconds>`:
+
+    tdd run start --plan tasks/plan.md --reuse-baselines --reuse-max-age 3600
+
+Entries older than the given threshold are ignored and re-probed fresh.
+
+### Parallel baseline probing (R9.5f)
+
+By default `run start` probes one project at a time. On a repo with many independent projects the
+wall-clock cost is the *sum* of all suite runtimes. Pass `--baseline-jobs N` to probe up to N
+projects concurrently:
+
+    tdd run start --plan tasks/plan.md --baseline-jobs 4
+
+Each probe is independent — one adapter instance per project — so concurrency does not affect
+which projects are probed, the refusal checks, or the baseline rows written. A `baseline_captured`
+heartbeat is still emitted per project as each probe completes.
+
+The default is `--baseline-jobs 1` (serial). Raise it deliberately:
+
+- **I/O-bound suites** (network, DB, file-heavy) benefit most; CPU-bound suites less so.
+- **Suites contending for global resources** (xctest simulators, fixed ports) should stay at 1,
+  or declare a `lease` name — leased suites serialize automatically even inside the pool.
+
+If any probe fails, `run start` returns a failure attributed to that project and no run row is
+created, so the worktree is immediately retryable.
+
+### When a sweep reaches an un-baselined project (R9.5d)
+
+If an edit during a run touches a file owned by an artifact that was outside the predicted
+reachable set, the close sweep may pull in a project that was never baselined. Its failures are
+unattributable — no baseline exists to subtract — so the sweep replies `resolve_blocker` with
+kind `no_baseline_for_project` rather than mislabelling them as regressions. Recovery:
+
+    tdd blocker --kind no_baseline_for_project --detail "svc pulled in unexpectedly"
+    tdd resume --unblock --accept-failures --note "folding svc sweep failures into baseline"
+
+`--accept-failures` inserts a fresh baseline row for the un-baselined project (recording those
+failures as pre-existing) and records a `baseline_amended` event. The next advance proceeds
+with the project properly baselined.
+
 ## Running a long baseline
 
-`run start` probes every project's suite before a run exists (R9.5a), and on a real project
+`run start` probes the reachable project set (R9.5c) before a run exists, and on a real project
 that can take minutes — well past an agent harness's default Bash timeout. If the command
 appears to hang or time out, **do not re-run it**: the probe is still making progress in the
 background, and a second `run start` against the same worktree is refused with
 `reason: "baseline_in_progress"` — retrying on timeout just stacks refusals on top of a
-baseline that was never stuck. In order of preference:
+baseline that was never stuck.
+
+`tdd advance` is similarly single-flight per worktree. A close sweep (artifact regeneration, full
+suite, lint, typecheck) can run for several minutes. If an advance appears to hang, **do not
+re-run it**: a second `advance` against the same worktree is refused with
+`reason: "advance_in_flight"`. The refusal carries `pid`, `started_at`, and `elapsed_s` so the
+agent can confirm the first process is still alive. Run `tdd status` to see the current run state. In order of preference:
 
 1. **Background it.** Run `tdd run start` in the background if your harness supports it. The
    heartbeat (`baseline_captured` / `project_completed` lines on stderr) lands in the task log
@@ -409,10 +560,11 @@ The CLI cannot compel an agent — only the harness can.
 artifact; a passed-on-arrival cycle cannot close without a verified sensitivity check;
 `advance` refuses an unchanged tree unless `--retry`.
 
-**Recorded, never blocked:** non-stub writes during RED, undeclared file touches, scope
-divergence, extra attempts. Prevention rules with edge cases produce false denials, and a
-blocked agent improvises around them — putting it right back in the reporting path the
-tool exists to keep it out of.
+**Recorded, never blocked mid-run:** non-stub writes during RED, undeclared file touches,
+scope divergence, extra attempts. Prevention rules with edge cases produce false denials,
+and a blocked agent improvises around them — putting it right back in the reporting path
+the tool exists to keep it out of. Undeclared file touches are an exception at run close:
+see the run-close gate above.
 
 **Delegated to hooks:** a Stop hook that queries `tdd status` and refuses to let an agent
 stop while a run is live; a Bash hook redirecting bare `pytest`/`vitest` through `tdd advance`.

{tdd_cli-0.6.0 → tdd_cli-0.8.0}/README.md

@@ -199,6 +199,8 @@ cycles:
     stub_expected: ["app/exception_map.py"]
     commit_red: "test: unmapped exception is not swallowed"
     commit_green: "feat: domain exception map skeleton"
+    meta:                           # optional authored-at-plan-time metadata; opaque to the tool
+      covers: ["B1", "B2"]         # any mapping is valid; contents are tool-opaque
   - n: 8
     project: backend
     pin_cycle: true                 # characterisation; passes on arrival by design
@@ -210,9 +212,51 @@ cycles:
       - "backend::tests/test_openapi.py::test_upload_body_schema"
       - "frontend::services/__tests__/upload.test.ts > matches contract"
 annotation_keys: ["literal_detail_handlers_kept"]
+ancillary_files:
+  - frontend/src/api/registerClient.ts   # type-break from regenerated client
+  - docs/INVARIANTS.md                   # companion doc read at runtime by cycle 7's test
 ---
 ```
 
+**Top-level keys:**
+
+`annotation_keys` — a list of judgement-annotation keys the plan requires; the run close
+gate checks that every key is present before the plan can be marked complete.
+
+`ancillary_files` — a plan-level list of repo-root-relative paths the plan is known to
+touch outside any registered project root (cross-project ripples, companion documents).
+Paths are hash-frozen with the plan blob like all other front-matter. A changed path that
+matches the list is classified as *declared* — no `undeclared_file_touched` event fires —
+and is staged into the GREEN/REFACTOR phase commit alongside the cycle's own files. A path
+not on the list still fires `undeclared_file_touched` exactly as today. This is a
+plan-level list only; per-cycle overrides are a planned follow-up.
+
+### Run-close gate for undeclared file touches
+
+When the last declared cycle closes, the tool gathers every path that appeared in any
+`undeclared_file_touched` event across the run and checks the worktree:
+
+- **Still dirty/untracked** → a typed blocker `undeclared_file_uncommitted` is inserted,
+  the run outcome is set to `blocked`, and `next_action.verb` is `"blocked"`. Resolution:
+  commit the files, then `tdd resume --unblock --note "committed notes.md"`, or discard
+  and record a justification with `tdd resume --unblock --note "discarding scratch file"`.
+- **Committed during the run** → clean; the run completes normally.
+- **Vanished without being committed** → an `undeclared_file_dropped` integrity event is
+  emitted (visible in `tdd metrics` and the friction log) and the run completes. The event
+  makes a silent drop visible without blocking, since the file is already gone.
+
+The gate composes with `ancillary_files`: declared paths never fire `undeclared_file_touched`,
+so they are never seen by the gate.
+
+**Per-cycle keys:** `n` (ordinal), `project`/`projects`, `test`/`tests`, `title`, `files`,
+`stub_expected`, `modifies_tests`, `commit_red`, `commit_green`, `commit_refactor`,
+`commit_pin`, `pin_cycle`, `contract_cycle`, `refactor_cycle`, and `meta`.
+`meta` is a reserved passthrough mapping: its *shape* is validated (must be a mapping),
+but its *contents* are opaque to the tool — any key/value pairs are accepted and
+round-tripped intact through `cycles_to_json`/`cycles_from_json`. Use it for
+authored-at-plan-time metadata that external tooling (e.g. a behaviour-coverage checker)
+needs to read back. Other unknown per-cycle keys are silently ignored.
+
 Absent front-matter is legitimate — the run proceeds as `undeclared` with
 `--allow-undeclared`, and fidelity metrics are unavailable. **Malformed** front-matter
 hard-fails registration: it is almost always a defect in the planning process, and that
@@ -286,6 +330,34 @@ test_paths   = ["src/test/"]
 test_command = "./gradlew testDebugUnitTest"
 ```
 
+The `xctest` adapter drives Swift and Objective-C projects through `xcodebuild`. Test ids
+use xcodebuild's own `-only-testing:` format — `BundleName/ClassName/testMethodName` — so
+a single XCTest can be driven through RED → GREEN without any id translation. Collection
+prefers `xcodebuild test -enumerate-tests` (Xcode 16+) and falls back to grepping
+`class Foo: XCTestCase` / `func testBar()` out of the Swift sources under `test_paths`,
+deriving the bundle name from `-scheme`. As with gradle, a *build* failure maps to
+`not_collected` rather than `failed`, so a stub referencing a missing symbol is not
+mistaken for RED.
+
+`test_command` is required here — the adapter cannot guess the scheme, destination, or
+derived-data path. It appends `-only-testing:` for targeted runs and `-enumerate-tests`
+for collection, and changes nothing else. Simulator runs are serial in practice: give
+them a `lease` so two projects don't drive the same simulator at once.
+
+```toml
+[project.native-ios]
+root         = "native-ios"
+adapter      = "xctest"
+test_paths   = ["AppTests/"]
+test_command = """xcodebuild test \
+  -project App.xcodeproj \
+  -scheme AppTests \
+  -destination 'platform=iOS Simulator,name=App-Unit' \
+  -derivedDataPath /tmp/app-unit-dd"""
+lease        = "ios-simulator"
+timeout      = 900
+```
+
 Third-party adapters register under the
 `tddcli.adapters` entry-point group:
 
@@ -347,14 +419,93 @@ and is never reclassified as a pin.
 | `tdd metrics` | fidelity, attempts, violations, interventions |
 | `tdd fleet [--json]` | all active runs across every worktree; read-only |
 
+## Scoped baseline capture (R9.5c)
+
+`run start` probes only the projects the plan can actually reach: the declared cycle projects
+plus the transitive `consumed_by` closure of artifacts whose producer is in that set. Projects
+outside the reachable set never run during the plan, so their baseline is never subtracted from
+anything — probing them is pure overhead. A `baseline_scoped` integrity event records which
+projects were skipped, so the scoping is auditable.
+
+Pass `--baseline-all` to probe every project in `tdd.toml` regardless:
+
+    tdd run start --plan tasks/plan.md --baseline-all
+
+Use this when a cycle may edit files outside the predicted reachable set and you want every
+project baselined up front rather than hitting the `no_baseline_for_project` escape hatch later.
+
+### Reusing baselines across runs (R9.5e)
+
+On repos where runs are frequent and most projects change rarely, re-probing unchanged suites
+wastes time. Pass `--reuse-baselines` to cache probe results and skip re-probing on the next run
+when nothing in the project changed:
+
+    tdd run start --plan tasks/plan.md --reuse-baselines
+
+The cache key is `(project, tree_hash(project root ∪ upstream producer roots), config_sha)`.
+If the key matches a previous entry, the cached failing set and collection snapshot are used —
+no suite is run — and a `baseline_reused` heartbeat appears on stderr. The baseline row carries
+`source = "reused"` for auditability, and a `baseline_reused` integrity event lists which
+projects were skipped. Without the flag, the cache is neither read nor written.
+
+A stale or wrong reused baseline is always recoverable via `resume --unblock --accept-failures`
+(see below) — reuse is loud by design, never silent.
+
+To limit how old a cached entry may be, pass `--reuse-max-age <seconds>`:
+
+    tdd run start --plan tasks/plan.md --reuse-baselines --reuse-max-age 3600
+
+Entries older than the given threshold are ignored and re-probed fresh.
+
+### Parallel baseline probing (R9.5f)
+
+By default `run start` probes one project at a time. On a repo with many independent projects the
+wall-clock cost is the *sum* of all suite runtimes. Pass `--baseline-jobs N` to probe up to N
+projects concurrently:
+
+    tdd run start --plan tasks/plan.md --baseline-jobs 4
+
+Each probe is independent — one adapter instance per project — so concurrency does not affect
+which projects are probed, the refusal checks, or the baseline rows written. A `baseline_captured`
+heartbeat is still emitted per project as each probe completes.
+
+The default is `--baseline-jobs 1` (serial). Raise it deliberately:
+
+- **I/O-bound suites** (network, DB, file-heavy) benefit most; CPU-bound suites less so.
+- **Suites contending for global resources** (xctest simulators, fixed ports) should stay at 1,
+  or declare a `lease` name — leased suites serialize automatically even inside the pool.
+
+If any probe fails, `run start` returns a failure attributed to that project and no run row is
+created, so the worktree is immediately retryable.
+
+### When a sweep reaches an un-baselined project (R9.5d)
+
+If an edit during a run touches a file owned by an artifact that was outside the predicted
+reachable set, the close sweep may pull in a project that was never baselined. Its failures are
+unattributable — no baseline exists to subtract — so the sweep replies `resolve_blocker` with
+kind `no_baseline_for_project` rather than mislabelling them as regressions. Recovery:
+
+    tdd blocker --kind no_baseline_for_project --detail "svc pulled in unexpectedly"
+    tdd resume --unblock --accept-failures --note "folding svc sweep failures into baseline"
+
+`--accept-failures` inserts a fresh baseline row for the un-baselined project (recording those
+failures as pre-existing) and records a `baseline_amended` event. The next advance proceeds
+with the project properly baselined.
+
 ## Running a long baseline
 
-`run start` probes every project's suite before a run exists (R9.5a), and on a real project
+`run start` probes the reachable project set (R9.5c) before a run exists, and on a real project
 that can take minutes — well past an agent harness's default Bash timeout. If the command
 appears to hang or time out, **do not re-run it**: the probe is still making progress in the
 background, and a second `run start` against the same worktree is refused with
 `reason: "baseline_in_progress"` — retrying on timeout just stacks refusals on top of a
-baseline that was never stuck. In order of preference:
+baseline that was never stuck.
+
+`tdd advance` is similarly single-flight per worktree. A close sweep (artifact regeneration, full
+suite, lint, typecheck) can run for several minutes. If an advance appears to hang, **do not
+re-run it**: a second `advance` against the same worktree is refused with
+`reason: "advance_in_flight"`. The refusal carries `pid`, `started_at`, and `elapsed_s` so the
+agent can confirm the first process is still alive. Run `tdd status` to see the current run state. In order of preference:
 
 1. **Background it.** Run `tdd run start` in the background if your harness supports it. The
    heartbeat (`baseline_captured` / `project_completed` lines on stderr) lands in the task log
@@ -381,10 +532,11 @@ The CLI cannot compel an agent — only the harness can.
 artifact; a passed-on-arrival cycle cannot close without a verified sensitivity check;
 `advance` refuses an unchanged tree unless `--retry`.
 
-**Recorded, never blocked:** non-stub writes during RED, undeclared file touches, scope
-divergence, extra attempts. Prevention rules with edge cases produce false denials, and a
-blocked agent improvises around them — putting it right back in the reporting path the
-tool exists to keep it out of.
+**Recorded, never blocked mid-run:** non-stub writes during RED, undeclared file touches,
+scope divergence, extra attempts. Prevention rules with edge cases produce false denials,
+and a blocked agent improvises around them — putting it right back in the reporting path
+the tool exists to keep it out of. Undeclared file touches are an exception at run close:
+see the run-close gate above.
 
 **Delegated to hooks:** a Stop hook that queries `tdd status` and refuses to let an agent
 stop while a run is live; a Bash hook redirecting bare `pytest`/`vitest` through `tdd advance`.

{tdd_cli-0.6.0 → tdd_cli-0.8.0}/src/tddcli/__init__.py

@@ -3,4 +3,4 @@
 State is derived from observed test execution, never asserted by the caller.
 """
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"

{tdd_cli-0.6.0 → tdd_cli-0.8.0}/src/tddcli/adapters/base.py

@@ -139,6 +139,14 @@ class Adapter:
         prefix = f"{self.project.name}::"
         return qualified[len(prefix) :] if qualified.startswith(prefix) else qualified
 
+    def normalise_id(self, test_id: str) -> str:
+        """Return the canonical form of a declared target id for matching against collected ids.
+
+        The default is an identity — subclasses override when the runner's collected
+        ids differ from a natural human spelling (e.g. vitest's describe/test separator).
+        """
+        return test_id
+
     def run(self, target: str | None = None) -> Verdict:
         raise NotImplementedError