pan-wizard 3.33.0 → 3.34.0

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

@@ -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
@@ -592,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,

package/pan-wizard-core/bin/lib/learn-index.cjs

@@ -168,15 +168,102 @@ function readIndex(sourceRoot) {
   }
 }
 
+// ─── Cue ranking (memory optimisation O5) ───────────────────────────────────
+//
+// The role ranking loads the same topics whatever the task, filling the budget
+// smallest-first, so a large topic the task needs (migration-safety for a
+// migration) drops out. With a cue — the phase objective and the files it
+// touches — topics are matched to the task: the cue's words against each topic's
+// name, pattern summaries and rules. Lexical, like `memory select`'s scorer, with
+// two changes topic text needs: common words are ignored, and a word meets its
+// own inflections (plurals fold; "corrupting" meets "corrupt", "parsed" "parse").
+
+const CUE_STOPWORDS = new Set((
+  'the and for with that this from into onto over under when then than them they their there these those '
+  + 'are was were been being have has had not but all any each every per its our your you who what which '
+  + 'can could should would will shall may might must also only just very more most less such same other '
+  + 'add adds added adding make makes made making use uses used using new old get gets set sets run runs '
+  + 'fix fixes fixed one two way ways out off how why where while after before about again still both '
+  + 'file files code thing things project phase plan plans task tasks work works working change changes'
+).split(' '));
+
+/**
+ * Fold a plural: "retries" → "retry", "classes" → "class", "matches" → "match",
+ * "failures" → "failure", "cases" → "case"; "class" and "status" stay.
+ */
+function foldPlural(w) {
+  if (w.length > 4 && w.endsWith('ies')) return `${w.slice(0, -3)}y`;
+  if (w.length > 5 && w.endsWith('sses')) return w.slice(0, -2);
+  if (w.length > 4 && /(x|z|ch|sh)es$/.test(w)) return w.slice(0, -2);
+  if (w.length > 3 && w.endsWith('s') && !/(ss|us|is)$/.test(w)) return w.slice(0, -1);
+  return w;
+}
+
+/** The content words of a text (3+ letters, plurals folded, no stopwords). */
+function cueTerms(text) {
+  const out = new Set();
+  for (const w of String(text || '').toLowerCase().match(/[a-z0-9]{3,}/g) || []) {
+    const f = foldPlural(w);
+    if (!CUE_STOPWORDS.has(w) && !CUE_STOPWORDS.has(f)) out.add(f);
+  }
+  return out;
+}
+
+/** Two words meet when equal, or when the shorter (4+ letters) begins the longer, at most 3 letters apart. */
+function termsMeet(a, b) {
+  if (a === b) return true;
+  const [s, l] = a.length <= b.length ? [a, b] : [b, a];
+  return s.length >= 4 && l.length - s.length <= 3 && l.startsWith(s);
+}
+
+function setHasTerm(set, t) {
+  if (set.has(t)) return true;
+  for (const u of set) if (termsMeet(t, u)) return true;
+  return false;
+}
+
+/**
+ * Each topic's terms from the store: its name, and its patterns' summaries and
+ * rules (not their evidence, which is long and incidental).
+ * @returns {Map<string, {name: Set<string>, text: Set<string>}>}
+ */
+function topicTermsFromStore(sourceRoot) {
+  const { extractFieldSection } = require('./learn-lint.cjs');
+  const text = new Map();
+  for (const p of collectAllPatterns(sourceRoot)) {
+    const prev = text.get(p.topic) || '';
+    text.set(p.topic, `${prev}\n${p.summary}\n${extractFieldSection(p.body, 'Rule')}`);
+  }
+  const out = new Map();
+  for (const [topic, t] of text) out.set(topic, { name: cueTerms(topic.replace(/-/g, ' ')), text: cueTerms(t) });
+  return out;
+}
+
+/** How well a topic matches the cue: 2 per cue term in its name, 1 per term in its text. */
+function cueScore(cue, terms) {
+  if (!terms) return 0;
+  let s = 0;
+  for (const t of cue) s += setHasTerm(terms.name, t) ? 2 : setHasTerm(terms.text, t) ? 1 : 0;
+  return s;
+}
+
 /**
  * Query: what topics should agent X load at this point?
  *
+ * With `opts.cue` and `opts.topicTerms`, topics are matched to the task (mode
+ * `cue`): every topic scoring at least half the best match is a candidate
+ * whatever its role relevance, ranked by cue score, then relevance, then size;
+ * the rest are not loaded. When nothing matches, or there is no cue, the role
+ * ranking applies (mode `role`): relevance, then smallest first.
+ *
  * @param {object} index - the index object
  * @param {object} opts
  * @param {string} opts.agent - 'planner' | 'executor' | 'verifier' | 'reviewer'
- * @param {string} [opts.minRelevance] - 'high' | 'medium' | 'low' (default 'medium')
+ * @param {string} [opts.minRelevance] - 'high' | 'medium' | 'low' (default 'medium'; role mode)
  * @param {number} [opts.tokenBudget] - max tokens to fit (default 5000)
- * @returns {object} { topics: [{name, scope, file, tokens, relevance}], total_tokens, dropped: [...] }
+ * @param {string} [opts.cue] - the phase objective and the files it touches
+ * @param {Map} [opts.topicTerms] - from topicTermsFromStore()
+ * @returns {object} { selected: [{name, scope, file, tokens, relevance, cue_score?}], total_tokens, dropped: [...], mode }
  */
 function topicsForAgent(index, opts) {
   const agent = opts.agent;
@@ -185,14 +272,22 @@ function topicsForAgent(index, opts) {
   const ranks = { high: 3, medium: 2, low: 1 };
   const minRank = ranks[minLevel] || 2;
 
-  const ranked = [];
-  for (const t of index.topics) {
+  const cue = cueTerms(opts.cue);
+  const scored = index.topics.map(t => {
     const rel = (t.agent_relevance || {})[agent] || 'low';
-    const rank = ranks[rel] || 1;
-    if (rank < minRank) continue;
-    ranked.push({ ...t, _relevance: rel, _rank: rank });
-  }
-  ranked.sort((a, b) => b._rank - a._rank || a.size_tokens_est - b.size_tokens_est);
+    return { ...t, _relevance: rel, _rank: ranks[rel] || 1, _cue: cue.size ? cueScore(cue, opts.topicTerms && opts.topicTerms.get(t.name)) : 0 };
+  });
+  // A topic must score at least half the best match: a single incidental shared
+  // word should not load a topic beside the ones the task is about. On the golden
+  // set (tests/fixtures/learn-cue-golden.json) this cut raised precision from
+  // 0.22 to 0.37 for a recall of 0.76 instead of 0.81.
+  const top = Math.max(0, ...scored.map(t => t._cue));
+  const matched = scored.filter(t => t._cue > 0 && t._cue >= Math.ceil(top / 2));
+  const mode = matched.length ? 'cue' : 'role';
+
+  const ranked = mode === 'cue'
+    ? matched.sort((a, b) => b._cue - a._cue || b._rank - a._rank || a.size_tokens_est - b.size_tokens_est)
+    : scored.filter(t => t._rank >= minRank).sort((a, b) => b._rank - a._rank || a.size_tokens_est - b.size_tokens_est);
 
   const selected = [];
   const dropped = [];
@@ -209,6 +304,7 @@ function topicsForAgent(index, opts) {
       tokens: t.size_tokens_est,
       relevance: t._relevance,
       patterns: t.patterns,
+      ...(mode === 'cue' ? { cue_score: t._cue } : {}),
     });
     total += t.size_tokens_est;
   }
@@ -217,6 +313,8 @@ function topicsForAgent(index, opts) {
     agent,
     min_relevance: minLevel,
     token_budget: budget,
+    mode,
+    ...(opts.cue ? { cue: opts.cue } : {}),
     selected,
     dropped,
     total_tokens: total,
@@ -237,7 +335,8 @@ function cmdBuildIndex(sourceRoot) {
 
 function cmdTopicsFor(sourceRoot, opts) {
   const index = readIndex(sourceRoot);
-  return topicsForAgent(index, opts);
+  const topicTerms = opts.cue ? topicTermsFromStore(sourceRoot) : undefined;
+  return topicsForAgent(index, { ...opts, topicTerms });
 }
 
 module.exports = {
@@ -245,6 +344,8 @@ module.exports = {
   writeIndex,
   readIndex,
   topicsForAgent,
+  topicTermsFromStore,
+  cueTerms,
   cmdBuildIndex,
   cmdTopicsFor,
   INDEX_PATH_REL,

package/pan-wizard-core/bin/lib/learn-lint.cjs

@@ -11,6 +11,8 @@
  *           (candidate for internal/ scope rather than universal/)
  *  - L-005: Revision marker (rN) appended in body but no supersession field
  *  - L-006: Universal-scope pattern cites an internal pattern id (dangles after install)
+ *  - L-007: A pattern's `cites` no longer holds — the cited file or symbol is gone
+ *           from the tree that holds the store (memory optimisation O4)
  *
  * These are not patterns themselves — they're integrity checks for the
  * pattern store. Wired to `pan-tools learn lint`.
@@ -45,7 +47,9 @@ function getLearningsDir(sourceRoot, scope) {
 }
 
 function readTopicFile(filePath) {
-  const content = fs.readFileSync(filePath, 'utf-8');
+  // LF: an install committed with core.autocrlf=true holds these files as CRLF,
+  // and the LF-only match below then read every topic as having no patterns.
+  const content = fs.readFileSync(filePath, 'utf-8').replace(/^/, '').replace(/\r\n/g, '\n');
   const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!fmMatch) return { frontmatter: { patterns: [] }, body: content };
   const fmText = fmMatch[1];
@@ -113,6 +117,7 @@ function collectAllPatterns(sourceRoot) {
           source_experiments: Array.isArray(p.source_experiments) ? p.source_experiments : [],
           superseded_by: p.superseded_by || null,
           superseded_id: p.superseded_id || null,
+          cites: Array.isArray(p.cites) ? p.cites : [],
           body: patternBody,
         });
       }
@@ -170,7 +175,7 @@ const PATTERN_REF_RE = /\bP-(?:[A-Z]+-)?\d+(?:-r\d+)?\b/g;
  *     pattern_count, file_count, scopes
  *   }
  */
-function lintPatterns(patterns) {
+function lintPatterns(patterns, opts = {}) {
   const violations = [];
 
   const idIndex = new Map(); // id -> [{scope, topic, file}, ...]
@@ -297,6 +302,28 @@ function lintPatterns(patterns) {
     }
   }
 
+  // L-007: a citation that no longer holds. A pattern may name the code it rests
+  // on (`cites: [pan-wizard-core/bin/lib/x.cjs#symbol]`, relative to the tree
+  // holding the store). When that code is gone the pattern is stale evidence, the
+  // way a memory entry is (O4). Checked only when the caller passes the root.
+  if (opts.sourceRoot) {
+    const { citationProblem } = require('./memory.cjs');
+    for (const p of patterns) {
+      for (const c of p.cites || []) {
+        const problem = citationProblem(opts.sourceRoot, c);
+        if (!problem) continue;
+        violations.push({
+          code: 'L-007',
+          severity: 'error',
+          pattern_id: p.id,
+          file: p.file,
+          message: `Pattern "${p.id}" cites ${c}, which no longer holds (${problem}) — update the pattern or retire it`,
+          cite: c,
+        });
+      }
+    }
+  }
+
   return {
     violations,
     pattern_count: patterns.length,
@@ -316,7 +343,7 @@ function cmdLearnLint(sourceRoot, opts = {}) {
   const filtered = opts.scope
     ? all.filter(p => p.scope === opts.scope)
     : all;
-  const result = lintPatterns(filtered);
+  const result = lintPatterns(filtered, { sourceRoot });
 
   const errors = result.violations.filter(v => v.severity === 'error').length;
   const warnings = result.violations.filter(v => v.severity === 'warning').length;

package/pan-wizard-core/bin/lib/memory-optimize.cjs

@@ -17,7 +17,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, safeReadFile } = require('./core.cjs');
+const { output, safeReadFile, toLf, dominantEol, withEol } = require('./core.cjs');
 const { planningPath } = require('./utils.cjs');
 const { writeStateMd } = require('./state.cjs');
 const { readMemory, parseEntries, listMemoryAgents, compactMemory, DEFAULT_MAX_ENTRIES, MEMORY_DIR } = require('./memory.cjs');
@@ -167,7 +167,11 @@ function reconcileBullets(lines, keepN, archived, quarantined) {
  */
 function optimizeStateContent(content, opts = {}) {
   const keepN = Number.isFinite(opts.keep) && opts.keep > 0 ? opts.keep : DEFAULT_KEEP;
-  const sections = parseSections(content);
+  // Work on LF and hand the file back in its own ending. On CRLF input
+  // headingText's `(.*)$` could not cross the trailing '\r', so no heading
+  // matched APPEND_HEAVY and every Windows project read as already lean.
+  const eol = dominantEol(content);
+  const sections = parseSections(toLf(content));
   const archived = [];
   const quarantined = [];
   const sectionsTouched = [];
@@ -184,7 +188,7 @@ function optimizeStateContent(content, opts = {}) {
     }
   }
 
-  return { content: changed ? joinSections(sections) : content, changed, archived, quarantined, sectionsTouched };
+  return { content: changed ? withEol(joinSections(sections), eol) : content, changed, archived, quarantined, sectionsTouched };
 }
 
 // ─── Command ────────────────────────────────────────────────────────────────
@@ -339,5 +343,5 @@ function maybeAutoOptimizeMemory(cwd, opts = {}) {
 module.exports = {
   optimizeStateContent, reconcileBullets, parseSections, joinSections, cmdMemoryOptimize,
   maybeAutoOptimizeMemory, autoOptimizeEnabled, isSuspiciousDirective,
-  APPEND_HEAVY, PLACEHOLDER, DIRECTIVE_PATTERNS, DEFAULT_KEEP, STATE_ARCHIVE_FILE, QUARANTINE_FILE,
+  APPEND_HEAVY, PLACEHOLDER, DIRECTIVE_PATTERNS, DEFAULT_KEEP, STATE_ARCHIVE_FILE, QUARANTINE_FILE, QUARANTINE_HEADER,
 };