# Durable Execution Engine Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make ForgeDock's headless pipeline durable — a code-driven per-phase state machine over the existing `runner.mjs`, with an append-only run-log mirrored to a compact `FORGE:STATE` block on GitHub, so runs resume from the last committed phase after any crash/kill/compaction.

**Architecture:** A runtime-agnostic engine core (`bin/engine/*`) drives one pipeline phase at a time by calling the existing `runner.runCommand()` with a fresh context per phase. Each phase's outcome is determined by inspecting GitHub state after the run (`detectOutcome`), not from the runner's return. State lives in a local `.forge/runs/{issue}.jsonl` (hot path) and a `FORGE:STATE` HTML-comment index on the issue (durable shared mirror); on divergence GitHub wins. All side effects (GitHub, git, the LLM run) are injected, so the whole engine is unit-testable with fakes and no network.

**Tech Stack:** Node.js ES modules (`.mjs`), `node:test` + `node:assert/strict`, `bin/runner.mjs` (existing, unmodified), `gh` and `git` CLIs (injected as async functions).

**Spec:** `docs/superpowers/specs/2026-07-03-durable-execution-engine-design.md`

## Global Constraints

- Node ES modules (`.mjs`); **zero runtime dependencies** — the Anthropic SDK stays lazy/optional inside `runner.mjs` only. Engine code imports nothing outside `node:*` and sibling engine modules.
- Tests run via `node --test "bin/tests/**/*.test.mjs"`, use `node:test` + `node:assert/strict`, no network, isolate filesystem with `mkdtempSync`.
- All side effects are **injected**: `io = { gh(args:string[]):Promise<string>, git(args:string[]):Promise<string> }`, `runner` (a `runCommand`-shaped async fn), and `now():number`. No engine module calls `gh`/`git`/the SDK directly.
- Windows-safe paths: use `node:path`; command names use `/` separators.
- Durability granularity is **per-phase**. `FORGE:STATE` is a **compact index** (no rich outputs). On divergence, **GitHub wins**.
- Commits: conventional (`feat(engine):`, `test(engine):`), signed off (`git commit -s`, DCO required on staging), **no AI attribution**.

## Shared types (JSDoc — referenced by every task)

```js
/**
 * @typedef {Object} RunState   // the working state; also the shape of the compact index
 * @property {number} v         // version = last committed run-log seq (0 if none)
 * @property {string|null} run  // run id
 * @property {number} issue
 * @property {string} lane      // "staging" | "milestone/<slug>"
 * @property {string[]} committed // phase ids committed, in order
 * @property {string|null} phase  // current/next phase id (null before start)
 * @property {string|null} branch
 * @property {number|null} pr
 * @property {boolean} terminal
 * @property {string|null} terminalReason // "merged"|"invalid"|"needs-human"|"decomposed"|null
 * @property {{by:string, until:number}|null} lease
 */

/**
 * @typedef {Object} PhaseOutcome
 * @property {"committed"|"failed"|"blocked"} status
 * @property {Object} [outputs]   // structured facts to record (branch, pr, skipped, ...)
 * @property {string} [detail]    // human reason for blocked/failed
 * @property {string} [terminalReason] // when a committed phase is terminal (e.g. "invalid")
 */

/**
 * @typedef {Object} Phase
 * @property {string} id
 * @property {string} command                 // spec name passed to runner.runCommand
 * @property {(s:RunState)=>boolean} entryCondition
 * @property {(s:RunState)=>boolean} [isTerminalAfter] // true if committing this phase ends the run
 * @property {(s:RunState, io:Io)=>Promise<{satisfied:boolean, outputs?:Object}>} [reconcile]
 * @property {(s:RunState, io:Io)=>Promise<PhaseOutcome>} detectOutcome
 */
```

---

### Task 1: Run-log store (`bin/engine/runlog.mjs`)

**Files:**
- Create: `bin/engine/runlog.mjs`
- Test: `bin/tests/engine-runlog.test.mjs`

**Interfaces:**
- Produces: `appendEvent(dir, issue, event) => void`, `readLog(dir, issue) => object[]`, `deriveState(events) => RunState`.
- Consumes: nothing (leaf module).

- [ ] **Step 1: Write the failing tests**

```js
// bin/tests/engine-runlog.test.mjs
import { describe, it, beforeEach, afterEach } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, rmSync, appendFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { appendEvent, readLog, deriveState } from "../engine/runlog.mjs";

let dir;
beforeEach(() => { dir = mkdtempSync(join(tmpdir(), "fd-runlog-")); });
afterEach(() => { rmSync(dir, { recursive: true, force: true }); });

describe("runlog", () => {
  it("append then read returns events in order with assigned seq", () => {
    appendEvent(dir, 42, { event: "RUN_START", issue: 42, run: "r1", lane: "staging" });
    appendEvent(dir, 42, { event: "PHASE_START", phase: "investigate" });
    const events = readLog(dir, 42);
    assert.equal(events.length, 2);
    assert.deepEqual(events.map(e => e.seq), [1, 2]);
    assert.equal(events[0].event, "RUN_START");
  });

  it("readLog tolerates a truncated final line (crash mid-write)", () => {
    appendEvent(dir, 42, { event: "RUN_START", issue: 42 });
    appendFileSync(join(dir, "42.jsonl"), '{"seq":2,"event":"PHA'); // no newline, partial JSON
    const events = readLog(dir, 42);
    assert.equal(events.length, 1); // partial final line ignored
  });

  it("deriveState: a PHASE_START without a following PHASE_COMMIT is NOT committed", () => {
    appendEvent(dir, 42, { event: "RUN_START", issue: 42, run: "r1", lane: "staging" });
    appendEvent(dir, 42, { event: "PHASE_START", phase: "investigate" });
    appendEvent(dir, 42, { event: "PHASE_COMMIT", phase: "investigate", outputs: {} });
    appendEvent(dir, 42, { event: "PHASE_START", phase: "build" }); // crashed here
    const s = deriveState(readLog(dir, 42));
    assert.deepEqual(s.committed, ["investigate"]);
    assert.equal(s.v, 3);       // last committed seq
    assert.equal(s.terminal, false);
  });

  it("deriveState: RUN_TERMINAL sets terminal + reason and carries branch/pr from commits", () => {
    appendEvent(dir, 42, { event: "RUN_START", issue: 42, run: "r1", lane: "staging" });
    appendEvent(dir, 42, { event: "PHASE_COMMIT", phase: "build", outputs: { branch: "fix/x-42" } });
    appendEvent(dir, 42, { event: "PHASE_COMMIT", phase: "review", outputs: { pr: 7 } });
    appendEvent(dir, 42, { event: "RUN_TERMINAL", reason: "merged" });
    const s = deriveState(readLog(dir, 42));
    assert.equal(s.terminal, true);
    assert.equal(s.terminalReason, "merged");
    assert.equal(s.branch, "fix/x-42");
    assert.equal(s.pr, 7);
  });

  it("deriveState of empty log is a zero-value state", () => {
    const s = deriveState([]);
    assert.equal(s.v, 0);
    assert.deepEqual(s.committed, []);
    assert.equal(s.phase, null);
  });
});
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `node --test bin/tests/engine-runlog.test.mjs`
Expected: FAIL — `Cannot find module '../engine/runlog.mjs'`.

- [ ] **Step 3: Write the implementation**

```js
// bin/engine/runlog.mjs
/**
 * Append-only per-issue run-log (the crash-safe local hot path).
 * One JSON event per line at {dir}/{issue}.jsonl. seq is assigned monotonically.
 */
import { readFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
import { join, dirname } from "node:path";

function logPath(dir, issue) { return join(dir, `${issue}.jsonl`); }

/** Append an event; assigns the next seq based on the current line count. */
export function appendEvent(dir, issue, event) {
  mkdirSync(dir, { recursive: true });
  const path = logPath(dir, issue);
  const seq = readLog(dir, issue).length + 1;
  appendFileSync(path, JSON.stringify({ seq, ...event }) + "\n");
}

/** Read all complete events; a truncated final line (crash mid-write) is ignored. */
export function readLog(dir, issue) {
  const path = logPath(dir, issue);
  if (!existsSync(path)) return [];
  const out = [];
  for (const line of readFileSync(path, "utf-8").split("\n")) {
    if (!line.trim()) continue;
    try { out.push(JSON.parse(line)); } catch { /* partial final line: ignore */ }
  }
  return out;
}

/** Fold events into a RunState. The commit rule lives here. */
export function deriveState(events) {
  /** @type {import("./phases.mjs").RunState} */
  const s = { v: 0, run: null, issue: null, lane: "staging", committed: [],
              phase: null, branch: null, pr: null, terminal: false,
              terminalReason: null, lease: null };
  for (const e of events) {
    switch (e.event) {
      case "RUN_START":
        s.run = e.run ?? s.run; s.issue = e.issue ?? s.issue; s.lane = e.lane ?? s.lane;
        break;
      case "PHASE_COMMIT":
        if (!s.committed.includes(e.phase)) s.committed.push(e.phase);
        s.v = e.seq;
        if (e.outputs?.branch) s.branch = e.outputs.branch;
        if (e.outputs?.pr != null) s.pr = e.outputs.pr;
        break;
      case "RUN_TERMINAL":
        s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
        break;
      // PHASE_START / PHASE_FAILED do not change committed state
    }
  }
  return s;
}
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `node --test bin/tests/engine-runlog.test.mjs`
Expected: PASS (5/5).

- [ ] **Step 5: Commit**

```bash
git add bin/engine/runlog.mjs bin/tests/engine-runlog.test.mjs
git commit -s -m "feat(engine): append-only run-log with commit-rule state derivation"
```

---

### Task 2: `FORGE:STATE` codec (`bin/engine/state.mjs`)

**Files:**
- Create: `bin/engine/state.mjs`
- Test: `bin/tests/engine-state.test.mjs`

**Interfaces:**
- Produces: `serializeState(index) => string`, `parseState(issueBody) => RunState|null`, `upsertStateBlock(body, index) => string`.
- Consumes: nothing.

- [ ] **Step 1: Write the failing tests**

```js
// bin/tests/engine-state.test.mjs
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { serializeState, parseState, upsertStateBlock } from "../engine/state.mjs";

const idx = { v: 7, run: "r1", issue: 42, lane: "staging",
  committed: ["investigate", "build"], phase: "review", branch: "fix/x-42",
  pr: null, terminal: false, terminalReason: null, lease: { by: "a7", until: 1000 } };

describe("state codec", () => {
  it("round-trips through serialize/parse", () => {
    const body = "Some issue text.\n\n" + serializeState(idx);
    const got = parseState(body);
    assert.deepEqual(got, idx);
  });

  it("parseState returns null when no block present", () => {
    assert.equal(parseState("no state here"), null);
  });

  it("upsertStateBlock replaces an existing block in place (no duplicate)", () => {
    let body = "Header\n\n" + serializeState(idx) + "\n\nFooter";
    body = upsertStateBlock(body, { ...idx, phase: "close", committed: [...idx.committed, "review"], v: 9 });
    assert.equal((body.match(/FORGE:STATE/g) || []).length, 1);
    assert.equal(parseState(body).phase, "close");
    assert.match(body, /Header/); assert.match(body, /Footer/);
  });

  it("upsertStateBlock appends a block when none exists", () => {
    const body = upsertStateBlock("Just text", idx);
    assert.equal(parseState(body).v, 7);
  });
});
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `node --test bin/tests/engine-state.test.mjs`
Expected: FAIL — module not found.

- [ ] **Step 3: Write the implementation**

```js
// bin/engine/state.mjs
/**
 * Codec for the single machine-readable FORGE:STATE HTML-comment block on an
 * issue body. Carries the COMPACT INDEX only (no rich per-phase outputs).
 */
const OPEN = "<!-- FORGE:STATE";
const CLOSE = "-->";
const BLOCK_RE = /<!-- FORGE:STATE\s*([\s\S]*?)-->/;

/** @param {import("./phases.mjs").RunState} index */
export function serializeState(index) {
  return `${OPEN}\n${JSON.stringify(index)}\n${CLOSE}`;
}

/** @returns {import("./phases.mjs").RunState|null} */
export function parseState(issueBody) {
  const m = BLOCK_RE.exec(issueBody || "");
  if (!m) return null;
  try { return JSON.parse(m[1].trim()); } catch { return null; }
}

/** Replace the FORGE:STATE block in place, or append one if absent. */
export function upsertStateBlock(body, index) {
  const block = serializeState(index);
  if (BLOCK_RE.test(body || "")) return body.replace(BLOCK_RE, () => block);
  return `${body || ""}\n\n${block}`.trimStart();
}
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `node --test bin/tests/engine-state.test.mjs`
Expected: PASS (4/4).

- [ ] **Step 5: Commit**

```bash
git add bin/engine/state.mjs bin/tests/engine-state.test.mjs
git commit -s -m "feat(engine): FORGE:STATE compact-index codec (serialize/parse/upsert)"
```

---

### Task 3: GitHub projector (`bin/engine/projector.mjs`)

**Files:**
- Create: `bin/engine/projector.mjs`
- Test: `bin/tests/engine-projector.test.mjs`

**Interfaces:**
- Consumes: `state.mjs` (`parseState`, `upsertStateBlock`).
- Produces: `makeProjector(io) => { readState(issue), writeState(issue, index), setLabel(issue, label), removeLabel(issue, label) }`, where `io.gh(args)` is an injected async fn returning stdout.

- [ ] **Step 1: Write the failing tests**

```js
// bin/tests/engine-projector.test.mjs
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { makeProjector } from "../engine/projector.mjs";
import { serializeState } from "../engine/state.mjs";

// Fake gh: records calls, serves a scripted issue body.
function fakeGh(body) {
  const calls = [];
  const gh = async (args) => {
    calls.push(args);
    if (args[0] === "issue" && args[1] === "view") return JSON.stringify({ body });
    if (args[0] === "issue" && args[1] === "edit") { body = argValue(args, "--body"); return ""; }
    return "";
  };
  return { gh, calls, getBody: () => body };
}
function argValue(args, flag) { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : null; }

const idx = { v: 3, run: "r1", issue: 42, lane: "staging", committed: ["investigate"],
  phase: "build", branch: null, pr: null, terminal: false, terminalReason: null, lease: null };

describe("projector", () => {
  it("readState returns null when the issue has no block", async () => {
    const f = fakeGh("plain body");
    const p = makeProjector({ gh: f.gh });
    assert.equal(await p.readState(42), null);
  });

  it("writeState upserts the block, readState reads it back", async () => {
    const f = fakeGh("Issue description.");
    const p = makeProjector({ gh: f.gh });
    await p.writeState(42, idx);
    assert.match(f.getBody(), /Issue description\./);       // original text preserved
    assert.deepEqual(await p.readState(42), idx);
  });

  it("setLabel calls gh issue edit --add-label", async () => {
    const f = fakeGh("x");
    const p = makeProjector({ gh: f.gh });
    await p.setLabel(42, "needs-human");
    assert.ok(f.calls.some(c => c.includes("--add-label") && c.includes("needs-human")));
  });
});
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `node --test bin/tests/engine-projector.test.mjs`
Expected: FAIL — module not found.

- [ ] **Step 3: Write the implementation**

```js
// bin/engine/projector.mjs
/**
 * GitHub adapter: reads/writes the FORGE:STATE block and workflow labels.
 * `io.gh(args)` is injected (async, returns stdout) so this is testable offline.
 */
import { parseState, upsertStateBlock } from "./state.mjs";

export function makeProjector(io) {
  const gh = io.gh;

  async function getBody(issue) {
    const out = await gh(["issue", "view", String(issue), "--json", "body"]);
    try { return JSON.parse(out).body ?? ""; } catch { return ""; }
  }

  return {
    /** @returns {Promise<import("./phases.mjs").RunState|null>} */
    async readState(issue) { return parseState(await getBody(issue)); },

    async writeState(issue, index) {
      const body = upsertStateBlock(await getBody(issue), index);
      await gh(["issue", "edit", String(issue), "--body", body]);
    },

    async setLabel(issue, label) {
      await gh(["issue", "edit", String(issue), "--add-label", label]);
    },

    async removeLabel(issue, label) {
      await gh(["issue", "edit", String(issue), "--remove-label", label]);
    },
  };
}
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `node --test bin/tests/engine-projector.test.mjs`
Expected: PASS (3/3).

- [ ] **Step 5: Commit**

```bash
git add bin/engine/projector.mjs bin/tests/engine-projector.test.mjs
git commit -s -m "feat(engine): GitHub projector for FORGE:STATE mirror + labels"
```

---

### Task 4: Phase table + `pickPhase` (`bin/engine/phases.mjs`)

**Files:**
- Create: `bin/engine/phases.mjs`
- Test: `bin/tests/engine-phases.test.mjs`

**Interfaces:**
- Produces: `PHASES` (Phase[]), `pickPhase(state) => Phase|null`, `TERMINAL_REASONS` (string[]).
- Consumes: `io` at call time for `reconcile`/`detectOutcome` (injected by the engine).

Each phase's `detectOutcome` inspects GitHub *after* the run (via `io.gh`/`io.git`) — the runner's return status is advisory only. The `build` phase encodes the #1305 fix (requires `FORGE:BUILDER:COMPLETE` **and** commits ahead of base).

- [ ] **Step 1: Write the failing tests**

```js
// bin/tests/engine-phases.test.mjs
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { PHASES, pickPhase } from "../engine/phases.mjs";

const base = { v: 0, run: "r1", issue: 42, lane: "staging", committed: [], phase: null,
  branch: null, pr: null, terminal: false, terminalReason: null, lease: null };

describe("pickPhase", () => {
  it("returns the first uncommitted phase whose entryCondition holds", () => {
    assert.equal(pickPhase(base).id, "investigate");
    assert.equal(pickPhase({ ...base, committed: ["investigate"] }).id, "context");
  });

  it("returns null once all phases are committed", () => {
    const all = PHASES.map(p => p.id);
    assert.equal(pickPhase({ ...base, committed: all }), null);
  });

  it("returns null when the state is already terminal", () => {
    assert.equal(pickPhase({ ...base, terminal: true, terminalReason: "invalid" }), null);
  });

  it("build.detectOutcome fails when there are no commits ahead of base (encodes #1305)", async () => {
    const build = PHASES.find(p => p.id === "build");
    const io = {
      gh: async () => JSON.stringify([{ body: "<!-- FORGE:BUILDER --> done <!-- FORGE:BUILDER:COMPLETE -->" }]),
      git: async () => "0", // rev-list count = 0 commits ahead
    };
    const outcome = await build.detectOutcome({ ...base, branch: "fix/x-42" }, io);
    assert.equal(outcome.status, "failed");
  });

  it("build.detectOutcome commits when :COMPLETE marker present AND commits exist", async () => {
    const build = PHASES.find(p => p.id === "build");
    const io = {
      gh: async () => JSON.stringify([{ body: "<!-- FORGE:BUILDER:COMPLETE -->" }]),
      git: async () => "2",
    };
    const outcome = await build.detectOutcome({ ...base, branch: "fix/x-42" }, io);
    assert.equal(outcome.status, "committed");
    assert.equal(outcome.outputs.branch, "fix/x-42");
  });
});
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `node --test bin/tests/engine-phases.test.mjs`
Expected: FAIL — module not found.

- [ ] **Step 3: Write the implementation**

```js
// bin/engine/phases.mjs
/**
 * Declarative phase table for the headless work-on pipeline. The ENGINE (not an
 * LLM) chooses the next phase via pickPhase. Each phase's outcome is read from
 * GitHub/git AFTER the run (detectOutcome); the runner's return is advisory.
 * @typedef ... (see plan "Shared types")
 */

export const TERMINAL_REASONS = ["merged", "invalid", "needs-human", "decomposed"];

/** Fetch the issue's comment bodies as one blob for marker checks. */
async function issueMarkers(issue, io) {
  const out = await io.gh(["api", `repos/{owner}/{repo}/issues/${issue}/comments`, "--jq", ".[].body"]);
  return out || "";
}
/** Count commits on branch ahead of the lane base. */
async function commitsAhead(state, io) {
  const n = await io.git(["rev-list", "--count", `origin/${state.lane}..${state.branch}`]);
  return parseInt(String(n).trim(), 10) || 0;
}
function has(blob, marker) { return blob.includes(marker); }

/** @type {Phase[]} */
export const PHASES = [
  {
    id: "investigate",
    command: "work-on/investigate",
    entryCondition: () => true,
    async detectOutcome(state, io) {
      const m = await issueMarkers(state.issue, io);
      if (has(m, "INVESTIGATION:INVALID"))
        return { status: "committed", terminalReason: "invalid", outputs: { verdict: "INVALID" } };
      if (has(m, "DECOMPOSE:YES"))
        return { status: "committed", terminalReason: "decomposed", outputs: { decompose: true } };
      if (has(m, "INVESTIGATION:COMPLETE"))
        return { status: "committed", outputs: { verdict: "CONFIRMED" } };
      return { status: "failed", detail: "no INVESTIGATION:COMPLETE marker" };
    },
    isTerminalAfter: (s) => s.terminalReason === "invalid" || s.terminalReason === "decomposed",
  },
  {
    id: "context",
    command: "work-on/build/context",
    entryCondition: (s) => s.committed.includes("investigate"),
    async detectOutcome(state, io) {
      const m = await issueMarkers(state.issue, io);
      // Context is non-critical: a missing marker is a VISIBLE skip, not a hard fail (spec §7).
      if (has(m, "FORGE:CONTEXT")) return { status: "committed", outputs: {} };
      return { status: "committed", outputs: { skipped: true, which: "context" } };
    },
  },
  {
    id: "architect",
    command: "work-on/build/architect",
    entryCondition: (s) => s.committed.includes("context"),
    async detectOutcome(state, io) {
      const m = await issueMarkers(state.issue, io);
      return has(m, "FORGE:ARCHITECT")
        ? { status: "committed", outputs: {} }
        : { status: "failed", detail: "no FORGE:ARCHITECT" };
    },
  },
  {
    id: "build",
    command: "work-on/build",
    entryCondition: (s) => s.committed.includes("architect"),
    async reconcile(state, io) {
      // Idempotent resume: branch already ahead of base → treat as done, skip the LLM.
      if (state.branch && (await commitsAhead(state, io)) > 0) {
        const m = await issueMarkers(state.issue, io);
        if (has(m, "FORGE:BUILDER:COMPLETE")) return { satisfied: true, outputs: { branch: state.branch } };
      }
      return { satisfied: false };
    },
    async detectOutcome(state, io) {
      const m = await issueMarkers(state.issue, io);
      const complete = has(m, "FORGE:BUILDER:COMPLETE");           // #1305: require :COMPLETE …
      const ahead = state.branch ? await commitsAhead(state, io) : 0; // … AND real commits
      if (complete && ahead > 0) return { status: "committed", outputs: { branch: state.branch } };
      return { status: "failed", detail: `builder complete=${complete} commitsAhead=${ahead}` };
    },
  },
  {
    id: "review",
    command: "work-on/review",
    entryCondition: (s) => s.committed.includes("build"),
    async reconcile(state, io) {
      const pr = await openPrFor(state, io);   // adopt an existing PR instead of opening a second
      return pr ? { satisfied: false, outputs: { pr } } : { satisfied: false };
    },
    async detectOutcome(state, io) {
      const pr = await prStatusFor(state, io);
      if (!pr) return { status: "failed", detail: "no PR created" };
      if (pr.merged) return { status: "committed", outputs: { pr: pr.number } };
      if (pr.needsHuman) return { status: "blocked", detail: "review escalated", outputs: { pr: pr.number } };
      return { status: "failed", detail: "PR open, not merged" };
    },
  },
  {
    id: "close",
    command: "work-on/close",
    entryCondition: (s) => s.committed.includes("review"),
    async detectOutcome(state, io) {
      const out = await io.gh(["issue", "view", String(state.issue), "--json", "state,labels"]);
      const j = JSON.parse(out || "{}");
      const labels = (j.labels || []).map((l) => l.name || l);
      if (j.state === "CLOSED" || labels.includes("workflow:merged"))
        return { status: "committed", terminalReason: "merged", outputs: {} };
      return { status: "failed", detail: "issue not closed" };
    },
    isTerminalAfter: () => true,
  },
];

async function openPrFor(state, io) {
  if (!state.branch) return null;
  const out = await io.gh(["pr", "list", "--head", state.branch, "--json", "number", "--state", "all"]);
  try { const a = JSON.parse(out || "[]"); return a[0]?.number ?? null; } catch { return null; }
}
async function prStatusFor(state, io) {
  const n = await openPrFor(state, io);
  if (!n) return null;
  const out = await io.gh(["pr", "view", String(n), "--json", "number,state,labels,mergedAt"]);
  const j = JSON.parse(out || "{}");
  const labels = (j.labels || []).map((l) => l.name || l);
  return { number: j.number, merged: !!j.mergedAt || j.state === "MERGED",
           needsHuman: labels.includes("needs-human") };
}

/** The engine's transition function: first uncommitted phase whose gate holds. */
export function pickPhase(state) {
  if (state.terminal) return null;
  for (const p of PHASES) {
    if (state.committed.includes(p.id)) continue;
    if (p.entryCondition(state)) return p;
  }
  return null;
}
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `node --test bin/tests/engine-phases.test.mjs`
Expected: PASS (5/5).

- [ ] **Step 5: Commit**

```bash
git add bin/engine/phases.mjs bin/tests/engine-phases.test.mjs
git commit -s -m "feat(engine): declarative phase table + deterministic pickPhase"
```

---

### Task 5: State reconciliation (`bin/engine/reconcile.mjs`)

**Files:**
- Create: `bin/engine/reconcile.mjs`
- Test: `bin/tests/engine-reconcile.test.mjs`

**Interfaces:**
- Produces: `reconcileState(local, remote) => { state:RunState, action:"local"|"hydrate"|"remirror"|"fresh" }`.
- Consumes: nothing (pure).

- [ ] **Step 1: Write the failing tests**

```js
// bin/tests/engine-reconcile.test.mjs
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { reconcileState } from "../engine/reconcile.mjs";

const mk = (v, phase) => ({ v, run: "r1", issue: 42, lane: "staging",
  committed: [], phase, branch: null, pr: null, terminal: false, terminalReason: null, lease: null });

describe("reconcileState (GitHub wins)", () => {
  it("no remote, no local → fresh", () => {
    assert.equal(reconcileState(null, null).action, "fresh");
  });
  it("no local, remote present → hydrate from remote", () => {
    const r = reconcileState(null, mk(3, "build"));
    assert.equal(r.action, "hydrate"); assert.equal(r.state.phase, "build");
  });
  it("remote ahead of local → GitHub wins (hydrate), discard local", () => {
    const r = reconcileState(mk(3, "build"), mk(5, "review"));
    assert.equal(r.action, "hydrate"); assert.equal(r.state.v, 5);
  });
  it("local ahead of remote → keep local, re-mirror", () => {
    const r = reconcileState(mk(5, "review"), mk(3, "build"));
    assert.equal(r.action, "remirror"); assert.equal(r.state.v, 5);
  });
  it("in sync → keep local", () => {
    const r = reconcileState(mk(3, "build"), mk(3, "build"));
    assert.equal(r.action, "local"); assert.equal(r.state.v, 3);
  });
});
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `node --test bin/tests/engine-reconcile.test.mjs`
Expected: FAIL — module not found.

- [ ] **Step 3: Write the implementation**

```js
// bin/engine/reconcile.mjs
/**
 * Merge the local run-log state and the remote FORGE:STATE index.
 * Rule: GitHub wins on divergence (spec §5.3).
 */
export function reconcileState(local, remote) {
  if (!remote) return { state: local ?? null, action: local ? "local" : "fresh" };
  if (!local) return { state: remote, action: "hydrate" };
  if (remote.v > local.v) return { state: remote, action: "hydrate" };   // advanced elsewhere
  if (remote.v < local.v) return { state: local, action: "remirror" };   // crashed pre-mirror
  return { state: local, action: "local" };
}
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `node --test bin/tests/engine-reconcile.test.mjs`
Expected: PASS (5/5).

- [ ] **Step 5: Commit**

```bash
git add bin/engine/reconcile.mjs bin/tests/engine-reconcile.test.mjs
git commit -s -m "feat(engine): state reconciliation (GitHub wins on divergence)"
```

---

### Task 6: Engine loop (`bin/engine.mjs`)

**Files:**
- Create: `bin/engine.mjs`
- Test: `bin/tests/engine.test.mjs`

**Interfaces:**
- Consumes: `runlog.mjs`, `phases.mjs`, `reconcile.mjs`, `projector.mjs`.
- Produces: `runIssue({ issue, dir, agentId, lane, io, runner, now, maxAttempts }) => Promise<{terminalReason:string}>`.
  - `io = { gh, git }` (async, injected). `runner` is a `runCommand`-shaped async fn. `now()` returns ms. `dir` is the run-log directory. `maxAttempts` defaults to 3.

- [ ] **Step 1: Write the failing test (golden path + visible block)**

```js
// bin/tests/engine.test.mjs
import { describe, it, beforeEach, afterEach } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { runIssue } from "../engine.mjs";
import { readLog, deriveState } from "../engine/runlog.mjs";

let dir; beforeEach(() => { dir = mkdtempSync(join(tmpdir(), "fd-engine-")); });
afterEach(() => { rmSync(dir, { recursive: true, force: true }); });

// A scriptable fake GitHub/git world whose markers advance as phases "run".
function fakeWorld() {
  const w = { markers: "", pr: null, prMerged: false, prNeedsHuman: false,
              issueState: "OPEN", labels: [], commitsAhead: 0, body: "Issue." };
  const io = {
    gh: async (args) => {
      const a = args.join(" ");
      if (a.startsWith("api ") && a.includes("/comments")) return w.markers;
      if (a.startsWith("issue view") && a.includes("body")) return JSON.stringify({ body: w.body });
      if (a.startsWith("issue view")) return JSON.stringify({ state: w.issueState, labels: w.labels });
      if (a.startsWith("issue edit")) { const i = args.indexOf("--body"); if (i>=0) w.body = args[i+1];
        const j = args.indexOf("--add-label"); if (j>=0) w.labels.push(args[j+1]); return ""; }
      if (a.startsWith("pr list")) return JSON.stringify(w.pr ? [{ number: w.pr }] : []);
      if (a.startsWith("pr view")) return JSON.stringify({ number: w.pr, state: w.prMerged?"MERGED":"OPEN",
        mergedAt: w.prMerged ? "t" : null, labels: w.prNeedsHuman ? [{name:"needs-human"}] : [] });
      return "";
    },
    git: async () => String(w.commitsAhead),
  };
  return { w, io };
}

describe("runIssue", () => {
  it("drives investigate→close to merged, committing every phase", async () => {
    const { w, io } = fakeWorld();
    // Each phase run advances the world so detectOutcome sees a committed result.
    const script = {
      "work-on/investigate": () => { w.markers += " INVESTIGATION:COMPLETE"; },
      "work-on/build/context": () => { w.markers += " FORGE:CONTEXT"; },
      "work-on/build/architect": () => { w.markers += " FORGE:ARCHITECT"; },
      "work-on/build": () => { w.markers += " FORGE:BUILDER:COMPLETE"; w.commitsAhead = 2; },
      "work-on/review": () => { w.pr = 7; w.prMerged = true; },
      "work-on/close": () => { w.issueState = "CLOSED"; },
    };
    const runner = async ({ commandName }) => { script[commandName](); return { status: "complete" }; };

    const res = await runIssue({ issue: 42, dir, agentId: "a1", lane: "staging",
      io, runner, now: () => 1000, maxAttempts: 3 });

    assert.equal(res.terminalReason, "merged");
    const s = deriveState(readLog(dir, 42));
    assert.deepEqual(s.committed, ["investigate","context","architect","build","review","close"]);
    assert.equal(s.branch, "fix/pipeline-42"); // set by engine before build (see impl)
  });

  it("stops at needs-human when a phase reports blocked (no silent merge)", async () => {
    const { w, io } = fakeWorld();
    const script = {
      "work-on/investigate": () => { w.markers += " INVESTIGATION:COMPLETE"; },
      "work-on/build/context": () => { w.markers += " FORGE:CONTEXT"; },
      "work-on/build/architect": () => { w.markers += " FORGE:ARCHITECT"; },
      "work-on/build": () => { w.markers += " FORGE:BUILDER:COMPLETE"; w.commitsAhead = 1; },
      "work-on/review": () => { w.pr = 7; w.prNeedsHuman = true; },
    };
    const runner = async ({ commandName }) => { script[commandName]?.(); return { status: "complete" }; };
    const res = await runIssue({ issue: 42, dir, agentId: "a1", lane: "staging",
      io, runner, now: () => 1000, maxAttempts: 1 });
    assert.equal(res.terminalReason, "needs-human");
    assert.ok(w.labels.includes("needs-human"));
  });
});
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `node --test bin/tests/engine.test.mjs`
Expected: FAIL — `Cannot find module '../engine.mjs'`.

- [ ] **Step 3: Write the implementation**

```js
// bin/engine.mjs
/**
 * Durable per-phase engine loop. Drives one pipeline phase at a time via an
 * injected runner (runCommand-shaped), determining each phase's outcome from
 * GitHub state (phase.detectOutcome). All effects are injected → fully testable.
 */
import { fileURLToPath } from "node:url";
import { appendEvent, readLog, deriveState } from "./engine/runlog.mjs";
import { pickPhase, TERMINAL_REASONS } from "./engine/phases.mjs";
import { reconcileState } from "./engine/reconcile.mjs";
import { makeProjector } from "./engine/projector.mjs";

const DEFAULT_MAX_ATTEMPTS = 3;

export async function runIssue(opts) {
  const { issue, dir, agentId, lane = "staging", io, runner,
          now = () => Date.now(), maxAttempts = DEFAULT_MAX_ATTEMPTS,
          commandsDir = fileURLToPath(new URL("../commands", import.meta.url)) } = opts;
  const projector = makeProjector(io);

  // 1. Load + reconcile (GitHub wins).
  const local = readLog(dir, issue).length ? deriveState(readLog(dir, issue)) : null;
  const remote = await projector.readState(issue);
  let { state, action } = reconcileState(local, remote);
  if (!state) {
    state = freshState(issue, lane);
    appendEvent(dir, issue, { event: "RUN_START", issue, run: state.run, lane });
    await projector.writeState(issue, state);
  } else if (action === "remirror") {
    await projector.writeState(issue, state);
  }

  // 2. Drive phases until terminal.
  let phase;
  while ((phase = pickPhase(state))) {
    // Every issue's build works on a deterministic branch; set it before build runs.
    if (phase.id === "build" && !state.branch) state.branch = `fix/pipeline-${issue}`;

    const reconciled = phase.reconcile ? await phase.reconcile(state, io) : { satisfied: false };
    let outcome;
    if (reconciled.satisfied) {
      outcome = { status: "committed", outputs: reconciled.outputs || {} };
    } else {
      if (reconciled.outputs?.pr) state.pr = reconciled.outputs.pr;
      outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts });
    }

    if (outcome.status === "blocked") return await terminate(state, "needs-human", outcome.detail);

    // committed
    appendEvent(dir, issue, { event: "PHASE_COMMIT", phase: phase.id, outputs: outcome.outputs || {} });
    state = deriveState(readLog(dir, issue));
    if (outcome.terminalReason) state.terminalReason = outcome.terminalReason;
    await projector.writeState(issue, { ...state, lease: { by: agentId, until: now() + 600000 } });

    if (outcome.terminalReason && TERMINAL_REASONS.includes(outcome.terminalReason))
      return await terminate(state, outcome.terminalReason);
    if (phase.isTerminalAfter && phase.isTerminalAfter(state))
      return await terminate(state, state.terminalReason || "merged");
  }
  return await terminate(state, state.terminalReason || "merged");

  async function terminate(s, reason, detail) {
    appendEvent(dir, issue, { event: "RUN_TERMINAL", reason });
    const final = { ...deriveState(readLog(dir, issue)), terminal: true, terminalReason: reason, lease: null };
    await projector.writeState(issue, final);
    if (reason === "needs-human") await projector.setLabel(issue, "needs-human");
    return { terminalReason: reason, detail };
  }
}

async function runPhaseWithRetry(phase, state, ctx) {
  const { io, runner, dir, issue, commandsDir, maxAttempts } = ctx;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    appendEvent(dir, issue, { event: "PHASE_START", phase: phase.id, attempt });
    try {
      await runner({ commandsDir, commandName: phase.command, args: [String(issue)] });
    } catch (e) {
      appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: e.message });
      continue;
    }
    const outcome = await phase.detectOutcome(state, io);
    if (outcome.status === "committed" || outcome.status === "blocked") return outcome;
    appendEvent(dir, issue, { event: "PHASE_FAILED", phase: phase.id, attempt, reason: outcome.detail });
  }
  // Exhausted transient retries → escalate (spec §7).
  return { status: "blocked", detail: `phase ${phase.id} failed after ${maxAttempts} attempts` };
}

function freshState(issue, lane) {
  return { v: 0, run: `r_${issue}_${lane}`, issue, lane, committed: [], phase: null,
           branch: null, pr: null, terminal: false, terminalReason: null, lease: null };
}
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `node --test bin/tests/engine.test.mjs`
Expected: PASS (2/2).

- [ ] **Step 5: Commit**

```bash
git add bin/engine.mjs bin/tests/engine.test.mjs
git commit -s -m "feat(engine): durable per-phase loop (runIssue) with retry + needs-human"
```

---

### Task 7: Crash-injection durability test (`bin/tests/engine-crash.test.mjs`)

**Files:**
- Create: `bin/tests/engine-crash.test.mjs`

**Interfaces:**
- Consumes: `runIssue` (Task 6), `runlog` helpers. No new production code — this task proves the durability property.

- [ ] **Step 1: Write the failing test**

```js
// bin/tests/engine-crash.test.mjs
import { describe, it, beforeEach, afterEach } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { runIssue } from "../engine.mjs";
import { readLog, deriveState } from "../engine/runlog.mjs";

let dir; beforeEach(() => { dir = mkdtempSync(join(tmpdir(), "fd-crash-")); });
afterEach(() => { rmSync(dir, { recursive: true, force: true }); });

function fakeWorld() {
  const w = { markers:"", pr:null, prMerged:false, issueState:"OPEN", labels:[], commitsAhead:0, body:"Issue." };
  const io = { gh: async (args) => { const a=args.join(" ");
    if (a.includes("/comments")) return w.markers;
    if (a.startsWith("issue view") && a.includes("body")) return JSON.stringify({ body:w.body });
    if (a.startsWith("issue view")) return JSON.stringify({ state:w.issueState, labels:w.labels });
    if (a.startsWith("issue edit")) { const i=args.indexOf("--body"); if(i>=0) w.body=args[i+1];
      const j=args.indexOf("--add-label"); if(j>=0) w.labels.push(args[j+1]); return ""; }
    if (a.startsWith("pr list")) return JSON.stringify(w.pr?[{number:w.pr}]:[]);
    if (a.startsWith("pr view")) return JSON.stringify({ number:w.pr, state:w.prMerged?"MERGED":"OPEN", mergedAt:w.prMerged?"t":null, labels:[] });
    return ""; }, git: async () => String(w.commitsAhead) };
  return { w, io };
}
const scriptFor = (w) => ({
  "work-on/investigate": () => { w.markers += " INVESTIGATION:COMPLETE"; },
  "work-on/build/context": () => { w.markers += " FORGE:CONTEXT"; },
  "work-on/build/architect": () => { w.markers += " FORGE:ARCHITECT"; },
  "work-on/build": () => { w.markers += " FORGE:BUILDER:COMPLETE"; w.commitsAhead = 2; },
  "work-on/review": () => { w.pr = 7; w.prMerged = true; },
  "work-on/close": () => { w.issueState = "CLOSED"; },
});

describe("crash injection", () => {
  it("resumes correctly when the process dies after each phase", async () => {
    const { w, io } = fakeWorld();
    const script = scriptFor(w);
    const order = ["work-on/investigate","work-on/build/context","work-on/build/architect","work-on/build","work-on/review","work-on/close"];

    // Run 1..N: each run "crashes" (throws) right after the k-th phase's runner executes.
    for (let crashAfter = 1; crashAfter <= order.length; crashAfter++) {
      let seen = 0;
      const runner = async ({ commandName }) => {
        script[commandName]();                 // real side effect happens…
        seen++;
        if (seen === crashAfter) throw new Error("SIMULATED CRASH"); // …then the process dies
        return { status: "complete" };
      };
      try { await runIssue({ issue: 42, dir, agentId: "a1", lane: "staging", io, runner, now: () => 1 }); }
      catch { /* crashed; next run resumes from the log */ }
    }
    // Final clean run finishes whatever remains.
    const runner = async ({ commandName }) => { script[commandName](); return { status: "complete" }; };
    const res = await runIssue({ issue: 42, dir, agentId: "a1", lane: "staging", io, runner, now: () => 1 });

    assert.equal(res.terminalReason, "merged");
    const s = deriveState(readLog(dir, 42));
    assert.deepEqual(s.committed, ["investigate","context","architect","build","review","close"]);
    // No phase double-committed (idempotent): each id appears once.
    assert.equal(new Set(s.committed).size, s.committed.length);
    // Exactly one PR was ever adopted (review.reconcile prevented a second).
    assert.equal(w.pr, 7);
  });
});
```

> **CORRECTION (supersedes the code block above).** Injecting the crash from the `runner` does NOT work: `runPhaseWithRetry` catches a thrown runner as a retryable `PHASE_FAILED` (so the run completes in one launch — a false positive), and `maxAttempts: 1` makes a single failure escalate straight to `needs-human` (breaking the run), not resume. A true process death must be injected where `runIssue` does NOT internally catch it: (1) the `projector.writeState` FORGE:STATE mirror (engine.mjs:53), which fires *after* the local `PHASE_COMMIT` is appended — resume must continue from the run-log; and (2) `phase.detectOutcome` (engine.mjs:81), which fires *after* a phase's side effect but *before* its commit — the phase must re-run idempotently. The committed `bin/tests/engine-crash.test.mjs` injects at both points (via a fake `io.gh`/`io.git` that throws once), relaunches `runIssue` like a supervisor, and asserts `launches >= 2` so the crash provably fired.

- [ ] **Step 2: Run the test to verify it fails (if it does), then reconcile**

Run: `node --test bin/tests/engine-crash.test.mjs`
Expected: 9/9 PASS — 8 mirror-crash points (initial state write + 6 phase commits + terminate) plus 1 mid-phase build crash, each asserting `launches >= 2` so resume is provably exercised (see the CORRECTION note below for why the crash is injected at the mirror/detectOutcome, not the runner).

- [ ] **Step 3: Commit**

```bash
git add bin/tests/engine-crash.test.mjs
git commit -s -m "test(engine): crash-injection proves per-phase resume + idempotency"
```

---

### Task 8: Headless CLI entry + stall scan (`bin/engine-cli.mjs`, wire into `bin/forgedock.mjs`)

**Files:**
- Create: `bin/engine-cli.mjs`
- Modify: `bin/forgedock.mjs` (add a `run-issue` subcommand case in the command switch near the existing `install/init/...` dispatch)
- Test: `bin/tests/engine-cli.test.mjs`

**Interfaces:**
- Consumes: `runIssue` (Task 6).
- Produces: `makeIo() => {gh, git}` (real `gh`/`git` via `execFile`), `scanStalls(issues, dir, io, now) => number[]` (issues whose lease expired on a non-terminal state), and `runFromCli(argv)`.

Note: the subcommand is named `run-issue`, not `run`, to avoid colliding with the pre-existing `forgedock run <command>` spec-runner from #1151.

- [ ] **Step 1: Write the failing test for `scanStalls` (pure, no network)**

```js
// bin/tests/engine-cli.test.mjs
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { scanStalls } from "../engine-cli.mjs";

describe("scanStalls", () => {
  it("flags issues whose lease expired and state is non-terminal", () => {
    const now = 10_000;
    const states = {
      42: { terminal: false, lease: { by: "a1", until: 5_000 } },   // expired → stalled
      43: { terminal: false, lease: { by: "a2", until: 20_000 } },  // live → ok
      44: { terminal: true,  lease: null },                          // done → ok
    };
    const io = { readState: async (i) => states[i] };
    return scanStalls([42, 43, 44], io, now).then((stalled) => {
      assert.deepEqual(stalled, [42]);
    });
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `node --test bin/tests/engine-cli.test.mjs`
Expected: FAIL — module not found.

- [ ] **Step 3: Write the implementation**

```js
// bin/engine-cli.mjs
/**
 * Headless entry point: `forgedock run-issue <issue>` drives one issue through the
 * durable engine; scanStalls finds dead-lease issues for the orchestrator to resume.
 */
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { homedir } from "node:os";
import { join } from "node:path";
import { runIssue } from "./engine.mjs";

const pexec = promisify(execFile);

/** Real gh/git accessors. */
export function makeIo() {
  const run = (bin) => async (args) => {
    const { stdout } = await pexec(bin, args, { maxBuffer: 100 * 1024 * 1024 });
    return stdout;
  };
  return { gh: run("gh"), git: run("git") };
}

export function runDir() { return join(homedir(), ".forge", "runs"); }

/**
 * @param {number[]} issues
 * @param {{readState:(i:number)=>Promise<{terminal:boolean,lease:?{until:number}}|null>}} io
 * @param {number} now
 * @returns {Promise<number[]>} issues that appear stalled (expired lease, non-terminal)
 */
export async function scanStalls(issues, io, now) {
  const stalled = [];
  for (const i of issues) {
    const s = await io.readState(i);
    if (s && !s.terminal && s.lease && s.lease.until < now) stalled.push(i);
  }
  return stalled;
}

export async function runFromCli(argv) {
  const issue = parseInt(argv[0], 10);
  if (!Number.isInteger(issue)) throw new Error("usage: forgedock run-issue <issue-number>");
  const lane = flag(argv, "--lane") || "staging";
  const io = makeIo();
  const agentId = `cli_${process.pid}`;
  const res = await runIssue({ issue, dir: runDir(), agentId, lane, io,
    runner: (await import("./runner.mjs")).runCommand, now: () => Date.now() });
  console.log(`issue #${issue} → ${res.terminalReason}`);
  return res;
}
function flag(argv, name) { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }
```

- [ ] **Step 4: Wire the subcommand into `bin/forgedock.mjs`**

Add a `case` to the existing command switch (the block that dispatches `install`/`init`/`update`/`help`). Locate it and insert:

```js
    case "run-issue": {
      const { runFromCli } = await import("./engine-cli.mjs");
      await runFromCli(process.argv.slice(3));
      break;
    }
```

Note: named `run-issue`, not `run`, to avoid colliding with the pre-existing `forgedock run <command>` spec-runner from #1151.

- [ ] **Step 5: Run test to verify it passes**

Run: `node --test bin/tests/engine-cli.test.mjs`
Expected: PASS (1/1).

- [ ] **Step 6: Verify the full engine suite is green**

Run: `node --test "bin/tests/**/*.test.mjs"`
Expected: PASS — all engine suites plus the pre-existing runner/tui/etc. suites.

- [ ] **Step 7: Commit**

```bash
git add bin/engine-cli.mjs bin/tests/engine-cli.test.mjs bin/forgedock.mjs
git commit -s -m "feat(engine): forgedock run-issue headless entry + lease-based stall scan"
```

---

### Task 9: Documentation — orchestrator integration note

**Files:**
- Modify: `commands/orchestrate.md` (add a short "Engine mode" section)
- Modify: `docs/superpowers/specs/2026-07-03-durable-execution-engine-design.md` (mark status: Implemented once Tasks 1–8 land)

**Interfaces:** none (docs only).

- [ ] **Step 1: Add an "Engine mode (headless)" subsection to `commands/orchestrate.md`**

Insert after the existing wave-dispatch description:

```markdown
### Engine mode (headless)

When running headless/CI, dispatch each issue via the durable engine instead of a
prose agent:

    forgedock run <issue> --lane <staging|milestone/slug>

The engine drives every phase transition deterministically, mirrors state to the
`FORGE:STATE` block on the issue, and holds a lease. To recover stalls, scan the
in-flight issues' `FORGE:STATE`; any issue with an expired lease and a non-terminal
state is re-dispatched with the same `forgedock run <issue>` command — it resumes
from the last committed phase (idempotent). This replaces the label-heuristic
"already in progress" check and the resume-with-nagging loop.
```

- [ ] **Step 2: Commit**

```bash
git add commands/orchestrate.md docs/superpowers/specs/2026-07-03-durable-execution-engine-design.md
git commit -s -m "docs(orchestrate): document headless engine mode + lease-based resume"
```

---

## Self-Review

**1. Spec coverage**

| Spec section | Task(s) |
|---|---|
| §4 components: runlog / state / projector / phases / engine | 1 / 2 / 3 / 4 / 6 |
| §5.1 run-log schema + commit rule | 1 |
| §5.2 FORGE:STATE compact index | 2, 3 |
| §5.3 resume + divergence (GitHub wins) | 5, 6 |
| §6 deterministic pickPhase | 4 |
| §6 phase idempotency (reconcile) | 4 (build/review), 6 (invocation) |
| §7 failure taxonomy (committed/failed/blocked, visible skips) | 4 (skip in context), 6 (retry/block) |
| §8 lease + orchestrator integration | 6 (lease write), 8 (scanStalls), 9 (docs) |
| §9 testing (units + crash injection) | 1–6 units, 7 crash injection |
| §12 definition of done | 6 (drive to merged), 7 (resume proof), 8 (headless entry) |

No spec section is left without a task.

**2. Placeholder scan:** No "TBD"/"handle edge cases"/"similar to Task N". Every code step shows complete code; every phase entry is fully written.

**3. Type consistency:** `RunState` shape (`v`, `committed`, `phase`, `branch`, `pr`, `terminal`, `terminalReason`, `lease`) is identical across `runlog.deriveState`, `state` codec, `reconcileState`, `phases`, and `engine`. `PhaseOutcome.status` values (`committed`/`failed`/`blocked`) match between `phases.detectOutcome` and `engine.runPhaseWithRetry`. `io = {gh, git}` and the `runner` signature (`{commandsDir, commandName, args}`) match `runner.runCommand`'s real parameters (verified against `origin/main:bin/runner.mjs`).

**Known follow-ups (out of scope, tracked separately):** full per-phase `reconcile` for context/architect/close; oversized-diff handling in `review` (verification spec #1315); interactive Claude Code adapter; in-process worker-pool vs process-per-issue decision (spec §10).