pan-wizard 3.35.0 → 3.37.0

package/pan-wizard-core/bin/lib/cross-family.cjs

@@ -0,0 +1,164 @@
+'use strict';
+/**
+ * The cross-family reviewer lane (program R4): `pan-tools review cross-family <phase>`.
+ *
+ * A reviewer from the same model family as the author tends to share its blind spots.
+ * This lane runs one more review of the phase on another host's CLI, read-only (the
+ * argv is hosts.cjs `review`), and keeps its pan-verdict block beside the others, so
+ * review-deep can merge it as a fourth source (`--cross-file`).
+ *
+ * Opt-in per project: `workflow.cross_family_review` is `off` by default, or names a
+ * host. `--host` overrides it for one run; `--dry-run` prints the lane, the argv and the
+ * prompt and spawns nothing; `--reps N` runs it N times and reports each verdict, which
+ * is what the lane's evidence run needs.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { output, execGit, safeReadFile, toPosix } = require('./core.cjs');
+const { planningPath } = require('./utils.cjs');
+const { HOSTS } = require('./hosts.cjs');
+const { findVerdictBlocks, validateVerdict } = require('./verdict.cjs');
+
+const MAX_DIFF_CHARS = 120000;
+// Windows caps a command line near 32k characters; a longer prompt goes through a file.
+const MAX_ARG_PROMPT = 24000;
+
+function laneHost(cwd, override) {
+  if (override) return override;
+  const wf = (require('./test-gate.cjs').rawConfig(cwd).workflow) || {};
+  const v = wf.cross_family_review;
+  return typeof v === 'string' && v && v !== 'off' ? v : null;
+}
+
+function buildPrompt(cwd, phase) {
+  const { reviewScope } = require('./verify-scope.cjs');
+  const scope = reviewScope(cwd, phase);
+  if (scope.error) return { error: scope.error, reason: scope.reason };
+  let diff = '';
+  if (scope.base) {
+    const r = execGit(cwd, ['diff', scope.base, '--', ...scope.files.map((f) => f.path)]);
+    if (r.exitCode === 0) diff = r.stdout;
+  } else if (scope.files.length) {
+    const r = execGit(cwd, ['diff', 'HEAD', '--', ...scope.files.map((f) => f.path)]);
+    if (r.exitCode === 0) diff = r.stdout;
+  }
+  const truncated = diff.length > MAX_DIFF_CHARS;
+  if (truncated) diff = diff.slice(0, MAX_DIFF_CHARS);
+  const contract = safeReadFile(path.join(__dirname, '..', '..', 'references', 'verdict-contract.md')) || '';
+  const intent = scope.intent.plans.map((p) => `### ${p.plan}\n${p.objective || ''}${p.review_focus ? `\n\nReview focus:\n${p.review_focus}` : ''}`).join('\n\n');
+  const reqs = scope.intent.requirements.map((r) => `- ${r.id}: ${r.text || '(missing)'}`).join('\n');
+  const prompt = [
+    `You are an independent code reviewer from a different model family than the author. Review phase ${scope.phase} of this project: find correctness, security and maintainability defects in the change below, judged against the plans' intent. Do not edit anything.`,
+    `Reply with one fenced \`pan-verdict\` block, as the contract below defines: \`"contract": "1.0"\`, \`"agent": "cross-family-reviewer"\`, \`"phase": "${scope.phase}"\`, a \`verdict\` and \`outcome\`, and one finding per defect (\`where\` as \`file:line\`). Name what you could not judge in \`declined\`.`,
+    '## Verdict contract', contract.trim(),
+    '## Intent', intent || '(no plans found)', reqs ? `## Requirements\n${reqs}` : '',
+    `## Files in scope\n${scope.files.map((f) => `- ${f.path}`).join('\n') || '(none)'}`,
+    `## Diff${scope.base ? ` (from ${scope.base.slice(0, 12)})` : ''}${truncated ? ' (truncated)' : ''}`, '```diff', diff || '(no diff)', '```',
+  ].filter(Boolean).join('\n\n');
+  return { phase: scope.phase, prompt, truncated };
+}
+
+/**
+ * How to launch a host binary on this platform. Off Windows: by name, no shell. On Windows
+ * a binary that resolves to an .exe (Copilot CLI's installer, say) is launched directly by
+ * its path, so Node quotes each argument and a multi-line prompt arrives whole. Anything
+ * else (an npm .cmd shim, a stand-in) needs cmd.exe, which joins arguments unquoted and
+ * ends the command at a newline: there the prompt goes through a file and each argument
+ * with whitespace or a quote is quoted (2026-10-23: `-p <prompt>` reached cmd.exe as words).
+ */
+function launchPlan(bin, platform = process.platform, env = process.env) {
+  if (platform !== 'win32') return { file: bin, shell: false, promptFile: false };
+  const exts = String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean).map((e) => e.toLowerCase());
+  for (const dir of String(env.PATH || env.Path || '').split(path.delimiter).map((d) => d.trim().replace(/^"(.*)"$/, '$1')).filter(Boolean)) {
+    for (const ext of exts) {
+      const p = path.join(dir, bin + ext);
+      if (!fs.existsSync(p)) continue;
+      if (ext === '.exe' || ext === '.com') return { file: p, shell: false, promptFile: false };
+      return { file: bin, shell: true, promptFile: true };
+    }
+  }
+  return { file: bin, shell: true, promptFile: true };
+}
+
+/**
+ * One argument for cmd.exe's command line: quoted when it holds whitespace, a quote or one of
+ * cmd's operators (& | < > ^), which are literal inside quotes. Pure.
+ */
+function quoteForCmd(arg) {
+  const s = String(arg);
+  return /[\s"&|<>^]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+
+function parseVerdict(text) {
+  const blocks = findVerdictBlocks(text || '');
+  const last = blocks.filter((b) => b.closed).pop();
+  if (!last) return { verdict: null, error: 'no_verdict_block' };
+  try {
+    const r = validateVerdict(JSON.parse(last.body));
+    return r.ok ? { verdict: r.verdict } : { verdict: null, error: r.error };
+  } catch { return { verdict: null, error: 'invalid_json' }; }
+}
+
+/**
+ * Plan or run the lane. Pure apart from reading the project and, without dryRun,
+ * spawning the host and writing `.planning/reviews/<NN>/cross-family-<host>.md`.
+ */
+function crossFamilyReview(cwd, phase, opts = {}) {
+  if (!phase) return { error: 'phase_required', reason: 'Usage: review cross-family <phase> [--host <name>] [--reps N] [--dry-run]' };
+  const host = laneHost(cwd, opts.host);
+  if (!host) return { enabled: false, reason: 'lane_off', hint: 'set workflow.cross_family_review to a host, or pass --host' };
+  const h = HOSTS[host];
+  if (!h || !h.review) return { error: 'unknown_host', reason: `no review lane for host "${host}"`, hosts: Object.keys(HOSTS) };
+  const built = buildPrompt(cwd, phase);
+  if (built.error) return built;
+  const nn = String(built.phase).padStart(2, '0');
+  const dir = planningPath(cwd, 'reviews', nn);
+  let prompt = built.prompt;
+  let promptFile = null;
+  const launch = launchPlan(h.bin);
+  if (h.review.promptVia === 'arg' && (prompt.length > MAX_ARG_PROMPT || launch.promptFile)) {
+    promptFile = path.join(dir, `cross-family-${host}-prompt.md`);
+    prompt = `Read ${toPosix(path.relative(cwd, promptFile))} and follow it exactly. Do not edit anything.`;
+  }
+  const argv = h.review.args(h.review.promptVia === 'arg' ? prompt : '');
+  const base = {
+    enabled: true, lane: `cross-family:${host}`, host, family: h.family, bin: h.bin,
+    argv, prompt_via: h.review.promptVia, truncated_diff: built.truncated,
+  };
+  if (opts.dryRun) return { ...base, prompt: built.prompt, prompt_file: promptFile && toPosix(path.relative(cwd, promptFile)), dry_run: true };
+
+  fs.mkdirSync(dir, { recursive: true });
+  if (promptFile) fs.writeFileSync(promptFile, built.prompt);
+  const reps = Math.max(1, Math.min(10, Number(opts.reps) || 1));
+  const runs = [];
+  const outputs = [];
+  const refused = require('./autodev.cjs').standinMissing(h.bin);
+  if (refused) return { ...base, error: 'standin_missing', reason: refused };
+  for (let i = 0; i < reps; i++) {
+    const r = spawnSync(launch.file, launch.shell ? argv.map(quoteForCmd) : argv, {
+      cwd, encoding: 'utf8', input: h.review.promptVia === 'stdin' ? built.prompt : undefined,
+      shell: launch.shell, timeout: Number(opts.timeoutMs) || 15 * 60 * 1000, maxBuffer: 32 * 1024 * 1024,
+    });
+    if (r.error) return { ...base, error: 'spawn_failed', reason: r.error.message };
+    const v = parseVerdict(r.stdout);
+    outputs.push(r.stdout || '');
+    runs.push({ rep: i + 1, exit: r.status, verdict: v.verdict ? v.verdict.verdict : null, outcome: v.verdict ? v.verdict.outcome : null, findings: v.verdict ? v.verdict.findings.length : 0, error: v.error });
+  }
+  const file = path.join(dir, `cross-family-${host}.md`);
+  // The last parseable run is the one review-deep merges; every rep is kept for the record.
+  const keep = outputs.map((o, i) => [o, runs[i]]).filter(([, r]) => r.outcome).pop();
+  fs.writeFileSync(file, `# Cross-family review: phase ${nn} on ${host} (${h.family})\n\n${(keep ? keep[0] : outputs[outputs.length - 1]).trim()}\n`);
+  const counts = {};
+  for (const r of runs) if (r.verdict) counts[r.verdict] = (counts[r.verdict] || 0) + 1;
+  const majority = Object.entries(counts).sort((a, b) => b[1] - a[1])[0];
+  return { ...base, reps, runs, verdict: majority ? majority[0] : null, file: toPosix(path.relative(cwd, file)) };
+}
+
+function cmdReviewCrossFamily(cwd, phase, opts, raw) {
+  const r = crossFamilyReview(cwd, phase, opts);
+  output(r, raw, r.file || r.reason || r.error);
+}
+
+module.exports = { crossFamilyReview, cmdReviewCrossFamily, buildPrompt, parseVerdict, launchPlan, quoteForCmd };

package/pan-wizard-core/bin/lib/debug-cases.cjs

@@ -0,0 +1,104 @@
+'use strict';
+/**
+ * Debug sessions as evidence and as a case base (program P5).
+ *
+ * `debug repro <slug>` runs the reproduction a session recorded (its `## Reproduction`
+ * `command:`), so a gap or a debug session closes only when that command turns green,
+ * not when an agent says it is fixed. The reproduction may name the requirement it
+ * stands for (`requirement: REQ-n`): one reproduction per requirement a gap breaks.
+ *
+ * `debug similar "<symptom>"` ranks the resolved sessions in `.planning/debug/resolved/`
+ * by token overlap with the new symptom (their symptoms, errors and root cause), so a
+ * recurring bug starts from the root cause and fix that worked before.
+ */
+const fs = require('fs');
+const path = require('path');
+const { output, error, toLf } = require('./core.cjs');
+const TG = require('./test-gate.cjs');
+
+const DEBUG_DIR = path.join('.planning', 'debug');
+const RESOLVED_DIR = path.join(DEBUG_DIR, 'resolved');
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+const DEFAULT_REPRO_TIMEOUT_MS = 2 * 60 * 1000;
+const STOP = new Set(['the', 'and', 'for', 'with', 'that', 'this', 'when', 'after', 'before', 'from', 'into', 'are', 'was', 'not', 'but', 'its', 'every', 'right']);
+
+/** The `key: value` lines of one `## Heading` section. */
+function sectionFields(text, heading) {
+  const m = new RegExp(`^## ${heading}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(text);
+  const out = {};
+  if (!m) return out;
+  for (const line of m[1].split('\n')) {
+    const kv = /^([a-z_]+):\s*(.*)$/.exec(line.trim());
+    if (kv) out[kv[1]] = kv[2].trim();
+  }
+  return out;
+}
+
+/** Parse a debug session file. */
+function parseDebugSession(raw) {
+  const text = toLf(String(raw || ''));
+  const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+  const status = fm ? ((/^status:\s*(.+)$/m.exec(fm[1]) || [])[1] || '').trim() : '';
+  return {
+    status,
+    symptoms: sectionFields(text, 'Symptoms'),
+    reproduction: sectionFields(text, 'Reproduction'),
+    resolution: sectionFields(text, 'Resolution'),
+  };
+}
+
+/** Run a session's reproduction. green | red | none (no command recorded). */
+function reproCheck(cwd, slug, opts = {}) {
+  if (!slug || !SLUG_RE.test(slug) || slug.includes('..')) return { error: 'invalid_slug', reason: 'a debug session slug is letters, digits, dots, dashes and underscores' };
+  const candidates = [path.join(cwd, DEBUG_DIR, `${slug}.md`), path.join(cwd, RESOLVED_DIR, `${slug}.md`)];
+  const file = candidates.find((f) => fs.existsSync(f));
+  if (!file) return { error: 'session_not_found', reason: `no .planning/debug/${slug}.md` };
+  const s = parseDebugSession(fs.readFileSync(file, 'utf8'));
+  const command = s.reproduction.command || '';
+  const requirement = s.reproduction.requirement || null;
+  if (!command || /^none\b/i.test(command) || /^\[/.test(command)) {
+    return { slug, result: 'none', closable: false, requirement, detail: 'the session records no reproduction command; its closing needs a human check' };
+  }
+  const r = TG.runCommand(cwd, command, opts.timeoutMs || DEFAULT_REPRO_TIMEOUT_MS);
+  const result = r.exit === 0 ? 'green' : 'red';
+  return { slug, result, closable: result === 'green', requirement, command, exit: r.exit, ...(r.timed_out ? { timed_out: true } : {}) };
+}
+
+function tokens(s) {
+  return new Set(String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').split(' ').filter((w) => w.length > 2 && !STOP.has(w)));
+}
+
+/** Rank resolved sessions by overlap with a symptom. */
+function similarCases(cwd, symptom, opts = {}) {
+  const want = tokens(symptom);
+  const dir = path.join(cwd, RESOLVED_DIR);
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')); } catch { /* none yet */ }
+  const cases = [];
+  for (const f of files) {
+    const s = parseDebugSession(fs.readFileSync(path.join(dir, f), 'utf8'));
+    const have = tokens([s.symptoms.expected, s.symptoms.actual, s.symptoms.errors, s.resolution.root_cause].join(' '));
+    let both = 0;
+    for (const t of want) if (have.has(t)) both++;
+    const score = want.size && have.size ? both / (want.size + have.size - both) : 0;
+    if (score <= 0) continue;
+    cases.push({ slug: f.replace(/\.md$/, ''), score: Number(score.toFixed(3)), root_cause: s.resolution.root_cause || null, fix: s.resolution.fix || null, reproduction: s.reproduction.command || null });
+  }
+  cases.sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
+  return { symptom, cases: cases.slice(0, opts.limit || 5) };
+}
+
+function cmdDebugRepro(cwd, slug, raw, opts = {}) {
+  if (!slug) error('Usage: debug repro <slug> [--timeout <ms>]');
+  const r = reproCheck(cwd, slug, { timeoutMs: opts.timeout ? Number(opts.timeout) : undefined });
+  if (r.error) { output(r, raw, 'error', 1); return; }
+  output(r, raw, r.result, r.result === 'green' ? 0 : 1);
+}
+
+function cmdDebugSimilar(cwd, symptom, raw, opts = {}) {
+  if (!symptom) error('Usage: debug similar "<symptom>" [--limit N]');
+  const r = similarCases(cwd, symptom, { limit: opts.limit ? Number(opts.limit) : undefined });
+  output(r, raw, r.cases.map((c) => c.slug).join('\n'));
+}
+
+module.exports = { parseDebugSession, reproCheck, similarCases, cmdDebugRepro, cmdDebugSimilar };

package/pan-wizard-core/bin/lib/doc-lint.cjs

@@ -343,11 +343,13 @@ function scanDocFlags(cwd, opts = {}) {
   const docDirs = opts.docDirs || ['docs'];
   const collected = [];
   for (const d of docDirs) {
-    const abs = path.join(cwd, d);
+    const abs = path.resolve(cwd, d);
     if (!fs.existsSync(abs)) continue;
     for (const f of walkMarkdownFiles(abs)) {
       if (f.readError) continue;
-      collected.push({ rel: path.join(d, f.relativePath).replace(/\\/g, '/'), content: f.content });
+      // Relative to the project root whether --doc-dir was given relative or
+      // absolute, so the frozen-doc allowlist sees project segments only.
+      collected.push({ rel: path.relative(cwd, path.join(abs, f.relativePath)).replace(/\\/g, '/'), content: f.content });
     }
   }
   for (const rel of (opts.files || [])) {
@@ -379,7 +381,7 @@ function scanDocFlags(cwd, opts = {}) {
 
 function cmdDocLintFlags(cwd, opts = {}, raw) {
   for (const d of opts.docDirs || []) {
-    const abs = path.isAbsolute(d) ? d : path.join(cwd, d);
+    const abs = path.resolve(cwd, d);
     if (fs.existsSync(abs)) requireDirectory(abs);
   }
   const r = scanDocFlags(cwd, opts);

package/pan-wizard-core/bin/lib/failure-class.cjs

@@ -0,0 +1,81 @@
+'use strict';
+/**
+ * The failure-class router (program A4).
+ *
+ * When an autodev unit fails, what to do next depends on why. classifyFailure reads the
+ * exit, the output tail and whether it timed out; routeFailure gives the class's policy
+ * for this attempt. Breadth before depth (Olausson et al.): a cheap retry with the error
+ * in front of the model comes before a tier escalation, and anything a model cannot fix
+ * (a missing CLI or login, a merge conflict, the guard's deny, an undeclared file) goes
+ * to a human.
+ *
+ *   retry_with_tail  rerun the unit with the error tail in the prompt
+ *   fresh_restart    rerun the unit as it was
+ *   escalate_tier    rerun it at the next model tier (core.cjs escalateTier)
+ *   quarantine       record it as a flake and go on
+ *   ask              stop: human_needed
+ *   stop_budget      stop: budget_usd
+ */
+
+const { escalateTier } = require('./core.cjs');
+
+const FAILURE_CLASSES = Object.freeze(['compile', 'assertion', 'timeout', 'flake', 'missing_env', 'merge_conflict', 'integrity_violation', 'scope_violation', 'budget', 'unknown']);
+
+// First match wins: the specific, unfixable classes are checked before the generic ones.
+const PATTERNS = [
+  ['budget', /max-budget-usd|credit balance|usage limit|rate limit|quota exceeded|budget exceeded/i],
+  ['missing_env', /is not recognized as an internal or external command|command not found|ENOENT|invalid api key|not logged in|please run \/login|authenticat(e|ion) (failed|required)|missing (an )?api key/i],
+  ['integrity_violation', /PAN guard:|integrity (check|violation)|hash mismatch|tamper/i],
+  ['merge_conflict', /CONFLICT \(|merge conflict|Automatic merge failed/i],
+  ['scope_violation', /scope violation|undeclared (file|test)|not declared by any plan|outside the plan/i],
+  ['timeout', /ETIMEDOUT|timed out|timeout of \d+/i],
+  ['compile', /error TS\d+|SyntaxError|ReferenceError|Cannot find (module|name)|compilation failed|failed to compile|cannot compile/i],
+  ['assertion', /AssertionError|assert\w*\.\w+|expected .{1,80} (to|but)|\btests? failed\b|\d+ failing\b|^not ok /im],
+];
+
+/**
+ * @param {{exit?: number|null, stderr?: string, stdout?: string, timedOut?: boolean, flaky?: boolean}} f
+ * @returns {string} one of FAILURE_CLASSES
+ */
+function classifyFailure(f = {}) {
+  if (f.flaky) return 'flake';
+  if (f.timedOut) return 'timeout';
+  const text = `${f.stderr || ''}\n${f.stdout || ''}`;
+  for (const [cls, re] of PATTERNS) if (re.test(text)) return cls;
+  if (f.exit === 127) return 'missing_env';
+  return 'unknown';
+}
+
+const POLICIES = {
+  compile: ['retry_with_tail', 'escalate_tier'],
+  assertion: ['retry_with_tail', 'escalate_tier'],
+  timeout: ['fresh_restart'],
+  flake: ['quarantine'],
+  missing_env: [],
+  merge_conflict: [],
+  integrity_violation: [],
+  scope_violation: [],
+  budget: ['stop_budget'],
+  unknown: ['fresh_restart'],
+};
+
+/**
+ * The policy for the `attempt`th failure of a unit (1 = its first failure).
+ * @returns {{action: string, tier?: string}}
+ */
+function routeFailure(cls, attempt = 1) {
+  const ladder = POLICIES[cls] || POLICIES.unknown;
+  if (cls === 'flake') return { action: 'quarantine' };
+  if (cls === 'budget') return { action: 'stop_budget' };
+  const action = ladder[attempt - 1] || 'ask';
+  if (action === 'escalate_tier') return { action, tier: escalateTier('mid', attempt).tier };
+  return { action };
+}
+
+/** The last lines of a failure's output, for the retry prompt (one line, shell-safe). */
+function errorTail(f = {}, max = 300) {
+  const text = `${f.stderr || ''}\n${f.stdout || ''}`.trim().split(/\r?\n/).filter(Boolean).slice(-4).join(' / ');
+  return text.replace(/[\r\n&|<>%^"]/g, ' ').replace(/\s+/g, ' ').slice(-max).trim();
+}
+
+module.exports = { FAILURE_CLASSES, classifyFailure, routeFailure, errorTail, POLICIES };