amicus 3.2.3 → 4.0.1

package/schemas/wave.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/wave.schema.json",
+  "title": "amicus wave result document",
+  "description": "Fan-out wave result (`fanout --json`, wave.json). counts named buckets may not sum to total (see result-schema.js COUNTS REMAINDER RULE).",
+  "type": "object",
+  "required": ["schemaVersion", "type", "waveId", "status", "counts", "legs"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "wave" },
+    "waveId": { "type": "string" },
+    "status": { "type": "string" },
+    "error": { "type": ["string", "null"] },
+    "counts": {
+      "type": "object",
+      "required": ["total", "complete", "error", "timeout", "aborted"],
+      "properties": {
+        "total": { "type": "number" },
+        "complete": { "type": "number" },
+        "error": { "type": "number" },
+        "timeout": { "type": "number" },
+        "aborted": { "type": "number" }
+      }
+    },
+    "legs": { "type": "array", "items": { "type": "object" } },
+    "prompt": { "type": ["object", "null"] },
+    "createdAt": { "type": ["string", "null"] },
+    "completedAt": { "type": ["string", "null"] },
+    "durationMs": { "type": ["number", "null"] },
+    "usage": { "type": "object" },
+    "notices": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/skills/second-opinion/SEAT-BRIEFS.md

@@ -178,13 +178,15 @@ Append to the chair packet (`_tmp-chair-packet.md`) when the element is toggled
 > 1. **HARD QUESTIONS** — three to five questions the artifact's author has probably not
 >    asked themselves, chosen so that an unanswerable question reveals a structural gap in
 >    the artifact (not gotchas — questions whose answers should exist).
-> 2. A final line, alone on the last line, in exactly this format:
+> 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 before the artifact is useful — name them. "Fundamental rethink" =
->    structural problems that cannot be patched — say what is wrong at the foundation.
+>    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.
 
 **Orchestration note:** surface the chair's `VERDICT:` line verbatim at the top of
 `report.md` and in the inline chat presentation of the results.

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