tdd-cli 0.7.0__tar.gz → 0.9.0__tar.gz

{tdd_cli-0.7.0 → tdd_cli-0.9.0}/CHANGELOG.md

@@ -6,6 +6,132 @@ and the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-03
+
+### Added
+
+- **`tdd note` — an executor-narrative channel.** `tdd note "<text>"` attaches
+  a phase-stamped note to the current cycle, or a run-level note once the run
+  has ended (it falls back to the latest run, so no active run is required).
+  Cycle notes render in the friction log as blockquote claims under their cycle;
+  run-level notes render under a new `## Executor narrative` section, which is
+  omitted when there are none. Envelopes that carry an integrity event now nudge
+  for a note while the reason is fresh (silenced once the cycle has one), and
+  the terminal `COMPLETE` envelope — via `advance` or a final-cycle skip — asks
+  for a closing narrative before rendering. Stored in a new `note` table via a
+  v7→v8 ledger migration (#77, #94).
+
+- **Baseline sanity gate.** `run start` refuses a baseline whose failing ratio
+  exceeds a threshold (default 0.5, suites under 10 collected tests exempt) with
+  `reason: "baseline_implausible"`, on the grounds that a mostly-red suite means
+  the environment is broken rather than the code. A per-project
+  `baseline_max_failure_ratio` in `tdd.toml` overrides the default, and
+  `--accept-baseline` bypasses the gate and logs a `baseline_accepted` integrity
+  event (#67, #84).
+
+- **Standing-failure delta.** A non-empty baseline is now compared against the
+  previous run's baseline for the same worktree and a `baseline_standing_delta`
+  event partitions the failing set into new versus inherited failures, so a
+  pre-existing red test is distinguishable from one that broke since the last
+  run (#67, #84).
+
+- **Per-project `health_command`.** An optional command in `tdd.toml` that is
+  probed before baseline capture; if it fails, `run start` refuses with
+  `reason: "services_unreachable"` instead of recording a baseline against a
+  down dependency (#67, #84).
+
+- **Declared-target lint.** `plan register` and `run start` now lint every
+  declared target against the adapter's id grammar (pytest `::`, vitest ` > `,
+  gradle `Class/method`, xctest `Bundle/Class/testMethod`) and against project
+  roots: a target path that duplicates a non-`.` project root prefix is refused
+  unless the nested path genuinely exists in the worktree. Findings are returned
+  under `reason: "target_lint"`; `run start` re-lints the stored contract
+  against the current config before claiming a baseline (#71, #88).
+
+- **Per-adapter sensitivity evidence line.** Each adapter now extracts a
+  `target_evidence` line from a failing target — the first `E` line for pytest
+  (skipping the xdist worker header), the first `: error:` line in the test's
+  window for xctest, `failureMessages[0]` for vitest, the junit failure message
+  for gradle, and the last non-empty output line for exec. The sensitivity check
+  persists it as `sensitivity_check.evidence_line` (v6→v7 migration) and the
+  friction log's observed snippet prefers it over the raw first line, rendering
+  `<no assertion line captured>` when empty and keeping the tail of over-long
+  lines. Legacy rows with no stored evidence keep the first-line fallback (#68,
+  #90).
+
+- **Diagnosable executor attribution.** `TDD_EXECUTOR_MODEL` lets a harness
+  declare the executor identity (`source: declared`), taking precedence over
+  transcript detection. When identity cannot be resolved, `Executor.reason`
+  says why — session id unset, transcript not found, or transcript without a
+  model record — and `run start` logs an `executor_unknown` event and surfaces
+  `executor_warning` in its envelope. `tdd doctor` gains an informational
+  executor-identity check (#74, #92).
+
+### Changed
+
+- **Target adoption is evaluated in the same `advance`.** When a cycle's
+  declared target is missing and exactly one new test appears, `advance`
+  adopts it (logging `declared_test_mismatch`) and judges RED — or drives the
+  sensitivity check when it passed — from the suite run that already happened,
+  instead of asking for a re-run. A declared id that differs
+  from a single same-file candidate only by separator normalisation is
+  disambiguated and adopted without asking; two same-file candidates still
+  require an explicit `tdd target` (#72, #91).
+
+- CI now tests on Python 3.11 and 3.14 only (#87).
+
+## [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

{tdd_cli-0.7.0 → tdd_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.7.0
+Version: 0.9.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
@@ -275,6 +319,13 @@ rendered, never written. Judgement enters in exactly two ways:
   `commit_shape_deviation`, `test_setup_smell`, `unplanned_change`, `new_work_raised`.
   `plan_defect` is the one that matters most: it records where the plan and the codebase
   disagreed, which is precisely what the next plan needs to know.
+- **Per cycle or run, through `tdd note "<text>"`** — free-text narrative captured at the
+  moment the reason exists. Cycle notes are scoped to the open cycle and phase; run-level
+  notes are written after the run ends and attach to the run. Both render in the friction
+  log as visually distinct blockquotes (claims, not measurements). Use notes to record
+  *why* something happened — a plan assumption that was wrong, an integrity event that the
+  telemetry already captures but cannot explain. Notes are unverified by design; an auditor
+  compares claims against reality.
 - **Per run, as prose appended below the rendered document.** Legitimate and expected —
   post-run narrative (CI failures, patterns noticed) has no cycle to attach to. But it
   is unverified: an auditor should trust the projected sections and read appended
@@ -397,6 +448,7 @@ and is never reclassified as a pin.
 | `tdd cycle skip --reason` | sanctioned path for a cycle the plan got wrong |
 | `tdd sensitivity begin\|check\|end` | prove a passing test can fail; verify restore |
 | `tdd annotate --key --value` | attach judgement to the current cycle |
+| `tdd note "<text>"` | attach a free-text narrative note to the current cycle or run |
 | `tdd blocker --kind --detail` | typed blocker; releases the stop hook |
 | `tdd resume [--unblock --note]` | reconstruct position; human intervention |
 | `tdd log render [--out]` | project the ledger into a friction log |
@@ -418,6 +470,50 @@ Pass `--baseline-all` to probe every project in `tdd.toml` regardless:
 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
@@ -432,6 +528,73 @@ kind `no_baseline_for_project` rather than mislabelling them as regressions. Rec
 failures as pre-existing) and records a `baseline_amended` event. The next advance proceeds
 with the project properly baselined.
 
+### Baseline sanity gate (R9.5g)
+
+`run start` refuses a baseline whose failure ratio is implausibly high — a signal that the
+environment, not the code, is broken. A project is flagged when it collected at least 10 tests
+(`BASELINE_MIN_COLLECTED`) and more than 50% of them failed (`BASELINE_MAX_FAILURE_RATIO_DEFAULT`):
+
+    error: baseline_implausible — backend: 1005/1010 failing (ratio 0.995)
+
+The gate targets stack-down blowouts (all 1000 tests failing because a service is unreachable),
+not small pre-existing failure sets (baseline subtraction handles those). A project collecting
+fewer than 10 tests is exempt — a 2-of-3 red baseline is ordinary pre-existing-failure territory,
+not a broken stack.
+
+Pass `--accept-baseline` to override the refusal and proceed anyway:
+
+    tdd run start --plan tasks/plan.md --accept-baseline
+
+An accepted implausible baseline records a `baseline_accepted` integrity event (visible in
+`tdd metrics` and the friction log) so the override is never silent. The gate runs on every
+baseline, including reused ones.
+
+To raise the threshold for a project whose legitimate baseline is inherently noisy, set
+`baseline_max_failure_ratio` in `tdd.toml`:
+
+```toml
+[project.legacy]
+root = "legacy"
+adapter = "pytest"
+baseline_max_failure_ratio = 0.8    # allow up to 80% failing at baseline
+```
+
+The value must be in `(0, 1]`. Without it, the repo-wide default of 0.5 applies.
+
+### Standing-failure delta
+
+When a non-empty baseline is captured, `run start` emits a `baseline_standing_delta` integrity
+event partitioning the current standing failures into:
+
+- **new** — absent from the previous run's baseline for this project (growing problem)
+- **inherited** — also present in the previous baseline (stable background noise)
+- **resolved** — in the previous baseline but absent now (fixed between runs)
+
+The event is visible in `tdd metrics` under `integrity_events`. A first run with no prior
+baseline reports every failure as `new`. A fully-green baseline (zero failing tests) emits
+nothing. Use this to spot a permanently-red set that baseline subtraction would otherwise hide.
+
+### Environment-dependent suites
+
+Declare a `health_command` on a project to probe reachability before `run start` captures its
+baseline:
+
+```toml
+[project.backend]
+root = "backend"
+adapter = "pytest"
+health_command = "curl -fsS http://localhost:8080/healthz"
+```
+
+If the command exits non-zero, `run start` refuses immediately with `reason:
+"services_unreachable"` — before claiming the worktree, before probing, before writing anything
+to the ledger. The error names the project and its exit code so the agent can surface the exact
+diagnosis rather than recording a ~1000-failure baseline and continuing.
+
+There is no override flag for `services_unreachable`: a down stack yields no believable baseline.
+The resolution is to fix the stack or drop the project from this run. Presence of `health_command`
+is the marker that a project requires live services; no separate boolean is needed.
+
 ## Running a long baseline
 
 `run start` probes the reachable project set (R9.5c) before a run exists, and on a real project
@@ -472,10 +635,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.7.0 → tdd_cli-0.9.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
@@ -247,6 +291,13 @@ rendered, never written. Judgement enters in exactly two ways:
   `commit_shape_deviation`, `test_setup_smell`, `unplanned_change`, `new_work_raised`.
   `plan_defect` is the one that matters most: it records where the plan and the codebase
   disagreed, which is precisely what the next plan needs to know.
+- **Per cycle or run, through `tdd note "<text>"`** — free-text narrative captured at the
+  moment the reason exists. Cycle notes are scoped to the open cycle and phase; run-level
+  notes are written after the run ends and attach to the run. Both render in the friction
+  log as visually distinct blockquotes (claims, not measurements). Use notes to record
+  *why* something happened — a plan assumption that was wrong, an integrity event that the
+  telemetry already captures but cannot explain. Notes are unverified by design; an auditor
+  compares claims against reality.
 - **Per run, as prose appended below the rendered document.** Legitimate and expected —
   post-run narrative (CI failures, patterns noticed) has no cycle to attach to. But it
   is unverified: an auditor should trust the projected sections and read appended
@@ -369,6 +420,7 @@ and is never reclassified as a pin.
 | `tdd cycle skip --reason` | sanctioned path for a cycle the plan got wrong |
 | `tdd sensitivity begin\|check\|end` | prove a passing test can fail; verify restore |
 | `tdd annotate --key --value` | attach judgement to the current cycle |
+| `tdd note "<text>"` | attach a free-text narrative note to the current cycle or run |
 | `tdd blocker --kind --detail` | typed blocker; releases the stop hook |
 | `tdd resume [--unblock --note]` | reconstruct position; human intervention |
 | `tdd log render [--out]` | project the ledger into a friction log |
@@ -390,6 +442,50 @@ Pass `--baseline-all` to probe every project in `tdd.toml` regardless:
 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
@@ -404,6 +500,73 @@ kind `no_baseline_for_project` rather than mislabelling them as regressions. Rec
 failures as pre-existing) and records a `baseline_amended` event. The next advance proceeds
 with the project properly baselined.
 
+### Baseline sanity gate (R9.5g)
+
+`run start` refuses a baseline whose failure ratio is implausibly high — a signal that the
+environment, not the code, is broken. A project is flagged when it collected at least 10 tests
+(`BASELINE_MIN_COLLECTED`) and more than 50% of them failed (`BASELINE_MAX_FAILURE_RATIO_DEFAULT`):
+
+    error: baseline_implausible — backend: 1005/1010 failing (ratio 0.995)
+
+The gate targets stack-down blowouts (all 1000 tests failing because a service is unreachable),
+not small pre-existing failure sets (baseline subtraction handles those). A project collecting
+fewer than 10 tests is exempt — a 2-of-3 red baseline is ordinary pre-existing-failure territory,
+not a broken stack.
+
+Pass `--accept-baseline` to override the refusal and proceed anyway:
+
+    tdd run start --plan tasks/plan.md --accept-baseline
+
+An accepted implausible baseline records a `baseline_accepted` integrity event (visible in
+`tdd metrics` and the friction log) so the override is never silent. The gate runs on every
+baseline, including reused ones.
+
+To raise the threshold for a project whose legitimate baseline is inherently noisy, set
+`baseline_max_failure_ratio` in `tdd.toml`:
+
+```toml
+[project.legacy]
+root = "legacy"
+adapter = "pytest"
+baseline_max_failure_ratio = 0.8    # allow up to 80% failing at baseline
+```
+
+The value must be in `(0, 1]`. Without it, the repo-wide default of 0.5 applies.
+
+### Standing-failure delta
+
+When a non-empty baseline is captured, `run start` emits a `baseline_standing_delta` integrity
+event partitioning the current standing failures into:
+
+- **new** — absent from the previous run's baseline for this project (growing problem)
+- **inherited** — also present in the previous baseline (stable background noise)
+- **resolved** — in the previous baseline but absent now (fixed between runs)
+
+The event is visible in `tdd metrics` under `integrity_events`. A first run with no prior
+baseline reports every failure as `new`. A fully-green baseline (zero failing tests) emits
+nothing. Use this to spot a permanently-red set that baseline subtraction would otherwise hide.
+
+### Environment-dependent suites
+
+Declare a `health_command` on a project to probe reachability before `run start` captures its
+baseline:
+
+```toml
+[project.backend]
+root = "backend"
+adapter = "pytest"
+health_command = "curl -fsS http://localhost:8080/healthz"
+```
+
+If the command exits non-zero, `run start` refuses immediately with `reason:
+"services_unreachable"` — before claiming the worktree, before probing, before writing anything
+to the ledger. The error names the project and its exit code so the agent can surface the exact
+diagnosis rather than recording a ~1000-failure baseline and continuing.
+
+There is no override flag for `services_unreachable`: a down stack yields no believable baseline.
+The resolution is to fix the stack or drop the project from this run. Presence of `health_command`
+is the marker that a project requires live services; no separate boolean is needed.
+
 ## Running a long baseline
 
 `run start` probes the reachable project set (R9.5c) before a run exists, and on a real project
@@ -444,10 +607,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.7.0 → tdd_cli-0.9.0}/examples/skills/tdd-drive/SKILL.md

@@ -74,9 +74,16 @@ end of the run.
 - The cycle absorbed undeclared scope, or surfaced follow-up work:
   `--key unplanned_change` / `--key new_work_raised`.
 
+To capture *why* something happened — a plan assumption that proved wrong, the reason an
+integrity event fired — use `tdd note "<text>"` at the moment you know. A note written
+during an open cycle is stamped with that cycle and phase and appears in the friction log
+as a blockquote alongside the cycle's telemetry. After the run ends, `tdd note` attaches
+at run level and renders in a dedicated **Executor narrative** section. Notes are unverified
+by design; write them as claims, not measurements.
+
 Narrative that spans cycles or happened after the run (CI failures, patterns) goes as
-markdown appended below the rendered friction log after `tdd log render` — never into a
-cycle annotation it doesn't belong to.
+`tdd note` after the run ends, or as markdown appended below the rendered friction log
+after `tdd log render` — never into a cycle annotation it doesn't belong to.
 
 ## When a suite run changes nothing
 

{tdd_cli-0.7.0 → tdd_cli-0.9.0}/src/tddcli/__init__.py

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

{tdd_cli-0.7.0 → tdd_cli-0.9.0}/src/tddcli/adapters/base.py

@@ -25,6 +25,7 @@ class Verdict:
     target: str | None = None
     target_outcome: str = NOT_FOUND
     target_failure: str = ""
+    target_evidence: str = ""
     passed: list[str] = field(default_factory=list)
     failed: list[str] = field(default_factory=list)
     duration_ms: int = 0
@@ -139,6 +140,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
 
@@ -206,6 +215,14 @@ class Adapter:
             return None
         return {k: os.path.expandvars(v) for k, v in merged.items()}
 
+    def lint_target_id(self, native: str) -> str | None:
+        """Return a problem message when `native` can never match a collected id, else None."""
+        return None
+
+    def target_path(self, native: str) -> str | None:
+        """Return the file-path portion of `native`, or None for non-path-bearing ids."""
+        return None
+
     def stub_hint(self) -> str:
         """The language idiom for a stub body, quoted into the create_stub directive."""
         return "a body that fails loudly, never working logic"

{tdd_cli-0.7.0 → tdd_cli-0.9.0}/src/tddcli/adapters/exec_adapter.py

@@ -168,6 +168,9 @@ class ExecAdapter(Adapter):
                 if target == qualified:
                     verdict.target_outcome = FAILED
                     verdict.target_failure = clip_failure(combined)
+                    verdict.target_evidence = next(
+                        (ln for ln in reversed(combined.splitlines()) if ln.strip()), ""
+                    )
 
         verdict.duration_ms = int((time.monotonic() - started) * 1000)
         return verdict