pan-wizard 3.34.0 → 3.35.0

package/pan-wizard-core/bin/lib/verify-plan-set.cjs

@@ -0,0 +1,230 @@
+'use strict';
+/**
+ * Plan checks in code (program V7).
+ *
+ * The plan-checker agent reads a phase's plans and judges them, but the parts of that
+ * judgement that are arithmetic were left to the model: whether every requirement is
+ * covered, whether two plans in one wave edit the same file, whether a dependency
+ * points at a plan that does not exist, at the same wave or a later one, or round in
+ * a circle. `verify plan-set` checks those in code, before the checker is spent.
+ *
+ * It also binds a passing plan check to the plans it checked. The recorder stores a
+ * hash of the phase's plan files with every plan-checker verdict (`plans_sha`), and
+ * `planCheckStatus` tells exec-phase whether the plans it is about to run are the
+ * plans that passed: `ok`, `stale` (edited since), `failed`, `missing`, `legacy`
+ * (a record from before hashing: a warning, never a refusal) or `disabled`.
+ *
+ * And it reports drift: a plan that records `planned_commit` lists the files it
+ * modifies that changed on the branch since it was planned.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { findPhaseInternal, output, error, execGit, loadConfig, toLf, toPosix } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { roadmapRequirementIds } = require('./roadmap.cjs');
+const { buildPlanIndex, dependencyNames } = require('./phase.cjs');
+const { ROADMAP_FILE, getPlanId } = require('./constants.cjs');
+const { planningPath, filterPlanFiles, filterSummaryFiles } = require('./utils.cjs');
+
+const PLAN_CHECKER = 'pan-plan-checker';
+
+const asList = (v) => (Array.isArray(v) ? v : (v == null || v === '' ? [] : [v])).map((x) => String(x).trim()).filter(Boolean);
+const normFile = (f) => toPosix(String(f).trim()).replace(/^\.\//, '');
+
+/** The phase directory and its plan and summary files, or `{error, reason}`. */
+function phaseFiles(cwd, phase) {
+  const info = findPhaseInternal(cwd, phase);
+  if (!info || !info.found) return { error: 'phase_not_found', reason: `no phase directory for phase ${phase}` };
+  const dir = path.join(cwd, info.directory);
+  let files = [];
+  try { files = fs.readdirSync(dir); } catch (e) { return { error: 'unreadable_phase', reason: `cannot read ${info.directory}: ${e.code || e.message}` }; }
+  return { info, dir, planFiles: filterPlanFiles(files).sort(), summaryFiles: filterSummaryFiles(files) };
+}
+
+/**
+ * A hash of a phase's plan files (names and line-ending-normalised contents), so a
+ * plan check can be matched to exactly the plans it checked.
+ */
+function plansSha(dir, planFiles) {
+  const h = crypto.createHash('sha256');
+  for (const f of [...planFiles].sort()) {
+    let text = '';
+    try { text = fs.readFileSync(path.join(dir, f), 'utf-8'); } catch { /* unreadable reads as empty */ }
+    h.update(f + '\u0000' + toLf(text) + '\u0000');
+  }
+  return h.digest('hex').slice(0, 16);
+}
+
+/** `plansSha` for a phase by number, or null when it has no plans. */
+function plansShaFor(cwd, phase) {
+  const pf = phaseFiles(cwd, phase);
+  if (pf.error || !pf.planFiles.length) return null;
+  return plansSha(pf.dir, pf.planFiles);
+}
+
+/** The phase's plans, each with its requirements, planned_commit and file name. */
+function loadPlans(pf) {
+  const { plans } = buildPlanIndex(pf.dir, pf.planFiles, pf.summaryFiles);
+  const byId = new Map(plans.map((p) => [p.id, p]));
+  for (const file of pf.planFiles) {
+    const p = byId.get(getPlanId(file));
+    if (!p) continue;
+    let fm = {};
+    try { fm = extractFrontmatter(fs.readFileSync(path.join(pf.dir, file), 'utf-8')) || {}; } catch { /* unreadable */ }
+    p.file = file;
+    p.requirements = asList(fm.requirements);
+    p.planned_commit = fm.planned_commit ? String(fm.planned_commit).trim() : null;
+    p.files_modified = p.files_modified.map(normFile).filter(Boolean);
+  }
+  return plans;
+}
+
+/** A dependency entry that names a plan of another phase (`02-01` from phase 03). */
+function isOtherPhase(dep, phaseNumber) {
+  const m = /^(\d+(?:\.\d+)*)-\d+$/.exec(String(dep).trim());
+  if (!m) return false;
+  const strip = (s) => String(s).split('.').map((x) => String(parseInt(x, 10))).join('.');
+  return strip(m[1]) !== strip(phaseNumber);
+}
+
+/**
+ * Check a phase's plan set.
+ * @returns {{phase, ok, errors: Array, warnings: Array, plans: number}|{error, reason}}
+ */
+function checkPlanSet(cwd, phase) {
+  const pf = phaseFiles(cwd, phase);
+  if (pf.error) return pf;
+  if (!pf.planFiles.length) return { error: 'no_plans', reason: `phase ${phase} has no plans` };
+  const phaseNumber = pf.info.phase_number || String(phase);
+  const plans = loadPlans(pf);
+  const errors = [];
+  const warnings = [];
+
+  // 1. Requirement coverage, against the roadmap's requirement ids for this phase.
+  let roadmap = '';
+  try { roadmap = fs.readFileSync(planningPath(cwd, ROADMAP_FILE), 'utf-8'); } catch { /* no roadmap: nothing to cover */ }
+  const required = roadmapRequirementIds(roadmap, phaseNumber);
+  const key = (id) => String(id).trim().toUpperCase();
+  const planned = new Set(plans.flatMap((p) => p.requirements.map(key)));
+  for (const id of required) {
+    if (!planned.has(key(id))) errors.push({ code: 'uncovered_requirement', requirement: id, detail: `requirement ${id} is in the roadmap for phase ${phaseNumber} but no plan lists it` });
+  }
+  if (required.length) {
+    const known = new Set(required.map(key));
+    for (const p of plans) for (const r of p.requirements) {
+      if (!known.has(key(r))) warnings.push({ code: 'unknown_requirement', plan: p.id, requirement: r, detail: `plan ${p.id} lists ${r}, which the roadmap does not give phase ${phaseNumber}` });
+    }
+  }
+
+  // 2. Dependencies: each must name a plan of this phase in an earlier wave.
+  const resolved = new Map(); // plan id → ids of the plans it depends on
+  for (const p of plans) {
+    const deps = [];
+    for (const d of p.depends_on) {
+      if (isOtherPhase(d, phaseNumber)) continue; // a finished phase's plan: not this set's to check
+      const target = plans.find((q) => q.id !== p.id && dependencyNames(d, q.id));
+      if (!target) {
+        if (dependencyNames(d, p.id)) errors.push({ code: 'self_reference', plan: p.id, detail: `plan ${p.id} depends on itself` });
+        else errors.push({ code: 'missing_reference', plan: p.id, depends_on: d, detail: `plan ${p.id} depends on "${d}", which names no plan in this phase` });
+        continue;
+      }
+      deps.push(target.id);
+      if (target.wave >= p.wave) {
+        errors.push({ code: 'future_reference', plan: p.id, depends_on: target.id, detail: `plan ${p.id} (wave ${p.wave}) depends on ${target.id} (wave ${target.wave}); a dependency must be in an earlier wave` });
+      }
+    }
+    resolved.set(p.id, deps);
+    const depWaves = deps.map((id) => plans.find((q) => q.id === id).wave);
+    const expected = depWaves.length ? Math.max(...depWaves) + 1 : 1;
+    if (p.wave > expected) {
+      warnings.push({ code: 'wave_gap', plan: p.id, detail: `plan ${p.id} is in wave ${p.wave} but its dependencies allow wave ${expected}` });
+    }
+  }
+
+  // 3. Cycles.
+  const state = new Map();
+  const reported = new Set();
+  const visit = (id, trail) => {
+    if (state.get(id) === 'done') return;
+    if (state.get(id) === 'active') {
+      const cycle = [...trail.slice(trail.indexOf(id)), id];
+      const sig = [...new Set(cycle)].sort().join(',');
+      if (!reported.has(sig)) { reported.add(sig); errors.push({ code: 'cycle', plans: cycle, detail: `dependency cycle: ${cycle.join(' → ')}` }); }
+      return;
+    }
+    state.set(id, 'active');
+    for (const d of resolved.get(id) || []) visit(d, [...trail, id]);
+    state.set(id, 'done');
+  };
+  for (const p of plans) visit(p.id, []);
+
+  // 4. Same-wave file overlap: two plans that run in parallel must not edit one file.
+  const dependsOn = (a, b, seen = new Set()) => {
+    if (seen.has(a)) return false;
+    seen.add(a);
+    return (resolved.get(a) || []).some((d) => d === b || dependsOn(d, b, seen));
+  };
+  for (let i = 0; i < plans.length; i++) {
+    for (let j = i + 1; j < plans.length; j++) {
+      const a = plans[i];
+      const b = plans[j];
+      if (a.wave !== b.wave) continue;
+      const shared = a.files_modified.filter((f) => b.files_modified.includes(f));
+      if (!shared.length || dependsOn(a.id, b.id) || dependsOn(b.id, a.id)) continue;
+      errors.push({ code: 'same_wave_overlap', plans: [a.id, b.id], files: shared, detail: `plans ${a.id} and ${b.id} both modify ${shared.join(', ')} in wave ${a.wave} with no dependency between them` });
+    }
+  }
+
+  return { phase: phaseNumber, ok: errors.length === 0, errors, warnings, plans: plans.length, plans_sha: plansSha(pf.dir, pf.planFiles) };
+}
+
+/**
+ * Whether the plans exec-phase is about to run are the plans that passed a plan check.
+ * @returns {{status: 'ok'|'stale'|'failed'|'missing'|'legacy'|'disabled', reason?: string, plans_sha?: string, checked_sha?: string, attempt?: number}}
+ */
+function planCheckStatus(cwd, phase) {
+  const config = loadConfig(cwd);
+  if (config.plan_checker === false) return { status: 'disabled', reason: 'workflow.plan_check is off in config.json' };
+  const F = require('./findings.cjs');
+  const V = require('./verdict.cjs');
+  const { verdicts } = F.foldFindings(F.readLedger(cwd).rows);
+  const mine = verdicts.filter((v) => v.agent === PLAN_CHECKER && V.comparablePhase(v.phase) === V.comparablePhase(phase));
+  const last = mine[mine.length - 1];
+  const current = plansShaFor(cwd, phase);
+  if (!last) return { status: 'missing', reason: 'no plan check is recorded for this phase', plans_sha: current };
+  if (last.outcome !== 'pass') return { status: 'failed', reason: `the last plan check (attempt ${last.attempt}) found issues`, attempt: last.attempt, plans_sha: current };
+  if (!last.plans_sha) return { status: 'legacy', reason: 'the plan check was recorded before plans were hashed, so it cannot show the plans are unchanged', attempt: last.attempt, plans_sha: current };
+  if (last.plans_sha !== current) return { status: 'stale', reason: 'the plans changed after they passed the plan check', attempt: last.attempt, checked_sha: last.plans_sha, plans_sha: current };
+  return { status: 'ok', attempt: last.attempt, plans_sha: current };
+}
+
+/**
+ * Plans not yet executed whose modified files changed since they were planned.
+ * @returns {Array<{plan, planned_commit, files?: string[], error?: string}>}
+ */
+function planDrift(cwd, phase) {
+  const pf = phaseFiles(cwd, phase);
+  if (pf.error || !pf.planFiles.length) return [];
+  const out = [];
+  for (const p of loadPlans(pf)) {
+    if (p.has_summary || !p.planned_commit || !p.files_modified.length) continue;
+    if (!/^[0-9a-f]{4,40}$/i.test(p.planned_commit)) { out.push({ plan: p.id, planned_commit: p.planned_commit, error: 'not a commit sha' }); continue; }
+    const r = execGit(cwd, ['diff', '--name-only', p.planned_commit, 'HEAD', '--']);
+    if (r.exitCode !== 0) { out.push({ plan: p.id, planned_commit: p.planned_commit, error: 'unknown commit' }); continue; }
+    const changed = new Set(r.stdout.split(/\r?\n/).map(normFile).filter(Boolean));
+    const files = p.files_modified.filter((f) => changed.has(f));
+    if (files.length) out.push({ plan: p.id, planned_commit: p.planned_commit, files });
+  }
+  return out;
+}
+
+function cmdVerifyPlanSet(cwd, phase, raw) {
+  if (!phase) error('Usage: verify plan-set <phase>');
+  const r = checkPlanSet(cwd, phase);
+  if (r.error) { output(r, raw); return; }
+  const result = { ...r, plan_check: planCheckStatus(cwd, phase), drift: planDrift(cwd, phase) };
+  output(result, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
+}
+
+module.exports = { checkPlanSet, plansSha, plansShaFor, planCheckStatus, planDrift, cmdVerifyPlanSet, PLAN_CHECKER };

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

@@ -68,27 +68,28 @@ function exclusionReason(file, planningPrefix) {
 
 /**
  * Files the phase's plan commits touched, paths relative to `cwd` (git's --relative).
- * @returns {{git: boolean, commits: number, files: Set<string>}}
+ * @returns {{git: boolean, commits: number, files: Set<string>, hashes: string[]}} hashes newest first
  */
 function committedFiles(cwd, phaseNumber) {
   const r = execGit(cwd, ['-c', 'core.quotepath=off', 'log', '--no-merges', '-n', String(COMMIT_SCAN_LIMIT), '--relative', '--name-only', '--format=@@%H%x09%s']);
-  if (r.exitCode !== 0) return { git: false, commits: 0, files: new Set() };
+  if (r.exitCode !== 0) return { git: false, commits: 0, files: new Set(), hashes: [] };
   // `{type}({phase}-{plan}):` with the phase's zero padding optional ("feat(03-01):", "fix(3-02)!:").
   const unpadded = String(phaseNumber).replace(/^0+(?=\d)/, '');
   const subjectRe = new RegExp(`^[a-z]+\\(0*${escapeRegex(unpadded)}-[0-9]+\\)!?:`);
   const files = new Set();
+  const hashes = [];
   let commits = 0;
   let inPhase = false;
   for (const line of r.stdout.split('\n')) {
     if (line.startsWith('@@')) {
       const subject = line.slice(2).split('\t').slice(1).join('\t');
       inPhase = subjectRe.test(subject);
-      if (inPhase) commits++;
+      if (inPhase) { commits++; hashes.push(line.slice(2).split('\t')[0]); }
       continue;
     }
     if (inPhase && line.trim()) files.add(normalisePath(line));
   }
-  return { git: true, commits, files };
+  return { git: true, commits, files, hashes };
 }
 
 /**
@@ -223,4 +224,4 @@ function cmdVerifyStale(cwd, phase, raw) {
   output(r, raw, r.error ? undefined : r.state);
 }
 
-module.exports = { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale, coveredFiles, LOCKFILES };
+module.exports = { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale, coveredFiles, committedFiles, LOCKFILES, TEST_PATH_RE, TEST_FILE_RE };

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

@@ -210,10 +210,38 @@ function createWorktree(cwd, phaseNum, scenario, opts) {
   };
 }
 
+/** Registered worktrees as {path, branch}; branch is null on a detached HEAD. */
+function listWorktrees(cwd) {
+  const r = execGit(cwd, ['worktree', 'list', '--porcelain']);
+  if (r.exitCode !== 0) return [];
+  const list = [];
+  for (const line of r.stdout.split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) list.push({ path: line.slice('worktree '.length), branch: null });
+    else if (line.startsWith('branch ') && list.length) list[list.length - 1].branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+  }
+  return list;
+}
+
+function samePath(a, b) {
+  const norm = (p) => {
+    let r = path.resolve(p);
+    try { r = fs.realpathSync.native(r); } catch { /* gone: compare the resolved form */ }
+    r = toPosix(r);
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+  };
+  return norm(a) === norm(b);
+}
+
 /**
  * Remove a worktree + its branch. Best-effort: errors are surfaced but
  * don't block subsequent cleanups.
  *
+ * Only what-if's own objects are touched: the branch must carry BRANCH_PREFIX and the
+ * worktree, when git still lists it, must be checked out on that branch (or, with no
+ * branch given, on some BRANCH_PREFIX branch). Anything else is refused before a single
+ * git write, because `branch -D` and `worktree remove --force` destroy unmerged commits
+ * and uncommitted files.
+ *
  * @param {string} cwd - Main project root (for the cleanup git call)
  * @param {string} worktreePath - Path returned by createWorktree
  * @param {string} branch - Branch name returned by createWorktree
@@ -224,15 +252,29 @@ function cleanupWorktree(cwd, worktreePath, branch, opts) {
   if (!isGitRepo(cwd)) {
     return { error: 'Not a git repo' };
   }
+  if (branch && !branch.startsWith(BRANCH_PREFIX)) {
+    return { error: `Refusing to delete branch '${branch}': what-if only cleans up branches it created (${BRANCH_PREFIX}*)` };
+  }
+  const entry = listWorktrees(cwd).find(w => samePath(w.path, worktreePath));
+  if (entry) {
+    const owned = entry.branch && entry.branch.startsWith(BRANCH_PREFIX) && (!branch || entry.branch === branch);
+    if (!owned) {
+      return { error: `Refusing to remove worktree ${toPosix(worktreePath)}: it is on '${entry.branch || 'a detached HEAD'}', not ${branch || BRANCH_PREFIX + '*'}` };
+    }
+  }
   const warnings = [];
   const force = opts?.force === true;
 
-  const rmArgs = ['worktree', 'remove'];
-  if (force) rmArgs.push('--force');
-  rmArgs.push(worktreePath);
-  const removeResult = execGit(cwd, rmArgs);
-  if (removeResult.exitCode !== 0) {
-    warnings.push(`worktree remove: ${removeResult.stderr}`);
+  if (entry) {
+    const rmArgs = ['worktree', 'remove'];
+    if (force) rmArgs.push('--force');
+    rmArgs.push(worktreePath);
+    const removeResult = execGit(cwd, rmArgs);
+    if (removeResult.exitCode !== 0) {
+      warnings.push(`worktree remove: ${removeResult.stderr}`);
+    }
+  } else {
+    warnings.push(`worktree remove: ${toPosix(worktreePath)} is not a registered worktree (already removed?)`);
   }
 
   // Branch cleanup — only if branch still exists.

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

@@ -31,7 +31,7 @@
  *   findings record|list|dispose|debt  Judges' verdicts and their findings ledger (evidence loop)
  *   phase-plan-index <phase>           Index plans with waves and status
  *   websearch <query>                  Search web via Brave API (if configured)
- *     [--limit N] [--freshness day|week|month]
+ *     [--limit N] [--freshness day|week|month|year]
  *
  * Phase Listing:
  *   phases list [--type plans|summaries]  List phases with optional type filter
@@ -237,6 +237,9 @@ const costRebuild = require('./lib/cost-rebuild.cjs');
 const preview = require('./lib/preview.cjs');
 const reviewDeep = require('./lib/review-deep.cjs');
 const findings = require('./lib/findings.cjs');
+const verifyPlanSet = require('./lib/verify-plan-set.cjs');
+const verifyIntegrity = require('./lib/verify-integrity.cjs');
+const phaseGate = require('./lib/phase-gate.cjs');
 const knowledge = require('./lib/knowledge.cjs');
 const skillAlign = require('./lib/skill-align.cjs');
 const hygiene = require('./lib/hygiene.cjs');
@@ -649,8 +652,12 @@ async function main() {
         verify.cmdVerifyScope(cwd, args[2], raw);
       } else if (subcommand === 'stale') {
         verify.cmdVerifyStale(cwd, args[2], raw);
+      } else if (subcommand === 'plan-set') {
+        verifyPlanSet.cmdVerifyPlanSet(cwd, args[2], raw);
+      } else if (subcommand === 'test-integrity') {
+        verifyIntegrity.cmdVerifyTestIntegrity(cwd, args[2], raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope, stale');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope, stale, plan-set, test-integrity');
       }
       break;
     }
@@ -766,9 +773,11 @@ async function main() {
       } else if (subcommand === 'complete') {
         if (!args[2]) error('phase complete requires a phase number');
         const noCommit = args.includes('--no-commit');
-        phase.cmdPhaseComplete(cwd, args[2], raw, { noCommit });
+        phase.cmdPhaseComplete(cwd, args[2], raw, { noCommit, force: args.includes('--force'), reason: getArgValue(args, '--reason') });
+      } else if (subcommand === 'gate') {
+        phaseGate.cmdPhaseGate(cwd, args[2], raw, { mode: getArgValue(args, '--mode') || undefined });
       } else {
-        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete');
+        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete, gate');
       }
       break;
     }

package/pan-wizard-core/mcp/merge-gate.cjs

@@ -52,17 +52,28 @@ function writeJson(p, obj) { fs.mkdirSync(path.dirname(p), { recursive: true });
  * Stage a merge request. Mints a fresh per-request approval token (nonce), records the
  * exact branch + the (caller-attested) CI/verify flags, marks it awaiting_approval, and
  * returns the record. Does NOT merge. The operator sets PAN_MERGE_APPROVAL to
- * `record.approval_token` after reviewing. (ci_green/verify_pass are agent-attested
- * advisory context for the human's decision; the token is the sole unfakeable anchor.)
+ * `record.approval_token` after reviewing. ci_green is agent-attested advisory context.
+ * verify_pass is too, unless the request names a `phase`: then it is the phase gate's
+ * verdict (program V1), computed here, and the caller's flag is ignored. The token is
+ * the sole unfakeable anchor either way.
  */
 function requestMerge(cwd, opts = {}) {
   const branch = validateBranch(opts.branch);
+  let verifyPass = !!opts.verify_pass;
+  let gate = null;
+  if (opts.phase != null && String(opts.phase).trim() !== '') {
+    const g = require('../bin/lib/phase-gate.cjs').phaseGate(cwd, String(opts.phase).trim());
+    gate = g.error ? { phase: String(opts.phase), error: g.error } : { phase: g.phase, ok: g.ok, reasons: g.reasons.map((r) => r.code) };
+    verifyPass = !g.error && g.ok;
+  }
   const record = {
     id: slugify(branch),
     branch,
     approval_token: crypto.randomBytes(9).toString('hex'),
     ci_green: !!opts.ci_green,
-    verify_pass: !!opts.verify_pass,
+    verify_pass: verifyPass,
+    verify_source: gate ? 'phase_gate' : 'caller',
+    ...(gate ? { gate } : {}),
     status: 'awaiting_approval',
     requested_at: opts.now || null,
   };

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

@@ -126,14 +126,14 @@ const NATIVE_TOOLS = [
   {
     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.',
+    description: 'Stage a squash-merge request for a branch and mark it awaiting human approval. Records intent only — does NOT merge. Name the phase the branch delivers: verify_pass is then the phase gate\'s verdict, not the caller\'s flag.',
     readOnly: false, destructive: false,
     inputSchema: {
       type: 'object', additionalProperties: false, required: ['branch'],
-      properties: { branch: { type: 'string' }, ci_green: { type: 'boolean' }, verify_pass: { type: 'boolean' } },
+      properties: { branch: { type: 'string' }, ci_green: { type: 'boolean' }, verify_pass: { type: 'boolean' }, phase: { type: 'string' } },
     },
     handler: ({ cwd, input }) => ({
-      json: mergeGate.requestMerge(cwd, { branch: input.branch, ci_green: input.ci_green, verify_pass: input.verify_pass }),
+      json: mergeGate.requestMerge(cwd, { branch: input.branch, ci_green: input.ci_green, verify_pass: input.verify_pass, phase: input.phase }),
     }),
   },
   {

package/pan-wizard-core/opencode/pan-wizard.js

@@ -11,8 +11,9 @@
 // hooks/pan-state-reinject.js after compaction.
 //
 // Installed by the PAN installer as <opencode config dir>/plugins/pan-wizard.js,
-// beside the `{"type":"commonjs"}` package.json PAN writes there, so this file is
-// CommonJS and exports the plugin module shape `{ id, server }`.
+// below the `{"type":"commonjs"}` package.json PAN writes in the config dir, so this file is
+// CommonJS and exports one object both loaders accept: `{ id, server, setup }`
+// (OpenCode 1 calls server(), OpenCode 2 calls setup()).
 //
 // Inert unless the project is a PAN project with work in flight (a state.md naming
 // a current phase and a roadmap.md with an unticked phase). Never writes anything.
@@ -96,16 +97,43 @@ function compactionContext(directory) {
   return block.length > BLOCK_MAX ? block.slice(0, BLOCK_MAX - 1) + '…' : block;
 }
 
+function directoryOf(ctx) {
+  return (ctx && (ctx.directory || ctx.worktree)) || process.cwd();
+}
+
+/** Push PAN's block onto the first array target; fail-open, inert outside work in flight. */
+function pushBlock(directory, target) {
+  try {
+    if (!Array.isArray(target)) return;
+    const block = compactionContext(directory);
+    if (block) target.push(block);
+  } catch { /* fail open: a compaction without PAN's block beats a broken one */ }
+}
+
+// OpenCode 1: the loader calls server() and reads its hook map.
 async function server(ctx) {
-  const directory = (ctx && (ctx.directory || ctx.worktree)) || process.cwd();
+  const directory = directoryOf(ctx);
   return {
     'experimental.session.compacting': async (input, output) => {
-      try {
-        const block = compactionContext(directory);
-        if (block && output && Array.isArray(output.context)) output.context.push(block);
-      } catch { /* fail open: a compaction without PAN's block beats a broken one */ }
+      pushBlock(directory, output && output.context);
     },
   };
 }
 
-module.exports = { id: 'pan-wizard', server };
+// OpenCode 2: the loader requires `setup` (or `effect`) and hooks register through
+// `ctx.session.hook(name, fn)` (opencode.ai/v2/docs/build/plugins, migrate-v1). The
+// compaction event's prompt parts are `system` (read from the 2.0 binary); `context`
+// is the documented v1 name and the fallback.
+function setup(ctx) {
+  try {
+    const directory = directoryOf(ctx);
+    const session = ctx && ctx.session;
+    if (!session || typeof session.hook !== 'function') return;
+    session.hook('compaction', async (event) => {
+      if (!event) return;
+      pushBlock(directory, Array.isArray(event.system) ? event.system : event.context);
+    });
+  } catch { /* fail open: a plugin that cannot register leaves the session as it was */ }
+}
+
+module.exports = { id: 'pan-wizard', server, setup };

package/pan-wizard-core/references/model-profiles.md

@@ -34,7 +34,7 @@ PAN never selects your host model — it recommends a *class*. Because the `reas
 
 The IDs below are *examples* of what you can configure in each class — not an exhaustive or only-valid list. A newer release in the same class behaves the same way here.
 
-At install time PAN also runs a **best-effort, advisory** capability check on the model ID you have configured (`detectModelCapabilities` in `bin/install-lib.cjs`). It recognizes the current Claude generations by name, and its forward threshold per family is the last reduced-capability release it records rather than the newest release it lists: any Claude ID newer than that boundary — a new major, or a later point release inside a major it already lists — inherits that family's modern profile instead of reporting no capabilities at all. "That family's profile" is the point: a newer Haiku inherits Haiku's, which is not a 1M-context/thinking profile. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. It is a name-matching heuristic, not a live probe of the model, so it can still be imprecise about something released after this table — read it as a hint, not a contract. Either way it decides one thing only: whether the installer prints a capability *warning*. No routing, mode-selection, or feature gate in PAN reads it, so a wrong guess costs you a misleading install-time line and nothing else.
+At install time PAN also runs a **best-effort, advisory** capability check on the model ID you have configured (`detectModelCapabilities` in `bin/install-lib.cjs`). It recognizes the current Claude generations by name, and its forward threshold per family is the last reduced-capability release it records rather than the newest release it lists: any Claude ID newer than that boundary — a new major, or a later point release inside a major it already lists — inherits that family's modern profile instead of reporting no capabilities at all. "That family's profile" is the point: a newer Haiku inherits the newest Haiku profile the table records (1M context and thinking, at the fast tier), not Opus's. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. It is a name-matching heuristic, not a live probe of the model, so it can still be imprecise about something released after this table — read it as a hint, not a contract. Either way it decides one thing only: whether the installer prints a capability *warning*. No routing, mode-selection, or feature gate in PAN reads it, so a wrong guess costs you a misleading install-time line and nothing else.
 
 | Class | Example model IDs | Role in PAN | Context | Relative cost | Notes |
 |-------|-------------------|-------------|---------|---------------|-------|

package/pan-wizard-core/references/planning-config.md

@@ -42,7 +42,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: update state" --f
 
 # Load config via state load (returns JSON):
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
-# commit_docs is available in the JSON output
+# commit_docs is at .config.commit_docs in the JSON output
 
 # Or use init commands which include commit_docs:
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "1")
@@ -147,7 +147,7 @@ INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "1")
 Or use `state load` for the config values:
 ```bash
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
-# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
+# Parse .config.branching_strategy, .config.phase_branch_template, .config.milestone_branch_template from JSON
 ```
 
 **Branch creation:**
@@ -168,7 +168,7 @@ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
 fi
 ```
 
-**Merge options at milestone-done:**
+**Merge options after milestone-done (it does not merge — run one yourself):**
 
 | Option | Git command | Result |
 |--------|-------------|--------|

package/pan-wizard-core/references/verdict-contract.md

@@ -26,6 +26,7 @@ A judging agent ends its report with one fenced `pan-verdict` block. The block i
 | `verdict` | yes | your own verdict word (table below) |
 | `outcome` | yes | `pass`, `fail` or `needs_human` |
 | `findings` | yes (may be empty) | a list of `{class, severity, where, summary}` |
+| `resolutions` | on a re-check | a list of `{id, status, evidence}` answering each earlier open finding you were given in `<open_findings>`: `status` is `resolved` (with `evidence`: what you checked and saw), `still_present` or `cannot_tell`. A finding you leave out stays open, and `resolved` without evidence is recorded as `cannot_tell` |
 | `not_checked` | when a check could not run | a list of `{check, reason}`: a check you were asked to make and could not run, and why (no test script, no browser, a file you could not read). Never fold it into `pass`: a verdict with entries here says what it did not see |
 
 | Agent | `verdict` → `outcome` |
@@ -36,6 +37,10 @@ A judging agent ends its report with one fenced `pan-verdict` block. The block i
 
 The verifier does not emit this block. Its verification.md frontmatter (`status`, `gaps`, `human_verification`, `unrequested`, `test_gate`, `not_checked`) is its machine contract, and the recorder reads that directly. `test_gate` is `passed`, `failed` or `skipped`. A skipped gate is recorded as a `tests` entry in `not_checked` even when the list leaves it out, and a verification that does not record `test_gate` at all is recorded with a `test_gate_unrecorded` warning.
 
+**Findings close on evidence, never on silence.** An earlier finding closes only when the judge answers it `resolved` with evidence (a `resolutions` entry, or a truth in the verifier's `re_verification.gaps_closed`), or, for a `code-fact:` finding, when that fact passes. A finding the new report neither repeats nor answers stays open and is listed as `unaddressed`. A reworded report of an earlier finding (same class family, where `missing` and `partial` count as one; same file; same truth or a similar summary) keeps the earlier id.
+
+**Code facts only lower a verdict (two-key verdict).** A fact the engine measures can turn a judge's `pass` or `needs_human` into a fail, never the reverse. `test_gate: failed` under `status: passed` records as `gaps_found`: the record keeps the judge's own word as `agent_verdict`, names the fact in `lowered_by`, and adds a high finding at `code-fact:test_gate` for the gap round to close. `findings record --raw` prints the lowered word, so the workflow routes to gap closure.
+
 ## `class`: what kind of finding
 
 | Class | Use when |
@@ -67,7 +72,7 @@ The verifier does not emit this block. Its verification.md frontmatter (`status`
 - `where`: `NN-MM-plan.md` or `NN-MM-plan.md#task-N`.
 
 **pan-reviewer.**
-- Classes by category: Convention → `quality`, Security → `risk`, Code Quality → `defect`, work no plan asked for → `unrequested`.
+- Classes by category: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Design smell → `quality`, work no plan asked for → `unrequested`.
 - Severity: ERROR → `high`, WARNING → `medium`, INFO → `info`.
 - `where`: `path:line`.
 

package/pan-wizard-core/templates/config.json

@@ -8,6 +8,7 @@
     "auto_advance": false,
     "nyquist_validation": false,
     "phase_record_compact": false,
+    "phase_gate": "warn",
     "phase_reports": { "enabled": false, "open": false, "theme": "auto", "index": true }
   },
   "planning": {
@@ -15,12 +16,7 @@
     "search_gitignored": false
   },
   "parallelization": {
-    "enabled": true,
-    "plan_level": true,
-    "task_level": false,
-    "skip_checkpoints": true,
-    "max_concurrent_agents": 3,
-    "min_plans_for_parallel": 2
+    "enabled": true
   },
   "gates": {
     "confirm_project": true,

package/pan-wizard-core/templates/debug-subagent-prompt.md

@@ -57,13 +57,14 @@ Create: .planning/debug/{slug}.md
 Task(
   prompt=filled_template,
   subagent_type="pan-debugger",
+  model="{debugger_model}",
   description="Debug {slug}"
 )
 ```
 
 **From diagnose-issues (UAT):**
 ```python
-Task(prompt=template, subagent_type="pan-debugger", description="Debug UAT-001")
+Task(prompt=template, subagent_type="pan-debugger", model="{debugger_model}", description="Debug UAT-001")
 ```
 
 ---

package/pan-wizard-core/templates/phase-prompt.md

@@ -22,6 +22,7 @@ files_modified: []
 autonomous: true
 requirements: []
 user_setup: []
+planned_commit: <sha>
 
 # Goal-backward verification (derived during planning, verified after execution); the Frontmatter Fields table below explains each field
 must_haves:
@@ -144,6 +145,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-summary.md`
 | `files_modified` | Yes | Files this plan touches. |
 | `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
 | `requirements` | Yes | **MUST** list requirement IDs from ROADMAP. Every roadmap requirement MUST appear in at least one plan. |
+| `planned_commit` | Yes | `git rev-parse HEAD` when the plan is written. exec-phase lists the `files_modified` that changed on the branch since then, so an executor knows its plan's picture of the code may be out of date. |
 | `user_setup` | No | Array of human-required setup items (external services) |
 | `must_haves` | Yes | Goal-backward verification criteria (see below) |
 

package/pan-wizard-core/templates/planner-subagent-prompt.md

@@ -71,6 +71,7 @@ Before returning PLANNING COMPLETE:
 Task(
   prompt=filled_template,
   subagent_type="pan-planner",
+  model="{planner_model}",
   description="Plan Phase {phase}"
 )
 ```
@@ -80,6 +81,7 @@ Task(
 Task(
   prompt=filled_template,  # with mode: gap_closure
   subagent_type="pan-planner",
+  model="{planner_model}",
   description="Plan gaps for Phase {phase}"
 )
 ```