chati-dev 2.1.0 → 3.0.0

package/src/autonomy/build-loop.js

@@ -0,0 +1,194 @@
+/**
+ * @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';
+
+// ---------------------------------------------------------------------------
+// Build Loop
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} BuildLoopConfig
+ * @property {string} projectDir - Project root directory
+ * @property {string[]} taskIds - Task IDs to execute
+ * @property {function(string): Promise<{success: boolean, output: string}>} executor - Task execution function
+ * @property {function(object): void} [onProgress] - Progress callback
+ * @property {boolean} [resume=false] - Whether to resume from existing state
+ */
+
+/**
+ * @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 } = 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();
+
+  // 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;
+    }
+
+    // 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);
+
+      if (result.success) {
+        state = updateCheckpoint(state, checkpoint.taskId, {
+          status: CheckpointStatus.COMPLETED,
+          output: result.output?.slice(0, 1000) || 'Completed',
+          error: null,
+        });
+
+        if (onProgress) {
+          onProgress({ type: 'task_completed', taskId: checkpoint.taskId });
+        }
+      } else {
+        state = updateCheckpoint(state, checkpoint.taskId, {
+          status: CheckpointStatus.IN_PROGRESS, // Will retry
+          error: result.output?.slice(0, 500) || 'Task failed',
+        });
+
+        if (onProgress) {
+          onProgress({ type: 'task_failed', taskId: checkpoint.taskId, attempt: checkpoint.attempts + 1, error: result.output });
+        }
+      }
+    } catch (err) {
+      state = updateCheckpoint(state, checkpoint.taskId, {
+        status: CheckpointStatus.IN_PROGRESS, // Will retry
+        error: err.message?.slice(0, 500) || 'Execution error',
+      });
+    }
+
+    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

@@ -0,0 +1,269 @@
+/**
+ * @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 } from 'fs';
+import { join, dirname } from 'path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Maximum iterations per individual task before giving up */
+export const MAX_ITERATIONS_PER_TASK = 10;
+
+/** 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} 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,
+      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 {
+    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`);
+  }
+
+  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.
+ *
+ * @param {TaskCheckpoint} checkpoint
+ * @returns {boolean}
+ */
+export function isTaskExhausted(checkpoint) {
+  return checkpoint.attempts >= MAX_ITERATIONS_PER_TASK;
+}
+
+/**
+ * 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)) {
+    const { unlinkSync } = require('fs');
+    unlinkSync(statePath);
+  }
+}

package/src/autonomy/execution-profile.js

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Execution profile manager.
+ *
+ * Manages 3 execution profiles that govern confirmation requirements:
+ * - explore: read-only, no writes
+ * - guided: confirm before writes (default)
+ * - autonomous: full autonomy with quality gates
+ *
+ * Profiles are orthogonal to mode governance (Article XI).
+ * Modes control WHERE; profiles control WHETHER.
+ *
+ * Constitution Article XVIII — Execution Profile Governance.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+// ---------------------------------------------------------------------------
+// Profile Definitions
+// ---------------------------------------------------------------------------
+
+/**
+ * Execution profile enum.
+ * @enum {string}
+ */
+export const Profile = {
+  /** Read-only. Agents analyze and suggest but perform no writes. */
+  EXPLORE: 'explore',
+  /** Default. Agents propose actions and wait for user confirmation. */
+  GUIDED: 'guided',
+  /** Full autonomy. Agents execute without confirmation when gates pass. */
+  AUTONOMOUS: 'autonomous',
+};
+
+/** Minimum gate score required to activate autonomous profile */
+export const AUTONOMOUS_GATE_THRESHOLD = 90;
+
+/**
+ * Operations that ALWAYS require confirmation regardless of profile.
+ * Constitution Article XVIII, point 4.
+ */
+export const ALWAYS_CONFIRM_OPERATIONS = [
+  'file_delete',
+  'database_drop',
+  'force_push',
+  'deploy_production',
+  'deviation_activate',
+  'backward_transition',
+];
+
+// ---------------------------------------------------------------------------
+// Profile Management
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the current execution profile from session state.
+ *
+ * @param {string} projectDir
+ * @returns {string} Current profile (defaults to 'guided')
+ */
+export function getCurrentProfile(projectDir) {
+  const sessionPath = join(projectDir, '.chati', 'session.yaml');
+  if (!existsSync(sessionPath)) return Profile.GUIDED;
+
+  const raw = readFileSync(sessionPath, 'utf-8');
+  const match = raw.match(/^\s*execution_profile:\s*(.+)$/m);
+  const profile = match ? match[1].trim().replace(/^["']|["']$/g, '') : Profile.GUIDED;
+
+  return Object.values(Profile).includes(profile) ? profile : Profile.GUIDED;
+}
+
+/**
+ * Check if a write operation is allowed under the current profile.
+ *
+ * @param {string} profile - Current execution profile
+ * @param {string} operation - Operation type (e.g., 'file_write', 'file_delete')
+ * @returns {{ allowed: boolean, reason: string }}
+ */
+export function isWriteAllowed(profile, operation) {
+  // Explore profile blocks ALL writes
+  if (profile === Profile.EXPLORE) {
+    return { allowed: false, reason: '[Article XVIII] Explore profile: read-only mode. No writes permitted.' };
+  }
+
+  // Always-confirm operations need user approval regardless of profile
+  if (ALWAYS_CONFIRM_OPERATIONS.includes(operation)) {
+    return { allowed: false, reason: `[Article XVIII] Operation "${operation}" always requires user confirmation.` };
+  }
+
+  // Guided profile: allowed but requires confirmation (caller handles confirmation)
+  if (profile === Profile.GUIDED) {
+    return { allowed: true, reason: 'Guided profile: confirmation required.' };
+  }
+
+  // Autonomous profile: allowed without confirmation
+  if (profile === Profile.AUTONOMOUS) {
+    return { allowed: true, reason: 'Autonomous profile: proceeding without confirmation.' };
+  }
+
+  return { allowed: true, reason: 'Default: allowed.' };
+}
+
+/**
+ * Validate whether autonomous profile can be activated.
+ *
+ * @param {string} projectDir
+ * @returns {{ canActivate: boolean, reason: string, currentScore: number }}
+ */
+export function canActivateAutonomous(projectDir) {
+  const sessionPath = join(projectDir, '.chati', 'session.yaml');
+  if (!existsSync(sessionPath)) {
+    return { canActivate: false, reason: 'No active session', currentScore: 0 };
+  }
+
+  const raw = readFileSync(sessionPath, 'utf-8');
+
+  // Look for most recent QA gate score
+  const scoreMatches = raw.match(/score:\s*([\d.]+)/g);
+  if (!scoreMatches || scoreMatches.length === 0) {
+    return { canActivate: false, reason: 'No gate scores found. Run QA gates first.', currentScore: 0 };
+  }
+
+  const scores = scoreMatches.map((m) => parseFloat(m.replace('score:', '').trim()));
+  const latestScore = scores[scores.length - 1];
+
+  if (latestScore < AUTONOMOUS_GATE_THRESHOLD) {
+    return {
+      canActivate: false,
+      reason: `Gate score ${latestScore}% < required ${AUTONOMOUS_GATE_THRESHOLD}%`,
+      currentScore: latestScore,
+    };
+  }
+
+  return { canActivate: true, reason: 'Gate scores meet threshold', currentScore: latestScore };
+}
+
+/**
+ * Check if autonomous profile should be downgraded due to quality drop.
+ *
+ * @param {number} currentScore - Current quality score
+ * @returns {{ shouldDowngrade: boolean, reason: string }}
+ */
+export function shouldDowngradeAutonomous(currentScore) {
+  if (currentScore < AUTONOMOUS_GATE_THRESHOLD) {
+    return {
+      shouldDowngrade: true,
+      reason: `Quality dropped to ${currentScore}% (< ${AUTONOMOUS_GATE_THRESHOLD}%). Auto-downgrading to guided profile.`,
+    };
+  }
+  return { shouldDowngrade: false, reason: '' };
+}