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

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

@@ -6,6 +6,80 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.8.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
@@ -319,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
@@ -441,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 |
@@ -520,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

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

@@ -291,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
@@ -413,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 |
@@ -492,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

{tdd_cli-0.8.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.8.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.8.0"
+__version__ = "0.9.0"

{tdd_cli-0.8.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
@@ -214,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.8.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

{tdd_cli-0.8.0 → tdd_cli-0.9.0}/src/tddcli/adapters/gradle_adapter.py

@@ -114,6 +114,14 @@ class GradleAdapter(Adapter):
             " assertion failure"
         )
 
+    def lint_target_id(self, native: str) -> str | None:
+        if "/" not in native:
+            return (
+                f"gradle target ids must contain '/' between class and method "
+                f"(got {native!r}); expected shape: com.example.ClassName/testMethodName"
+            )
+        return None
+
     # ------------------------------------------------------------------
     # Core command
     # ------------------------------------------------------------------
@@ -321,7 +329,11 @@ class GradleAdapter(Adapter):
             verdict.target_outcome = PASSED
         elif target in failed:
             verdict.target_outcome = FAILED
-            verdict.target_failure = failures.get(target, "test failed")
+            failure_text = failures.get(target, "test failed")
+            verdict.target_failure = failure_text
+            verdict.target_evidence = next(
+                (ln for ln in failure_text.splitlines() if ln.strip()), ""
+            )
         # else NOT_FOUND (default): the suite ran but never produced this id
 
         return verdict

{tdd_cli-0.8.0 → tdd_cli-0.9.0}/src/tddcli/adapters/pytest_adapter.py

@@ -12,6 +12,7 @@ Two defects in the prior system are corrected here (R10.2):
 from __future__ import annotations
 
 import json
+import re
 import shlex
 import tempfile
 from pathlib import Path
@@ -48,6 +49,14 @@ class PytestAdapter(Adapter):
     def stub_hint(self) -> str:
         return "`raise NotImplementedError` in every body"
 
+    def lint_target_id(self, native: str) -> str | None:
+        if "::" not in native:
+            return f"pytest target ids must contain '::' (got {native!r}); expected shape: path/to/test_file.py::test_name"
+        return None
+
+    def target_path(self, native: str) -> str | None:
+        return native.split("::", 1)[0]
+
     def _runner_prefix(self) -> str:
         """The project root is checked before the worktree root: a workspace keeps
         one lockfile at the top, but a member with its own marker owns its choice."""
@@ -140,7 +149,9 @@ class PytestAdapter(Adapter):
         if hit is not None:
             verdict.target_outcome = PASSED if hit["outcome"] == "passed" else FAILED
             call = hit.get("call") or hit.get("setup") or {}
-            verdict.target_failure = clip_failure(str(call.get("longrepr", "")))
+            longrepr = str(call.get("longrepr", ""))
+            verdict.target_failure = clip_failure(longrepr)
+            verdict.target_evidence = self._evidence_line(longrepr)
         else:
             target_file = native.split("::", 1)[0]
             if any(c == target_file or c.startswith(target_file) for c in uncollectable):
@@ -152,6 +163,14 @@ class PytestAdapter(Adapter):
                 verdict.target_outcome = NOT_FOUND
         return verdict
 
+    @staticmethod
+    def _evidence_line(longrepr: str) -> str:
+        for line in longrepr.splitlines():
+            m = re.match(r"^E\s+(.*)", line)
+            if m:
+                return m.group(1)
+        return ""
+
     @staticmethod
     def _collector_error(collectors: list[dict], target_file: str) -> str:
         for collector in collectors:

{tdd_cli-0.8.0 → tdd_cli-0.9.0}/src/tddcli/adapters/vitest_adapter.py

@@ -47,6 +47,17 @@ class VitestAdapter(Adapter):
     def stub_hint(self) -> str:
         return '`throw new Error("not implemented")` in every body'
 
+    def lint_target_id(self, native: str) -> str | None:
+        if " > " not in native:
+            return (
+                f"vitest target ids must contain ' > ' between the file and test name "
+                f"(got {native!r}); expected shape: <file> > <describe titles> <test title>"
+            )
+        return None
+
+    def target_path(self, native: str) -> str | None:
+        return native.split(" > ", 1)[0]
+
     def normalise_id(self, test_id: str) -> str:
         """Canonicalise the describe/test separator for target matching.
 
@@ -141,8 +152,13 @@ class VitestAdapter(Adapter):
                         self.normalise_id(self._id_for(suite.get("name", ""), t["fullName"]))
                         == ntarget
                     ):
+                        messages = t.get("failureMessages", [])
                         verdict.target_failure = "\n".join(
-                            clip_failure(m, 600) for m in t.get("failureMessages", [])[:3]
+                            clip_failure(m, 600) for m in messages[:3]
+                        )
+                        first_msg = messages[0] if messages else ""
+                        verdict.target_evidence = next(
+                            (ln for ln in first_msg.splitlines() if ln.strip()), ""
                         )
             return verdict
 

{tdd_cli-0.8.0 → tdd_cli-0.9.0}/src/tddcli/adapters/xctest_adapter.py

@@ -94,6 +94,15 @@ class XCTestAdapter(Adapter):
             " compiles first, then observe the assertion failure"
         )
 
+    def lint_target_id(self, native: str) -> str | None:
+        parts = native.split("/")
+        if len(parts) != 3 or any(not p for p in parts):
+            return (
+                f"xctest target ids must be exactly three '/'-separated parts "
+                f"(got {native!r}); expected shape: Bundle/Class/testMethod"
+            )
+        return None
+
     # ------------------------------------------------------------------
     # Core command
     # ------------------------------------------------------------------
@@ -263,7 +272,9 @@ class XCTestAdapter(Adapter):
             verdict.target_outcome = PASSED
         elif target in verdict.failed:
             verdict.target_outcome = FAILED
-            verdict.target_failure = self._failure_for(combined, self.strip(target))
+            window = self._failure_for(combined, self.strip(target))
+            verdict.target_failure = window
+            verdict.target_evidence = self._evidence_line(window)
         # else NOT_FOUND (default)
 
         return verdict
@@ -280,6 +291,13 @@ class XCTestAdapter(Adapter):
             if ": error:" in line or "** BUILD FAILED **" in line
         )
 
+    @staticmethod
+    def _evidence_line(window: str) -> str:
+        for line in window.splitlines():
+            if ": error:" in line:
+                return line
+        return ""
+
     def _failure_for(self, combined: str, native_id: str) -> str:
         """Capture the assertion lines between 'started' and 'failed' for one test.
 

{tdd_cli-0.8.0 → tdd_cli-0.9.0}/src/tddcli/advance.py

@@ -22,13 +22,35 @@ from .machine import (
     Engine,
 )
 
+NUDGE_KINDS = {"red_first_violation", "undeclared_file_touched", "implementation_during_red"}
+
+
+def _note_nudge(engine: Engine, cycle) -> str:
+    if cycle is None:
+        return ""
+    events = engine.ledger.all(
+        "SELECT kind FROM integrity_event WHERE cycle_id = ? AND kind IN ({})".format(
+            ",".join("?" * len(NUDGE_KINDS))
+        ),
+        (cycle["id"], *NUDGE_KINDS),
+    )
+    if not events:
+        return ""
+    existing_note = engine.ledger.one(
+        "SELECT id FROM note WHERE cycle_id = ?", (cycle["id"],)
+    )
+    if existing_note is not None:
+        return ""
+    return ' An integrity event was recorded on this cycle — consider `tdd note "<why>"` while the reason is fresh.'
+
 
 def _reply(engine: Engine, cycle, verb: Verb, detail: str, **result) -> Envelope:
     fresh = engine.ledger.one("SELECT * FROM cycle WHERE id = ?", (cycle["id"],)) if cycle else None
+    nudge = _note_nudge(engine, fresh or cycle)
     return Envelope(
         run=engine.run_state(fresh or cycle),
         result=result,
-        next_action=NextAction(verb, detail),
+        next_action=NextAction(verb, detail + nudge),
     )
 
 
@@ -117,6 +139,27 @@ def _stage_and_commit(engine: Engine, cycle, phase: str, declared) -> tuple[str
     return sha, staged, classification
 
 
+def _disambiguate(candidates: list[str], declared: str, adapter) -> str | None:
+    norm_declared = adapter.normalise_id(declared)
+    matches = [c for c in candidates if adapter.normalise_id(c) == norm_declared]
+    if len(matches) == 1:
+        return matches[0]
+    declared_file = declared.split("::", 1)[-1].split("::")[0].split(" > ")[0]
+    same_file = [c for c in candidates if c.split("::", 1)[-1].split("::")[0].split(" > ")[0] == declared_file]
+    if len(same_file) == 1:
+        return same_file[0]
+    return None
+
+
+def _outcome_from_verdicts(verdicts, test_id: str) -> str | None:
+    for v in verdicts:
+        if test_id in v.failed:
+            return FAILED
+        if test_id in v.passed:
+            return PASSED
+    return None
+
+
 # -- handlers ------------------------------------------------------------
 
 
@@ -127,7 +170,7 @@ def _handle_test_phase(engine: Engine, cycle, retried: bool, expect_pass: bool)
     targets = json.loads(cycle["target_tests"])
     phase = cycle["phase"]
 
-    outcomes, others, _, failure = engine.run_projects(
+    outcomes, others, verdicts, failure = engine.run_projects(
         projects, targets, cycle, phase, retried
     )
 
@@ -144,29 +187,60 @@ def _handle_test_phase(engine: Engine, cycle, retried: bool, expect_pass: bool)
                 "cycle", cycle["id"], target_tests=json.dumps(kept + candidates)
             )
             cycle = engine.ledger.one("SELECT * FROM cycle WHERE id = ?", (cycle["id"],))
+            adopted_outcome = _outcome_from_verdicts(verdicts, candidates[0])
+            if adopted_outcome is None:
+                return _reply(
+                    engine, cycle, Verb.REFACTOR_OR_ADVANCE,
+                    f"Adopted {candidates[0]} as the target (declared {missing[0]} was not"
+                    " collected). Run `tdd advance` again to evaluate it.",
+                    adopted=candidates,
+                )
+            targets = kept + candidates
+            outcomes = {candidates[0]: adopted_outcome}
+            others = [t for t in others if t != candidates[0]]
+        elif len(candidates) > 1:
+            owner = missing[0].split("::", 1)[0]
+            adapter = adapters.build(engine.config.project(owner), engine.worktree)
+            resolved = _disambiguate(candidates, missing[0], adapter)
+            if resolved is not None:
+                engine.ledger.event(
+                    engine.run["id"], cycle["id"], "declared_test_mismatch",
+                    json.dumps({"declared": missing, "adopted": [resolved], "all_candidates": candidates}),
+                )
+                kept = [t for t in targets if t not in missing]
+                engine.ledger.update(
+                    "cycle", cycle["id"], target_tests=json.dumps(kept + [resolved])
+                )
+                cycle = engine.ledger.one("SELECT * FROM cycle WHERE id = ?", (cycle["id"],))
+                adopted_outcome = _outcome_from_verdicts(verdicts, resolved)
+                if adopted_outcome is None:
+                    return _reply(
+                        engine, cycle, Verb.REFACTOR_OR_ADVANCE,
+                        f"Adopted {resolved} as the target (declared {missing[0]} was not"
+                        " collected). Run `tdd advance` again to evaluate it.",
+                        adopted=[resolved],
+                    )
+                targets = kept + [resolved]
+                outcomes = {resolved: adopted_outcome}
+                others = [t for t in others if t != resolved]
+            else:
+                engine.ledger.event(
+                    engine.run["id"], cycle["id"], "multiple_new_tests",
+                    json.dumps(candidates),
+                )
+                return _reply(
+                    engine, cycle, Verb.NAME_TARGET_TEST,
+                    "Several new tests appeared; a cycle covers one behaviour. Name the"
+                    " intended target with `tdd target <id>`.",
+                    candidates=candidates,
+                )
+        else:
             return _reply(
-                engine, cycle, Verb.REFACTOR_OR_ADVANCE,
-                f"Adopted {candidates[0]} as the target (declared {missing[0]} was not"
-                " collected). Run `tdd advance` again to evaluate it.",
-                adopted=candidates,
-            )
-        if len(candidates) > 1:
-            engine.ledger.event(
-                engine.run["id"], cycle["id"], "multiple_new_tests",
-                json.dumps(candidates),
-            )
-            return _reply(
-                engine, cycle, Verb.NAME_TARGET_TEST,
-                "Several new tests appeared; a cycle covers one behaviour. Name the"
-                " intended target with `tdd target <id>`.",
-                candidates=candidates,
+                engine, cycle, Verb.WRITE_TEST,
+                f"Target {missing[0]} was not collected and no new test was found."
+                " Write the failing test.",
+                missing=missing,
             )
-        return _reply(
-            engine, cycle, Verb.WRITE_TEST,
-            f"Target {missing[0]} was not collected and no new test was found."
-            " Write the failing test.",
-            missing=missing,
-        )
 
     not_collected = [t for t, o in outcomes.items() if o == NOT_COLLECTED]
     if not_collected:
@@ -392,7 +466,10 @@ def _handle_refactor(engine: Engine, cycle, retried: bool) -> Envelope:
             },
             result={"commit": sha, "regenerated": regenerated or None},
             next_action=NextAction(
-                Verb.COMPLETE, "All declared cycles are complete. Run `tdd log render`."
+                Verb.COMPLETE,
+                "All declared cycles are complete."
+                " Before rendering, record a closing narrative with `tdd note \"<hardest cycle and why, plan inaccuracies, deviations>\"`."
+                " Then run `tdd log render`.",
             ),
         )
     verb, opening = engine.opening_action(nxt)