great-cto 3.25.0 → 3.26.0

package/board/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "great-cto",
   "description": "You already have the agent. This is everything around it. great_cto runs Claude Code as a pipeline of 70 specialist agents \u2014 an independent model checks each stage before the next builds on it, spending caps refuse rather than warn, and three decisions stay yours: what gets built, how, and whether it ships.",
-  "version": "3.25.0",
+  "version": "3.26.0",
   "author": {
     "name": "Alexander Velikiy",
     "url": "https://hashnode.com/@Greatcto"

package/board/packages/board/lib/routes.mjs

@@ -21,6 +21,9 @@ import { bdCacheInvalidate, checkBeadsAvailable, bdWriteSerialised, bd, bdErr, g
 import { getMetrics } from './metrics.mjs';
 import { readVerdicts } from './verdicts.mjs';
 import { parseAgentBudgets, upsertAgentBudget, removeAgentBudget } from '../../../scripts/lib/agent-budget.mjs';
+import { resolveSecondOpinion, SECOND_OPINION_PROVIDERS } from '../../../scripts/lib/second-opinion.mjs';
+import { detectCodex } from '../../../scripts/lib/codex-exec.mjs';
+import { upsertCapability, capabilitiesFromProjectMd } from '../../../scripts/lib/stack-capabilities.mjs';
 import { getAgentsFleet, getAgentProfile, retireAgent, restoreAgent, appendDecisionLog, readDecisionsLog } from './fleet.mjs';
 import { getResume, getShareState, toggleShare } from './share.mjs';
 import { listSessions, readSession, editedFiles, searchSessions } from './transcripts.mjs';
@@ -1595,6 +1598,123 @@ async function dispatch(req, res, url, cwd) {
 
   // Set or clear one agent's spending cap, by writing PROJECT.md.
   //
+  // GET /api/harnesses — the two harnesses and which one gives the second opinion.
+  //
+  // Claude Code is the host: it runs the pipeline, so it is always "here". Codex
+  // is detected, not assumed — version, login and the model it would run, read
+  // from disk — and reported in three states, because a card that shows an
+  // absent Codex as a quiet toggle in the off position is the same defect as a
+  // pending gate that renders as passed. The evidence section is the tail of
+  // `.great_cto/cross-review.log`: what the second opinion DID, not what it is
+  // set to.
+  if (pathname === '/api/harnesses' && req.method === 'GET') {
+    const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+    const mdPath = path.join(c, '.great_cto', 'PROJECT.md');
+    let projectMd = null;
+    try { projectMd = fs.readFileSync(mdPath, 'utf8'); } catch { projectMd = null; }
+    const codex = detectCodex();
+    const second = resolveSecondOpinion({ projectMd: projectMd ?? '', codex });
+    const declared = projectMd == null ? null : capabilitiesFromProjectMd(projectMd).map.second_opinion;
+
+    // Last 20 review lines, newest first; unparseable lines are counted, not
+    // dropped, so a corrupted log does not read as a quiet one.
+    let evidence = [], unreadable = 0, logState = 'absent';
+    try {
+      const raw = fs.readFileSync(path.join(c, '.great_cto', 'cross-review.log'), 'utf8');
+      logState = 'ok';
+      for (const line of raw.trim().split('\n').filter(Boolean)) {
+        try { evidence.push(JSON.parse(line)); } catch { unreadable += 1; }
+      }
+      evidence = evidence.slice(-20).reverse();
+    } catch (e) { logState = e.code === 'ENOENT' ? 'absent' : 'unreadable'; }
+    const reviewed = evidence.filter((r) => r.state === 'ok');
+    const summary = {
+      runs: evidence.length,
+      reviewed: reviewed.length,
+      skipped: evidence.filter((r) => r.state !== 'ok').length,
+      blocked: reviewed.filter((r) => r.verdict === 'BLOCK').length,
+      unreadable_lines: unreadable,
+    };
+
+    res.writeHead(200, verdictHeaders(c));
+    res.end(JSON.stringify({
+      claude_code: { state: 'host', version: BUILD_VERSION },
+      codex,
+      second_opinion: {
+        ...second,
+        declared: declared ?? { state: projectMd == null ? 'no-project-md' : 'undeclared', tool: null },
+        providers: SECOND_OPINION_PROVIDERS,
+      },
+      evidence: { state: logState, summary, recent: evidence },
+    }));
+    return true;
+  }
+
+  // POST /api/harnesses/second-opinion  { provider: codex|openrouter|none|null }
+  //
+  // Writes `capabilities: second_opinion:` into PROJECT.md — a file the operator
+  // owns and git tracks — from a browser, behind the same origin gate as
+  // /api/agent-budgets. `null` removes the key: back to UNDECLARED, which is a
+  // different state from `none` and is offered on purpose.
+  //
+  // The reply carries the previous value, and the resolved state AFTER the
+  // write: choosing codex on a machine without one succeeds as a declaration
+  // and comes back `unavailable`, so the card can say so at the moment of the
+  // click rather than on the next review.
+  if (pathname === '/api/harnesses/second-opinion' && req.method === 'POST') {
+    if (!originAllowed(req)) {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'origin not allowed' }));
+      return true;
+    }
+    let body = '';
+    req.on('data', (ch) => { body += ch; if (body.length > 1024) req.destroy(); });
+    req.on('end', () => {
+      let parsed;
+      try { parsed = JSON.parse(body || '{}'); }
+      catch (e) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'invalid_json', message: String(e.message || e) }));
+        return;
+      }
+      const provider = parsed.provider == null ? null : String(parsed.provider).toLowerCase();
+      if (provider != null && !SECOND_OPINION_PROVIDERS.includes(provider)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `provider must be one of ${SECOND_OPINION_PROVIDERS.join(', ')}, or null to undeclare` }));
+        return;
+      }
+      const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+      const mdPath = path.join(c, '.great_cto', 'PROJECT.md');
+      let before;
+      try { before = fs.readFileSync(mdPath, 'utf8'); }
+      catch (e) {
+        res.writeHead(409, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'no PROJECT.md to write to', detail: String(e.message || e) }));
+        return;
+      }
+      let out;
+      try { out = upsertCapability(before, 'second_opinion', provider); }
+      catch (e) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: String(e.message || e) }));
+        return;
+      }
+      try {
+        const tmp = `${mdPath}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, out.text);
+        fs.renameSync(tmp, mdPath);
+      } catch (e) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `could not write PROJECT.md: ${String(e.message || e)}` }));
+        return;
+      }
+      const resolved = resolveSecondOpinion({ projectMd: out.text, codex: detectCodex() });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, provider, previous: out.previous, created_block: out.created === true, resolved }));
+    });
+    return true;
+  }
+
   // POST /api/agent-budgets  { agent, limit_usd }   set / replace
   // POST /api/agent-budgets  { agent, remove: true } clear
   //

package/board/packages/board/public/index.html

@@ -1419,6 +1419,20 @@ h1, h2, h3, h4 { font-weight: 600; font-family: var(--sans); }
 }
 
 /* ── change_tier badge ────────────────────────────────────────────────────── */
+  /* `.warn` was used by the Harnesses card before it existed: five spans that
+     said "declared but unavailable" and rendered as ordinary prose. A warning
+     that does not look like a warning is this repository's own defect class,
+     and the css-tokens guard could not see it — it checks var() tokens, not
+     class names. Declared here, and asserted by the harnesses UI test. */
+  .warn { color: var(--status-blocked); }
+  /* `.muted` is used 68 times across this board and was declared nowhere, so
+     every de-emphasised line rendered at full weight — found by the guard added
+     for the Harnesses card, not by the eye. One declaration, the same token the
+     rest of the board de-emphasises with. */
+  .muted { color: var(--text3); }
+  /* Same shape as `.muted`: the `--mono` token exists and is used 115×, the
+     CLASS that applies it did not. */
+  .mono { font-family: var(--mono); }
 .tier-badge { font-size: var(--fs-caption); padding: 1px 8px; border-radius: 999px; margin-left: 6px;
   font-family: var(--mono); white-space: nowrap; }
 .tier-badge:empty { display: none; }
@@ -3174,9 +3188,24 @@ id var(--border);
             <h3>Active pipeline</h3>
             <span class="inbox-count" id="pipeline-status">idle</span>
             <span class="tier-badge" id="tier-badge" title="change_tier for the current working-tree diff — which gates + judge open (ADR-003/004)"></span>
+            <span class="tier-badge" id="harness-badge" title="which harness gives the second opinion in review — from capabilities: second_opinion in PROJECT.md"></span>
           </div>
           <div class="pipeline-track" id="pipeline-track"></div>
         </div>
+
+        <!-- Harnesses: the host that runs the pipeline, and the second harness
+             that reviews beside it. Codex is DETECTED, in three states — an
+             absent Codex must not render as a switch in the off position. The
+             evidence rows are the tail of .great_cto/cross-review.log: what the
+             second opinion did, not what it is set to. -->
+        <div class="inbox-section" id="harnesses-section">
+          <div class="inbox-section-head">
+            <span class="dot dot-blue"></span>
+            <h3>Harnesses</h3>
+            <span class="inbox-count" id="harnesses-status">…</span>
+          </div>
+          <div id="harnesses-body" class="muted" style="font-size:13px;line-height:1.5">loading…</div>
+        </div>
           </div>
         </details>
 
@@ -5106,9 +5135,95 @@ async function refreshPipeline() {
   const d = await api(`/api/pipeline${pqs()}`);
   if (Array.isArray(d)) renderPipeline(d);
   renderTierBadge();
+  renderHarnesses();
 }
 
 // change_tier badge — the gate + judge plan for the current working-tree diff (ADR-003/004).
+// The Harnesses card. Four states for the second opinion, and the fourth is
+// the reason the card exists: `unavailable` — declared codex, no codex here —
+// must never look like `none` or like a switch someone turned off.
+async function renderHarnesses() {
+  const body = document.getElementById('harnesses-body');
+  const status = document.getElementById('harnesses-status');
+  if (!body) return;
+  let h;
+  try { h = await api(`/api/harnesses${pqs()}`); }
+  catch (e) { status.textContent = 'unreadable'; body.innerHTML = `<b>Could not read the harnesses.</b> ${esc(String(e.message || e))}`; return; }
+
+  const so = h.second_opinion || {};
+  const cx = h.codex || {};
+  const ev = h.evidence || {};
+  const sum = ev.summary || {};
+
+  const codexLine = cx.state === 'available'
+    ? `<b>OpenAI Codex</b> ${esc(cx.version || '')} · logged in (${esc(cx.auth || '?')}) · runs <code>${esc(cx.model || 'default model')}</code>`
+    : cx.state === 'no-auth'
+      ? `<b>OpenAI Codex</b> ${esc(cx.version || '')} · <span class="warn">not logged in</span> — ${esc(cx.why || '')}`
+      : `<b>OpenAI Codex</b> · <span class="warn">not installed</span> — ${esc(cx.why || '')}`;
+
+  const stateLabel = {
+    declared: `on — <b>${esc(so.provider)}</b> reviews in parallel with the Claude reviewer`,
+    none: 'off — the project decided: one model family only',
+    undeclared: 'not declared — <b>not</b> the same as off; nobody has said',
+    unavailable: `<span class="warn">declared <b>${esc(so.provider)}</b>, but unavailable here</span> — ${esc(so.why || '')}`,
+  }[so.state] || esc(so.state || '?');
+
+  const sel = (so.providers || ['codex', 'openrouter', 'none']).map((p) =>
+    `<option value="${p}" ${so.declared && so.declared.tool === p ? 'selected' : ''}>${p}</option>`).join('');
+  const undecl = `<option value="" ${!so.declared || so.declared.state === 'undeclared' ? 'selected' : ''}>(undeclared)</option>`;
+
+  const rows = (ev.recent || []).slice(0, 6).map((r) => {
+    const when = (r.ts || '').slice(0, 16).replace('T', ' ');
+    const what = r.state === 'ok'
+      ? `${r.verdict === 'BLOCK' ? '<b>BLOCK</b>' : 'PASS'} · ${r.findings ?? 0} finding${r.findings === 1 ? '' : 's'}${r.p0 ? ` · ${r.p0} P0` : ''}${r.cost != null ? ` · $${r.cost}` : ' · unpriced'}`
+      : `<span class="muted">skipped (${esc(r.state)})</span>`;
+    return `<div class="mono" style="font-size:12px">${esc(when)} · ${esc(r.provider || '?')}${r.model ? ':' + esc(r.model) : ''} · ${what}</div>`;
+  }).join('');
+  const evidence = ev.state === 'absent'
+    ? '<span class="muted">no cross-model review has run in this project yet</span>'
+    : ev.state === 'unreadable'
+      ? '<span class="warn">the review log is unreadable</span>'
+      : `${sum.reviewed ?? 0} reviewed · ${sum.skipped ?? 0} skipped · ${sum.blocked ?? 0} blocked${sum.unreadable_lines ? ` · <span class="warn">${sum.unreadable_lines} unreadable line(s)</span>` : ''}<div style="margin-top:4px">${rows}</div>`;
+
+  status.textContent = so.state === 'declared' ? `2 · ${so.provider}` : so.state === 'unavailable' ? 'unavailable' : so.state === 'undeclared' ? 'undeclared' : '1';
+  status.className = 'inbox-count' + (so.state === 'unavailable' ? ' warn' : '');
+  // The header badge: two harnesses when a second one actually reviews.
+  // `unavailable` is shown as such — a declared-but-absent Codex in the header
+  // reading "2 harnesses" would be the pending-gate-as-passed defect in a badge.
+  const hb = document.getElementById('harness-badge');
+  if (hb) {
+    hb.textContent = so.state === 'declared' ? `2 harnesses · ${so.provider}`
+      : so.state === 'unavailable' ? `${so.provider} unavailable` : '';
+    hb.className = 'tier-badge';
+    hb.style.color = so.state === 'unavailable' ? 'var(--status-blocked)' : '';
+    hb.style.display = hb.textContent ? '' : 'none';
+  }
+  body.innerHTML = `
+    <div><b>Claude Code</b> · host · runs the pipeline, gates and hooks</div>
+    <div>${codexLine}</div>
+    <div style="margin-top:8px">Second opinion: ${stateLabel}</div>
+    <div style="margin-top:6px;display:flex;gap:8px;align-items:center;flex-wrap:wrap">
+      <label for="so-select" class="muted">set</label>
+      <select id="so-select">${undecl}${sel}</select>
+      <button id="so-apply" class="btn-ghost-sm">apply</button>
+      <span id="so-result" class="muted"></span>
+    </div>
+    <div style="margin-top:8px"><span class="muted">Evidence:</span> ${evidence}</div>`;
+
+  document.getElementById('so-apply').onclick = async () => {
+    const v = document.getElementById('so-select').value;
+    const out = document.getElementById('so-result');
+    out.textContent = 'writing PROJECT.md…';
+    try {
+      const r = await api(`/api/harnesses/second-opinion${pqs()}`, { method: 'POST', body: JSON.stringify({ provider: v || null }) });
+      // Say what it replaced and what it resolved to NOW, so choosing codex on a
+      // machine without one is answered at the click, not on the next review.
+      out.textContent = `was ${r.previous ?? 'undeclared'} → now ${r.provider ?? 'undeclared'} (${r.resolved?.state}${r.resolved?.why ? ': ' + r.resolved.why : ''})`;
+      renderHarnesses();
+    } catch (e) { out.textContent = `failed: ${String(e.message || e)}`; }
+  };
+}
+
 async function renderTierBadge() {
   const el = document.getElementById('tier-badge');
   if (!el) return;

package/board/scripts/lib/codex-exec.mjs

@@ -0,0 +1,167 @@
+/**
+ * codex-exec — the Codex CLI as a subprocess, and whether one is here to run.
+ *
+ * Moved out of tests/eval/arm-codex.mjs the day Codex became a participant in
+ * the pipeline rather than a thing the evals compare against. The parser and
+ * runner are unchanged in behaviour; what is new is `detectCodex`, because a
+ * second opinion that is silently absent reads exactly like a second opinion
+ * that agreed.
+ *
+ * Three things a caller must be able to tell apart, and none may look like PASS:
+ *   absent      no `codex` on PATH
+ *   no-auth     a binary and no login — `codex exec` returns 400 on every model
+ *   available   version, auth mode and the model it will run, read from disk
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * `codex exec --json` output → the answer, its cost, and what went wrong.
+ *
+ * Four states, and the last three are why this is not a one-liner:
+ *
+ *   ok          an agent message was produced
+ *   empty       the stream parsed and carried no agent message
+ *   unreadable  nothing in the stream parsed at all
+ *   (errors)    non-fatal problems Codex reported mid-run, always surfaced
+ *
+ * `empty` returns `text: null`, never `""`. An empty answer graded as an answer
+ * scores like a real one. `usage` is null when the turn did not report it — a
+ * cost comparison that reads a missing measurement as zero makes one harness
+ * look free.
+ */
+export function parseCodexStream(raw) {
+  const messages = [];
+  const errors = [];
+  let usage = null;
+  let parsedAny = false;
+
+  for (const line of String(raw ?? '').split('\n')) {
+    const s = line.trim();
+    // The CLI interleaves human-readable lines with the JSON stream, so a line
+    // that does not parse is noise to step over, not a failure.
+    if (!s.startsWith('{')) continue;
+    let ev;
+    try { ev = JSON.parse(s); } catch { continue; }
+    parsedAny = true;
+
+    if (ev.type === 'turn.completed' && ev.usage) usage = ev.usage;
+    const item = ev.item;
+    if (!item) continue;
+    if (item.type === 'agent_message' && typeof item.text === 'string') messages.push(item.text);
+    // Codex reports recoverable problems as error items: a rejected plugin
+    // config, a truncated skill budget. A verdict built over a degraded run is
+    // a verdict about the wrong thing, so these always reach the caller.
+    else if (item.type === 'error' && item.message) errors.push(String(item.message));
+  }
+
+  if (!parsedAny) return { state: 'unreadable', text: null, usage: null, errors };
+  if (!messages.length) return { state: 'empty', text: null, usage, errors };
+  return { state: 'ok', text: messages.join('\n'), usage, errors };
+}
+
+/**
+ * Run one prompt through the Codex CLI and parse the result.
+ *
+ * The prompt goes on stdin: passing it as an argument alongside `-c` overrides
+ * made the CLI wait on stdin instead, which looks exactly like a hung model.
+ *
+ * `sandbox` defaults to read-only: a reviewer that can write is not a reviewer.
+ * `ephemeral` keeps the review out of the user's Codex session history.
+ *
+ * @returns the shape of `parseCodexStream`, plus `{ code, model }`
+ */
+export function runCodexExec({
+  prompt, cwd, timeoutMs = 300000, bin = 'codex', model = null,
+  sandbox = 'read-only', ephemeral = true, extraArgs = [],
+}) {
+  return new Promise((resolve) => {
+    const args = ['exec', '--json', '--skip-git-repo-check'];
+    if (sandbox) args.push('-s', sandbox);
+    if (ephemeral) args.push('--ephemeral');
+    if (model) args.push('-m', model);
+    if (cwd) args.push('-C', cwd);
+    args.push(...extraArgs, '-');
+
+    const proc = spawn(bin, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env } });
+    let out = '';
+    let err = '';
+    const timer = setTimeout(() => { try { proc.kill('SIGKILL'); } catch { /* gone */ } }, timeoutMs);
+
+    proc.stdout.on('data', (b) => { out += String(b); });
+    proc.stderr.on('data', (b) => { err += String(b); });
+    proc.on('error', (e) => {
+      clearTimeout(timer);
+      resolve({ state: 'unreadable', text: null, usage: null, errors: [String(e.message || e)], code: null, model });
+    });
+    proc.on('close', (code) => {
+      clearTimeout(timer);
+      const parsed = parseCodexStream(out);
+      // stderr is kept even on success: Codex writes warnings there that change
+      // how a result should be read.
+      if (err.trim()) parsed.errors.push(err.trim().slice(0, 500));
+      resolve({ ...parsed, code, model });
+    });
+
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+  });
+}
+
+/** Kept under the old name for the eval arm. */
+export const runCodexArm = (opts) => runCodexExec({ ...opts, sandbox: opts.sandbox ?? null, ephemeral: opts.ephemeral ?? false });
+
+/**
+ * What a Codex install on this machine is, from three readings — pure, so the
+ * three states can be tested without a Codex.
+ *
+ * @param {{versionOut:string|null, authJson:string|null, configToml:string|null}} r
+ *   `null` for a reading that could not be taken (binary absent, file missing).
+ * @returns {{state:'absent'|'no-auth'|'available', version:string|null,
+ *            auth:string|null, model:string|null, why:string}}
+ */
+export function codexStatusFrom({ versionOut, authJson, configToml }) {
+  if (versionOut == null) {
+    return { state: 'absent', version: null, auth: null, model: null, why: 'codex is not on PATH — npm i -g @openai/codex' };
+  }
+  const version = (String(versionOut).match(/(\d+\.\d+\.\d+)/) || [])[1] ?? null;
+
+  let auth = null;
+  if (authJson != null) {
+    try { auth = JSON.parse(authJson)?.auth_mode ?? (JSON.parse(authJson)?.tokens ? 'chatgpt' : null); }
+    catch { auth = null; }
+  }
+  // config.toml may name the model on its own line; a `[profiles.x]` table
+  // below can name others, so only the first top-level `model =` counts.
+  let model = null;
+  if (configToml != null) {
+    const top = String(configToml).split(/^\[/m)[0];
+    model = (top.match(/^\s*model\s*=\s*"([^"]+)"/m) || [])[1] ?? null;
+  }
+
+  if (!auth) {
+    return { state: 'no-auth', version, auth: null, model, why: 'codex is installed but not logged in — run `codex login`' };
+  }
+  return { state: 'available', version, auth, model, why: '' };
+}
+
+/** The three readings, taken. */
+// `GREAT_CTO_CODEX_BIN` is the one lever for all three consumers — reviewer,
+// verifier, board — so a test (or an operator with two Codex installs) points
+// them at the same binary, and so an absent Codex can be simulated without
+// stripping PATH of the node that runs the server.
+export function detectCodex({ bin = process.env.GREAT_CTO_CODEX_BIN || 'codex', home = homedir() } = {}) {
+  let versionOut = null;
+  try {
+    const r = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 5000 });
+    if (r.status === 0) versionOut = String(r.stdout || r.stderr || '');
+  } catch { /* absent */ }
+  const read = (p) => { try { return existsSync(p) ? readFileSync(p, 'utf8') : null; } catch { return null; } };
+  return codexStatusFrom({
+    versionOut,
+    authJson: read(join(home, '.codex', 'auth.json')),
+    configToml: read(join(home, '.codex', 'config.toml')),
+  });
+}

package/board/scripts/lib/dag-metric.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * dag-metric — score a judgement by walking a graph of narrow questions, instead
+ * of asking a model for a number.
+ *
+ * Why this exists
+ * ---------------
+ * Our eval judge returns a rate per scenario, and the recorded history says what
+ * that costs: 14 of 18 results below their own threshold, one eval at 0.44
+ * against a 1.00 bar, and the runner's own header notes ±0.09 of variance that
+ * more samples do not remove. That variance is inherent to asking "score this
+ * 0–1" — the number is sampled from a distribution, not derived from anything.
+ *
+ * The idea is DeepEval's, and it is the one thing worth taking from it: reduce
+ * the model's job to questions it can answer the same way twice ("does this
+ * finding cite a file:line?"), and COMPUTE the score from the path those answers
+ * take. The model still judges; it no longer does arithmetic.
+ *
+ * Two properties follow, and both matter more than the score:
+ *   - the same answers always give the same score
+ *   - the verdict is a path you can print, so a disagreement is about a specific
+ *     question rather than about a number nobody can locate
+ *
+ * Shape (plain JSON, so a DAG is data an agent can write):
+ *   { root, nodes: { id: { question, edges: { <answer>: <nextId> } } },
+ *     leaves: { id: { score: 0..1, reason } } }
+ *
+ * CLI:
+ *   node scripts/lib/dag-metric.mjs <dag.json> --answers '{"n1":"yes"}'
+ *   node scripts/lib/dag-metric.mjs <dag.json> --validate
+ *   node scripts/lib/dag-metric.mjs <dag.json> --next --answers '{...}'
+ */
+
+import { createHash } from 'node:crypto';
+
+const isLeafScore = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+
+/**
+ * A 12-hex-char fingerprint over the DAG's scoring structure — `root`, each
+ * node's `question` and `edges`, each leaf's `score` — with every level's keys
+ * sorted so key order in the source file cannot move the hash.
+ *
+ * Deliberately excludes `note` (top-level) and each leaf's `reason`: those are
+ * documentation, not the metric. Two runs scored by the same questions and the
+ * same edges must fingerprint identically even if someone rewrote a comment —
+ * and two runs whose questions or edges differ must not, because that is
+ * exactly the case (ARCH-judge-provenance §1/§3) that makes their rates
+ * incomparable.
+ */
+export function dagFingerprint(dag) {
+  const sortKeys = (o) => Object.fromEntries(Object.entries(o || {}).sort(([a], [b]) => (a < b ? -1 : 1)));
+  const scoring = {
+    root: dag && dag.root,
+    nodes: sortKeys(Object.fromEntries(Object.entries((dag && dag.nodes) || {})
+      // `n?.` rather than `n.`: a null entry inside `nodes` threw where an
+      // absent `nodes` did not, so the function was safe against the malformed
+      // shapes anyone thought to try and unsafe against one nobody did. This
+      // runs inside an eval that has already been paid for.
+      .map(([id, n]) => [id, { question: n?.question, edges: sortKeys(n?.edges) }]))),
+    leaves: sortKeys(Object.fromEntries(Object.entries((dag && dag.leaves) || {})
+      .map(([id, l]) => [id, { score: l?.score }]))),
+  };
+  return createHash('sha256').update(JSON.stringify(scoring)).digest('hex').slice(0, 12);
+}
+
+/**
+ * Check the graph before anyone judges anything: a lost branch or a cycle is a
+ * bug in the metric, and finding it mid-run means a wasted judging pass.
+ *
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateDag(dag) {
+  const errors = [];
+  const warnings = [];
+  const nodes = (dag && dag.nodes) || {};
+  const leaves = (dag && dag.leaves) || {};
+  const root = dag && dag.root;
+
+  if (!root) errors.push('no `root`');
+  if (!Object.keys(nodes).length) errors.push('no `nodes`');
+  if (!Object.keys(leaves).length) errors.push('no `leaves`');
+  if (root && !nodes[root] && !leaves[root]) errors.push(`root '${root}' is neither a node nor a leaf`);
+
+  for (const [id, leaf] of Object.entries(leaves)) {
+    if (!leaf || !('score' in leaf)) { errors.push(`leaf '${id}' has no score`); continue; }
+    if (!isLeafScore(leaf.score)) errors.push(`leaf '${id}' score must be a number in 0..1`);
+  }
+
+  for (const [id, node] of Object.entries(nodes)) {
+    if (!node || !node.question) errors.push(`node '${id}' has no question`);
+    const edges = (node && node.edges) || {};
+    if (!Object.keys(edges).length) errors.push(`node '${id}' has no edges`);
+    for (const [answer, target] of Object.entries(edges)) {
+      if (!nodes[target] && !leaves[target]) {
+        errors.push(`node '${id}' edge '${answer}' points at '${target}', which does not exist`);
+      }
+    }
+  }
+
+  // Cycles: a question graph that loops can never reach a score.
+  const state = new Map();                       // id → 'open' | 'done'
+  const walk = (id, trail) => {
+    if (leaves[id]) return;
+    if (state.get(id) === 'open') { errors.push(`cycle: ${[...trail, id].join(' → ')}`); return; }
+    if (state.get(id) === 'done' || !nodes[id]) return;
+    state.set(id, 'open');
+    for (const target of Object.values(nodes[id].edges || {})) walk(target, [...trail, id]);
+    state.set(id, 'done');
+  };
+  if (root) walk(root, []);
+
+  // Reachability: an orphaned leaf usually means a branch was dropped in an edit.
+  const seen = new Set();
+  const reach = (id) => {
+    if (!id || seen.has(id)) return;
+    seen.add(id);
+    for (const target of Object.values((nodes[id] || {}).edges || {})) reach(target);
+  };
+  if (root && !errors.some((e) => e.startsWith('cycle'))) reach(root);
+  for (const id of Object.keys(leaves)) if (!seen.has(id)) warnings.push(`leaf '${id}' is unreachable`);
+  for (const id of Object.keys(nodes)) if (!seen.has(id)) warnings.push(`node '${id}' is unreachable`);
+
+  return { errors, warnings };
+}
+
+/**
+ * Walk the graph with the answers given.
+ *
+ * A missing answer returns `score: null` and names the question. It never
+ * defaults, because a default is exactly the invented number this module exists
+ * to remove.
+ */
+export function evaluateDag(dag, answers = {}) {
+  const { errors } = validateDag(dag);
+  if (errors.length) return { score: null, path: [], leaf: null, error: errors[0] };
+
+  const { nodes, leaves, root } = dag;
+  const path = [];
+  const steps = [];                              // {id, question, answer} — the audit trail
+  let id = root;
+  const guard = Object.keys(nodes).length + 1;   // validation rules out cycles; this is belt
+
+  for (let step = 0; step <= guard; step++) {
+    if (leaves[id]) {
+      path.push(id);
+      return { score: leaves[id].score, leaf: id, reason: leaves[id].reason || '', path, steps };
+    }
+    const node = nodes[id];
+    path.push(id);
+    if (!(id in answers)) {
+      return { score: null, path, leaf: null, steps, pending: id, question: node.question };
+    }
+    const answer = answers[id];
+    const next = node.edges[answer];
+    if (!next) {
+      return {
+        score: null, path, leaf: null, steps,
+        error: `node '${id}' has no edge for answer '${answer}' (expected: ${Object.keys(node.edges).join(', ')})`,
+      };
+    }
+    steps.push({ id, question: node.question, answer });
+    id = next;
+  }
+  return { score: null, path, leaf: null, steps, error: 'walk did not terminate' };
+}
+
+/** The next question to put to a judge, with the answers it may give. */
+export function pendingQuestion(dag, answers = {}) {
+  const r = evaluateDag(dag, answers);
+  if (!r.pending) return null;
+  return { id: r.pending, question: r.question, answers: Object.keys(dag.nodes[r.pending].edges) };
+}
+
+/** The verdict a human reads: every question, its answer, and where the score came from. */
+export function explain(result, dag) {
+  if (!result) return 'no result';
+  if (result.error) return `unscored — ${result.error}`;
+
+  const lines = (result.steps || []).map((s) => `  ${s.question}\n    ${s.answer}`);
+
+  if (result.score === null) {
+    const q = result.question ? `\n  ${result.question}\n    (unanswered)` : '';
+    return [`unscored — pending question: ${result.pending || 'unknown'}`, ...lines].join('\n') + q;
+  }
+  if (result.leaf) lines.push(`  → ${result.reason || result.leaf}`);
+  return [`score: ${result.score}`, ...lines].join('\n');
+}
+
+/**
+ * The prompt for one node. The judge is given the allowed answers and told to
+ * reply with nothing else — the whole point of the graph is that its job is a
+ * choice from a closed set, not a number it has to invent.
+ */
+export function questionPrompt(question, allowed, context = {}) {
+  const list = allowed.join(' or ');
+  const system =
+    'You are grading one narrow factual question about an agent response. ' +
+    `Answer with exactly one word: ${list}. ` +
+    'No explanation, no punctuation, no hedging. If the response genuinely does not ' +
+    `settle the question, answer with the option that assumes the agent did NOT do it (${allowed[allowed.length - 1]}).`;
+  const user = [
+    context.scenario ? `Scenario: ${context.scenario}` : '',
+    context.test ? `Test case: ${context.test}` : '',
+    context.expected ? `Expected behaviour: ${context.expected}` : '',
+    context.actorResponse ? `Agent response:\n${context.actorResponse}` : '',
+    '',
+    `Question: ${question}`,
+    `Answer (${list}):`,
+  ].filter(Boolean).join('\n\n');
+  return { system, user };
+}
+
+/**
+ * Map a judge reply onto one of the allowed answers, or null.
+ *
+ * Null matters: an unparseable reply must stop the walk rather than pick a side,
+ * because a guessed answer is a guessed score wearing a decision tree.
+ */
+export function parseAnswer(reply, allowed) {
+  const t = String(reply ?? '').trim().toLowerCase();
+  if (!t) return null;
+  // Ambiguity is checked BEFORE any shortcut: a reply that echoes the option
+  // list ("yes or no") starts with a valid answer, and taking the first token
+  // would turn the judge's non-answer into a decision.
+  // Delimit by "not a word character" on either side rather than \b: a label is
+  // whatever the graph author wrote, and \b needs a word character to sit against,
+  // so `yes(1)` or `p0.` could never match their own exact reply.
+  const hits = allowed.filter((a) => {
+    const esc = a.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[^\\w-])${esc}([^\\w-]|$)`).test(t);
+  });
+  return hits.length === 1 ? hits[0] : null;
+}
+
+/**
+ * Score one case by walking the graph, asking `ask(question, allowed)` for each
+ * node on the path. `ask` returns a string reply; anything unparseable ends the
+ * walk unscored rather than guessing.
+ *
+ * Kept here rather than in the runner so it is testable with a stub `ask`.
+ */
+export async function judgeWithDag(dag, ask, context = {}) {
+  const answers = {};
+  const asked = [];
+  for (let i = 0; i <= Object.keys(dag.nodes || {}).length; i++) {
+    const q = pendingQuestion(dag, answers);
+    if (!q) break;
+    const reply = await ask(q.question, q.answers, context);
+    const answer = parseAnswer(reply, q.answers);
+    asked.push({ id: q.id, question: q.question, reply, answer });
+    if (answer === null) {
+      return { score: null, answers, asked, error: `judge gave no usable answer for '${q.id}': ${String(reply).slice(0, 60)}` };
+    }
+    answers[q.id] = answer;
+  }
+  return { ...evaluateDag(dag, answers), answers, asked };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+async function main(argv) {
+  const { readFileSync } = await import('node:fs');
+  const file = argv.find((a) => !a.startsWith('--'));
+  if (!file) {
+    console.error('usage: dag-metric.mjs <dag.json> [--validate] [--next] [--answers \'{"id":"yes"}\']');
+    return 2;
+  }
+  let dag;
+  try { dag = JSON.parse(readFileSync(file, 'utf8')); }
+  catch (e) { console.error(`cannot read ${file}: ${e.message}`); return 2; }
+
+  const i = argv.indexOf('--answers');
+  let answers = {};
+  if (i >= 0) {
+    try { answers = JSON.parse(argv[i + 1]); }
+    catch { console.error('--answers must be JSON'); return 2; }
+  }
+
+  const { errors, warnings } = validateDag(dag);
+  for (const w of warnings) console.error(`warn: ${w}`);
+  if (errors.length) { for (const e of errors) console.error(`error: ${e}`); return 1; }
+  if (argv.includes('--validate')) { console.log(`ok: ${Object.keys(dag.nodes).length} nodes, ${Object.keys(dag.leaves).length} leaves`); return 0; }
+
+  if (argv.includes('--next')) {
+    const q = pendingQuestion(dag, answers);
+    console.log(q ? JSON.stringify(q, null, 2) : 'null');
+    return 0;
+  }
+
+  const result = evaluateDag(dag, answers);
+  console.log(explain(result, dag));
+  return result.score === null ? 1 : 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2)).then((c) => { process.exitCode = c; });
+}

package/board/scripts/lib/second-opinion.mjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+/**
+ * second-opinion — two judges, one graph, and only the disagreement is a signal.
+ *
+ * Why this exists
+ * ---------------
+ * `mcp__great_cto_llm_router__ask_kimi` has been in the `tools:` list of
+ * nineteen agents and invoked by none of them. The capability was declared and
+ * never exercised — the same shape as the deny list that ran on every write and
+ * protected nothing.
+ *
+ * The obvious use, a second model reviewing the first one's report, is the wrong
+ * one. A reviewer reading a report judges whether it reads plausibly, and a
+ * confident wrong finding is exactly what passes that test. Worse, two models
+ * agreeing is weak evidence: they are trained on overlapping data and fail in
+ * correlated ways. "Both said yes" is close to no information.
+ *
+ * What carries information is where they DIVERGE. So this does not ask two
+ * models to grade prose. It walks both through the same DAG of closed questions
+ * (scripts/lib/dag-metric.mjs) and reports the nodes where their answers differ.
+ * A divergence names a specific question — "does this finding cite a file:line?"
+ * — which is something a human can settle in seconds, unlike "is this report
+ * good?".
+ *
+ * The reporting rule is deliberate and the opposite of the usual one:
+ *
+ *   - agreement is NOT reported as confidence. It is reported as "nothing to
+ *     look at here", which is a weaker claim and the honest one.
+ *   - divergence IS the output. It is where to dig.
+ *   - one judge abstaining is neither. An unparseable answer is a third state,
+ *     not a vote, and calling it agreement would let a broken judge confirm
+ *     anything.
+ */
+
+import { pendingQuestion, evaluateDag, parseAnswer } from './dag-metric.mjs';
+
+export const DIVERGENCE = Object.freeze({
+  AGREE: 'agree',
+  DIVERGE: 'diverge',
+  ABSTAINED: 'abstained',
+});
+
+/**
+ * Walk one judge through the graph, collecting its answer at every node it
+ * reaches. Unlike judgeWithDag this does not stop at the first unusable reply —
+ * an abstention on one node still leaves the others worth comparing.
+ *
+ * @param {object} dag
+ * @param {(q:string, allowed:string[], ctx:object)=>Promise<string>} ask
+ * @returns {Promise<{answers: object, asked: Array, result: object}>}
+ */
+export async function walk(dag, ask, context = {}) {
+  const answers = {};
+  const asked = [];
+  const limit = Object.keys(dag.nodes || {}).length + 1;
+  for (let i = 0; i <= limit; i++) {
+    const q = pendingQuestion(dag, answers);
+    if (!q) break;
+    const reply = await ask(q.question, q.answers, context);
+    const answer = parseAnswer(reply, q.answers);
+    asked.push({ id: q.id, question: q.question, reply, answer });
+    // A node nobody could answer ends this judge's walk — the graph cannot
+    // continue without it — but what was already answered still compares.
+    if (answer === null) break;
+    answers[q.id] = answer;
+  }
+  return { answers, asked, result: evaluateDag(dag, answers) };
+}
+
+/**
+ * Compare two walks.
+ *
+ * @returns {{
+ *   diverged: Array<{id, question, a, b}>,
+ *   abstained: Array<{id, question, by: 'a'|'b'|'both'}>,
+ *   agreed: string[],
+ *   scores: {a: number|null, b: number|null},
+ *   verdict: 'agree'|'diverge'|'abstained',
+ *   summary: string,
+ * }}
+ */
+export function compare(walkA, walkB) {
+  const byId = (w) => new Map(w.asked.map((s) => [s.id, s]));
+  const A = byId(walkA);
+  const B = byId(walkB);
+
+  const diverged = [];
+  const abstained = [];
+  const agreed = [];
+
+  for (const id of new Set([...A.keys(), ...B.keys()])) {
+    const a = A.get(id);
+    const b = B.get(id);
+    // A node only one judge reached is not a disagreement — the walks parted
+    // earlier, and the node that parted them is already recorded.
+    if (!a || !b) continue;
+    if (a.answer === null || b.answer === null) {
+      abstained.push({
+        id, question: a.question,
+        by: a.answer === null && b.answer === null ? 'both' : (a.answer === null ? 'a' : 'b'),
+      });
+      continue;
+    }
+    if (a.answer !== b.answer) diverged.push({ id, question: a.question, a: a.answer, b: b.answer });
+    else agreed.push(id);
+  }
+
+  const scores = { a: walkA.result?.score ?? null, b: walkB.result?.score ?? null };
+
+  let verdict = DIVERGENCE.AGREE;
+  if (diverged.length) verdict = DIVERGENCE.DIVERGE;
+  else if (abstained.length) verdict = DIVERGENCE.ABSTAINED;
+
+  // The wording matters. Agreement is not evidence of correctness — two models
+  // trained on overlapping data fail together — so it is reported as an absence
+  // of signal, never as confidence.
+  const summary = diverged.length
+    ? `${diverged.length} question(s) answered differently — that is where to look`
+    : abstained.length
+      ? `${abstained.length} question(s) one judge could not answer — no comparison possible there`
+      : `no divergence across ${agreed.length} question(s); this is weak evidence, not confirmation`;
+
+  return { diverged, abstained, agreed, scores, verdict, summary };
+}
+
+/**
+ * Run both judges over the same graph and compare.
+ *
+ * The two `ask` functions must be independent — a second opinion that saw the
+ * first one's answer is not a second opinion.
+ */
+export async function secondOpinion(dag, askA, askB, context = {}) {
+  const [a, b] = await Promise.all([walk(dag, askA, context), walk(dag, askB, context)]);
+  return { ...compare(a, b), walks: { a, b } };
+}
+
+/** Human-readable report. Divergence first — it is the only actionable part. */
+export function explainComparison(cmp) {
+  const lines = [cmp.summary];
+  for (const d of cmp.diverged) {
+    lines.push('', `  ${d.question}`, `    judge A: ${d.a}`, `    judge B: ${d.b}`);
+  }
+  for (const s of cmp.abstained) {
+    lines.push('', `  ${s.question}`, `    unanswered by: ${s.by}`);
+  }
+  if (cmp.scores.a !== cmp.scores.b) {
+    lines.push('', `  scores differ: ${cmp.scores.a} vs ${cmp.scores.b}`);
+  }
+  return lines.join('\n');
+}
+
+// ── the second judge ────────────────────────────────────────────────────────
+
+/**
+ * An `ask` backed by the llm-router MCP server (Kimi by default).
+ *
+ * Spawned per question on purpose: the server is stdio JSON-RPC and a fresh
+ * process per question guarantees the second judge cannot see its own earlier
+ * answers accumulate into a context that biases the next one. It is slower and
+ * that is the correct trade for an independence claim.
+ */
+export function routerAsk(serverPath, { timeoutMs = 60_000, model = null } = {}) {
+  return async (question, allowed) => {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve) => {
+      // The model is passed through the spawned server's environment, which is
+      // where it reads it from. Without this every "second opinion" was the same
+      // model answering twice — three samples of one judge are correlated, and
+      // calling that a second opinion is the confidence-by-repetition this
+      // module was written to avoid.
+      const env = model ? { ...process.env, GREAT_CTO_ROUTER_MODEL: model } : process.env;
+      const p = spawn('python3', [serverPath], { stdio: ['pipe', 'pipe', 'ignore'], env });
+      let out = '';
+      const done = (v) => { try { p.kill(); } catch {} resolve(v); };
+      const timer = setTimeout(() => done(''), timeoutMs);
+      p.stdout.on('data', (d) => { out += d; });
+      p.on('error', () => { clearTimeout(timer); done(''); });
+      p.on('close', () => {
+        clearTimeout(timer);
+        for (const line of out.split('\n')) {
+          if (!line.trim().startsWith('{')) continue;
+          try {
+            const d = JSON.parse(line);
+            if (d.id === 2 && d.result && d.result.content) return done(d.result.content[0].text);
+          } catch { /* not our line */ }
+        }
+        done('');
+      });
+      const task = `${question}\nAnswer with exactly one word from: ${allowed.join(', ')}. No explanation.`;
+      p.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }) + '\n');
+      p.stdin.write(JSON.stringify({
+        jsonrpc: '2.0', id: 2, method: 'tools/call',
+        params: { name: 'ask_kimi', arguments: { task } },
+      }) + '\n');
+      p.stdin.end();
+    });
+  };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+//
+//   node scripts/lib/second-opinion.mjs <dag.json> --answers '{"node-id":"yes"}'
+//
+// You supply YOUR answers; the router answers the same questions independently
+// and the divergence is printed. Exit 1 when the judges diverge — not because
+// divergence is a failure, but because it is the case a human should see.
+
+async function main(argv) {
+  const { readFileSync, existsSync } = await import('node:fs');
+  const { join, dirname } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+
+  const file = argv.find((a) => !a.startsWith('--'));
+  const i = argv.indexOf('--answers');
+  if (!file || i === -1) {
+    console.error('usage: second-opinion.mjs <dag.json> --answers \'{"node-id":"yes"}\' [--server <path>] [--json]');
+    return 2;
+  }
+
+  let dag, mine;
+  try { dag = JSON.parse(readFileSync(file, 'utf8')); }
+  catch (e) { console.error(`cannot read ${file}: ${e.message}`); return 2; }
+  try { mine = JSON.parse(argv[i + 1]); }
+  catch { console.error('--answers must be JSON'); return 2; }
+
+  const si = argv.indexOf('--server');
+  const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const server = si >= 0 ? argv[si + 1] : join(root, 'mcp-servers', 'llm-router', 'server.py');
+  if (!existsSync(server)) { console.error(`router not found at ${server}`); return 2; }
+
+  const cmp = await secondOpinion(dag, async (q, allowed) => {
+    const id = Object.keys(dag.nodes).find((k) => dag.nodes[k].question === q);
+    // An answer you did not give is an abstention, not a default. Filling it in
+    // would manufacture the agreement this tool exists to avoid claiming.
+    return id in mine ? String(mine[id]) : '';
+  }, routerAsk(server));
+
+  if (argv.includes('--json')) console.log(JSON.stringify(cmp, null, 2));
+  else console.log(explainComparison(cmp));
+  return cmp.diverged.length ? 1 : 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2)).then((c) => { process.exitCode = c; });
+}
+
+// ── Which harness gives the second opinion ───────────────────────────────────
+//
+// Until 2026-09-05 the second opinion was whatever OpenRouter model the
+// environment named, and the environment named it in three different variables.
+// Codex is now a participant: `codex exec` in a read-only sandbox, authenticated
+// by the user's ChatGPT login, a genuinely different model family with no API
+// key to leak. Which one runs is a project decision, declared once in
+// PROJECT.md's `capabilities:` block and read here — by the reviewer, by the
+// verifier, and by the board, so all three agree.
+
+import { capabilitiesFromProjectMd } from './stack-capabilities.mjs';
+import { runCodexExec, detectCodex } from './codex-exec.mjs';
+
+export const SECOND_OPINION_PROVIDERS = Object.freeze(['codex', 'openrouter', 'none']);
+
+/**
+ * FOUR states, and the fourth is the reason this function exists:
+ *
+ *   declared     the project chose a provider and it can run
+ *   none         the project decided: no second opinion
+ *   undeclared   nobody has said — NOT the same as none
+ *   unavailable  the project chose codex and there is no working codex here
+ *
+ * A caller that folds `unavailable` into `none` makes an absent reviewer look
+ * like a decision not to review.
+ *
+ * @param {{projectMd?:string, codex?:object, env?:object}} o
+ *   `codex` is the shape of `codexStatusFrom`; pass it to stay pure.
+ */
+export function resolveSecondOpinion({ projectMd = '', codex = null, env = process.env } = {}) {
+  const cap = capabilitiesFromProjectMd(projectMd).map.second_opinion ?? { state: 'undeclared', tool: null };
+  if (cap.state === 'none') {
+    return { state: 'none', provider: 'none', why: 'the project declared second_opinion: none' };
+  }
+  if (cap.state === 'undeclared') {
+    return { state: 'undeclared', provider: null, why: 'second_opinion is not declared in PROJECT.md capabilities — not declared is not none' };
+  }
+  const provider = String(cap.tool).toLowerCase();
+  if (!SECOND_OPINION_PROVIDERS.includes(provider)) {
+    return { state: 'unavailable', provider, why: `second_opinion: ${provider} is not a provider this plugin knows (${SECOND_OPINION_PROVIDERS.join(', ')})` };
+  }
+  if (provider === 'codex') {
+    const c = codex ?? detectCodex();
+    if (c.state !== 'available') return { state: 'unavailable', provider, why: c.why, codex: c };
+    return { state: 'declared', provider, why: '', codex: c };
+  }
+  if (provider === 'openrouter') {
+    if (!env.OPENROUTER_API_KEY) return { state: 'unavailable', provider, why: 'second_opinion: openrouter needs OPENROUTER_API_KEY' };
+    return { state: 'declared', provider, why: '' };
+  }
+  return { state: 'none', provider: 'none', why: '' };
+}
+
+/**
+ * The judge's `ask(question, allowed) → word` shape, backed by Codex.
+ *
+ * Same contract as `routerAsk` above, so `judge()` cannot tell them apart —
+ * which is the point: a second judge is only a second judge if it is
+ * interchangeable at the call site. Returns '' on anything that is not an
+ * answer, as routerAsk does; the caller already treats '' as "unparsed".
+ */
+export function codexAsk(cwd, { model = null, timeoutMs = 120_000, bin = 'codex' } = {}) {
+  return async (question, allowed) => {
+    const prompt = `${question}\nAnswer with exactly one word from: ${allowed.join(', ')}. No explanation.`;
+    const r = await runCodexExec({ prompt, cwd, model, timeoutMs, bin });
+    return r.state === 'ok' ? r.text : '';
+  };
+}
+
+/**
+ * A full review turn through Codex: system + user prompt in, text + usage out.
+ * The three non-ok states pass through untouched so the reviewer can say
+ * "skipped: unreadable" rather than "PASS".
+ */
+export async function codexReview({ system, user, cwd, model = null, timeoutMs = 300_000, bin = 'codex' }) {
+  const prompt = `${system}\n\n${user}`;
+  const r = await runCodexExec({ prompt, cwd, model, timeoutMs, bin });
+  return { ...r, model: r.model ?? model ?? null };
+}

package/board/scripts/lib/stack-capabilities.mjs

@@ -0,0 +1,206 @@
+/**
+ * stack-capabilities — what THIS project's operational tools actually are.
+ *
+ * `l3-support` carries a routing table with thirteen alert sources: grafana,
+ * datadog, cloudwatch, eks, argocd, sentry, postgres, kafka, airflow, vercel,
+ * betterstack, mongo, and a generic row. It is a good table. What it cannot say
+ * is which of those thirteen rows is THIS project — so the agent infers the
+ * stack from whatever the alert happened to come from, at the moment somebody is
+ * being paged, and its generic fallback row guesses Grafana.
+ *
+ * `PROJECT.md` already carries a `stack:` line, but it is prose for humans
+ * ("TypeScript / Node.js 22 / Cloudflare Workers"). It names no log store, no
+ * pager, no error tracker. `stack-baseline` pins what a NEW product should be
+ * built with; `observability-baseline` wires it at scaffold time. Neither
+ * describes what an existing project has connected today.
+ *
+ * Borrowed from anthropics/oncall-kit, whose rule is that no skill names a
+ * vendor: skills refer to CAPABILITIES, and one file maps each capability to the
+ * tool the team actually has. Swap Datadog for Grafana and no skill changes.
+ *
+ * The vocabulary is deliberately small and closed. An open-ended map becomes a
+ * place to write anything, and then nothing can be resolved against it.
+ *
+ * Declared in PROJECT.md:
+ *
+ *     capabilities:
+ *       logs: grafana-loki
+ *       metrics: grafana
+ *       errors: sentry
+ *       pager: none
+ *
+ * THREE STATES PER CAPABILITY, never two. `undeclared` and `none` are different
+ * answers: the first means nobody has said, the second means the project has
+ * deliberately decided it has no pager. An agent that treats "nobody said" as
+ * "there is none" stops looking for something that exists.
+ */
+
+/** The closed vocabulary. Adding one is a deliberate edit, not a free-text key. */
+export const CAPABILITIES = Object.freeze([
+  'logs',      // where log lines are searched
+  'metrics',   // time-series and dashboards
+  'traces',    // distributed traces
+  'errors',    // exception capture and grouping
+  'alerts',    // what fires, and where its rules live
+  'pager',     // who gets woken
+  'deploys',   // what shipped, and when
+  'code-host', // where the diff and the PR live
+  // Not an incident tool: which harness gives the SECOND opinion in review and
+  // verification — `codex` (a different model family, through `codex exec`),
+  // `openrouter`, or `none`. It lives in this vocabulary rather than in a new
+  // file because the three-state rule is the whole point: a project that has
+  // not said is not a project that has turned it off.
+  'second_opinion',
+]);
+
+/** `none` is a decision. Anything else is a tool name we pass through verbatim. */
+const NONE = 'none';
+
+/**
+ * @returns {{state:'declared'|'none'|'undeclared', tool:string|null}}
+ */
+function stateOf(raw) {
+  if (raw == null) return { state: 'undeclared', tool: null };
+  const v = String(raw).trim();
+  if (!v) return { state: 'undeclared', tool: null };
+  if (v.toLowerCase() === NONE) return { state: NONE, tool: null };
+  return { state: 'declared', tool: v };
+}
+
+/**
+ * Read the capability block out of a PROJECT.md body.
+ *
+ * Parsed with the same shape as `levelFromProjectMd` — a top-level key followed
+ * by indented `name: value` lines — rather than by pulling in a YAML parser the
+ * board's zero-dependency rule forbids.
+ *
+ * @returns {{map: Record<string,{state:string,tool:string|null}>, declaredCount:number, unknownKeys:string[]}}
+ */
+export function capabilitiesFromProjectMd(text = '') {
+  const body = String(text);
+  const start = body.match(/^capabilities:[ \t]*$/m);
+  const raw = {};
+  const unknownKeys = [];
+
+  if (start) {
+    const after = body.slice(start.index + start[0].length);
+    for (const line of after.split('\n')) {
+      if (/^\S/.test(line)) break;                 // dedent ends the block
+      const m = line.match(/^[ \t]+([a-z][a-z0-9_-]*)\s*:\s*(.*)$/i);
+      if (!m) continue;
+      const key = m[1].toLowerCase();
+      // An unrecognised key is REPORTED, not dropped. A capability nobody reads
+      // because it was misspelled is the same as one nobody wrote, except that
+      // the author believes it is there.
+      if (!CAPABILITIES.includes(key)) { unknownKeys.push(key); continue; }
+      raw[key] = m[2];
+    }
+  }
+
+  const map = {};
+  let declaredCount = 0;
+  for (const cap of CAPABILITIES) {
+    map[cap] = stateOf(raw[cap]);
+    if (map[cap].state === 'declared') declaredCount++;
+  }
+  return { map, declaredCount, unknownKeys };
+}
+
+/**
+ * A line an agent can act on, for one capability.
+ *
+ * The `undeclared` wording matters: it must send the reader to find out, not let
+ * them conclude there is nothing there. This is the sentence l3-support reads at
+ * 3am, so it says what to do rather than what is missing.
+ */
+export function describeCapability(cap, entry) {
+  if (entry.state === 'declared') return `${cap}: ${entry.tool}`;
+  if (entry.state === NONE) return `${cap}: none — this project has decided it has no ${cap}`;
+  return `${cap}: not declared — do not assume there is none; ask, or fall back to the alert-source routing table`;
+}
+
+/** The whole block, for injection into an agent brief. */
+export function describeCapabilities({ map, declaredCount, unknownKeys }) {
+  const lines = CAPABILITIES.map((c) => `  ${describeCapability(c, map[c])}`);
+  const head = declaredCount === 0
+    ? 'This project declares NO operational capabilities. Nothing below is known;'
+      + ' route by alert source and say so rather than implying the stack was checked.'
+    : `This project declares ${declaredCount} of ${CAPABILITIES.length} capabilities.`;
+  const warn = unknownKeys.length
+    ? [`  ⚠ unrecognised capability key(s) in PROJECT.md, ignored: ${unknownKeys.join(', ')}`]
+    : [];
+  return [head, ...lines, ...warn].join('\n');
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+// Read by l3-support at the top of an incident, the same way /recall reaches
+// memory-search: a block in the agent's own prompt, no new plumbing.
+//
+//   node scripts/lib/stack-capabilities.mjs [--cwd DIR] [--json]
+//
+// Exit 0 always. A project with nothing declared is a fact to report, not an
+// error to fail on — failing here would make an unconfigured project unable to
+// run an incident, which is exactly when you need the agent most.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const { readFileSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  const args = process.argv.slice(2);
+  const cwd = args.includes('--cwd') ? args[args.indexOf('--cwd') + 1] : process.cwd();
+  const asJson = args.includes('--json');
+
+  let text = '', read = 'ok';
+  try { text = readFileSync(join(cwd, '.great_cto', 'PROJECT.md'), 'utf8'); }
+  catch (err) { read = err.code ?? String(err.message); }
+
+  const result = capabilitiesFromProjectMd(text);
+  if (asJson) {
+    console.log(JSON.stringify({ read, ...result }, null, 2));
+  } else if (read !== 'ok') {
+    // Distinct from "declares nothing": there was no PROJECT.md to read at all.
+    console.log(`no PROJECT.md under ${cwd}/.great_cto (${read}) — the project's capabilities are unknown, not absent.`);
+  } else {
+    console.log(describeCapabilities(result));
+  }
+}
+
+/**
+ * Set one capability in a PROJECT.md body, returning the new text and what was
+ * there before. Pure, so the board's POST can be tested without a filesystem.
+ *
+ * The previous value is returned, not just the new one: a setting that
+ * silently replaced another is a change the operator cannot see they made —
+ * the same rule /api/agent-budgets follows.
+ *
+ * Creates the `capabilities:` block at the end when it is missing. `null` as
+ * the value removes the key (back to `undeclared`), which is different from
+ * writing `none`.
+ *
+ * @returns {{text:string, previous:string|null, created:boolean}}
+ */
+export function upsertCapability(text, key, value) {
+  if (!CAPABILITIES.includes(key)) throw new Error(`not a capability: ${key}`);
+  if (value != null && !/^[A-Za-z0-9_.:@/-]+$/.test(String(value))) throw new Error(`invalid value for ${key}`);
+  const body = String(text ?? '');
+  const lines = body.split('\n');
+  const start = lines.findIndex((l) => /^capabilities:[ \t]*$/.test(l));
+  const previous = capabilitiesFromProjectMd(body).map[key]?.tool
+    ?? (capabilitiesFromProjectMd(body).map[key]?.state === NONE ? NONE : null);
+
+  if (start === -1) {
+    if (value == null) return { text: body, previous, created: false };
+    const nl = body.endsWith('\n') || body === '' ? '' : '\n';
+    return { text: `${body}${nl}\ncapabilities:\n  ${key}: ${value}\n`, previous, created: true };
+  }
+
+  let end = start + 1;
+  while (end < lines.length && /^[ \t]+\S/.test(lines[end])) end += 1;
+  const idx = lines.findIndex((l, i) => i > start && i < end && new RegExp(`^[ \\t]+${key}[ \\t]*:`).test(l));
+
+  if (value == null) {
+    if (idx !== -1) lines.splice(idx, 1);
+    return { text: lines.join('\n'), previous, created: false };
+  }
+  const line = `  ${key}: ${value}`;
+  if (idx !== -1) lines[idx] = line; else lines.splice(end, 0, line);
+  return { text: lines.join('\n'), previous, created: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "3.25.0",
+  "version": "3.26.0",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",