amicus 3.2.3 → 4.0.1

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,
+};

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 };