pan-wizard 3.33.0 → 3.35.0

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;
@@ -253,7 +253,7 @@ function cmdPhasePlanIndex(cwd, phase, raw, opts = {}) {
   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;
@@ -708,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) {
@@ -825,6 +823,26 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
     error(`Phase ${phaseNum} not found`);
   }
 
+  // The phase gate (V1). In `enforce` mode a refusal stops here unless --force
+  // --reason, which records a decision; in `warn` mode the reasons travel with the
+  // result. A --force without a reason is refused in either mode.
+  const { phaseGate, recordGateOverride } = require('./phase-gate.cjs');
+  const force = !!(opts && opts.force);
+  const forceReason = opts && typeof opts.reason === 'string' ? opts.reason.trim() : '';
+  if (force && !forceReason) {
+    output({ error: 'reason_required', reason: 'phase complete --force needs --reason "<why the gate is being overridden>"' }, raw);
+    return;
+  }
+  const gate = phaseGate(cwd, phaseNum);
+  let gateOverride = null;
+  if (!gate.error && !gate.ok) {
+    if (gate.mode === 'enforce' && !force) {
+      output({ error: 'phase_gate_refused', reason: gate.reasons.map((r) => `${r.code}: ${r.detail}`).join(' | '), gate }, raw);
+      return;
+    }
+    if (force) gateOverride = recordGateOverride(cwd, gate, forceReason);
+  }
+
   const planCount = phaseInfo.plans.length;
   const summaryCount = phaseInfo.summaries.length;
 
@@ -888,6 +906,8 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
     date: today,
     roadmap_updated: fileAccessible(roadmapPath),
     state_updated: fileAccessible(statePath),
+    gate: gate.error ? { error: gate.error } : { ok: gate.ok, mode: gate.mode, reasons: gate.reasons, not_checked: gate.not_checked },
+    ...(gateOverride ? { gate_override: gateOverride } : {}),
   };
   if (roadmapResult && roadmapResult.requirements_warning) {
     result.requirements_warning = roadmapResult.requirements_warning;
@@ -900,8 +920,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() + '/']);
@@ -980,6 +1004,8 @@ module.exports = {
   cmdFindPhase,
   cmdPhasePlanIndex,
   blockedPlans,
+  buildPlanIndex,
+  dependencyNames,
   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,
@@ -160,7 +161,8 @@ function buildPhasePreview(cwd, phaseNum) {
  * Produce a dependency graph + mermaid source + parallel-batch recommendation.
  *
  * Dependency detection:
- *  - plan frontmatter `depends_on: [phase:NN, phase:MM]` (explicit)
+ *  - the roadmap's `**Depends on:** Phase N` line (explicit)
+ *  - plan frontmatter `depends_on: [phase:NN, phase:MM]` (explicit; bare plan ids are not phases)
  *  - mentions of prior phases in plan text (heuristic, flagged as "hidden")
  *
  * @param {string} cwd - Project root
@@ -194,6 +196,13 @@ function buildPhaseDependencyGraph(cwd) {
     }
   }
 
+  // Graph keys are the roadmap checklist's numbers; a dependency written "01" or
+  // "Phase 1" resolves to the key whose unpadded form matches.
+  const unpad = (n) => String(n).trim().replace(/^0+(?=\d)/, '');
+  const keyByUnpadded = new Map(phaseList.map(p => [unpad(p.num), p.num]));
+  const keyOf = (n) => keyByUnpadded.get(unpad(n)) || unpad(n);
+  const { phaseDependencies } = require('./roadmap.cjs');
+
   for (const p of phaseList) {
     graph[p.num] = {
       num: p.num,
@@ -203,6 +212,15 @@ function buildPhaseDependencyGraph(cwd) {
       hidden_deps: [],
     };
 
+    const addExplicit = (d) => {
+      const key = keyOf(d);
+      if (key !== keyOf(p.num) && !graph[p.num].explicit_deps.includes(key)) graph[p.num].explicit_deps.push(key);
+    };
+
+    // Explicit via the roadmap: the phase's `**Depends on:** Phase N` line.
+    const roadmapPhase = getRoadmapPhaseInternal(cwd, p.num);
+    for (const d of phaseDependencies(roadmapPhase && roadmapPhase.section)) addExplicit(d);
+
     // Read plan files for depends_on frontmatter + prior-phase mentions.
     const dir = phaseDirs[p.num];
     if (!dir) continue;
@@ -210,35 +228,19 @@ 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');
-
-    // Explicit via frontmatter. Parse depends_on as freeform string (either
-    // inline `[phase:1, phase:2]`, or block-list). Extract all digit runs.
-    const fmMatch = phaseText.match(/^---\n([\s\S]*?)\n---/);
-    if (fmMatch) {
-      const depsLine = fmMatch[1].match(/^depends_on:\s*(.+)$/m);
-      if (depsLine) {
-        const digitRuns = depsLine[1].match(/\d+(?:\.\d+)?/g) || [];
-        for (const d of digitRuns) {
-          if (d !== p.num && !graph[p.num].explicit_deps.includes(d)) {
-            graph[p.num].explicit_deps.push(d);
-          }
-        }
-      }
-      // Also support block-list form:
-      //   depends_on:
-      //     - phase:1
-      //     - phase:2
-      const blockMatch = fmMatch[1].match(/^depends_on:\s*\n((?:\s*-\s*.+\n?)*)/m);
-      if (blockMatch && !depsLine) {
-        const items = blockMatch[1].match(/^\s*-\s*(.+)$/gm) || [];
-        for (const item of items) {
-          const d = item.match(/\d+(?:\.\d+)?/);
-          if (d && d[0] !== p.num && !graph[p.num].explicit_deps.includes(d[0])) {
-            graph[p.num].explicit_deps.push(d[0]);
-          }
-        }
-      }
+    // LF, so the frontmatter match below also finds a CRLF plan's depends_on.
+    const planTexts = files.map(f => toLf(safeReadFile(path.join(fullDir, f)) || ''));
+    const phaseText = planTexts.join('\n');
+
+    // Explicit via each plan's frontmatter. A plan's `depends_on` names plan ids
+    // inside its own phase (`["01"]`), so only `phase:N` entries are phase
+    // dependencies, inline (`[phase:1, phase:2]`) or as a block list.
+    for (const text of planTexts) {
+      const fmMatch = text.match(/^---\n([\s\S]*?)\n---/);
+      if (!fmMatch) continue;
+      const depsBlock = fmMatch[1].match(/^depends_on:[^\n]*(?:\n[ \t]*-[^\n]*)*/m);
+      if (!depsBlock) continue;
+      for (const m of depsBlock[0].matchAll(/\bphase[:\s]*(\d+(?:\.\d+)?)/gi)) addExplicit(m[1]);
     }
 
     // Hidden via mentions: "phase N", "from phase N", "as in phase N".
@@ -246,7 +248,8 @@ function buildPhaseDependencyGraph(cwd) {
     let mm;
     const mentions = new Set();
     while ((mm = mentionRe.exec(phaseText)) !== null) {
-      if (mm[1] !== p.num) mentions.add(mm[1]);
+      const k = keyOf(mm[1]);
+      if (k !== keyOf(p.num)) mentions.add(k);
     }
     graph[p.num].hidden_deps = [...mentions].filter(d => !graph[p.num].explicit_deps.includes(d));
   }

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,
+};