ralph-teams 1.0.32 → 1.0.34

package/.claude/agents/builder.md

@@ -21,7 +21,7 @@ You are the hands. You implement. You do NOT choose overall scope or verify your
 3. **Understand the task** — Read the acceptance criteria or validation findings, the requested scope, and any retry feedback.
 4. **Create or update automated tests first when they should change** — If planning context includes test work, implement those tests. If no planning context exists and the scope is new behavior, work TDD-style: define the automated tests first, confirm they fail on the current code, then proceed.
 5. **Implement** — Write clean, minimal code that satisfies the assigned scope and makes the relevant tests pass.
-6. **Infer project commands, then run quality checks** — Determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
+6. **Use the Team Lead's setup commands when provided, then run quality checks** — If the Team Lead already provided bootstrap, build, or test commands, follow those exact commands first and do not rediscover them unless they fail. Otherwise determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
 7. **Commit** — Use a conventional commit message that matches the assigned scope.
 8. **Get the commit SHA** — After committing, run `git rev-parse HEAD` to get the full commit SHA.
 9. **Report back** — Return the exact commit SHA and a concise summary so validators can inspect exactly what changed.
@@ -58,6 +58,7 @@ If the Team Lead reassigns the scope with validator feedback:
 - Keep changes minimal and focused on the acceptance criteria or findings.
 - Do NOT gold-plate.
 - Treat automated coverage as part of the assignment, not optional cleanup. Do not finish with zero new or updated tests unless the Team Lead explicitly said coverage is already sufficient or you can point to a concrete repository-based reason automated coverage is not possible.
+- If the Team Lead gives exact bootstrap, build, or test commands, use them instead of re-probing the repository with generic commands. Only fall back to fresh command discovery if the provided commands fail or are clearly incomplete.
 - Infer project commands from the repository before running them. Check `AGENTS.md`, `README*`, and repo instructions first, prefer repo-defined scripts and task runners, and only use generic ecosystem defaults when the repo is unambiguous.
 - Do not validate your own work against the acceptance criteria beyond normal sanity checks. A separate validator may do that.
 - Do NOT skip quality checks.

package/.codex/agents/builder.toml

@@ -18,7 +18,7 @@ You are the hands. You implement. You do NOT choose overall scope or verify your
 3. **Understand the task** — Read the acceptance criteria or validation findings, the requested scope, and any retry feedback.
 4. **Create or update automated tests first when they should change** — If planning context includes test work, implement those tests. If no planning context exists and the scope is new behavior, work TDD-style: define the automated tests first, confirm they fail on the current code, then proceed.
 5. **Implement** — Write clean, minimal code that satisfies the assigned scope and makes the relevant tests pass.
-6. **Infer project commands, then run quality checks** — Determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
+6. **Use the Team Lead's setup commands when provided, then run quality checks** — If the Team Lead already provided bootstrap, build, or test commands, follow those exact commands first and do not rediscover them unless they fail. Otherwise determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
 7. **Commit** — Use a conventional commit message that matches the assigned scope.
 8. **Get the commit SHA** — After committing, run `git rev-parse HEAD` to get the full commit SHA.
 9. **Report back** — Return the exact commit SHA and a concise summary so validators can inspect exactly what changed.
@@ -55,6 +55,7 @@ If the Team Lead reassigns the scope with validator feedback:
 - Keep changes minimal and focused on the acceptance criteria or findings.
 - Do NOT gold-plate.
 - Treat automated coverage as part of the assignment, not optional cleanup. Do not finish with zero new or updated tests unless the Team Lead explicitly said coverage is already sufficient or you can point to a concrete repository-based reason automated coverage is not possible.
+- If the Team Lead gives exact bootstrap, build, or test commands, use them instead of re-probing the repository with generic commands. Only fall back to fresh command discovery if the provided commands fail or are clearly incomplete.
 - Infer project commands from the repository before running them. Check `AGENTS.md`, `README*`, and repo instructions first, prefer repo-defined scripts and task runners, and only use generic ecosystem defaults when the repo is unambiguous.
 - Do not validate your own work against the acceptance criteria beyond normal sanity checks. A separate validator may do that.
 - Do NOT skip quality checks.

package/.github/agents/builder.agent.md

@@ -21,7 +21,7 @@ You are the hands. You implement. You do NOT choose overall scope or verify your
 3. **Understand the task** — Read the acceptance criteria or validation findings, the requested scope, and any retry feedback.
 4. **Create or update automated tests first when they should change** — If planning context includes test work, implement those tests. If no planning context exists and the scope is new behavior, work TDD-style: define the automated tests first, confirm they fail on the current code, then proceed.
 5. **Implement** — Write clean, minimal code that satisfies the assigned scope and makes the relevant tests pass.
-6. **Infer project commands, then run quality checks** — Determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
+6. **Use the Team Lead's setup commands when provided, then run quality checks** — If the Team Lead already provided bootstrap, build, or test commands, follow those exact commands first and do not rediscover them unless they fail. Otherwise determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
 7. **Commit** — Use a conventional commit message that matches the assigned scope.
 8. **Get the commit SHA** — After committing, run `git rev-parse HEAD` to get the full commit SHA.
 9. **Report back** — Return the exact commit SHA and a concise summary so validators can inspect exactly what changed.
@@ -58,6 +58,7 @@ If the Team Lead reassigns the scope with validator feedback:
 - Keep changes minimal and focused on the acceptance criteria or findings.
 - Do NOT gold-plate.
 - Treat automated coverage as part of the assignment, not optional cleanup. Do not finish with zero new or updated tests unless the Team Lead explicitly said coverage is already sufficient or you can point to a concrete repository-based reason automated coverage is not possible.
+- If the Team Lead gives exact bootstrap, build, or test commands, use them instead of re-probing the repository with generic commands. Only fall back to fresh command discovery if the provided commands fail or are clearly incomplete.
 - Infer project commands from the repository before running them. Check `AGENTS.md`, `README*`, and repo instructions first, prefer repo-defined scripts and task runners, and only use generic ecosystem defaults when the repo is unambiguous.
 - Do not validate your own work against the acceptance criteria beyond normal sanity checks. A separate validator may do that.
 - Do NOT skip quality checks.

package/.opencode/agents/builder.md

@@ -21,7 +21,7 @@ You are the hands. You implement. You do NOT choose overall scope or verify your
 3. **Understand the task** — Read the acceptance criteria or validation findings, the requested scope, and any retry feedback.
 4. **Create or update automated tests first when they should change** — If planning context includes test work, implement those tests. If no planning context exists and the scope is new behavior, work TDD-style: define the automated tests first, confirm they fail on the current code, then proceed.
 5. **Implement** — Write clean, minimal code that satisfies the assigned scope and makes the relevant tests pass.
-6. **Infer project commands, then run quality checks** — Determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
+6. **Use the Team Lead's setup commands when provided, then run quality checks** — If the Team Lead already provided bootstrap, build, or test commands, follow those exact commands first and do not rediscover them unless they fail. Otherwise determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
 7. **Commit** — Use a conventional commit message that matches the assigned scope.
 8. **Get the commit SHA** — After committing, run `git rev-parse HEAD` to get the full commit SHA.
 9. **Report back** — Return the exact commit SHA and a concise summary so validators can inspect exactly what changed.
@@ -58,6 +58,7 @@ If the Team Lead reassigns the scope with validator feedback:
 - Keep changes minimal and focused on the acceptance criteria or findings.
 - Do NOT gold-plate.
 - Treat automated coverage as part of the assignment, not optional cleanup. Do not finish with zero new or updated tests unless the Team Lead explicitly said coverage is already sufficient or you can point to a concrete repository-based reason automated coverage is not possible.
+- If the Team Lead gives exact bootstrap, build, or test commands, use them instead of re-probing the repository with generic commands. Only fall back to fresh command discovery if the provided commands fail or are clearly incomplete.
 - Infer project commands from the repository before running them. Check `AGENTS.md`, `README*`, and repo instructions first, prefer repo-defined scripts and task runners, and only use generic ecosystem defaults when the repo is unambiguous.
 - Do not validate your own work against the acceptance criteria beyond normal sanity checks. A separate validator may do that.
 - Do NOT skip quality checks.

package/README.md

@@ -44,9 +44,9 @@ This diagram shows the default `balanced` workflow only.
 
 ```mermaid
 flowchart TD
-    A[Start run] --> B[Validate PRD and create loop branch]
+    A[Start run] --> B[Validate PRD and create loop branch plus loop worktree]
     B --> C[Pick ready epic]
-    C --> D[Create worktree and run-scoped epic branch]
+    C --> D[Create epic worktree and run-scoped epic branch]
     D --> E[Team Lead decides on epic planner]
     E --> F[Team Lead runs stories with builder]
     F --> G{Epic validator needed?}
@@ -553,9 +553,9 @@ The current execution contract is:
 - blocked epics are skipped until dependencies are complete
 - runs sequentially by default
 - experimental wave parallelism is enabled only with `--parallel <n>`
-- at run start Ralph auto-commits any dirty worktree changes, then creates a fresh loop branch from your current branch
+- at run start Ralph auto-commits any dirty source-worktree changes, then creates a fresh loop branch and checks it out in `.ralph-teams/.worktrees/loop`
 - each epic gets its own worktree and a run-scoped branch rooted from that loop branch, using `ralph/epic/<loop-run>/<epic-id>`
-- before the Team Lead starts, Ralph creates the worktree and hands repo inspection, setup, build, and test command inference to the agents
+- before the Team Lead starts, Ralph creates the worktree and expects the Team Lead to establish that epic worktree's setup once, then hand the exact bootstrap, build, and test commands to Builders
 - agents are expected to prefer repo-defined scripts and docs over generic ecosystem defaults when choosing setup and verification commands
 - the shell-built Team Lead prompt must keep literal filenames shell-safe; do not add raw Markdown backticks inside that Bash string because Bash will treat them as command substitution
 - when an epic completes successfully, the Team Lead is expected to merge its epic branch back into the loop branch and write the merge-result artifact
@@ -638,9 +638,9 @@ Install or relink the package so the bundled JSON CLI is on your `PATH`:
 npm install -g ralph-teams
 ```
 
-### Ralph needs to switch branches but the worktree is dirty
+### Ralph needs a clean base commit before creating the loop worktree
 
-Ralph auto-commits current changes before creating or switching to the loop branch. If you do not want that commit, clean up the worktree yourself before starting the run.
+Ralph auto-commits current source-worktree changes before creating the loop branch and loop worktree. If you do not want that commit, clean up the worktree yourself before starting the run.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-teams",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "CLI tool for Ralph Teams",
   "bin": {
     "ralph-teams": "dist/index.js",

package/prompts/agents/builder.md

@@ -19,7 +19,7 @@ You are the hands. You implement. You do NOT choose overall scope or verify your
 3. **Understand the task** — Read the acceptance criteria or validation findings, the requested scope, and any retry feedback.
 4. **Create or update automated tests first when they should change** — If planning context includes test work, implement those tests. If no planning context exists and the scope is new behavior, work TDD-style: define the automated tests first, confirm they fail on the current code, then proceed.
 5. **Implement** — Write clean, minimal code that satisfies the assigned scope and makes the relevant tests pass.
-6. **Infer project commands, then run quality checks** — Determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
+6. **Use the Team Lead's setup commands when provided, then run quality checks** — If the Team Lead already provided bootstrap, build, or test commands, follow those exact commands first and do not rediscover them unless they fail. Otherwise determine the setup, build, and test commands from repo instructions and manifests. Check `AGENTS.md`, `README*`, and contributor docs first. Prefer repo-defined scripts or task runners over ecosystem defaults, then run the relevant verification commands for the assigned scope. Fix issues before committing.
 7. **Commit** — Use a conventional commit message that matches the assigned scope.
 8. **Get the commit SHA** — After committing, run `git rev-parse HEAD` to get the full commit SHA.
 9. **Report back** — Return the exact commit SHA and a concise summary so validators can inspect exactly what changed.
@@ -56,6 +56,7 @@ If the Team Lead reassigns the scope with validator feedback:
 - Keep changes minimal and focused on the acceptance criteria or findings.
 - Do NOT gold-plate.
 - Treat automated coverage as part of the assignment, not optional cleanup. Do not finish with zero new or updated tests unless the Team Lead explicitly said coverage is already sufficient or you can point to a concrete repository-based reason automated coverage is not possible.
+- If the Team Lead gives exact bootstrap, build, or test commands, use them instead of re-probing the repository with generic commands. Only fall back to fresh command discovery if the provided commands fail or are clearly incomplete.
 - Infer project commands from the repository before running them. Check `AGENTS.md`, `README*`, and repo instructions first, prefer repo-defined scripts and task runners, and only use generic ecosystem defaults when the repo is unambiguous.
 - Do not validate your own work against the acceptance criteria beyond normal sanity checks. A separate validator may do that.
 - Do NOT skip quality checks.

package/prompts/team-lead-policy.md

@@ -20,6 +20,10 @@ You coordinate epic execution. For clearly easy, low-risk mechanical tasks, you
 - Start with repository instructions: `AGENTS.md`, `README*`, contributor docs, and any project-local guidance files referenced there. Then prefer repository-defined task runners and scripts over language defaults: `Makefile`, `justfile`, `Taskfile.yml`, package scripts, wrapper scripts, or documented commands.
 - Then inspect ecosystem manifests such as `package.json`, `pyproject.toml`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Gemfile`, `pom.xml`, `build.gradle*`, `mix.exs`, `Dockerfile`, and `docker-compose*.yml`.
 - Prefer explicit repository commands over generic ecosystem defaults even when the language is obvious.
+- Before the first Builder for an epic, prepare the epic worktree environment once. Do not make each Builder rediscover basic setup from scratch.
+- Start by checking whether the source checkout path provided in the runtime prompt already contains reusable dependency or generated setup artifacts that the epic worktree can safely reuse.
+- If safe reuse is possible, materialize that reuse inside the epic worktree and continue. If reuse is not possible, run the repository's native bootstrap or install command inside the epic worktree before delegating implementation.
+- Once the bootstrap, build, and test commands are established, pass the exact commands and any required environment-prep steps to every Builder for that epic.
 - Only use generic defaults when the repository is unambiguous.
 - If setup or verification remains ambiguous after inspection, do not guess wildly. Mark the attempt failed with a short concrete reason describing the ambiguity.
 
@@ -47,7 +51,8 @@ You coordinate epic execution. For clearly easy, low-risk mechanical tasks, you
 
 - Before starting a story, check the epic state file. If the story has `passes: true`, skip it.
 - For clearly easy, low-risk mechanical stories, you may implement directly in the Team Lead session when delegation overhead would exceed the work. Keep the change narrowly scoped and still run the required verification yourself before counting the story complete.
-- Before delegating a story, determine the likely setup/build/test commands for this repository and pass the relevant commands or repository-based guidance to the Builder.
+- Before delegating the first story, ensure the epic worktree environment is actually runnable.
+- Before delegating any story, pass the exact bootstrap, build, and test commands already established for this epic to the Builder.
 - If an epic plan exists, give the Builder the story, acceptance criteria, relevant plan section, and especially the story's planned test design.
 - If a story planner was used, give the Builder the story planner output too.
 - Require the Builder to add or update automated tests for the story and make them pass before the story can count as complete.

package/prompts/team-lead-runtime.md

@@ -7,12 +7,20 @@ You are the Team Lead for this epic. Read the epic below and execute it.
 ALL work for this epic MUST happen in this directory: {{WORKTREE_ABS_PATH}}
 Do NOT modify files outside this directory, except for the epic state file below and the final merge workflow paths listed later in this prompt.
 
+## Source Checkout
+- Source checkout path: {{SOURCE_ROOT_DIR}}
+- You may inspect this source checkout read-only to understand repo-level setup and to reuse existing dependency or build artifacts when that is safer or faster than reinstalling inside the epic worktree.
+- Do NOT modify the source checkout during normal implementation. Any reuse should materialize inside the epic worktree, for example by creating a symlink there or copying a cacheable artifact into the worktree.
+
 ## Project Setup Strategy
 - Ralph does not preinstall dependencies or preselect build/test commands for this repo.
-- Before delegating implementation, infer the setup, build, and test commands from project context.
+- Before delegating implementation, establish the epic worktree environment once for this epic: determine the setup, build, and test commands, then make the worktree runnable before the first Builder starts.
 - Check repo instructions first: 'AGENTS.md', 'README*', contributor docs, and project-local guidance files. Then check repo-defined task runners or scripts such as 'Makefile', 'justfile', 'Taskfile.yml', package scripts, wrapper scripts, or documented commands.
 - Then inspect ecosystem manifests such as 'package.json', 'pyproject.toml', 'requirements.txt', 'Cargo.toml', 'go.mod', 'Gemfile', 'pom.xml', 'build.gradle*', 'mix.exs', 'Dockerfile', and 'docker-compose*.yml'.
 - Prefer explicit repository commands over generic ecosystem defaults.
+- If the epic worktree is missing dependencies or other generated setup artifacts, first check whether the source checkout already has reusable artifacts that can be safely reused from the worktree.
+- Prefer safe reuse from the source checkout when the repository structure and lockfiles make that reuse trustworthy; otherwise run the repository's native bootstrap/install step inside the epic worktree.
+- After you determine the correct bootstrap, build, and test commands, pass those exact commands to every Builder for this epic and tell Builders not to rediscover them unless the provided commands fail.
 - Only fall back to generic defaults when the repository is unambiguous.
 - If setup remains ambiguous after inspection, stop guessing and fail the story attempt with a short concrete reason describing what you found.
 

package/ralph.sh

@@ -331,15 +331,17 @@ if [ ! -f "$PRD_FILE" ]; then
   exit 1
 fi
 
-ROOT_DIR="$(pwd)"
-RALPH_RUNTIME_DIR="${ROOT_DIR}/${RALPH_RUNTIME_DIRNAME}"
+SOURCE_ROOT_DIR="$(pwd)"
+ROOT_DIR="$SOURCE_ROOT_DIR"
+LOOP_ROOT_DIR=""
+RALPH_RUNTIME_DIR="${SOURCE_ROOT_DIR}/${RALPH_RUNTIME_DIRNAME}"
 PROGRESS_FILE="${RALPH_RUNTIME_DIR}/progress.txt"
 PLANS_DIR="${RALPH_RUNTIME_DIR}/plans"
 LOGS_DIR="${RALPH_RUNTIME_DIR}/logs"
 STATE_DIR="${RALPH_RUNTIME_DIR}/state"
 WORKTREES_DIR="${RALPH_RUNTIME_DIR}/.worktrees"
 
-repair_root_runtime_dir_if_needed() {
+repair_source_runtime_dir_if_needed() {
   if [ -L "$RALPH_RUNTIME_DIR" ]; then
     local runtime_link_target=""
     runtime_link_target=$(readlink "$RALPH_RUNTIME_DIR" 2>/dev/null || true)
@@ -357,7 +359,7 @@ unstage_runtime_artifacts() {
   git rm --cached -r --ignore-unmatch "$RALPH_RUNTIME_DIRNAME" >/dev/null 2>&1 || true
 }
 
-repair_root_runtime_dir_if_needed
+repair_source_runtime_dir_if_needed
 mkdir -p "$RALPH_RUNTIME_DIR" "$PLANS_DIR" "$LOGS_DIR" "$STATE_DIR" "$WORKTREES_DIR"
 
 ensure_runtime_rjq_bin() {
@@ -581,7 +583,7 @@ ensure_runtime_gitignore_entries() {
 prompt_to_commit_dirty_worktree() {
   local target_branch="$1"
 
-  echo "Worktree has uncommitted changes and Ralph needs to create or switch to branch '$target_branch'."
+  echo "Worktree has uncommitted changes and Ralph needs a clean base commit before creating loop worktree branch '$target_branch'."
   echo "Ralph will now stage and commit all current changes before the run."
   git status --short
   git add -A
@@ -617,6 +619,15 @@ auto_remove_stale_worktree_dir() {
   rm -rf "$worktree_path"
 }
 
+find_worktree_for_branch() {
+  local branch_name="$1"
+
+  git worktree list --porcelain 2>/dev/null | awk -v branch="refs/heads/${branch_name}" '
+    $1 == "worktree" { path = substr($0, 10); next }
+    $1 == "branch" && $2 == branch { print path; exit }
+  '
+}
+
 cleanup_epic_worktree_artifacts() {
   local worktree_path="$1"
   local branch_name="$2"
@@ -637,34 +648,56 @@ cleanup_epic_worktree_artifacts() {
   git branch -D "$branch_name" >/dev/null 2>&1 || true
 }
 
-# --- Ensure loop branch exists and is checked out ---
+# --- Ensure loop branch exists and has a dedicated worktree ---
 ensure_runtime_gitignore_entries
 ensure_repo_has_initial_commit
 
 mkdir -p "$RALPH_RUNTIME_DIR" "$PLANS_DIR" "$LOGS_DIR" "$STATE_DIR" "$WORKTREES_DIR"
 
-ensure_loop_branch_ready() {
-  local checkout_output=""
+ensure_loop_worktree_ready() {
+  local loop_worktree_path="${WORKTREES_DIR}/loop"
+  local add_output=""
+  local retry_output=""
+  local existing_worktree=""
+
+  existing_worktree="$(find_worktree_for_branch "$LOOP_BRANCH" || true)"
+  if [ -n "$existing_worktree" ] && [ -d "$existing_worktree" ]; then
+    LOOP_ROOT_DIR="$existing_worktree"
+    ensure_worktree_runtime_link "$LOOP_ROOT_DIR"
+    return
+  fi
+
+  if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+    prompt_to_commit_dirty_worktree "$LOOP_BRANCH"
+  fi
 
-  if [ "$CURRENT_BRANCH" != "$LOOP_BRANCH" ]; then
-    if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
-      prompt_to_commit_dirty_worktree "$LOOP_BRANCH"
+  if ! git show-ref --verify --quiet "refs/heads/${LOOP_BRANCH}"; then
+    echo "Creating loop branch: $LOOP_BRANCH (from $CURRENT_BRANCH)"
+    if ! add_output=$(git branch "$LOOP_BRANCH" "$CURRENT_BRANCH" 2>&1 >/dev/null); then
+      echo "Error: failed to create loop branch '$LOOP_BRANCH' from '$CURRENT_BRANCH'." >&2
+      [ -n "$add_output" ] && echo "$add_output" >&2
+      exit 1
     fi
+  fi
 
-    if git show-ref --verify --quiet "refs/heads/${LOOP_BRANCH}"; then
-      echo "Switching to loop branch: $LOOP_BRANCH"
-      if ! checkout_output=$(git checkout "$LOOP_BRANCH" 2>&1 >/dev/null); then
-        echo "Error: failed to switch to loop branch '$LOOP_BRANCH'." >&2
-        [ -n "$checkout_output" ] && echo "$checkout_output" >&2
-        exit 1
-      fi
-    else
-      echo "Creating loop branch: $LOOP_BRANCH (from $CURRENT_BRANCH)"
-      if ! checkout_output=$(git checkout -b "$LOOP_BRANCH" 2>&1 >/dev/null); then
-        echo "Error: failed to create loop branch '$LOOP_BRANCH' from '$CURRENT_BRANCH'." >&2
-        [ -n "$checkout_output" ] && echo "$checkout_output" >&2
-        exit 1
-      fi
+  git worktree prune >/dev/null 2>&1 || true
+  if [ -d "$loop_worktree_path" ] && ! git worktree list | grep -Fq "$loop_worktree_path"; then
+    auto_remove_stale_worktree_dir "$loop_worktree_path" "$LOOP_BRANCH"
+  fi
+
+  echo "Creating loop worktree: $loop_worktree_path ($LOOP_BRANCH)"
+  if ! add_output=$(git worktree add "$loop_worktree_path" "$LOOP_BRANCH" 2>&1 >/dev/null); then
+    echo "Loop worktree creation for '$LOOP_BRANCH' failed on the first attempt; pruning stale state and retrying once." >&2
+    [ -n "$add_output" ] && echo "$add_output" >&2
+    git worktree prune >/dev/null 2>&1 || true
+    git worktree remove "$loop_worktree_path" --force >/dev/null 2>&1 || true
+    if [ -d "$loop_worktree_path" ]; then
+      auto_remove_stale_worktree_dir "$loop_worktree_path" "$LOOP_BRANCH"
+    fi
+    if ! retry_output=$(git worktree add "$loop_worktree_path" "$LOOP_BRANCH" 2>&1 >/dev/null); then
+      echo "Error: failed to create loop worktree '$loop_worktree_path' for '$LOOP_BRANCH'." >&2
+      [ -n "$retry_output" ] && echo "$retry_output" >&2
+      exit 1
     fi
   fi
 
@@ -673,15 +706,17 @@ ensure_loop_branch_ready() {
     exit 1
   fi
 
-  CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
-  if [ "$CURRENT_BRANCH" != "$LOOP_BRANCH" ]; then
-    echo "Error: expected current branch '$LOOP_BRANCH' after setup, got '${CURRENT_BRANCH:-<none>}'." >&2
+  LOOP_ROOT_DIR="$loop_worktree_path"
+  ensure_worktree_runtime_link "$LOOP_ROOT_DIR"
+
+  local loop_branch_name=""
+  loop_branch_name=$(git -C "$LOOP_ROOT_DIR" branch --show-current 2>/dev/null || echo "")
+  if [ "$loop_branch_name" != "$LOOP_BRANCH" ]; then
+    echo "Error: expected loop worktree branch '$LOOP_BRANCH' after setup, got '${loop_branch_name:-<none>}'." >&2
     exit 1
   fi
 }
 
-ensure_loop_branch_ready
-
 epic_branch_name() {
   local epic_id="$1"
   echo "ralph/epic/${LOOP_BRANCH#ralph/}/${epic_id}"
@@ -746,7 +781,7 @@ create_epic_worktree() {
   local epic_id="$1"
   local branch_name
   branch_name=$(epic_branch_name "$epic_id")
-  local worktree_path="${RALPH_RUNTIME_DIRNAME}/.worktrees/${epic_id}"
+  local worktree_path="${WORKTREES_DIR}/${epic_id}"
   local add_output
   local retry_output
 
@@ -785,10 +820,20 @@ ensure_worktree_runtime_link() {
   local worktree_abs_path="$1"
   local worktree_runtime_path="${worktree_abs_path}/${RALPH_RUNTIME_DIRNAME}"
 
-  if [ -L "$worktree_runtime_path" ]; then
+  if [ "$worktree_abs_path" = "$SOURCE_ROOT_DIR" ]; then
     return 0
   fi
 
+  if [ -L "$worktree_runtime_path" ]; then
+    local current_target
+    current_target="$(readlink "$worktree_runtime_path")"
+    if [ "$current_target" = "$RALPH_RUNTIME_DIR" ]; then
+      return 0
+    fi
+    log_warn "Stale runtime symlink in worktree (points to '${current_target}', expected '${RALPH_RUNTIME_DIR}') — relinking"
+    rm -f "$worktree_runtime_path"
+  fi
+
   if [ -e "$worktree_runtime_path" ] && [ ! -L "$worktree_runtime_path" ]; then
     rm -rf "$worktree_runtime_path"
   fi
@@ -796,15 +841,20 @@ ensure_worktree_runtime_link() {
   ln -s "$RALPH_RUNTIME_DIR" "$worktree_runtime_path"
 }
 
+ensure_loop_worktree_ready
+ROOT_DIR="$LOOP_ROOT_DIR"
+cd "$ROOT_DIR"
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+
 # Removes a worktree. The branch is kept for potential merge by a later agent.
 cleanup_epic_worktree() {
   local epic_id="$1"
-  git worktree remove "${RALPH_RUNTIME_DIRNAME}/.worktrees/${epic_id}" --force 2>/dev/null || true
+  git worktree remove "${WORKTREES_DIR}/${epic_id}" --force 2>/dev/null || true
 }
 
 # Removes ALL .worktrees/* entries (used on EXIT).
 cleanup_all_worktrees() {
-  for dir in "${RALPH_RUNTIME_DIRNAME}"/.worktrees/*/; do
+  for dir in "${WORKTREES_DIR}"/*/; do
     [ -d "$dir" ] && git worktree remove "$dir" --force 2>/dev/null || true
   done
 }
@@ -912,8 +962,8 @@ CURRENT_STORY_ID=""
 
 # Resolve absolute path to PRD file so team lead always has the correct path
 PRD_ABS_PATH="$(cd "$(dirname "$PRD_FILE")" && pwd)/$(basename "$PRD_FILE")"
-if [ "${PRD_ABS_PATH#"$ROOT_DIR"/}" != "$PRD_ABS_PATH" ]; then
-  PRD_REL_PATH="${PRD_ABS_PATH#"$ROOT_DIR"/}"
+if [ "${PRD_ABS_PATH#"$SOURCE_ROOT_DIR"/}" != "$PRD_ABS_PATH" ]; then
+  PRD_REL_PATH="${PRD_ABS_PATH#"$SOURCE_ROOT_DIR"/}"
 else
   PRD_REL_PATH="$(basename "$PRD_FILE")"
 fi
@@ -1305,12 +1355,13 @@ prepare_codex_agent_configs
 LOOP_STARTED_AT=$(date +%s)
 
 # Cleanup worktrees on exit only when NOT interrupted (on interrupt, worktrees are preserved for resume)
-trap 'if [ "$INTERRUPTED" = false ]; then cleanup_all_worktrees; fi; [ -n "${CODEX_AGENT_RUNTIME_DIR:-}" ] && rm -rf "${CODEX_AGENT_RUNTIME_DIR}"; kill $(jobs -p) 2>/dev/null || true' EXIT
+trap 'if [ "$INTERRUPTED" = false ]; then cd "$SOURCE_ROOT_DIR" 2>/dev/null || true; cleanup_all_worktrees; fi; [ -n "${CODEX_AGENT_RUNTIME_DIR:-}" ] && rm -rf "${CODEX_AGENT_RUNTIME_DIR}"; kill $(jobs -p) 2>/dev/null || true' EXIT
 
 render_team_lead_prompt() {
   TEAM_LEAD_TEMPLATE_PATH="$TEAM_LEAD_PROMPT_FILE" \
   TEAM_LEAD_TEMPLATE_PROJECT="$PROJECT" \
   TEAM_LEAD_TEMPLATE_WORKTREE_ABS_PATH="$WORKTREE_ABS_PATH" \
+  TEAM_LEAD_TEMPLATE_SOURCE_ROOT_DIR="$SOURCE_ROOT_DIR" \
   TEAM_LEAD_TEMPLATE_WORKTREE_STATE_FILE="$WORKTREE_STATE_FILE" \
   TEAM_LEAD_TEMPLATE_WORKTREE_PRD_PATH="$WORKTREE_PRD_PATH" \
   TEAM_LEAD_TEMPLATE_LOOP_BRANCH="$LOOP_BRANCH" \
@@ -1550,7 +1601,7 @@ spawn_epic_bg() {
   local WORKTREE_PATH
   WORKTREE_PATH=$(create_epic_worktree "$EPIC_ID")
   local WORKTREE_ABS_PATH
-  WORKTREE_ABS_PATH="$(cd "${ROOT_DIR}/${WORKTREE_PATH}" && pwd)"
+  WORKTREE_ABS_PATH="$WORKTREE_PATH"
   local EPIC_BRANCH
   EPIC_BRANCH=$(epic_branch_name "$EPIC_ID")
   ensure_worktree_runtime_link "$WORKTREE_ABS_PATH"
@@ -1586,7 +1637,11 @@ spawn_epic_bg() {
     ) &
   elif [ "$BACKEND" = "codex" ]; then
     (
-      run_codex_exec "$WORKTREE_ABS_PATH" "$TEAM_PROMPT" --add-dir "$ROOT_DIR" --add-dir "$SCRIPT_DIR" > "$EPIC_LOG" 2>&1
+      if [ "$SOURCE_ROOT_DIR" != "$ROOT_DIR" ]; then
+        run_codex_exec "$WORKTREE_ABS_PATH" "$TEAM_PROMPT" --add-dir "$ROOT_DIR" --add-dir "$SOURCE_ROOT_DIR" --add-dir "$SCRIPT_DIR" > "$EPIC_LOG" 2>&1
+      else
+        run_codex_exec "$WORKTREE_ABS_PATH" "$TEAM_PROMPT" --add-dir "$ROOT_DIR" --add-dir "$SCRIPT_DIR" > "$EPIC_LOG" 2>&1
+      fi
     ) &
   else
     (
@@ -1623,6 +1678,8 @@ merge_wave() {
   for epic_id in "${completed_epic_ids[@]}"; do
     local branch_name
     branch_name=$(epic_branch_name "$epic_id")
+    local epic_index
+    epic_index=$(rjq find-index "$PRD_FILE" .epics id "$epic_id")
 
     # Check if branch exists
     if ! git show-ref --verify --quiet "refs/heads/${branch_name}"; then
@@ -1647,15 +1704,18 @@ merge_wave() {
     # be stripped before the merge result is recorded in git history.
     if git merge "${branch_name}" --no-commit --no-ff 2>/dev/null; then
       unstage_runtime_artifacts
-      repair_root_runtime_dir_if_needed
+      repair_source_runtime_dir_if_needed
       if [ -f ".git/MERGE_HEAD" ]; then
         git commit --no-edit >/dev/null 2>&1 || true
       fi
+      if [ -n "$epic_index" ]; then
+        rjq set "$PRD_FILE" ".epics[$epic_index].status" '"completed"'
+      fi
       echo "  [$epic_id] Merge successful (clean)"
       echo "[$epic_id] MERGED (clean) — $(date)" >> "$PROGRESS_FILE"
     else
       unstage_runtime_artifacts
-      repair_root_runtime_dir_if_needed
+      repair_source_runtime_dir_if_needed
       local conflicted_files
       conflicted_files=$(git diff --name-only --diff-filter=U 2>/dev/null || true)
       local conflict_count
@@ -1669,8 +1729,6 @@ merge_wave() {
         [ -n "$merge_error" ] && echo "  [$epic_id] Working tree state:" && printf '%s\n' "$merge_error" | sed 's/^/    /'
         merge_failures=$((merge_failures + 1))
 
-        local epic_index
-        epic_index=$(rjq find-index "$PRD_FILE" .epics id "$epic_id")
         if [ -n "$epic_index" ]; then
           rjq set "$PRD_FILE" ".epics[$epic_index].status" '"merge-failed"'
         fi
@@ -1687,6 +1745,9 @@ merge_wave() {
         git checkout --ours -- prd.json
         git add prd.json
         git commit --no-edit >/dev/null 2>&1 || true
+        if [ -n "$epic_index" ]; then
+          rjq set "$PRD_FILE" ".epics[$epic_index].status" '"completed"'
+        fi
         echo "  [$epic_id] Merge successful (kept projected prd.json)"
         echo "[$epic_id] MERGED (projected prd.json) — $(date)" >> "$PROGRESS_FILE"
         git branch -d "${branch_name}" 2>/dev/null || true
@@ -1698,8 +1759,6 @@ merge_wave() {
       echo "[$epic_id] MERGE FAILED (conflicts remain, files: ${conflicted_files}) — $(date)" >> "$PROGRESS_FILE"
       merge_failures=$((merge_failures + 1))
 
-      local epic_index
-      epic_index=$(rjq find-index "$PRD_FILE" .epics id "$epic_id")
       if [ -n "$epic_index" ]; then
         rjq set "$PRD_FILE" ".epics[$epic_index].status" '"merge-failed"'
       fi
@@ -1797,17 +1856,32 @@ run_backend_agent_session() {
       local prompt_file="${SCRIPT_DIR}/prompts/agents/${agent_name}.md"
       local role_body
       role_body="$(extract_prompt_body "$prompt_file")"
-      printf 'Runtime note: This Codex session runs in exec mode. `request_user_input` is unavailable. Never call it. Do not stop to ask the user questions. Make a reasonable assumption and continue.\n\n%s\n\n## Assignment\n%s\n' "$role_body" "$prompt" | codex \
-        -a never \
-        exec \
-        -C "$workdir" \
-        -m "$model" \
-        -s workspace-write \
-        --skip-git-repo-check \
-        --color never \
-        --add-dir "$ROOT_DIR" \
-        --add-dir "$SCRIPT_DIR" \
-        - > "$log_file" 2>&1 || true
+      if [ "$SOURCE_ROOT_DIR" != "$ROOT_DIR" ]; then
+        printf 'Runtime note: This Codex session runs in exec mode. `request_user_input` is unavailable. Never call it. Do not stop to ask the user questions. Make a reasonable assumption and continue.\n\n%s\n\n## Assignment\n%s\n' "$role_body" "$prompt" | codex \
+          -a never \
+          exec \
+          -C "$workdir" \
+          -m "$model" \
+          -s workspace-write \
+          --skip-git-repo-check \
+          --color never \
+          --add-dir "$ROOT_DIR" \
+          --add-dir "$SOURCE_ROOT_DIR" \
+          --add-dir "$SCRIPT_DIR" \
+          - > "$log_file" 2>&1 || true
+      else
+        printf 'Runtime note: This Codex session runs in exec mode. `request_user_input` is unavailable. Never call it. Do not stop to ask the user questions. Make a reasonable assumption and continue.\n\n%s\n\n## Assignment\n%s\n' "$role_body" "$prompt" | codex \
+          -a never \
+          exec \
+          -C "$workdir" \
+          -m "$model" \
+          -s workspace-write \
+          --skip-git-repo-check \
+          --color never \
+          --add-dir "$ROOT_DIR" \
+          --add-dir "$SCRIPT_DIR" \
+          - > "$log_file" 2>&1 || true
+      fi
       ;;
   esac
 }
@@ -1905,6 +1979,24 @@ $validation_result_file
 
 }
 
+persist_loop_branch_state_if_dirty() {
+  local dirty_status=""
+  dirty_status=$(git status --porcelain --untracked-files=no 2>/dev/null || true)
+  [ -n "$dirty_status" ] || return 0
+
+  git add -u
+  unstage_runtime_artifacts
+
+  if git diff --cached --quiet >/dev/null 2>&1; then
+    git reset >/dev/null 2>&1 || true
+    return 0
+  fi
+
+  if git commit -m "chore: persist loop branch state" >/dev/null 2>&1; then
+    echo "Persisted loop branch state on ${LOOP_BRANCH}"
+  fi
+}
+
 if ! recover_pending_merges "resume/startup"; then
   initialize_counters
 fi
@@ -2309,6 +2401,8 @@ if ! run_final_validation_cycle; then
   FAILED=$((FAILED + 1))
 fi
 
+persist_loop_branch_state_if_dirty
+
 # --- Summary ---
 REMAINING=$((TOTAL_EPICS - COMPLETED - FAILED))
 echo ""