amicus 3.2.2 → 4.0.0

package/skills/second-opinion/SKILL.md

@@ -33,6 +33,13 @@ Operating lessons from each run fold back into `MODEL-NOTES.md` (with approval),
 
 **Transport rule — CLI not on PATH:** every command below assumes the `amicus` CLI. If `amicus` is not on PATH (typical for **plugin-only installs**), run the identical commands as `npx -y amicus@latest <args>` (e.g. `npx -y amicus@latest fanout --models "m1,m2,m3" --prompt-file <path> --json`), or use the equivalent MCP tools (`amicus_fanout`, `amicus_start`, `amicus_wait`, `amicus_status`, `amicus_read`, `amicus_council_tally`, `amicus_council_stats`, `amicus_verdict`) — council briefings are always self-contained (`--no-context`), so MCP transport is equivalent.
 
+**Headless contexts (v4.0):** CI and scripted environments with no Claude runtime can run the
+whole mechanical pipeline (Stages 1–3 plus the deterministic Stage-5 artifacts) as one command —
+`amicus council run --prompt-file <briefing.md> --models "a,b,c" --chair <model> --json` — see
+[docs/council.md](../../docs/council.md#amicus-council-run). This skill's staged, human-in-the-loop
+orchestration remains the interactive path: Stage 0 intake, Stage 4 decisions, and Stage 6 lessons
+are human stages the engine never automates.
+
 ## When to use
 
 - The user provides documents, artifacts, or links **and** an analysis request **and** criteria, and wants other models to weigh in independently.
@@ -169,6 +176,7 @@ file) returns `{waveId, taskIds[]}` immediately. Preferred: call `amicus_wait` w
 one blocking call per wave; re-call it while it returns `timedOut: true`. Fallback: poll
 `amicus_status`. Either way, `amicus_read` each leg when done. The council's briefings are always
 self-contained (`--no-context`), so MCP transport is equivalent.
+Council JSON returned by the MCP tools (`amicus_council_tally`, `amicus_council_stats`, `amicus_verdict`) arrives wrapped in the `<untrusted_sidecar_output>` fence since v4.0 — parse the JSON from inside the fence; CLI `--json` output remains unfenced.
 
 **Required structured output from every model.** Instruct each council model to produce:
 

package/src/cli-handlers-abort.js

@@ -14,6 +14,31 @@ const { validateTaskId, safeSessionDir } = require('./utils/validators');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { buildAbortResult } = require('./utils/result-schema');
 
+/**
+ * Council-run abort via the sessions-dir pointer (v4.0 §8). Returns the exit
+ * code when the taskId was a council run, or null to fall through to the
+ * ordinary session/wave paths.
+ */
+function tryCouncilAbort(project, taskId, useJson) {
+  const { abortCouncilRun } = require('./mcp-council-run');
+  const res = abortCouncilRun(project, taskId);
+  if (!res) { return null; }
+  if (res.alreadyTerminal) {
+    if (useJson) {
+      console.log(JSON.stringify(buildAbortResult({ scope: 'council-run', taskId, aborted: [] }), null, 2));
+    } else {
+      console.log(`Council run ${taskId} is not running (status: ${res.status}).`);
+    }
+    return 0;
+  }
+  if (useJson) {
+    console.log(JSON.stringify(buildAbortResult({ scope: 'council-run', taskId, aborted: [taskId] }), null, 2));
+  } else {
+    console.log(`Council run ${taskId} marked as aborted (${res.cascaded} running leg(s) aborted).`);
+  }
+  return 0;
+}
+
 /**
  * Handle 'amicus abort --all --json': mark every running session aborted.
  * @returns {number} exit code (always 0 — even a no-op --all is a success)
@@ -45,6 +70,8 @@ async function handleAbortTaskJson(args, taskId) {
   const metaPath = path.join(sessionDir, 'metadata.json');
 
   if (!fs.existsSync(metaPath)) {
+    const council = tryCouncilAbort(project, taskId, true);
+    if (council !== null) { return council; }
     process.exit(failJson(true, { code: ERROR_CODES.BAD_SESSION, message: `Session ${taskId} not found` }));
   }
 
@@ -171,6 +198,8 @@ async function handleAbort(args) {
   const metaPath = path.join(sessionDir, 'metadata.json');
 
   if (!fs.existsSync(metaPath)) {
+    const council = tryCouncilAbort(project, taskId, false);
+    if (council !== null) { return council; }
     console.error(`Session ${taskId} not found`);
     process.exit(1);
   }

package/src/cli-handlers-council-run.js

@@ -0,0 +1,168 @@
+// src/cli-handlers-council-run.js
+'use strict';
+
+/**
+ * CLI `amicus council run` (v4.0 spec §4): flag validation, headless engine
+ * invocation, document emission, exit codes. Lives in its own file because
+ * cli-handlers-council.js is near the 300-line gate; dispatched from
+ * handleCouncil. Pre-flight failures go through the error envelope (exit 1)
+ * BEFORE any spend.
+ */
+
+const path = require('path');
+const { failJson, buildErrorDoc, ERROR_CODES } = require('./utils/error-doc');
+const { validateTaskId } = require('./utils/validators');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
+
+const CHAIR_DEFAULT = 'deepseek';
+
+function parseList(value) {
+  return String(value).split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/** Resolve bench models from --models XOR --council (mirrors handleFanout). */
+function resolveBench(args, useJson) {
+  const hasModels = typeof args.models === 'string' && args.models.trim();
+  const hasCouncil = args.council !== undefined && args.council !== false;
+  if (hasModels && hasCouncil) {
+    return { fail: failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: pass exactly one of --models / --council, not both' }) };
+  }
+  if (!hasModels && !hasCouncil) {
+    return { fail: failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: council run needs --models a,b,c or --council <preset> (at least 2 seats)' }) };
+  }
+  if (hasCouncil) {
+    if (typeof args.council !== 'string' || !args.council.trim()) {
+      return { fail: failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+        message: 'Error: --council requires a council name (e.g. --council budget)' }) };
+    }
+    const { resolveCouncilMembers } = require('./utils/config');
+    const { readCache } = require('./utils/model-catalog');
+    const catalog = (readCache() || {}).models || [];
+    const expanded = resolveCouncilMembers(args.council.trim(), catalog);
+    if (expanded.error) {
+      return { fail: failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: ${expanded.error}` }) };
+    }
+    if (expanded.dropped && expanded.dropped.length && !useJson) {
+      process.stderr.write(`Notice: dropped unavailable council member(s): ${expanded.dropped.join(', ')}\n`);
+    }
+    return { bench: expanded.models };
+  }
+  return { bench: parseList(args.models) };
+}
+
+function renderRunHuman(run) {
+  const lines = [
+    `Council run ${run.runId}: ${run.status} (exit ${run.exitCode})`,
+    `  bench: ${(run.bench || []).join(', ')}  chair: ${run.chair}`,
+    `  dir:   ${run.options && run.options.outDir}`,
+  ];
+  if (run.usage && run.usage.cost && typeof run.usage.cost.amount === 'number') {
+    lines.push(`  cost:  $${run.usage.cost.amount.toFixed(4)} (${run.usage.cost.source})`);
+  }
+  if (run.error) { lines.push(`  error: ${run.error.code}: ${run.error.message}`); }
+  return lines.join('\n') + '\n';
+}
+
+/** @param {object} args parsed CLI args @returns {Promise<number>} exit code */
+async function handleCouncilRun(args) {
+  const useJson = !!args.json;
+
+  // --prompt-file required; inline --prompt rejected (councils always have
+  // real briefings — same rationale as MCP fanout's briefing-via-file).
+  if (args.prompt !== undefined) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: council run takes --prompt-file only (no inline --prompt)',
+      hint: 'write the briefing to a file and pass --prompt-file <path>' });
+  }
+  const { resolvePromptSource } = require('./utils/prompt-source');
+  const promptRes = resolvePromptSource(args);
+  if (promptRes.error) {
+    return failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error });
+  }
+
+  const benchRes = resolveBench(args, useJson);
+  if (benchRes.fail !== undefined) { return benchRes.fail; }
+  const bench = benchRes.bench;
+  if (bench.length < 2) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: a council needs at least 2 seats (fanout semantics)' });
+  }
+
+  const chair = (typeof args.chair === 'string' && args.chair.trim())
+    ? args.chair.trim() : CHAIR_DEFAULT;
+  if (bench.includes(chair)) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: `Error: chair '${chair}' is a bench seat — the chair must not review`,
+      hint: `pick a chair outside --models (default: ${CHAIR_DEFAULT}), or remove '${chair}' from the bench` });
+  }
+  const critic = (typeof args.critic === 'string' && args.critic.trim()) ? args.critic.trim() : null;
+  if (critic && !bench.includes(critic)) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: `Error: critic '${critic}' must be one of the bench seats`,
+      hint: `--critic swaps one seat's brief; pass one of: ${bench.join(', ')}` });
+  }
+  const lenses = (typeof args.lenses === 'string' && args.lenses.trim()) ? parseList(args.lenses) : null;
+  if (critic && lenses) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: --critic and --lenses are mutually exclusive in v4.0' });
+  }
+  if (lenses && lenses.length !== bench.length) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: `Error: --lenses needs exactly one lens per seat (${bench.length} seats, got ${lenses.length})` });
+  }
+  if (args.timeout !== undefined && args.timeout <= 0) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --timeout must be a positive number' });
+  }
+  const mc = args['max-cost'];
+  if (mc !== undefined && (typeof mc !== 'number' || !Number.isFinite(mc) || mc <= 0)) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' });
+  }
+  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` });
+  }
+  let runId;
+  if (args['run-id']) {
+    const check = validateTaskId(String(args['run-id']));
+    if (!check.valid) {
+      return failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: check.error });
+    }
+    runId = String(args['run-id']);
+  } else {
+    runId = require('./sidecar/start').generateTaskId();
+  }
+
+  const project = args.cwd || process.cwd();
+  const runDir = args['out-dir']
+    ? path.resolve(project, String(args['out-dir']))
+    : path.resolve(project, `council-${runId}`);
+
+  const { resolveGatewayMode } = require('./utils/config');
+  const { runCouncil } = require('./council/run');
+  const { exitCode, run } = await runCouncil({
+    briefing: promptRes.prompt, models: bench, chair, critic, lenses,
+    project, runId, runDir,
+    timeout: args.timeout, maxCost: mc !== undefined ? mc : null,
+    gateway: resolveGatewayMode(args.gateway),
+    noValidateModel: !!args['no-validate-model'],
+    date: new Date().toISOString().slice(0, 10),
+  });
+
+  if (useJson) {
+    // Spec §4: exit-1 rows fail through the error envelope; 0/2 emit the manifest.
+    if (exitCode === 1 && run && run.error) {
+      process.stdout.write(JSON.stringify(buildErrorDoc({
+        code: run.error.code, message: run.error.message, command: 'council run',
+      }), null, 2) + '\n');
+    } else {
+      process.stdout.write(JSON.stringify(run, null, 2) + '\n');
+    }
+  } else {
+    process.stdout.write(renderRunHuman(run));
+  }
+  return exitCode;
+}
+
+module.exports = { handleCouncilRun, CHAIR_DEFAULT };

package/src/cli-handlers-council.js

@@ -2,11 +2,11 @@
 'use strict';
 const fs = require('fs');
 const { tally } = require('./council/tally');
-const { deriveReliability, appendRun } = require('./council/ledger');
+const { deriveReliability, appendRun, buildStatsDoc } = require('./council/ledger');
 const { sumWaveUsage, formatCost } = require('./utils/pricing');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { buildReport } = require('./council/report');
-const { validateFindings } = require('./council/findings');
+const { validateFindings, buildValidateDoc } = require('./council/findings');
 const { buildVerdict, writeVerdictAtomic } = require('./council/verdict');
 const {
   runSave: runCouncilSave,
@@ -44,7 +44,9 @@ function runTally(inputPath, useJson, opts = {}) {
 
 function runStats(useJson) {
   const agg = deriveReliability();
-  process.stdout.write(useJson ? JSON.stringify(agg, null, 2) + '\n' : renderStats(agg));
+  // v4.0 §7: --json emits the enveloped doc (breaking: was a bare array);
+  // human output is unchanged (renderStats still takes the rows).
+  process.stdout.write(useJson ? JSON.stringify(buildStatsDoc(agg), null, 2) + '\n' : renderStats(agg));
   return 0;
 }
 
@@ -117,7 +119,7 @@ function runValidate(filePath, useJson) {
       hint: 'pass a Stage-1 reviewer output file (prose + trailing ```json findings block)' });
   }
   const result = validateFindings(text);
-  process.stdout.write(useJson ? JSON.stringify(result, null, 2) + '\n' : renderValidate(result));
+  process.stdout.write(useJson ? JSON.stringify(buildValidateDoc(result), null, 2) + '\n' : renderValidate(result));
   return result.ok ? 0 : 2;
 }
 
@@ -185,6 +187,7 @@ function renderVerdict(v, outPath) {
 async function handleCouncil(args) {
   const sub = args._[1];
   const useJson = !!args.json;
+  if (sub === 'run') { return require('./cli-handlers-council-run').handleCouncilRun(args); }
   if (sub === 'tally') { return runTally(args._[2], useJson, { append: !args['no-ledger'] }); }
   if (sub === 'stats') { return runStats(useJson); }
   if (sub === 'report') { return runReport(args, useJson); }
@@ -195,7 +198,7 @@ async function handleCouncil(args) {
   if (sub === 'show') { return runCouncilShow(args._[2], useJson); }
   return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
     message: `unknown council subcommand '${sub || ''}'`,
-    hint: 'amicus council tally|stats|report|validate|verdict|save|list|show' });
+    hint: 'amicus council run|tally|stats|report|validate|verdict|save|list|show' });
 }
 
 module.exports = { handleCouncil };

package/src/cli-handlers-status.js

@@ -9,6 +9,7 @@
 'use strict';
 
 const { validateTaskId } = require('./utils/validators');
+const { failJson, ERROR_CODES } = require('./utils/error-doc');
 
 /** Render a key-value block for a single-session status payload. */
 function formatRunHuman(d) {
@@ -42,6 +43,18 @@ function formatWaveHumanStatus(d) {
   return [head, ...legLines].join('\n');
 }
 
+/** Render a council-run payload: header + one line per stage. */
+function formatCouncilHuman(d) {
+  const head = `Council run ${d.runId}: ${d.status}` +
+    (d.currentStage ? ` — ${d.currentStage}` : '') +
+    (d.legsTotal !== null && d.legsTotal !== undefined ? ` (${d.legsComplete}/${d.legsTotal} legs)` : '') +
+    ` (${d.elapsed})`;
+  const stageLines = (d.stages || []).map(s =>
+    `  ${String(s.name).padEnd(10)} ${String(s.status).padEnd(10)}${s.waveId ? ` wave ${s.waveId}` : ''}`);
+  const tail = d.reason ? [`  Reason: ${d.reason}`] : [];
+  return [head, ...stageLines, ...tail].join('\n');
+}
+
 /**
  * Handle 'amicus status'. Exit code 0 = status retrieved (any run state, even
  * a failed/crashed run — the QUERY succeeded); 1 = missing/invalid/unknown id.
@@ -49,28 +62,46 @@ function formatWaveHumanStatus(d) {
  * @returns {Promise<number>}
  */
 async function handleStatus(args) {
+  const useJson = !!args.json;
   const taskId = args.wave || args._[1];
   if (!taskId || taskId === true) {
+    // v4.0 §7: --json failures land on stdout as the error doc; human stderr
+    // is byte-identical to pre-4.0.
+    if (useJson) {
+      return failJson(true, { code: ERROR_CODES.BAD_SESSION, message: 'task_id is required for status',
+        hint: 'amicus status <task_id> [--json]   (or: amicus status --wave <wave_id>)' });
+    }
     process.stderr.write('Error: task_id is required for status\n');
     process.stderr.write('Usage: amicus status <task_id> [--json]   (or: amicus status --wave <wave_id>)\n');
     return 1;
   }
   const check = validateTaskId(String(taskId));
-  if (!check.valid) { process.stderr.write(`${check.error}\n`); return 1; }
+  if (!check.valid) {
+    if (useJson) { return failJson(true, { code: ERROR_CODES.BAD_SESSION, message: check.error }); }
+    process.stderr.write(`${check.error}\n`);
+    return 1;
+  }
 
   const project = args.cwd || process.cwd();
   const { handlers } = require('./mcp-server');
   const result = await handlers.amicus_status({ taskId: String(taskId) }, project);
   const text = result.content[0].text;
-  if (result.isError) { process.stderr.write(`${text}\n`); return 1; }
+  if (result.isError) {
+    if (useJson) { return failJson(true, { code: ERROR_CODES.BAD_SESSION, message: text }); }
+    process.stderr.write(`${text}\n`);
+    return 1;
+  }
 
   let data;
   try { data = JSON.parse(text); } catch { process.stdout.write(`${text}\n`); return 0; }
   delete data.next_poll; // MCP-agent polling guidance, not CLI output
 
   if (args.json) { process.stdout.write(`${JSON.stringify(data, null, 2)}\n`); return 0; }
-  process.stdout.write(`${data.type === 'wave' ? formatWaveHumanStatus(data) : formatRunHuman(data)}\n`);
+  const rendered = data.type === 'wave' ? formatWaveHumanStatus(data)
+    : data.type === 'council-run' ? formatCouncilHuman(data)
+    : formatRunHuman(data);
+  process.stdout.write(`${rendered}\n`);
   return 0;
 }
 
-module.exports = { handleStatus, formatRunHuman, formatWaveHumanStatus };
+module.exports = { handleStatus, formatRunHuman, formatWaveHumanStatus, formatCouncilHuman };

package/src/cli.js

@@ -357,6 +357,7 @@ Commands:
   continue    New session building on previous
   read        Output session summary/conversation
   models      List/search the model catalog, refresh it, audit aliases
+  council run <briefing.md> (--models a,b,c | --council <name>)   Headless council: reviews → cross-review → tally → chair → verdict
   council tally <input.json> [--json]   Tally council findings → tiers/street-cred
   council stats [--json]                Reviewer-reliability from the ledger
   council report <verdict.json> [--wave <wave.json>] [--md|--html]   Disagreement+verdict report
@@ -507,6 +508,14 @@ Subcommands for 'council':
     --decisions <d.json>       Optional. Stage-4 decisions array (default [])
     -o, --out <out.json>       Output path (default ./verdict.json)
     --json                     Print the full verdict document
+  run --prompt-file <briefing.md> (--models a,b,c | --council <name>)
+      [--chair <model>] [--critic <model>] [--lenses s1,s2,...]
+      [--out-dir <dir>] [--json] [--max-cost <usd>] [--timeout <min>]
+      [--gateway auto|direct|openrouter] [--no-validate-model]
+                                Run the full headless council engine (v4.0).
+                                Chair default: deepseek (must NOT be a bench seat).
+                                --critic and --lenses are mutually exclusive.
+                                Exit: 0 full run, 2 degraded, 1 quorum/cost/validation.
   save <name> --models a,b,c    Save a named council preset (>=2 resolvable members)
     --json                     Machine-readable output
   list                          List saved councils plus the built-in benches

package/src/council/anonymize.js

@@ -0,0 +1,76 @@
+// src/council/anonymize.js
+'use strict';
+
+/**
+ * @module council/anonymize
+ * Pure label-map helpers for the headless council engine (spec §6).
+ * Each surviving Stage-1 review gets a stable letter label ('Review A',
+ * 'Review B', …) in bench order. The label↔model map lives ONLY in
+ * orchestrator memory and run.json — never in any judge-visible file.
+ */
+
+const LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+/**
+ * Assign stable labels in the given model order.
+ * @param {string[]} models reviewed model ids (bench order)
+ * @returns {{entries: Array<{label: string, letter: string, model: string}>,
+ *   labelMap: Object<string, string>, letterByModel: Object<string, string>}}
+ */
+function assignLabels(models) {
+  if (!Array.isArray(models) || models.length === 0 || models.length > LETTERS.length) {
+    throw new Error(`assignLabels needs 1-${LETTERS.length} models`);
+  }
+  const entries = models.map((model, i) => ({
+    label: `Review ${LETTERS[i]}`, letter: LETTERS[i], model,
+  }));
+  const labelMap = {};
+  const letterByModel = {};
+  for (const e of entries) {
+    labelMap[e.label] = e.model;
+    letterByModel[e.model] = e.letter;
+  }
+  return { entries, labelMap, letterByModel };
+}
+
+/** Rewrite a review's local integer finding id to its run-global label id. */
+function toGlobalId(letter, localId) {
+  return `${letter}${localId}`;
+}
+
+/**
+ * Rewrite a validated review's findings to run-global tally-input entries.
+ * @param {string} letter review letter (e.g. 'A')
+ * @param {string} raiser de-anonymized model id
+ * @param {Array<{id: number, severity: string, claim: string, location: string}>} findings
+ * @returns {Array<{id: string, raiser: string, severity: string, claim: string, location: string}>}
+ */
+function toGlobalFindings(letter, raiser, findings) {
+  // claim + location must reach tally-input.json — Action v2 (Plan C) joins on
+  // them for file:line annotations; tally() reads only id/raiser/severity.
+  return findings.map(f => ({
+    id: toGlobalId(letter, f.id), raiser, severity: f.severity, claim: f.claim,
+    location: f.location,
+  }));
+}
+
+/**
+ * Translate a judge's anonymized ranking (labels; ties as nested arrays) into
+ * a tally rankings[].order array of model ids via the private label map.
+ * @param {Array<string|string[]>} ranking
+ * @param {Object<string, string>} labelMap
+ * @returns {{order: Array<string|string[]>, errors: string[]}}
+ */
+function rankingToOrder(ranking, labelMap) {
+  const errors = [];
+  const mapOne = (label) => {
+    const model = labelMap[label];
+    if (!model) { errors.push(`unknown label '${label}'`); }
+    return model;
+  };
+  const order = (Array.isArray(ranking) ? ranking : [])
+    .map(slot => (Array.isArray(slot) ? slot.map(mapOne) : mapOne(slot)));
+  return { order, errors };
+}
+
+module.exports = { assignLabels, toGlobalId, toGlobalFindings, rankingToOrder, LETTERS };

package/src/council/briefings-stage2.js

@@ -0,0 +1,150 @@
+// src/council/briefings-stage2.js
+'use strict';
+
+/**
+ * @module council/briefings-stage2
+ * Pure Stage-2 (judge bundle) and Stage-3 (chair packet) template builders
+ * for the headless council engine (spec §5). Split from ./briefings.js for
+ * the 300-line gate. The bundle is identical for every judge and never leaks
+ * seat/lens/critic information or model names (skill §5.1 / Stage-2 rule).
+ */
+
+const JUDGE_NO_TOOLS_PREAMBLE =
+  'Do NOT use any tools or read any files; everything is in this message; ' +
+  'begin immediately with A1:';
+
+const CHAIR_NO_TOOLS_PREAMBLE =
+  'Do NOT use any tools or read any files; everything is in this message; ' +
+  'begin immediately with the verdict.';
+
+const CHAIR_VERDICT_VALUES = ['Ship it', 'Fix these first', 'Fundamental rethink'];
+
+/** Stage-2 headless output contract (spec §5, embedded in the judge bundle). */
+const JUDGE_OUTPUT_CONTRACT = [
+  'End your response with a trailing fenced ```json block — no text after it — in',
+  'exactly this shape:',
+  '',
+  '```json',
+  '{',
+  '  "ranking": ["Review B", "Review A", "Review C"],',
+  '  "adjudications": [',
+  '    { "id": "A1", "verdict": "agree" },',
+  '    { "id": "B2", "verdict": "dispute" }',
+  '  ]',
+  '}',
+  '```',
+  '',
+  '- "ranking": every review label below, ordered most to least accurate and insightful.',
+  '  Ties: use a nested array for tied labels, e.g. [["Review A", "Review B"], "Review C"].',
+  '- "adjudications": one entry per listed finding id; "verdict" is one of:',
+  '  agree | dispute | neutral. An "I missed this — it\'s valid" counts as agree.',
+].join('\n');
+
+/**
+ * The single shared anonymized judge bundle.
+ * @param {{reviews: Array<{label: string, text: string}>,
+ *   findings: Array<{id: string, severity: string, claim: string}>}} args
+ */
+function buildJudgeBundle({ reviews, findings }) {
+  const findingLines = findings.map(f => `${f.id} [${f.severity}] ${f.claim}`).join('\n');
+  const reviewBlocks = reviews
+    .map(r => `--- ${r.label} ---\n${r.text}`)
+    .join('\n\n');
+  return [
+    JUDGE_NO_TOOLS_PREAMBLE,
+    'You are judging the anonymized peer reviews below. Do two things:',
+    'Task A — Rank: order the reviews from most to least accurate and insightful.',
+    'Task B — Adjudicate: for EVERY finding id listed below, state agree, dispute, or ' +
+    'neutral with your reasoning in prose.',
+    JUDGE_OUTPUT_CONTRACT,
+    '--- FINDINGS INDEX (run-global ids) ---',
+    findingLines,
+    reviewBlocks,
+  ].join('\n\n');
+}
+
+/** Bounded judge-repair re-prompt (solo; ≤ 2 per judge — spec §5). */
+function buildJudgeRepairPrompt({ errors }) {
+  const lines = (errors || []).map(e => `- ${e.code}: ${e.detail}`).join('\n');
+  return [
+    'Do NOT use any tools or read any files; everything is in this message; begin ' +
+    'immediately with the JSON block.',
+    'Your previous judging response\'s trailing JSON failed validation with these errors:',
+    lines,
+    'Re-emit ONLY the corrected JSON block as a single fenced ```json block:',
+    JUDGE_OUTPUT_CONTRACT,
+  ].join('\n\n');
+}
+
+/** Verdict-scale addendum (SEAT-BRIEFS.md § Chair verdict-scale addendum; always on headless). */
+const VERDICT_SCALE_ADDENDUM = [
+  'After your synthesis, add two closing sections:',
+  '',
+  '1. HARD QUESTIONS — three to five questions the material\'s author has probably not',
+  '   asked themselves, chosen so that an unanswerable question reveals a structural gap',
+  '   (not gotchas — questions whose answers should exist).',
+  '2. A final line, alone on the last line, containing ONLY the phrase — no rationale, no',
+  '   dash, no trailing text of any kind — exactly one of:',
+  '',
+  '   VERDICT: Ship it',
+  '   VERDICT: Fix these first',
+  '   VERDICT: Fundamental rethink',
+  '',
+  '   Pick one. "Ship it" = solid, nothing blocking. "Fix these first" = specific gaps',
+  '   must be resolved first. "Fundamental rethink" = structural problems that cannot be',
+  '   patched. Name the gaps or the structural problems in the synthesis ABOVE, not on the',
+  '   VERDICT line itself — that line carries the phrase and nothing else.',
+].join('\n');
+
+/**
+ * De-anonymized chair packet (spec §5/§6: the chair sees identities).
+ * @param {{reviews: Array<{model: string, text: string}>,
+ *   rankings: Array<{judge: string, order: Array<string|string[]>}>,
+ *   adjudications: Array<{findingId: string, judge: string, verdict: string}>,
+ *   tierCounts: object}} args
+ */
+function buildChairPacket({ reviews, rankings, adjudications, tierCounts }) {
+  const reviewBlocks = reviews.map(r => `--- Review by ${r.model} ---\n${r.text}`).join('\n\n');
+  const rankingLines = rankings
+    .map(r => `${r.judge}: ${JSON.stringify(r.order)}`)
+    .join('\n');
+  const adjLines = adjudications
+    .map(a => `${a.findingId} — ${a.judge}: ${a.verdict}`)
+    .join('\n');
+  const tiers = JSON.stringify(tierCounts);
+  return [
+    CHAIR_NO_TOOLS_PREAMBLE,
+    'You are the council chair. Write the synthesized verdict across the reviews, ' +
+    'rankings, and adjudications below. Weigh each reviewer\'s findings by their ' +
+    'peer-validated standing (rank position and adjudication pattern), distinguish ' +
+    'findings the bench broadly endorsed from contested or singleton claims, and ' +
+    'arrive at an overall assessment of the material.',
+    `Deterministic tier counts (peers-only cascade): ${tiers}`,
+    '--- STAGE-1 REVIEWS (de-anonymized) ---',
+    reviewBlocks,
+    '--- PEER RANKINGS (judge: order, best first) ---',
+    rankingLines,
+    '--- PER-FINDING ADJUDICATIONS ---',
+    adjLines,
+    VERDICT_SCALE_ADDENDUM,
+  ].join('\n\n');
+}
+
+/** One-shot chair repair: the VERDICT line was missing (spec §5 chair contract). */
+function buildChairRepairPrompt() {
+  return [
+    'Do NOT use any tools or read any files; everything is in this message; begin ' +
+    'immediately with the VERDICT line.',
+    'Your synthesis was received, but the final parseable line was missing. Emit ONLY ' +
+    'one line, exactly one of:',
+    'VERDICT: Ship it',
+    'VERDICT: Fix these first',
+    'VERDICT: Fundamental rethink',
+  ].join('\n\n');
+}
+
+module.exports = {
+  JUDGE_NO_TOOLS_PREAMBLE, CHAIR_NO_TOOLS_PREAMBLE, CHAIR_VERDICT_VALUES,
+  JUDGE_OUTPUT_CONTRACT, VERDICT_SCALE_ADDENDUM,
+  buildJudgeBundle, buildJudgeRepairPrompt, buildChairPacket, buildChairRepairPrompt,
+};