pan-wizard 3.34.0 → 3.35.0

package/hooks/dist/pan-statusline.js

@@ -13,7 +13,7 @@ const os = require('os');
  *
  * @param {Object} data - Parsed stdin JSON from Claude Code.
  * @param {Object} [deps] - Optional dep injection for testing.
- *   {fs, path, homeDir, tmpDir} — defaults to real modules + OS paths.
+ *   {fs, path, homeDir, tmpDir, configDir} — defaults to real modules + OS paths (configDir: CLAUDE_CONFIG_DIR, ignored when homeDir is given).
  * @returns {string} The statusline content.
  */
 function buildStatuslineOutput(data, deps) {
@@ -155,7 +155,10 @@ function buildStatuslineOutput(data, deps) {
 
   // Current task from todos
   let task = '';
-  const todosDir = pathMod.join(homeDir, '.claude', 'todos');
+  // Claude Code keeps its todos in CLAUDE_CONFIG_DIR when that is set (a given
+  // homeDir is a test seam and ignores it).
+  const configDir = d.configDir !== undefined ? d.configDir : (d.homeDir ? '' : (process.env.CLAUDE_CONFIG_DIR || ''));
+  const todosDir = configDir ? pathMod.join(configDir, 'todos') : pathMod.join(homeDir, '.claude', 'todos');
   let todosExists = false;
   try { todosExists = fsMod.statSync(todosDir).isDirectory(); } catch { /* missing */ }
   if (session && todosExists) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.34.0",
+  "version": "3.35.0",
   "description": "Command a bot army for your codebase: a reasoning-tier Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"

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

@@ -556,6 +556,21 @@ function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
   output(fullResult, raw);
 }
 
+/**
+ * Map a --freshness value to Brave's `freshness` parameter, which accepts only
+ * pd/pw/pm/py or a YYYY-MM-DDtoYYYY-MM-DD range. Returns null for anything else.
+ * @param {string} value - day|week|month|year, or a value Brave accepts as is
+ * @returns {string|null}
+ */
+function braveFreshness(value) {
+  const v = String(value || '').trim().toLowerCase();
+  const named = { day: 'pd', week: 'pw', month: 'pm', year: 'py' };
+  if (named[v]) return named[v];
+  if (/^p[dwmy]$/.test(v)) return v;
+  if (/^\d{4}-\d{2}-\d{2}to\d{4}-\d{2}-\d{2}$/.test(v)) return v;
+  return null;
+}
+
 /**
  * Search the web using Brave Search API and return structured results.
  *
@@ -588,6 +603,12 @@ async function cmdWebsearch(query, options, raw) {
     return;
   }
 
+  const freshness = options.freshness ? braveFreshness(options.freshness) : null;
+  if (options.freshness && !freshness) {
+    output({ available: false, error: `Invalid --freshness "${options.freshness}": use day, week, month, year, pd, pw, pm, py or YYYY-MM-DDtoYYYY-MM-DD` }, raw, '');
+    return;
+  }
+
   const params = new URLSearchParams({
     q: query,
     count: String(options.limit || 10),
@@ -596,8 +617,8 @@ async function cmdWebsearch(query, options, raw) {
     text_decorations: 'false'
   });
 
-  if (options.freshness) {
-    params.set('freshness', options.freshness);
+  if (freshness) {
+    params.set('freshness', freshness);
   }
 
   try {
@@ -1161,6 +1182,7 @@ module.exports = {
   cmdSummaryExtract,
   summaryOneLiner,
   cmdWebsearch,
+  braveFreshness,
   cmdProgressRender,
   cmdTodoComplete,
   cmdScaffold,

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

@@ -53,10 +53,15 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       verifier: true,
       nyquist_validation: false,
       phase_record_compact: false,
+      // V1: the phase gate. `warn` reports refusals and completes; `enforce` refuses.
+      phase_gate: 'warn',
       // M2: opt-in per-phase HTML reports at the verify→complete gate.
       phase_reports: { enabled: false, open: false, theme: 'auto', index: true },
     },
     parallelization: true,
+    // A7: the pre-tool guard. `report` logs to <planning>/guard.jsonl; `enforce` also
+    // denies a write that puts a credential in a file; `off` disables it.
+    hooks: { guard: 'report' },
     brave_search: hasBraveSearch,
     budget: {
       default_points: 50,

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

@@ -16,11 +16,14 @@
  *     again (a regression);
  *   - with no disposition, a finding is `open`.
  *
- * Two rules are applied when a verdict is recorded:
- *   - AUTO-FIX: the same agent's earlier open findings on the phase that the new
- *     verdict does not report become `fixed`. That is how a gap-closure round
- *     closes its gaps. `human` and `unrequested` are exempt, because a re-run does
- *     not re-check them.
+ * Rules applied when a verdict is recorded:
+ *   - EVIDENCE CLOSES, SILENCE DOES NOT (V6): an earlier open finding closes only when
+ *     the judge answers it `resolved` with evidence (a `resolutions` entry, or the
+ *     verifier's `re_verification.gaps_closed`), or, for a `code-fact:<fact>` finding,
+ *     when that fact passes. One the new verdict neither reports nor answers stays
+ *     open and is listed as `unaddressed`. `still_present` counts as a re-report.
+ *   - IDENTITY: a reworded report of an earlier finding (same class family, same
+ *     file, same truth or a similar summary) keeps that finding's id.
  *   - IDEMPOTENCY: recording the same artifact twice is a no-op that returns the
  *     first verdict (record_sig). That is why exec-phase and verify-phase may both
  *     record one verification.md.
@@ -122,6 +125,69 @@ function samePhase(a, b) {
   return V.comparablePhase(a) === V.comparablePhase(b);
 }
 
+// ─── Finding identity across reports (V6) ───────────────────────────────────
+
+/** The file a `where` names, without a line or column suffix. */
+function fileOf(where) {
+  return where ? String(where).replace(/\\/g, '/').replace(/(:\d+){1,2}$/, '').replace(/#L?\d+.*$/, '') : '';
+}
+
+function tokens(s) {
+  return new Set(String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').split(' ').filter((w) => w.length > 2));
+}
+
+/** Token overlap (Jaccard) of two summaries at or above one half. */
+function similar(a, b) {
+  const A = tokens(a);
+  const B = tokens(b);
+  if (!A.size || !B.size) return false;
+  let both = 0;
+  for (const t of A) if (B.has(t)) both++;
+  return both / (A.size + B.size - both) >= 0.5;
+}
+
+/** The part of a summary before " — " (a verifier gap's truth), lower-cased. */
+const headOf = (s) => String(s || '').split(' — ')[0].trim().toLowerCase();
+/** A verifier gap moves between missing and partial as it is worked on: one family. */
+const familyOf = (c) => (c === 'partial' ? 'missing' : c);
+
+/** Same class family, same file, and the same truth or a similar summary. */
+function sameFinding(e, f) {
+  return familyOf(e.class) === familyOf(f.class) && fileOf(e.where) === fileOf(f.where)
+    && (headOf(e.summary) === headOf(f.summary) || similar(e.summary, f.summary));
+}
+
+/** The earlier finding a judge's resolution answers: by id, else by its truth or summary. */
+function resolutionTarget(mine, r) {
+  if (r.id) return mine.find((f) => f.id === r.id) || null;
+  const head = headOf(r.summary);
+  return mine.find((f) => headOf(f.summary) === head) || mine.find((f) => similar(f.summary, r.summary)) || null;
+}
+
+function truncateReason(s) {
+  return String(s).replace(/\s+/g, ' ').trim().slice(0, REASON_MAX);
+}
+
+/**
+ * How stable a judge's findings are across its reports on one phase (V6): between
+ * consecutive verdicts, how many ids appeared and how many disappeared. A judge whose
+ * findings churn while the code does not change is not measuring the code.
+ */
+function findingsChurn(rows, phase, agent) {
+  const seq = foldFindings(rows).verdicts.filter((v) => v.agent === agent && samePhase(v.phase, phase));
+  let added = 0;
+  let dropped = 0;
+  let union = 0;
+  for (let i = 1; i < seq.length; i++) {
+    const a = new Set(seq[i - 1].finding_ids || []);
+    const b = new Set(seq[i].finding_ids || []);
+    for (const id of b) if (!a.has(id)) added++;
+    for (const id of a) if (!b.has(id)) dropped++;
+    union += new Set([...a, ...b]).size;
+  }
+  return { reports: seq.length, transitions: Math.max(0, seq.length - 1), added, dropped, rate: union ? Math.round(((added + dropped) / union) * 1000) / 1000 : 0 };
+}
+
 /** `.planning/` must exist: the ledger fills a planning tree, it never creates one. */
 function requirePlanningTree(cwd) {
   try { return fs.statSync(planningPath(cwd)).isDirectory(); } catch { return false; }
@@ -163,11 +229,15 @@ function recordVerdict(cwd, input) {
   // `not_checked` (M23): what the judge could not run. A pass with entries here is a
   // pass over less than the whole phase, and the record says so.
   const notChecked = verdict.not_checked || [];
-  const base = { contract: V.VERDICT_CONTRACT, agent, verdict: verdict.verdict, outcome: verdict.outcome, not_checked: notChecked, source_kind: parsed.source_kind, warnings: parsed.warnings };
+  // Two-key verdict (V9): when a code fact lowered the judge's word, the record keeps
+  // both, and `verdict` is the lowered word the workflow branches on.
+  const lowered = Array.isArray(parsed.lowered_by) && parsed.lowered_by.length
+    ? { agent_verdict: verdict.agent_verdict, lowered_by: parsed.lowered_by } : {};
+  const base = { contract: V.VERDICT_CONTRACT, agent, verdict: verdict.verdict, outcome: verdict.outcome, ...lowered, not_checked: notChecked, source_kind: parsed.source_kind, warnings: parsed.warnings };
 
   const dup = fold.verdicts.find((r) => r.record_sig === recordSig && r.agent === agent && samePhase(r.phase, phase));
   if (dup) {
-    return { ...base, recorded: false, duplicate: true, verdict_id: dup.verdict_id, attempt: dup.attempt, phase, findings: (dup.finding_ids || []).length, new: 0, auto_fixed: 0, reopened: 0 };
+    return { ...base, recorded: false, duplicate: true, verdict_id: dup.verdict_id, attempt: dup.attempt, phase, findings: (dup.finding_ids || []).length, new: 0, rematched: 0, resolved: 0, unaddressed: [], reopened: 0 };
   }
 
   const prior = fold.verdicts.filter((r) => r.agent === agent && samePhase(r.phase, phase));
@@ -180,21 +250,52 @@ function recordVerdict(cwd, input) {
   const ids = [];
   const newRows = [];
   const findingRows = [];
+  const mine = [...fold.findings.values()].filter((e) => e.agent === agent && samePhase(e.phase, phase));
+  let rematched = 0;
   for (const f of verdict.findings) {
-    const id = V.findingId(phase, agent, f);
+    let id = V.findingId(phase, agent, f);
+    if (!fold.findings.has(id)) {
+      // A reworded report of an earlier finding keeps that finding's id (V6), so a
+      // rewording is a re-report, not a fix plus a new finding.
+      const earlier = mine.filter((e) => !ids.includes(e.id) && sameFinding(e, f)).sort((a, b) => (a.status === 'open' ? 0 : 1) - (b.status === 'open' ? 0 : 1))[0];
+      if (earlier) { id = earlier.id; rematched++; }
+    }
     if (ids.includes(id)) continue; // the same finding twice in one report is one finding
     ids.push(id);
     if (!fold.findings.has(id)) {
       findingRows.push({ v: LEDGER_V, kind: 'finding', ts, id, verdict_id: verdictId, phase, milestone, agent, class: f.class, severity: f.severity, where: f.where, summary: f.summary });
     }
   }
-  const reopened = ids.filter((id) => fold.findings.has(id) && fold.findings.get(id).status === 'fixed').length;
-  const autoFixRows = [];
-  for (const f of fold.findings.values()) {
-    if (f.agent !== agent || !samePhase(f.phase, phase) || f.status !== 'open') continue;
-    if (ids.includes(f.id) || V.AUTO_FIX_EXEMPT.includes(f.class)) continue;
-    autoFixRows.push({ v: LEDGER_V, kind: 'disposition', ts, id: f.id, disposition: 'fixed', reason: `not reported by ${agent} at attempt ${attempt}`, auto: true, verdict_id: verdictId });
+
+  // Findings close only on evidence (V6). Silence is not evidence: an earlier open
+  // finding the new verdict neither reports nor answers stays open, and the record
+  // lists it as unaddressed. What closes one: the judge's `resolved` answer with its
+  // evidence, or, for a code-fact finding, the fact passing.
+  const resolveRows = [];
+  const closing = new Set();
+  const close = (f, reason) => {
+    if (closing.has(f.id) || ids.includes(f.id) || f.status !== 'open') return;
+    closing.add(f.id);
+    resolveRows.push({ v: LEDGER_V, kind: 'disposition', ts, id: f.id, disposition: 'fixed', reason: truncateReason(reason), auto: true, verdict_id: verdictId });
+  };
+  let contradicted = 0;
+  for (const r of verdict.resolutions || []) {
+    const target = resolutionTarget(mine, r);
+    if (!target) { parsed.warnings.push(`resolution_unmatched: ${r.id || r.summary}`); continue; }
+    if (r.status === 'resolved') {
+      if (ids.includes(target.id)) { contradicted++; continue; }
+      close(target, `resolved by ${agent} at attempt ${attempt}: ${r.evidence}`);
+    } else if (r.status === 'still_present' && !ids.includes(target.id)) {
+      ids.push(target.id); // a re-report: reopens a fixed finding, keeps an open one open
+    }
+  }
+  if (contradicted) parsed.warnings.push(`resolution_contradicted: ${contradicted} finding(s) answered resolved but reported again; they stay open`);
+  for (const fact of parsed.facts_ok || []) {
+    for (const f of mine) if (f.where === `code-fact:${fact}`) close(f, `${fact} passed at attempt ${attempt}`);
   }
+  const reopened = ids.filter((id) => fold.findings.has(id) && fold.findings.get(id).status === 'fixed').length;
+  const unaddressed = mine.filter((f) => f.status === 'open' && !ids.includes(f.id) && !closing.has(f.id)).map((f) => f.id);
+  if (unaddressed.length) parsed.warnings.push(`open_findings_unaddressed: ${unaddressed.length} earlier finding(s) neither reported nor resolved; they stay open`);
 
   const bySeverity = countBy(verdict.findings, 'severity');
   const byClass = countBy(verdict.findings, 'class');
@@ -205,11 +306,14 @@ function recordVerdict(cwd, input) {
   }
   newRows.push({
     v: LEDGER_V, kind: 'verdict', ts, verdict_id: verdictId, record_sig: recordSig, phase, milestone, agent,
-    verdict: verdict.verdict, outcome: verdict.outcome, attempt, source, finding_ids: ids,
+    verdict: verdict.verdict, outcome: verdict.outcome, ...lowered, attempt, source, finding_ids: ids,
     by_severity: bySeverity, by_class: byClass, warnings: parsed.warnings,
     ...(notChecked.length ? { not_checked: notChecked } : {}),
+    // A plan check is bound to the plans it checked (V7): exec-phase compares this
+    // hash with the plans it is about to run.
+    ...(agent === 'pan-plan-checker' ? { plans_sha: require('./verify-plan-set.cjs').plansShaFor(cwd, phase) } : {}),
   });
-  appendRows(cwd, [...findingRows, ...newRows, ...autoFixRows]);
+  appendRows(cwd, [...findingRows, ...newRows, ...resolveRows]);
 
   const category = { pass: 'verdict_passed', fail: 'verdict_failed', needs_human: 'verdict_needs_human' }[verdict.outcome];
   const serious = (bySeverity.critical || 0) + (bySeverity.high || 0) > 0;
@@ -228,13 +332,13 @@ function recordVerdict(cwd, input) {
       category: 'verdict_retry',
       agent,
       phase,
-      description: `${agent} judged phase ${phase} again (attempt ${attempt}): ${previous.outcome} → ${verdict.outcome}, ${autoFixRows.length} earlier finding(s) no longer reported`,
+      description: `${agent} judged phase ${phase} again (attempt ${attempt}): ${previous.outcome} → ${verdict.outcome}, ${resolveRows.length} earlier finding(s) resolved, ${unaddressed.length} unaddressed`,
       impact: 'minor',
-      context: { agent, phase, attempt, previous_outcome: previous.outcome, outcome: verdict.outcome, auto_fixed: autoFixRows.length, reopened, verdict_id: verdictId },
+      context: { agent, phase, attempt, previous_outcome: previous.outcome, outcome: verdict.outcome, resolved: resolveRows.length, unaddressed: unaddressed.length, reopened, verdict_id: verdictId },
     });
   }
 
-  return { ...base, recorded: true, duplicate: false, verdict_id: verdictId, attempt, phase, findings: ids.length, new: findingRows.length, auto_fixed: autoFixRows.length, reopened, ledger: planningRel(FINDINGS_FILE) };
+  return { ...base, recorded: true, duplicate: false, verdict_id: verdictId, attempt, phase, findings: ids.length, new: findingRows.length, rematched, resolved: resolveRows.length, unaddressed, reopened, ledger: planningRel(FINDINGS_FILE) };
 }
 
 /**
@@ -299,6 +403,7 @@ function listFindings(cwd, filters = {}) {
     findings,
     counts: { total: findings.length, by_status: countBy(findings, 'status'), by_class: countBy(findings, 'class'), by_severity: countBy(findings, 'severity') },
     verdicts: fold.verdicts.length,
+    ...(filters.phase && filters.agent ? { churn: findingsChurn(rows, filters.phase, filters.agent) } : {}),
     malformed_rows: malformed,
   };
 }
@@ -384,6 +489,8 @@ module.exports = {
   disposeFindings,
   listFindings,
   findingsDebt,
+  findingsChurn,
+  sameFinding,
   findingIdsIn,
   cmdFindingsRecord,
   cmdFindingsDispose,

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

@@ -300,10 +300,14 @@ function hostMemoryProjectRoot(cwd) {
   }
 }
 
-/** Claude Code's auto-memory directory for a project, and how it was found. */
-function hostMemoryDir(cwd, homeDir) {
+/**
+ * Claude Code's auto-memory directory for a project, and how it was found.
+ * `configDir` is Claude Code's user directory when CLAUDE_CONFIG_DIR moves it.
+ */
+function hostMemoryDir(cwd, homeDir, configDir = '') {
   const claudeDir = '.claude';
-  for (const f of [path.join(cwd, claudeDir, 'settings.local.json'), path.join(cwd, claudeDir, 'settings.json'), path.join(homeDir, claudeDir, 'settings.json')]) {
+  const userDir = configDir || path.join(homeDir, claudeDir);
+  for (const f of [path.join(cwd, claudeDir, 'settings.local.json'), path.join(cwd, claudeDir, 'settings.json'), path.join(userDir, 'settings.json')]) {
     let s = null;
     try { s = JSON.parse(safeReadFile(f) || 'null'); } catch { /* unreadable settings */ }
     if (s && typeof s.autoMemoryDirectory === 'string' && s.autoMemoryDirectory.trim()) {
@@ -312,18 +316,20 @@ function hostMemoryDir(cwd, homeDir) {
     }
   }
   const key = hostMemoryProjectRoot(cwd).replace(/[^A-Za-z0-9]/g, '-');
+  if (configDir) return { dir: path.join(configDir, 'projects', key, 'memory'), display: toPosix(path.join(configDir, 'projects', key, 'memory')), source: 'default' };
   return { dir: path.join(homeDir, claudeDir, 'projects', key, 'memory'), display: `~/${claudeDir}/projects/${key}/memory`, source: 'default' };
 }
 
 /**
  * H-11: Claude Code's auto-memory index. Read-only; never fixable by PAN.
  * @param {string} cwd
- * @param {{homeDir?: string}} [opts]
+ * @param {{homeDir?: string, configDir?: string}} [opts] - a given homeDir (a test seam) ignores CLAUDE_CONFIG_DIR
  */
 function checkHostMemory(cwd, opts = {}) {
   const findings = [];
   const home = opts.homeDir || require('os').homedir();
-  const loc = hostMemoryDir(cwd, home);
+  const configDir = opts.configDir !== undefined ? opts.configDir : (opts.homeDir ? '' : (process.env.CLAUDE_CONFIG_DIR || ''));
+  const loc = hostMemoryDir(cwd, home, configDir);
   const text = safeReadFile(path.join(loc.dir, 'MEMORY.md'));
   if (text == null) return { findings, host_memory: { dir: loc.display, index: false } };
   const lines = text.replace(/\r\n/g, '\n').replace(/\n$/, '').split('\n');

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

@@ -8,6 +8,7 @@ const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInte
 const { PHASES_DIR, CODEBASE_DIR, QUICK_DIR, MILESTONES_DIR, STATE_FILE, ROADMAP_FILE, CONFIG_FILE, PROJECT_FILE, REQUIREMENTS_FILE, isPlanFile, isSummaryFile, isResearchFile, isContextFile, isVerificationFile, PLAN_SUFFIX, SUMMARY_SUFFIX, CONTEXT_SUFFIX, RESEARCH_SUFFIX, VERIFICATION_SUFFIX, UAT_SUFFIX, MAX_SLUG_LENGTH } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, classifyPhaseStatus, hasBraveSearchKey, parsePhaseDir, planningRel } = require('./utils.cjs');
 const { classifyPlanTier } = require('./phase.cjs');
+const { planCheckStatus, planDrift } = require('./verify-plan-set.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { detectLanguages } = require('./codebase.cjs');
 const { detectForeignPlanningTreeAt } = require('./foreign-planning.cjs');
@@ -205,6 +206,11 @@ function cmdInitExecutePhase(cwd, phase, raw, opts) {
     execution_mode: (config.execution && config.execution.default_mode) || 'wave_order',
     dry_run: dryRun,
     rollback_tag: null,
+
+    // Plan checks in code (V7): whether these plans are the ones that passed the
+    // plan check, and which planned files changed on the branch since planning.
+    plan_check: phaseInfo ? planCheckStatus(cwd, phase) : null,
+    plan_drift: phaseInfo ? planDrift(cwd, phase) : [],
   };
 
   output(result, raw);

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

@@ -1269,6 +1269,18 @@ function cmdOptimizeLearn(cwd, opts, raw) {
   }, raw);
 }
 
+/**
+ * `--report` as given resolves against the project (`--cwd`), not the shell's
+ * directory; a bare file name that is not there is looked up in the reports dir.
+ */
+function resolveReportPath(cwd, given) {
+  const abs = path.resolve(cwd, given);
+  if (fs.existsSync(abs)) return abs;
+  if (path.basename(given) !== given) return abs; // a path with directories is taken as given
+  const inReports = path.join(getReportsDir(cwd), given);
+  return fs.existsSync(inReports) ? inReports : abs;
+}
+
 function cmdOptimizeApply(cwd, opts, raw) {
   const reports = listOptimizationReports(cwd);
   if (reports.error || reports.count === 0) {
@@ -1276,7 +1288,7 @@ function cmdOptimizeApply(cwd, opts, raw) {
     return;
   }
 
-  const reportPath = opts.reportPath || reports.reports[0].path;
+  const reportPath = opts.reportPath ? resolveReportPath(cwd, opts.reportPath) : reports.reports[0].path;
   const result = applyReportRecommendations(cwd, reportPath);
   output({ report: path.basename(reportPath), ...result }, raw);
 }

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

@@ -0,0 +1,174 @@
+'use strict';
+/**
+ * The phase gate (program V1): may this phase be marked complete?
+ *
+ * Every guarantee at the end of PAN's loop used to be a sentence in a workflow:
+ * "do not advance unless the verification passed", "reconcile before advancing".
+ * The model skipped one (exec-phase's `--no-transition` path never ran reconcile at
+ * all), and `phase complete` marked the phase done regardless. The gate puts those
+ * rules in code, in one function every caller uses: `phase complete`, the native
+ * exec-waves script, and the MCP merge request.
+ *
+ * Refusal reasons, one code per class:
+ *   no_plans · missing_summary · no_verification · verification_unreadable ·
+ *   verification_failed (V9 lowering included) · human_needed_unapproved ·
+ *   verification_stale · reconcile_contradiction · test_failed · open_findings ·
+ *   stubs_found · integrity_violation
+ *
+ * What the gate could not check is listed in `not_checked`, never refused on:
+ * a skipped test gate, an unknown freshness, no git, no plan commits, the verifier
+ * switched off. `workflow.phase_gate` is `warn` (default: report and proceed) or
+ * `enforce` (refuse unless `--force --reason`, which records a decision).
+ */
+const fs = require('fs');
+const path = require('path');
+const { findPhaseInternal, safeReadFile, loadConfig, output, error } = require('./core.cjs');
+const { isVerificationFile } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+const MODES = Object.freeze(['warn', 'enforce']);
+const SERIOUS = new Set(['critical', 'high']);
+
+/** `workflow.phase_gate` from config.json: `enforce` or (anything else) `warn`. */
+function gateMode(cwd) {
+  let cfg = null;
+  try { cfg = JSON.parse(fs.readFileSync(planningPath(cwd, 'config.json'), 'utf-8')); } catch { /* defaults */ }
+  const v = cfg && cfg.workflow && cfg.workflow.phase_gate;
+  return MODES.includes(v) ? v : 'warn';
+}
+
+/**
+ * @param {string} cwd
+ * @param {string|number} phase
+ * @param {{mode?: 'warn'|'enforce'}} [opts]
+ * @returns {{phase, mode, ok, reasons: Array<{code, detail}>, facts: Object, not_checked: Array<{check, reason}>}|{error, reason}}
+ */
+function phaseGate(cwd, phase, opts = {}) {
+  const info = findPhaseInternal(cwd, phase);
+  if (!info || !info.found) return { error: 'phase_not_found', reason: `no phase directory for phase ${phase}` };
+  const V = require('./verdict.cjs');
+  const F = require('./findings.cjs');
+  const { reconcilePhase, verificationFreshness, scanStubs } = require('./verify.cjs');
+  const { committedFiles } = require('./verify-scope.cjs');
+  const { checkTestIntegrity } = require('./verify-integrity.cjs');
+
+  const mode = MODES.includes(opts.mode) ? opts.mode : gateMode(cwd);
+  const reasons = [];
+  const notChecked = [];
+  const facts = {};
+  const refuse = (code, detail, extra = {}) => reasons.push({ code, detail, ...extra });
+  const skip = (check, reason) => notChecked.push({ check, reason });
+  const phaseNumber = info.phase_number || String(phase);
+  const dir = path.join(cwd, info.directory);
+
+  // 1. Every plan has a summary.
+  const plans = info.plans || [];
+  const incomplete = info.incomplete_plans || [];
+  facts.plans = `${plans.length - incomplete.length}/${plans.length}`;
+  if (!plans.length) refuse('no_plans', 'the phase has no plans');
+  else if (incomplete.length) refuse('missing_summary', `${incomplete.length} plan(s) have no summary: ${incomplete.join(', ')}`, { plans: incomplete });
+
+  // 2. A passing verification (with code facts applied, V9).
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { /* unreadable reads as empty */ }
+  const verFile = names.filter(isVerificationFile).sort().pop();
+  const verifierOn = loadConfig(cwd).verifier !== false;
+  if (!verFile) {
+    if (verifierOn) refuse('no_verification', 'the phase has no verification; run /pan:verify-phase');
+    else skip('verification', 'workflow.verifier is off');
+  } else {
+    const parsed = V.parseVerdictText(safeReadFile(path.join(dir, verFile)) || '', { agent: 'pan-verifier', phase: phaseNumber });
+    if (!parsed.ok) {
+      refuse('verification_unreadable', `${verFile}: ${parsed.reason}`);
+    } else {
+      const v = parsed.verdict;
+      const fm = V.verdictFromVerificationFrontmatter(safeReadFile(path.join(dir, verFile)) || '') || {};
+      facts.verification = v.verdict;
+      facts.test_gate = fm.test_gate || null;
+      if (parsed.lowered_by && parsed.lowered_by.length) facts.lowered_by = parsed.lowered_by;
+      if (fm.test_gate === 'failed') refuse('test_failed', 'the verification records test_gate: failed');
+      else if (fm.test_gate === 'skipped') skip('tests', 'the test gate was skipped');
+      else if (!fm.test_gate) skip('tests', 'the verification does not record its test gate');
+      if (v.outcome === 'fail') {
+        refuse('verification_failed', `the verification is ${v.verdict}${v.agent_verdict ? ` (the verifier wrote ${v.agent_verdict})` : ''}`);
+      } else if (v.outcome === 'needs_human') {
+        const human = F.listFindings(cwd, { phase: phaseNumber, agent: 'pan-verifier', class: 'human' }).findings;
+        const unapproved = human.filter((f) => f.status !== 'decision');
+        if (unapproved.length || !human.length) {
+          refuse('human_needed_unapproved', `${unapproved.length || 'the'} human verification item(s) have no recorded approval; record it with \`findings dispose <id> --as decision --reason "<what was checked>"\``, { ids: unapproved.map((f) => f.id) });
+        }
+      }
+    }
+  }
+
+  // 3. The verification still describes the code.
+  if (verFile) {
+    const fresh = verificationFreshness(cwd, phaseNumber, info);
+    facts.freshness = fresh.state;
+    if (fresh.state === 'stale') refuse('verification_stale', `files changed since the verified commit: ${(fresh.changed_since || []).slice(0, 5).join(', ')}`, { changed_since: fresh.changed_since });
+    else if (fresh.state === 'unknown') skip('freshness', fresh.reason || 'unknown');
+  }
+
+  // 4. The written verdict agrees with the mechanical checks.
+  if (verFile) {
+    const rec = reconcilePhase(cwd, phaseNumber);
+    facts.reconciled = rec.reconciled;
+    if (!rec.reconciled) refuse('reconcile_contradiction', rec.contradictions.join('; '), { contradictions: rec.contradictions });
+  }
+
+  // 5. No critical or high finding left open without a disposition.
+  const open = F.listFindings(cwd, { phase: phaseNumber, status: 'open' }).findings
+    .filter((f) => SERIOUS.has(f.severity) && f.class !== 'human');
+  facts.open_serious_findings = open.length;
+  if (open.length) refuse('open_findings', `${open.length} critical/high finding(s) are open: dispose each (\`findings dispose <id> --as fixed|deferred|dismissed|decision --reason "…"\`) or fix it`, { ids: open.map((f) => f.id) });
+
+  // 6. No stub in the files the phase committed.
+  const committed = committedFiles(cwd, phaseNumber);
+  if (!committed.git) {
+    skip('stubs', 'git is unavailable');
+  } else {
+    const files = [...committed.files].filter((f) => fs.existsSync(path.join(cwd, f)));
+    const stubs = scanStubs(cwd, { files });
+    facts.stubs_blocking = stubs.blocking;
+    if (stubs.blocking) refuse('stubs_found', `${stubs.blocking} stub marker(s) in committed files: ${stubs.findings.filter((s) => s.severity === 'high').slice(0, 3).map((s) => `${s.file}:${s.line}`).join(', ')}`);
+  }
+
+  // 7. The phase did not weaken its own tests.
+  const integrity = checkTestIntegrity(cwd, phaseNumber);
+  if (integrity.error || !integrity.checked) {
+    skip('test_integrity', integrity.reason || integrity.error);
+  } else {
+    facts.test_integrity = integrity.ok ? 'clean' : 'violated';
+    if (!integrity.ok) refuse('integrity_violation', integrity.violations.slice(0, 3).map((x) => `${x.code} ${x.file}`).join('; '), { violations: integrity.violations });
+  }
+
+  return { phase: phaseNumber, mode, ok: reasons.length === 0, reasons, facts, not_checked: notChecked };
+}
+
+/**
+ * `--force --reason`: complete past the gate, on the record. Every open finding the
+ * gate counted gets a `decision` disposition with the reason, and the trace logs it.
+ */
+function recordGateOverride(cwd, gate, reason) {
+  const F = require('./findings.cjs');
+  const ids = [];
+  for (const r of gate.reasons) for (const id of r.ids || []) if (!ids.includes(id)) ids.push(id);
+  const disposed = ids.length ? F.disposeFindings(cwd, { ids, as: 'decision', reason: `phase completed past the gate: ${reason}` }) : { disposed: [] };
+  try {
+    require('./optimize.cjs').logTraceEvent(cwd, {
+      type: 'decision', category: 'phase_gate_forced', agent: 'orchestrator', phase: gate.phase,
+      description: `phase ${gate.phase} completed past the gate (${gate.reasons.map((r) => r.code).join(', ')}): ${reason}`,
+      impact: 'major', context: { reasons: gate.reasons.map((r) => r.code), reason },
+    });
+  } catch { /* telemetry is best effort */ }
+  return { reason, refused_by: gate.reasons.map((r) => r.code), disposed: disposed.disposed || [] };
+}
+
+function cmdPhaseGate(cwd, phase, raw, opts = {}) {
+  if (!phase) error('Usage: phase gate <N> [--mode warn|enforce]');
+  const r = phaseGate(cwd, phase, opts);
+  if (r.error) { output(r, raw); return; }
+  output(r, raw, r.ok ? 'pass' : 'refuse', r.ok ? 0 : 1);
+}
+
+module.exports = { phaseGate, recordGateOverride, gateMode, cmdPhaseGate, MODES };

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

@@ -823,6 +823,26 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
     error(`Phase ${phaseNum} not found`);
   }
 
+  // The phase gate (V1). In `enforce` mode a refusal stops here unless --force
+  // --reason, which records a decision; in `warn` mode the reasons travel with the
+  // result. A --force without a reason is refused in either mode.
+  const { phaseGate, recordGateOverride } = require('./phase-gate.cjs');
+  const force = !!(opts && opts.force);
+  const forceReason = opts && typeof opts.reason === 'string' ? opts.reason.trim() : '';
+  if (force && !forceReason) {
+    output({ error: 'reason_required', reason: 'phase complete --force needs --reason "<why the gate is being overridden>"' }, raw);
+    return;
+  }
+  const gate = phaseGate(cwd, phaseNum);
+  let gateOverride = null;
+  if (!gate.error && !gate.ok) {
+    if (gate.mode === 'enforce' && !force) {
+      output({ error: 'phase_gate_refused', reason: gate.reasons.map((r) => `${r.code}: ${r.detail}`).join(' | '), gate }, raw);
+      return;
+    }
+    if (force) gateOverride = recordGateOverride(cwd, gate, forceReason);
+  }
+
   const planCount = phaseInfo.plans.length;
   const summaryCount = phaseInfo.summaries.length;
 
@@ -886,6 +906,8 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
     date: today,
     roadmap_updated: fileAccessible(roadmapPath),
     state_updated: fileAccessible(statePath),
+    gate: gate.error ? { error: gate.error } : { ok: gate.ok, mode: gate.mode, reasons: gate.reasons, not_checked: gate.not_checked },
+    ...(gateOverride ? { gate_override: gateOverride } : {}),
   };
   if (roadmapResult && roadmapResult.requirements_warning) {
     result.requirements_warning = roadmapResult.requirements_warning;
@@ -982,6 +1004,8 @@ module.exports = {
   cmdFindPhase,
   cmdPhasePlanIndex,
   blockedPlans,
+  buildPlanIndex,
+  dependencyNames,
   cmdPhaseAdd,
   cmdPhaseInsert,
   cmdPhaseRemove,