pan-wizard 3.36.0 → 3.37.0

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

@@ -0,0 +1,143 @@
+'use strict';
+/**
+ * CI as an oracle for the autodev loop (program A2).
+ *
+ * The loop never takes a session's word for its tests. Locally the oracle is the phase
+ * gate and the test-run engine (V1, V2); with `autodev run --ci` it is also the pull
+ * request's checks, read through GitHub's `gh` CLI (optional: without it the CI oracle
+ * is `unavailable`). A check that already fails on the base branch is not this change's
+ * doing and is ignored. The failing log tail is what a fix round gets as feedback, and a
+ * breaker stops after N rounds.
+ *
+ * `autodev run --ci local` needs no pull request: the oracle is the project's own gate,
+ * run here — `npm run ci:local` when package.json has that script, else `npm test`.
+ */
+
+const { spawnSync } = require('child_process');
+
+const DEFAULT_CI_ROUNDS = 3;
+
+function defaultExec(cwd) {
+  const refused = require('./autodev.cjs').standinMissing('gh');
+  if (refused) return () => ({ status: null, error: new Error(refused), stdout: '', stderr: refused });
+  return (args) => spawnSync('gh', args, { cwd, encoding: 'utf8', shell: process.platform === 'win32', timeout: 120000 });
+}
+
+function parseJson(r) {
+  if (!r || r.error || r.status !== 0) return null;
+  try { return JSON.parse(r.stdout); } catch { return null; }
+}
+
+const BUCKET = { pass: 'pass', fail: 'fail', pending: 'pending', skipping: 'skip', cancel: 'fail' };
+function bucketOf(c) {
+  if (c.bucket && BUCKET[c.bucket]) return BUCKET[c.bucket];
+  const s = String(c.state || c.conclusion || '').toUpperCase();
+  if (['SUCCESS', 'NEUTRAL'].includes(s)) return 'pass';
+  if (['SKIPPED'].includes(s)) return 'skip';
+  if (['FAILURE', 'ERROR', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].includes(s)) return 'fail';
+  return 'pending';
+}
+
+/** Names (check and workflow) whose latest run on the base branch failed. */
+function baseFailing(exec, base) {
+  if (!base) return new Set();
+  const runs = parseJson(exec(['run', 'list', '--branch', base, '--limit', '30', '--json', 'name,workflowName,conclusion']));
+  const latest = new Map();
+  for (const r of Array.isArray(runs) ? runs : []) {
+    const key = r.workflowName || r.name;
+    if (!latest.has(key)) latest.set(key, r);
+  }
+  const out = new Set();
+  for (const [key, r] of latest) if (String(r.conclusion).toLowerCase() === 'failure') { out.add(key); if (r.name) out.add(r.name); }
+  return out;
+}
+
+function logTail(exec, checks) {
+  for (const c of checks) {
+    const m = String(c.link || '').match(/\/actions\/runs\/(\d+)/);
+    if (!m) continue;
+    const r = exec(['run', 'view', m[1], '--log-failed']);
+    if (r && r.status === 0 && r.stdout) return r.stdout.trim().split(/\r?\n/).slice(-40).join('\n');
+  }
+  return '';
+}
+
+/**
+ * The CI oracle for the current branch's pull request.
+ * @param {string} cwd
+ * @param {{exec?: Function, ref?: string, base?: string, head?: string}} opts
+ * @returns {{status: 'passed'|'failed'|'pending'|'unavailable'|'stale', failed: string[], ignored: string[], tail: string, reason?: string}}
+ */
+function ciOracle(cwd, opts = {}) {
+  const exec = opts.exec || defaultExec(cwd);
+  const res = { status: 'unavailable', failed: [], ignored: [], tail: '' };
+  const checksRaw = exec(['pr', 'checks', ...(opts.ref ? [opts.ref] : []), '--json', 'name,state,bucket,link,workflow']);
+  if (!checksRaw || checksRaw.error || checksRaw.status == null) return { ...res, reason: 'gh is not available' };
+  const checks = parseJson(checksRaw);
+  if (!Array.isArray(checks)) return { ...res, reason: (checksRaw.stderr || 'no pull request checks').trim().slice(0, 200) };
+  if (opts.head) {
+    const pr = parseJson(exec(['pr', 'view', ...(opts.ref ? [opts.ref] : []), '--json', 'headRefOid']));
+    if (pr && pr.headRefOid && pr.headRefOid !== opts.head) return { ...res, status: 'stale', reason: `the checks are for ${pr.headRefOid.slice(0, 9)}, HEAD is ${opts.head.slice(0, 9)}: push the branch` };
+  }
+  const onBase = baseFailing(exec, opts.base);
+  const failing = checks.filter((c) => bucketOf(c) === 'fail');
+  const ignored = failing.filter((c) => onBase.has(c.name) || onBase.has(c.workflow));
+  const counted = failing.filter((c) => !ignored.includes(c));
+  res.ignored = ignored.map((c) => c.name);
+  res.failed = counted.map((c) => c.name);
+  if (counted.length) return { ...res, status: 'failed', tail: logTail(exec, counted) };
+  if (checks.some((c) => bucketOf(c) === 'pending')) return { ...res, status: 'pending' };
+  return { ...res, status: 'passed' };
+}
+
+/** Wait for pending checks, up to `timeoutMs`. */
+function waitForCi(cwd, opts = {}) {
+  const deadline = Date.now() + (opts.timeoutMs || 30 * 60 * 1000);
+  for (;;) {
+    const r = ciOracle(cwd, opts);
+    if (r.status !== 'pending' || Date.now() >= deadline) return r;
+    spawnSync(process.execPath, ['-e', `setTimeout(() => {}, ${Math.min(opts.pollMs || 30000, Math.max(0, deadline - Date.now()))})`]);
+  }
+}
+
+/** The project's own gate: its `ci:local` script, else its `test` script, else none. */
+function localGate(cwd) {
+  let scripts = {};
+  try { scripts = JSON.parse(require('fs').readFileSync(require('path').join(cwd, 'package.json'), 'utf8')).scripts || {}; } catch { /* no package.json */ }
+  if (scripts['ci:local']) return { name: 'ci:local', args: ['run', 'ci:local'] };
+  if (scripts.test) return { name: 'test', args: ['test'] };
+  return null;
+}
+
+/**
+ * The local CI oracle: run the project's gate in `cwd` and judge it by its exit code.
+ * With ci:local, the failing gate ids come from .ci-local/report.json.
+ * @param {string} cwd
+ * @param {{exec?: Function, timeoutMs?: number}} opts
+ * @returns {{status: 'passed'|'failed'|'unavailable', failed: string[], ignored: string[], tail: string, reason?: string}}
+ */
+function localOracle(cwd, opts = {}) {
+  const res = { status: 'unavailable', failed: [], ignored: [], tail: '' };
+  const gate = localGate(cwd);
+  if (!gate) return { ...res, reason: 'package.json has neither a ci:local nor a test script' };
+  const exec = opts.exec || ((args) => spawnSync('npm', args, { cwd, encoding: 'utf8', shell: process.platform === 'win32', timeout: opts.timeoutMs || 60 * 60 * 1000, maxBuffer: 256 * 1024 * 1024 }));
+  const r = exec(gate.args);
+  if (!r || r.error || r.status == null) return { ...res, reason: `npm ${gate.args.join(' ')} did not run${r && r.error ? `: ${r.error.message}` : ''}` };
+  const tail = `${r.stdout || ''}${r.stderr || ''}`.trim().split(/\r?\n/).slice(-40).join('\n');
+  if (r.status === 0) return { ...res, status: 'passed', tail };
+  let failed = [gate.name];
+  if (gate.name === 'ci:local') {
+    try {
+      const report = JSON.parse(require('fs').readFileSync(require('path').join(cwd, '.ci-local', 'report.json'), 'utf8'));
+      const ids = (report.gates || []).filter((g) => g.status === 'fail').map((g) => g.id);
+      if (ids.length) failed = ids;
+    } catch { /* the exit code is the verdict; the gate names are a courtesy */ }
+  }
+  return { ...res, status: 'failed', failed, tail };
+}
+
+function breakerTripped(rounds, max = DEFAULT_CI_ROUNDS) {
+  return rounds >= max;
+}
+
+module.exports = { ciOracle, waitForCi, localOracle, localGate, breakerTripped, baseFailing, bucketOf, DEFAULT_CI_ROUNDS };

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

@@ -941,7 +941,7 @@ function cmdScaffold(cwd, type, options, raw) {
     }
     case 'uat': {
       filePath = path.join(phaseDir, `${padded}${UAT_SUFFIX}`);
-      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} -- User Acceptance Testing\n\n## Test Results\n\n| # | Test | Status | Notes |\n|---|------|--------|-------|\n\n## Summary\n\n_Pending UAT_\n`;
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} -- User Acceptance Testing\n\n## Tests\n\n_One \`### N. <name>\` per user-observable truth, with \`expected:\` and \`result: [pending]\` (the walkthrough writes them; \`uat record\` fills the results)_\n\n## Gaps\n\n## Summary\n\n_Pending UAT_\n`;
       break;
     }
     case 'verification': {

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

@@ -48,7 +48,9 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
     phase_branch_template: 'pan/phase-{phase}-{slug}',
     milestone_branch_template: 'pan/{milestone}-{slug}',
     workflow: {
-      research: true,
+      // Research is opt-in (2026-10-25): `--research` on new-project or plan-phase, or
+      // this key set true. A config that already says true keeps it.
+      research: false,
       plan_check: true,
       verifier: true,
       nyquist_validation: false,
@@ -59,6 +61,23 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       // V5: the mutation report on a phase's diff. `report` lists surviving mutants and
       // never refuses; `off` skips it; `gate` is reserved for V5G.
       mutation_gate: 'report',
+      // V5G: the score `gate` mode needs (killed / sampled, 0..1).
+      mutation_floor: 0.6,
+      // R2: `single` runs one reviewer pass; `lenses` runs one per lens (review-vote.cjs
+      // LENSES) and keeps only the findings a quorum of passes reported. Opt-in until
+      // its paired corpus run decides.
+      review_mode: 'single',
+      // R4: a second review on another host's CLI (another model family), read-only.
+      // `off`, or a host: claude | codex | copilot | gemini | opencode.
+      cross_family_review: 'off',
+      // A3: pan-exec-waves runs each executor in its own git worktree (Claude Code).
+      worktree_isolation: false,
+      // Right-sized ceremony (sizing.cjs): `auto` sizes each phase and quick task and gives a
+      // small, well-specified one the lean path; `full` always runs the whole ceremony. The
+      // `quality` profile also means full.
+      ceremony: 'auto',
+      // The most requirements a phase can map and still be sized lean.
+      lean_max_requirements: 5,
       // M2: opt-in per-phase HTML reports at the verify→complete gate.
       phase_reports: { enabled: false, open: false, theme: 'auto', index: true },
     },
@@ -80,6 +99,10 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       // Fraction of the spawn budget held back for re-verification (0..0.5).
       // Surfaced as an indicator always; a hard early stop only under enforce.
       verify_reserve: 0.15,
+      // A6: autodev's dollar caps, per run and per day (UTC), across every run's ledger.
+      // null: none set. An unattended run needs a run cap, here or as --max-usd.
+      max_usd_run: null,
+      max_usd_day: null,
     },
     commit: {
       safety_checks: true,
@@ -156,8 +179,13 @@ function knownConfigKeys() {
  * @param {string} keyPath
  * @returns {boolean}
  */
+// A lowercase `x-` key is the user's own metadata, never a typo (market-ideas M51,
+// after OpenSpec v1.14.2): PAN ignores it at the top level and inside a section.
+const USER_KEY = /^x-/;
+
 function isKnownConfigPath(keyPath) {
   const [head, sub] = String(keyPath).split('.');
+  if (USER_KEY.test(head) || (sub !== undefined && USER_KEY.test(sub))) return true;
   const { top, sections } = knownConfigKeys();
   if (!top.has(head)) return false;
   return sub === undefined || !sections.has(head) || sections.get(head).has(sub);
@@ -174,10 +202,11 @@ function unknownConfigKeys(config) {
   const { top, sections } = knownConfigKeys();
   const unknown = [];
   for (const [k, v] of Object.entries(config)) {
+    if (USER_KEY.test(k)) continue;
     if (!top.has(k)) { unknown.push(k); continue; }
     const known = sections.get(k);
     if (!known || !v || typeof v !== 'object' || Array.isArray(v)) continue;
-    for (const sub of Object.keys(v)) if (!known.has(sub)) unknown.push(`${k}.${sub}`);
+    for (const sub of Object.keys(v)) if (!known.has(sub) && !USER_KEY.test(sub)) unknown.push(`${k}.${sub}`);
   }
   return unknown;
 }

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

@@ -165,6 +165,29 @@ const CATEGORY_DEFAULTS = {
 /** Doc files to scan for staleness (focus sync) */
 const DOC_SYNC_FILES = ['README.md', 'docs/DEVELOPMENT.md', 'docs/CLI-REFERENCE.md', 'docs/USER-GUIDE.md', 'docs/ARCHITECTURE.md'];
 
+/**
+ * Commands folded into another (program L7). The installer writes an alias command for
+ * each old name on every runtime, so `/pan:<old>` keeps working: it runs `to` with
+ * `args` in front of whatever the user passed.
+ */
+const COMMAND_ALIASES = {
+  dashboard: { to: 'hud', args: '' },
+  'milestone-cleanup': { to: 'milestone-done', args: '--cleanup' },
+  'milestone-gaps': { to: 'milestone-audit', args: '--gaps' },
+  optimize: { to: 'learn', args: '--optimize' },
+  'research-phase': { to: 'plan-phase', args: '--research-only' },
+  profile: { to: 'settings', args: '--profile' },
+  'focus-doc-audit': { to: 'focus-docs', args: '' },
+  'focus-sync': { to: 'focus-docs', args: '--sync' },
+  'focus-scan': { to: 'focus-auto', args: '--step scan' },
+  'focus-plan': { to: 'focus-auto', args: '--step plan' },
+  'focus-exec': { to: 'focus-auto', args: '--step exec' },
+  'focus-drift-walking': { to: 'focus-auto', args: '--step drift' },
+};
+
+/** Commands removed with no replacement (program L7). */
+const RETIRED_COMMANDS = ['discord', 'mcp-bridge'];
+
 /** Old→new command name mapping for detecting stale docs */
 const COMMAND_RENAME_MAP = {
   'execute-phase': 'exec-phase',
@@ -178,7 +201,8 @@ const COMMAND_RENAME_MAP = {
   'new-milestone': 'milestone-new',
   'complete-milestone': 'milestone-done',
   'audit-milestone': 'milestone-audit',
-  'plan-milestone-gaps': 'milestone-gaps',
+  'plan-milestone-gaps': 'milestone-audit --gaps',
+  ...Object.fromEntries(Object.entries(COMMAND_ALIASES).map(([old, a]) => [old, a.args ? `${a.to} ${a.args}` : a.to])),
 };
 
 /** Default max cycles for auto-runner */
@@ -818,6 +842,8 @@ module.exports = {
   FOCUS_SOURCES,
   DOC_SYNC_FILES,
   COMMAND_RENAME_MAP,
+  COMMAND_ALIASES,
+  RETIRED_COMMANDS,
   CATEGORY_PRIORITY_RANGE,
   CATEGORY_DEFAULTS,
   DEFAULT_MAX_CYCLES,

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

@@ -132,13 +132,14 @@ const MODEL_PROFILES = {
   'pan-designer':             { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
   'pan-roadmapper':           { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
   'pan-executor':             { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
-  'pan-phase-researcher':     { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
-  'pan-project-researcher':   { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
-  'pan-research-synthesizer': { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  // Right-sized ceremony (2026-10-24): balanced runs the researchers and the plan-checker
+  // on the mid tier, about half the launch model's price; quality keeps them on reasoning.
+  'pan-phase-researcher':     { quality: 'reasoning', balanced: 'mid', budget: 'fast' },
+  'pan-project-researcher':   { quality: 'reasoning', balanced: 'mid', budget: 'fast' },
   'pan-debugger':             { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
   'pan-document_code':        { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   'pan-verifier':             { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
-  'pan-plan-checker':         { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-plan-checker':         { quality: 'reasoning', balanced: 'mid', budget: 'fast' },
   'pan-design-checker':       { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   'pan-integration-checker':  { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   'pan-reviewer':             { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
@@ -193,7 +194,6 @@ const AGENT_BASE_EFFORT = {
   // Research/synthesis/review — moderate depth
   'pan-phase-researcher':     'medium',
   'pan-project-researcher':   'medium',
-  'pan-research-synthesizer': 'medium',
   'pan-knowledge':            'medium',
   'pan-distiller':            'medium',
   'pan-meta-reviewer':        'medium',
@@ -324,7 +324,7 @@ function reportsFailure(result) {
  */
 function output(result, raw, rawValue, exitCode) {
   if (raw && rawValue !== undefined) {
-    process.stdout.write(String(rawValue));
+    writeStdoutSync(String(rawValue));
   } else {
     const json = JSON.stringify(result, null, 2);
     // Large payloads exceed Claude Code's Bash tool buffer (~50KB).
@@ -337,19 +337,31 @@ function output(result, raw, rawValue, exitCode) {
         const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-'));
         const tmpPath = path.join(tmpDir, 'out.json');
         fs.writeFileSync(tmpPath, json, { encoding: 'utf-8', flag: 'wx' });
-        process.stdout.write('@file:' + tmpPath);
+        writeStdoutSync('@file:' + tmpPath);
       } catch {
         // Tmpfile write failed (disk full, permissions) — truncate and write to stdout
         const truncated = json.slice(0, MAX_JSON_SIZE);
-        process.stdout.write(truncated);
+        writeStdoutSync(truncated);
       }
     } else {
-      process.stdout.write(json);
+      writeStdoutSync(json);
     }
   }
   process.exit(exitCode === undefined ? (reportsFailure(result) ? 1 : 0) : exitCode);
 }
 
+/**
+ * Write all of `text` to stdout before returning. output() exits right after it writes,
+ * and on macOS (and Linux) stdout to a pipe is asynchronous: process.exit() dropped
+ * whatever had not drained past the pipe buffer, so a reader got JSON cut at about 8 KB.
+ * Making the stdout handle blocking first turns the write synchronous on a pipe too.
+ */
+function writeStdoutSync(text) {
+  const handle = process.stdout._handle;
+  if (handle && typeof handle.setBlocking === 'function') handle.setBlocking(true);
+  process.stdout.write(String(text));
+}
+
 /**
  * Write error message to stderr and exit with code 1.
  * @param {string} message - Error message
@@ -434,7 +446,7 @@ function loadConfig(cwd) {
     branching_strategy: 'none',
     phase_branch_template: 'pan/phase-{phase}-{slug}',
     milestone_branch_template: 'pan/{milestone}-{slug}',
-    research: true,
+    research: false, // opt-in: a config that says true keeps it
     plan_checker: true,
     verifier: true,
     nyquist_validation: false,

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

@@ -149,7 +149,8 @@ const DEFAULT_RATES = {
 
   // Google Gemini — ai.google.dev/gemini-api/docs/pricing, paid tier, text input,
   // the ≤200K-token prompt tier where the page splits by length, read 2026-09-23.
-  // cache_read is the page's "context caching" price: 0.1× input on every row, not
+  // cache_read is the page's "context caching" price: 0.1× input on every row but
+  // Gemini 4 Argon (0.05×), not
   // the 0.25× this block carried until 2026-09-22 (cache reads 2.5× high, R26). The
   // tokens that CREATE a cache bill at the standard input price (Google Cloud's
   // context-cache overview; the Gemini API pages list only cached-token and storage
@@ -157,7 +158,12 @@ const DEFAULT_RATES = {
   // HOUR, which a per-token table cannot carry: PAN's Gemini totals exclude it.
   // The 3.6/3.7/3.8 Flash prices run "through December 31, 2026" and double from
   // January 1, 2027 (the page states both) — re-read them after that date.
-  'gemini-3.8-flash':       { input: 0.75, output: 3.75, cache_read: 0.075, cache_write: 0.75 },
+  // Gemini 4 Argon (paid tier only; one price at every prompt length; implicit caching
+  // only): these rates run "through November 30, 2026" and double from December 1,
+  // 2026 (input $4.00, output $20.00, caching $0.20; read 2026-10-19) — change the row
+  // on that date.
+  'gemini-4-argon':         { input: 2.00, output: 10.0, cache_read: 0.10,  cache_write: 2.00 },
+  'gemini-3.8-flash':      { input: 0.75, output: 3.75, cache_read: 0.075, cache_write: 0.75 },
   'gemini-3.7-flash':       { input: 0.75, output: 3.75, cache_read: 0.075, cache_write: 0.75 },
   'gemini-3.6-flash':       { input: 0.75, output: 3.75, cache_read: 0.075, cache_write: 0.75 },
   'gemini-3.5-flash':       { input: 1.50, output: 9.00, cache_read: 0.15,  cache_write: 1.50 },
@@ -899,8 +905,12 @@ function cmdCostAppend(cwd, rec, raw) {
 
 function cmdCostClear(cwd, raw) {
   try {
-    fs.unlinkSync(tokensFile(cwd));
-    output({ cleared: true, file: tokensFile(cwd) }, raw);
+    // L6a: the ledger is the only record of what was spent; keep a copy before deleting it.
+    const file = tokensFile(cwd);
+    const backup = `${file}.bak-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}`;
+    fs.copyFileSync(file, backup);
+    fs.unlinkSync(file);
+    output({ cleared: true, file, backup }, raw);
   } catch (e) {
     output({ cleared: false, error: e.message || 'ledger_clear_failed' }, raw);
   }

package/pan-wizard-core/bin/lib/cross-family.cjs

@@ -0,0 +1,164 @@
+'use strict';
+/**
+ * The cross-family reviewer lane (program R4): `pan-tools review cross-family <phase>`.
+ *
+ * A reviewer from the same model family as the author tends to share its blind spots.
+ * This lane runs one more review of the phase on another host's CLI, read-only (the
+ * argv is hosts.cjs `review`), and keeps its pan-verdict block beside the others, so
+ * review-deep can merge it as a fourth source (`--cross-file`).
+ *
+ * Opt-in per project: `workflow.cross_family_review` is `off` by default, or names a
+ * host. `--host` overrides it for one run; `--dry-run` prints the lane, the argv and the
+ * prompt and spawns nothing; `--reps N` runs it N times and reports each verdict, which
+ * is what the lane's evidence run needs.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { output, execGit, safeReadFile, toPosix } = require('./core.cjs');
+const { planningPath } = require('./utils.cjs');
+const { HOSTS } = require('./hosts.cjs');
+const { findVerdictBlocks, validateVerdict } = require('./verdict.cjs');
+
+const MAX_DIFF_CHARS = 120000;
+// Windows caps a command line near 32k characters; a longer prompt goes through a file.
+const MAX_ARG_PROMPT = 24000;
+
+function laneHost(cwd, override) {
+  if (override) return override;
+  const wf = (require('./test-gate.cjs').rawConfig(cwd).workflow) || {};
+  const v = wf.cross_family_review;
+  return typeof v === 'string' && v && v !== 'off' ? v : null;
+}
+
+function buildPrompt(cwd, phase) {
+  const { reviewScope } = require('./verify-scope.cjs');
+  const scope = reviewScope(cwd, phase);
+  if (scope.error) return { error: scope.error, reason: scope.reason };
+  let diff = '';
+  if (scope.base) {
+    const r = execGit(cwd, ['diff', scope.base, '--', ...scope.files.map((f) => f.path)]);
+    if (r.exitCode === 0) diff = r.stdout;
+  } else if (scope.files.length) {
+    const r = execGit(cwd, ['diff', 'HEAD', '--', ...scope.files.map((f) => f.path)]);
+    if (r.exitCode === 0) diff = r.stdout;
+  }
+  const truncated = diff.length > MAX_DIFF_CHARS;
+  if (truncated) diff = diff.slice(0, MAX_DIFF_CHARS);
+  const contract = safeReadFile(path.join(__dirname, '..', '..', 'references', 'verdict-contract.md')) || '';
+  const intent = scope.intent.plans.map((p) => `### ${p.plan}\n${p.objective || ''}${p.review_focus ? `\n\nReview focus:\n${p.review_focus}` : ''}`).join('\n\n');
+  const reqs = scope.intent.requirements.map((r) => `- ${r.id}: ${r.text || '(missing)'}`).join('\n');
+  const prompt = [
+    `You are an independent code reviewer from a different model family than the author. Review phase ${scope.phase} of this project: find correctness, security and maintainability defects in the change below, judged against the plans' intent. Do not edit anything.`,
+    `Reply with one fenced \`pan-verdict\` block, as the contract below defines: \`"contract": "1.0"\`, \`"agent": "cross-family-reviewer"\`, \`"phase": "${scope.phase}"\`, a \`verdict\` and \`outcome\`, and one finding per defect (\`where\` as \`file:line\`). Name what you could not judge in \`declined\`.`,
+    '## Verdict contract', contract.trim(),
+    '## Intent', intent || '(no plans found)', reqs ? `## Requirements\n${reqs}` : '',
+    `## Files in scope\n${scope.files.map((f) => `- ${f.path}`).join('\n') || '(none)'}`,
+    `## Diff${scope.base ? ` (from ${scope.base.slice(0, 12)})` : ''}${truncated ? ' (truncated)' : ''}`, '```diff', diff || '(no diff)', '```',
+  ].filter(Boolean).join('\n\n');
+  return { phase: scope.phase, prompt, truncated };
+}
+
+/**
+ * How to launch a host binary on this platform. Off Windows: by name, no shell. On Windows
+ * a binary that resolves to an .exe (Copilot CLI's installer, say) is launched directly by
+ * its path, so Node quotes each argument and a multi-line prompt arrives whole. Anything
+ * else (an npm .cmd shim, a stand-in) needs cmd.exe, which joins arguments unquoted and
+ * ends the command at a newline: there the prompt goes through a file and each argument
+ * with whitespace or a quote is quoted (2026-10-23: `-p <prompt>` reached cmd.exe as words).
+ */
+function launchPlan(bin, platform = process.platform, env = process.env) {
+  if (platform !== 'win32') return { file: bin, shell: false, promptFile: false };
+  const exts = String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean).map((e) => e.toLowerCase());
+  for (const dir of String(env.PATH || env.Path || '').split(path.delimiter).map((d) => d.trim().replace(/^"(.*)"$/, '$1')).filter(Boolean)) {
+    for (const ext of exts) {
+      const p = path.join(dir, bin + ext);
+      if (!fs.existsSync(p)) continue;
+      if (ext === '.exe' || ext === '.com') return { file: p, shell: false, promptFile: false };
+      return { file: bin, shell: true, promptFile: true };
+    }
+  }
+  return { file: bin, shell: true, promptFile: true };
+}
+
+/**
+ * One argument for cmd.exe's command line: quoted when it holds whitespace, a quote or one of
+ * cmd's operators (& | < > ^), which are literal inside quotes. Pure.
+ */
+function quoteForCmd(arg) {
+  const s = String(arg);
+  return /[\s"&|<>^]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+
+function parseVerdict(text) {
+  const blocks = findVerdictBlocks(text || '');
+  const last = blocks.filter((b) => b.closed).pop();
+  if (!last) return { verdict: null, error: 'no_verdict_block' };
+  try {
+    const r = validateVerdict(JSON.parse(last.body));
+    return r.ok ? { verdict: r.verdict } : { verdict: null, error: r.error };
+  } catch { return { verdict: null, error: 'invalid_json' }; }
+}
+
+/**
+ * Plan or run the lane. Pure apart from reading the project and, without dryRun,
+ * spawning the host and writing `.planning/reviews/<NN>/cross-family-<host>.md`.
+ */
+function crossFamilyReview(cwd, phase, opts = {}) {
+  if (!phase) return { error: 'phase_required', reason: 'Usage: review cross-family <phase> [--host <name>] [--reps N] [--dry-run]' };
+  const host = laneHost(cwd, opts.host);
+  if (!host) return { enabled: false, reason: 'lane_off', hint: 'set workflow.cross_family_review to a host, or pass --host' };
+  const h = HOSTS[host];
+  if (!h || !h.review) return { error: 'unknown_host', reason: `no review lane for host "${host}"`, hosts: Object.keys(HOSTS) };
+  const built = buildPrompt(cwd, phase);
+  if (built.error) return built;
+  const nn = String(built.phase).padStart(2, '0');
+  const dir = planningPath(cwd, 'reviews', nn);
+  let prompt = built.prompt;
+  let promptFile = null;
+  const launch = launchPlan(h.bin);
+  if (h.review.promptVia === 'arg' && (prompt.length > MAX_ARG_PROMPT || launch.promptFile)) {
+    promptFile = path.join(dir, `cross-family-${host}-prompt.md`);
+    prompt = `Read ${toPosix(path.relative(cwd, promptFile))} and follow it exactly. Do not edit anything.`;
+  }
+  const argv = h.review.args(h.review.promptVia === 'arg' ? prompt : '');
+  const base = {
+    enabled: true, lane: `cross-family:${host}`, host, family: h.family, bin: h.bin,
+    argv, prompt_via: h.review.promptVia, truncated_diff: built.truncated,
+  };
+  if (opts.dryRun) return { ...base, prompt: built.prompt, prompt_file: promptFile && toPosix(path.relative(cwd, promptFile)), dry_run: true };
+
+  fs.mkdirSync(dir, { recursive: true });
+  if (promptFile) fs.writeFileSync(promptFile, built.prompt);
+  const reps = Math.max(1, Math.min(10, Number(opts.reps) || 1));
+  const runs = [];
+  const outputs = [];
+  const refused = require('./autodev.cjs').standinMissing(h.bin);
+  if (refused) return { ...base, error: 'standin_missing', reason: refused };
+  for (let i = 0; i < reps; i++) {
+    const r = spawnSync(launch.file, launch.shell ? argv.map(quoteForCmd) : argv, {
+      cwd, encoding: 'utf8', input: h.review.promptVia === 'stdin' ? built.prompt : undefined,
+      shell: launch.shell, timeout: Number(opts.timeoutMs) || 15 * 60 * 1000, maxBuffer: 32 * 1024 * 1024,
+    });
+    if (r.error) return { ...base, error: 'spawn_failed', reason: r.error.message };
+    const v = parseVerdict(r.stdout);
+    outputs.push(r.stdout || '');
+    runs.push({ rep: i + 1, exit: r.status, verdict: v.verdict ? v.verdict.verdict : null, outcome: v.verdict ? v.verdict.outcome : null, findings: v.verdict ? v.verdict.findings.length : 0, error: v.error });
+  }
+  const file = path.join(dir, `cross-family-${host}.md`);
+  // The last parseable run is the one review-deep merges; every rep is kept for the record.
+  const keep = outputs.map((o, i) => [o, runs[i]]).filter(([, r]) => r.outcome).pop();
+  fs.writeFileSync(file, `# Cross-family review: phase ${nn} on ${host} (${h.family})\n\n${(keep ? keep[0] : outputs[outputs.length - 1]).trim()}\n`);
+  const counts = {};
+  for (const r of runs) if (r.verdict) counts[r.verdict] = (counts[r.verdict] || 0) + 1;
+  const majority = Object.entries(counts).sort((a, b) => b[1] - a[1])[0];
+  return { ...base, reps, runs, verdict: majority ? majority[0] : null, file: toPosix(path.relative(cwd, file)) };
+}
+
+function cmdReviewCrossFamily(cwd, phase, opts, raw) {
+  const r = crossFamilyReview(cwd, phase, opts);
+  output(r, raw, r.file || r.reason || r.error);
+}
+
+module.exports = { crossFamilyReview, cmdReviewCrossFamily, buildPrompt, parseVerdict, launchPlan, quoteForCmd };