dev-harness-cli 1.0.0

package/cli/lib/ralph-outer.mjs

@@ -0,0 +1,249 @@
+/**
+ * ralph-outer — Outer Ralph Loop Engine.
+ *
+ * Advances through the phase pipeline in order. In copilot mode,
+ * runs one phase and stops. In autopilot mode, auto-advances
+ * through all remaining phases after each gate passes.
+ *
+ * The outer loop does NOT iterate tasks or features — that's
+ * entirely the inner loop's job (T8).
+ *
+ * Usage:
+ *   import { continuePipeline, runAutopilot } from './ralph-outer.mjs';
+ *   const result = continuePipeline('/path/to/project', 'build');
+ */
+import { loadConfig, transitionPhase, set as stateSet, getPhaseOrder } from './state.mjs';
+import { runPhase, loadFeatureList } from './ralph-inner.mjs';
+import { existsSync } from 'node:fs';
+import { execGit } from './git.mjs';
+
+/**
+ * After a phase completes (gate passes), continue the pipeline.
+ *
+ * In copilot mode: prints next-step instructions and stops.
+ * In autopilot mode: auto-advances to the next phase and runs it.
+ *
+ * @param {string} targetDir
+ * @param {string} completedPhase — the phase that just finished
+ * @param {object} [options]
+ * @param {boolean} [options.json] — JSON output mode
+ * @param {boolean} [options.verbose] — print detailed output
+ * @returns {{ ok: boolean, status: string, message: string, currentPhase: string|null, phasesRemaining: number }}
+ */
+export function continuePipeline(targetDir, completedPhase, options = {}) {
+  const { json = false, verbose = false } = options;
+
+  const { config, ok } = loadConfig(targetDir);
+  if (!ok) {
+    return { ok: false, status: 'error', message: 'Cannot load config', currentPhase: null, phasesRemaining: 0 };
+  }
+
+  const mode = config.mode ?? 'copilot';
+  const order = getPhaseOrder(config.phases?.enabled);
+  const phaseIdx = order.indexOf(completedPhase);
+  const nextPhase = (phaseIdx >= 0 && phaseIdx < order.length - 1) ? order[phaseIdx + 1] : null;
+  if (!nextPhase) {
+    // Pipeline complete
+    let msg = `Pipeline complete after "${completedPhase}".`;
+
+    // Increment pipeline iteration
+    if (config.pipelineIteration === undefined) {config.pipelineIteration = 0;}
+    config.pipelineIteration = (config.pipelineIteration || 0) + 1;
+    stateSet(targetDir, 'pipelineIteration', config.pipelineIteration);
+
+    // Count remaining features
+    let featuresRemaining = 0;
+    try {
+      const fl = loadFeatureList(targetDir);
+      // fl.ok === false means the file is missing OR malformed JSON.
+      // Missing file is benign (early phases have no feature list yet);
+      // a present-but-unparseable file is a real error we must surface.
+      if (fl.ok === false && fl.path && existsSync(fl.path)) {
+        process.stderr.write(
+          `Warning: feature_list.json at ${fl.path} is present but could not be parsed. Treating as 0 features.\n`,
+        );
+      }
+      featuresRemaining = fl.features ? fl.features.filter(f => !f.passes).length : 0;
+    } catch (err) {
+      // Defensive: loadFeatureList never throws, but guard anyway.
+      process.stderr.write(`Warning: failed to read feature list: ${err.message}\n`);
+    }
+
+    msg += ` Iteration ${config.pipelineIteration}.`;
+    if (featuresRemaining > 0) {
+      msg += ` ${featuresRemaining} feature(s) remaining.`;
+    } else {
+      msg += ' All features complete.';
+    }
+
+    if (!json && verbose) {
+      process.stdout.write(`\n${msg}\n`);
+    }
+    // Git auto-tag if enabled
+    if (config.git?.autoTag) {
+      autoTag(targetDir, completedPhase, json);
+    }
+    return {
+      ok: true,
+      status: 'complete',
+      message: msg,
+      currentPhase: completedPhase,
+      phasesRemaining: 0,
+      pipelineIteration: config.pipelineIteration,
+      featuresRemaining,
+    };
+  }
+
+  const phasesRemaining = order.length - phaseIdx - 1;
+
+  if (mode === 'copilot') {
+    // Copilot: print instructions for next phase
+    const msg = `${completedPhase.toUpperCase()} complete. Next: harness-dev phase ${nextPhase}`;
+    if (json) {
+      return {
+        ok: true,
+        status: 'instruction',
+        message: msg,
+        currentPhase: completedPhase,
+        phasesRemaining,
+        nextPhase,
+      };
+    }
+    if (verbose) {
+      process.stdout.write(`\n  ✓ ${completedPhase.toUpperCase()} complete.\n`);
+      process.stdout.write(`  ▶ ${msg}\n`);
+    }
+    return {
+      ok: true,
+      status: 'instruction',
+      message: msg,
+      currentPhase: completedPhase,
+      phasesRemaining,
+      nextPhase,
+    };
+  }
+
+  // ── Autopilot mode ────────────────────────────────────────────────────
+  // Auto-advance: transition to next phase and run inner loop
+
+  // Re-check pause before auto-advancing (user may have paused during phase execution)
+  if (config.paused) {
+    const msg = `Autopilot paused after "${completedPhase}". Run: harness-dev resume`;
+    if (verbose && !json) {
+      process.stdout.write(`\n  ⏸ ${msg}\n`);
+    }
+    return {
+      ok: true,
+      status: 'paused',
+      message: msg,
+      currentPhase: completedPhase,
+      nextPhase: null,
+      phasesRemaining,
+    };
+  }
+
+  if (verbose && !json) {
+    process.stdout.write(`\n  ● Autopilot: advancing to "${nextPhase}"...\n`);
+  }
+
+  // Transition to next phase
+  const transResult = transitionPhase(targetDir, nextPhase);
+  if (!transResult.ok) {
+    return {
+      ok: false,
+      status: 'error',
+      message: `Autopilot: transition to "${nextPhase}" failed: ${transResult.error}`,
+      currentPhase: completedPhase,
+      phasesRemaining,
+    };
+  }
+
+  // Run inner loop for next phase
+  const loopResult = runPhase(targetDir, nextPhase, { json });
+
+  if (loopResult.status === 'escalated') {
+    // Retries exhausted — stop pipeline, escalate to human
+    if (!json && verbose) {
+      process.stdout.write(`\n  ✗ ${nextPhase.toUpperCase()} — ${loopResult.message}\n`);
+      process.stdout.write(`  Escalating to human.\n`);
+    }
+    return {
+      ok: false,
+      status: 'escalated',
+      message: loopResult.message,
+      currentPhase: nextPhase,
+      nextPhase: null,
+      phasesRemaining,
+      details: loopResult.details,
+    };
+  }
+
+  if (loopResult.status === 'complete') {
+    // Phase completed successfully — continue the chain
+    if (verbose && !json) {
+      process.stdout.write(`  ✓ ${nextPhase.toUpperCase()} complete.\n`);
+    }
+    return continuePipeline(targetDir, nextPhase, options);
+  }
+
+  // Phase returned instruction or error — stop chain
+  const orderRemaining = getPhaseOrder();
+  const currentIdx = orderRemaining.indexOf(nextPhase);
+  const pipelineNext = (currentIdx >= 0 && currentIdx < orderRemaining.length - 1) ? orderRemaining[currentIdx + 1] : null;
+  return {
+    ok: loopResult.ok,
+    status: loopResult.status,
+    message: loopResult.message,
+    currentPhase: nextPhase,
+    nextPhase: pipelineNext,
+    phasesRemaining,
+    details: loopResult.details,
+  };
+}
+
+/**
+ * Run the full autopilot pipeline from current state through SHIP.
+ *
+ * This is a convenience wrapper — normally autopilot is triggered
+ * by calling `harness-dev phase <name>` while in autopilot mode.
+ *
+ * @param {string} targetDir
+ * @param {object} [options]
+ * @returns {{ ok: boolean, status: string, message: string }}
+ */
+export function runAutopilot(targetDir, options = {}) {
+  const { config, ok } = loadConfig(targetDir);
+  if (!ok) {
+    return { ok: false, status: 'error', message: 'Cannot load config' };
+  }
+
+  const currentPhase = config.currentPhase;
+  const order = getPhaseOrder(config.phases?.enabled);
+
+  if (!currentPhase || !order.includes(currentPhase)) {
+    // Start from the beginning
+    const firstPhase = order[0];
+    if (!firstPhase) {
+      return { ok: false, status: 'error', message: 'No phases enabled in config' };
+    }
+    const transResult = transitionPhase(targetDir, firstPhase);
+    if (!transResult.ok) {
+      return { ok: false, status: 'error', message: transResult.error || 'Transition failed' };
+    }
+    return continuePipeline(targetDir, firstPhase, options);
+  }
+
+  // Already in a phase — continue from here
+  return continuePipeline(targetDir, currentPhase, options);
+}
+
+/** Create a git tag for pipeline iteration. */
+function autoTag(targetDir, phase, json) {
+  const now = new Date();
+  const tag = `pipeline-${now.toISOString().slice(0, 10)}-${now.getTime().toString(36)}`;
+  const r = execGit(`git tag "${tag}"`, targetDir);
+  if (r.ok && !json) {
+    process.stdout.write(`  ● Git tag: ${tag}\n`);
+  }
+  // Not a git repo or tag failed — skip silently
+}

package/cli/lib/ralph-output.mjs

@@ -0,0 +1,178 @@
+/**
+ * ralph-output — Human-readable instruction builders for Ralph loop phases.
+ *
+ * Extracted from ralph-inner.mjs to separate instruction text generation
+ * from loop orchestration logic. Each builder returns a string of agent
+ * instructions for a phase/feature/task combination.
+ *
+ * Usage:
+ *   import { buildFeatureIterateOutput, buildDeliverableRetryOutput } from "./ralph-output.mjs";
+ */
+import { phaseLabel } from './command-helpers.mjs';
+
+// ── Output builders ──────────────────────────────────────────────────────────
+
+/**
+ * Build human-readable instructions for the SIMPLIFY phase.
+ * Spec: PROJECT_PLAN.md lines 602-631.
+ */
+export function buildSimplifyOutput(feature, task, maxRetries, resetOnRetry, autoCommit) {
+  let out = '';
+  out += `═══ SIMPLIFY PHASE ═══\n`;
+  out += `\n`;
+  out += `This is a feature-iterate phase. Pick one feature at a time.\n`;
+  out += `If validation fails (up to ${maxRetries} attempts), retry with fresh context.\n`;
+  out += `\n`;
+  out += `Current feature: "${feature.name}" (${feature.id})\n`;
+  out += `\n`;
+  out += `Planner: identify code smells, excessive nesting,\n`;
+  out += `         DRY violations, premature optimization\n`;
+  out += `         Set targets: "flatten nested loop X",\n`;
+  out += `         "extract validation logic from controller Y"\n`;
+  out += `\n`;
+  out += `Simplifier (Generator persona): refactor code for clarity\n`;
+  out += `  - Extract repeated logic into shared functions\n`;
+  out += `  - Flatten nested conditionals (max 4 levels)\n`;
+  out += `  - Remove dead code and commented-out blocks\n`;
+  out += `  - Rename unclear variables\n`;
+  out += `  - Break functions exceeding ~40 lines\n`;
+  out += `  - ⚠ Never change behavior — tests must still pass\n`;
+  out += `\n`;
+  out += `Evaluator: verify against these criteria:\n`;
+  out += `  - No dead code or unused imports\n`;
+  out += `  - No commented-out code blocks\n`;
+  out += `  - No nesting beyond 4 levels\n`;
+  out += `  - No DRY violations (same logic repeated 3+ times)\n`;
+  out += `  - All tests still pass after refactoring\n`;
+  out += `\n`;
+  out += `Iteration: validate --feature ${feature.id} --task ${task.id}\n`;
+  out += `  → pass → next feature\n`;
+  out += `  → fail (≤${maxRetries}x) → retry with fresh context\n`;
+  out += `  → fail (>${maxRetries}x) → escalate to human\n`;
+  if (resetOnRetry) { out += `\n  Git reset on retry: enabled\n`; }
+  if (autoCommit) { out += `  Auto-commit: enabled\n`; }
+  return out;
+}
+
+/**
+ * Build human-readable instructions for a feature-iterate phase.
+ */
+export function buildFeatureIterateOutput(phase, feature, task, mode, maxRetries, resetOnRetry, autoCommit) {
+  if (phase === 'simplify') {
+    return buildSimplifyOutput(feature, task, maxRetries, resetOnRetry, autoCommit);
+  }
+  let out = '';
+  out += `═══ ${phaseLabel(phase)} PHASE ═══\n`;
+  out += `\n`;
+  out += `This is a feature-iterate phase. You pick one incomplete\n`;
+  out += `feature at a time. If validation fails (up to ${maxRetries}\n`;
+  out += `attempts), retry that task with fresh context.\n`;
+  out += `\n`;
+  out += `Current feature: "${feature.name}" (${feature.id})\n`;
+  out += `Current task: "${task.description}" (${task.id})\n`;
+  out += `\n`;
+  out += `Planner: pick next feature from feature_list.json where passes=false\n`;
+  out += `         Select one uncompleted task from that feature's task list\n`;
+  out += `\n`;
+  out += `Generator: implement ONE task only. When done, call validate.\n`;
+  out += `\n`;
+  out += `Evaluator: verify against that task's acceptance criteria.\n`;
+  out += `           Run the verification commands yourself.\n`;
+  out += `\n`;
+  out += `Iteration pattern:\n`;
+  out += `  Pick task → implement → validate --feature ${feature.id} --task ${task.id}\n`;
+  out += `  → Pass: mark task complete, pick next task\n`;
+  out += `  → Fail (≤${maxRetries}x): git auto-commit, retry with fresh context\n`;
+  out += `  → Fail (>${maxRetries}x): escalate to human\n`;
+  if (resetOnRetry) {out += `\n  Git reset on retry: enabled\n`;}
+  if (autoCommit) {out += `  Auto-commit: enabled\n`;}
+  return out;
+}
+
+/**
+ * Build human-readable instructions for a deliverable-retry phase.
+ */
+export function buildDeliverableRetryOutput(phase, mode, maxRetries, resetOnRetry, autoCommit) {
+  let out = '';
+  out += `═══ ${phaseLabel(phase)} PHASE ═══\n`;
+  out += `\n`;
+  out += `This is a deliverable-retry phase. You produce one deliverable.\n`;
+  out += `If validation fails (up to ${maxRetries} attempts), retry with fresh context.\n`;
+  out += `\n`;
+
+  // Phase-specific planner/generator/evaluator instructions
+  switch (phase) {
+    case 'define':
+      out += `Planner: interview the user, write PRD in specs/*.md,\n`;
+      out += `         define acceptance criteria per feature\n`;
+      if (mode === 'autopilot') {
+        out += `\n`;
+        out += `         Write plans/outer-loop-plan.md with:\n`;
+        out += `         - Feature delivery order\n`;
+        out += `         - Estimated iterations per feature\n`;
+        out += `         - Risk factors and escalation thresholds\n`;
+      }
+      out += `\n`;
+      out += `Generator: produce spec documents (specs/*.md,\n`;
+      out += `           sprint-contract.md) following the PRD\n`;
+      if (mode === 'autopilot') {
+        out += `           Create plans/outer-loop-plan.md\n`;
+      }
+      out += `\n`;
+      out += `Evaluator: verify against these criteria:\n`;
+      out += `  - All 5 spec sections present (overview, requirements,\n`;
+      out += `    acceptance criteria, edge cases, open questions)\n`;
+      out += `  - No TODO/FIXME placeholders in specs\n`;
+      out += `  - Sprint Contract agreed between Planner and Evaluator\n`;
+      break;
+    case 'plan':
+      out += `Planner: decompose features into tasks in feature_list.json\n`;
+      out += `         Define task dependencies and effort estimates\n`;
+      out += `\n`;
+      out += `Generator: populate feature_list.json with all features\n`;
+      out += `           and tasks for this sprint\n`;
+      out += `\n`;
+      out += `Evaluator: verify against these criteria:\n`;
+      out += `  - feature_list.json is valid JSON\n`;
+      out += `  - All features have at least one task\n`;
+      out += `  - DAG of tasks is acyclic\n`;
+      break;
+    case 'review':
+      out += `Planner: review all phase gates have passed\n`;
+      out += `         Identify any outstanding blockers\n`;
+      out += `\n`;
+      out += `Generator: update evaluator-rubric.md with results\n`;
+      out += `           Ensure CHANGELOG.md is updated\n`;
+      out += `\n`;
+      out += `Evaluator: verify against these criteria:\n`;
+      out += `  - Branch up-to-date with main\n`;
+      out += `  - All gates pass (lint, tests, coverage)\n`;
+      out += `  - Sprint contract acceptance criteria met\n`;
+      break;
+    case 'ship':
+      out += `Planner: verify pipeline is complete\n`;
+      out += `         Prepare release notes\n`;
+      out += `\n`;
+      out += `Generator: tag commit, update changelog,\n`;
+      out += `           verify git clean\n`;
+      out += `\n`;
+      out += `Evaluator: verify against these criteria:\n`;
+      out += `  - Git status is clean\n`;
+      out += `  - HEAD is tagged\n`;
+      out += `  - CHANGELOG.md updated\n`;
+      break;
+    default:
+      out += `Planner: define scope of this deliverable\n`;
+      out += `\n`;
+      out += `Generator: produce the phase deliverable\n`;
+      out += `\n`;
+      out += `Evaluator: verify against phase criteria\n`;
+      break;
+  }
+
+  out += `\n`;
+  out += `When done, run: harness-dev validate\n`;
+  if (resetOnRetry) {out += `Git reset on retry: enabled\n`;}
+  if (autoCommit) {out += `Auto-commit: enabled\n`;}
+  return out;
+}