pan-wizard 3.31.0 → 3.33.0

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

@@ -0,0 +1,223 @@
+'use strict';
+/**
+ * Verify scope — the mechanical half of the unrequested-work check (market item M11,
+ * evidence loop spec D12). Re-exported by verify.cjs, like the other verify-* modules.
+ *
+ * It answers one question in code: which files did this phase change that none of
+ * its plans declared? The verifier judges each candidate. Tests for a declared file
+ * or a config change the feature needs are supporting work; anything else it
+ * records as `unrequested:` in verification.md. A candidate is a lead, not a
+ * finding: code cannot tell scope creep from necessary glue.
+ *
+ *   declared = the union of the phase plans' `files_modified`
+ *   changed  = files touched by the phase's plan commits (subject `{type}({phase}-{plan}):`,
+ *              the executor's convention), plus the summaries' `key-files`
+ *   excluded = the planning tree, lockfiles, and PAN's own runtime directories
+ */
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, execGit, findPhaseInternal, toPosix, output, escapeRegex } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { isPlanFile, isSummaryFile, isVerificationFile } = require('./constants.cjs');
+const { planningRel } = require('./utils.cjs');
+
+const LOCKFILES = new Set([
+  'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lockb', 'bun.lock',
+  'Cargo.lock', 'go.sum', 'poetry.lock', 'Pipfile.lock', 'uv.lock', 'composer.lock', 'Gemfile.lock', 'mix.lock', 'pubspec.lock',
+]);
+// 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']);
+const TEST_PATH_RE = /(^|\/)(tests?|__tests__|specs?)\//i;
+const TEST_FILE_RE = /\.(test|spec)\.[a-z0-9]+$/i;
+const COMMIT_SCAN_LIMIT = 2000;
+
+function normalisePath(p) {
+  return toPosix(String(p || '').trim()).replace(/^\.\/+/, '').replace(/\\/g, '/');
+}
+
+function asList(v) {
+  if (Array.isArray(v)) return v.map(String);
+  if (typeof v === 'string' && v.trim()) return [v];
+  return [];
+}
+
+/** A file's stem without directory, a test/spec infix, or extension: `src/auth.ts` → `auth`. */
+function stem(p) {
+  return path.posix.basename(p).replace(/\.(test|spec)(?=\.)/i, '').replace(/\.[^.]+$/, '').toLowerCase();
+}
+
+function isDeclared(file, declared) {
+  for (const d of declared) {
+    if (d === file) return true;
+    if (d.endsWith('/') && file.startsWith(d)) return true;
+  }
+  return false;
+}
+
+function exclusionReason(file, planningPrefix) {
+  if (file === planningPrefix || file.startsWith(planningPrefix + '/')) return 'planning tree';
+  if (LOCKFILES.has(path.posix.basename(file))) return 'lockfile';
+  if (PAN_OWNED_FILES.has(file) || PAN_OWNED_PREFIXES.some((p) => file.startsWith(p))) return 'PAN runtime directory';
+  return null;
+}
+
+/**
+ * Files the phase's plan commits touched, paths relative to `cwd` (git's --relative).
+ * @returns {{git: boolean, commits: number, files: Set<string>}}
+ */
+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() };
+  // `{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();
+  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++;
+      continue;
+    }
+    if (inPhase && line.trim()) files.add(normalisePath(line));
+  }
+  return { git: true, commits, files };
+}
+
+/**
+ * The scope check for one phase.
+ * @returns {Object} `{phase, directory, declared, changed, candidates, excluded, git, commits}` or `{error}`
+ */
+function scopePhase(cwd, phase) {
+  const info = findPhaseInternal(cwd, phase);
+  if (!info) return { error: 'phase_not_found', reason: `no phase directory for phase ${phase}` };
+  const dir = path.join(cwd, info.directory);
+  const declared = new Set();
+  for (const f of info.plans.filter(isPlanFile)) {
+    const fm = extractFrontmatter(safeReadFile(path.join(dir, f)) || '');
+    for (const p of asList(fm.files_modified || fm['files-modified'])) {
+      const n = normalisePath(p);
+      if (n) declared.add(n);
+    }
+  }
+  const sources = new Map();
+  const note = (file, source) => {
+    if (!file) return;
+    if (!sources.has(file)) sources.set(file, new Set());
+    sources.get(file).add(source);
+  };
+  for (const f of info.summaries.filter(isSummaryFile)) {
+    const fm = extractFrontmatter(safeReadFile(path.join(dir, f)) || '');
+    const kf = fm['key-files'] || fm.key_files || {};
+    for (const p of [...asList(kf.created), ...asList(kf.modified)]) note(normalisePath(p), 'summary');
+  }
+  const git = committedFiles(cwd, info.phase_number);
+  for (const p of git.files) note(p, 'commit');
+
+  const planningPrefix = normalisePath(planningRel());
+  const declaredList = [...declared].sort();
+  const declaredStems = new Set(declaredList.filter((d) => !d.endsWith('/')).map(stem));
+  const changed = [...sources.keys()].sort();
+  const candidates = [];
+  const excluded = [];
+  for (const file of changed) {
+    const why = exclusionReason(file, planningPrefix);
+    if (why) { excluded.push({ path: file, reason: why }); continue; }
+    if (isDeclared(file, declared)) continue;
+    const isTest = TEST_PATH_RE.test(file) || TEST_FILE_RE.test(file);
+    candidates.push({
+      path: file,
+      hint: isTest && declaredStems.has(stem(file)) ? 'test_for_declared' : null,
+      sources: [...sources.get(file)].sort(),
+    });
+  }
+  return {
+    phase: info.phase_number,
+    directory: info.directory,
+    declared: declaredList,
+    changed,
+    candidates,
+    excluded,
+    git: git.git,
+    commits: git.commits,
+  };
+}
+
+function cmdVerifyScope(cwd, phase, raw) {
+  if (!phase) { output({ error: 'phase_required', reason: 'Usage: verify scope <phase>' }, raw); return; }
+  const r = scopePhase(cwd, phase);
+  output(r, raw, r.error ? undefined : String(r.candidates.length));
+}
+
+// ─── Stale verification (market-ideas M27) ───────────────────────────────────
+// A verification describes the code at one commit. Until 2026-10-03 nothing tied it
+// to that commit, so a phase edited after it passed still read as verified. The
+// verifier now records `verified_commit`; any file the phase covers that changed
+// since then, committed or not, makes the verification stale.
+
+const SHA_RE = /^[0-9a-f]{7,40}$/i;
+
+/**
+ * The files a phase's verification covered: the plans' declared `files_modified` and
+ * the summaries' `key-files`, minus the planning tree, lockfiles and PAN's runtime
+ * directories. No git log scan, so `progress` can afford it for every phase.
+ */
+function coveredFiles(cwd, info) {
+  const dir = path.join(cwd, info.directory);
+  const files = new Set();
+  for (const f of info.plans.filter(isPlanFile)) {
+    const fm = extractFrontmatter(safeReadFile(path.join(dir, f)) || '');
+    for (const p of asList(fm.files_modified || fm['files-modified'])) files.add(normalisePath(p));
+  }
+  for (const f of info.summaries.filter(isSummaryFile)) {
+    const fm = extractFrontmatter(safeReadFile(path.join(dir, f)) || '');
+    const kf = fm['key-files'] || fm.key_files || {};
+    for (const p of [...asList(kf.created), ...asList(kf.modified)]) files.add(normalisePath(p));
+  }
+  const planningPrefix = normalisePath(planningRel());
+  return [...files].filter((f) => f && !exclusionReason(f, planningPrefix)).sort();
+}
+
+/**
+ * Whether a phase's verification still describes the code.
+ * @param {string} cwd
+ * @param {string} phase
+ * @param {Object} [info] - findPhaseInternal's result, when the caller already has it
+ * @returns {Object} `{phase, state, verified_commit, verification, changed_since, reason?}` or `{error, reason}`.
+ *   state: `fresh` · `stale` (covered files changed since the verified commit) ·
+ *   `unverified` (no verification file) · `unknown` (no usable verified_commit, or no git)
+ */
+function verificationFreshness(cwd, phase, info) {
+  info = info || findPhaseInternal(cwd, phase);
+  if (!info) return { error: 'phase_not_found', reason: `no phase directory for phase ${phase}` };
+  const dir = path.join(cwd, info.directory);
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { /* unreadable: no verification */ }
+  const verification = names.filter(isVerificationFile).sort().pop() || null;
+  const base = { phase: info.phase_number, state: 'unverified', verified_commit: null, verification: verification ? toPosix(path.join(info.directory, verification)) : null, changed_since: [] };
+  if (!verification) return base;
+  const fm = extractFrontmatter(safeReadFile(path.join(dir, verification)) || '');
+  const sha = String(fm.verified_commit || '').trim();
+  if (!SHA_RE.test(sha)) return { ...base, state: 'unknown', reason: 'the verification records no verified_commit' };
+  const known = execGit(cwd, ['cat-file', '-e', `${sha}^{commit}`]);
+  if (known.exitCode !== 0) return { ...base, state: 'unknown', verified_commit: sha, reason: 'the verified commit is not in this repository (rebased, squashed, or no git)' };
+  const covered = coveredFiles(cwd, info);
+  if (!covered.length) return { ...base, state: 'unknown', verified_commit: sha, reason: 'the phase declares no files to compare' };
+  // Against the working tree, not HEAD: an uncommitted edit makes the pass stale too.
+  const diff = execGit(cwd, ['-c', 'core.quotepath=off', 'diff', '--name-only', '--relative', sha, '--', ...covered]);
+  if (diff.exitCode !== 0) return { ...base, state: 'unknown', verified_commit: sha, reason: 'git diff failed' };
+  const changed = diff.stdout.split('\n').map(normalisePath).filter(Boolean).sort();
+  return { ...base, state: changed.length ? 'stale' : 'fresh', verified_commit: sha, changed_since: changed };
+}
+
+function cmdVerifyStale(cwd, phase, raw) {
+  if (!phase) { output({ error: 'phase_required', reason: 'Usage: verify stale <phase>' }, raw); return; }
+  const r = verificationFreshness(cwd, phase);
+  output(r, raw, r.error ? undefined : r.state);
+}
+
+module.exports = { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale, coveredFiles, LOCKFILES };

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { safeReadFile, normalizePhaseName, comparePhaseNum, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, EXIT_OK, error, escapeRegex } = require('./core.cjs');
+const { safeReadFile, normalizePhaseName, comparePhaseNum, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, EXIT_OK, error, escapeRegex, loadConfig, isGitIgnored, isGitRepo } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd, readStateSafe } = require('./state.cjs');
 const {
@@ -16,12 +16,14 @@ 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, verificationFreshness, cmdVerifyStale } = require('./verify-scope.cjs');
 const { planningRootRel } = require('./planning-root.cjs');
 
 /**
@@ -115,6 +117,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
@@ -138,14 +190,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);
@@ -155,11 +217,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');
@@ -821,6 +891,23 @@ function checkStateFile(cwd, addIssue, repairs) {
  * @param {Function} addIssue - Issue recording callback
  * @param {string[]} repairs - Mutable array of repair actions to schedule
  */
+/**
+ * I005: the planning tree is ignored by git while `commit_docs` is on, so every
+ * `pan-tools commit` of planning docs commits nothing, silently. planning-with-files
+ * adds `.planning/` to .gitignore by default (its README, read 2026-09-28), which is
+ * how a PAN project ends up like this (market item M3). Info, not a warning: keeping
+ * the docs out of git is a legitimate choice, and it is one config key away.
+ */
+function checkPlanningIgnored(cwd, addIssue) {
+  try {
+    if (loadConfig(cwd).commit_docs === false || !isGitRepo(cwd)) return;
+    const rel = planningRootRel();
+    if (!isGitIgnored(cwd, `${rel}/`)) return;
+    addIssue('info', 'I005', `${rel}/ is ignored by git while commit_docs is true, so PAN's planning commits commit nothing`,
+      `Remove ${rel}/ from .gitignore (planning-with-files adds it by default), or keep the docs out of git on purpose: pan-tools config-set commit_docs false`);
+  } catch { /* best effort: a git failure is not a finding */ }
+}
+
 function checkConfigFile(cwd, addIssue, repairs) {
   const configFullPath = path.join(planningPath(cwd), CONFIG_FILE);
   let rawContent;
@@ -838,6 +925,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);
@@ -1314,7 +1410,9 @@ function cmdValidateHealth(cwd, options, raw) {
   // error and stop: E002-E005 would describe a foreign layout as a broken PAN one,
   // and --repair must never write into it. Reality check R15.
   const foreign = detectForeignPlanningTree(planningPath(cwd));
-  if (foreign) {
+  if (foreign && foreign.coexists) {
+    addIssue('info', 'I004', `${foreign.tool} also writes into this planning tree: ${foreign.evidence.join(', ')}`, 'None needed: PAN leaves its files alone. Give PAN its own tree with --planning-dir if you prefer them apart (ADR-0043)');
+  } else if (foreign) {
     addIssue('error', 'E006', `planning tree belongs to ${foreign.tool}: ${foreign.evidence.join(', ')}`, 'Run PAN with --planning-dir <dir> to use a separate tree (ADR-0043)');
     output({ status: HEALTH_STATUS.BROKEN, errors, warnings, info, repairable_count: 0 }, raw, undefined, 1);
     return;
@@ -1337,6 +1435,7 @@ function cmdValidateHealth(cwd, options, raw) {
     addIssue('info', 'I003', `${shape.model}-model project (${shape.evidence.join(', ')}) — the phase-model checks (project.md, roadmap.md, state.md, phases/) do not apply`, null);
   }
   checkConfigFile(cwd, addIssue, repairs);
+  checkPlanningIgnored(cwd, addIssue);
   if (phaseModel) {
     checkPhaseDirectories(cwd, addIssue);
     checkPhaseContents(cwd, addIssue);
@@ -1535,6 +1634,10 @@ module.exports = {
   cmdVerifyReconcile,
   scanStubs,
   cmdVerifyStubs,
+  scopePhase,
+  cmdVerifyScope,
+  verificationFreshness,
+  cmdVerifyStale,
   cmdValidateConsistency,
   cmdValidateHealth,
   cmdPreflight,

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

@@ -28,6 +28,7 @@
  *   history-digest                     Aggregate all summary.md data
  *   summary-extract <path> [--fields]  Extract structured data from summary.md
  *   state-snapshot                     Structured parse of state.md (alias: state snapshot)
+ *   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]
@@ -206,6 +207,7 @@ const cost = require('./lib/cost.cjs');
 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 knowledge = require('./lib/knowledge.cjs');
 const skillAlign = require('./lib/skill-align.cjs');
 const hygiene = require('./lib/hygiene.cjs');
@@ -331,7 +333,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, 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';
 
   if (!command) {
     error(USAGE);
@@ -412,7 +414,7 @@ async function main() {
       } else if (subcommand === 'load' || !subcommand) {
         state.cmdStateLoad(cwd, raw);
       } else {
-        error(`Unknown state subcommand: ${subcommand}. Available: json, update, get, patch, advance-plan, record-metric, update-progress, add-decision, add-blocker, resolve-blocker, record-session, load, snapshot`);
+        error(`Unknown state subcommand: ${subcommand}. Available: json, update, get, patch, compact, advance-plan, record-metric, update-progress, add-decision, add-blocker, resolve-blocker, record-session, load, snapshot`);
       }
       break;
     }
@@ -607,12 +609,21 @@ async function main() {
         verify.cmdVerifyReconcile(cwd, args[2], raw);
       } else if (subcommand === 'stubs') {
         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');
+        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;
@@ -840,7 +851,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;
     }
 
@@ -914,7 +926,13 @@ async function main() {
             output({ error: 'No batch file found. Run focus plan first.' }, raw);
             break;
           }
-          items = batch.batch || [];
+          if (batch.error) {
+            // The newest batch is the one /pan:focus-exec runs; classifying another would
+            // hand it waves for the wrong items, so an unusable newest batch is an error.
+            output({ error: batch.error }, raw);
+            break;
+          }
+          items = batch.batch;
         }
         output(focus.classifyStageDependencies(items), raw);
       } else if (subcommand === 'reflection') {
@@ -1177,6 +1195,44 @@ async function main() {
       break;
     }
 
+    case 'findings': {
+      // Evidence loop (ADR-0049): judges' verdicts recorded from their reports, and
+      // the dispositions workflows give the findings they continue past.
+      const subcommand = args[1];
+      const filters = {
+        phase: getArgValue(args, '--phase'),
+        agent: getArgValue(args, '--agent'),
+        status: getArgValue(args, '--status'),
+        class: getArgValue(args, '--class'),
+        milestone: getArgValue(args, '--milestone'),
+      };
+      if (subcommand === 'record') {
+        findings.cmdFindingsRecord(cwd, {
+          phase: filters.phase,
+          agent: filters.agent,
+          file: getArgValue(args, '--file'),
+          text: getArgValue(args, '--text'),
+          stdin: args.includes('--stdin'),
+        }, raw);
+      } else if (subcommand === 'list') {
+        findings.cmdFindingsList(cwd, filters, raw);
+      } else if (subcommand === 'dispose') {
+        findings.cmdFindingsDispose(cwd, {
+          ids: findings.findingIdsIn(args.slice(2)),
+          phase: filters.phase,
+          agent: filters.agent,
+          open: args.includes('--open'),
+          as: getArgValue(args, '--as'),
+          reason: getArgValue(args, '--reason'),
+        }, raw);
+      } else if (subcommand === 'debt') {
+        findings.cmdFindingsDebt(cwd, { milestone: filters.milestone }, raw);
+      } else {
+        error('Unknown findings subcommand. Available: record, list, dispose, debt');
+      }
+      break;
+    }
+
     case 'preview': {
       const subcommand = args[1];
       if (subcommand === 'phase') {
@@ -1408,17 +1464,23 @@ async function main() {
       } else if (subcommand === 'learn') {
         optimize.cmdOptimizeLearn(cwd, {
           sessionId: getArgValue(args, '--session'),
+          sessions: getArgValue(args, '--sessions'),
         }, raw);
       } else if (subcommand === 'apply') {
         optimize.cmdOptimizeApply(cwd, {
           reportPath: getArgValue(args, '--report'),
         }, raw);
+      } else if (subcommand === 'revert') {
+        optimize.cmdOptimizeRevert(cwd, {
+          applyId: args[2] && !args[2].startsWith('--') ? args[2] : null,
+          last: args.includes('--last'),
+        }, raw);
       } else if (subcommand === 'list') {
         optimize.cmdOptimizeList(cwd, raw);
       } else if (subcommand === 'stats') {
         optimize.cmdOptimizeStats(cwd, raw);
       } else {
-        error('Unknown optimize subcommand. Available: trace, learn, apply, list, stats');
+        error('Unknown optimize subcommand. Available: trace, learn, apply, revert, list, stats');
       }
       break;
     }

package/pan-wizard-core/learnings/README.md

@@ -4,7 +4,7 @@ This directory holds AI-derived behavioral patterns extracted from real PAN
 Wizard sessions via the **self-improvement loop** (v3.7.0+, see
 [ADR-0026](../../docs/decisions/ADR-0026-self-improvement-loop.md)).
 
-Patterns are produced by running `pan-tools learn promote --pattern <id>` over
+Patterns are promoted by hand with `pan-tools learn promote` (see Lifecycle) from
 harvested experiment data. They are **advisory** — orchestrators weight them
 against current context, not as hard rules.
 
@@ -46,9 +46,10 @@ patterns:
 
 ## Lifecycle
 
-1. **Promote** — `pan-tools learn promote --pattern <id> --scope universal --topic <name>` appends a pattern to the topic file (creates the file if absent).
-2. **Unpromote** — `pan-tools learn unpromote --pattern <id> --topic <name>` removes a pattern (for rollback).
+1. **Promote** — `pan-tools learn promote --pattern <id> --scope universal --topic <name> --summary <text> --rule <text>` appends a pattern to the topic file (creates the file if absent); `--evidence`, `--applies-in` and `--source-experiments` fill in the rest of the entry.
+2. **Unpromote** — `pan-tools learn unpromote --pattern <id> --scope <universal|internal> --topic <name>` removes a pattern (for rollback) and deletes the topic file once it holds none.
 3. **List** — `pan-tools learn list-promoted` shows the inventory across both tiers.
+4. **Index** — `pan-tools learn build-index` regenerates `index.json`, the topic index `pan-tools learn topics-for --agent <name>` reads; promote and unpromote do not update it.
 
 ## Why two tiers
 
@@ -58,13 +59,15 @@ apply when the project *is* PAN. Examples:
 - **PAN-internal**: "Always commit individually, never `git add -A`" (because of source repo's pre-commit hooks)
 - **Universal**: "Run the full test suite before marking a phase complete"
 
-The promote step uses a heuristic filter on file paths in the pattern's
-evidence. References to `pan-wizard-core/`, `bin/install.js`, `commands/pan/*`
-suggest `internal` scope. The human running `promote` makes the final call.
+The promote step warns when a universal-scope pattern reads like a prompt
+fragment rather than a structural pattern (P-RES-007), and `pan-tools learn lint`
+warns when a universal pattern's heading or Rule names PAN-internal terms such as
+`pan-wizard-core` or `pan-tools`, a candidate for `internal` scope. The human
+running `promote` makes the final call.
 
 ## Maintenance
 
 These files are **AI-managed**. Direct human edits create drift between
-the frontmatter `pattern_ids` list and the body content. For human-authored
+the frontmatter `patterns` list and the body content. For human-authored
 behavioral content, use `references/` instead — that's the canonical
 hand-authored channel (e.g., `references/guardrails.md` shipped in v3.6.0).