pan-wizard 3.33.0 → 3.34.0

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

@@ -294,22 +294,22 @@ function cmdStateRecordMetric(cwd, options, raw) {
     return;
   }
 
-  // Find Performance Metrics section and its table
-  const metricsPattern = /(##\s*Performance Metrics[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n)([\s\S]*?)(?=\n##|\n$|$)/i;
+  // The Performance Metrics section's first table: its rows only, then an optional
+  // "None yet" line. Taking the rest of the section as the table body put every row
+  // below the template's "Recent Trend" and footer lines, outside the table. The
+  // separator is matched on one line: `[-|\s]+` ran on into a `| - | - |` row.
+  const metricsPattern = /(##\s*Performance Metrics[\s\S]*?\n\|[^\n]+\n\|[-|: \t]+\r?\n)((?:\|[^\n]*(?:\n|$))*)((?:[^\S\n]*None yet\.?[^\S\n]*(?:\n|$))?)/i;
   const metricsMatch = content.match(metricsPattern);
 
   if (metricsMatch) {
-    let tableBody = metricsMatch[2].trimEnd();
     const cell = escapeTableCell;
     const newRow = `| Phase ${cell(phase)} P${cell(plan)} | ${cell(duration)} | ${cell(tasks || '-')} tasks | ${cell(files || '-')} files |`;
+    // A template placeholder row (`| - | - | - | - |`, `| None yet | | | |`) gives way.
+    const isPlaceholder = (row) => /None yet/i.test(row) || row.split('|').slice(1, -1).every((c) => /^\s*-?\s*$/.test(c));
+    const rows = metricsMatch[2].split('\n').map((r) => r.replace(/\r$/, '')).filter((r) => r.trim() && !isPlaceholder(r));
+    rows.push(newRow);
 
-    if (tableBody.trim() === '' || tableBody.includes('None yet')) {
-      tableBody = newRow;
-    } else {
-      tableBody = tableBody + '\n' + newRow;
-    }
-
-    content = content.replace(metricsPattern, (_match, header) => `${header}${tableBody}\n`);
+    content = content.replace(metricsPattern, (_match, header) => `${header}${rows.join('\n')}\n`);
     writeStateMd(statePath, content, cwd);
     output({ recorded: true, phase, plan, duration }, raw, 'true');
   } else {
@@ -432,7 +432,8 @@ function cmdStateAddBlocker(cwd, text, raw) {
 
   if (match) {
     let sectionBody = match[2];
-    sectionBody = sectionBody.replace(/None\.?\s*\n?/gi, '').replace(/None yet\.?\s*\n?/gi, '');
+    // "None yet" first: stripping "None" first left a stray "yet." on the template.
+    sectionBody = sectionBody.replace(/None yet\.?\s*\n?/gi, '').replace(/None\.?\s*\n?/gi, '');
     sectionBody = sectionBody.trimEnd() + '\n' + entry + '\n';
     content = content.replace(sectionPattern, (_match, header) => `${header}${sectionBody}`);
     writeStateMd(statePath, content, cwd);
@@ -538,14 +539,23 @@ function cmdStateRecordSession(cwd, options, raw) {
 // --- Snapshot Parsers --------------------------------------------------------
 
 /**
- * Parse the Decisions Made table from state.md content.
- * Extracts rows from a markdown table under the "## Decisions Made" heading,
- * splitting each row into phase, summary, and rationale cells.
+ * Parse the decisions from state.md content: the `- [Phase N]: summary — rationale`
+ * bullets `state add-decision` appends under `### Decisions` (the template's
+ * heading), or else an older "## Decisions Made" table. Reading only the table
+ * left `decisions` empty on every state.md PAN itself writes.
  * @param {string} content - Full state.md content
  * @returns {Array<{phase: string, summary: string, rationale: string}>}
  */
 function parseDecisionsFromState(content) {
   const decisions = [];
+  const section = content.match(/###?\s*(?:Decisions|Decisions Made|Accumulated.*Decisions)\s*\n([\s\S]*?)(?=\n###?|\n##[^#]|$)/i);
+  for (const line of section ? section[1].split('\n') : []) {
+    const m = line.match(/^-\s+\[Phase\s+([^\]]*)\]:\s*(.+?)\s*$/i);
+    if (!m) continue;
+    const [summary, ...rest] = m[2].split(' — ');
+    decisions.push({ phase: m[1].trim(), summary: summary.trim(), rationale: rest.join(' — ').trim() });
+  }
+  if (decisions.length > 0) return decisions;
   // Match the decisions table body after header row and separator row
   const decisionsMatch = content.match(/##\s*Decisions Made[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n([\s\S]*?)(?=\n##|\n$|$)/i);
   if (decisionsMatch) {
@@ -567,14 +577,15 @@ function parseDecisionsFromState(content) {
 
 /**
  * Parse the Blockers section from state.md content.
- * Extracts bullet-point items (lines starting with "- ") from under
- * the "## Blockers" heading.
+ * Extracts bullet-point items (lines starting with "- ") from under the heading
+ * `state add-blocker` writes to: `### Blockers/Concerns` in the template, or
+ * `Blockers` / `Concerns`. Matching only "## Blockers" left the list empty.
  * @param {string} content - Full state.md content
  * @returns {string[]} Array of blocker text strings
  */
 function parseBlockersFromState(content) {
   const blockers = [];
-  const blockersMatch = content.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
+  const blockersMatch = content.match(/###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n([\s\S]*?)(?=\n###?|\n##[^#]|$)/i);
   if (blockersMatch) {
     const blockersSection = blockersMatch[1];
     const items = blockersSection.match(/^-\s+(.+)$/gm) || [];
@@ -585,6 +596,18 @@ function parseBlockersFromState(content) {
   return blockers;
 }
 
+/**
+ * The blockers that are still open: the section's bullets minus a "None" placeholder.
+ * `preflight` and `dashboard` read a `## Blockers` heading of their own, which the
+ * state template never writes (it writes `### Blockers/Concerns`, where
+ * `state add-blocker` puts its bullets), so both reported no blockers with one open.
+ * @param {string} content - Full state.md content
+ * @returns {string[]}
+ */
+function activeBlockersFromState(content) {
+  return parseBlockersFromState(content).filter((b) => b && !/^none(\s+yet)?\.?$/i.test(b));
+}
+
 /**
  * Parse the Session section from state.md content.
  * Extracts **Last Date:**, **Stopped At:**, and **Resume File:** bold-field
@@ -1029,17 +1052,8 @@ function cmdDashboard(cwd, raw) {
     lastActivity = stateExtractField(stateContent, 'Last Activity');
     lastActivityDesc = stateExtractField(stateContent, 'Last Activity Description');
 
-    // Parse blockers
-    const blockersMatch = stateContent.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
-    if (blockersMatch) {
-      const items = blockersMatch[1].match(/^-\s+(.+)$/gm) || [];
-      for (const item of items) {
-        const text = item.replace(/^-\s+/, '').trim();
-        if (text && !/^none$/i.test(text)) {
-          activeBlockers.push(text);
-        }
-      }
-    }
+    // Parse blockers (the template's `### Blockers/Concerns`, or a legacy `## Blockers`)
+    activeBlockers.push(...activeBlockersFromState(stateContent));
     blockerCount = activeBlockers.length;
   }
 
@@ -1111,6 +1125,7 @@ function cmdDashboard(cwd, raw) {
 
 module.exports = {
   readStateSafe: safeReadFile,
+  activeBlockersFromState,
   stateExtractField,
   stateReplaceField,
   writeStateMd,

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const {
-  PHASES_DIR, PLAN_SUFFIX, SUMMARY_SUFFIX, VERIFICATION_SUFFIX,
+  PHASES_DIR, PLAN_SUFFIX, SUMMARY_SUFFIX, VERIFICATION_SUFFIX, ROADMAP_SLICE_SUFFIX,
   SIMPLE_TASK_THRESHOLD, SIMPLE_FILE_THRESHOLD, COMPLEX_TASK_THRESHOLD, COMPLEX_FILE_THRESHOLD,
 } = require('./constants.cjs');
 const { planningPath, phasesPath } = require('./utils.cjs');
@@ -86,7 +86,7 @@ function cmdTemplateSelect(cwd, planPath, raw) {
  * @param {string} phaseName - Human-readable phase name
  * @param {string} phaseSlug - Phase slug for directory naming
  * @param {string} phaseNum - Raw phase number from options
- * @param {Object} options - Additional options (type, wave, fields)
+ * @param {Object} options - Additional options (type, wave, fields, slicePath)
  * @returns {{frontmatter: Object, body: string, fileName: string}}
  */
 function generatePlanTemplate(phaseId, planId, phaseName, phaseSlug, phaseNum, options) {
@@ -94,6 +94,10 @@ function generatePlanTemplate(phaseId, planId, phaseName, phaseSlug, phaseNum, o
   const wave = parseInt(options.wave, 10) || 1;
   const fields = options.fields || {};
   const padded = phaseId.split('-')[0]; // e.g., "01" from "01-setup-auth"
+  // The <context> names the phase's roadmap slice, as templates/phase-prompt.md
+  // does (O2): `@.planning/roadmap.md` handed every executor the whole roadmap.
+  // cmdTemplateFill passes the phase's real directory.
+  const slicePath = options.slicePath || `.planning/phases/${phaseId}/${padded}${ROADMAP_SLICE_SUFFIX}`;
 
   const frontmatter = {
     phase: phaseId,
@@ -121,7 +125,7 @@ function generatePlanTemplate(phaseId, planId, phaseName, phaseSlug, phaseNum, o
     '',
     '## Context',
     '@.planning/project.md',
-    '@.planning/roadmap.md',
+    `@${slicePath}`,
     '@.planning/state.md',
     '',
     '## Tasks',
@@ -286,7 +290,10 @@ function cmdTemplateFill(cwd, templateType, options, raw) {
       generated = generateSummaryTemplate(phaseId, planNum, phaseName, options.phase, fields);
       break;
     case 'plan':
-      generated = generatePlanTemplate(phaseId, planNum, phaseName, phaseSlug, options.phase, options);
+      generated = generatePlanTemplate(phaseId, planNum, phaseName, phaseSlug, options.phase, {
+        ...options,
+        slicePath: toPosix(path.join(phaseInfo.directory, `${padded}${ROADMAP_SLICE_SUFFIX}`)),
+      });
       break;
     case 'verification':
       generated = generateVerificationTemplate(phaseId, phaseName, options.phase, fields);

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

@@ -7,7 +7,7 @@
 const fs = require('fs');
 const path = require('path');
 const { safeReadFile, execGit, findPhaseInternal, output, normalizePhaseName } = require('./core.cjs');
-const { readStateSafe } = require('./state.cjs');
+const { readStateSafe, activeBlockersFromState } = require('./state.cjs');
 const {
   STATE_FILE, ROADMAP_FILE, CONFIG_FILE, PATTERNS_FILE, PHASE_DIR_RE,
 } = require('./constants.cjs');
@@ -44,19 +44,10 @@ function cmdPreflight(cwd, target, raw) {
     blockers.push('state.md not found — run /pan:new-project');
   }
 
-  // Check 3: no unresolved blockers in state.md
+  // Check 3: no unresolved blockers in state.md (the template's `### Blockers/Concerns`,
+  // where `state add-blocker` writes, or a legacy `## Blockers`)
   if (stateContent) {
-    const blockersMatch = stateContent.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
-    const activeBlockers = [];
-    if (blockersMatch) {
-      const items = blockersMatch[1].match(/^-\s+(.+)$/gm) || [];
-      for (const item of items) {
-        const text = item.replace(/^-\s+/, '').trim();
-        if (text && !/^none$/i.test(text)) {
-          activeBlockers.push(text);
-        }
-      }
-    }
+    const activeBlockers = activeBlockersFromState(stateContent);
     if (activeBlockers.length === 0) {
       checks.push({ name: 'no_blockers', passed: true });
     } else {

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

@@ -122,9 +122,11 @@ function cmdRetro(cwd, raw, args) {
     common_gap_patterns: gapGroups,
   };
 
-  // E-4: optional memory write. Top gap patterns become lessons for pan-planner
-  // (they surface what plans routinely miss). First-try rate deltas feed
-  // pan-verifier memory.
+  // E-4: optional memory write. Top gap patterns become lessons in pan-planner's
+  // log (they surface what plans routinely miss), first-try rate deltas in
+  // pan-verifier's. Stored for /pan:knowledge: PAN's workflows no longer load agent
+  // memory into agents (ADR-0036, amended 2026-10-04), and /pan:army no longer
+  // passes the flag.
   const argsList = Array.isArray(args) ? args : [];
   if (argsList.includes('--write-memory')) {
     const { appendMemory } = require('./memory.cjs');

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

@@ -27,8 +27,11 @@ const LOCKFILES = new Set([
 ]);
 // PAN's own installed trees: a phase commit that touches them is PAN bookkeeping,
 // never the project's scope (pan-reviewer skips them for the same reason).
-const PAN_OWNED_PREFIXES = ['.claude/', '.codex/', '.gemini/', '.opencode/', '.agents/', '.github/pan-wizard-core/', '.github/agents/', '.github/prompts/', '.github/skills/'];
-const PAN_OWNED_FILES = new Set(['.github/copilot-instructions.md', '.github/hooks/pan.json']);
+// A Copilot install shares `.github/` with the project: only what the installer writes as
+// its own is listed, so the project's workflows, hooks and Copilot instructions stay in scope,
+// and so do the files PAN merges into (`mcp.json`, `copilot/settings.json`).
+const PAN_OWNED_PREFIXES = ['.claude/', '.codex/', '.gemini/', '.opencode/', '.agents/', '.github/pan-wizard-core/', '.github/pan-local-patches/', '.github/agents/pan-', '.github/skills/pan-', '.github/hooks/pan-'];
+const PAN_OWNED_FILES = new Set(['.github/hooks/pan.json', '.github/package.json', '.github/pan-file-manifest.json']);
 const TEST_PATH_RE = /(^|\/)(tests?|__tests__|specs?)\//i;
 const TEST_FILE_RE = /\.(test|spec)\.[a-z0-9]+$/i;
 const COMMIT_SCAN_LIMIT = 2000;

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

@@ -25,6 +25,7 @@ const { detectInstalledRuntimes, validateRuntimeInstall, cmdValidateDeployment }
 const { cmdPreflight, cmdDepsValidate } = require('./verify-preflight.cjs');
 const { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale } = require('./verify-scope.cjs');
 const { planningRootRel } = require('./planning-root.cjs');
+const { roadmapRequirementIds } = require('./roadmap.cjs');
 
 /**
  * Spot-check files mentioned in summary content.
@@ -439,11 +440,10 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
     // artifacts: [], key_links: [] }` (pan-wizard-core/templates/phase-prompt.md,
     // template.cjs generatePlanTemplate), so an empty block is the documented default
     // state of a scaffolded plan; presence of the block is enforced by
-    // `verify plan-structure`, not here. (2) parseMustHavesBlock currently matches the
-    // block header at 4-space indent while every shipped template and agent emits it at
-    // 2 — so this branch is reached for *every* plan authored in PAN's own format, and
-    // exiting non-zero would fail every real `verify artifacts` call. Reclassifying
-    // this as a failure requires fixing that indentation mismatch first.
+    // `verify plan-structure`, not here. (2) parseMustHavesBlock once required a
+    // 4-space indent while every shipped template and agent writes 2, so this branch
+    // fired for every plan in PAN's own format. It reads relative indent now
+    // (frontmatter.cjs), so reaching it means the plan declares no artifacts.
     output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw, undefined, EXIT_OK);
     return;
   }
@@ -508,8 +508,7 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
   const r = checkKeyLinks(cwd, content);
   if (r.total === 0) {
     // EXIT_OK: same reasoning as cmdVerifyArtifacts above — an empty key_links block is
-    // the shipped template default, and the parseMustHavesBlock indent mismatch means
-    // this branch fires for every plan written in PAN's own format.
+    // the shipped template default, so a plan that declares none is a result, not a failure.
     output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw, undefined, EXIT_OK);
     return;
   }
@@ -550,10 +549,19 @@ function reconcilePhase(cwd, phaseNum) {
   const sm = verRaw.match(/^status:\s*([A-Za-z_-]+)/m);
   const status = sm ? sm[1].toLowerCase() : 'unknown';
   const claimsPass = /^(pass|passed|verified|complete|verified_pass)$/.test(status);
-  const planFile = files.find(f => isPlanFile(f));
-  const planContent = planFile ? (safeReadFile(path.join(dir, planFile)) || '') : '';
-  const artifacts = checkArtifacts(cwd, planContent);
-  const keyLinks = checkKeyLinks(cwd, planContent);
+  // Every plan's must_haves. Reading only the first plan let a later plan's failing
+  // artifact through under a passing verdict — the rubber stamp this check exists for.
+  const artifacts = { all_passed: true, passed: 0, total: 0, artifacts: [] };
+  const keyLinks = { all_verified: true, verified: 0, total: 0, links: [] };
+  for (const planFile of files.filter(f => isPlanFile(f)).sort()) {
+    const planContent = safeReadFile(path.join(dir, planFile)) || '';
+    const a = checkArtifacts(cwd, planContent);
+    const k = checkKeyLinks(cwd, planContent);
+    artifacts.passed += a.passed; artifacts.total += a.total; artifacts.artifacts.push(...a.artifacts.map(x => ({ plan: planFile, ...x })));
+    keyLinks.verified += k.verified; keyLinks.total += k.total; keyLinks.links.push(...k.links.map(x => ({ plan: planFile, ...x })));
+  }
+  artifacts.all_passed = artifacts.passed === artifacts.total;
+  keyLinks.all_verified = keyLinks.verified === keyLinks.total;
   const signals = artifacts.total + keyLinks.total;
   const contradictions = [];
   if (claimsPass) {
@@ -1236,11 +1244,10 @@ function syncRequirementCheckboxes(cwd) {
   // For each completed phase, find linked requirement IDs and check their boxes
   let fixed = 0;
   for (const phaseNum of completedPhases) {
-    const reqMatch = roadmapContent.match(
-      new RegExp(`Phase\\s+${escapeRegex(phaseNum)}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i')
-    );
-    if (!reqMatch) continue;
-    const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(id => id.trim()).filter(Boolean);
+    // The phase's own requirements, as `phase complete` reads them: a bare "Phase N …
+    // Requirements" search took the first section's line for every phase when the
+    // checklist sits above the sections, as templates/roadmap.md lays it out.
+    const reqIds = roadmapRequirementIds(roadmapContent, phaseNum);
     for (const reqId of reqIds) {
       const escaped = escapeRegex(reqId);
       const re = new RegExp(`(- \\[) (\\]\\s*\\*\\*${escaped}\\*\\*)`, 'gi');
@@ -1461,7 +1468,6 @@ function cmdValidateHealth(cwd, options, raw) {
   // Check 10 (optional): full validation — run tests and build
   let testStatus;
   let buildStatus;
-  let memoryBudget;
   if (options.full) {
     testStatus = runFullTestCheck(cwd);
     buildStatus = runFullBuildCheck(cwd);
@@ -1471,14 +1477,9 @@ function cmdValidateHealth(cwd, options, raw) {
     if (buildStatus.pass === false) {
       addIssue('error', 'BUILD_FAIL', `Build failed (exit code ${buildStatus.exitCode})`, 'Fix build errors');
     }
-    // Memory-load budget (ADR-0036 acceptance signal): keep per-agent memory
-    // injection bounded as logs grow. Read-only, non-blocking.
-    memoryBudget = require('./memory.cjs').memoryLoadBudget(cwd);
-    if (memoryBudget.status === 'critical') {
-      addIssue('warning', 'MEM_BUDGET', memoryBudget.advisory, "Run 'pan-tools memory compact <agent>' or scope injection with 'memory select'");
-    } else if (memoryBudget.status === 'warning') {
-      addIssue('info', 'MEM_BUDGET', memoryBudget.advisory, "Run 'pan-tools memory compact <agent>' or scope injection with 'memory select'");
-    }
+    // No memory-load check: PAN's workflows no longer load agent memory into
+    // agents (ADR-0036, amended 2026-10-04), so its size costs no agent context.
+    // `pan-tools memory budget` still sizes the store on request.
   }
 
   // Check 11 (optional): drift analysis
@@ -1539,7 +1540,6 @@ function cmdValidateHealth(cwd, options, raw) {
   if (options.full) {
     result.test_status = testStatus;
     result.build_status = buildStatus;
-    result.memory_budget = memoryBudget;
   }
   if (options.drift) {
     result.drift_status = driftResult;
@@ -1549,8 +1549,10 @@ function cmdValidateHealth(cwd, options, raw) {
   }
 
   // Explicit verdict exit: `broken` → 1; `degraded` and `healthy` → 0 (warnings are
-  // not failures). Computed AFTER --repair ran, so the code reflects the post-repair
-  // state the JSON reports. See the note at the early-return site above.
+  // not failures). The issue lists were collected before --repair ran and a repair
+  // removes nothing from them, so the status and this code describe the tree as it
+  // was before the repairs; `repairs_performed` says what changed, and a second run
+  // shows the result. See the note at the early-return site above.
   output(result, raw, undefined, status === HEALTH_STATUS.BROKEN ? 1 : 0);
 }
 

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

@@ -187,10 +187,12 @@ function createWorktree(cwd, phaseNum, scenario, opts) {
     return { error: 'Not a git repo — what-if requires git worktree support' };
   }
   const slug = scenarioSlug(scenario);
-  const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  const branch = `${BRANCH_PREFIX}${phaseNum}-${slug}-${ts.slice(0, 15)}`;
+  // To the millisecond: cut to `slice(0, 15)` it had ten-minute resolution, so a repeat
+  // of the same phase and scenario within ten minutes failed on an existing branch.
+  const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 23);
+  const branch = `${BRANCH_PREFIX}${phaseNum}-${slug}-${ts}`;
   const worktreeRoot = opts?.worktree_root
-    || path.join(path.dirname(cwd), `pan-whatif-${phaseNum}-${slug}-${ts.slice(0, 15)}`);
+    || path.join(path.dirname(cwd), `pan-whatif-${phaseNum}-${slug}-${ts}`);
 
   // Base ref: current HEAD by default. Callers can override (e.g. to branch
   // off main for a clean comparison).

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

@@ -187,6 +187,35 @@
 
 const fs = require('fs');
 const path = require('path');
+
+// Compile cache (Node 22.1+; a no-op before): V8 reuses the compiled code of pan-tools
+// and its modules across processes, which workflows start many times per phase — a
+// `version` call went from 100 to 75 ms median (measured 2026-10-10, bare node 44 ms).
+// The cache sits in the per-user 0700 directory the hooks already use, never Node's
+// default under the shared system temp directory, where another user could plant
+// compiled code. A directory that is a symlink, not ours, or open to group or other
+// disables it. NODE_COMPILE_CACHE, when set, is Node's own choice and wins; any failure
+// runs without a cache.
+function enableCompileCache() {
+  try {
+    const mod = require('module');
+    if (typeof mod.enableCompileCache !== 'function' || process.env.NODE_COMPILE_CACHE) return;
+    const os = require('os');
+    const uid = typeof process.getuid === 'function' ? process.getuid() : (process.env.USERNAME || 'win');
+    const parent = path.join(os.tmpdir(), `pan-hooks-${uid}`);
+    const dir = path.join(parent, 'compile-cache');
+    for (const d of [parent, dir]) {
+      fs.mkdirSync(d, { recursive: true, mode: 0o700 });
+      const st = fs.lstatSync(d);
+      if (st.isSymbolicLink()) return;
+      // POSIX only: Windows reports synthetic mode bits.
+      if (typeof process.getuid === 'function' && (st.uid !== process.getuid() || (st.mode & 0o077) !== 0)) return;
+    }
+    mod.enableCompileCache(dir);
+  } catch { /* best effort: run uncached */ }
+}
+enableCompileCache();
+
 const { error, output, buildCachedContext } = require('./lib/core.cjs');
 const state = require('./lib/state.cjs');
 const phase = require('./lib/phase.cjs');
@@ -333,7 +362,7 @@ async function main() {
     + '  --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, findings, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links';
+    + '\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, findings, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links, version';
 
   if (!command) {
     error(USAGE);
@@ -538,9 +567,16 @@ async function main() {
       const force = args.includes('--force');
       const failOnError = args.includes('--fail-on-error');
       const message = args[1] && !args[1].startsWith('--') ? args[1] : null;
-      // Parse --files flag (collect args after --files, stopping at other flags)
+      // Parse --files flag: collect args after --files, stopping at the next flag. A
+      // filter here took every later bare argument, so `--files f --type docs` staged `docs`.
       const filesIndex = args.indexOf('--files');
-      const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : [];
+      const files = [];
+      if (filesIndex !== -1) {
+        for (const a of args.slice(filesIndex + 1)) {
+          if (a.startsWith('--')) break;
+          files.push(a);
+        }
+      }
       const commitType = getArgValue(args, '--type');
       commands.cmdCommit(cwd, message, files, raw, amend, { type: commitType, force, failOnError });
       break;
@@ -689,8 +725,16 @@ async function main() {
       } else if (subcommand === 'update-plan-progress') {
         if (!args[2]) error('roadmap update-plan-progress requires a phase number');
         roadmap.cmdRoadmapUpdatePlanProgress(cwd, args[2], raw);
+      } else if (subcommand === 'slice') {
+        if (!args[2]) error('roadmap slice requires a phase number');
+        roadmap.cmdRoadmapSlice(cwd, args[2], { write: args.includes('--write') }, raw);
+      } else if (subcommand === 'compact') {
+        const keepIdx = args.indexOf('--keep');
+        const keep = keepIdx !== -1 ? Number(args[keepIdx + 1]) : undefined;
+        if (keepIdx !== -1 && !(Number.isInteger(keep) && keep >= 0)) error('roadmap compact --keep needs a whole number of phases (0 or more)');
+        require('./lib/roadmap-compact.cjs').cmdRoadmapCompact(cwd, { apply: args.includes('--apply'), keep }, raw);
       } else {
-        error('Unknown roadmap subcommand. Available: get-phase, analyze, update-plan-progress');
+        error('Unknown roadmap subcommand. Available: get-phase, analyze, update-plan-progress, slice, compact');
       }
       break;
     }
@@ -1038,7 +1082,12 @@ async function main() {
       if (subcommand === 'read') {
         memory.cmdMemoryRead(cwd, args[2], raw);
       } else if (subcommand === 'append') {
-        memory.cmdMemoryAppend(cwd, args[2], args.slice(3).join(' '), raw);
+        // `--cites <path[#symbol]>,...` is taken out before the entry words are joined.
+        const rest = args.slice(3);
+        const ci = rest.indexOf('--cites');
+        const cites = ci === -1 ? undefined : rest[ci + 1];
+        if (ci !== -1) rest.splice(ci, 2);
+        memory.cmdMemoryAppend(cwd, args[2], rest.join(' '), raw, { cites });
       } else if (subcommand === 'list') {
         memory.cmdMemoryList(cwd, raw);
       } else if (subcommand === 'compact') {
@@ -1048,7 +1097,22 @@ async function main() {
           cue: getArgValue(args, '--cue'),
           tokenBudget: getArgValue(args, '--token-budget'),
           recencyFloor: getArgValue(args, '--recency-floor'),
+          all: args.includes('--all'),
+          markUsed: args.includes('--mark-used'),
+          expireDays: getArgValue(args, '--days'),
+        }, raw);
+      } else if (subcommand === 'record') {
+        memory.cmdMemoryRecord(cwd, args[2] && !args[2].startsWith('--') ? args[2] : null, {
+          lesson: getArgValue(args, '--lesson'),
+          finding: getArgValue(args, '--finding'),
+          trace: getArgValue(args, '--trace'),
+          cites: getArgValue(args, '--cites'),
         }, raw);
+      } else if (subcommand === 'prune') {
+        const daysArg = getArgValue(args, '--days');
+        if (daysArg !== null && !/^\d+$/.test(daysArg)) error('memory prune --days needs a whole number of days (0 turns expiry off)');
+        const target = args[2] && !args[2].startsWith('--') ? args[2] : null;
+        memory.cmdMemoryPrune(cwd, target, { apply: args.includes('--apply'), days: daysArg === null ? undefined : Number(daysArg) }, raw);
       } else if (subcommand === 'budget') {
         memory.cmdMemoryBudget(cwd, raw);
       } else if (subcommand === 'optimize') {
@@ -1062,7 +1126,7 @@ async function main() {
           apply: args.includes('--apply'),
         }, raw);
       } else {
-        error('Unknown memory subcommand. Available: read, append, list, compact, select, budget, optimize, rebuild');
+        error('Unknown memory subcommand. Available: read, append, list, compact, select, record, prune, budget, optimize, rebuild');
       }
       break;
     }
@@ -1117,7 +1181,14 @@ async function main() {
     case 'knowledge': {
       const subcommand = args[1];
       if (subcommand === 'ask') {
-        const question = args.slice(2).filter(a => !a.startsWith('--')).join(' ');
+        // The question is every word after `ask` that is neither a flag nor a flag's
+        // value: `--recall-cue "session tokens" --max-sources 3` used to join it.
+        const words = [];
+        for (let i = 2; i < args.length; i++) {
+          if (args[i] === '--max-sources' || args[i] === '--recall-cue') { i++; continue; }
+          if (!args[i].startsWith('--')) words.push(args[i]);
+        }
+        const question = words.join(' ');
         const maxSources = getArgValue(args, '--max-sources');
         knowledge.cmdKnowledgeAsk(cwd, question, {
           max_sources: maxSources ? Number(maxSources) : undefined,
@@ -1249,7 +1320,8 @@ async function main() {
 
     case 'cost': {
       const subcommand = args[1];
-      if (subcommand === 'report' || !subcommand) {
+      // `report` is the default, so a leading flag (`cost --format chart`) means report, as for `links`.
+      if (subcommand === 'report' || !subcommand || subcommand.startsWith('--')) {
         const format = getArgValue(args, '--format', 'json');
         const since = getArgValue(args, '--since');
         const until = getArgValue(args, '--until');
@@ -1276,8 +1348,10 @@ async function main() {
           mainThread: !args.includes('--no-main-thread'),
           claudeDir: getArgValue(args, '--claude-dir'),
         }, raw);
+      } else if (subcommand === 'limits') {
+        cost.cmdCostLimits(cwd, raw);
       } else {
-        error('Unknown cost subcommand. Available: report, append, clear, rebuild');
+        error('Unknown cost subcommand. Available: report, append, clear, rebuild, limits');
       }
       break;
     }
@@ -1330,7 +1404,7 @@ async function main() {
         campaign.cmdCampaignSchedule(cwd, {
           goal: getArgValue(args, '--goal'),
           source: getArgValue(args, '--source'),
-          cadence: getArgValue(args, '--cadence', 'daily'),
+          cadence: getArgValue(args, '--cadence'),
           daily_budget: budget != null ? Number(budget) : undefined,
           enabled: args.includes('--disable') ? false : undefined,
           paused: args.includes('--pause') ? true : (args.includes('--resume') ? false : undefined),
@@ -1539,9 +1613,11 @@ async function main() {
           ? sourceExpsCsv.split(',').map(s => s.trim()).filter(Boolean)
           : [];
         const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
+        const citesCsv = getArgValue(args, '--cites') || '';
+        const cites = citesCsv ? citesCsv.split(',').map(s => s.trim()).filter(Boolean) : [];
 
         const result = optimize.promotePattern(
-          { id: patternId, summary, evidence, rule, applies_in: appliesIn, source_experiments: sourceExperiments },
+          { id: patternId, summary, evidence, rule, applies_in: appliesIn, source_experiments: sourceExperiments, ...(cites.length ? { cites } : {}) },
           { scope, topic, sourceRoot }
         );
         output(result, raw);
@@ -1589,9 +1665,13 @@ async function main() {
         if (!agent) { error('learn topics-for requires --agent <name>'); }
         const minRelevance = getArgValue(args, '--min-relevance', 'medium');
         const tokenBudget = parseInt(getArgValue(args, '--token-budget', '5000'), 10);
-        const result = learnIndex.cmdTopicsFor(sourceRoot, { agent, minRelevance, tokenBudget });
+        const cue = getArgValue(args, '--cue') || undefined;
+        const result = learnIndex.cmdTopicsFor(sourceRoot, { agent, minRelevance, tokenBudget, cue });
         if (raw) {
-          const lines = [`Topics for "${agent}" (min ${minRelevance}, budget ${tokenBudget}):`, ``];
+          const head = result.mode === 'cue'
+            ? `Topics for "${agent}" matching the cue (budget ${tokenBudget}):`
+            : `Topics for "${agent}" (min ${minRelevance}, budget ${tokenBudget})${cue ? ' — nothing matched the cue, so by role' : ''}:`;
+          const lines = [head, ``];
           for (const t of result.selected) {
             lines.push(`  [${t.relevance.padEnd(6)}] ${t.scope}/${t.name.padEnd(22)} ${t.tokens.toString().padStart(5)}t   ${t.patterns.join(', ')}`);
           }
@@ -1646,18 +1726,24 @@ async function main() {
       // and to the suggestion index that is now parsed from those strings.
       // Publishing it fixes the error AND feeds the suggester, with no second
       // list to maintain.
-      if (subcommand) {
+      //
+      // A flag is not a subcommand: `learn --session <id>` and `learn --sessions N`
+      // take the alias with `optimize learn`'s flags (the guard used to refuse both).
+      if (subcommand && !subcommand.startsWith('--')) {
         error('Unknown learn subcommand. Available: promote, unpromote, list-promoted, build-index, topics-for, lint');
       }
       optimize.cmdOptimizeLearn(cwd, {
         sessionId: getArgValue(args, '--session'),
+        sessions: getArgValue(args, '--sessions'),
       }, raw);
       break;
     }
 
     case 'links': {
       const subcommand = args[1];
-      if (subcommand === 'validate' || !subcommand) {
+      // `validate` is the default, flags and all: `links --strict` used to be refused
+      // as an unknown subcommand while bare `links` validated.
+      if (subcommand === 'validate' || !subcommand || subcommand.startsWith('--')) {
         const collectMulti = (flag) => {
           const vals = [];
           for (let i = 0; i < args.length; i++) {