ralph-teams 1.0.35 → 1.0.36

package/package.json

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

package/prompts/team-lead-policy.md

@@ -16,13 +16,13 @@ You coordinate epic execution. For clearly easy, low-risk mechanical tasks, you
 
 ## Command Inference
 
-- Ralph does not centrally bootstrap project dependencies for the worktree. You must infer the right setup, build, and test commands from the repository itself.
+- Ralph does not centrally bootstrap project dependencies for the epic workspace. You must infer the right setup, build, and test commands from the repository itself.
 - 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.
+- Before the first Builder for an epic, prepare the epic workspace 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 workspace can safely reuse.
+- If safe reuse is possible, materialize that reuse inside the epic workspace and continue. If reuse is not possible, run the repository's native bootstrap or install command inside the epic workspace 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.
@@ -51,7 +51,7 @@ 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 the first story, ensure the epic worktree environment is actually runnable.
+- Before delegating the first story, ensure the epic workspace 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.
@@ -102,13 +102,14 @@ You coordinate epic execution. For clearly easy, low-risk mechanical tasks, you
 
 ## Merge Completion
 
-- If every story in the epic passes, this same Team Lead session must attempt the merge before exiting.
+- The Team Lead always owns the first merge attempt before exiting.
 - Use the loop-branch name, repository-root path, epic branch name, and merge-result artifact path provided by the runtime prompt.
-- You may leave the epic worktree only for this final merge attempt. Keep all other work inside the epic worktree.
+- You may leave the epic workspace only for this final merge attempt. Keep all other work inside the epic workspace.
 - Attempt the merge on the repository root branch with `git merge <epic-branch> --no-commit --no-ff` so you can resolve conflicts before the final commit.
-- Before the merge attempt, check the repository root for uncommitted changes. If it is dirty, create a checkpoint commit so the merge can proceed cleanly.
-- If the merge is clean, commit it and write a merge-result artifact with `status: "merged"` and mode `clean` or `projected-prd` as appropriate.
-- If there are conflicts, resolve them yourself in this same session. Do not delegate to another merger role or any other teammate. If you resolve the conflicts, commit the merge and write `status: "merged"` with mode `conflict-resolved`.
-- If you cannot resolve the merge safely, abort the merge, write a merge-result artifact with `status: "merge-failed"`, include a short concrete `details` string, and then exit.
-- The merge-result artifact must be written atomically to the exact path provided by the runtime prompt before you print the final DONE line.
-- Only print `DONE: X/Y stories passed` after the merge attempt and merge-result artifact write are finished.
+- Before the Team Lead-owned merge attempt, check the repository root for uncommitted changes. If it is dirty, create a checkpoint commit so the merge can proceed cleanly.
+- If the Team Lead-owned merge is clean, commit it and write a merge-result artifact with `status: "merged"` and mode `clean` or `projected-prd` as appropriate.
+- If there are conflicts during a Team Lead-owned merge, resolve them yourself in this same session. Do not delegate to another merger role or any other teammate. If you resolve the conflicts, commit the merge and write `status: "merged"` with mode `conflict-resolved`.
+- If you cannot resolve a Team Lead-owned merge safely, abort the merge, write a merge-result artifact with `status: "merge-failed"`, include a short concrete `details` string, and then exit.
+- Write the merge-result artifact atomically to the exact path provided by the runtime prompt before you print the final DONE line.
+- Ralph will verify the merge result after your session exits and may attempt a scripted fallback merge if the branch is still unmerged.
+- Only print `DONE: X/Y stories passed` after the required final action for this runtime mode is finished.

package/prompts/team-lead-runtime.md

@@ -9,17 +9,17 @@ Do NOT modify files outside this directory, except for the epic state file below
 
 ## 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.
+- 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 workspace.
+- Do NOT modify the source checkout during normal implementation. Any reuse should materialize inside the epic workspace, for example by creating a symlink there or copying a cacheable artifact into the workspace.
 
 ## Project Setup Strategy
 - Ralph does not preinstall dependencies or preselect build/test commands for this repo.
-- 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.
+- Before delegating implementation, establish the epic workspace environment once for this epic: determine the setup, build, and test commands, then make the workspace 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.
+- If the epic workspace 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 workspace.
+- 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 workspace.
 - 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.
@@ -31,16 +31,7 @@ Do NOT modify files outside this directory, except for the epic state file below
 {{WORKTREE_PRD_PATH}}
 
 ## Merge Responsibility
-- If all stories pass, this same Team Lead session owns the merge attempt before exiting.
-- Loop branch to merge into: {{LOOP_BRANCH}}
-- Source epic branch: {{EPIC_BRANCH}}
-- Repository root for the merge attempt: {{ROOT_DIR}}
-- Write the final merge result artifact to: {{WORKTREE_MERGE_RESULT_FILE}}
-- The merge result artifact must be valid JSON with fields: epicId, status, mode, details, timestamp.
-- Allowed status values: merged, merge-failed.
-- Allowed mode values: clean, projected-prd, conflict-resolved, unknown.
-- When all stories pass, do not print DONE until after you have attempted the merge and written the merge result artifact.
-- During the merge attempt you may operate in the repository root path above even though normal implementation work stays inside the epic worktree.
+{{MERGE_RESPONSIBILITY}}
 
 ## Epic
 {{EPIC_JSON}}

package/ralph.sh

@@ -686,8 +686,15 @@ ensure_repo_has_initial_commit
 
 mkdir -p "$RALPH_RUNTIME_DIR" "$PLANS_DIR" "$LOGS_DIR" "$STATE_DIR" "$WORKTREES_DIR"
 
+loop_worktree_path() {
+  local loop_suffix="${LOOP_BRANCH#ralph/loop/}"
+  loop_suffix=$(printf '%s' "$loop_suffix" | tr '/:' '--')
+  echo "${WORKTREES_DIR}/loop-${loop_suffix}"
+}
+
 ensure_loop_worktree_ready() {
-  local loop_worktree_path="${WORKTREES_DIR}/loop"
+  local loop_worktree_path
+  loop_worktree_path="$(loop_worktree_path)"
   local add_output=""
   local retry_output=""
   local existing_worktree=""
@@ -804,6 +811,10 @@ fail_on_pending_epic_git_state_mismatch() {
 fail_on_pending_epic_git_state_mismatch
 
 # --- Worktree Management ---
+use_dedicated_epic_worktrees() {
+  [ -n "$PARALLEL" ] && [ "$PARALLEL" -gt 1 ]
+}
+
 # Creates a git worktree at .worktrees/<epic_id> on a run-scoped branch under
 # the current loop branch name, rooted from the loop branch for this run.
 # rooted from the loop branch for this run.
@@ -843,6 +854,56 @@ create_epic_worktree() {
   echo "$worktree_path"
 }
 
+restore_loop_worktree_branch() {
+  local current_branch=""
+  current_branch=$(git -C "$LOOP_ROOT_DIR" branch --show-current 2>/dev/null || echo "")
+
+  if [ -z "$current_branch" ] || [ "$current_branch" = "$LOOP_BRANCH" ]; then
+    return 0
+  fi
+
+  local dirty_status=""
+  dirty_status=$(git -C "$LOOP_ROOT_DIR" status --porcelain 2>/dev/null || true)
+  if [ -n "$dirty_status" ]; then
+    git -C "$LOOP_ROOT_DIR" add -A
+    (
+      cd "$LOOP_ROOT_DIR"
+      unstage_runtime_artifacts
+    )
+    if git -C "$LOOP_ROOT_DIR" commit -m "chore: checkpoint ${current_branch} before returning to loop branch" >/dev/null 2>&1; then
+      echo "  [${current_branch}] Auto-committed dirty workspace before returning to ${LOOP_BRANCH}"
+    fi
+  fi
+
+  git -C "$LOOP_ROOT_DIR" checkout "$LOOP_BRANCH" >/dev/null 2>&1
+}
+
+prepare_sequential_epic_workspace() {
+  local epic_id="$1"
+  local branch_name
+  branch_name=$(epic_branch_name "$epic_id")
+
+  restore_loop_worktree_branch
+
+  if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
+    git -C "$LOOP_ROOT_DIR" checkout "$branch_name" >/dev/null 2>&1
+  else
+    git -C "$LOOP_ROOT_DIR" checkout -b "$branch_name" "$LOOP_BRANCH" >/dev/null 2>&1
+  fi
+
+  echo "$LOOP_ROOT_DIR"
+}
+
+prepare_epic_workspace() {
+  local epic_id="$1"
+
+  if use_dedicated_epic_worktrees; then
+    create_epic_worktree "$epic_id"
+  else
+    prepare_sequential_epic_workspace "$epic_id"
+  fi
+}
+
 compute_file_checksum() {
   local file_path="$1"
   cksum "$file_path" | awk '{print $1 ":" $2}'
@@ -884,6 +945,16 @@ cleanup_epic_worktree() {
   git worktree remove "${WORKTREES_DIR}/${epic_id}" --force 2>/dev/null || true
 }
 
+cleanup_epic_workspace() {
+  local epic_id="$1"
+
+  if use_dedicated_epic_worktrees; then
+    cleanup_epic_worktree "$epic_id"
+  else
+    restore_loop_worktree_branch
+  fi
+}
+
 # Removes ALL .worktrees/* entries (used on EXIT).
 cleanup_all_worktrees() {
   for dir in "${WORKTREES_DIR}"/*/; do
@@ -1405,6 +1476,7 @@ render_team_lead_prompt() {
   TEAM_LEAD_TEMPLATE_EPIC_PLANNED="$EPIC_PLANNED" \
   TEAM_LEAD_TEMPLATE_WORKTREE_PLAN_EXISTS="$WORKTREE_PLAN_EXISTS" \
   TEAM_LEAD_TEMPLATE_PENDING_STORIES_JSON="$PENDING_STORIES_JSON" \
+  TEAM_LEAD_TEMPLATE_MERGE_RESPONSIBILITY="$MERGE_RESPONSIBILITY" \
   TEAM_LEAD_TEMPLATE_TEAM_LEAD_POLICY="$TEAM_LEAD_POLICY" \
   TEAM_LEAD_TEMPLATE_STORY_PLANNING_ENABLED="$STORY_PLANNING_ENABLED" \
   TEAM_LEAD_TEMPLATE_STORY_VALIDATION_ENABLED="$STORY_VALIDATION_ENABLED" \
@@ -1432,7 +1504,7 @@ NODE
 process_epic_result() {
   local epic_index="$1"
   local epic_id
-  epic_id=$(rjq read "$PRD_FILE" ".epics[$epic_index].id")
+  epic_id=$(rjq read "$PRD_FILE" ".epics[$epic_index].id" 2>/dev/null) || epic_id="EPIC-???"
   local merge_status=""
   merge_status=$(read_epic_merge_result_field "$epic_id" .status "" 2>/dev/null || true)
   local merge_mode=""
@@ -1441,48 +1513,36 @@ process_epic_result() {
   merge_details=$(read_epic_merge_result_field "$epic_id" .details "" 2>/dev/null || true)
 
   local total_stories
-  total_stories=$(rjq length "$PRD_FILE" ".epics[$epic_index].userStories")
+  total_stories=$(rjq length "$PRD_FILE" ".epics[$epic_index].userStories" 2>/dev/null) || total_stories=0
   local passed_stories
-  passed_stories=$(rjq count-where "$PRD_FILE" ".epics[$epic_index].userStories" "passes=true")
+  passed_stories=$(rjq count-where "$PRD_FILE" ".epics[$epic_index].userStories" "passes=true" 2>/dev/null) || passed_stories=0
 
   if [ "$passed_stories" -eq "$total_stories" ] && [ "$total_stories" -gt 0 ]; then
-    if [ "$merge_status" = "merge-failed" ]; then
-      echo ""
-      echo "  [$epic_id] MERGE FAILED — all stories passed but merge did not complete"
-      [ -n "$merge_details" ] && echo "  [$epic_id] Merge details: $merge_details"
-      rjq set "$PRD_FILE" ".epics[$epic_index].status" '"merge-failed"'
-      FAILED=$((FAILED + 1))
-      echo "[$epic_id] MERGE FAILED (${merge_details:-team lead merge failed}) — $(date)" >> "$PROGRESS_FILE"
-      return
-    fi
-
-    if [ "$merge_status" != "merged" ]; then
-      echo ""
-      echo "  [$epic_id] MERGE FAILED — all stories passed but Team Lead did not record a merge result"
-      rjq set "$PRD_FILE" ".epics[$epic_index].status" '"merge-failed"'
-      FAILED=$((FAILED + 1))
-      echo "[$epic_id] MERGE FAILED (missing team lead merge result artifact) — $(date)" >> "$PROGRESS_FILE"
-      return
-    fi
-
     echo ""
     echo "  [$epic_id] PASSED — all stories completed ($passed_stories/$total_stories)"
-    rjq set "$PRD_FILE" ".epics[$epic_index].status" '"completed"'
+    rjq set "$PRD_FILE" ".epics[$epic_index].status" '"completed"' 2>/dev/null || echo "  [WARN] Failed to set epic $epic_index status" >&2
     COMPLETED=$((COMPLETED + 1))
     echo "[$epic_id] PASSED — $(date)" >> "$PROGRESS_FILE"
     if [ "$merge_status" = "merged" ]; then
       echo "  [$epic_id] Merge successful (team lead, ${merge_mode:-unknown})"
       echo "[$epic_id] MERGED (team lead ${merge_mode:-unknown}) — $(date)" >> "$PROGRESS_FILE"
+    elif [ "$merge_status" = "merge-failed" ]; then
+      echo "  [$epic_id] Team Lead merge did not complete — Ralph will verify and may retry on ${LOOP_BRANCH}"
+      [ -n "$merge_details" ] && echo "  [$epic_id] Merge details: $merge_details"
+      echo "[$epic_id] PENDING MERGE VERIFICATION (${merge_details:-team lead merge failed}) — $(date)" >> "$PROGRESS_FILE"
+    else
+      echo "  [$epic_id] Merge result missing — Ralph will verify and may retry on ${LOOP_BRANCH}"
+      echo "[$epic_id] PENDING MERGE VERIFICATION (missing team lead merge result artifact) — $(date)" >> "$PROGRESS_FILE"
     fi
   elif [ "$passed_stories" -gt 0 ]; then
     echo ""
     echo "  [$epic_id] PARTIAL — $passed_stories/$total_stories stories passed"
-    rjq set "$PRD_FILE" ".epics[$epic_index].status" '"partial"'
+    rjq set "$PRD_FILE" ".epics[$epic_index].status" '"partial"' 2>/dev/null || echo "  [WARN] Failed to set epic $epic_index status" >&2
     echo "[$epic_id] PARTIAL ($passed_stories/$total_stories) — $(date)" >> "$PROGRESS_FILE"
   else
     echo ""
     echo "  [$epic_id] FAILED — 0/$total_stories stories passed"
-    rjq set "$PRD_FILE" ".epics[$epic_index].status" '"failed"'
+    rjq set "$PRD_FILE" ".epics[$epic_index].status" '"failed"' 2>/dev/null || echo "  [WARN] Failed to set epic $epic_index status" >&2
     FAILED=$((FAILED + 1))
     echo "[$epic_id] FAILED (0/$total_stories) — $(date)" >> "$PROGRESS_FILE"
   fi
@@ -1532,6 +1592,31 @@ read_epic_merge_result_field() {
   rjq read "$result_file" "$field_path" "$default_value"
 }
 
+write_epic_merge_result_file() {
+  local epic_id="$1"
+  local status="$2"
+  local mode="$3"
+  local details="$4"
+  local result_file="${STATE_DIR}/merge-${epic_id}.json"
+  local tmp_file
+  tmp_file=$(mktemp "${STATE_DIR}/.merge-${epic_id}.json.XXXXXX")
+
+  node - "$tmp_file" "$epic_id" "$status" "$mode" "$details" <<'NODE'
+const fs = require('fs');
+const [filePath, epicId, status, mode, details] = process.argv.slice(2);
+const payload = {
+  epicId,
+  status,
+  mode,
+  details,
+  timestamp: new Date().toISOString(),
+};
+fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`);
+NODE
+
+  mv "$tmp_file" "$result_file"
+}
+
 delete_epic_branch() {
   local epic_id="$1"
   local branch_name
@@ -1564,7 +1649,7 @@ NODE
 
 read_epic_prd_passed() {
   local epic_index="$1"
-  rjq count-where "$PRD_FILE" ".epics[$epic_index].userStories" "passes=true"
+  rjq count-where "$PRD_FILE" ".epics[$epic_index].userStories" "passes=true" 2>/dev/null || echo 0
 }
 
 project_state_to_prd() {
@@ -1612,26 +1697,36 @@ NODE
 
 # spawn_epic_bg: create worktree, build prompt, and run team lead in the background.
 # Sets LAST_SPAWN_PID to the background PID.
-# Callers must wait on that PID and then call cleanup_epic_worktree + process_epic_result.
+# Callers must wait on that PID and then call cleanup_epic_workspace + process_epic_result.
 spawn_epic_bg() {
   local EPIC_INDEX="$1"
   local EPIC_ID
-  EPIC_ID=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].id")
+  EPIC_ID=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].id" 2>/dev/null) || {
+    echo "  [ERROR] Cannot read epic id for index $EPIC_INDEX — skipping spawn" >&2
+    LAST_SPAWN_PID=0
+    LAST_SPAWN_LOG="/dev/null"
+    return 1
+  }
   local EPIC_TITLE
-  EPIC_TITLE=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].title")
+  EPIC_TITLE=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].title" 2>/dev/null) || EPIC_TITLE="(unknown)"
   local EPIC_JSON
-  EPIC_JSON=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX]")
+  EPIC_JSON=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX]" 2>/dev/null) || {
+    echo "  [ERROR] Cannot read epic JSON for $EPIC_ID — skipping spawn" >&2
+    LAST_SPAWN_PID=0
+    LAST_SPAWN_LOG="/dev/null"
+    return 1
+  }
   local EPIC_PLANNED
-  EPIC_PLANNED=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].planned" "false")
+  EPIC_PLANNED=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].planned" "false" 2>/dev/null) || EPIC_PLANNED="false"
   local PENDING_STORIES_JSON
-  PENDING_STORIES_JSON=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].userStories" | \
-    node -e 'const fs=require("fs"); const stories=JSON.parse(fs.readFileSync(0,"utf8")); process.stdout.write(JSON.stringify(stories.filter(s => s.passes !== true)));')
+  PENDING_STORIES_JSON=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].userStories" 2>/dev/null | \
+    node -e 'const fs=require("fs"); const stories=JSON.parse(fs.readFileSync(0,"utf8")); process.stdout.write(JSON.stringify(stories.filter(s => s.passes !== true)));') || PENDING_STORIES_JSON="[]"
 
   local EPIC_LOG="${LOGS_DIR}/epic-${EPIC_ID}-$(date +%s).log"
 
-  # Create isolated worktree for this epic
+  # Create or reuse the workspace for this epic.
   local WORKTREE_PATH
-  WORKTREE_PATH=$(create_epic_worktree "$EPIC_ID")
+  WORKTREE_PATH=$(prepare_epic_workspace "$EPIC_ID")
   local WORKTREE_ABS_PATH
   WORKTREE_ABS_PATH="$WORKTREE_PATH"
   local EPIC_BRANCH
@@ -1645,11 +1740,30 @@ spawn_epic_bg() {
   if [ -f "$WORKTREE_PLAN_FILE" ]; then
     WORKTREE_PLAN_EXISTS="true"
   fi
+  local MERGE_RESPONSIBILITY
+  MERGE_RESPONSIBILITY=$(cat <<EOF
+ - If all stories pass, this Team Lead session owns the merge attempt before exiting.
+- Loop branch to merge into: ${LOOP_BRANCH}
+- Source epic branch: ${EPIC_BRANCH}
+- Repository root for the merge attempt: ${ROOT_DIR}
+- Write the final merge result artifact to: ${WORKTREE_MERGE_RESULT_FILE}
+- The merge result artifact must be valid JSON with fields: epicId, status, mode, details, timestamp.
+- Allowed status values: merged, merge-failed.
+- Allowed mode values: clean, projected-prd, conflict-resolved, unknown.
+- When all stories pass, do not print DONE until after you have attempted the merge and written the merge result artifact.
+- During the merge attempt you may operate in the repository root path above even though normal implementation work stays inside the epic workspace.
+- If the merge does not complete in this session, Ralph will verify the result and may attempt a scripted fallback merge afterward.
+EOF
+)
 
   init_epic_state_file "$EPIC_ID" "$EPIC_INDEX"
   reset_epic_merge_result_file "$EPIC_ID"
 
-  echo "  Spawning [$EPIC_ID] in worktree $WORKTREE_PATH"
+  if use_dedicated_epic_worktrees; then
+    echo "  Spawning [$EPIC_ID] in worktree $WORKTREE_PATH"
+  else
+    echo "  Spawning [$EPIC_ID] on branch ${EPIC_BRANCH} in loop worktree $WORKTREE_PATH"
+  fi
 
   local TEAM_LEAD_POLICY
   TEAM_LEAD_POLICY="$(cat "$TEAM_LEAD_POLICY_FILE")"
@@ -1703,7 +1817,22 @@ merge_wave() {
   local merge_failures=0
   local target_branch="$LOOP_BRANCH"
 
-  if [ "$(git branch --show-current 2>/dev/null || echo "")" != "$target_branch" ]; then
+  local current_branch=""
+  current_branch=$(git branch --show-current 2>/dev/null || echo "")
+  if [ -n "$current_branch" ] && [ "$current_branch" != "$target_branch" ]; then
+    local current_branch_dirty=""
+    current_branch_dirty=$(git status --porcelain 2>/dev/null || true)
+    if [ -n "$current_branch_dirty" ]; then
+      git add -A
+      unstage_runtime_artifacts
+      if git commit -m "chore: checkpoint ${current_branch} before scripted merge" >/dev/null 2>&1; then
+        echo "  [${current_branch}] Auto-committed dirty branch before scripted merge"
+        echo "[${current_branch}] AUTO-COMMIT before scripted merge — $(date)" >> "$PROGRESS_FILE"
+      fi
+    fi
+  fi
+
+  if [ "$current_branch" != "$target_branch" ]; then
     git checkout "$target_branch" >/dev/null 2>&1
   fi
 
@@ -1743,6 +1872,7 @@ merge_wave() {
       if [ -n "$epic_index" ]; then
         rjq set "$PRD_FILE" ".epics[$epic_index].status" '"completed"'
       fi
+      write_epic_merge_result_file "$epic_id" "merged" "clean" "Scripted merge of ${branch_name} into ${target_branch}"
       echo "  [$epic_id] Merge successful (clean)"
       echo "[$epic_id] MERGED (clean) — $(date)" >> "$PROGRESS_FILE"
     else
@@ -1760,6 +1890,7 @@ merge_wave() {
         echo "[$epic_id] MERGE FAILED (merge did not enter conflict state) — $(date)" >> "$PROGRESS_FILE"
         [ -n "$merge_error" ] && echo "  [$epic_id] Working tree state:" && printf '%s\n' "$merge_error" | sed 's/^/    /'
         merge_failures=$((merge_failures + 1))
+        write_epic_merge_result_file "$epic_id" "merge-failed" "unknown" "Scripted merge did not enter a merge state"
 
         if [ -n "$epic_index" ]; then
           rjq set "$PRD_FILE" ".epics[$epic_index].status" '"merge-failed"'
@@ -1780,6 +1911,7 @@ merge_wave() {
         if [ -n "$epic_index" ]; then
           rjq set "$PRD_FILE" ".epics[$epic_index].status" '"completed"'
         fi
+        write_epic_merge_result_file "$epic_id" "merged" "projected-prd" "Scripted merge kept the projected prd.json from ${target_branch}"
         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
@@ -1787,6 +1919,7 @@ merge_wave() {
       fi
 
       git merge --abort 2>/dev/null || true
+      write_epic_merge_result_file "$epic_id" "merge-failed" "unknown" "Scripted merge left conflicts in: ${conflicted_files}"
       echo "  [$epic_id] Merge FAILED — conflicts remain; leaving ${branch_name} for a later clean retry"
       echo "[$epic_id] MERGE FAILED (conflicts remain, files: ${conflicted_files}) — $(date)" >> "$PROGRESS_FILE"
       merge_failures=$((merge_failures + 1))
@@ -2039,7 +2172,7 @@ WAVE_NUM=0
 # Count total stories across all epics for running estimate calculations
 TOTAL_STORIES=0
 for i in $(seq 0 $((TOTAL_EPICS - 1))); do
-  sc=$(rjq length "$PRD_FILE" ".epics[$i].userStories")
+  sc=$(rjq length "$PRD_FILE" ".epics[$i].userStories" 2>/dev/null) || sc=0
   TOTAL_STORIES=$((TOTAL_STORIES + sc))
 done
 
@@ -2048,20 +2181,20 @@ while true; do
   WAVE_EPICS=()
 
   for EPIC_INDEX in $(seq 0 $((TOTAL_EPICS - 1))); do
-    EPIC_STATUS=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].status" "pending")
+    EPIC_STATUS=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].status" "pending" 2>/dev/null) || EPIC_STATUS="pending"
     [ "$EPIC_STATUS" != "pending" ] && continue
 
     # Check all dependencies
     ALL_DEPS_MET=true
-    DEPS=$(rjq list "$PRD_FILE" ".epics[$EPIC_INDEX].dependsOn")
+    DEPS=$(rjq list "$PRD_FILE" ".epics[$EPIC_INDEX].dependsOn" 2>/dev/null) || DEPS=""
     for DEP in $DEPS; do
-      DEP_STATUS=$(rjq read-where "$PRD_FILE" .epics id "$DEP" status "pending")
+      DEP_STATUS=$(rjq read-where "$PRD_FILE" .epics id "$DEP" status "pending" 2>/dev/null) || DEP_STATUS="pending"
       if [ "$DEP_STATUS" = "failed" ] || [ "$DEP_STATUS" = "partial" ] || [ "$DEP_STATUS" = "merge-failed" ]; then
         # Dependency failed — skip this epic permanently
-        EPIC_ID=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].id")
-        EPIC_TITLE=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].title")
+        EPIC_ID=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].id" 2>/dev/null) || EPIC_ID="EPIC-???"
+        EPIC_TITLE=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].title" 2>/dev/null) || EPIC_TITLE="(unknown)"
         echo "  [$EPIC_ID] $EPIC_TITLE — skipped (dependency $DEP has status: $DEP_STATUS)"
-        rjq set "$PRD_FILE" ".epics[$EPIC_INDEX].status" '"failed"'
+        rjq set "$PRD_FILE" ".epics[$EPIC_INDEX].status" '"failed"' 2>/dev/null || echo "  [WARN] Failed to set epic $EPIC_INDEX status to failed" >&2
         FAILED=$((FAILED + 1))
         echo "[$EPIC_ID] SKIPPED (dependency $DEP failed) — $(date)" >> "$PROGRESS_FILE"
         ALL_DEPS_MET=false
@@ -2089,7 +2222,7 @@ while true; do
   if [ -n "$PARALLEL" ]; then
     echo "  Wave $WAVE_NUM — ${#WAVE_EPICS[@]} epic(s), $PARALLEL at a time"
   else
-    REMAINING_EPICS=$(rjq count-where "$PRD_FILE" .epics "status=pending" --default pending)
+    REMAINING_EPICS=$(rjq count-where "$PRD_FILE" .epics "status=pending" --default pending 2>/dev/null) || REMAINING_EPICS="?"
     echo "  ${REMAINING_EPICS} epic(s) remaining to run sequentially"
   fi
   echo "========================================================"
@@ -2102,7 +2235,7 @@ while true; do
     echo "=== Run — $(date) ===" >> "$PROGRESS_FILE"
   fi
   for IDX in "${WAVE_EPICS[@]}"; do
-    W_EPIC_ID=$(rjq read "$PRD_FILE" ".epics[$IDX].id")
+    W_EPIC_ID=$(rjq read "$PRD_FILE" ".epics[$IDX].id" 2>/dev/null) || W_EPIC_ID="EPIC-???"
     echo "  $W_EPIC_ID" >> "$PROGRESS_FILE"
   done
 
@@ -2166,7 +2299,10 @@ while true; do
       now=$(date +%s)
       for slot in "${!active_pids[@]}"; do
         local finished_epic_id
-        finished_epic_id=$(rjq read "$PRD_FILE" ".epics[${active_indices[$slot]}].id")
+        finished_epic_id=$(rjq read "$PRD_FILE" ".epics[${active_indices[$slot]}].id" 2>/dev/null) || {
+          echo "  [WARN] rjq failed reading epic id for index ${active_indices[$slot]} — skipping slot" >&2
+          continue
+        }
         local process_finished=false
 
         emit_new_log_output "$finished_epic_id" "${active_logs[$slot]}" "${active_log_lines[$slot]:-0}"
@@ -2181,7 +2317,7 @@ while true; do
           wait "${active_pids[$slot]}" 2>/dev/null || true
           # Check progress and retry if possible
           local _to_total _to_state_passed _to_prd_passed _to_passed
-          _to_total=$(rjq length "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories")
+          _to_total=$(rjq length "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories" 2>/dev/null) || _to_total=0
           _to_state_passed=$(read_epic_state_passed "$finished_epic_id")
           _to_prd_passed=$(read_epic_prd_passed "${active_indices[$slot]}")
           _to_passed="$_to_state_passed"
@@ -2193,16 +2329,21 @@ while true; do
             echo "  [$finished_epic_id] Timeout with $_to_passed/$_to_total passed — retry $((_to_retry_count + 1))/$MAX_CRASH_RETRIES"
             echo "[$finished_epic_id] TIMEOUT RETRY $((_to_retry_count + 1))/$MAX_CRASH_RETRIES ($_to_passed/$_to_total passed) — $(date)" >> "$PROGRESS_FILE"
             project_state_to_prd "$finished_epic_id" || true
-            cleanup_epic_worktree "$finished_epic_id"
-            spawn_epic_bg "${active_indices[$slot]}"
-            active_pids[$slot]="$LAST_SPAWN_PID"
-            active_start_times[$slot]="$(date +%s)"
-            active_logs[$slot]="$LAST_SPAWN_LOG"
-            active_log_lines[$slot]="0"
-            continue
+            cleanup_epic_workspace "$finished_epic_id"
+            if spawn_epic_bg "${active_indices[$slot]}"; then
+              active_pids[$slot]="$LAST_SPAWN_PID"
+              active_start_times[$slot]="$(date +%s)"
+              active_logs[$slot]="$LAST_SPAWN_LOG"
+              active_log_lines[$slot]="0"
+              continue
+            fi
+            echo "  [$finished_epic_id] Retry spawn failed — treating as timeout failure" >&2
           fi
           project_state_to_prd "$finished_epic_id" || true
-          cleanup_epic_worktree "$finished_epic_id"
+          cleanup_epic_workspace "$finished_epic_id"
+          if ! use_dedicated_epic_worktrees; then
+            project_state_to_prd "$finished_epic_id" || true
+          fi
           echo "TIMEOUT: Epic exceeded ${EPIC_TIMEOUT}s limit" >> "${active_logs[$slot]}"
           # Log timeout-specific message before generic result
           echo "[$finished_epic_id] FAILED (epic timeout after ${EPIC_TIMEOUT}s) — $(date)" >> "$PROGRESS_FILE"
@@ -2239,7 +2380,7 @@ while true; do
           wait "${active_pids[$slot]}" 2>/dev/null || true
           # Check progress and retry if possible
           local _it_total _it_state_passed _it_prd_passed _it_passed
-          _it_total=$(rjq length "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories")
+          _it_total=$(rjq length "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories" 2>/dev/null) || _it_total=0
           _it_state_passed=$(read_epic_state_passed "$finished_epic_id")
           _it_prd_passed=$(read_epic_prd_passed "${active_indices[$slot]}")
           _it_passed="$_it_state_passed"
@@ -2251,16 +2392,21 @@ while true; do
             echo "  [$finished_epic_id] Idle timeout with $_it_passed/$_it_total passed — retry $((_it_retry_count + 1))/$MAX_CRASH_RETRIES"
             echo "[$finished_epic_id] IDLE RETRY $((_it_retry_count + 1))/$MAX_CRASH_RETRIES ($_it_passed/$_it_total passed) — $(date)" >> "$PROGRESS_FILE"
             project_state_to_prd "$finished_epic_id" || true
-            cleanup_epic_worktree "$finished_epic_id"
-            spawn_epic_bg "${active_indices[$slot]}"
-            active_pids[$slot]="$LAST_SPAWN_PID"
-            active_start_times[$slot]="$(date +%s)"
-            active_logs[$slot]="$LAST_SPAWN_LOG"
-            active_log_lines[$slot]="0"
-            continue
+            cleanup_epic_workspace "$finished_epic_id"
+            if spawn_epic_bg "${active_indices[$slot]}"; then
+              active_pids[$slot]="$LAST_SPAWN_PID"
+              active_start_times[$slot]="$(date +%s)"
+              active_logs[$slot]="$LAST_SPAWN_LOG"
+              active_log_lines[$slot]="0"
+              continue
+            fi
+            echo "  [$finished_epic_id] Retry spawn failed — treating as idle timeout failure" >&2
           fi
           project_state_to_prd "$finished_epic_id" || true
-          cleanup_epic_worktree "$finished_epic_id"
+          cleanup_epic_workspace "$finished_epic_id"
+          if ! use_dedicated_epic_worktrees; then
+            project_state_to_prd "$finished_epic_id" || true
+          fi
           # Log idle-timeout-specific message before generic result
           echo "[$finished_epic_id] FAILED (idle timeout — no output for ${IDLE_TIMEOUT}s) — $(date)" >> "$PROGRESS_FILE"
           process_epic_result "${active_indices[$slot]}"
@@ -2283,7 +2429,7 @@ while true; do
         fi
 
         local total_s passed_s_state passed_s_prd passed_s
-        total_s=$(rjq length "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories")
+        total_s=$(rjq length "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories" 2>/dev/null) || total_s=0
         passed_s_state=$(read_epic_state_passed "$finished_epic_id")
         passed_s_prd=$(read_epic_prd_passed "${active_indices[$slot]}")
         passed_s="$passed_s_state"
@@ -2300,6 +2446,13 @@ while true; do
         if [ "$all_done" = true ] && [ "$merge_recorded" = true ]; then
           epic_flow_complete=true
         fi
+        local process_exit_complete=false
+        if [ "$all_done" = true ]; then
+          # Once all stories pass, accept a normal Team Lead exit even if the
+          # merge result is still missing. Ralph will verify the merge result
+          # and attempt a scripted fallback merge when needed.
+          process_exit_complete=true
+        fi
 
         if [ "$process_finished" = true ] || [ "$epic_flow_complete" = true ]; then
           # Only terminate an in-flight session early after the Team Lead has
@@ -2310,10 +2463,10 @@ while true; do
           fi
           wait "${active_pids[$slot]}" 2>/dev/null || true
 
-          # If the process exited before the epic reached full completion
-          # (stories passed plus merge result recorded), consider it a crash
+          # If the process exited before the Team Lead session reached the
+          # expected completion point for this run mode, consider it a crash
           # and retry when possible.
-          if [ "$epic_flow_complete" = false ]; then
+          if [ "$process_exit_complete" = false ]; then
             local retry_count
             retry_count="$(get_crash_retry_count "$finished_epic_id")"
             if [ "$retry_count" -lt "$MAX_CRASH_RETRIES" ]; then
@@ -2322,14 +2475,16 @@ while true; do
               echo "  [$finished_epic_id] CRASH DETECTED ($passed_s/$total_s passed) — retry $((retry_count + 1))/$MAX_CRASH_RETRIES"
               echo "[$finished_epic_id] CRASH RETRY $((retry_count + 1))/$MAX_CRASH_RETRIES ($passed_s/$total_s passed so far) — $(date)" >> "$PROGRESS_FILE"
               project_state_to_prd "$finished_epic_id" || true
-              cleanup_epic_worktree "$finished_epic_id"
-              spawn_epic_bg "${active_indices[$slot]}"
-              active_pids[$slot]="$LAST_SPAWN_PID"
-              active_start_times[$slot]="$(date +%s)"
-              active_logs[$slot]="$LAST_SPAWN_LOG"
-              active_log_lines[$slot]="0"
-              # Don't free slot — respawned epic reuses it. Continue polling.
-              continue
+              cleanup_epic_workspace "$finished_epic_id"
+              if spawn_epic_bg "${active_indices[$slot]}"; then
+                active_pids[$slot]="$LAST_SPAWN_PID"
+                active_start_times[$slot]="$(date +%s)"
+                active_logs[$slot]="$LAST_SPAWN_LOG"
+                active_log_lines[$slot]="0"
+                # Don't free slot — respawned epic reuses it. Continue polling.
+                continue
+              fi
+              echo "  [$finished_epic_id] Retry spawn failed — treating as crash failure" >&2
             fi
             echo ""
             echo "  [$finished_epic_id] CRASH — retries exhausted ($passed_s/$total_s stories passed)"
@@ -2349,11 +2504,17 @@ while true; do
           process_epic_result "${active_indices[$slot]}"
           # Track completed epics for merge_wave only when the Team Lead did not already merge.
           local post_status
-          post_status=$(rjq read "$PRD_FILE" ".epics[${active_indices[$slot]}].status" "pending")
-          if [ "$post_status" = "completed" ] && [ "$merge_status" != "merged" ]; then
+          post_status=$(rjq read "$PRD_FILE" ".epics[${active_indices[$slot]}].status" "pending" 2>/dev/null) || post_status="pending"
+          if [ "$post_status" = "completed" ] && [ "$merge_status" != "merged" ] && use_dedicated_epic_worktrees; then
             wave_completed_ids+=("$finished_epic_id")
           fi
-          cleanup_epic_worktree "$finished_epic_id"
+
+          if [ "$post_status" = "completed" ] && [ "$merge_status" != "merged" ] && ! use_dedicated_epic_worktrees; then
+            merge_wave "$finished_epic_id" || true
+            merge_status=$(read_epic_merge_result_field "$finished_epic_id" .status "" 2>/dev/null || true)
+          fi
+
+          cleanup_epic_workspace "$finished_epic_id"
           if [ "$merge_status" = "merged" ]; then
             delete_epic_branch "$finished_epic_id"
           fi
@@ -2386,10 +2547,10 @@ while true; do
       break
     fi
 
-    EPIC_STATUS=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].status" "pending")
+    EPIC_STATUS=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].status" "pending" 2>/dev/null) || EPIC_STATUS="pending"
     if [ "$EPIC_STATUS" = "completed" ]; then
-      local_epic_id=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].id")
-      local_epic_title=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].title")
+      local_epic_id=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].id" 2>/dev/null) || local_epic_id="EPIC-???"
+      local_epic_title=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].title" 2>/dev/null) || local_epic_title="(unknown)"
       echo "  [$local_epic_id] $local_epic_title — already completed, skipping"
       COMPLETED=$((COMPLETED + 1))
       continue
@@ -2401,7 +2562,11 @@ while true; do
     done
 
     PROCESSED=$((PROCESSED + 1))
-    spawn_epic_bg "$EPIC_INDEX"
+    if ! spawn_epic_bg "$EPIC_INDEX"; then
+      echo "  [WARN] Failed to spawn epic at index $EPIC_INDEX — skipping" >&2
+      FAILED=$((FAILED + 1))
+      continue
+    fi
     active_pids+=("$LAST_SPAWN_PID")
     active_indices+=("$EPIC_INDEX")
     active_start_times+=("$(date +%s)")
@@ -2417,7 +2582,7 @@ while true; do
 
   # Merge completed epic branches back to starting branch
   if [ ${#wave_completed_ids[@]} -gt 0 ]; then
-    merge_wave "${wave_completed_ids[@]}"
+    merge_wave "${wave_completed_ids[@]}" || true
   fi
 
   # If we hit --max-epics mid-wave, stop processing further waves