pan-wizard 3.26.0 → 3.27.0

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

@@ -0,0 +1,339 @@
+/**
+ * state compact — move closed history out of state.md.
+ *
+ * state.md sits in CACHEABLE_CONTEXT_FILES, so it is re-read into EVERY agent
+ * call. Its section writers only ever append (`sectionBody.trimEnd() + entry`),
+ * so the file can only grow: a field project reached 54 KB, of which 30 KB was
+ * a June session log, a resolved milestone audit, and three phase closures —
+ * roughly 7k tokens of settled history re-read on every call for months. Prompt
+ * cache reads outweigh generated tokens by about two orders of magnitude in a
+ * PAN project, which makes this file the single largest recurring cost.
+ *
+ * The rule this module encodes: PAN already knows how to bound its other
+ * append-only store (`memory compact`); state.md gets the same treatment.
+ *
+ * Safety, in order of importance:
+ *   1. Nothing is ever deleted. Sections are appended to state-history.md
+ *      FIRST, and only then removed from state.md.
+ *   2. `state get <section>` can read ANY heading by name, so a section is
+ *      archived only when it is unambiguously historical — a dated heading
+ *      past the retention window, or one that says "closure". Everything else
+ *      stays, including anything unrecognised.
+ *   3. A protected list guards the headings PAN itself reads and writes, so
+ *      they survive even if a title were to match the historical patterns.
+ *   4. Dry-run by default. `--apply` is required to touch either file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error } = require('./core.cjs');
+const {
+  STATE_FILE,
+  STATE_HISTORY_FILE,
+  STATE_COMPACT_KEEP_DAYS,
+  CHARS_PER_TOKEN,
+} = require('./constants.cjs');
+const { planningPath, planningRel } = require('./utils.cjs');
+
+/**
+ * Headings PAN's own tooling reads or writes. Never archived, whatever else
+ * matches — `state.cjs` parses Decisions/Blockers/Session by name, and the
+ * remainder are the live working set a resumed session depends on.
+ */
+const PROTECTED_HEADINGS = [
+  /^decisions/i,
+  /^accumulated/i,
+  /^blockers/i,
+  /^concerns/i,
+  /^session\b/i,
+  /^next action/i,
+  /^phase progress/i,
+  /^project reference/i,
+  /^source authority/i,
+  /^toolchain/i,
+  /^metrics/i,
+  /^current/i,
+  /^status/i,
+];
+
+/** Marker left in state.md where an archived section used to be. */
+const POINTER_PREFIX = '_Archived to ';
+
+/**
+ * Body fields that `state.cjs::extractFieldsFromState` reads to REGENERATE the
+ * frontmatter on every write. It takes the FIRST `**Field:**` match anywhere in
+ * the body, so removing a section that carries one can silently change which
+ * value wins — a compaction that quietly rewrites `status:` or `Current Phase`
+ * would be exactly the kind of invisible damage this tool must not do.
+ *
+ * A section carrying any of these is therefore never archived, regardless of
+ * how historical its heading looks.
+ */
+const FRONTMATTER_SOURCE_FIELDS = [
+  'Current Phase', 'Current Phase Name', 'Current Plan', 'Total Phases',
+  'Total Plans in Phase', 'Status', 'Progress', 'Last Activity',
+  'Last Activity Description', 'Stopped At', 'Stopped at', 'Paused At',
+];
+
+const FRONTMATTER_SOURCE_RE = new RegExp(
+  '\\*\\*(?:' + FRONTMATTER_SOURCE_FIELDS.map(f => f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|') + '):\\*\\*',
+  'i'
+);
+
+/** A heading that opens with an ISO date: "## 2026-06-04 — Post-milestone session". */
+const DATED_HEADING_RE = /^\s*(\d{4}-\d{2}-\d{2})\b/;
+
+/** A heading recording a closed unit of work: "## Phase 3 closure" / "## Phase 3 closed". */
+const CLOSURE_HEADING_RE = /\b(closure|closures|closed)\b/i;
+
+/**
+ * Split state.md into its preamble and top-level (H2) sections.
+ *
+ * Only `## ` headings split the file; deeper headings belong to their parent
+ * section, because `state.cjs` writes Decisions/Blockers as `###` nested inside
+ * an H2 and splitting on those would tear a live section in half.
+ *
+ * @param {string} content - full state.md text
+ * @returns {{preamble: string, sections: Array<{title: string, text: string, start: number}>}}
+ */
+function splitSections(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  const heads = [];
+  lines.forEach((line, i) => {
+    if (/^##(?!#)\s+/.test(line)) heads.push({ i, title: line.replace(/^##\s+/, '').trim() });
+  });
+
+  const preamble = lines.slice(0, heads.length ? heads[0].i : lines.length).join('\n');
+  const sections = heads.map((h, k) => {
+    const end = k + 1 < heads.length ? heads[k + 1].i : lines.length;
+    return { title: h.title, text: lines.slice(h.i, end).join('\n'), start: h.i + 1 };
+  });
+  return { preamble, sections };
+}
+
+/**
+ * Decide whether one section is settled history.
+ *
+ * @param {{title: string}} section
+ * @param {number} keepDays - dated sections newer than this stay
+ * @param {number} now - epoch ms, injectable for tests
+ * @returns {{archive: boolean, reason: string}}
+ */
+function classifySection(section, keepDays, now) {
+  const title = section.title || '';
+  const text = section.text || '';
+
+  // Already compacted: the section is now just a pointer at its archived body.
+  // Without this a closure heading would be re-archived on every run, appending
+  // the same pointer to state-history.md forever.
+  if (text.includes(POINTER_PREFIX)) {
+    return { archive: false, reason: 'already archived — only a pointer remains' };
+  }
+
+  if (PROTECTED_HEADINGS.some(re => re.test(title))) {
+    return { archive: false, reason: 'protected — PAN reads or writes this section' };
+  }
+
+  if (FRONTMATTER_SOURCE_RE.test(section.text || '')) {
+    return { archive: false, reason: 'carries a field the frontmatter is rebuilt from — moving it could change state.md metadata' };
+  }
+
+  const dated = title.match(DATED_HEADING_RE);
+  if (dated) {
+    const t = Date.parse(dated[1]);
+    if (!Number.isFinite(t)) return { archive: false, reason: 'unparseable date — left in place' };
+    const ageDays = Math.floor((now - t) / (24 * 3600 * 1000));
+    if (ageDays > keepDays) {
+      return { archive: true, reason: `dated section ${ageDays}d old (keep ${keepDays}d)` };
+    }
+    return { archive: false, reason: `dated section ${ageDays}d old — within the ${keepDays}d window` };
+  }
+
+  if (CLOSURE_HEADING_RE.test(title)) {
+    return { archive: true, reason: 'closure record — the work it describes is finished' };
+  }
+
+  return { archive: false, reason: 'not recognised as history — left in place' };
+}
+
+/**
+ * Rebuild state.md with the named sections replaced by a pointer.
+ *
+ * Shared by the planner and the applier so a dry-run reports the exact bytes
+ * `--apply` will produce, rather than an estimate that could disagree with it.
+ *
+ * @param {string} content - current state.md text
+ * @param {Set<string>} toArchive - section titles to replace
+ * @param {string} stamp - YYYY-MM-DD recorded in each pointer
+ * @returns {string} the rebuilt file
+ */
+function rebuildState(content, toArchive, stamp) {
+  const { preamble, sections } = splitSections(content);
+  const parts = [preamble.trimEnd()];
+  for (const s of sections) {
+    parts.push(toArchive.has(s.title)
+      ? `## ${s.title}\n\n${POINTER_PREFIX}[${STATE_HISTORY_FILE}](${STATE_HISTORY_FILE}) on ${stamp}._`
+      : s.text.trimEnd());
+  }
+  return parts.filter(Boolean).join('\n\n') + '\n';
+}
+
+/**
+ * Plan a compaction without touching anything.
+ *
+ * @param {string} cwd - project root
+ * @param {Object} [opts] - {keepDays, now}
+ * @returns {Object} plan with per-section verdicts and before/after sizes
+ */
+function planStateCompaction(cwd, opts = {}) {
+  const keepDays = Number.isFinite(Number(opts.keepDays)) && opts.keepDays !== null && opts.keepDays !== undefined
+    ? Number(opts.keepDays)
+    : STATE_COMPACT_KEEP_DAYS;
+  const now = opts.now || Date.now();
+  const statePath = planningPath(cwd, STATE_FILE);
+
+  let content;
+  try {
+    content = fs.readFileSync(statePath, 'utf-8');
+  } catch {
+    return { found: false, path: planningRel(STATE_FILE), sections: [], archivable: [], keep_days: keepDays };
+  }
+
+  const { preamble, sections } = splitSections(content);
+  const verdicts = sections.map(s => {
+    const c = classifySection(s, keepDays, now);
+    return { title: s.title, bytes: s.text.length, archive: c.archive, reason: c.reason };
+  });
+
+  let archivable = verdicts.filter(v => v.archive);
+  const bytesBefore = content.length;
+  // 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.
+  const stamp = new Date(now).toISOString().slice(0, 10);
+  let bytesAfter = rebuildState(content, new Set(archivable.map(v => v.title)), stamp).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
+  // bodies they replace — churning state.md to make it BIGGER helps nobody, so
+  // stand down and say why.
+  if (archivable.length > 0 && bytesAfter >= bytesBefore) {
+    for (const v of verdicts) {
+      if (!v.archive) continue;
+      v.archive = false;
+      v.reason = 'archiving it would not shrink state.md — the pointer costs more than the section';
+    }
+    archivable = [];
+    bytesAfter = bytesBefore;
+  }
+
+  return {
+    found: true,
+    path: planningRel(STATE_FILE),
+    history_path: planningRel(STATE_HISTORY_FILE),
+    keep_days: keepDays,
+    sections: verdicts,
+    archivable,
+    bytes_before: bytesBefore,
+    bytes_after: bytesAfter,
+    tokens_before: Math.ceil(bytesBefore / CHARS_PER_TOKEN),
+    tokens_after: Math.ceil(bytesAfter / CHARS_PER_TOKEN),
+    tokens_saved_per_call: Math.max(0, Math.ceil((bytesBefore - bytesAfter) / CHARS_PER_TOKEN)),
+  };
+}
+
+/**
+ * Apply a compaction. Archive is written BEFORE state.md is rewritten, so an
+ * interruption can only ever leave a duplicate — never a loss.
+ *
+ * @param {string} cwd - project root
+ * @param {Object} [opts] - {keepDays, now, apply}
+ * @returns {Object} result
+ */
+function compactState(cwd, opts = {}) {
+  const plan = planStateCompaction(cwd, opts);
+  if (!plan.found) return { ...plan, applied: false, dry_run: !opts.apply };
+  if (!opts.apply || plan.archivable.length === 0) {
+    return { ...plan, applied: false, dry_run: !opts.apply, archived: [] };
+  }
+
+  const statePath = planningPath(cwd, STATE_FILE);
+  const historyPath = planningPath(cwd, STATE_HISTORY_FILE);
+  const content = fs.readFileSync(statePath, 'utf-8');
+  const { sections } = splitSections(content);
+  const now = opts.now || Date.now();
+  const stamp = new Date(now).toISOString().slice(0, 10);
+
+  const toArchive = new Set(plan.archivable.map(v => v.title));
+  const archivedText = sections.filter(s => toArchive.has(s.title)).map(s => s.text.trimEnd()).join('\n\n');
+
+  // 1. Append to history FIRST, so an interruption can only ever duplicate.
+  //
+  //    The preamble is created with an exclusive open rather than an
+  //    existsSync check. Check-then-write is a time-of-check/time-of-use race
+  //    (CWE-367): two compactions running together would each see "absent" and
+  //    each prepend a preamble. `wx` makes creation atomic — EEXIST simply
+  //    means someone else won, which is the outcome we wanted anyway.
+  const preamble = `# State history\n\nSections compacted out of ${STATE_FILE} by \`pan-tools state compact\`.\n`
+    + 'They are kept verbatim and are no longer re-read into agent context.\n';
+  try {
+    fs.writeFileSync(historyPath, preamble, { flag: 'wx', encoding: 'utf-8' });
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+  }
+  fs.appendFileSync(historyPath,
+    `\n\n<!-- compacted from ${STATE_FILE} on ${stamp} -->\n${archivedText}\n`, 'utf-8');
+
+  // 2. Only now rewrite state.md, replacing each archived section with a pointer.
+  const next = rebuildState(content, toArchive, stamp);
+
+  const { writeStateMd } = require('./state.cjs');
+  writeStateMd(statePath, next, cwd);
+
+  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)),
+  };
+}
+
+/** CLI wrapper for `state compact`. */
+function cmdStateCompact(cwd, opts, raw) {
+  const result = compactState(cwd, opts);
+  if (!result.found) {
+    error(`${result.path} not found — nothing to compact`);
+    return;
+  }
+  if (!raw) return output(result, false);
+
+  const lines = [];
+  lines.push(result.applied
+    ? `state compact — APPLIED (${result.archived.length} section(s) archived)`
+    : `state compact — DRY-RUN (pass --apply to execute)`);
+  lines.push(`  ${result.path}: ${(result.bytes_before / 1024).toFixed(1)} KB (~${result.tokens_before} tokens) re-read on every agent call`);
+  for (const s of result.sections) {
+    lines.push(`   ${s.archive ? '→' : '·'} ${(s.bytes / 1024).toFixed(1).padStart(6)} KB  ${s.title.slice(0, 54)}`);
+    lines.push(`        ${s.reason}`);
+  }
+  if (result.archivable.length === 0) {
+    lines.push('  Nothing to compact — no settled history past the retention window.');
+  } else {
+    lines.push(`  → ${result.history_path}`);
+    lines.push(`  after: ~${result.tokens_after} tokens (saves ~${result.tokens_saved_per_call} tokens per agent call)`);
+  }
+  output(result, true, lines.join('\n'));
+}
+
+module.exports = {
+  splitSections,
+  classifySection,
+  planStateCompaction,
+  compactState,
+  cmdStateCompact,
+  PROTECTED_HEADINGS,
+};

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

@@ -8,7 +8,6 @@ const { loadConfig, getMilestoneInfo, escapeRegex, safeReadFile, output, error }
 const { extractFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
 const { withFileLock, writeFileAtomic } = require('./lock.cjs');
 const {
-  PLANNING_DIR,
   STATE_FILE,
   ROADMAP_FILE,
   CONFIG_FILE,

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const {
-  PLANNING_DIR, PHASES_DIR, PLAN_SUFFIX, SUMMARY_SUFFIX, VERIFICATION_SUFFIX,
+  PHASES_DIR, PLAN_SUFFIX, SUMMARY_SUFFIX, VERIFICATION_SUFFIX,
   SIMPLE_TASK_THRESHOLD, SIMPLE_FILE_THRESHOLD, COMPLEX_TASK_THRESHOLD, COMPLEX_FILE_THRESHOLD,
 } = require('./constants.cjs');
 const { planningPath, phasesPath } = require('./utils.cjs');

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

@@ -9,13 +9,13 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const {
-  PLANNING_DIR,
   PHASES_DIR,
   MILESTONES_DIR,
   isPlanFile,
   isSummaryFile,
   PHASE_DIR_RE,
 } = require('./constants.cjs');
+const { planningRootRel, planningRootAbs } = require('./planning-root.cjs');
 
 // ─── File utilities ──────────────────────────────────────────────────────────
 
@@ -44,30 +44,57 @@ function removeQuotes(str) {
 // ─── Phase directory utilities ───────────────────────────────────────────────
 
 /**
- * Build the absolute path to the .planning directory.
+ * Build an absolute path inside the ACTIVE planning root.
+ *
+ * The root is `.planning/` by default but may be a track (`--track verify`) or
+ * any project-relative tree (`--planning-dir`). Every absolute planning path in
+ * the codebase goes through here, which is what makes a non-default root
+ * reachable at all — see planning-root.cjs.
+ *
  * @param {string} cwd - Project root directory
- * @returns {string} Absolute path to .planning/
+ * @param {...string} segments - Path segments below the planning root
+ * @returns {string} Absolute path
+ */
+function planningPath(cwd, ...segments) {
+  return path.join(planningRootAbs(cwd), ...segments.filter(s => s != null && s !== ''));
+}
+
+/**
+ * Build a project-relative, POSIX-separated path inside the active planning
+ * root — the display form used in command output, findings, and `git add`
+ * arguments. Kept in lockstep with planningPath() so what a command reports is
+ * the tree it actually touched.
+ *
+ * @param {...string} segments - Path segments below the planning root
+ * @returns {string} e.g. `.planning/tracks/verify/state.md`
  */
-function planningPath(cwd) {
-  return path.join(cwd, PLANNING_DIR);
+function planningRel(...segments) {
+  const parts = [planningRootRel()];
+  for (const s of segments) {
+    if (s == null || s === '') continue;
+    for (const seg of String(s).split(/[\\/]+/)) {
+      if (seg && seg !== '.') parts.push(seg);
+    }
+  }
+  return parts.join('/');
 }
 
 /**
- * Build the absolute path to the phases directory.
+ * Build the absolute path to the phases directory of the active planning root.
  * @param {string} cwd - Project root directory
- * @returns {string} Absolute path to .planning/phases/
+ * @returns {string} Absolute path to <planning-root>/phases/
  */
 function phasesPath(cwd) {
-  return path.join(cwd, PLANNING_DIR, PHASES_DIR);
+  return planningPath(cwd, PHASES_DIR);
 }
 
 /**
- * Build the absolute path to the milestones directory.
+ * Build the absolute path to the milestones directory of the active planning root.
  * @param {string} cwd - Project root directory
- * @returns {string} Absolute path to .planning/milestones/
+ * @returns {string} Absolute path to <planning-root>/milestones/
  */
 function milestonesPath(cwd) {
-  return path.join(cwd, PLANNING_DIR, MILESTONES_DIR);
+  return planningPath(cwd, MILESTONES_DIR);
 }
 
 /**
@@ -159,6 +186,7 @@ module.exports = {
   readJsonFile,
   removeQuotes,
   planningPath,
+  planningRel,
   phasesPath,
   milestonesPath,
   listPhaseDirs,

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

@@ -9,7 +9,7 @@ const { safeReadFile, normalizePhaseName, comparePhaseNum, execGit, findPhaseInt
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd, readStateSafe } = require('./state.cjs');
 const {
-  PLANNING_DIR, PHASES_DIR, STATE_FILE, ROADMAP_FILE, REQUIREMENTS_FILE, CONFIG_FILE, PROJECT_FILE, PATTERNS_FILE,
+  PHASES_DIR, STATE_FILE, ROADMAP_FILE, REQUIREMENTS_FILE, CONFIG_FILE, PROJECT_FILE, PATTERNS_FILE,
   isPlanFile, isSummaryFile, isVerificationFile, PHASE_HEADER_RE, PHASE_DIR_RE, ARCHIVE_DIR_RE, FIELD_VALUE_RE,
   PLAN_SUFFIX, SUMMARY_SUFFIX, STANDARDS_FILE, STANDARDS_CATALOG, HEALTH_STATUS,
   BUILTIN_DRIFT_RULES, DRIFT_VERDICTS, BINARY_EXTENSIONS, DRIFT_MAX_FILES, DRIFT_MAX_FILE_SIZE, DRIFT_SEVERITY_WEIGHTS,
@@ -21,6 +21,7 @@ const { runDriftCheck, parseConventionRules, checkFileConventions, calculateDrif
 const { collectVerificationStats, countRoadmapPhases, groupGapPatterns, cmdRetro } = require('./verify-retro.cjs');
 const { detectInstalledRuntimes, validateRuntimeInstall, cmdValidateDeployment } = require('./verify-deploy.cjs');
 const { cmdPreflight, cmdDepsValidate } = require('./verify-preflight.cjs');
+const { planningRootRel } = require('./planning-root.cjs');
 
 /**
  * Spot-check files mentioned in summary content.
@@ -715,7 +716,7 @@ function cmdValidateConsistency(cwd, raw) {
  */
 function checkPlanningDirExists(cwd, addIssue) {
   if (!fileAccessible(planningPath(cwd))) {
-    addIssue('error', 'E001', PLANNING_DIR + '/ directory not found', 'Run /pan:new-project to initialize');
+    addIssue('error', 'E001', planningRootRel() + '/ directory not found', 'Run /pan:new-project to initialize');
     return false;
   }
   return true;
@@ -998,7 +999,7 @@ function repairIssues(cwd, repairs) {
           const milestone = getMilestoneInfo(cwd);
           let stateContent = '# Session State\n\n';
           stateContent += '## Project Reference\n\n';
-          stateContent += `See: ${PLANNING_DIR}/${PROJECT_FILE}\n\n`;
+          stateContent += `See: ${planningRootRel()}/${PROJECT_FILE}\n\n`;
           stateContent += '## Position\n\n';
           stateContent += `**Milestone:** ${milestone.version} ${milestone.name}\n`;
           stateContent += '**Current phase:** (determining...)\n';

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

@@ -19,7 +19,6 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error, safeReadFile, isGitRepo, execGit, toPosix, findPhaseInternal } = require('./core.cjs');
-const { PLANNING_DIR } = require('./constants.cjs');
 const { planningPath } = require('./utils.cjs');
 
 const COUNTERFACTUALS_DIR = 'counterfactuals';

package/pan-wizard-core/bin/pan-tools.cjs

@@ -128,7 +128,7 @@
  *   init verify-work <phase>           All context for verify-work workflow
  *   init phase-op <phase>              Generic phase operation context
  *   init todos [area]                  All context for todo workflows
- *   init milestone-op                  All context for milestone operations
+ *   init milestone-op [--all-tracks]   All context for milestone operations
  *   init map-codebase                  All context for map-codebase workflow
  *   init progress                      All context for progress workflow
  *
@@ -219,6 +219,8 @@ const docLint = require('./lib/doc-lint.cjs');
 const learnLint = require('./lib/learn-lint.cjs');
 const learnIndex = require('./lib/learn-index.cjs');
 const links = require('./lib/links.cjs');
+const { setPlanningRoot, describePlanningRoot } = require('./lib/planning-root.cjs');
+const stateCompact = require('./lib/state-compact.cjs');
 
 /**
  * Get the value following a flag in the args array.
@@ -233,6 +235,30 @@ function getArgValue(args, flag, defaultVal = null) {
   return args[idx + 1];
 }
 
+/**
+ * Read a global `--flag value` / `--flag=value` pair and REMOVE it from args,
+ * so per-command parsers never see it. Returns null when the flag is absent.
+ *
+ * @param {string[]} args - CLI arguments (mutated)
+ * @param {string} flag - Flag name (e.g. '--track')
+ * @returns {string|null} The flag's value, or null
+ */
+function takeFlagValue(args, flag) {
+  const eqArg = args.find(a => a.startsWith(`${flag}=`));
+  if (eqArg) {
+    const value = eqArg.slice(flag.length + 1).trim();
+    if (!value) error(`Missing value for ${flag}`);
+    args.splice(args.indexOf(eqArg), 1);
+    return value;
+  }
+  const idx = args.indexOf(flag);
+  if (idx === -1) return null;
+  const value = args[idx + 1];
+  if (!value || value.startsWith('--')) error(`Missing value for ${flag}`);
+  args.splice(idx, 2);
+  return value;
+}
+
 /**
  * Parse JSON string or call error() with a descriptive message.
  * @param {string} raw - Raw JSON string
@@ -270,6 +296,22 @@ async function main() {
     error(`Invalid --cwd: ${cwd}`);
   }
 
+  // Which planning tree do we act on? `--cwd` moves the PROJECT root; these
+  // move the PLANNING root inside it, so a repo holding several planning trees
+  // can address any of them. Parsed here, before dispatch, because the answer
+  // has to be settled once for every path the command will build.
+  const planningDirFlag = takeFlagValue(args, '--planning-dir');
+  const trackFlag = takeFlagValue(args, '--track');
+  const allTracksIndex = args.indexOf('--all-tracks');
+  const allTracks = allTracksIndex !== -1;
+  if (allTracks) args.splice(allTracksIndex, 1);
+
+  try {
+    setPlanningRoot({ planningDir: planningDirFlag, track: trackFlag });
+  } catch (e) {
+    error(e.message);
+  }
+
   const rawIndex = args.indexOf('--raw');
   const raw = rawIndex !== -1;
   if (rawIndex !== -1) args.splice(rawIndex, 1);
@@ -282,7 +324,13 @@ async function main() {
 
   const command = args[0];
 
-  const USAGE = 'Usage: pan-tools <command> [args] [--raw] [--cwd <path>]\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, state-snapshot, summary-extract, rollback-snapshot, batch-commit, websearch, focus, preflight, dashboard, hud, report, learnings, deps, drift-check, memory, bridge, whatif, knowledge, skills, hygiene, review-deep, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links';
+  const USAGE = 'Usage: pan-tools <command> [args] [--raw] [--cwd <path>] [--track <name> | --planning-dir <path>] [--all-tracks]\n'
+    + '\nPlanning root (which .planning tree to act on):\n'
+    + '  --track <name>         act on .planning/tracks/<name>/ instead of .planning/\n'
+    + '  --planning-dir <path>  act on an arbitrary project-relative planning tree\n'
+    + '  --all-tracks           (hygiene) act on the root tree AND every discovered track\n'
+    + '  env: PAN_TRACK, PAN_PLANNING_DIR (flags win)\n'
+    + '\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, state-snapshot, summary-extract, rollback-snapshot, batch-commit, websearch, focus, preflight, dashboard, hud, report, learnings, deps, drift-check, memory, bridge, whatif, knowledge, skills, hygiene, review-deep, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links';
 
   if (!command) {
     error(USAGE);
@@ -317,6 +365,11 @@ async function main() {
           }
         }
         state.cmdStatePatch(cwd, patches, raw);
+      } else if (subcommand === 'compact') {
+        stateCompact.cmdStateCompact(cwd, {
+          apply: args.includes('--apply'),
+          keepDays: getArgValue(args, '--keep-days'),
+        }, raw);
       } else if (subcommand === 'advance-plan') {
         state.cmdStateAdvancePlan(cwd, raw);
       } else if (subcommand === 'record-metric') {
@@ -765,7 +818,7 @@ async function main() {
           init.cmdInitTodos(cwd, args[2], raw);
           break;
         case 'milestone-op':
-          init.cmdInitMilestoneOp(cwd, raw);
+          init.cmdInitMilestoneOp(cwd, raw, { allTracks });
           break;
         case 'map-codebase':
           init.cmdInitMapCodebase(cwd, raw);
@@ -1087,13 +1140,14 @@ async function main() {
       const hygieneOpts = {
         traceAgeDays: getArgValue(args, '--trace-age-days'),
         apply: args.includes('--apply'),
+        allTracks,
       };
       if (subcommand === 'scan') {
         hygiene.cmdHygieneScan(cwd, hygieneOpts, raw);
       } else if (subcommand === 'clean') {
         hygiene.cmdHygieneClean(cwd, hygieneOpts, raw);
       } else {
-        error('Unknown hygiene subcommand. Available: scan, clean [--apply] [--trace-age-days N]');
+        error('Unknown hygiene subcommand. Available: scan, clean [--apply] [--trace-age-days N] [--all-tracks] [--track <name>]');
       }
       break;
     }