chati-dev 4.3.1 → 4.4.1

package/src/autonomy/build-loop.js

@@ -1,281 +0,0 @@
-/**
- * @fileoverview Autonomous build loop (Ralph Wiggum v2).
- *
- * Executes tasks autonomously with checkpoint-based state management,
- * retry logic, and quality gate integration.
- *
- * Named "Ralph Wiggum" internally — the autonomous execution mode
- * that iterates until all tasks are complete or escalation is needed.
- *
- * Constitution Article XVII — Execution Mode Governance.
- */
-
-import {
-  createBuildState,
-  loadBuildState,
-  saveBuildState,
-  startBuild,
-  completeBuild,
-  failBuild,
-  updateCheckpoint,
-  getNextPendingTask,
-  isTaskExhausted,
-  isTimedOut,
-  getProgress,
-  CheckpointStatus,
-  BuildStatus,
-} from './build-state.js';
-import { analyzeCause, buildRetryGuidance } from './cause-analyzer.js';
-import { shouldEscalate, getEscalationConfig, buildEscalationSummary } from './escalation.js';
-
-// ---------------------------------------------------------------------------
-// Build Loop
-// ---------------------------------------------------------------------------
-
-/**
- * @typedef {object} BuildLoopConfig
- * @property {string} projectDir - Project root directory
- * @property {string[]} taskIds - Task IDs to execute
- * @property {function(string, object?): Promise<{success: boolean, output: string}>} executor - Task execution function (taskId, options?)
- * @property {function(object): void} [onProgress] - Progress callback
- * @property {boolean} [resume=false] - Whether to resume from existing state
- * @property {string} [model='sonnet'] - Current model tier for escalation
- */
-
-/**
- * @typedef {object} BuildLoopResult
- * @property {string} status - Final build status
- * @property {number} completed - Tasks completed
- * @property {number} failed - Tasks failed
- * @property {number} totalAttempts - Total execution attempts
- * @property {string} duration - Human-readable duration
- */
-
-/**
- * Run the autonomous build loop.
- *
- * Loop logic:
- * 1. Load or create build state
- * 2. Get next pending task
- * 3. Execute task
- * 4. Save checkpoint
- * 5. If task failed and not exhausted, retry
- * 6. If task exhausted, mark as failed and continue
- * 7. Repeat until all tasks complete or global timeout
- *
- * @param {BuildLoopConfig} config
- * @returns {Promise<BuildLoopResult>}
- */
-export async function runBuildLoop(config) {
-  const { projectDir, taskIds, executor, onProgress, resume = false, model = 'sonnet' } = config;
-
-  // Load or create state
-  let state = resume ? loadBuildState(projectDir) : null;
-
-  if (!state || state.status === BuildStatus.COMPLETED || state.status === BuildStatus.ABANDONED) {
-    state = createBuildState(taskIds);
-  }
-
-  state = startBuild(state);
-  saveBuildState(projectDir, state);
-
-  const startTime = Date.now();
-
-  // Per-task attempt history for cause analysis
-  /** @type {Map<string, Array<{category: string, output: string}>>} */
-  const attemptHistory = new Map();
-
-  // Main loop
-  while (true) {
-    // Check global timeout
-    if (isTimedOut(state)) {
-      state = failBuild(state, 'Global timeout exceeded');
-      saveBuildState(projectDir, state);
-      break;
-    }
-
-    // Get next task
-    const checkpoint = getNextPendingTask(state);
-    if (!checkpoint) {
-      // All tasks processed
-      const hasFailures = state.checkpoints.some((c) => c.status === CheckpointStatus.FAILED);
-      if (hasFailures) {
-        state = failBuild(state, 'Some tasks failed');
-      } else {
-        state = completeBuild(state);
-      }
-      saveBuildState(projectDir, state);
-      break;
-    }
-
-    // Check if task is exhausted
-    if (isTaskExhausted(checkpoint)) {
-      state = updateCheckpoint(state, checkpoint.taskId, {
-        status: CheckpointStatus.FAILED,
-        error: `Exceeded max iterations (${checkpoint.attempts})`,
-      });
-      saveBuildState(projectDir, state);
-
-      if (onProgress) {
-        onProgress({ type: 'task_exhausted', taskId: checkpoint.taskId, attempts: checkpoint.attempts });
-      }
-      continue;
-    }
-
-    // --- Escalation check (before execution) ---
-    const previousAttempts = attemptHistory.get(checkpoint.taskId) || [];
-    const executorOptions = {};
-
-    if (checkpoint.attempts > 0 && checkpoint.error) {
-      // Analyze the cause of the previous failure
-      const analysis = analyzeCause(checkpoint.error, previousAttempts);
-      const escalation = shouldEscalate(checkpoint, analysis);
-
-      if (escalation.escalate) {
-        const escalationConfig = getEscalationConfig(escalation.newLevel, model);
-
-        // Update checkpoint with escalation level
-        state = updateCheckpoint(state, checkpoint.taskId, {
-          escalationLevel: escalation.newLevel,
-        });
-
-        if (onProgress) {
-          onProgress({
-            type: 'escalation',
-            taskId: checkpoint.taskId,
-            level: escalation.newLevel,
-            summary: buildEscalationSummary(escalation.newLevel, escalation.reason),
-          });
-        }
-
-        // Pause for human intervention at MAX level
-        if (escalationConfig.shouldPause) {
-          state = updateCheckpoint(state, checkpoint.taskId, {
-            status: CheckpointStatus.FAILED,
-            error: `Escalation MAX — paused for human intervention: ${escalation.reason}`,
-          });
-          saveBuildState(projectDir, state);
-
-          if (onProgress) {
-            onProgress({ type: 'escalation_pause', taskId: checkpoint.taskId, reason: escalation.reason });
-          }
-          continue;
-        }
-
-        // Build executor options with escalation context
-        executorOptions.modelOverride = escalationConfig.model;
-        if (escalationConfig.contextBoost) {
-          executorOptions.retryGuidance = buildRetryGuidance(analysis, checkpoint.attempts + 1);
-        }
-      }
-    }
-
-    // Mark task as in progress
-    state = updateCheckpoint(state, checkpoint.taskId, {
-      status: CheckpointStatus.IN_PROGRESS,
-      attempts: checkpoint.attempts + 1,
-      lastAttempt: new Date().toISOString(),
-    });
-    saveBuildState(projectDir, state);
-
-    if (onProgress) {
-      const progress = getProgress(state);
-      onProgress({ type: 'task_started', taskId: checkpoint.taskId, attempt: checkpoint.attempts + 1, progress });
-    }
-
-    // Execute task
-    try {
-      const result = await executor(checkpoint.taskId, executorOptions);
-
-      if (result.success) {
-        state = updateCheckpoint(state, checkpoint.taskId, {
-          status: CheckpointStatus.COMPLETED,
-          output: result.output?.slice(0, 1000) || 'Completed',
-          error: null,
-          escalationLevel: undefined, // Reset on success
-        });
-
-        if (onProgress) {
-          onProgress({ type: 'task_completed', taskId: checkpoint.taskId });
-        }
-      } else {
-        // --- Self-critique: analyze failure cause ---
-        const failureOutput = result.output || 'Task failed';
-        const analysis = analyzeCause(failureOutput, previousAttempts);
-
-        // Record attempt in history
-        if (!attemptHistory.has(checkpoint.taskId)) {
-          attemptHistory.set(checkpoint.taskId, []);
-        }
-        attemptHistory.get(checkpoint.taskId).push({
-          category: analysis.category,
-          output: failureOutput.slice(0, 500),
-        });
-
-        state = updateCheckpoint(state, checkpoint.taskId, {
-          status: CheckpointStatus.IN_PROGRESS, // Will retry
-          error: failureOutput.slice(0, 500),
-        });
-
-        if (onProgress) {
-          onProgress({
-            type: 'task_failed',
-            taskId: checkpoint.taskId,
-            attempt: checkpoint.attempts + 1,
-            error: failureOutput,
-            causeAnalysis: analysis,
-          });
-        }
-      }
-    } catch (err) {
-      const errorMsg = err.message?.slice(0, 500) || 'Execution error';
-
-      // Record exception in history for cause analysis
-      const analysis = analyzeCause(errorMsg, previousAttempts);
-      if (!attemptHistory.has(checkpoint.taskId)) {
-        attemptHistory.set(checkpoint.taskId, []);
-      }
-      attemptHistory.get(checkpoint.taskId).push({
-        category: analysis.category,
-        output: errorMsg,
-      });
-
-      state = updateCheckpoint(state, checkpoint.taskId, {
-        status: CheckpointStatus.IN_PROGRESS, // Will retry
-        error: errorMsg,
-      });
-    }
-
-    saveBuildState(projectDir, state);
-  }
-
-  const duration = Date.now() - startTime;
-  const progress = getProgress(state);
-
-  return {
-    status: state.status,
-    completed: progress.completed,
-    failed: progress.failed,
-    totalAttempts: state.totalAttempts,
-    duration: `${Math.round(duration / 1000)}s`,
-  };
-}
-
-/**
- * Get current build loop status without executing.
- *
- * @param {string} projectDir
- * @returns {object|null}
- */
-export function getBuildStatus(projectDir) {
-  const state = loadBuildState(projectDir);
-  if (!state) return null;
-
-  return {
-    sessionId: state.sessionId,
-    status: state.status,
-    progress: getProgress(state),
-    startedAt: state.startedAt,
-    lastCheckpoint: state.lastCheckpoint,
-  };
-}

package/src/autonomy/build-state.js

@@ -1,286 +0,0 @@
-/**
- * @fileoverview Build state manager with checkpoint-based persistence.
- *
- * Manages the state of autonomous build execution, including
- * checkpoints saved after each task completion, abandoned build
- * detection, and attempt logging.
- *
- * Constitution Article XVII — Execution Mode Governance.
- */
-
-import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
-import { join, dirname } from 'path';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Maximum iterations per individual task before giving up */
-export const MAX_ITERATIONS_PER_TASK = 10;
-
-/** Maximum time per individual task before giving up (10 minutes) */
-export const MAX_TIME_PER_TASK_MS = 10 * 60 * 1000;
-
-/** Global timeout for an autonomous build session (30 minutes) */
-export const GLOBAL_TIMEOUT_MS = 30 * 60 * 1000;
-
-/** Time after which a build is considered abandoned (1 hour) */
-export const ABANDONED_THRESHOLD_MS = 60 * 60 * 1000;
-
-/**
- * Build status enum.
- * @enum {string}
- */
-export const BuildStatus = {
-  PENDING: 'pending',
-  IN_PROGRESS: 'in_progress',
-  PAUSED: 'paused',
-  ABANDONED: 'abandoned',
-  FAILED: 'failed',
-  COMPLETED: 'completed',
-};
-
-/**
- * Task checkpoint status.
- * @enum {string}
- */
-export const CheckpointStatus = {
-  PENDING: 'pending',
-  IN_PROGRESS: 'in_progress',
-  COMPLETED: 'completed',
-  FAILED: 'failed',
-  SKIPPED: 'skipped',
-};
-
-// ---------------------------------------------------------------------------
-// State Schema
-// ---------------------------------------------------------------------------
-
-/**
- * @typedef {object} TaskCheckpoint
- * @property {string} taskId
- * @property {string} status - CheckpointStatus
- * @property {number} attempts - Number of execution attempts
- * @property {string|null} firstAttempt - ISO timestamp of first attempt
- * @property {string|null} lastAttempt - ISO timestamp of last attempt
- * @property {string|null} output - Last output summary
- * @property {string|null} error - Last error message (if failed)
- */
-
-/**
- * @typedef {object} BuildState
- * @property {string} sessionId - Build session identifier
- * @property {string} status - BuildStatus
- * @property {TaskCheckpoint[]} checkpoints - Per-task checkpoints
- * @property {string} startedAt - ISO timestamp
- * @property {string|null} lastCheckpoint - ISO timestamp of last checkpoint
- * @property {string|null} completedAt - ISO timestamp of completion
- * @property {number} totalAttempts - Total execution attempts across all tasks
- */
-
-const BUILD_STATE_FILE = '.chati/build-state.json';
-
-// ---------------------------------------------------------------------------
-// State Management
-// ---------------------------------------------------------------------------
-
-/**
- * Initialize a new build state.
- *
- * @param {string[]} taskIds - Array of task IDs to execute
- * @returns {BuildState}
- */
-export function createBuildState(taskIds) {
-  return {
-    sessionId: `build-${Date.now()}`,
-    status: BuildStatus.PENDING,
-    checkpoints: taskIds.map((taskId) => ({
-      taskId,
-      status: CheckpointStatus.PENDING,
-      attempts: 0,
-      firstAttempt: null,
-      lastAttempt: null,
-      output: null,
-      error: null,
-    })),
-    startedAt: new Date().toISOString(),
-    lastCheckpoint: null,
-    completedAt: null,
-    totalAttempts: 0,
-  };
-}
-
-/**
- * Load build state from disk.
- *
- * @param {string} projectDir
- * @returns {BuildState|null}
- */
-export function loadBuildState(projectDir) {
-  const statePath = join(projectDir, BUILD_STATE_FILE);
-  if (!existsSync(statePath)) return null;
-  try {
-    const state = JSON.parse(readFileSync(statePath, 'utf-8'));
-
-    // Check for abandoned builds
-    if (state.status === BuildStatus.IN_PROGRESS && state.lastCheckpoint) {
-      const elapsed = Date.now() - new Date(state.lastCheckpoint).getTime();
-      if (elapsed > ABANDONED_THRESHOLD_MS) {
-        state.status = BuildStatus.ABANDONED;
-      }
-    }
-
-    return state;
-  } catch { /* expected: operation may fail gracefully */
-    return null;
-  }
-}
-
-/**
- * Save build state to disk.
- *
- * @param {string} projectDir
- * @param {BuildState} state
- */
-export function saveBuildState(projectDir, state) {
-  const statePath = join(projectDir, BUILD_STATE_FILE);
-  mkdirSync(dirname(statePath), { recursive: true });
-  writeFileSync(statePath, JSON.stringify(state, null, 2));
-}
-
-/**
- * Update a task checkpoint.
- *
- * @param {BuildState} state
- * @param {string} taskId
- * @param {Partial<TaskCheckpoint>} update
- * @returns {BuildState}
- */
-export function updateCheckpoint(state, taskId, update) {
-  const checkpoint = state.checkpoints.find((c) => c.taskId === taskId);
-  if (!checkpoint) {
-    throw new Error(`Task "${taskId}" not found in build state`);
-  }
-
-  // Set firstAttempt on the first execution attempt
-  if (update.attempts !== undefined && update.attempts > 0 && !checkpoint.firstAttempt) {
-    checkpoint.firstAttempt = new Date().toISOString();
-  }
-
-  Object.assign(checkpoint, update);
-  state.lastCheckpoint = new Date().toISOString();
-
-  if (update.attempts !== undefined) {
-    state.totalAttempts = state.checkpoints.reduce((sum, c) => sum + c.attempts, 0);
-  }
-
-  return state;
-}
-
-/**
- * Mark the build as started.
- *
- * @param {BuildState} state
- * @returns {BuildState}
- */
-export function startBuild(state) {
-  state.status = BuildStatus.IN_PROGRESS;
-  state.startedAt = new Date().toISOString();
-  return state;
-}
-
-/**
- * Mark the build as completed.
- *
- * @param {BuildState} state
- * @returns {BuildState}
- */
-export function completeBuild(state) {
-  state.status = BuildStatus.COMPLETED;
-  state.completedAt = new Date().toISOString();
-  return state;
-}
-
-/**
- * Mark the build as failed.
- *
- * @param {BuildState} state
- * @param {string} [reason]
- * @returns {BuildState}
- */
-export function failBuild(state, _reason) {
-  state.status = BuildStatus.FAILED;
-  state.completedAt = new Date().toISOString();
-  return state;
-}
-
-/**
- * Get the next pending task checkpoint.
- *
- * @param {BuildState} state
- * @returns {TaskCheckpoint|null}
- */
-export function getNextPendingTask(state) {
-  return state.checkpoints.find(
-    (c) => c.status === CheckpointStatus.PENDING || c.status === CheckpointStatus.IN_PROGRESS,
-  ) || null;
-}
-
-/**
- * Check if a task has exceeded max iterations or max time.
- *
- * Dual check: exhausted if attempts >= MAX_ITERATIONS_PER_TASK
- * OR if elapsed time since first attempt >= MAX_TIME_PER_TASK_MS.
- *
- * @param {TaskCheckpoint} checkpoint
- * @returns {boolean}
- */
-export function isTaskExhausted(checkpoint) {
-  if (checkpoint.attempts >= MAX_ITERATIONS_PER_TASK) return true;
-  if (checkpoint.firstAttempt) {
-    const elapsed = Date.now() - new Date(checkpoint.firstAttempt).getTime();
-    if (elapsed >= MAX_TIME_PER_TASK_MS) return true;
-  }
-  return false;
-}
-
-/**
- * Check if the global timeout has been exceeded.
- *
- * @param {BuildState} state
- * @returns {boolean}
- */
-export function isTimedOut(state) {
-  const elapsed = Date.now() - new Date(state.startedAt).getTime();
-  return elapsed > GLOBAL_TIMEOUT_MS;
-}
-
-/**
- * Get build progress summary.
- *
- * @param {BuildState} state
- * @returns {{ total: number, completed: number, failed: number, pending: number, progress: number }}
- */
-export function getProgress(state) {
-  const total = state.checkpoints.length;
-  const completed = state.checkpoints.filter((c) => c.status === CheckpointStatus.COMPLETED).length;
-  const failed = state.checkpoints.filter((c) => c.status === CheckpointStatus.FAILED).length;
-  const pending = state.checkpoints.filter(
-    (c) => c.status === CheckpointStatus.PENDING || c.status === CheckpointStatus.IN_PROGRESS,
-  ).length;
-  const progress = total > 0 ? Math.round((completed / total) * 100) : 0;
-
-  return { total, completed, failed, pending, progress };
-}
-
-/**
- * Clear build state (after completion or manual reset).
- *
- * @param {string} projectDir
- */
-export function clearBuildState(projectDir) {
-  const statePath = join(projectDir, BUILD_STATE_FILE);
-  if (existsSync(statePath)) {
-    unlinkSync(statePath);
-  }
-}