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

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

@@ -6,6 +6,19 @@ and the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-10
+
+### Added
+
+- Per-pattern suite overrides (`[[project.<name>.override]]` in `tdd.toml`): an
+  alternate `test_command` — plus optional `collect_command` and `env` — for
+  files the default runner config cannot reach, such as contract tests that need
+  a live backend. Collection and suite runs union the default suite with every
+  override suite, so a cycle can target such a test without widening the default
+  config (which breaks CI and pollutes target adoption with the other suite's
+  tests). Override patterns classify their files as tests without being repeated
+  in `test_paths`; `env` values may reference `${VAR}`, expanded at invocation.
+
 ## [0.1.0] - 2026-08-08
 
 Initial release.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tdd-cli
-Version: 0.1.0
+Version: 0.2.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
@@ -132,6 +132,35 @@ generated   = true                   # excluded from authorship accounting
 A generator that is never hand-edited (`codegen`) is an artifact regeneration command, not a
 project. It has no tests and no cycles.
 
+Some tests intentionally live outside the project's default runner config — contract tests
+that need a live backend being the common case, where CI runs the default suite with no
+backend up. Widening the default config to make such a test collectable is the wrong fix:
+the plain suite starts making real network calls, and the other suite's tests pollute
+target adoption. Instead, declare an override per pattern:
+
+```toml
+[project.frontend]
+root         = "frontend"
+adapter      = "vitest"
+test_paths   = ["**/*.test.ts"]
+test_command = "npx vitest run"
+
+[[project.frontend.override]]
+pattern         = "src/__contract__/"
+test_command    = "npx vitest run --config vitest.contract.config.ts"
+collect_command = "npx vitest list --config vitest.contract.config.ts"
+env             = { API_URL = "http://localhost:${API_PORT}" }
+```
+
+Collection and suite runs union the default suite with every override suite, so a cycle can
+target a test only the alternate config reaches. Patterns match paths relative to the
+project root with `test_paths` semantics, and override files classify as tests without
+being repeated in `test_paths`. `env` values may reference `${VAR}`, expanded from the
+environment at invocation. For pytest, `collect_command` is optional (`--collect-only`
+composes with the run command); a vitest override must declare one — `vitest list` knows
+nothing of the override config, and the mismatch is refused at `tdd run start`, not
+mid-cycle.
+
 ## Sharing cores between concurrent agents
 
 Several agents running tdd-cli on one machine (each in its own worktree) face a bad

{tdd_cli-0.1.0 → tdd_cli-0.2.0}/README.md

@@ -104,6 +104,35 @@ generated   = true                   # excluded from authorship accounting
 A generator that is never hand-edited (`codegen`) is an artifact regeneration command, not a
 project. It has no tests and no cycles.
 
+Some tests intentionally live outside the project's default runner config — contract tests
+that need a live backend being the common case, where CI runs the default suite with no
+backend up. Widening the default config to make such a test collectable is the wrong fix:
+the plain suite starts making real network calls, and the other suite's tests pollute
+target adoption. Instead, declare an override per pattern:
+
+```toml
+[project.frontend]
+root         = "frontend"
+adapter      = "vitest"
+test_paths   = ["**/*.test.ts"]
+test_command = "npx vitest run"
+
+[[project.frontend.override]]
+pattern         = "src/__contract__/"
+test_command    = "npx vitest run --config vitest.contract.config.ts"
+collect_command = "npx vitest list --config vitest.contract.config.ts"
+env             = { API_URL = "http://localhost:${API_PORT}" }
+```
+
+Collection and suite runs union the default suite with every override suite, so a cycle can
+target a test only the alternate config reaches. Patterns match paths relative to the
+project root with `test_paths` semantics, and override files classify as tests without
+being repeated in `test_paths`. `env` values may reference `${VAR}`, expanded from the
+environment at invocation. For pytest, `collect_command` is optional (`--collect-only`
+composes with the run command); a vitest override must declare one — `vitest list` knows
+nothing of the override config, and the mismatch is refused at `tdd run start`, not
+mid-cycle.
+
 ## Sharing cores between concurrent agents
 
 Several agents running tdd-cli on one machine (each in its own worktree) face a bad

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

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

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

@@ -77,7 +77,9 @@ class Adapter:
     def run(self, target: str | None = None) -> Verdict:
         raise NotImplementedError
 
-    def _run_suite(self, command: str) -> tuple[int, str, str]:
+    def _run_suite(
+        self, command: str, extra_env: dict[str, str] | None = None
+    ) -> tuple[int, str, str]:
         """Run the suite under a machine-wide worker lease.
 
         Substituting `{workers}` is opt-in per project; a command without the
@@ -91,9 +93,31 @@ class Adapter:
             return run_command(
                 command.replace("{workers}", str(workers)),
                 self.root,
-                extra_env={"TDD_WORKERS": str(workers)},
+                extra_env={"TDD_WORKERS": str(workers), **(extra_env or {})},
             )
 
+    def _test_cmd(self) -> str:
+        raise NotImplementedError
+
+    def _suite_invocations(self) -> list[tuple[str, dict[str, str] | None]]:
+        """The default suite plus one invocation per declared override (R7.13).
+
+        Runs and collection union these results, so a test reachable only under an
+        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
+        ]
+
+    @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:
+            return None
+        return {k: os.path.expandvars(v) for k, v in override.env.items()}
+
     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.1.0 → tdd_cli-0.2.0}/src/tddcli/adapters/pytest_adapter.py

@@ -71,8 +71,9 @@ class PytestAdapter(Adapter):
     def _collect_cmd(self) -> str:
         return self.project.collect_command or self._base_cmd()
 
-    def run(self, target: str | None = None) -> Verdict:
-        verdict = Verdict(project=self.project.name, adapter=self.name, target=target)
+    def _suite_report(
+        self, base_cmd: str, extra_env: dict[str, str] | None
+    ) -> tuple[dict | None, str]:
         with tempfile.TemporaryDirectory(prefix="tdd-pytest-") as tmp:
             report_path = Path(tmp) / "report.json"
             # Only reporting flags are appended — parallelism, markers and plugins
@@ -80,26 +81,40 @@ class PytestAdapter(Adapter):
             # `collectors` is omitted when nothing fails to collect, and present with
             # the failing entry when something does, which is when it is consulted.
             cmd = (
-                f"{self._test_cmd()} --json-report"
+                f"{base_cmd} --json-report"
                 f" --json-report-file={shlex.quote(str(report_path))}"
             )
-            code, out, err = self._run_suite(cmd)
+            code, out, err = self._run_suite(cmd, extra_env)
             if not report_path.is_file():
-                verdict.error = (
-                    "pytest produced no JSON report (is pytest-json-report installed?): "
-                    + (err or out)[:500]
+                return None, (
+                    f"`{base_cmd}` produced no JSON report"
+                    " (is pytest-json-report installed?): " + (err or out)[:500]
                 )
-                return verdict
-            report = json.loads(report_path.read_text())
+            return json.loads(report_path.read_text()), ""
 
-        verdict.duration_ms = int(report.get("duration", 0) * 1000)
+    def run(self, target: str | None = None) -> Verdict:
+        verdict = Verdict(project=self.project.name, adapter=self.name, target=target)
+        # Union across the default suite and every override suite (R7.13). A suite
+        # that produces no report is a loud error, not a silent gap: swallowing it
+        # would report a target that lives in that suite as `not_found`, sending the
+        # agent to rewrite a test that is fine.
+        tests: list[dict] = []
+        collectors: list[dict] = []
+        for base_cmd, extra_env in self._suite_invocations():
+            report, error = self._suite_report(base_cmd, extra_env)
+            if report is None:
+                verdict.error = error
+                return verdict
+            verdict.duration_ms += int(report.get("duration", 0) * 1000)
+            tests.extend(report.get("tests", []))
+            collectors.extend(report.get("collectors", []))
 
         uncollectable: set[str] = set()
-        for collector in report.get("collectors", []):
+        for collector in collectors:
             if collector.get("outcome") not in (None, "passed"):
                 uncollectable.add(collector.get("nodeid", ""))
 
-        for test in report.get("tests", []):
+        for test in tests:
             qualified = self.qualify(test["nodeid"])
             if test["outcome"] == "passed":
                 verdict.passed.append(qualified)
@@ -111,9 +126,7 @@ class PytestAdapter(Adapter):
             return verdict
 
         native = self.strip(target)
-        hit = next(
-            (t for t in report.get("tests", []) if t["nodeid"] == native), None
-        )
+        hit = next((t for t in tests if t["nodeid"] == native), None)
         if hit is not None:
             verdict.target_outcome = PASSED if hit["outcome"] == "passed" else FAILED
             call = hit.get("call") or hit.get("setup") or {}
@@ -122,21 +135,30 @@ class PytestAdapter(Adapter):
             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(report, target_file)[:1500]
+                verdict.target_failure = self._collector_error(collectors, target_file)[:1500]
             else:
                 verdict.target_outcome = NOT_FOUND
         return verdict
 
     @staticmethod
-    def _collector_error(report: dict, target_file: str) -> str:
-        for collector in report.get("collectors", []):
+    def _collector_error(collectors: list[dict], target_file: str) -> str:
+        for collector in collectors:
             if collector.get("nodeid", "").startswith(target_file):
                 return str(collector.get("longrepr", ""))
         return ""
 
+    def _collect_cmd_for(self, rel: str) -> tuple[str, dict[str, str] | None]:
+        """The collection command for one file: the owning override's, else the
+        project default. An override without a `collect_command` collects with its
+        `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)
+
     def _test_files(self) -> list[Path]:
         found: list[Path] = []
-        for pattern in self.project.test_paths or ["tests/"]:
+        for pattern in self.project.test_patterns or ["tests/"]:
             if pattern.endswith("/"):
                 base = self.root / pattern
                 if base.is_dir():
@@ -147,27 +169,40 @@ class PytestAdapter(Adapter):
         return sorted({p for p in found if p.is_file()})
 
     def collectable(self) -> GateResult:
-        """A single whole-suite `--collect-only` (§10), not the per-file
-        `collect()` loop below — that loop is R10.3/R10.4's per-file collection,
-        the slow path (the whole-suite probe costs 0.04s on a broken project vs.
-        minutes for the per-file sweep on a real one).
+        """One whole-suite `--collect-only` per declared suite (§10) — the default
+        command plus each override's — not the per-file `collect()` loop below.
+        That loop is R10.3/R10.4's per-file collection, the slow path (the
+        whole-suite probe costs 0.04s on a broken project vs. minutes for the
+        per-file sweep on a real one).
 
         Reads **stdout**, not stderr: `uv` writes environment warnings
         (`VIRTUAL_ENV=... does not match ...`) to stderr while pytest writes the
         actual `ModuleNotFoundError` to stdout. A doctor check that reads stderr
         loses the real error and the failure surfaces unattributed.
         """
-        code, out, err = run_command(f"{self._collect_cmd()} --collect-only -q", self.root)
-        return GateResult(ok=code == 0, output="" if code == 0 else out.strip()[:2000])
+        chunks = []
+        probes = [(self._collect_cmd(), None)] + [
+            (ov.collect_command or ov.test_command, self._override_env(ov))
+            for ov in self.project.overrides
+        ]
+        for cmd, env in probes:
+            code, out, err = run_command(
+                f"{cmd} --collect-only -q", self.root, extra_env=env
+            )
+            if code != 0:
+                chunks.append(out.strip())
+        return GateResult(ok=not chunks, output="\n\n".join(chunks)[:2000])
 
     def collect(self) -> Collection:
         """Per file (R10.3) — one uncollectable module must not destroy the whole set."""
         result = Collection()
         for path in self._test_files():
             rel = path.relative_to(self.root)
+            base, env = self._collect_cmd_for(str(rel))
             code, out, err = run_command(
-                f"{self._collect_cmd()} --collect-only -q {shlex.quote(str(rel))}",
+                f"{base} --collect-only -q {shlex.quote(str(rel))}",
                 self.root,
+                extra_env=env,
             )
             if code != 0:
                 result.failed_files[str(rel)] = (err or out).strip()[:800]

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

@@ -49,19 +49,32 @@ class VitestAdapter(Adapter):
             rel = suite_path
         return self.qualify(f"{rel} > {full_name}")
 
+    def _test_cmd(self) -> str:
+        return self.project.test_command or "npx vitest run"
+
+    def _collect_cmd(self) -> str:
+        return self.project.collect_command or "npx vitest list"
+
     def run(self, target: str | None = None) -> Verdict:
         verdict = Verdict(project=self.project.name, adapter=self.name, target=target)
-        base = self.project.test_command or "npx vitest run"
-        code, out, err = self._run_suite(f"{base} --reporter=json")
-        report = _extract_json(out)
-        if report is None:
-            verdict.error = f"vitest produced no JSON output: {(err or out)[:500]}"
-            return verdict
+        # Union across the default suite and every override suite (R7.13). A suite
+        # 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] = []
+        for base, extra_env in self._suite_invocations():
+            code, out, err = self._run_suite(f"{base} --reporter=json", extra_env)
+            report = _extract_json(out)
+            if report is None:
+                verdict.error = (
+                    f"`{base}` produced no JSON output: {(err or out)[:500]}"
+                )
+                return verdict
+            verdict.duration_ms += int(report.get("duration") or 0)
+            suites.extend(report.get("testResults", []))
 
-        verdict.duration_ms = int(report.get("duration") or 0)
         failed_suites: dict[str, str] = {}
 
-        for suite in report.get("testResults", []):
+        for suite in suites:
             suite_path = suite.get("name", "")
             assertions = suite.get("assertionResults", [])
             if not assertions and suite.get("status") == "failed":
@@ -82,7 +95,7 @@ class VitestAdapter(Adapter):
             return verdict
         if target in verdict.failed:
             verdict.target_outcome = FAILED
-            for suite in report.get("testResults", []):
+            for suite in suites:
                 for t in suite.get("assertionResults", []):
                     if self._id_for(suite.get("name", ""), t["fullName"]) == target:
                         verdict.target_failure = "\n".join(
@@ -101,7 +114,7 @@ class VitestAdapter(Adapter):
 
     def _test_files(self) -> list[Path]:
         found: set[Path] = set()
-        for pattern in self.project.test_paths or ["**/*.test.ts"]:
+        for pattern in self.project.test_patterns or ["**/*.test.ts"]:
             pat = pattern.rstrip("/") + "/**/*" if pattern.endswith("/") else pattern
             for path in self.root.glob(pat):
                 if path.is_file() and path.suffix in (".ts", ".tsx", ".js", ".jsx"):
@@ -134,19 +147,50 @@ class VitestAdapter(Adapter):
         return found
 
     def collectable(self) -> GateResult:
-        """A single whole-suite probe, mirroring the pytest adapter's `--collect-only`
-        (§10): `npx vitest list` at the project root rather than the
-        per-file `collect()` loop below."""
-        base = self.project.collect_command or "npx vitest list"
-        code, out, err = run_command(base, self.root)
-        return GateResult(ok=code == 0, output="" if code == 0 else (err or out).strip()[:2000])
+        """One whole-suite probe per declared suite, mirroring the pytest adapter's
+        `--collect-only` (§10): `npx vitest list` at the project root rather than
+        the per-file `collect()` loop below.
+
+        An override without a `collect_command` fails here, at run start, not
+        per-file during a cycle: `vitest list` knows nothing of the override's
+        config, and falling back to the override's *run* command would execute the
+        suite — against a live backend — just to enumerate it.
+        """
+        chunks = []
+        code, out, err = run_command(self._collect_cmd(), self.root)
+        if code != 0:
+            chunks.append((err or out).strip())
+        for ov in self.project.overrides:
+            if not ov.collect_command:
+                chunks.append(
+                    f"override {ov.pattern!r}: a vitest override needs an explicit"
+                    ' collect_command (e.g. "npx vitest list --config'
+                    ' vitest.other.config.ts")'
+                )
+                continue
+            code, out, err = run_command(
+                ov.collect_command, self.root, extra_env=self._override_env(ov)
+            )
+            if code != 0:
+                chunks.append((err or out).strip())
+        return GateResult(ok=not chunks, output="\n\n".join(chunks)[:2000])
 
     def collect(self) -> Collection:
         result = Collection()
         for path in self._test_files():
             rel = path.relative_to(self.root)
-            base = self.project.collect_command or "npx vitest list"
-            code, out, err = run_command(f"{base} {shlex.quote(str(rel))}", self.root)
+            ov = self.project.override_for(str(rel))
+            if ov is not None and not ov.collect_command:
+                result.failed_files[str(rel)] = (
+                    f"override {ov.pattern!r} declares no collect_command; vitest"
+                    " cannot list these tests under the default config"
+                )
+                continue
+            base = ov.collect_command if ov else self._collect_cmd()
+            env = self._override_env(ov)
+            code, out, err = run_command(
+                f"{base} {shlex.quote(str(rel))}", self.root, extra_env=env
+            )
 
             payload = _extract_json(out)
             if payload is not None:

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

@@ -42,6 +42,35 @@ class ConfigError(RuntimeError):
     pass
 
 
+def _pattern_matches(rel_path: str, pattern: str) -> bool:
+    """`test_paths`-style matching: trailing-slash directory, glob, or bare
+    directory prefix."""
+    if pattern.endswith("/"):
+        return rel_path.startswith(pattern)
+    return fnmatch(rel_path, pattern) or rel_path.startswith(pattern.rstrip("/") + "/")
+
+
+@dataclass
+class Override:
+    """An alternate suite for the files matching `pattern` (R7.13).
+
+    Some tests intentionally live outside the project's default runner config —
+    contract tests that need a live backend being the motivating case. Widening the
+    default config to satisfy collection breaks CI (the default suite suddenly makes
+    real network calls) and pollutes target adoption with tests from the other suite.
+    Instead the registry declares the alternate command; collection and suite runs
+    union the default suite with every override suite.
+
+    `pattern` matches paths relative to the project root, like `test_paths`.
+    `env` values may reference `${VAR}`, expanded from the environment at invocation.
+    """
+
+    pattern: str
+    test_command: str
+    collect_command: str | None = None
+    env: dict[str, str] = field(default_factory=dict)
+
+
 @dataclass
 class Project:
     name: str
@@ -59,6 +88,26 @@ class Project:
     #: Per-file collection. Must not be parallelised: collection is cheap and xdist
     #: adds startup cost per file.
     collect_command: str | None = None
+    #: Alternate suites for files the default command cannot reach (R7.13).
+    overrides: list[Override] = field(default_factory=list)
+
+    def override_for(self, rel_path: str) -> Override | None:
+        """First declared override whose pattern matches (path relative to the
+        project root), so precedence is the reviewed file's order, never dict or
+        filesystem order. Patterns follow `test_paths` semantics: a glob, a
+        trailing-slash directory, or a bare directory prefix."""
+        for ov in self.overrides:
+            if _pattern_matches(rel_path, ov.pattern):
+                return ov
+        return None
+
+    @property
+    def test_patterns(self) -> list[str]:
+        """`test_paths` plus every override pattern. An override's files are tests by
+        declaration — the pattern exists to name the command that runs them — so they
+        classify as tests for staging and discovery without being repeated in
+        `test_paths`."""
+        return self.test_paths + [ov.pattern for ov in self.overrides]
 
     def owns(self, rel_path: str) -> bool:
         if self.root == ".":     # single-project repo: the root is the worktree itself
@@ -74,7 +123,7 @@ class Project:
         if not self.owns(rel_path):
             return False
         inner = self.relative_to_root(rel_path)
-        for pattern in self.test_paths:
+        for pattern in self.test_patterns:
             if pattern.endswith("/"):
                 if inner.startswith(pattern):
                     return True
@@ -196,6 +245,39 @@ def find_config(start: Path) -> Path | None:
     return None
 
 
+def _load_overrides(project: str, raw: list) -> list[Override]:
+    overrides: list[Override] = []
+    for i, body in enumerate(raw, start=1):
+        if not isinstance(body, dict):
+            raise ConfigError(
+                f"project {project!r} override #{i} must be a table"
+                " ([[project.<name>.override]])"
+            )
+        if "pattern" not in body:
+            raise ConfigError(f"project {project!r} override #{i} has no pattern")
+        if "test_command" not in body:
+            raise ConfigError(
+                f"project {project!r} override {body['pattern']!r} has no test_command"
+            )
+        env = body.get("env", {})
+        if not isinstance(env, dict) or not all(
+            isinstance(v, str) for v in env.values()
+        ):
+            raise ConfigError(
+                f"project {project!r} override {body['pattern']!r}: env must be a"
+                " table of string values"
+            )
+        overrides.append(
+            Override(
+                pattern=body["pattern"],
+                test_command=body["test_command"],
+                collect_command=body.get("collect_command"),
+                env=env,
+            )
+        )
+    return overrides
+
+
 def load(worktree: Path) -> Config:
     path = worktree / CONFIG_NAME
     if not path.is_file():
@@ -218,6 +300,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"),
+            overrides=_load_overrides(name, body.get("override", [])),
         )
 
     artifacts: dict[str, Artifact] = {}

tdd_cli-0.2.0/tests/test_suite_overrides.py

@@ -0,0 +1,406 @@
+"""Per-pattern suite overrides (R7.13).
+
+Some tests intentionally live outside the project's default runner config —
+contract tests that need a live backend being the motivating case. Before
+overrides existed, the only way to make such a test collectable was to widen the
+default config, which broke CI (the plain suite suddenly made real network
+calls) and polluted target adoption with the other suite's tests. The registry
+now declares the alternate command per pattern, and collection and runs union
+the default suite with every override suite.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest as pytest_framework
+
+from conftest import git, run_cli, write_plan
+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")
+
+
+OVERRIDE_BLOCK = (
+    "[[project.backend.override]]\n"
+    'pattern         = "contract/"\n'
+    'test_command    = "pytest contract"\n'
+    'collect_command = "pytest contract -p no:cacheprovider"\n'
+    "env             = { API_URL = \"http://localhost:${TDD_TEST_PORT}\" }\n"
+)
+
+
+# -- registry ------------------------------------------------------------
+
+
+def test_override_is_parsed_from_the_registry(tmp_path):
+    project = project_with(tmp_path, OVERRIDE_BLOCK)
+    (ov,) = project.overrides
+    assert ov.pattern == "contract/"
+    assert ov.test_command == "pytest contract"
+    assert ov.collect_command == "pytest contract -p no:cacheprovider"
+    assert ov.env == {"API_URL": "http://localhost:${TDD_TEST_PORT}"}
+
+
+def test_override_without_pattern_or_command_is_refused(tmp_path):
+    with pytest_framework.raises(ConfigError, match="has no pattern"):
+        project_with(
+            tmp_path, '[[project.backend.override]]\ntest_command = "pytest x"\n'
+        )
+    with pytest_framework.raises(ConfigError, match="has no test_command"):
+        project_with(tmp_path, '[[project.backend.override]]\npattern = "x/"\n')
+
+
+def test_override_env_must_be_string_valued(tmp_path):
+    with pytest_framework.raises(ConfigError, match="env must be a table"):
+        project_with(
+            tmp_path,
+            "[[project.backend.override]]\n"
+            'pattern      = "x/"\n'
+            'test_command = "pytest x"\n'
+            "env          = { PORT = 9600 }\n",
+        )
+
+
+def test_override_for_matches_like_test_paths_first_declared_wins(tmp_path):
+    project = project_with(
+        tmp_path,
+        "[[project.backend.override]]\n"
+        'pattern      = "contract/smoke/**"\n'
+        'test_command = "pytest contract/smoke"\n'
+        "[[project.backend.override]]\n"
+        'pattern      = "contract/"\n'
+        'test_command = "pytest contract"\n'
+        "[[project.backend.override]]\n"
+        'pattern      = "legacy"\n'
+        'test_command = "pytest legacy"\n',
+    )
+    assert project.override_for("contract/smoke/test_a.py").test_command == (
+        "pytest contract/smoke"
+    )
+    assert project.override_for("contract/test_b.py").test_command == "pytest contract"
+    assert project.override_for("legacy/test_old.py").test_command == "pytest legacy"
+    assert project.override_for("tests/test_c.py") is None
+
+
+def test_override_files_classify_as_tests_without_repeating_test_paths(tmp_path):
+    """Staging classification must see override files as tests: otherwise a RED
+    commit containing only the new contract test is flagged as implementation
+    written during RED."""
+    project = project_with(tmp_path, OVERRIDE_BLOCK)
+    assert project.is_test_file("backend/contract/test_api.py")
+    assert not project.is_test_file("backend/app/api.py")
+
+
+# -- pytest adapter ------------------------------------------------------
+
+
+def _fake_pytest_run(reports_by_prefix: dict[str, dict], seen: list):
+    """A run_command double that answers each suite command with its own report,
+    keyed by command prefix, writing the JSON where the real plugin would."""
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        seen.append((command, extra_env))
+        for prefix, report in reports_by_prefix.items():
+            if command.startswith(prefix):
+                marker = "--json-report-file="
+                if marker in command:
+                    path = command.split(marker, 1)[1].split(" --", 1)[0]
+                    Path(path.strip("'\"")).write_text(json.dumps(report))
+                return 1 if report.get("tests") else 0, "", ""
+        raise AssertionError(f"unexpected command: {command}")
+
+    return fake
+
+
+def test_pytest_run_unions_default_and_override_suites(tmp_path, monkeypatch):
+    project = project_with(
+        tmp_path,
+        'test_command = "pytest tests"\n' + OVERRIDE_BLOCK,
+    )
+    adapter = adapters.build(project, tmp_path)
+    seen: list = []
+    monkeypatch.setattr(
+        adapters.base,
+        "run_command",
+        _fake_pytest_run(
+            {
+                "pytest tests": {
+                    "duration": 1.0,
+                    "tests": [{"nodeid": "tests/test_a.py::test_a", "outcome": "passed"}],
+                },
+                "pytest contract": {
+                    "duration": 2.0,
+                    "tests": [
+                        {
+                            "nodeid": "contract/test_api.py::test_ping",
+                            "outcome": "failed",
+                            "call": {"longrepr": "boom"},
+                        }
+                    ],
+                },
+            },
+            seen,
+        ),
+    )
+    verdict = adapter.run("backend::contract/test_api.py::test_ping")
+    assert verdict.error is None
+    assert verdict.target_outcome == "failed"
+    assert verdict.target_failure == "boom"
+    assert verdict.passed == ["backend::tests/test_a.py::test_a"]
+    assert verdict.failed == ["backend::contract/test_api.py::test_ping"]
+    assert verdict.duration_ms == 3000
+    assert [c.split(" --json-report", 1)[0] for c, _ in seen] == [
+        "pytest tests",
+        "pytest contract",
+    ]
+
+
+def test_pytest_override_env_reaches_the_suite_with_vars_expanded(
+    tmp_path, monkeypatch
+):
+    monkeypatch.setenv("TDD_TEST_PORT", "9600")
+    project = project_with(tmp_path, 'test_command = "pytest tests"\n' + OVERRIDE_BLOCK)
+    adapter = adapters.build(project, tmp_path)
+    seen: list = []
+    monkeypatch.setattr(
+        adapters.base,
+        "run_command",
+        _fake_pytest_run(
+            {"pytest tests": {"tests": []}, "pytest contract": {"tests": []}}, seen
+        ),
+    )
+    adapter.run(None)
+    (_, default_env), (_, override_env) = seen
+    assert "API_URL" not in default_env
+    assert override_env["API_URL"] == "http://localhost:9600"
+
+
+def test_pytest_broken_override_suite_is_a_loud_error_not_a_silent_gap(
+    tmp_path, monkeypatch
+):
+    """Swallowing a report-less override run would resolve a target living in that
+    suite as `not_found`, sending the agent to rewrite a perfectly good test."""
+    project = project_with(tmp_path, 'test_command = "pytest tests"\n' + OVERRIDE_BLOCK)
+    adapter = adapters.build(project, tmp_path)
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        if command.startswith("pytest contract"):
+            return 4, "", "ERROR: file or directory not found: contract"
+        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)
+    verdict = adapter.run("backend::contract/test_api.py::test_ping")
+    assert verdict.error is not None
+    assert "pytest contract" in verdict.error
+
+
+def test_pytest_collection_routes_override_files_to_the_override_command(
+    tmp_path, monkeypatch
+):
+    project = project_with(tmp_path, OVERRIDE_BLOCK)
+    (tmp_path / "backend" / "tests").mkdir(parents=True)
+    (tmp_path / "backend" / "contract").mkdir()
+    (tmp_path / "backend" / "tests" / "test_a.py").write_text("def test_a(): pass\n")
+    (tmp_path / "backend" / "contract" / "test_api.py").write_text(
+        "def test_ping(): pass\n"
+    )
+    adapter = adapters.build(project, tmp_path)
+    seen: list = []
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        seen.append((command, extra_env))
+        name = "test_api.py::test_ping" if "contract" in command else "test_a.py::test_a"
+        return 0, name, ""
+
+    monkeypatch.setattr(adapters.pytest_adapter, "run_command", fake)
+    collection = adapter.collect()
+    assert collection.tests == {
+        "backend::test_a.py::test_a",
+        "backend::test_api.py::test_ping",
+    }
+    contract_calls = [c for c, _ in seen if "contract/test_api.py" in c]
+    assert contract_calls and contract_calls[0].startswith(
+        "pytest contract -p no:cacheprovider --collect-only -q"
+    )
+
+
+# -- vitest adapter ------------------------------------------------------
+
+
+VITEST_OVERRIDE = (
+    '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'
+)
+
+
+def _vitest_report(file_path: str, full_name: str, status: str) -> dict:
+    return {
+        "duration": 5,
+        "testResults": [
+            {
+                "name": file_path,
+                "status": status,
+                "assertionResults": [
+                    {"fullName": full_name, "status": status, "failureMessages": ["nope"]}
+                ],
+            }
+        ],
+    }
+
+
+def test_vitest_run_finds_a_target_that_only_the_override_config_reaches(
+    tmp_path, monkeypatch
+):
+    project = project_with(tmp_path, VITEST_OVERRIDE, adapter="vitest")
+    adapter = adapters.build(project, tmp_path)
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        if "--config vitest.contract.config.ts" in command:
+            report = _vitest_report(
+                str(tmp_path / "backend" / "contract" / "api.contract.test.ts"),
+                "pings the api",
+                "failed",
+            )
+        else:
+            report = _vitest_report(
+                str(tmp_path / "backend" / "unit.test.ts"), "adds", "passed"
+            )
+        return 1, json.dumps(report), ""
+
+    monkeypatch.setattr(adapters.base, "run_command", fake)
+    target = "backend::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"]
+
+
+def test_vitest_override_without_collect_command_fails_the_collectable_gate(
+    tmp_path, monkeypatch
+):
+    """Fail at run start, not per-file mid-cycle: `vitest list` knows nothing of
+    the override config, and falling back to the override's *run* command would
+    execute the suite — against a live backend — just to enumerate it."""
+    project = project_with(
+        tmp_path,
+        "[[project.backend.override]]\n"
+        'pattern      = "contract/"\n'
+        'test_command = "npx vitest run --config vitest.contract.config.ts"\n',
+        adapter="vitest",
+    )
+    adapter = adapters.build(project, tmp_path)
+    monkeypatch.setattr(
+        adapters.vitest_adapter, "run_command", lambda *a, **k: (0, "", "")
+    )
+    gate = adapter.collectable()
+    assert not gate.ok
+    assert "collect_command" in gate.output
+
+    (tmp_path / "backend" / "contract").mkdir(parents=True)
+    (tmp_path / "backend" / "contract" / "api.contract.test.ts").write_text("")
+    collection = adapter.collect()
+    assert "contract/api.contract.test.ts" in collection.failed_files
+
+
+def test_vitest_collection_routes_override_files_to_the_override_command(
+    tmp_path, monkeypatch
+):
+    project = project_with(tmp_path, VITEST_OVERRIDE, adapter="vitest")
+    (tmp_path / "backend" / "contract").mkdir(parents=True)
+    contract_file = tmp_path / "backend" / "contract" / "api.contract.test.ts"
+    contract_file.write_text("")
+    adapter = adapters.build(project, tmp_path)
+    seen: list = []
+
+    def fake(command, cwd, timeout=1800, extra_env=None):
+        seen.append(command)
+        return 0, "contract/api.contract.test.ts > pings the api", ""
+
+    monkeypatch.setattr(adapters.vitest_adapter, "run_command", fake)
+    collection = adapter.collect()
+    assert collection.tests == {
+        "backend::backend/contract/api.contract.test.ts > pings the api"
+    }
+    assert seen[0].startswith("npx vitest list --config vitest.contract.config.ts ")
+
+    # With every suite listable the gate passes: the probe must not manufacture a
+    # failure out of a healthy override.
+    assert adapter.collectable().ok
+
+
+# -- end to end ----------------------------------------------------------
+
+
+PLAN = """---
+cycles:
+  - n: 1
+    project: backend
+    test: "contract/test_api.py::test_add_via_api"
+---
+"""
+
+
+def test_a_cycle_can_target_a_test_only_an_override_suite_reaches(repo):
+    """The full RED → GREEN path for a target the default command never runs.
+
+    The default suite is pinned to `pytest tests`, so nothing under `contract/`
+    is reachable by it; before overrides this cycle could not reach RED at all.
+    """
+    (repo / "backend" / "contract").mkdir()
+    (repo / "backend" / "contract" / "test_ping.py").write_text(
+        "def test_ping():\n    assert True\n"
+    )
+    (repo / "backend" / "app" / "calc.py").write_text(
+        "def add(a, b):\n    raise NotImplementedError\n"
+    )
+    (repo / "tdd.toml").write_text(
+        "[project.backend]\n"
+        'root         = "backend"\n'
+        'adapter      = "pytest"\n'
+        'test_paths   = ["tests/"]\n'
+        'test_command = "pytest tests"\n'
+        "lint         = []\n"
+        "typecheck    = []\n"
+        "[[project.backend.override]]\n"
+        'pattern      = "contract/"\n'
+        'test_command = "pytest contract"\n'
+    )
+    git(repo, "add", "-A")
+    git(repo, "commit", "-q", "-m", "declare the contract-suite override")
+
+    plan = write_plan(repo, PLAN)
+    run_cli(repo, "plan", "register", plan)
+    start = run_cli(repo, "run", "start", "--plan", plan)
+    assert start["ok"], start
+
+    (repo / "backend" / "contract" / "test_api.py").write_text(
+        "from app.calc import add\n\n\n"
+        "def test_add_via_api():\n    assert add(2, 2) == 4\n"
+    )
+    red = run_cli(repo, "advance")
+    assert red["next_action"]["verb"] == "write_implementation", red
+
+    (repo / "backend" / "app" / "calc.py").write_text(
+        "def add(a, b):\n    return a + b\n"
+    )
+    green = run_cli(repo, "advance")
+    assert green["next_action"]["verb"] == "refactor_or_advance", green