pan-wizard 3.33.0 → 3.35.0

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

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

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

@@ -27,8 +27,11 @@ const LOCKFILES = new Set([
 ]);
 // PAN's own installed trees: a phase commit that touches them is PAN bookkeeping,
 // never the project's scope (pan-reviewer skips them for the same reason).
-const PAN_OWNED_PREFIXES = ['.claude/', '.codex/', '.gemini/', '.opencode/', '.agents/', '.github/pan-wizard-core/', '.github/agents/', '.github/prompts/', '.github/skills/'];
-const PAN_OWNED_FILES = new Set(['.github/copilot-instructions.md', '.github/hooks/pan.json']);
+// A Copilot install shares `.github/` with the project: only what the installer writes as
+// its own is listed, so the project's workflows, hooks and Copilot instructions stay in scope,
+// and so do the files PAN merges into (`mcp.json`, `copilot/settings.json`).
+const PAN_OWNED_PREFIXES = ['.claude/', '.codex/', '.gemini/', '.opencode/', '.agents/', '.github/pan-wizard-core/', '.github/pan-local-patches/', '.github/agents/pan-', '.github/skills/pan-', '.github/hooks/pan-'];
+const PAN_OWNED_FILES = new Set(['.github/hooks/pan.json', '.github/package.json', '.github/pan-file-manifest.json']);
 const TEST_PATH_RE = /(^|\/)(tests?|__tests__|specs?)\//i;
 const TEST_FILE_RE = /\.(test|spec)\.[a-z0-9]+$/i;
 const COMMIT_SCAN_LIMIT = 2000;
@@ -65,27 +68,28 @@ function exclusionReason(file, planningPrefix) {
 
 /**
  * Files the phase's plan commits touched, paths relative to `cwd` (git's --relative).
- * @returns {{git: boolean, commits: number, files: Set<string>}}
+ * @returns {{git: boolean, commits: number, files: Set<string>, hashes: string[]}} hashes newest first
  */
 function committedFiles(cwd, phaseNumber) {
   const r = execGit(cwd, ['-c', 'core.quotepath=off', 'log', '--no-merges', '-n', String(COMMIT_SCAN_LIMIT), '--relative', '--name-only', '--format=@@%H%x09%s']);
-  if (r.exitCode !== 0) return { git: false, commits: 0, files: new Set() };
+  if (r.exitCode !== 0) return { git: false, commits: 0, files: new Set(), hashes: [] };
   // `{type}({phase}-{plan}):` with the phase's zero padding optional ("feat(03-01):", "fix(3-02)!:").
   const unpadded = String(phaseNumber).replace(/^0+(?=\d)/, '');
   const subjectRe = new RegExp(`^[a-z]+\\(0*${escapeRegex(unpadded)}-[0-9]+\\)!?:`);
   const files = new Set();
+  const hashes = [];
   let commits = 0;
   let inPhase = false;
   for (const line of r.stdout.split('\n')) {
     if (line.startsWith('@@')) {
       const subject = line.slice(2).split('\t').slice(1).join('\t');
       inPhase = subjectRe.test(subject);
-      if (inPhase) commits++;
+      if (inPhase) { commits++; hashes.push(line.slice(2).split('\t')[0]); }
       continue;
     }
     if (inPhase && line.trim()) files.add(normalisePath(line));
   }
-  return { git: true, commits, files };
+  return { git: true, commits, files, hashes };
 }
 
 /**
@@ -220,4 +224,4 @@ function cmdVerifyStale(cwd, phase, raw) {
   output(r, raw, r.error ? undefined : r.state);
 }
 
-module.exports = { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale, coveredFiles, LOCKFILES };
+module.exports = { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale, coveredFiles, committedFiles, LOCKFILES, TEST_PATH_RE, TEST_FILE_RE };

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

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

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

@@ -187,10 +187,12 @@ function createWorktree(cwd, phaseNum, scenario, opts) {
     return { error: 'Not a git repo — what-if requires git worktree support' };
   }
   const slug = scenarioSlug(scenario);
-  const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  const branch = `${BRANCH_PREFIX}${phaseNum}-${slug}-${ts.slice(0, 15)}`;
+  // To the millisecond: cut to `slice(0, 15)` it had ten-minute resolution, so a repeat
+  // of the same phase and scenario within ten minutes failed on an existing branch.
+  const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 23);
+  const branch = `${BRANCH_PREFIX}${phaseNum}-${slug}-${ts}`;
   const worktreeRoot = opts?.worktree_root
-    || path.join(path.dirname(cwd), `pan-whatif-${phaseNum}-${slug}-${ts.slice(0, 15)}`);
+    || path.join(path.dirname(cwd), `pan-whatif-${phaseNum}-${slug}-${ts}`);
 
   // Base ref: current HEAD by default. Callers can override (e.g. to branch
   // off main for a clean comparison).
@@ -208,10 +210,38 @@ function createWorktree(cwd, phaseNum, scenario, opts) {
   };
 }
 
+/** Registered worktrees as {path, branch}; branch is null on a detached HEAD. */
+function listWorktrees(cwd) {
+  const r = execGit(cwd, ['worktree', 'list', '--porcelain']);
+  if (r.exitCode !== 0) return [];
+  const list = [];
+  for (const line of r.stdout.split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) list.push({ path: line.slice('worktree '.length), branch: null });
+    else if (line.startsWith('branch ') && list.length) list[list.length - 1].branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+  }
+  return list;
+}
+
+function samePath(a, b) {
+  const norm = (p) => {
+    let r = path.resolve(p);
+    try { r = fs.realpathSync.native(r); } catch { /* gone: compare the resolved form */ }
+    r = toPosix(r);
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+  };
+  return norm(a) === norm(b);
+}
+
 /**
  * Remove a worktree + its branch. Best-effort: errors are surfaced but
  * don't block subsequent cleanups.
  *
+ * Only what-if's own objects are touched: the branch must carry BRANCH_PREFIX and the
+ * worktree, when git still lists it, must be checked out on that branch (or, with no
+ * branch given, on some BRANCH_PREFIX branch). Anything else is refused before a single
+ * git write, because `branch -D` and `worktree remove --force` destroy unmerged commits
+ * and uncommitted files.
+ *
  * @param {string} cwd - Main project root (for the cleanup git call)
  * @param {string} worktreePath - Path returned by createWorktree
  * @param {string} branch - Branch name returned by createWorktree
@@ -222,15 +252,29 @@ function cleanupWorktree(cwd, worktreePath, branch, opts) {
   if (!isGitRepo(cwd)) {
     return { error: 'Not a git repo' };
   }
+  if (branch && !branch.startsWith(BRANCH_PREFIX)) {
+    return { error: `Refusing to delete branch '${branch}': what-if only cleans up branches it created (${BRANCH_PREFIX}*)` };
+  }
+  const entry = listWorktrees(cwd).find(w => samePath(w.path, worktreePath));
+  if (entry) {
+    const owned = entry.branch && entry.branch.startsWith(BRANCH_PREFIX) && (!branch || entry.branch === branch);
+    if (!owned) {
+      return { error: `Refusing to remove worktree ${toPosix(worktreePath)}: it is on '${entry.branch || 'a detached HEAD'}', not ${branch || BRANCH_PREFIX + '*'}` };
+    }
+  }
   const warnings = [];
   const force = opts?.force === true;
 
-  const rmArgs = ['worktree', 'remove'];
-  if (force) rmArgs.push('--force');
-  rmArgs.push(worktreePath);
-  const removeResult = execGit(cwd, rmArgs);
-  if (removeResult.exitCode !== 0) {
-    warnings.push(`worktree remove: ${removeResult.stderr}`);
+  if (entry) {
+    const rmArgs = ['worktree', 'remove'];
+    if (force) rmArgs.push('--force');
+    rmArgs.push(worktreePath);
+    const removeResult = execGit(cwd, rmArgs);
+    if (removeResult.exitCode !== 0) {
+      warnings.push(`worktree remove: ${removeResult.stderr}`);
+    }
+  } else {
+    warnings.push(`worktree remove: ${toPosix(worktreePath)} is not a registered worktree (already removed?)`);
   }
 
   // Branch cleanup — only if branch still exists.

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

@@ -31,7 +31,7 @@
  *   findings record|list|dispose|debt  Judges' verdicts and their findings ledger (evidence loop)
  *   phase-plan-index <phase>           Index plans with waves and status
  *   websearch <query>                  Search web via Brave API (if configured)
- *     [--limit N] [--freshness day|week|month]
+ *     [--limit N] [--freshness day|week|month|year]
  *
  * Phase Listing:
  *   phases list [--type plans|summaries]  List phases with optional type filter
@@ -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');
@@ -208,6 +237,9 @@ const costRebuild = require('./lib/cost-rebuild.cjs');
 const preview = require('./lib/preview.cjs');
 const reviewDeep = require('./lib/review-deep.cjs');
 const findings = require('./lib/findings.cjs');
+const verifyPlanSet = require('./lib/verify-plan-set.cjs');
+const verifyIntegrity = require('./lib/verify-integrity.cjs');
+const phaseGate = require('./lib/phase-gate.cjs');
 const knowledge = require('./lib/knowledge.cjs');
 const skillAlign = require('./lib/skill-align.cjs');
 const hygiene = require('./lib/hygiene.cjs');
@@ -333,7 +365,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 +570,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;
@@ -613,8 +652,12 @@ async function main() {
         verify.cmdVerifyScope(cwd, args[2], raw);
       } else if (subcommand === 'stale') {
         verify.cmdVerifyStale(cwd, args[2], raw);
+      } else if (subcommand === 'plan-set') {
+        verifyPlanSet.cmdVerifyPlanSet(cwd, args[2], raw);
+      } else if (subcommand === 'test-integrity') {
+        verifyIntegrity.cmdVerifyTestIntegrity(cwd, args[2], raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope, stale');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope, stale, plan-set, test-integrity');
       }
       break;
     }
@@ -689,8 +732,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;
     }
@@ -722,9 +773,11 @@ async function main() {
       } else if (subcommand === 'complete') {
         if (!args[2]) error('phase complete requires a phase number');
         const noCommit = args.includes('--no-commit');
-        phase.cmdPhaseComplete(cwd, args[2], raw, { noCommit });
+        phase.cmdPhaseComplete(cwd, args[2], raw, { noCommit, force: args.includes('--force'), reason: getArgValue(args, '--reason') });
+      } else if (subcommand === 'gate') {
+        phaseGate.cmdPhaseGate(cwd, args[2], raw, { mode: getArgValue(args, '--mode') || undefined });
       } else {
-        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete');
+        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete, gate');
       }
       break;
     }
@@ -1038,7 +1091,12 @@ async function main() {
       if (subcommand === 'read') {
         memory.cmdMemoryRead(cwd, args[2], raw);
       } else if (subcommand === 'append') {
-        memory.cmdMemoryAppend(cwd, args[2], args.slice(3).join(' '), raw);
+        // `--cites <path[#symbol]>,...` is taken out before the entry words are joined.
+        const rest = args.slice(3);
+        const ci = rest.indexOf('--cites');
+        const cites = ci === -1 ? undefined : rest[ci + 1];
+        if (ci !== -1) rest.splice(ci, 2);
+        memory.cmdMemoryAppend(cwd, args[2], rest.join(' '), raw, { cites });
       } else if (subcommand === 'list') {
         memory.cmdMemoryList(cwd, raw);
       } else if (subcommand === 'compact') {
@@ -1048,7 +1106,22 @@ async function main() {
           cue: getArgValue(args, '--cue'),
           tokenBudget: getArgValue(args, '--token-budget'),
           recencyFloor: getArgValue(args, '--recency-floor'),
+          all: args.includes('--all'),
+          markUsed: args.includes('--mark-used'),
+          expireDays: getArgValue(args, '--days'),
+        }, raw);
+      } else if (subcommand === 'record') {
+        memory.cmdMemoryRecord(cwd, args[2] && !args[2].startsWith('--') ? args[2] : null, {
+          lesson: getArgValue(args, '--lesson'),
+          finding: getArgValue(args, '--finding'),
+          trace: getArgValue(args, '--trace'),
+          cites: getArgValue(args, '--cites'),
         }, raw);
+      } else if (subcommand === 'prune') {
+        const daysArg = getArgValue(args, '--days');
+        if (daysArg !== null && !/^\d+$/.test(daysArg)) error('memory prune --days needs a whole number of days (0 turns expiry off)');
+        const target = args[2] && !args[2].startsWith('--') ? args[2] : null;
+        memory.cmdMemoryPrune(cwd, target, { apply: args.includes('--apply'), days: daysArg === null ? undefined : Number(daysArg) }, raw);
       } else if (subcommand === 'budget') {
         memory.cmdMemoryBudget(cwd, raw);
       } else if (subcommand === 'optimize') {
@@ -1062,7 +1135,7 @@ async function main() {
           apply: args.includes('--apply'),
         }, raw);
       } else {
-        error('Unknown memory subcommand. Available: read, append, list, compact, select, budget, optimize, rebuild');
+        error('Unknown memory subcommand. Available: read, append, list, compact, select, record, prune, budget, optimize, rebuild');
       }
       break;
     }
@@ -1117,7 +1190,14 @@ async function main() {
     case 'knowledge': {
       const subcommand = args[1];
       if (subcommand === 'ask') {
-        const question = args.slice(2).filter(a => !a.startsWith('--')).join(' ');
+        // The question is every word after `ask` that is neither a flag nor a flag's
+        // value: `--recall-cue "session tokens" --max-sources 3` used to join it.
+        const words = [];
+        for (let i = 2; i < args.length; i++) {
+          if (args[i] === '--max-sources' || args[i] === '--recall-cue') { i++; continue; }
+          if (!args[i].startsWith('--')) words.push(args[i]);
+        }
+        const question = words.join(' ');
         const maxSources = getArgValue(args, '--max-sources');
         knowledge.cmdKnowledgeAsk(cwd, question, {
           max_sources: maxSources ? Number(maxSources) : undefined,
@@ -1249,7 +1329,8 @@ async function main() {
 
     case 'cost': {
       const subcommand = args[1];
-      if (subcommand === 'report' || !subcommand) {
+      // `report` is the default, so a leading flag (`cost --format chart`) means report, as for `links`.
+      if (subcommand === 'report' || !subcommand || subcommand.startsWith('--')) {
         const format = getArgValue(args, '--format', 'json');
         const since = getArgValue(args, '--since');
         const until = getArgValue(args, '--until');
@@ -1276,8 +1357,10 @@ async function main() {
           mainThread: !args.includes('--no-main-thread'),
           claudeDir: getArgValue(args, '--claude-dir'),
         }, raw);
+      } else if (subcommand === 'limits') {
+        cost.cmdCostLimits(cwd, raw);
       } else {
-        error('Unknown cost subcommand. Available: report, append, clear, rebuild');
+        error('Unknown cost subcommand. Available: report, append, clear, rebuild, limits');
       }
       break;
     }
@@ -1330,7 +1413,7 @@ async function main() {
         campaign.cmdCampaignSchedule(cwd, {
           goal: getArgValue(args, '--goal'),
           source: getArgValue(args, '--source'),
-          cadence: getArgValue(args, '--cadence', 'daily'),
+          cadence: getArgValue(args, '--cadence'),
           daily_budget: budget != null ? Number(budget) : undefined,
           enabled: args.includes('--disable') ? false : undefined,
           paused: args.includes('--pause') ? true : (args.includes('--resume') ? false : undefined),
@@ -1539,9 +1622,11 @@ async function main() {
           ? sourceExpsCsv.split(',').map(s => s.trim()).filter(Boolean)
           : [];
         const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
+        const citesCsv = getArgValue(args, '--cites') || '';
+        const cites = citesCsv ? citesCsv.split(',').map(s => s.trim()).filter(Boolean) : [];
 
         const result = optimize.promotePattern(
-          { id: patternId, summary, evidence, rule, applies_in: appliesIn, source_experiments: sourceExperiments },
+          { id: patternId, summary, evidence, rule, applies_in: appliesIn, source_experiments: sourceExperiments, ...(cites.length ? { cites } : {}) },
           { scope, topic, sourceRoot }
         );
         output(result, raw);
@@ -1589,9 +1674,13 @@ async function main() {
         if (!agent) { error('learn topics-for requires --agent <name>'); }
         const minRelevance = getArgValue(args, '--min-relevance', 'medium');
         const tokenBudget = parseInt(getArgValue(args, '--token-budget', '5000'), 10);
-        const result = learnIndex.cmdTopicsFor(sourceRoot, { agent, minRelevance, tokenBudget });
+        const cue = getArgValue(args, '--cue') || undefined;
+        const result = learnIndex.cmdTopicsFor(sourceRoot, { agent, minRelevance, tokenBudget, cue });
         if (raw) {
-          const lines = [`Topics for "${agent}" (min ${minRelevance}, budget ${tokenBudget}):`, ``];
+          const head = result.mode === 'cue'
+            ? `Topics for "${agent}" matching the cue (budget ${tokenBudget}):`
+            : `Topics for "${agent}" (min ${minRelevance}, budget ${tokenBudget})${cue ? ' — nothing matched the cue, so by role' : ''}:`;
+          const lines = [head, ``];
           for (const t of result.selected) {
             lines.push(`  [${t.relevance.padEnd(6)}] ${t.scope}/${t.name.padEnd(22)} ${t.tokens.toString().padStart(5)}t   ${t.patterns.join(', ')}`);
           }
@@ -1646,18 +1735,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/merge-gate.cjs

@@ -52,17 +52,28 @@ function writeJson(p, obj) { fs.mkdirSync(path.dirname(p), { recursive: true });
  * Stage a merge request. Mints a fresh per-request approval token (nonce), records the
  * exact branch + the (caller-attested) CI/verify flags, marks it awaiting_approval, and
  * returns the record. Does NOT merge. The operator sets PAN_MERGE_APPROVAL to
- * `record.approval_token` after reviewing. (ci_green/verify_pass are agent-attested
- * advisory context for the human's decision; the token is the sole unfakeable anchor.)
+ * `record.approval_token` after reviewing. ci_green is agent-attested advisory context.
+ * verify_pass is too, unless the request names a `phase`: then it is the phase gate's
+ * verdict (program V1), computed here, and the caller's flag is ignored. The token is
+ * the sole unfakeable anchor either way.
  */
 function requestMerge(cwd, opts = {}) {
   const branch = validateBranch(opts.branch);
+  let verifyPass = !!opts.verify_pass;
+  let gate = null;
+  if (opts.phase != null && String(opts.phase).trim() !== '') {
+    const g = require('../bin/lib/phase-gate.cjs').phaseGate(cwd, String(opts.phase).trim());
+    gate = g.error ? { phase: String(opts.phase), error: g.error } : { phase: g.phase, ok: g.ok, reasons: g.reasons.map((r) => r.code) };
+    verifyPass = !g.error && g.ok;
+  }
   const record = {
     id: slugify(branch),
     branch,
     approval_token: crypto.randomBytes(9).toString('hex'),
     ci_green: !!opts.ci_green,
-    verify_pass: !!opts.verify_pass,
+    verify_pass: verifyPass,
+    verify_source: gate ? 'phase_gate' : 'caller',
+    ...(gate ? { gate } : {}),
     status: 'awaiting_approval',
     requested_at: opts.now || null,
   };

package/pan-wizard-core/mcp/native-tools.cjs

@@ -126,14 +126,14 @@ const NATIVE_TOOLS = [
   {
     name: 'pan_request_merge',
     title: 'Request a gated merge',
-    description: 'Stage a squash-merge request for a branch and mark it awaiting human approval. Records intent only — does NOT merge.',
+    description: 'Stage a squash-merge request for a branch and mark it awaiting human approval. Records intent only — does NOT merge. Name the phase the branch delivers: verify_pass is then the phase gate\'s verdict, not the caller\'s flag.',
     readOnly: false, destructive: false,
     inputSchema: {
       type: 'object', additionalProperties: false, required: ['branch'],
-      properties: { branch: { type: 'string' }, ci_green: { type: 'boolean' }, verify_pass: { type: 'boolean' } },
+      properties: { branch: { type: 'string' }, ci_green: { type: 'boolean' }, verify_pass: { type: 'boolean' }, phase: { type: 'string' } },
     },
     handler: ({ cwd, input }) => ({
-      json: mergeGate.requestMerge(cwd, { branch: input.branch, ci_green: input.ci_green, verify_pass: input.verify_pass }),
+      json: mergeGate.requestMerge(cwd, { branch: input.branch, ci_green: input.ci_green, verify_pass: input.verify_pass, phase: input.phase }),
     }),
   },
   {