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

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

@@ -6,6 +6,93 @@ and the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-05
+
+### Added
+
+- **cargo adapter** — Rust driver through `cargo test`. Ids are `<target>::<path>`
+  (`lib::…` for unit tests, `<tests-file-stem>::…` for integration tests) and compose
+  to `--lib`/`--test <name>` + `-- --exact <path>` for targeted runs. Verdicts are
+  parsed from cargo's per-test console lines, attributed to targets by the
+  `Running …` headers with stderr merged; doc-tests are excluded. A compile error maps
+  to `not_collected`, matching gradle/xctest. Collection is `cargo test --tests --
+  --list` with a per-file `--test <stem>` fallback; `tdd doctor`'s collectable gate is
+  `cargo test --no-run`. Target lint requires the `::` separator.
+
+## [0.9.0] - 2026-09-03
+
+### Added
+
+- **`tdd note` — an executor-narrative channel.** `tdd note "<text>"` attaches
+  a phase-stamped note to the current cycle, or a run-level note once the run
+  has ended (it falls back to the latest run, so no active run is required).
+  Cycle notes render in the friction log as blockquote claims under their cycle;
+  run-level notes render under a new `## Executor narrative` section, which is
+  omitted when there are none. Envelopes that carry an integrity event now nudge
+  for a note while the reason is fresh (silenced once the cycle has one), and
+  the terminal `COMPLETE` envelope — via `advance` or a final-cycle skip — asks
+  for a closing narrative before rendering. Stored in a new `note` table via a
+  v7→v8 ledger migration (#77, #94).
+
+- **Baseline sanity gate.** `run start` refuses a baseline whose failing ratio
+  exceeds a threshold (default 0.5, suites under 10 collected tests exempt) with
+  `reason: "baseline_implausible"`, on the grounds that a mostly-red suite means
+  the environment is broken rather than the code. A per-project
+  `baseline_max_failure_ratio` in `tdd.toml` overrides the default, and
+  `--accept-baseline` bypasses the gate and logs a `baseline_accepted` integrity
+  event (#67, #84).
+
+- **Standing-failure delta.** A non-empty baseline is now compared against the
+  previous run's baseline for the same worktree and a `baseline_standing_delta`
+  event partitions the failing set into new versus inherited failures, so a
+  pre-existing red test is distinguishable from one that broke since the last
+  run (#67, #84).
+
+- **Per-project `health_command`.** An optional command in `tdd.toml` that is
+  probed before baseline capture; if it fails, `run start` refuses with
+  `reason: "services_unreachable"` instead of recording a baseline against a
+  down dependency (#67, #84).
+
+- **Declared-target lint.** `plan register` and `run start` now lint every
+  declared target against the adapter's id grammar (pytest `::`, vitest ` > `,
+  gradle `Class/method`, xctest `Bundle/Class/testMethod`) and against project
+  roots: a target path that duplicates a non-`.` project root prefix is refused
+  unless the nested path genuinely exists in the worktree. Findings are returned
+  under `reason: "target_lint"`; `run start` re-lints the stored contract
+  against the current config before claiming a baseline (#71, #88).
+
+- **Per-adapter sensitivity evidence line.** Each adapter now extracts a
+  `target_evidence` line from a failing target — the first `E` line for pytest
+  (skipping the xdist worker header), the first `: error:` line in the test's
+  window for xctest, `failureMessages[0]` for vitest, the junit failure message
+  for gradle, and the last non-empty output line for exec. The sensitivity check
+  persists it as `sensitivity_check.evidence_line` (v6→v7 migration) and the
+  friction log's observed snippet prefers it over the raw first line, rendering
+  `<no assertion line captured>` when empty and keeping the tail of over-long
+  lines. Legacy rows with no stored evidence keep the first-line fallback (#68,
+  #90).
+
+- **Diagnosable executor attribution.** `TDD_EXECUTOR_MODEL` lets a harness
+  declare the executor identity (`source: declared`), taking precedence over
+  transcript detection. When identity cannot be resolved, `Executor.reason`
+  says why — session id unset, transcript not found, or transcript without a
+  model record — and `run start` logs an `executor_unknown` event and surfaces
+  `executor_warning` in its envelope. `tdd doctor` gains an informational
+  executor-identity check (#74, #92).
+
+### Changed
+
+- **Target adoption is evaluated in the same `advance`.** When a cycle's
+  declared target is missing and exactly one new test appears, `advance`
+  adopts it (logging `declared_test_mismatch`) and judges RED — or drives the
+  sensitivity check when it passed — from the suite run that already happened,
+  instead of asking for a re-run. A declared id that differs
+  from a single same-file candidate only by separator normalisation is
+  disambiguated and adopted without asking; two same-file candidates still
+  require an explicit `tdd target` (#72, #91).
+
+- CI now tests on Python 3.11 and 3.14 only (#87).
+
 ## [0.8.0] - 2026-08-28
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.8.0
+Version: 0.10.0
 Summary: Ledger-backed TDD process controller for autonomous coding agents
 Project-URL: Homepage, https://github.com/geuben/tdd-cli
 Project-URL: Repository, https://github.com/geuben/tdd-cli
@@ -319,6 +319,13 @@ rendered, never written. Judgement enters in exactly two ways:
   `commit_shape_deviation`, `test_setup_smell`, `unplanned_change`, `new_work_raised`.
   `plan_defect` is the one that matters most: it records where the plan and the codebase
   disagreed, which is precisely what the next plan needs to know.
+- **Per cycle or run, through `tdd note "<text>"`** — free-text narrative captured at the
+  moment the reason exists. Cycle notes are scoped to the open cycle and phase; run-level
+  notes are written after the run ends and attach to the run. Both render in the friction
+  log as visually distinct blockquotes (claims, not measurements). Use notes to record
+  *why* something happened — a plan assumption that was wrong, an integrity event that the
+  telemetry already captures but cannot explain. Notes are unverified by design; an auditor
+  compares claims against reality.
 - **Per run, as prose appended below the rendered document.** Legitimate and expected —
   post-run narrative (CI failures, patterns noticed) has no cycle to attach to. But it
   is unverified: an auditor should trust the projected sections and read appended
@@ -334,7 +341,7 @@ the next plan is written.
 
 ## Adapters
 
-`pytest`, `vitest`, `gradle`, `xctest`, and `exec` are built in. The pytest adapter runs
+`pytest`, `vitest`, `gradle`, `xctest`, `cargo`, and `exec` 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
@@ -386,6 +393,23 @@ lease        = "ios-simulator"
 timeout      = 900
 ```
 
+The `cargo` adapter drives Rust crates through `cargo test`. Test ids are
+`<target>::<path>` — `lib::layout::tests::wraps_short` for a `#[cfg(test)]` unit test,
+`roundtrip::renders_cover_only` for `tests/roundtrip.rs` — so a targeted run composes to
+cargo's own selectors (`--lib` / `--test <name>` plus `-- --exact <path>`) with no
+translation. Verdicts come from cargo's per-test console lines, attributed to targets by
+the `Running …` headers (stderr is merged so the order survives); doc-tests are excluded
+(`--tests`). A *compile* failure maps to `not_collected`, as for gradle and xctest: write a
+compiling stub (`todo!()`), then observe the panic. Declare `tests/` as `test_paths`, not
+`src/` — unit-test modules live inside production files and must not be staged as tests.
+
+```toml
+[project.kernel]
+root       = "kernel"
+adapter    = "cargo"
+test_paths = ["tests/"]
+```
+
 Third-party adapters register under the
 `tddcli.adapters` entry-point group:
 
@@ -441,6 +465,7 @@ and is never reclassified as a pin.
 | `tdd cycle skip --reason` | sanctioned path for a cycle the plan got wrong |
 | `tdd sensitivity begin\|check\|end` | prove a passing test can fail; verify restore |
 | `tdd annotate --key --value` | attach judgement to the current cycle |
+| `tdd note "<text>"` | attach a free-text narrative note to the current cycle or run |
 | `tdd blocker --kind --detail` | typed blocker; releases the stop hook |
 | `tdd resume [--unblock --note]` | reconstruct position; human intervention |
 | `tdd log render [--out]` | project the ledger into a friction log |
@@ -520,6 +545,73 @@ kind `no_baseline_for_project` rather than mislabelling them as regressions. Rec
 failures as pre-existing) and records a `baseline_amended` event. The next advance proceeds
 with the project properly baselined.
 
+### Baseline sanity gate (R9.5g)
+
+`run start` refuses a baseline whose failure ratio is implausibly high — a signal that the
+environment, not the code, is broken. A project is flagged when it collected at least 10 tests
+(`BASELINE_MIN_COLLECTED`) and more than 50% of them failed (`BASELINE_MAX_FAILURE_RATIO_DEFAULT`):
+
+    error: baseline_implausible — backend: 1005/1010 failing (ratio 0.995)
+
+The gate targets stack-down blowouts (all 1000 tests failing because a service is unreachable),
+not small pre-existing failure sets (baseline subtraction handles those). A project collecting
+fewer than 10 tests is exempt — a 2-of-3 red baseline is ordinary pre-existing-failure territory,
+not a broken stack.
+
+Pass `--accept-baseline` to override the refusal and proceed anyway:
+
+    tdd run start --plan tasks/plan.md --accept-baseline
+
+An accepted implausible baseline records a `baseline_accepted` integrity event (visible in
+`tdd metrics` and the friction log) so the override is never silent. The gate runs on every
+baseline, including reused ones.
+
+To raise the threshold for a project whose legitimate baseline is inherently noisy, set
+`baseline_max_failure_ratio` in `tdd.toml`:
+
+```toml
+[project.legacy]
+root = "legacy"
+adapter = "pytest"
+baseline_max_failure_ratio = 0.8    # allow up to 80% failing at baseline
+```
+
+The value must be in `(0, 1]`. Without it, the repo-wide default of 0.5 applies.
+
+### Standing-failure delta
+
+When a non-empty baseline is captured, `run start` emits a `baseline_standing_delta` integrity
+event partitioning the current standing failures into:
+
+- **new** — absent from the previous run's baseline for this project (growing problem)
+- **inherited** — also present in the previous baseline (stable background noise)
+- **resolved** — in the previous baseline but absent now (fixed between runs)
+
+The event is visible in `tdd metrics` under `integrity_events`. A first run with no prior
+baseline reports every failure as `new`. A fully-green baseline (zero failing tests) emits
+nothing. Use this to spot a permanently-red set that baseline subtraction would otherwise hide.
+
+### Environment-dependent suites
+
+Declare a `health_command` on a project to probe reachability before `run start` captures its
+baseline:
+
+```toml
+[project.backend]
+root = "backend"
+adapter = "pytest"
+health_command = "curl -fsS http://localhost:8080/healthz"
+```
+
+If the command exits non-zero, `run start` refuses immediately with `reason:
+"services_unreachable"` — before claiming the worktree, before probing, before writing anything
+to the ledger. The error names the project and its exit code so the agent can surface the exact
+diagnosis rather than recording a ~1000-failure baseline and continuing.
+
+There is no override flag for `services_unreachable`: a down stack yields no believable baseline.
+The resolution is to fix the stack or drop the project from this run. Presence of `health_command`
+is the marker that a project requires live services; no separate boolean is needed.
+
 ## Running a long baseline
 
 `run start` probes the reachable project set (R9.5c) before a run exists, and on a real project

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

@@ -291,6 +291,13 @@ rendered, never written. Judgement enters in exactly two ways:
   `commit_shape_deviation`, `test_setup_smell`, `unplanned_change`, `new_work_raised`.
   `plan_defect` is the one that matters most: it records where the plan and the codebase
   disagreed, which is precisely what the next plan needs to know.
+- **Per cycle or run, through `tdd note "<text>"`** — free-text narrative captured at the
+  moment the reason exists. Cycle notes are scoped to the open cycle and phase; run-level
+  notes are written after the run ends and attach to the run. Both render in the friction
+  log as visually distinct blockquotes (claims, not measurements). Use notes to record
+  *why* something happened — a plan assumption that was wrong, an integrity event that the
+  telemetry already captures but cannot explain. Notes are unverified by design; an auditor
+  compares claims against reality.
 - **Per run, as prose appended below the rendered document.** Legitimate and expected —
   post-run narrative (CI failures, patterns noticed) has no cycle to attach to. But it
   is unverified: an auditor should trust the projected sections and read appended
@@ -306,7 +313,7 @@ the next plan is written.
 
 ## Adapters
 
-`pytest`, `vitest`, `gradle`, `xctest`, and `exec` are built in. The pytest adapter runs
+`pytest`, `vitest`, `gradle`, `xctest`, `cargo`, and `exec` 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
@@ -358,6 +365,23 @@ lease        = "ios-simulator"
 timeout      = 900
 ```
 
+The `cargo` adapter drives Rust crates through `cargo test`. Test ids are
+`<target>::<path>` — `lib::layout::tests::wraps_short` for a `#[cfg(test)]` unit test,
+`roundtrip::renders_cover_only` for `tests/roundtrip.rs` — so a targeted run composes to
+cargo's own selectors (`--lib` / `--test <name>` plus `-- --exact <path>`) with no
+translation. Verdicts come from cargo's per-test console lines, attributed to targets by
+the `Running …` headers (stderr is merged so the order survives); doc-tests are excluded
+(`--tests`). A *compile* failure maps to `not_collected`, as for gradle and xctest: write a
+compiling stub (`todo!()`), then observe the panic. Declare `tests/` as `test_paths`, not
+`src/` — unit-test modules live inside production files and must not be staged as tests.
+
+```toml
+[project.kernel]
+root       = "kernel"
+adapter    = "cargo"
+test_paths = ["tests/"]
+```
+
 Third-party adapters register under the
 `tddcli.adapters` entry-point group:
 
@@ -413,6 +437,7 @@ and is never reclassified as a pin.
 | `tdd cycle skip --reason` | sanctioned path for a cycle the plan got wrong |
 | `tdd sensitivity begin\|check\|end` | prove a passing test can fail; verify restore |
 | `tdd annotate --key --value` | attach judgement to the current cycle |
+| `tdd note "<text>"` | attach a free-text narrative note to the current cycle or run |
 | `tdd blocker --kind --detail` | typed blocker; releases the stop hook |
 | `tdd resume [--unblock --note]` | reconstruct position; human intervention |
 | `tdd log render [--out]` | project the ledger into a friction log |
@@ -492,6 +517,73 @@ kind `no_baseline_for_project` rather than mislabelling them as regressions. Rec
 failures as pre-existing) and records a `baseline_amended` event. The next advance proceeds
 with the project properly baselined.
 
+### Baseline sanity gate (R9.5g)
+
+`run start` refuses a baseline whose failure ratio is implausibly high — a signal that the
+environment, not the code, is broken. A project is flagged when it collected at least 10 tests
+(`BASELINE_MIN_COLLECTED`) and more than 50% of them failed (`BASELINE_MAX_FAILURE_RATIO_DEFAULT`):
+
+    error: baseline_implausible — backend: 1005/1010 failing (ratio 0.995)
+
+The gate targets stack-down blowouts (all 1000 tests failing because a service is unreachable),
+not small pre-existing failure sets (baseline subtraction handles those). A project collecting
+fewer than 10 tests is exempt — a 2-of-3 red baseline is ordinary pre-existing-failure territory,
+not a broken stack.
+
+Pass `--accept-baseline` to override the refusal and proceed anyway:
+
+    tdd run start --plan tasks/plan.md --accept-baseline
+
+An accepted implausible baseline records a `baseline_accepted` integrity event (visible in
+`tdd metrics` and the friction log) so the override is never silent. The gate runs on every
+baseline, including reused ones.
+
+To raise the threshold for a project whose legitimate baseline is inherently noisy, set
+`baseline_max_failure_ratio` in `tdd.toml`:
+
+```toml
+[project.legacy]
+root = "legacy"
+adapter = "pytest"
+baseline_max_failure_ratio = 0.8    # allow up to 80% failing at baseline
+```
+
+The value must be in `(0, 1]`. Without it, the repo-wide default of 0.5 applies.
+
+### Standing-failure delta
+
+When a non-empty baseline is captured, `run start` emits a `baseline_standing_delta` integrity
+event partitioning the current standing failures into:
+
+- **new** — absent from the previous run's baseline for this project (growing problem)
+- **inherited** — also present in the previous baseline (stable background noise)
+- **resolved** — in the previous baseline but absent now (fixed between runs)
+
+The event is visible in `tdd metrics` under `integrity_events`. A first run with no prior
+baseline reports every failure as `new`. A fully-green baseline (zero failing tests) emits
+nothing. Use this to spot a permanently-red set that baseline subtraction would otherwise hide.
+
+### Environment-dependent suites
+
+Declare a `health_command` on a project to probe reachability before `run start` captures its
+baseline:
+
+```toml
+[project.backend]
+root = "backend"
+adapter = "pytest"
+health_command = "curl -fsS http://localhost:8080/healthz"
+```
+
+If the command exits non-zero, `run start` refuses immediately with `reason:
+"services_unreachable"` — before claiming the worktree, before probing, before writing anything
+to the ledger. The error names the project and its exit code so the agent can surface the exact
+diagnosis rather than recording a ~1000-failure baseline and continuing.
+
+There is no override flag for `services_unreachable`: a down stack yields no believable baseline.
+The resolution is to fix the stack or drop the project from this run. Presence of `health_command`
+is the marker that a project requires live services; no separate boolean is needed.
+
 ## Running a long baseline
 
 `run start` probes the reachable project set (R9.5c) before a run exists, and on a real project

{tdd_cli-0.8.0 → tdd_cli-0.10.0}/examples/skills/tdd-drive/SKILL.md

@@ -74,9 +74,16 @@ end of the run.
 - The cycle absorbed undeclared scope, or surfaced follow-up work:
   `--key unplanned_change` / `--key new_work_raised`.
 
+To capture *why* something happened — a plan assumption that proved wrong, the reason an
+integrity event fired — use `tdd note "<text>"` at the moment you know. A note written
+during an open cycle is stamped with that cycle and phase and appears in the friction log
+as a blockquote alongside the cycle's telemetry. After the run ends, `tdd note` attaches
+at run level and renders in a dedicated **Executor narrative** section. Notes are unverified
+by design; write them as claims, not measurements.
+
 Narrative that spans cycles or happened after the run (CI failures, patterns) goes as
-markdown appended below the rendered friction log after `tdd log render` — never into a
-cycle annotation it doesn't belong to.
+`tdd note` after the run ends, or as markdown appended below the rendered friction log
+after `tdd log render` — never into a cycle annotation it doesn't belong to.
 
 ## When a suite run changes nothing
 

{tdd_cli-0.8.0 → tdd_cli-0.10.0}/pyproject.toml

@@ -47,10 +47,11 @@ 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", "zizmor>=1.29"]
+dev = ["pytest>=8.0", "pytest-json-report>=1.5", "pytest-xdist>=3.5", "ruff>=0.5", "zizmor>=1.29"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+addopts = ["-n", "auto"]
 
 [tool.ruff]
 line-length = 100

{tdd_cli-0.8.0 → tdd_cli-0.10.0}/src/tddcli/__init__.py

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

{tdd_cli-0.8.0 → tdd_cli-0.10.0}/src/tddcli/adapters/__init__.py

@@ -4,6 +4,7 @@ import importlib.metadata
 from pathlib import Path
 
 from .base import Adapter, Collection, GateResult, Verdict
+from .cargo_adapter import CargoAdapter
 from .exec_adapter import ExecAdapter
 from .gradle_adapter import GradleAdapter
 from .pytest_adapter import PytestAdapter
@@ -11,6 +12,7 @@ from .vitest_adapter import VitestAdapter
 from .xctest_adapter import XCTestAdapter
 
 REGISTRY: dict[str, type[Adapter]] = {
+    "cargo": CargoAdapter,
     "exec": ExecAdapter,
     "gradle": GradleAdapter,
     "pytest": PytestAdapter,

{tdd_cli-0.8.0 → tdd_cli-0.10.0}/src/tddcli/adapters/base.py

@@ -25,6 +25,7 @@ class Verdict:
     target: str | None = None
     target_outcome: str = NOT_FOUND
     target_failure: str = ""
+    target_evidence: str = ""
     passed: list[str] = field(default_factory=list)
     failed: list[str] = field(default_factory=list)
     duration_ms: int = 0
@@ -214,6 +215,14 @@ class Adapter:
             return None
         return {k: os.path.expandvars(v) for k, v in merged.items()}
 
+    def lint_target_id(self, native: str) -> str | None:
+        """Return a problem message when `native` can never match a collected id, else None."""
+        return None
+
+    def target_path(self, native: str) -> str | None:
+        """Return the file-path portion of `native`, or None for non-path-bearing ids."""
+        return None
+
     def stub_hint(self) -> str:
         """The language idiom for a stub body, quoted into the create_stub directive."""
         return "a body that fails loudly, never working logic"