@canivel/ralph 0.2.3 → 0.3.0

package/.agents/ralph/loop.sh

@@ -1,1027 +1,1265 @@
-#!/bin/bash
-# Ralph loop — simple, portable, single-agent
-# Usage:
-#   ./.agents/ralph/loop.sh                 # build mode, default iterations
-#   ./.agents/ralph/loop.sh build           # build mode
-#   ./.agents/ralph/loop.sh prd "request"   # generate PRD via agent
-#   ./.agents/ralph/loop.sh 10              # build mode, 10 iterations
-#   ./.agents/ralph/loop.sh build 1 --no-commit
-
-set -euo pipefail
-
-# Cross-platform Python detection (Windows uses 'python', Unix uses 'python3')
-# On Windows, 'python' may exist as an App Execution Alias that redirects to Microsoft Store
-# We need to actually test if the command works, not just if it exists
-PYTHON_CMD=""
-for py_cmd in python3 python; do
-  if command -v "$py_cmd" >/dev/null 2>&1; then
-    # Test if Python actually runs (catches Windows App Execution Alias issue)
-    if "$py_cmd" --version >/dev/null 2>&1; then
-      PYTHON_CMD="$py_cmd"
-      break
-    fi
-  fi
-done
-
-if [ -z "$PYTHON_CMD" ]; then
-  echo "Error: Python is required but not found or not working."
-  echo "Install Python 3.x and ensure it's in your PATH."
-  echo "On Windows, you may need to disable App Execution Aliases for python in Settings."
-  exit 1
-fi
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ROOT_DIR="$(cd "${RALPH_ROOT:-${SCRIPT_DIR}/../..}" && pwd)"
-CONFIG_FILE="${SCRIPT_DIR}/config.sh"
-
-DEFAULT_PRD_PATH=".agents/tasks/prd.json"
-DEFAULT_PROGRESS_PATH=".ralph/progress.md"
-DEFAULT_AGENTS_PATH="AGENTS.md"
-DEFAULT_PROMPT_BUILD=".agents/ralph/PROMPT_build.md"
-DEFAULT_GUARDRAILS_PATH=".ralph/guardrails.md"
-DEFAULT_ERRORS_LOG_PATH=".ralph/errors.log"
-DEFAULT_ACTIVITY_LOG_PATH=".ralph/activity.log"
-DEFAULT_TMP_DIR=".ralph/.tmp"
-DEFAULT_RUNS_DIR=".ralph/runs"
-DEFAULT_GUARDRAILS_REF=".agents/ralph/references/GUARDRAILS.md"
-DEFAULT_CONTEXT_REF=".agents/ralph/references/CONTEXT_ENGINEERING.md"
-DEFAULT_ACTIVITY_CMD=".agents/ralph/log-activity.sh"
-if [[ -n "${RALPH_ROOT:-}" ]]; then
-  agents_path="$RALPH_ROOT/.agents/ralph/agents.sh"
-else
-  agents_path="$SCRIPT_DIR/agents.sh"
-fi
-if [[ -f "$agents_path" ]]; then
-  # shellcheck source=/dev/null
-  source "$agents_path"
-fi
-
-DEFAULT_MAX_ITERATIONS=25
-DEFAULT_NO_COMMIT=false
-DEFAULT_STALE_SECONDS=0
-PRD_REQUEST_PATH=""
-PRD_INLINE=""
-
-# Optional config overrides (simple shell vars)
-if [ -f "$CONFIG_FILE" ]; then
-  # shellcheck source=/dev/null
-  . "$CONFIG_FILE"
-fi
-
-DEFAULT_AGENT_NAME="${DEFAULT_AGENT:-codex}"
-resolve_agent_cmd() {
-  local name="$1"
-  local interactive="${2:-0}"
-  case "$name" in
-    claude)
-      if [ "$interactive" = "1" ]; then
-        echo "${AGENT_CLAUDE_INTERACTIVE_CMD:-"claude --dangerously-skip-permissions -"}"
-      else
-        echo "${AGENT_CLAUDE_CMD:-"claude --dangerously-skip-permissions -p -"}"
-      fi
-      ;;
-    droid)
-      if [ "$interactive" = "1" ]; then
-        echo "${AGENT_DROID_INTERACTIVE_CMD:-"droid --skip-permissions-unsafe {prompt}"}"
-      else
-        echo "${AGENT_DROID_CMD:-"droid exec --skip-permissions-unsafe -f {prompt}"}"
-      fi
-      ;;
-    codex|"")
-      if [ "$interactive" = "1" ]; then
-        echo "${AGENT_CODEX_INTERACTIVE_CMD:-"codex --yolo {prompt}"}"
-      else
-        echo "${AGENT_CODEX_CMD:-codex exec --yolo --skip-git-repo-check -}"
-      fi
-      ;;
-    opencode)
-      if [ "$interactive" = "1" ]; then
-        echo "${AGENT_OPENCODE_INTERACTIVE_CMD:-"opencode --prompt {prompt}"}"
-      else
-        echo "${AGENT_OPENCODE_CMD:-"opencode run {prompt}"}"
-      fi
-      ;;
-    *)
-      echo "${AGENT_CODEX_CMD:-codex exec --yolo --skip-git-repo-check -}"
-      ;;
-  esac
-}
-DEFAULT_AGENT_CMD="$(resolve_agent_cmd "$DEFAULT_AGENT_NAME" 0)"
-
-PRD_PATH="${PRD_PATH:-$DEFAULT_PRD_PATH}"
-PROGRESS_PATH="${PROGRESS_PATH:-$DEFAULT_PROGRESS_PATH}"
-AGENTS_PATH="${AGENTS_PATH:-$DEFAULT_AGENTS_PATH}"
-PROMPT_BUILD="${PROMPT_BUILD:-$DEFAULT_PROMPT_BUILD}"
-GUARDRAILS_PATH="${GUARDRAILS_PATH:-$DEFAULT_GUARDRAILS_PATH}"
-ERRORS_LOG_PATH="${ERRORS_LOG_PATH:-$DEFAULT_ERRORS_LOG_PATH}"
-ACTIVITY_LOG_PATH="${ACTIVITY_LOG_PATH:-$DEFAULT_ACTIVITY_LOG_PATH}"
-TMP_DIR="${TMP_DIR:-$DEFAULT_TMP_DIR}"
-RUNS_DIR="${RUNS_DIR:-$DEFAULT_RUNS_DIR}"
-GUARDRAILS_REF="${GUARDRAILS_REF:-$DEFAULT_GUARDRAILS_REF}"
-CONTEXT_REF="${CONTEXT_REF:-$DEFAULT_CONTEXT_REF}"
-ACTIVITY_CMD="${ACTIVITY_CMD:-$DEFAULT_ACTIVITY_CMD}"
-AGENT_CMD="${AGENT_CMD:-$DEFAULT_AGENT_CMD}"
-MAX_ITERATIONS="${MAX_ITERATIONS:-$DEFAULT_MAX_ITERATIONS}"
-NO_COMMIT="${NO_COMMIT:-$DEFAULT_NO_COMMIT}"
-STALE_SECONDS="${STALE_SECONDS:-$DEFAULT_STALE_SECONDS}"
-
-abs_path() {
-  local p="$1"
-  # Check for Unix absolute path (starts with /) or Windows absolute path (contains :)
-  if [[ "$p" = /* ]] || [[ "$p" == *:* ]]; then
-    echo "$p"
-  else
-    echo "$ROOT_DIR/$p"
-  fi
-}
-
-PRD_PATH="$(abs_path "$PRD_PATH")"
-PROGRESS_PATH="$(abs_path "$PROGRESS_PATH")"
-AGENTS_PATH="$(abs_path "$AGENTS_PATH")"
-PROMPT_BUILD="$(abs_path "$PROMPT_BUILD")"
-GUARDRAILS_PATH="$(abs_path "$GUARDRAILS_PATH")"
-ERRORS_LOG_PATH="$(abs_path "$ERRORS_LOG_PATH")"
-ACTIVITY_LOG_PATH="$(abs_path "$ACTIVITY_LOG_PATH")"
-TMP_DIR="$(abs_path "$TMP_DIR")"
-RUNS_DIR="$(abs_path "$RUNS_DIR")"
-GUARDRAILS_REF="$(abs_path "$GUARDRAILS_REF")"
-CONTEXT_REF="$(abs_path "$CONTEXT_REF")"
-ACTIVITY_CMD="$(abs_path "$ACTIVITY_CMD")"
-
-require_agent() {
-  local agent_cmd="${1:-$AGENT_CMD}"
-  local agent_bin
-  agent_bin="${agent_cmd%% *}"
-  if [ -z "$agent_bin" ]; then
-    echo "AGENT_CMD is empty. Set it in config.sh."
-    exit 1
-  fi
-  if ! command -v "$agent_bin" >/dev/null 2>&1; then
-    echo "Agent command not found: $agent_bin"
-    case "$agent_bin" in
-      codex)
-        echo "Install: npm i -g @openai/codex"
-        ;;
-      claude)
-        echo "Install: curl -fsSL https://claude.ai/install.sh | bash"
-        ;;
-      droid)
-        echo "Install: curl -fsSL https://app.factory.ai/cli | sh"
-        ;;
-      opencode)
-        echo "Install: curl -fsSL https://opencode.ai/install.sh | bash"
-        ;;
-    esac
-    echo "Then authenticate per the CLI's instructions."
-    exit 1
-  fi
-}
-
-run_agent() {
-  local prompt_file="$1"
-  if [[ "$AGENT_CMD" == *"{prompt}"* ]]; then
-    local escaped
-    escaped=$(printf '%q' "$prompt_file")
-    local cmd="${AGENT_CMD//\{prompt\}/$escaped}"
-    eval "$cmd"
-  else
-    cat "$prompt_file" | eval "$AGENT_CMD"
-  fi
-}
-
-run_agent_inline() {
-  local prompt_file="$1"
-  local prompt_content
-  prompt_content="$(cat "$prompt_file")"
-  local escaped
-  escaped=$(printf "%s" "$prompt_content" | sed "s/'/'\\\\''/g")
-  local cmd="${PRD_AGENT_CMD:-$AGENT_CMD}"
-  if [[ "$cmd" == *"{prompt}"* ]]; then
-    cmd="${cmd//\{prompt\}/'$escaped'}"
-  else
-    cmd="$cmd '$escaped'"
-  fi
-  eval "$cmd"
-}
-
-MODE="build"
-while [ $# -gt 0 ]; do
-  case "$1" in
-    build|prd)
-      MODE="$1"
-      shift
-      ;;
-    --prompt)
-      PRD_REQUEST_PATH="$2"
-      shift 2
-      ;;
-    --no-commit)
-      NO_COMMIT=true
-      shift
-      ;;
-    *)
-      if [ "$MODE" = "prd" ]; then
-        PRD_INLINE="${PRD_INLINE:+$PRD_INLINE }$1"
-        shift
-      elif [[ "$1" =~ ^[0-9]+$ ]]; then
-        MAX_ITERATIONS="$1"
-        shift
-      else
-        echo "Unknown arg: $1"
-        exit 1
-      fi
-      ;;
-  esac
-done
-
-PROMPT_FILE="$PROMPT_BUILD"
-
-if [ "$MODE" = "prd" ]; then
-  # For PRD mode, use interactive agent command (file-based with {prompt} placeholder)
-  if [ -z "${PRD_AGENT_CMD:-}" ]; then
-    PRD_AGENT_CMD="$(resolve_agent_cmd "$DEFAULT_AGENT_NAME" 1)"
-  fi
-  if [ "${RALPH_DRY_RUN:-}" != "1" ]; then
-    require_agent "${PRD_AGENT_CMD}"
-  fi
-
-  if [[ "$PRD_PATH" == *.json ]]; then
-    mkdir -p "$(dirname "$PRD_PATH")" "$TMP_DIR"
-  else
-    mkdir -p "$PRD_PATH" "$TMP_DIR"
-  fi
-
-  if [ -z "$PRD_REQUEST_PATH" ] && [ -n "$PRD_INLINE" ]; then
-    PRD_REQUEST_PATH="$TMP_DIR/prd-request-$(date +%Y%m%d-%H%M%S)-$$.txt"
-    printf '%s\n' "$PRD_INLINE" > "$PRD_REQUEST_PATH"
-  fi
-
-  if [ -z "$PRD_REQUEST_PATH" ] || [ ! -f "$PRD_REQUEST_PATH" ]; then
-    echo "PRD request missing. Provide a prompt string or --prompt <file>."
-    exit 1
-  fi
-
-  if [ "${RALPH_DRY_RUN:-}" = "1" ]; then
-    if [[ "$PRD_PATH" == *.json ]]; then
-      if [ ! -f "$PRD_PATH" ]; then
-        {
-          echo '{'
-          echo '  "version": 1,'
-          echo '  "project": "ralph",'
-          echo '  "qualityGates": [],'
-          echo '  "stories": []'
-          echo '}'
-        } > "$PRD_PATH"
-      fi
-    fi
-    exit 0
-  fi
-
-  PRD_PROMPT_FILE="$TMP_DIR/prd-prompt-$(date +%Y%m%d-%H%M%S)-$$.md"
-  # Look for prd skill in project skills or ralph bundled skills
-  PRD_SKILL_FILE=""
-  for skill_path in "$ROOT_DIR/.claude/skills/prd/SKILL.md" "$ROOT_DIR/skills/prd/SKILL.md" "$SCRIPT_DIR/../skills/prd/SKILL.md"; do
-    if [[ -f "$skill_path" ]]; then
-      PRD_SKILL_FILE="$skill_path"
-      break
-    fi
-  done
-  # Also check ralph's bundled skills directory
-  if [[ -z "$PRD_SKILL_FILE" ]]; then
-    ralph_skills_dir="$(cd "$SCRIPT_DIR/../.." 2>/dev/null && pwd)/skills/prd/SKILL.md"
-    if [[ -f "$ralph_skills_dir" ]]; then
-      PRD_SKILL_FILE="$ralph_skills_dir"
-    fi
-  fi
-  {
-    echo "You are an autonomous coding agent."
-    echo ""
-    # Include the PRD skill instructions if available
-    if [[ -n "$PRD_SKILL_FILE" && -f "$PRD_SKILL_FILE" ]]; then
-      cat "$PRD_SKILL_FILE"
-      echo ""
-      echo "---"
-      echo ""
-    fi
-    echo "# Output Requirements"
-    echo ""
-    if [[ "$PRD_PATH" == *.json ]]; then
-      echo "Save the PRD JSON to: $PRD_PATH"
-    else
-      echo "Save the PRD as JSON in directory: $PRD_PATH"
-      echo "Filename rules: prd-<short-slug>.json using 1-3 meaningful words."
-      echo "Examples: prd-workout-tracker.json, prd-usage-billing.json"
-    fi
-    echo ""
-    echo "Do NOT implement anything. Only generate the JSON PRD file."
-    echo ""
-    echo "After saving the PRD, end your response with:"
-    echo "PRD JSON saved to <path>. Close this chat and run \`ralph build\`."
-    echo ""
-    echo "---"
-    echo ""
-    echo "# User Request"
-    echo ""
-    cat "$PRD_REQUEST_PATH"
-  } > "$PRD_PROMPT_FILE"
-
-  # Use PRD_AGENT_CMD for the agent call (always file-based for PRD mode)
-  AGENT_CMD="$PRD_AGENT_CMD"
-  run_agent "$PRD_PROMPT_FILE"
-  exit 0
-fi
-
-if [ "${RALPH_DRY_RUN:-}" != "1" ]; then
-  require_agent
-fi
-
-if [ ! -f "$PROMPT_FILE" ]; then
-  echo "Prompt not found: $PROMPT_FILE"
-  exit 1
-fi
-
-if [ "$MODE" != "prd" ] && [ ! -f "$PRD_PATH" ]; then
-  echo "PRD not found: $PRD_PATH"
-  exit 1
-fi
-
-mkdir -p "$(dirname "$PROGRESS_PATH")" "$TMP_DIR" "$RUNS_DIR"
-
-if [ ! -f "$PROGRESS_PATH" ]; then
-  {
-    echo "# Progress Log"
-    echo "Started: $(date)"
-    echo ""
-    echo "## Codebase Patterns"
-    echo "- (add reusable patterns here)"
-    echo ""
-    echo "---"
-  } > "$PROGRESS_PATH"
-fi
-
-if [ ! -f "$GUARDRAILS_PATH" ]; then
-  {
-    echo "# Guardrails (Signs)"
-    echo ""
-    echo "> Lessons learned from failures. Read before acting."
-    echo ""
-    echo "## Core Signs"
-    echo ""
-    echo "### Sign: Read Before Writing"
-    echo "- **Trigger**: Before modifying any file"
-    echo "- **Instruction**: Read the file first"
-    echo "- **Added after**: Core principle"
-    echo ""
-    echo "### Sign: Test Before Commit"
-    echo "- **Trigger**: Before committing changes"
-    echo "- **Instruction**: Run required tests and verify outputs"
-    echo "- **Added after**: Core principle"
-    echo ""
-    echo "---"
-    echo ""
-    echo "## Learned Signs"
-    echo ""
-  } > "$GUARDRAILS_PATH"
-fi
-
-if [ ! -f "$ERRORS_LOG_PATH" ]; then
-  {
-    echo "# Error Log"
-    echo ""
-    echo "> Failures and repeated issues. Use this to add guardrails."
-    echo ""
-  } > "$ERRORS_LOG_PATH"
-fi
-
-if [ ! -f "$ACTIVITY_LOG_PATH" ]; then
-  {
-    echo "# Activity Log"
-    echo ""
-    echo "## Run Summary"
-    echo ""
-    echo "## Events"
-    echo ""
-  } > "$ACTIVITY_LOG_PATH"
-fi
-
-RUN_TAG="$(date +%Y%m%d-%H%M%S)-$$"
-
-render_prompt() {
-  local src="$1"
-  local dst="$2"
-  local story_meta="$3"
-  local story_block="$4"
-  local run_id="$5"
-  local iter="$6"
-  local run_log="$7"
-  local run_meta="$8"
-  $PYTHON_CMD - "$src" "$dst" "$PRD_PATH" "$AGENTS_PATH" "$PROGRESS_PATH" "$ROOT_DIR" "$GUARDRAILS_PATH" "$ERRORS_LOG_PATH" "$ACTIVITY_LOG_PATH" "$GUARDRAILS_REF" "$CONTEXT_REF" "$ACTIVITY_CMD" "$NO_COMMIT" "$story_meta" "$story_block" "$run_id" "$iter" "$run_log" "$run_meta" <<'PY'
-import sys
-from pathlib import Path
-
-src = Path(sys.argv[1]).read_text()
-prd, agents, progress, root = sys.argv[3:7]
-guardrails = sys.argv[7]
-errors_log = sys.argv[8]
-activity_log = sys.argv[9]
-guardrails_ref = sys.argv[10]
-context_ref = sys.argv[11]
-activity_cmd = sys.argv[12]
-no_commit = sys.argv[13]
-meta_path = sys.argv[14] if len(sys.argv) > 14 else ""
-block_path = sys.argv[15] if len(sys.argv) > 15 else ""
-run_id = sys.argv[16] if len(sys.argv) > 16 else ""
-iteration = sys.argv[17] if len(sys.argv) > 17 else ""
-run_log = sys.argv[18] if len(sys.argv) > 18 else ""
-run_meta = sys.argv[19] if len(sys.argv) > 19 else ""
-repl = {
-    "PRD_PATH": prd,
-    "AGENTS_PATH": agents,
-    "PROGRESS_PATH": progress,
-    "REPO_ROOT": root,
-    "GUARDRAILS_PATH": guardrails,
-    "ERRORS_LOG_PATH": errors_log,
-    "ACTIVITY_LOG_PATH": activity_log,
-    "GUARDRAILS_REF": guardrails_ref,
-    "CONTEXT_REF": context_ref,
-    "ACTIVITY_CMD": activity_cmd,
-    "NO_COMMIT": no_commit,
-    "RUN_ID": run_id,
-    "ITERATION": iteration,
-    "RUN_LOG_PATH": run_log,
-    "RUN_META_PATH": run_meta,
-}
-story = {"id": "", "title": "", "block": ""}
-quality_gates = []
-if meta_path:
-    try:
-        import json
-        meta = json.loads(Path(meta_path).read_text())
-        story["id"] = meta.get("id", "") or ""
-        story["title"] = meta.get("title", "") or ""
-        quality_gates = meta.get("quality_gates", []) or []
-    except Exception:
-        pass
-if block_path and Path(block_path).exists():
-    story["block"] = Path(block_path).read_text()
-repl["STORY_ID"] = story["id"]
-repl["STORY_TITLE"] = story["title"]
-repl["STORY_BLOCK"] = story["block"]
-if quality_gates:
-    repl["QUALITY_GATES"] = "\n".join([f"- {g}" for g in quality_gates])
-else:
-    repl["QUALITY_GATES"] = "- (none)"
-for k, v in repl.items():
-    src = src.replace("{{" + k + "}}", v)
-Path(sys.argv[2]).write_text(src)
-PY
-}
-
-select_story() {
-  local meta_out="$1"
-  local block_out="$2"
-  $PYTHON_CMD - "$PRD_PATH" "$meta_out" "$block_out" "$STALE_SECONDS" <<'PY'
-import json
-import os
-import sys
-from pathlib import Path
-from datetime import datetime, timezone
-try:
-    import fcntl
-except Exception:
-    fcntl = None
-
-prd_path = Path(sys.argv[1])
-meta_out = Path(sys.argv[2])
-block_out = Path(sys.argv[3])
-stale_seconds = 0
-if len(sys.argv) > 4:
-    try:
-        stale_seconds = int(sys.argv[4])
-    except Exception:
-        stale_seconds = 0
-
-if not prd_path.exists():
-    meta_out.write_text(json.dumps({"ok": False, "error": "PRD not found"}, indent=2) + "\n")
-    block_out.write_text("")
-    sys.exit(0)
-
-def normalize_status(value):
-    if value is None:
-        return "open"
-    return str(value).strip().lower()
-
-def parse_ts(value):
-    if not value:
-        return None
-    text = str(value).strip()
-    if text.endswith("Z"):
-        text = text[:-1] + "+00:00"
-    try:
-        return datetime.fromisoformat(text)
-    except Exception:
-        return None
-
-def now_iso():
-    return datetime.now(timezone.utc).isoformat()
-
-with prd_path.open("r+", encoding="utf-8") as fh:
-    if fcntl is not None:
-        fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
-    try:
-        try:
-            data = json.load(fh)
-        except Exception as exc:
-            meta_out.write_text(json.dumps({"ok": False, "error": f"Invalid PRD JSON: {exc}"}, indent=2) + "\n")
-            block_out.write_text("")
-            sys.exit(0)
-
-        stories = data.get("stories") if isinstance(data, dict) else None
-        if not isinstance(stories, list) or not stories:
-            meta_out.write_text(json.dumps({"ok": False, "error": "No stories found in PRD"}, indent=2) + "\n")
-            block_out.write_text("")
-            sys.exit(0)
-
-        story_index = {s.get("id"): s for s in stories if isinstance(s, dict)}
-
-        def is_done(story_id: str) -> bool:
-            target = story_index.get(story_id)
-            if not isinstance(target, dict):
-                return False
-            return normalize_status(target.get("status")) == "done"
-
-        if stale_seconds > 0:
-            now = datetime.now(timezone.utc)
-            for story in stories:
-                if not isinstance(story, dict):
-                    continue
-                if normalize_status(story.get("status")) != "in_progress":
-                    continue
-                started = parse_ts(story.get("startedAt"))
-                if started is None or (now - started).total_seconds() > stale_seconds:
-                    story["status"] = "open"
-                    story["startedAt"] = None
-                    story["completedAt"] = None
-                    story["updatedAt"] = now_iso()
-
-        candidate = None
-        for story in stories:
-            if not isinstance(story, dict):
-                continue
-            if normalize_status(story.get("status")) != "open":
-                continue
-            deps = story.get("dependsOn") or []
-            if not isinstance(deps, list):
-                deps = []
-            if all(is_done(dep) for dep in deps):
-                candidate = story
-                break
-
-        remaining = sum(
-            1 for story in stories
-            if isinstance(story, dict) and normalize_status(story.get("status")) != "done"
-        )
-
-        meta = {
-            "ok": True,
-            "total": len(stories),
-            "remaining": remaining,
-            "quality_gates": data.get("qualityGates", []) or [],
-        }
-
-        if candidate:
-            candidate["status"] = "in_progress"
-            if not candidate.get("startedAt"):
-                candidate["startedAt"] = now_iso()
-            candidate["completedAt"] = None
-            candidate["updatedAt"] = now_iso()
-            meta.update({
-                "id": candidate.get("id", ""),
-                "title": candidate.get("title", ""),
-            })
-
-            depends = candidate.get("dependsOn") or []
-            if not isinstance(depends, list):
-                depends = []
-            acceptance = candidate.get("acceptanceCriteria") or []
-            if not isinstance(acceptance, list):
-                acceptance = []
-
-            description = candidate.get("description") or ""
-            block_lines = []
-            block_lines.append(f"### {candidate.get('id', '')}: {candidate.get('title', '')}")
-            block_lines.append(f"Status: {candidate.get('status', 'open')}")
-            block_lines.append(
-                f"Depends on: {', '.join(depends) if depends else 'None'}"
-            )
-            block_lines.append("")
-            block_lines.append("Description:")
-            block_lines.append(description if description else "(none)")
-            block_lines.append("")
-            block_lines.append("Acceptance Criteria:")
-            if acceptance:
-                block_lines.extend([f"- [ ] {item}" for item in acceptance])
-            else:
-                block_lines.append("- (none)")
-            block_out.write_text("\n".join(block_lines).rstrip() + "\n")
-        else:
-            block_out.write_text("")
-
-        fh.seek(0)
-        fh.truncate()
-        json.dump(data, fh, indent=2)
-        fh.write("\n")
-        fh.flush()
-        os.fsync(fh.fileno())
-    finally:
-        if fcntl is not None:
-            fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
-
-meta_out.write_text(json.dumps(meta, indent=2) + "\n")
-PY
-}
-
-remaining_stories() {
-  local meta_file="$1"
-  $PYTHON_CMD - "$meta_file" <<'PY'
-import json
-import sys
-from pathlib import Path
-
-data = json.loads(Path(sys.argv[1]).read_text())
-print(data.get("remaining", "unknown"))
-PY
-}
-
-remaining_from_prd() {
-  $PYTHON_CMD - "$PRD_PATH" <<'PY'
-import json
-import sys
-from pathlib import Path
-
-prd_path = Path(sys.argv[1])
-if not prd_path.exists():
-    print("unknown")
-    sys.exit(0)
-
-try:
-    data = json.loads(prd_path.read_text())
-except Exception:
-    print("unknown")
-    sys.exit(0)
-
-stories = data.get("stories") if isinstance(data, dict) else None
-if not isinstance(stories, list):
-    print("unknown")
-    sys.exit(0)
-
-def normalize_status(value):
-    if value is None:
-        return "open"
-    return str(value).strip().lower()
-
-remaining = sum(
-    1 for story in stories
-    if isinstance(story, dict) and normalize_status(story.get("status")) != "done"
-)
-print(remaining)
-PY
-}
-
-story_field() {
-  local meta_file="$1"
-  local field="$2"
-  $PYTHON_CMD - "$meta_file" "$field" <<'PY'
-import json
-import sys
-from pathlib import Path
-
-data = json.loads(Path(sys.argv[1]).read_text())
-field = sys.argv[2]
-print(data.get(field, ""))
-PY
-}
-
-update_story_status() {
-  local story_id="$1"
-  local new_status="$2"
-  $PYTHON_CMD - "$PRD_PATH" "$story_id" "$new_status" <<'PY'
-import json
-import os
-import sys
-from pathlib import Path
-from datetime import datetime, timezone
-try:
-    import fcntl
-except Exception:
-    fcntl = None
-
-prd_path = Path(sys.argv[1])
-story_id = sys.argv[2]
-new_status = sys.argv[3]
-
-if not story_id:
-    sys.exit(0)
-
-if not prd_path.exists():
-    sys.exit(0)
-
-def now_iso():
-    return datetime.now(timezone.utc).isoformat()
-
-with prd_path.open("r+", encoding="utf-8") as fh:
-    if fcntl is not None:
-        fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
-    try:
-        data = json.load(fh)
-        stories = data.get("stories") if isinstance(data, dict) else None
-        if not isinstance(stories, list):
-            sys.exit(0)
-        for story in stories:
-            if isinstance(story, dict) and story.get("id") == story_id:
-                story["status"] = new_status
-                story["updatedAt"] = now_iso()
-                if new_status == "in_progress":
-                    if not story.get("startedAt"):
-                        story["startedAt"] = now_iso()
-                    story["completedAt"] = None
-                elif new_status == "done":
-                    story["completedAt"] = now_iso()
-                    if not story.get("startedAt"):
-                        story["startedAt"] = now_iso()
-                elif new_status == "open":
-                    story["startedAt"] = None
-                    story["completedAt"] = None
-                break
-        fh.seek(0)
-        fh.truncate()
-        json.dump(data, fh, indent=2)
-        fh.write("\n")
-        fh.flush()
-        os.fsync(fh.fileno())
-    finally:
-        if fcntl is not None:
-            fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
-PY
-}
-
-log_activity() {
-  local message="$1"
-  local timestamp
-  timestamp=$(date '+%Y-%m-%d %H:%M:%S')
-  echo "[$timestamp] $message" >> "$ACTIVITY_LOG_PATH"
-}
-
-log_error() {
-  local message="$1"
-  local timestamp
-  timestamp=$(date '+%Y-%m-%d %H:%M:%S')
-  echo "[$timestamp] $message" >> "$ERRORS_LOG_PATH"
-}
-
-append_run_summary() {
-  local line="$1"
-  $PYTHON_CMD - "$ACTIVITY_LOG_PATH" "$line" <<'PY'
-import sys
-from pathlib import Path
-
-path = Path(sys.argv[1])
-line = sys.argv[2]
-text = path.read_text().splitlines()
-out = []
-inserted = False
-for l in text:
-    out.append(l)
-    if not inserted and l.strip() == "## Run Summary":
-        out.append(f"- {line}")
-        inserted = True
-if not inserted:
-    out = [
-        "# Activity Log",
-        "",
-        "## Run Summary",
-        f"- {line}",
-        "",
-        "## Events",
-        "",
-    ] + text
-Path(path).write_text("\n".join(out).rstrip() + "\n")
-PY
-}
-
-write_run_meta() {
-  local path="$1"
-  local mode="$2"
-  local iter="$3"
-  local run_id="$4"
-  local story_id="$5"
-  local story_title="$6"
-  local started="$7"
-  local ended="$8"
-  local duration="$9"
-  local status="${10}"
-  local log_file="${11}"
-  local head_before="${12}"
-  local head_after="${13}"
-  local commit_list="${14}"
-  local changed_files="${15}"
-  local dirty_files="${16}"
-  {
-    echo "# Ralph Run Summary"
-    echo ""
-    echo "- Run ID: $run_id"
-    echo "- Iteration: $iter"
-    echo "- Mode: $mode"
-    if [ -n "$story_id" ]; then
-      echo "- Story: $story_id: $story_title"
-    fi
-    echo "- Started: $started"
-    echo "- Ended: $ended"
-    echo "- Duration: ${duration}s"
-    echo "- Status: $status"
-    echo "- Log: $log_file"
-    echo ""
-    echo "## Git"
-    echo "- Head (before): ${head_before:-unknown}"
-    echo "- Head (after): ${head_after:-unknown}"
-    echo ""
-    echo "### Commits"
-    if [ -n "$commit_list" ]; then
-      echo "$commit_list"
-    else
-      echo "- (none)"
-    fi
-    echo ""
-    echo "### Changed Files (commits)"
-    if [ -n "$changed_files" ]; then
-      echo "$changed_files"
-    else
-      echo "- (none)"
-    fi
-    echo ""
-    echo "### Uncommitted Changes"
-    if [ -n "$dirty_files" ]; then
-      echo "$dirty_files"
-    else
-      echo "- (clean)"
-    fi
-    echo ""
-  } > "$path"
-}
-
-git_head() {
-  if git -C "$ROOT_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-    git -C "$ROOT_DIR" rev-parse HEAD 2>/dev/null || true
-  else
-    echo ""
-  fi
-}
-
-git_commit_list() {
-  local before="$1"
-  local after="$2"
-  if [ -n "$before" ] && [ -n "$after" ] && [ "$before" != "$after" ]; then
-    git -C "$ROOT_DIR" log --oneline "$before..$after" | sed 's/^/- /'
-  else
-    echo ""
-  fi
-}
-
-git_changed_files() {
-  local before="$1"
-  local after="$2"
-  if [ -n "$before" ] && [ -n "$after" ] && [ "$before" != "$after" ]; then
-    git -C "$ROOT_DIR" diff --name-only "$before" "$after" | sed 's/^/- /'
-  else
-    echo ""
-  fi
-}
-
-git_dirty_files() {
-  if git -C "$ROOT_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-    git -C "$ROOT_DIR" status --porcelain | awk '{print "- " $2}'
-  else
-    echo ""
-  fi
-}
-
-echo "Ralph mode: $MODE"
-echo "Max iterations: $MAX_ITERATIONS"
-echo "PRD: $PRD_PATH"
-HAS_ERROR="false"
-
-for i in $(seq 1 "$MAX_ITERATIONS"); do
-  echo ""
-  echo "═══════════════════════════════════════════════════════"
-  echo "  Ralph Iteration $i of $MAX_ITERATIONS"
-  echo "═══════════════════════════════════════════════════════"
-
-  STORY_META=""
-  STORY_BLOCK=""
-  ITER_START=$(date +%s)
-  ITER_START_FMT=$(date '+%Y-%m-%d %H:%M:%S')
-  if [ "$MODE" = "build" ]; then
-    STORY_META="$TMP_DIR/story-$RUN_TAG-$i.json"
-    STORY_BLOCK="$TMP_DIR/story-$RUN_TAG-$i.md"
-    select_story "$STORY_META" "$STORY_BLOCK"
-    REMAINING="$(remaining_stories "$STORY_META")"
-    if [ "$REMAINING" = "unknown" ]; then
-      echo "Could not parse stories from PRD: $PRD_PATH"
-      exit 1
-    fi
-    if [ "$REMAINING" = "0" ]; then
-      echo "No remaining stories."
-      exit 0
-    fi
-    STORY_ID="$(story_field "$STORY_META" "id")"
-    STORY_TITLE="$(story_field "$STORY_META" "title")"
-    if [ -z "$STORY_ID" ]; then
-      echo "No actionable open stories (all blocked or in progress). Remaining: $REMAINING"
-      exit 0
-    fi
-  fi
-
-  HEAD_BEFORE="$(git_head)"
-  PROMPT_RENDERED="$TMP_DIR/prompt-$RUN_TAG-$i.md"
-  LOG_FILE="$RUNS_DIR/run-$RUN_TAG-iter-$i.log"
-  RUN_META="$RUNS_DIR/run-$RUN_TAG-iter-$i.md"
-  render_prompt "$PROMPT_FILE" "$PROMPT_RENDERED" "$STORY_META" "$STORY_BLOCK" "$RUN_TAG" "$i" "$LOG_FILE" "$RUN_META"
-
-  if [ "$MODE" = "build" ] && [ -n "${STORY_ID:-}" ]; then
-    log_activity "ITERATION $i start (mode=$MODE story=$STORY_ID)"
-  else
-    log_activity "ITERATION $i start (mode=$MODE)"
-  fi
-  set +e
-  if [ "${RALPH_DRY_RUN:-}" = "1" ]; then
-    echo "[RALPH_DRY_RUN] Skipping agent execution." | tee "$LOG_FILE"
-    CMD_STATUS=0
-  else
-    # Run agent - capture output to log file while displaying to terminal
-    # Note: On some systems, piping through tee can cause buffering issues
-    # with interactive CLIs like Claude. If you see no output, the agent
-    # is still running - check the log file for captured output.
-    run_agent "$PROMPT_RENDERED" 2>&1 | tee "$LOG_FILE"
-    CMD_STATUS=${PIPESTATUS[0]}
-  fi
-  set -e
-  if [ "$CMD_STATUS" -eq 130 ] || [ "$CMD_STATUS" -eq 143 ]; then
-    echo "Interrupted."
-    exit "$CMD_STATUS"
-  fi
-  ITER_END=$(date +%s)
-  ITER_END_FMT=$(date '+%Y-%m-%d %H:%M:%S')
-  ITER_DURATION=$((ITER_END - ITER_START))
-  HEAD_AFTER="$(git_head)"
-  log_activity "ITERATION $i end (duration=${ITER_DURATION}s)"
-  if [ "$CMD_STATUS" -ne 0 ]; then
-    log_error "ITERATION $i command failed (status=$CMD_STATUS)"
-    HAS_ERROR="true"
-  fi
-  COMMIT_LIST="$(git_commit_list "$HEAD_BEFORE" "$HEAD_AFTER")"
-  CHANGED_FILES="$(git_changed_files "$HEAD_BEFORE" "$HEAD_AFTER")"
-  DIRTY_FILES="$(git_dirty_files)"
-  STATUS_LABEL="success"
-  if [ "$CMD_STATUS" -ne 0 ]; then
-    STATUS_LABEL="error"
-  fi
-  if [ "$MODE" = "build" ] && [ "$NO_COMMIT" = "false" ] && [ -n "$DIRTY_FILES" ]; then
-    log_error "ITERATION $i left uncommitted changes; review run summary at $RUN_META"
-  fi
-  write_run_meta "$RUN_META" "$MODE" "$i" "$RUN_TAG" "${STORY_ID:-}" "${STORY_TITLE:-}" "$ITER_START_FMT" "$ITER_END_FMT" "$ITER_DURATION" "$STATUS_LABEL" "$LOG_FILE" "$HEAD_BEFORE" "$HEAD_AFTER" "$COMMIT_LIST" "$CHANGED_FILES" "$DIRTY_FILES"
-  if [ "$MODE" = "build" ] && [ -n "${STORY_ID:-}" ]; then
-    append_run_summary "$(date '+%Y-%m-%d %H:%M:%S') | run=$RUN_TAG | iter=$i | mode=$MODE | story=$STORY_ID | duration=${ITER_DURATION}s | status=$STATUS_LABEL"
-  else
-    append_run_summary "$(date '+%Y-%m-%d %H:%M:%S') | run=$RUN_TAG | iter=$i | mode=$MODE | duration=${ITER_DURATION}s | status=$STATUS_LABEL"
-  fi
-
-  if [ "$MODE" = "build" ]; then
-    if [ "$CMD_STATUS" -ne 0 ]; then
-      log_error "ITERATION $i exited non-zero; review $LOG_FILE"
-      update_story_status "$STORY_ID" "open"
-      echo "Iteration failed; story reset to open."
-    elif grep -q "<promise>COMPLETE</promise>" "$LOG_FILE"; then
-      update_story_status "$STORY_ID" "done"
-      echo "Completion signal received; story marked done."
-    else
-      update_story_status "$STORY_ID" "open"
-      echo "No completion signal; story reset to open."
-    fi
-    REMAINING="$(remaining_from_prd)"
-    echo "Iteration $i complete. Remaining stories: $REMAINING"
-    if [ "$REMAINING" = "0" ]; then
-      echo "No remaining stories."
-      exit 0
-    fi
-  else
-    echo "Iteration $i complete."
-  fi
-  sleep 2
-
-done
-
-echo "Reached max iterations ($MAX_ITERATIONS)."
-if [ "$HAS_ERROR" = "true" ]; then
-  exit 1
-fi
-exit 0
+#!/bin/bash
+# Ralph loop — simple, portable, single-agent
+# Usage:
+#   ./.agents/ralph/loop.sh                 # build mode, default iterations
+#   ./.agents/ralph/loop.sh build           # build mode
+#   ./.agents/ralph/loop.sh prd "request"   # generate PRD via agent
+#   ./.agents/ralph/loop.sh 10              # build mode, 10 iterations
+#   ./.agents/ralph/loop.sh build 1 --no-commit
+
+set -euo pipefail
+
+# Cross-platform Python detection (Windows uses 'python', Unix uses 'python3')
+# On Windows, 'python' may exist as an App Execution Alias that redirects to Microsoft Store
+# We need to actually test if the command works, not just if it exists
+PYTHON_CMD=""
+for py_cmd in python3 python; do
+  if command -v "$py_cmd" >/dev/null 2>&1; then
+    # Test if Python actually runs (catches Windows App Execution Alias issue)
+    if "$py_cmd" --version >/dev/null 2>&1; then
+      PYTHON_CMD="$py_cmd"
+      break
+    fi
+  fi
+done
+
+if [ -z "$PYTHON_CMD" ]; then
+  echo "Error: Python is required but not found or not working."
+  echo "Install Python 3.x and ensure it's in your PATH."
+  echo "On Windows, you may need to disable App Execution Aliases for python in Settings."
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${RALPH_ROOT:-${SCRIPT_DIR}/../..}" && pwd)"
+CONFIG_FILE="${SCRIPT_DIR}/config.sh"
+
+DEFAULT_PRD_PATH=".agents/tasks/prd.json"
+DEFAULT_PROGRESS_PATH=".ralph/progress.md"
+DEFAULT_AGENTS_PATH="AGENTS.md"
+DEFAULT_PROMPT_BUILD=".agents/ralph/PROMPT_build.md"
+DEFAULT_GUARDRAILS_PATH=".ralph/guardrails.md"
+DEFAULT_ERRORS_LOG_PATH=".ralph/errors.log"
+DEFAULT_ACTIVITY_LOG_PATH=".ralph/activity.log"
+DEFAULT_TMP_DIR=".ralph/.tmp"
+DEFAULT_RUNS_DIR=".ralph/runs"
+DEFAULT_GUARDRAILS_REF=".agents/ralph/references/GUARDRAILS.md"
+DEFAULT_CONTEXT_REF=".agents/ralph/references/CONTEXT_ENGINEERING.md"
+DEFAULT_ACTIVITY_CMD=".agents/ralph/log-activity.sh"
+if [[ -n "${RALPH_ROOT:-}" ]]; then
+  agents_path="$RALPH_ROOT/.agents/ralph/agents.sh"
+else
+  agents_path="$SCRIPT_DIR/agents.sh"
+fi
+if [[ -f "$agents_path" ]]; then
+  # shellcheck source=/dev/null
+  source "$agents_path"
+fi
+
+DEFAULT_MAX_ITERATIONS=25
+DEFAULT_NO_COMMIT=false
+DEFAULT_STALE_SECONDS=0
+DEFAULT_MAX_RETRIES=3
+DEFAULT_RETRY_DELAY=10
+DEFAULT_MAX_STORY_FAILURES=3
+PRD_REQUEST_PATH=""
+PRD_INLINE=""
+
+# Optional config overrides (simple shell vars)
+if [ -f "$CONFIG_FILE" ]; then
+  # shellcheck source=/dev/null
+  . "$CONFIG_FILE"
+fi
+
+DEFAULT_AGENT_NAME="${DEFAULT_AGENT:-codex}"
+resolve_agent_cmd() {
+  local name="$1"
+  local interactive="${2:-0}"
+  case "$name" in
+    claude)
+      if [ "$interactive" = "1" ]; then
+        echo "${AGENT_CLAUDE_INTERACTIVE_CMD:-"claude --dangerously-skip-permissions -"}"
+      else
+        echo "${AGENT_CLAUDE_CMD:-"claude --dangerously-skip-permissions -p -"}"
+      fi
+      ;;
+    droid)
+      if [ "$interactive" = "1" ]; then
+        echo "${AGENT_DROID_INTERACTIVE_CMD:-"droid --skip-permissions-unsafe {prompt}"}"
+      else
+        echo "${AGENT_DROID_CMD:-"droid exec --skip-permissions-unsafe -f {prompt}"}"
+      fi
+      ;;
+    codex|"")
+      if [ "$interactive" = "1" ]; then
+        echo "${AGENT_CODEX_INTERACTIVE_CMD:-"codex --yolo {prompt}"}"
+      else
+        echo "${AGENT_CODEX_CMD:-codex exec --yolo --skip-git-repo-check -}"
+      fi
+      ;;
+    opencode)
+      if [ "$interactive" = "1" ]; then
+        echo "${AGENT_OPENCODE_INTERACTIVE_CMD:-"opencode --prompt {prompt}"}"
+      else
+        echo "${AGENT_OPENCODE_CMD:-"opencode run {prompt}"}"
+      fi
+      ;;
+    *)
+      echo "${AGENT_CODEX_CMD:-codex exec --yolo --skip-git-repo-check -}"
+      ;;
+  esac
+}
+DEFAULT_AGENT_CMD="$(resolve_agent_cmd "$DEFAULT_AGENT_NAME" 0)"
+
+PRD_PATH="${PRD_PATH:-$DEFAULT_PRD_PATH}"
+PROGRESS_PATH="${PROGRESS_PATH:-$DEFAULT_PROGRESS_PATH}"
+AGENTS_PATH="${AGENTS_PATH:-$DEFAULT_AGENTS_PATH}"
+PROMPT_BUILD="${PROMPT_BUILD:-$DEFAULT_PROMPT_BUILD}"
+GUARDRAILS_PATH="${GUARDRAILS_PATH:-$DEFAULT_GUARDRAILS_PATH}"
+ERRORS_LOG_PATH="${ERRORS_LOG_PATH:-$DEFAULT_ERRORS_LOG_PATH}"
+ACTIVITY_LOG_PATH="${ACTIVITY_LOG_PATH:-$DEFAULT_ACTIVITY_LOG_PATH}"
+TMP_DIR="${TMP_DIR:-$DEFAULT_TMP_DIR}"
+RUNS_DIR="${RUNS_DIR:-$DEFAULT_RUNS_DIR}"
+GUARDRAILS_REF="${GUARDRAILS_REF:-$DEFAULT_GUARDRAILS_REF}"
+CONTEXT_REF="${CONTEXT_REF:-$DEFAULT_CONTEXT_REF}"
+ACTIVITY_CMD="${ACTIVITY_CMD:-$DEFAULT_ACTIVITY_CMD}"
+AGENT_CMD="${AGENT_CMD:-$DEFAULT_AGENT_CMD}"
+MAX_ITERATIONS="${MAX_ITERATIONS:-$DEFAULT_MAX_ITERATIONS}"
+NO_COMMIT="${NO_COMMIT:-$DEFAULT_NO_COMMIT}"
+STALE_SECONDS="${STALE_SECONDS:-$DEFAULT_STALE_SECONDS}"
+MAX_RETRIES="${MAX_RETRIES:-$DEFAULT_MAX_RETRIES}"
+RETRY_DELAY="${RETRY_DELAY:-$DEFAULT_RETRY_DELAY}"
+MAX_STORY_FAILURES="${MAX_STORY_FAILURES:-$DEFAULT_MAX_STORY_FAILURES}"
+
+abs_path() {
+  local p="$1"
+  # Check for Unix absolute path (starts with /) or Windows absolute path (contains :)
+  if [[ "$p" = /* ]] || [[ "$p" == *:* ]]; then
+    echo "$p"
+  else
+    echo "$ROOT_DIR/$p"
+  fi
+}
+
+PRD_PATH="$(abs_path "$PRD_PATH")"
+PROGRESS_PATH="$(abs_path "$PROGRESS_PATH")"
+AGENTS_PATH="$(abs_path "$AGENTS_PATH")"
+PROMPT_BUILD="$(abs_path "$PROMPT_BUILD")"
+GUARDRAILS_PATH="$(abs_path "$GUARDRAILS_PATH")"
+ERRORS_LOG_PATH="$(abs_path "$ERRORS_LOG_PATH")"
+ACTIVITY_LOG_PATH="$(abs_path "$ACTIVITY_LOG_PATH")"
+TMP_DIR="$(abs_path "$TMP_DIR")"
+RUNS_DIR="$(abs_path "$RUNS_DIR")"
+GUARDRAILS_REF="$(abs_path "$GUARDRAILS_REF")"
+CONTEXT_REF="$(abs_path "$CONTEXT_REF")"
+ACTIVITY_CMD="$(abs_path "$ACTIVITY_CMD")"
+
+require_agent() {
+  local agent_cmd="${1:-$AGENT_CMD}"
+  local agent_bin
+  agent_bin="${agent_cmd%% *}"
+  if [ -z "$agent_bin" ]; then
+    echo "AGENT_CMD is empty. Set it in config.sh."
+    exit 1
+  fi
+  if ! command -v "$agent_bin" >/dev/null 2>&1; then
+    echo "Agent command not found: $agent_bin"
+    case "$agent_bin" in
+      codex)
+        echo "Install: npm i -g @openai/codex"
+        ;;
+      claude)
+        echo "Install: curl -fsSL https://claude.ai/install.sh | bash"
+        ;;
+      droid)
+        echo "Install: curl -fsSL https://app.factory.ai/cli | sh"
+        ;;
+      opencode)
+        echo "Install: curl -fsSL https://opencode.ai/install.sh | bash"
+        ;;
+    esac
+    echo "Then authenticate per the CLI's instructions."
+    exit 1
+  fi
+}
+
+run_agent() {
+  local prompt_file="$1"
+  if [[ "$AGENT_CMD" == *"{prompt}"* ]]; then
+    local escaped
+    escaped=$(printf '%q' "$prompt_file")
+    local cmd="${AGENT_CMD//\{prompt\}/$escaped}"
+    eval "$cmd"
+  else
+    cat "$prompt_file" | eval "$AGENT_CMD"
+  fi
+}
+
+run_agent_inline() {
+  local prompt_file="$1"
+  local prompt_content
+  prompt_content="$(cat "$prompt_file")"
+  local escaped
+  escaped=$(printf "%s" "$prompt_content" | sed "s/'/'\\\\''/g")
+  local cmd="${PRD_AGENT_CMD:-$AGENT_CMD}"
+  if [[ "$cmd" == *"{prompt}"* ]]; then
+    cmd="${cmd//\{prompt\}/'$escaped'}"
+  else
+    cmd="$cmd '$escaped'"
+  fi
+  eval "$cmd"
+}
+
+MODE="build"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    build|prd)
+      MODE="$1"
+      shift
+      ;;
+    --prompt)
+      PRD_REQUEST_PATH="$2"
+      shift 2
+      ;;
+    --no-commit)
+      NO_COMMIT=true
+      shift
+      ;;
+    *)
+      if [ "$MODE" = "prd" ]; then
+        PRD_INLINE="${PRD_INLINE:+$PRD_INLINE }$1"
+        shift
+      elif [[ "$1" =~ ^[0-9]+$ ]]; then
+        MAX_ITERATIONS="$1"
+        shift
+      else
+        echo "Unknown arg: $1"
+        exit 1
+      fi
+      ;;
+  esac
+done
+
+PROMPT_FILE="$PROMPT_BUILD"
+
+if [ "$MODE" = "prd" ]; then
+  # For PRD mode, use interactive agent command (file-based with {prompt} placeholder)
+  if [ -z "${PRD_AGENT_CMD:-}" ]; then
+    PRD_AGENT_CMD="$(resolve_agent_cmd "$DEFAULT_AGENT_NAME" 1)"
+  fi
+  if [ "${RALPH_DRY_RUN:-}" != "1" ]; then
+    require_agent "${PRD_AGENT_CMD}"
+  fi
+
+  if [[ "$PRD_PATH" == *.json ]]; then
+    mkdir -p "$(dirname "$PRD_PATH")" "$TMP_DIR"
+  else
+    mkdir -p "$PRD_PATH" "$TMP_DIR"
+  fi
+
+  if [ -z "$PRD_REQUEST_PATH" ] && [ -n "$PRD_INLINE" ]; then
+    PRD_REQUEST_PATH="$TMP_DIR/prd-request-$(date +%Y%m%d-%H%M%S)-$$.txt"
+    printf '%s\n' "$PRD_INLINE" > "$PRD_REQUEST_PATH"
+  fi
+
+  if [ -z "$PRD_REQUEST_PATH" ] || [ ! -f "$PRD_REQUEST_PATH" ]; then
+    echo "PRD request missing. Provide a prompt string or --prompt <file>."
+    exit 1
+  fi
+
+  if [ "${RALPH_DRY_RUN:-}" = "1" ]; then
+    if [[ "$PRD_PATH" == *.json ]]; then
+      if [ ! -f "$PRD_PATH" ]; then
+        {
+          echo '{'
+          echo '  "version": 1,'
+          echo '  "project": "ralph",'
+          echo '  "qualityGates": [],'
+          echo '  "stories": []'
+          echo '}'
+        } > "$PRD_PATH"
+      fi
+    fi
+    exit 0
+  fi
+
+  PRD_PROMPT_FILE="$TMP_DIR/prd-prompt-$(date +%Y%m%d-%H%M%S)-$$.md"
+  # Look for prd skill in project skills or ralph bundled skills
+  PRD_SKILL_FILE=""
+  for skill_path in "$ROOT_DIR/.claude/skills/prd/SKILL.md" "$ROOT_DIR/skills/prd/SKILL.md" "$SCRIPT_DIR/../skills/prd/SKILL.md"; do
+    if [[ -f "$skill_path" ]]; then
+      PRD_SKILL_FILE="$skill_path"
+      break
+    fi
+  done
+  # Also check ralph's bundled skills directory
+  if [[ -z "$PRD_SKILL_FILE" ]]; then
+    ralph_skills_dir="$(cd "$SCRIPT_DIR/../.." 2>/dev/null && pwd)/skills/prd/SKILL.md"
+    if [[ -f "$ralph_skills_dir" ]]; then
+      PRD_SKILL_FILE="$ralph_skills_dir"
+    fi
+  fi
+  {
+    echo "You are an autonomous coding agent."
+    echo ""
+    # Include the PRD skill instructions if available
+    if [[ -n "$PRD_SKILL_FILE" && -f "$PRD_SKILL_FILE" ]]; then
+      cat "$PRD_SKILL_FILE"
+      echo ""
+      echo "---"
+      echo ""
+    fi
+    echo "# Output Requirements"
+    echo ""
+    if [[ "$PRD_PATH" == *.json ]]; then
+      echo "Save the PRD JSON to: $PRD_PATH"
+    else
+      echo "Save the PRD as JSON in directory: $PRD_PATH"
+      echo "Filename rules: prd-<short-slug>.json using 1-3 meaningful words."
+      echo "Examples: prd-workout-tracker.json, prd-usage-billing.json"
+    fi
+    echo ""
+    echo "Do NOT implement anything. Only generate the JSON PRD file."
+    echo ""
+    echo "After saving the PRD, end your response with:"
+    echo "PRD JSON saved to <path>. Close this chat and run \`ralph build\`."
+    echo ""
+    echo "---"
+    echo ""
+    echo "# User Request"
+    echo ""
+    cat "$PRD_REQUEST_PATH"
+  } > "$PRD_PROMPT_FILE"
+
+  # Use PRD_AGENT_CMD for the agent call (always file-based for PRD mode)
+  AGENT_CMD="$PRD_AGENT_CMD"
+  run_agent "$PRD_PROMPT_FILE"
+  exit 0
+fi
+
+if [ "${RALPH_DRY_RUN:-}" != "1" ]; then
+  require_agent
+fi
+
+if [ ! -f "$PROMPT_FILE" ]; then
+  echo "Prompt not found: $PROMPT_FILE"
+  exit 1
+fi
+
+if [ "$MODE" != "prd" ] && [ ! -f "$PRD_PATH" ]; then
+  echo "PRD not found: $PRD_PATH"
+  exit 1
+fi
+
+mkdir -p "$(dirname "$PROGRESS_PATH")" "$TMP_DIR" "$RUNS_DIR"
+
+if [ ! -f "$PROGRESS_PATH" ]; then
+  {
+    echo "# Progress Log"
+    echo "Started: $(date)"
+    echo ""
+    echo "## Codebase Patterns"
+    echo "- (add reusable patterns here)"
+    echo ""
+    echo "---"
+  } > "$PROGRESS_PATH"
+fi
+
+if [ ! -f "$GUARDRAILS_PATH" ]; then
+  {
+    echo "# Guardrails (Signs)"
+    echo ""
+    echo "> Lessons learned from failures. Read before acting."
+    echo ""
+    echo "## Core Signs"
+    echo ""
+    echo "### Sign: Read Before Writing"
+    echo "- **Trigger**: Before modifying any file"
+    echo "- **Instruction**: Read the file first"
+    echo "- **Added after**: Core principle"
+    echo ""
+    echo "### Sign: Test Before Commit"
+    echo "- **Trigger**: Before committing changes"
+    echo "- **Instruction**: Run required tests and verify outputs"
+    echo "- **Added after**: Core principle"
+    echo ""
+    echo "---"
+    echo ""
+    echo "## Learned Signs"
+    echo ""
+  } > "$GUARDRAILS_PATH"
+fi
+
+if [ ! -f "$ERRORS_LOG_PATH" ]; then
+  {
+    echo "# Error Log"
+    echo ""
+    echo "> Failures and repeated issues. Use this to add guardrails."
+    echo ""
+  } > "$ERRORS_LOG_PATH"
+fi
+
+if [ ! -f "$ACTIVITY_LOG_PATH" ]; then
+  {
+    echo "# Activity Log"
+    echo ""
+    echo "## Run Summary"
+    echo ""
+    echo "## Events"
+    echo ""
+  } > "$ACTIVITY_LOG_PATH"
+fi
+
+RUN_TAG="$(date +%Y%m%d-%H%M%S)-$$"
+
+render_prompt() {
+  local src="$1"
+  local dst="$2"
+  local story_meta="$3"
+  local story_block="$4"
+  local run_id="$5"
+  local iter="$6"
+  local run_log="$7"
+  local run_meta="$8"
+  $PYTHON_CMD - "$src" "$dst" "$PRD_PATH" "$AGENTS_PATH" "$PROGRESS_PATH" "$ROOT_DIR" "$GUARDRAILS_PATH" "$ERRORS_LOG_PATH" "$ACTIVITY_LOG_PATH" "$GUARDRAILS_REF" "$CONTEXT_REF" "$ACTIVITY_CMD" "$NO_COMMIT" "$story_meta" "$story_block" "$run_id" "$iter" "$run_log" "$run_meta" "$RUNS_DIR" <<'PY'
+import sys
+from pathlib import Path
+
+src = Path(sys.argv[1]).read_text()
+prd, agents, progress, root = sys.argv[3:7]
+guardrails = sys.argv[7]
+errors_log = sys.argv[8]
+activity_log = sys.argv[9]
+guardrails_ref = sys.argv[10]
+context_ref = sys.argv[11]
+activity_cmd = sys.argv[12]
+no_commit = sys.argv[13]
+meta_path = sys.argv[14] if len(sys.argv) > 14 else ""
+block_path = sys.argv[15] if len(sys.argv) > 15 else ""
+run_id = sys.argv[16] if len(sys.argv) > 16 else ""
+iteration = sys.argv[17] if len(sys.argv) > 17 else ""
+run_log = sys.argv[18] if len(sys.argv) > 18 else ""
+run_meta = sys.argv[19] if len(sys.argv) > 19 else ""
+runs_dir = sys.argv[20] if len(sys.argv) > 20 else ""
+repl = {
+    "PRD_PATH": prd,
+    "AGENTS_PATH": agents,
+    "PROGRESS_PATH": progress,
+    "REPO_ROOT": root,
+    "GUARDRAILS_PATH": guardrails,
+    "ERRORS_LOG_PATH": errors_log,
+    "ACTIVITY_LOG_PATH": activity_log,
+    "GUARDRAILS_REF": guardrails_ref,
+    "CONTEXT_REF": context_ref,
+    "ACTIVITY_CMD": activity_cmd,
+    "NO_COMMIT": no_commit,
+    "RUN_ID": run_id,
+    "ITERATION": iteration,
+    "RUN_LOG_PATH": run_log,
+    "RUN_META_PATH": run_meta,
+    "RUNS_DIR": runs_dir,
+}
+story = {"id": "", "title": "", "block": ""}
+quality_gates = []
+if meta_path:
+    try:
+        import json
+        meta = json.loads(Path(meta_path).read_text())
+        story["id"] = meta.get("id", "") or ""
+        story["title"] = meta.get("title", "") or ""
+        quality_gates = meta.get("quality_gates", []) or []
+    except Exception:
+        pass
+if block_path and Path(block_path).exists():
+    story["block"] = Path(block_path).read_text()
+repl["STORY_ID"] = story["id"]
+repl["STORY_TITLE"] = story["title"]
+repl["STORY_BLOCK"] = story["block"]
+if quality_gates:
+    repl["QUALITY_GATES"] = "\n".join([f"- {g}" for g in quality_gates])
+else:
+    repl["QUALITY_GATES"] = "- (none)"
+for k, v in repl.items():
+    src = src.replace("{{" + k + "}}", v)
+Path(sys.argv[2]).write_text(src)
+PY
+}
+
+select_story() {
+  local meta_out="$1"
+  local block_out="$2"
+  $PYTHON_CMD - "$PRD_PATH" "$meta_out" "$block_out" "$STALE_SECONDS" <<'PY'
+import json
+import os
+import sys
+from pathlib import Path
+from datetime import datetime, timezone
+try:
+    import fcntl
+except Exception:
+    fcntl = None
+
+prd_path = Path(sys.argv[1])
+meta_out = Path(sys.argv[2])
+block_out = Path(sys.argv[3])
+stale_seconds = 0
+if len(sys.argv) > 4:
+    try:
+        stale_seconds = int(sys.argv[4])
+    except Exception:
+        stale_seconds = 0
+
+if not prd_path.exists():
+    meta_out.write_text(json.dumps({"ok": False, "error": "PRD not found"}, indent=2) + "\n")
+    block_out.write_text("")
+    sys.exit(0)
+
+def normalize_status(value):
+    if value is None:
+        return "open"
+    return str(value).strip().lower()
+
+def parse_ts(value):
+    if not value:
+        return None
+    text = str(value).strip()
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    try:
+        return datetime.fromisoformat(text)
+    except Exception:
+        return None
+
+def now_iso():
+    return datetime.now(timezone.utc).isoformat()
+
+with prd_path.open("r+", encoding="utf-8") as fh:
+    if fcntl is not None:
+        fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+    try:
+        try:
+            data = json.load(fh)
+        except Exception as exc:
+            meta_out.write_text(json.dumps({"ok": False, "error": f"Invalid PRD JSON: {exc}"}, indent=2) + "\n")
+            block_out.write_text("")
+            sys.exit(0)
+
+        stories = data.get("stories") if isinstance(data, dict) else None
+        if not isinstance(stories, list) or not stories:
+            meta_out.write_text(json.dumps({"ok": False, "error": "No stories found in PRD"}, indent=2) + "\n")
+            block_out.write_text("")
+            sys.exit(0)
+
+        story_index = {s.get("id"): s for s in stories if isinstance(s, dict)}
+
+        def is_done(story_id: str) -> bool:
+            target = story_index.get(story_id)
+            if not isinstance(target, dict):
+                return False
+            return normalize_status(target.get("status")) == "done"
+
+        if stale_seconds > 0:
+            now = datetime.now(timezone.utc)
+            for story in stories:
+                if not isinstance(story, dict):
+                    continue
+                if normalize_status(story.get("status")) != "in_progress":
+                    continue
+                started = parse_ts(story.get("startedAt"))
+                if started is None or (now - started).total_seconds() > stale_seconds:
+                    story["status"] = "open"
+                    story["startedAt"] = None
+                    story["completedAt"] = None
+                    story["updatedAt"] = now_iso()
+
+        candidate = None
+        for story in stories:
+            if not isinstance(story, dict):
+                continue
+            if normalize_status(story.get("status")) != "open":
+                continue
+            deps = story.get("dependsOn") or []
+            if not isinstance(deps, list):
+                deps = []
+            if all(is_done(dep) for dep in deps):
+                candidate = story
+                break
+
+        # Count remaining stories (excluding done and blocked)
+        remaining = sum(
+            1 for story in stories
+            if isinstance(story, dict) and normalize_status(story.get("status")) not in ("done", "blocked")
+        )
+
+        meta = {
+            "ok": True,
+            "total": len(stories),
+            "remaining": remaining,
+            "quality_gates": data.get("qualityGates", []) or [],
+        }
+
+        if candidate:
+            candidate["status"] = "in_progress"
+            if not candidate.get("startedAt"):
+                candidate["startedAt"] = now_iso()
+            candidate["completedAt"] = None
+            candidate["updatedAt"] = now_iso()
+            meta.update({
+                "id": candidate.get("id", ""),
+                "title": candidate.get("title", ""),
+            })
+
+            depends = candidate.get("dependsOn") or []
+            if not isinstance(depends, list):
+                depends = []
+            acceptance = candidate.get("acceptanceCriteria") or []
+            if not isinstance(acceptance, list):
+                acceptance = []
+
+            description = candidate.get("description") or ""
+            block_lines = []
+            block_lines.append(f"### {candidate.get('id', '')}: {candidate.get('title', '')}")
+            block_lines.append(f"Status: {candidate.get('status', 'open')}")
+            block_lines.append(
+                f"Depends on: {', '.join(depends) if depends else 'None'}"
+            )
+            block_lines.append("")
+            block_lines.append("Description:")
+            block_lines.append(description if description else "(none)")
+            block_lines.append("")
+            block_lines.append("Acceptance Criteria:")
+            if acceptance:
+                block_lines.extend([f"- [ ] {item}" for item in acceptance])
+            else:
+                block_lines.append("- (none)")
+            block_out.write_text("\n".join(block_lines).rstrip() + "\n")
+        else:
+            block_out.write_text("")
+
+        fh.seek(0)
+        fh.truncate()
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+        fh.flush()
+        os.fsync(fh.fileno())
+    finally:
+        if fcntl is not None:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+
+meta_out.write_text(json.dumps(meta, indent=2) + "\n")
+PY
+}
+
+remaining_stories() {
+  local meta_file="$1"
+  $PYTHON_CMD - "$meta_file" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+data = json.loads(Path(sys.argv[1]).read_text())
+print(data.get("remaining", "unknown"))
+PY
+}
+
+remaining_from_prd() {
+  $PYTHON_CMD - "$PRD_PATH" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+prd_path = Path(sys.argv[1])
+if not prd_path.exists():
+    print("unknown")
+    sys.exit(0)
+
+try:
+    data = json.loads(prd_path.read_text())
+except Exception:
+    print("unknown")
+    sys.exit(0)
+
+stories = data.get("stories") if isinstance(data, dict) else None
+if not isinstance(stories, list):
+    print("unknown")
+    sys.exit(0)
+
+def normalize_status(value):
+    if value is None:
+        return "open"
+    return str(value).strip().lower()
+
+# Count remaining stories (excluding done and blocked)
+remaining = sum(
+    1 for story in stories
+    if isinstance(story, dict) and normalize_status(story.get("status")) not in ("done", "blocked")
+)
+print(remaining)
+PY
+}
+
+story_field() {
+  local meta_file="$1"
+  local field="$2"
+  $PYTHON_CMD - "$meta_file" "$field" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+data = json.loads(Path(sys.argv[1]).read_text())
+field = sys.argv[2]
+print(data.get(field, ""))
+PY
+}
+
+update_story_status() {
+  local story_id="$1"
+  local new_status="$2"
+  $PYTHON_CMD - "$PRD_PATH" "$story_id" "$new_status" <<'PY'
+import json
+import os
+import sys
+from pathlib import Path
+from datetime import datetime, timezone
+try:
+    import fcntl
+except Exception:
+    fcntl = None
+
+prd_path = Path(sys.argv[1])
+story_id = sys.argv[2]
+new_status = sys.argv[3]
+
+if not story_id:
+    sys.exit(0)
+
+if not prd_path.exists():
+    sys.exit(0)
+
+def now_iso():
+    return datetime.now(timezone.utc).isoformat()
+
+with prd_path.open("r+", encoding="utf-8") as fh:
+    if fcntl is not None:
+        fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+    try:
+        data = json.load(fh)
+        stories = data.get("stories") if isinstance(data, dict) else None
+        if not isinstance(stories, list):
+            sys.exit(0)
+        for story in stories:
+            if isinstance(story, dict) and story.get("id") == story_id:
+                story["status"] = new_status
+                story["updatedAt"] = now_iso()
+                if new_status == "in_progress":
+                    if not story.get("startedAt"):
+                        story["startedAt"] = now_iso()
+                    story["completedAt"] = None
+                elif new_status == "done":
+                    story["completedAt"] = now_iso()
+                    if not story.get("startedAt"):
+                        story["startedAt"] = now_iso()
+                elif new_status == "open":
+                    story["startedAt"] = None
+                    story["completedAt"] = None
+                break
+        fh.seek(0)
+        fh.truncate()
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+        fh.flush()
+        os.fsync(fh.fileno())
+    finally:
+        if fcntl is not None:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+PY
+}
+
+log_activity() {
+  local message="$1"
+  local timestamp
+  timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+  echo "[$timestamp] $message" >> "$ACTIVITY_LOG_PATH"
+}
+
+log_error() {
+  local message="$1"
+  local timestamp
+  timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+  echo "[$timestamp] $message" >> "$ERRORS_LOG_PATH"
+}
+
+# Check if the log file contains a transient/retryable error
+# Only returns true if the log is small (< 20 lines) AND contains a known error
+# This prevents retrying after a successful run that happens to mention an error
+is_transient_error() {
+  local log_file="$1"
+  if [ ! -f "$log_file" ]; then
+    # No log file at all - treat as transient (agent didn't even start)
+    return 0
+  fi
+
+  # Check log file size
+  local line_count
+  line_count=$(wc -l < "$log_file" | tr -d ' ')
+
+  # Empty or very small log file (<= 5 lines) with non-zero exit - likely transient
+  # The agent didn't produce meaningful output
+  if [ "$line_count" -le 5 ]; then
+    return 0
+  fi
+
+  # If the log file has substantial content (> 20 lines), don't retry
+  # This means the agent actually ran and produced output
+  if [ "$line_count" -gt 20 ]; then
+    return 1
+  fi
+
+  # For files between 6-20 lines, check for known error patterns
+  if grep -q "No messages returned" "$log_file"; then
+    return 0
+  fi
+  if grep -q "rate_limit_error" "$log_file"; then
+    return 0
+  fi
+  if grep -q "overloaded_error" "$log_file"; then
+    return 0
+  fi
+  if grep -q "ECONNRESET" "$log_file"; then
+    return 0
+  fi
+  if grep -q "ETIMEDOUT" "$log_file"; then
+    return 0
+  fi
+  if grep -q "socket hang up" "$log_file"; then
+    return 0
+  fi
+  if grep -q "API error" "$log_file"; then
+    return 0
+  fi
+  return 1
+}
+
+# Clean up uncommitted changes after failed iteration
+git_cleanup_dirty() {
+  if git -C "$ROOT_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    local dirty
+    dirty="$(git -C "$ROOT_DIR" status --porcelain 2>/dev/null || true)"
+    if [ -n "$dirty" ]; then
+      echo "Cleaning up uncommitted changes from failed iteration..."
+      git -C "$ROOT_DIR" checkout -- . 2>/dev/null || true
+      git -C "$ROOT_DIR" clean -fd 2>/dev/null || true
+    fi
+  fi
+}
+
+# Track story failure counts (stored in temp file)
+STORY_FAILURES_FILE="$TMP_DIR/story-failures-$$.json"
+
+init_story_failures() {
+  echo "{}" > "$STORY_FAILURES_FILE"
+}
+
+get_story_failure_count() {
+  local story_id="$1"
+  if [ ! -f "$STORY_FAILURES_FILE" ]; then
+    echo "0"
+    return
+  fi
+  $PYTHON_CMD - "$STORY_FAILURES_FILE" "$story_id" <<'PY'
+import json
+import sys
+from pathlib import Path
+try:
+    data = json.loads(Path(sys.argv[1]).read_text())
+    print(data.get(sys.argv[2], 0))
+except Exception:
+    print("0")
+PY
+}
+
+increment_story_failure() {
+  local story_id="$1"
+  $PYTHON_CMD - "$STORY_FAILURES_FILE" "$story_id" <<'PY'
+import json
+import sys
+from pathlib import Path
+path = Path(sys.argv[1])
+story_id = sys.argv[2]
+try:
+    data = json.loads(path.read_text())
+except Exception:
+    data = {}
+data[story_id] = data.get(story_id, 0) + 1
+path.write_text(json.dumps(data))
+PY
+}
+
+# Mark a story as blocked (too many failures) in PRD
+mark_story_blocked() {
+  local story_id="$1"
+  local reason="$2"
+  $PYTHON_CMD - "$PRD_PATH" "$story_id" "$reason" <<'PY'
+import json
+import os
+import sys
+from pathlib import Path
+from datetime import datetime, timezone
+try:
+    import fcntl
+except Exception:
+    fcntl = None
+
+prd_path = Path(sys.argv[1])
+story_id = sys.argv[2]
+reason = sys.argv[3] if len(sys.argv) > 3 else "Too many failures"
+
+if not story_id or not prd_path.exists():
+    sys.exit(0)
+
+def now_iso():
+    return datetime.now(timezone.utc).isoformat()
+
+with prd_path.open("r+", encoding="utf-8") as fh:
+    if fcntl is not None:
+        fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+    try:
+        data = json.load(fh)
+        stories = data.get("stories") if isinstance(data, dict) else None
+        if not isinstance(stories, list):
+            sys.exit(0)
+        for story in stories:
+            if isinstance(story, dict) and story.get("id") == story_id:
+                story["status"] = "blocked"
+                story["blockedReason"] = reason
+                story["updatedAt"] = now_iso()
+                break
+        fh.seek(0)
+        fh.truncate()
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+        fh.flush()
+        os.fsync(fh.fileno())
+    finally:
+        if fcntl is not None:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+PY
+}
+
+append_run_summary() {
+  local line="$1"
+  $PYTHON_CMD - "$ACTIVITY_LOG_PATH" "$line" <<'PY'
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+line = sys.argv[2]
+text = path.read_text().splitlines()
+out = []
+inserted = False
+for l in text:
+    out.append(l)
+    if not inserted and l.strip() == "## Run Summary":
+        out.append(f"- {line}")
+        inserted = True
+if not inserted:
+    out = [
+        "# Activity Log",
+        "",
+        "## Run Summary",
+        f"- {line}",
+        "",
+        "## Events",
+        "",
+    ] + text
+Path(path).write_text("\n".join(out).rstrip() + "\n")
+PY
+}
+
+write_run_meta() {
+  local path="$1"
+  local mode="$2"
+  local iter="$3"
+  local run_id="$4"
+  local story_id="$5"
+  local story_title="$6"
+  local started="$7"
+  local ended="$8"
+  local duration="$9"
+  local status="${10}"
+  local log_file="${11}"
+  local head_before="${12}"
+  local head_after="${13}"
+  local commit_list="${14}"
+  local changed_files="${15}"
+  local dirty_files="${16}"
+  {
+    echo "# Ralph Run Summary"
+    echo ""
+    echo "- Run ID: $run_id"
+    echo "- Iteration: $iter"
+    echo "- Mode: $mode"
+    if [ -n "$story_id" ]; then
+      echo "- Story: $story_id: $story_title"
+    fi
+    echo "- Started: $started"
+    echo "- Ended: $ended"
+    echo "- Duration: ${duration}s"
+    echo "- Status: $status"
+    echo "- Log: $log_file"
+    echo ""
+    echo "## Git"
+    echo "- Head (before): ${head_before:-unknown}"
+    echo "- Head (after): ${head_after:-unknown}"
+    echo ""
+    echo "### Commits"
+    if [ -n "$commit_list" ]; then
+      echo "$commit_list"
+    else
+      echo "- (none)"
+    fi
+    echo ""
+    echo "### Changed Files (commits)"
+    if [ -n "$changed_files" ]; then
+      echo "$changed_files"
+    else
+      echo "- (none)"
+    fi
+    echo ""
+    echo "### Uncommitted Changes"
+    if [ -n "$dirty_files" ]; then
+      echo "$dirty_files"
+    else
+      echo "- (clean)"
+    fi
+    echo ""
+  } > "$path"
+}
+
+git_head() {
+  if git -C "$ROOT_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    git -C "$ROOT_DIR" rev-parse HEAD 2>/dev/null || true
+  else
+    echo ""
+  fi
+}
+
+git_commit_list() {
+  local before="$1"
+  local after="$2"
+  if [ -n "$before" ] && [ -n "$after" ] && [ "$before" != "$after" ]; then
+    git -C "$ROOT_DIR" log --oneline "$before..$after" | sed 's/^/- /'
+  else
+    echo ""
+  fi
+}
+
+git_changed_files() {
+  local before="$1"
+  local after="$2"
+  if [ -n "$before" ] && [ -n "$after" ] && [ "$before" != "$after" ]; then
+    git -C "$ROOT_DIR" diff --name-only "$before" "$after" | sed 's/^/- /'
+  else
+    echo ""
+  fi
+}
+
+git_dirty_files() {
+  if git -C "$ROOT_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    git -C "$ROOT_DIR" status --porcelain | awk '{print "- " $2}'
+  else
+    echo ""
+  fi
+}
+
+echo "Ralph mode: $MODE"
+echo "Max iterations: $MAX_ITERATIONS"
+echo "Max retries per iteration: $MAX_RETRIES"
+echo "Max story failures before blocking: $MAX_STORY_FAILURES"
+echo "PRD: $PRD_PATH"
+HAS_ERROR="false"
+
+# Initialize story failure tracking
+init_story_failures
+
+for i in $(seq 1 "$MAX_ITERATIONS"); do
+  echo ""
+  echo "═══════════════════════════════════════════════════════"
+  echo "  Ralph Iteration $i of $MAX_ITERATIONS"
+  echo "═══════════════════════════════════════════════════════"
+
+  STORY_META=""
+  STORY_BLOCK=""
+  ITER_START=$(date +%s)
+  ITER_START_FMT=$(date '+%Y-%m-%d %H:%M:%S')
+  if [ "$MODE" = "build" ]; then
+    STORY_META="$TMP_DIR/story-$RUN_TAG-$i.json"
+    STORY_BLOCK="$TMP_DIR/story-$RUN_TAG-$i.md"
+    select_story "$STORY_META" "$STORY_BLOCK"
+    REMAINING="$(remaining_stories "$STORY_META")"
+    if [ "$REMAINING" = "unknown" ]; then
+      echo "Could not parse stories from PRD: $PRD_PATH"
+      exit 1
+    fi
+    if [ "$REMAINING" = "0" ]; then
+      echo "No remaining stories."
+      exit 0
+    fi
+    STORY_ID="$(story_field "$STORY_META" "id")"
+    STORY_TITLE="$(story_field "$STORY_META" "title")"
+    if [ -z "$STORY_ID" ]; then
+      echo "No actionable open stories (all blocked or in progress). Remaining: $REMAINING"
+      exit 0
+    fi
+
+    # Check if this story has failed too many times
+    STORY_FAILURES="$(get_story_failure_count "$STORY_ID")"
+    if [ "$STORY_FAILURES" -ge "$MAX_STORY_FAILURES" ]; then
+      echo "Story $STORY_ID has failed $STORY_FAILURES times, marking as blocked."
+      mark_story_blocked "$STORY_ID" "Failed $STORY_FAILURES times"
+      log_error "Story $STORY_ID blocked after $STORY_FAILURES failures"
+      continue
+    fi
+  fi
+
+  HEAD_BEFORE="$(git_head)"
+  PROMPT_RENDERED="$TMP_DIR/prompt-$RUN_TAG-$i.md"
+  LOG_FILE="$RUNS_DIR/run-$RUN_TAG-iter-$i.log"
+  RUN_META="$RUNS_DIR/run-$RUN_TAG-iter-$i.md"
+  render_prompt "$PROMPT_FILE" "$PROMPT_RENDERED" "$STORY_META" "$STORY_BLOCK" "$RUN_TAG" "$i" "$LOG_FILE" "$RUN_META"
+
+  if [ "$MODE" = "build" ] && [ -n "${STORY_ID:-}" ]; then
+    log_activity "ITERATION $i start (mode=$MODE story=$STORY_ID)"
+  else
+    log_activity "ITERATION $i start (mode=$MODE)"
+  fi
+
+  # Retry loop for transient errors
+  RETRY_COUNT=0
+  CMD_STATUS=1
+  while [ "$RETRY_COUNT" -lt "$MAX_RETRIES" ]; do
+    set +e
+    if [ "${RALPH_DRY_RUN:-}" = "1" ]; then
+      echo "[RALPH_DRY_RUN] Skipping agent execution." | tee "$LOG_FILE"
+      CMD_STATUS=0
+    else
+      # Run agent - capture output to log file while displaying to terminal
+      # Note: On some systems, piping through tee can cause buffering issues
+      # with interactive CLIs like Claude. If you see no output, the agent
+      # is still running - check the log file for captured output.
+      run_agent "$PROMPT_RENDERED" 2>&1 | tee "$LOG_FILE"
+      CMD_STATUS=${PIPESTATUS[0]}
+    fi
+    set -e
+
+    # Check for user interrupt
+    if [ "$CMD_STATUS" -eq 130 ] || [ "$CMD_STATUS" -eq 143 ]; then
+      echo "Interrupted."
+      exit "$CMD_STATUS"
+    fi
+
+    # If command succeeded, break retry loop
+    if [ "$CMD_STATUS" -eq 0 ]; then
+      break
+    fi
+
+    # Check if this is a transient error worth retrying
+    if is_transient_error "$LOG_FILE"; then
+      RETRY_COUNT=$((RETRY_COUNT + 1))
+      if [ "$RETRY_COUNT" -lt "$MAX_RETRIES" ]; then
+        echo ""
+        echo "╔═══════════════════════════════════════════════════════╗"
+        echo "║  Transient error detected, retrying ($RETRY_COUNT/$MAX_RETRIES)..."
+        echo "╚═══════════════════════════════════════════════════════╝"
+        log_activity "ITERATION $i retry $RETRY_COUNT (transient error)"
+        # Clean up any dirty state before retry
+        git_cleanup_dirty
+        # Exponential backoff: 10s, 20s, 40s, ...
+        local backoff_delay=$((RETRY_DELAY * (1 << (RETRY_COUNT - 1))))
+        echo "Waiting ${backoff_delay}s before retry..."
+        sleep "$backoff_delay"
+        continue
+      fi
+    fi
+
+    # Non-transient error or max retries reached
+    break
+  done
+
+  ITER_END=$(date +%s)
+  ITER_END_FMT=$(date '+%Y-%m-%d %H:%M:%S')
+  ITER_DURATION=$((ITER_END - ITER_START))
+  HEAD_AFTER="$(git_head)"
+  log_activity "ITERATION $i end (duration=${ITER_DURATION}s)"
+  if [ "$CMD_STATUS" -ne 0 ]; then
+    log_error "ITERATION $i command failed (status=$CMD_STATUS) after $((RETRY_COUNT)) retries"
+    HAS_ERROR="true"
+  fi
+  COMMIT_LIST="$(git_commit_list "$HEAD_BEFORE" "$HEAD_AFTER")"
+  CHANGED_FILES="$(git_changed_files "$HEAD_BEFORE" "$HEAD_AFTER")"
+  DIRTY_FILES="$(git_dirty_files)"
+  STATUS_LABEL="success"
+  if [ "$CMD_STATUS" -ne 0 ]; then
+    STATUS_LABEL="error"
+  fi
+  if [ "$MODE" = "build" ] && [ "$NO_COMMIT" = "false" ] && [ -n "$DIRTY_FILES" ]; then
+    log_error "ITERATION $i left uncommitted changes; review run summary at $RUN_META"
+    # Clean up dirty state on failure to prevent polluting next iteration
+    if [ "$CMD_STATUS" -ne 0 ]; then
+      git_cleanup_dirty
+    fi
+  fi
+  write_run_meta "$RUN_META" "$MODE" "$i" "$RUN_TAG" "${STORY_ID:-}" "${STORY_TITLE:-}" "$ITER_START_FMT" "$ITER_END_FMT" "$ITER_DURATION" "$STATUS_LABEL" "$LOG_FILE" "$HEAD_BEFORE" "$HEAD_AFTER" "$COMMIT_LIST" "$CHANGED_FILES" "$DIRTY_FILES"
+  if [ "$MODE" = "build" ] && [ -n "${STORY_ID:-}" ]; then
+    append_run_summary "$(date '+%Y-%m-%d %H:%M:%S') | run=$RUN_TAG | iter=$i | mode=$MODE | story=$STORY_ID | duration=${ITER_DURATION}s | status=$STATUS_LABEL | retries=$RETRY_COUNT"
+  else
+    append_run_summary "$(date '+%Y-%m-%d %H:%M:%S') | run=$RUN_TAG | iter=$i | mode=$MODE | duration=${ITER_DURATION}s | status=$STATUS_LABEL"
+  fi
+
+  if [ "$MODE" = "build" ]; then
+    if [ "$CMD_STATUS" -ne 0 ]; then
+      log_error "ITERATION $i exited non-zero; review $LOG_FILE"
+      increment_story_failure "$STORY_ID"
+      STORY_FAILURES="$(get_story_failure_count "$STORY_ID")"
+      if [ "$STORY_FAILURES" -ge "$MAX_STORY_FAILURES" ]; then
+        echo "Story $STORY_ID has now failed $STORY_FAILURES times, marking as blocked."
+        mark_story_blocked "$STORY_ID" "Failed $STORY_FAILURES times"
+        log_error "Story $STORY_ID blocked after $STORY_FAILURES consecutive failures"
+      else
+        update_story_status "$STORY_ID" "open"
+        echo "Iteration failed (attempt $STORY_FAILURES/$MAX_STORY_FAILURES); story reset to open."
+      fi
+    elif grep -q "<promise>COMPLETE</promise>" "$LOG_FILE"; then
+      update_story_status "$STORY_ID" "done"
+      echo "Completion signal received; story marked done."
+    else
+      # No completion signal - could be agent didn't finish or didn't output signal
+      increment_story_failure "$STORY_ID"
+      STORY_FAILURES="$(get_story_failure_count "$STORY_ID")"
+      if [ "$STORY_FAILURES" -ge "$MAX_STORY_FAILURES" ]; then
+        echo "Story $STORY_ID has failed $STORY_FAILURES times (no completion signal), marking as blocked."
+        mark_story_blocked "$STORY_ID" "No completion signal after $STORY_FAILURES attempts"
+        log_error "Story $STORY_ID blocked: no completion signal after $STORY_FAILURES attempts"
+      else
+        update_story_status "$STORY_ID" "open"
+        echo "No completion signal (attempt $STORY_FAILURES/$MAX_STORY_FAILURES); story reset to open."
+      fi
+    fi
+    REMAINING="$(remaining_from_prd)"
+    echo "Iteration $i complete. Remaining stories: $REMAINING"
+    if [ "$REMAINING" = "0" ]; then
+      echo "No remaining stories."
+      exit 0
+    fi
+  else
+    echo "Iteration $i complete."
+  fi
+  sleep 2
+
+done
+
+echo "Reached max iterations ($MAX_ITERATIONS)."
+if [ "$HAS_ERROR" = "true" ]; then
+  exit 1
+fi
+exit 0