amicus 3.2.2 → 4.0.0

package/src/council/briefings.js

@@ -0,0 +1,141 @@
+// src/council/briefings.js
+'use strict';
+
+/**
+ * @module council/briefings
+ * Pure Stage-1 briefing template builders for the headless council engine
+ * (spec §5), adapted from skills/second-opinion/SEAT-BRIEFS.md with stricter
+ * headless output contracts. No IO, no model calls. Stage-2 / chair templates
+ * live in ./briefings-stage2.js (300-line gate split).
+ */
+
+/** SEAT-BRIEFS.md standard anti-sycophancy clause — verbatim, EVERY Stage-1 briefing. */
+const ANTI_SYCOPHANCY_CLAUSE =
+  'Do not soften findings to be agreeable. Lead with your most severe finding. ' +
+  'No praise cushions before criticism, and never perform enthusiasm you don\'t hold — ' +
+  'if the artifact is mediocre, say so and show why. Do not pad: report every real ' +
+  'finding and no invented ones. An empty severity category is a valid result.';
+
+/**
+ * "Produce exactly two things" framing (prose review, THEN the trailing json
+ * block). Stage-1 builders need this. The findings-repair prompt deliberately
+ * does NOT use it — a repair turn wants ONLY the corrected json, never a
+ * fresh prose review (keeping this fragment out of the repair prompt fixes
+ * the prior self-contradiction: "re-emit ONLY the JSON" followed by this
+ * "write prose then json" framing).
+ */
+const FINDINGS_TWO_PART_FRAMING = [
+  'Produce exactly two things, in this order:',
+  '',
+  '1. A prose review — your full narrative assessment of the material.',
+  '2. A trailing fenced ```json block immediately after the prose — no text after it:',
+].join('\n');
+
+/** JSON shape + field rules — shared by the full Stage-1 contract AND the repair prompt. */
+const FINDINGS_JSON_SHAPE = [
+  '```json',
+  '{',
+  '  "overall": "one-paragraph take",',
+  '  "findings": [',
+  '    { "id": 1, "severity": "blocker",',
+  '      "claim": "…", "location": "…", "rationale": "…" }',
+  '  ]',
+  '}',
+  '```',
+  '',
+  '- "id" — sequential integer within this review, starting at 1.',
+  '- "severity" — one of: blocker | major | minor | nit.',
+  '- "claim", "location", "rationale" — non-empty strings.',
+  'Emit the JSON verbatim after the prose, without preamble, so it parses cleanly.',
+].join('\n');
+
+/** Strict headless structured-output contract (prose + trailing ```json findings block). */
+const FINDINGS_CONTRACT = [FINDINGS_TWO_PART_FRAMING, FINDINGS_JSON_SHAPE].join('\n\n');
+
+/** Adapted from SEAT-BRIEFS.md § Critic seat brief (quota deliberately absent). */
+const CRITIC_BRIEF = [
+  'You are this review bench\'s designated critic. Assume problems exist; your job is to',
+  'find them, not to confirm the material is fine. Work through four passes and fold',
+  'everything into one findings list:',
+  '',
+  '1. Adversarial pass — for every claim: what evidence supports it, or is it an',
+  '   assumption presented as fact? For every goal: is it measurable? For every decision:',
+  '   what alternatives were considered? For every scope boundary: real constraint, or',
+  '   avoidance of hard work?',
+  '2. Edge-case hunt — walk every journey, requirement, and scenario. What happens on the',
+  '   unexpected input, the failed integration, the malformed data? At zero, at one, at',
+  '   scale? Report only unhandled cases.',
+  '3. Consistency check — cross-reference sections against each other: do goals have',
+  '   metrics, and metrics targets? Do requirements trace back to stated needs? Does',
+  '   anything contradict a stated non-goal or constraint?',
+  '4. Executability test — could someone act on this material without coming back with',
+  '   clarifying questions? Wherever the answer is no, name the specific section and',
+  '   exactly what is missing.',
+  '',
+  'Be specific: name the section, the line, the exact gap. Report every real finding and',
+  'no invented ones; do not pad to look thorough. An empty pass is a valid result.',
+].join('\n');
+
+function dateLine(date) {
+  return `Today's date is ${date}.`;
+}
+
+function compose(role, { briefing, date }) {
+  return [
+    role,
+    ANTI_SYCOPHANCY_CLAUSE,
+    dateLine(date),
+    FINDINGS_CONTRACT,
+    '--- MATERIAL / BRIEFING ---',
+    briefing,
+  ].join('\n\n');
+}
+
+/** Standard seat briefing (Stage-1 fanout wave). */
+function buildSeatBriefing(args) {
+  return compose(
+    'You are one reviewer on an independent multi-model review bench. Review the material ' +
+    'below against the briefing\'s own criteria.',
+    args
+  );
+}
+
+/** Critic seat briefing (concurrent solo — spec §4 --critic). */
+function buildCriticBriefing(args) {
+  return compose(CRITIC_BRIEF, args);
+}
+
+/** Expert-lens briefing (concurrent solo per seat — spec §4 --lenses). */
+function buildLensBriefing({ lens, briefing, date }) {
+  return compose(
+    `Review this material strictly through the lens of a ${lens}. Raise only findings ` +
+    'that perspective is qualified to raise, at the depth a top practitioner of it would ' +
+    'reach. Stay in-domain: if something matters but is outside your lens, leave it to ' +
+    'the other reviewers.',
+    { briefing, date }
+  );
+}
+
+/**
+ * Bounded findings-repair re-prompt (solo; ≤ 2 per seat — SKILL.md Stage-1
+ * repair loop). References ONLY the json-shape fragment — never the
+ * "prose review THEN json" framing — so a headless model isn't handed license
+ * to write a whole new prose review on a tight repair turn.
+ */
+function buildFindingsRepairPrompt({ 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 review\'s trailing findings JSON failed validation with these errors:',
+    lines,
+    'Re-emit ONLY the corrected findings JSON block (the same findings, fixed — do not ' +
+    'add or remove findings), as a single fenced ```json block:',
+    FINDINGS_JSON_SHAPE,
+  ].join('\n\n');
+}
+
+module.exports = {
+  ANTI_SYCOPHANCY_CLAUSE, FINDINGS_CONTRACT, FINDINGS_JSON_SHAPE, FINDINGS_TWO_PART_FRAMING,
+  buildSeatBriefing, buildCriticBriefing, buildLensBriefing, buildFindingsRepairPrompt,
+};

package/src/council/findings.js

@@ -45,4 +45,16 @@ function validateFindings(jsonText) {
   return { ok: errors.length === 0, findings: errors.length === 0 ? findings : [], errors };
 }
 
-module.exports = { validateFindings, SEVERITIES };
+/**
+ * v4.0 §7: stamp the council v2 envelope onto a validateFindings result
+ * (additive — ok/findings/errors stay top-level; existing key-readers keep
+ * working). Used by `amicus council validate --json`.
+ * @param {{ok:boolean, findings:Array, errors:Array}} result
+ * @returns {object} enveloped validate doc
+ */
+function buildValidateDoc(result) {
+  const { COUNCIL_SCHEMA_VERSION } = require('./tally');
+  return { schemaVersion: COUNCIL_SCHEMA_VERSION, type: 'council-validate', ...result };
+}
+
+module.exports = { validateFindings, buildValidateDoc, SEVERITIES, lastJsonBlock };

package/src/council/ledger.js

@@ -79,4 +79,16 @@ function deriveReliability(opts = {}) {
   });
 }
 
-module.exports = { buildLedgerRows, appendRun, deriveReliability, LEDGER_FILE, LEDGER_SCHEMA_VERSION };
+/**
+ * v4.0 §7: wrap the deriveReliability() rows in the council v2 envelope —
+ * THE one sanctioned breaking shape change (`council stats --json` used to
+ * emit the bare array). Human rendering keeps consuming the bare rows.
+ * @param {Array<object>} models deriveReliability() output
+ * @returns {{schemaVersion: number, type: 'council-stats', models: Array<object>}}
+ */
+function buildStatsDoc(models) {
+  const { COUNCIL_SCHEMA_VERSION } = require('./tally');
+  return { schemaVersion: COUNCIL_SCHEMA_VERSION, type: 'council-stats', models };
+}
+
+module.exports = { buildLedgerRows, appendRun, deriveReliability, buildStatsDoc, LEDGER_FILE, LEDGER_SCHEMA_VERSION };

package/src/council/parse-stage2.js

@@ -0,0 +1,103 @@
+// src/council/parse-stage2.js
+'use strict';
+
+/**
+ * @module council/parse-stage2
+ * Stage-2 output parsing for the headless council engine (spec §5): the
+ * judge's trailing JSON block ({ranking, adjudications}) and the chair's
+ * final `VERDICT:` line. Shares last-JSON-block extraction with findings.js.
+ * Pure — the ≤2-repair loop lives in run-stages.js; the tri-state
+ * (clean|repaired|unstructured) is recorded by the driver.
+ */
+
+const { lastJsonBlock } = require('./findings');
+
+const JUDGE_VERDICTS = ['agree', 'dispute', 'neutral'];
+const CHAIR_VERDICTS = ['Ship it', 'Fix these first', 'Fundamental rethink'];
+
+/**
+ * Parse + shape-validate one judge's output.
+ * @param {string} text raw judge output (prose + trailing ```json block)
+ * @param {{labels: string[], findingIds: string[]}} ctx known labels/ids
+ * @returns {{ok: boolean, ranking: Array|null, adjudications: Array|null,
+ *   errors: Array<{code: string, detail: string}>}}
+ */
+function parseJudgeOutput(text, { labels, findingIds }) {
+  const fail = (errors) => ({ ok: false, ranking: null, adjudications: null, errors });
+  const body = lastJsonBlock(text || '');
+  if (body === null) {
+    return fail([{ code: 'NO_FENCED_BLOCK', detail: 'no ```json block found' }]);
+  }
+  let parsed;
+  try { parsed = JSON.parse(body); }
+  catch (e) { return fail([{ code: 'NOT_PARSEABLE', detail: e.message }]); }
+
+  const errors = [];
+  const known = new Set(labels);
+  const flat = [];
+  if (!Array.isArray(parsed.ranking) || parsed.ranking.length === 0) {
+    errors.push({ code: 'BAD_RANKING', detail: 'ranking must be a non-empty array of review labels' });
+  } else {
+    for (const slot of parsed.ranking) {
+      for (const label of (Array.isArray(slot) ? slot : [slot])) {
+        if (!known.has(label)) {
+          errors.push({ code: 'UNKNOWN_LABEL', detail: `unknown review label '${label}'` });
+        }
+        flat.push(label);
+      }
+    }
+    if (new Set(flat).size !== flat.length) {
+      errors.push({ code: 'DUPLICATE_LABEL', detail: 'a review label appears more than once' });
+    }
+  }
+
+  const knownIds = new Set(findingIds);
+  if (!Array.isArray(parsed.adjudications)) {
+    errors.push({ code: 'BAD_ADJUDICATIONS', detail: 'adjudications must be an array' });
+  } else {
+    for (const a of parsed.adjudications) {
+      const id = a && a.id;
+      if (!knownIds.has(id)) {
+        errors.push({ code: 'UNKNOWN_FINDING_ID', detail: `unknown finding id '${id}'` });
+      }
+      if (!a || !JUDGE_VERDICTS.includes(a.verdict)) {
+        errors.push({ code: 'BAD_VERDICT', detail: `bad verdict '${a && a.verdict}' on '${id}'` });
+      }
+    }
+  }
+
+  if (errors.length) { return fail(errors); }
+  return { ok: true, ranking: parsed.ranking, adjudications: parsed.adjudications, errors: [] };
+}
+
+/** Per-phrase `^<phrase>(?![A-Za-z0-9])` matchers — prefix-anchored, case-sensitive. */
+const CHAIR_VERDICT_PREFIXES = CHAIR_VERDICTS.map(
+  (v) => new RegExp('^' + v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(?![A-Za-z0-9])')
+);
+
+/**
+ * Parse the chair's final verdict line. Last matching `VERDICT:` line wins. A
+ * line matches when the text after `VERDICT:` equals a canonical phrase, or
+ * starts with one followed by a word boundary (trailing rationale, e.g.
+ * `VERDICT: Fix these first — <gaps>`). Returns the canonical phrase, not the
+ * trailing text.
+ * @param {string} text
+ * @returns {string|null} one of CHAIR_VERDICTS, or null
+ */
+function parseChairVerdict(text) {
+  let found = null;
+  for (const line of String(text || '').split('\n')) {
+    const m = line.match(/^\s*VERDICT:\s*(.+?)\s*$/);
+    if (!m) { continue; }
+    const rest = m[1];
+    for (let i = 0; i < CHAIR_VERDICTS.length; i++) {
+      if (rest === CHAIR_VERDICTS[i] || CHAIR_VERDICT_PREFIXES[i].test(rest)) {
+        found = CHAIR_VERDICTS[i];
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+module.exports = { parseJudgeOutput, parseChairVerdict, CHAIR_VERDICTS, JUDGE_VERDICTS };

package/src/council/run-assemble.js

@@ -0,0 +1,100 @@
+// src/council/run-assemble.js
+'use strict';
+
+/**
+ * @module council/run-assemble
+ * Pure assembly + artifact emission for the headless council engine (spec §5):
+ * the five-keys tally input (meta pins: claudeInCouncil false, models = bench
+ * seats exactly — critic included, chair excluded — runType 'headless'),
+ * runStats rows copied verbatim from leg docs, and the run-dir artifact set
+ * (tally-input.json, tally.json, verdict.json with overallVerdict, report.html,
+ * chair-output.md). Raiser self-votes are INCLUDED in adjudications — exclusion
+ * is tally's job (tally.js:95); judged is tally's job (tally.js:110).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { writeFileAtomic } = require('../utils/atomic-write');
+const { buildVerdict, writeVerdictAtomic } = require('./verdict');
+const { buildReport } = require('./report');
+
+const CONFORMANCE_RANK = { clean: 0, repaired: 1, unstructured: 2 };
+
+/** Worst-wins merge of Stage-1 findings conformance and Stage-2 judge conformance. */
+function worseConformance(a, b) {
+  return (CONFORMANCE_RANK[a] || 0) >= (CONFORMANCE_RANK[b] || 0) ? a : b;
+}
+
+/**
+ * One runStats row from a leg run document. Verbatim copies only — a missing
+ * leg doc yields durationMs/usage null (never invent a value). `model` (the
+ * council alias) overrides leg.model (the resolved executable id) so ledger
+ * rows join meta.models by exact string (ledger.js:20-24).
+ */
+function buildRunStatsEntry({ leg, model, role, wasChair, conformance }) {
+  return {
+    model: model !== undefined ? model : (leg ? leg.model : null),
+    role,
+    wasChair: !!wasChair,
+    conformance: conformance || 'clean',
+    status: leg ? leg.status : 'error',
+    durationMs: leg && typeof leg.durationMs === 'number' ? leg.durationMs : null,
+    usage: (leg && leg.usage) || null,
+  };
+}
+
+/**
+ * Assemble the five-keys tally input (spec §5 / SKILL.md Stage-2 recipe).
+ * @param {{runId: string, date: string, bench: string[], chair: string,
+ *   reviews: Array<{model, role, conformance, leg, globalFindings}>,
+ *   judgeResults: Array<{judge, ok, order, adjudications}>,
+ *   chairStats: object|null}} args
+ */
+function buildTallyInput({ runId, date, bench, chair, reviews, judgeResults, chairStats }) {
+  const meta = {
+    runId, date, runType: 'headless',
+    models: bench.slice(),          // bench seats exactly: critic included, chair excluded
+    chair,
+    claudeInCouncil: false,         // pinned for headless runs
+  };
+  const findings = reviews.flatMap(r => r.globalFindings);
+  const okJudges = judgeResults.filter(j => j.ok);
+  const adjudications = okJudges.flatMap(j =>
+    j.adjudications.map(a => ({ findingId: a.id, judge: j.judge, verdict: a.verdict })));
+  const rankings = okJudges.map(j => ({ judge: j.judge, order: j.order }));
+  const runStats = reviews.map(r => buildRunStatsEntry({
+    leg: r.leg, model: r.model, role: r.role, wasChair: false, conformance: r.conformance,
+  }));
+  if (chairStats) { runStats.push(chairStats); }
+  return { meta, findings, adjudications, rankings, runStats };
+}
+
+/** Persist the assembled input (auditability) and the tally record. */
+function writeTallyFiles({ runDir, tallyInput, record }) {
+  writeFileAtomic(path.join(runDir, 'tally-input.json'),
+    JSON.stringify(tallyInput, null, 2), { mode: 0o600 });
+  writeFileAtomic(path.join(runDir, 'tally.json'),
+    JSON.stringify(record, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Undecided verdict + deterministic report. Sets the nullable overallVerdict
+ * (council family v2, Plan A) on buildVerdict's output — independent of
+ * buildVerdict's own signature.
+ * @returns {object} the verdict written to disk
+ */
+function writeVerdictFiles({ runDir, record, overallVerdict, chairText }) {
+  const verdict = buildVerdict(record, []);
+  verdict.overallVerdict = (overallVerdict === undefined) ? null : overallVerdict;
+  writeVerdictAtomic(path.join(runDir, 'verdict.json'), verdict);
+  const html = buildReport({ verdict }, { format: 'html' });
+  fs.writeFileSync(path.join(runDir, 'report.html'), html, { mode: 0o600 });
+  if (chairText) {
+    fs.writeFileSync(path.join(runDir, 'chair-output.md'), chairText, { mode: 0o600 });
+  }
+  return verdict;
+}
+
+module.exports = {
+  buildRunStatsEntry, worseConformance, buildTallyInput, writeTallyFiles, writeVerdictFiles,
+};

package/src/council/run-launch.js

@@ -0,0 +1,99 @@
+// src/council/run-launch.js
+'use strict';
+
+/**
+ * @module council/run-launch
+ * Council-flavored, DI-injected launch wrappers over the fanout transport
+ * (spec §5). Every council call — Stage-1 wave, critic/lens solos, Stage-2
+ * judge wave, repair re-prompts, chair — goes through runFanout with:
+ *   - `--agent Plan` default (fixes the skill-vs-engine 'build' default
+ *     mismatch, fanout.js:184),
+ *   - `--no-context` (council briefings are self-contained),
+ *   - quiet mode (the engine owns stdout; wave docs are consumed in-process).
+ * Solos are SINGLE-LEG WAVES: one launch primitive gives every call the same
+ * leg contract, budget gate, signal abort, and usage accounting.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @param {{fanoutFn?: Function}} [deps] test seam; default = real runFanout
+ * @returns {{launchWave: Function, launchSolo: Function}}
+ */
+function createLaunchers(deps = {}) {
+  const fanoutFn = deps.fanoutFn || require('../sidecar/fanout').runFanout;
+
+  /**
+   * @param {{models: string[], prompt: string, project: string, waveId: string,
+   *   timeout?: number, gateway?: string, noValidateModel?: boolean, agent?: string}} opts
+   * @returns {Promise<{wave: object|null, exitCode: number}>}
+   */
+  async function launchWave(opts) {
+    fs.mkdirSync(opts.project, { recursive: true });
+    const { wave, exitCode } = await fanoutFn({
+      models: opts.models.join(','),
+      prompt: opts.prompt,
+      promptMeta: { source: 'council-engine', file: null, chars: opts.prompt.length },
+      waveId: opts.waveId,
+      project: opts.project,
+      agent: opts.agent || 'Plan',
+      timeout: opts.timeout,
+      summaryLength: 'verbose',
+      includeContext: false,
+      gatewayMode: opts.gateway,
+      noValidateModel: opts.noValidateModel,
+      json: false,
+      quiet: true,
+      // Spec §6 judge isolation: pin every leg's OpenCode tool-exec cwd to its
+      // own session dir (judges' `project` is `<runDir>/_scratch`, so this
+      // scopes them there) and strip inherited MCP servers, so a tool-capable
+      // judge can't read the de-anonymized review-*.md files or the plaintext
+      // labelMap in run.json sitting in the parent run dir.
+      directory: opts.project,
+      noMcp: true,
+    });
+    return { wave, exitCode };
+  }
+
+  /**
+   * One-model launch (critic/lens legs, repairs, the chair) as a 1-leg wave.
+   * @returns {Promise<{wave: object|null, exitCode: number, leg: object|null}>}
+   */
+  async function launchSolo(opts) {
+    const { wave, exitCode } = await launchWave({ ...opts, models: [opts.model] });
+    const leg = (wave && Array.isArray(wave.legs) && wave.legs[0]) || null;
+    return { wave, exitCode, leg };
+  }
+
+  return { launchWave, launchSolo };
+}
+
+/** Filesystem-safe model name for review-/judge- artifact filenames. */
+function sanitizeName(model) {
+  return String(model).replace(/[^a-zA-Z0-9._-]/g, '-');
+}
+
+/**
+ * Write `review-<modelInput>.md` per surviving Stage-1 leg (skill layout).
+ * Dead legs and empty summaries are skipped — the caller applies the
+ * wave-degrade rules to what remains.
+ * @param {string} runDir
+ * @param {Array<object>} legs run documents from the wave/solo docs
+ * @returns {Array<{model: string, modelInput: string, file: string, text: string, leg: object}>}
+ */
+function materializeReviews(runDir, legs) {
+  const out = [];
+  for (const leg of legs) {
+    if (!leg || leg.status !== 'complete') { continue; }
+    const text = leg.summary;
+    if (!text || !String(text).trim()) { continue; }
+    const modelInput = leg.modelInput || leg.model;
+    const file = path.join(runDir, `review-${sanitizeName(modelInput)}.md`);
+    fs.writeFileSync(file, text, { mode: 0o600 });
+    out.push({ model: leg.model, modelInput, file, text, leg });
+  }
+  return out;
+}
+
+module.exports = { createLaunchers, materializeReviews, sanitizeName };

package/src/council/run-stages.js

@@ -0,0 +1,187 @@
+// src/council/run-stages.js
+'use strict';
+
+/**
+ * @module council/run-stages
+ * Stage-1 (independent reviews) and Stage-2 (anonymized cross-review) loops
+ * for the headless council engine — launch, materialize, validate, bounded
+ * repair. Split from run.js for the 300-line gate. All model calls go through
+ * ctx.launchers (DI); the whole-run cost ceiling is consulted via
+ * ctx.overBudget() before every paid repair launch (spec §4).
+ *
+ * Headless adaptations (vs SKILL.md):
+ *  - A review still malformed after 2 repair re-prompts is KEPT with
+ *    conformance 'unstructured' and zero findings entries (the skill's Claude
+ *    hand-parse fallback has no headless equivalent; the review still gets
+ *    ranked in Stage 2).
+ *  - A judge still malformed after 2 repairs is dropped from rankings and
+ *    adjudications (ok:false) and recorded conformance 'unstructured' (spec §5).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { validateFindings } = require('./findings');
+const briefings = require('./briefings');
+const stage2 = require('./briefings-stage2');
+const { parseJudgeOutput } = require('./parse-stage2');
+const { materializeReviews, sanitizeName } = require('./run-launch');
+
+function isAbortExit(code) { return code === 130 || code === 143; }
+
+function slug(text) {
+  return String(text).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+/** Launch all Stage-1 legs (wave + critic/lens solos), collect run docs. */
+async function launchStage1(ctx) {
+  const { o, launchers } = ctx;
+  const common = {
+    project: o.runDir, timeout: o.timeout, gateway: o.gateway,
+    noValidateModel: o.noValidateModel,
+  };
+  const launches = [];
+  if (o.lenses) {
+    o.models.forEach((m, i) => launches.push(launchers.launchSolo({
+      ...common, model: m, waveId: `${o.runId}-l${i + 1}`,
+      prompt: briefings.buildLensBriefing({ lens: o.lenses[i], briefing: o.briefing, date: o.date }),
+    })));
+  } else {
+    const seats = o.models.filter(m => m !== o.critic);
+    if (seats.length > 0) {
+      launches.push(launchers.launchWave({
+        ...common, models: seats, waveId: `${o.runId}-s1`,
+        prompt: briefings.buildSeatBriefing({ briefing: o.briefing, date: o.date }),
+      }));
+    }
+    if (o.critic) {
+      launches.push(launchers.launchSolo({
+        ...common, model: o.critic, waveId: `${o.runId}-c1`,
+        prompt: briefings.buildCriticBriefing({ briefing: o.briefing, date: o.date }),
+      }));
+    }
+  }
+  const results = await Promise.all(launches);
+  let aborted = null;
+  const legs = [];
+  for (const r of results) {
+    ctx.addWave(r.wave);
+    if (isAbortExit(r.exitCode)) { aborted = r.exitCode; }
+    if (r.wave && Array.isArray(r.wave.legs)) { legs.push(...r.wave.legs); }
+  }
+  return { aborted, legs };
+}
+
+/** Role of a seat by its input alias. */
+function roleFor(o, alias) {
+  if (o.lenses) {
+    const i = o.models.indexOf(alias);
+    return i === -1 ? 'seat' : `lens:${slug(o.lenses[i])}`;
+  }
+  return alias === o.critic ? 'critic' : 'seat';
+}
+
+/**
+ * Stage 1: independent reviews + findings validation + bounded repair.
+ * @returns {Promise<{aborted: number|null, reviews: Array, deadLegs: Array}>}
+ */
+async function runStage1(ctx) {
+  const { o } = ctx;
+  const { aborted, legs } = await launchStage1(ctx);
+  if (aborted) { return { aborted, reviews: [], deadLegs: [] }; }
+
+  const materialized = materializeReviews(o.runDir, legs);
+  const alive = new Set(materialized.map(m => m.leg));
+  const deadLegs = legs.filter(l => !alive.has(l));
+
+  const reviews = [];
+  let repairSeq = 0;
+  for (const m of materialized) {
+    let conformance = 'clean';
+    let res = validateFindings(m.text);
+    let attempts = 0;
+    while (!res.ok && attempts < 2 && !ctx.overBudget()) {
+      attempts += 1;
+      repairSeq += 1;
+      const solo = await ctx.launchers.launchSolo({
+        model: m.modelInput, prompt: briefings.buildFindingsRepairPrompt({ errors: res.errors }),
+        project: o.runDir, waveId: `${o.runId}-p${repairSeq}`, timeout: o.timeout,
+        gateway: o.gateway, noValidateModel: o.noValidateModel,
+      });
+      ctx.addWave(solo.wave);
+      if (isAbortExit(solo.exitCode)) { return { aborted: solo.exitCode, reviews, deadLegs }; }
+      res = validateFindings((solo.leg && solo.leg.summary) || '');
+      if (res.ok) { conformance = 'repaired'; }
+    }
+    if (!res.ok) { conformance = 'unstructured'; }
+    reviews.push({
+      model: m.modelInput, modelInput: m.modelInput, role: roleFor(o, m.modelInput),
+      text: m.text, findings: res.ok ? res.findings : [], conformance, leg: m.leg,
+    });
+  }
+  return { aborted: null, reviews, deadLegs };
+}
+
+/**
+ * Stage 2: shared anonymized bundle → judge wave in _scratch → parse + repair.
+ * @param {object} ctx
+ * @param {{reviews: Array, labels: {entries, labelMap}, globalFindings: Array}} args
+ * @returns {Promise<{aborted: number|null, judgeResults: Array}>}
+ */
+async function runStage2(ctx, { reviews, labels, globalFindings }) {
+  const { o } = ctx;
+  const { rankingToOrder } = require('./anonymize');
+  fs.mkdirSync(ctx.scratchDir, { recursive: true, mode: 0o700 });
+
+  const labeled = labels.entries.map((e, i) => ({ label: e.label, text: reviews[i].text }));
+  const bundle = stage2.buildJudgeBundle({ reviews: labeled, findings: globalFindings });
+  fs.writeFileSync(path.join(o.runDir, 'bundle-stage2.md'), bundle, { mode: 0o600 });
+
+  const judges = reviews.map(r => r.modelInput);
+  const parseCtx = {
+    labels: labels.entries.map(e => e.label),
+    findingIds: globalFindings.map(f => f.id),
+  };
+  const { wave, exitCode } = await ctx.launchers.launchWave({
+    models: judges, prompt: bundle, project: ctx.scratchDir, waveId: `${o.runId}-s2`,
+    timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
+  });
+  ctx.addWave(wave);
+  if (isAbortExit(exitCode)) { return { aborted: exitCode, judgeResults: [] }; }
+
+  const judgeResults = [];
+  let repairSeq = 0;
+  for (const leg of (wave && wave.legs) || []) {
+    const judge = leg.modelInput || leg.model;
+    if (leg.status === 'complete' && leg.summary) {
+      fs.writeFileSync(path.join(o.runDir, `judge-${sanitizeName(judge)}.md`), leg.summary, { mode: 0o600 });
+    }
+    let conformance = 'clean';
+    let parsed = (leg.status === 'complete' && leg.summary)
+      ? parseJudgeOutput(leg.summary, parseCtx)
+      : { ok: false, errors: [{ code: 'DEAD_LEG', detail: leg.error || leg.status }] };
+    let attempts = 0;
+    while (!parsed.ok && leg.status === 'complete' && leg.summary && attempts < 2 && !ctx.overBudget()) {
+      attempts += 1;
+      repairSeq += 1;
+      const solo = await ctx.launchers.launchSolo({
+        model: judge, prompt: stage2.buildJudgeRepairPrompt({ errors: parsed.errors }),
+        project: ctx.scratchDir, waveId: `${o.runId}-q${repairSeq}`, timeout: o.timeout,
+        gateway: o.gateway, noValidateModel: o.noValidateModel,
+      });
+      ctx.addWave(solo.wave);
+      if (isAbortExit(solo.exitCode)) { return { aborted: solo.exitCode, judgeResults }; }
+      parsed = parseJudgeOutput((solo.leg && solo.leg.summary) || '', parseCtx);
+      if (parsed.ok) { conformance = 'repaired'; }
+    }
+    if (!parsed.ok) {
+      judgeResults.push({ judge, ok: false, order: null, adjudications: null,
+        conformance: leg.status === 'complete' ? 'unstructured' : 'clean' });
+      continue;
+    }
+    const { order } = rankingToOrder(parsed.ranking, labels.labelMap);
+    judgeResults.push({ judge, ok: true, order, adjudications: parsed.adjudications, conformance });
+  }
+  return { aborted: null, judgeResults };
+}
+
+module.exports = { runStage1, runStage2, isAbortExit, slug };