pan-wizard 3.31.0 → 3.32.0

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

@@ -0,0 +1,431 @@
+'use strict';
+/**
+ * Verdict contract — the machine-readable half of a judging agent's report
+ * (evidence loop, docs/specs/evidence_loop_featureai.md §3.3; ADR-0049).
+ *
+ * The judges that return text (pan-plan-checker, pan-reviewer, pan-design-checker)
+ * end their report with a fenced `pan-verdict` JSON block. The verifier already
+ * writes a machine contract — the verification.md frontmatter that
+ * `/pan:plan-phase --gaps` consumes — so its verdict is read from that frontmatter
+ * instead of from a second block that could disagree with it.
+ *
+ * Pure: no filesystem access, no process exit. findings.cjs does the IO.
+ *
+ * Contract rules (D11): `contract` is "1.x"; fields may be ADDED within a major
+ * version and are never renamed or removed; readers accept any 1.x and ignore
+ * fields they do not know; an unknown major is refused.
+ */
+const crypto = require('crypto');
+
+const VERDICT_CONTRACT = '1.0';
+const OUTCOMES = Object.freeze(['pass', 'fail', 'needs_human']);
+// Spec Kit's converge classes (missing / partial / contradicts / unrequested) for the
+// verification side, plus the review side's defect / risk / quality, plus `human`
+// for what no check can settle mechanically.
+const FINDING_CLASSES = Object.freeze(['missing', 'partial', 'contradicts', 'unrequested', 'defect', 'risk', 'quality', 'human']);
+// The one severity ladder in PAN — identical to review-deep.cjs SEVERITIES
+// (tests/verdict.test.cjs pins the equality; a cycle stops this module importing it).
+const SEVERITIES = Object.freeze(['critical', 'high', 'medium', 'low', 'info']);
+const DISPOSITIONS = Object.freeze(['fixed', 'deferred', 'dismissed', 'decision']);
+const REASON_REQUIRED = Object.freeze(['deferred', 'dismissed', 'decision']);
+// A re-run does not re-check these, so their absence from a later verdict is not
+// evidence that they were resolved (D6).
+const AUTO_FIX_EXEMPT = Object.freeze(['human', 'unrequested']);
+
+/** Each judge's own verdict word → the normalised outcome it implies. */
+const KNOWN_VERDICTS = Object.freeze({
+  'pan-verifier': Object.freeze({ passed: 'pass', gaps_found: 'fail', human_needed: 'needs_human' }),
+  'pan-plan-checker': Object.freeze({ passed: 'pass', issues_found: 'fail' }),
+  'pan-reviewer': Object.freeze({ PASS: 'pass', PASS_WITH_WARNINGS: 'pass', NEEDS_FIXES: 'fail' }),
+  'pan-design-checker': Object.freeze({ PASS: 'pass', GAPS: 'fail' }),
+});
+
+const LIMITS = Object.freeze({ findings: 100, where: 200, summary: 300, verdict: 40, score: 40 });
+const AGENT_RE = /^[a-z][a-z0-9-]{0,63}$/;
+const OPEN_FENCE_RE = /^[ \t]*(`{3,}|~{3,})[ \t]*pan-verdict[ \t]*$/;
+const CLOSE_FENCE_RE = /^[ \t]*(`{3,}|~{3,})[ \t]*$/;
+
+function sha256(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+/** EOL-normalised text: BOM dropped, CRLF → LF. */
+function normaliseEol(text) {
+  return String(text == null ? '' : text).replace(/^/, '').replace(/\r\n/g, '\n');
+}
+
+/** Phase numbers compare without their zero padding ("03" === "3", "03.1" === "3.1"). */
+function comparablePhase(p) {
+  return String(p == null ? '' : p).trim().replace(/^0+(?=\d)/, '');
+}
+
+/**
+ * Every fenced `pan-verdict` block in `text`, in order. Backtick or tilde fences,
+ * any leading indentation (the host indents framed subagent results). An
+ * unterminated block runs to the end of the text and is marked `closed: false`.
+ * @returns {{body: string, closed: boolean}[]}
+ */
+function findVerdictBlocks(text) {
+  const lines = normaliseEol(text).split('\n');
+  const blocks = [];
+  for (let i = 0; i < lines.length; i++) {
+    const open = OPEN_FENCE_RE.exec(lines[i]);
+    if (!open) continue;
+    const fence = open[1];
+    const body = [];
+    let closed = false;
+    let j = i + 1;
+    for (; j < lines.length; j++) {
+      const close = CLOSE_FENCE_RE.exec(lines[j]);
+      if (close && close[1][0] === fence[0] && close[1].length >= fence.length) { closed = true; break; }
+      body.push(lines[j]);
+    }
+    blocks.push({ body: body.join('\n'), closed });
+    i = j;
+  }
+  return blocks;
+}
+
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function cleanText(v) {
+  return String(v).replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Normalise contract `1`, `"1"`, `"1.x"` to a `1.x` string; null for anything else.
+ */
+function normaliseContract(c) {
+  if (c === 1 || c === '1') return VERDICT_CONTRACT;
+  if (typeof c === 'string' && /^1\.\d+$/.test(c.trim())) return c.trim();
+  return null;
+}
+
+/**
+ * Validate and normalise a parsed verdict object.
+ *
+ * Refuses (ok:false) only what makes the verdict unusable: not an object, an
+ * unsupported contract, no agent, no valid outcome. Everything else is recorded
+ * in its closest valid form and reported in `warnings`.
+ *
+ * @param {*} obj - the parsed block
+ * @param {{agent?: string, phase?: string|number}} [opts] - the orchestrator's view:
+ *   the agent it spawned (wins over the block's own claim) and the phase it asked about
+ * @returns {{ok: true, verdict: Object, warnings: string[]}|{ok: false, error: string, reason: string}}
+ */
+function validateVerdict(obj, opts = {}) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    return { ok: false, error: 'invalid_verdict', reason: 'the pan-verdict block must hold a JSON object' };
+  }
+  const warnings = [];
+  const contract = normaliseContract(obj.contract);
+  if (!contract) {
+    return {
+      ok: false,
+      error: 'unsupported_contract',
+      reason: `contract ${JSON.stringify(obj.contract === undefined ? null : obj.contract)} is not a supported 1.x version`,
+    };
+  }
+
+  const claimed = typeof obj.agent === 'string' ? obj.agent.trim() : '';
+  const given = typeof opts.agent === 'string' ? opts.agent.trim() : '';
+  const agent = given || claimed;
+  if (!AGENT_RE.test(agent)) {
+    return { ok: false, error: 'missing_agent', reason: 'no valid agent name (block "agent" or --agent)' };
+  }
+  if (given && claimed && given !== claimed) warnings.push(`agent_mismatch: the block says ${claimed}, recorded as ${given}`);
+
+  const outcome = typeof obj.outcome === 'string' ? obj.outcome.trim().toLowerCase() : '';
+  if (!OUTCOMES.includes(outcome)) {
+    return { ok: false, error: 'invalid_outcome', reason: `outcome must be one of ${OUTCOMES.join(', ')}` };
+  }
+
+  let verdict = null;
+  if (obj.verdict != null && String(obj.verdict).trim() !== '') {
+    verdict = String(obj.verdict).trim();
+    if (verdict.length > LIMITS.verdict) {
+      verdict = verdict.slice(0, LIMITS.verdict);
+      warnings.push('verdict_truncated');
+    }
+    const implied = KNOWN_VERDICTS[agent] && Object.prototype.hasOwnProperty.call(KNOWN_VERDICTS[agent], verdict)
+      ? KNOWN_VERDICTS[agent][verdict] : null;
+    if (implied && implied !== outcome) warnings.push(`outcome_mismatch: ${verdict} implies ${implied}, the block says ${outcome}`);
+  }
+
+  const phase = obj.phase == null || String(obj.phase).trim() === '' ? null : String(obj.phase).trim();
+  if (phase && opts.phase != null && comparablePhase(phase) !== comparablePhase(opts.phase)) {
+    warnings.push(`phase_mismatch: the block says ${phase}, recorded under ${opts.phase}`);
+  }
+
+  const score = obj.score == null ? null : truncate(cleanText(obj.score), LIMITS.score);
+
+  let raw = [];
+  if (obj.findings != null) {
+    if (Array.isArray(obj.findings)) raw = obj.findings;
+    else warnings.push('findings_not_an_array');
+  }
+  if (raw.length > LIMITS.findings) {
+    warnings.push(`findings_truncated: ${raw.length} reported, ${LIMITS.findings} kept`);
+    raw = raw.slice(0, LIMITS.findings);
+  }
+  const findings = [];
+  raw.forEach((f, i) => {
+    if (!f || typeof f !== 'object' || Array.isArray(f) || typeof f.summary !== 'string' || !cleanText(f.summary)) {
+      warnings.push(`finding_dropped: #${i} has no summary`);
+      return;
+    }
+    let cls = typeof f.class === 'string' ? f.class.trim().toLowerCase() : '';
+    if (!FINDING_CLASSES.includes(cls)) {
+      warnings.push(`unknown_class: #${i} ${JSON.stringify(f.class === undefined ? null : f.class)} recorded as quality`);
+      cls = 'quality';
+    }
+    let severity = typeof f.severity === 'string' ? f.severity.trim().toLowerCase() : '';
+    if (!SEVERITIES.includes(severity)) {
+      warnings.push(`unknown_severity: #${i} ${JSON.stringify(f.severity === undefined ? null : f.severity)} recorded as info`);
+      severity = 'info';
+    }
+    let summary = cleanText(f.summary);
+    if (summary.length > LIMITS.summary) {
+      summary = truncate(summary, LIMITS.summary);
+      warnings.push(`summary_truncated: #${i}`);
+    }
+    const where = f.where == null || cleanText(f.where) === '' ? null : truncate(cleanText(f.where).replace(/\\/g, '/'), LIMITS.where);
+    findings.push({ class: cls, severity, where, summary });
+  });
+
+  return { ok: true, verdict: { contract, agent, outcome, verdict, phase, score, findings }, warnings };
+}
+
+// ─── verification.md frontmatter adapter ─────────────────────────────────────
+
+/** The YAML between the leading `---` fences, or null. */
+function frontmatterText(text) {
+  const m = normaliseEol(text).match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  return m ? m[1] : null;
+}
+
+/**
+ * A YAML value without its trailing comment. The verifier's templates annotate list
+ * keys (`gaps: # Only if status: gaps_found`), and a model copying the template
+ * copies the comment, so `# …` must not read as a value. A quoted value ends at its
+ * closing quote.
+ */
+function stripComment(v) {
+  const s = String(v == null ? '' : v).trim();
+  if (s[0] === '"' || s[0] === "'") {
+    const q = s[0];
+    for (let i = 1; i < s.length; i++) {
+      if (q === '"' && s[i] === '\\') { i++; continue; }
+      if (s[i] === q) {
+        if (q === "'" && s[i + 1] === "'") { i++; continue; }
+        return s.slice(0, i + 1);
+      }
+    }
+    return s;
+  }
+  return s.replace(/(^|\s)#.*$/, '').trim();
+}
+
+function unquote(v) {
+  const s = stripComment(v);
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    try { return JSON.parse(s); } catch { return s.slice(1, -1); }
+  }
+  if (s.length >= 2 && s[0] === "'" && s[s.length - 1] === "'") return s.slice(1, -1).replace(/''/g, "'");
+  return s;
+}
+
+const KEY_VALUE_RE = /^([A-Za-z_][A-Za-z0-9_-]*):[ \t]*(.*)$/;
+const ITEM_RE = /^([ \t]*)-[ \t]*(.*)$/;
+const indentOf = (line) => /^[ \t]*/.exec(line)[0].length;
+
+/**
+ * A top-level YAML list of mappings, in the shape the verifier template writes:
+ *
+ *   gaps:
+ *     - truth: "…"
+ *       status: failed
+ *       artifacts:
+ *         - path: "src/x.ts"
+ *
+ * Each item comes back as its scalar fields plus `_first_path` (the first nested
+ * `path:` value, for `artifacts`). PAN's general frontmatter parser reads such a
+ * list as bare strings (`'truth: "…'`), so this reader exists for the adapter alone
+ * rather than changing a parser every other module depends on.
+ */
+function listOfMappings(yaml, key) {
+  const lines = yaml.split('\n');
+  const start = lines.findIndex((l) => {
+    const m = KEY_VALUE_RE.exec(l);
+    return m && m[1] === key && indentOf(l) === 0;
+  });
+  if (start === -1) return [];
+  const head = KEY_VALUE_RE.exec(lines[start]);
+  if (stripComment(head[2]) !== '') return []; // `gaps: []` or a scalar — nothing to read
+  const items = [];
+  let itemIndent = -1;
+  let item = null;
+  let contentIndent = -1;
+  let nested = null;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    const ind = indentOf(line);
+    const isItem = ITEM_RE.exec(line);
+    if (ind === 0 && !isItem) break; // the next top-level key
+    if (isItem && (itemIndent === -1 || ind === itemIndent)) {
+      if (itemIndent === -1) itemIndent = ind;
+      item = {};
+      items.push(item);
+      contentIndent = ind + (line.length - line.replace(/^[ \t]*-[ \t]*/, '').length) - ind;
+      nested = null;
+      const kv = KEY_VALUE_RE.exec(isItem[2]);
+      if (kv) {
+        if (stripComment(kv[2]) === '') nested = kv[1];
+        else item[kv[1]] = unquote(kv[2]);
+      }
+      continue;
+    }
+    if (!item) continue;
+    const body = line.trim();
+    if (ind === contentIndent) {
+      const kv = KEY_VALUE_RE.exec(body);
+      if (!kv) continue;
+      if (stripComment(kv[2]) === '') { nested = kv[1]; continue; }
+      item[kv[1]] = unquote(kv[2]);
+      nested = null;
+      continue;
+    }
+    if (ind > contentIndent && nested) {
+      const inner = body.replace(/^-[ \t]*/, '');
+      const kv = KEY_VALUE_RE.exec(inner);
+      if (kv && kv[1] === 'path' && item._first_path === undefined && stripComment(kv[2]) !== '') {
+        item._first_path = unquote(kv[2]);
+      }
+    }
+  }
+  return items;
+}
+
+/** A top-level scalar from the frontmatter (e.g. `status`), or null. */
+function frontmatterScalar(yaml, key) {
+  for (const l of yaml.split('\n')) {
+    const m = KEY_VALUE_RE.exec(l);
+    if (m && m[1] === key && indentOf(l) === 0) {
+      const v = unquote(m[2]);
+      return v === '' ? null : v;
+    }
+  }
+  return null;
+}
+
+/**
+ * Build a raw verdict object from a verification.md frontmatter (the adapter, D2).
+ * `status` → verdict and outcome; `gaps[]` → missing (failed) / partial;
+ * `human_verification[]` → human; `unrequested[]` (M11) → unrequested.
+ * @returns {Object|null} a raw verdict for validateVerdict, or null when the text
+ *   carries no verification frontmatter status
+ */
+function verdictFromVerificationFrontmatter(text, agent = 'pan-verifier') {
+  const yaml = frontmatterText(text);
+  if (yaml === null) return null;
+  const status = frontmatterScalar(yaml, 'status');
+  if (!status) return null;
+  const table = KNOWN_VERDICTS['pan-verifier'];
+  const outcome = Object.prototype.hasOwnProperty.call(table, status) ? table[status] : null;
+  const findings = [];
+  for (const g of listOfMappings(yaml, 'gaps')) {
+    const truth = g.truth ? String(g.truth) : '';
+    const reason = g.reason ? String(g.reason) : '';
+    const summary = truth && reason ? `${truth} — ${reason}` : (truth || reason);
+    if (!summary) continue;
+    const partial = String(g.status || '').toLowerCase() === 'partial';
+    findings.push({ class: partial ? 'partial' : 'missing', severity: partial ? 'medium' : 'high', where: g._first_path || null, summary });
+  }
+  for (const h of listOfMappings(yaml, 'human_verification')) {
+    const summary = h.test ? String(h.test) + (h.expected ? ` — expected: ${h.expected}` : '') : '';
+    if (summary) findings.push({ class: 'human', severity: 'info', where: null, summary });
+  }
+  for (const u of listOfMappings(yaml, 'unrequested')) {
+    const what = u.what ? String(u.what) : (u.why ? String(u.why) : '');
+    const path = u.path ? String(u.path) : null;
+    const summary = what || (path ? `unrequested change to ${path}` : '');
+    if (summary) findings.push({ class: 'unrequested', severity: 'low', where: path, summary });
+  }
+  return { contract: VERDICT_CONTRACT, agent, verdict: status, outcome, findings };
+}
+
+/**
+ * Read a judge's verdict from an artifact: the LAST `pan-verdict` block wins; with
+ * no block, a verification.md frontmatter `status` is read through the adapter.
+ * @param {string} text
+ * @param {{agent?: string, phase?: string|number}} [opts]
+ * @returns {{ok: true, verdict: Object, warnings: string[], source_kind: 'block'|'frontmatter'}
+ *          |{ok: false, error: string, reason: string}}
+ */
+function parseVerdictText(text, opts = {}) {
+  const blocks = findVerdictBlocks(text);
+  if (blocks.length) {
+    const last = blocks[blocks.length - 1];
+    if (!last.closed) return { ok: false, error: 'unterminated_block', reason: 'the last pan-verdict block has no closing fence' };
+    let obj;
+    try { obj = JSON.parse(last.body); } catch (e) {
+      return { ok: false, error: 'invalid_json', reason: `the last pan-verdict block is not valid JSON: ${e.message}` };
+    }
+    const r = validateVerdict(obj, opts);
+    return r.ok ? { ...r, source_kind: 'block' } : r;
+  }
+  const adapted = verdictFromVerificationFrontmatter(text, opts.agent || 'pan-verifier');
+  if (adapted) {
+    if (!adapted.outcome) {
+      return { ok: false, error: 'unknown_status', reason: `verification status "${adapted.verdict}" is not passed, gaps_found or human_needed` };
+    }
+    const r = validateVerdict(adapted, opts);
+    return r.ok ? { ...r, source_kind: 'frontmatter' } : r;
+  }
+  return { ok: false, error: 'no_verdict', reason: 'no pan-verdict block and no verification frontmatter status' };
+}
+
+/** Identity of the artifact a verdict was read from: EOL-normalised content hash. */
+function recordSig(text) {
+  return sha256(normaliseEol(text).replace(/\s+$/, '')).slice(0, 16);
+}
+
+/**
+ * A finding's stable id: the same finding reported again keeps its id, so a
+ * re-verification can say which earlier findings it no longer reports.
+ */
+function findingId(phase, agent, finding) {
+  const summary = cleanText(finding.summary || '').toLowerCase().replace(/[.;:,!]+$/, '');
+  const where = finding.where ? cleanText(finding.where).replace(/\\/g, '/') : '';
+  return 'f_' + sha256([comparablePhase(phase), agent, finding.class, where, summary].join('\u0000')).slice(0, 10);
+}
+
+/** The outcome an agent's own verdict word implies, or null when it is not a known pair. */
+function outcomeForVerdict(agent, verdict) {
+  const table = KNOWN_VERDICTS[agent];
+  return table && Object.prototype.hasOwnProperty.call(table, verdict) ? table[verdict] : null;
+}
+
+module.exports = {
+  VERDICT_CONTRACT,
+  OUTCOMES,
+  FINDING_CLASSES,
+  SEVERITIES,
+  DISPOSITIONS,
+  REASON_REQUIRED,
+  AUTO_FIX_EXEMPT,
+  KNOWN_VERDICTS,
+  LIMITS,
+  findVerdictBlocks,
+  validateVerdict,
+  verdictFromVerificationFrontmatter,
+  parseVerdictText,
+  recordSig,
+  findingId,
+  outcomeForVerdict,
+  comparablePhase,
+  normaliseEol,
+};

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

@@ -102,10 +102,12 @@ function cmdPreflight(cwd, target, raw) {
     const currentPhaseMatch = stateContent.match(/\*\*Current Phase:\*\*\s*(\S+)/);
     const currentPhase = currentPhaseMatch ? currentPhaseMatch[1] : null;
     if (target === 'batch') {
-      // Check that a batch file exists
+      // Check that a batch file exists, and name the one `focus exec` would run (the
+      // shared ordering in focus.cjs; required lazily, it is only needed here)
       const focusDir = path.join(planDir, 'focus');
       try {
-        const files = fs.readdirSync(focusDir).filter(f => f.startsWith('batch-') && f.endsWith('.json'));
+        fs.readdirSync(focusDir);
+        const files = require('./focus.cjs').listBatchFiles(cwd);
         if (files.length > 0) {
           checks.push({ name: 'batch_exists', passed: true, detail: files[files.length - 1] });
         } else {

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

@@ -0,0 +1,156 @@
+'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 } = 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));
+}
+
+module.exports = { scopePhase, cmdVerifyScope, 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 {
@@ -22,6 +22,7 @@ const { runDriftCheck, parseConventionRules, checkFileConventions, calculateDrif
 const { collectVerificationStats, countRoadmapPhases, groupGapPatterns, cmdRetro } = require('./verify-retro.cjs');
 const { detectInstalledRuntimes, validateRuntimeInstall, cmdValidateDeployment } = require('./verify-deploy.cjs');
 const { cmdPreflight, cmdDepsValidate } = require('./verify-preflight.cjs');
+const { scopePhase, cmdVerifyScope } = require('./verify-scope.cjs');
 const { planningRootRel } = require('./planning-root.cjs');
 
 /**
@@ -821,6 +822,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;
@@ -1314,7 +1332,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 +1357,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 +1556,8 @@ module.exports = {
   cmdVerifyReconcile,
   scanStubs,
   cmdVerifyStubs,
+  scopePhase,
+  cmdVerifyScope,
   cmdValidateConsistency,
   cmdValidateHealth,
   cmdPreflight,