pan-wizard 3.32.0 → 3.34.0

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

@@ -0,0 +1,267 @@
+'use strict';
+
+/**
+ * roadmap compact — move shipped phases' detail out of roadmap.md (memory optimisation O3).
+ *
+ * roadmap.md only grows: every phase adds a detail section (goal, success criteria,
+ * plan list, notes) and nothing ever takes one away. A 54-phase field project's
+ * roadmap reached 476 KB, about 121k tokens. Phase agents now read a slice of it
+ * (`roadmap slice`, O2), but the roadmapper, the milestone workflows and people
+ * still read it whole. This bounds it the way `state compact` bounds state.md
+ * (ADR-0044).
+ *
+ * Safety, in order of importance:
+ *   1. Nothing is deleted. Sections are appended to roadmap-history.md FIRST, and
+ *      only then shortened in roadmap.md, so an interruption can only duplicate.
+ *   2. Only a shipped phase moves: its checklist line is ticked, it is not the
+ *      current phase in state.md, and it is not one of the `keep` most recently
+ *      shipped phases (default 2), which the next phase's planning may lean on.
+ *   3. A stub stays: the heading, the Goal, Depends on and Requirements lines and
+ *      any `<!-- model_tier: … -->` override, so goal lookups, the dependency goals
+ *      in a slice and `roadmap analyze` still read the phase. Readers that need the
+ *      rest (`roadmap get-phase`, `phase report`, a slice of that phase) find the
+ *      stub and read the section from roadmap-history.md.
+ *   4. A section already compacted is never compacted again.
+ *   5. Dry-run by default; `--apply` writes. Declines when nothing would shrink.
+ *   6. Parsed on LF and written back in the file's own line ending.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ROADMAP_FILE, STATE_FILE, CHARS_PER_TOKEN } = require('./constants.cjs');
+const { planningPath, planningRel } = require('./utils.cjs');
+const { output, safeReadFile, toLf, dominantEol, withEol } = require('./core.cjs');
+
+const ROADMAP_HISTORY_FILE = 'roadmap-history.md';
+const ROADMAP_COMPACT_KEEP = 2;
+/** The line a stub carries in place of the section's body. */
+const STUB_MARK = '_Shipped; the full section is in [roadmap-history.md]';
+
+const PHASE_HEADING_RE = /^(#{2,4})\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*(.+?)\s*$/;
+const KEPT_LINE_RE = /^(?:\*\*(Goal|Depends on|Requirements)(?::\*\*|\*\*:)|<!--\s*(model_tier):)/i;
+/** The line each compaction writes into the history ahead of the sections it moved. */
+const HISTORY_BATCH_MARK = `<!-- compacted from ${ROADMAP_FILE} on `;
+const unpad = (n) => String(n).replace(/^0+(?=\d)/, '');
+
+/**
+ * The phase detail sections of roadmap.md (LF text): each runs from its heading to
+ * the next phase heading or the next heading at its level or above, or to an HTML
+ * block boundary such as a milestone's `</details>`, so a trailing progress table
+ * never rides along. In roadmap-history.md a section also ends at the next
+ * compaction's batch line. Trailing blank lines stay outside the section.
+ */
+function phaseSections(lines) {
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(PHASE_HEADING_RE);
+    if (!m) continue;
+    const level = m[1].length;
+    let end = i + 1;
+    for (; end < lines.length; end++) {
+      const h = lines[end].match(/^(#{1,6})\s/);
+      if (h && (h[1].length <= level || PHASE_HEADING_RE.test(lines[end]))) break;
+      if (/^\s*<\/?details\b/i.test(lines[end])) break;
+      if (lines[end].startsWith(HISTORY_BATCH_MARK)) break;
+    }
+    let last = end;
+    while (last > i + 1 && !lines[last - 1].trim()) last--;
+    out.push({ start: i, end: last, number: unpad(m[2]), title: m[3], heading: lines[i] });
+  }
+  return out;
+}
+
+/** Phase numbers whose checklist line is ticked (`- [x] **Phase 3: …`). */
+function shippedPhases(lines) {
+  const s = new Set();
+  for (const l of lines) {
+    const m = l.match(/^\s*-\s*\[[xX]\]\s*\*{0,2}Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/);
+    if (m) s.add(unpad(m[1]));
+  }
+  return s;
+}
+
+/** The current phase named in state.md, or null. */
+function currentPhase(stateText) {
+  const t = toLf(stateText || '');
+  const m = t.match(/\*\*Current Phase:\*\*\s*([0-9]+[A-Z]?(?:\.[0-9]+)*)/i) || t.match(/^current_phase:\s*"?([0-9]+[A-Z]?(?:\.[0-9]+)*)/m);
+  return m ? unpad(m[1]) : null;
+}
+
+/** The stub left in roadmap.md for an archived section. */
+function stubFor(sectionLines, stamp) {
+  const kept = [];
+  const seen = new Set();
+  for (const l of sectionLines.slice(1)) {
+    const m = l.match(KEPT_LINE_RE);
+    const key = m && (m[1] || m[2]).toLowerCase();
+    if (m && !seen.has(key)) { seen.add(key); kept.push(l); }
+  }
+  return [sectionLines[0], ...kept, '', `${STUB_MARK}(${ROADMAP_HISTORY_FILE}) (compacted ${stamp})._`];
+}
+
+/**
+ * Pure: plan (and build) a compaction of roadmap.md text.
+ * @param {string} roadmap - roadmap.md content
+ * @param {{keep?: number, current?: string|null, now?: number}} [opts]
+ * @returns {{sections: Array, archivable: Array, content: string, archivedText: string, bytes_before: number, bytes_after: number}}
+ */
+function planRoadmapCompaction(roadmap, opts = {}) {
+  const keep = Number.isInteger(opts.keep) && opts.keep >= 0 ? opts.keep : ROADMAP_COMPACT_KEEP;
+  const eol = dominantEol(roadmap);
+  const lines = toLf(roadmap).split('\n');
+  const shipped = shippedPhases(lines);
+  const sections = phaseSections(lines);
+  const stamp = new Date(opts.now || Date.now()).toISOString().slice(0, 10);
+
+  const isStub = (s) => lines.slice(s.start, s.end).some(l => l.startsWith(STUB_MARK));
+  const candidates = sections.filter(s => shipped.has(s.number) && !isStub(s) && s.number !== opts.current);
+  const keepSet = new Set(candidates.slice(Math.max(0, candidates.length - keep)).map(s => s.start));
+
+  const verdicts = sections.map(s => {
+    let archive = false;
+    let reason;
+    if (isStub(s)) reason = 'already compacted';
+    else if (!shipped.has(s.number)) reason = 'not shipped — its checklist line is not ticked';
+    else if (s.number === opts.current) reason = 'the current phase in state.md';
+    else if (keepSet.has(s.start)) reason = `one of the ${keep} most recently shipped phases`;
+    else { archive = true; reason = 'shipped'; }
+    return { phase: s.number, title: s.title, bytes: lines.slice(s.start, s.end).join('\n').length, archive, reason, start: s.start, end: s.end };
+  });
+
+  const toArchive = verdicts.filter(v => v.archive);
+  const next = [];
+  let cursor = 0;
+  for (const v of toArchive) {
+    next.push(...lines.slice(cursor, v.start), ...stubFor(lines.slice(v.start, v.end), stamp));
+    cursor = v.end;
+  }
+  next.push(...lines.slice(cursor));
+  const content = withEol(next.join('\n'), eol);
+  const archivedText = toArchive.map(v => lines.slice(v.start, v.end).join('\n')).join('\n\n');
+
+  let archivable = toArchive.map(({ start, end, ...rest }) => rest);
+  let after = content.length;
+  // A stub on a tiny section can cost more than the section: decline rather than
+  // churn roadmap.md to make it bigger.
+  if (archivable.length && after >= roadmap.length) {
+    for (const v of verdicts) if (v.archive) { v.archive = false; v.reason = 'archiving it would not shrink roadmap.md'; }
+    archivable = [];
+    after = roadmap.length;
+  }
+  return {
+    sections: verdicts.map(({ start, end, ...rest }) => rest),
+    archivable,
+    content: archivable.length ? content : roadmap,
+    archivedText: archivable.length ? archivedText : '',
+    bytes_before: roadmap.length,
+    bytes_after: after,
+    stamp,
+  };
+}
+
+/**
+ * Plan or apply `roadmap compact` for a project. Archive is written BEFORE
+ * roadmap.md is rewritten, so an interruption can only ever leave a duplicate.
+ * @param {string} cwd
+ * @param {{apply?: boolean, keep?: number, now?: number}} [opts]
+ */
+function compactRoadmap(cwd, opts = {}) {
+  const roadmapPath = planningPath(cwd, ROADMAP_FILE);
+  const roadmap = safeReadFile(roadmapPath);
+  if (roadmap == null) return { found: false, path: planningRel(ROADMAP_FILE), archivable: [], applied: false };
+  const current = currentPhase(safeReadFile(planningPath(cwd, STATE_FILE)));
+  const plan = planRoadmapCompaction(roadmap, { keep: opts.keep, current, now: opts.now });
+  const result = {
+    found: true,
+    path: planningRel(ROADMAP_FILE),
+    history_path: planningRel(ROADMAP_HISTORY_FILE),
+    keep: Number.isInteger(opts.keep) && opts.keep >= 0 ? opts.keep : ROADMAP_COMPACT_KEEP,
+    current_phase: current,
+    sections: plan.sections,
+    archivable: plan.archivable,
+    bytes_before: plan.bytes_before,
+    bytes_after: plan.bytes_after,
+    tokens_before: Math.ceil(plan.bytes_before / CHARS_PER_TOKEN),
+    tokens_after: Math.ceil(plan.bytes_after / CHARS_PER_TOKEN),
+    applied: false,
+    dry_run: !opts.apply,
+  };
+  if (!opts.apply || !plan.archivable.length) return result;
+
+  // 1. History first. The preamble is created with an exclusive open (no
+  //    check-then-write race); appends follow the history file's own line ending.
+  const historyPath = planningPath(cwd, ROADMAP_HISTORY_FILE);
+  const preamble = `# Roadmap history\n\nPhase sections compacted out of ${ROADMAP_FILE} by \`pan-tools roadmap compact\`.\n`
+    + 'They are kept verbatim; roadmap.md keeps a stub with each heading, goal, dependencies and requirements.\n';
+  try {
+    fs.writeFileSync(historyPath, preamble, { flag: 'wx', encoding: 'utf-8' });
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+  }
+  const histEol = dominantEol(safeReadFile(historyPath) || '');
+  fs.appendFileSync(historyPath, withEol(`\n\n${HISTORY_BATCH_MARK}${plan.stamp} -->\n${plan.archivedText}\n`, histEol), 'utf-8');
+
+  // 2. Only now shorten roadmap.md.
+  fs.writeFileSync(roadmapPath, plan.content, 'utf-8');
+  return { ...result, applied: true, dry_run: false, archived: plan.archivable.map(v => v.phase) };
+}
+
+/** True when a phase section (LF or CRLF text) is a compaction stub. */
+function isCompactedSection(section) {
+  return String(section || '').split('\n').some(l => l.trimStart().startsWith(STUB_MARK));
+}
+
+/**
+ * A compacted phase's full section from roadmap-history.md text, or null. The last
+ * copy wins: each compaction appends.
+ */
+function archivedPhaseSection(historyText, phase) {
+  if (!historyText) return null;
+  const want = unpad(phase);
+  const lines = toLf(historyText).split('\n');
+  let hit = null;
+  for (const s of phaseSections(lines)) if (s.number === want) hit = s;
+  return hit ? lines.slice(hit.start, hit.end).join('\n') : null;
+}
+
+/**
+ * For a reader that found a stub where a phase's section should be: the full
+ * section from roadmap-history.md. Returns null when `section` is not a stub, so
+ * the history is read only for a compacted phase.
+ * @returns {{section: string|null, compacted: true, history_path: string, history_found: boolean}|null}
+ */
+function compactedPhaseSection(cwd, phase, section) {
+  if (!isCompactedSection(section)) return null;
+  const full = archivedPhaseSection(safeReadFile(planningPath(cwd, ROADMAP_HISTORY_FILE)), phase);
+  return { section: full, compacted: true, history_path: planningRel(ROADMAP_HISTORY_FILE), history_found: full != null };
+}
+
+/** How many sections a compaction would archive now — hygiene offers the fix only then. */
+function roadmapCompactionAvailable(cwd) {
+  try { return compactRoadmap(cwd).archivable.length; } catch { return 0; }
+}
+
+/** `roadmap compact [--apply] [--keep N]` */
+function cmdRoadmapCompact(cwd, opts, raw) {
+  const r = compactRoadmap(cwd, opts);
+  if (!r.found) { output(r, raw, 'roadmap.md not found'); return; }
+  const saved = Math.max(0, r.tokens_before - r.tokens_after);
+  const summary = r.applied
+    ? `archived ${r.archived.length} phase section(s) to ${r.history_path}; roadmap.md ~${saved} tokens smaller`
+    : r.archivable.length
+      ? `would archive ${r.archivable.length} phase section(s) (phases ${r.archivable.map(v => v.phase).join(', ')}); roadmap.md ~${saved} tokens smaller — rerun with --apply`
+      : 'nothing to compact — no shipped phase past the most recent ones';
+  output(r, raw, summary);
+}
+
+module.exports = {
+  ROADMAP_HISTORY_FILE,
+  ROADMAP_COMPACT_KEEP,
+  isCompactedSection,
+  archivedPhaseSection,
+  compactedPhaseSection,
+  planRoadmapCompaction,
+  compactRoadmap,
+  roadmapCompactionAvailable,
+  cmdRoadmapCompact,
+};

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

@@ -4,9 +4,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const { PHASES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, isPlanFile, isSummaryFile, isContextFile, isResearchFile, PHASE_HEADER_RE, getPlanId, getSummaryId } = require('./constants.cjs');
-const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, classifyPhaseStatus } = require('./utils.cjs');
-const { escapeRegex, normalizePhaseName, output, error, findPhaseInternal } = require('./core.cjs');
+const { PHASES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, ROADMAP_SLICE_SUFFIX, isPlanFile, isSummaryFile, isContextFile, isResearchFile, PHASE_HEADER_RE, getPlanId, getSummaryId } = require('./constants.cjs');
+const { planningPath, planningRel, phasesPath, filterPlanFiles, filterSummaryFiles, classifyPhaseStatus } = require('./utils.cjs');
+const { escapeRegex, normalizePhaseName, output, error, findPhaseInternal, safeReadFile, toLf, dominantEol, withEol } = require('./core.cjs');
 
 /**
  * Extract a single phase section from roadmap.md including goal and success criteria.
@@ -21,8 +21,8 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
   try {
     const content = fs.readFileSync(roadmapPath, 'utf-8');
 
-    // Escape special regex chars in phase number, handle decimal
-    const escapedPhase = escapeRegex(phaseNum);
+    // Padded or not: `init` hands workflows "05", roadmaps write "Phase 5:".
+    const escapedPhase = phaseNumRe(phaseNum);
 
     // Match "## Phase X:", "### Phase X:", or "#### Phase X:" with optional name
     const phasePattern = new RegExp(
@@ -65,7 +65,12 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
       ? headerIndex + nextHeaderMatch.index
       : content.length;
 
-    const section = content.slice(headerIndex, sectionEnd).trim();
+    let section = content.slice(headerIndex, sectionEnd).trim();
+
+    // A phase moved out by `roadmap compact` leaves a stub here; its success
+    // criteria and the rest of its section are in roadmap-history.md.
+    const compacted = require('./roadmap-compact.cjs').compactedPhaseSection(cwd, phaseNum, section);
+    if (compacted && compacted.section) section = compacted.section;
 
     // Extract goal if present
     const goalMatch = section.match(/(?:\*\*Goal:\*\*|\*\*Goal\*\*:)\s*([^\n]+)/i);
@@ -85,6 +90,7 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
         goal,
         success_criteria,
         section,
+        ...(compacted ? { compacted: true, history_path: compacted.history_path, history_found: compacted.history_found } : {}),
       },
       raw,
       section
@@ -346,7 +352,7 @@ const isSeparator = (line) => /^\s*\|(?:\s*:?-{3,}:?\s*\|)+\s*$/.test(line);
 function updateProgressTableRow(content, phaseNum, values) {
   const eol = content.includes('\r\n') ? '\r\n' : '\n';
   const lines = content.split(/\r?\n/);
-  const phaseRe = new RegExp(`^(?:phase\\s+)?${escapeRegex(String(phaseNum))}\\.?(?=\\s|:|$)`, 'i');
+  const phaseRe = new RegExp(`^(?:phase\\s+)?${phaseNumRe(phaseNum)}\\.?(?=\\s|:|$)`, 'i');
   let reason = null;
   for (let i = 0; i + 1 < lines.length; i++) {
     if (!isTableLine(lines[i]) || !isSeparator(lines[i + 1])) continue;
@@ -377,7 +383,7 @@ function updateProgressTableRow(content, phaseNum, values) {
 /** Rewrite `**Plans:**` inside the phase's own section only. Pure. */
 function updatePhasePlansLine(content, phaseNum, text) {
   const lines = content.split(/(?<=\n)/);
-  const headRe = new RegExp(`^(#{2,4})\\s*Phase\\s+${escapeRegex(String(phaseNum))}(?=[\\s:.]|$)`, 'i');
+  const headRe = new RegExp(`^(#{2,4})\\s*Phase\\s+${phaseNumRe(phaseNum)}(?=[\\s:.]|$)`, 'i');
   const start = lines.findIndex((l) => headRe.test(l));
   if (start < 0) return { content, updated: false };
   const level = lines[start].match(headRe)[1].length;
@@ -426,7 +432,9 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     output({ updated: false, reason: 'roadmap.md not found', error: 'roadmap_not_found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
     return;
   }
-  const phaseEscaped = escapeRegex(phaseNum);
+  // Padded or not: the executor passes init's "05" for a `Phase 5` roadmap, and
+  // every lookup below used to miss it while the result still said `updated: true`.
+  const phaseEscaped = phaseNumRe(phaseNum);
 
   // Progress table row: the Plans, Status and Completed cells, found by header.
   const table = updateProgressTableRow(roadmapContent, phaseNum, {
@@ -530,14 +538,240 @@ function syncRequirementCheckboxes(cwd, requirementIds) {
   return { updated: checked > 0, checked, total: requirementIds.length };
 }
 
+// ─── Phase slice (memory optimisation O2) ────────────────────────────────────
+//
+// What work on ONE phase needs from roadmap.md and requirements.md: a one-line
+// index of every phase, this phase's section, the goals of the phases it depends
+// on, and the requirement lines it names. The planner, the plan checker, the
+// researcher, the executors (through the plan's <context>) and the verifier read
+// this instead of the whole files. Measured on the field installs (2026-10-04):
+// 89–98% smaller; a 54-phase project went from ~146k tokens to ~3k, and those
+// whole files had been re-read on every turn of every spawn that listed them.
+
+/** Phase numbers compare without zero padding: "03" and "3" are one phase. */
+const unpadPhase = (n) => String(n).trim().replace(/^0+(?=\d)/, '');
+
+/** A phase number as a regex source matching it padded or not ("05" finds `Phase 5:` and `Phase 05:`). */
+const phaseNumRe = (n) => `0*${escapeRegex(unpadPhase(n))}`;
+
+/**
+ * Requirement ids on a phase section's `**Requirements**:` line. Taken by shape,
+ * not by splitting on commas: field roadmaps write prose there ("none of its own;
+ * pulled forward from Phase 45 (`CI-01`)…", "seeding (replace …), TEST-01 (…)").
+ * An id is a `CAT-01`-style token anywhere on the line, or a comma-separated item
+ * that is a single token carrying a digit (`R1`, `REQ001`).
+ */
+function phaseRequirementIds(section) {
+  const m = String(section || '').match(/^\*\*Requirements\*\*:[^\S\n]*([^\n]*)$/m)
+    || String(section || '').match(/^\*\*Requirements:\*\*[^\S\n]*([^\n]*)$/m);
+  if (!m) return [];
+  const line = m[1].replace(/[[\]`]/g, ' ');
+  const shaped = line.match(/\b[A-Z][A-Z0-9]*(?:-[A-Z][A-Z0-9]*)*-\d+[A-Za-z]?\b/g) || [];
+  const tokens = line.split(',').map(s => s.trim()).filter(s => /^[A-Za-z][A-Za-z0-9._-]*\d[A-Za-z0-9._-]*$/.test(s));
+  return [...new Set([...shaped, ...tokens])];
+}
+
+/** Phase numbers on a section's `**Depends on**:` line ("Phase 2, Phase 2.1" → ['2', '2.1']). */
+function phaseDependencies(section) {
+  const m = String(section || '').match(/(?:\*\*Depends on:\*\*|\*\*Depends on\*\*:)\s*([^\n]+)/i);
+  if (!m) return [];
+  return [...new Set([...m[1].matchAll(/\bPhase\s+(\d+[A-Z]?(?:\.\d+)*)/gi)].map(x => unpadPhase(x[1])))];
+}
+
+/** A phase's section in roadmap.md content, or null. Mirrors getRoadmapPhaseInternal. */
+function roadmapPhaseSection(content, phaseNum) {
+  const escaped = escapeRegex(unpadPhase(phaseNum));
+  const header = content.match(new RegExp(`#{2,4}\\s*Phase\\s+0*${escaped}:\\s*([^\\n]+)`, 'i'));
+  if (!header) return null;
+  const rest = content.slice(header.index);
+  const next = rest.match(/\n#{2,4}\s+Phase\s+\d/i);
+  const section = content.slice(header.index, next ? header.index + next.index : content.length).trim();
+  return { name: header[1].trim(), section };
+}
+
+/**
+ * The requirement ids roadmap.md names for one phase: from its own `### Phase N:`
+ * section, else from a `**Requirements:**` line under its checklist entry, before
+ * the next "Phase <n>" (the layout older roadmaps use). `phase complete` and
+ * `validate health --repair` read them here: their own search took the first
+ * Requirements line after the first "Phase N" anywhere, which on the template's
+ * layout (checklist above the sections) was phase 1's, and matched "05" to nothing.
+ */
+function roadmapRequirementIds(content, phaseNum) {
+  const text = String(content || '');
+  const sec = roadmapPhaseSection(text, phaseNum);
+  if (sec) return phaseRequirementIds(sec.section);
+  const start = text.search(new RegExp(`Phase\\s+${phaseNumRe(phaseNum)}(?![\\d.])`, 'i'));
+  if (start < 0) return [];
+  const rest = text.slice(start);
+  const next = rest.slice(1).search(/Phase\s+\d/i);
+  const span = next < 0 ? rest : rest.slice(0, next + 1);
+  return phaseRequirementIds(span.replace(/^[ \t]+(?=\*\*Requirements)/gm, ''));
+}
+
+/** Lines of requirements.md that name one of `ids`, each with its indented continuation. */
+function requirementLines(requirements, ids) {
+  const lines = String(requirements || '').split('\n');
+  const pick = new Set();
+  const found = new Set();
+  const patterns = ids.map(id => ({ id, re: new RegExp(`(^|[^A-Za-z0-9_-])${escapeRegex(id)}(?![A-Za-z0-9_-])`) }));
+  lines.forEach((line, i) => {
+    const hits = patterns.filter(p => p.re.test(line));
+    if (!hits.length) return;
+    for (const h of hits) found.add(h.id);
+    pick.add(i);
+    // A list item keeps its detail: the lines after it indented deeper than it.
+    if (/^\s*[-*]\s/.test(line)) {
+      const indent = line.length - line.trimStart().length;
+      for (let j = i + 1; j < lines.length; j++) {
+        const l = lines[j];
+        if (!l.trim() || l.length - l.trimStart().length <= indent) break;
+        pick.add(j);
+      }
+    }
+  });
+  // A picked table row keeps its table's header and separator, so it still reads as a table.
+  for (const i of [...pick]) {
+    if (!/^\s*\|/.test(lines[i])) continue;
+    let top = i;
+    while (top > 0 && /^\s*\|/.test(lines[top - 1])) top--;
+    if (top < i) pick.add(top);
+    if (top + 1 < i && /^\s*\|[\s:|-]+\|\s*$/.test(lines[top + 1])) pick.add(top + 1);
+  }
+  return { lines: [...pick].sort((a, b) => a - b).map(i => lines[i]), missing: ids.filter(id => !found.has(id)) };
+}
+
+/**
+ * Pure: the slice of `roadmap` and `requirements` for one phase.
+ * `history` (roadmap-history.md text, or a function returning it) is consulted only
+ * when the phase's section is a `roadmap compact` stub, to put its full section back.
+ * @param {{roadmap: string, requirements: string|null, phase: string, planningRel?: string,
+ *   history?: string|null|(() => string|null)}} args
+ * @returns {{found: boolean, phase_number: string, phase_name?: string, content?: string,
+ *   requirement_ids?: string[], missing_requirement_ids?: string[], depends_on?: string[],
+ *   tokens?: number, whole_tokens?: number}}
+ */
+function buildRoadmapSlice({ roadmap, requirements, phase, planningRel = '.planning', history = null }) {
+  const rm = toLf(roadmap);
+  const req = requirements == null ? null : toLf(requirements);
+  const target = roadmapPhaseSection(rm, phase);
+  if (!target) return { found: false, phase_number: String(phase) };
+  const { isCompactedSection, archivedPhaseSection } = require('./roadmap-compact.cjs');
+  if (isCompactedSection(target.section)) {
+    const full = archivedPhaseSection(typeof history === 'function' ? history() : history, phase);
+    if (full) target.section = full;
+  }
+
+  const num = unpadPhase(phase);
+  const phases = enumerateRoadmapPhases(rm);
+  // Any one-character box: roadmaps mark work in flight `[~]` or `[-]` as well as `[ ]` / `[x]`.
+  const checklist = rm.split('\n').filter(l => /^\s*-\s*\[[^\]]\]\s*\*\*Phase\s+\d/i.test(l)).map(l => l.trim());
+  const thisLine = new RegExp(`\\*\\*Phase\\s+0*${escapeRegex(num)}\\s*:`, 'i');
+  const index = (checklist.length ? checklist : phases.map(p => `- Phase ${p.number}: ${p.name}`))
+    .map(l => (thisLine.test(l) || new RegExp(`^- Phase 0*${escapeRegex(num)}:`).test(l) ? `${l}  ← this phase` : l));
+
+  const deps = phaseDependencies(target.section);
+  const depLines = deps.map(d => {
+    const p = phases.find(x => unpadPhase(x.number) === d);
+    return p ? `- **Phase ${p.number}: ${p.name}** — ${p.goal || 'no goal line in roadmap.md'}` : `- **Phase ${d}** — not found in roadmap.md`;
+  });
+
+  const ids = phaseRequirementIds(target.section);
+  let reqBody;
+  let missing = [];
+  if (req == null) reqBody = `_There is no \`${planningRel}/requirements.md\`._`;
+  else if (!ids.length) reqBody = '_The roadmap names no requirement ids for this phase._';
+  else {
+    const r = requirementLines(req, ids);
+    missing = r.missing;
+    reqBody = (r.lines.length ? r.lines.join('\n') : '') + (missing.length ? `${r.lines.length ? '\n\n' : ''}_Not found in requirements.md: ${missing.join(', ')}._` : '');
+  }
+
+  const content = [
+    `# Roadmap slice — Phase ${num}: ${target.name}`,
+    '',
+    `Generated by \`pan-tools roadmap slice ${num}\` from \`${planningRel}/roadmap.md\` and \`${planningRel}/requirements.md\`. It holds what work on this phase needs from those files; read the whole files only for something it leaves out.`,
+    '',
+    '## Every phase',
+    '',
+    ...index,
+    '',
+    '## This phase',
+    '',
+    target.section,
+    '',
+    '## Phases it depends on',
+    '',
+    ...(depLines.length ? depLines : ['_None._']),
+    '',
+    '## Its requirements',
+    '',
+    reqBody,
+    '',
+  ].join('\n');
+
+  return {
+    found: true,
+    phase_number: num,
+    phase_name: target.name,
+    requirement_ids: ids,
+    missing_requirement_ids: missing,
+    depends_on: deps,
+    content,
+    tokens: Math.ceil(content.length / 4),
+    whole_tokens: Math.ceil((rm.length + (req || '').length) / 4),
+  };
+}
+
+/**
+ * `roadmap slice <phase> [--write]` — the phase's slice; `--write` puts it at
+ * `<phase dir>/<NN>-roadmap-slice.md` (the path the plan template's <context> names)
+ * and prints the path and sizes.
+ */
+function cmdRoadmapSlice(cwd, phase, opts, raw) {
+  const roadmap = safeReadFile(path.join(planningPath(cwd), ROADMAP_FILE));
+  if (roadmap == null) { output({ found: false, error: 'roadmap.md not found' }, raw, ''); return; }
+  const requirements = safeReadFile(path.join(planningPath(cwd), REQUIREMENTS_FILE));
+  const history = () => safeReadFile(path.join(planningPath(cwd), require('./roadmap-compact.cjs').ROADMAP_HISTORY_FILE));
+  const slice = buildRoadmapSlice({ roadmap, requirements, phase, planningRel: planningRel(), history });
+  if (!slice.found) { output(slice, raw, ''); return; }
+  const summary = {
+    found: true, phase_number: slice.phase_number, phase_name: slice.phase_name,
+    requirement_ids: slice.requirement_ids, missing_requirement_ids: slice.missing_requirement_ids,
+    depends_on: slice.depends_on, tokens: slice.tokens, whole_tokens: slice.whole_tokens,
+    smaller_pct: slice.whole_tokens ? Math.round(100 * (1 - slice.tokens / slice.whole_tokens)) : 0,
+  };
+  if (!opts || !opts.write) { output({ ...summary, content: slice.content }, raw, slice.content); return; }
+
+  const dir = findPhaseInternal(cwd, phase);
+  if (!dir || !dir.directory) {
+    output({ ...summary, written: false, reason: 'no phase directory yet — create it first, or read the whole files' }, raw, '');
+    return;
+  }
+  const rel = `${dir.directory}/${normalizePhaseName(phase)}${ROADMAP_SLICE_SUFFIX}`;
+  const abs = path.join(cwd, rel);
+  // Same bytes in the file's own line ending, and no write when nothing changed,
+  // so regenerating at each workflow start leaves git alone.
+  const existing = safeReadFile(abs);
+  const next = withEol(slice.content, existing == null ? '\n' : dominantEol(existing));
+  if (existing !== next) fs.writeFileSync(abs, next, 'utf-8');
+  output({ ...summary, written: true, changed: existing !== next, path: rel }, raw, rel);
+}
+
 module.exports = {
   cmdRoadmapGetPhase,
   cmdRoadmapAnalyze,
   cmdRoadmapUpdatePlanProgress,
+  cmdRoadmapSlice,
   syncRequirementCheckboxes,
   // Exported for testability
   enumerateRoadmapPhases,
   enrichPhaseWithDiskStatus,
   extractMilestones,
   computeRoadmapStats,
+  buildRoadmapSlice,
+  roadmapRequirementIds,
+  phaseRequirementIds,
+  phaseDependencies,
+  ROADMAP_SLICE_SUFFIX,
 };

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

@@ -38,7 +38,8 @@ const { getExperimentManifest, PAN_EXPERIMENTS_ROOT_DEFAULT } = require('./exper
  * shell: 'win32' — they default to direct spawn, which suits test mocks like
  * `node -e '...'` that are resolvable directly. P-102 fix (v3.7.1).
  *
- * GitHub Copilot CLI has no documented headless prompt mode, so it's null.
+ * GitHub Copilot CLI is null: no adapter is written yet, although `copilot -p`
+ * runs a prompt headless (the PAN Harness drives it that way).
  */
 // P-1302 fix (v3.7.2): autonomous claude/gemini runs default to non-interactive
 // permissions. Without these flags, the CLI prompts for tool approval, which

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

@@ -26,7 +26,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error } = require('./core.cjs');
+const { output, error, dominantEol, withEol } = require('./core.cjs');
 const {
   STATE_FILE,
   STATE_HISTORY_FILE,
@@ -210,9 +210,13 @@ function planStateCompaction(cwd, opts = {}) {
   // Build the post-compaction text for real rather than estimating it. An
   // estimate that ignores pointer overhead can claim a saving on a file where
   // the pointers cost more than the sections they replace — a dry-run that
-  // overstates its own benefit is worse than no dry-run.
+  // overstates its own benefit is worse than no dry-run. The rebuild comes back
+  // LF and writeStateMd restores the file's own ending on disk, so measure it in
+  // that ending too: on a CRLF file the LF rebuild otherwise "saved" a byte per
+  // line, and a compaction that archived nothing still reported tokens saved.
   const stamp = new Date(now).toISOString().slice(0, 10);
-  let bytesAfter = rebuildState(content, new Set(archivable.map(v => v.title)), stamp).length;
+  const eol = dominantEol(content);
+  let bytesAfter = withEol(rebuildState(content, new Set(archivable.map(v => v.title)), stamp), eol).length;
 
   // The point of compaction is a smaller re-read on every agent call. On a file
   // whose history sections are tiny, the pointers left behind cost more than the
@@ -291,14 +295,15 @@ function compactState(cwd, opts = {}) {
   const { writeStateMd } = require('./state.cjs');
   writeStateMd(statePath, next, cwd);
 
+  const onDisk = withEol(next, dominantEol(content));
   return {
     ...plan,
     applied: true,
     dry_run: false,
     archived: plan.archivable.map(v => v.title),
-    bytes_after: next.length,
-    tokens_after: Math.ceil(next.length / CHARS_PER_TOKEN),
-    tokens_saved_per_call: Math.max(0, Math.ceil((plan.bytes_before - next.length) / CHARS_PER_TOKEN)),
+    bytes_after: onDisk.length,
+    tokens_after: Math.ceil(onDisk.length / CHARS_PER_TOKEN),
+    tokens_saved_per_call: Math.max(0, Math.ceil((plan.bytes_before - onDisk.length) / CHARS_PER_TOKEN)),
   };
 }