tdd-cli 0.1.0__py3-none-any.whl

tdd_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,391 @@
+Metadata-Version: 2.4
+Name: tdd-cli
+Version: 0.1.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
+Project-URL: Issues, https://github.com/geuben/tdd-cli/issues
+Project-URL: Changelog, https://github.com/geuben/tdd-cli/blob/main/CHANGELOG.md
+Author: geuben
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,pytest,tdd,testing,vitest,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# tdd-cli
+
+A ledger-backed TDD process controller for autonomous coding agents.
+
+Process state is **derived from observed test execution**, never asserted by the caller.
+There is no command that accepts a phase, and no file an agent can edit to claim progress
+it has not made.
+
+Implements [`tdd-cli-prd.md`](./docs/PRD.md). Requirement ids (`R9.14`, `§6.2`) in the source
+refer to that document.
+
+## Why
+
+An agent instructed to follow TDD will report that it did. The usual ways to hold it to
+that — prompt rules, a checklist, a state file in the worktree — all share one flaw: the
+record of progress is written by the same agent it is meant to constrain. That flaw
+produces four failure classes, reliably: state that is corrupted or edited to claim
+progress never made; "the test failed first" as an unverifiable self-report; runs that
+stop silently mid-plan; and no record comparable across runs, plans, or models.
+
+This tool removes the agent from the reporting path. It runs the suites itself, computes
+every phase transition from what the tests observably did, and records the whole run in a
+ledger the agent cannot reach — which is also what makes the friction logs and metrics at
+the end trustworthy.
+
+## Install
+
+```sh
+pip install tdd-cli        # or: uv tool install tdd-cli
+tdd --help
+```
+
+From source:
+
+```sh
+uv sync
+uv run tdd --help
+```
+
+## Quick start
+
+```sh
+tdd init                       # scaffold tdd.toml from detected projects — then review it
+tdd doctor                     # environment preflight
+tdd plan register tasks/my-plan.md
+tdd run start --plan tasks/my-plan.md
+tdd advance                    # the only command that changes phase
+```
+
+Every command emits JSON with a `next_action`. That verb is the single authority on control
+flow — skills describe *how* to do the work and must never contain stopping instructions.
+[`docs/harness-integration.md`](./docs/harness-integration.md) specifies the verb set and how
+to write such a skill; [`examples/skills/tdd-drive/`](./examples/skills/tdd-drive/) is a
+runnable one for Claude Code. Its planning-side counterpart,
+[`examples/skills/tdd-handoff/`](./examples/skills/tdd-handoff/), hardens a
+draft plan and authors its contract before the run starts.
+
+## Configuration
+
+`tdd.toml` at the worktree root. Roots are declared, never discovered by scanning for marker
+files: two projects can share a marker, and directory-listing order must not decide which
+suite runs.
+
+A single-project repository declares the worktree root itself:
+
+```toml
+[project.app]
+root       = "."
+adapter    = "pytest"
+test_paths = ["tests/"]
+```
+
+A monorepo declares one project per root:
+
+```toml
+[project.backend]
+root       = "backend"
+adapter    = "pytest"
+test_paths = ["tests/"]
+lint       = ["ruff check"]
+typecheck  = ["mypy ."]
+
+[project.frontend]
+root       = "frontend"
+adapter    = "vitest"
+test_paths = ["**/__tests__/**", "**/*.test.ts"]
+typecheck  = ["tsc --noEmit"]
+
+[artifact.openapi]
+path        = "schema/openapi.json"
+produced_by = "backend"
+regenerate  = "uv run python -m app.export_openapi"
+consumed_by = ["frontend"]
+
+[artifact.api_client]
+path        = "frontend/generated"
+produced_by = "artifact.openapi"     # artifacts chain
+regenerate  = "npm --prefix codegen run generate"
+check       = "npm --prefix codegen run check"
+consumed_by = ["frontend"]
+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.
+
+## Sharing cores between concurrent agents
+
+Several agents running tdd-cli on one machine (each in its own worktree) face a bad
+trade: a fixed worker count in the test command either oversubscribes the box when
+agents run together or serialises every suite when an agent is alone. Instead, declare
+where the worker count goes and let the tool compute it:
+
+```toml
+[project.backend]
+test_command = "uv run pytest -n {workers}"
+
+[project.frontend]
+test_command = "npx vitest run --maxWorkers={workers}"
+```
+
+Each suite invocation takes a lease in a machine-wide directory (`~/.cache/tdd-cli/leases`,
+override with `TDD_LEASE_DIR`) held for the duration of the run, and receives
+`max(1, cores // live_leases)` workers: one agent gets the whole machine, four agents get a
+quarter each. Leases whose process has died, or older than a suite could legitimately run,
+are swept — a crash never throttles the machine.
+
+`{workers}` is opt-in per project; without it the declared command runs verbatim, but the
+budget is still exported as `TDD_WORKERS` for commands that prefer to read it themselves,
+and the lease is still held so other agents account for the running suite. Set
+`TDD_CORE_BUDGET` to cap the total below `os.cpu_count()` and keep headroom for the agents
+themselves.
+
+The split is computed at lease acquisition: an agent arriving mid-run takes the smaller
+share immediately, and the earlier agent's share corrects on its next invocation. Per-file
+collection stays serial — collection is cheap and xdist adds startup cost per file.
+
+## Watching every agent at once
+
+The ledger is one database per repository, shared by all worktrees, so every agent's
+progress is already in one place. `tdd fleet` reads it:
+
+```sh
+tdd fleet          # one line per active run, plus in-flight baselines and executing suites
+tdd fleet --json   # the same as a machine envelope
+```
+
+Each run line carries the worktree, plan, cycle N of M, phase, and the age of the newest
+suite invocation — a stale age is the signal for a wedged agent. Baselines still being
+collected are listed separately, and the worker-lease directory is read (never modified)
+to show how many suites are executing right now and each one's share of the cores.
+
+The command is safe to run while agents are mid-run from any worktree on any branch: it
+opens the ledger with SQLite's read-only mode, so it is structurally incapable of creating,
+migrating, or writing the database, and it requires no `tdd.toml`, plan, or active run.
+
+## Plan contracts
+
+The plan carries its own contract in YAML front-matter, so a planning agent needs no
+integration with this tool. The contract is hashed at the **committed blob**, so editing
+front-matter mid-run raises `plan_blob_changed`.
+
+```yaml
+---
+cycles:
+  - n: 1
+    project: backend
+    title: "unmapped exception is not swallowed"
+    test: "tests/test_map.py::test_unmapped_is_not_swallowed"
+    stub_expected: ["app/exception_map.py"]
+    commit_red: "test: unmapped exception is not swallowed"
+    commit_green: "feat: domain exception map skeleton"
+  - n: 8
+    project: backend
+    pin_cycle: true                 # characterisation; passes on arrival by design
+    test: "tests/test_keys.py::test_enrol_maps_signature_error_to_422"
+  - n: 12
+    projects: ["backend", "frontend"]
+    contract_cycle: true            # breaking change: no intermediate green state
+    tests:
+      - "backend::tests/test_openapi.py::test_upload_body_schema"
+      - "frontend::services/__tests__/upload.test.ts > matches contract"
+annotation_keys: ["literal_detail_handlers_kept"]
+---
+```
+
+Absent front-matter is legitimate — the run proceeds as `undeclared` with
+`--allow-undeclared`, and fidelity metrics are unavailable. **Malformed** front-matter
+hard-fails registration: it is almost always a defect in the planning process, and that
+signal must surface rather than degrade silently.
+
+[`examples/plan.md`](./examples/plan.md) is a complete plan — every cycle kind, the full
+front-matter vocabulary, and the body structure (context, verified repo facts, per-cycle
+expected failures) that lets an agent execute it without conversation context. The test
+suite registers it, so it cannot drift from the contract parser.
+
+Producing a plan of that shape is itself a process.
+[`examples/skills/tdd-handoff/`](./examples/skills/tdd-handoff/) is a Claude
+Code skill that takes a draft plan, verifies its claims against the codebase, probes each
+cycle's RED path empirically, assigns cycle kinds, and authors the contract — gated on
+`tdd plan register` succeeding with the intended cycle count and kind breakdown.
+
+## The friction log
+
+`tdd log render` projects the ledger into a markdown friction log — the feedback channel
+back to the **planning** process. It reports plan fidelity (declared vs delivered vs
+skipped vs never-reached cycles, human interventions) and, per cycle: the target, suite
+runs by phase, the first-run outcome against expectation, sensitivity checks, commits,
+and integrity events.
+
+Every observable fact in it is projected from recorded events. The agent that did the
+work cannot compose it — that is what makes it worth reading, and why the log is
+rendered, never written. Judgement enters in exactly two ways:
+
+- **Per cycle, through `tdd annotate`** — rendered inline in the cycle it concerns.
+  Beyond keys the plan requires via `annotation_keys`, these keys are reserved for
+  judgement agents volunteer: `plan_defect`, `friction_note`, `red_expectation`,
+  `commit_shape_deviation`, `test_setup_smell`, `unplanned_change`, `new_work_raised`.
+  `plan_defect` is the one that matters most: it records where the plan and the codebase
+  disagreed, which is precisely what the next plan needs to know.
+- **Per run, as prose appended below the rendered document.** Legitimate and expected —
+  post-run narrative (CI failures, patterns noticed) has no cycle to attach to. But it
+  is unverified: an auditor should trust the projected sections and read appended
+  narrative as the agent's opinion.
+
+`tdd metrics` is the quantitative companion: attempts per cycle, RED-first violation
+rate, fidelity, blockers, interventions. Cross-plan aggregates are deliberately labelled
+non-comparable — cycle difficulty varies too much — so compare runs of the same contract
+only (e.g. the same plan executed by two models).
+
+The loop closes when the rendered log is committed alongside the plan and read before
+the next plan is written.
+
+## Adapters
+
+`pytest` and `vitest` are built in. The pytest adapter runs the suite through the
+project's own environment manager, detected from its marker files — `uv.lock`,
+`poetry.lock`, `Pipfile`, `pdm.lock`, or `[tool.poetry]` in `pyproject.toml` — checked at
+the project root first, then the worktree root (workspace layouts keep one lockfile at the
+top). With no marker, the active environment's bare `pytest` runs. An explicit
+`test_command` always wins.
+
+Third-party adapters register under the
+`tddcli.adapters` entry-point group:
+
+```toml
+[project.entry-points."tddcli.adapters"]
+cargo = "tddcli_cargo:CargoAdapter"
+```
+
+The class must implement `tddcli.adapters.base.Adapter`. Built-in names cannot be
+shadowed: a plugin named `pytest` is ignored, so what "observed test execution" means for
+existing configs can never change underneath them.
+
+## Platform support
+
+Linux and macOS. Windows is refused at startup with `reason: "unsupported_platform"` —
+worker leases and process-liveness checks are POSIX-only. Use WSL.
+
+Every JSON envelope carries `envelope_version`; consumers should check it rather than
+assuming the shape is stable across releases. See also [SECURITY.md](./SECURITY.md) for
+the trust model: running `tdd` executes the repository's declared commands.
+
+## Cycle kinds
+
+**Standard / contract** — `AWAITING_TEST → AWAITING_IMPL → AWAITING_REFACTOR → CLOSED`
+
+**Pin** — `AWAITING_PIN → SENSITIVITY_REQUIRED → AWAITING_REFACTOR → CLOSED`
+
+A pin characterises existing behaviour before deleting or restructuring it, so its test
+passes on arrival by design and its sensitivity check is mandatory. Pins are excluded from
+the RED-first violation metric; a *standard* cycle that passes on arrival remains a violation
+and is never reclassified as a pin.
+
+## What the tool does, that agents do not
+
+- **Stages and commits.** The staged set is derived from the phase: RED takes tests and
+  declared stubs, GREEN takes the rest. This makes "implementation written during RED" an
+  exact, language-independent detection with no source parsing.
+- **Regenerates stale artifacts**, in their own commit, so hand-written and generated changes
+  stay separately reviewable.
+- **Resolves executor identity** from the session transcript. It is never an argument.
+- **Runs the close sweep** over the cycle's projects plus anything downstream of an artifact
+  it touched — not every project every time.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `tdd init` / `tdd doctor` | scaffold config; environment preflight |
+| `tdd plan register <path>` | parse and hash the contract |
+| `tdd run start --plan <path>` | capture baselines, resolve executor, open cycle 1 |
+| `tdd status` | position and `next_action`; safe any time |
+| `tdd advance [--retry]` | run suites, compute the transition, commit |
+| `tdd cycle skip --reason` | sanctioned path for a cycle the plan got wrong |
+| `tdd sensitivity begin\|check\|end` | prove a passing test can fail; verify restore |
+| `tdd annotate --key --value` | attach judgement to the current cycle |
+| `tdd blocker --kind --detail` | typed blocker; releases the stop hook |
+| `tdd resume [--unblock --note]` | reconstruct position; human intervention |
+| `tdd log render [--out]` | project the ledger into a friction log |
+| `tdd metrics` | fidelity, attempts, violations, interventions |
+| `tdd fleet [--json]` | all active runs across every worktree; read-only |
+
+## Running a long baseline
+
+`run start` probes every project's suite before a run exists (R9.5a), and on a real project
+that can take minutes — well past an agent harness's default Bash timeout. If the command
+appears to hang or time out, **do not re-run it**: the probe is still making progress in the
+background, and a second `run start` against the same worktree is refused with
+`reason: "baseline_in_progress"` — retrying on timeout just stacks refusals on top of a
+baseline that was never stuck. In order of preference:
+
+1. **Background it.** Run `tdd run start` in the background if your harness supports it. The
+   heartbeat (`baseline_captured` / `project_completed` lines on stderr) lands in the task log
+   as each project finishes, and most harnesses re-invoke the agent when a backgrounded command
+   exits — a real completion callback, with no timeout ceiling.
+2. **Raise the timeout.** Claude Code's Bash tool takes an explicit `timeout` (default 120000ms,
+   max 600000ms). A baseline that takes 3–8 minutes fits inside ten.
+3. **Poll.** `tdd progress` (and `tdd status`) report `collecting_baseline` with per-project
+   counters and elapsed time while a baseline is in flight, with `next_action.verb ==
+   "await_baseline"` — the fallback for an agent that inherited a run it did not start itself.
+
+## Storage
+
+One SQLite ledger **per repository**, in `~/.local/share/tdd-cli/` (override with
+`TDD_LEDGER_HOME`), keyed by the common git dir. Never inside the worktree, never resolved
+from the current directory, never committed. `worktree_path` is a column, so concurrent runs
+in separate worktrees are isolated without a pruned worktree orphaning its history.
+
+## Enforcement boundary
+
+The CLI cannot compel an agent — only the harness can.
+
+**Hard gates here:** phase is never caller-supplied; a cycle cannot close over a stale
+artifact; a passed-on-arrival cycle cannot close without a verified sensitivity check;
+`advance` refuses an unchanged tree unless `--retry`.
+
+**Recorded, never blocked:** non-stub writes during RED, undeclared file touches, scope
+divergence, extra attempts. Prevention rules with edge cases produce false denials, and a
+blocked agent improvises around them — putting it right back in the reporting path the
+tool exists to keep it out of.
+
+**Delegated to hooks:** a Stop hook that queries `tdd status` and refuses to let an agent
+stop while a run is live; a Bash hook redirecting bare `pytest`/`vitest` through `tdd advance`.
+Ready-made Claude Code implementations of both live in
+[`examples/claude-code-hooks/`](./examples/claude-code-hooks/).
+
+**Delegated to the skill:** how to respond to each `next_action` verb — writing the test,
+the stub, the implementation. [`docs/harness-integration.md`](./docs/harness-integration.md)
+is the contract for writing one against any harness.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check src tests
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE)

tdd_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+tddcli/__init__.py,sha256=tGM1_L4f_rJ1N2dps6a3IDvEtcb1YsmVkvno1PK40Y8,189
+tddcli/advance.py,sha256=_DBSBVQIC9vzlmEbg-7tPlMAnS5UWJmtGTC5iPAoF7Y,16794
+tddcli/cli.py,sha256=8tV7OeNat7Gkrksa27WRMO2Ey_8Ns671ykP2RIiOtd0,41214
+tddcli/config.py,sha256=nqm3OCRu6NIN1dTqmXGErOwGE6Z157vgV9u3vpoXS_I,9168
+tddcli/contract.py,sha256=9G0cD22Pgns5uSQIx3AtUNFmj7RGpYWc2UQYsoPRqGA,8273
+tddcli/envelope.py,sha256=qBDL-PfPoEwh0q5VxXz5UE-wOJJgk_Cu7Y3WTI9fLVI,3101
+tddcli/fleet.py,sha256=CpxKRR99jOS8D_nJK9dCx_bcHVMdCdBLJVA5Z_qBmqk,4678
+tddcli/gitutil.py,sha256=u72NJvcGFf2lRYVQSFud_vCshYlkGHXz31Mw05tfzh0,4297
+tddcli/identity.py,sha256=sk4BGPyI3zTQLYL5FtwqjbqAWyCKeo31Ncf3fbjjYQQ,2734
+tddcli/leases.py,sha256=pUTzXMwvl8wMSyfzt-dk281qyHvqyH8OgpyYd4vig9w,4103
+tddcli/ledger.py,sha256=D03btDrxZJ0c5-Yd1T7QzQ07jFgIeemHh64-4m0gew0,16071
+tddcli/machine.py,sha256=W31Z1vUkl-4W2tz9gDboX--ysSFQdEZwal4T9Jk0jAo,15859
+tddcli/render.py,sha256=kLPtiY4Gvoav1ChIZzxg9eZs5IGot4mYYX3Mv1S4K1E,10676
+tddcli/snapshot.py,sha256=uMP3vq9g2TmWch5ndhy3LIgVZ644Hqr2e1pZZgzoRK8,2981
+tddcli/staging.py,sha256=O7_58jpK4decmx6jcBdXAPrj--mOm1DJmQVwapk_Zlg,4549
+tddcli/adapters/__init__.py,sha256=eo5jBGnud3OLjxery6-0vNe9Izv2HocfSqM0wuZooWk,1620
+tddcli/adapters/base.py,sha256=9BhqnzALkvseRuPINuzp3sMFaLbNzlJwHNxA5siIEdg,3618
+tddcli/adapters/pytest_adapter.py,sha256=qLaW2YlYMyvg-PmZL_fKNbJmyYx06wUScFyMcjIxNlc,7387
+tddcli/adapters/vitest_adapter.py,sha256=py0lU8T7EEzXwTe3wBwZsc8vFfL0S_JSlR83lATenYk,6635
+tdd_cli-0.1.0.dist-info/METADATA,sha256=ZDmFLNR8s3r1-BYHPsZpRR5bKGn8QCUzvxcQXsZxcmY,17584
+tdd_cli-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+tdd_cli-0.1.0.dist-info/entry_points.txt,sha256=ToEhgkhPB4epNYbzkGE5lB-ZhiKj12r4B_Vp7KIbELY,40
+tdd_cli-0.1.0.dist-info/licenses/LICENSE,sha256=58gZrnAWFIvOo6A6l6XeG7tMHZZTQa2SRaZFc784NaY,1063
+tdd_cli-0.1.0.dist-info/RECORD,,

tdd_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tdd_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tdd = tddcli.cli:main

tdd_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 geuben
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tddcli/__init__.py

@@ -0,0 +1,6 @@
+"""tdd-cli — a ledger-backed TDD process controller for autonomous coding agents.
+
+State is derived from observed test execution, never asserted by the caller.
+"""
+
+__version__ = "0.1.0"

tddcli/adapters/__init__.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import importlib.metadata
+from pathlib import Path
+
+from .base import Adapter, Collection, GateResult, Verdict
+from .pytest_adapter import PytestAdapter
+from .vitest_adapter import VitestAdapter
+
+REGISTRY: dict[str, type[Adapter]] = {
+    "pytest": PytestAdapter,
+    "vitest": VitestAdapter,
+}
+
+
+def _entry_points():
+    """Third-party adapters, published under the `tddcli.adapters` entry-point group.
+
+    A separate seam so tests can substitute fake entry points without installing a
+    distribution. Loading is deferred to `build`: enumerating names must stay cheap
+    (doctor lists them), and a broken plugin must not break projects that never
+    reference it.
+    """
+    return importlib.metadata.entry_points(group="tddcli.adapters")
+
+
+def available() -> set[str]:
+    """Every adapter name that `build` could resolve, built-in or plugin."""
+    return set(REGISTRY) | {ep.name for ep in _entry_points()}
+
+
+def build(project, worktree: Path) -> Adapter:
+    # Built-ins always win: a plugin must not be able to shadow `pytest` and
+    # change what observed test execution means for every existing config.
+    cls = REGISTRY.get(project.adapter)
+    if cls is None:
+        for ep in _entry_points():
+            if ep.name == project.adapter:
+                cls = ep.load()
+                break
+    if cls is None:
+        raise RuntimeError(
+            f"unknown adapter {project.adapter!r}; available: {sorted(available())}"
+        )
+    return cls(project, worktree)
+
+
+__all__ = ["Adapter", "Collection", "GateResult", "Verdict", "REGISTRY", "available", "build"]

tddcli/adapters/base.py

@@ -0,0 +1,119 @@
+"""Adapter contract (§10). Adding an adapter requires no change to core logic."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .. import leases
+
+NOT_FOUND = "not_found"
+NOT_COLLECTED = "not_collected"
+PASSED = "passed"
+FAILED = "failed"
+
+
+@dataclass
+class Verdict:
+    project: str
+    adapter: str
+    target: str | None = None
+    target_outcome: str = NOT_FOUND
+    target_failure: str = ""
+    passed: list[str] = field(default_factory=list)
+    failed: list[str] = field(default_factory=list)
+    duration_ms: int = 0
+    error: str | None = None
+
+
+@dataclass
+class GateResult:
+    ok: bool
+    output: str = ""
+
+
+@dataclass
+class Collection:
+    """Per-file collection (R10.3): one uncollectable file must not destroy the set."""
+
+    tests: set[str] = field(default_factory=set)
+    failed_files: dict[str, str] = field(default_factory=dict)
+
+
+def run_command(
+    command: str, cwd: Path, timeout: int = 1800,
+    extra_env: dict[str, str] | None = None,
+) -> tuple[int, str, str]:
+    proc = subprocess.run(
+        command,
+        shell=True,
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        env=None if extra_env is None else {**os.environ, **extra_env},
+    )
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+class Adapter:
+    name = "base"
+
+    def __init__(self, project, worktree: Path):
+        self.project = project
+        self.worktree = worktree
+        self.root = worktree / project.root
+
+    def qualify(self, raw_id: str) -> str:
+        """Namespace a runner-native id with its project (R9.12)."""
+        return f"{self.project.name}::{raw_id}"
+
+    def strip(self, qualified: str) -> str:
+        prefix = f"{self.project.name}::"
+        return qualified[len(prefix):] if qualified.startswith(prefix) else qualified
+
+    def run(self, target: str | None = None) -> Verdict:
+        raise NotImplementedError
+
+    def _run_suite(self, command: str) -> tuple[int, str, str]:
+        """Run the suite under a machine-wide worker lease.
+
+        Substituting `{workers}` is opt-in per project; a command without the
+        placeholder runs verbatim, so parallelism stays exactly as the project
+        declared (§10). TDD_WORKERS is exported either way for commands that
+        prefer to read the budget themselves. The lease is held for the whole
+        invocation so concurrent agents in other worktrees see this one and
+        take a smaller share.
+        """
+        with leases.worker_lease() as workers:
+            return run_command(
+                command.replace("{workers}", str(workers)),
+                self.root,
+                extra_env={"TDD_WORKERS": str(workers)},
+            )
+
+    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"
+
+    def collect(self) -> Collection:
+        raise NotImplementedError
+
+    def collectable(self) -> GateResult:
+        raise NotImplementedError
+
+    def lint(self) -> GateResult:
+        return self._gate(self.project.lint)
+
+    def typecheck(self) -> GateResult:
+        return self._gate(self.project.typecheck)
+
+    def _gate(self, commands: list[str]) -> GateResult:
+        chunks = []
+        for cmd in commands:
+            code, out, err = run_command(cmd, self.root)
+            if code != 0:
+                chunks.append(f"$ {cmd}\n{out}\n{err}".strip())
+        return GateResult(ok=not chunks, output="\n\n".join(chunks)[:4000])