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

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

@@ -6,6 +6,58 @@ and the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-28
+
+### Added
+
+- **`--reuse-baselines` caches baseline probes by content hash.** `run start`
+  can skip re-probing a project whose tree is unchanged: a probe result is
+  cached keyed by `(project, tree_hash, config_sha)` — where `tree_hash` folds in
+  every upstream producer root — and an identical rerun emits `baseline_reused`
+  instead of `baseline_captured`, reusing the cached failing set and collection
+  snapshot rather than re-running the suite. Provenance is recorded on the
+  baseline row (`source`), and `--reuse-max-age` re-probes any entry older than
+  the given age. Off by default; the cache stays empty unless the flag is passed
+  (#45, #59).
+
+- **`--baseline-jobs` parallelizes baseline probing.** `run start` probes each
+  project's baseline under a bounded `ThreadPoolExecutor` when `--baseline-jobs`
+  is greater than 1 (default 1, must be >= 1). The `baseline_captured` heartbeat
+  survives the pool, and a worker probe that raises becomes an attributed failure
+  that aborts cleanly and frees the worktree rather than wedging it (#46, #62).
+
+- **Plan-level `ancillary_files`.** A top-level front-matter key declaring
+  cross-project or companion paths a plan touches (README, generated fixtures,
+  sibling-project files). Declared ancillary paths are bucketed into their own
+  staging bucket, committed with the cycle, and fire no `undeclared_file_touched`
+  event. Validated as a list of strings at registration and persisted to the
+  ledger via a v5→v6 migration (#70, #80).
+
+- **Run-close gate on undeclared touched paths.** `run close` now blocks when a
+  path previously flagged as `undeclared_file_touched` is still dirty in the
+  worktree, so undeclared changes cannot slip through at the end of a run. A
+  flagged path that was since committed does not block; one that has vanished is
+  reported via a new `undeclared_file_dropped` event rather than blocking (#69,
+  #81).
+
+- **Reserved per-cycle `meta:` passthrough.** A cycle may carry an authored
+  `meta:` mapping in the plan front-matter; it round-trips through storage
+  unchanged and is available for plan-time metadata. A non-mapping `meta:`
+  hard-fails registration with a `ContractError` (#58, #65).
+
+### Fixed
+
+- `undeclared_file_touched` is deduplicated within a cycle, so a path touched
+  across multiple phases no longer floods the cycle with repeated events (#55,
+  #61).
+- vitest test ids are normalised on the describe/test separator before matching,
+  so a formatting-only difference between a declared target and the observed
+  verdict is no longer reported as a spurious `declared_test_mismatch` (#57,
+  #63).
+- The `stale_artifact` event is suppressed when the tool auto-regenerates the
+  artifact and commits it, so a successful regeneration no longer also emits a
+  staleness warning (#64).
+
 ## [0.7.0] - 2026-08-23
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tdd-cli
-Version: 0.7.0
+Version: 0.8.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
@@ -227,6 +227,8 @@ cycles:
     stub_expected: ["app/exception_map.py"]
     commit_red: "test: unmapped exception is not swallowed"
     commit_green: "feat: domain exception map skeleton"
+    meta:                           # optional authored-at-plan-time metadata; opaque to the tool
+      covers: ["B1", "B2"]         # any mapping is valid; contents are tool-opaque
   - n: 8
     project: backend
     pin_cycle: true                 # characterisation; passes on arrival by design
@@ -238,9 +240,51 @@ cycles:
       - "backend::tests/test_openapi.py::test_upload_body_schema"
       - "frontend::services/__tests__/upload.test.ts > matches contract"
 annotation_keys: ["literal_detail_handlers_kept"]
+ancillary_files:
+  - frontend/src/api/registerClient.ts   # type-break from regenerated client
+  - docs/INVARIANTS.md                   # companion doc read at runtime by cycle 7's test
 ---
 ```
 
+**Top-level keys:**
+
+`annotation_keys` — a list of judgement-annotation keys the plan requires; the run close
+gate checks that every key is present before the plan can be marked complete.
+
+`ancillary_files` — a plan-level list of repo-root-relative paths the plan is known to
+touch outside any registered project root (cross-project ripples, companion documents).
+Paths are hash-frozen with the plan blob like all other front-matter. A changed path that
+matches the list is classified as *declared* — no `undeclared_file_touched` event fires —
+and is staged into the GREEN/REFACTOR phase commit alongside the cycle's own files. A path
+not on the list still fires `undeclared_file_touched` exactly as today. This is a
+plan-level list only; per-cycle overrides are a planned follow-up.
+
+### Run-close gate for undeclared file touches
+
+When the last declared cycle closes, the tool gathers every path that appeared in any
+`undeclared_file_touched` event across the run and checks the worktree:
+
+- **Still dirty/untracked** → a typed blocker `undeclared_file_uncommitted` is inserted,
+  the run outcome is set to `blocked`, and `next_action.verb` is `"blocked"`. Resolution:
+  commit the files, then `tdd resume --unblock --note "committed notes.md"`, or discard
+  and record a justification with `tdd resume --unblock --note "discarding scratch file"`.
+- **Committed during the run** → clean; the run completes normally.
+- **Vanished without being committed** → an `undeclared_file_dropped` integrity event is
+  emitted (visible in `tdd metrics` and the friction log) and the run completes. The event
+  makes a silent drop visible without blocking, since the file is already gone.
+
+The gate composes with `ancillary_files`: declared paths never fire `undeclared_file_touched`,
+so they are never seen by the gate.
+
+**Per-cycle keys:** `n` (ordinal), `project`/`projects`, `test`/`tests`, `title`, `files`,
+`stub_expected`, `modifies_tests`, `commit_red`, `commit_green`, `commit_refactor`,
+`commit_pin`, `pin_cycle`, `contract_cycle`, `refactor_cycle`, and `meta`.
+`meta` is a reserved passthrough mapping: its *shape* is validated (must be a mapping),
+but its *contents* are opaque to the tool — any key/value pairs are accepted and
+round-tripped intact through `cycles_to_json`/`cycles_from_json`. Use it for
+authored-at-plan-time metadata that external tooling (e.g. a behaviour-coverage checker)
+needs to read back. Other unknown per-cycle keys are silently ignored.
+
 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
@@ -418,6 +462,50 @@ Pass `--baseline-all` to probe every project in `tdd.toml` regardless:
 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.
 
+### Reusing baselines across runs (R9.5e)
+
+On repos where runs are frequent and most projects change rarely, re-probing unchanged suites
+wastes time. Pass `--reuse-baselines` to cache probe results and skip re-probing on the next run
+when nothing in the project changed:
+
+    tdd run start --plan tasks/plan.md --reuse-baselines
+
+The cache key is `(project, tree_hash(project root ∪ upstream producer roots), config_sha)`.
+If the key matches a previous entry, the cached failing set and collection snapshot are used —
+no suite is run — and a `baseline_reused` heartbeat appears on stderr. The baseline row carries
+`source = "reused"` for auditability, and a `baseline_reused` integrity event lists which
+projects were skipped. Without the flag, the cache is neither read nor written.
+
+A stale or wrong reused baseline is always recoverable via `resume --unblock --accept-failures`
+(see below) — reuse is loud by design, never silent.
+
+To limit how old a cached entry may be, pass `--reuse-max-age <seconds>`:
+
+    tdd run start --plan tasks/plan.md --reuse-baselines --reuse-max-age 3600
+
+Entries older than the given threshold are ignored and re-probed fresh.
+
+### Parallel baseline probing (R9.5f)
+
+By default `run start` probes one project at a time. On a repo with many independent projects the
+wall-clock cost is the *sum* of all suite runtimes. Pass `--baseline-jobs N` to probe up to N
+projects concurrently:
+
+    tdd run start --plan tasks/plan.md --baseline-jobs 4
+
+Each probe is independent — one adapter instance per project — so concurrency does not affect
+which projects are probed, the refusal checks, or the baseline rows written. A `baseline_captured`
+heartbeat is still emitted per project as each probe completes.
+
+The default is `--baseline-jobs 1` (serial). Raise it deliberately:
+
+- **I/O-bound suites** (network, DB, file-heavy) benefit most; CPU-bound suites less so.
+- **Suites contending for global resources** (xctest simulators, fixed ports) should stay at 1,
+  or declare a `lease` name — leased suites serialize automatically even inside the pool.
+
+If any probe fails, `run start` returns a failure attributed to that project and no run row is
+created, so the worktree is immediately retryable.
+
 ### 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
@@ -472,10 +560,11 @@ The CLI cannot compel an agent — only the harness can.
 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.
+**Recorded, never blocked mid-run:** 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. Undeclared file touches are an exception at run close:
+see the run-close gate above.
 
 **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`.

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

@@ -199,6 +199,8 @@ cycles:
     stub_expected: ["app/exception_map.py"]
     commit_red: "test: unmapped exception is not swallowed"
     commit_green: "feat: domain exception map skeleton"
+    meta:                           # optional authored-at-plan-time metadata; opaque to the tool
+      covers: ["B1", "B2"]         # any mapping is valid; contents are tool-opaque
   - n: 8
     project: backend
     pin_cycle: true                 # characterisation; passes on arrival by design
@@ -210,9 +212,51 @@ cycles:
       - "backend::tests/test_openapi.py::test_upload_body_schema"
       - "frontend::services/__tests__/upload.test.ts > matches contract"
 annotation_keys: ["literal_detail_handlers_kept"]
+ancillary_files:
+  - frontend/src/api/registerClient.ts   # type-break from regenerated client
+  - docs/INVARIANTS.md                   # companion doc read at runtime by cycle 7's test
 ---
 ```
 
+**Top-level keys:**
+
+`annotation_keys` — a list of judgement-annotation keys the plan requires; the run close
+gate checks that every key is present before the plan can be marked complete.
+
+`ancillary_files` — a plan-level list of repo-root-relative paths the plan is known to
+touch outside any registered project root (cross-project ripples, companion documents).
+Paths are hash-frozen with the plan blob like all other front-matter. A changed path that
+matches the list is classified as *declared* — no `undeclared_file_touched` event fires —
+and is staged into the GREEN/REFACTOR phase commit alongside the cycle's own files. A path
+not on the list still fires `undeclared_file_touched` exactly as today. This is a
+plan-level list only; per-cycle overrides are a planned follow-up.
+
+### Run-close gate for undeclared file touches
+
+When the last declared cycle closes, the tool gathers every path that appeared in any
+`undeclared_file_touched` event across the run and checks the worktree:
+
+- **Still dirty/untracked** → a typed blocker `undeclared_file_uncommitted` is inserted,
+  the run outcome is set to `blocked`, and `next_action.verb` is `"blocked"`. Resolution:
+  commit the files, then `tdd resume --unblock --note "committed notes.md"`, or discard
+  and record a justification with `tdd resume --unblock --note "discarding scratch file"`.
+- **Committed during the run** → clean; the run completes normally.
+- **Vanished without being committed** → an `undeclared_file_dropped` integrity event is
+  emitted (visible in `tdd metrics` and the friction log) and the run completes. The event
+  makes a silent drop visible without blocking, since the file is already gone.
+
+The gate composes with `ancillary_files`: declared paths never fire `undeclared_file_touched`,
+so they are never seen by the gate.
+
+**Per-cycle keys:** `n` (ordinal), `project`/`projects`, `test`/`tests`, `title`, `files`,
+`stub_expected`, `modifies_tests`, `commit_red`, `commit_green`, `commit_refactor`,
+`commit_pin`, `pin_cycle`, `contract_cycle`, `refactor_cycle`, and `meta`.
+`meta` is a reserved passthrough mapping: its *shape* is validated (must be a mapping),
+but its *contents* are opaque to the tool — any key/value pairs are accepted and
+round-tripped intact through `cycles_to_json`/`cycles_from_json`. Use it for
+authored-at-plan-time metadata that external tooling (e.g. a behaviour-coverage checker)
+needs to read back. Other unknown per-cycle keys are silently ignored.
+
 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
@@ -390,6 +434,50 @@ Pass `--baseline-all` to probe every project in `tdd.toml` regardless:
 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.
 
+### Reusing baselines across runs (R9.5e)
+
+On repos where runs are frequent and most projects change rarely, re-probing unchanged suites
+wastes time. Pass `--reuse-baselines` to cache probe results and skip re-probing on the next run
+when nothing in the project changed:
+
+    tdd run start --plan tasks/plan.md --reuse-baselines
+
+The cache key is `(project, tree_hash(project root ∪ upstream producer roots), config_sha)`.
+If the key matches a previous entry, the cached failing set and collection snapshot are used —
+no suite is run — and a `baseline_reused` heartbeat appears on stderr. The baseline row carries
+`source = "reused"` for auditability, and a `baseline_reused` integrity event lists which
+projects were skipped. Without the flag, the cache is neither read nor written.
+
+A stale or wrong reused baseline is always recoverable via `resume --unblock --accept-failures`
+(see below) — reuse is loud by design, never silent.
+
+To limit how old a cached entry may be, pass `--reuse-max-age <seconds>`:
+
+    tdd run start --plan tasks/plan.md --reuse-baselines --reuse-max-age 3600
+
+Entries older than the given threshold are ignored and re-probed fresh.
+
+### Parallel baseline probing (R9.5f)
+
+By default `run start` probes one project at a time. On a repo with many independent projects the
+wall-clock cost is the *sum* of all suite runtimes. Pass `--baseline-jobs N` to probe up to N
+projects concurrently:
+
+    tdd run start --plan tasks/plan.md --baseline-jobs 4
+
+Each probe is independent — one adapter instance per project — so concurrency does not affect
+which projects are probed, the refusal checks, or the baseline rows written. A `baseline_captured`
+heartbeat is still emitted per project as each probe completes.
+
+The default is `--baseline-jobs 1` (serial). Raise it deliberately:
+
+- **I/O-bound suites** (network, DB, file-heavy) benefit most; CPU-bound suites less so.
+- **Suites contending for global resources** (xctest simulators, fixed ports) should stay at 1,
+  or declare a `lease` name — leased suites serialize automatically even inside the pool.
+
+If any probe fails, `run start` returns a failure attributed to that project and no run row is
+created, so the worktree is immediately retryable.
+
 ### 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
@@ -444,10 +532,11 @@ The CLI cannot compel an agent — only the harness can.
 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.
+**Recorded, never blocked mid-run:** 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. Undeclared file touches are an exception at run close:
+see the run-close gate above.
 
 **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`.

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

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

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

@@ -139,6 +139,14 @@ class Adapter:
         prefix = f"{self.project.name}::"
         return qualified[len(prefix) :] if qualified.startswith(prefix) else qualified
 
+    def normalise_id(self, test_id: str) -> str:
+        """Return the canonical form of a declared target id for matching against collected ids.
+
+        The default is an identity — subclasses override when the runner's collected
+        ids differ from a natural human spelling (e.g. vitest's describe/test separator).
+        """
+        return test_id
+
     def run(self, target: str | None = None) -> Verdict:
         raise NotImplementedError
 

{tdd_cli-0.7.0 → tdd_cli-0.8.0}/src/tddcli/adapters/vitest_adapter.py

@@ -45,7 +45,25 @@ class VitestAdapter(Adapter):
     name = "vitest"
 
     def stub_hint(self) -> str:
-        return "`throw new Error(\"not implemented\")` in every body"
+        return '`throw new Error("not implemented")` in every body'
+
+    def normalise_id(self, test_id: str) -> str:
+        """Canonicalise the describe/test separator for target matching.
+
+        vitest's `fullName` joins ancestor titles and the test title with a space,
+        so collected ids look like `frontend::a.test.ts > someHelper formats a value`.
+        A planner naturally writes ` > ` at each nesting level. Treating both as
+        equivalent prevents a formatting-only difference from producing NOT_FOUND.
+
+        The structural ` > ` between the file and the name is preserved; only the
+        ` > ` separators inside the name part are collapsed to a space.
+        """
+        raw = self.strip(test_id)
+        file_part, sep, remainder = raw.partition(" > ")
+        if not sep:
+            return test_id
+        name = " ".join(part.strip() for part in remainder.split(" > "))
+        return self.qualify(f"{file_part} > {name}")
 
     def _id_for(self, suite_path: str, full_name: str) -> str:
         abs_path = Path(suite_path)
@@ -72,18 +90,18 @@ class VitestAdapter(Adapter):
             code, out, err = self._run_suite(f"{base} --reporter=json", extra_env)
             report = _extract_json(out)
             if report is None:
-                verdict.error = (
-                    f"`{base}` produced no JSON output: {(err or out)[:500]}"
-                )
+                verdict.error = f"`{base}` produced no JSON output: {(err or out)[:500]}"
                 return verdict
             verdict.duration_ms += int(report.get("duration") or 0)
             results = report.get("testResults", [])
             suites.extend(results)
-            suite_ids.append({
-                self._id_for(s.get("name", ""), t["fullName"])
-                for s in results
-                for t in s.get("assertionResults", [])
-            })
+            suite_ids.append(
+                {
+                    self._id_for(s.get("name", ""), t["fullName"])
+                    for s in results
+                    for t in s.get("assertionResults", [])
+                }
+            )
 
         overlap = _suite_overlap(suite_ids)
         if overlap:
@@ -108,17 +126,23 @@ class VitestAdapter(Adapter):
             verdict.target_outcome = NOT_FOUND
             return verdict
 
-        if target in verdict.passed:
+        ntarget = self.normalise_id(target)
+        passed_norm = {self.normalise_id(t): t for t in verdict.passed}
+        failed_norm = {self.normalise_id(t): t for t in verdict.failed}
+
+        if ntarget in passed_norm:
             verdict.target_outcome = PASSED
             return verdict
-        if target in verdict.failed:
+        if ntarget in failed_norm:
             verdict.target_outcome = FAILED
             for suite in suites:
                 for t in suite.get("assertionResults", []):
-                    if self._id_for(suite.get("name", ""), t["fullName"]) == target:
+                    if (
+                        self.normalise_id(self._id_for(suite.get("name", ""), t["fullName"]))
+                        == ntarget
+                    ):
                         verdict.target_failure = "\n".join(
-                            clip_failure(m, 600)
-                            for m in t.get("failureMessages", [])[:3]
+                            clip_failure(m, 600) for m in t.get("failureMessages", [])[:3]
                         )
             return verdict
 
@@ -206,22 +230,26 @@ class VitestAdapter(Adapter):
         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]
-                for line in out.splitlines()
-                if " > " in line
-            )
-            if self.project.override_for(f)
-        })
+        reached = sorted(
+            {
+                f
+                for f in (
+                    line.strip().partition(" > ")[0] for line in out.splitlines() if " > " in line
+                )
+                if self.project.override_for(f)
+            }
+        )
         if not reached:
             return GateResult(ok=True)
-        return GateResult(ok=False, output=(
-            "the default config's discovery reaches files an override owns, so"
-            " suite runs would observe them without the override's command/env:"
-            f" {', '.join(reached[:5])}. Exclude them from the default vitest"
-            " config (test.exclude) or scope its include globs."
-        ))
+        return GateResult(
+            ok=False,
+            output=(
+                "the default config's discovery reaches files an override owns, so"
+                " suite runs would observe them without the override's command/env:"
+                f" {', '.join(reached[:5])}. Exclude them from the default vitest"
+                " config (test.exclude) or scope its include globs."
+            ),
+        )
 
     def _collect_invocations(self) -> list[tuple[str, dict[str, str] | None]]:
         """An override with no `collect_command` gets no batch — `vitest list` knows
@@ -229,7 +257,8 @@ class VitestAdapter(Adapter):
         missing `collect_command` against each of them as before."""
         return [(self._collect_cmd(), self._suite_env(None))] + [
             (ov.collect_command, self._suite_env(ov))
-            for ov in self.project.overrides if ov.collect_command
+            for ov in self.project.overrides
+            if ov.collect_command
         ]
 
     def _collect_batch(
@@ -270,7 +299,9 @@ class VitestAdapter(Adapter):
             base = ov.collect_command if ov else self._collect_cmd()
             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",
             )
 
@@ -290,7 +321,6 @@ class VitestAdapter(Adapter):
                 # Zero tests from a file that exists is a tooling failure, not an
                 # empty file — record it rather than silently collecting nothing.
                 result.failed_files[str(rel)] = (
-                    f"no tests parsed from `{base}` (exit {code}): "
-                    + (err or out).strip()[:600]
+                    f"no tests parsed from `{base}` (exit {code}): " + (err or out).strip()[:600]
                 )
         return result

{tdd_cli-0.7.0 → tdd_cli-0.8.0}/src/tddcli/advance.py

@@ -12,6 +12,7 @@ from . import adapters, gitutil, staging
 from . import config as config_mod
 from .adapters.base import FAILED, NOT_COLLECTED, NOT_FOUND, PASSED
 from .envelope import Envelope, NextAction, Verb
+from .ledger import now
 from .machine import (
     AWAITING_IMPL,
     AWAITING_PIN,
@@ -58,6 +59,16 @@ def _stub_directive_issued(engine: Engine, cycle) -> bool:
     ) is not None
 
 
+def _last_outside_emitted(engine: Engine, cycle) -> str | None:
+    row = engine.ledger.one(
+        "SELECT detail FROM integrity_event"
+        " WHERE cycle_id = ? AND kind = 'undeclared_file_touched'"
+        " ORDER BY id DESC LIMIT 1",
+        (cycle["id"],),
+    )
+    return row["detail"] if row else None
+
+
 def _sanctioned_stubs(engine: Engine, cycle, implementation: list[str]) -> list[str]:
     """The files that answer a `create_stub` directive the tool itself issued.
 
@@ -74,7 +85,8 @@ def _sanctioned_stubs(engine: Engine, cycle, implementation: list[str]) -> list[
 def _stage_and_commit(engine: Engine, cycle, phase: str, declared) -> tuple[str | None, list[str], object]:
     changed = engine.authored_changes(cycle)
     classification = staging.classify(
-        engine.config, changed, json.loads(cycle["projects"]), declared, engine.excluded
+        engine.config, changed, json.loads(cycle["projects"]), declared, engine.excluded,
+        ancillary=set(engine.ancillary_files),
     )
     if phase == staging.RED:
         adopted = _sanctioned_stubs(engine, cycle, classification.implementation)
@@ -89,10 +101,12 @@ def _stage_and_commit(engine: Engine, cycle, phase: str, declared) -> tuple[str
                 json.dumps(classification.implementation),
             )
     if classification.outside:
-        engine.ledger.event(
-            engine.run["id"], cycle["id"], "undeclared_file_touched",
-            json.dumps(classification.outside),
-        )
+        _detail = json.dumps(classification.outside)
+        if _last_outside_emitted(engine, cycle) != _detail:
+            engine.ledger.event(
+                engine.run["id"], cycle["id"], "undeclared_file_touched",
+                _detail,
+            )
     paths = staging.paths_for_phase(phase, classification)
     message = staging.default_message(phase, declared, cycle["ordinal"])
     sha, staged = staging.commit(
@@ -335,6 +349,38 @@ def _handle_refactor(engine: Engine, cycle, retried: bool) -> Envelope:
 
     nxt = engine.close_cycle(cycle)
     if nxt is None:
+        blocking = engine.close_undeclared_gate(cycle)
+        if blocking:
+            engine.ledger.insert(
+                "blocker",
+                run_id=engine.run["id"],
+                cycle_id=cycle["id"],
+                kind="undeclared_file_uncommitted",
+                detail=json.dumps(blocking),
+                at=now(),
+            )
+            engine.ledger.update("run", engine.run["id"], outcome="blocked")
+            return Envelope(
+                run={
+                    "id": engine.run["id"],
+                    "plan": engine.contract_row["plan_path"],
+                    "cycle": cycle["ordinal"],
+                    "of": len(engine.declared),
+                    "phase": "BLOCKED",
+                    "executor": engine.run["executor_model"],
+                },
+                result={
+                    "kind": "undeclared_file_uncommitted",
+                    "paths": blocking,
+                    "commit": sha,
+                },
+                next_action=NextAction(
+                    Verb.BLOCKED,
+                    f"Run reached its last cycle but {len(blocking)} flagged file(s) are"
+                    f" uncommitted: {blocking}. Commit them, or"
+                    " `tdd resume --unblock --note ...` to discard.",
+                ),
+            )
         return Envelope(
             run={
                 "id": engine.run["id"],