spec-and-loop 2.0.1 → 2.1.1

package/lib/mini-ralph/runner.js

@@ -11,7 +11,8 @@
  * isolated in a thin invoker that can be swapped in tests.
  */
 
-const { execFileSync } = require('child_process');
+const childProcess = require('child_process');
+const path = require('path');
 const state = require('./state');
 const history = require('./history');
 const context = require('./context');
@@ -30,6 +31,74 @@ const DEFAULTS = {
   verbose: false,
 };
 
+function _isFailedIteration(result) {
+  if (!result || typeof result !== 'object') return false;
+  if (result.signal !== null && result.signal !== undefined && result.signal !== '') {
+    return true;
+  }
+  return result.exitCode !== 0;
+}
+
+function _wasSuccessfulIteration(result) {
+  return !_isFailedIteration(result);
+}
+
+function _failureStageForError(err) {
+  if (!err || typeof err !== 'object') {
+    return 'invoke_contract';
+  }
+
+  if (err.failureStage) {
+    return err.failureStage;
+  }
+
+  return 'invoke_contract';
+}
+
+function _errorText(err) {
+  if (!err) return 'Unknown fatal iteration failure';
+
+  if (err.stack && typeof err.stack === 'string' && err.stack.trim()) {
+    return err.stack;
+  }
+
+  if (err.message && typeof err.message === 'string' && err.message.trim()) {
+    return err.message;
+  }
+
+  return String(err);
+}
+
+function _appendFatalIterationFailure(ralphDir, entry) {
+  errors.append(ralphDir, {
+    iteration: entry.iteration,
+    task: entry.task,
+    exitCode: entry.exitCode,
+    signal: entry.signal || '',
+    failureStage: entry.failureStage || '',
+    stderr: entry.stderr || '',
+    stdout: entry.stdout || '',
+  });
+
+  history.append(ralphDir, {
+    iteration: entry.iteration,
+    duration: entry.duration,
+    completionDetected: false,
+    taskDetected: false,
+    toolUsage: [],
+    filesChanged: [],
+    exitCode: entry.exitCode,
+    signal: entry.signal || '',
+    failureStage: entry.failureStage || '',
+    completedTasks: [],
+    commitAttempted: false,
+    commitCreated: false,
+    commitAnomaly: '',
+    commitAnomalyType: '',
+    protectedArtifacts: [],
+  });
+}
+
 /**
  * Run the iteration loop.
  *
@@ -41,164 +110,246 @@ async function run(opts) {
   _validateOptions(options);
 
   const ralphDir = options.ralphDir;
+  const runLock = state.acquireRunLock(ralphDir, {
+    tasksFile: options.tasksFile || null,
+    promptFile: options.promptFile || null,
+    tasksMode: options.tasksMode,
+  });
   const maxIterations = options.maxIterations;
   const minIterations = options.minIterations;
   const completionPromise = options.completionPromise;
   const taskPromise = options.taskPromise;
 
-  // Determine starting iteration — resume from prior state if it exists,
-  // otherwise start fresh at 1.
-  const existingState = state.read(ralphDir);
-  const resumeIteration = _resolveStartIteration(existingState, options);
+  let stateInitialized = false;
+  let iterationCount = 0;
+  let completed = false;
+  let exitReason = 'max_iterations';
 
-  if (options.verbose && resumeIteration > 1) {
-    process.stderr.write(
-      `[mini-ralph] resuming from iteration ${resumeIteration} ` +
-      `(${resumeIteration - 1} prior iteration(s) preserved)\n`
-    );
-  }
+  try {
 
-  // Initialize state file for this run, preserving history count if resuming.
-  state.init(ralphDir, {
-    active: true,
-    iteration: resumeIteration,
-    minIterations,
-    maxIterations,
-    completionPromise,
-    taskPromise,
-    tasksMode: options.tasksMode,
-    tasksFile: options.tasksFile || null,
-    promptFile: options.promptFile || null,
-    promptTemplate: options.promptTemplate || null,
-    noCommit: options.noCommit,
-    model: options.model || '',
-    startedAt: new Date().toISOString(),
-    resumedAt: resumeIteration > 1 ? new Date().toISOString() : null,
-  });
+    // Determine starting iteration — resume from prior state if it exists,
+    // otherwise start fresh at 1.
+    const existingState = state.read(ralphDir);
+    const resumeIteration = _resolveStartIteration(existingState, options);
 
-  // Synchronize .ralph/ralph-tasks.md symlink to the OpenSpec tasks.md so the
-  // loop engine always operates on the source-of-truth task file.
-  if (options.tasksMode && options.tasksFile) {
-    tasks.syncLink(ralphDir, options.tasksFile);
-  }
+    if (options.verbose && resumeIteration > 1) {
+      process.stderr.write(
+        `[mini-ralph] resuming from iteration ${resumeIteration} ` +
+        `(${resumeIteration - 1} prior iteration(s) preserved)\n`
+      );
+    }
 
-  let iterationCount = resumeIteration - 1;
-  let completed = false;
-  let exitReason = 'max_iterations';
+    // Initialize state file for this run, preserving history count if resuming.
+    state.init(ralphDir, {
+      active: true,
+      iteration: resumeIteration,
+      minIterations,
+      maxIterations,
+      completionPromise,
+      taskPromise,
+      tasksMode: options.tasksMode,
+      tasksFile: options.tasksFile || null,
+      promptFile: options.promptFile || null,
+      promptTemplate: options.promptTemplate || null,
+      noCommit: options.noCommit,
+      model: options.model || '',
+      startedAt: new Date().toISOString(),
+      resumedAt: resumeIteration > 1 ? new Date().toISOString() : null,
+      completedAt: null,
+      stoppedAt: null,
+      exitReason: null,
+    });
+    stateInitialized = true;
 
-  while (iterationCount < maxIterations) {
-    iterationCount++;
+    // Synchronize .ralph/ralph-tasks.md symlink to the OpenSpec tasks.md so the
+    // loop engine always operates on the source-of-truth task file.
+    if (options.tasksMode && options.tasksFile) {
+      tasks.syncLink(ralphDir, options.tasksFile);
+    }
 
-    // Update state with current iteration
-    state.update(ralphDir, { iteration: iterationCount, active: true });
+    iterationCount = resumeIteration - 1;
 
-    // Build the prompt for this iteration
-    const renderedPrompt = await prompt.render(options, iterationCount);
-    const errorContent = errors.read(ralphDir, 3);
-    const iterationFeedback = _buildIterationFeedback(history.recent(ralphDir, 3), errorContent);
+    try {
+      while (iterationCount < maxIterations) {
+        iterationCount++;
 
-    // Inject any pending context
-    const pendingContext = context.consume(ralphDir);
-    const promptSections = [renderedPrompt];
+        // Update state with current iteration
+        state.update(ralphDir, { iteration: iterationCount, active: true });
 
-    if (iterationFeedback) {
-      promptSections.push(`## Recent Loop Signals\n\n${iterationFeedback}`);
-    }
+        const iterStart = Date.now();
+        const tasksBefore = options.tasksMode && options.tasksFile
+          ? tasks.parseTasks(options.tasksFile)
+          : [];
+        const currentTask = _getCurrentTaskDescription(tasksBefore);
 
-    if (pendingContext) {
-      promptSections.push(`## Injected Context\n\n${pendingContext}`);
-    }
+        let result;
 
-    const finalPrompt = promptSections.join('\n\n');
+        try {
+          // Build the prompt for this iteration
+          let renderedPrompt;
+          try {
+            renderedPrompt = await prompt.render(options, iterationCount);
+          } catch (err) {
+            err.failureStage = err.failureStage || 'prompt_render';
+            throw err;
+          }
 
-    const iterStart = Date.now();
-    const tasksBefore = options.tasksMode && options.tasksFile
-      ? tasks.parseTasks(options.tasksFile)
-      : [];
+          const errorEntries = errors.readEntries(ralphDir, 3);
+          const iterationFeedback = _buildIterationFeedback(history.recent(ralphDir, 3), errorEntries);
 
-    // Invoke OpenCode
-    const result = await invoker.invoke({
-      prompt: finalPrompt,
-      model: options.model,
-      noCommit: options.noCommit,
-      verbose: options.verbose,
-      ralphDir,
-    });
+          // Inject any pending context
+          const pendingContext = context.consume(ralphDir);
+          const promptSections = [renderedPrompt];
 
-    const duration = Date.now() - iterStart;
-
-    // Detect promises in output
-    const outputText = result.stdout || '';
-    const hasCompletion = _containsPromise(outputText, completionPromise);
-    const hasTask = _containsPromise(outputText, taskPromise);
-    const tasksAfter = options.tasksMode && options.tasksFile
-      ? tasks.parseTasks(options.tasksFile)
-      : [];
-    const completedTasks = _completedTaskDelta(tasksBefore, tasksAfter);
-
-    // Record iteration in history
-    history.append(ralphDir, {
-      iteration: iterationCount,
-      duration,
-      completionDetected: hasCompletion,
-      taskDetected: hasTask,
-      toolUsage: result.toolUsage || [],
-      filesChanged: result.filesChanged || [],
-      exitCode: result.exitCode,
-      completedTasks: completedTasks.map((task) => task.fullDescription || task.description),
-    });
+          if (iterationFeedback) {
+            promptSections.push(`## Recent Loop Signals\n\n${iterationFeedback}`);
+          }
 
-    if (result.exitCode !== 0) {
-      const currentTask = _getCurrentTaskDescription(tasksBefore);
-      errors.append(ralphDir, {
-        iteration: iterationCount,
-        task: currentTask,
-        exitCode: result.exitCode,
-        stderr: result.stderr || '',
-        stdout: result.stdout || '',
-      });
-    }
+          if (pendingContext) {
+            promptSections.push(`## Injected Context\n\n${pendingContext}`);
+          }
 
-    // Auto-commit only for successful task/completion iterations.
-    if (
-      !options.noCommit &&
-      result.exitCode === 0 &&
-      result.filesChanged &&
-      result.filesChanged.length > 0 &&
-      (hasCompletion || (options.tasksMode && hasTask))
-    ) {
-      _autoCommit(iterationCount, {
-        completedTasks,
-        verbose: options.verbose,
-      });
-    }
+          const finalPrompt = promptSections.join('\n\n');
+
+          // Invoke OpenCode
+          try {
+            result = await invoker.invoke({
+              prompt: finalPrompt,
+              model: options.model,
+              noCommit: options.noCommit,
+              verbose: options.verbose,
+              ralphDir,
+            });
+          } catch (err) {
+            err.failureStage = err.failureStage || 'invoke_start';
+            throw err;
+          }
+        } catch (err) {
+          _appendFatalIterationFailure(ralphDir, {
+            iteration: iterationCount,
+            task: currentTask,
+            duration: Date.now() - iterStart,
+            exitCode: null,
+            signal: '',
+            failureStage: _failureStageForError(err),
+            stderr: _errorText(err),
+            stdout: '',
+          });
+          throw err;
+        }
+
+        const duration = Date.now() - iterStart;
+
+        // Detect promises in output
+        const outputText = result.stdout || '';
+        const iterationSucceeded = _wasSuccessfulIteration(result);
+        const hasCompletion = iterationSucceeded && _containsPromise(outputText, completionPromise);
+        const hasTask = iterationSucceeded && _containsPromise(outputText, taskPromise);
+        const tasksAfter = options.tasksMode && options.tasksFile
+          ? tasks.parseTasks(options.tasksFile)
+          : [];
+        const completedTasks = _completedTaskDelta(tasksBefore, tasksAfter);
+
+        let commitResult = { attempted: false, committed: false, anomaly: null };
+
+        if (_isFailedIteration(result)) {
+          errors.append(ralphDir, {
+            iteration: iterationCount,
+            task: currentTask,
+            exitCode: result.exitCode,
+            signal: result.signal || '',
+            failureStage: result.failureStage || '',
+            stderr: result.stderr || '',
+            stdout: result.stdout || '',
+          });
+        }
+
+        // Auto-commit only for successful task/completion iterations.
+        if (
+          !options.noCommit &&
+          _wasSuccessfulIteration(result) &&
+          result.filesChanged &&
+          result.filesChanged.length > 0 &&
+          (hasCompletion || (options.tasksMode && hasTask))
+        ) {
+          commitResult = _autoCommit(iterationCount, {
+            completedTasks,
+            filesToStage: _buildAutoCommitAllowlist(result.filesChanged, completedTasks, options.tasksFile),
+            tasksFile: options.tasksFile,
+            verbose: options.verbose,
+          });
+        }
 
-    // Check completion condition (must also satisfy minIterations)
-    if (hasCompletion && iterationCount >= minIterations) {
-      completed = true;
-      exitReason = 'completion_promise';
-      break;
+        // Record iteration in history after commit handling so operator-visible
+        // anomalies are captured alongside the task/completion signal.
+        history.append(ralphDir, {
+          iteration: iterationCount,
+          duration,
+          completionDetected: hasCompletion,
+          taskDetected: hasTask,
+          toolUsage: result.toolUsage || [],
+          filesChanged: result.filesChanged || [],
+          exitCode: result.exitCode,
+          signal: result.signal || '',
+          failureStage: result.failureStage || '',
+          completedTasks: completedTasks.map((task) => task.fullDescription || task.description),
+          commitAttempted: commitResult.attempted,
+          commitCreated: commitResult.committed,
+          commitAnomaly: commitResult.anomaly ? commitResult.anomaly.message : '',
+          commitAnomalyType: commitResult.anomaly ? commitResult.anomaly.type : '',
+          protectedArtifacts: commitResult.anomaly ? commitResult.anomaly.protectedArtifacts || [] : [],
+        });
+
+        // Check completion condition (must also satisfy minIterations)
+        if (hasCompletion && iterationCount >= minIterations) {
+          completed = true;
+          exitReason = 'completion_promise';
+          break;
+        }
+
+        // In tasks mode, task promise just continues the loop
+        if (options.tasksMode && hasTask) {
+          // Continue to next iteration
+          continue;
+        }
+      }
+    } catch (err) {
+      exitReason = 'fatal_error';
+      throw err;
     }
 
-    // In tasks mode, task promise just continues the loop
-    if (options.tasksMode && hasTask) {
-      // Continue to next iteration
-      continue;
+    if (completed) {
+      _cleanupCompletedErrors(ralphDir, options.verbose);
     }
-  }
 
-  if (completed) {
-    const archivePath = errors.archive(ralphDir);
-    if (archivePath && options.verbose) {
-      process.stderr.write(`[mini-ralph] errors archived to ${archivePath}\n`);
+    return { completed, iterations: iterationCount, exitReason };
+  } finally {
+    if (stateInitialized) {
+      _finalizeRunState(ralphDir, { completed, exitReason });
     }
-    errors.clear(ralphDir);
+    state.releaseRunLock(ralphDir, runLock);
   }
+}
 
-  // Mark loop as inactive
-  state.update(ralphDir, { active: false, completedAt: new Date().toISOString() });
+function _finalizeRunState(ralphDir, outcome) {
+  const now = new Date().toISOString();
+
+  if (outcome && outcome.completed) {
+    state.update(ralphDir, {
+      active: false,
+      completedAt: now,
+      stoppedAt: null,
+      exitReason: outcome.exitReason || 'completion_promise',
+    });
+    return;
+  }
 
-  return { completed, iterations: iterationCount, exitReason };
+  state.update(ralphDir, {
+    active: false,
+    completedAt: null,
+    stoppedAt: now,
+    exitReason: outcome && outcome.exitReason ? outcome.exitReason : 'stopped',
+  });
 }
 
 /**
@@ -210,7 +361,11 @@ async function run(opts) {
  */
 function _containsPromise(text, promiseName) {
   if (!text || !promiseName) return false;
-  return text.includes(`<promise>${promiseName}</promise>`);
+
+  const expectedTag = `<promise>${promiseName}</promise>`;
+  return text
+    .split(/\r?\n/)
+    .some((line) => line.trim() === expectedTag);
 }
 
 /**
@@ -247,38 +402,66 @@ function _validateOptions(options) {
  * @param {number} iteration
  * @param {object} opts
  * @param {Array<object>} [opts.completedTasks]
+ * @param {Array<string>} [opts.filesToStage]
  * @param {boolean} [opts.verbose]
  */
 function _autoCommit(iteration, opts = {}) {
-  const { completedTasks = [], verbose = false } = opts;
+  const { completedTasks = [], filesToStage = [], tasksFile = null, verbose = false } = opts;
   const message = _formatAutoCommitMessage(iteration, completedTasks);
 
   if (!message) {
     if (verbose) {
       process.stderr.write('[mini-ralph] auto-commit skipped: no completed tasks detected\n');
     }
-    return;
+    return { attempted: false, committed: false, anomaly: null };
+  }
+
+  if (!Array.isArray(filesToStage) || filesToStage.length === 0) {
+    if (verbose) {
+      process.stderr.write('[mini-ralph] auto-commit skipped: no iteration files to stage\n');
+    }
+    return { attempted: false, committed: false, anomaly: null };
+  }
+
+  const protectedArtifacts = _detectProtectedCommitArtifacts(filesToStage, tasksFile);
+  if (protectedArtifacts.length > 0) {
+    const anomaly = {
+      type: 'protected_artifacts',
+      message:
+        'Auto-commit blocked: loop-managed commits cannot include protected OpenSpec artifacts: ' +
+        protectedArtifacts.join(', '),
+      protectedArtifacts,
+    };
+
+    process.stderr.write(`[mini-ralph] warning: ${anomaly.message}\n`);
+    return { attempted: true, committed: false, anomaly };
   }
 
   try {
-    execFileSync('git', ['add', '-A'], {
+    childProcess.execFileSync('git', ['add', '--', ...filesToStage], {
       stdio: verbose ? 'inherit' : ['pipe', 'pipe', 'pipe'],
       encoding: 'utf8',
     });
 
-    const stagedFiles = execFileSync('git', ['diff', '--cached', '--name-only'], {
+    const stagedFiles = childProcess.execFileSync('git', ['diff', '--cached', '--name-only'], {
       stdio: ['pipe', 'pipe', 'pipe'],
       encoding: 'utf8',
     });
 
     if (!stagedFiles.trim()) {
+      const anomaly = {
+        type: 'nothing_staged',
+        message: 'Auto-commit failed: nothing was staged after git add',
+      };
+
+      process.stderr.write(`[mini-ralph] warning: ${anomaly.message}\n`);
       if (verbose) {
         process.stderr.write('[mini-ralph] auto-commit skipped: nothing staged\n');
       }
-      return;
+      return { attempted: true, committed: false, anomaly };
     }
 
-    execFileSync('git', ['commit', '-m', message], {
+    childProcess.execFileSync('git', ['commit', '-m', message], {
       stdio: verbose ? 'inherit' : ['pipe', 'pipe', 'pipe'],
       encoding: 'utf8',
     });
@@ -286,12 +469,44 @@ function _autoCommit(iteration, opts = {}) {
     if (verbose) {
       process.stderr.write(`[mini-ralph] auto-committed: ${message}\n`);
     }
+    return { attempted: true, committed: true, anomaly: null };
   } catch (err) {
-    // Auto-commit is best-effort; don't fail the loop if commit fails
-    if (verbose) {
-      process.stderr.write(`[mini-ralph] auto-commit skipped: ${err.message}\n`);
+    const anomaly = {
+      type: 'commit_failed',
+      message: `Auto-commit failed: ${_gitErrorMessage(err)}`,
+    };
+
+    process.stderr.write(`[mini-ralph] warning: ${anomaly.message}\n`);
+    return { attempted: true, committed: false, anomaly };
+  }
+}
+
+/**
+ * Build the explicit per-iteration git staging allowlist.
+ *
+ * @param {Array<string>} filesChanged
+ * @param {Array<object>} completedTasks
+ * @param {string|null|undefined} tasksFile
+ * @returns {Array<string>}
+ */
+function _buildAutoCommitAllowlist(filesChanged, completedTasks, tasksFile) {
+  const allowlist = new Set();
+
+  for (const file of filesChanged || []) {
+    const relativeFile = _repoRelativePath(file);
+    if (relativeFile) {
+      allowlist.add(relativeFile);
+    }
+  }
+
+  if (Array.isArray(completedTasks) && completedTasks.length > 0 && tasksFile) {
+    const relativeTasksFile = _repoRelativePath(tasksFile);
+    if (relativeTasksFile) {
+      allowlist.add(relativeTasksFile);
     }
   }
+
+  return Array.from(allowlist);
 }
 
 /**
@@ -342,7 +557,7 @@ function _formatAutoCommitMessage(iteration, completedTasks) {
  * @param {Array<object>} recentHistory
  * @returns {string}
  */
-function _buildIterationFeedback(recentHistory, errorContent) {
+function _buildIterationFeedback(recentHistory, errorEntries) {
   if (!Array.isArray(recentHistory) || recentHistory.length === 0) {
     return '';
   }
@@ -352,10 +567,18 @@ function _buildIterationFeedback(recentHistory, errorContent) {
   for (const entry of recentHistory) {
     const issues = [];
 
-    if (entry.exitCode !== 0) {
+    if (entry.signal) {
+      issues.push(`opencode exited via signal ${entry.signal}`);
+    } else if (entry.failureStage) {
+      issues.push(`iteration aborted during ${entry.failureStage}`);
+    } else if (entry.exitCode !== 0) {
       issues.push(`opencode exited with code ${entry.exitCode}`);
     }
 
+    if (entry.commitAnomaly) {
+      issues.push(`commit anomaly: ${entry.commitAnomaly}`);
+    }
+
     if (!entry.filesChanged || entry.filesChanged.length === 0) {
       issues.push('no files changed');
     }
@@ -367,10 +590,16 @@ function _buildIterationFeedback(recentHistory, errorContent) {
     if (issues.length > 0) {
       let line = `- Iteration ${entry.iteration}: ${issues.join('; ')}.`;
 
-      if (entry.exitCode !== 0 && errorContent) {
-        const errorDetails = _extractErrorForIteration(errorContent, entry.iteration);
+      if (_isFailedIteration(entry) && errorEntries) {
+        const errorDetails = _extractErrorForIteration(errorEntries, entry.iteration);
         if (errorDetails) {
           line += '\n  Error output:';
+          if (errorDetails.signal) {
+            line += `\n  signal: ${errorDetails.signal}`;
+          }
+          if (errorDetails.failureStage) {
+            line += `\n  failure stage: ${errorDetails.failureStage}`;
+          }
           if (errorDetails.stderr) {
             line += `\n  ${errorDetails.stderr}`;
           }
@@ -394,30 +623,24 @@ function _buildIterationFeedback(recentHistory, errorContent) {
   ].join('\n');
 }
 
-function _extractErrorForIteration(errorContent, iteration) {
-  if (!errorContent) return null;
-
-  const entries = errorContent.split(/^---$/m).filter((e) => e.trim());
-
-  for (const entry of entries) {
-    if (!entry.includes(`Iteration: ${iteration}`)) continue;
+function _extractErrorForIteration(errorEntries, iteration) {
+  if (!Array.isArray(errorEntries) || errorEntries.length === 0) return null;
 
-    let stderr = '';
-    let stdout = '';
+  const match = errors.matchIteration(errorEntries, iteration);
+  if (!match) return null;
 
-    const stderrMatch = entry.match(/### stderr\n([\s\S]*?)(?=\n### stdout|$)/);
-    const stdoutMatch = entry.match(/### stdout\n([\s\S]*?)$/);
+  let stderr = match.stderr || '';
+  let stdout = match.stdout || '';
 
-    if (stderrMatch) stderr = stderrMatch[1].trim();
-    if (stdoutMatch) stdout = stdoutMatch[1].trim();
+  if (stderr.length > 2000) stderr = stderr.substring(0, 2000) + '...';
+  if (stdout.length > 500) stdout = stdout.substring(0, 500) + '...';
 
-    if (stderr.length > 2000) stderr = stderr.substring(0, 2000) + '...';
-    if (stdout.length > 500) stdout = stdout.substring(0, 500) + '...';
-
-    return { stderr, stdout };
-  }
-
-  return null;
+  return {
+    stderr,
+    stdout,
+    signal: match.signal || '',
+    failureStage: match.failureStage || '',
+  };
 }
 
 function _getCurrentTaskDescription(tasksBefore) {
@@ -427,12 +650,95 @@ function _getCurrentTaskDescription(tasksBefore) {
   return 'N/A';
 }
 
+function _cleanupCompletedErrors(ralphDir, verbose) {
+  let archivePath = null;
+
+  try {
+    archivePath = errors.archive(ralphDir);
+    if (archivePath && verbose) {
+      process.stderr.write(`[mini-ralph] errors archived to ${archivePath}\n`);
+    }
+  } catch (err) {
+    process.stderr.write(`[mini-ralph] warning: failed to archive error history: ${err.message}\n`);
+    return;
+  }
+
+  try {
+    errors.clear(ralphDir);
+  } catch (err) {
+    process.stderr.write(`[mini-ralph] warning: failed to clear active error history: ${err.message}\n`);
+  }
+}
+
 function _taskIdentity(task) {
   return task.number
     ? `${task.number}|${task.fullDescription || task.description}`
     : (task.fullDescription || task.description);
 }
 
+function _repoRelativePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return '';
+  const normalized = path.normalize(filePath);
+  if (!normalized || normalized === '.') return '';
+  const relative = path.isAbsolute(normalized)
+    ? path.relative(process.cwd(), normalized)
+    : normalized;
+
+  if (!relative || relative.startsWith('..')) {
+    return '';
+  }
+
+  return relative.split(path.sep).join('/');
+}
+
+function _detectProtectedCommitArtifacts(filesToStage, tasksFile) {
+  if (!Array.isArray(filesToStage) || filesToStage.length === 0 || !tasksFile) {
+    return [];
+  }
+
+  const relativeTasksFile = _repoRelativePath(tasksFile);
+  if (!relativeTasksFile) {
+    return [];
+  }
+
+  const changeRoot = path.posix.dirname(relativeTasksFile);
+  const protectedArtifacts = [];
+
+  for (const file of filesToStage) {
+    const normalized = _repoRelativePath(file);
+    if (!normalized) continue;
+
+    const isProposal = normalized === `${changeRoot}/proposal.md`;
+    const isDesign = normalized === `${changeRoot}/design.md`;
+    const isSpec = normalized.startsWith(`${changeRoot}/specs/`) && normalized.endsWith('/spec.md');
+
+    if (isProposal || isDesign || isSpec) {
+      protectedArtifacts.push(normalized);
+    }
+  }
+
+  return protectedArtifacts;
+}
+
+function _gitErrorMessage(err) {
+  if (!err) return 'unknown git error';
+
+  const stderr = _coerceGitErrorStream(err.stderr);
+  const stdout = _coerceGitErrorStream(err.stdout);
+
+  if (stderr) return stderr;
+  if (stdout) return stdout;
+  if (err.message) return err.message;
+  return 'unknown git error';
+}
+
+function _coerceGitErrorStream(stream) {
+  if (!stream) return '';
+  if (Buffer.isBuffer(stream)) return stream.toString('utf8').trim();
+  if (typeof stream === 'string') return stream.trim();
+  return '';
+}
+
 /**
  * Determine the starting iteration for a new run.
  *
@@ -474,13 +780,23 @@ function _resolveStartIteration(existingState, options) {
 
 module.exports = {
   run,
+  _finalizeRunState,
   _containsPromise,
   _validateOptions,
   _autoCommit,
+  _buildAutoCommitAllowlist,
   _resolveStartIteration,
   _completedTaskDelta,
   _formatAutoCommitMessage,
   _buildIterationFeedback,
   _extractErrorForIteration,
   _getCurrentTaskDescription,
+  _cleanupCompletedErrors,
+  _detectProtectedCommitArtifacts,
+  _gitErrorMessage,
+  _isFailedIteration,
+  _wasSuccessfulIteration,
+  _failureStageForError,
+  _errorText,
+  _appendFatalIterationFailure,
 };