ralph-teams 1.0.31 → 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/.claude/agents/final-validator.md

@@ -10,6 +10,8 @@ model: sonnet
 
 You independently validate the final integrated branch after all epic work is complete. Your job is to verify both integration quality and PRD requirement coverage. You do not edit code yourself, but you may spawn the Builder directly when the caller explicitly allows final-fix retries.
 
+Final validation also owns the last check for unresolved merge integration. If the PRD or run context shows `merge-failed` epics and the corresponding leftover epic branches still exist, you should inspect that state explicitly and attempt a clean merge retry before deciding PASS or FAIL.
+
 ## Workflow
 
 1. Read the project and run context provided by the caller.
@@ -18,15 +20,19 @@ You independently validate the final integrated branch after all epic work is co
 4. Run the relevant broad verification commands yourself.
 5. Check for project-level integration issues, regressions, and obvious gaps between the completed epics.
 6. Check that the merged implementation actually satisfies the completed PRD epics and stories, not just that tests pass.
-7. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
-8. Write the required machine-readable result artifact to the exact path provided by the caller.
-9. Report a clear PASS or FAIL verdict with concrete fix items.
+7. Check whether any epics are marked `merge-failed` in `prd.json`.
+8. If a `merge-failed` epic still has a leftover epic branch, inspect it and attempt a clean merge retry yourself when it is safe to do so.
+9. If a merge retry still conflicts or otherwise fails, treat that as a validation failure and report it explicitly.
+10. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
+11. Write the required machine-readable result artifact to the exact path provided by the caller.
+12. Report a clear PASS or FAIL verdict with concrete fix items.
 
 ## Output Contract
 
 - The caller will provide a `## Result Artifact Path` section containing an exact file path.
 - The caller will provide a `## PRD File Path` section. Read that file yourself before deciding the verdict.
 - The caller may provide an `Allowed final-fix retries` value. Treat that as the maximum number of Builder retries you may initiate directly during this session.
+- The caller may also provide loop-branch and repository-root context. Use that information when checking leftover `merge-failed` epic branches.
 - Before exiting, write a JSON file to that exact path.
 - The JSON must include:
   - `phase`: `"final-validation"`
@@ -49,6 +55,7 @@ You independently validate the final integrated branch after all epic work is co
 ### Findings
 - PASS: [area that is verified]
 - FAIL: [specific issue or missing PRD requirement]
+- FAIL: [merge-failed epic still could not be integrated, with branch/conflict summary]
 
 ### Tests: PASS / FAIL
 [summary]
@@ -64,6 +71,8 @@ You independently validate the final integrated branch after all epic work is co
 
 - Never edit code yourself.
 - If you spawn the Builder, keep ownership of the validation decision. The Builder only fixes; you still re-verify and decide PASS or FAIL.
+- If `prd.json` contains `merge-failed` epics, you must treat that as part of final validation scope, not as an unrelated shell concern.
+- You may attempt a clean merge retry for a leftover `merge-failed` epic branch, but do not hand merge-conflict resolution to a fresh Team Lead session from here.
 - Do not exceed the allowed final-fix retry budget from the caller.
 - Focus on whole-run integration, regression risks, and PRD requirement coverage.
 - Fail the validation if the merged result misses or only partially implements required PRD behavior, even when existing tests pass.

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/.codex/agents/final-validator.toml

@@ -7,6 +7,8 @@ developer_instructions = """
 
 You independently validate the final integrated branch after all epic work is complete. Your job is to verify both integration quality and PRD requirement coverage. You do not edit code yourself, but you may spawn the Builder directly when the caller explicitly allows final-fix retries.
 
+Final validation also owns the last check for unresolved merge integration. If the PRD or run context shows `merge-failed` epics and the corresponding leftover epic branches still exist, you should inspect that state explicitly and attempt a clean merge retry before deciding PASS or FAIL.
+
 ## Workflow
 
 1. Read the project and run context provided by the caller.
@@ -15,15 +17,19 @@ You independently validate the final integrated branch after all epic work is co
 4. Run the relevant broad verification commands yourself.
 5. Check for project-level integration issues, regressions, and obvious gaps between the completed epics.
 6. Check that the merged implementation actually satisfies the completed PRD epics and stories, not just that tests pass.
-7. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
-8. Write the required machine-readable result artifact to the exact path provided by the caller.
-9. Report a clear PASS or FAIL verdict with concrete fix items.
+7. Check whether any epics are marked `merge-failed` in `prd.json`.
+8. If a `merge-failed` epic still has a leftover epic branch, inspect it and attempt a clean merge retry yourself when it is safe to do so.
+9. If a merge retry still conflicts or otherwise fails, treat that as a validation failure and report it explicitly.
+10. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
+11. Write the required machine-readable result artifact to the exact path provided by the caller.
+12. Report a clear PASS or FAIL verdict with concrete fix items.
 
 ## Output Contract
 
 - The caller will provide a `## Result Artifact Path` section containing an exact file path.
 - The caller will provide a `## PRD File Path` section. Read that file yourself before deciding the verdict.
 - The caller may provide an `Allowed final-fix retries` value. Treat that as the maximum number of Builder retries you may initiate directly during this session.
+- The caller may also provide loop-branch and repository-root context. Use that information when checking leftover `merge-failed` epic branches.
 - Before exiting, write a JSON file to that exact path.
 - The JSON must include:
   - `phase`: `"final-validation"`
@@ -46,6 +52,7 @@ You independently validate the final integrated branch after all epic work is co
 ### Findings
 - PASS: [area that is verified]
 - FAIL: [specific issue or missing PRD requirement]
+- FAIL: [merge-failed epic still could not be integrated, with branch/conflict summary]
 
 ### Tests: PASS / FAIL
 [summary]
@@ -61,6 +68,8 @@ You independently validate the final integrated branch after all epic work is co
 
 - Never edit code yourself.
 - If you spawn the Builder, keep ownership of the validation decision. The Builder only fixes; you still re-verify and decide PASS or FAIL.
+- If `prd.json` contains `merge-failed` epics, you must treat that as part of final validation scope, not as an unrelated shell concern.
+- You may attempt a clean merge retry for a leftover `merge-failed` epic branch, but do not hand merge-conflict resolution to a fresh Team Lead session from here.
 - Do not exceed the allowed final-fix retry budget from the caller.
 - Focus on whole-run integration, regression risks, and PRD requirement coverage.
 - Fail the validation if the merged result misses or only partially implements required PRD behavior, even when existing tests pass.

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/.github/agents/final-validator.agent.md

@@ -10,6 +10,8 @@ model: gpt-5.3-codex
 
 You independently validate the final integrated branch after all epic work is complete. Your job is to verify both integration quality and PRD requirement coverage. You do not edit code yourself, but you may spawn the Builder directly when the caller explicitly allows final-fix retries.
 
+Final validation also owns the last check for unresolved merge integration. If the PRD or run context shows `merge-failed` epics and the corresponding leftover epic branches still exist, you should inspect that state explicitly and attempt a clean merge retry before deciding PASS or FAIL.
+
 ## Workflow
 
 1. Read the project and run context provided by the caller.
@@ -18,15 +20,19 @@ You independently validate the final integrated branch after all epic work is co
 4. Run the relevant broad verification commands yourself.
 5. Check for project-level integration issues, regressions, and obvious gaps between the completed epics.
 6. Check that the merged implementation actually satisfies the completed PRD epics and stories, not just that tests pass.
-7. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
-8. Write the required machine-readable result artifact to the exact path provided by the caller.
-9. Report a clear PASS or FAIL verdict with concrete fix items.
+7. Check whether any epics are marked `merge-failed` in `prd.json`.
+8. If a `merge-failed` epic still has a leftover epic branch, inspect it and attempt a clean merge retry yourself when it is safe to do so.
+9. If a merge retry still conflicts or otherwise fails, treat that as a validation failure and report it explicitly.
+10. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
+11. Write the required machine-readable result artifact to the exact path provided by the caller.
+12. Report a clear PASS or FAIL verdict with concrete fix items.
 
 ## Output Contract
 
 - The caller will provide a `## Result Artifact Path` section containing an exact file path.
 - The caller will provide a `## PRD File Path` section. Read that file yourself before deciding the verdict.
 - The caller may provide an `Allowed final-fix retries` value. Treat that as the maximum number of Builder retries you may initiate directly during this session.
+- The caller may also provide loop-branch and repository-root context. Use that information when checking leftover `merge-failed` epic branches.
 - Before exiting, write a JSON file to that exact path.
 - The JSON must include:
   - `phase`: `"final-validation"`
@@ -49,6 +55,7 @@ You independently validate the final integrated branch after all epic work is co
 ### Findings
 - PASS: [area that is verified]
 - FAIL: [specific issue or missing PRD requirement]
+- FAIL: [merge-failed epic still could not be integrated, with branch/conflict summary]
 
 ### Tests: PASS / FAIL
 [summary]
@@ -64,6 +71,8 @@ You independently validate the final integrated branch after all epic work is co
 
 - Never edit code yourself.
 - If you spawn the Builder, keep ownership of the validation decision. The Builder only fixes; you still re-verify and decide PASS or FAIL.
+- If `prd.json` contains `merge-failed` epics, you must treat that as part of final validation scope, not as an unrelated shell concern.
+- You may attempt a clean merge retry for a leftover `merge-failed` epic branch, but do not hand merge-conflict resolution to a fresh Team Lead session from here.
 - Do not exceed the allowed final-fix retry budget from the caller.
 - Focus on whole-run integration, regression risks, and PRD requirement coverage.
 - Fail the validation if the merged result misses or only partially implements required PRD behavior, even when existing tests pass.

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/.opencode/agents/final-validator.md

@@ -10,6 +10,8 @@ model: openai/gpt-5.3-codex
 
 You independently validate the final integrated branch after all epic work is complete. Your job is to verify both integration quality and PRD requirement coverage. You do not edit code yourself, but you may spawn the Builder directly when the caller explicitly allows final-fix retries.
 
+Final validation also owns the last check for unresolved merge integration. If the PRD or run context shows `merge-failed` epics and the corresponding leftover epic branches still exist, you should inspect that state explicitly and attempt a clean merge retry before deciding PASS or FAIL.
+
 ## Workflow
 
 1. Read the project and run context provided by the caller.
@@ -18,15 +20,19 @@ You independently validate the final integrated branch after all epic work is co
 4. Run the relevant broad verification commands yourself.
 5. Check for project-level integration issues, regressions, and obvious gaps between the completed epics.
 6. Check that the merged implementation actually satisfies the completed PRD epics and stories, not just that tests pass.
-7. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
-8. Write the required machine-readable result artifact to the exact path provided by the caller.
-9. Report a clear PASS or FAIL verdict with concrete fix items.
+7. Check whether any epics are marked `merge-failed` in `prd.json`.
+8. If a `merge-failed` epic still has a leftover epic branch, inspect it and attempt a clean merge retry yourself when it is safe to do so.
+9. If a merge retry still conflicts or otherwise fails, treat that as a validation failure and report it explicitly.
+10. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
+11. Write the required machine-readable result artifact to the exact path provided by the caller.
+12. Report a clear PASS or FAIL verdict with concrete fix items.
 
 ## Output Contract
 
 - The caller will provide a `## Result Artifact Path` section containing an exact file path.
 - The caller will provide a `## PRD File Path` section. Read that file yourself before deciding the verdict.
 - The caller may provide an `Allowed final-fix retries` value. Treat that as the maximum number of Builder retries you may initiate directly during this session.
+- The caller may also provide loop-branch and repository-root context. Use that information when checking leftover `merge-failed` epic branches.
 - Before exiting, write a JSON file to that exact path.
 - The JSON must include:
   - `phase`: `"final-validation"`
@@ -49,6 +55,7 @@ You independently validate the final integrated branch after all epic work is co
 ### Findings
 - PASS: [area that is verified]
 - FAIL: [specific issue or missing PRD requirement]
+- FAIL: [merge-failed epic still could not be integrated, with branch/conflict summary]
 
 ### Tests: PASS / FAIL
 [summary]
@@ -64,6 +71,8 @@ You independently validate the final integrated branch after all epic work is co
 
 - Never edit code yourself.
 - If you spawn the Builder, keep ownership of the validation decision. The Builder only fixes; you still re-verify and decide PASS or FAIL.
+- If `prd.json` contains `merge-failed` epics, you must treat that as part of final validation scope, not as an unrelated shell concern.
+- You may attempt a clean merge retry for a leftover `merge-failed` epic branch, but do not hand merge-conflict resolution to a fresh Team Lead session from here.
 - Do not exceed the allowed final-fix retry budget from the caller.
 - Focus on whole-run integration, regression risks, and PRD requirement coverage.
 - Fail the validation if the merged result misses or only partially implements required PRD behavior, even when existing tests pass.

package/README.md

@@ -19,6 +19,7 @@ Many spec-driven tools are heavy, burn a lot of tokens, and are harder to adapt
 
 The default `balanced` mode is intentionally simple:
 - the Team Lead orchestrates the epic
+- for clearly easy, low-risk mechanical work, the Team Lead may implement directly
 - it can spawn the epic planner if needed
 - it spawns one Builder per story attempt
 - it validates inline or spawns a validator when independent verification is needed
@@ -43,18 +44,18 @@ 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 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?}
-    G -->|No| J[Merge epic branch]
+    G -->|No| J[Team Lead merges epic branch and writes merge artifact]
     G -->|Yes| H[Run epic validator]
     H -->|PASS| J
     H -->|FAIL and retries left| I[Builder fixes epic-level findings]
     I --> H
-    J --> K[If needed, run merger]
+    J --> K[If needed, fallback merge recovery handles leftovers]
     K --> L{More epics?}
     L -->|Yes| C
     L -->|No| M{2+ epics and final validation enabled?}
@@ -74,7 +75,7 @@ Other presets:
 
 At a high level:
 - `ralph.sh` owns the run loop, worktrees, merges, resume state, and backend process lifecycle.
-- one Team Lead session runs per epic and delegates to planner, builder, validator, and merger roles as needed.
+- one Team Lead session runs per epic and delegates to planner, builder, validator, and merger roles as needed, or implements trivial work directly.
 - `ralph.config.yml` controls backend choice, workflow toggles, parallelism, timeouts, and model selection.
 
 Workflow presets:
@@ -534,6 +535,7 @@ During a run, Ralph writes:
 - `.ralph-teams/progress.txt`: high-level run log
 - `.ralph-teams/.worktrees/EPIC-xxx/`: isolated git worktree for an active epic
 - `.ralph-teams/state/EPIC-xxx.json`: per-epic story pass/fail state (Team Lead reads/writes)
+- `.ralph-teams/state/merge-EPIC-xxx.json`: per-epic merge-result artifact written by the Team Lead or merge recovery path
 - `.ralph-teams/plans/plan-EPIC-xxx.md`: epic-planner output for an epic
 - planned epics are expected to use these files as their implementation contract
 - `.ralph-teams/logs/epic-EPIC-xxx-<timestamp>.log`: raw backend session log
@@ -551,12 +553,12 @@ 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
-- each epic gets its own worktree and branch rooted from that loop branch
-- before the Team Lead starts, Ralph creates the worktree and hands repo inspection, setup, build, and test command inference to the agents
+- 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 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, its branch is merged back into the loop branch
+- 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
 - the backend team processes one epic per session
 - stories run sequentially inside that epic
 - already-passed stories are skipped
@@ -566,8 +568,10 @@ The current execution contract is:
 - a Builder attempt only counts when the Team Lead receives a concrete commit SHA for that story attempt
 - scoped validators check output independently from the builder's reasoning
 - the Team Lead is expected to delegate early and not inspect the codebase beyond the minimum needed before delegation
-- `DONE: X/Y stories passed` is a required session footer, but the durable completion signal is the epic state file updated by the Team Lead
-- after updating the epic state file for all attempted stories, the team lead must print `DONE: X/Y stories passed` and exit the session immediately
+- for clearly easy, low-risk mechanical tasks, the Team Lead may implement directly instead of delegating
+- `DONE: X/Y stories passed` is a required session footer, but it is not enough to complete an epic on its own
+- the durable epic-completion contract is: projected story state plus a valid merge-result artifact
+- if PRD state says an epic is pending but the current loop branch already contains prior merge history for that run-scoped epic branch, Ralph fails fast instead of silently reusing stale history
 - pressing `Ctrl-C` writes `.ralph-teams/ralph-state.json` so the run can be resumed later with `ralph-teams resume`
 
 ## Troubleshooting
@@ -634,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.31",
+  "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/agents/final-validator.md

@@ -8,6 +8,8 @@ title: "Final Validator Agent"
 
 You independently validate the final integrated branch after all epic work is complete. Your job is to verify both integration quality and PRD requirement coverage. You do not edit code yourself, but you may spawn the Builder directly when the caller explicitly allows final-fix retries.
 
+Final validation also owns the last check for unresolved merge integration. If the PRD or run context shows `merge-failed` epics and the corresponding leftover epic branches still exist, you should inspect that state explicitly and attempt a clean merge retry before deciding PASS or FAIL.
+
 ## Workflow
 
 1. Read the project and run context provided by the caller.
@@ -16,15 +18,19 @@ You independently validate the final integrated branch after all epic work is co
 4. Run the relevant broad verification commands yourself.
 5. Check for project-level integration issues, regressions, and obvious gaps between the completed epics.
 6. Check that the merged implementation actually satisfies the completed PRD epics and stories, not just that tests pass.
-7. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
-8. Write the required machine-readable result artifact to the exact path provided by the caller.
-9. Report a clear PASS or FAIL verdict with concrete fix items.
+7. Check whether any epics are marked `merge-failed` in `prd.json`.
+8. If a `merge-failed` epic still has a leftover epic branch, inspect it and attempt a clean merge retry yourself when it is safe to do so.
+9. If a merge retry still conflicts or otherwise fails, treat that as a validation failure and report it explicitly.
+10. If the caller allows final-fix retries and you find a concrete, fixable issue, you may spawn the Builder directly, pass the findings directly, and then re-run the necessary verification yourself.
+11. Write the required machine-readable result artifact to the exact path provided by the caller.
+12. Report a clear PASS or FAIL verdict with concrete fix items.
 
 ## Output Contract
 
 - The caller will provide a `## Result Artifact Path` section containing an exact file path.
 - The caller will provide a `## PRD File Path` section. Read that file yourself before deciding the verdict.
 - The caller may provide an `Allowed final-fix retries` value. Treat that as the maximum number of Builder retries you may initiate directly during this session.
+- The caller may also provide loop-branch and repository-root context. Use that information when checking leftover `merge-failed` epic branches.
 - Before exiting, write a JSON file to that exact path.
 - The JSON must include:
   - `phase`: `"final-validation"`
@@ -47,6 +53,7 @@ You independently validate the final integrated branch after all epic work is co
 ### Findings
 - PASS: [area that is verified]
 - FAIL: [specific issue or missing PRD requirement]
+- FAIL: [merge-failed epic still could not be integrated, with branch/conflict summary]
 
 ### Tests: PASS / FAIL
 [summary]
@@ -62,6 +69,8 @@ You independently validate the final integrated branch after all epic work is co
 
 - Never edit code yourself.
 - If you spawn the Builder, keep ownership of the validation decision. The Builder only fixes; you still re-verify and decide PASS or FAIL.
+- If `prd.json` contains `merge-failed` epics, you must treat that as part of final validation scope, not as an unrelated shell concern.
+- You may attempt a clean merge retry for a leftover `merge-failed` epic branch, but do not hand merge-conflict resolution to a fresh Team Lead session from here.
 - Do not exceed the allowed final-fix retry budget from the caller.
 - Focus on whole-run integration, regression risks, and PRD requirement coverage.
 - Fail the validation if the merged result misses or only partially implements required PRD behavior, even when existing tests pass.

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
     (
@@ -1599,10 +1654,10 @@ spawn_epic_bg() {
   LAST_SPAWN_LOG="$EPIC_LOG"
 }
 
-# merge_wave: fallback merge pass for completed epic branches that were not already
-# merged by their original Team Lead sessions. Takes epic IDs as arguments.
-# Clean merges succeed without AI intervention. On conflict, hands the repo to a
-# tightly-scoped Team Lead takeover. Logs all outcomes to progress.txt.
+# merge_wave: fallback merge pass for epic branches that still exist after
+# their original Team Lead session. Takes epic IDs as arguments.
+# Clean merges succeed without AI intervention. On conflict, Ralph records the
+# merge failure and leaves the branch in place for a later clean retry.
 merge_wave() {
   local -a completed_epic_ids=("$@")
 
@@ -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,90 +1745,25 @@ 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
         continue
       fi
 
-      # Conflicts detected — hand off the current merge state to the Team Lead.
-      echo "  [$epic_id] conflicts detected — team lead takeover..."
-      echo "[$epic_id] merge conflicts — team lead takeover — $(date)" >> "$PROGRESS_FILE"
-
-      local merge_prompt="You are the Team Lead. Take over this merge conflict resolution directly.
-
-## Context
-- Target branch: ${target_branch}
-- Source branch: ${branch_name}
-- Epic ID: ${epic_id}
-
-## Conflicted Files
-${conflicted_files}
-
-## Instructions
-1. Stay in the current repository and operate on the existing in-progress merge state.
-2. Do NOT delegate. Do NOT spawn merger, builder, planner, or validator work.
-3. For each conflicted file listed above, read the full file and inspect the conflict markers.
-4. Run: git log --oneline ${target_branch}..${branch_name} to see what the epic branch changed.
-5. Run: git log --oneline ${branch_name}..${target_branch} to see what changed on the target branch.
-6. Resolve each conflict by combining both sides' intent where possible.
-7. Stage each resolved file with: git add <filename>.
-8. Do NOT commit. ralph.sh will create the merge commit after all conflicts are resolved.
-9. Do NOT run git merge --abort.
-10. If you cannot safely resolve a conflict, leave the conflict markers in place.
-
-When you are finished, print exactly one final line:
-- MERGE_SUCCESS
-- MERGE_FAILED
-
-Begin resolving."
-
-      local merge_log="${LOGS_DIR}/merge-${epic_id}-$(date +%s).log"
-
-      case "$BACKEND" in
-        claude)
-          echo "$merge_prompt" | $AGENT_CMD --agent team-lead --model "$MODEL_TEAM_LEAD" --dangerously-skip-permissions --print --verbose --output-format stream-json > "$merge_log" 2>&1 || true
-          ;;
-        copilot)
-          COPILOT_MERGE_PROMPT="$merge_prompt" \
-            script -q /dev/null /bin/sh -lc 'exec gh copilot -- --agent team-lead --allow-all --no-ask-user --stream on -p "$COPILOT_MERGE_PROMPT"' \
-            > "$merge_log" 2>&1 || true
-          ;;
-        codex)
-          run_codex_exec "$ROOT_DIR" "$merge_prompt" > "$merge_log" 2>&1 || true
-          ;;
-        opencode)
-          run_opencode_exec "$ROOT_DIR" "$merge_prompt" team-lead "$MODEL_TEAM_LEAD" > "$merge_log" 2>&1 || true
-          ;;
-      esac
-
-      # Check for remaining unresolved conflicts
-      local remaining_conflicts
-      remaining_conflicts=$(git diff --name-only --diff-filter=U 2>/dev/null || true)
-
-      # Also check if agent aborted the merge (MERGE_HEAD won't exist)
-      if [ -z "$remaining_conflicts" ] && [ -f ".git/MERGE_HEAD" ]; then
-        # All conflicts resolved — complete the merge commit
-        git commit --no-edit 2>/dev/null || true
-        echo "  [$epic_id] merged (AI-resolved conflicts)"
-        echo "  [$epic_id] Merge log: ${merge_log}"
-        echo "[$epic_id] MERGED (AI-resolved) — $(date)" >> "$PROGRESS_FILE"
-        git branch -d "${branch_name}" 2>/dev/null || true
-      else
-        # AI failed or aborted — ensure clean state
-        git merge --abort 2>/dev/null || true
-        echo "  [$epic_id] Merge FAILED — AI could not resolve conflicts in: ${conflicted_files}"
-        echo "  [$epic_id] Merge log: ${merge_log}"
-        echo "[$epic_id] MERGE FAILED (AI resolution failed, files: ${conflicted_files}) — $(date)" >> "$PROGRESS_FILE"
-        merge_failures=$((merge_failures + 1))
+      git merge --abort 2>/dev/null || true
+      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))
 
-        # Update epic status to merge-failed
-        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
+      if [ -n "$epic_index" ]; then
+        rjq set "$PRD_FILE" ".epics[$epic_index].status" '"merge-failed"'
       fi
+
+      continue
     fi
 
     # Clean up the merged branch
@@ -1786,7 +1779,7 @@ collect_pending_merge_epics() {
   for epic_index in $(seq 0 $((TOTAL_EPICS - 1))); do
     local epic_status
     epic_status=$(rjq read "$PRD_FILE" ".epics[$epic_index].status" "pending")
-    [ "$epic_status" = "completed" ] || continue
+    [ "$epic_status" = "completed" ] || [ "$epic_status" = "merge-failed" ] || continue
 
     local epic_id
     epic_id=$(rjq read "$PRD_FILE" ".epics[$epic_index].id")
@@ -1863,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
 }
@@ -1903,7 +1911,7 @@ read_final_validation_verdict() {
 
 run_final_validation_cycle() {
   [ "$FINAL_VALIDATION_ENABLED" = "1" ] || return 0
-  [ "$COMPLETED" -eq "$TOTAL_EPICS" ] || return 0
+  [ $((COMPLETED + FAILED)) -eq "$TOTAL_EPICS" ] || return 0
   [ "$TOTAL_EPICS" -ge 2 ] || return 0
 
   echo ""
@@ -1971,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
@@ -2375,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 ""