spec-and-loop 3.1.0 → 3.3.0

package/lib/mini-ralph/history.js

@@ -52,6 +52,10 @@ function read(ralphDir) {
  * @param {Array}  entry.toolUsage         - Tool usage summary array
  * @param {Array}  entry.filesChanged      - Files changed in this iteration
  * @param {number} entry.exitCode          - OpenCode exit code
+ * @param {boolean} [entry.blockedHandoffDetected] - Whether the iteration emitted
+ *   the configured blocked-handoff promise and stopped for operator action.
+ * @param {string}  [entry.blockedHandoffNote] - Compact, single-line preview of
+ *   the extracted blocker note. The full note is persisted in HANDOFF.md.
  * @param {number} [entry.promptBytes]     - UTF-8 byte length of the assembled prompt
  * @param {number} [entry.promptChars]     - Character length of the assembled prompt
  * @param {number} [entry.promptTokens]    - Estimated token count for the prompt (chars/4, rounded)

package/lib/mini-ralph/index.js

@@ -35,6 +35,7 @@ const prompt = require('./prompt');
  * @param {number} [options.maxIterations]   - Maximum iterations (default: 50)
  * @param {string} [options.completionPromise] - Promise string signaling loop completion (default: "COMPLETE")
  * @param {string} [options.taskPromise]     - Promise string signaling task completion (default: "READY_FOR_NEXT_TASK")
+ * @param {string} [options.blockedHandoffPromise] - Promise string signaling the agent is blocked and requesting human handoff (default: "BLOCKED_HANDOFF")
  * @param {boolean} [options.tasksMode]      - Enable tasks mode (default: false)
  * @param {string} [options.tasksFile]       - Path to tasks file when tasksMode is true
  * @param {boolean} [options.noCommit]       - Suppress auto-commit (default: false)

package/lib/mini-ralph/runner.js

@@ -28,6 +28,14 @@ const DEFAULTS = {
   maxIterations: 50,
   completionPromise: 'COMPLETE',
   taskPromise: 'READY_FOR_NEXT_TASK',
+  // Emitted by the agent when a task's `Stop and hand off if:` clause fires
+  // (i.e. external decision required: revert protected drift, file an
+  // out-of-scope refactor, escalate to a human reviewer, etc). The runner
+  // recognizes this as a *clean* exit distinct from `stalled` — it preserves
+  // the agent's diagnosis under `<ralphDir>/HANDOFF.md` and surfaces
+  // `exitReason='blocked_handoff'` so operators can tell "this task is
+  // genuinely blocked on me" apart from "the loop livelocked."
+  blockedHandoffPromise: 'BLOCKED_HANDOFF',
   tasksMode: false,
   noCommit: false,
   verbose: false,
@@ -48,11 +56,16 @@ const DEFAULTS = {
  * Determine whether an iteration made any forward progress.
  *
  * An iteration is considered productive if any of the following are true:
- *   - OpenCode emitted the task or completion promise
+ *   - OpenCode emitted the task, completion, or blocked-handoff promise
  *   - One or more tasks transitioned to "completed" during the iteration
  *   - At least one repo-tracked file was observed to have changed
  *   - The iteration failed outright (its signal is handled separately)
  *
+ * Note: a blocked-handoff iteration is intentionally excluded from "stalled"
+ * because the agent followed protocol — it surfaced a structured exit, the
+ * runner caught it, and the loop will break this iteration. We never want
+ * to penalize the agent (or the operator) for the canonical hand-off path.
+ *
  * @param {object} iterationSignals
  * @returns {boolean}
  */
@@ -61,6 +74,7 @@ function _iterationIsStalled(iterationSignals) {
   if (iterationSignals.iterationFailed) return false;
   if (iterationSignals.hasCompletion) return false;
   if (iterationSignals.hasTask) return false;
+  if (iterationSignals.hasBlockedHandoff) return false;
   if (iterationSignals.completedTasksCount > 0) return false;
   if (iterationSignals.filesChangedCount > 0) return false;
   return true;
@@ -118,6 +132,243 @@ function _errorText(err) {
   return String(err);
 }
 
+/**
+ * Extract the agent's blocker note from iteration output. The convention is:
+ * the line containing `<promise>BLOCKED_HANDOFF</promise>` MAY be preceded by
+ * a free-text rationale block (any number of lines up to a sentinel header
+ * `## Blocker` / `## Blocker Note` / `Blocker:`), and MAY include `## Why:` /
+ * `## Done-When-Will-Be:` / `## Suggested Next Step:` sections. We capture
+ * everything from the first sentinel header up to the promise tag, with a
+ * fallback to the last 40 non-blank lines preceding the tag if no sentinel
+ * is present, so the operator gets *something* useful even when the agent
+ * skips the structured format.
+ *
+ * @param {string} outputText  full iteration stdout
+ * @param {string} promiseName configured BLOCKED_HANDOFF promise name
+ * @returns {string} the extracted note (empty string if the tag is absent)
+ */
+function _extractBlockerNote(outputText, promiseName) {
+  if (!outputText || !promiseName) return '';
+  const tag = `<promise>${promiseName}</promise>`;
+  const lines = outputText.split(/\r?\n/);
+  let tagIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === tag) {
+      tagIdx = i;
+      break;
+    }
+  }
+  if (tagIdx === -1) return '';
+
+  // Look backwards for a sentinel header.
+  const sentinel = /^\s*(##\s*Blocker(\s+Note)?|Blocker:)/i;
+  let startIdx = tagIdx;
+  for (let i = tagIdx - 1; i >= 0; i--) {
+    if (sentinel.test(lines[i])) {
+      startIdx = i;
+      break;
+    }
+  }
+
+  if (startIdx === tagIdx) {
+    // No sentinel — fall back to the last 40 non-blank lines before the tag.
+    const window = [];
+    for (let i = tagIdx - 1; i >= 0 && window.length < 40; i--) {
+      const l = lines[i];
+      if (l.trim()) window.unshift(l);
+    }
+    return window.join('\n').trim();
+  }
+
+  return lines.slice(startIdx, tagIdx).join('\n').trim();
+}
+
+/**
+ * Scan well-known locations for blocker / diagnostic artifacts the agent
+ * may have written during the most recent iteration, and return their
+ * content (truncated) so we can tee it into the next iteration's prompt.
+ *
+ * The motivation is the failure mode we observed in the wild: the agent
+ * writes `<change-baseline>/shared-chrome-invariant-report.txt` with a clear
+ * `STATUS=BLOCKED  REASON=...` diagnosis, then on the next iteration starts
+ * from a blank slate, re-derives the same diagnosis, and burns another full
+ * LLM cycle. By auto-detecting and surfacing the artifact, the agent gets
+ * its own prior diagnosis as input on the next turn, freeing it to either
+ * (a) act on it, or (b) emit BLOCKED_HANDOFF with a richer note.
+ *
+ * Probe paths (relative to ralphDir's parent — i.e. the change root):
+ *   - <ralphDir>/HANDOFF.md
+ *   - <ralphDir>/BLOCKED.md
+ *   - <ralphDir>/blocker.md  /  blocker-note.md
+ *   - <repoRoot>/.ralph/baselines/<change>/*report*.{txt,md}
+ *   - any file under <ralphDir> matching /(blocker|handoff|invariant-report)\.[a-z]+$/i
+ *
+ * We cap the returned text at 1500 chars per artifact and 3 artifacts total
+ * so the feedback block stays bounded. Freshness is required by default to
+ * avoid carrying stale diagnostics forever; when a prior run explicitly ended
+ * with BLOCKED_HANDOFF, the canonical handoff files may be included even when
+ * stale because they are the persisted operator-facing diagnosis.
+ *
+ * @param {string} ralphDir
+ * @param {object} [options] { repoRoot, maxArtifacts = 3, maxCharsEach = 1500, includeStaleHandoff = false }
+ * @returns {Array<{ path: string, content: string, truncated: boolean }>}
+ */
+function _detectBlockerArtifacts(ralphDir, options) {
+  const fs = require('fs');
+  const fsPath = require('path');
+  const opts = Object.assign(
+    {
+      repoRoot: process.cwd(),
+      maxArtifacts: 3,
+      maxCharsEach: 1500,
+      includeStaleHandoff: false,
+    },
+    options || {}
+  );
+
+  if (!ralphDir || !fs.existsSync(ralphDir)) return [];
+
+  const matches = new Map(); // path -> mtimeMs (dedup by absolute path)
+  const isHandoffArtifact = (name) =>
+    /^(handoff|blocked|blocker(-note)?)\.(md|txt)$/i.test(name);
+  const isInteresting = (name) =>
+    isHandoffArtifact(name) ||
+    /(invariant|blocker|handoff).*report\.(md|txt)$/i.test(name) ||
+    /report\.(md|txt)$/i.test(name);
+
+  const consider = (p) => {
+    try {
+      const st = fs.statSync(p);
+      if (!st.isFile()) return;
+      // Files larger than 1MB are almost certainly not human-curated blocker
+      // notes; skip them so we don't load logs or screenshots into the prompt.
+      if (st.size > 1024 * 1024) return;
+      // Only surface artifacts touched within the last ~10 minutes — older
+      // files are almost always stale leftovers from prior runs, and the
+      // failure mode we care about (repeated diagnosis with no progress)
+      // produces fresh writes every iteration.
+      const stale = Date.now() - st.mtimeMs > 10 * 60 * 1000;
+      if (stale && !(opts.includeStaleHandoff && isHandoffArtifact(fsPath.basename(p)))) {
+        return;
+      }
+      matches.set(fsPath.resolve(p), st.mtimeMs);
+    } catch (_) {
+      // ENOENT / permission errors: ignore — this is a best-effort probe.
+    }
+  };
+
+  // 1) Direct ralphDir scan, one level deep. .ralph/ is small, so a flat
+  //    listing is cheap and bounded.
+  try {
+    const entries = fs.readdirSync(ralphDir, { withFileTypes: true });
+    for (const ent of entries) {
+      if (ent.isFile() && isInteresting(ent.name)) {
+        consider(fsPath.join(ralphDir, ent.name));
+      }
+    }
+  } catch (_) { /* ignore */ }
+
+  // 2) Convention-based baseline location used by spec-and-loop changes:
+  //    <repoRoot>/.ralph/baselines/<change>/*report*.{txt,md}
+  //    The change name is the parent directory of ralphDir's parent in the
+  //    OpenSpec layout (e.g. .../changes/<name>/.ralph), so we derive it.
+  try {
+    const changeDir = fsPath.dirname(ralphDir);
+    const changeName = fsPath.basename(changeDir);
+    const baselinesDir = fsPath.join(opts.repoRoot, '.ralph', 'baselines', changeName);
+    if (fs.existsSync(baselinesDir)) {
+      const entries = fs.readdirSync(baselinesDir, { withFileTypes: true });
+      for (const ent of entries) {
+        if (ent.isFile() && isInteresting(ent.name)) {
+          consider(fsPath.join(baselinesDir, ent.name));
+        }
+      }
+    }
+  } catch (_) { /* ignore */ }
+
+  if (matches.size === 0) return [];
+
+  // Sort by mtime descending so the freshest artifact wins when we cap.
+  const sorted = Array.from(matches.entries())
+    .sort((a, b) => b[1] - a[1])
+    .map(([p]) => p);
+
+  const out = [];
+  for (const p of sorted.slice(0, opts.maxArtifacts)) {
+    try {
+      const raw = fs.readFileSync(p, 'utf8');
+      const truncated = raw.length > opts.maxCharsEach;
+      const content = truncated ? raw.slice(0, opts.maxCharsEach) : raw;
+      out.push({
+        path: fsPath.relative(opts.repoRoot, p) || p,
+        content: content.trim(),
+        truncated,
+      });
+    } catch (_) {
+      // Ignore unreadable artifacts.
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Write the agent's blocker note to <ralphDir>/HANDOFF.md with iteration
+ * metadata so an operator can reproduce the context. Appends rather than
+ * overwrites: a single change can hit several BLOCKED_HANDOFFs over time
+ * (operator unblocks, loop resumes, hits a different blocker), and we want
+ * the full audit trail in one file.
+ *
+ * @param {string} ralphDir
+ * @param {object} entry { iteration, task, note, completionPromise, taskPromise }
+ * @returns {string} the absolute path to HANDOFF.md
+ */
+function _writeHandoff(ralphDir, entry) {
+  const fs = require('fs');
+  const fsPath = require('path');
+  if (!fs.existsSync(ralphDir)) {
+    fs.mkdirSync(ralphDir, { recursive: true });
+  }
+  const handoffPath = fsPath.join(ralphDir, 'HANDOFF.md');
+  const ts = new Date().toISOString();
+  const taskLine = entry.task && entry.task !== 'N/A'
+    ? entry.task
+    : '(no task in progress)';
+  const noteBlock = entry.note && entry.note.trim()
+    ? entry.note.trim()
+    : '(agent emitted BLOCKED_HANDOFF without a structured blocker note;\n' +
+      'check the iteration stdout log for the rationale)';
+
+  const section = [
+    '',
+    `## Iteration ${entry.iteration} — ${ts}`,
+    '',
+    `**Task:** ${taskLine}`,
+    '',
+    '**Agent blocker note:**',
+    '',
+    noteBlock,
+    '',
+    '**Operator next step:** investigate the blocker, take one of the actions',
+    'the task spec authorizes (revert / isolate / justify / escalate), then',
+    'rerun `ralph-run` to resume.',
+    '',
+    '---',
+    '',
+  ].join('\n');
+
+  let existing = '';
+  if (fs.existsSync(handoffPath)) {
+    existing = fs.readFileSync(handoffPath, 'utf8');
+  } else {
+    existing = '# Ralph Handoff Log\n\nThis file is appended whenever the loop\n' +
+      'exits with `BLOCKED_HANDOFF`. Each section is one blocker the\n' +
+      'agent surfaced — review newest first.\n';
+  }
+  fs.writeFileSync(handoffPath, existing + section, 'utf8');
+  return handoffPath;
+}
+
 function _appendFatalIterationFailure(ralphDir, entry) {
   errors.append(ralphDir, {
     iteration: entry.iteration,
@@ -155,6 +406,14 @@ function _appendFatalIterationFailure(ralphDir, entry) {
   });
 }
 
+function _summarizeBlockerNote(note, limit = 500) {
+  if (!note || typeof note !== 'string') return '';
+  const oneLine = note.replace(/\s+/g, ' ').trim();
+  if (!oneLine) return '';
+  if (oneLine.length <= limit) return oneLine;
+  return `${oneLine.slice(0, Math.max(0, limit - 1)).replace(/\s+$/, '')}…`;
+}
+
 /**
  * Run the iteration loop.
  *
@@ -175,6 +434,7 @@ async function run(opts) {
   const minIterations = options.minIterations;
   const completionPromise = options.completionPromise;
   const taskPromise = options.taskPromise;
+  const blockedHandoffPromise = options.blockedHandoffPromise;
   const stallThreshold =
     typeof options.stallThreshold === 'number' && options.stallThreshold >= 0
       ? Math.floor(options.stallThreshold)
@@ -200,6 +460,8 @@ async function run(opts) {
     // otherwise start fresh at 1.
     const existingState = state.read(ralphDir);
     const resumeIteration = _resolveStartIteration(existingState, options);
+    const priorRunWasBlockedHandoff =
+      existingState && existingState.exitReason === 'blocked_handoff';
 
     if (options.verbose && resumeIteration > 1) {
       process.stderr.write(
@@ -234,6 +496,7 @@ async function run(opts) {
       maxIterations,
       completionPromise,
       taskPromise,
+      blockedHandoffPromise,
       tasksMode: options.tasksMode,
       tasksFile: options.tasksFile || null,
       promptFile: options.promptFile || null,
@@ -294,8 +557,19 @@ async function run(opts) {
           // dedup collapses identical entries into a single "same failure as
           // iteration N" line, so the 3-entry window is sufficient to surface
           // recurring patterns without bloating the prompt.
+          const recentHistory = history.recent(ralphDir, 3);
           const errorEntries = errors.readEntries(ralphDir, 3);
-          const iterationFeedback = _buildIterationFeedback(history.recent(ralphDir, 3), errorEntries);
+          const blockerArtifacts = _detectBlockerArtifacts(ralphDir, {
+            repoRoot: process.cwd(),
+            includeStaleHandoff:
+              priorRunWasBlockedHandoff ||
+              recentHistory.some((entry) => entry && entry.blockedHandoffDetected),
+          });
+          const iterationFeedback = _buildIterationFeedback(
+            recentHistory,
+            errorEntries,
+            blockerArtifacts,
+          );
 
           // Inject any pending context
           const pendingContext = context.consume(ralphDir);
@@ -392,6 +666,14 @@ async function run(opts) {
         const iterationSucceeded = _wasSuccessfulIteration(result);
         const hasCompletion = iterationSucceeded && _containsPromise(outputText, completionPromise);
         const hasTask = iterationSucceeded && _containsPromise(outputText, taskPromise);
+        // Blocked-handoff is also a successful-iteration signal (the agent
+        // followed protocol and explicitly emitted a structured exit). We
+        // treat it as a third top-level outcome alongside completion/task.
+        const hasBlockedHandoff = iterationSucceeded
+          && _containsPromise(outputText, blockedHandoffPromise);
+        const blockerNote = hasBlockedHandoff
+          ? _extractBlockerNote(outputText, blockedHandoffPromise)
+          : '';
         const tasksAfter = options.tasksMode && options.tasksFile
           ? tasks.parseTasks(options.tasksFile)
           : [];
@@ -435,6 +717,10 @@ async function run(opts) {
           duration,
           completionDetected: hasCompletion,
           taskDetected: hasTask,
+          blockedHandoffDetected: hasBlockedHandoff,
+          ...(blockerNote ? { blockedHandoffNote: _summarizeBlockerNote(blockerNote) } : {}),
+          taskNumber: currentTaskMeta.number,
+          taskDescription: currentTaskMeta.description,
           toolUsage: result.toolUsage || [],
           filesChanged: result.filesChanged || [],
           exitCode: result.exitCode,
@@ -472,6 +758,7 @@ async function run(opts) {
           iterationFailed,
           hasCompletion,
           hasTask,
+          hasBlockedHandoff,
           completedTasksCount: completedTasks.length,
           filesChangedCount: Array.isArray(result.filesChanged) ? result.filesChanged.length : 0,
         });
@@ -487,12 +774,15 @@ async function run(opts) {
           durationMs: duration,
           outcome: iterationFailed
             ? 'failure'
-            : stalledThisIteration
-              ? 'stalled'
-              : 'success',
+            : hasBlockedHandoff
+              ? 'blocked'
+              : stalledThisIteration
+                ? 'stalled'
+                : 'success',
           committed: commitResult.committed === true,
           hasCompletion,
           hasTask,
+          hasBlockedHandoff,
           completedTasksCount: completedTasks.length,
           filesChangedCount: Array.isArray(result.filesChanged) ? result.filesChanged.length : 0,
           stallStreak,
@@ -508,6 +798,44 @@ async function run(opts) {
           break;
         }
 
+        // Blocked-handoff exits the loop *immediately* (no minIterations
+        // floor). The agent has signaled an external decision is required;
+        // we want the operator unblocked as fast as possible. We persist the
+        // agent's note before breaking so it survives even a hard-kill on
+        // the parent process (e.g. the operator hits Ctrl-C right after).
+        if (hasBlockedHandoff) {
+          let handoffPath = '';
+          try {
+            handoffPath = _writeHandoff(ralphDir, {
+              iteration: iterationCount,
+              task: currentTask,
+              note: blockerNote,
+              completionPromise,
+              taskPromise,
+            });
+          } catch (writeErr) {
+            // Don't let a HANDOFF.md write failure mask the original signal —
+            // we still want to exit cleanly with `blocked_handoff`. Surface
+            // the write error to stderr so it's diagnosable.
+            process.stderr.write(
+              `[mini-ralph] warning: failed to write HANDOFF.md: ${writeErr.message}\n`
+            );
+          }
+          reporter.note(
+            handoffPath
+              ? `agent emitted ${blockedHandoffPromise}; blocker note saved to ${handoffPath}.`
+              : `agent emitted ${blockedHandoffPromise}; halting (HANDOFF.md write failed; see stderr).`,
+            'warn'
+          );
+          if (options.verbose) {
+            process.stderr.write(
+              `[mini-ralph] ${blockedHandoffPromise} detected at iteration ${iterationCount}; halting.\n`
+            );
+          }
+          exitReason = 'blocked_handoff';
+          break;
+        }
+
         if (stallThreshold > 0 && stallStreak >= stallThreshold) {
           reporter.note(
             `stall detector: ${stallStreak} consecutive no-op iteration(s); halting.`,
@@ -976,16 +1304,19 @@ function _failureFingerprint(entry, errorEntries) {
     stderrHead = _firstNonEmptyLine(match && match.stderr, 120);
   }
   // A "no promise emitted" iteration is also a distinguishable failure mode
-  // even when exitCode===0 and there's no stderr (e.g. the agent explicitly
-  // refuses to continue). Encoding it in the fingerprint lets the dedup
-  // collapse repeated hand-off iterations into a single actionable line
-  // instead of N identical bullets.
-  const noPromise = !entry.completionDetected && !entry.taskDetected;
+  // even when exitCode===0 and there's no stderr (e.g. the agent refuses to
+  // continue without using the control protocol). Encoding it separately keeps
+  // no-progress stalls distinct from explicit BLOCKED_HANDOFF stops.
+  const noPromise =
+    !entry.completionDetected &&
+    !entry.taskDetected &&
+    !entry.blockedHandoffDetected;
   return JSON.stringify({
     failureStage: entry.failureStage || '',
     exitCode: entry.exitCode,
     stderrHead,
     noPromise,
+    blockedHandoff: Boolean(entry.blockedHandoffDetected),
     commitAnomalyType: entry.commitAnomalyType || '',
   });
 }
@@ -998,6 +1329,7 @@ function _isEmptyFingerprint(fingerprint) {
       obj.exitCode === 0 &&
       !obj.stderrHead &&
       !obj.noPromise &&
+      !obj.blockedHandoff &&
       !obj.commitAnomalyType
     );
   } catch {
@@ -1005,14 +1337,23 @@ function _isEmptyFingerprint(fingerprint) {
   }
 }
 
-function _buildIterationFeedback(recentHistory, errorEntries) {
-  if (!Array.isArray(recentHistory) || recentHistory.length === 0) {
+function _buildIterationFeedback(recentHistory, errorEntries, blockerArtifacts) {
+  const hasArtifacts = Array.isArray(blockerArtifacts) && blockerArtifacts.length > 0;
+  if ((!Array.isArray(recentHistory) || recentHistory.length === 0) && !hasArtifacts) {
     return '';
   }
+  if (!Array.isArray(recentHistory)) recentHistory = [];
 
   const problemLines = [];
   // Track fingerprint -> first iteration number for dedup
   const fingerprintSeen = new Map();
+  // Track which task each *problematic* iteration was working when it failed
+  // / produced no progress. The same `taskNumber|taskDescription` repeating
+  // across the recent window is the strongest livelock signal we have — the
+  // agent is hitting the same wall with no new information. Persist the run
+  // length so we can emit a HARD prefix above the per-iteration list when
+  // the streak crosses the noise floor (3+ consecutive on the same task).
+  const recentTasks = [];
 
   for (const entry of recentHistory) {
     const issues = [];
@@ -1029,11 +1370,28 @@ function _buildIterationFeedback(recentHistory, errorEntries) {
       issues.push(`commit anomaly: ${entry.commitAnomaly}`);
     }
 
-    if (!entry.completionDetected && !entry.taskDetected) {
+    if (entry.blockedHandoffDetected) {
+      issues.push('agent emitted BLOCKED_HANDOFF and requested operator handoff');
+    } else if (!entry.completionDetected && !entry.taskDetected) {
       issues.push('no loop promise emitted');
     }
 
     if (issues.length > 0) {
+      // Build the task-identity stamp (used both for the per-line prefix and
+      // for streak detection). Empty when the runner had no task context for
+      // the iteration (non-tasks-mode, or pre-resume entries written by an
+      // older runner version).
+      const rawTaskId = entry.taskNumber
+        ? `${entry.taskNumber}|${entry.taskDescription || ''}`
+        : (entry.taskDescription || '');
+      const taskStamp = entry.taskNumber
+        ? `Task ${entry.taskNumber}` +
+          (entry.taskDescription ? ` (${entry.taskDescription})` : '')
+        : (entry.taskDescription
+          ? `Task ${entry.taskDescription}`
+          : '');
+      if (rawTaskId) recentTasks.push(rawTaskId);
+
       // Compute fingerprint for dedup
       const fp = _failureFingerprint(entry, errorEntries);
       const isRealFailure = !_isEmptyFingerprint(fp);
@@ -1047,13 +1405,19 @@ function _buildIterationFeedback(recentHistory, errorEntries) {
 
       if (isRealFailure && fingerprintSeen.has(fp) && !isIgnoreFilterAnomaly) {
         const firstIteration = fingerprintSeen.get(fp);
+        const stampSuffix = taskStamp ? ` [${taskStamp}]` : '';
         problemLines.push(
-          `- Iteration ${entry.iteration}: same failure as iteration ${firstIteration} (see above).`
+          `- Iteration ${entry.iteration}${stampSuffix}: same failure as iteration ${firstIteration} (see above).`
         );
       } else {
         if (isRealFailure && !isIgnoreFilterAnomaly) fingerprintSeen.set(fp, entry.iteration);
 
-        let line = `- Iteration ${entry.iteration}: ${issues.join('; ')}.`;
+        const stampPrefix = taskStamp ? ` [${taskStamp}]` : '';
+        let line = `- Iteration ${entry.iteration}${stampPrefix}: ${issues.join('; ')}.`;
+
+        if (entry.blockedHandoffDetected && entry.blockedHandoffNote) {
+          line += ` Blocker note: ${entry.blockedHandoffNote}`;
+        }
 
         // For paths_ignored_filtered / all_paths_ignored, append the first two
         // ignored paths inline (with a (+N more) suffix) so the agent can see
@@ -1116,14 +1480,82 @@ function _buildIterationFeedback(recentHistory, errorEntries) {
     }
   }
 
-  if (problemLines.length === 0) {
+  if (problemLines.length === 0 && !hasArtifacts) {
     return '';
   }
 
-  return [
-    'Use these signals to avoid repeating the same failed approach:',
-    ...problemLines,
-  ].join('\n');
+  // Detect the longest *trailing* run of the same task identity in the
+  // problematic-iteration window. Trailing because the only thing that
+  // matters is "is the most recent stretch still the same task?" — a stale
+  // streak from earlier in the window is irrelevant once the task changed.
+  let sameTaskStreak = 0;
+  let stuckTaskId = '';
+  if (recentTasks.length > 0) {
+    const last = recentTasks[recentTasks.length - 1];
+    if (last) {
+      stuckTaskId = last;
+      for (let i = recentTasks.length - 1; i >= 0; i--) {
+        if (recentTasks[i] === last) {
+          sameTaskStreak++;
+        } else {
+          break;
+        }
+      }
+    }
+  }
+
+  const sections = [];
+  // The 3-iteration threshold matches the default `stallThreshold` so the
+  // hard-prefix and the eventual stall halt are aligned: the agent sees the
+  // warning one iteration before the stall detector fires, giving it a final
+  // chance to hand off cleanly via BLOCKED_HANDOFF rather than livelock.
+  if (sameTaskStreak >= 3 && stuckTaskId) {
+    const display = stuckTaskId.includes('|')
+      ? stuckTaskId.replace('|', ' — ')
+      : stuckTaskId;
+    sections.push(
+      [
+        '⚠ STUCK ON SAME TASK',
+        `You have failed to make progress on the same task ${sameTaskStreak} iterations in a row: ${display}.`,
+        'Stop retrying the same approach. Re-read the task spec, then either:',
+        '  1. Pick a materially different approach (different files, different invariant).',
+        '  2. If the task spec authorizes it (e.g. a "Stop and hand off if:" clause fired), emit <promise>BLOCKED_HANDOFF</promise> with a structured Blocker Note and stop. The runner will save it to .ralph/HANDOFF.md.',
+        '',
+      ].join('\n')
+    );
+  }
+
+  if (problemLines.length > 0) {
+    sections.push(
+      [
+        'Use these signals to avoid repeating the same failed approach:',
+        ...problemLines,
+      ].join('\n')
+    );
+  }
+
+  if (hasArtifacts) {
+    const artifactBlocks = blockerArtifacts.map((art) => {
+      const header = `### ${art.path}${art.truncated ? '  (truncated)' : ''}`;
+      // Code-fence the body so MDX-y artifacts (` ` `, `<promise>`) don't
+      // collide with the surrounding prompt markdown.
+      return [
+        header,
+        '```',
+        art.content,
+        '```',
+      ].join('\n');
+    });
+
+    sections.push(
+      [
+        'Prior-iteration blocker artifacts (read these BEFORE re-deriving the same diagnosis):',
+        ...artifactBlocks,
+      ].join('\n\n')
+    );
+  }
+
+  return sections.join('\n');
 }
 
 function _extractErrorForIteration(errorEntries, iteration) {
@@ -1358,4 +1790,7 @@ module.exports = {
   _failureFingerprint,
   _firstNonEmptyLine,
   _iterationIsStalled,
+  _extractBlockerNote,
+  _writeHandoff,
+  _detectBlockerArtifacts,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-and-loop",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "OpenSpec + Ralph Loop integration for iterative development with opencode",
   "main": "index.js",
   "bin": {

package/scripts/mini-ralph-cli.js

@@ -22,6 +22,11 @@
  *   --stall-threshold <n>      Halt after N consecutive no-op iterations (default: 3; 0 disables)
  *   --completion-promise <s>   Completion promise string (default: COMPLETE)
  *   --task-promise <s>         Task promise string (default: READY_FOR_NEXT_TASK)
+ *   --blocked-handoff-promise <s>
+ *                              Blocked-handoff promise string (default: BLOCKED_HANDOFF).
+ *                              Loop exits cleanly with `blocked_handoff` when the
+ *                              agent emits this tag and writes the agent's note
+ *                              to <ralph-dir>/HANDOFF.md.
  *   --no-commit                Suppress auto-commit
  *   --model <name>             Optional model override
  *   --verbose                  Verbose output
@@ -53,6 +58,7 @@ function parseArgs(argv) {
     stallThreshold: 3,
     completionPromise: 'COMPLETE',
     taskPromise: 'READY_FOR_NEXT_TASK',
+    blockedHandoffPromise: 'BLOCKED_HANDOFF',
     noCommit: false,
     model: '',
     verbose: false,
@@ -101,6 +107,9 @@ function parseArgs(argv) {
       case '--task-promise':
         opts.taskPromise = args[++i];
         break;
+      case '--blocked-handoff-promise':
+        opts.blockedHandoffPromise = args[++i];
+        break;
       case '--no-commit':
         opts.noCommit = true;
         break;
@@ -154,6 +163,8 @@ Options:
   --stall-threshold <n>      Halt after N consecutive no-op iterations (default: 3; 0 disables)
   --completion-promise <s>   Completion promise string
   --task-promise <s>         Task promise string
+  --blocked-handoff-promise <s>
+                             Blocked-handoff promise string (default: BLOCKED_HANDOFF)
   --no-commit                Suppress auto-commit
   --model <name>             Model override
   --verbose                  Verbose output
@@ -212,6 +223,7 @@ async function main() {
     stallThreshold: opts.stallThreshold,
     completionPromise: opts.completionPromise,
     taskPromise: opts.taskPromise,
+    blockedHandoffPromise: opts.blockedHandoffPromise,
     noCommit: opts.noCommit,
     model: opts.model,
     verbose: opts.verbose,

package/scripts/ralph-run.sh

@@ -333,6 +333,19 @@ validate_dependencies() {
     log_verbose "All dependencies validated"
 }
 
+should_auto_fix_artifacts() {
+    case "${RALPH_RUN_AUTO_FIX_ARTIFACTS:-}" in
+        1|true|TRUE|yes|YES)
+            return 0
+            ;;
+        0|false|FALSE|no|NO)
+            return 1
+            ;;
+    esac
+
+    [[ -t 0 ]]
+}
+
 ensure_artifacts_present() {
     local change_dir="$1"
     local change_name="$2"
@@ -351,6 +364,13 @@ ensure_artifacts_present() {
     fi
 
     log_info "Blocked artifacts detected: $blocked"
+    if ! should_auto_fix_artifacts; then
+        log_error "OpenSpec artifacts are blocked and this is a non-interactive run."
+        log_error 'Run `ralph-run init` or complete the artifacts manually, then rerun.'
+        log_error "Set RALPH_RUN_AUTO_FIX_ARTIFACTS=true to opt into opencode artifact repair in automation."
+        exit 1
+    fi
+
     log_info "Invoking opencode to complete missing artifacts..."
 
     opencode run "/opsx-ff $change_name" || true
@@ -651,15 +671,21 @@ validate_script_state() {
     
     log_verbose "Validating script state..."
     
-    local required_dirs=(
-        ".ralph"
-    )
-    
-    for dir in "${required_dirs[@]}"; do
-        if [[ ! -d "$change_dir/$dir" ]]; then
-            log_verbose "Required directory not found: $dir (will be created)"
-        fi
-    done
+    if [[ ! -d "$change_dir/.ralph" ]]; then
+        log_verbose "Required directory not found: .ralph (will be created)"
+    fi
+
+    if [[ ! -d "$change_dir/specs" ]]; then
+        log_error "Required directory not found: specs"
+        return 1
+    fi
+
+    local first_spec=""
+    first_spec=$(find "$change_dir/specs" -name "spec.md" -type f -print -quit 2>/dev/null || true)
+    if [[ -z "$first_spec" ]]; then
+        log_error "No spec.md files found under specs"
+        return 1
+    fi
     
     local required_files=(
         "tasks.md"
@@ -949,7 +975,20 @@ You are operating inside an automated loop. Follow these constraints EXACTLY:
 1. Implement exactly ONE pending task from the task list /opsx-apply shows you.
 2. After marking the task checkbox [x] on disk, output <promise>READY_FOR_NEXT_TASK</promise> on its own line.
 3. If and only if EVERY task checkbox is [x], output <promise>COMPLETE</promise> instead.
-4. Do not ask questions or wait for input. If blocked, output a short failure note describing the blocker and stop.
+4. Do not ask questions or wait for input. If you cannot make progress on the current task because an external decision is required (revert protected drift outside the change scope, file an out-of-scope refactor, escalate to a human reviewer, etc.), STOP and emit a structured handoff in this exact form:
+
+   ## Blocker Note
+   <one paragraph describing what is blocked>
+
+   ## Why
+   <one paragraph: which task spec clause / invariant fired, and what evidence (file paths, hashes, test names) supports the diagnosis>
+
+   ## Suggested Next Step
+   <one or two bullets the human can execute to unblock>
+
+   <promise>BLOCKED_HANDOFF</promise>
+
+   The runner will save this note to .ralph/HANDOFF.md and exit cleanly with reason=blocked_handoff. Do NOT keep retrying the same task; emit the handoff and stop. Do NOT emit BLOCKED_HANDOFF for transient errors that a retry could fix (network blips, tool-not-found that is fixable by an absolute path, etc.) — those are normal failures the loop will retry on its own.
 5. If the task is already satisfied by prior work, still flip the checkbox to [x] before emitting the promise.
 
 Do not create git commits yourself. The Ralph runner manages automatic task commits when auto-commit is enabled."
@@ -975,12 +1014,53 @@ Do not create git commits yourself. The Ralph runner manages automatic task comm
         mini_ralph_args+=("--quiet")
     fi
 
-    # Run the internal mini Ralph CLI and capture output
-    {
-        node "$MINI_RALPH_CLI" "${mini_ralph_args[@]}"
-    } > >(tee "$stdout_log") 2> >(tee "$stderr_log")
-    local node_exit_code=$?
-    wait
+    # Run the internal mini Ralph CLI and capture output.
+    #
+    # Avoid Bash process substitution here. macOS ships Bash 3.2, and under
+    # Bats' captured `run` wrapper a bare `wait` after `> >(tee ...)` can hang
+    # after the node child has already exited. Explicit FIFOs give us concrete
+    # tee PIDs to wait on and work consistently on macOS and Linux.
+    local stdout_pipe="$output_dir/ralph-stdout.pipe"
+    local stderr_pipe="$output_dir/ralph-stderr.pipe"
+    local node_exit_code=0
+    local tee_stdout_pid=""
+    local tee_stderr_pid=""
+    local had_errexit=false
+    case $- in
+        *e*)
+            had_errexit=true
+            set +e
+            ;;
+    esac
+
+    if mkfifo "$stdout_pipe" "$stderr_pipe" 2>/dev/null; then
+        tee "$stdout_log" < "$stdout_pipe" &
+        tee_stdout_pid=$!
+        tee "$stderr_log" < "$stderr_pipe" >&2 &
+        tee_stderr_pid=$!
+
+        node "$MINI_RALPH_CLI" "${mini_ralph_args[@]}" > "$stdout_pipe" 2> "$stderr_pipe"
+        node_exit_code=$?
+
+        wait "$tee_stdout_pid" 2>/dev/null || true
+        wait "$tee_stderr_pid" 2>/dev/null || true
+        rm -f "$stdout_pipe" "$stderr_pipe"
+    else
+        log_verbose "mkfifo unavailable; capturing output without live tee"
+        node "$MINI_RALPH_CLI" "${mini_ralph_args[@]}" > "$stdout_log" 2> "$stderr_log"
+        node_exit_code=$?
+        if [[ -s "$stdout_log" ]]; then
+            cat "$stdout_log"
+        fi
+        if [[ -s "$stderr_log" ]]; then
+            cat "$stderr_log" >&2
+        fi
+    fi
+
+    if [[ "$had_errexit" == true ]]; then
+        set -e
+    fi
+
     return $node_exit_code
 }
 
@@ -1159,6 +1239,7 @@ check_ralphified() {
 
 show_ralphify_warning() {
     local change_name="$1"
+    local preset_choice="${RALPH_RUN_RALPHIFY_CHOICE:-}"
 
     cat >&2 << 'WARNING_BOX'
 ┌─────────────────────────────────────────────────────────────────────┐
@@ -1173,16 +1254,29 @@ show_ralphify_warning() {
 └─────────────────────────────────────────────────────────────────────┘
 WARNING_BOX
 
+    if [[ -z "$preset_choice" && ! -t 0 ]]; then
+        log_info "Non-interactive environment detected. Continuing without Ralph Wiggum configuration."
+        log_info 'Run `ralph-run init` to configure Ralph Wiggum best practices before the next interactive run.'
+        return 0
+    fi
+
     while true; do
-        echo "" >&2
-        echo "Choose an option:" >&2
-        echo "  [A] Run ralphify init and redo the proposal, then continue" >&2
-        echo "  [C] Continue without init" >&2
-        echo "  [Q] Quit" >&2
-        printf "Enter choice: " >&2
-        if ! read -r choice; then
-            log_info "Non-interactive environment detected. Continuing without Ralph Wiggum configuration."
-            return 0
+        local choice=""
+        if [[ -n "$preset_choice" ]]; then
+            choice="$preset_choice"
+            preset_choice=""
+            log_info "Using RALPH_RUN_RALPHIFY_CHOICE=$choice"
+        else
+            echo "" >&2
+            echo "Choose an option:" >&2
+            echo "  [A] Run ralphify init and redo the proposal, then continue" >&2
+            echo "  [C] Continue without init" >&2
+            echo "  [Q] Quit" >&2
+            printf "Enter choice: " >&2
+            if ! read -r choice; then
+                log_info "Non-interactive environment detected. Continuing without Ralph Wiggum configuration."
+                return 0
+            fi
         fi
 
         case "$choice" in