feat(history): add historical log context for Ralph iterations

.agents/ralph/PROMPT_build.md

@@ -33,6 +33,12 @@ Story details:
 
 If the story details are empty or missing, STOP and report that the PRD story format could not be parsed.
 
+## Historical Context (from previous runs)
+
+{{HISTORICAL_CONTEXT}}
+
+> If historical context shows previous failures for this story, review the approaches that failed and try different solutions. Learn from what didn't work to avoid repeating the same mistakes.
+
 ## Rules (Non-Negotiable)
 
 - Implement **only** the work required to complete the selected story.

.agents/ralph/config.sh

@@ -278,3 +278,31 @@ RALPH_MERGE_REQUIRE_CONFIRM=true
 # Note: Worktrees provide strongest isolation and are recommended when possible.
 # Sequential mode is for projects where worktrees are not feasible.
 # ─────────────────────────────────────────────────────────────────────────────
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Historical Log Context Configuration
+# ─────────────────────────────────────────────────────────────────────────────
+# Enable historical context from previous runs to help agents avoid repeating
+# failed approaches. Context is generated from run-*.md summary files.
+#
+# History mode (choose one):
+#   off    - No historical context (default, no overhead)
+#   smart  - Focused context on failures and current story (recommended)
+#   full   - Complete historical context for all indexed runs
+#
+# Default: off (no change to existing behavior)
+RALPH_HISTORY_MODE=off
+#
+# Maximum tokens to allocate for historical context (default: 4000):
+# Higher values provide more context but consume more of the prompt budget.
+RALPH_HISTORY_TOKEN_BUDGET=4000
+#
+# Maximum historical runs to consider when building index (default: 10):
+# More runs = better context but slower indexing.
+RALPH_HISTORY_MAX_RUNS=10
+#
+# Override via CLI:
+#   ralph build 5 --with-history        # Sets mode to "smart"
+#   ralph build 5 --no-history          # Sets mode to "off"
+#   ralph build 5 --history-mode=full   # Sets mode explicitly
+# ─────────────────────────────────────────────────────────────────────────────

.agents/ralph/loop.sh

@@ -978,6 +978,7 @@ render_prompt() {
   local run_meta="$8"
   python3 - "$src" "$dst" "$PRD_PATH" "$PLAN_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
+import os
 from pathlib import Path
 
 src = Path(sys.argv[1]).read_text()
@@ -995,6 +996,8 @@ run_id = sys.argv[17] if len(sys.argv) > 17 else ""
 iteration = sys.argv[18] if len(sys.argv) > 18 else ""
 run_log = sys.argv[19] if len(sys.argv) > 19 else ""
 run_meta = sys.argv[20] if len(sys.argv) > 20 else ""
+# Get historical context from environment (US-XXX Historical Log Context)
+historical_context = os.environ.get("HISTORICAL_CONTEXT", "")
 repl = {
     "PRD_PATH": prd,
     "PLAN_PATH": plan,
@@ -1012,6 +1015,7 @@ repl = {
     "ITERATION": iteration,
     "RUN_LOG_PATH": run_log,
     "RUN_META_PATH": run_meta,
+    "HISTORICAL_CONTEXT": historical_context,
 }
 story = {"id": "", "title": "", "block": ""}
 if meta_path:
@@ -3545,6 +3549,22 @@ for i in $(seq $START_ITERATION "$MAX_ITERATIONS"); do
   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"
+
+  # Generate historical context if enabled (US-XXX Historical Log Context)
+  HISTORICAL_CONTEXT=""
+  if [[ "${RALPH_HISTORY_MODE:-off}" != "off" ]] && [ -n "${STORY_ID:-}" ]; then
+    PRD_FOLDER="$(dirname "$PRD_PATH")"
+    HISTORICAL_CONTEXT=$(node "$SCRIPT_DIR/../../lib/history/context-cli.js" \
+      --prd-folder "$PRD_FOLDER" \
+      --story-id "$STORY_ID" \
+      --mode "${RALPH_HISTORY_MODE}" \
+      --token-budget "${RALPH_HISTORY_TOKEN_BUDGET:-4000}" 2>/dev/null || echo "")
+    if [ -n "$HISTORICAL_CONTEXT" ]; then
+      log_activity "HISTORY_CONTEXT generated mode=${RALPH_HISTORY_MODE} story=$STORY_ID tokens=$(echo -n "$HISTORICAL_CONTEXT" | wc -c | tr -d ' ')"
+    fi
+  fi
+  export HISTORICAL_CONTEXT
+
   render_prompt "$PROMPT_FILE" "$PROMPT_RENDERED" "$STORY_META" "$STORY_BLOCK" "$RUN_TAG" "$i" "$LOG_FILE" "$RUN_META"
 
   if [ "$MODE" = "build" ] && [ -n "${STORY_ID:-}" ]; then

bin/ralph

@@ -39,7 +39,7 @@
 // ============================================================================
 // Utility Functions
 // ============================================================================
 const success = (msg) => console.log(pc.green(msg));
 const error = (msg) => console.error(pc.red(msg));
 const info = (msg) => console.log(pc.cyan(msg));
 const dim = (msg) => console.log(pc.dim(msg));
@@ -77,6 +77,7 @@
   uiOpenBrowser: false,
   watchBuildMode: false,
   estimatePricing: null,
+  historyMode: null, // Historical log context: off, smart, full
 };
 
 // Parse global flags from rawArgs
@@ -157,6 +158,8 @@
   if (arg === "--no-retry") { globalFlags.noRetry = true; continue; }
   if (arg === "--build") { globalFlags.watchBuildMode = true; continue; }
   if (arg === "--skip-risk-check") { globalFlags.skipRiskCheck = true; continue; }
+  if (arg === "--with-history") { globalFlags.historyMode = "smart"; continue; }
+  if (arg === "--no-history") { globalFlags.historyMode = "off"; continue; }
 
   // --import-from flag
   if (arg.startsWith("--import-from=")) {
@@ -198,6 +201,26 @@
     continue;
   }
 
+  // --history-mode flag (Historical Log Context)
+  if (arg.startsWith("--history-mode=")) {
+    const mode = arg.split("=").slice(1).join("=");
+    if (!["off", "smart", "full"].includes(mode)) {
+      error(`Invalid --history-mode value: ${mode}. Must be: off, smart, or full`);
+      process.exit(1);
+    }
+    globalFlags.historyMode = mode;
+    continue;
+  }
+  if (arg === "--history-mode") {
+    const mode = rawArgs[++i];
+    if (!["off", "smart", "full"].includes(mode)) {
+      error(`Invalid --history-mode value: ${mode}. Must be: off, smart, or full`);
+      process.exit(1);
+    }
+    globalFlags.historyMode = mode;
+    continue;
+  }
+
   // --parallel flag
   if (arg.startsWith("--parallel=")) {
     const val = arg.split("=").slice(1).join("=");
@@ -326,6 +349,7 @@
 if (globalFlags.modelOverride) env.RALPH_MODEL_OVERRIDE = globalFlags.modelOverride;
 if (globalFlags.autoFixMode) env.AUTO_FIX = globalFlags.autoFixMode;
 if (globalFlags.skipRiskCheck) env.RALPH_SKIP_RISK = "1";
+if (globalFlags.historyMode) env.RALPH_HISTORY_MODE = globalFlags.historyMode;
 
 if (templateDir === globalDir) {
   env.PROMPT_PLAN = path.join(templateDir, "PROMPT_plan.md");
@@ -722,7 +746,7 @@
 
     // Handle parallel execution
     if (globalFlags.parallelConcurrency && (cmd === "build" || !cmd)) {
       const parallelModule = require("../lib/parallel");
       // ... parallel execution logic (kept minimal in dispatcher)
       info(`Running parallel execution with ${pc.bold(globalFlags.parallelConcurrency)} concurrent agents...`);
       // This would need the full parallel setup - for now delegate to loop.sh
@@ -864,7 +888,7 @@
         process.exit(result.success ? 0 : 1);
       } catch (err) {
         // Graceful fallback to bash loop
         warn(`TypeScript executor failed: ${err.message}`);
         info("Falling back to bash loop...");
         // Continue to bash execution below
       }