automaton/tasks/complete/add-blast-radius-scheduler/SPEC.md

SPEC: add-blast-radius-scheduler

Context

Task 2 (add-status-brakes) shipped --can-edit --loop [--loop-worktree], the _gate_worktree_drift brake gate, and platform.system() dispatch for scheduler generation. Task 3 (add-loop-runner) shipped the runner with a stub at step 4: # worktree plumbing lands in task add-blast-radius-scheduler. The runner currently uses state["worktree_path"] if set, else falls back to project_root -- but never creates the worktree. This task closes that gap: the runner ensures a per-loop git worktree exists before spawning the Implement role, per technical.md section 7 step 4 and D2.

Non-Goals (deferred)

• --no-worktree CLI flag for --create-loop -> v1.1 (the blast_radius.use_worktree: false field in loop.json is the v1 opt-out mechanism; a CLI flag is convenience sugar).
• Worktree garbage collection / pruning -> v1.1 (BACKLOG worktree-gc).
• blast_radius.base_branch parameterization -> v1.1 (hardening item; v1 hardcodes main as the base).
• --claim-loop-task atomic ownership -> v1.1.
• Fcntl lock on worktree creation -> v1.1 (same TOCTOU item as add-status-brakes A6).

Requirements

R1 -- _ensure_worktree helper in loop-runner.py

• New function _ensure_worktree(state, cfg, loop_path, project_dir) -> str that returns the cwd to use for harness invocations.
• Reads blast_radius.use_worktree from loop.json (default: True when the field is missing, matching D2 "default is worktree-on").
• When use_worktree is False: return str(project_dir) immediately. No git calls. No state mutation.
• When use_worktree is True and state["worktree_path"] is already set and the path exists: return the existing worktree path. No state mutation.
• When use_worktree is True and state["worktree_path"] is null or the path no longer exists:
  1. Determine the worktree path: <loop_path>/worktree (using LOOP_WORKTREE_DIR = "worktree").
  2. Determine the branch name: loop/<name> where <name> is state["name"] or the loop dir name.
  3. Run git rev-parse --is-inside-work-tree from project_dir to verify it is a git repo. If not, fall back to R2.
  4. Run git worktree add <worktree_path> -b loop/<name> from project_dir. If the branch already exists, use git worktree add <worktree_path> loop/<name> (checkout existing branch, no -b).
  5. On success: update state["worktree_path"] and state["worktree_branch"], write state atomically, return the worktree path.
  6. On failure: fall back to R2.
• Tests: test_ensure_worktree_creates_worktree, test_ensure_worktree_reuses_existing, test_ensure_worktree_use_worktree_false_returns_project_root, test_ensure_worktree_missing_field_defaults_true.

R2 -- Graceful degradation (no git / not a repo / worktree creation fails)

• If git is not found (FileNotFoundError), or git rev-parse --is-inside-work-tree fails (non-zero exit), or git worktree add fails (non-zero exit): log a WARNING to .state.log and return str(project_dir) as cwd.
• The loop does NOT halt. The tick proceeds with cwd = project_dir. The drift gate (_gate_worktree_drift) will skip itself because worktree_path remains null.
• This makes worktree creation best-effort: a loop configured with use_worktree: true on a non-git project simply edits the primary checkout. The operator is responsible for understanding this trade-off (documented in functional.md).
• Tests: test_ensure_worktree_falls_back_when_not_git_repo, test_ensure_worktree_falls_back_when_git_missing, test_ensure_worktree_falls_back_when_worktree_add_fails, test_ensure_worktree_logs_warning_on_fallback.

R3 -- Integration into cmd_tick

• Replace the current step 4 block in cmd_tick (lines ~493-498 of loop-runner.py) with a call to _ensure_worktree(state, cfg, loop_path, project_dir).
• The returned cwd is used for all three role invocations (Implement, Verify, Orchestrate).
• The state mutation (setting worktree_path/worktree_branch) happens inside _ensure_worktree via _write_state_loop. This is safe because it occurs before any harness subprocess; a crash after this point but before step 10 leaves the worktree path recorded (which is correct -- the worktree exists on disk).
• Tests: test_tick_creates_worktree_on_first_tick, test_tick_reuses_worktree_on_second_tick, test_tick_falls_back_to_project_root_when_no_git.

R4 -- Worktree branch already exists

• When git worktree add <path> -b loop/<name> fails because the branch already exists (exit code 128, stderr contains already exists), retry with git worktree add <path> loop/<name> (checkout existing branch without -b).
• If the retry also fails, fall back to R2.
• This handles the case where a loop was previously created, the worktree was deleted, but the branch remains in the repo.
• Tests: test_ensure_worktree_reuses_existing_branch, test_ensure_worktree_falls_back_when_branch_checkout_fails.

R5 -- State consistency

• _ensure_worktree writes worktree_path and worktree_branch to .state.loop atomically via _write_state_loop (same tmp+rename pattern).
• If the worktree path was previously set but the directory no longer exists (e.g. manually deleted), clear worktree_path and worktree_branch in state before attempting recreation. If recreation fails, leave them cleared (R2 fallback).
• Tests: test_ensure_worktree_clears_stale_worktree_path, test_ensure_worktree_recreates_after_deletion.

R6 -- Platform path handling

• Use pathlib.Path for all path construction. On Windows, Path handles backslash separators automatically.
• The git worktree add command receives the worktree path as a string; git handles OS-specific path normalization on its own.
• No platform.system() calls needed in the runner for worktree creation (unlike --install-schedule which generates OS-native scheduler units). The runner's worktree creation is platform-agnostic via Path.
• Tests: test_worktree_path_uses_pathlib (verify the path is constructed via Path not string concatenation; checked by examining the argv passed to subprocess.run).

R7 -- Doc updates

• Update design/loops/technical.md section 7 step 4 to note the runner now creates the worktree (remove the "deferred" language if present).
• Update CHANGELOG.md under [unreleased].
• Tests: none (doc-only).

R8 -- New test file tests/test_blast_radius.py

• Mirrors test_loop_runner.py's stubbing pattern (monkeypatch.setattr(subprocess, "run", fake_run)).
• Covers R1-R6 as itemized above; target 12-16 tests.
• All subprocess calls stubbed; no live git operations in CI. For tests that need a real git repo, use tmp_path + subprocess.run(["git", "init"]) in a fixture (these are integration tests that hit the real git binary but are fast and deterministic).
• Add one regression test: test_existing_loop_with_worktree_path_ticks_unchanged -- a loop with worktree_path set and the path existing still ticks without calling git worktree add.
• Tests: self-referential (the file IS the test).

Verification

• python3 -m py_compile scripts/loop-runner.py
• python3 -m pytest tests/test_blast_radius.py -v
• python3 -m pytest tests/ -q -- full suite must remain green; expected total approx 370 (354 + 12-16 new).
• bash -n scripts/*.sh (no shell changes; safety check).