tdd-cli 0.5.1__tar.gz → 0.7.0__tar.gz

{tdd_cli-0.5.1 → tdd_cli-0.7.0}/CHANGELOG.md

@@ -4,6 +4,52 @@ 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.7.0] - 2026-08-23
+
+### Fixed
+
+- **Concurrent `tdd advance` no longer corrupts a run.** Two `advance` processes
+  racing on the same worktree could both close the same cycle row. Because
+  `close_cycle` unconditionally opened the next ordinal, a double-close forked the
+  run into two parallel cycle chains; every remaining cycle ran twice, the run
+  "completed" with one chain's last row permanently open, and the doubling was
+  invisible from the agent's perspective. `close_cycle` now re-reads `closed_at`
+  before acting; if the row is already closed it returns the currently-open cycle
+  without transitioning or opening anything. `open_cycle` returns the existing open
+  row for an ordinal rather than inserting a duplicate.
+
+### Added
+
+- **Per-worktree advance claim.** `tdd advance` now acquires a `advance_claim` row
+  before dispatching. A second concurrent `advance` is refused immediately with
+  `ok: false`, `reason: "advance_in_flight"`, and metadata (`pid`, `started_at`,
+  `elapsed_s`) that lets the agent confirm the holder is still alive. The claim is
+  released in a `finally` so a raising handler cannot wedge the worktree; a claim
+  held by a dead pid is reclaimed automatically on the next call. Schema version
+  bumped to 3.
+
+## [0.6.0] - 2026-08-19
+
+### Added
+
+- **gradle adapter** — Gradle driver for Kotlin/JVM and Android projects. Runs the
+  project's Gradle test task (`./gradlew test`, `testDebugUnitTest`, or
+  `connectedDebugAndroidTest`) and reads per-test verdicts from the JUnit XML Gradle
+  writes, rather than scraping the console — unit and instrumented tasks share one
+  parser, so the task is a config choice, not a code path. A compile failure maps to
+  `not_collected` rather than `failed`: Kotlin has no separate collection phase, so a
+  test referencing a missing symbol fails the build, and the "stub before RED"
+  discipline holds exactly as it does for a Python import error. The discriminator is
+  whether fresh JUnit XML was produced, not "BUILD FAILED" (a test failure prints that
+  too); a `--tests` filter matching nothing maps to `not_found`. Stale results are
+  cleared before each run, which also invalidates Gradle's up-to-date check so a
+  targeted run is scored only against the XML it produced. Collection is a per-file
+  grep of Kotlin/Java sources (Gradle has no cheap whole-suite enumerator), so one
+  unreadable file cannot destroy the set. `tdd doctor` gains a `gradle wrapper present`
+  check, active only when the command uses `./gradlew` (#41).
+
 ## [0.5.1] - 2026-08-17
 
 ### Added

{tdd_cli-0.5.1 → tdd_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.5.1
+Version: 0.7.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
@@ -290,12 +290,57 @@ 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.
+`pytest`, `vitest`, `gradle`, `xctest`, 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
+lockfile at the top). With no marker, the active environment's bare `pytest` runs. An
+explicit `test_command` always wins.
+
+The `gradle` adapter drives Kotlin/JVM and Android projects. It runs the project's Gradle
+test task and reads per-test verdicts from the JUnit XML Gradle writes, rather than
+scraping the console. The task is a config choice — `./gradlew test` or `testDebugUnitTest`
+for fast JVM unit tests, `connectedDebugAndroidTest` for instrumented tests on a device
+(give those a longer `timeout` and a `lease` so only one run touches the device at a time).
+A *compile* failure maps to `not_collected`, not `failed`: Kotlin has no separate
+collection phase, so a stub referencing a missing symbol fails the build, and the "stub
+before RED" discipline holds exactly as it does for a Python import error.
+
+```toml
+[project.android-app]
+root         = "android-app"
+adapter      = "gradle"
+test_paths   = ["src/test/"]
+test_command = "./gradlew testDebugUnitTest"
+```
+
+The `xctest` adapter drives Swift and Objective-C projects through `xcodebuild`. Test ids
+use xcodebuild's own `-only-testing:` format — `BundleName/ClassName/testMethodName` — so
+a single XCTest can be driven through RED → GREEN without any id translation. Collection
+prefers `xcodebuild test -enumerate-tests` (Xcode 16+) and falls back to grepping
+`class Foo: XCTestCase` / `func testBar()` out of the Swift sources under `test_paths`,
+deriving the bundle name from `-scheme`. As with gradle, a *build* failure maps to
+`not_collected` rather than `failed`, so a stub referencing a missing symbol is not
+mistaken for RED.
+
+`test_command` is required here — the adapter cannot guess the scheme, destination, or
+derived-data path. It appends `-only-testing:` for targeted runs and `-enumerate-tests`
+for collection, and changes nothing else. Simulator runs are serial in practice: give
+them a `lease` so two projects don't drive the same simulator at once.
+
+```toml
+[project.native-ios]
+root         = "native-ios"
+adapter      = "xctest"
+test_paths   = ["AppTests/"]
+test_command = """xcodebuild test \
+  -project App.xcodeproj \
+  -scheme AppTests \
+  -destination 'platform=iOS Simulator,name=App-Unit' \
+  -derivedDataPath /tmp/app-unit-dd"""
+lease        = "ios-simulator"
+timeout      = 900
+```
 
 Third-party adapters register under the
 `tddcli.adapters` entry-point group:
@@ -358,14 +403,49 @@ and is never reclassified as a pin.
 | `tdd metrics` | fidelity, attempts, violations, interventions |
 | `tdd fleet [--json]` | all active runs across every worktree; read-only |
 
+## Scoped baseline capture (R9.5c)
+
+`run start` probes only the projects the plan can actually reach: the declared cycle projects
+plus the transitive `consumed_by` closure of artifacts whose producer is in that set. Projects
+outside the reachable set never run during the plan, so their baseline is never subtracted from
+anything — probing them is pure overhead. A `baseline_scoped` integrity event records which
+projects were skipped, so the scoping is auditable.
+
+Pass `--baseline-all` to probe every project in `tdd.toml` regardless:
+
+    tdd run start --plan tasks/plan.md --baseline-all
+
+Use this when a cycle may edit files outside the predicted reachable set and you want every
+project baselined up front rather than hitting the `no_baseline_for_project` escape hatch later.
+
+### When a sweep reaches an un-baselined project (R9.5d)
+
+If an edit during a run touches a file owned by an artifact that was outside the predicted
+reachable set, the close sweep may pull in a project that was never baselined. Its failures are
+unattributable — no baseline exists to subtract — so the sweep replies `resolve_blocker` with
+kind `no_baseline_for_project` rather than mislabelling them as regressions. Recovery:
+
+    tdd blocker --kind no_baseline_for_project --detail "svc pulled in unexpectedly"
+    tdd resume --unblock --accept-failures --note "folding svc sweep failures into baseline"
+
+`--accept-failures` inserts a fresh baseline row for the un-baselined project (recording those
+failures as pre-existing) and records a `baseline_amended` event. The next advance proceeds
+with the project properly baselined.
+
 ## Running a long baseline
 
-`run start` probes every project's suite before a run exists (R9.5a), and on a real project
+`run start` probes the reachable project set (R9.5c) before a run exists, 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:
+baseline that was never stuck.
+
+`tdd advance` is similarly single-flight per worktree. A close sweep (artifact regeneration, full
+suite, lint, typecheck) can run for several minutes. If an advance appears to hang, **do not
+re-run it**: a second `advance` against the same worktree is refused with
+`reason: "advance_in_flight"`. The refusal carries `pid`, `started_at`, and `elapsed_s` so the
+agent can confirm the first process is still alive. Run `tdd status` to see the current run state. 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

{tdd_cli-0.5.1 → tdd_cli-0.7.0}/README.md

@@ -262,12 +262,57 @@ 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.
+`pytest`, `vitest`, `gradle`, `xctest`, 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
+lockfile at the top). With no marker, the active environment's bare `pytest` runs. An
+explicit `test_command` always wins.
+
+The `gradle` adapter drives Kotlin/JVM and Android projects. It runs the project's Gradle
+test task and reads per-test verdicts from the JUnit XML Gradle writes, rather than
+scraping the console. The task is a config choice — `./gradlew test` or `testDebugUnitTest`
+for fast JVM unit tests, `connectedDebugAndroidTest` for instrumented tests on a device
+(give those a longer `timeout` and a `lease` so only one run touches the device at a time).
+A *compile* failure maps to `not_collected`, not `failed`: Kotlin has no separate
+collection phase, so a stub referencing a missing symbol fails the build, and the "stub
+before RED" discipline holds exactly as it does for a Python import error.
+
+```toml
+[project.android-app]
+root         = "android-app"
+adapter      = "gradle"
+test_paths   = ["src/test/"]
+test_command = "./gradlew testDebugUnitTest"
+```
+
+The `xctest` adapter drives Swift and Objective-C projects through `xcodebuild`. Test ids
+use xcodebuild's own `-only-testing:` format — `BundleName/ClassName/testMethodName` — so
+a single XCTest can be driven through RED → GREEN without any id translation. Collection
+prefers `xcodebuild test -enumerate-tests` (Xcode 16+) and falls back to grepping
+`class Foo: XCTestCase` / `func testBar()` out of the Swift sources under `test_paths`,
+deriving the bundle name from `-scheme`. As with gradle, a *build* failure maps to
+`not_collected` rather than `failed`, so a stub referencing a missing symbol is not
+mistaken for RED.
+
+`test_command` is required here — the adapter cannot guess the scheme, destination, or
+derived-data path. It appends `-only-testing:` for targeted runs and `-enumerate-tests`
+for collection, and changes nothing else. Simulator runs are serial in practice: give
+them a `lease` so two projects don't drive the same simulator at once.
+
+```toml
+[project.native-ios]
+root         = "native-ios"
+adapter      = "xctest"
+test_paths   = ["AppTests/"]
+test_command = """xcodebuild test \
+  -project App.xcodeproj \
+  -scheme AppTests \
+  -destination 'platform=iOS Simulator,name=App-Unit' \
+  -derivedDataPath /tmp/app-unit-dd"""
+lease        = "ios-simulator"
+timeout      = 900
+```
 
 Third-party adapters register under the
 `tddcli.adapters` entry-point group:
@@ -330,14 +375,49 @@ and is never reclassified as a pin.
 | `tdd metrics` | fidelity, attempts, violations, interventions |
 | `tdd fleet [--json]` | all active runs across every worktree; read-only |
 
+## Scoped baseline capture (R9.5c)
+
+`run start` probes only the projects the plan can actually reach: the declared cycle projects
+plus the transitive `consumed_by` closure of artifacts whose producer is in that set. Projects
+outside the reachable set never run during the plan, so their baseline is never subtracted from
+anything — probing them is pure overhead. A `baseline_scoped` integrity event records which
+projects were skipped, so the scoping is auditable.
+
+Pass `--baseline-all` to probe every project in `tdd.toml` regardless:
+
+    tdd run start --plan tasks/plan.md --baseline-all
+
+Use this when a cycle may edit files outside the predicted reachable set and you want every
+project baselined up front rather than hitting the `no_baseline_for_project` escape hatch later.
+
+### When a sweep reaches an un-baselined project (R9.5d)
+
+If an edit during a run touches a file owned by an artifact that was outside the predicted
+reachable set, the close sweep may pull in a project that was never baselined. Its failures are
+unattributable — no baseline exists to subtract — so the sweep replies `resolve_blocker` with
+kind `no_baseline_for_project` rather than mislabelling them as regressions. Recovery:
+
+    tdd blocker --kind no_baseline_for_project --detail "svc pulled in unexpectedly"
+    tdd resume --unblock --accept-failures --note "folding svc sweep failures into baseline"
+
+`--accept-failures` inserts a fresh baseline row for the un-baselined project (recording those
+failures as pre-existing) and records a `baseline_amended` event. The next advance proceeds
+with the project properly baselined.
+
 ## Running a long baseline
 
-`run start` probes every project's suite before a run exists (R9.5a), and on a real project
+`run start` probes the reachable project set (R9.5c) before a run exists, 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:
+baseline that was never stuck.
+
+`tdd advance` is similarly single-flight per worktree. A close sweep (artifact regeneration, full
+suite, lint, typecheck) can run for several minutes. If an advance appears to hang, **do not
+re-run it**: a second `advance` against the same worktree is refused with
+`reason: "advance_in_flight"`. The refusal carries `pid`, `started_at`, and `elapsed_s` so the
+agent can confirm the first process is still alive. Run `tdd status` to see the current run state. 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

{tdd_cli-0.5.1 → tdd_cli-0.7.0}/src/tddcli/__init__.py

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

{tdd_cli-0.5.1 → tdd_cli-0.7.0}/src/tddcli/adapters/__init__.py

@@ -5,12 +5,14 @@ from pathlib import Path
 
 from .base import Adapter, Collection, GateResult, Verdict
 from .exec_adapter import ExecAdapter
+from .gradle_adapter import GradleAdapter
 from .pytest_adapter import PytestAdapter
 from .vitest_adapter import VitestAdapter
 from .xctest_adapter import XCTestAdapter
 
 REGISTRY: dict[str, type[Adapter]] = {
     "exec": ExecAdapter,
+    "gradle": GradleAdapter,
     "pytest": PytestAdapter,
     "vitest": VitestAdapter,
     "xctest": XCTestAdapter,

tdd_cli-0.7.0/src/tddcli/adapters/gradle_adapter.py

@@ -0,0 +1,327 @@
+"""gradle adapter — Gradle driver for Kotlin/JVM and Android projects (§10).
+
+Runs the project's Gradle test task (`./gradlew test`, `testDebugUnitTest`,
+`connectedDebugAndroidTest`, …) and reads the per-test verdicts from the
+JUnit XML Gradle always writes.  Console output is *not* parsed: Gradle's
+console is a task-level summary, not a reliable per-test log, whereas the XML
+under `build/test-results/` (unit) and `build/outputs/.../androidTest-results/`
+(instrumented) carries an exact `classname` / `name` / `failure` for every
+case.  Both unit and instrumented tasks write the same JUnit shape, so one
+parser serves both — the task is a config choice (`test_command`), not a code
+path.
+
+Test ids use `FQCN/method` so a targeted run composes to Gradle's own filter
+without translation:
+
+    com.example.PollCadenceTest/scalesOnlyUnderE2E
+
+The adapter appends `--tests com.example.PollCadenceTest.scalesOnlyUnderE2E`
+for a targeted run; nothing else.
+
+A *compile* failure maps to `not_collected`, not `failed`.  Kotlin has no
+separate collection phase — a test referencing a missing symbol fails
+`compileTestKotlin`, not the run — so a compile error is treated like Python's
+import error and Swift's build failure: write a compiling stub, then observe
+the assertion failure.  The discriminator is not "BUILD FAILED" (a *test*
+failure prints that too) but *whether any fresh JUnit XML was produced*: tests
+that ran leave results, a compile error leaves none.
+
+Stale results (R10.3): Gradle leaves the previous run's XML on disk and skips
+up-to-date tasks, so a targeted `--tests` run could otherwise be scored against
+another test's old XML.  The adapter deletes the result files before each run —
+which also invalidates Gradle's up-to-date check, forcing the task to actually
+re-run — so whatever XML exists afterward belongs to this invocation alone.
+
+Collection is a per-file grep of Kotlin/Java sources (R10.3's fallback):
+Gradle has no cheap whole-suite test enumerator, so there is no batch path.
+One uncollectable file is recorded against itself and cannot destroy the set.
+
+Config (`tdd.toml`):
+
+    [project.android-app]
+    root         = "android-app"
+    adapter      = "gradle"
+    test_paths   = ["src/test/"]                 # Kotlin/Java test sources
+    test_command = "./gradlew testDebugUnitTest"  # JVM unit tests (fast)
+
+Instrumented tests run the same way through a different task; give them a
+longer timeout and a `lease` so only one run touches a device at a time:
+
+    [project.android-e2e]
+    root         = "android-app"
+    adapter      = "gradle"
+    test_paths   = ["src/androidTest/"]
+    test_command = "./gradlew connectedDebugAndroidTest"
+    lease        = "android-emulator"
+    timeout      = 1200
+    in_close_sweep = false                        # too slow per cycle
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+import time
+from pathlib import Path
+from xml.etree import ElementTree
+
+from .base import (
+    FAILED,
+    NOT_COLLECTED,
+    PASSED,
+    Adapter,
+    Collection,
+    GateResult,
+    Verdict,
+    clip_failure,
+)
+
+# ---------------------------------------------------------------------------
+# Patterns applied to gradle console output (only to classify a run that
+# produced no test results — the XML is authoritative for everything else)
+# ---------------------------------------------------------------------------
+
+_BUILD_FAILED_RE = re.compile(r"BUILD FAILED")
+
+# A --tests filter that matched nothing: the target is not_found, not a failure.
+#   > No tests found for given includes: [com.example.FooTest.bar](--tests filter)
+_NO_TESTS_RE = re.compile(r"No tests found for given includes")
+
+# Kotlin compiler errors ("e: file:line:col: message") and javac errors.
+_KOTLIN_ERROR_RE = re.compile(r"^e: .*$", re.MULTILINE)
+
+# Kotlin/Java source patterns for the per-file grep fallback.
+_PACKAGE_RE = re.compile(r"^\s*package\s+([\w.]+)", re.MULTILINE)
+_CLASS_RE = re.compile(r"\bclass\s+(\w+)")
+# `@Test` (JUnit 4/5) followed by the annotated function/method name. Handles
+# Kotlin `fun name`, Kotlin backtick names (`fun \`does the thing\`()`), and
+# Java `void name()`.  Cross-class attribution within a file is not scope-aware
+# — the batch (a real run) is authoritative; this is the fallback.
+_METHOD_RE = re.compile(
+    r"@Test\b.*?\b(?:fun|void)\s+(?:`(?P<bt>[^`]+)`|(?P<id>\w+))",
+    re.DOTALL,
+)
+
+
+class GradleAdapter(Adapter):
+    name = "gradle"
+
+    def stub_hint(self) -> str:
+        return (
+            "a test method body that compiles but fails its assertion — a missing"
+            " symbol is a *compile* failure (not_collected), not RED; write a stub"
+            ' that compiles first (e.g. `fail("not implemented")`), then observe the'
+            " assertion failure"
+        )
+
+    # ------------------------------------------------------------------
+    # Core command
+    # ------------------------------------------------------------------
+
+    def _test_cmd(self) -> str:
+        return self.project.test_command or "./gradlew test"
+
+    def _gradle_filter(self, native_id: str) -> str:
+        """Translate an `FQCN/method` id into Gradle's `--tests FQCN.method` form.
+
+        A bare class id (no `/`) is passed through, targeting the whole class.
+        """
+        if "/" in native_id:
+            cls, method = native_id.rsplit("/", 1)
+            return f"{cls}.{method}"
+        return native_id
+
+    # ------------------------------------------------------------------
+    # Discovery — Kotlin / Java source files
+    # ------------------------------------------------------------------
+
+    def _test_files(self) -> list[Path]:
+        found: set[Path] = set()
+        for pattern in self.project.test_patterns or []:
+            if pattern.endswith("/"):
+                base = self.root / pattern
+                if base.is_dir():
+                    for suffix in ("*.kt", "*.java"):
+                        found.update(p for p in base.rglob(suffix) if p.is_file())
+            else:
+                found.update(p for p in self.root.glob(pattern) if p.is_file())
+        return sorted(found)
+
+    # ------------------------------------------------------------------
+    # Collection — per-file grep (no cheap whole-suite enumerator exists)
+    # ------------------------------------------------------------------
+
+    def collect(self) -> Collection:
+        result = Collection()
+        for path in self._test_files():
+            rel = str(path.relative_to(self.root))
+            try:
+                result.tests |= self._grep_tests(path)
+            except OSError as exc:
+                result.failed_files[rel] = str(exc)
+        return result
+
+    def _grep_tests(self, path: Path) -> set[str]:
+        """Extract `pkg.Class/method` ids from one Kotlin/Java source file.
+
+        Finds every `@Test`-annotated method and every declared class, forming
+        `pkg.Class/method` ids qualified by the package declaration.  Matches
+        are file-order, not scope-aware — a file with two classes attributes
+        each test method to both.  The batch path is authoritative; this is the
+        fallback that keeps one unreadable file from destroying the whole set.
+        """
+        text = path.read_text(encoding="utf-8", errors="replace")
+        pkg_match = _PACKAGE_RE.search(text)
+        pkg = f"{pkg_match.group(1)}." if pkg_match else ""
+        classes = _CLASS_RE.findall(text)
+        methods = [m.group("bt") or m.group("id") for m in _METHOD_RE.finditer(text)]
+        ids: set[str] = set()
+        for class_ in classes:
+            for method in methods:
+                ids.add(self.qualify(f"{pkg}{class_}/{method}"))
+        return ids
+
+    # The base collect() calls these three; gradle overrides collect() entirely
+    # so they are never reached.  Trivial bodies avoid surprising a direct caller.
+    def _collect_invocations(self):
+        return []
+
+    def _collect_batch(self, command, env):
+        return None
+
+    def _collect_per_file(self, rels, result):
+        return result
+
+    # ------------------------------------------------------------------
+    # Doctor gate
+    # ------------------------------------------------------------------
+
+    def collectable(self) -> GateResult:
+        """Collection is a source grep — it needs no toolchain, so enumeration is
+        always possible.  Whether Gradle itself can run is checked by the
+        `gradle wrapper present` branch in `tdd doctor` (§8.1)."""
+        return GateResult(ok=True)
+
+    # ------------------------------------------------------------------
+    # JUnit XML results
+    # ------------------------------------------------------------------
+
+    def _result_files(self) -> list[Path]:
+        """Every JUnit XML file Gradle writes for this project's tests.
+
+        Covers both JVM unit tasks (`build/test-results/<task>/TEST-*.xml`) and
+        Android instrumented tasks (`build/outputs/.../androidTest-results/`),
+        across every module under the project root.
+        """
+        found: set[Path] = set()
+        found.update(self.root.glob("**/build/test-results/**/*.xml"))
+        found.update(self.root.glob("**/build/outputs/**/androidTest-results/**/*.xml"))
+        return sorted(found)
+
+    def _clear_results(self) -> None:
+        """Delete stale JUnit XML before a run.
+
+        Two problems in one: Gradle leaves the previous run's XML on disk, and
+        it skips up-to-date tasks (so no fresh XML is written).  Removing the
+        result files fixes both — a targeted run is scored only against the XML
+        it produced, and deleting a task's output invalidates its up-to-date
+        check so the task actually re-runs.
+        """
+        for path in self._result_files():
+            try:
+                path.unlink()
+            except OSError:
+                pass
+
+    def _parse_results(self) -> tuple[set[str], set[str], dict[str, str]]:
+        """Parse every JUnit XML file into `(passed, failed, failures)`.
+
+        A `<testcase>` with a `<failure>`/`<error>` child failed; with a
+        `<skipped>` child it is neither (excluded); otherwise it passed. Ids are
+        qualified. `failures` maps a failed id to its message + stack trace.
+        """
+        passed: set[str] = set()
+        failed: set[str] = set()
+        failures: dict[str, str] = {}
+        for path in self._result_files():
+            try:
+                tree = ElementTree.parse(path)
+            except ElementTree.ParseError:
+                continue
+            for case in tree.iter("testcase"):
+                classname = case.get("classname") or ""
+                method = case.get("name") or ""
+                raw = f"{classname}/{method}" if classname else method
+                qualified = self.qualify(raw)
+                failure = case.find("failure")
+                if failure is None:
+                    failure = case.find("error")
+                if failure is not None:
+                    failed.add(qualified)
+                    failures[qualified] = self._failure_text(failure)
+                elif case.find("skipped") is None:
+                    passed.add(qualified)
+        return passed, failed, failures
+
+    @staticmethod
+    def _failure_text(failure: ElementTree.Element) -> str:
+        message = failure.get("message") or ""
+        body = (failure.text or "").strip()
+        combined = "\n".join(part for part in (message, body) if part)
+        return clip_failure(combined) if combined else "test failed"
+
+    def _build_errors(self, combined: str) -> str:
+        """Lines that explain why a run produced no tests: compiler errors and
+        Gradle's own failure report."""
+        wanted = ("e: ", ": error:", "FAILED", "FAILURE:", "What went wrong", "Execution failed")
+        lines = [line for line in combined.splitlines() if any(w in line for w in wanted)]
+        return clip_failure("\n".join(lines)) if lines else clip_failure(combined)
+
+    # ------------------------------------------------------------------
+    # Suite run
+    # ------------------------------------------------------------------
+
+    def run(self, target: str | None = None) -> Verdict:
+        verdict = Verdict(project=self.project.name, adapter=self.name, target=target)
+        env = self._suite_env(None)
+
+        cmd = self._test_cmd()
+        if target is not None:
+            native = self.strip(target)
+            cmd = f"{cmd} --tests {shlex.quote(self._gradle_filter(native))}"
+
+        started = time.monotonic()
+        self._clear_results()
+        code, out, err = self._run_suite(cmd, env)
+        verdict.duration_ms = int((time.monotonic() - started) * 1000)
+        combined = out + "\n" + err
+
+        passed, failed, failures = self._parse_results()
+        verdict.passed = sorted(passed)
+        verdict.failed = sorted(failed)
+
+        # No test ran. Distinguish "filter matched nothing" (not_found) from a
+        # compile/config failure (not_collected) from a genuinely empty suite.
+        if not passed and not failed:
+            if _NO_TESTS_RE.search(combined):
+                return verdict  # target stays NOT_FOUND; empty full run is clean
+            if code != 0 or _BUILD_FAILED_RE.search(combined):
+                errors = self._build_errors(combined)
+                if target is not None:
+                    verdict.target_outcome = NOT_COLLECTED
+                    verdict.target_failure = errors
+                else:
+                    verdict.error = errors
+            return verdict
+
+        if target is None:
+            return verdict
+
+        if target in passed:
+            verdict.target_outcome = PASSED
+        elif target in failed:
+            verdict.target_outcome = FAILED
+            verdict.target_failure = failures.get(target, "test failed")
+        # else NOT_FOUND (default): the suite ran but never produced this id
+
+        return verdict