spec-and-loop 3.3.0 → 3.3.3

package/OPENSPEC-RALPH-BP.md

@@ -21,6 +21,7 @@ Enforced rules:
 - Title is one outcome, not a list. If you need "and" twice, split.
 - Scope names files so the loop does not hunt.
 - `Done when` bullets are observable or runnable. No soft verbs (`ensure`, `support`, `validate`, `keep`) without attached evidence.
+- Verifier commands use the narrowest runnable command that proves the scoped change. Prefer a named test file, spec pattern, package script, or static check over a full-suite command.
 - `Stop and hand off if` gives the loop written permission to halt.
 
 ## Ordering
@@ -52,22 +53,55 @@ Rules:
 
 Split test: if the loop stopped halfway, would the repo be clean and reviewable? If yes and there's a verifier for each half, split. If no half is meaningful alone, don't split.
 
+## Surgical validation
+
+Task validators must be surgical and efficient so the loop spends tokens on implementation signal, not unrelated test noise.
+
+- Start every task with the cheapest verifier that proves the task's stated scope: direct unit test file, targeted node/browser spec, exact lint/typecheck command for touched files if available, schema validator, or focused `rg` assertion.
+- Verify command routing before writing it into `tasks.md`. If `npm test -- <pattern>` or similar still runs unrelated suites in that repo, write the direct runner command instead (for example, `pnpm exec vitest --config <config> --run <test-file>`).
+- Use broad gates (`npm test`, `pnpm typecheck`, `make all`, browser/e2e suites) only when the task owns repo-wide integration behavior, when they are recorded as pre-flight baselines, or in a final integrated quality-gate task.
+- If a broad gate is still required for a narrow task, pair it with explicit baseline classification: `` `<gate command>` exits 0, or failures match the pre-flight baseline with no new failures in this task's scope ``.
+- Prefer one focused verifier per task. Add a second verifier only when it proves a different artifact class, such as a schema validator plus one targeted unit test.
+
 ## Quality gates
 
 - A failing `Done when` check means the task is NOT done. No rationalization.
 - "Pre-existing" requires a before-baseline. Without one, any failure could be a regression.
 - First task in a chain that needs clean gates must be a pre-flight baseline that records gate output.
 - Explicitly distinguish known-broken validators (document and continue) from required-clean validators (hard stop). If only one is named, the loop generalizes permissively.
+- If a pre-flight baseline records a failing gate, later tasks MUST NOT require only a strict clean result for that same gate unless the task is intentionally responsible for fixing that baseline failure. Use one of these explicit forms:
+  - Baseline classification: `` `<gate command>` exits 0, or failures match the pre-flight baseline with no new failures in this task's scope ``
+  - Authorized cleanup: `` `<gate command>` exits 0 after fixing the named baseline failures in `<path/one.ts>` and `<path/two.ts>` ``
+  - Hard blocker: `` `<gate command>` exits 0; baseline failures are not allowed for this task ``
+- When strict clean-gate text conflicts with a failing pre-flight baseline and no classification/cleanup rule is written, `ralph-run` will warn the agent to stop with `BLOCKED_HANDOFF` instead of spending iterations on unauthorized cleanup.
+- When a task refers to a pre-flight baseline, or follows a completed pre-flight baseline task, but the matching `.ralph/baselines/<change>-<gate>.txt` artifact is missing, `ralph-run` will warn the agent to stop with `BLOCKED_HANDOFF` instead of treating undocumented failures as known.
+- A pre-flight baseline task must produce runner-recognizable artifacts, not just human-readable logs: baseline files must live under the change-local `.ralph/baselines/` directory that `ralph-run` reads, their filenames must identify the gate (`typecheck`, `lint`, `test`, etc.), and every captured gate file must end with a literal `EXIT=<integer>` line.
+- If a later task is allowed to repair baseline artifact compatibility, say so explicitly. Its `Scope:` must name the change-local `.ralph/baselines/` directory and its `Done when:` bullets must require the missing or malformed baseline files to be restored with parseable `EXIT=<integer>` footers. Without that authorization, baseline artifact repair remains an operator handoff, not product implementation work.
+- Authorized cleanup is intentionally narrow: the named files must be backticked, the cleanup is limited to compiler/lint-only fixes, and `ralph-run` gives the agent one repair attempt for those files on that task. If the gate still fails after that attempt, the next prompt tells the agent to hand off instead of retrying.
 
 Pre-flight template:
 ```markdown
 - [ ] **Pre-flight: record quality gate baselines**
-  - Scope: no code edits
+  - Scope: no code edits; writes only under `.ralph/baselines/`
   - Change: Capture current state of all gates later tasks require.
   - Done when:
-    - `.ralph/baselines/<change>-<gate>.txt` exists for each gate with full output
-    - `.ralph/baselines/<change>-readme.md` lists passing/failing gates and exact failing identifiers
-  - Stop and hand off if: any gate is nondeterministic across two runs.
+    - `.ralph/baselines/<gate>.txt` or `.ralph/baselines/<change>-<gate>.txt` exists for each gate with full output
+    - every captured gate file ends with a literal `EXIT=<integer>` line
+    - `.ralph/baselines/<change>-readme.md` lists passing/failing gates, exit codes, and exact failing identifiers
+  - Stop and hand off if: any gate is nondeterministic across two runs, or any captured baseline file is missing the `EXIT=<integer>` final line after retrying the capture command.
+```
+
+Baseline artifact compatibility repair template:
+```markdown
+- [ ] **Repair pre-flight baseline artifact compatibility**
+  - Scope: `.ralph/baselines/`, `tasks.md`
+  - Change: Restore or regenerate baseline artifacts so `ralph-run` can classify later quality-gate failures.
+  - Done when:
+    - change-local `.ralph/baselines/<gate>.txt` files exist for every gate referenced by later baseline-classified tasks
+    - every restored gate file ends with a literal `EXIT=<integer>` line
+    - the baseline readme records the source of any restored artifact and the exit code for each gate
+  - Stop and hand off if:
+    - the original gate output is missing, the original exit code cannot be recovered, or restoring the artifact would require rerunning a nondeterministic gate.
 ```
 
 ## Anti-patterns (do not do these)
@@ -80,6 +114,8 @@ Pre-flight template:
 - `Done when` that only checks unit tests when real behavior is end-to-end
 - Visual verification without splitting from code changes (context overflow risk)
 - "Maybe this, maybe that" wording in tasks or specs once loop starts
+- Repo-wide or slow validators for a narrow task when a focused verifier exists (`npm test`, `make all`, full browser/e2e suites)
+- Ambiguous package-manager forwarding such as `npm test -- event-schema` unless confirmed to execute only the intended test scope
 
 ## Examples
 
@@ -119,7 +155,7 @@ Pre-flight template:
   - Change: Harbor components registered once at boot, typed for TSX.
   - Done when:
     - `rg "registerHarbor" src` returns exactly one call site
-    - `npm test -- harbor-bootstrap` passes
+    - `npm exec vitest --run src/components/harbor-bootstrap.test.tsx` exits 0
   - Stop and hand off if: more than one registration site is required.
 ```
 
@@ -136,7 +172,7 @@ Pre-flight template:
   - Change: ReleaseCard renders timestamps through the shared helper.
   - Done when:
     - `rg "toLocaleDateString" src/components/ReleaseCard.tsx` returns no matches
-    - `npm test -- ReleaseCard` passes
+    - `npm exec vitest --run src/components/ReleaseCard.test.tsx` exits 0
   - Stop and hand off if: `formatDate` does not cover a required locale.
 ```
 

package/lib/mini-ralph/runner.js

@@ -50,6 +50,10 @@ const DEFAULTS = {
   // toward the streak because their signal is already surfaced via the
   // `Recent Loop Signals` feedback block.
   stallThreshold: 3,
+  // Opt-in continuation after a BLOCKED_HANDOFF only when the handoff note has
+  // explicit evidence for a safe, bounded resolution class.
+  autoResolveHandoffs: true,
+  autoResolveHandoffMaxPerRun: 6,
 };
 
 /**
@@ -80,6 +84,170 @@ function _iterationIsStalled(iterationSignals) {
   return true;
 }
 
+function _resolveAutoResolveHandoffConfig(options, existingState) {
+  const enabled = options.autoResolveHandoffs === true;
+  const maxPerRun =
+    Number.isInteger(options.autoResolveHandoffMaxPerRun) &&
+    options.autoResolveHandoffMaxPerRun > 0
+      ? options.autoResolveHandoffMaxPerRun
+      : DEFAULTS.autoResolveHandoffMaxPerRun;
+  const previous =
+    existingState &&
+    existingState.autoResolveHandoffs &&
+    typeof existingState.autoResolveHandoffs === 'object'
+      ? existingState.autoResolveHandoffs
+      : {};
+  const previousAttempts =
+    previous.attempts && typeof previous.attempts === 'object'
+      ? previous.attempts
+      : {};
+  const previousTotal = Number.isInteger(previous.totalAttempts)
+    ? previous.totalAttempts
+    : 0;
+
+  return {
+    enabled,
+    maxPerRun,
+    state: {
+      enabled,
+      maxPerRun,
+      totalAttempts: previousTotal,
+      attempts: Object.assign({}, previousAttempts),
+      lastDecision: previous.lastDecision || null,
+    },
+  };
+}
+
+function _handoffHasFocusedVerifierEvidence(note) {
+  if (!note) return false;
+  const text = String(note);
+  const mentionsFocusedVerifier =
+    /\bfocused\b[\s\S]{0,500}\b(verifier|command|test|spec|vitest)\b/i.test(text) ||
+    /\b(verifier|command|test|spec|vitest)\b[\s\S]{0,500}\bfocused\b/i.test(text);
+  const saysFocusedPasses =
+    /\b(passes?|passed|exits?\s+0|exit(?:ed)?\s+0|green)\b/i.test(text);
+  const saysBroadFails =
+    /\b(broad|full|required|suite|repo-wide)\b[\s\S]{0,500}\b(fails?|failed|red|non[-\s]?zero)\b/i.test(text) ||
+    /\b(fails?|failed|red|non[-\s]?zero)\b[\s\S]{0,500}\b(broad|full|required|suite|repo-wide)\b/i.test(text);
+  const saysFailuresAreUnrelated =
+    /\b(unrelated|pre[-\s]?existing|out[-\s]?of[-\s]?scope|known failures?|not introduced|baseline)\b/i.test(text);
+
+  return mentionsFocusedVerifier && saysFocusedPasses && saysBroadFails && saysFailuresAreUnrelated;
+}
+
+function _classifyAutoResolvableHandoff(blockerNote, baselineGateConflict) {
+  if (_handoffHasFocusedVerifierEvidence(blockerNote)) {
+    return {
+      className: 'verifier_narrowing',
+      summary: 'focused verifier passes while the broad verifier fails on unrelated/pre-existing failures',
+      allowedFiles: [],
+    };
+  }
+
+  if (
+    baselineGateConflict &&
+    baselineGateConflict.mode === 'authorized_cleanup' &&
+    baselineGateConflict.budgetUsed !== true &&
+    Array.isArray(baselineGateConflict.allowedFiles) &&
+    baselineGateConflict.allowedFiles.length > 0
+  ) {
+    return {
+      className: 'authorized_cleanup',
+      summary: 'task text explicitly authorizes one cleanup attempt for named files',
+      allowedFiles: baselineGateConflict.allowedFiles.slice(),
+    };
+  }
+
+  return null;
+}
+
+function _autoResolveHandoffBudgetKey(currentTaskMeta, className) {
+  const taskId =
+    currentTaskMeta && currentTaskMeta.number
+      ? currentTaskMeta.number
+      : currentTaskMeta && currentTaskMeta.description
+        ? currentTaskMeta.description
+        : 'unknown-task';
+  return `${taskId}:${className || 'unknown'}`;
+}
+
+function _decideAutoResolveHandoff(config, blockerNote, currentTaskMeta, baselineGateConflict) {
+  const disabledDecision = { allowed: false, reason: 'disabled', className: '', budgetKey: '' };
+  if (!config || config.enabled !== true) return disabledDecision;
+
+  const classification = _classifyAutoResolvableHandoff(blockerNote, baselineGateConflict);
+  if (!classification) {
+    return {
+      allowed: false,
+      reason: 'ambiguous_or_unsupported_handoff',
+      className: '',
+      budgetKey: '',
+    };
+  }
+
+  const budgetKey = _autoResolveHandoffBudgetKey(currentTaskMeta, classification.className);
+  const totalAttempts = Number.isInteger(config.state && config.state.totalAttempts)
+    ? config.state.totalAttempts
+    : 0;
+  const maxPerRun = Number.isInteger(config.maxPerRun)
+    ? config.maxPerRun
+    : DEFAULTS.autoResolveHandoffMaxPerRun;
+  const attempts = config.state && config.state.attempts ? config.state.attempts : {};
+
+  if (totalAttempts >= maxPerRun) {
+    return Object.assign({}, classification, {
+      allowed: false,
+      reason: 'global_budget_exhausted',
+      budgetKey,
+    });
+  }
+
+  if (attempts[budgetKey]) {
+    return Object.assign({}, classification, {
+      allowed: false,
+      reason: 'task_class_budget_exhausted',
+      budgetKey,
+    });
+  }
+
+  return Object.assign({}, classification, {
+    allowed: true,
+    reason: 'authorized',
+    budgetKey,
+  });
+}
+
+function _consumeAutoResolveHandoffBudget(config, decision, iteration) {
+  if (!config || !config.state || !decision || decision.allowed !== true || !decision.budgetKey) {
+    return null;
+  }
+
+  const attempts = Object.assign({}, config.state.attempts || {});
+  attempts[decision.budgetKey] = {
+    className: decision.className,
+    iteration,
+    attemptedAt: new Date().toISOString(),
+  };
+
+  const totalAttempts = (Number.isInteger(config.state.totalAttempts)
+    ? config.state.totalAttempts
+    : 0) + 1;
+
+  config.state = Object.assign({}, config.state, {
+    totalAttempts,
+    attempts,
+    lastDecision: {
+      className: decision.className,
+      reason: decision.reason,
+      budgetKey: decision.budgetKey,
+      iteration,
+      allowedFiles: decision.allowedFiles || [],
+    },
+  });
+
+  return config.state;
+}
+
 function _isFailedIteration(result) {
   if (!result || typeof result !== 'object') return false;
   if (result.signal !== null && result.signal !== undefined && result.signal !== '') {
@@ -462,6 +630,7 @@ async function run(opts) {
     const resumeIteration = _resolveStartIteration(existingState, options);
     const priorRunWasBlockedHandoff =
       existingState && existingState.exitReason === 'blocked_handoff';
+    const autoResolveHandoffs = _resolveAutoResolveHandoffConfig(options, existingState);
 
     if (options.verbose && resumeIteration > 1) {
       process.stderr.write(
@@ -488,6 +657,9 @@ async function run(opts) {
       resumeIteration > 1 && existingState && existingState.startedAt
         ? existingState.startedAt
         : nowIso;
+    let pendingDirtyPaths = _normalizePendingDirtyPaths(
+      existingState && existingState.pendingDirtyPaths
+    );
 
     state.init(ralphDir, {
       active: true,
@@ -508,6 +680,8 @@ async function run(opts) {
       completedAt: null,
       stoppedAt: null,
       exitReason: null,
+      pendingDirtyPaths,
+      autoResolveHandoffs: autoResolveHandoffs.state,
     });
     stateInitialized = true;
 
@@ -532,6 +706,20 @@ async function run(opts) {
           : [];
         const currentTask = _getCurrentTaskDescription(tasksBefore);
         const currentTaskMeta = _getCurrentTaskMeta(tasksBefore);
+        pendingDirtyPaths = _refreshPendingDirtyPaths(pendingDirtyPaths);
+        state.update(ralphDir, { pendingDirtyPaths });
+
+        if (
+          pendingDirtyPaths &&
+          !_samePendingTask(pendingDirtyPaths, currentTaskMeta, currentTask)
+        ) {
+          reporter.note(
+            _formatPendingDirtyPathsBlock(pendingDirtyPaths, currentTaskMeta, currentTask),
+            'error'
+          );
+          exitReason = 'pending_dirty_paths';
+          break;
+        }
 
         reporter.iterationStarted({
           iteration: iterationCount,
@@ -542,6 +730,7 @@ async function run(opts) {
         let result;
         let promptSize = null;
         let responseSize = { bytes: 0, chars: 0, tokens: 0 };
+        let baselineGateConflict = null;
 
         try {
           // Build the prompt for this iteration
@@ -558,6 +747,7 @@ async function run(opts) {
           // 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 fullHistory = history.read(ralphDir);
           const errorEntries = errors.readEntries(ralphDir, 3);
           const blockerArtifacts = _detectBlockerArtifacts(ralphDir, {
             repoRoot: process.cwd(),
@@ -570,6 +760,14 @@ async function run(opts) {
             errorEntries,
             blockerArtifacts,
           );
+          baselineGateConflict = _analyzeBaselineGateConflict(
+            ralphDir,
+            options.tasksFile,
+            currentTaskMeta,
+            fullHistory,
+          );
+          const baselineGateFeedback = _formatBaselineGateFeedback(baselineGateConflict);
+          const autoResolveHandoffFeedback = _buildAutoResolveHandoffFeedback(recentHistory);
 
           // Inject any pending context
           const pendingContext = context.consume(ralphDir);
@@ -577,10 +775,18 @@ async function run(opts) {
           const lessonsSection = lessons.inject(ralphDir, { limit: 15 });
           const promptSections = [renderedPrompt];
 
+          if (baselineGateFeedback) {
+            promptSections.push(`## Baseline Gate Conflict\n\n${baselineGateFeedback}`);
+          }
+
           if (iterationFeedback) {
             promptSections.push(`## Recent Loop Signals\n\n${iterationFeedback}`);
           }
 
+          if (autoResolveHandoffFeedback) {
+            promptSections.push(`## Auto-Resolve Handoff\n\n${autoResolveHandoffFeedback}`);
+          }
+
           if (lessonsSection) {
             promptSections.push(lessonsSection);
           }
@@ -674,6 +880,24 @@ async function run(opts) {
         const blockerNote = hasBlockedHandoff
           ? _extractBlockerNote(outputText, blockedHandoffPromise)
           : '';
+        const autoResolveHandoffDecision = hasBlockedHandoff
+          ? _decideAutoResolveHandoff(
+              autoResolveHandoffs,
+              blockerNote,
+              currentTaskMeta,
+              baselineGateConflict,
+            )
+          : null;
+        if (autoResolveHandoffDecision && autoResolveHandoffDecision.allowed) {
+          const nextAutoResolveState = _consumeAutoResolveHandoffBudget(
+            autoResolveHandoffs,
+            autoResolveHandoffDecision,
+            iterationCount,
+          );
+          if (nextAutoResolveState) {
+            state.update(ralphDir, { autoResolveHandoffs: nextAutoResolveState });
+          }
+        }
         const tasksAfter = options.tasksMode && options.tasksFile
           ? tasks.parseTasks(options.tasksFile)
           : [];
@@ -701,13 +925,42 @@ async function run(opts) {
           result.filesChanged.length > 0 &&
           (hasCompletion || (options.tasksMode && hasTask))
         ) {
+          const filesToStage = _buildAutoCommitAllowlist(
+            _mergePathLists(result.filesChanged, pendingDirtyPaths ? pendingDirtyPaths.files : []),
+            completedTasks,
+            options.tasksFile
+          );
           commitResult = _autoCommit(iterationCount, {
             completedTasks,
-            filesToStage: _buildAutoCommitAllowlist(result.filesChanged, completedTasks, options.tasksFile),
+            filesToStage,
             tasksFile: options.tasksFile,
             verbose: options.verbose,
             reporter,
           });
+          if (commitResult.committed && pendingDirtyPaths) {
+            pendingDirtyPaths = _remainingPendingDirtyPathsAfterCommit(
+              pendingDirtyPaths,
+              commitResult.anomaly
+            );
+            state.update(ralphDir, { pendingDirtyPaths });
+          }
+        }
+
+        if (
+          !commitResult.committed &&
+          Array.isArray(result.filesChanged) &&
+          result.filesChanged.length > 0 &&
+          (_isFailedIteration(result) || hasBlockedHandoff)
+        ) {
+          pendingDirtyPaths = _recordPendingDirtyPaths(pendingDirtyPaths, {
+            iteration: iterationCount,
+            reason: hasBlockedHandoff ? 'blocked_handoff' : 'failed_iteration',
+            task: currentTask,
+            taskNumber: currentTaskMeta.number,
+            taskDescription: currentTaskMeta.description,
+            files: result.filesChanged,
+          });
+          state.update(ralphDir, { pendingDirtyPaths });
         }
 
         // Record iteration in history after commit handling so operator-visible
@@ -727,11 +980,30 @@ async function run(opts) {
           signal: result.signal || '',
           failureStage: result.failureStage || '',
           completedTasks: completedTasks.map((task) => task.fullDescription || task.description),
+          ...(autoResolveHandoffDecision
+            ? {
+                autoResolveHandoffAttempted: autoResolveHandoffDecision.allowed === true,
+                autoResolveHandoffClass: autoResolveHandoffDecision.className || '',
+                autoResolveHandoffReason: autoResolveHandoffDecision.reason || '',
+                autoResolveHandoffBudgetKey: autoResolveHandoffDecision.budgetKey || '',
+                autoResolveHandoffAllowedFiles: autoResolveHandoffDecision.allowedFiles || [],
+              }
+            : {}),
           commitAttempted: commitResult.attempted,
           commitCreated: commitResult.committed,
           commitAnomaly: commitResult.anomaly ? commitResult.anomaly.message : '',
           commitAnomalyType: commitResult.anomaly ? commitResult.anomaly.type : '',
           protectedArtifacts: commitResult.anomaly ? commitResult.anomaly.protectedArtifacts || [] : [],
+          ...(baselineGateConflict
+            ? {
+                baselineGateConflictMode: baselineGateConflict.mode,
+                baselineGateRepairAllowedFiles: baselineGateConflict.allowedFiles || [],
+                baselineGateRepairAttempted: _baselineGateRepairAttempted(
+                  baselineGateConflict,
+                  result.filesChanged || []
+                ),
+              }
+            : {}),
           ...(commitResult.anomaly && commitResult.anomaly.ignoredPaths && commitResult.anomaly.ignoredPaths.length > 0
             ? { ignoredPaths: commitResult.anomaly.ignoredPaths }
             : {}),
@@ -824,9 +1096,21 @@ async function run(opts) {
           reporter.note(
             handoffPath
               ? `agent emitted ${blockedHandoffPromise}; blocker note saved to ${handoffPath}.`
-              : `agent emitted ${blockedHandoffPromise}; halting (HANDOFF.md write failed; see stderr).`,
+              : `agent emitted ${blockedHandoffPromise}; HANDOFF.md write failed (see stderr).`,
             'warn'
           );
+          if (autoResolveHandoffDecision && autoResolveHandoffDecision.allowed) {
+            reporter.note(
+              `auto-resolve handoffs: continuing once for ${autoResolveHandoffDecision.className} (${autoResolveHandoffDecision.budgetKey}).`,
+              'warn'
+            );
+            if (options.verbose) {
+              process.stderr.write(
+                `[mini-ralph] auto-resolve handoff consumed budget key ${autoResolveHandoffDecision.budgetKey}; continuing.\n`
+              );
+            }
+            continue;
+          }
           if (options.verbose) {
             process.stderr.write(
               `[mini-ralph] ${blockedHandoffPromise} detected at iteration ${iterationCount}; halting.\n`
@@ -915,6 +1199,145 @@ function _containsPromise(text, promiseName) {
     .some((line) => line.trim() === expectedTag);
 }
 
+function _normalizePendingDirtyPaths(pending) {
+  if (!pending || typeof pending !== 'object') return null;
+  const files = _mergePathLists(pending.files || pending.paths || []);
+  if (files.length === 0) return null;
+
+  return {
+    iteration: typeof pending.iteration === 'number' ? pending.iteration : null,
+    reason: pending.reason || 'blocked_handoff',
+    task: pending.task || '',
+    taskNumber: pending.taskNumber || '',
+    taskDescription: pending.taskDescription || '',
+    files,
+    recordedAt: pending.recordedAt || new Date().toISOString(),
+  };
+}
+
+function _recordPendingDirtyPaths(existing, update) {
+  const normalized = _normalizePendingDirtyPaths({
+    iteration: update && typeof update.iteration === 'number' ? update.iteration : null,
+    reason: update && update.reason ? update.reason : 'blocked_handoff',
+    task: update && update.task ? update.task : '',
+    taskNumber: update && update.taskNumber ? update.taskNumber : '',
+    taskDescription: update && update.taskDescription ? update.taskDescription : '',
+    files: _mergePathLists(
+      existing && existing.files ? existing.files : [],
+      update && update.files ? update.files : []
+    ),
+    recordedAt: update && update.recordedAt ? update.recordedAt : new Date().toISOString(),
+  });
+
+  return normalized;
+}
+
+function _remainingPendingDirtyPathsAfterCommit(pending, anomaly) {
+  const normalized = _normalizePendingDirtyPaths(pending);
+  if (!normalized) return null;
+
+  const ignoredPaths = anomaly && Array.isArray(anomaly.ignoredPaths)
+    ? anomaly.ignoredPaths.map(_repoRelativePath).filter(Boolean)
+    : [];
+  if (ignoredPaths.length === 0) return null;
+
+  const ignoredSet = new Set(ignoredPaths);
+  const files = normalized.files.filter((file) => ignoredSet.has(file));
+  if (files.length === 0) return null;
+  return Object.assign({}, normalized, { files });
+}
+
+function _refreshPendingDirtyPaths(pending) {
+  const normalized = _normalizePendingDirtyPaths(pending);
+  if (!normalized) return null;
+
+  const dirtyPaths = _currentDirtyPathSet();
+  if (!dirtyPaths) return normalized;
+  const files = normalized.files.filter((file) => dirtyPaths.has(file));
+  if (files.length === 0) return null;
+
+  return Object.assign({}, normalized, { files });
+}
+
+function _samePendingTask(pending, currentTaskMeta, currentTask) {
+  if (!pending) return true;
+  const currentNumber = currentTaskMeta && currentTaskMeta.number ? currentTaskMeta.number : '';
+  const currentDescription = currentTaskMeta && currentTaskMeta.description ? currentTaskMeta.description : '';
+  const currentFull = currentTask || '';
+
+  if (pending.taskNumber && currentNumber) {
+    return pending.taskNumber === currentNumber;
+  }
+
+  if (pending.taskDescription && currentDescription) {
+    return pending.taskDescription === currentDescription;
+  }
+
+  return Boolean(pending.task && currentFull && pending.task === currentFull);
+}
+
+function _formatPendingDirtyPathsBlock(pending, currentTaskMeta, currentTask) {
+  const currentStamp = currentTaskMeta && currentTaskMeta.number
+    ? `${currentTaskMeta.number} ${currentTaskMeta.description || ''}`.trim()
+    : (currentTask || 'the current task');
+  const pendingStamp = pending.taskNumber
+    ? `${pending.taskNumber} ${pending.taskDescription || ''}`.trim()
+    : (pending.task || 'a prior blocked handoff');
+  const files = (pending.files || []).slice(0, 8);
+  const extra = (pending.files || []).length - files.length;
+  const fileLines = files.map((file) => `  - ${file}`).join('\n');
+  const suffix = extra > 0 ? `\n  - (+${extra} more)` : '';
+
+  return [
+    `pending dirty paths from ${pending.reason || 'blocked_handoff'} iteration ${pending.iteration || 'unknown'} remain unresolved.`,
+    `Prior task: ${pendingStamp}`,
+    `Current task: ${currentStamp}`,
+    'Resolve the prior patch before Ralph can safely continue: commit it with the same task, revert it, or move it to a separate change.',
+    'Pending paths:',
+    `${fileLines}${suffix}`,
+  ].join('\n');
+}
+
+function _currentDirtyPathSet() {
+  try {
+    const output = childProcess.execFileSync('git', ['status', '--porcelain'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const paths = new Set();
+    for (const line of output.split('\n')) {
+      for (const file of _parseGitStatusPaths(line)) {
+        if (file) paths.add(file);
+      }
+    }
+    return paths;
+  } catch (_) {
+    return null;
+  }
+}
+
+function _parseGitStatusPaths(line) {
+  if (!line || typeof line !== 'string') return [];
+  const rawPath = line.slice(3).trim();
+  if (!rawPath) return [];
+  if (rawPath.includes(' -> ')) {
+    return rawPath.split(' -> ').map(_stripGitStatusQuotes).filter(Boolean);
+  }
+  return [_stripGitStatusQuotes(rawPath)].filter(Boolean);
+}
+
+function _stripGitStatusQuotes(value) {
+  if (!value) return '';
+  const trimmed = value.trim();
+  if (!(trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+    return trimmed;
+  }
+  return trimmed
+    .slice(1, -1)
+    .replace(/\\"/g, '"')
+    .replace(/\\\\/g, '\\');
+}
+
 /**
  * Validate required options and throw descriptive errors.
  *
@@ -1163,6 +1586,19 @@ function _filterGitignored(paths, cwd) {
   }
 }
 
+function _mergePathLists(...lists) {
+  const merged = new Set();
+  for (const list of lists) {
+    for (const file of list || []) {
+      const relativeFile = _repoRelativePath(file);
+      if (relativeFile) {
+        merged.add(relativeFile);
+      }
+    }
+  }
+  return Array.from(merged);
+}
+
 /**
  * Build the explicit per-iteration git staging allowlist.
  *
@@ -1558,6 +1994,430 @@ function _buildIterationFeedback(recentHistory, errorEntries, blockerArtifacts)
   return sections.join('\n');
 }
 
+function _buildAutoResolveHandoffFeedback(recentHistory) {
+  if (!Array.isArray(recentHistory) || recentHistory.length === 0) return '';
+
+  const entry = recentHistory
+    .slice()
+    .reverse()
+    .find((item) => item && item.autoResolveHandoffAttempted === true);
+
+  if (!entry) return '';
+
+  const className = entry.autoResolveHandoffClass || 'unknown';
+  const lines = [
+    `The previous iteration emitted BLOCKED_HANDOFF, but auto-resolution is enabled and spent its bounded attempt for ${className}.`,
+    'You have exactly one continuation attempt for this task/blocker class. Do not broaden task scope, do not repair unrelated snapshots or UI behavior, and do not keep retrying if the evidence does not hold.',
+  ];
+
+  if (className === 'verifier_narrowing') {
+    lines.push(
+      'Allowed action: if the handoff explicitly names a focused verifier that passes and a broad verifier that fails only on unrelated/pre-existing failures, update only the current task verifier from the broad command to that focused command, run the focused command once, and complete the task only if it passes. If the focused command is absent, ambiguous, or fails, emit BLOCKED_HANDOFF instead of retrying.'
+    );
+  } else if (className === 'authorized_cleanup') {
+    const files = Array.isArray(entry.autoResolveHandoffAllowedFiles)
+      ? entry.autoResolveHandoffAllowedFiles.filter(Boolean)
+      : [];
+    lines.push(
+      `Allowed action: make one cleanup attempt only in the task-authorized file list${files.length > 0 ? ` (${files.join(', ')})` : ''}. If the gate still fails, emit BLOCKED_HANDOFF instead of continuing.`
+    );
+  } else {
+    lines.push(
+      'Allowed action: continue only if the blocker evidence remains explicit and within the runner-approved safe class; otherwise emit BLOCKED_HANDOFF.'
+    );
+  }
+
+  return lines.join('\n');
+}
+
+function _buildBaselineGateFeedback(ralphDir, tasksFile, currentTaskMeta, recentHistory) {
+  return _formatBaselineGateFeedback(
+    _analyzeBaselineGateConflict(ralphDir, tasksFile, currentTaskMeta, recentHistory)
+  );
+}
+
+function _analyzeBaselineGateConflict(ralphDir, tasksFile, currentTaskMeta, recentHistory) {
+  if (!ralphDir || !tasksFile || !currentTaskMeta || !currentTaskMeta.description) {
+    return null;
+  }
+
+  const taskBlock = _extractCurrentTaskBlock(tasksFile, currentTaskMeta);
+  if (!taskBlock) return null;
+
+  const strictGates = _detectStrictCleanGates(taskBlock);
+  if (strictGates.length === 0) return null;
+
+  const recordedBaselines = _detectRecordedBaselineGates(ralphDir);
+  const missingBaselines = _detectMissingBaselineGates(
+    strictGates,
+    recordedBaselines,
+    taskBlock,
+    tasksFile
+  );
+
+  if (missingBaselines.length > 0) {
+    return {
+      mode: 'missing_baseline',
+      conflicts: [],
+      missingBaselines,
+      allowedFiles: [],
+      budgetUsed: false,
+    };
+  }
+
+  const failingBaselines = recordedBaselines.filter((gate) => gate.exitCode !== 0);
+  if (failingBaselines.length === 0) return null;
+
+  const baselineByGate = new Map(failingBaselines.map((gate) => [gate.name, gate]));
+  const conflicts = strictGates
+    .map((gate) => ({ gate, baseline: baselineByGate.get(gate.name) }))
+    .filter((item) => item.baseline);
+
+  if (conflicts.length === 0) return null;
+
+  const cleanup = _detectAuthorizedBaselineCleanup(taskBlock);
+  if (cleanup.allowedFiles.length > 0) {
+    return {
+      mode: 'authorized_cleanup',
+      conflicts,
+      allowedFiles: cleanup.allowedFiles,
+      budgetUsed: _baselineGateRepairBudgetUsed(recentHistory, currentTaskMeta, cleanup.allowedFiles),
+    };
+  }
+
+  if (_taskExplicitlyHandlesBaselineFailures(taskBlock)) {
+    return {
+      mode: 'baseline_classification',
+      conflicts,
+      allowedFiles: [],
+      budgetUsed: false,
+    };
+  }
+
+  return {
+    mode: 'missing_policy',
+    conflicts,
+    allowedFiles: [],
+    budgetUsed: false,
+  };
+}
+
+function _formatBaselineGateFeedback(conflict) {
+  const conflicts = Array.isArray(conflict && conflict.conflicts) ? conflict.conflicts : [];
+  const missingBaselines = Array.isArray(conflict && conflict.missingBaselines)
+    ? conflict.missingBaselines
+    : [];
+
+  if (!conflict || (conflicts.length === 0 && missingBaselines.length === 0)) {
+    return '';
+  }
+
+  const conflictLines = conflicts.map(({ gate, baseline }) =>
+    `- ${gate.command}: baseline ${baseline.file} exits ${baseline.exitCode}.`
+  );
+  const missingLines = missingBaselines.map((gate) =>
+    `- ${gate.command}: no matching baseline artifact found under .ralph/baselines.`
+  );
+
+  if (conflict.mode === 'missing_baseline') {
+    return [
+      'The current task uses a strict clean quality gate and the task plan indicates a pre-flight baseline should exist, but the matching baseline artifact is missing.',
+      'Do not classify failures as pre-existing or spend an implementation iteration trying to satisfy an impossible task contract.',
+      'emit BLOCKED_HANDOFF and ask the operator to rerun or restore the pre-flight baseline artifact, or update the task spec to authorize a different gate policy.',
+      '',
+      ...missingLines,
+    ].join('\n');
+  }
+
+  if (conflict.mode === 'authorized_cleanup') {
+    if (conflict.budgetUsed) {
+      return [
+        'The current task explicitly authorized cleanup for baseline gate failures, but its one repair attempt has already been used.',
+        'Do not keep iterating on cleanup or broaden the edit scope.',
+        'If the gate is still failing, emit BLOCKED_HANDOFF with the remaining failing identifiers and ask for either a broader cleanup task or a task-spec change.',
+        '',
+        `Authorized cleanup files: ${conflict.allowedFiles.join(', ')}`,
+        ...conflictLines,
+      ].join('\n');
+    }
+
+    return [
+      'The current task explicitly authorizes cleanup for baseline gate failures in named files.',
+      'You have exactly one repair attempt for this task. Limit edits to compiler/lint-only fixes in the authorized files; do not change behavior or edit other files for this cleanup.',
+      'If this attempt does not clear the gate, emit BLOCKED_HANDOFF instead of continuing to retry.',
+      '',
+      `Authorized cleanup files: ${conflict.allowedFiles.join(', ')}`,
+      ...conflictLines,
+    ].join('\n');
+  }
+
+  if (conflict.mode === 'baseline_classification') {
+    return [
+      'The current task has strict quality-gate checks, and matching pre-flight baselines are already failing.',
+      'The task text appears to authorize baseline classification, so do not repair unrelated baseline failures unless the task explicitly names those files.',
+      'Complete the task only if the current run has no new failures beyond the named baseline failures.',
+      '',
+      ...conflictLines,
+    ].join('\n');
+  }
+
+  return [
+    'The current task requires a clean gate that already has a failing pre-flight baseline, but the task text does not say whether baseline-matching failures may be classified.',
+    'Do not spend iterations repairing unrelated files outside the current task scope.',
+    'If the only remaining gate failures match the baseline, emit BLOCKED_HANDOFF with a task-spec correction request: either allow baseline classification for this gate, or explicitly authorize the named out-of-scope repair.',
+    '',
+    ...conflictLines,
+  ].join('\n');
+}
+
+function _extractCurrentTaskBlock(tasksFile, currentTaskMeta) {
+  const fs = require('fs');
+  if (!tasksFile || !fs.existsSync(tasksFile)) return '';
+
+  const lines = fs.readFileSync(tasksFile, 'utf8').split(/\r?\n/);
+  const taskHeader = /^-\s+\[[ x/]\]\s+(.+)$/;
+  const targetNumber = currentTaskMeta.number || '';
+  const targetDescription = (currentTaskMeta.description || '').trim();
+  let start = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(taskHeader);
+    if (!match) continue;
+
+    const fullDescription = match[1].trim();
+    const numMatch = fullDescription.match(/^(\d+\.\d+)\s+(.+)$/);
+    const number = numMatch ? numMatch[1] : '';
+    const description = (numMatch ? numMatch[2] : fullDescription).trim();
+
+    if (
+      (targetNumber && number === targetNumber) ||
+      (!targetNumber && description === targetDescription) ||
+      (targetNumber && description === targetDescription)
+    ) {
+      start = i;
+      break;
+    }
+  }
+
+  if (start === -1) return '';
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (taskHeader.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+
+  return lines.slice(start, end).join('\n');
+}
+
+function _detectStrictCleanGates(taskBlock) {
+  if (!taskBlock) return [];
+
+  const gates = [
+    {
+      name: 'typecheck',
+      command: 'pnpm typecheck',
+      pattern: /`?pnpm\s+typecheck`?[^\n]*(?:exits?|returns?)\s+0/i,
+    },
+    {
+      name: 'lint',
+      command: 'pnpm lint',
+      pattern: /`?pnpm\s+lint`?[^\n]*(?:exits?|returns?)\s+0/i,
+    },
+    {
+      name: 'test',
+      command: 'pnpm test',
+      pattern: /`?pnpm\s+test`?[^\n]*(?:exits?|returns?)\s+0/i,
+    },
+  ];
+
+  return gates.filter((gate) => gate.pattern.test(taskBlock));
+}
+
+function _detectFailingBaselineGates(ralphDir) {
+  return _detectRecordedBaselineGates(ralphDir).filter((gate) => gate.exitCode !== 0);
+}
+
+function _detectRecordedBaselineGates(ralphDir) {
+  const fs = require('fs');
+  const fsPath = require('path');
+  const baselinesDir = fsPath.join(ralphDir, 'baselines');
+  if (!fs.existsSync(baselinesDir) || !fs.statSync(baselinesDir).isDirectory()) {
+    return [];
+  }
+
+  const gates = [];
+  for (const name of fs.readdirSync(baselinesDir)) {
+    if (!/\.txt$/i.test(name)) continue;
+
+    const gateName = _gateNameFromBaselineFile(name);
+    if (!gateName) continue;
+
+    const file = fsPath.join(baselinesDir, name);
+    const tail = _readFileTail(file, 16384);
+    const exitMatch = tail.match(/(?:^|\n)EXIT=(\d+)(?:\n|$)/);
+    if (!exitMatch) continue;
+
+    const exitCode = Number(exitMatch[1]);
+    if (!Number.isInteger(exitCode)) continue;
+
+    gates.push({ name: gateName, file: fsPath.join('baselines', name), exitCode });
+  }
+
+  const priority = { typecheck: 1, lint: 2, test: 3 };
+  return gates.sort((a, b) =>
+    (priority[a.name] || 99) - (priority[b.name] || 99) ||
+    a.file.localeCompare(b.file)
+  );
+}
+
+function _detectMissingBaselineGates(strictGates, recordedBaselines, taskBlock, tasksFile) {
+  if (!Array.isArray(strictGates) || strictGates.length === 0) return [];
+
+  const expectsBaseline =
+    _taskExplicitlyHandlesBaselineFailures(taskBlock) ||
+    _completedPreflightBaselineExists(tasksFile);
+
+  if (!expectsBaseline) return [];
+
+  const recordedNames = new Set((recordedBaselines || []).map((gate) => gate.name));
+  return strictGates.filter((gate) => !recordedNames.has(gate.name));
+}
+
+function _completedPreflightBaselineExists(tasksFile) {
+  const fs = require('fs');
+  if (!tasksFile || !fs.existsSync(tasksFile)) return false;
+
+  const lines = fs.readFileSync(tasksFile, 'utf8').split(/\r?\n/);
+  return lines.some((line) =>
+    /^-\s+\[x\]\s+.*\bpre-?flight\b.*\bbaselines?\b/i.test(line)
+  );
+}
+
+function _gateNameFromBaselineFile(fileName) {
+  const normalized = fileName.toLowerCase();
+  if (/(^|[-_.])typecheck([-_.]|\.|$)/.test(normalized)) return 'typecheck';
+  if (/(^|[-_.])lint([-_.]|\.|$)/.test(normalized)) return 'lint';
+  if (/(^|[-_.])test([-_.]|\.|$)/.test(normalized)) return 'test';
+  return '';
+}
+
+function _readFileTail(file, maxBytes) {
+  const fs = require('fs');
+  let fd = null;
+  try {
+    const stat = fs.statSync(file);
+    const length = Math.min(stat.size, maxBytes);
+    const offset = Math.max(0, stat.size - length);
+    const buffer = Buffer.alloc(length);
+    fd = fs.openSync(file, 'r');
+    fs.readSync(fd, buffer, 0, length, offset);
+    return buffer.toString('utf8');
+  } catch {
+    return '';
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // Ignore close failures while building best-effort feedback.
+      }
+    }
+  }
+}
+
+function _taskExplicitlyHandlesBaselineFailures(taskBlock) {
+  return /\bbaseline\b/i.test(taskBlock) &&
+    /\b(match|matches|matching|classif(?:y|ied|ication)|pre-existing|preexisting|no new failures?)\b/i.test(taskBlock);
+}
+
+function _detectAuthorizedBaselineCleanup(taskBlock) {
+  if (!taskBlock || !/\b(authori[sz]ed cleanup|after fixing|fixing the named baseline failures?)\b/i.test(taskBlock)) {
+    return { allowedFiles: [] };
+  }
+
+  const allowedFiles = [];
+  const seen = new Set();
+  const backtickPattern = /`([^`]+)`/g;
+  let match;
+
+  while ((match = backtickPattern.exec(taskBlock)) !== null) {
+    const candidate = match[1].trim();
+    if (!_looksLikeCleanupPath(candidate)) continue;
+
+    const normalized = candidate.replace(/\\/g, '/');
+    if (seen.has(normalized)) continue;
+
+    seen.add(normalized);
+    allowedFiles.push(normalized);
+  }
+
+  return { allowedFiles };
+}
+
+function _looksLikeCleanupPath(value) {
+  if (!value || /\s/.test(value)) return false;
+  if (/^(pnpm|npm|yarn|node|gtimeout|timeout|rg|git)(\s|$)/i.test(value)) return false;
+  if (/^--?/.test(value)) return false;
+  if (/[*{}]/.test(value)) return false;
+  return value.includes('/') || /\.[A-Za-z0-9]+$/.test(value);
+}
+
+function _baselineGateRepairBudgetUsed(recentHistory, currentTaskMeta, allowedFiles) {
+  if (!Array.isArray(recentHistory) || recentHistory.length === 0) return false;
+
+  return recentHistory.some((entry) => {
+    if (!_historyEntryMatchesTask(entry, currentTaskMeta)) return false;
+    if (entry.baselineGateRepairAttempted === true) return true;
+
+    return _baselineGateRepairAttempted(
+      { mode: 'authorized_cleanup', allowedFiles },
+      entry.filesChanged || []
+    );
+  });
+}
+
+function _baselineGateRepairAttempted(conflict, filesChanged) {
+  if (
+    !conflict ||
+    conflict.mode !== 'authorized_cleanup' ||
+    !Array.isArray(conflict.allowedFiles) ||
+    conflict.allowedFiles.length === 0 ||
+    !Array.isArray(filesChanged) ||
+    filesChanged.length === 0
+  ) {
+    return false;
+  }
+
+  return _pathsIntersect(conflict.allowedFiles, filesChanged);
+}
+
+function _historyEntryMatchesTask(entry, currentTaskMeta) {
+  if (!entry || !currentTaskMeta) return false;
+
+  const currentNumber = currentTaskMeta.number || '';
+  const currentDescription = currentTaskMeta.description || '';
+
+  if (currentNumber && entry.taskNumber === currentNumber) return true;
+  if (!currentNumber && currentDescription && entry.taskDescription === currentDescription) return true;
+
+  return false;
+}
+
+function _pathsIntersect(left, right) {
+  const normalizedLeft = new Set((left || []).map(_normalizeComparablePath));
+  return (right || []).some((pathValue) => normalizedLeft.has(_normalizeComparablePath(pathValue)));
+}
+
+function _normalizeComparablePath(pathValue) {
+  return String(pathValue || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '');
+}
+
 function _extractErrorForIteration(errorEntries, iteration) {
   if (!Array.isArray(errorEntries) || errorEntries.length === 0) return null;
 
@@ -1769,12 +2629,36 @@ module.exports = {
   _validateOptions,
   _autoCommit,
   _buildAutoCommitAllowlist,
+  _mergePathLists,
+  _normalizePendingDirtyPaths,
+  _recordPendingDirtyPaths,
+  _remainingPendingDirtyPathsAfterCommit,
+  _refreshPendingDirtyPaths,
+  _samePendingTask,
+  _currentDirtyPathSet,
   _filterGitignored,
   _resolveStartIteration,
   _completedTaskDelta,
   _formatAutoCommitMessage,
   _truncateSubjectSummary,
   _buildIterationFeedback,
+  _buildAutoResolveHandoffFeedback,
+  _resolveAutoResolveHandoffConfig,
+  _handoffHasFocusedVerifierEvidence,
+  _classifyAutoResolvableHandoff,
+  _decideAutoResolveHandoff,
+  _consumeAutoResolveHandoffBudget,
+  _buildBaselineGateFeedback,
+  _analyzeBaselineGateConflict,
+  _formatBaselineGateFeedback,
+  _extractCurrentTaskBlock,
+  _detectStrictCleanGates,
+  _detectFailingBaselineGates,
+  _detectRecordedBaselineGates,
+  _detectMissingBaselineGates,
+  _detectAuthorizedBaselineCleanup,
+  _baselineGateRepairBudgetUsed,
+  _baselineGateRepairAttempted,
   _extractErrorForIteration,
   _getCurrentTaskDescription,
   _getCurrentTaskMeta,

package/lib/mini-ralph/status.js

@@ -60,6 +60,31 @@ function render(ralphDir, tasksFile) {
     lines.push(`Exit reason:   ${loopState.exitReason}`);
   }
 
+  const pendingDirtyPaths = _pendingDirtyPaths(loopState);
+  if (pendingDirtyPaths) {
+    lines.push('');
+    lines.push('--- Pending Dirty Paths ---');
+    lines.push(`  Reason: ${pendingDirtyPaths.reason || 'blocked_handoff'}`);
+    if (pendingDirtyPaths.iteration) {
+      lines.push(`  From iteration: ${pendingDirtyPaths.iteration}`);
+    }
+    const task = pendingDirtyPaths.taskNumber
+      ? `${pendingDirtyPaths.taskNumber} ${pendingDirtyPaths.taskDescription || ''}`.trim()
+      : (pendingDirtyPaths.task || '');
+    if (task) {
+      lines.push(`  Prior task: ${task}`);
+    }
+    const files = pendingDirtyPaths.files.slice(0, 10);
+    for (const file of files) {
+      lines.push(`  - ${file}`);
+    }
+    if (pendingDirtyPaths.files.length > files.length) {
+      lines.push(`  - (+${pendingDirtyPaths.files.length - files.length} more)`);
+    }
+    lines.push('  Resolve before continuing: commit with the same task, revert, or move to a separate change.');
+    lines.push('-'.repeat(50));
+  }
+
   const latestCommitAnomaly = _latestCommitAnomaly(history.recent(ralphDir, 20));
   if (latestCommitAnomaly) {
     lines.push(`Commit issue:  ${latestCommitAnomaly.commitAnomaly}`);
@@ -186,6 +211,16 @@ function _promptSummary(loopState) {
   return '';
 }
 
+function _pendingDirtyPaths(loopState) {
+  const pending = loopState && loopState.pendingDirtyPaths;
+  if (!pending || typeof pending !== 'object') return null;
+  const files = Array.isArray(pending.files)
+    ? pending.files.filter((file) => typeof file === 'string' && file.trim())
+    : [];
+  if (files.length === 0) return null;
+  return Object.assign({}, pending, { files });
+}
+
 /**
  * Try to find a tasks file path from loop state.
  *

package/package.json

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

package/scripts/mini-ralph-cli.js

@@ -27,6 +27,10 @@
  *                              Loop exits cleanly with `blocked_handoff` when the
  *                              agent emits this tag and writes the agent's note
  *                              to <ralph-dir>/HANDOFF.md.
+ *   --auto-resolve-handoffs   Enable bounded continuation attempts for
+ *                              explicit, safe BLOCKED_HANDOFF classes
+ *   --no-auto-resolve-handoffs
+ *                              Disable auto-resolution even when enabled by env
  *   --no-commit                Suppress auto-commit
  *   --model <name>             Optional model override
  *   --verbose                  Verbose output
@@ -44,6 +48,11 @@ const miniRalph = require('../lib/mini-ralph/index');
 // Argument parsing
 // ---------------------------------------------------------------------------
 
+function _envFlagDefaultEnabled(value) {
+  if (value === undefined) return true;
+  return !/^(0|false|no|off)$/i.test(String(value || '').trim());
+}
+
 function parseArgs(argv) {
   const args = argv.slice(2);
   const opts = {
@@ -59,6 +68,7 @@ function parseArgs(argv) {
     completionPromise: 'COMPLETE',
     taskPromise: 'READY_FOR_NEXT_TASK',
     blockedHandoffPromise: 'BLOCKED_HANDOFF',
+    autoResolveHandoffs: _envFlagDefaultEnabled(process.env.RALPH_AUTO_RESOLVE_HANDOFFS),
     noCommit: false,
     model: '',
     verbose: false,
@@ -110,6 +120,12 @@ function parseArgs(argv) {
       case '--blocked-handoff-promise':
         opts.blockedHandoffPromise = args[++i];
         break;
+      case '--auto-resolve-handoffs':
+        opts.autoResolveHandoffs = true;
+        break;
+      case '--no-auto-resolve-handoffs':
+        opts.autoResolveHandoffs = false;
+        break;
       case '--no-commit':
         opts.noCommit = true;
         break;
@@ -165,6 +181,8 @@ Options:
   --task-promise <s>         Task promise string
   --blocked-handoff-promise <s>
                              Blocked-handoff promise string (default: BLOCKED_HANDOFF)
+  --auto-resolve-handoffs    Enable bounded continuation for explicit safe handoffs
+  --no-auto-resolve-handoffs Disable bounded continuation for explicit safe handoffs
   --no-commit                Suppress auto-commit
   --model <name>             Model override
   --verbose                  Verbose output
@@ -224,6 +242,7 @@ async function main() {
     completionPromise: opts.completionPromise,
     taskPromise: opts.taskPromise,
     blockedHandoffPromise: opts.blockedHandoffPromise,
+    autoResolveHandoffs: opts.autoResolveHandoffs,
     noCommit: opts.noCommit,
     model: opts.model,
     verbose: opts.verbose,
@@ -251,4 +270,11 @@ async function main() {
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  _envFlagDefaultEnabled,
+  _parseArgs: parseArgs,
+};

package/scripts/ralph-run.sh

@@ -129,6 +129,7 @@ resolve_ralph_command() {
 CHANGE_NAME=""
 MAX_ITERATIONS=""
 NO_COMMIT=false
+AUTO_RESOLVE_HANDOFFS=""
 SHOW_STATUS=false
 SHOW_VERSION=false
 ADD_CONTEXT=""
@@ -186,6 +187,9 @@ OPTIONS:
     --change <name>          Specify the OpenSpec change to execute (default: auto-detect)
     --max-iterations <n>     Maximum iterations for Ralph loop (default: 50)
     --no-commit              Suppress automatic git commits during the loop
+    --auto-resolve-handoffs  Enable bounded continuation for explicit safe handoffs
+    --no-auto-resolve-handoffs
+                             Disable bounded continuation for explicit safe handoffs
     --verbose, -v            Enable verbose mode for debugging
     --quiet                  Suppress the per-iteration progress stream
     --version                Print the version and exit
@@ -232,6 +236,14 @@ parse_arguments() {
                 NO_COMMIT=true
                 shift
                 ;;
+            --auto-resolve-handoffs)
+                AUTO_RESOLVE_HANDOFFS=true
+                shift
+                ;;
+            --no-auto-resolve-handoffs)
+                AUTO_RESOLVE_HANDOFFS=false
+                shift
+                ;;
             --verbose|-v)
                 VERBOSE=true
                 shift
@@ -1006,6 +1018,12 @@ Do not create git commits yourself. The Ralph runner manages automatic task comm
         mini_ralph_args+=("--no-commit")
     fi
 
+    if [[ "$AUTO_RESOLVE_HANDOFFS" == true ]]; then
+        mini_ralph_args+=("--auto-resolve-handoffs")
+    elif [[ "$AUTO_RESOLVE_HANDOFFS" == false ]]; then
+        mini_ralph_args+=("--no-auto-resolve-handoffs")
+    fi
+
     if [[ "$VERBOSE" == true ]]; then
         mini_ralph_args+=("--verbose")
     fi
@@ -1182,6 +1200,7 @@ rules:
   tasks:
     - Use the task template from OPENSPEC-RALPH-BP.md
     - Each task has one dominant outcome and one verification cluster
+    - Use surgical, scope-targeted validation commands; reserve broad gates for pre-flight baselines or final integration tasks
     - Include explicit stop-and-hand-off conditions
   design:
     - Do not leave core policy choices unresolved
@@ -1203,6 +1222,7 @@ Before generating any OpenSpec artifacts, you MUST:
 - Read `openspec/OPENSPEC-RALPH-BP.md` (Ralph Wiggum authoring guide)
 - Verify proposals against the Ralph authoring checklist
 - Ensure tasks use the task template with objective done-when conditions
+- Ensure each task uses the narrowest verifier that proves its scope; use broad gates only with baseline classification or final integration tasks
 - Include explicit stop-and-hand-off conditions in every task
 RALPH_AGENTS
         log_verbose "Updated $agents_file with Ralph Wiggum compliance section"
@@ -1311,7 +1331,7 @@ WARNING_BOX
                 fi
                 local ralph_guidance=""
                 if [[ -f "$bp_file" ]]; then
-                    ralph_guidance=" When creating artifacts, read ${bp_file} and follow the Ralph Wiggum task template and authoring checklist. Ensure the proposal includes explicit scope, non-goals, first-rollout boundaries, and capabilities that map to Ralph-friendly tasks. Ensure tasks use the task template with objective done-when conditions and explicit stop-and-hand-off conditions. Do NOT restore or copy from any .bak backup files - write fresh artifacts from scratch."
+                    ralph_guidance=" When creating artifacts, read ${bp_file} and follow the Ralph Wiggum task template and authoring checklist. Ensure the proposal includes explicit scope, non-goals, first-rollout boundaries, and capabilities that map to Ralph-friendly tasks. Ensure tasks use the task template with objective done-when conditions, surgical scope-targeted verifier commands, and explicit stop-and-hand-off conditions. Prefer direct test-file or validator commands over full-suite commands; reserve broad gates for pre-flight baselines or final integration tasks. Do NOT restore or copy from any .bak backup files - write fresh artifacts from scratch."
                 fi
 
                 log_info "Invoking opencode to regenerate proposal and tasks with Ralph Wiggum best practices..."