pan-wizard 3.24.0 → 3.26.0

package/pan-wizard-core/bin/lib/verify-deploy.cjs

@@ -135,7 +135,13 @@ function validateRuntimeInstall(cwd, configDir, runtime) {
     }
   }
 
-  const status = missing.length > 0 ? 'broken' : modified.length > 0 ? 'modified' : 'clean';
+  const mcp = validateMcpRegistration(cwd, configDir, runtime);
+  if (!mcp.ok) settingsIssues.push(...mcp.issues);
+
+  const status = missing.length > 0 ? 'broken'
+    : modified.length > 0 ? 'modified'
+      : !mcp.ok ? 'modified'
+        : 'clean';
 
   return {
     status,
@@ -144,11 +150,114 @@ function validateRuntimeInstall(cwd, configDir, runtime) {
     missing,
     modified,
     orphaned: [],
-    settings_ok: settingsOk,
+    settings_ok: settingsOk && mcp.ok,
     settings_issues: settingsIssues,
+    mcp,
   };
 }
 
+/**
+ * Where each runtime's MCP registration lives, relative to the project (claude)
+ * or to the runtime's config dir (everything else), and under which container
+ * key. This MIRRORS `MCP_REGISTRATION` in bin/install-lib.cjs — the installer
+ * writes, this reads, and the two must agree.
+ *
+ * Duplicated rather than imported on purpose: install-lib.cjs is installer-side
+ * and is NOT shipped into an install, while this module runs from inside one. A
+ * scenario test pins the two tables against each other so the copy cannot drift
+ * silently.
+ *
+ * `codex` is absent because registration there is `register: false` — PAN prints
+ * a TOML snippet rather than writing config, so there is nothing to verify.
+ */
+const MCP_EXPECTED = {
+  claude: { rel: '.mcp.json', fromProjectRoot: true, key: 'mcpServers' },
+  copilot: { rel: 'mcp.json', fromProjectRoot: false, key: 'mcpServers' },
+  gemini: { rel: 'settings.json', fromProjectRoot: false, key: 'mcpServers' },
+  opencode: { rel: 'opencode.json', fromProjectRoot: false, key: 'mcp' },
+};
+
+/**
+ * Verify the MCP registration this install wrote.
+ *
+ * WHY: `registerMcpServer()` writes up to four config files per install, and this
+ * verdict is the only thing most callers check afterwards. Until 2026-08 it had no
+ * idea MCP existed, so a fresh install reported `clean` whether registration
+ * succeeded, was skipped because the server file was missing, or was refused
+ * because the runtime's config was unparseable JSON. The installer recorded those
+ * cases as warnings; nothing surfaced them where anyone looks.
+ *
+ * Every part of this is checkable without launching the bridge: the config is
+ * present, it parses, it carries a `pan` entry, and the server path in that entry
+ * exists on disk. Whether a RUNTIME then loads it is a separate claim this cannot
+ * make, and does not.
+ *
+ * @returns {{ok:boolean, registered:boolean, path:string|null, issues:string[]}}
+ */
+function validateMcpRegistration(cwd, configDir, runtime) {
+  const spec = MCP_EXPECTED[runtime];
+  // codex (and any future register:false runtime) has nothing to verify.
+  if (!spec) return { ok: true, registered: false, path: null, issues: [], skipped: 'no-registration-by-design' };
+
+  // ONLY expect a registration when this install actually SHIPS the bridge.
+  //
+  // An install made before the MCP bridge existed has no `.mcp.json` and never
+  // should have — flagging it would be a false alarm on every older deployment,
+  // and the first version of this check did exactly that, turning four green
+  // fixtures red for lacking a file they were never supposed to have. The
+  // installed tree is the authority: if `pan-wizard-core/mcp/server.cjs` is
+  // present, registration is expected; if it is not, there is nothing to verify.
+  const bridge = path.join(cwd, configDir, 'pan-wizard-core', 'mcp', 'server.cjs');
+  try {
+    fs.accessSync(bridge);
+  } catch (_) {
+    return { ok: true, registered: false, path: null, issues: [], skipped: 'bridge-not-in-this-install' };
+  }
+
+  const configPath = spec.fromProjectRoot
+    ? path.join(cwd, spec.rel)
+    : path.join(cwd, configDir, spec.rel);
+  const shown = path.relative(cwd, configPath) || spec.rel;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    // Absent and unparseable are different failures and must read differently:
+    // one means registration never happened, the other means PAN deliberately
+    // left a file it could not safely rewrite.
+    const missingFile = e && e.code === 'ENOENT';
+    return {
+      ok: false,
+      registered: false,
+      path: shown,
+      issues: [missingFile
+        ? `MCP not registered: ${shown} is missing`
+        : `MCP config unreadable (left untouched by design): ${shown} — ${e.message}`],
+    };
+  }
+
+  const bag = parsed && parsed[spec.key];
+  const entry = bag && typeof bag === 'object' ? bag.pan : undefined;
+  if (!entry) {
+    return { ok: false, registered: false, path: shown, issues: [`MCP not registered: no "pan" entry under "${spec.key}" in ${shown}`] };
+  }
+
+  // The server path is `args[0]` everywhere except opencode, whose `command` is a
+  // single array of [cmd, ...args] — the shape difference that has already caused
+  // one bug in this feature.
+  const serverPath = Array.isArray(entry.command) ? entry.command[1] : (entry.args && entry.args[0]);
+  const issues = [];
+  if (!serverPath) {
+    issues.push(`MCP entry in ${shown} names no server path`);
+  } else {
+    try { fs.accessSync(serverPath); } catch (_) {
+      issues.push(`MCP server path does not exist: ${serverPath} (from ${shown})`);
+    }
+  }
+  return { ok: issues.length === 0, registered: true, path: shown, server: serverPath || null, issues };
+}
+
 /**
  * CLI command: validate deployment
  * Validates PAN installations in the current directory.
@@ -190,4 +299,6 @@ module.exports = {
   detectInstalledRuntimes,
   validateRuntimeInstall,
   cmdValidateDeployment,
+  validateMcpRegistration,
+  MCP_EXPECTED,
 };

package/pan-wizard-core/bin/lib/worktree.cjs

@@ -89,6 +89,91 @@ function listArmyWorktrees(cwd) {
   return out;
 }
 
+/**
+ * Sweep every army worktree and orphaned army/ branch (P-1815, PanLoop
+ * finding 13). The what-if subsystem always had this (`whatif cleanup`); the
+ * army path created worktrees that nothing removed — sibling `pan-army-*`
+ * directories and `army/*` branches accumulated after every campaign.
+ *
+ * Safety posture (the L3 lesson — never trade clutter for silent data loss):
+ * - A DIRTY worktree is kept unless `force` — git refuses, we surface why.
+ * - A branch is deleted only when its tip is reachable from HEAD (truly
+ *   integrated). Squash-merged and aborted branches are NOT reachable and may
+ *   hold the only copy of real work, so by default they are KEPT and listed
+ *   with the exact command to delete them; `force` sweeps them too.
+ *   (The per-task Phase 5 teardown — `worktree remove --branch` right after
+ *   the merge lands — deletes unconditionally; at that moment the deletion is
+ *   the documented intent. The sweeper is the abort/orphan tool, so it errs
+ *   the other way.)
+ * @param {string} cwd - main project root
+ * @param {Object} [opts] - { force: boolean }
+ * @returns {{removed_worktrees, deleted_branches, kept, pruned, clean}|{error}}
+ */
+function cleanupArmyWorktrees(cwd, opts) {
+  if (!isGitRepo(cwd)) return { error: 'Not a git repo' };
+  const force = opts?.force === true;
+  const removedWorktrees = [];
+  const deletedBranches = [];
+  const kept = [];
+
+  const branchIsIntegrated = (branch) =>
+    execGit(cwd, ['merge-base', '--is-ancestor', branch, 'HEAD']).exitCode === 0;
+
+  const deleteBranch = (branch, hadWorktree) => {
+    if (force || branchIsIntegrated(branch)) {
+      const del = execGit(cwd, ['branch', '-D', branch]);
+      if (del.exitCode === 0) deletedBranches.push(branch);
+      else kept.push({ branch, reason: `branch -D failed: ${del.stderr.trim()}` });
+    } else {
+      kept.push({
+        branch,
+        reason: `carries commits not reachable from HEAD (squash-merged or aborted work${hadWorktree ? '' : '; no worktree attached'}) — rerun with --force, or: git branch -D ${branch}`,
+      });
+    }
+  };
+
+  // 1. Registered army worktrees. Track every branch step 1 has already
+  //    decided on — deleted OR deliberately kept — so the orphan scan below
+  //    does not re-process (and double-report) it.
+  const handledBranches = new Set();
+  for (const t of listArmyWorktrees(cwd)) {
+    const rmArgs = ['worktree', 'remove'];
+    if (force) rmArgs.push('--force');
+    rmArgs.push(t.worktree);
+    const rm = execGit(cwd, rmArgs);
+    if (rm.exitCode !== 0) {
+      kept.push({ worktree: t.worktree, branch: t.branch, reason: `worktree remove refused: ${rm.stderr.trim()} — pass --force to discard uncommitted changes` });
+      if (t.branch) handledBranches.add(t.branch);
+      continue;
+    }
+    removedWorktrees.push(t.worktree);
+    if (t.branch) {
+      handledBranches.add(t.branch);
+      deleteBranch(t.branch, true);
+    }
+  }
+
+  // 2. Drop stale registrations (a manually deleted directory leaves one).
+  const pruned = execGit(cwd, ['worktree', 'prune']).exitCode === 0;
+
+  // 3. Orphaned army/ branches — a worktree removed without its branch.
+  const stillAttached = new Set(listArmyWorktrees(cwd).map(t => t.branch));
+  const ls = execGit(cwd, ['branch', '--list', `${ARMY_BRANCH_PREFIX}*`, '--format=%(refname:short)']);
+  if (ls.exitCode === 0) {
+    for (const branch of ls.stdout.split(/\r?\n/).map(s => s.trim()).filter(Boolean)) {
+      if (!stillAttached.has(branch) && !handledBranches.has(branch)) deleteBranch(branch, false);
+    }
+  }
+
+  return {
+    removed_worktrees: removedWorktrees,
+    deleted_branches: deletedBranches,
+    kept,
+    pruned,
+    clean: kept.length === 0,
+  };
+}
+
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 
 function cmdWorktreeList(cwd, raw) {
@@ -112,12 +197,25 @@ function cmdWorktreeRemove(cwd, worktreePath, branch, raw, opts) {
   output(r, raw, r.warnings.length ? r.warnings.join('\n') : 'removed');
 }
 
+function cmdWorktreeCleanup(cwd, raw, opts) {
+  const r = cleanupArmyWorktrees(cwd, opts);
+  if (r.error) return error(r.error);
+  const lines = [
+    ...r.removed_worktrees.map(w => `removed worktree ${w}`),
+    ...r.deleted_branches.map(b => `deleted branch ${b}`),
+    ...r.kept.map(k => `KEPT ${k.worktree || k.branch}: ${k.reason}`),
+  ];
+  output(r, raw, lines.length ? lines.join('\n') : 'nothing to clean');
+}
+
 module.exports = {
   ARMY_BRANCH_PREFIX,
   createTaskWorktree,
   removeTaskWorktree,
   listArmyWorktrees,
+  cleanupArmyWorktrees,
   cmdWorktreeList,
   cmdWorktreeCreate,
   cmdWorktreeRemove,
+  cmdWorktreeCleanup,
 };

package/pan-wizard-core/bin/pan-tools.cjs

@@ -1191,8 +1191,10 @@ async function main() {
         worktree.cmdWorktreeCreate(cwd, args[2], raw, { base: getArgValue(args, '--base') });
       } else if (subcommand === 'remove') {
         worktree.cmdWorktreeRemove(cwd, args[2], getArgValue(args, '--branch'), raw, { force: args.includes('--force') });
+      } else if (subcommand === 'cleanup') {
+        worktree.cmdWorktreeCleanup(cwd, raw, { force: args.includes('--force') });
       } else {
-        error('Unknown worktree subcommand. Available: list, create, remove');
+        error('Unknown worktree subcommand. Available: list, create, remove, cleanup');
       }
       break;
     }
@@ -1497,7 +1499,24 @@ async function main() {
         break;
       }
 
-      // Default: convenience alias for optimize learn (existing behavior)
+      // BARE `learn` is the documented convenience alias for `optimize learn`
+      // (docs/CLI-REFERENCE.md lists it as `learn (alias)`), so it is kept.
+      //
+      // An UNKNOWN subcommand, however, used to fall through to that same alias
+      // and silently run trace analysis. A ledger flagged `learn` as colliding
+      // with `optimize learn`; the collision turned out to be a superset rather
+      // than two meanings, but this fallthrough was the real defect underneath —
+      // `pan-tools learn promotee` (a typo) ran the analyser and returned a
+      // trace-session error, so the caller concluded `promote` was broken.
+      //
+      // `learn` was also the ONLY group of the ~33 that never published an
+      // "Available:" list, which made its subcommands invisible both to a user
+      // and to the suggestion index that is now parsed from those strings.
+      // Publishing it fixes the error AND feeds the suggester, with no second
+      // list to maintain.
+      if (subcommand) {
+        error('Unknown learn subcommand. Available: promote, unpromote, list-promoted, build-index, topics-for, lint');
+      }
       optimize.cmdOptimizeLearn(cwd, {
         sessionId: getArgValue(args, '--session'),
       }, raw);
@@ -1526,8 +1545,27 @@ async function main() {
       error(`Unknown links subcommand: ${subcommand}. Available: validate`);
     }
 
-    default:
-      error(`Unknown command: ${command}. Run pan-tools --help to see available commands.`);
+    default: {
+      // A ledger recorded `pan-tools trace` 18 times — the most-repeated agent
+      // behaviour it had seen — and every one got "unknown, go read the list".
+      // But `trace` is a REAL subcommand one namespace away (`optimize trace`),
+      // so naming the right form turns a dead end into a self-correction. The
+      // docs were cleared as the cause, which is exactly why the fix belongs
+      // here: it works whatever led the caller to type it.
+      //
+      // Parsed from this file's own "Available:" strings on the error path only,
+      // so nothing is paid on a healthy call and no second list can drift. Fails
+      // open to the original message.
+      let hint = '';
+      try {
+        const suggest = require('./lib/suggest.cjs');
+        const src = require('fs').readFileSync(__filename, 'utf8');
+        const topLevel = (USAGE.split('Commands: ')[1] || '').split(',').map((s) => s.trim()).filter(Boolean);
+        hint = suggest.formatSuggestions(
+          suggest.suggestCommand(command, suggest.buildSubcommandIndex(src), topLevel));
+      } catch { /* suggestions are a courtesy — never let them mask the error */ }
+      error(`Unknown command: ${command}.${hint} Run pan-tools --help to see available commands.`);
+    }
   }
 }
 

package/pan-wizard-core/mcp/native-tools.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * PAN-Z M2 — native MCP tools whose logic lives in-process (not a pan-tools spawn).
+ *
+ * These are the deterministic grafts the review demanded: the orchestrator's
+ * `next-action` state machine and the two-step merge gate. A native tool declares a
+ * `handler({ cwd, input, env, gitImpl }) -> { json | text, isError? }` instead of a
+ * `verb`; a thrown Error is surfaced as JSON-RPC -32602 (invalid params) by the server.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const mergeGate = require('./merge-gate.cjs');
+const orchestrator = require('./orchestrator.cjs');
+
+/**
+ * Fill in the `verified` run fact from disk where the caller did not state it.
+ *
+ * WHY THIS EXISTS. `nextAction` is pure and takes `verified`/`merged` as run
+ * facts, which is what makes the human merge gate reachable at all. But nothing
+ * asks the caller to remember them, and a phase that is `complete` without
+ * `verified` returns `verify` — so a project whose phases were completed in an
+ * earlier session would be told to verify phase 1 forever. That is a live-lock of
+ * exactly the kind this whole fix set out to remove, just moved one step along.
+ *
+ * PAN already records verification on disk: `verification.md` (or
+ * `*-verification.md`) inside the phase directory. `classifyPhaseStatus()` ignores
+ * it — it counts plans against summaries and nothing else — which is precisely why
+ * `verified` could not come from the status vocabulary and had to be a run fact.
+ *
+ * So: derive it here, in the impure layer that has a cwd, and leave `nextAction`
+ * pure. An explicit value from the caller always wins. `merged` is NOT derived —
+ * no file records it, and a phase resting at `request_merge` until a human acts is
+ * the gate working, not a stall.
+ *
+ * Fail-open: any fs problem leaves the snapshot exactly as the caller sent it.
+ */
+function enrichVerifiedFromDisk(cwd, state) {
+  if (!state || !Array.isArray(state.phases)) return state;
+  let phaseDirs;
+  try {
+    const root = path.join(cwd, '.planning', 'phases');
+    phaseDirs = fs.readdirSync(root, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => ({ name: e.name, full: path.join(root, e.name) }));
+  } catch {
+    return state; // no .planning/phases — nothing to derive
+  }
+
+  const hasVerification = (dir) => {
+    try {
+      return fs.readdirSync(dir).some((f) => f === 'verification.md' || f.endsWith('-verification.md'));
+    } catch { return false; }
+  };
+
+  const phases = state.phases.map((p) => {
+    if (!p || typeof p !== 'object' || p.verified !== undefined) return p;
+    const num = String(p.number == null ? '' : p.number).trim();
+    if (!num) return p;
+    // Phase dirs are `NN-slug`; match on the leading number with or without
+    // zero padding, so both "3" and "03" find `03-foo`.
+    const padded = num.padStart(2, '0');
+    const match = phaseDirs.find((d) => d.name === num || d.name.startsWith(`${num}-`) || d.name.startsWith(`${padded}-`));
+    if (!match) return p;
+    return hasVerification(match.full) ? Object.assign({}, p, { verified: true }) : p;
+  });
+  return Object.assign({}, state, { phases });
+}
+
+const NATIVE_TOOLS = [
+  {
+    name: 'pan_next_action',
+    title: 'Next deterministic action',
+    // The description is the ONLY thing an LLM caller reads, so it names the
+    // correct source explicitly. An audit found callers following the old prose
+    // ("assemble from the pan-mcp resources") straight into an infinite plan
+    // loop: `pan://progress` reports Title Case and `pan://phases` returns
+    // directory names with no status at all. `pan_roadmap_analyze` is the source
+    // whose shape actually matches — say so here rather than in a comment.
+    description: 'Given a phase snapshot, return the next step the primary agent should take (plan/execute/verify/request_merge/await_approval/stop), enforcing the safety caps, the regression circuit-breaker and the human merge gate. Build `state.phases` from `pan_roadmap_analyze` (its `phases[].disk_status` matches this contract); `pan://phases` carries no status and is NOT a substitute. Set `verified`/`merged` on a phase once you have performed those steps — they are run facts no file records, and without them the merge gate is never reached.',
+    readOnly: true, destructive: false,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['state'],
+      properties: {
+        state: {
+          type: 'object',
+          // `phases` is REQUIRED. It previously was not, so `{}` — or any object
+          // with a misspelled key — collapsed to an empty list and reported
+          // "all_complete / done:true", i.e. a malformed request read as success.
+          required: ['phases'],
+          properties: {
+            phases: {
+              type: 'array',
+              description: 'Ordered phases. status is the lowercase disk vocabulary (empty|discussed|researched|planned|partial|complete); case is folded, so Title Case from pan://progress is accepted.',
+              items: {
+                type: 'object',
+                required: ['status'],
+                properties: {
+                  number: { type: ['number', 'string'] },
+                  status: { type: 'string' },
+                  verified: { type: 'boolean', description: 'Run fact: verification passed for this phase.' },
+                  merged: { type: 'boolean', description: 'Run fact: this phase has been merged.' },
+                },
+              },
+            },
+            cycles: { type: 'number' },
+            points_used: { type: 'number' },
+            tests_before: { type: 'number' },
+            tests_after: { type: 'number' },
+            awaiting_approval: { type: 'boolean' },
+            aborted: { type: 'boolean' },
+          },
+        },
+        caps: { type: 'object' },
+      },
+    },
+    handler: ({ cwd, input }) => {
+      if (!input.state || typeof input.state !== 'object') throw new Error('Invalid "state": an object snapshot is required');
+      // Derive `verified` from disk for any phase the caller left unset, so the
+      // verify step terminates on a real project instead of looping. Explicit
+      // caller values are never overwritten.
+      return { json: orchestrator.nextAction(enrichVerifiedFromDisk(cwd, input.state), input.caps) };
+    },
+  },
+  {
+    name: 'pan_request_merge',
+    title: 'Request a gated merge',
+    description: 'Stage a squash-merge request for a branch and mark it awaiting human approval. Records intent only — does NOT merge.',
+    readOnly: false, destructive: false,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['branch'],
+      properties: { branch: { type: 'string' }, ci_green: { type: 'boolean' }, verify_pass: { type: 'boolean' } },
+    },
+    handler: ({ cwd, input }) => ({
+      json: mergeGate.requestMerge(cwd, { branch: input.branch, ci_green: input.ci_green, verify_pass: input.verify_pass }),
+    }),
+  },
+  {
+    name: 'pan_confirm_merge',
+    title: 'Confirm a human-approved merge',
+    description: 'Perform a squash-merge ONLY if CI is green, verify passed, and a human-origin approval token (env PAN_MERGE_APPROVAL equal to the request\'s approval_token) is present. Any agent-supplied approval is ignored; never force-pushes or rewrites history.',
+    readOnly: false, destructive: true,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['branch'],
+      properties: { branch: { type: 'string' } },
+    },
+    handler: ({ cwd, input, env, gitImpl }) => {
+      const res = mergeGate.confirmMerge(cwd, { branch: input.branch }, env, gitImpl);
+      // A refused gate (missing approval / CI / verify) is a normal, non-error result the
+      // agent should read; only a real git failure is flagged isError.
+      const gitFailed = !res.merged && Array.isArray(res.reasons)
+        && res.reasons.some((r) => r === 'git_merge_failed' || r === 'git_commit_failed');
+      return { json: res, isError: gitFailed };
+    },
+  },
+];
+
+module.exports = { NATIVE_TOOLS };

package/pan-wizard-core/mcp/orchestrator.cjs

@@ -0,0 +1,179 @@
+'use strict';
+
+/**
+ * The deterministic orchestrator ("next-action" state machine).
+ *
+ * A host with no workflow engine cannot machine-intercept a subagent spawn, so
+ * PAN's sequencing + safety harness (waves, regression circuit-breaker,
+ * spawn/budget caps, the human merge gate) cannot live in agent prose or a
+ * pre-spawn hook. The fix: keep the state machine here and expose ONE
+ * `next-action` tool the primary Agent polls before each step. Enforcement then
+ * happens at the (gateable) MCP-tool-call boundary, not at the (un-gateable)
+ * spawn event.
+ *
+ * `nextAction` is a PURE function of a snapshot, so its decisions are
+ * reproducible and unit-testable.
+ *
+ * ─── THE VOCABULARY, and why it is what it is ──────────────────────────────
+ *
+ * An external audit (2026-08-15) found this machine keyed on statuses that
+ * NOTHING IN PAN EMITS. It expected `executed` and `verified`; the only producer
+ * of a phase status is `classifyPhaseStatus()` (bin/lib/utils.cjs), which emits
+ *
+ *     complete · partial · planned · researched · discussed · empty
+ *
+ * The consequences were severe and all three were reproduced before this rewrite:
+ *
+ *   1. `verify` and `request_merge` were UNREACHABLE. A phase ran
+ *      planned → execute → complete and the machine moved to the next one, so
+ *      **the human merge gate — the safety centrepiece — was skipped entirely.**
+ *   2. `partial` had no entry and fell through to `plan`, re-planning a
+ *      half-executed phase forever (a live-lock).
+ *   3. `pan://progress` reports Title Case (`"Planned"`), so a caller following
+ *      this file's own instruction to assemble the snapshot from the MCP
+ *      resources got `undefined` → `plan` on every cycle, forever.
+ *
+ * The suite was green throughout because its fixtures spoke `executed`/`verified`
+ * — a vocabulary no producer emits. The fixture was MORE capable than reality and
+ * therefore produced false confidence. Fixtures here must use the real vocabulary.
+ *
+ * ─── The model now ─────────────────────────────────────────────────────────
+ *
+ * Disk status answers "how far did the artifacts get?". It cannot answer "was
+ * this verified?" or "was it merged?" — those are RUN facts, known to the caller
+ * that just performed them, and no file on disk records them. So a phase carries
+ * its disk status plus two optional booleans:
+ *
+ *     { number, status, verified?: boolean, merged?: boolean }
+ *
+ * which makes the full ladder reachable from the vocabulary PAN actually emits:
+ *
+ *     planned                        → execute
+ *     partial                        → execute   (RESUME, never re-plan)
+ *     empty | discussed | researched → plan
+ *     complete & !verified           → verify
+ *     complete &  verified & !merged → request_merge
+ *     complete &  verified &  merged → (skip; this phase is finished)
+ */
+
+// Budget is advisory by default (enforceBudget:false) — it never stops the loop
+// unless the caller opts in. maxCycles remains a hard safety stop.
+const DEFAULT_CAPS = { maxCycles: 25, budget: Infinity, enforceBudget: false };
+
+/**
+ * Disk status → next action, for statuses that precede execution.
+ * Keys are the REAL `classifyPhaseStatus()` vocabulary. `complete` is absent on
+ * purpose: what follows completion depends on the run facts, not on disk.
+ *
+ * The two legacy keys are retained as aliases so a caller written against the
+ * old contract keeps working, but nothing in PAN produces them.
+ */
+const PHASE_NEXT = {
+  // real disk vocabulary
+  empty: 'plan',
+  discussed: 'plan',
+  researched: 'plan',
+  planned: 'execute',
+  partial: 'execute',
+  // legacy aliases — no producer emits these; kept for callers written against
+  // the pre-2026-08 contract. Do NOT use them in new fixtures.
+  none: 'plan',
+  executed: 'verify',
+  verified: 'request_merge',
+};
+
+/** Statuses meaning "the artifacts are all there". */
+const COMPLETE_STATUS = 'complete';
+
+/**
+ * Normalise a status to the lowercase vocabulary the table keys on.
+ *
+ * `pan://progress` emits Title Case (`"Planned"`) while `roadmap analyze` emits
+ * lowercase (`"planned"`); this file's docs point callers at the resources, so
+ * the Title Case form is the one a compliant caller will actually send. Folding
+ * case here is what makes the documented assembly path work at all.
+ */
+function normalizeStatus(status) {
+  return typeof status === 'string' ? status.trim().toLowerCase() : '';
+}
+
+/** True when a phase still needs work of any kind. */
+function isPhaseOpen(phase) {
+  if (!phase || typeof phase !== 'object') return false;
+  const status = normalizeStatus(phase.status);
+  if (status !== COMPLETE_STATUS) return true;
+  // Complete on disk, but the run facts decide whether it is actually finished.
+  return !(phase.verified === true && phase.merged === true);
+}
+
+/**
+ * Decide the next deterministic action.
+ *
+ * @param {Object} state snapshot:
+ *   { phases:[{number, status, verified?, merged?}], cycles?, points_used?,
+ *     tests_before?, tests_after?, awaiting_approval?, aborted? }
+ *   `phases` is REQUIRED. A snapshot without a usable one is reported as
+ *   `no_phases` / `done:false` — never as success (see below).
+ * @param {Object} [caps] { maxCycles, budget, enforceBudget }
+ * @returns {{action:string, args?:Object, reason:string, done:boolean}}
+ *   action ∈ plan | execute | verify | request_merge | await_approval | stop
+ */
+function nextAction(state, caps) {
+  const c = Object.assign({}, DEFAULT_CAPS, caps || {});
+  state = state || {};
+
+  // Hard stops first — safety caps and the circuit-breaker outrank all progress.
+  if (state.aborted) return { action: 'stop', reason: 'aborted', done: true };
+  if (
+    typeof state.tests_before === 'number' &&
+    typeof state.tests_after === 'number' &&
+    state.tests_after < state.tests_before
+  ) {
+    return { action: 'stop', reason: 'regression', done: true };
+  }
+  if ((state.cycles || 0) >= c.maxCycles) return { action: 'stop', reason: 'max_cycles', done: true };
+  if (c.enforceBudget && (state.points_used || 0) >= c.budget) return { action: 'stop', reason: 'budget_cap', done: true };
+
+  // The human merge gate is a barrier: while a merge awaits approval, do nothing else.
+  if (state.awaiting_approval) return { action: 'await_approval', reason: 'human_gate', done: false };
+
+  // A MISSING OR MISSHAPEN `phases` IS NOT SUCCESS.
+  //
+  // This previously collapsed to `[]`, and `[].find(...)` is indistinguishable
+  // from "every phase is complete" — so `{}`, a wrong key, or a non-array all
+  // returned all_complete/done:true. An orchestrator wrong in the "keep working"
+  // direction wastes tokens and gets noticed; one wrong in the `done:true`
+  // direction silently stops the loop and reports success. `no_phases` carries
+  // `done:false` precisely so a caller cannot mistake "I could not read this"
+  // for "the work is finished".
+  const hasPhases = Array.isArray(state.phases)
+    && state.phases.some((p) => p && typeof p === 'object' && (p.status !== undefined || p.number !== undefined));
+  if (!hasPhases) {
+    return { action: 'stop', reason: 'no_phases', done: false };
+  }
+
+  // Advance the first phase that is not finished.
+  const phase = state.phases.find(isPhaseOpen);
+  if (!phase) return { action: 'stop', reason: 'all_complete', done: true };
+
+  const status = normalizeStatus(phase.status);
+  const args = { phase: phase.number };
+
+  // Complete on disk: the run facts decide. This is the branch that makes the
+  // merge gate reachable — without it a completed phase was simply skipped.
+  if (status === COMPLETE_STATUS) {
+    if (phase.verified !== true) return { action: 'verify', args, reason: 'phase_complete_unverified', done: false };
+    return { action: 'request_merge', args, reason: 'phase_verified_unmerged', done: false };
+  }
+
+  const action = PHASE_NEXT[status];
+  if (!action) {
+    // An unknown status is a caller/producer mismatch, not a licence to re-plan.
+    // Say so, rather than silently defaulting the way the old `|| 'plan'` did —
+    // that default is what turned Title Case into an infinite plan loop.
+    return { action: 'plan', args, reason: `phase_unknown_status_${status || 'missing'}`, done: false };
+  }
+  return { action, args, reason: `phase_${status}`, done: false };
+}
+
+module.exports = { nextAction, DEFAULT_CAPS, PHASE_NEXT, normalizeStatus, isPhaseOpen };