tdd-cli 0.2.1__tar.gz → 0.4.0__tar.gz

{tdd_cli-0.2.1 → tdd_cli-0.4.0}/CHANGELOG.md

@@ -4,7 +4,62 @@ 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.4.0] - 2026-08-16
+
+### Added
+
+- `baseline_captured` reports `run_s` and `collect_s` alongside `elapsed_s`. The
+  suite run and the per-file collection have unrelated cost models — one scales
+  with tests, the other with files — so a single total could not say which was
+  slow, and answering that meant measuring projects by hand outside the tool.
+- `TDD_TIMING=1` emits a `command_timing` line per subprocess on stderr
+  (`label`, `command`, `cwd`, `duration_ms`, `exit_code`), covering every
+  subprocess the tool spawns: suite runs, per-file collection, lint/typecheck
+  gates, doctor probes and artifact hooks. Off by default — the per-file loop
+  would otherwise emit one line per test file on every invocation. `label` is
+  one of `suite`, `collect`, `gate`, `doctor`; an unlabelled row comes from a
+  third-party adapter, since every built-in call site names itself (R8.4).
+
+### Fixed
+
+- `tdd doctor` no longer emits a blocker it cannot explain. Every failing check
+  now carries a `detail` naming what to fix, enforced by the checklist recorder
+  so a check added later inherits the guarantee. Previously `worktree clean`
+  failed with `detail: ""`, leaving an agent with `resolve_blocker` and nothing
+  to resolve — it re-ran doctor and read the identical output.
+- `worktree clean` is scoped to dirt a run would actually read: a declared
+  project root, a declared artifact path, or `tdd.toml`. Build residue is
+  excluded via `config.is_ignored`, so doctor's own `uv run` / `vitest list`
+  probes (`.venv`, `node_modules`, caches) can no longer be what makes doctor
+  fail. Unrelated dirt is reported in the passing check's `detail` rather than
+  blocking the run.
+
+## [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
 

{tdd_cli-0.2.1 → tdd_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.2.1
+Version: 0.4.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.1 → tdd_cli-0.4.0}/pyproject.toml

@@ -47,7 +47,7 @@ packages = ["src/tddcli"]
 include = ["src", "tests", "examples", "README.md", "LICENSE", "CHANGELOG.md", "SECURITY.md"]
 
 [dependency-groups]
-dev = ["pytest>=8.0", "pytest-json-report>=1.5", "ruff>=0.5"]
+dev = ["pytest>=8.0", "pytest-json-report>=1.5", "ruff>=0.5", "zizmor>=1.29"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{tdd_cli-0.2.1 → tdd_cli-0.4.0}/src/tddcli/__init__.py

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

{tdd_cli-0.2.1 → tdd_cli-0.4.0}/src/tddcli/adapters/base.py

@@ -4,11 +4,13 @@ from __future__ import annotations
 
 import os
 import subprocess
+import time
 from collections import Counter
 from dataclasses import dataclass, field
 from pathlib import Path
 
 from .. import leases
+from ..envelope import heartbeat
 
 NOT_FOUND = "not_found"
 NOT_COLLECTED = "not_collected"
@@ -64,10 +66,40 @@ def _overlap_error(overlap: list[str]) -> str:
     )
 
 
+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:]}"
+
+
+#: Opt-in per-command timing. Off by default: the per-file collect loop would emit
+#: one line per test file on every invocation, drowning the heartbeats that exist
+#: to make a slow baseline legible.
+TIMING_ENV = "TDD_TIMING"
+
+
 def run_command(
     command: str, cwd: Path, timeout: int = 1800,
     extra_env: dict[str, str] | None = None,
+    label: str | None = None,
 ) -> tuple[int, str, str]:
+    """Every subprocess the tool spawns passes through here, which makes it the one
+    place worth timing: suite runs, per-file collection, lint and typecheck gates,
+    doctor probes, artifact hooks.
+
+    `label` is what makes the rows groupable. This function sees a command string
+    and a cwd — not which project or phase asked for it — so an unlabelled timing
+    is readable by a human and useless to a query.
+    """
+    started = time.monotonic()
     proc = subprocess.run(
         command,
         shell=True,
@@ -77,6 +109,15 @@ def run_command(
         timeout=timeout,
         env=None if extra_env is None else {**os.environ, **extra_env},
     )
+    if os.environ.get(TIMING_ENV):
+        heartbeat(
+            event="command_timing",
+            label=label,
+            command=command,
+            cwd=str(cwd),
+            duration_ms=int((time.monotonic() - started) * 1000),
+            exit_code=proc.returncode,
+        )
     return proc.returncode, proc.stdout, proc.stderr
 
 
@@ -116,6 +157,7 @@ class Adapter:
                 command.replace("{workers}", str(workers)),
                 self.root,
                 extra_env={"TDD_WORKERS": str(workers), **(extra_env or {})},
+                label="suite",
             )
 
     def _test_cmd(self) -> str:
@@ -128,17 +170,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."""
@@ -168,7 +212,7 @@ class Adapter:
     def _gate(self, commands: list[str]) -> GateResult:
         chunks = []
         for cmd in commands:
-            code, out, err = run_command(cmd, self.root)
+            code, out, err = run_command(cmd, self.root, label="gate")
             if code != 0:
                 chunks.append(f"$ {cmd}\n{out}\n{err}".strip())
         return GateResult(ok=not chunks, output="\n\n".join(chunks)[:4000])

{tdd_cli-0.2.1 → tdd_cli-0.4.0}/src/tddcli/adapters/pytest_adapter.py

@@ -27,6 +27,7 @@ from .base import (
     Verdict,
     _overlap_error,
     _suite_overlap,
+    clip_failure,
     run_command,
 )
 
@@ -139,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
@@ -162,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] = []
@@ -190,13 +193,13 @@ 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:
             code, out, err = run_command(
-                f"{cmd} --collect-only -q", self.root, extra_env=env
+                f"{cmd} --collect-only -q", self.root, extra_env=env, label="doctor"
             )
             if code != 0:
                 chunks.append(out.strip())
@@ -212,7 +215,9 @@ class PytestAdapter(Adapter):
         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)
+        code, out, err = run_command(
+            probe, self.root, extra_env=self._suite_env(None), label="doctor"
+        )
         reached = sorted({
             f for f in (
                 line.split("::", 1)[0]
@@ -240,6 +245,7 @@ class PytestAdapter(Adapter):
                 f"{base} --collect-only -q {shlex.quote(str(rel))}",
                 self.root,
                 extra_env=env,
+                label="collect",
             )
             if code != 0:
                 result.failed_files[str(rel)] = (err or out).strip()[:800]

{tdd_cli-0.2.1 → tdd_cli-0.4.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
@@ -23,6 +26,7 @@ from .base import (
     Verdict,
     _overlap_error,
     _suite_overlap,
+    clip_failure,
     run_command,
 )
 
@@ -46,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}")
@@ -92,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":
@@ -113,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
 
@@ -171,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), label="doctor"
+        )
         if code != 0:
             chunks.append((err or out).strip())
         for ov in self.project.overrides:
@@ -183,7 +190,7 @@ 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), label="doctor"
             )
             if code != 0:
                 chunks.append((err or out).strip())
@@ -196,7 +203,9 @@ class VitestAdapter(Adapter):
         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)
+        code, out, err = run_command(
+            self._collect_cmd(), self.root, extra_env=self._suite_env(None), label="doctor"
+        )
         reached = sorted({
             f for f in (
                 line.strip().partition(" > ")[0]
@@ -226,9 +235,10 @@ 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
+                f"{base} {shlex.quote(str(rel))}", self.root, extra_env=env,
+                label="collect",
             )
 
             payload = _extract_json(out)

{tdd_cli-0.2.1 → tdd_cli-0.4.0}/src/tddcli/cli.py

@@ -6,12 +6,14 @@ 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
 import sqlite3
 import sys
 import time
+from collections.abc import Callable
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -216,16 +218,61 @@ def _legacy_artifacts(worktree: Path) -> list[Path]:
     return sorted(found)
 
 
-def cmd_doctor(args) -> Envelope:
-    worktree = _worktree()
+def _doctor_checklist() -> tuple[list[dict], Callable]:
+    """A checks list and its recorder, which refuses a blocker it cannot explain.
+
+    `resolve_blocker` with an empty `detail` is unfalsifiable: an agent is told to
+    fix something and given nothing to fix. It re-runs doctor, reads the identical
+    output, and loops. Enforcing the detail here means a check added later inherits
+    the guarantee instead of relying on its author to remember.
+    """
     checks: list[dict] = []
 
     def check(name, ok, detail="", project=None):
+        if not ok and not str(detail).strip():
+            raise AssertionError(
+                f"doctor check {name!r} would fail silently: a failing check must"
+                " name what to fix"
+            )
         entry = {"check": name, "ok": bool(ok), "detail": detail}
         if project is not None:
             entry["project"] = project
         checks.append(entry)
 
+    return checks, check
+
+
+def _blocks_the_loop(rel_path: str, cfg) -> bool:
+    """Whether dirt at `rel_path` is somewhere a run would actually read it."""
+    if rel_path == config_mod.CONFIG_NAME:
+        return True
+    if cfg.owning_project(rel_path) is not None:
+        return True
+    return any(art.owns(rel_path) for art in cfg.artifacts.values())
+
+
+def _cleanliness_detail(blocking: list[str], unrelated: list[str]) -> str:
+    def listed(paths: list[str]) -> str:
+        head = ", ".join(paths[:5])
+        return head if len(paths) <= 5 else f"{head} (+{len(paths) - 5} more)"
+
+    if blocking:
+        return (
+            f"uncommitted changes a run would observe: {listed(blocking)}."
+            " Commit, stash, or gitignore them before `tdd run start`."
+        )
+    if unrelated:
+        return (
+            f"clean where a run reads; {len(unrelated)} unrelated path(s) left as-is:"
+            f" {listed(unrelated)}"
+        )
+    return ""
+
+
+def cmd_doctor(args) -> Envelope:
+    worktree = _worktree()
+    checks, check = _doctor_checklist()
+
     check("worktree resolvable", True, str(worktree))
     try:
         cfg = config_mod.load(worktree)
@@ -245,13 +292,20 @@ def cmd_doctor(args) -> Envelope:
         root = worktree / project.root
         check("root exists", root.is_dir(), str(root), project=name)
         check("adapter known", project.adapter in adapters.available(), project.adapter, project=name)
-        check("test_paths declared", bool(project.test_paths), project=name)
+        declared = bool(project.test_paths)
+        check(
+            "test_paths declared", declared,
+            "" if declared
+            else f"add `test_paths` to [project.{name}] in tdd.toml — without it no"
+                 " suite can be discovered for this project",
+            project=name,
+        )
         if project.adapter == "pytest":
             # The probe runs in the project's own environment (uv, poetry, pipenv,
             # pdm or the active venv) — hardcoding `uv run` here failed the check
             # on any non-uv project even with the plugin installed.
             probe = adapters.build(project, worktree).plugin_probe_cmd()
-            code, out, err = adapters.base.run_command(probe, root)
+            code, out, err = adapters.base.run_command(probe, root, label="doctor")
             check("pytest-json-report installed", code == 0, (err or "")[:200], project=name)
 
         # Run before `collectable()` so this actionable message wins over
@@ -288,11 +342,33 @@ def cmd_doctor(args) -> Envelope:
         projects[name] = {"ok": all(c["ok"] for c in checks[before:])}
 
     for art in cfg.artifacts.values():
-        check(f"artifact {art.name}: has check or regenerate", bool(art.check or art.regenerate))
+        # One evaluation feeds both `ok` and the detail: evaluating the condition
+        # twice lets them disagree, and a passing check that still says "add a hook"
+        # is the same misdirection as a failing check that says nothing.
+        has_hook = bool(art.check or art.regenerate)
+        check(
+            f"artifact {art.name}: has check or regenerate", has_hook,
+            "" if has_hook
+            else f"add `check` or `regenerate` to [artifact.{art.name}] in tdd.toml —"
+                 " freshness cannot be verified without one",
+        )
 
     stale = _legacy_artifacts(worktree)
-    check("no legacy state artifacts", not stale, ", ".join(str(s) for s in stale[:5]))
-    check("worktree clean", not gitutil.is_dirty(worktree))
+    check(
+        "no legacy state artifacts", not stale,
+        f"delete these pre-ledger state files: {', '.join(str(s) for s in stale[:5])}"
+        if stale else "",
+    )
+
+    # Only dirt a run would read can corrupt one. Blocking on everything else
+    # stopped agents on unrelated notes and editor settings, and — because the
+    # check named no path — gave them nothing to act on but a re-run. `is_ignored`
+    # also excludes doctor's own probe residue (`.venv`, `node_modules`, caches),
+    # so running doctor can no longer be what makes doctor fail.
+    dirt = sorted(p for p in gitutil.dirty_paths(worktree) if not cfg.is_ignored(p))
+    blocking = [p for p in dirt if _blocks_the_loop(p, cfg)]
+    unrelated = [p for p in dirt if p not in set(blocking)]
+    check("worktree clean", not blocking, _cleanliness_detail(blocking, unrelated))
 
     ok = all(c["ok"] for c in checks)
     return Envelope(
@@ -363,12 +439,18 @@ def _probe_projects(cfg, worktree, ledger, on_progress):
     for done, (name, project) in enumerate(cfg.projects.items(), start=1):
         adapter = adapters.build(project, worktree)
         started = time.monotonic()
-        verdict, collection = adapter.run(None), adapter.collect()
+        verdict = adapter.run(None)
+        ran = time.monotonic()
+        collection = adapter.collect()
         elapsed = time.monotonic() - started
         probes[name] = (verdict, collection)
+        # Split, not just totalled: `run` and `collect` have unrelated cost models
+        # — one scales with tests, the other with files — and a single number sends
+        # whoever asks "why was that slow?" out of the tool to measure by hand.
         heartbeat(
             event="baseline_captured", project=name,
             test_count=len(collection.tests), elapsed_s=round(elapsed, 2),
+            run_s=round(ran - started, 2), collect_s=round(elapsed - (ran - started), 2),
         )
         on_progress(done, name)
     return probes
@@ -822,6 +904,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.1 → tdd_cli-0.4.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", [])),
         )