infinity-harness 2.0.4 → 2.2.0

package/src/goal.ts

@@ -0,0 +1,411 @@
+/**
+ * infinity-harness — the goal loop, connected to the pipeline.
+ *
+ * `goalSpec`, `goalLoop` and `goalState` are a complete outer loop: state a
+ * goal, do a pass of work, judge whether the goal is actually met, and go
+ * round again if it is not, under iteration and wall-clock limits. Ported from
+ * pi-long-task, 1,600 lines, fully typed, well tested.
+ *
+ * And nothing ever turned the crank. `createGoalLoopState` was called by its
+ * own tests and by nothing else. The three modules were a state machine with
+ * no driver — which is why the harness could finish a pipeline and declare
+ * "complete" without anyone ever asking the only question that matters: is the
+ * thing the human asked for actually done?
+ *
+ * This module is the driver, and the mapping it chooses is the whole design:
+ *
+ *   one goal iteration  =  one full pass of the phase pipeline
+ *
+ * DEFINE→SHIP produces work; the goal loop then asks whether that work met the
+ * goal. If it did, the run is over. If it did not, the pipeline is rewound to
+ * DEFINE with the remaining work named, and the next iteration begins. The
+ * gate decides whether the *work* is done; the goal loop decides whether the
+ * *goal* is done. They are different questions and the harness needed both.
+ *
+ * The reviewer's verdict comes from the agent, not from here. Whether a body
+ * of work satisfies a stated goal is a judgement, and the harness's rule is
+ * that judgements belong to the model while enforcement belongs to the gate.
+ * What this module enforces is that the judgement is recorded, bounded, and
+ * has consequences.
+ */
+
+import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import {
+  createGoalLoopState,
+  startGoalIteration,
+  recordGeneratedTodo,
+  recordWorkerResult,
+  recordReviewerResult,
+  cancelGoalLoop,
+  goalLoopStopReason,
+  type GoalLoopState,
+  type GoalReviewerDecision,
+} from "./goalLoop.ts";
+import { GoalStateStore, canonicalGoalSpecPath } from "./goalState.ts";
+import { createGoalSpecification, type GoalSpecification } from "./goalSpec.ts";
+import { loadConfig, saveConfig } from "./core/config.ts";
+import { loadFeatureList, computeProgress } from "./core/featureList.ts";
+import { writeTaskList } from "./taskList.ts";
+import { harnessDir } from "./core/paths.ts";
+import { readJsonSafe, writeJsonAtomic } from "./core/fsx.ts";
+import { getPhaseOrder } from "./core/phases.ts";
+import { PHASE_ROLE, type Phase } from "./core/types.ts";
+
+/** Which goal run this project is on, so a new session can find it. */
+export const GOAL_POINTER_FILE = "goal.json";
+
+type GoalPointer = { goalRunId: string; goalRunDir: string; startedAt: string };
+
+export function goalPointerPath(targetDir: string): string {
+  return resolve(harnessDir(targetDir), GOAL_POINTER_FILE);
+}
+
+function readPointer(targetDir: string): GoalPointer | null {
+  return readJsonSafe<GoalPointer | null>(goalPointerPath(targetDir), null);
+}
+
+function storeFor(targetDir: string, pointer: GoalPointer): GoalStateStore {
+  return new GoalStateStore({
+    cwd: targetDir,
+    goalRunId: pointer.goalRunId,
+    goalRunDir: pointer.goalRunDir,
+  });
+}
+
+export type GoalView = {
+  goal: string;
+  goalRunId: string;
+  status: GoalLoopState["status"];
+  phase: GoalLoopState["phase"];
+  iteration: number;
+  maxIterations: number;
+  /** What the last review said is still missing. */
+  remainingWork: string[];
+  /** Set once the loop reaches a terminal state. */
+  completion: GoalLoopState["completion"];
+  startedAt: string;
+  deadlineAt?: string;
+};
+
+export function viewOf(state: GoalLoopState): GoalView {
+  const last = state.iterations[state.iterations.length - 1];
+  return {
+    goal: state.goal,
+    goalRunId: state.goalRunId,
+    status: state.status,
+    phase: state.phase,
+    iteration: state.currentIteration,
+    maxIterations: state.limits.maxIterations,
+    remainingWork: last?.reviewerResult?.remainingWork ?? [],
+    completion: state.completion,
+    startedAt: state.startedAt,
+    deadlineAt: state.deadlineAt,
+  };
+}
+
+/** The goal run this project is on, or null. Never throws. */
+export async function loadGoal(targetDir: string): Promise<GoalLoopState | null> {
+  const pointer = readPointer(targetDir);
+  if (!pointer) return null;
+  try {
+    return await storeFor(targetDir, pointer).loadState();
+  } catch {
+    return null;
+  }
+}
+
+export type StartGoalOptions = {
+  targetDir: string;
+  goal: string;
+  runId: string;
+  maxIterations?: number;
+  timeoutMs?: number;
+  now?: Date;
+};
+
+/**
+ * State a goal and open iteration 1.
+ *
+ * The goal specification is written to `harness/goals/GOAL_SPEC.json` — a
+ * committed, human-readable statement of what this run is for — while the
+ * loop's own state lives under `tmp/`, because it is run bookkeeping and
+ * nobody wants it in a diff.
+ */
+export async function startGoal(options: StartGoalOptions): Promise<{ state: GoalLoopState; spec: GoalSpecification }> {
+  const { targetDir, runId } = options;
+  const goal = options.goal.trim();
+  if (!goal) throw new Error("a goal needs to say something");
+
+  const existing = await loadGoal(targetDir);
+  if (existing && existing.status === "running") {
+    throw new Error(
+      `This project is already pursuing a goal: "${existing.goal}". ` +
+        `Finish it or cancel it (/infinity:goal cancel) before starting another.`,
+    );
+  }
+
+  const spec = createGoalSpecification({ goalRunId: runId, originalGoal: goal, now: () => options.now ?? new Date() });
+  let state = createGoalLoopState({
+    goal,
+    goalRunId: runId,
+    cwd: targetDir,
+    maxIterations: options.maxIterations,
+    timeoutMs: options.timeoutMs,
+    now: () => options.now ?? new Date(),
+  });
+  state = startGoalIteration(state, { now: options.now });
+
+  const store = new GoalStateStore({ cwd: targetDir, goalRunId: runId, goalRunDir: state.goalRunDir });
+  await store.ensureRunDir();
+  await store.saveGoalSpecificationWithCanonical(spec, targetDir);
+  await store.saveState(state);
+  writeJsonAtomic(goalPointerPath(targetDir), {
+    goalRunId: runId,
+    goalRunDir: state.goalRunDir,
+    startedAt: state.startedAt,
+  } satisfies GoalPointer);
+
+  // The goal also becomes the pipeline's goal, so every brief carries it.
+  rewindPipeline(targetDir, goal, [], 1, state.limits.maxIterations);
+  return { state, spec };
+}
+
+/**
+ * Record that the pipeline has produced a pass of work.
+ *
+ * Called when the phase pipeline completes. Moves the iteration through
+ * `todo_generated` → `todo_executed`, which is what makes it reviewable.
+ */
+export async function recordPipelinePass(
+  targetDir: string,
+  summary: string,
+  now?: Date,
+): Promise<GoalLoopState | null> {
+  const pointer = readPointer(targetDir);
+  if (!pointer) return null;
+  const store = storeFor(targetDir, pointer);
+  let state: GoalLoopState;
+  try {
+    state = await store.loadState();
+  } catch {
+    return null;
+  }
+  if (state.status !== "running") return state;
+
+  const iteration = state.currentIteration;
+  const { list } = loadFeatureList(targetDir);
+  const progress = computeProgress(list);
+  const at = (now ?? new Date()).toISOString();
+
+  if (state.phase === "goal_received") {
+    state = recordGeneratedTodo(
+      state,
+      iteration,
+      { todoPath: "harness/features/feature-list.json", summary: `${progress.tasksTotal} task(s) planned`, generatedAt: at },
+      { now },
+    );
+  }
+  if (state.phase === "todo_generated") {
+    state = recordWorkerResult(
+      state,
+      iteration,
+      {
+        status: progress.tasksDone === progress.tasksTotal ? "done" : "partial",
+        summary,
+        totalTasks: progress.tasksTotal,
+        completedTasks: progress.tasksDone,
+        endedAt: at,
+      },
+      { now },
+    );
+  }
+  await store.saveState(state);
+  return state;
+}
+
+export type ReviewInput = {
+  decision: GoalReviewerDecision;
+  rationale: string;
+  remainingWork?: string[];
+  summary?: string;
+};
+
+export type ReviewOutcome = {
+  state: GoalLoopState;
+  /** True when the goal loop is finished, either way. */
+  terminal: boolean;
+  /** Set when another pass begins: the pipeline was rewound to here. */
+  rewoundTo: Phase | null;
+  message: string;
+};
+
+/**
+ * Judge whether the work meets the goal, and act on the answer.
+ *
+ * A `complete` verdict ends the run. Anything else opens the next iteration
+ * and rewinds the pipeline, because the harness has no other way to do more
+ * work: the phase machine is forward-only, so a second pass means starting a
+ * second pass, with the remaining work stated up front.
+ */
+export async function reviewGoal(
+  targetDir: string,
+  input: ReviewInput,
+  now?: Date,
+): Promise<ReviewOutcome> {
+  const pointer = readPointer(targetDir);
+  if (!pointer) throw new Error("No goal is being pursued in this project. Start one with /infinity:goal.");
+  const store = storeFor(targetDir, pointer);
+  let state = await store.loadState();
+
+  if (state.status !== "running") {
+    return { state, terminal: true, message: `The goal loop already finished: ${state.status}.`, rewoundTo: null };
+  }
+
+  const at = (now ?? new Date()).toISOString();
+  const remainingWork = (input.remainingWork ?? []).map((s) => s.trim()).filter(Boolean);
+  if (input.decision !== "complete" && remainingWork.length === 0) {
+    // "Not done" with nothing named is not a review, it is a shrug — and the
+    // next iteration would start with no more information than this one had.
+    throw new Error(
+      `A "${input.decision}" verdict must name what is still missing (remainingWork). ` +
+        `The next pass is planned from that list.`,
+    );
+  }
+
+  state = recordReviewerResult(
+    state,
+    state.currentIteration,
+    {
+      decision: input.decision,
+      complete: input.decision === "complete",
+      summary: input.summary?.trim() || input.rationale.trim(),
+      rationale: input.rationale.trim(),
+      remainingWork,
+      reviewedAt: at,
+    },
+    { now },
+  );
+
+  if (state.status !== "running") {
+    await store.saveState(state);
+    await store.initializeResultIfMissing(state);
+    return {
+      state,
+      terminal: true,
+      rewoundTo: null,
+      message:
+        state.status === "done"
+          ? `Goal met after ${state.iterations.length} pass(es): ${state.goal}`
+          : `Goal loop ended ${state.status}: ${state.completion?.reason ?? input.rationale}`,
+    };
+  }
+
+  // Not done, and not fatal: go round again — unless a limit says otherwise.
+  const stop = goalLoopStopReason(state, { now });
+  if (stop) {
+    state = cancelGoalLoop(state, stop.message, { now });
+    await store.saveState(state);
+    await store.initializeResultIfMissing(state);
+    return { state, terminal: true, rewoundTo: null, message: `Goal loop stopped: ${stop.message}` };
+  }
+
+  state = startGoalIteration(state, { now });
+  await store.saveState(state);
+  const phase = rewindPipeline(
+    targetDir,
+    state.goal,
+    remainingWork,
+    state.currentIteration,
+    state.limits.maxIterations,
+  );
+  return {
+    state,
+    terminal: false,
+    rewoundTo: phase,
+    message:
+      `Pass ${state.currentIteration - 1} did not meet the goal. Starting pass ${state.currentIteration} at ` +
+      `${phase.toUpperCase()} with ${remainingWork.length} item(s) still to do:\n` +
+      remainingWork.map((w) => `  - ${w}`).join("\n"),
+  };
+}
+
+/** Stop pursuing the goal, on purpose. */
+export async function cancelGoal(targetDir: string, reason: string, now?: Date): Promise<GoalLoopState | null> {
+  const pointer = readPointer(targetDir);
+  if (!pointer) return null;
+  const store = storeFor(targetDir, pointer);
+  let state: GoalLoopState;
+  try {
+    state = await store.loadState();
+  } catch {
+    return null;
+  }
+  if (state.status !== "running") return state;
+  state = cancelGoalLoop(state, reason, { now });
+  await store.saveState(state);
+  await store.initializeResultIfMissing(state);
+  return state;
+}
+
+/**
+ * Point the pipeline at the goal and send it back to the first phase.
+ *
+ * The phase machine is forward-only by design — the agent must not be able to
+ * decide it is bored of BUILD. Rewinding is therefore not something the agent
+ * can do; it happens here, once, when a review says the goal is not met, and
+ * it is recorded in the goal trace.
+ */
+function rewindPipeline(
+  targetDir: string,
+  goal: string,
+  remainingWork: string[] = [],
+  pass = 1,
+  maxPasses = 1,
+): Phase {
+  // The goal belongs in the plan, not the config: `harness/features/feature-list.json`
+  // is the single source of truth the brief, the widget and the dashboard all
+  // read. Writing it anywhere else means a goal nothing displays.
+  try {
+    writeTaskList(targetDir, { goal });
+  } catch {
+    // A plan too broken to accept a goal is a problem the gate will report;
+    // it must not stop the goal loop from being recorded.
+  }
+
+  const { config, ok } = loadConfig(targetDir);
+  if (!ok) return "define";
+  const order = getPhaseOrder(config.phases?.enabled);
+  const first = order[0] ?? "define";
+  config.currentPhase = first;
+  config.currentRole = PHASE_ROLE[first];
+  config.remainingWork = remainingWork;
+  config.goalPass = pass;
+  config.goalMaxPasses = maxPasses;
+  // A new pass starts with fresh retry budgets. The old ones were spent on
+  // work that turned out to be insufficient, not on work that was wrong.
+  config.taskRetryCount = 0;
+  config.featureRetryCount = 0;
+  config.phaseRetryCount = 0;
+  saveConfig(targetDir, config);
+  return first;
+}
+
+/** The canonical goal specification, if one has been written. */
+export function readGoalSpec(targetDir: string): GoalSpecification | null {
+  const path = canonicalGoalSpecPath(targetDir);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as GoalSpecification;
+  } catch {
+    return null;
+  }
+}
+
+/** One line for the widget and the status command. */
+export function describeGoal(view: GoalView): string {
+  if (view.status !== "running") {
+    return `goal ${view.status}: ${view.goal}`;
+  }
+  return `goal pass ${view.iteration}/${view.maxIterations} · ${view.goal}`;
+}

package/src/loop.ts

@@ -32,6 +32,13 @@ import { buildBrief, renderBrief } from "./core/brief.ts";
 import { harnessDir } from "./core/paths.ts";
 import { readJsonSafe, writeJsonAtomic, fileExists } from "./core/fsx.ts";
 import { run } from "./core/exec.ts";
+import {
+  emptyEscalationState,
+  escalate,
+  describeEscalation,
+  type EscalationState,
+} from "./escalate.ts";
+import { loadGoal, recordPipelinePass, viewOf } from "./goal.ts";
 
 export const LOOP_STATE_FILE = "loop-state.json";
 export const STOP_FILE = "STOP";
@@ -52,8 +59,26 @@ export type LoopState = {
   lastDecision: string | null;
   stoppedAt: string | null;
   stopReason: string | null;
+  /** Where this run sits on the escalation ladder. */
+  escalation: EscalationState;
+  /** Every rung taken, so the human coming back can see the shape of it. */
+  escalations: { at: string; strategy: string; reason: string; applied: string | null }[];
 };
 
+/** Escalation history kept in the loop state. Older entries tell no story. */
+export const ESCALATION_HISTORY_LIMIT = 50;
+
+/**
+ * Consecutive stalled gate failures before the ladder is consulted.
+ *
+ * One is enough. A stalled failure means the gate failed AND nothing in the
+ * tree moved — the agent produced no work at all — and there is no reason to
+ * let that repeat before doing something about it. The no-progress limit still
+ * governs when the run gives up entirely; this only governs when it starts
+ * trying something different.
+ */
+export const ESCALATE_AFTER_STALLS = 1;
+
 export type LoopBudget = {
   maxIterations: number;
   maxWallClockMs: number;
@@ -85,12 +110,21 @@ export function newLoopState(runId: string, now = new Date()): LoopState {
     lastDecision: null,
     stoppedAt: null,
     stopReason: null,
+    escalation: emptyEscalationState(),
+    escalations: [],
   };
 }
 
 export function loadLoopState(targetDir: string, runId: string, now = new Date()): LoopState {
   const stored = readJsonSafe<LoopState | null>(loopStatePath(targetDir), null);
-  if (stored && stored.runId === runId) return stored;
+  if (stored && stored.runId === runId) {
+    // A state file written before the ladder existed has neither field.
+    return {
+      ...stored,
+      escalation: { ...emptyEscalationState(), ...(stored.escalation ?? {}) },
+      escalations: Array.isArray(stored.escalations) ? stored.escalations : [],
+    };
+  }
   return newLoopState(runId, now);
 }
 
@@ -143,6 +177,8 @@ export async function fingerprint(targetDir: string): Promise<string> {
 }
 
 export type DecideOptions = {
+  /** Skip the escalation ladder. Tests use it to isolate the base loop. */
+  skipEscalation?: boolean;
   targetDir: string;
   runId: string;
   now?: Date;
@@ -205,11 +241,17 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
   const allTasksDone = progress.tasksTotal > 0 && progress.tasksDone === progress.tasksTotal;
 
   if (isFinalPhase(config.currentPhase, config.phases?.enabled) && allTasksDone) {
-    return finish({
-      action: "stop",
-      reason: "complete",
-      detail: `Pipeline complete: ${progress.tasksDone}/${progress.tasksTotal} tasks across ${progress.featuresTotal} feature(s).`,
-    });
+    const detail = `Pipeline complete: ${progress.tasksDone}/${progress.tasksTotal} tasks across ${progress.featuresTotal} feature(s).`;
+
+    // A finished pipeline is not necessarily a met goal. When a goal is being
+    // pursued, the run does not stop here — it hands the work to the outer
+    // loop, which asks the only question the gate cannot: is the thing that
+    // was actually asked for done? Without this the harness declares victory
+    // on whatever happened to be planned.
+    const goalReview = await requestGoalReview(targetDir, detail);
+    if (goalReview) return finish(goalReview);
+
+    return finish({ action: "stop", reason: "complete", detail });
   }
 
   const exhausted = isRetryExhausted(config);
@@ -295,10 +337,65 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
 
   if (previous === null || previous !== fp) {
     state.noProgressStreak = 0;
+    // The tree moved, so whatever the run was stuck on, it is not stuck on it
+    // any more. The next stall starts from the bottom of the ladder — the
+    // budgets in rework.json and replan.json still bound the run across
+    // stalls, but a rung spent on a problem that resolved should not be
+    // missing when a different problem appears.
+    state.escalation = { ...state.escalation, tried: [] };
   } else {
     state.noProgressStreak += 1;
   }
 
+  // -- the escalation ladder ------------------------------------------------
+  //
+  // A stalled failure — the gate failed and the tree did not move — means the
+  // agent produced nothing, and repeating the same brief will produce nothing
+  // again. Before spending another strike, ask the ladder what to do
+  // differently: retry, reframe, consult a stronger model, rework the task
+  // that poisoned everything downstream, amend the plan, or go to master.
+  //
+  // Escalating never *prevents* the run from stopping. The strike is still
+  // counted; the ladder just gets a turn first, so a run stops because nothing
+  // worked rather than because nothing was tried.
+  let escalation = null as Awaited<ReturnType<typeof escalate>> | null;
+  if (!options.skipEscalation && state.noProgressStreak >= ESCALATE_AFTER_STALLS) {
+    escalation = await escalate({
+      targetDir,
+      runId,
+      phase,
+      failures: gate ? gate.failures : [],
+      fileDelta: previous !== null && previous !== fp,
+      fingerprint: fp,
+      state: state.escalation,
+      now,
+    });
+    state.escalation = escalation.next;
+    if (escalation.strategy) {
+      state.escalations = [
+        ...state.escalations,
+        {
+          at: now.toISOString(),
+          strategy: escalation.strategy,
+          reason: escalation.reason,
+          applied: escalation.applied,
+        },
+      ].slice(-ESCALATION_HISTORY_LIMIT);
+
+      // A new rung is a genuinely different attempt, so it does not count as
+      // another repetition of the same one — the streak resets and the ladder
+      // gets room to climb. This cannot run forever: every rung is bounded
+      // (retry and reframe once per stall, consult and rework and replan by
+      // their budgets, master once), so the ladder runs out, returns null, and
+      // the streak resumes counting to the stop.
+      state.noProgressStreak = 0;
+
+      // Rework rewrites task statuses, so the plan the next brief reads is not
+      // the plan this fingerprint was taken from.
+      if (escalation.strategy === "rework") state.lastFingerprint = await fingerprint(targetDir);
+    }
+  }
+
   if (state.noProgressStreak >= budget.noProgressLimit) {
     return finish({
       action: "stop",
@@ -307,7 +404,13 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
         `The gate has failed ${state.noProgressStreak} times in a row with no change to the working tree ` +
         `or the plan. The agent is looping without making progress` +
         (gate ? `: ${gate.failures.join(", ")}` : "") +
-        `. Stopping so a human can intervene.`,
+        `.` +
+        (state.escalations.length
+          ? ` The escalation ladder was spent first: ${state.escalations
+              .map((e) => e.strategy)
+              .join(" → ")}.`
+          : "") +
+        ` Stopping so a human can intervene.`,
     });
   }
 
@@ -330,16 +433,59 @@ export async function decideNext(options: DecideOptions): Promise<{ decision: Lo
   const task = nextActionableTask(list);
   const focus = task ? `\nCurrent task: ${task.compositeKey} — ${task.description}` : "";
 
+  // An escalation replaces the standard "fix these" nudge, because repeating
+  // that nudge is exactly what the ladder exists to interrupt.
+  const head = escalation?.instruction
+    ? `${escalation.instruction}\n`
+    : `The ${phase.toUpperCase()} gate did not pass. Fix exactly these, then stop talking — ` +
+      `the harness will re-validate automatically.\n\n${failures}${focus}\n`;
+
   return finish({
     action: "continue",
-    reason: "gate failed",
-    message:
-      `The ${phase.toUpperCase()} gate did not pass. Fix exactly these, then stop talking — ` +
-      `the harness will re-validate automatically.\n\n${failures}${focus}\n\n` +
-      renderBrief(brief, fresh.ok ? fresh.config : undefined),
+    reason: escalation?.strategy ? `escalated: ${describeEscalation(escalation)}` : "gate failed",
+    message: `${head}\n${renderBrief(brief, fresh.ok ? fresh.config : undefined)}`,
   });
 }
 
+/**
+ * Hand a finished pipeline to the goal loop, if one is running.
+ *
+ * Returns a `continue` decision carrying the review request, or null when
+ * there is no goal and the pipeline finishing really is the end of the run.
+ * Never throws: a goal loop that cannot be read must not turn a completed
+ * pipeline into a crash.
+ */
+async function requestGoalReview(
+  targetDir: string,
+  summary: string,
+): Promise<LoopDecision | null> {
+  try {
+    const existing = await loadGoal(targetDir);
+    if (!existing || existing.status !== "running") return null;
+
+    const state = await recordPipelinePass(targetDir, summary);
+    if (!state) return null;
+    const view = viewOf(state);
+
+    return {
+      action: "continue",
+      reason: "goal review",
+      message:
+        `${summary}\n\nTHE PIPELINE IS DONE. THE GOAL MAY NOT BE.\n\n` +
+        `Goal: ${view.goal}\nPass ${view.iteration} of at most ${view.maxIterations}.\n\n` +
+        `Judge the work against the GOAL, not against the plan — the plan is only what you ` +
+        `thought the goal needed when you wrote it. Then call \`infinity_goal\` with ` +
+        `action "review":\n` +
+        `  - decision "complete" ends the run.\n` +
+        `  - anything else must name what is still missing in remainingWork; the next pass is ` +
+        `planned from that list.\n\n` +
+        `Do not mark it complete to end the run. The run ending is not the point.`,
+    };
+  } catch {
+    return null;
+  }
+}
+
 /** Human-readable one-liner for the status bar / notify. */
 export function describeDecision(d: LoopDecision): string {
   switch (d.action) {