pan-wizard 3.33.0 → 3.35.0

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

@@ -6,7 +6,7 @@ const fs = require('fs');
 const path = require('path');
 const { PHASES_DIR, MILESTONES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, STATE_FILE, isPlanFile } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible, planningRel } = require('./utils.cjs');
-const { output, error, isGitRepo, execGit, escapeRegex } = require('./core.cjs');
+const { output, error, isGitRepo, isGitIgnored, execGit, escapeRegex, loadConfig } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -258,8 +258,13 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     result.archive_warnings = archiveResult.warnings;
   }
 
-  // Auto-commit + tag unless --no-commit or not a git repo
-  if (!options.noCommit && isGitRepo(cwd)) {
+  // Auto-commit + tag unless --no-commit, not a git repo, or the project keeps planning
+  // files out of git (`commit_docs: false` or a gitignored planning tree), the rules
+  // `phase complete` and `pan-tools commit` follow (this commit used to ignore both).
+  const noCommit = options.noCommit
+    || loadConfig(cwd).commit_docs === false
+    || isGitIgnored(cwd, planningRel());
+  if (!noCommit && isGitRepo(cwd)) {
     execGit(cwd, ['add', planningRel() + '/']);
     const commitMsg = `docs: milestone ${version} complete`;
     const commitResult = execGit(cwd, ['commit', '-m', commitMsg]);

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, escapeRegex, execGit } = require('./core.cjs');
+const { output, escapeRegex, execGit, toLf } = require('./core.cjs');
 const { planningPath, planningRel } = require('./utils.cjs');
 
 // ─── Storage layout ──────────────────────────────────────────────────────────
@@ -793,6 +793,27 @@ function revertedIndices(rows) {
   return out;
 }
 
+/** The trace session a report belongs to, from its name (`<session>-opt-report.md`, `<session>-analysis.json`). */
+function reportSessionId(reportPath) {
+  const m = path.basename(String(reportPath || '')).match(/^(.+?)-(?:opt-report\.md|analysis\.json)$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * An older report's memory actions (`memory`, `memory_append`, `memory_entry`) still
+ * write into `.planning/memory/`, but PAN's workflows no longer load that folder into
+ * agents (ADR-0036, amended 2026-10-04). Say so in the result rather than let the
+ * apply look like it taught anyone anything.
+ */
+const MEMORY_NOT_LOADED_WARNING = "stored in .planning/memory/, which PAN's workflows do not load into agents (ADR-0036): "
+  + "write a lesson where the agents read — the project's instructions, a test, or the code";
+
+function notLoadedWarning(cwd, relPath) {
+  const abs = path.resolve(cwd, relPath || '');
+  if (path.dirname(abs) !== path.resolve(planningPath(cwd), 'memory')) return {};
+  return { warning: MEMORY_NOT_LOADED_WARNING };
+}
+
 function applyReportRecommendations(cwd, reportPath) {
   let reportContent;
   try {
@@ -842,15 +863,23 @@ function applyReportRecommendations(cwd, reportPath) {
   const resolvedCwd = path.resolve(cwd);
   actions.forEach((action, i) => {
     try {
-      // Containment: action.path on memory writes is report/agent-authored and
-      // must stay inside the project. A `../` (or absolute) path otherwise
-      // escapes and writes anywhere the process can (M23, ADR audit 2026-08).
+      // Containment: action.path on memory writes is report/agent-authored. A `../`
+      // (or absolute) path escaped the project (M23, ADR audit 2026-08), and a path
+      // inside it reached any file: a report's `memory_append` to CLAUDE.md made
+      // agent-written text a standing instruction with no review (ADR-0040), and
+      // `/pan:learn --apply` runs this on the optimizer's own report. A memory action
+      // writes memory: `.planning/memory/` and nothing else.
       if (action.type === 'memory' || action.type === 'memory_append') {
         const abs = path.resolve(cwd, action.path || '');
+        const memoryDir = path.resolve(planningPath(cwd), 'memory');
         if (abs !== resolvedCwd && !abs.startsWith(resolvedCwd + path.sep)) {
           skipped.push({ action, reason: 'path escapes project root — skipped' });
           return;
         }
+        if (!abs.startsWith(memoryDir + path.sep)) {
+          skipped.push({ action, reason: 'a memory action writes only into .planning/memory/ — skipped; make a change to the project\'s instructions yourself' });
+          return;
+        }
       }
       const earlier = live.get(actionSig(action));
       if (earlier) {
@@ -867,11 +896,29 @@ function applyReportRecommendations(cwd, reportPath) {
           fs.mkdirSync(path.dirname(memPath), { recursive: true });
           fs.writeFileSync(memPath, action.content, 'utf-8');
           records.push({ i, type: action.type, path: rel(memPath), kind: 'created', sha256_after: normalisedHash(fs.readFileSync(memPath, 'utf-8')), action_sig: actionSig(action) });
-          applied.push({ action, result: `Written to ${action.path}` });
+          applied.push({ action, result: `Written to ${action.path}`, ...notLoadedWarning(cwd, action.path) });
         }
       } else if (action.type === 'memory_append') {
         appendRecorded(path.join(cwd, action.path), '\n' + action.content, action, i);
-        applied.push({ action, result: `Appended to ${action.path}` });
+        applied.push({ action, result: `Appended to ${action.path}`, ...notLoadedWarning(cwd, action.path) });
+      } else if (action.type === 'memory_entry') {
+        // The gated write path (O6): a lesson drawn from this report's trace session,
+        // recorded only if it carries citations that hold and passes `memory record`'s
+        // other rules. The optimizer no longer proposes these; an older report's are
+        // still recorded, as created/appended so revert works.
+        const session = reportSessionId(reportPath);
+        if (!session) { skipped.push({ action, reason: 'a memory entry needs the trace session the report came from, and this report\'s name does not carry one' }); return; }
+        const { recordLesson } = require('./memory.cjs');
+        const logPath = path.join(planningPath(cwd), 'memory', `${String(action.agent || '')}.md`);
+        let before = null;
+        try { before = fs.readFileSync(logPath, 'utf-8'); } catch { /* a new log */ }
+        const r = recordLesson(cwd, String(action.agent || ''), { lesson: action.lesson, trace: session, cites: action.cites });
+        if (r.error || !r.recorded) { skipped.push({ action, reason: r.error || `memory record refused it: ${r.reason}` }); return; }
+        const after = fs.readFileSync(logPath, 'utf-8');
+        records.push(before === null
+          ? { i, type: action.type, path: rel(logPath), kind: 'created', sha256_after: normalisedHash(after), action_sig: actionSig(action) }
+          : { i, type: action.type, path: rel(logPath), kind: 'appended', text: toLf(after).slice(toLf(before).length), sha256_after: normalisedHash(after), action_sig: actionSig(action) });
+        applied.push({ action, result: `Recorded for ${r.agent} from ${r.evidence}`, warning: MEMORY_NOT_LOADED_WARNING });
       } else if (action.type === 'note') {
         // Write a human-readable suggestion note
         const entry = `\n## ${new Date().toISOString()}: ${action.description || 'Suggestion'}\n\n${action.content || action.suggestion || ''}\n\n**Target:** ${action.target || 'unspecified'}\n`;
@@ -992,7 +1039,11 @@ function revertApply(cwd, which) {
   return { apply_id: apply.apply_id, reverted: out.sort((x, y) => x - y), refused, status: remaining === 0 ? 'reverted' : (out.length ? 'partial' : 'refused') };
 }
 
-// Derive basic memory actions from a raw JSON analysis when no optimizer agent
+// Where a lesson reaches the next run's agents: they read the project's
+// instructions, and PAN's workflows no longer load `.planning/memory/` (ADR-0036).
+const LESSON_TARGET = "the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section)";
+
+// Derive suggestion notes from a raw JSON analysis when no optimizer agent
 // report is available (fallback for /pan:optimize apply on a JSON file).
 function deriveActionsFromAnalysis(analysis) {
   const actions = [];
@@ -1002,9 +1053,9 @@ function deriveActionsFromAnalysis(analysis) {
     memory_miss_patterns.slice(0, 3).forEach(p => {
       actions.push({
         type: 'note',
-        description: `Memory miss: ${p.pattern}`,
-        content: `This topic was missing from memory ${p.count} time(s) during the traced session. Consider adding a memory entry for it.`,
-        target: '.planning/memory/',
+        description: `Missing knowledge: ${p.pattern}`,
+        content: `An agent logged this as missing ${p.count} time(s) during the traced session. Write the answer where the agents read: ${LESSON_TARGET}, or a comment at the code it concerns.`,
+        target: LESSON_TARGET,
       });
     });
   }
@@ -1016,8 +1067,8 @@ function deriveActionsFromAnalysis(analysis) {
     actions.push({
       type: 'note',
       description: `Recurring tool failure: ${p.agent} ${p.tool} (${p.error_class})`,
-      content: `${p.agent}'s ${p.tool} call failed with "${p.message}" in ${p.spawns} spawns across ${p.sessions} session(s) (${p.occurrences} times in all). Record the working form of the call, or the precondition it needs, as a memory entry for ${p.agent}.`,
-      target: '.planning/memory/',
+      content: `${p.agent}'s ${p.tool} call failed with "${p.message}" in ${p.spawns} spawns across ${p.sessions} session(s) (${p.occurrences} times in all). Write the working form of the call, or the precondition it needs, where ${p.agent} reads it: ${LESSON_TARGET}.`,
+      target: LESSON_TARGET,
     });
   });
   Object.entries(analysis.verdict_stats || {}).filter(([, s]) => s.fail >= 2).forEach(([agent, s]) => {
@@ -1025,7 +1076,7 @@ function deriveActionsFromAnalysis(analysis) {
       type: 'note',
       description: `Repeated judge failures: ${agent}`,
       content: `${agent} failed ${s.fail} time(s) (${s.retries} retr${s.retries === 1 ? 'y' : 'ies'}, ${s.resolved_by_retry} resolved by the retry). Read the recorded findings (\`pan-tools findings list --agent ${agent}\`) for the class that keeps recurring before the next phase.`,
-      target: '.planning/memory/',
+      target: '.planning/findings.jsonl',
     });
   });
 
@@ -1034,8 +1085,8 @@ function deriveActionsFromAnalysis(analysis) {
       actions.push({
         type: 'note',
         description: `Knowledge gap: ${p.pattern}`,
-        content: `The agent had to infer this ${p.count} time(s). Research and cache the answer.`,
-        target: '.planning/memory/',
+        content: `The agent had to infer this ${p.count} time(s). Research the answer and write it where the agents read: ${LESSON_TARGET}, or a comment at the code it concerns.`,
+        target: LESSON_TARGET,
       });
     });
   }
@@ -1218,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) {
@@ -1225,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);
 }
@@ -1286,6 +1349,14 @@ function validatePromoteInputs(pattern, opts) {
   if (!pattern.id) return 'pattern.id is required';
   if (!pattern.summary) return 'pattern.summary is required';
   if (!pattern.rule) return 'pattern.rule is required';
+  // A citation names the code the pattern rests on, relative to the tree that
+  // holds the store; it must hold now, and learn lint L-007 keeps checking it.
+  if (pattern.cites !== undefined && !Array.isArray(pattern.cites)) return 'pattern.cites must be a list';
+  const { citationProblem } = require('./memory.cjs');
+  for (const c of pattern.cites || []) {
+    const problem = citationProblem(opts.sourceRoot, c);
+    if (problem) return `citation ${c}: ${problem}`;
+  }
   return null;
 }
 
@@ -1366,7 +1437,8 @@ function classifyPatternKind(pattern) {
  * always written by us — no general YAML dependency needed).
  */
 function readTopicFile(filePath) {
-  const content = fs.readFileSync(filePath, 'utf-8');
+  // LF: an install committed with core.autocrlf=true holds these files as CRLF.
+  const content = toLf(fs.readFileSync(filePath, 'utf-8'));
   const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!fmMatch) {
     return { frontmatter: { topic: '', patterns: [] }, body: content, _raw: content };
@@ -1429,6 +1501,13 @@ function serializeTopicFile(topic, patterns, body) {
     fm += `    promoted_at: ${p.promoted_at || ts}\n`;
     const srcExps = Array.isArray(p.source_experiments) ? p.source_experiments : [];
     fm += `    source_experiments: [${srcExps.join(', ')}]\n`;
+    // Optional fields survive a re-serialisation: promoting into an existing topic
+    // rewrites every pattern's frontmatter, and dropping these lost the supersession
+    // learn lint L-005 reads, and the citations L-007 checks.
+    const cites = Array.isArray(p.cites) ? p.cites : [];
+    if (cites.length) fm += `    cites: [${cites.join(', ')}]\n`;
+    if (p.superseded_by) fm += `    superseded_by: ${p.superseded_by}\n`;
+    if (p.superseded_id) fm += `    superseded_id: ${p.superseded_id}\n`;
   }
   return `---\n${fm}---\n${body}`;
 }
@@ -1519,6 +1598,7 @@ function promotePattern(pattern, opts) {
     summary: pattern.summary,
     promoted_at: promotedAt,
     source_experiments: pattern.source_experiments || [],
+    ...(pattern.cites && pattern.cites.length ? { cites: pattern.cites } : {}),
   });
 
   const serialized = serializeTopicFile(topic, frontmatter.patterns, body);

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-remove.cjs

@@ -173,6 +173,74 @@ function renumberIntegerPhases(phasesDir, removedInt) {
   return { renamedDirs, renamedFiles };
 }
 
+/**
+ * Remove one phase's section from roadmap text. The section runs from its `Phase N:` heading
+ * to the first line outside a code fence that is another phase heading, a heading at the
+ * section's own level or above (`## Progress`, a milestone group), a `</details>` that closes
+ * an enclosing block, or a collapsed milestone's `<details>` (its `<summary>` names a version
+ * or a phase range). Any other `<details>` block the section opens and closes itself is part
+ * of it. Running to the end of the file deleted `## Progress` with the last phase and the next
+ * milestone group's heading with a group's last phase; a line-blind bound stopped at a
+ * `# comment` or `## Usage` inside a fenced block.
+ * @param {string} content - roadmap.md text (LF or CRLF; line endings are kept)
+ * @param {string} phaseNum - the phase number as written in its heading
+ * @returns {string} the text without that section (unchanged when no heading matches)
+ */
+function removePhaseSection(content, phaseNum) {
+  const lines = content.split('\n');
+  const fenced = new Array(lines.length).fill(false);
+  // A fence line with an info string opens a block, even inside another (a nested example);
+  // a bare one closes the innermost block it can close. A block never closed stays unfenced.
+  for (let i = 0, stack = []; i < lines.length; i++) {
+    const f = lines[i].match(/^\s{0,3}(`{3,}|~{3,})(.*)/);
+    if (!f) continue;
+    const top = stack[stack.length - 1];
+    if (top && !f[2].trim() && f[1][0] === top.fence[0] && f[1].length >= top.fence.length) {
+      stack.pop();
+      fenced.fill(true, top.open, i + 1);
+    } else if (!top || f[2].trim()) stack.push({ fence: f[1], open: i });
+  }
+  const headRe = new RegExp(`^(#{2,4})\\s*Phase\\s+${escapeRegex(phaseNum)}\\s*:`, 'i');
+  const start = lines.findIndex((l, i) => !fenced[i] && headRe.test(l));
+  if (start === -1) return content;
+  const levelEndRe = new RegExp(`^#{1,${lines[start].match(headRe)[1].length}}\\s`);
+  const endsSection = (i) => !fenced[i] && (/^#{2,4}\s*Phase\s+\d/i.test(lines[i]) || levelEndRe.test(lines[i]));
+  const opens = (i) => !fenced[i] && /^\s*<details\b/i.test(lines[i]);
+  const closes = (i) => !fenced[i] && /^\s*<\/details\b/i.test(lines[i]);
+  const oneLine = (i) => /<\/details\s*>/i.test(lines[i]);
+  // A collapsed milestone's <summary> names its version or phase range ("v1.0 MVP (Phases 1-4)").
+  const milestone = (i) => /<summary>[^<]*\b(?:v\d+\.\d+|phases\s+\d)/i.test(`${lines[i]} ${lines[i + 1] || ''}`);
+  // A <details> closed before anything that ends the section is the section's own block.
+  const ownBlock = (at) => {
+    for (let i = at + 1, d = 0; i < lines.length; i++) {
+      if (endsSection(i)) return false;
+      if (opens(i) && !oneLine(i)) d++;
+      else if (closes(i)) { if (d === 0) return true; d--; }
+    }
+    return false;
+  };
+  let end = start + 1;
+  for (let depth = 0; end < lines.length; end++) {
+    if (endsSection(end)) break;
+    if (opens(end)) {
+      if (depth === 0 && milestone(end)) break;
+      if (oneLine(end)) continue;
+      if (depth > 0 || ownBlock(end)) { depth++; continue; }
+      break;
+    }
+    if (closes(end)) { if (depth > 0) { depth--; continue; } break; }
+  }
+  const toEof = end === lines.length;
+  lines.splice(start, end - start);
+  let out = lines.join('\n');
+  // A section that ran to the end of the file took the final line ending with it.
+  if (toEof && content.endsWith('\n')) {
+    out = out.replace(/\r$/, '');
+    if (!out.endsWith('\n')) out += content.endsWith('\r\n') ? '\r\n' : '\n';
+  }
+  return out;
+}
+
 /**
  * Rewrite roadmap.md after a phase is removed: delete the target section,
  * remove checkbox/table references, and renumber subsequent phase references.
@@ -189,14 +257,8 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
     roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
   } catch { return; }
 
-  // Remove the target phase section from roadmap.md.
-  // Matches from the phase heading to the next phase heading (or end of file).
+  roadmapContent = removePhaseSection(roadmapContent, phaseNum);
   const targetEscaped = escapeRegex(phaseNum);
-  const sectionPattern = new RegExp(
-    `\\n?#{2,4}\\s*Phase\\s+${targetEscaped}\\s*:[\\s\\S]*?(?=\\n#{2,4}\\s+Phase\\s+\\d|$)`,
-    'i'
-  );
-  roadmapContent = roadmapContent.replace(sectionPattern, '');
 
   // Remove checkbox list items referencing this phase
   const checkboxPattern = new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${targetEscaped}[:\\s][^\\n]*`, 'gi');
@@ -207,8 +269,9 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
   roadmapContent = roadmapContent.replace(tableRowPattern, '');
 
   // For integer phase removal, renumber all references to subsequent phases.
-  // Walk from highest phase number down to removedInt+1, decrementing each by 1.
-  // This avoids double-renaming (e.g. 8->7 then 7->6 would break if done ascending).
+  // Walk UP from removedInt+1, decrementing each by 1. A downward walk re-hits its
+  // own output (10->9, then that 9 and the real 9 ->8), so every later phase
+  // collapsed onto the removed number.
   if (!isDecimal) {
     const removedInt = parseInt(normalized, 10);
 
@@ -219,35 +282,35 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
     // and an unbounded lower end is how `phase remove -1234567890` turned into
     // ~1.2 billion regex passes. The loop can now never exceed maxPhase steps.
     const stopAt = Math.max(removedInt, 0);
-    for (let oldNum = maxPhase; oldNum > stopAt; oldNum--) {
+    for (let oldNum = stopAt + 1; oldNum <= maxPhase; oldNum++) {
       const newNum = oldNum - 1;
       const oldStr = String(oldNum);
       const newStr = String(newNum);
       const oldPad = oldStr.padStart(2, '0');
       const newPad = newStr.padStart(2, '0');
 
-      // Phase headings: ## Phase 18: or ### Phase 18: -> ## Phase 17:
+      // Phase headings: ## Phase 18: or ### Phase 18.1: -> ## Phase 17: / ### Phase 17.1:
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'),
+        new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}((?:\\.\\d+)?\\s*:)`, 'gi'),
         `$1${newStr}$2`
       );
 
-      // Inline phase references: "Phase 18:" or "Phase 18 " -> "Phase 17:"
+      // Inline phase references: "Phase 18:", "Phase 18 " or "Phase 18.1:" -> "Phase 17..."
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'),
+        new RegExp(`(Phase\\s+)${oldStr}((?:\\.\\d+)?[:\\s])`, 'g'),
         `$1${newStr}$2`
       );
 
-      // Plan references in padded form: 18-01 -> 17-01
+      // Plan references in padded form: 18-01 / 18.1-01 -> 17-01 / 17.1-01, never inside a date (2026-10-01)
       roadmapContent = roadmapContent.replace(
-        new RegExp(`${oldPad}-(\\d{2})`, 'g'),
-        `${newPad}-$1`
+        new RegExp(`(?<![\\d.-])${oldPad}((?:\\.\\d+)?)-(\\d{2})(?!\\d)`, 'g'),
+        `${newPad}$1-$2`
       );
 
-      // Progress table row numbers: | 18. -> | 17.
+      // Progress table row numbers: | 18. or | 18.1. -> | 17. / | 17.1.
       roadmapContent = roadmapContent.replace(
-        new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'),
-        `$1${newStr}. `
+        new RegExp(`(\\|\\s*)${oldStr}((?:\\.\\d+)?)\\.\\s`, 'g'),
+        `$1${newStr}$2. `
       );
 
       // Depends-on references: "Depends on:** Phase 18" -> "Phase 17"
@@ -279,7 +342,7 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
   // PHASE_NUM_RE does not match — so a bad argument used to reach the renumber
   // logic and do real damage, in both cases reporting success and exiting 0:
   //   `phase remove 0`      renumbered EVERY roadmap heading down to "Phase 0"
-  //                         (the descending renumber loop runs 99..1 and re-hits
+  //                         (the renumber loop then ran down from 99 and re-hit
   //                         its own output, collapsing 3->2->1->0) and renamed
   //                         every phase directory one lower.
   //   `phase remove -1e9`   spun that same loop ~1.2 billion times, each pass
@@ -425,6 +488,7 @@ module.exports = {
   collectDirsToRenumber,
   renamePhaseDir,
   renumberIntegerPhases,
+  removePhaseSection,
   updateRoadmapAfterRemoval,
   cmdPhaseRemove,
   updateStateAfterPhaseRemoval,

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

@@ -96,14 +96,20 @@ function resolvePhase(cwd, phaseNumber) {
 function extractPhaseGoal(cwd, phaseNumber) {
   const content = safeReadFile(path.join(planningPath(cwd), ROADMAP_FILE));
   if (!content) return { objective: null, success_criteria: [] };
-  const re = new RegExp('#{2,4}\\s*Phase\\s+' + escapeRegex(String(phaseNumber)) + ':\\s*([^\\n]+)', 'i');
+  // Padded or not: the number comes from the zero-padded phase directory ("02"),
+  // while PAN writes `### Phase 2:` headings, so the report found no goal.
+  const unpadded = String(phaseNumber).trim().replace(/^0+(?=\d)/, '');
+  const re = new RegExp('#{2,4}\\s*Phase\\s+0*' + escapeRegex(unpadded) + ':\\s*([^\\n]+)', 'i');
   const m = content.match(re);
   if (!m) return { objective: null, success_criteria: [] };
   const start = m.index;
   const rest = content.slice(start + 1);
   const nextH = rest.match(/\n#{2,4}\s+Phase\s+\d/i);
   const end = nextH ? start + 1 + nextH.index : content.length;
-  const section = content.slice(start, end);
+  let section = content.slice(start, end);
+  // A phase moved out by `roadmap compact` keeps a stub; its criteria are in the history.
+  const compacted = require('./roadmap-compact.cjs').compactedPhaseSection(cwd, phaseNumber, section);
+  if (compacted && compacted.section) section = compacted.section;
   const gm = section.match(/(?:\*\*Goal:\*\*|\*\*Goal\*\*:)\s*([^\n]+)/i);
   const objective = gm ? gm[1].trim() : null;
   const cm = section.match(/\*\*Success Criteria\*\*[^\n]*:\s*\n((?:\s*\d+\.\s*[^\n]+\n?)+)/i);