pan-wizard 3.25.0 → 3.27.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/verify.cjs

@@ -9,7 +9,7 @@ const { safeReadFile, normalizePhaseName, comparePhaseNum, execGit, findPhaseInt
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd, readStateSafe } = require('./state.cjs');
 const {
-  PLANNING_DIR, PHASES_DIR, STATE_FILE, ROADMAP_FILE, REQUIREMENTS_FILE, CONFIG_FILE, PROJECT_FILE, PATTERNS_FILE,
+  PHASES_DIR, STATE_FILE, ROADMAP_FILE, REQUIREMENTS_FILE, CONFIG_FILE, PROJECT_FILE, PATTERNS_FILE,
   isPlanFile, isSummaryFile, isVerificationFile, PHASE_HEADER_RE, PHASE_DIR_RE, ARCHIVE_DIR_RE, FIELD_VALUE_RE,
   PLAN_SUFFIX, SUMMARY_SUFFIX, STANDARDS_FILE, STANDARDS_CATALOG, HEALTH_STATUS,
   BUILTIN_DRIFT_RULES, DRIFT_VERDICTS, BINARY_EXTENSIONS, DRIFT_MAX_FILES, DRIFT_MAX_FILE_SIZE, DRIFT_SEVERITY_WEIGHTS,
@@ -21,6 +21,7 @@ const { runDriftCheck, parseConventionRules, checkFileConventions, calculateDrif
 const { collectVerificationStats, countRoadmapPhases, groupGapPatterns, cmdRetro } = require('./verify-retro.cjs');
 const { detectInstalledRuntimes, validateRuntimeInstall, cmdValidateDeployment } = require('./verify-deploy.cjs');
 const { cmdPreflight, cmdDepsValidate } = require('./verify-preflight.cjs');
+const { planningRootRel } = require('./planning-root.cjs');
 
 /**
  * Spot-check files mentioned in summary content.
@@ -715,7 +716,7 @@ function cmdValidateConsistency(cwd, raw) {
  */
 function checkPlanningDirExists(cwd, addIssue) {
   if (!fileAccessible(planningPath(cwd))) {
-    addIssue('error', 'E001', PLANNING_DIR + '/ directory not found', 'Run /pan:new-project to initialize');
+    addIssue('error', 'E001', planningRootRel() + '/ directory not found', 'Run /pan:new-project to initialize');
     return false;
   }
   return true;
@@ -998,7 +999,7 @@ function repairIssues(cwd, repairs) {
           const milestone = getMilestoneInfo(cwd);
           let stateContent = '# Session State\n\n';
           stateContent += '## Project Reference\n\n';
-          stateContent += `See: ${PLANNING_DIR}/${PROJECT_FILE}\n\n`;
+          stateContent += `See: ${planningRootRel()}/${PROJECT_FILE}\n\n`;
           stateContent += '## Position\n\n';
           stateContent += `**Milestone:** ${milestone.version} ${milestone.name}\n`;
           stateContent += '**Current phase:** (determining...)\n';

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

@@ -19,7 +19,6 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error, safeReadFile, isGitRepo, execGit, toPosix, findPhaseInternal } = require('./core.cjs');
-const { PLANNING_DIR } = require('./constants.cjs');
 const { planningPath } = require('./utils.cjs');
 
 const COUNTERFACTUALS_DIR = 'counterfactuals';

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

@@ -128,7 +128,7 @@
  *   init verify-work <phase>           All context for verify-work workflow
  *   init phase-op <phase>              Generic phase operation context
  *   init todos [area]                  All context for todo workflows
- *   init milestone-op                  All context for milestone operations
+ *   init milestone-op [--all-tracks]   All context for milestone operations
  *   init map-codebase                  All context for map-codebase workflow
  *   init progress                      All context for progress workflow
  *
@@ -219,6 +219,8 @@ const docLint = require('./lib/doc-lint.cjs');
 const learnLint = require('./lib/learn-lint.cjs');
 const learnIndex = require('./lib/learn-index.cjs');
 const links = require('./lib/links.cjs');
+const { setPlanningRoot, describePlanningRoot } = require('./lib/planning-root.cjs');
+const stateCompact = require('./lib/state-compact.cjs');
 
 /**
  * Get the value following a flag in the args array.
@@ -233,6 +235,30 @@ function getArgValue(args, flag, defaultVal = null) {
   return args[idx + 1];
 }
 
+/**
+ * Read a global `--flag value` / `--flag=value` pair and REMOVE it from args,
+ * so per-command parsers never see it. Returns null when the flag is absent.
+ *
+ * @param {string[]} args - CLI arguments (mutated)
+ * @param {string} flag - Flag name (e.g. '--track')
+ * @returns {string|null} The flag's value, or null
+ */
+function takeFlagValue(args, flag) {
+  const eqArg = args.find(a => a.startsWith(`${flag}=`));
+  if (eqArg) {
+    const value = eqArg.slice(flag.length + 1).trim();
+    if (!value) error(`Missing value for ${flag}`);
+    args.splice(args.indexOf(eqArg), 1);
+    return value;
+  }
+  const idx = args.indexOf(flag);
+  if (idx === -1) return null;
+  const value = args[idx + 1];
+  if (!value || value.startsWith('--')) error(`Missing value for ${flag}`);
+  args.splice(idx, 2);
+  return value;
+}
+
 /**
  * Parse JSON string or call error() with a descriptive message.
  * @param {string} raw - Raw JSON string
@@ -270,6 +296,22 @@ async function main() {
     error(`Invalid --cwd: ${cwd}`);
   }
 
+  // Which planning tree do we act on? `--cwd` moves the PROJECT root; these
+  // move the PLANNING root inside it, so a repo holding several planning trees
+  // can address any of them. Parsed here, before dispatch, because the answer
+  // has to be settled once for every path the command will build.
+  const planningDirFlag = takeFlagValue(args, '--planning-dir');
+  const trackFlag = takeFlagValue(args, '--track');
+  const allTracksIndex = args.indexOf('--all-tracks');
+  const allTracks = allTracksIndex !== -1;
+  if (allTracks) args.splice(allTracksIndex, 1);
+
+  try {
+    setPlanningRoot({ planningDir: planningDirFlag, track: trackFlag });
+  } catch (e) {
+    error(e.message);
+  }
+
   const rawIndex = args.indexOf('--raw');
   const raw = rawIndex !== -1;
   if (rawIndex !== -1) args.splice(rawIndex, 1);
@@ -282,7 +324,13 @@ async function main() {
 
   const command = args[0];
 
-  const USAGE = 'Usage: pan-tools <command> [args] [--raw] [--cwd <path>]\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, state-snapshot, summary-extract, rollback-snapshot, batch-commit, websearch, focus, preflight, dashboard, hud, report, learnings, deps, drift-check, memory, bridge, whatif, knowledge, skills, hygiene, review-deep, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links';
+  const USAGE = 'Usage: pan-tools <command> [args] [--raw] [--cwd <path>] [--track <name> | --planning-dir <path>] [--all-tracks]\n'
+    + '\nPlanning root (which .planning tree to act on):\n'
+    + '  --track <name>         act on .planning/tracks/<name>/ instead of .planning/\n'
+    + '  --planning-dir <path>  act on an arbitrary project-relative planning tree\n'
+    + '  --all-tracks           (hygiene) act on the root tree AND every discovered track\n'
+    + '  env: PAN_TRACK, PAN_PLANNING_DIR (flags win)\n'
+    + '\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, state-snapshot, summary-extract, rollback-snapshot, batch-commit, websearch, focus, preflight, dashboard, hud, report, learnings, deps, drift-check, memory, bridge, whatif, knowledge, skills, hygiene, review-deep, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links';
 
   if (!command) {
     error(USAGE);
@@ -317,6 +365,11 @@ async function main() {
           }
         }
         state.cmdStatePatch(cwd, patches, raw);
+      } else if (subcommand === 'compact') {
+        stateCompact.cmdStateCompact(cwd, {
+          apply: args.includes('--apply'),
+          keepDays: getArgValue(args, '--keep-days'),
+        }, raw);
       } else if (subcommand === 'advance-plan') {
         state.cmdStateAdvancePlan(cwd, raw);
       } else if (subcommand === 'record-metric') {
@@ -765,7 +818,7 @@ async function main() {
           init.cmdInitTodos(cwd, args[2], raw);
           break;
         case 'milestone-op':
-          init.cmdInitMilestoneOp(cwd, raw);
+          init.cmdInitMilestoneOp(cwd, raw, { allTracks });
           break;
         case 'map-codebase':
           init.cmdInitMapCodebase(cwd, raw);
@@ -1087,13 +1140,14 @@ async function main() {
       const hygieneOpts = {
         traceAgeDays: getArgValue(args, '--trace-age-days'),
         apply: args.includes('--apply'),
+        allTracks,
       };
       if (subcommand === 'scan') {
         hygiene.cmdHygieneScan(cwd, hygieneOpts, raw);
       } else if (subcommand === 'clean') {
         hygiene.cmdHygieneClean(cwd, hygieneOpts, raw);
       } else {
-        error('Unknown hygiene subcommand. Available: scan, clean [--apply] [--trace-age-days N]');
+        error('Unknown hygiene subcommand. Available: scan, clean [--apply] [--trace-age-days N] [--all-tracks] [--track <name>]');
       }
       break;
     }
@@ -1499,7 +1553,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);
@@ -1528,8 +1599,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 };