pan-wizard 3.36.0 → 3.37.0

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

@@ -13,6 +13,18 @@
  * its type is `stale`, not an error: what a version or a price was two months ago
  * says little about today, while a practice lasts for years. The plan-checker weighs
  * stale claims against what the plans rest on.
+ *
+ * Research answers questions (2026-10-25: research that surveyed a domain never
+ * finished and grew the scope). The orchestrator writes at most five open questions
+ * that block building; one researcher answers them in a table
+ *
+ *   | # | Question | Answer | Source | Confidence | Decision it settles |
+ *
+ * `research check <questions> <research> [--market]` holds it to that: at most five
+ * questions, every question a row with an answer and a source, or an answer marked
+ * `unknown` that names the assumption the plan uses; in market mode, at most five
+ * comparable products. Without a `## Claims` table, `research lint` reads the
+ * answered rows of that table as claims, with the date in the source cell.
  */
 const fs = require('fs');
 const path = require('path');
@@ -75,10 +87,22 @@ function lintResearch(cwd, target, opts = {}) {
   const text = toLf(fs.readFileSync(at.abs, 'utf-8'));
   const base = { file, ok: true, claims: 0, errors: [], warnings: [], stale: [], windows: FRESHNESS_DAYS };
   const body = sectionBody(text, 'Claims');
+  let header;
+  let rows;
   if (body == null) {
-    return { ...base, ok: false, errors: [{ code: 'claims_missing', detail: 'no `## Claims` table (claim · type · source · checked)' }] };
+    // A question-driven research file: its answered rows are the claims.
+    const answers = answerTable(text);
+    if (!answers) {
+      return { ...base, ok: false, errors: [{ code: 'claims_missing', detail: 'no `## Claims` table (claim · type · source · checked) and no answers table (# · question · answer · source)' }] };
+    }
+    header = ['claim', 'type', 'source', 'checked'];
+    rows = answers.rows.filter((r) => !isUnknown(r.answer)).map((r) => {
+      const date = (r.source.match(/\d{4}-\d{2}-\d{2}/) || [''])[0];
+      return [r.answer, 'general', r.source, date];
+    });
+  } else {
+    ({ header, rows } = claimRows(body));
   }
-  const { header, rows } = claimRows(body);
   const col = (name, fallback) => {
     const i = header ? header.findIndex((h) => h.startsWith(name)) : -1;
     return i === -1 ? fallback : i;
@@ -111,6 +135,129 @@ function lintResearch(cwd, target, opts = {}) {
   return { ...base, ok: errors.length === 0, claims: rows.length, errors, warnings, stale };
 }
 
+const MAX_QUESTIONS = 5;
+const MAX_PRODUCTS = 5;
+
+/** Every markdown table in `text` as arrays of cells (rule rows dropped); a non-table line ends a table. */
+function tables(text) {
+  const out = [];
+  let cur = null;
+  for (const line of String(text).split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('|')) { cur = null; continue; }
+    const cells = t.replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    if (cells.every((c) => /^:?-+:?$/.test(c) || c === '')) continue;
+    if (!cur) { cur = []; out.push(cur); }
+    cur.push(cells);
+  }
+  return out;
+}
+
+/** The answers table (`# · Question · Answer · Source …`), rows as objects, or null. */
+function answerTable(text) {
+  for (const t of tables(text)) {
+    const h = t[0].map((c) => c.toLowerCase());
+    const qi = h.findIndex((c) => c.startsWith('question'));
+    const ai = h.findIndex((c) => c.startsWith('answer'));
+    const si = h.findIndex((c) => c.startsWith('source'));
+    if (qi === -1 || ai === -1 || si === -1) continue;
+    const ni = h.findIndex((c) => c === '#' || c === 'no' || c === 'n');
+    const ci = h.findIndex((c) => c.startsWith('confidence'));
+    const di = h.findIndex((c) => c.startsWith('decision'));
+    return {
+      rows: t.slice(1).map((r, i) => ({
+        n: ni === -1 ? i + 1 : parseInt(String(r[ni] || '').replace(/\D/g, ''), 10),
+        question: r[qi] || '', answer: r[ai] || '', source: r[si] || '',
+        confidence: ci === -1 ? '' : (r[ci] || ''), decision: di === -1 ? '' : (r[di] || ''),
+      })),
+    };
+  }
+  return null;
+}
+
+/** Rows of the comparable-products table (first header cell `Product`), or null. */
+function productTable(text) {
+  const t = tables(text).find((tb) => /^products?$/i.test(tb[0][0] || ''));
+  return t ? t.slice(1) : null;
+}
+
+const isUnknown = (answer) => /^\W*unknown\b/i.test(answer);
+const hasAssumption = (cell) => /assum\w*\s*[:\u2014\u2013-]?\s*\S/i.test(cell);
+
+/** Numbered questions in a questions file: lines `1. …` or `1) …`, or `| 1 | … |` table rows. */
+function readQuestions(text) {
+  const qs = [];
+  for (const line of String(text).split('\n')) {
+    const m = line.match(/^\s*(\d+)[.)]\s+(\S.*)$/) || line.match(/^\s*\|\s*(\d+)\s*\|\s*([^|]*\S[^|]*)\|/);
+    if (m) qs.push({ n: parseInt(m[1], 10), text: m[2].trim() });
+  }
+  return qs;
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} questionsPath  the questions file the orchestrator wrote
+ * @param {string} researchPath   the researcher's answers
+ * @param {{market?: boolean}} [opts]  market mode also requires the products table
+ */
+function checkResearch(cwd, questionsPath, researchPath, opts = {}) {
+  const qAbs = path.resolve(cwd, String(questionsPath));
+  const rAbs = path.resolve(cwd, String(researchPath));
+  if (!fs.existsSync(qAbs)) return { error: 'file_not_found', reason: `no questions file at ${questionsPath}` };
+  if (!fs.existsSync(rAbs)) return { error: 'file_not_found', reason: `no research file at ${researchPath}` };
+  const questions = readQuestions(toLf(fs.readFileSync(qAbs, 'utf-8')));
+  const text = toLf(fs.readFileSync(rAbs, 'utf-8'));
+  const errors = [];
+  const warnings = [];
+  if (questions.length === 0) errors.push({ code: 'no_questions', detail: 'the questions file lists no numbered question: with nothing blocking the build, no research runs' });
+  if (questions.length > MAX_QUESTIONS) errors.push({ code: 'too_many_questions', detail: `${questions.length} questions; at most ${MAX_QUESTIONS}, the ones that block building` });
+  const table = answerTable(text);
+  let answered = 0;
+  let unknown = 0;
+  if (!table) {
+    errors.push({ code: 'answers_missing', detail: 'no answers table (| # | Question | Answer | Source | Confidence | Decision it settles |)' });
+  } else {
+    for (const q of questions) {
+      const row = table.rows.find((r) => r.n === q.n);
+      if (!row || !row.answer || (PLACEHOLDER_RE.test(row.answer) && !isUnknown(row.answer))) {
+        errors.push({ code: 'question_unanswered', question: q.n, detail: `question ${q.n} has no answer row` });
+        continue;
+      }
+      if (isUnknown(row.answer)) {
+        if (hasAssumption(`${row.answer} ${row.decision}`)) unknown++;
+        else errors.push({ code: 'unknown_without_assumption', question: q.n, detail: `question ${q.n} is unknown but names no assumption the plan should use` });
+        continue;
+      }
+      if (!row.source || PLACEHOLDER_RE.test(row.source)) {
+        errors.push({ code: 'answer_no_source', question: q.n, detail: `question ${q.n} has an answer with no source (URL or doc, and date)` });
+        continue;
+      }
+      if (!/^(high|medium|low)\b/i.test(row.confidence)) warnings.push({ code: 'answer_no_confidence', question: q.n, detail: `question ${q.n} gives no HIGH, MEDIUM or LOW confidence` });
+      answered++;
+    }
+    const known = new Set(questions.map((q) => q.n));
+    for (const r of table.rows) {
+      if (!known.has(r.n)) warnings.push({ code: 'extra_row', row: r.n, detail: `row ${r.n} answers no listed question: new scope goes under Ideas, not into the answers` });
+    }
+  }
+  const products = productTable(text);
+  if (products && products.length > MAX_PRODUCTS) errors.push({ code: 'too_many_products', detail: `${products.length} comparable products; at most ${MAX_PRODUCTS}` });
+  if (opts.market && !products) errors.push({ code: 'products_missing', detail: 'market mode: no table whose first column is Product' });
+  const rel = (abs) => { const r = path.relative(path.resolve(cwd), abs); return r && !r.startsWith('..') ? toPosix(r) : toPosix(abs); };
+  return {
+    questions_file: rel(qAbs), research_file: rel(rAbs), ok: errors.length === 0,
+    questions: questions.length, answered, unknown, products: products ? products.length : 0,
+    limits: { questions: MAX_QUESTIONS, products: MAX_PRODUCTS }, errors, warnings,
+  };
+}
+
+function cmdResearchCheck(cwd, questionsPath, researchPath, opts, raw) {
+  if (!questionsPath || !researchPath) error('Usage: research check <questions file> <research file> [--market]');
+  const r = checkResearch(cwd, questionsPath, researchPath, opts);
+  if (r.error) { output(r, raw); return; }
+  output(r, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
+}
+
 function cmdResearchLint(cwd, target, opts, raw) {
   if (!target) error('Usage: research lint <phase|path> [--now YYYY-MM-DD]');
   const r = lintResearch(cwd, target, opts);
@@ -118,4 +265,4 @@ function cmdResearchLint(cwd, target, opts, raw) {
   output(r, raw, r.ok ? 'valid' : 'invalid', r.ok ? 0 : 1);
 }
 
-module.exports = { FRESHNESS_DAYS, lintResearch, cmdResearchLint };
+module.exports = { FRESHNESS_DAYS, MAX_QUESTIONS, MAX_PRODUCTS, lintResearch, cmdResearchLint, checkResearch, cmdResearchCheck };

package/pan-wizard-core/bin/lib/review-deep.cjs

@@ -14,14 +14,14 @@
  *   - writeDeepReview(cwd, phaseNum, payload) — serialize the merged output
  *     to .planning/reviews/<N>/deep-review.md
  *
- * Agents publish to `review-handoff` channel via bus.cjs for audit trail.
+ * It used to publish each merge to a `review-handoff` bus channel that nothing read;
+ * deep-review.md is the record (program L7).
  */
 
 const fs = require('fs');
 const path = require('path');
 const { output, error, safeReadFile, toPosix, escapeTableCell } = require('./core.cjs');
 const { planningPath } = require('./utils.cjs');
-const { publish } = require('./bus.cjs');
 const { findVerdictBlocks, validateVerdict } = require('./verdict.cjs');
 
 const REVIEWS_DIR = 'reviews';
@@ -126,14 +126,16 @@ function findingsFromVerdictBlock(content, source) {
  * @param {Array|string} reviewer - reviewer findings array OR markdown content
  * @param {Array|string} hardener - hardener findings array OR markdown content
  * @param {Array|string} [meta]   - optional meta-reviewer findings
+ * @param {Array|string} [cross]  - optional cross-family lane findings (R4)
  * @returns {Object} Merged payload
  */
-function mergeReviews(reviewer, hardener, meta) {
+function mergeReviews(reviewer, hardener, meta, cross) {
   const r = Array.isArray(reviewer) ? reviewer : parseReviewFindings(reviewer || '', 'reviewer');
   const h = Array.isArray(hardener) ? hardener : parseReviewFindings(hardener || '', 'hardener');
   const m = Array.isArray(meta) ? meta : parseReviewFindings(meta || '', 'meta-reviewer');
+  const x = Array.isArray(cross) ? cross : parseReviewFindings(cross || '', 'cross-family');
 
-  const findings = [...r, ...h, ...m].sort((a, b) => {
+  const findings = [...r, ...h, ...m, ...x].sort((a, b) => {
     const wa = SEVERITY_WEIGHT[a.severity] ?? 0;
     const wb = SEVERITY_WEIGHT[b.severity] ?? 0;
     if (wa !== wb) return wb - wa;
@@ -174,6 +176,7 @@ function mergeReviews(reviewer, hardener, meta) {
       reviewer: r.length,
       hardener: h.length,
       meta_reviewer: m.length,
+      cross_family: x.length,
     },
     by_severity: SEVERITIES.reduce((acc, s) => { acc[s] = findings.filter(f => f.severity === s).length; return acc; }, {}),
   };
@@ -263,19 +266,6 @@ function writeDeepReview(cwd, phaseNum, payload, opts) {
     return { error: `Failed to write ${file}: ${e.message}` };
   }
 
-  // Audit trail on the review-handoff bus channel (best-effort).
-  if (opts?.audit_channel !== false) {
-    try {
-      publish(cwd, 'review-handoff', {
-        phase: phaseNum,
-        verdict: payload.verdict,
-        finding_count: payload.coverage.total,
-        conflict_count: payload.conflicts.length,
-        file: toPosix(path.relative(cwd, file)),
-      }, { source: 'pan-meta-reviewer' });
-    } catch { /* non-blocking */ }
-  }
-
   return { written: true, file: toPosix(path.relative(cwd, file)) };
 }
 
@@ -290,15 +280,16 @@ function resolveAgainstCwd(cwd, p) {
 }
 
 function cmdReviewDeepMerge(cwd, phaseNum, opts, raw) {
-  if (!phaseNum) error('Usage: review-deep merge <phase> --reviewer-file X --hardener-file Y [--meta-file Z]');
+  if (!phaseNum) error('Usage: review-deep merge <phase> --reviewer-file X --hardener-file Y [--meta-file Z] [--cross-file W]');
   const reviewerContent = opts.reviewerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.reviewerFile)) : '';
   const hardenerContent = opts.hardenerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.hardenerFile)) : '';
   const metaContent = opts.metaFile ? safeReadFile(resolveAgainstCwd(cwd, opts.metaFile)) : '';
-  if (!reviewerContent && !hardenerContent && !metaContent) {
+  const crossContent = opts.crossFile ? safeReadFile(resolveAgainstCwd(cwd, opts.crossFile)) : '';
+  if (!reviewerContent && !hardenerContent && !metaContent && !crossContent) {
     output({ error: 'No input files provided or readable' }, raw);
     return;
   }
-  const payload = mergeReviews(reviewerContent, hardenerContent, metaContent);
+  const payload = mergeReviews(reviewerContent, hardenerContent, metaContent, crossContent);
   const result = writeDeepReview(cwd, phaseNum, payload);
   if (result.error) { output(result, raw); return; }
   output({ ...result, verdict: payload.verdict, coverage: payload.coverage, conflicts: payload.conflicts.length }, raw);
@@ -306,11 +297,12 @@ function cmdReviewDeepMerge(cwd, phaseNum, opts, raw) {
 
 function cmdReviewDeepAnalyze(cwd, phaseNum, opts, raw) {
   // Returns the merged payload WITHOUT writing a file. Useful for piping.
-  if (!phaseNum) error('Usage: review-deep analyze <phase> --reviewer-file X --hardener-file Y [--meta-file Z]');
+  if (!phaseNum) error('Usage: review-deep analyze <phase> --reviewer-file X --hardener-file Y [--meta-file Z] [--cross-file W]');
   const reviewerContent = opts.reviewerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.reviewerFile)) : '';
   const hardenerContent = opts.hardenerFile ? safeReadFile(resolveAgainstCwd(cwd, opts.hardenerFile)) : '';
   const metaContent = opts.metaFile ? safeReadFile(resolveAgainstCwd(cwd, opts.metaFile)) : '';
-  output(mergeReviews(reviewerContent, hardenerContent, metaContent), raw);
+  const crossContent = opts.crossFile ? safeReadFile(resolveAgainstCwd(cwd, opts.crossFile)) : '';
+  output(mergeReviews(reviewerContent, hardenerContent, metaContent, crossContent), raw);
 }
 
 module.exports = {

package/pan-wizard-core/bin/lib/review-vote.cjs

@@ -0,0 +1,105 @@
+'use strict';
+/**
+ * Review lenses and k-pass voting (program R2).
+ *
+ * With `workflow.review_mode: lenses`, exec-phase runs the reviewer once per lens
+ * (LENSES) instead of once, and `review vote` merges the passes in code. A finding
+ * survives only when a quorum of passes reported it (the validator: a finding one
+ * pass alone raised is a likely false alarm), at the highest severity any pass gave
+ * it. The verdict is recomputed from what survived, never taken from one pass. The
+ * merged report carries a normal `pan-verdict` block, so `findings record` reads it
+ * like any single review.
+ *
+ * Opt-in until its evidence gate decides: a paired corpus run must show lenses
+ * catching more without raising false alarms (docs/specs/product-excellence-superplan.md).
+ */
+const fs = require('fs');
+const path = require('path');
+const { output, error } = require('./core.cjs');
+const V = require('./verdict.cjs');
+const { sameFinding } = require('./findings.cjs');
+
+const LENSES = Object.freeze(['correctness', 'security', 'maintainability']);
+const SEVERITY_RANK = Object.fromEntries(V.SEVERITIES.map((s, i) => [s, V.SEVERITIES.length - i]));
+const FENCE = '```';
+
+/**
+ * Merge reviewer passes.
+ * @param {string[]} texts - each pass's full report (with its pan-verdict block)
+ * @param {{phase?: string, quorum?: number}} [opts]
+ * @returns {{ok:true, passes, quorum, verdict, dropped, text}|{ok:false, error, reason}}
+ */
+function voteVerdicts(texts, opts = {}) {
+  const parsed = [];
+  for (let i = 0; i < texts.length; i++) {
+    const p = V.parseVerdictText(String(texts[i] || ''), { agent: 'pan-reviewer', phase: opts.phase });
+    if (!p.ok) return { ok: false, error: 'unreadable_pass', reason: `pass ${i + 1} has no readable pan-verdict block (${p.error})` };
+    parsed.push(p.verdict);
+  }
+  if (parsed.length === 0) return { ok: false, error: 'no_passes', reason: 'review vote needs at least one pass' };
+  const quorum = Number.isInteger(opts.quorum) && opts.quorum > 0 ? opts.quorum : Math.ceil(parsed.length / 2);
+
+  // Cluster findings across passes; a pass counts once per cluster.
+  const clusters = [];
+  parsed.forEach((v, pass) => {
+    for (const f of v.findings) {
+      const c = clusters.find((x) => sameFinding(x.finding, f));
+      if (c) {
+        c.passes.add(pass);
+        if ((SEVERITY_RANK[f.severity] || 0) > (SEVERITY_RANK[c.finding.severity] || 0)) c.finding = { ...c.finding, severity: f.severity };
+      } else {
+        clusters.push({ finding: { ...f }, passes: new Set([pass]) });
+      }
+    }
+  });
+  const kept = clusters.filter((c) => c.passes.size >= quorum).map((c) => ({ ...c.finding, votes: c.passes.size }));
+  const dropped = clusters.filter((c) => c.passes.size < quorum).map((c) => ({ ...c.finding, votes: c.passes.size }));
+
+  const counted = kept.filter((f) => !f.pre_existing);
+  const errors = counted.some((f) => f.severity === 'critical' || f.severity === 'high');
+  const warnings = counted.some((f) => f.severity === 'medium' || f.severity === 'low');
+  const verdictWord = errors ? 'NEEDS_FIXES' : (warnings ? 'PASS_WITH_WARNINGS' : 'PASS');
+
+  const declined = [];
+  for (const v of parsed) for (const d of v.declined || []) if (!declined.some((x) => x.behaviour === d.behaviour)) declined.push(d);
+  const notChecked = [];
+  for (const v of parsed) for (const n of v.not_checked || []) if (!notChecked.some((x) => x.check === n.check)) notChecked.push(n);
+
+  const verdict = {
+    contract: V.VERDICT_CONTRACT, agent: 'pan-reviewer', phase: opts.phase || parsed[0].phase || null,
+    verdict: verdictWord, outcome: errors ? 'fail' : 'pass',
+    findings: kept.map(({ votes, ...f }) => ({ ...f, votes })),
+    ...(declined.length ? { declined } : {}),
+    ...(notChecked.length ? { not_checked: notChecked } : {}),
+  };
+  const lines = [
+    `## Code Review — Phase ${verdict.phase || '?'} (${parsed.length} passes, quorum ${quorum})`,
+    '',
+    `### Verdict`,
+    verdictWord,
+    '',
+    `Kept ${kept.length} finding(s) at least ${quorum} pass(es) reported; dropped ${dropped.length} only fewer passes raised.`,
+    ...kept.map((f) => `- ${f.severity.toUpperCase()} ${f.where || '(no location)'}: ${f.summary} (${f.votes}/${parsed.length})`),
+    ...(dropped.length ? ['', 'Dropped (below quorum):', ...dropped.map((f) => `- ${f.severity} ${f.where || '(no location)'}: ${f.summary} (${f.votes}/${parsed.length})`)] : []),
+    '',
+    `${FENCE}pan-verdict`,
+    JSON.stringify(verdict),
+    FENCE,
+    '',
+  ];
+  return { ok: true, passes: parsed.length, quorum, verdict, dropped, text: lines.join('\n') };
+}
+
+function cmdReviewVote(cwd, opts, raw) {
+  const files = opts.files || [];
+  if (!files.length) error('Usage: review vote [--phase N] [--quorum K] [--out <file>] <pass-file>...');
+  const texts = files.map((f) => {
+    try { return fs.readFileSync(path.isAbsolute(f) ? f : path.join(cwd, f), 'utf8'); } catch { return ''; }
+  });
+  const r = voteVerdicts(texts, { phase: opts.phase, quorum: opts.quorum ? Number(opts.quorum) : undefined });
+  if (!r.ok) { output(r, raw, 'error', 1); return; }
+  if (opts.out) fs.writeFileSync(path.isAbsolute(opts.out) ? opts.out : path.join(cwd, opts.out), r.text);
+  output({ ok: true, passes: r.passes, quorum: r.quorum, kept: r.verdict.findings.length, dropped: r.dropped.length, verdict: r.verdict.verdict, out: opts.out || null }, raw, r.verdict.verdict);
+}
+
+module.exports = { LENSES, voteVerdicts, cmdReviewVote };

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

@@ -55,22 +55,8 @@ const { getExperimentManifest, PAN_EXPERIMENTS_ROOT_DEFAULT } = require('./exper
 // claude into `--output-format json` so the trailing usage envelope can be
 // parsed for cost/token metrics. Other runtimes are unchanged — token
 // metering for codex/gemini/opencode is deferred (no equivalent flag).
-const RUNTIME_RUNNERS = Object.freeze({
-  claude:   {
-    bin: 'claude',
-    buildArgs: (prompt, opts) => {
-      const args = ['-p', '--dangerously-skip-permissions'];
-      if (opts && opts.captureMetrics) args.push('--output-format', 'json');
-      args.push(prompt);
-      return args;
-    },
-    shell: 'win32',
-  },
-  codex:    { bin: 'codex',    buildArgs: (prompt) => ['exec', prompt],                                  shell: 'win32' },
-  gemini:   { bin: 'gemini',   buildArgs: (prompt) => ['-p', '--yolo', prompt],                          shell: 'win32' },
-  opencode: { bin: 'opencode', buildArgs: (prompt) => [prompt],                                          shell: 'win32' },
-  copilot:  null,
-});
+// The adapters live in hosts.cjs, the one host table (program A0).
+const RUNTIME_RUNNERS = require('./hosts.cjs').runnerTable();
 
 // ── Stop reasons (enum-ish) ─────────────────────────────────────────────────