pan-wizard 3.32.0 → 3.34.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,
       });
     });
   }
@@ -1286,6 +1337,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 +1425,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 +1489,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 +1586,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-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);

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

@@ -4,10 +4,10 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, loadConfig, output, error, toPosix, isGitRepo, execGit } = require('./core.cjs');
+const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, loadConfig, output, error, toPosix, isGitRepo, isGitIgnored, execGit } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { writeStateMd, readStateSafe } = require('./state.cjs');
-const { enumerateRoadmapPhases } = require('./roadmap.cjs');
+const { enumerateRoadmapPhases, roadmapRequirementIds } = require('./roadmap.cjs');
 const { PHASES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, STATE_FILE, isPlanFile, isSummaryFile, getPlanId, PHASE_DIR_RE, ARCHIVE_DIR_RE } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, parsePhaseDir, fileAccessible, planningRel } = require('./utils.cjs');
 // Phase removal lives in phase-remove.cjs; re-exported below so consumers of
@@ -63,7 +63,7 @@ function cmdPhasesList(cwd, options, raw) {
     // If filtering by phase number
     if (phase) {
       const normalized = normalizePhaseName(phase);
-      const match = dirs.find(dir => dir.startsWith(normalized));
+      const match = dirs.find(dir => dir === normalized || dir.startsWith(normalized + '-'));
       if (!match) {
         output({ files: [], count: 0, phase_dir: null, error: 'Phase not found' }, raw, '');
         return;
@@ -200,7 +200,7 @@ function cmdFindPhase(cwd, phase, raw) {
     const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
     const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort((left, right) => comparePhaseNum(left, right));
 
-    const match = dirs.find(dir => dir.startsWith(normalized));
+    const match = dirs.find(dir => dir === normalized || dir.startsWith(normalized + '-'));
     if (!match) {
       output(notFound, raw, '');
       return;
@@ -239,7 +239,7 @@ function cmdFindPhase(cwd, phase, raw) {
  * @param {boolean} raw - If true, output raw value instead of JSON
  * @returns {void}
  */
-function cmdPhasePlanIndex(cwd, phase, raw) {
+function cmdPhasePlanIndex(cwd, phase, raw, opts = {}) {
   if (!phase) {
     error('phase required for phase-plan-index');
   }
@@ -253,7 +253,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
   try {
     const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
     const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort((left, right) => comparePhaseNum(left, right));
-    const match = dirs.find(dir => dir.startsWith(normalized));
+    const match = dirs.find(dir => dir === normalized || dir.startsWith(normalized + '-'));
     if (match) {
       phaseDir = path.join(phasesDir, match);
       phaseDirName = match;
@@ -280,7 +280,52 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
 
   const { plans, waves, incomplete, hasCheckpoints } = buildPlanIndex(phaseDir, planFiles, summaryFiles);
 
-  output({ phase: normalized, plans, waves, incomplete, has_checkpoints: hasCheckpoints }, raw);
+  const result = { phase: normalized, plans, waves, incomplete, has_checkpoints: hasCheckpoints };
+  // `--failed <ids>` (market-ideas M28): the plans that must not run after those
+  // failed, because a dependency, direct or transitive, is among them.
+  if (opts.failed) {
+    const failed = String(opts.failed).split(',').map((s) => s.trim()).filter(Boolean);
+    result.failed = failed;
+    result.blocked = blockedPlans(plans, failed);
+  }
+  output(result, raw);
+}
+
+/** Whether a `depends_on` entry names this plan: its full id ("03-02") or its plan number ("02", "2"). */
+function dependencyNames(dep, planId) {
+  const d = String(dep).trim();
+  if (d === planId) return true;
+  const own = planId.split('-').pop();
+  const strip = (s) => s.replace(/^0+(?=\d)/, '');
+  return /^\d+$/.test(d) && /^\d+$/.test(own) && strip(d) === strip(own);
+}
+
+/**
+ * The plans that must not run because a plan they depend on failed (market-ideas
+ * M28). Transitive: a plan waiting on a blocked plan is blocked too. Plans that
+ * already have a summary are done and never blocked.
+ * @param {Array<{id: string, depends_on: string[], has_summary: boolean}>} plans
+ * @param {string[]} failedIds
+ * @returns {Array<{id: string, blocked_by: string[]}>} in plan order; blocked_by names the failed plans
+ */
+function blockedPlans(plans, failedIds) {
+  const failed = new Set(failedIds);
+  const blockedBy = new Map(); // plan id → Set of failed ids behind it
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const p of plans) {
+      if (p.has_summary || failed.has(p.id)) continue;
+      const roots = blockedBy.get(p.id) || new Set();
+      const before = roots.size;
+      for (const dep of p.depends_on || []) {
+        for (const f of failed) if (dependencyNames(dep, f)) roots.add(f);
+        for (const [b, bRoots] of blockedBy) if (dependencyNames(dep, b)) for (const r of bRoots) roots.add(r);
+      }
+      if (roots.size > before) { blockedBy.set(p.id, roots); changed = true; }
+    }
+  }
+  return plans.filter((p) => blockedBy.has(p.id)).map((p) => ({ id: p.id, blocked_by: [...blockedBy.get(p.id)].sort() }));
 }
 
 /**
@@ -339,10 +384,14 @@ function buildPlanIndex(phaseDir, planFiles, summaryFiles) {
     const hasSummary = completedPlanIds.has(planId);
     if (!hasSummary) incomplete.push(planId);
 
+    const rawDeps = frontmatter.depends_on || frontmatter['depends-on'];
+    const dependsOn = (Array.isArray(rawDeps) ? rawDeps : (rawDeps ? [rawDeps] : [])).map(String).filter((d) => d.trim());
+
     plans.push({
       id: planId, wave, autonomous,
       objective,
       files_modified: filesModified,
+      depends_on: dependsOn,
       task_count: taskCount,
       has_summary: hasSummary,
     });
@@ -659,12 +708,10 @@ function markRequirementsCompleteForPhase(cwd, phaseNum, roadmapContent) {
   const reqPath = path.join(planningPath(cwd), REQUIREMENTS_FILE);
   try {
     const reqReadContent = fs.readFileSync(reqPath, 'utf-8');
-    const reqMatch = roadmapContent.match(
-      new RegExp(`Phase\\s+${escapeRegex(phaseNum)}[\\s\\S]*?(?:\\*\\*Requirements:\\*\\*|\\*\\*Requirements\\*\\*:)\\s*([^\\n]+)`, 'i')
-    );
-    if (!reqMatch) return;
-
-    const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(id => id.trim()).filter(Boolean);
+    // The phase's own requirements, matched padded or not (roadmapRequirementIds): a
+    // bare `Phase N … Requirements` search ticked phase 1's when completing phase 5.
+    const reqIds = roadmapRequirementIds(roadmapContent, phaseNum);
+    if (reqIds.length === 0) return;
     let reqContent = reqReadContent;
 
     for (const reqId of reqIds) {
@@ -851,8 +898,12 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
     result.roadmap_updated = false;
   }
 
-  // Auto-commit .planning/ metadata unless --no-commit or not a git repo
-  const noCommit = opts && opts.noCommit;
+  // Auto-commit .planning/ metadata 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 same rules `pan-tools commit` follows (this commit used to ignore both).
+  const noCommit = (opts && opts.noCommit)
+    || loadConfig(cwd).commit_docs === false
+    || isGitIgnored(cwd, planningRel());
   if (!noCommit && isGitRepo(cwd)) {
     const commitMsg = `docs(${normalized}): complete phase — ${phaseInfo.phase_name}`;
     execGit(cwd, ['add', planningRel() + '/']);
@@ -930,6 +981,7 @@ module.exports = {
   cmdPhaseNextDecimal,
   cmdFindPhase,
   cmdPhasePlanIndex,
+  blockedPlans,
   cmdPhaseAdd,
   cmdPhaseInsert,
   cmdPhaseRemove,

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

@@ -20,6 +20,7 @@ const {
   findPhaseInternal,
   getRoadmapPhaseInternal,
   toPosix,
+  toLf,
 } = require('./core.cjs');
 const {
   ROADMAP_FILE,
@@ -210,7 +211,8 @@ function buildPhaseDependencyGraph(cwd) {
     let files = [];
     try { files = fs.readdirSync(fullDir).filter(isPlanFile); } catch { continue; }
 
-    const phaseText = files.map(f => safeReadFile(path.join(fullDir, f)) || '').join('\n');
+    // LF, so the frontmatter match below also finds a CRLF plan's depends_on.
+    const phaseText = toLf(files.map(f => safeReadFile(path.join(fullDir, f)) || '').join('\n'));
 
     // Explicit via frontmatter. Parse depends_on as freeform string (either
     // inline `[phase:1, phase:2]`, or block-list). Extract all digit runs.

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

@@ -19,7 +19,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, safeReadFile, toPosix } = require('./core.cjs');
+const { output, error, safeReadFile, toPosix, escapeTableCell } = require('./core.cjs');
 const { planningPath } = require('./utils.cjs');
 const { publish } = require('./bus.cjs');
 const { findVerdictBlocks, validateVerdict } = require('./verdict.cjs');
@@ -235,7 +235,7 @@ function writeDeepReview(cwd, phaseNum, payload, opts) {
       const loc = f.file ? `\`${f.file}${f.line ? `:${f.line}` : ''}\`` : '—';
       // Neutralize markdown-table-breaking chars: escape pipes and flatten any
       // newlines so a finding description can't corrupt the table structure.
-      const desc = String(f.description).replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
+      const desc = escapeTableCell(f.description);
       lines.push(`| ${f.severity} | ${f.source} | ${f.category} | ${desc} | ${loc} |`);
     }
     lines.push('');