pan-wizard 3.32.0 → 3.34.0

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

@@ -22,6 +22,7 @@ const {
 const { extractFrontmatter, extractPriorityEffort } = require('./frontmatter.cjs');
 const { enumerateRoadmapPhases } = require('./roadmap.cjs');
 const { readErrorPatterns } = require('./commands.cjs');
+const { weeklyLimitStop } = require('./cost.cjs');
 const { planningPath, listPhaseDirs, classifyPhaseStatus, filterPlanFiles, filterSummaryFiles, planningRel } = require('./utils.cjs');
 
 // ─── Scan helpers ───────────────────────────────────────────────────────────
@@ -302,10 +303,13 @@ function allocateBudget(items, budget, mode) {
   } else if (mode === 'features') {
     const { picked: mPicked, used: mUsed } = allocatePass(items, budget, { maxPriority: 0, minPriority: 0, track: 'mandatory' });
     addToBatch(mPicked);
-    const featureBudget = Math.floor(budget * FEATURE_RATIO);
+    // The feature/stability split shares what the P0 pass left: splitting the
+    // whole budget again let a batch reach nearly twice the budget.
+    const rest = budget - mUsed;
+    const featureBudget = Math.floor(rest * FEATURE_RATIO);
     const { picked: fPicked, used: fUsed } = allocatePass(items, featureBudget, { minPriority: 3, maxPriority: 5, track: 'feature', exclude: batchIds });
     addToBatch(fPicked);
-    const { picked: sPicked, used: sUsed } = allocatePass(items, budget - featureBudget, { minPriority: 1, maxPriority: 2, track: 'stability', exclude: batchIds });
+    const { picked: sPicked, used: sUsed } = allocatePass(items, rest - featureBudget, { minPriority: 1, maxPriority: 2, track: 'stability', exclude: batchIds });
     addToBatch(sPicked);
     allocated = mUsed + fUsed + sUsed;
   } else {
@@ -920,9 +924,14 @@ function focusAutoUpdate(cwd, raw, getVal) {
   run.totals.tests_current = cycle.tests_after;
   run.status = AUTORUN_STATUSES.IN_PROGRESS;
 
-  const stopReason = determineStopReason(cycle, run);
+  // The host's 7-day usage window (Claude Code subscriptions, read from what PAN's
+  // status line last saw): past cost.weekly_limit_stop_pct the run stops resumable,
+  // so the rest of the window stays the user's. No fresh reading never stops it.
+  const weekly = weeklyLimitStop(cwd);
+  cycle.weekly_limit_used_pct = weekly.seven_day_used_pct;
+  const stopReason = determineStopReason(cycle, run) || (weekly.stop ? 'weekly_limit' : null);
   if (stopReason) {
-    run.status = stopReason === 'regression' ? AUTORUN_STATUSES.STOPPED : AUTORUN_STATUSES.COMPLETED;
+    run.status = stopReason === 'regression' || stopReason === 'weekly_limit' ? AUTORUN_STATUSES.STOPPED : AUTORUN_STATUSES.COMPLETED;
     run.stop_reason = stopReason;
   }
 

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, output, error, escapeRegex } = require('./core.cjs');
+const { safeReadFile, output, error, escapeRegex, toLf, dominantEol, withEol } = require('./core.cjs');
 const { FIELD_VALUE_RE, PRIORITY_LEVELS, EFFORT_SIZES } = require('./constants.cjs');
 
 // --- Inline array rendering thresholds -------------------------------------------
@@ -169,7 +169,21 @@ function renderYamlEntry(lines, key, value, depth) {
       lines.push(`${indent}${key}:`);
       const itemIndent = '  '.repeat(depth + 1);
       for (const item of value) {
-        lines.push(`${itemIndent}- ${quoteIfNeeded(item)}`);
+        if (item && typeof item === 'object' && !Array.isArray(item)) {
+          // A list of maps (a plan's must_haves artifacts and key_links): the first
+          // key on the dash line, the rest under it. Written as a scalar, each item
+          // came out "[object Object]".
+          const entries = Object.entries(item).filter(([, v]) => v !== null && v !== undefined);
+          entries.forEach(([k, v], idx) => {
+            // An array value goes out as a flow sequence of JSON strings, which the
+            // parser reads back as an array (`exports: ["GET", "POST"]`).
+            const text = Array.isArray(v) ? `[${v.map((x) => JSON.stringify(String(x))).join(', ')}]`
+              : quoteIfNeeded(typeof v === 'object' ? JSON.stringify(v) : v);
+            lines.push(`${itemIndent}${idx === 0 ? '- ' : '  '}${k}: ${text}`);
+          });
+        } else {
+          lines.push(`${itemIndent}- ${quoteIfNeeded(item)}`);
+        }
       }
     }
   } else if (typeof value === 'object') {
@@ -201,34 +215,76 @@ function quoteIfNeeded(value) {
  */
 function spliceFrontmatter(content, newObj) {
   const yamlStr = reconstructFrontmatter(newObj);
-  const match = content.match(/^---\n[\s\S]+?\n---/);
+  // Match on LF and give the file back in its own ending. The LF-only match
+  // missed the block in a CRLF file, so `frontmatter set` and `merge` stacked a
+  // second frontmatter on top of the first instead of replacing it.
+  const eol = dominantEol(content);
+  const text = toLf(content);
+  const match = text.match(/^---\n[\s\S]+?\n---/);
   if (match) {
-    return `---\n${yamlStr}\n---` + content.slice(match[0].length);
+    return withEol(`---\n${yamlStr}\n---` + text.slice(match[0].length), eol);
+  }
+  return withEol(`---\n${yamlStr}\n---\n\n` + text, eol);
+}
+
+/**
+ * A YAML scalar as written in a must_haves value: a double-quoted one unescapes `\\`
+ * and `\"`, a single-quoted one `''`, a plain one is taken as written. The raw `\\.`
+ * of the shipped key-link example reached `new RegExp` in `verify key-links`, so
+ * `pattern: "prisma\\.message\\.(find|create)"` never matched.
+ * @param {string} raw - The value text after `key:` (or after `- `)
+ * @returns {string}
+ */
+function yamlScalar(raw) {
+  const s = String(raw).trim();
+  // A flow sequence (`exports: ["GET", "POST"]`, as the plan template writes it) is an
+  // array of scalars: taken whole it was one string, and `verify artifacts` then
+  // reported every export missing.
+  if (s.length >= 2 && s.startsWith('[') && s.endsWith(']')) {
+    const items = [];
+    let cur = '';
+    let quote = null;
+    const inner = s.slice(1, -1);
+    for (let i = 0; i < inner.length; i++) {
+      const c = inner[i];
+      if (quote) {
+        cur += c;
+        if (c === '\\' && quote === '"' && i + 1 < inner.length) cur += inner[++i];
+        else if (c === quote) quote = null;
+      } else if (c === '"' || c === "'") { quote = c; cur += c; }
+      else if (c === ',') { items.push(cur); cur = ''; }
+      else cur += c;
+    }
+    items.push(cur);
+    return items.map((x) => yamlScalar(x)).filter((x) => x !== '');
   }
-  return `---\n${yamlStr}\n---\n\n` + content;
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) return s.slice(1, -1).replace(/\\(["\\])/g, '$1');
+  if (s.length >= 2 && s.startsWith("'") && s.endsWith("'")) return s.slice(1, -1).replace(/''/g, "'");
+  return s;
 }
 
 /**
  * Parse a specific block (artifacts, key_links, truths) from must_haves in raw YAML frontmatter.
  *
- * Block structure being parsed:
- *   The must_haves section is a 3-level nested YAML structure:
- *     must_haves:           (level 1 -- 2-space indent)
- *       artifacts:          (level 2 -- 4-space indent, the blockName)
- *         - path: foo       (level 3 -- 6-space indent, list items)
- *           provides: bar   (level 3+ -- 8-space indent, continuation k-v pairs)
+ * Block structure being parsed (indents are relative, never fixed columns):
+ *     must_haves:
+ *       artifacts:          (the blockName, deeper than must_haves)
+ *         - path: foo       (list items)
+ *           provides: bar   (continuation k-v pairs, deeper than the item's dash)
  *
- *   This function finds the named block at the 4-space level, then parses
- *   its list items (at 6-space indent) and their nested key-value pairs
- *   (at 8+ space indent) into an array of objects or strings.
+ *   This function finds the named block under must_haves, then parses its list
+ *   items and their nested key-value pairs into an array of objects or strings.
+ *   Values go through yamlScalar.
  *
  * @param {string} content - Full markdown content with frontmatter
  * @param {string} blockName - Block name to extract (e.g., "artifacts", "key_links")
  * @returns {Array} Parsed array of block items (objects or strings)
  */
 function parseMustHavesBlock(content, blockName) {
-  // Extract raw YAML between --- delimiters
-  const fmMatch = content.match(/^---\n([\s\S]+?)\n---/);
+  // Extract raw YAML between --- delimiters. On LF: a CRLF plan (every Windows
+  // field project) matched nothing here, so its must_haves read as empty and the
+  // reconcile gate below trusted the verdict again, as it did before the indent fix.
+  const fmMatch = toLf(content).match(/^---\n([\s\S]+?)\n---/);
   if (!fmMatch) return [];
 
   const yaml = fmMatch[1];
@@ -290,18 +346,18 @@ function parseMustHavesBlock(content, blockName) {
 
       const body = dashMatch[2];
       // A plain string item — no `key: value` shape.
-      const kvMatch = body.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+      const kvMatch = body.match(/^(\w+):\s*(.*?)\s*$/);
       if (kvMatch) {
         currentItem = {};
-        currentItem[kvMatch[1]] = kvMatch[2];
+        currentItem[kvMatch[1]] = yamlScalar(kvMatch[2]);
       } else {
-        currentItem = body.replace(/^"|"$/g, '').trim();
+        currentItem = yamlScalar(body);
       }
     } else if (currentItem && typeof currentItem === 'object') {
       // Continuation key-value: deeper than the item's dash (properties of it)
-      const kvMatch = line.match(/^\s+(\w+):\s*"?([^"]*)"?\s*$/);
+      const kvMatch = line.match(/^\s+(\w+):\s*(.*?)\s*$/);
       if (kvMatch) {
-        const val = kvMatch[2];
+        const val = yamlScalar(kvMatch[2]);
         // Coerce pure-integer strings to numbers for convenience
         currentItem[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
       }
@@ -309,7 +365,7 @@ function parseMustHavesBlock(content, blockName) {
       // already deeper than the list-item dash (a shallower one would have been
       // treated as a new item above), so relative depth alone identifies it —
       // no fixed column.
-      const arrMatch = line.match(/^\s+-\s+"?([^"]+)"?\s*$/);
+      const arrMatch = line.match(/^\s+-\s+(.+?)\s*$/);
       if (arrMatch) {
         // Convert the most recently added key's scalar value into an array,
         // then append this item to that array
@@ -318,7 +374,7 @@ function parseMustHavesBlock(content, blockName) {
         if (lastKey && !Array.isArray(currentItem[lastKey])) {
           currentItem[lastKey] = currentItem[lastKey] ? [currentItem[lastKey]] : [];
         }
-        if (lastKey) currentItem[lastKey].push(arrMatch[1]);
+        if (lastKey) currentItem[lastKey].push(yamlScalar(arrMatch[1]));
       }
     }
   }
@@ -354,6 +410,27 @@ const FRONTMATTER_SCHEMAS = {
   verification: { required: ['phase', 'verified', 'status', 'score'] },
 };
 
+/**
+ * extractFrontmatter cannot read a list of maps: each must_haves artifact and key
+ * link came back as the string of its first line (`path: "src/x.ts`), so the plan
+ * checker and verify-phase, which read them through `frontmatter get`, got no
+ * objects. parseMustHavesBlock reads both blocks by relative indent.
+ * @param {object} fm - extractFrontmatter output
+ * @param {string} content - the file it came from
+ * @returns {object} fm, with must_haves.artifacts and .key_links as objects
+ */
+function withParsedMustHaves(fm, content) {
+  const mh = fm && fm.must_haves;
+  if (!mh || typeof mh !== 'object' || Array.isArray(mh)) return fm;
+  const fixed = { ...mh };
+  for (const block of ['artifacts', 'key_links']) {
+    if (!(block in fixed)) continue;
+    const parsed = parseMustHavesBlock(content, block);
+    if (parsed.length) fixed[block] = parsed;
+  }
+  return { ...fm, must_haves: fixed };
+}
+
 /**
  * Get frontmatter from a file, optionally filtered to a single field.
  * @param {string} cwd - Working directory path
@@ -367,7 +444,7 @@ function cmdFrontmatterGet(cwd, filePath, field, raw) {
   const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
   const content = safeReadFile(fullPath);
   if (!content) { output({ error: 'File not found', path: filePath }, raw); return; }
-  const fm = extractFrontmatter(content);
+  const fm = withParsedMustHaves(extractFrontmatter(content), content);
   if (field) {
     const value = fm[field];
     if (value === undefined) { output({ error: 'Field not found', field }, raw); return; }
@@ -395,7 +472,9 @@ function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
   } catch {
     output({ error: 'File not found', path: filePath }, raw); return;
   }
-  const fm = extractFrontmatter(content);
+  // The block is rewritten whole, so a plan's must_haves lists of maps must be read
+  // as maps: extractFrontmatter alone flattened each item to its first line.
+  const fm = withParsedMustHaves(extractFrontmatter(content), content);
   let parsedValue;
   // Attempt JSON parse so callers can pass structured values (arrays, objects);
   // fall back to raw string if the value is not valid JSON
@@ -427,7 +506,7 @@ function cmdFrontmatterMerge(cwd, filePath, data, raw) {
   } catch {
     output({ error: 'File not found', path: filePath }, raw); return;
   }
-  const fm = extractFrontmatter(content);
+  const fm = withParsedMustHaves(extractFrontmatter(content), content);
   let mergeData;
   // Parse the JSON data string; abort with error if the caller passed invalid JSON
   try { mergeData = JSON.parse(data); } catch { error('Invalid JSON for --data'); return; }

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

@@ -40,10 +40,12 @@ const {
   HYGIENE_TMP_AGE_MS,
   CHARS_PER_TOKEN,
   STATE_FILE,
+  ROADMAP_FILE,
+  REQUIREMENTS_FILE,
 } = require('./constants.cjs');
 const { planningPath, planningRel, detectPlanningModel } = require('./utils.cjs');
 const { detectForeignPlanningTree } = require('./foreign-planning.cjs');
-const { listMemoryAgents, readMemory, compactMemory } = require('./memory.cjs');
+const { listMemoryAgents, readMemory, compactMemory, pruneMemory, RESERVED_MEMORY_NAMES } = require('./memory.cjs');
 const { readRecords, isSuspectRecord, METRICS_DIR, TOKENS_FILE } = require('./cost.cjs');
 const { assessCacheTtl } = require('./context-budget.cjs');
 const { planningRootRel, planningRoots, withPlanningRoot, describePlanningRoot, TRACKS_DIR } = require('./planning-root.cjs');
@@ -223,22 +225,131 @@ function checkTmpOrphans(cwd, now = Date.now()) {
   return { findings };
 }
 
-/** H-4: per-agent memory logs past the entry cap (compaction never ran). */
+/**
+ * H-4: per-agent memory logs — past the entry cap (compaction never ran), holding
+ * entries `memory select` no longer returns (O4: cited code gone, or unused past the
+ * expiry window), and files in the folder that are not read as memory at all.
+ */
 function checkMemoryLogs(cwd) {
   const findings = [];
   const { agents } = listMemoryAgents(cwd);
   for (const a of agents) {
     const mem = readMemory(cwd, a.agent);
     if (!mem || !Array.isArray(mem.entries)) continue;
-    if (mem.entries.length <= MEMORY_ENTRY_CAP) continue;
-    findings.push(mkFinding('memory-bloat', 'warn',
-      planningRel('memory', `${a.agent}.md`),
-      `${mem.entries.length} entries exceeds cap ${MEMORY_ENTRY_CAP} — whole-file reads flood context`,
-      { action: 'compact-memory', agent: a.agent }));
+    const rel = planningRel('memory', `${a.agent}.md`);
+    if (mem.entries.length > MEMORY_ENTRY_CAP) {
+      findings.push(mkFinding('memory-bloat', 'warn', rel,
+        `${mem.entries.length} entries exceeds cap ${MEMORY_ENTRY_CAP} — compaction keeps the newest`,
+        { action: 'compact-memory', agent: a.agent }));
+    }
+    const prune = pruneMemory(cwd, a.agent);
+    const stale = prune.agents ? prune.agents[0].archive : [];
+    if (stale.length) {
+      const gone = stale.filter(x => x.reason.startsWith('cited code gone')).length;
+      findings.push(mkFinding('memory-stale', 'warn', rel,
+        `${stale.length} entr${stale.length === 1 ? 'y is' : 'ies are'} stale or expired `
+        + `(${gone} cite code that is gone, ${stale.length - gone} unused for ${prune.expire_days} days) — `
+        + '`memory prune` archives them',
+        { action: 'prune-memory', agent: a.agent }));
+    }
+  }
+  // A file in the folder with no `## Entries` list is never read as memory (PAN's
+  // own archives aside): say so rather than let it look like memory.
+  for (const n of listMemoryAgents(cwd).not_loaded || []) {
+    if (RESERVED_MEMORY_NAMES.includes(n.file.slice(0, -3).toLowerCase())) continue;
+    findings.push(mkFinding('memory-format', 'info', planningRel('memory', n.file),
+      `${n.reason}, so \`memory select\` and \`/pan:knowledge\` do not read it as memory — move the rules that still hold into an agent log with \`memory append <agent> "<rule>" --cites <path>\``,
+      null));
   }
   return { findings };
 }
 
+// ─── Host memory (memory optimisation O10) ───────────────────────────────────
+//
+// Cross-session memory accumulates in the host, not in PAN (F7): Claude Code's auto
+// memory keeps an index, MEMORY.md, and loads only its first 200 lines or 25 KB at
+// the start of every session. PAN does not own that store (MI-010) and never writes
+// it; it reads the index and reports what the host will silently cut, and index
+// lines that hold content where a one-line pointer belongs.
+
+const HOST_INDEX_MAX_LINES = 200;
+const HOST_INDEX_MAX_BYTES = 25000;      // "25KB": the smaller reading, so a warning is never late
+const HOST_INDEX_LINE_MAX_CHARS = 300;   // a pointer line is ~100–150 characters
+
+/** The directory Claude Code keys a project's auto memory by: the git repository root, the main one for a worktree. */
+function hostMemoryProjectRoot(cwd) {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    const dotGit = path.join(dir, '.git');
+    let st = null;
+    try { st = fs.statSync(dotGit); } catch { /* keep walking */ }
+    if (st && st.isDirectory()) return dir;
+    if (st && st.isFile()) {
+      // A worktree: `.git` is a file naming <main>/.git/worktrees/<name>.
+      const m = (safeReadFile(dotGit) || '').match(/^gitdir:\s*(.+?)\s*$/m);
+      if (m) {
+        const gitdir = path.resolve(dir, m[1]);
+        const i = gitdir.split(path.sep).lastIndexOf('.git');
+        if (i > 0 && gitdir.split(path.sep)[i + 1] === 'worktrees') return gitdir.split(path.sep).slice(0, i).join(path.sep);
+      }
+      return dir;
+    }
+    const up = path.dirname(dir);
+    if (up === dir) return path.resolve(cwd);
+    dir = up;
+  }
+}
+
+/** Claude Code's auto-memory directory for a project, and how it was found. */
+function hostMemoryDir(cwd, homeDir) {
+  const claudeDir = '.claude';
+  for (const f of [path.join(cwd, claudeDir, 'settings.local.json'), path.join(cwd, claudeDir, 'settings.json'), path.join(homeDir, claudeDir, 'settings.json')]) {
+    let s = null;
+    try { s = JSON.parse(safeReadFile(f) || 'null'); } catch { /* unreadable settings */ }
+    if (s && typeof s.autoMemoryDirectory === 'string' && s.autoMemoryDirectory.trim()) {
+      const v = s.autoMemoryDirectory.trim();
+      return { dir: path.resolve(v.startsWith('~/') ? path.join(homeDir, v.slice(2)) : v), display: v, source: 'autoMemoryDirectory' };
+    }
+  }
+  const key = hostMemoryProjectRoot(cwd).replace(/[^A-Za-z0-9]/g, '-');
+  return { dir: path.join(homeDir, claudeDir, 'projects', key, 'memory'), display: `~/${claudeDir}/projects/${key}/memory`, source: 'default' };
+}
+
+/**
+ * H-11: Claude Code's auto-memory index. Read-only; never fixable by PAN.
+ * @param {string} cwd
+ * @param {{homeDir?: string}} [opts]
+ */
+function checkHostMemory(cwd, opts = {}) {
+  const findings = [];
+  const home = opts.homeDir || require('os').homedir();
+  const loc = hostMemoryDir(cwd, home);
+  const text = safeReadFile(path.join(loc.dir, 'MEMORY.md'));
+  if (text == null) return { findings, host_memory: { dir: loc.display, index: false } };
+  const lines = text.replace(/\r\n/g, '\n').replace(/\n$/, '').split('\n');
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const rel = `${loc.display}/MEMORY.md`;
+  const overLines = lines.length > HOST_INDEX_MAX_LINES;
+  const overBytes = bytes > HOST_INDEX_MAX_BYTES;
+  if (overLines || overBytes) {
+    findings.push(mkFinding('host-memory', 'warn', rel,
+      `Claude Code's memory index is ${lines.length} lines / ${(bytes / 1024).toFixed(1)} KB; it loads only the first ${HOST_INDEX_MAX_LINES} lines or 25 KB at session start, so the rest is never seen. `
+      + 'Keep one line per memory there and move detail into topic files (PAN does not edit this store)',
+      null));
+  } else if (lines.length >= HOST_INDEX_MAX_LINES * 0.9 || bytes >= HOST_INDEX_MAX_BYTES * 0.9) {
+    findings.push(mkFinding('host-memory', 'info', rel,
+      `Claude Code's memory index is ${lines.length} lines / ${(bytes / 1024).toFixed(1)} KB, near the ${HOST_INDEX_MAX_LINES}-line / 25 KB load limit`,
+      null));
+  }
+  const long = lines.filter(l => l.length > HOST_INDEX_LINE_MAX_CHARS);
+  if (long.length) {
+    findings.push(mkFinding('host-memory', 'info', rel,
+      `${long.length} index line${long.length === 1 ? ' holds' : 's hold'} content instead of a pointer (longest ${Math.max(...long.map(l => l.length))} characters; a pointer is one short line to a topic file)`,
+      null));
+  }
+  return { findings, host_memory: { dir: loc.display, source: loc.source, index: true, lines: lines.length, bytes, long_lines: long.length } };
+}
+
 /**
  * Thousands separator that does not depend on the host locale. `toLocaleString()`
  * emits a narrow no-break space in some locales and a comma in others, which
@@ -407,17 +518,18 @@ function checkCachedContext(cwd) {
   try { cached = buildCachedContext(cwd); } catch { return { findings }; }
   if (!cached || !Array.isArray(cached.blocks)) return { findings };
 
-  // An empty block is not "small" — it means this project gets NO prompt
-  // caching at all, which is worth saying out loud rather than reporting as a
-  // healthy zero. But only for a tree that HAS planning content: a freshly
-  // scaffolded `.planning/phases/` has nothing to cache yet, and reporting that
-  // as a finding is noise on every new project. The signal is "you have
-  // planning docs and none of them are cached", not "you have no docs".
+  // An empty block is not "small" — it means this check measures nothing, which
+  // is worth saying rather than reporting a healthy zero. (PAN primes no cache,
+  // ADR-0023 amended: the host caches each prompt prefix by itself, so this is
+  // about measurement, not about caching.) But only for a tree that HAS planning
+  // content: a freshly scaffolded `.planning/phases/` has nothing to measure yet,
+  // and reporting that is noise on every new project.
   if (cached.blocks.length === 0) {
     if (planningDocCount(cwd) > 0) {
       findings.push(mkFinding('cache-context', 'info', planningRel(),
-        'planning docs exist but none are cacheable — every agent call re-sends its context uncached. '
-        + 'Add project.md/standards.md, or list stable docs under config.json cache.extra_files',
+        'planning docs exist but none of the stable files this check measures (project.md, requirements.md, '
+        + 'roadmap.md, state.md, standards.md), so it has nothing to read. List stable docs under config.json '
+        + 'cache.extra_files to measure them',
         null));
     }
     return { findings };
@@ -429,7 +541,8 @@ function checkCachedContext(cwd) {
     findings.push(mkFinding('cache-context', severity, planningRel(),
       `cached context block is ~${fmtTokens(blockTokens)} tokens across ${cached.blocks.length} file(s) `
       + `(warn ${fmtTokens(CACHE_BLOCK_WARN_TOKENS)}, critical ${fmtTokens(CACHE_BLOCK_CRIT_TOKENS)}) — `
-      + 're-read on every agent call, so this is the project\'s largest recurring cost',
+      + 'state.md is re-read on every agent call; roadmap.md and requirements.md whole by the roadmapper and milestone work '
+      + '(phase agents read `roadmap slice`)',
       null));
   }
 
@@ -437,6 +550,27 @@ function checkCachedContext(cwd) {
     const tokens = Math.ceil((b.content || '').length / CHARS_PER_TOKEN);
     if (tokens < CACHE_FILE_WARN_TOKENS) continue;
     const isState = String(b.path).endsWith(STATE_FILE);
+    const isRoadmap = String(b.path).endsWith(ROADMAP_FILE);
+    const isRequirements = String(b.path).endsWith(REQUIREMENTS_FILE);
+
+    // The roadmap and requirements are read whole only by the roadmapper and the
+    // milestone workflows now; phase agents get `roadmap slice` (O2). A roadmap
+    // with shipped phases past the most recent ones can be compacted (O3).
+    if (isRoadmap || isRequirements) {
+      let fix = null;
+      let detail = `~${fmtTokens(tokens)} tokens, read whole by the roadmapper and milestone work (phase agents read \`roadmap slice\`)`;
+      if (isRoadmap) {
+        const archivable = roadmapCompactionAvailable(cwd);
+        if (archivable > 0) {
+          fix = { action: 'compact-roadmap' };
+          detail += ` — ${archivable} shipped phase section(s) can move to roadmap-history.md (\`roadmap compact\`)`;
+        }
+      } else {
+        detail += ' — `/pan:milestone-done` archives a shipped milestone\'s requirements to `milestones/` and starts the next milestone\'s file fresh';
+      }
+      findings.push(mkFinding('cache-context', 'warn', b.path, detail, fix));
+      continue;
+    }
 
     // A finding may only advertise `auto-fixable` when running the fix would
     // actually change something. state.md stays over the threshold once its
@@ -491,6 +625,12 @@ function stateCompactionAvailable(cwd) {
   }
 }
 
+/** Same rule for roadmap.md: offer `compact-roadmap` only when it would archive something. */
+function roadmapCompactionAvailable(cwd) {
+  // Lazy for the same reason as state-compact: keep hygiene off a load-time cycle.
+  return require('./roadmap-compact.cjs').roadmapCompactionAvailable(cwd);
+}
+
 /** H-7: fragment .planning — artifacts present but no project spine. Report-only. */
 function checkPlanningFragment(cwd) {
   const findings = [];
@@ -572,9 +712,11 @@ function scanHygiene(cwd, opts) {
   // matter how many trees we sweep, or a four-track repo reports the same
   // drift four times.
   const version = checkVersionAlignment(cwd);
+  // The host's memory index is one per project too, whatever the tracks.
+  const host = checkHostMemory(cwd, { homeDir: opts?.homeDir });
   const roots = planningRoots(cwd, { allTracks: !!opts?.allTracks });
 
-  const findings = [...version.findings];
+  const findings = [...version.findings, ...host.findings];
   const scanned = [];
   let planningExists = false;
 
@@ -601,6 +743,7 @@ function scanHygiene(cwd, opts) {
   return {
     findings,
     installs: version.installs,
+    host_memory: host.host_memory,
     latest_version: version.latest_version,
     planning_exists: planningExists,
     // What was actually looked at. Present in every scan, not just --all-tracks:
@@ -653,6 +796,12 @@ function applyFix(cwd, finding) {
         if (r.error) return { applied: false, detail: r.error };
         return { applied: true, detail: `compacted to ${r.kept ?? r.entries ?? 'cap'} entries` };
       }
+      case 'prune-memory': {
+        const r = pruneMemory(cwd, fix.agent, { apply: true });
+        if (r.error) return { applied: false, detail: r.error };
+        if (!r.applied) return { applied: false, detail: 'nothing stale or expired any more' };
+        return { applied: true, detail: `archived ${r.archivable} entr${r.archivable === 1 ? 'y' : 'ies'} to ${r.archive_dir}/` };
+      }
       case 'compact-state': {
         // Required lazily: state-compact pulls in state.cjs, which pulls in core
         // — importing it at module load would put hygiene on that cycle.
@@ -665,6 +814,16 @@ function applyFix(cwd, finding) {
           detail: `archived ${r.archived.length} section(s) to ${r.history_path} — saves ~${r.tokens_saved_per_call} tokens per agent call`,
         };
       }
+      case 'compact-roadmap': {
+        const { compactRoadmap } = require('./roadmap-compact.cjs');
+        const r = compactRoadmap(cwd, { apply: true });
+        if (!r.found) return { applied: false, detail: 'roadmap.md not found' };
+        if (!r.applied) return { applied: false, detail: 'no shipped phase past the most recent ones' };
+        return {
+          applied: true,
+          detail: `archived ${r.archived.length} shipped phase section(s) to ${r.history_path} — roadmap.md ~${r.tokens_before - r.tokens_after} tokens smaller`,
+        };
+      }
       case 'quarantine-ledger': {
         const stamp = new Date().toISOString().slice(0, 10);
         const dest = `${abs}.quarantined-${stamp}`;
@@ -832,6 +991,8 @@ module.exports = {
   checkLegacyUppercase,
   checkTmpOrphans,
   checkMemoryLogs,
+  checkHostMemory,
+  hostMemoryDir,
   checkCostLedger,
   checkStaleTraces,
   checkStaleReports,

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, normalizePhaseName, toPosix, output, error, scanPendingTodos, isGitRepo, execGit } = require('./core.cjs');
+const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, normalizePhaseName, toPosix, output, error, scanPendingTodos, isGitRepo, execGit, escapeTableCell } = require('./core.cjs');
 const { PHASES_DIR, CODEBASE_DIR, QUICK_DIR, MILESTONES_DIR, STATE_FILE, ROADMAP_FILE, CONFIG_FILE, PROJECT_FILE, REQUIREMENTS_FILE, isPlanFile, isSummaryFile, isResearchFile, isContextFile, isVerificationFile, PLAN_SUFFIX, SUMMARY_SUFFIX, CONTEXT_SUFFIX, RESEARCH_SUFFIX, VERIFICATION_SUFFIX, UAT_SUFFIX, MAX_SLUG_LENGTH } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, classifyPhaseStatus, hasBraveSearchKey, parsePhaseDir, planningRel } = require('./utils.cjs');
 const { classifyPlanTier } = require('./phase.cjs');
@@ -31,10 +31,11 @@ function planningRelPath(...segments) {
 /**
  * Extract requirement IDs from a ROADMAP phase section.
  * Looks for a **Requirements**: line, strips brackets, splits by comma,
- * and returns null when absent or set to 'TBD'.
+ * and returns null when absent or set to 'TBD'. Both bold forms count: the roadmap
+ * template writes `**Requirements:**`, which this used to miss (phase_req_ids null).
  */
 function extractReqIds(roadmapPhase) {
-  const reqMatch = roadmapPhase?.section?.match(/^\*\*Requirements\*\*:[^\S\n]*([^\n]*)$/m);
+  const reqMatch = roadmapPhase?.section?.match(/^\*\*Requirements(?:\*\*:|:\*\*)[^\S\n]*([^\n]*)$/m);
   const reqExtracted = reqMatch
     ? reqMatch[1].replace(/[\[\]]/g, '').split(',').map(segment => segment.trim()).filter(Boolean).join(', ')
     : null;
@@ -246,7 +247,9 @@ function cmdInitPlanPhase(cwd, phase, raw) {
     phase_number: phaseInfo?.phase_number || roadmapPhase?.phase_number || null,
     phase_name: phaseInfo?.phase_name || roadmapPhase?.phase_name || null,
     phase_slug: phaseInfo?.phase_slug || (roadmapPhase?.phase_name ? generateSlugInternal(roadmapPhase.phase_name) : null),
-    padded_phase: (phaseInfo?.phase_number || roadmapPhase?.phase_number)?.toString().padStart(2, '0') || null,
+    // normalizePhaseName pads the integer part, as directories are named (2.1 → 02.1);
+    // padStart(2, '0') left a decimal phase unpadded.
+    padded_phase: (phaseInfo?.phase_number || roadmapPhase?.phase_number) ? normalizePhaseName(String(phaseInfo?.phase_number || roadmapPhase?.phase_number)) : null,
     phase_req_ids: phaseReqIds,
 
     // Existing artifacts
@@ -445,6 +448,10 @@ function cmdInitQuick(cwd, description, raw) {
     next_num: nextNum,
     slug: slug,
     description: description || null,
+    // The description as one markdown table cell (pipes escaped, line breaks
+    // folded). The workflow writes this, never the raw text, into state.md's
+    // "Quick Tasks Completed" table, where a raw `|` would break the table.
+    description_cell: description ? escapeTableCell(description) : null,
 
     // Timestamps
     date: now.toISOString().split('T')[0],
@@ -588,7 +595,7 @@ function cmdInitPhaseOp(cwd, phase, raw) {
     phase_number: phaseInfo?.phase_number || null,
     phase_name: phaseInfo?.phase_name || null,
     phase_slug: phaseInfo?.phase_slug || null,
-    padded_phase: phaseInfo?.phase_number?.padStart(2, '0') || null,
+    padded_phase: phaseInfo?.phase_number ? normalizePhaseName(String(phaseInfo.phase_number)) : null,
 
     // Existing artifacts
     has_research: phaseInfo?.has_research || false,

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

@@ -16,7 +16,21 @@ const fs = require('fs');
 const path = require('path');
 const { output, error, safeReadFile, toPosix, escapeRegex } = require('./core.cjs');
 const { planningPath } = require('./utils.cjs');
-const { listMemoryAgents, readMemory } = require('./memory.cjs');
+const { listMemoryAgents, readMemory, RESERVED_MEMORY_NAMES } = require('./memory.cjs');
+
+/**
+ * PAN's own archives in `.planning/memory/` are never offered as sources: the
+ * quarantine holds directives PAN refused to follow (ADR-0040), the state archive
+ * is old state, and `archive/` holds the entries `memory prune` retired. Until
+ * 2026-10-05 `knowledge ask` ranked them like any other file, and a question about
+ * deploying returned the quarantine as its top source for the pan-knowledge agent.
+ */
+function isMemoryArchive(relPosix) {
+  const m = String(relPosix).match(/^\.planning\/memory\/(.+)$/);
+  if (!m) return false;
+  if (m[1] === 'archive' || m[1].startsWith('archive/')) return true;
+  return !m[1].includes('/') && RESERVED_MEMORY_NAMES.includes(m[1].replace(/\.md$/i, '').toLowerCase());
+}
 
 const CONVERSATIONS_DIR = 'conversations';
 const PLAYBOOK_FILE = 'playbook.md';
@@ -84,6 +98,7 @@ function gatherCandidates(cwd, question, recallCue) {
       try { entries = fs.readdirSync(abs); } catch { continue; }
       for (const entry of entries) {
         const entryAbs = path.join(abs, entry);
+        if (isMemoryArchive(toPosix(path.join(rel, entry)))) continue;
         let entryStat;
         try { entryStat = fs.statSync(entryAbs); } catch { continue; }
         if (entryStat.isFile() && entry.endsWith('.md')) {
@@ -359,6 +374,7 @@ module.exports = {
   cmdKnowledgeDiscuss,
   cmdKnowledgePlaybook,
   CITATION_ROOTS,
+  isMemoryArchive,
   CONVERSATIONS_DIR,
   PLAYBOOK_FILE,
   PLAYBOOK_CATEGORIES,