pan-wizard 3.12.5 → 3.14.0

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, safeReadFile, loadConfig, scanPendingTodos, scanSourceTodos, toPosix, isGitRepo, execGit } = require('./core.cjs');
+const { output, error, safeReadFile, loadConfig, scanPendingTodos, scanSourceTodos, toPosix, isGitRepo, execGit, escapeRegex } = require('./core.cjs');
 const {
   PLANNING_DIR, PHASES_DIR, ROADMAP_FILE, PATTERNS_FILE, EFFORT_POINTS, PRIORITY_LEVELS, EFFORT_SIZES,
   FOCUS_MODES, FOCUS_TIERS, FOCUS_DIR,
@@ -457,7 +457,7 @@ function checkDocStaleness(cwd, opts) {
 function checkOldCommandNames(content, file, stale) {
   for (const [oldName, newName] of Object.entries(COMMAND_RENAME_MAP)) {
     // Match /pan:old-name or pan:old-name (command references)
-    const pattern = new RegExp(`pan:${oldName.replace(/-/g, '\\-')}\\b`);
+    const pattern = new RegExp(`pan:${escapeRegex(oldName)}\\b`);
     if (pattern.test(content)) {
       stale.push({ file, entity: 'renamed_command', old: oldName, new: newName });
     }
@@ -717,6 +717,45 @@ function focusAutoStop(cwd, raw) {
   }, raw);
 }
 
+// Anti-fake (ADR-0036 review): the regression breaker compares tests_after vs
+// tests_before, both historically agent-supplied CLI args that focus-auto never
+// re-ran — so a fabricated "tests green" passed unchecked. When verification is
+// enabled (config.focus.verify_tests), re-run the node:test suite and use the
+// REAL pass count; otherwise keep the supplied value but mark the cycle
+// tests_verified:false so the loop's trust is visible to the HUD/audit/human.
+//
+// Invocation is a fixed execFile('node', ['--test']) — NO shell and NO
+// configurable command string, so there is no command-injection surface (same
+// safe pattern verify.cjs uses). If no node:test suite is present, fall back to
+// the supplied value rather than mis-firing the regression breaker.
+function verifyTestCount(cwd, config, fallback) {
+  const focusCfg = (config && config.focus) || {};
+  if (!focusCfg.verify_tests) return { tests_after: fallback, verified: false };
+  const { execFileSync } = require('child_process');
+  const num = (out, re) => { const m = String(out || '').match(re); return m ? Number(m[1]) : null; };
+  const interpret = (out, exitCode) => {
+    // node --test summary lines use either the TAP marker ("# tests N") or the
+    // spec reporter's info marker ("ℹ tests N"), depending on Node version /
+    // reporter — match both so the count is captured regardless.
+    const total = num(out, /[#ℹ]\s*tests\s+(\d+)/);
+    if (!total) return { tests_after: fallback, verified: false }; // no node:test suite here
+    const passed = num(out, /[#ℹ]\s*pass\s+(\d+)/);
+    return { tests_after: passed !== null ? passed : (exitCode === 0 ? fallback : 0), verified: true, exit_code: exitCode };
+  };
+  // Strip any NODE_TEST_* context so the child runs as a standalone runner with
+  // predictable spec/TAP output — otherwise, when focus-auto is itself invoked
+  // from within a `node --test` process, the child inherits the nested-test
+  // context and emits a serialized format we can't parse.
+  const env = { ...process.env };
+  for (const k of Object.keys(env)) { if (k.startsWith('NODE_TEST')) delete env[k]; }
+  try {
+    const out = execFileSync('node', ['--test'], { cwd, timeout: 120000, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', env });
+    return interpret(out, 0);
+  } catch (err) {
+    return interpret(err && err.stdout, (err && err.status) || 1);
+  }
+}
+
 function focusAutoUpdate(cwd, raw, getVal) {
   const run = readAutoRun(cwd);
   if (!run) return error('No auto-run in progress. Cannot update.');
@@ -735,6 +774,12 @@ function focusAutoUpdate(cwd, raw, getVal) {
     timestamp: new Date().toISOString(),
   };
 
+  // Anti-fake: re-run the suite when verification is enabled; else record that
+  // this count was self-reported (tests_verified:false) so the trust is visible.
+  const tv = verifyTestCount(cwd, loadConfig(cwd), cycle.tests_after);
+  cycle.tests_after = tv.tests_after;
+  cycle.tests_verified = tv.verified;
+
   if (!run.cycles) run.cycles = [];
   run.cycles.push(cycle);
 
@@ -1016,6 +1061,7 @@ module.exports = {
   writeAutoRun,
   cmdFocusAuto,
   determineStopReason,
+  verifyTestCount,
   // Opus 4.7
   determineContinuation,
   classifyStageDependencies,

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

@@ -822,13 +822,29 @@ ${body}
 
 function openInBrowser(filePath) {
   const { execFileSync } = require('child_process');
+  // Only open a path we can resolve to an existing regular file, and refuse
+  // anything carrying shell/cmd metacharacters — on Windows `start` is a cmd
+  // builtin that re-parses its command line, so a crafted --out value must not
+  // be able to reach it. The allowlist check is the taint barrier; `resolved`
+  // is what actually gets opened.
+  let resolved;
+  try {
+    resolved = path.resolve(filePath);
+    if (!fs.statSync(resolved).isFile()) return false;
+  } catch {
+    return false;
+  }
+  // Allowlist barrier: only ordinary path characters may reach the opener.
+  // Anything outside this set (shell/cmd metacharacters, quotes, newlines) is
+  // rejected outright, so a crafted --out value cannot reach Windows `start`.
+  if (!/^[A-Za-z0-9 _.:\\/()-]+$/.test(resolved)) return false;
   try {
     if (process.platform === 'win32') {
-      execFileSync('cmd', ['/c', 'start', '', filePath], { stdio: 'ignore' });
+      execFileSync('cmd', ['/c', 'start', '', resolved], { stdio: 'ignore' });
     } else if (process.platform === 'darwin') {
-      execFileSync('open', [filePath], { stdio: 'ignore' });
+      execFileSync('open', [resolved], { stdio: 'ignore' });
     } else {
-      execFileSync('xdg-open', [filePath], { stdio: 'ignore' });
+      execFileSync('xdg-open', [resolved], { stdio: 'ignore' });
     }
     return true;
   } catch {

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

@@ -0,0 +1,447 @@
+/**
+ * Hygiene — project cleanup + version alignment (ADR: docs/FIELD-HARVEST-2026-07.md follow-ups).
+ *
+ * A PAN-managed project accumulates drift as PAN versions advance and
+ * campaigns run: runtime installs fall behind the latest version, legacy
+ * uppercase planning filenames linger from pre-v2.2 layouts, atomic-write
+ * .tmp orphans survive crashes, per-agent memory logs grow past the cap,
+ * cost ledgers written by pre-v3.12.4 hooks are 100% poisoned, telemetry
+ * trace sessions pile up unboundedly, and stray fragment `.planning/`
+ * directories appear where a mapping step once ran.
+ *
+ * Two commands, one module:
+ *   - scan  — detect all of the above, report findings (read-only)
+ *   - clean — apply the SAFE fixes (case renames, tmp removal, memory
+ *             compaction, ledger quarantine-by-rename, trace pruning);
+ *             dry-run by default, `--apply` to execute. Version drift and
+ *             fragment dirs are never auto-fixed — they get remediation
+ *             text instead (installer re-run / manual delete).
+ *
+ * Nothing here deletes user content: the poisoned ledger is renamed in
+ * place (quarantined-<date> suffix), and only derived/ephemeral artifacts
+ * (.tmp orphans, aged trace sessions) are removed outright.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, safeReadFile, toPosix } = require('./core.cjs');
+const {
+  PLANNING_DIR,
+  HYGIENE_TRACE_RETENTION_DAYS,
+  HYGIENE_TRACE_KEEP_MIN,
+  HYGIENE_LEDGER_SUSPECT_RATIO,
+  HYGIENE_LEDGER_MIN_RECORDS,
+  HYGIENE_TMP_AGE_MS,
+} = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+const { listMemoryAgents, readMemory, compactMemory } = require('./memory.cjs');
+const { readRecords, isSuspectRecord, METRICS_DIR, TOKENS_FILE } = require('./cost.cjs');
+
+/** Runtime config dirs a PAN install can live in, relative to project root. */
+const RUNTIME_DIRS = [
+  { runtime: 'claude', dir: '.claude' },
+  { runtime: 'codex', dir: '.codex' },
+  { runtime: 'gemini', dir: '.gemini' },
+  { runtime: 'opencode', dir: '.opencode' },
+  { runtime: 'copilot', dir: '.github' },
+];
+
+const MANIFEST_NAME = 'pan-file-manifest.json';
+
+/** Pre-v2.2 uppercase planning filenames whose canonical form is lowercase. */
+const LEGACY_UPPERCASE_FILES = [
+  'STATE.md', 'ROADMAP.md', 'PROJECT.md', 'REQUIREMENTS.md',
+  'MILESTONES.md', 'STANDARDS.md', 'PAUSE.md',
+];
+
+const MEMORY_ENTRY_CAP = (() => {
+  try { return require('./memory.cjs').DEFAULT_MAX_ENTRIES || 500; } catch { return 500; }
+})();
+
+// ─── Small helpers ──────────────────────────────────────────────────────────
+
+/** Compare dotted versions; returns -1/0/1. Tolerates missing segments. */
+function compareVersions(a, b) {
+  const pa = String(a || '0').split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b || '0').split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Version of the pan-wizard-core copy executing this code (install or source root). */
+function ownVersion() {
+  const pkg = safeReadFile(path.resolve(__dirname, '..', '..', '..', 'package.json'));
+  if (!pkg) return null;
+  try { return JSON.parse(pkg).version || null; } catch { return null; }
+}
+
+function mkFinding(check, severity, relPath, detail, fix) {
+  return { check, severity, path: toPosix(relPath), detail, fix: fix || null, fixable: !!fix };
+}
+
+// ─── Checks ─────────────────────────────────────────────────────────────────
+
+/**
+ * H-1: version alignment across runtime installs. Report-only — the fix is
+ * re-running the installer, which hygiene must not do on its own.
+ */
+function checkVersionAlignment(cwd) {
+  const findings = [];
+  const installs = [];
+  for (const { runtime, dir } of RUNTIME_DIRS) {
+    const manifestPath = path.join(cwd, dir, MANIFEST_NAME);
+    const raw = safeReadFile(manifestPath);
+    if (raw === null) {
+      // A pan-wizard-core copy without a manifest is an untracked install.
+      let hasCore = false;
+      try { fs.accessSync(path.join(cwd, dir, 'pan-wizard-core')); hasCore = true; } catch { /* absent */ }
+      if (hasCore) {
+        findings.push(mkFinding('version-alignment', 'warn', path.join(dir),
+          `${runtime}: pan-wizard-core present but no ${MANIFEST_NAME} — untracked install`,
+          null));
+      }
+      continue;
+    }
+    let version = null;
+    try { version = JSON.parse(raw).version || null; } catch { /* malformed */ }
+    installs.push({ runtime, dir, version });
+  }
+
+  const own = ownVersion();
+  const latest = [own, ...installs.map(i => i.version)]
+    .filter(Boolean)
+    .sort(compareVersions)
+    .pop() || null;
+
+  for (const i of installs) {
+    if (i.version && latest && compareVersions(i.version, latest) < 0) {
+      findings.push(mkFinding('version-alignment', 'warn', i.dir,
+        `${i.runtime}: installed ${i.version}, latest ${latest} — re-run the installer to align`,
+        null));
+    }
+    if (!i.version) {
+      findings.push(mkFinding('version-alignment', 'warn', i.dir,
+        `${i.runtime}: manifest has no version field — re-run the installer`,
+        null));
+    }
+  }
+  return { findings, installs, latest_version: latest };
+}
+
+/** H-2: legacy uppercase planning filenames (pre-v2.2 layout). */
+function checkLegacyUppercase(cwd) {
+  const findings = [];
+  const dir = planningPath(cwd);
+  let entries = [];
+  try { entries = fs.readdirSync(dir); } catch { return { findings }; }
+  for (const name of entries) {
+    if (!LEGACY_UPPERCASE_FILES.includes(name)) continue;
+    const lower = name.toLowerCase();
+    // Case-sensitive twin check via literal directory listing (existsSync is
+    // case-insensitive on Windows and would always be true here).
+    const twin = entries.includes(lower);
+    if (twin) {
+      findings.push(mkFinding('legacy-filenames', 'warn', path.join(PLANNING_DIR, name),
+        `legacy ${name} coexists with ${lower} — merge manually, auto-rename would clobber`,
+        null));
+    } else {
+      findings.push(mkFinding('legacy-filenames', 'warn', path.join(PLANNING_DIR, name),
+        `legacy uppercase filename — canonical form is ${lower}`,
+        { action: 'rename-lowercase', from: name, to: lower }));
+    }
+  }
+  return { findings };
+}
+
+/** Bounded recursive walk of .planning collecting file paths. */
+function walkPlanning(cwd, maxDepth = 5) {
+  const root = planningPath(cwd);
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > maxDepth) return;
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) walk(abs, depth + 1);
+      else out.push(abs);
+    }
+  };
+  walk(root, 0);
+  return out;
+}
+
+/** H-3: orphaned atomic-write .tmp files older than the age threshold. */
+function checkTmpOrphans(cwd, now = Date.now()) {
+  const findings = [];
+  for (const abs of walkPlanning(cwd)) {
+    if (!abs.endsWith('.tmp')) continue;
+    let stat;
+    try { stat = fs.statSync(abs); } catch { continue; }
+    if (now - stat.mtimeMs < HYGIENE_TMP_AGE_MS) continue;
+    findings.push(mkFinding('tmp-orphans', 'info', path.relative(cwd, abs),
+      `orphaned atomic-write temp file (age ${Math.round((now - stat.mtimeMs) / 3600000)}h)`,
+      { action: 'delete' }));
+  }
+  return { findings };
+}
+
+/** H-4: per-agent memory logs past the entry cap (compaction never ran). */
+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',
+      path.join(PLANNING_DIR, 'memory', `${a.agent}.md`),
+      `${mem.entries.length} entries exceeds cap ${MEMORY_ENTRY_CAP} — whole-file reads flood context`,
+      { action: 'compact-memory', agent: a.agent }));
+  }
+  return { findings };
+}
+
+/** H-5: cost ledger dominated by physically implausible (pre-v3.12.4) records. */
+function checkCostLedger(cwd) {
+  const findings = [];
+  let records = [];
+  try { records = readRecords(cwd) || []; } catch { return { findings }; }
+  if (records.length < HYGIENE_LEDGER_MIN_RECORDS) return { findings };
+  const suspect = records.filter(r => isSuspectRecord(r)).length;
+  const ratio = suspect / records.length;
+  if (ratio < HYGIENE_LEDGER_SUSPECT_RATIO) return { findings };
+  findings.push(mkFinding('poisoned-ledger', 'critical',
+    path.join(PLANNING_DIR, METRICS_DIR, TOKENS_FILE),
+    `${suspect}/${records.length} records are suspect (${Math.round(ratio * 100)}%) — pre-v3.12.4 oversum signature; aggregates quarantine them but the file is dead weight`,
+    { action: 'quarantine-ledger' }));
+  return { findings };
+}
+
+/** H-6: telemetry trace sessions beyond retention (always keep the newest few). */
+function checkStaleTraces(cwd, opts, now = Date.now()) {
+  const findings = [];
+  const retentionDays = Number(opts?.traceAgeDays) || HYGIENE_TRACE_RETENTION_DAYS;
+  const tracesDir = path.join(planningPath(cwd), 'optimization', 'traces');
+  let entries = [];
+  try { entries = fs.readdirSync(tracesDir, { withFileTypes: true }); } catch { return { findings }; }
+  const sessions = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const abs = path.join(tracesDir, e.name);
+    let stat;
+    try { stat = fs.statSync(abs); } catch { continue; }
+    sessions.push({ name: e.name, abs, mtime: stat.mtimeMs });
+  }
+  sessions.sort((a, b) => b.mtime - a.mtime);
+  const cutoff = now - retentionDays * 24 * 3600 * 1000;
+  for (const s of sessions.slice(HYGIENE_TRACE_KEEP_MIN)) {
+    if (s.mtime >= cutoff) continue;
+    findings.push(mkFinding('stale-traces', 'info',
+      path.relative(cwd, s.abs),
+      `trace session older than ${retentionDays}d retention (and not among newest ${HYGIENE_TRACE_KEEP_MIN})`,
+      { action: 'delete-dir' }));
+  }
+  return { findings };
+}
+
+/** H-7: fragment .planning — artifacts present but no project spine. Report-only. */
+function checkPlanningFragment(cwd) {
+  const findings = [];
+  const dir = planningPath(cwd);
+  let entries = [];
+  try { entries = fs.readdirSync(dir); } catch { return { findings, planning_exists: false }; }
+  const lower = entries.map(e => e.toLowerCase());
+  // Spine = anything that marks a deliberate PAN workflow: the phase model
+  // (project/state/phases/roadmap/requirements/milestones) OR the focus model
+  // (focus/quick) OR an orchestration campaign. A dir holding only generated
+  // artifacts (codebase maps, metrics, traces) is a stray fragment.
+  const SPINE = ['project.md', 'state.md', 'phases', 'roadmap.md', 'requirements.md',
+    'milestones', 'focus', 'quick', 'orchestration'];
+  const hasSpine = SPINE.some(s => lower.includes(s));
+  if (!hasSpine && entries.length > 0) {
+    findings.push(mkFinding('planning-fragment', 'info', PLANNING_DIR,
+      `.planning exists with ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} (${entries.slice(0, 5).join(', ')}) but no workflow spine (project/state/phases/focus/…) — likely a stray partial run; review and delete manually`,
+      null));
+  }
+  return { findings, planning_exists: true };
+}
+
+// ─── Scan ───────────────────────────────────────────────────────────────────
+
+/**
+ * Run all hygiene checks. Read-only.
+ *
+ * @param {string} cwd - project root
+ * @param {Object} [opts] - {traceAgeDays}
+ * @returns {Object} {findings, installs, latest_version, planning_exists, summary}
+ */
+function scanHygiene(cwd, opts) {
+  const version = checkVersionAlignment(cwd);
+  const fragment = checkPlanningFragment(cwd);
+  const findings = [
+    ...version.findings,
+    ...fragment.findings,
+    ...checkLegacyUppercase(cwd).findings,
+    ...checkTmpOrphans(cwd).findings,
+    ...checkMemoryLogs(cwd).findings,
+    ...checkCostLedger(cwd).findings,
+    ...checkStaleTraces(cwd, opts).findings,
+  ];
+  const byCheck = {};
+  for (const f of findings) byCheck[f.check] = (byCheck[f.check] || 0) + 1;
+  return {
+    findings,
+    installs: version.installs,
+    latest_version: version.latest_version,
+    planning_exists: fragment.planning_exists !== false,
+    summary: {
+      total: findings.length,
+      fixable: findings.filter(f => f.fixable).length,
+      by_check: byCheck,
+      by_severity: findings.reduce((m, f) => { m[f.severity] = (m[f.severity] || 0) + 1; return m; }, {}),
+    },
+  };
+}
+
+// ─── Clean ──────────────────────────────────────────────────────────────────
+
+function applyFix(cwd, finding) {
+  const fix = finding.fix;
+  const abs = path.join(cwd, finding.path);
+  try {
+    switch (fix.action) {
+      case 'rename-lowercase': {
+        // Two-step rename: Windows treats case-only renames inconsistently
+        // across fs layers, so hop through a temp name.
+        const dir = path.dirname(abs);
+        const hop = path.join(dir, `${fix.to}.case-hop`);
+        fs.renameSync(abs, hop);
+        fs.renameSync(hop, path.join(dir, fix.to));
+        return { applied: true, detail: `renamed ${fix.from} -> ${fix.to}` };
+      }
+      case 'delete':
+        fs.unlinkSync(abs);
+        return { applied: true, detail: 'deleted' };
+      case 'delete-dir':
+        fs.rmSync(abs, { recursive: true, force: true });
+        return { applied: true, detail: 'removed directory' };
+      case 'compact-memory': {
+        const r = compactMemory(cwd, fix.agent);
+        if (r.error) return { applied: false, detail: r.error };
+        return { applied: true, detail: `compacted to ${r.kept ?? r.entries ?? 'cap'} entries` };
+      }
+      case 'quarantine-ledger': {
+        const stamp = new Date().toISOString().slice(0, 10);
+        const dest = `${abs}.quarantined-${stamp}`;
+        fs.renameSync(abs, dest);
+        return { applied: true, detail: `renamed to ${path.basename(dest)} — fresh ledger starts clean` };
+      }
+      default:
+        return { applied: false, detail: `unknown fix action ${fix.action}` };
+    }
+  } catch (e) {
+    return { applied: false, detail: `fix failed: ${e.message}` };
+  }
+}
+
+/**
+ * Apply safe fixes for fixable findings. Dry-run unless opts.apply.
+ *
+ * @param {string} cwd
+ * @param {Object} [opts] - {apply, traceAgeDays}
+ * @returns {Object} {dry_run, applied, skipped, remaining, summary}
+ */
+function cleanHygiene(cwd, opts) {
+  const scan = scanHygiene(cwd, opts);
+  const apply = !!opts?.apply;
+  const applied = [];
+  const skipped = [];
+  for (const f of scan.findings) {
+    if (!f.fixable) {
+      skipped.push({ check: f.check, path: f.path, reason: 'no safe auto-fix — see detail', detail: f.detail });
+      continue;
+    }
+    if (!apply) {
+      applied.push({ check: f.check, path: f.path, action: f.fix.action, applied: false, detail: 'dry-run' });
+      continue;
+    }
+    const result = applyFix(cwd, f);
+    applied.push({ check: f.check, path: f.path, action: f.fix.action, ...result });
+  }
+  return {
+    dry_run: !apply,
+    applied,
+    skipped,
+    summary: {
+      fixable: applied.length,
+      executed: applied.filter(a => a.applied).length,
+      failed: apply ? applied.filter(a => !a.applied).length : 0,
+      manual: skipped.length,
+    },
+  };
+}
+
+// ─── CLI wrappers ───────────────────────────────────────────────────────────
+
+function renderFindings(findings) {
+  const lines = [];
+  for (const f of findings) {
+    lines.push(`  [${f.severity.toUpperCase().padEnd(8)}] ${f.check.padEnd(18)} ${f.path}`);
+    lines.push(`             ${f.detail}${f.fixable ? '  (auto-fixable)' : ''}`);
+  }
+  return lines;
+}
+
+function cmdHygieneScan(cwd, opts, raw) {
+  const result = scanHygiene(cwd, opts);
+  if (raw) {
+    const lines = [`Hygiene scan: ${result.summary.total} finding(s), ${result.summary.fixable} auto-fixable`];
+    if (result.latest_version) {
+      lines.push(`Latest version seen: ${result.latest_version}; installs: ${result.installs.map(i => `${i.runtime}@${i.version || '?'}`).join(', ') || 'none'}`);
+    }
+    lines.push('', ...renderFindings(result.findings));
+    if (result.findings.length === 0) lines.push('  Clean — nothing to do.');
+    output(result, true, lines.join('\n'));
+  } else {
+    output(result, false);
+  }
+}
+
+function cmdHygieneClean(cwd, opts, raw) {
+  const result = cleanHygiene(cwd, opts);
+  if (raw) {
+    const mode = result.dry_run ? 'DRY-RUN (pass --apply to execute)' : 'APPLIED';
+    const lines = [`Hygiene clean — ${mode}`, ''];
+    for (const a of result.applied) {
+      lines.push(`  ${a.applied ? '✓' : (result.dry_run ? '·' : '✗')} ${a.action.padEnd(18)} ${a.path}  ${a.detail}`);
+    }
+    for (const s of result.skipped) {
+      lines.push(`  ! manual            ${s.path}  ${s.detail}`);
+    }
+    lines.push('', `fixable: ${result.summary.fixable}, executed: ${result.summary.executed}, failed: ${result.summary.failed}, manual: ${result.summary.manual}`);
+    output(result, true, lines.join('\n'));
+  } else {
+    output(result, false);
+  }
+}
+
+module.exports = {
+  scanHygiene,
+  cleanHygiene,
+  checkVersionAlignment,
+  checkLegacyUppercase,
+  checkTmpOrphans,
+  checkMemoryLogs,
+  checkCostLedger,
+  checkStaleTraces,
+  checkPlanningFragment,
+  compareVersions,
+  cmdHygieneScan,
+  cmdHygieneClean,
+  RUNTIME_DIRS,
+  LEGACY_UPPERCASE_FILES,
+};

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

@@ -14,7 +14,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, safeReadFile, toPosix } = require('./core.cjs');
+const { output, error, safeReadFile, toPosix, escapeRegex } = require('./core.cjs');
 const { PLANNING_DIR } = require('./constants.cjs');
 const { planningPath } = require('./utils.cjs');
 const { listMemoryAgents, readMemory } = require('./memory.cjs');
@@ -56,7 +56,7 @@ function scoreRelevance(question, content) {
   const body = content.toLowerCase();
   let score = 0;
   for (const w of words) {
-    const count = (body.match(new RegExp(`\\b${w.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\b`, 'g')) || []).length;
+    const count = (body.match(new RegExp(`\\b${escapeRegex(w)}\\b`, 'g')) || []).length;
     score += count;
   }
   return score;
@@ -66,15 +66,20 @@ function scoreRelevance(question, content) {
  * Walk a path (file or directory, 1 level deep for .md files) and return
  * {file, score} entries.
  */
-function gatherCandidates(cwd, question) {
+function gatherCandidates(cwd, question, recallCue) {
   const candidates = [];
+  const mk = (rel, content) => ({
+    file: toPosix(rel),
+    score: scoreRelevance(question, content),
+    recall_score: recallCue ? scoreRelevance(recallCue, content) : 0,
+    bytes: Buffer.byteLength(content || '', 'utf-8'),
+  });
   for (const rel of CITATION_ROOTS) {
     const abs = path.join(cwd, rel);
     let stat;
     try { stat = fs.statSync(abs); } catch { continue; }
     if (stat.isFile()) {
-      const content = safeReadFile(abs);
-      candidates.push({ file: toPosix(rel), score: scoreRelevance(question, content), bytes: Buffer.byteLength(content || '', 'utf-8') });
+      candidates.push(mk(rel, safeReadFile(abs)));
     } else if (stat.isDirectory()) {
       let entries = [];
       try { entries = fs.readdirSync(abs); } catch { continue; }
@@ -83,18 +88,14 @@ function gatherCandidates(cwd, question) {
         let entryStat;
         try { entryStat = fs.statSync(entryAbs); } catch { continue; }
         if (entryStat.isFile() && entry.endsWith('.md')) {
-          const entryRel = toPosix(path.join(rel, entry));
-          const content = safeReadFile(entryAbs);
-          candidates.push({ file: entryRel, score: scoreRelevance(question, content), bytes: Buffer.byteLength(content || '', 'utf-8') });
+          candidates.push(mk(path.join(rel, entry), safeReadFile(entryAbs)));
         } else if (entryStat.isDirectory()) {
           // One more level for phases/<NN>/ and milestones/
           let sub = [];
           try { sub = fs.readdirSync(entryAbs); } catch { continue; }
           for (const s of sub) {
             if (!s.endsWith('.md')) continue;
-            const subRel = toPosix(path.join(rel, entry, s));
-            const content = safeReadFile(path.join(entryAbs, s));
-            candidates.push({ file: subRel, score: scoreRelevance(question, content), bytes: Buffer.byteLength(content || '', 'utf-8') });
+            candidates.push(mk(path.join(rel, entry, s), safeReadFile(path.join(entryAbs, s))));
           }
         }
       }
@@ -116,17 +117,32 @@ function ask(cwd, question, opts) {
     return { error: 'question must be a non-empty string' };
   }
   const max = Math.max(1, Math.min(100, Number(opts?.max_sources) || DEFAULT_MAX_SOURCES));
-  const all = gatherCandidates(cwd, question);
+  const recallCue = opts && typeof opts.recall_cue === 'string' && opts.recall_cue.trim()
+    ? opts.recall_cue.trim() : null;
+  const all = gatherCandidates(cwd, question, recallCue);
   const ranked = all
     .filter(c => c.score > 0 || c.file.endsWith('project.md') || c.file.endsWith('requirements.md'))
     .sort((a, b) => b.score - a.score || a.file.localeCompare(b.file))
     .slice(0, max);
-  return {
+  const result = {
     question,
-    sources: ranked,
+    // Strip the internal recall_score so `sources` keeps its {file, score, bytes} shape.
+    sources: ranked.map(({ recall_score, ...rest }) => rest),
     total_candidates: all.length,
     returned: ranked.length,
   };
+  if (recallCue) {
+    // FW-1 (minimal, ADR-0036): re-score the SAME already-gathered candidates
+    // against a follow-up cue and return a tighter recall slice — no second
+    // filesystem walk, no new dependency, still distill-and-select.
+    result.recall_cue = recallCue;
+    result.recall_sources = all
+      .filter(c => c.recall_score > 0)
+      .sort((a, b) => b.recall_score - a.recall_score || a.file.localeCompare(b.file))
+      .slice(0, max)
+      .map(c => ({ file: c.file, recall_score: c.recall_score, bytes: c.bytes }));
+  }
+  return result;
 }
 
 // ─── Mode: discuss — session state for multi-turn conversations ────────────