tdd-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/CHANGELOG.md

@@ -4,7 +4,50 @@ 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.3.0] - 2026-08-10
+
+### Added
+
+- `env` on `[project.<name>]`: environment for the default suite's runs and
+  collection, with the same semantics as an override's `env` (`${VAR}` expands
+  from the environment at invocation). An override's `env` layers on top for
+  its own suite. Previously only override suites could declare environment,
+  leaving a default suite that reads an endpoint from a variable with no
+  registry-level way to receive it (#16).
+
+### Fixed
+
+- vitest test ids are project-root-relative (`frontend::app/x.test.tsx > name`),
+  matching pytest nodeids and the form plan declarations qualify to — they were
+  worktree-relative (`frontend::frontend/app/...`), so a declared vitest target
+  could never match a verdict: standard cycles limped through on R8.9 adoption
+  (a spurious `declared_test_mismatch` per cycle) and pin cycles deadlocked in
+  `AWAITING_PIN`, since a pre-existing test is never adoptable (#21).
+- `tdd target` refuses a name that is not a collected test in the cycle's
+  projects, suggesting the closest collected ids — previously any string was
+  recorded as the target and failed later, misattributed, as `not_found` (#15).
+- Failure text (`target_failure`, uncollected-suite messages) is clipped keeping
+  both ends instead of truncated from the head: Python puts the actual error at
+  the tail of a traceback, so a head-only cut on a deep stack delivered
+  framework frames and cut exactly the line that says what went wrong (#17).
+
+## [0.2.1] - 2026-08-10
+
+### Added
+
+- `tdd doctor` check `default suite cannot reach override files`: when a
+  project declares overrides, doctor probes the default suite's discovery
+  (pytest: the test command with `--collect-only`; vitest: `vitest list`) and
+  fails if it reaches files an override owns — the premise suite overrides
+  require, which nothing previously enforced.
+
+### Fixed
+
+- A test observed by more than one suite invocation of the union (the default
+  suite's discovery sweeping an override's files, e.g. a bare `pytest` default)
+  is now a loud tooling error naming the overlapping tests and the fix, instead
+  of the target being silently judged by whichever suite reported it first —
+  previously an env-less run whose failure said nothing about the overlap.
 
 ## [0.2.0] - 2026-08-10
 

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tdd-cli
-Version: 0.2.0
+Version: 0.3.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

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/src/tddcli/__init__.py

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

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/src/tddcli/adapters/base.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 import subprocess
+from collections import Counter
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -42,6 +43,41 @@ class Collection:
     failed_files: dict[str, str] = field(default_factory=dict)
 
 
+def _suite_overlap(suite_ids: list[set[str]]) -> list[str]:
+    """Test ids observed by more than one suite invocation of the union (R7.13).
+    Overlap means the default command's discovery reaches files an override
+    owns, so those tests also ran without the override's command/env — and
+    target matching would judge the target by whichever run came first."""
+    counts = Counter(i for ids in suite_ids for i in ids)
+    return sorted(i for i, n in counts.items() if n > 1)
+
+
+def _overlap_error(overlap: list[str]) -> str:
+    shown = ", ".join(overlap[:5])
+    more = f" (and {len(overlap) - 5} more)" if len(overlap) > 5 else ""
+    return (
+        f"observed by more than one suite invocation: {shown}{more}."
+        " The default suite's discovery reaches files an override owns, so"
+        " these tests also ran without the override's command/env. Scope the"
+        " default test_command so it cannot reach them (e.g. pass the default"
+        " test directories explicitly)."
+    )
+
+
+def clip_failure(text: str, limit: int = 1500) -> str:
+    """Clip failure text to `limit`, keeping both ends. Python puts the actual
+    error at the tail of a traceback, so a head-only cut on a deep stack
+    (async frameworks, ORMs, HTTP clients) delivered framework frames and cut
+    exactly the line that says what went wrong — forcing a re-run outside tdd
+    to see an error the tool already had. The head is kept too: for a plain
+    assertion failure the first line carries the assertion itself."""
+    if len(text) <= limit:
+        return text
+    head = limit // 5
+    tail = limit - head
+    return f"{text[:head]}\n… [clipped] …\n{text[-tail:]}"
+
+
 def run_command(
     command: str, cwd: Path, timeout: int = 1800,
     extra_env: dict[str, str] | None = None,
@@ -106,17 +142,19 @@ class Adapter:
         alternate runner config is still observed — without widening the default
         config, which is exactly the workaround that breaks CI.
         """
-        return [(self._test_cmd(), None)] + [
-            (ov.test_command, self._override_env(ov)) for ov in self.project.overrides
+        return [(self._test_cmd(), self._suite_env(None))] + [
+            (ov.test_command, self._suite_env(ov)) for ov in self.project.overrides
         ]
 
-    @staticmethod
-    def _override_env(override) -> dict[str, str] | None:
-        """`${VAR}` references resolve from the environment at invocation time, so a
-        port assigned by the harness need not be hard-coded in the reviewed file."""
-        if override is None or not override.env:
+    def _suite_env(self, override) -> dict[str, str] | None:
+        """The environment for one suite invocation: the project's `env`, with the
+        owning override's layered on top (None means the default suite). `${VAR}`
+        references resolve from the environment at invocation time, so a port
+        assigned per checkout need not be hard-coded in the reviewed file."""
+        merged = {**self.project.env, **(override.env if override else {})}
+        if not merged:
             return None
-        return {k: os.path.expandvars(v) for k, v in override.env.items()}
+        return {k: os.path.expandvars(v) for k, v in merged.items()}
 
     def stub_hint(self) -> str:
         """The language idiom for a stub body, quoted into the create_stub directive."""
@@ -128,6 +166,15 @@ class Adapter:
     def collectable(self) -> GateResult:
         raise NotImplementedError
 
+    def override_isolation(self) -> GateResult:
+        """Whether the default suite's discovery stays out of files an override
+        owns (R7.13's premise). Overlap means runs observe those tests without
+        the override's command/env — and the union then holds the same test
+        twice with conflicting outcomes. Adapters with a way to probe discovery
+        override this; the base answer is ok so third-party adapters without a
+        probe don't fail doctor."""
+        return GateResult(ok=True)
+
     def lint(self) -> GateResult:
         return self._gate(self.project.lint)
 

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/src/tddcli/adapters/pytest_adapter.py

@@ -25,6 +25,9 @@ from .base import (
     Collection,
     GateResult,
     Verdict,
+    _overlap_error,
+    _suite_overlap,
+    clip_failure,
     run_command,
 )
 
@@ -100,6 +103,7 @@ class PytestAdapter(Adapter):
         # agent to rewrite a test that is fine.
         tests: list[dict] = []
         collectors: list[dict] = []
+        suite_ids: list[set[str]] = []
         for base_cmd, extra_env in self._suite_invocations():
             report, error = self._suite_report(base_cmd, extra_env)
             if report is None:
@@ -108,6 +112,12 @@ class PytestAdapter(Adapter):
             verdict.duration_ms += int(report.get("duration", 0) * 1000)
             tests.extend(report.get("tests", []))
             collectors.extend(report.get("collectors", []))
+            suite_ids.append({t["nodeid"] for t in report.get("tests", [])})
+
+        overlap = _suite_overlap(suite_ids)
+        if overlap:
+            verdict.error = _overlap_error(overlap)
+            return verdict
 
         uncollectable: set[str] = set()
         for collector in collectors:
@@ -130,12 +140,14 @@ 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 = str(call.get("longrepr", ""))[:1500]
+            verdict.target_failure = clip_failure(str(call.get("longrepr", "")))
         else:
             target_file = native.split("::", 1)[0]
             if any(c == target_file or c.startswith(target_file) for c in uncollectable):
                 verdict.target_outcome = NOT_COLLECTED
-                verdict.target_failure = self._collector_error(collectors, target_file)[:1500]
+                verdict.target_failure = clip_failure(
+                    self._collector_error(collectors, target_file)
+                )
             else:
                 verdict.target_outcome = NOT_FOUND
         return verdict
@@ -153,8 +165,8 @@ class PytestAdapter(Adapter):
         `test_command` — pytest's `--collect-only` composes with any run command."""
         ov = self.project.override_for(rel)
         if ov is None:
-            return self._collect_cmd(), None
-        return ov.collect_command or ov.test_command, self._override_env(ov)
+            return self._collect_cmd(), self._suite_env(None)
+        return ov.collect_command or ov.test_command, self._suite_env(ov)
 
     def _test_files(self) -> list[Path]:
         found: list[Path] = []
@@ -181,8 +193,8 @@ class PytestAdapter(Adapter):
         loses the real error and the failure surfaces unattributed.
         """
         chunks = []
-        probes = [(self._collect_cmd(), None)] + [
-            (ov.collect_command or ov.test_command, self._override_env(ov))
+        probes = [(self._collect_cmd(), self._suite_env(None))] + [
+            (ov.collect_command or ov.test_command, self._suite_env(ov))
             for ov in self.project.overrides
         ]
         for cmd, env in probes:
@@ -193,6 +205,34 @@ class PytestAdapter(Adapter):
                 chunks.append(out.strip())
         return GateResult(ok=not chunks, output="\n\n".join(chunks)[:2000])
 
+    def override_isolation(self) -> GateResult:
+        """Probes the *test* command's discovery, not `collect_command`'s: the
+        test command is what runs at suite time, and a scoped `test_command`
+        with a bare per-file `collect_command` is a legitimate registry (the
+        per-file command always gets an explicit path). `{workers}` becomes 0 —
+        xdist's "no workers" — since discovery needs no parallelism. A probe
+        that fails to collect at all is `collectable`'s finding, not this one's."""
+        if not self.project.overrides:
+            return GateResult(ok=True)
+        probe = f"{self._test_cmd().replace('{workers}', '0')} --collect-only -q"
+        code, out, err = run_command(probe, self.root, extra_env=self._suite_env(None))
+        reached = sorted({
+            f for f in (
+                line.split("::", 1)[0]
+                for line in out.splitlines()
+                if "::" in line
+            )
+            if self.project.override_for(f)
+        })
+        if not reached:
+            return GateResult(ok=True)
+        return GateResult(ok=False, output=(
+            "the default suite's discovery reaches files an override owns, so"
+            " suite runs would observe them without the override's command/env:"
+            f" {', '.join(reached[:5])}. Scope the default test_command so it"
+            " cannot reach them (e.g. `pytest tests/`)."
+        ))
+
     def collect(self) -> Collection:
         """Per file (R10.3) — one uncollectable module must not destroy the whole set."""
         result = Collection()

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/src/tddcli/adapters/vitest_adapter.py

@@ -1,8 +1,11 @@
 """vitest adapter.
 
-Test ids are `<worktree-relative file> > <fullName>`, where fullName is the
-space-joined ancestorTitles plus the test title. vitest may prefix its JSON with
-non-JSON lines, so the payload is located rather than assumed (R10.2).
+Test ids are `<project-root-relative file> > <fullName>`, where fullName is the
+space-joined ancestorTitles plus the test title. Root-relative matches the pytest
+adapter's nodeids and — decisively — `Engine._qualify`, which strips the project
+root from plan declarations; a worktree-relative id here can never equal a
+declared target. vitest may prefix its JSON with non-JSON lines, so the payload
+is located rather than assumed (R10.2).
 """
 
 from __future__ import annotations
@@ -21,6 +24,9 @@ from .base import (
     Collection,
     GateResult,
     Verdict,
+    _overlap_error,
+    _suite_overlap,
+    clip_failure,
     run_command,
 )
 
@@ -44,7 +50,7 @@ class VitestAdapter(Adapter):
     def _id_for(self, suite_path: str, full_name: str) -> str:
         abs_path = Path(suite_path)
         try:
-            rel = os.path.relpath(abs_path, self.worktree)
+            rel = os.path.relpath(abs_path, self.root)
         except ValueError:
             rel = suite_path
         return self.qualify(f"{rel} > {full_name}")
@@ -61,6 +67,7 @@ class VitestAdapter(Adapter):
         # producing no JSON is a loud error, not a silent gap: swallowing it would
         # report a target living in that suite as `not_found`.
         suites: list[dict] = []
+        suite_ids: list[set[str]] = []
         for base, extra_env in self._suite_invocations():
             code, out, err = self._run_suite(f"{base} --reporter=json", extra_env)
             report = _extract_json(out)
@@ -70,7 +77,18 @@ class VitestAdapter(Adapter):
                 )
                 return verdict
             verdict.duration_ms += int(report.get("duration") or 0)
-            suites.extend(report.get("testResults", []))
+            results = report.get("testResults", [])
+            suites.extend(results)
+            suite_ids.append({
+                self._id_for(s.get("name", ""), t["fullName"])
+                for s in results
+                for t in s.get("assertionResults", [])
+            })
+
+        overlap = _suite_overlap(suite_ids)
+        if overlap:
+            verdict.error = _overlap_error(overlap)
+            return verdict
 
         failed_suites: dict[str, str] = {}
 
@@ -78,7 +96,7 @@ class VitestAdapter(Adapter):
             suite_path = suite.get("name", "")
             assertions = suite.get("assertionResults", [])
             if not assertions and suite.get("status") == "failed":
-                failed_suites[suite_path] = str(suite.get("message", ""))[:1500]
+                failed_suites[suite_path] = clip_failure(str(suite.get("message", "")))
             for t in assertions:
                 qualified = self._id_for(suite_path, t["fullName"])
                 if t["status"] == "passed":
@@ -99,7 +117,8 @@ class VitestAdapter(Adapter):
                 for t in suite.get("assertionResults", []):
                     if self._id_for(suite.get("name", ""), t["fullName"]) == target:
                         verdict.target_failure = "\n".join(
-                            m[:600] for m in t.get("failureMessages", [])[:3]
+                            clip_failure(m, 600)
+                            for m in t.get("failureMessages", [])[:3]
                         )
             return verdict
 
@@ -157,7 +176,9 @@ class VitestAdapter(Adapter):
         suite — against a live backend — just to enumerate it.
         """
         chunks = []
-        code, out, err = run_command(self._collect_cmd(), self.root)
+        code, out, err = run_command(
+            self._collect_cmd(), self.root, extra_env=self._suite_env(None)
+        )
         if code != 0:
             chunks.append((err or out).strip())
         for ov in self.project.overrides:
@@ -169,12 +190,39 @@ class VitestAdapter(Adapter):
                 )
                 continue
             code, out, err = run_command(
-                ov.collect_command, self.root, extra_env=self._override_env(ov)
+                ov.collect_command, self.root, extra_env=self._suite_env(ov)
             )
             if code != 0:
                 chunks.append((err or out).strip())
         return GateResult(ok=not chunks, output="\n\n".join(chunks)[:2000])
 
+    def override_isolation(self) -> GateResult:
+        """Probes with the default `vitest list` — the same stand-in for the
+        default run config that `collectable()` already relies on (`vitest run`
+        has no listing mode, and running the suite just to enumerate it would
+        execute against whatever the tests need live)."""
+        if not self.project.overrides:
+            return GateResult(ok=True)
+        code, out, err = run_command(
+            self._collect_cmd(), self.root, extra_env=self._suite_env(None)
+        )
+        reached = sorted({
+            f for f in (
+                line.strip().partition(" > ")[0]
+                for line in out.splitlines()
+                if " > " in line
+            )
+            if self.project.override_for(f)
+        })
+        if not reached:
+            return GateResult(ok=True)
+        return GateResult(ok=False, output=(
+            "the default config's discovery reaches files an override owns, so"
+            " suite runs would observe them without the override's command/env:"
+            f" {', '.join(reached[:5])}. Exclude them from the default vitest"
+            " config (test.exclude) or scope its include globs."
+        ))
+
     def collect(self) -> Collection:
         result = Collection()
         for path in self._test_files():
@@ -187,7 +235,7 @@ class VitestAdapter(Adapter):
                 )
                 continue
             base = ov.collect_command if ov else self._collect_cmd()
-            env = self._override_env(ov)
+            env = self._suite_env(ov)
             code, out, err = run_command(
                 f"{base} {shlex.quote(str(rel))}", self.root, extra_env=env
             )

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/src/tddcli/cli.py

@@ -6,6 +6,7 @@ No command accepts a phase, a cycle number, or executor identity (R8.3).
 from __future__ import annotations
 
 import argparse
+import difflib
 import json
 import os
 import socket
@@ -275,6 +276,16 @@ def cmd_doctor(args) -> Envelope:
         gate = adapter.collectable()
         check("collectable", gate.ok, gate.output, project=name)
 
+        # R7.13's premise — "files the default runner config cannot reach" — is
+        # a config property nothing else enforces. Probe it at preflight so the
+        # overlap is named here, not discovered as an opaque mid-cycle failure.
+        if project.overrides:
+            gate = adapter.override_isolation()
+            check(
+                "default suite cannot reach override files",
+                gate.ok, gate.output, project=name,
+            )
+
         projects[name] = {"ok": all(c["ok"] for c in checks[before:])}
 
     for art in cfg.artifacts.values():
@@ -812,6 +823,23 @@ def cmd_target(args) -> Envelope:
     cycle = ledger.open_cycle(run["id"])
     if cycle is None:
         return failure("no open cycle")
+
+    # The target must be grounded in observed collection, the same way phase is
+    # grounded in observed execution (#15): recording free text deferred a typo —
+    # or a speculative `tdd target env` — to the next suite run, where it
+    # surfaced as `not_found` against a test that never existed.
+    known: set[str] = set()
+    for name in json.loads(cycle["projects"]):
+        adapter = adapters.build(cfg.project(name), worktree)
+        known |= adapter.collect().tests
+    if args.test not in known:
+        close = difflib.get_close_matches(args.test, sorted(known), n=3, cutoff=0.6)
+        hint = f" Closest collected ids: {', '.join(close)}." if close else ""
+        return failure(
+            f"{args.test} is not a collected test in this cycle's projects;"
+            f" the target was not changed.{hint}"
+        )
+
     ledger.update("cycle", cycle["id"], target_tests=json.dumps([args.test]))
     ledger.event(run["id"], cycle["id"], "target_named_by_agent", args.test)
     return Envelope(

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/src/tddcli/config.py

@@ -88,6 +88,11 @@ class Project:
     #: Per-file collection. Must not be parallelised: collection is cheap and xdist
     #: adds startup cost per file.
     collect_command: str | None = None
+    #: Environment for the default suite's runs and collection, same semantics as
+    #: an override's `env`: `${VAR}` references expand from the environment at
+    #: invocation, so per-checkout values (a database port) stay out of the
+    #: reviewed file. An override's `env` layers on top for its own suite.
+    env: dict[str, str] = field(default_factory=dict)
     #: Alternate suites for files the default command cannot reach (R7.13).
     overrides: list[Override] = field(default_factory=list)
 
@@ -290,6 +295,13 @@ def load(worktree: Path) -> Config:
             raise ConfigError(f"project {name!r} has no root")
         if "adapter" not in body:
             raise ConfigError(f"project {name!r} has no adapter")
+        env = body.get("env", {})
+        if not isinstance(env, dict) or not all(
+            isinstance(v, str) for v in env.values()
+        ):
+            raise ConfigError(
+                f"project {name!r}: env must be a table of string values"
+            )
         projects[name] = Project(
             name=name,
             root=body["root"].rstrip("/"),
@@ -300,6 +312,7 @@ def load(worktree: Path) -> Config:
             in_close_sweep=body.get("in_close_sweep", True),
             test_command=body.get("test_command"),
             collect_command=body.get("collect_command"),
+            env=env,
             overrides=_load_overrides(name, body.get("override", [])),
         )
 

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/tests/test_doctor_attribution.py

@@ -73,3 +73,46 @@ def test_doctor_does_not_check_node_modules_for_a_pytest_project(repo_multi):
     backend_checks = [c for c in checks if c.get("project") == "backend"]
     assert backend_checks, checks
     assert not any(c["check"] == "node_modules present" for c in backend_checks), backend_checks
+
+
+def test_doctor_flags_a_default_suite_that_reaches_override_files(repo):
+    """R7.13's premise — "files the default runner config cannot reach" — is a
+    config property nothing else enforces. With a bare `pytest` default, its own
+    discovery sweeps the override directory, and every run would observe those
+    tests without the override's command/env. Doctor must name the overlap at
+    preflight instead of leaving it to fail opaquely mid-cycle."""
+    (repo / "backend" / "contract").mkdir()
+    (repo / "backend" / "contract" / "test_api.py").write_text(
+        "def test_ping():\n    assert True\n"
+    )
+    (repo / "tdd.toml").write_text(
+        "[project.backend]\n"
+        'root       = "backend"\n'
+        'adapter    = "pytest"\n'
+        'test_paths = ["tests/"]\n'
+        "[[project.backend.override]]\n"
+        'pattern      = "contract/"\n'
+        'test_command = "pytest contract"\n'
+    )
+    out = run_cli(repo, "doctor")
+    isolation = [
+        c for c in out["result"]["checks"]
+        if c["check"] == "default suite cannot reach override files"
+    ]
+    assert len(isolation) == 1
+    assert isolation[0]["ok"] is False
+    assert isolation[0]["project"] == "backend"
+    assert "contract/test_api.py" in isolation[0]["detail"]
+
+    scoped = (repo / "tdd.toml").read_text().replace(
+        'test_paths = ["tests/"]\n',
+        'test_paths = ["tests/"]\ntest_command = "pytest tests"\n',
+    )
+    (repo / "tdd.toml").write_text(scoped)
+    out = run_cli(repo, "doctor")
+    isolation = [
+        c for c in out["result"]["checks"]
+        if c["check"] == "default suite cannot reach override files"
+    ]
+    assert len(isolation) == 1
+    assert isolation[0]["ok"] is True

tdd_cli-0.3.0/tests/test_failure_clipping.py

@@ -0,0 +1,64 @@
+"""Failure text keeps the tail, where Python puts the error (#17).
+
+`target_failure` was truncated to a fixed budget from the head. Deep tracebacks
+(async frameworks, ORMs, HTTP stacks) exceed it easily, delivering frames of
+framework internals and cutting exactly the line that says what went wrong —
+forcing a manual re-run outside tdd to see an error the tool already had.
+Both ends are kept: the head carries the assertion line for plain failures,
+the tail carries the exception for deep ones.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from tddcli import adapters
+from tddcli import config as config_mod
+from tddcli.adapters.base import clip_failure
+
+
+def test_short_text_passes_through_unclipped():
+    assert clip_failure("boom", 1500) == "boom"
+
+
+def test_long_text_keeps_both_ends_and_marks_the_elision():
+    text = "assert first line\n" + ("framework frame\n" * 200) + "ConnectionRefusedError: [Errno 61]"
+    clipped = clip_failure(text, 1500)
+    assert len(clipped) <= 1500 + 20   # the marker is the only overhead
+    assert clipped.startswith("assert first line")
+    assert clipped.endswith("ConnectionRefusedError: [Errno 61]")
+    assert "…" in clipped
+
+
+def _pytest_adapter(tmp_path):
+    (tmp_path / "tdd.toml").write_text(
+        "[project.backend]\n"
+        'root         = "backend"\n'
+        'adapter      = "pytest"\n'
+        'test_paths   = ["tests/"]\n'
+        'test_command = "pytest tests"\n'
+    )
+    return adapters.build(config_mod.load(tmp_path).project("backend"), tmp_path)
+
+
+def test_pytest_target_failure_keeps_the_error_at_the_tail(tmp_path, monkeypatch):
+    adapter = _pytest_adapter(tmp_path)
+    longrepr = ("connector frame\n" * 300) + "ConnectionRefusedError: [Errno 61]"
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        marker = "--json-report-file="
+        path = command.split(marker, 1)[1].split(" --", 1)[0]
+        Path(path.strip("'\"")).write_text(json.dumps({
+            "tests": [{
+                "nodeid": "tests/test_db.py::test_connects",
+                "outcome": "failed",
+                "call": {"longrepr": longrepr},
+            }],
+        }))
+        return 1, "", ""
+
+    monkeypatch.setattr(adapters.base, "run_command", fake)
+    verdict = adapter.run("backend::tests/test_db.py::test_connects")
+    assert verdict.target_failure.endswith("ConnectionRefusedError: [Errno 61]")
+    assert len(verdict.target_failure) <= 1520

tdd_cli-0.3.0/tests/test_project_env.py

@@ -0,0 +1,124 @@
+"""Per-project `env` for the default suite (#16).
+
+Override suites gained an `env` mapping in 0.2.0 because suite commands
+sometimes need environment the invoking shell doesn't have. That need is not
+specific to override suites: a default suite that reads an infrastructure
+endpoint from a variable (a database port varying per worktree being the
+motivating shape) previously had no registry-level way to receive it — the
+workarounds were baking values into `test_command`, teaching the suite's own
+bootstrap to hunt for env files, or exporting variables invisibly in whatever
+shell runs `tdd advance`.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest as pytest_framework
+
+from tddcli import adapters
+from tddcli import config as config_mod
+from tddcli.config import ConfigError
+
+
+def project_with(tmp_path: Path, extra: str, adapter: str = "pytest"):
+    (tmp_path / "tdd.toml").write_text(
+        "[project.backend]\n"
+        'root       = "backend"\n'
+        f'adapter    = "{adapter}"\n'
+        'test_paths = ["tests/"]\n' + extra
+    )
+    return config_mod.load(tmp_path).project("backend")
+
+
+def test_project_env_is_parsed_from_the_registry(tmp_path):
+    project = project_with(
+        tmp_path, 'env = { TEST_DB_PORT = "${DB_PORT}" }\n'
+    )
+    assert project.env == {"TEST_DB_PORT": "${DB_PORT}"}
+
+
+def test_project_env_must_be_string_valued(tmp_path):
+    with pytest_framework.raises(ConfigError, match="env must be a table"):
+        project_with(tmp_path, "env = { PORT = 6032 }\n")
+
+
+def test_default_suite_runs_with_the_project_env_expanded(tmp_path, monkeypatch):
+    monkeypatch.setenv("DB_PORT", "6032")
+    project = project_with(
+        tmp_path,
+        'test_command = "pytest tests"\n'
+        'env = { TEST_DB_PORT = "${DB_PORT}" }\n',
+    )
+    adapter = adapters.build(project, tmp_path)
+    seen: list = []
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        seen.append((command, extra_env))
+        marker = "--json-report-file="
+        path = command.split(marker, 1)[1].split(" --", 1)[0]
+        Path(path.strip("'\"")).write_text(json.dumps({"tests": []}))
+        return 0, "", ""
+
+    monkeypatch.setattr(adapters.base, "run_command", fake)
+    adapter.run(None)
+    ((_, env),) = seen
+    assert env["TEST_DB_PORT"] == "6032"
+
+
+def test_override_env_layers_on_top_of_the_project_env(tmp_path, monkeypatch):
+    monkeypatch.setenv("DB_PORT", "6032")
+    project = project_with(
+        tmp_path,
+        'test_command = "pytest tests"\n'
+        'env = { TEST_DB_PORT = "${DB_PORT}", SHARED = "from-project" }\n'
+        "[[project.backend.override]]\n"
+        'pattern      = "contract/"\n'
+        'test_command = "pytest contract"\n'
+        'env          = { SHARED = "from-override" }\n',
+    )
+    adapter = adapters.build(project, tmp_path)
+    invocations = adapter._suite_invocations()
+    assert invocations[0][1] == {"TEST_DB_PORT": "6032", "SHARED": "from-project"}
+    assert invocations[1][1] == {"TEST_DB_PORT": "6032", "SHARED": "from-override"}
+
+
+def test_pytest_collection_of_default_files_carries_the_project_env(
+    tmp_path, monkeypatch
+):
+    project = project_with(tmp_path, 'env = { TEST_DB_PORT = "6032" }\n')
+    (tmp_path / "backend" / "tests").mkdir(parents=True)
+    (tmp_path / "backend" / "tests" / "test_a.py").write_text(
+        "def test_a(): pass\n"
+    )
+    adapter = adapters.build(project, tmp_path)
+    seen: list = []
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        seen.append((command, extra_env))
+        return 0, "tests/test_a.py::test_a\n", ""
+
+    monkeypatch.setattr(adapters.pytest_adapter, "run_command", fake)
+    adapter.collect()
+    assert seen and all(env == {"TEST_DB_PORT": "6032"} for _, env in seen)
+
+
+def test_vitest_default_suite_runs_with_the_project_env(tmp_path, monkeypatch):
+    project = project_with(
+        tmp_path,
+        'test_command = "npx vitest run"\n'
+        'env = { API_URL = "http://localhost:6032" }\n',
+        adapter="vitest",
+    )
+    adapter = adapters.build(project, tmp_path)
+    seen: list = []
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        seen.append((command, extra_env))
+        return 0, json.dumps({"testResults": []}), ""
+
+    monkeypatch.setattr(adapters.base, "run_command", fake)
+    adapter.run(None)
+    ((_, env),) = seen
+    assert env["API_URL"] == "http://localhost:6032"

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/tests/test_suite_overrides.py

@@ -286,12 +286,12 @@ def test_vitest_run_finds_a_target_that_only_the_override_config_reaches(
         return 1, json.dumps(report), ""
 
     monkeypatch.setattr(adapters.base, "run_command", fake)
-    target = "backend::backend/contract/api.contract.test.ts > pings the api"
+    target = "backend::contract/api.contract.test.ts > pings the api"
     verdict = adapter.run(target)
     assert verdict.error is None
     assert verdict.target_outcome == "failed"
     assert verdict.target_failure == "nope"
-    assert verdict.passed == ["backend::backend/unit.test.ts > adds"]
+    assert verdict.passed == ["backend::unit.test.ts > adds"]
 
 
 def test_vitest_override_without_collect_command_fails_the_collectable_gate(
@@ -338,7 +338,7 @@ def test_vitest_collection_routes_override_files_to_the_override_command(
     monkeypatch.setattr(adapters.vitest_adapter, "run_command", fake)
     collection = adapter.collect()
     assert collection.tests == {
-        "backend::backend/contract/api.contract.test.ts > pings the api"
+        "backend::contract/api.contract.test.ts > pings the api"
     }
     assert seen[0].startswith("npx vitest list --config vitest.contract.config.ts ")
 
@@ -404,3 +404,182 @@ def test_a_cycle_can_target_a_test_only_an_override_suite_reaches(repo):
     )
     green = run_cli(repo, "advance")
     assert green["next_action"]["verb"] == "refactor_or_advance", green
+
+
+# -- overlap between the default suite and an override suite -------------
+#
+# The feature's premise is "files the default runner config cannot reach". A
+# bare default command (plain `pytest`) quietly breaks that premise: its own
+# discovery sweeps the override directories, the union then holds the same test
+# twice — once observed without the override's command/env — and target
+# matching judged the target by whichever suite reported it first. That failure
+# is opaque (the test fails on some downstream assertion, nothing names the
+# overlap), so it must be a loud typed error instead.
+
+
+def test_pytest_duplicate_nodeid_across_suites_is_a_loud_error(
+    tmp_path, monkeypatch
+):
+    project = project_with(
+        tmp_path, 'test_command = "pytest"\n' + OVERRIDE_BLOCK
+    )
+    adapter = adapters.build(project, tmp_path)
+    duplicated = {
+        "nodeid": "contract/test_api.py::test_ping",
+        "outcome": "failed",
+        "call": {"longrepr": "assert None == '1'"},
+    }
+    monkeypatch.setattr(
+        adapters.base,
+        "run_command",
+        _fake_pytest_run(
+            {
+                # Bare default discovery sweeps contract/ too.
+                "pytest --json-report": {"duration": 1.0, "tests": [duplicated]},
+                "pytest contract": {
+                    "duration": 2.0,
+                    "tests": [dict(duplicated, outcome="passed")],
+                },
+            },
+            [],
+        ),
+    )
+    verdict = adapter.run("backend::contract/test_api.py::test_ping")
+    assert verdict.error is not None
+    assert "contract/test_api.py::test_ping" in verdict.error
+    assert "more than one suite" in verdict.error
+    assert "test_command" in verdict.error
+
+
+def test_vitest_duplicate_test_id_across_suites_is_a_loud_error(
+    tmp_path, monkeypatch
+):
+    project = project_with(
+        tmp_path,
+        'test_command = "npx vitest run"\n'
+        "[[project.backend.override]]\n"
+        'pattern         = "contract/"\n'
+        'test_command    = "npx vitest run --config vitest.contract.config.ts"\n'
+        'collect_command = "npx vitest list --config vitest.contract.config.ts"\n',
+        adapter="vitest",
+    )
+    adapter = adapters.build(project, tmp_path)
+    suite_path = str(tmp_path / "backend" / "contract" / "api.test.ts")
+
+    def result(status):
+        return {
+            "testResults": [
+                {
+                    "name": suite_path,
+                    "status": status,
+                    "assertionResults": [
+                        {"fullName": "pings", "status": status}
+                    ],
+                }
+            ]
+        }
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        if "--config" in command:
+            return 0, json.dumps(result("passed")), ""
+        return 1, json.dumps(result("failed")), ""
+
+    monkeypatch.setattr(adapters.base, "run_command", fake)
+    verdict = adapter.run("backend::contract/api.test.ts > pings")
+    assert verdict.error is not None
+    assert "contract/api.test.ts > pings" in verdict.error
+    assert "more than one suite" in verdict.error
+
+
+def test_pytest_isolation_probe_flags_default_reach_into_override_files(
+    tmp_path, monkeypatch
+):
+    project = project_with(
+        tmp_path, 'test_command = "pytest -n {workers}"\n' + OVERRIDE_BLOCK
+    )
+    adapter = adapters.build(project, tmp_path)
+    seen: list = []
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        seen.append(command)
+        return 0, (
+            "tests/test_a.py::test_a\n"
+            "contract/test_api.py::test_ping\n"
+            "2 tests collected in 0.01s\n"
+        ), ""
+
+    monkeypatch.setattr(adapters.pytest_adapter, "run_command", fake)
+    gate = adapter.override_isolation()
+    assert gate.ok is False
+    assert "contract/test_api.py" in gate.output
+    assert "test_command" in gate.output
+    # The probe asks the *test* command what it would discover — that is the
+    # command whose reach matters at run time — with parallelism disabled.
+    assert seen == ["pytest -n 0 --collect-only -q"]
+
+
+def test_pytest_isolation_probe_passes_when_the_default_suite_is_scoped(
+    tmp_path, monkeypatch
+):
+    project = project_with(
+        tmp_path, 'test_command = "pytest tests"\n' + OVERRIDE_BLOCK
+    )
+    adapter = adapters.build(project, tmp_path)
+    monkeypatch.setattr(
+        adapters.pytest_adapter,
+        "run_command",
+        lambda command, cwd, timeout=1800, extra_env=None: (
+            0, "tests/test_a.py::test_a\n", ""
+        ),
+    )
+    gate = adapter.override_isolation()
+    assert gate.ok is True
+
+
+def test_vitest_isolation_probe_flags_default_reach_into_override_files(
+    tmp_path, monkeypatch
+):
+    project = project_with(
+        tmp_path,
+        "[[project.backend.override]]\n"
+        'pattern         = "contract/"\n'
+        'test_command    = "npx vitest run --config vitest.contract.config.ts"\n'
+        'collect_command = "npx vitest list --config vitest.contract.config.ts"\n',
+        adapter="vitest",
+    )
+    adapter = adapters.build(project, tmp_path)
+    seen: list = []
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        seen.append(command)
+        return 0, (
+            "src/__tests__/a.test.ts > adds\n"
+            "contract/api.test.ts > pings\n"
+        ), ""
+
+    monkeypatch.setattr(adapters.vitest_adapter, "run_command", fake)
+    gate = adapter.override_isolation()
+    assert gate.ok is False
+    assert "contract/api.test.ts" in gate.output
+    assert seen == ["npx vitest list"]
+
+
+def test_isolation_probe_is_free_when_a_project_declares_no_overrides(
+    tmp_path, monkeypatch
+):
+    project = project_with(tmp_path, 'test_command = "pytest tests"\n')
+    adapter = adapters.build(project, tmp_path)
+
+    def explode(command, cwd, timeout=1800, extra_env=None):
+        raise AssertionError("no probe should run without overrides")
+
+    monkeypatch.setattr(adapters.pytest_adapter, "run_command", explode)
+    assert adapter.override_isolation().ok is True
+
+
+def test_overlap_error_truncates_past_five_ids():
+    ids = [f"contract/test_api.py::test_{i}" for i in range(7)]
+    message = adapters.base._overlap_error(ids)
+    assert "test_4" in message and "test_5" not in message
+    assert "and 2 more" in message
+    assert "test_command" in message

tdd_cli-0.3.0/tests/test_target_validation.py

@@ -0,0 +1,55 @@
+"""`tdd target` must refuse a name that is not a collected test (#15).
+
+The command previously recorded whatever string it was given. A typo — or an
+agent probing the CLI surface with something like `tdd target env` — silently
+*changed the target* to a nonexistent test, deferred the failure to the next
+suite run, and misattributed it as `not_found`, pointing the executor at a test
+that was never supposed to exist. Phase is derived from observed execution;
+the target must be grounded in observed collection the same way.
+"""
+
+from __future__ import annotations
+
+from conftest import run_cli, write_plan
+
+PLAN = """---
+cycles:
+  - n: 1
+    project: backend
+    title: "adding two numbers"
+    test: "tests/test_add.py::test_add_two_numbers"
+    stub_expected: ["app/calc.py"]
+    commit_red: "test: adding two numbers"
+    commit_green: "feat: add()"
+---
+
+# Plan
+"""
+
+
+def start(repo):
+    plan = write_plan(repo, PLAN)
+    assert run_cli(repo, "plan", "register", plan)["ok"]
+    started = run_cli(repo, "run", "start", "--plan", plan)
+    assert started["ok"], started
+
+
+def test_target_refuses_a_name_that_is_not_a_collected_test(repo):
+    start(repo)
+    out = run_cli(repo, "target", "env")
+    assert out["ok"] is False
+    assert "not a collected test" in out["error"]
+
+
+def test_target_suggests_the_closest_collected_ids_on_a_near_miss(repo):
+    start(repo)
+    out = run_cli(repo, "target", "backend::tests/test_smoke.py::test_smok")
+    assert out["ok"] is False
+    assert "backend::tests/test_smoke.py::test_smoke" in out["error"]
+
+
+def test_target_accepts_a_collected_test(repo):
+    start(repo)
+    out = run_cli(repo, "target", "backend::tests/test_smoke.py::test_smoke")
+    assert out["ok"] is True, out
+    assert out["result"]["target"] == "backend::tests/test_smoke.py::test_smoke"

{tdd_cli-0.2.0 → tdd_cli-0.3.0}/tests/test_vitest_adapter.py

@@ -56,11 +56,39 @@ def test_parsed_ids_match_the_form_run_produces(tmp_path):
     assert from_run in from_list, sorted(from_list)
 
 
-def test_ids_are_project_namespaced_and_worktree_relative(tmp_path):
+def test_ids_are_project_namespaced_and_root_relative(tmp_path):
+    """The path inside the id is project-root-relative, like a pytest nodeid.
+
+    Found live: ids were worktree-relative (`frontend::frontend/app/...`) while
+    `Engine._qualify` strips the root prefix from plan declarations
+    (`frontend::app/...`), so a declared vitest target could never match a
+    verdict. Standard cycles limped through on R8.9 adoption; pin cycles
+    deadlocked in AWAITING_PIN because the pinned test predates the run.
+    """
     adapter = adapter_for(tmp_path)
     path = tmp_path / "frontend" / "contexts" / "__tests__" / "AuthContext.test.tsx"
     one = next(iter(adapter._parse_list_output(LIST_OUTPUT, path)))
-    assert one.startswith("frontend::frontend/contexts/__tests__/AuthContext.test.tsx > ")
+    assert one.startswith("frontend::contexts/__tests__/AuthContext.test.tsx > ")
+
+
+def test_ids_match_what_a_plan_declaration_qualifies_to(tmp_path):
+    """A plan declaring `frontend/contexts/... > name` must hit the adapter's id."""
+    from tddcli.contract import DeclaredCycle
+    from tddcli.machine import Engine
+
+    adapter = adapter_for(tmp_path)
+    path = tmp_path / "frontend" / "contexts" / "__tests__" / "AuthContext.test.tsx"
+    declared = DeclaredCycle(
+        ordinal=1,
+        kind="pin",
+        projects=["frontend"],
+        tests=[
+            "frontend/contexts/__tests__/AuthContext.test.tsx"
+            " > logout clears the stored token"
+        ],
+    )
+    qualified = Engine._qualify(declared, declared.tests[0])
+    assert qualified in adapter._parse_list_output(LIST_OUTPUT, path)
 
 
 def test_arrows_are_not_left_in_the_name(tmp_path):