pan-wizard 3.32.0 → 3.34.0

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

@@ -16,14 +16,16 @@ const {
 } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible, detectPlanningModel } = require('./utils.cjs');
 const { detectForeignPlanningTree } = require('./foreign-planning.cjs');
+const { unknownConfigKeys, nearestConfigKey } = require('./config.cjs');
 // Drift detection lives in verify-drift.cjs; re-exported below so consumers of
 // verify.cjs are unaffected by the decomposition.
 const { runDriftCheck, parseConventionRules, checkFileConventions, calculateDriftScore, getChangedFiles, cmdDriftCheck } = require('./verify-drift.cjs');
 const { collectVerificationStats, countRoadmapPhases, groupGapPatterns, cmdRetro } = require('./verify-retro.cjs');
 const { detectInstalledRuntimes, validateRuntimeInstall, cmdValidateDeployment } = require('./verify-deploy.cjs');
 const { cmdPreflight, cmdDepsValidate } = require('./verify-preflight.cjs');
-const { scopePhase, cmdVerifyScope } = require('./verify-scope.cjs');
+const { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale } = require('./verify-scope.cjs');
 const { planningRootRel } = require('./planning-root.cjs');
+const { roadmapRequirementIds } = require('./roadmap.cjs');
 
 /**
  * Spot-check files mentioned in summary content.
@@ -116,6 +118,56 @@ function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
   }, raw, passed ? 'passed' : 'failed');
 }
 
+// Longer than a signature, a type or a short config snippet: an implementation body.
+const MAX_ACTION_CODE_LINES = 20;
+
+/** The line count of the longest fenced code block in a piece of markdown (0 if none). */
+function longestFencedBlock(text) {
+  let longest = 0;
+  for (const m of String(text).matchAll(/(^|\n)[ \t]*(`{3,}|~{3,})[^\n]*\n([\s\S]*?)\n[ \t]*\2[ \t]*(?=\n|$)/g)) {
+    longest = Math.max(longest, m[3].split('\n').length);
+  }
+  return longest;
+}
+
+// The elements each checkpoint type needs (references/checkpoints.md).
+const CHECKPOINT_REQUIRED = {
+  'checkpoint:human-verify': ['what-built', 'how-to-verify'],
+  'checkpoint:decision': ['decision', 'options'],
+  'checkpoint:human-action': ['action'],
+};
+
+/**
+ * Check one checkpoint task against its type's shape. A decision checkpoint may
+ * carry `auto_select="<option id>"`: the option auto mode takes. Without one, auto
+ * mode stops for a human instead of taking whichever option is listed first
+ * (market-ideas M22), and an `auto_select` naming no option is an error.
+ * @returns {{name: string, type: string, auto_select?: string|null}} the task entry
+ */
+function checkCheckpointTask(type, attrs, body, errors, warnings) {
+  const keyText = (body.match(/<(?:decision|what-built|action)>([\s\S]*?)<\/(?:decision|what-built|action)>/) || [])[1];
+  const label = keyText ? keyText.trim().replace(/\s+/g, ' ').slice(0, 80) : `unnamed ${type}`;
+  const required = CHECKPOINT_REQUIRED[type];
+  if (!required) {
+    errors.push(`Task '${label}' has unknown checkpoint type '${type}'`);
+    return { name: label, type };
+  }
+  for (const el of required) {
+    if (!body.includes(`<${el}>`)) errors.push(`Checkpoint '${label}' missing <${el}>`);
+  }
+  if (type !== 'checkpoint:decision') return { name: label, type };
+
+  const optionIds = [...body.matchAll(/<option\b[^>]*\bid=["']([^"']+)["']/g)].map(m => m[1]);
+  if (optionIds.length === 0) errors.push(`Decision checkpoint '${label}' has no <option id="...">`);
+  const autoMatch = attrs.match(/\bauto_select=["']([^"']*)["']/);
+  if (!autoMatch) {
+    warnings.push(`Decision checkpoint '${label}' has no auto_select: auto mode stops here for a human`);
+  } else if (!optionIds.includes(autoMatch[1])) {
+    errors.push(`Decision checkpoint '${label}' auto_select="${autoMatch[1]}" names no option (options: ${optionIds.join(', ') || 'none'})`);
+  }
+  return { name: label, type, auto_select: autoMatch ? autoMatch[1] : null };
+}
+
 /**
  * Validate a plan.md structure: required frontmatter, task elements, and consistency.
  * @param {string} cwd - Working directory path
@@ -139,14 +191,24 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
     if (fm[field] === undefined) errors.push(`Missing required frontmatter field: ${field}`);
   }
 
-  // Parse XML <task> elements and validate each has required sub-elements:
-  // <name> (required), <action> (required), <verify> (recommended),
-  // <done> (recommended), <files> (recommended)
-  const taskPattern = /<task[^>]*>([\s\S]*?)<\/task>/g;
+  // Parse XML <task> elements. An auto task needs <name> and <action> and should
+  // have <verify>, <done> and <files>. A checkpoint task has its own shape
+  // (references/checkpoints.md) and is checked against that instead: until
+  // 2026-10-03 every checkpoint failed the auto-task checks, and the `<task[^>]*>`
+  // pattern also matched the `<tasks>` wrapper, so a decision's first option name
+  // was read as the task's name. `\b` keeps the wrapper out.
+  const taskPattern = /<task\b([^>]*)>([\s\S]*?)<\/task>/g;
   const tasks = [];
   let taskMatch;
   while ((taskMatch = taskPattern.exec(content)) !== null) {
-    const taskContent = taskMatch[1];
+    const attrs = taskMatch[1];
+    const taskContent = taskMatch[2];
+    const typeMatch = attrs.match(/\btype=["']?([\w:-]+)/);
+    const taskType = typeMatch ? typeMatch[1] : 'auto';
+    if (taskType.startsWith('checkpoint:')) {
+      tasks.push(checkCheckpointTask(taskType, attrs, taskContent, errors, warnings));
+      continue;
+    }
     const nameMatch = taskContent.match(/<name>([\s\S]*?)<\/name>/);
     const taskName = nameMatch ? nameMatch[1].trim() : 'unnamed';
     const hasFiles = /<files>/.test(taskContent);
@@ -156,11 +218,19 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
 
     if (!nameMatch) errors.push('Task missing <name> element');
     if (!hasAction) errors.push(`Task '${taskName}' missing <action>`);
+    // Decisions, not code (market-ideas M32): an <action> names signatures, values,
+    // assertions and the verify command. A long fenced block there is an
+    // implementation body the planner wrote for the executor.
+    const actionText = (taskContent.match(/<action>([\s\S]*?)<\/action>/) || [])[1] || '';
+    const longest = longestFencedBlock(actionText);
+    if (longest > MAX_ACTION_CODE_LINES) {
+      warnings.push(`Task '${taskName}' embeds a ${longest}-line code block in <action>: a plan records decisions (signatures, values, assertions, the verify command), not implementation`);
+    }
     if (!hasVerify) warnings.push(`Task '${taskName}' missing <verify>`);
     if (!hasDone) warnings.push(`Task '${taskName}' missing <done>`);
     if (!hasFiles) warnings.push(`Task '${taskName}' missing <files>`);
 
-    tasks.push({ name: taskName, hasFiles, hasAction, hasVerify, hasDone });
+    tasks.push({ name: taskName, type: taskType, hasFiles, hasAction, hasVerify, hasDone });
   }
 
   if (tasks.length === 0) warnings.push('No <task> elements found');
@@ -370,11 +440,10 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
     // artifacts: [], key_links: [] }` (pan-wizard-core/templates/phase-prompt.md,
     // template.cjs generatePlanTemplate), so an empty block is the documented default
     // state of a scaffolded plan; presence of the block is enforced by
-    // `verify plan-structure`, not here. (2) parseMustHavesBlock currently matches the
-    // block header at 4-space indent while every shipped template and agent emits it at
-    // 2 — so this branch is reached for *every* plan authored in PAN's own format, and
-    // exiting non-zero would fail every real `verify artifacts` call. Reclassifying
-    // this as a failure requires fixing that indentation mismatch first.
+    // `verify plan-structure`, not here. (2) parseMustHavesBlock once required a
+    // 4-space indent while every shipped template and agent writes 2, so this branch
+    // fired for every plan in PAN's own format. It reads relative indent now
+    // (frontmatter.cjs), so reaching it means the plan declares no artifacts.
     output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw, undefined, EXIT_OK);
     return;
   }
@@ -439,8 +508,7 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
   const r = checkKeyLinks(cwd, content);
   if (r.total === 0) {
     // EXIT_OK: same reasoning as cmdVerifyArtifacts above — an empty key_links block is
-    // the shipped template default, and the parseMustHavesBlock indent mismatch means
-    // this branch fires for every plan written in PAN's own format.
+    // the shipped template default, so a plan that declares none is a result, not a failure.
     output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw, undefined, EXIT_OK);
     return;
   }
@@ -481,10 +549,19 @@ function reconcilePhase(cwd, phaseNum) {
   const sm = verRaw.match(/^status:\s*([A-Za-z_-]+)/m);
   const status = sm ? sm[1].toLowerCase() : 'unknown';
   const claimsPass = /^(pass|passed|verified|complete|verified_pass)$/.test(status);
-  const planFile = files.find(f => isPlanFile(f));
-  const planContent = planFile ? (safeReadFile(path.join(dir, planFile)) || '') : '';
-  const artifacts = checkArtifacts(cwd, planContent);
-  const keyLinks = checkKeyLinks(cwd, planContent);
+  // Every plan's must_haves. Reading only the first plan let a later plan's failing
+  // artifact through under a passing verdict — the rubber stamp this check exists for.
+  const artifacts = { all_passed: true, passed: 0, total: 0, artifacts: [] };
+  const keyLinks = { all_verified: true, verified: 0, total: 0, links: [] };
+  for (const planFile of files.filter(f => isPlanFile(f)).sort()) {
+    const planContent = safeReadFile(path.join(dir, planFile)) || '';
+    const a = checkArtifacts(cwd, planContent);
+    const k = checkKeyLinks(cwd, planContent);
+    artifacts.passed += a.passed; artifacts.total += a.total; artifacts.artifacts.push(...a.artifacts.map(x => ({ plan: planFile, ...x })));
+    keyLinks.verified += k.verified; keyLinks.total += k.total; keyLinks.links.push(...k.links.map(x => ({ plan: planFile, ...x })));
+  }
+  artifacts.all_passed = artifacts.passed === artifacts.total;
+  keyLinks.all_verified = keyLinks.verified === keyLinks.total;
   const signals = artifacts.total + keyLinks.total;
   const contradictions = [];
   if (claimsPass) {
@@ -856,6 +933,15 @@ function checkConfigFile(cwd, addIssue, repairs) {
     if (parsed.model_profile && !validProfiles.includes(parsed.model_profile)) {
       addIssue('warning', 'W004', `${CONFIG_FILE}: invalid model_profile "${parsed.model_profile}"`, `Valid values: ${validProfiles.join(', ')}`);
     }
+    // I006 (market-ideas M26): keys PAN does not read. Info, not a warning: the key
+    // may be the user's own note or meant for a newer PAN, but a typo must not pass
+    // as a setting that took effect.
+    const unknown = unknownConfigKeys(parsed);
+    if (unknown.length) {
+      const hints = unknown.map((k) => { const n = nearestConfigKey(k); return n ? `${k} → ${n}?` : k; });
+      addIssue('info', 'I006', `${CONFIG_FILE}: PAN does not read ${unknown.length === 1 ? 'this key' : 'these keys'}: ${unknown.join(', ')}`,
+        `Check the spelling (${hints.join('; ')}), or remove the key. pan-tools config-set names an unknown key when you set it.`);
+    }
   } catch (err) {
     // JSON parse failed -- config is corrupt and should be reset
     addIssue('error', 'E005', `${CONFIG_FILE}: JSON parse error - ${err.message}`, 'Run /pan:health --repair to reset to defaults', true);
@@ -1158,11 +1244,10 @@ function syncRequirementCheckboxes(cwd) {
   // For each completed phase, find linked requirement IDs and check their boxes
   let fixed = 0;
   for (const phaseNum of completedPhases) {
-    const reqMatch = roadmapContent.match(
-      new RegExp(`Phase\\s+${escapeRegex(phaseNum)}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i')
-    );
-    if (!reqMatch) continue;
-    const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(id => id.trim()).filter(Boolean);
+    // The phase's own requirements, as `phase complete` reads them: a bare "Phase N …
+    // Requirements" search took the first section's line for every phase when the
+    // checklist sits above the sections, as templates/roadmap.md lays it out.
+    const reqIds = roadmapRequirementIds(roadmapContent, phaseNum);
     for (const reqId of reqIds) {
       const escaped = escapeRegex(reqId);
       const re = new RegExp(`(- \\[) (\\]\\s*\\*\\*${escaped}\\*\\*)`, 'gi');
@@ -1383,7 +1468,6 @@ function cmdValidateHealth(cwd, options, raw) {
   // Check 10 (optional): full validation — run tests and build
   let testStatus;
   let buildStatus;
-  let memoryBudget;
   if (options.full) {
     testStatus = runFullTestCheck(cwd);
     buildStatus = runFullBuildCheck(cwd);
@@ -1393,14 +1477,9 @@ function cmdValidateHealth(cwd, options, raw) {
     if (buildStatus.pass === false) {
       addIssue('error', 'BUILD_FAIL', `Build failed (exit code ${buildStatus.exitCode})`, 'Fix build errors');
     }
-    // Memory-load budget (ADR-0036 acceptance signal): keep per-agent memory
-    // injection bounded as logs grow. Read-only, non-blocking.
-    memoryBudget = require('./memory.cjs').memoryLoadBudget(cwd);
-    if (memoryBudget.status === 'critical') {
-      addIssue('warning', 'MEM_BUDGET', memoryBudget.advisory, "Run 'pan-tools memory compact <agent>' or scope injection with 'memory select'");
-    } else if (memoryBudget.status === 'warning') {
-      addIssue('info', 'MEM_BUDGET', memoryBudget.advisory, "Run 'pan-tools memory compact <agent>' or scope injection with 'memory select'");
-    }
+    // No memory-load check: PAN's workflows no longer load agent memory into
+    // agents (ADR-0036, amended 2026-10-04), so its size costs no agent context.
+    // `pan-tools memory budget` still sizes the store on request.
   }
 
   // Check 11 (optional): drift analysis
@@ -1461,7 +1540,6 @@ function cmdValidateHealth(cwd, options, raw) {
   if (options.full) {
     result.test_status = testStatus;
     result.build_status = buildStatus;
-    result.memory_budget = memoryBudget;
   }
   if (options.drift) {
     result.drift_status = driftResult;
@@ -1471,8 +1549,10 @@ function cmdValidateHealth(cwd, options, raw) {
   }
 
   // Explicit verdict exit: `broken` → 1; `degraded` and `healthy` → 0 (warnings are
-  // not failures). Computed AFTER --repair ran, so the code reflects the post-repair
-  // state the JSON reports. See the note at the early-return site above.
+  // not failures). The issue lists were collected before --repair ran and a repair
+  // removes nothing from them, so the status and this code describe the tree as it
+  // was before the repairs; `repairs_performed` says what changed, and a second run
+  // shows the result. See the note at the early-return site above.
   output(result, raw, undefined, status === HEALTH_STATUS.BROKEN ? 1 : 0);
 }
 
@@ -1558,6 +1638,8 @@ module.exports = {
   cmdVerifyStubs,
   scopePhase,
   cmdVerifyScope,
+  verificationFreshness,
+  cmdVerifyStale,
   cmdValidateConsistency,
   cmdValidateHealth,
   cmdPreflight,

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

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

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

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

package/pan-wizard-core/learnings/index.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "generated_at": "2026-08-07T13:36:47.532Z",
+  "generated_at": "2026-10-04T10:14:05.059Z",
   "topics": [
     {
       "name": "experiment-runner",
@@ -14,8 +14,8 @@
         "P-EXP-005",
         "P-NPRS-005"
       ],
-      "size_bytes": 8889,
-      "size_tokens_est": 2223,
+      "size_bytes": 8956,
+      "size_tokens_est": 2239,
       "agent_relevance": {
         "planner": "low",
         "executor": "low",
@@ -804,7 +804,7 @@
   "totals": {
     "topics": 47,
     "patterns": 93,
-    "size_bytes": 150126,
-    "size_tokens_est": 37549
+    "size_bytes": 150193,
+    "size_tokens_est": 37565
   }
 }

package/pan-wizard-core/mcp/server.cjs

@@ -50,6 +50,15 @@ const META_SERVER_INFO_KEY = 'io.modelcontextprotocol/serverInfo';
 // claim to speak a version we don't. Newest first (the `server/discover` order).
 const SUPPORTED_VERSIONS_LIST = [MODERN_PROTOCOL_VERSION, '2025-06-18', '2025-03-26', '2024-11-05'];
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(SUPPORTED_VERSIONS_LIST);
+// The `CacheableResult` fields a modern result MUST carry where its type extends
+// that interface: DiscoverResult, ListToolsResult, ListResourcesResult and
+// ReadResourceResult (schema/2026-07-28/schema.ts). Claude Code 2.1.288 drops a
+// list without them, so the server showed as connected with no tools and no
+// resources (live check H2, 2026-10-03). The registry is fixed for the life of the
+// process, so its lists are public and long-lived; a resource is the project's
+// state at the moment it is read, so a read is private and stale at once.
+const REGISTRY_CACHE = Object.freeze({ ttlMs: 3600000, cacheScope: 'public' });
+const READ_CACHE = Object.freeze({ ttlMs: 0, cacheScope: 'private' });
 /**
  * The version the server reports in `initialize` / `server/discover`. Read from the
  * package.json two levels up: the repository root in the source tree, the runtime
@@ -320,12 +329,13 @@ function createServer(opts = {}) {
         { supported: SUPPORTED_VERSIONS_LIST, requested: requestedVersion });
     }
 
-    // Modern results MUST carry a `resultType`; legacy results MUST NOT change
-    // shape (clients treat an absent resultType as "complete"). Stamp it only on
+    // Modern results MUST carry a `resultType`, a cacheable one its caching fields,
+    // and each SHOULD name the server in `_meta`; legacy results MUST NOT change
+    // shape (clients treat an absent resultType as "complete"). Stamp them only on
     // the modern path.
-    const reply = (result) => rpcResult(id,
+    const reply = (result, cache) => rpcResult(id,
       isModern && result && typeof result === 'object' && result.resultType === undefined
-        ? { resultType: 'complete', ...result }
+        ? { resultType: 'complete', ...cache, ...result, _meta: { ...result._meta, [META_SERVER_INFO_KEY]: SERVER_INFO } }
         : result);
 
     switch (method) {
@@ -339,8 +349,7 @@ function createServer(opts = {}) {
           supportedVersions: SUPPORTED_VERSIONS_LIST,
           capabilities: { tools: {}, resources: {} },
           instructions: 'PAN Wizard engine bridge: planning, verification, and orchestration tools backed by the pan-tools CLI. All tools are read-only except the gated pan_confirm_merge.',
-          ttlMs: 3600000,
-          cacheScope: 'public',
+          ...REGISTRY_CACHE,
           _meta: { [META_SERVER_INFO_KEY]: SERVER_INFO },
         });
       case 'initialize': {
@@ -354,9 +363,9 @@ function createServer(opts = {}) {
       case 'ping':
         return reply({});
       case 'tools/list':
-        return reply({ tools: reg.TOOLS.map(toMcpTool) });
+        return reply({ tools: reg.TOOLS.map(toMcpTool) }, REGISTRY_CACHE);
       case 'resources/list':
-        return reply({ resources: reg.RESOURCES.map(toMcpResource) });
+        return reply({ resources: reg.RESOURCES.map(toMcpResource) }, REGISTRY_CACHE);
       case 'tools/call': {
         const out = callTool(params && params.name, params && params.arguments);
         return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result);
@@ -364,7 +373,7 @@ function createServer(opts = {}) {
       case 'resources/read': {
         const out = readResource(params && params.uri);
         if (out.unknown) return rpcError(id, -32602, `Unknown resource: ${params && params.uri}`);
-        return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result);
+        return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result, READ_CACHE);
       }
       default:
         return rpcError(id, -32601, `Method not found: ${method}`);