@golden-frijoles/kit 0.0.0 → 0.2.0

package/dist/build-order-sync.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// build-order-sync.mjs — regenerate Roadmap/00-ideas/BUILD-ORDER.md when it's drifted from the SSOT,
+// and open a `claude/` DOCS PR with the fix. Never hand-edits the board (SSOT = each epic README's
+// frontmatter `status:`, per scripts/build-order.mjs).
+//
+// Usage:
+//   node scripts/build-order-sync.mjs             # check → regen → branch → commit → push → gh pr create
+//   node scripts/build-order-sync.mjs --dry-run   # check → regen → print `git diff --stat` → restore the
+//                                                  # file (`git checkout --`), leaving the working tree
+//                                                  # exactly as found — no branch/commit/push/PR, and no
+//                                                  # lingering file mutation either
+//
+// The branch stays `claude/`-prefixed on purpose — that's a routine's DEFAULT push scope (see
+// scripts/routines/README.md's two standing rules), unlike standup.mjs which needed push enabled
+// BEYOND that default to land its log commit on `main` directly. Don't over-grant push for this one.
+//
+// Reuse, don't rebuild: scripts/build-order.mjs (the regenerator + --check), ensureGh()/die()
+// (scripts/lib/cross-agent-cli.mjs). Zero new npm deps — Node 18+.
+
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { ensureGh, die } from './lib/cross-agent-cli.mjs';
+import { createPullRequest } from './lib/gh-rest.mjs';
+import { projectRoot } from './lib/project-root.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = projectRoot(); // D2: the user's project, wherever this set runs from
+const BOARD_PATH = 'Roadmap/00-ideas/BUILD-ORDER.md';
+const BANNER =
+  "> **Advisory — docs-only.** Auto-regenerated from the SSOT (each epic README's frontmatter " +
+  '`status:`). This PR only refreshes the derived board; it never touches the doc that caused the drift.';
+
+const DRY_RUN = process.argv.includes('--dry-run');
+
+function run(cmd, args, opts = {}) {
+  return spawnSync(cmd, args, { cwd: ROOT, encoding: 'utf8', ...opts });
+}
+
+// Pure — the date-stamped branch name. Exported for the co-located test.
+export function branchName(date = new Date()) {
+  return `claude/build-order-sync-${date.toISOString().slice(0, 10)}`;
+}
+
+// Pure — the PR title + body. Exported for the co-located test.
+export function buildPrBody() {
+  return [
+    BANNER,
+    '',
+    `\`${BOARD_PATH}\` was stale — regenerated via \`node scripts/build-order.mjs\` and committed as-is,`,
+    'no hand edits.',
+    '',
+    'Advisory only — not a gate. Review the diff and merge by hand.',
+  ].join('\n');
+}
+export const PR_TITLE = 'chore(build-order): regenerate stale board';
+
+// Pure — parses "owner/repo" from either remote URL form git produces (HTTPS or SSH). Exported for the
+// co-located test. `(?:^|[/@])` requires "github.com" to be preceded by the start of the string, `/`, or
+// `@` — not just any substring match — so a host like `notgithub.com` doesn't false-positive. The repo
+// group allows dots (GitHub permits dotted repo names); it's non-greedy so a trailing `.git` still gets
+// stripped rather than swallowed into the name.
+export function repoSlugFromRemoteUrl(url) {
+  const m = /(?:^|[/@])github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/.exec((url || '').trim());
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+function isDrifted() {
+  const r = run(process.execPath, [join(__dirname, 'build-order.mjs'), '--check']); // a sibling, never the project's copy
+  return r.status !== 0;
+}
+
+function regenerate() {
+  const r = run(process.execPath, [join(__dirname, 'build-order.mjs')]);
+  if (r.status !== 0) die(`build-order.mjs regen failed: ${(r.stderr || r.stdout || '').trim()}`);
+}
+
+function boardActuallyChanged() {
+  const r = run('git', ['status', '--porcelain', '--', BOARD_PATH]);
+  return !!(r.stdout || '').trim();
+}
+
+function main() {
+  if (!isDrifted()) {
+    console.log('BUILD-ORDER.md is up to date — no PR needed.');
+    return;
+  }
+
+  regenerate();
+  if (!boardActuallyChanged()) {
+    console.log(
+      'build-order.mjs --check reported drift, but regen produced no file diff — nothing to commit.'
+    );
+    return;
+  }
+
+  if (DRY_RUN) {
+    const diff = run('git', ['diff', '--stat', '--', BOARD_PATH]);
+    console.log('DRY-RUN — board would be regenerated (no branch/commit/push/PR):');
+    console.log((diff.stdout || '').trim());
+    // regenerate() already wrote the file to disk to compute this diff — restore it so --dry-run leaves
+    // the working tree exactly as it found it (a real "would do this" preview, not a partial mutation).
+    const restore = run('git', ['checkout', '--', BOARD_PATH]);
+    if (restore.status !== 0) {
+      console.error(
+        `build-order-sync: could not restore ${BOARD_PATH} after --dry-run (${(restore.stderr || '').trim()}) — the working tree is left with the regenerated file; revert it manually if needed.`
+      );
+    }
+    return;
+  }
+
+  ensureGh();
+
+  const branch = branchName();
+  const checkout = run('git', ['checkout', '-b', branch]);
+  if (checkout.status !== 0) die(`git checkout -b ${branch} failed: ${(checkout.stderr || '').trim()}`);
+
+  const add = run('git', ['add', BOARD_PATH]);
+  if (add.status !== 0) die(`git add failed: ${(add.stderr || '').trim()}`);
+
+  const commit = run('git', ['commit', '-m', 'chore(build-order): regenerate stale board', '--', BOARD_PATH]);
+  if (commit.status !== 0) die(`git commit failed: ${(commit.stderr || '').trim()}`);
+
+  const push = run('git', ['push', '-u', 'origin', branch]);
+  if (push.status !== 0) die(`git push failed: ${(push.stderr || '').trim()}`);
+
+  // REST-only (scripts/lib/gh-rest.mjs) — `gh pr create` hits GraphQL internally, which is blocked in at
+  // least one live routine sandbox (confirmed 2026-07-02, ops-nightly). createPullRequest() is a plain
+  // REST POST instead, so this needs the owner/repo slug explicitly (gh CLI normally infers it from the
+  // current directory's git remote — parsed here from `git remote get-url origin` instead).
+  const remoteUrl = (run('git', ['remote', 'get-url', 'origin']).stdout || '').trim();
+  const repo = repoSlugFromRemoteUrl(remoteUrl);
+  if (!repo) die(`could not parse an owner/repo slug from the origin remote URL: ${remoteUrl || '(empty)'}`);
+
+  const pr = createPullRequest({ repo, head: branch, base: 'main', title: PR_TITLE, body: buildPrBody() });
+  if (!pr) die('creating the build-order docs PR failed.');
+  console.log(pr.url);
+}
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (isMain) main();

package/dist/build-order.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// build-order.mjs — render Roadmap/00-ideas/BUILD-ORDER.md from the SAME projection every roadmap
+// tool reads (roadmap-extract.mjs). One source of truth: seed frontmatter + epic/sprint
+// status lines. This file is GENERATED — never hand-edit BUILD-ORDER.md; run this instead.
+//
+//   node scripts/build-order.mjs            # write Roadmap/00-ideas/BUILD-ORDER.md
+//   node scripts/build-order.mjs --check    # exit 1 if the file is stale (for CI/precommit)
+//
+// Why this exists: BUILD-ORDER.md used to be hand-maintained, so it drifted on every merge. Status
+// and ordering already live in seed frontmatter (the SSOT the Notion projection reads). This makes
+// the in-repo board a derived view that cannot drift.
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { EPIC_STATUS_ORDER, SEED_FUNNEL_STATUSES } from './lib/roadmap-status-buckets.mjs';
+import { projectRoot } from './lib/project-root.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO = projectRoot(); // D2
+const OUT = join(REPO, 'Roadmap', '00-ideas', 'BUILD-ORDER.md');
+const EXTRACTOR = join(__dirname, 'roadmap-extract.mjs');
+
+function extract() {
+  const json = execFileSync('node', [EXTRACTOR], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return JSON.parse(json);
+}
+
+// SSOT = each epic README's frontmatter `status:` field (00-ideas/README). The extractor resolves it
+// into r.status (frontmatter-authoritative, prose/retro fallback) and also emits r.status_derived (the
+// fallback derivation) so this board can flag an advisory drift when the two disagree. No seed read
+// here — a scaffolded epic's seed is funnel-only; the epic README owns its status.
+
+// Epic status → bucket. Sprints are folded into their epic via sprint_progress; seeds are the funnel.
+// The bucket KEYS/ORDER and the seed-funnel status set live in scripts/lib/roadmap-status-buckets.mjs —
+// shared with any other view of the roadmap (a reporting hub, a dashboard) so it can never independently
+// drift from this board's counts. Emoji/title here are this board's own presentation.
+const EPIC_BUCKET_META = {
+  'In progress': { emoji: '🏗️', title: 'Building now' },
+  Scaffolded: { emoji: '📋', title: 'Ready to build (scaffolded, not started)' },
+  Shipped: { emoji: '✅', title: 'Shipped' },
+};
+const EPIC_BUCKETS = EPIC_STATUS_ORDER.map((key) => ({ key, ...EPIC_BUCKET_META[key] }));
+const SEED_FUNNEL = SEED_FUNNEL_STATUSES;
+
+function line(r) {
+  const bits = [`[${r.name}](../../${r.doc_link.replace(/^Roadmap\//, '')})`];
+  const meta = [];
+  if (r.area) meta.push(r.area);
+  if (r.sprint_progress) meta.push(r.sprint_progress);
+  if (r.risk) meta.push(`risk: ${r.risk}`);
+  if (r.priority) meta.push(r.priority);
+  return `- ${bits[0]}${meta.length ? ` — ${meta.join(' · ')}` : ''}`;
+}
+
+function render(rows) {
+  const epics = rows.filter((r) => r.grain === 'Epic');
+  const seeds = rows.filter((r) => r.grain === 'Seed');
+  const now = new Date().toISOString().slice(0, 10);
+
+  // Epic status is authoritative from the README frontmatter (the extractor resolved it into e.status).
+  // Advisory drift = the prose/retro derivation (e.status_derived) disagreeing with that authoritative
+  // status — usually a close-out that forgot to set `status:`, or a stale README. Non-gating signal.
+  const drift = [];
+  for (const e of epics) {
+    if (e.status_derived && e.status_derived !== e.status) {
+      drift.push({ name: e.name, frontmatter: e.status, derived: e.status_derived });
+    }
+  }
+  render._drift = drift;
+
+  const out = [];
+  out.push('<!-- GENERATED FILE — do not edit by hand.');
+  out.push('     Regenerate:  node scripts/build-order.mjs');
+  out.push("     Status SSOT: each epic README's frontmatter `status:` field (set at epic close). Funnel");
+  out.push('     ordering: seed frontmatter (priority). Both projected via scripts/roadmap-extract.mjs. -->');
+  out.push('');
+  out.push('# Build order — generated status board');
+  out.push('');
+  out.push(
+    `> **Generated ${now} — do not hand-edit.** Epic status SSOT = the epic \`README.md\` frontmatter`
+  );
+  out.push(
+    '> `status:` field (set at epic close). To change what this shows, edit that field (or a seed for the'
+  );
+  out.push(
+    '> funnel), then run `node scripts/build-order.mjs`. This board and the Notion "Marketplace Roadmap"'
+  );
+  out.push('> DB are both *derived views* — never hand-edit the board.');
+  out.push('');
+
+  for (const b of EPIC_BUCKETS) {
+    const list = epics
+      .filter((e) => e.status === b.key)
+      .sort((a, z) => (a.area || '').localeCompare(z.area || '') || a.name.localeCompare(z.name));
+    out.push(`## ${b.emoji} ${b.title} (${list.length})`);
+    out.push('');
+    out.push(list.length ? list.map(line).join('\n') : '_None._');
+    out.push('');
+  }
+
+  const funnel = seeds
+    .filter((s) => SEED_FUNNEL.has(s.status))
+    .sort((a, z) => (a.priority || 'zzz').localeCompare(z.priority || 'zzz') || a.name.localeCompare(z.name));
+  out.push(`## ⬜ Funnel — seeds not yet scaffolded (${funnel.length})`);
+  out.push('');
+  out.push(
+    funnel.length
+      ? funnel
+          .map((s) => {
+            const meta = [s.status, s.type, s.appetite ? `appetite ${s.appetite}` : null, s.priority]
+              .filter(Boolean)
+              .join(' · ');
+            // A queued seed without an underwriter is funded-but-unowned — advisory drift, loud on the board.
+            const warn =
+              s.status === 'Queued' && !s.underwritten_by
+                ? ' — ⚠️ no underwriter (set `underwritten_by:` at the betting table)'
+                : '';
+            return `- [${s.name}](seeds/${s.slug}.md)${meta ? ` — ${meta}` : ''}${warn}`;
+          })
+          .join('\n')
+      : '_None._'
+  );
+  out.push('');
+
+  if (drift.length) {
+    out.push(`## ⚠️ Status drift — README frontmatter vs sprint/retro-derived (${drift.length})`);
+    out.push('');
+    out.push('These epics’ authoritative README-frontmatter `status:` disagrees with what the sprint/retro');
+    out.push('derivation infers. The board trusts the **frontmatter**; a mismatch usually means a close-out');
+    out.push(
+      'forgot to set `status:` (or the README is stale). Reconcile the README, then this advisory clears.'
+    );
+    out.push('');
+    out.push('| Epic | frontmatter (used) | sprint/retro-derived |');
+    out.push('|---|---|---|');
+    for (const d of drift) out.push(`| ${d.name} | ${d.frontmatter} | ${d.derived} |`);
+    out.push('');
+  }
+
+  out.push('---');
+  out.push(
+    `_Epics: ${epics.length} · seeds in funnel: ${funnel.length} · status drift: ${drift.length}. Regenerate with \`node scripts/build-order.mjs\`._`
+  );
+  out.push('');
+  return out.join('\n');
+}
+
+const rows = extract();
+
+// Underwriting enforcement (WAYS-OF-WORKING → Betting & appetite): a QUEUED seed is a bet — it
+// must carry an `appetite:`. Hard fail, not advisory: the board physically rejects unfunded work
+// (the same enforced-not-advisory stance as the status enum).
+const unfunded = rows.filter((r) => r.grain === 'Seed' && r.status === 'Queued' && !r.appetite);
+if (unfunded.length) {
+  console.error(
+    'Queued seeds missing `appetite:` frontmatter (S | M | L — set at shaping, bet at the wave boundary):'
+  );
+  for (const s of unfunded) console.error(`  - ${s.doc_link}`);
+  process.exit(1);
+}
+
+const content = render(rows);
+
+if (process.argv.includes('--check')) {
+  const current = existsSync(OUT) ? readFileSync(OUT, 'utf8') : '';
+  // Ignore the "Generated <date>" line when comparing so a date-only diff isn't "stale".
+  const norm = (s) => s.replace(/^> \*\*Generated \d{4}-\d{2}-\d{2} /m, '> **Generated DATE ');
+  if (norm(current) !== norm(content)) {
+    console.error('BUILD-ORDER.md is stale — run: node scripts/build-order.mjs');
+    process.exit(1);
+  }
+  console.log('BUILD-ORDER.md is up to date.');
+} else {
+  writeFileSync(OUT, content);
+  console.log(`Wrote ${OUT}`);
+}

package/dist/cross-panel.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// cross-panel.mjs — an ADVISORY cross-agent second opinion on a PROPOSED PLAN (a scope/seed doc).
+//
+// The planning-half sibling of cross-review.mjs: instead of a PR diff it reads ONE plan doc and pipes it
+// into a DIFFERENT model family's CLI (Codex or Antigravity) with an architecture LENS prompt
+// (scripts/cross-panel.prompt.md), then PRINTS the critique. It is dev tooling, not app code, and is:
+//   • SINGLE-PASS — one read per lens, no debate / iterate-to-convergence loop (our #1 token sink).
+//   • PRINT-ONLY — it NEVER edits the doc. The product owner commits any takeaways as a normal doc commit.
+//   • ADVISORY ONLY — never gates. The product owner's scope-doc approval remains the only gate (planning has no CI).
+//
+// Usage:
+//   node scripts/cross-panel.mjs <scope-doc> --agent codex|antigravity --lens architect-purist [--dry-run]
+//
+// CLI plumbing is shared with cross-review.mjs via scripts/lib/cross-agent-cli.mjs. Zero npm deps — Node 18+.
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import {
+  AGENTS,
+  AGENT_BIN,
+  die,
+  need,
+  ensureCmd,
+  checkAgyVersion,
+  loadPromptBody,
+  runCodex,
+  runAntigravity,
+  runVibe,
+  runClaudeCode,
+} from './lib/cross-agent-cli.mjs';
+import { projectAsset } from './lib/project-root.mjs';
+
+const PROMPT_PATH = projectAsset('cross-panel.prompt.md'); // a TEMPLATE FILL-IN the project owns
+
+function helpText(lenses) {
+  return `cross-panel.mjs — advisory cross-agent second opinion on a proposed plan (a scope/seed doc).
+
+Usage:
+  node scripts/cross-panel.mjs <scope-doc> --agent codex|antigravity --lens <name> [--dry-run]
+
+Flags:
+  --agent <name>   reviewer CLI: ${Object.keys(AGENTS).join('|')} (default: codex)
+  --lens  <name>   architecture lens: ${lenses.join('|')}|both (default: both)
+  --dry-run        print the composed prompt(s) that WOULD be sent, without invoking the CLI
+  -h, --help       show this help
+
+The pair (--lens both, the default) runs each lens single-pass on the chosen --agent, then prints one
+combined advisory block with a contradiction-synthesis. For model-family diversity, run twice with a
+different --agent. A single --lens <name> is the quick one-lens look.
+
+Advisory only — single-pass, print-only, never gates. Your scope-doc approval decides.`;
+}
+
+function parseArgs(argv) {
+  const out = { doc: null, agent: 'codex', lens: 'both', dryRun: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--agent') out.agent = need(argv[++i], '--agent');
+    else if (a.startsWith('--agent=')) out.agent = a.slice('--agent='.length);
+    else if (a === '--lens') out.lens = need(argv[++i], '--lens');
+    else if (a.startsWith('--lens=')) out.lens = a.slice('--lens='.length);
+    else if (!a.startsWith('-') && out.doc === null) out.doc = a;
+    else die(`unknown argument '${a}' (try --help)`);
+  }
+  return out;
+}
+
+// Slice the section starting at `from` (a `## ` heading) up to the next `## ` heading or EOF.
+function sliceSection(body, from) {
+  const rest = body.slice(from + 2);
+  const nextRel = rest.search(/^##[ \t]+/m);
+  const to = nextRel === -1 ? body.length : from + 2 + nextRel;
+  return body.slice(from, to).trim();
+}
+
+// Parse the prompt library into { preamble, lenses: {name: sectionText}, synthesis }. The shared preamble is
+// everything before the first `## LENS:` heading; each lens / the `## SYNTHESIS` section runs to the next
+// `## ` heading or EOF.
+function parsePromptLibrary(body) {
+  const lensRe = /^##[ \t]+LENS:[ \t]*(\S+)[ \t]*$/gm;
+  const firstLens = body.search(/^##[ \t]+LENS:/m);
+  if (firstLens === -1) die(`no '## LENS:' sections found in ${PROMPT_PATH}`);
+  const preamble = body.slice(0, firstLens).trim();
+
+  const lenses = {};
+  let m;
+  while ((m = lensRe.exec(body)) !== null) lenses[m[1]] = sliceSection(body, m.index);
+
+  const synthAt = body.search(/^##[ \t]+SYNTHESIS[ \t]*$/m);
+  const synthesis = synthAt === -1 ? null : sliceSection(body, synthAt);
+
+  return { preamble, lenses, synthesis };
+}
+
+function readDoc(path) {
+  if (!existsSync(path)) die(`scope doc not found: ${path}`);
+  if (statSync(path).isDirectory()) die(`expected a file, got a directory: ${path}`);
+  const text = readFileSync(path, 'utf8');
+  if (!text.trim()) die(`scope doc is empty: ${path}`);
+  return text;
+}
+
+const BANNER =
+  "> **Advisory only — not a gate.** CI/QA don't apply to planning; your scope-doc approval decides. " +
+  'Single-pass second opinion from a different model family.';
+
+// Compose the full prompt for one lens: shared preamble + the lens section.
+function composeLensPrompt(preamble, lensSection) {
+  return `${preamble}\n\n${lensSection}\n`;
+}
+
+// Run a single-pass prompt + context block through the selected agent. codex takes the context on stdin;
+// agy and vibe have no usable stdin for the prompt, so the context rides embedded in the argv string
+// (size-capped in each helper); codex and claude take it on stdin.
+// opts.soft → return null instead of die()-ing on CLI failure (used by the non-essential synthesis pass).
+function runWithAgent(agent, prompt, contextLabel, contextText, opts = {}) {
+  const block = `## ${contextLabel}\n\n${contextText}`;
+  if (agent === 'codex') return runCodex(prompt, block, opts);
+  if (agent === 'antigravity') return runAntigravity(`${prompt}\n\n${block}\n`, opts);
+  if (agent === 'vibe') return runVibe(`${prompt}\n\n${block}\n`, opts);
+  if (agent === 'claude') return runClaudeCode(prompt, block, opts);
+  die(`unknown --agent '${agent}'; use ${Object.keys(AGENTS).join('|')}`);
+}
+
+function ensureAgentCli(agent) {
+  if (agent === 'codex') {
+    ensureCmd('codex', 'codex not found — install Codex CLI (https://github.com/openai/codex) and `codex login`.');
+  } else if (agent === 'antigravity') {
+    ensureCmd('agy', 'agy not found — install the Antigravity CLI and authenticate it, then retry.');
+    checkAgyVersion();
+  } else if (agent === 'vibe') {
+    ensureCmd(
+      AGENT_BIN.vibe,
+      'vibe not found — install the Mistral Vibe CLI (`uv tool install mistral-vibe`) and authenticate it, then retry.'
+    );
+  } else if (agent === 'claude') {
+    ensureCmd(
+      AGENT_BIN.claude,
+      'claude not found — install Claude Code (https://claude.com/claude-code) and run `claude auth login`, then retry.'
+    );
+  }
+}
+
+// Run the contradiction-synthesis over the lens critiques (soft — degrades to a note instead of dying).
+function runSynthesis(agent, synthesisSection, results) {
+  if (!synthesisSection) return null;
+  const critiques = results.map((r) => `### ${r.name} critique\n\n${r.findings}`).join('\n\n');
+  return runWithAgent(agent, synthesisSection, 'Two critiques to compare', critiques, { soft: true });
+}
+
+function main() {
+  const body = loadPromptBody(PROMPT_PATH);
+  const { preamble, lenses, synthesis } = parsePromptLibrary(body);
+  const lensNames = Object.keys(lenses);
+
+  const { doc, agent, lens, dryRun, help } = parseArgs(process.argv.slice(2));
+  if (help) {
+    process.stdout.write(helpText(lensNames) + '\n');
+    process.exit(0);
+  }
+  if (doc === null) die('missing <scope-doc>. Usage: node scripts/cross-panel.mjs <scope-doc> --lens both');
+  if (!AGENTS[agent]) die(`unknown --agent '${agent}'; use ${Object.keys(AGENTS).join('|')}`);
+  if (lens !== 'both' && !lenses[lens]) die(`unknown --lens '${lens}'; use ${lensNames.join('|')}|both`);
+
+  const lensesToRun = lens === 'both' ? lensNames : [lens];
+  const docText = readDoc(doc);
+  const contextLabel = `Plan to review (${doc})`;
+
+  if (dryRun) {
+    for (const name of lensesToRun) {
+      process.stdout.write(`# --dry-run: composed prompt for lens '${name}' (agent: ${agent})\n\n`);
+      process.stdout.write(composeLensPrompt(preamble, lenses[name]) + '\n');
+      process.stdout.write(`## ${contextLabel}\n\n${docText}\n\n`);
+    }
+    if (lensesToRun.length > 1) {
+      process.stdout.write(`# --dry-run: a contradiction-synthesis pass would then run over the ${lensesToRun.length} critiques.\n`);
+    }
+    process.stderr.write('\n(dry-run — no CLI invoked)\n');
+    process.exit(0);
+  }
+
+  ensureAgentCli(agent);
+
+  const results = [];
+  for (const name of lensesToRun) {
+    const findings = runWithAgent(agent, composeLensPrompt(preamble, lenses[name]), contextLabel, docText);
+    if (!findings) die(`${AGENTS[agent]} returned no output for lens '${name}'.`);
+    results.push({ name, findings });
+  }
+
+  // Single lens → a single labeled block. The pair → one combined panel + a contradiction-synthesis.
+  if (results.length === 1) {
+    const { name, findings } = results[0];
+    process.stdout.write(`### 🔎 Cross-agent planning panel — ${name} (${AGENTS[agent]})\n\n`);
+    process.stdout.write(`${BANNER}\n\n---\n\n${findings}\n`);
+    return;
+  }
+
+  process.stdout.write(`### 🔎 Cross-agent planning panel\n\n${BANNER}\n\n---\n`);
+  for (const { name, findings } of results) {
+    process.stdout.write(`\n## ${name} (${AGENTS[agent]})\n\n${findings}\n`);
+  }
+
+  const contradictions = runSynthesis(agent, synthesis, results);
+  process.stdout.write('\n## Contradictions to adjudicate\n\n');
+  if (contradictions) {
+    process.stdout.write(contradictions + '\n');
+  } else {
+    process.stdout.write(
+      '_(Synthesis pass unavailable — compare the lens critiques above; no contradiction list was produced.)_\n'
+    );
+  }
+}
+
+main();

package/dist/cross-panel.prompt.md

@@ -0,0 +1,115 @@
+<!--
+  cross-panel.prompt.md — the lens-prompt library for the cross-agent PLANNING panel.
+
+  Single source of truth for `scripts/cross-panel.mjs` (the cross-agent second-opinion-on-a-plan command)
+  and for a human reading the panel's rubric. It factors this project's own AGENTS.md rules + the
+  WAYS-OF-WORKING single-pass discipline into a shared preamble, then adds one section per architecture
+  lens. It is NOT a new rubric — if the criteria change, change them HERE.
+
+  TEMPLATE NOTE: the "rules that cannot be violated" section and the two lens names/framings below are
+  fill-in slots calibrated to a project with ONE dominant system-of-record that everything should route
+  through first. If your project doesn't have that shape, rename the "primitives-first purist" lens to
+  whatever the equivalent house discipline is (or drop it) — don't ship the placeholder framing unedited.
+
+  STRUCTURE the script depends on (don't reorganise without updating the loader):
+    • Everything below the first `---` line is the prompt body.
+    • The SHARED PREAMBLE is everything from the body start up to the first `## LENS:` heading.
+    • Each lens is a `## LENS: <name>` section, running to the next `## ` heading (or end of file).
+    • `## SYNTHESIS` is the contradiction-finder used only on a pair run.
+  The script sends: shared preamble + the selected `## LENS:` section (+ the doc as context).
+
+  The HTML comment above is not part of the prompt; the script sends everything below the first `---`.
+-->
+
+---
+
+You are an **advisory second-opinion reviewer** from a different model family than the agent that is
+grooming this plan. You are reviewing a **proposed plan** — a scope/seed doc for a feature, bug, spike,
+or chore — **before** it gets sliced into an epic and built. Your job is to catch the architecture blind
+spots a same-family planner would miss, while the plan is still cheap to change.
+
+You are **not a gate.** You do not approve, block, or authorize anything. Planning has no deterministic CI
+under it, and your output does not become one — the product owner's scope-doc approval remains the only
+gate. Say so if anyone reads your output as a decision.
+
+This is a **plan, not a diff** — critique the *approach*, not code. Re-derive the intent from the doc itself;
+do not assume the author's framing is correct.
+<!-- TEMPLATE FILL-IN: one or two sentences naming this project's stack/architecture and its dominant
+     system of record, e.g. "the app is <framework> + <commerce/data engine> + <auth provider>." -->
+The rules below are load-bearing.
+
+## Do this in a SINGLE pass
+One read, then write your findings. Do **not** iterate toward consensus or run a back-and-forth loop — that
+loop is this codebase's single largest token cost and is deliberately out of scope. One careful read.
+
+## The rules that cannot be violated (from this project's AGENTS.md)
+<!-- TEMPLATE FILL-IN: replace with your project's own 3–5 "cannot be violated" rules, copied verbatim
+     from AGENTS.md. See cross-review.prompt.md's fill-in note for the expected shape/specificity. -->
+
+## Mandatory: attach a CHECKABLE claim
+Planning output is worthless if it's pure vibes. **End your critique with a "Checkable claim" line**: state
+the single load-bearing assumption your read depends on, plus a *cheap, concrete* way to validate it before
+building — name the file/route/command/doc to check. If your assumption is wrong, the plan changes; the
+checkable claim is how the product owner finds out in five minutes, not five days.
+
+## How to report
+Lead with your lens's verdict in one line. Then group findings by weight: **Blocking concern** (a rule
+violation or a plan that won't hold), **Should reconsider**, **Worth noting**. Each: a one-line claim + why
+it matters for *this* plan. If the plan is sound from your lens, say so plainly — do not manufacture
+findings. Be concise; no preamble, no restating the doc back. Close with the **Checkable claim** line.
+
+## LENS: primitives-first purist
+<!-- TEMPLATE FILL-IN: rename/reframe this lens around your project's own dominant system-of-record, or
+     drop it if the project has no single such system. -->
+You are the **primitives-first purist.** Your question on every line: *does this belong in the project's
+canonical system of record for this domain, and is the team reusing the right primitive instead of
+rebuilding it?* Push hard on:
+- **The dominant-system rule first.** Anything touching this project's core domain must be modeled on
+  its canonical primitives, not a secondary datastore or a bespoke route. Flag any plan that retrofits
+  core-domain state elsewhere.
+- **Reuse vs rebuild.** Does an existing module/seam/route/normalizer already model this? A new table or
+  a new primitive must be *justified* against what already exists.
+- **The remaining rules.** Name the specific rule (from the fill-in list above) a plan strains.
+- **Expensive-to-reverse calls.** A schema/migration shape, a new public route's contract, an id
+  namespace — things that are cheap now and costly later. Say which decisions to get right before slicing.
+Do not reward thinness that *violates a rule* — a quick shortcut around the canonical system is still
+wrong. Hold the architecture line; the pragmatist lens will argue the other side.
+Remember the **Checkable claim** line is mandatory — name the file/route/normalizer to read that would
+confirm (or kill) your "already modeled / not modeled" assumption.
+
+## LENS: architect-pragmatist
+You are the **ship-it pragmatist.** Your question on every line: *what is the thinnest thing that actually
+works and ships, and is this plan over-built for v1?* Push hard on:
+- **Can we already do this today?** (LEARNINGS / the groom skill's "can we already do this?" stage.) Sort
+  the ask into *already-possible* (existing features + the right messaging/positioning — no build),
+  *light-enhancement* (a small story or copy/config change on an existing feature), or *genuinely-new*.
+  If buckets 1–2 hit the outcome, say so loudly — that's the win. A plan that builds net-new when copy +
+  an existing flow would do is the failure mode to catch.
+- **The skateboard.** Is the first slice a real, shippable end-to-end skateboard, or a half-built chassis?
+  Name the thinnest slice that delivers the outcome and call out scope that should be deferred to a later
+  increment (the "car"). Fewer sprints, smaller stories, ship sooner.
+- **Reuse to ship faster.** An existing seam, route, normalizer, or component the plan should lean on so
+  v1 is days not weeks — same reuse instinct as the purist, aimed at speed-to-ship not architectural purity.
+- **Cost & reversibility.** Is the plan paying for a heavy/irreversible thing (a migration, a new public
+  contract, a new dependency, a new service) it doesn't yet need? Prefer the cheap, reversible move now;
+  earn the heavy one with evidence later.
+Do not reward thinness that *violates a rule* (defer to the purist there) — but do challenge any scope,
+sprint, or primitive the outcome doesn't strictly need for v1.
+Remember the **Checkable claim** line is mandatory — name the existing feature/flow/route to *try* that
+would confirm (or kill) your "already achievable / lighter path exists" assumption.
+
+## SYNTHESIS
+You are given two single-pass architecture critiques of the **same plan** — one from the primitives-first
+lens, one from the ship-it pragmatist lens (provided as context). Your only job is to surface where they
+**genuinely contradict** so the product owner has the one thing to adjudicate.
+
+Do **this only**, in a single pass:
+- List ONLY *specific* contradictions — where the two lenses recommend **opposite actions on the same
+  decision** (e.g. one says "extract the shared helper now", the other says "defer it — over-build for v1").
+  For each, give: the decision in one phrase · what the purist wants · what the pragmatist wants · the
+  single question for the product owner to decide.
+- Do **not** summarize the critiques, re-list their individual findings, agreements, or nits. No back-and-
+  forth, no attempt to resolve the disagreement yourself — surface it, don't settle it.
+- If they do **not** contradict on any specific decision, output exactly one line:
+  `Complementary — no direct contradictions; the lenses don't conflict on a specific decision.`
+Be terse. This is advisory only and does not gate anything.

package/dist/doc-format.enforced.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "Which Roadmap docs `node scripts/doc-format.mjs --check` FAILS on (everything else is reported, not enforced). A trailing \"/\" makes a prefix. A new project enforces all of Roadmap/ — nothing predates the groom templates. A project adopting this late lists files as each area is swept.",
+  "enforced": ["Roadmap/"]
+}