pan-wizard 3.32.0 → 3.34.0

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

@@ -3,13 +3,15 @@
  */
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, loadConfig, isGitIgnored, isGitRepo, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, resolveModelDetailed, resolveEffortInternal, detectProvider, resolveTierToModel, estimateCostMultiplier, MODEL_PROFILES, output, error, findPhaseInternal, scanPendingTodos, toPosix } = require('./core.cjs');
+const { safeReadFile, loadConfig, isGitIgnored, isGitRepo, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, resolveModelDetailed, resolveEffortInternal, detectProvider, resolveTierToModel, estimateCostMultiplier, MODEL_PROFILES, output, error, findPhaseInternal, scanPendingTodos, toPosix, toLf } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { PHASES_DIR, MILESTONES_DIR, QUICK_DIR, STATE_FILE, ROADMAP_FILE, PROJECT_FILE, PATTERNS_FILE, SESSION_HISTORY_FILE, LEARNINGS_FILE, CONTEXT_SUFFIX, UAT_SUFFIX, VERIFICATION_SUFFIX, isPlanFile, isSummaryFile, ARCHIVE_DIR_RE, PHASE_DIR_RE, CONTEXT_WINDOW, WARNING_THRESHOLD, CRITICAL_THRESHOLD, VALID_COMMIT_TYPES, DEFAULT_SENSITIVE_PATTERNS, STATE_CONTRACT } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, planningRel } = require('./utils.cjs');
 const { estimateTokens } = require('./context-budget.cjs');
 const { collectPhaseSummaries, readErrorPatterns, appendErrorPattern, appendSessionSummary, parseLearnings, formatLearningEntry, cmdLearningsExtract, cmdLearningsList, cmdLearningsPrune } = require('./commands-learnings.cjs');
 const { planningRootRel } = require('./planning-root.cjs');
+const { verificationFreshness } = require('./verify-scope.cjs');
+const { isVerificationFile } = require('./constants.cjs');
 
 /**
  * Generate a URL-safe slug from text by lowercasing and replacing non-alphanumeric chars.
@@ -151,9 +153,12 @@ function buildDigest(summaries, techStack) {
       frontmatter.provides.forEach(item => phases[phaseNum].provides.add(item));
     }
 
-    // Merge affects from nested dependency-graph
+    // Merge affects from either nested dependency-graph or the flat `affects:` list the
+    // summary templates write (only the nested form was read, so `affects` stayed empty)
     if (frontmatter['dependency-graph'] && Array.isArray(frontmatter['dependency-graph'].affects)) {
       frontmatter['dependency-graph'].affects.forEach(item => phases[phaseNum].affects.add(item));
+    } else if (Array.isArray(frontmatter.affects)) {
+      frontmatter.affects.forEach(item => phases[phaseNum].affects.add(item));
     }
 
     // Merge established patterns
@@ -313,7 +318,9 @@ function runCommitSafetyChecks(cwd, config, force) {
   if (statusResult.exitCode === 0 && statusResult.stdout) {
     for (const line of statusResult.stdout.split('\n').filter(Boolean)) {
       if (line.startsWith(' D') || line.startsWith('D ') || line.startsWith('D')) {
-        const fileName = line.slice(3).trim();
+        // execGit trims stdout, so a first line of ` D gone.txt` arrives as `D gone.txt`:
+        // strip the status code by pattern, not by a fixed three-character slice
+        const fileName = line.replace(/^\s*[A-Z?!]{1,2}\s+/, '').trim();
         if (fileName) safetyChecks.deleted_files.push(fileName);
       }
     }
@@ -331,7 +338,13 @@ function runCommitSafetyChecks(cwd, config, force) {
     if (patterns.length > 0) {
       const stagedFiles = stagedResult.stdout.split('\n').filter(Boolean);
       const regexes = patterns.map(p => { try { return new RegExp(p, 'i'); } catch { return null; } }).filter(Boolean);
+      // PAN's own cost ledger matches the bare `token` pattern, which blocked every
+      // commit that staged .planning/ once the cost logger had written to it. It holds
+      // token counts, never a credential. The hook always writes the root tree's copy.
+      const { METRICS_DIR, TOKENS_FILE } = require('./cost.cjs');
+      const ownLedger = new Set([planningRel(METRICS_DIR, TOKENS_FILE), `.planning/${METRICS_DIR}/${TOKENS_FILE}`]);
       for (const f of stagedFiles) {
+        if (ownLedger.has(f)) continue;
         if (regexes.some(re => re.test(f))) safetyChecks.sensitive_files_blocked.push(f);
       }
     }
@@ -461,6 +474,22 @@ function cmdCommit(cwd, message, files, raw, amend, opts) {
   output({ committed: true, hash, reason: 'committed', type: commitType || null, safety_checks: safety.safetyChecks }, raw, hash || 'committed');
 }
 
+/**
+ * A summary's one-liner: the `one-liner` frontmatter key, else the bold line under the
+ * `# Phase … Summary` title, which is where the summary templates put it (none writes
+ * the key, so reading only the key gave `one_liner: null` for every summary PAN writes).
+ * Read on LF: the body match failed on a CRLF summary.
+ * @param {string} content - Whole summary.md
+ * @returns {string|null}
+ */
+function summaryOneLiner(content) {
+  const text = toLf(String(content || ''));
+  const fm = extractFrontmatter(text);
+  if (fm['one-liner']) return fm['one-liner'];
+  const m = text.replace(/^?---\n[\s\S]*?\n---\n/, '').match(/^#\s[^\n]*\n+\*\*([^\n*][^\n]*?)\*\*\s*$/m);
+  return m ? m[1].trim() : null;
+}
+
 /**
  * Extract structured data from a summary.md frontmatter with optional field filtering.
  * @param {string} cwd - Working directory path
@@ -500,10 +529,11 @@ function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
     });
   };
 
+
   // Build full result
   const fullResult = {
     path: summaryPath,
-    one_liner: frontmatter['one-liner'] || null,
+    one_liner: summaryOneLiner(content),
     key_files: frontmatter['key-files'] || [],
     tech_added: (frontmatter['tech-stack'] && frontmatter['tech-stack'].added) || [],
     patterns: frontmatter['patterns-established'] || [],
@@ -631,6 +661,7 @@ function cmdProgressRender(cwd, format, raw) {
   const milestone = getMilestoneInfo(cwd);
 
   const phases = [];
+  const verifiedPhases = []; // indexes into phases[] of phases with a verification file
   let totalPlans = 0;
   let totalSummaries = 0;
 
@@ -661,12 +692,25 @@ function cmdProgressRender(cwd, format, raw) {
       else if (summaryCount > 0) status = 'In Progress';
       else status = 'Planned';
 
+      if (phaseFiles.some(isVerificationFile)) verifiedPhases.push(phases.length);
       phases.push({ number: phaseNum, name: phaseName, plans: planCount, summaries: summaryCount, status });
     }
   } catch {
     // Phases directory does not exist or is unreadable; return empty progress
   }
 
+  // A verified phase whose covered files changed since the verified commit is
+  // stale (market-ideas M27). Not for the bar or the health score: the statusline
+  // calls the bar, which never shows it, and each check costs a git call.
+  if (format !== 'bar' && format !== 'health') {
+    for (const i of verifiedPhases) {
+      const f = verificationFreshness(cwd, phases[i].number);
+      if (f.error) continue;
+      phases[i].verification = f.state;
+      if (f.state === 'stale') phases[i].changed_since_verification = f.changed_since;
+    }
+  }
+
   const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
 
   if (format === 'health') {
@@ -682,7 +726,7 @@ function cmdProgressRender(cwd, format, raw) {
     rendered += '| Phase | Name | Plans | Status |\n';
     rendered += '|-------|------|-------|--------|\n';
     for (const phase of phases) {
-      rendered += `| ${phase.number} | ${phase.name} | ${phase.summaries}/${phase.plans} | ${phase.status} |\n`;
+      rendered += `| ${phase.number} | ${phase.name} | ${phase.summaries}/${phase.plans} | ${phase.status}${phase.verification === 'stale' ? ' (verification stale)' : ''} |\n`;
     }
     output({ rendered }, raw, rendered);
   } else if (format === 'bar') {
@@ -1027,9 +1071,85 @@ function shouldSkipTests(files) {
   return files.every(f => /\.md$/i.test(f));
 }
 
+// ─── version (market-ideas M29) ──────────────────────────────────────────────
+// The version of the PAN core that is running, where it lives, and, with --check,
+// the update state the SessionStart update check last recorded. Reads only local
+// files: the check itself (`npm view`, up to 10 s) stays in the hook's background
+// child, so `version --check` never waits on the network and never throws offline.
+
+// Where each install directory's update-check hook writes its cache: the hook's
+// `join(homeDir, '.claude', 'cache')` is rewritten to the runtime's GLOBAL config dir
+// (getConfigDirFromHome(runtime, true) in the installer).
+const UPDATE_CACHE_HOME_DIR = {
+  '.claude': ['.claude'], '.codex': ['.codex'], '.gemini': ['.gemini'],
+  '.opencode': ['.config', 'opencode'], opencode: ['.config', 'opencode'],
+  '.github': ['.copilot'], '.copilot': ['.copilot'],
+};
+
+/** The running core's version, its directory, and the install directory holding it. */
+function panVersionInfo(coreDir = path.resolve(__dirname, '..', '..')) {
+  let version = null;
+  // VERSION is written by the installer; a source checkout has the package.json instead.
+  try { version = fs.readFileSync(path.join(coreDir, 'VERSION'), 'utf8').trim() || null; } catch { /* not an install */ }
+  if (!version) {
+    try { version = JSON.parse(fs.readFileSync(path.join(coreDir, '..', 'package.json'), 'utf8')).version || null; } catch { /* neither */ }
+  }
+  return { version, core: toPosix(coreDir), install_dir: path.basename(path.dirname(coreDir)) };
+}
+
+/** The update-check cache for this install's runtime, else the newest one any runtime wrote. */
+function readUpdateCache(homeDir, installDir) {
+  const read = (segments) => {
+    const file = path.join(homeDir, ...segments, 'cache', 'pan-update-check.json');
+    try { return { file: toPosix(file), data: JSON.parse(fs.readFileSync(file, 'utf8')) }; } catch { return null; }
+  };
+  const own = UPDATE_CACHE_HOME_DIR[installDir] ? read(UPDATE_CACHE_HOME_DIR[installDir]) : null;
+  if (own) return own;
+  const seen = new Set();
+  const all = [];
+  for (const segs of Object.values(UPDATE_CACHE_HOME_DIR)) {
+    const key = segs.join('/');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const c = read(segs);
+    if (c) all.push(c);
+  }
+  all.sort((a, b) => (Number(b.data.checked) || 0) - (Number(a.data.checked) || 0));
+  return all[0] || null;
+}
+
+/**
+ * The update state from a cache record: `unchecked` (no check has run), `offline`
+ * (the last check could not reach npm), `available`, `current`, or `ahead` (this
+ * core is newer than npm's latest, e.g. a prerelease or a source checkout).
+ */
+function updateState(version, cache) {
+  if (!cache) return { state: 'unchecked', latest: null, checked_at: null, cache: null };
+  const checkedAt = Number(cache.data.checked) ? new Date(Number(cache.data.checked) * 1000).toISOString() : null;
+  const latest = cache.data.latest && cache.data.latest !== 'unknown' ? String(cache.data.latest) : null;
+  if (!latest) return { state: 'offline', latest: null, checked_at: checkedAt, cache: cache.file };
+  const { compareVersions } = require('./hygiene.cjs');
+  const cmp = version ? compareVersions(version, latest) : -1;
+  return { state: cmp < 0 ? 'available' : cmp > 0 ? 'ahead' : 'current', latest, checked_at: checkedAt, cache: cache.file };
+}
+
+function cmdVersion(_cwd, opts, raw) {
+  const info = panVersionInfo();
+  const result = { version: info.version, core: info.core, install_dir: info.install_dir, node: process.version };
+  if (opts.check) result.update = updateState(info.version, readUpdateCache(require('os').homedir(), info.install_dir));
+  const text = opts.check
+    ? `${info.version || 'unknown'} (${result.update.state}${result.update.latest ? `, npm latest ${result.update.latest}` : ''})`
+    : String(info.version || 'unknown');
+  output(result, raw, text);
+}
+
 // ---- Error patterns, session history, learnings — extracted to commands-learnings.cjs (re-exported below)
 
 module.exports = {
+  cmdVersion,
+  panVersionInfo,
+  readUpdateCache,
+  updateState,
   cmdGenerateSlug,
   cmdCurrentTimestamp,
   cmdListTodos,
@@ -1039,6 +1159,7 @@ module.exports = {
   cmdEstimateCost,
   cmdCommit,
   cmdSummaryExtract,
+  summaryOneLiner,
   cmdWebsearch,
   cmdProgressRender,
   cmdTodoComplete,

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

@@ -103,6 +103,102 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
   };
 }
 
+// What PAN reads beyond the keys buildConfigDefaults writes (market-ideas M26). The
+// rest of the known set is derived from the defaults, so a new default is known the
+// day it is added. Each entry has a reader: loadConfig's flat aliases and alias
+// sections (`planning.*`, `git.*`), the stop guard (`mode`, `workflow.stop_guard`),
+// the roadmapper and new-project (`depth`), memory-optimize (`memory`), and the
+// workflows that config-get `workflow.auto_advance`. tests/config-keys in
+// tests/config.test.cjs pins this list against the keys shipped code and prose use.
+const CONFIG_KEYS_BEYOND_DEFAULTS = Object.freeze({
+  top: Object.freeze(['research', 'plan_checker', 'verifier', 'nyquist_validation', 'mode', 'depth', 'planning', 'git',
+    'focus', 'model_overrides', 'effort_overrides', 'cost', 'cache', 'build', 'verification', 'concurrency', 'memory']),
+  sections: Object.freeze({
+    workflow: Object.freeze(['auto_advance', 'stop_guard']),
+    planning: Object.freeze(['commit_docs', 'search_gitignored']),
+    git: Object.freeze(['branching_strategy', 'phase_branch_template', 'milestone_branch_template']),
+  }),
+});
+// Sections whose keys are the user's own (model ids, agent names, file lists,
+// commands), so nothing below them is checked.
+const OPEN_CONFIG_SECTIONS = Object.freeze(['focus', 'model_overrides', 'effort_overrides', 'cost', 'cache', 'build', 'verification', 'concurrency', 'memory']);
+
+/** The known top-level keys, and the known keys one level inside each closed section. */
+function knownConfigKeys() {
+  const defaults = buildConfigDefaults(false, {});
+  const top = new Set([...Object.keys(defaults), ...CONFIG_KEYS_BEYOND_DEFAULTS.top]);
+  const sections = new Map();
+  for (const [k, v] of Object.entries(defaults)) {
+    if (v && typeof v === 'object' && !Array.isArray(v)) sections.set(k, new Set(Object.keys(v)));
+  }
+  for (const [k, list] of Object.entries(CONFIG_KEYS_BEYOND_DEFAULTS.sections)) {
+    sections.set(k, new Set([...(sections.get(k) || []), ...list]));
+  }
+  for (const k of OPEN_CONFIG_SECTIONS) sections.delete(k);
+  return { top, sections };
+}
+
+/**
+ * Whether PAN reads a dot-notation key path: the top-level key is known, and inside a
+ * closed section so is the second segment. Deeper segments are not checked.
+ * @param {string} keyPath
+ * @returns {boolean}
+ */
+function isKnownConfigPath(keyPath) {
+  const [head, sub] = String(keyPath).split('.');
+  const { top, sections } = knownConfigKeys();
+  if (!top.has(head)) return false;
+  return sub === undefined || !sections.has(head) || sections.get(head).has(sub);
+}
+
+/**
+ * The key paths in a parsed config.json that PAN does not read (market-ideas M26):
+ * unknown top-level keys, and unknown keys one level inside a closed section.
+ * @param {Object} config
+ * @returns {string[]}
+ */
+function unknownConfigKeys(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) return [];
+  const { top, sections } = knownConfigKeys();
+  const unknown = [];
+  for (const [k, v] of Object.entries(config)) {
+    if (!top.has(k)) { unknown.push(k); continue; }
+    const known = sections.get(k);
+    if (!known || !v || typeof v !== 'object' || Array.isArray(v)) continue;
+    for (const sub of Object.keys(v)) if (!known.has(sub)) unknown.push(`${k}.${sub}`);
+  }
+  return unknown;
+}
+
+/** The known key path nearest an unknown one (edit distance 2 or less), or null. */
+function nearestConfigKey(keyPath) {
+  const { top, sections } = knownConfigKeys();
+  const candidates = [...top];
+  for (const [k, subs] of sections) for (const s of subs) candidates.push(`${k}.${s}`);
+  const want = String(keyPath).split('.').slice(0, 2).join('.');
+  let best = null;
+  let bestD = 3;
+  for (const c of candidates) {
+    const d = editDistance(want, c);
+    if (d < bestD) { best = c; bestD = d; }
+  }
+  return best;
+}
+
+function editDistance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = tmp;
+    }
+  }
+  return row[b.length];
+}
+
 function cmdConfigEnsureSection(cwd, raw) {
   const configPath = path.join(planningPath(cwd), CONFIG_FILE);
 
@@ -216,6 +312,14 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
   try {
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
     const result = { updated: true, key: keyPath, value: parsedValue };
+    // A key PAN does not read is still written (a newer PAN, or the user's own
+    // note, may want it), but never silently: a typo used to look like a setting
+    // that took effect (market-ideas M26).
+    if (!isKnownConfigPath(keyPath)) {
+      const near = nearestConfigKey(keyPath);
+      result.warning = `unknown config key "${keyPath}": PAN does not read it` + (near ? `; did you mean "${near}"?` : '');
+      process.stderr.write(`pan-tools: ${result.warning}\n`);
+    }
     output(result, raw, `${keyPath}=${parsedValue}`);
   } catch (err) {
     // Config file could not be written — disk full, permissions, etc.
@@ -261,7 +365,8 @@ function cmdConfigGet(cwd, keyPath, raw) {
     error(`Key not found: ${keyPath}`);
   }
 
-  output(current, raw, String(current));
+  // An object or array prints as JSON under --raw: String() gave "[object Object]".
+  output(current, raw, current !== null && typeof current === 'object' ? JSON.stringify(current) : String(current));
 }
 
 // ─── Standards commands ─────────────────────────────────────────────────────
@@ -664,6 +769,12 @@ function cmdStandardsTools(cwd, standardId, raw) {
 
 module.exports = {
   buildConfigDefaults,
+  CONFIG_KEYS_BEYOND_DEFAULTS,
+  OPEN_CONFIG_SECTIONS,
+  knownConfigKeys,
+  isKnownConfigPath,
+  unknownConfigKeys,
+  nearestConfigKey,
   cmdConfigEnsureSection,
   cmdConfigSet,
   cmdConfigGet,

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

@@ -34,6 +34,9 @@ const RESEARCH_SUFFIX = '-research.md';
 const VERIFICATION_SUFFIX = '-verification.md';
 const UAT_SUFFIX = '-uat.md';
 const VALIDATION_SUFFIX = '-validation.md';
+// A phase's roadmap slice (roadmap slice --write), which phase agents and plans read
+// in place of the whole roadmap.md and requirements.md.
+const ROADMAP_SLICE_SUFFIX = '-roadmap-slice.md';
 
 // ─── File matching helpers ───────────────────────────────────────────────────
 
@@ -207,16 +210,18 @@ const STANDARDS_CATALOG = {
     level: 'foundational',
     url: 'https://owasp.org/www-project-top-ten/',
     checklist: [
-      'A01: Broken Access Control — verify authorization checks on all endpoints',
-      'A02: Cryptographic Failures — verify sensitive data encryption at rest and in transit',
-      'A03: Injection — verify input validation and parameterized queries',
-      'A04: Insecure Design — verify threat modeling and secure design patterns',
-      'A05: Security Misconfiguration — verify default credentials removed, headers set',
-      'A06: Vulnerable Components — verify dependency scanning, no known CVEs',
+      // The 2025 list (top10.owasp.org): until 2026-10-03 this held the 2021 list
+      // under the 2025 name (prompt audit, market-ideas M34). SSRF is now part of A01.
+      'A01: Broken Access Control — verify authorization checks on all endpoints, and allowlists for server-side requests (SSRF)',
+      'A02: Security Misconfiguration — verify default credentials removed, headers set',
+      'A03: Software Supply Chain Failures — verify dependency scanning, no known CVEs, pinned and verified packages and build tooling',
+      'A04: Cryptographic Failures — verify sensitive data encryption at rest and in transit',
+      'A05: Injection — verify input validation and parameterized queries',
+      'A06: Insecure Design — verify threat modeling and secure design patterns',
       'A07: Authentication Failures — verify MFA support, session management, credential storage',
-      'A08: Software and Data Integrity — verify CI/CD pipeline integrity, signed updates',
-      'A09: Logging and Monitoring — verify security events logged, alerts configured',
-      'A10: SSRF — verify server-side request validation, allowlists',
+      'A08: Software or Data Integrity Failures — verify CI/CD pipeline integrity, signed updates',
+      'A09: Security Logging and Alerting Failures — verify security events logged, alerts configured',
+      'A10: Mishandling of Exceptional Conditions — verify errors fail closed, are handled, and release resources',
     ],
   },
   'owasp-asvs-l1': {
@@ -574,17 +579,23 @@ const TOTAL_BUDGET_MIN = 5;
 const TOTAL_BUDGET_MAX = 5000;
 
 // Memory read/budget (ADR-0036 FW-2/FW-3): distill-and-select on the memory axis.
-const MEMORY_SELECT_BUDGET_TOKENS = 2000; // per-agent cap for cue-scoped memory injection
+const MEMORY_SELECT_BUDGET_TOKENS = 2000; // per-agent cap for a cue-scoped `memory select`
 const MEMORY_RECENCY_FLOOR = 5;           // always keep this many newest entries (recall never empty)
 const MEMORY_SOFT_CAP_MULT = 2;           // soft auto-compaction trigger = DEFAULT_MAX_ENTRIES × this
 const MEMORY_LOAD_WARN_TOKENS = 4000;     // memory-budget telemetry: warn threshold (absolute tokens)
 const MEMORY_LOAD_CRIT_TOKENS = 8000;     // memory-budget telemetry: critical threshold (absolute tokens)
 const MEMORY_LOAD_MAX_FRACTION = 0.15;    // memory-budget telemetry: max fraction of median agent input
-
-// Cached prompt context (ADR-0044). The files in CACHEABLE_CONTEXT_FILES are
-// re-read into EVERY agent call, so their combined size is the single largest
-// recurring cost in a PAN project — cache reads dominate token traffic by roughly
-// two orders of magnitude over generation. These thresholds mirror the
+// Cited, verified, expiring memory (memory optimisation O4; the Copilot Memory
+// pattern). An entry not used for this many days is no longer selected and
+// `memory prune` archives it; `memory select --mark-used` refreshes it.
+const MEMORY_EXPIRE_DAYS = 60;
+const MEMORY_CITED_FILE_MAX_BYTES = 2 * 1024 * 1024; // larger cited files: existence is the evidence
+
+// Stable planning files (ADR-0044): what `cache prime`, `context-budget` and
+// hygiene's cache-context check measure. state.md among them is re-read on every
+// agent call, the largest recurring cost in a PAN project; roadmap.md and
+// requirements.md are read whole only by the roadmapper and milestone work, since
+// phase agents read `roadmap slice` (O2). These thresholds mirror the
 // MEMORY_LOAD_* pattern above: measured, classified, and surfaced.
 const CACHE_BLOCK_WARN_TOKENS = 15000;    // cached context block: warn threshold (absolute tokens)
 const CACHE_BLOCK_CRIT_TOKENS = 25000;    // cached context block: critical threshold
@@ -778,6 +789,7 @@ module.exports = {
   VERIFICATION_SUFFIX,
   UAT_SUFFIX,
   VALIDATION_SUFFIX,
+  ROADMAP_SLICE_SUFFIX,
   // File matchers
   isPlanFile,
   isSummaryFile,
@@ -860,6 +872,8 @@ module.exports = {
   MEMORY_LOAD_WARN_TOKENS,
   MEMORY_LOAD_CRIT_TOKENS,
   MEMORY_LOAD_MAX_FRACTION,
+  MEMORY_EXPIRE_DAYS,
+  MEMORY_CITED_FILE_MAX_BYTES,
   // Hygiene
   CACHE_BLOCK_WARN_TOKENS,
   CACHE_BLOCK_CRIT_TOKENS,

package/pan-wizard-core/bin/lib/context-budget.cjs

@@ -267,8 +267,8 @@ function cmdContextBudget(cwd, raw) {
     }
   }
 
-  // E-8: cache metrics — surface how much of the total context would be
-  // served from prompt cache when Opus 4.7 cache_control is active.
+  // E-8: cache metrics — how much of the total context is the stable set that
+  // agents re-read, which the host serves from its prompt cache when it can.
   const { buildCachedContext } = require('./core.cjs');
   let cache = null;
   try {
@@ -277,10 +277,10 @@ function cmdContextBudget(cwd, raw) {
     const eligiblePct = totalTokens > 0
       ? Math.round((cacheTokens / totalTokens) * 1000) / 10
       : 0;
-    // The cached block is re-read into EVERY agent call, so its size is the
-    // project's largest recurring cost. This used to be measured and reported
-    // with no threshold attached, which meant a block that had grown to ~28k
-    // tokens of mostly closed history looked exactly like a healthy one.
+    // The stable planning files; state.md among them is re-read on every agent
+    // call, the project's largest recurring cost. This used to be measured and
+    // reported with no threshold attached, which meant a block that had grown to
+    // ~28k tokens of mostly closed history looked exactly like a healthy one.
     // Classifying it is what turns the measurement into a signal.
     const { CACHE_BLOCK_WARN_TOKENS, CACHE_BLOCK_CRIT_TOKENS, CACHE_FILE_WARN_TOKENS } = require('./constants.cjs');
     const largest = cached.blocks
@@ -292,12 +292,15 @@ function cmdContextBudget(cwd, raw) {
     else if (cacheTokens >= CACHE_BLOCK_CRIT_TOKENS) cacheStatus = 'critical';
     else if (cacheTokens >= CACHE_BLOCK_WARN_TOKENS) cacheStatus = 'warn';
 
+    // PAN primes no cache (ADR-0023, amended): an absent block means nothing to
+    // measure, not that the host stops caching.
     const advice = cacheStatus === 'absent'
-      ? 'no cacheable context files — every agent call re-sends its context uncached'
+      ? 'none of the stable planning files exist yet, so there is nothing to measure'
       : cacheStatus === 'ok'
         ? null
-        : `cached context is re-read on every agent call; largest file ${largest[0].path} (~${largest[0].tokens} tokens)`
-          + (largest[0].path.endsWith('state.md') ? ' — run `pan-tools state compact`' : '');
+        : `stable planning files past the budget; largest file ${largest[0].path} (~${largest[0].tokens} tokens)`
+          + (largest[0].path.endsWith('state.md') ? ' — re-read on every agent call; run `pan-tools state compact`'
+            : largest[0].path.endsWith('roadmap.md') ? ' — read whole by the roadmapper and milestone work; run `pan-tools roadmap compact`' : '');
 
     // Lifetime signal from the ledger (suspect rows excluded — they carry
     // poisoned counters, not real writes). Absent ledger → zero rows, no advice.