# Manual Orchestration (fallback path) This is the **fallback path**; the engine is primary since v4.1 (`amicus council run --prompt-file --models "a,b,c" --chair --json`). Use this doc when: the engine is unavailable or misbehaving, you need a fully custom per-seat brief beyond `--critic`/`--lenses`, you need to inspect or intervene mid-stage, or you are running a 1-model scale-down. SKILL.md's §4.7 fallback rules point here. --- ### Stage 1 (manual) Each council model reviews **the artifact** independently. Write one Stage-1 briefing file (`_tmp-briefing-stage1.md` in the run folder) and launch the whole wave as ONE background call: ``` amicus fanout --models "" --prompt-file /_tmp-briefing-stage1.md --json \ --agent Plan --no-context --summary-length verbose --timeout ``` Always quote the `--models` list — unquoted, PowerShell splits on commas and the CLI receives one mangled alias (instant arg-parse failure). Run it in the background (`run_in_background: true`); you are notified on completion — do not poll. `fanout` is headless by definition. The command exits when every leg is terminal and prints ONE JSON wave document on stdout (`schemaVersion: 2`; the wave's id field is `waveId`, each leg's id is `taskId`): check `status` (`complete` | `partial` | `error`), `counts`, and each leg in `legs[]` — a leg's `summary` field IS that model's review; `model`/`modelInput` identify the reviewer (`model` is the resolved id, `modelInput` the alias you passed — use the alias for `review-.md` filenames); `status`/`error` identify failures. Exit code 0 = all legs complete, 2 = partial (apply the wave-degrade rules below), 1 = error/aborted. (To re-fetch a single leg later: `amicus read --json`.) **Red-team variant:** fanout legs share a single prompt by design. When one model gets a distinct red-team brief, launch it as a separate concurrent solo run alongside the wave: ``` amicus start --model --no-ui --json \ --prompt-file /_tmp-briefing-redteam.md \ --agent Plan --no-context --summary-length verbose --timeout ``` Its stdout is a single run document; the `summary` field is the review. **Critic seat (optional element, when ON):** one bench member — recommended by Claude at Stage 0, typically a strong reasoner that is not the chair — receives the critic brief from `SEAT-BRIEFS.md § Critic seat brief` **instead of** the standard review brief. Launch it exactly like the red-team variant: a separate concurrent solo run (`_tmp-briefing-critic.md`) alongside the fanout wave of the remaining members — same total review count. Everything downstream is unchanged: same structured-output contract, same `council validate` + repair loop, same anonymization into the Stage-2 bundle (judges are never told a critic seat exists). Record `role: "critic"` on that seat's `runStats` entry. One standing disclosure for `report.md`: the critic model can recognize its own review in the Stage-2 bundle by its adversarial shape, so self-bias wash-out is weakened for that one seat. **Expert lenses (optional element, when ON):** every seat gets a distinct per-seat brief, so there is no shared-prompt wave — launch **all** legs as concurrent solo runs (`_tmp-briefing-lens-.md`, one per seat), using the lens templates and panel-scoping rules in `SEAT-BRIEFS.md § Expert lens briefs`. The lens↔model assignment is random and lives only in the private label map — no reviewer learns the other seats' lenses. Same structured-output contract and validation. Record `role: "lens:"` on each `runStats` entry. Two standing consequences, both disclosed in `report.md`: Stage-2 anonymity is weakened (each judge can spot its own lens-flavored review), and the Stage-2 tally runs `--no-ledger` (lens reviews are not comparable to standard reviews and must not feed cross-run reliability stats). Wave-degrade rules apply to these solos exactly as to fanout legs. **Cowork / no-Bash environments:** use the MCP tools instead — `amicus_fanout` (briefing via file) returns `{waveId, taskIds[]}` immediately. Preferred: call `amicus_wait` with the waveId — 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 `` 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: 1. A **prose review** — the reviewer's full narrative assessment of the artifact. 2. A **trailing fenced ` ```json ` block** immediately after the prose, containing: ```json { "overall": "one-paragraph take", "findings": [ { "id": 1, "severity": "blocker", "claim": "…", "location": "…", "rationale": "…" } ] } ``` - `id` — sequential integer within this review (`1..n`); at Stage-2 assembly Claude rewrites each into a **run-global label id** (`A1`, `B1`, …) by prefixing the review's anonymized label. - `severity ∈ {blocker, major, minor, nit}` - `claim`, `location`, `rationale` — non-empty strings. Instruct models to emit the structured JSON verbatim after the prose, without preamble, so it parses cleanly. **Every Stage-1 briefing — standard seats included — must contain the standard anti-sycophancy clause from `SEAT-BRIEFS.md` verbatim** (do not soften, lead with the most severe finding, no praise cushions, no padding — an empty severity category is a valid result). This is briefing hygiene, not an optional element. Save each leg's full output (prose + findings block) to the run folder as `review-.md` (one file per reviewer) before moving on. **After the wave returns, validate each leg's findings block** by running `amicus council validate --json` (a thin CLI wrapper over `validateFindings`, Unit A — `src/council/findings.js`). It reads the leg's saved `review-.md` and prints `{ok, findings, errors}`. Exit codes are a **tri-state** contract: `0` when `ok:true` (well-formed, proceed), `2` when `ok:false` (validation failed — a distinct, scriptable outcome, not a crash), `1` (`BAD_ARGS`) for a missing/unreadable file. If a leg's JSON fails validation (`ok:false` / exit 2): 1. Issue a **solo `start --json`** re-prompt to that one model: "re-emit only the findings JSON, fixing: \." Keep the first-pass prose. (Solo `start` passes through the **same budget gate** as `fanout`. If launching the wave required `--max-cost <$>` or `--no-cost-gate`, pass the **same flag on every repair re-prompt and on the chair call** — otherwise the gate can refuse a repair or the chair mid-council.) 2. If still malformed, retry **once more** (cap = **2** re-prompts total). 3. If still malformed after 2 retries, mark the review `unstructured` and hand-parse its prose into the schema. The review proceeds — never dropped for a formatting miss. Record per-model **conformance** (`clean` | `repaired` | `unstructured`) for inclusion in the tally input's `runStats` and the Stage-6 MODEL-NOTES note. **"Claude in the council" (when toggled on):** Claude also produces a **fresh** Stage-1 review on the artifact in the identical findings format — a new structured pass on the artifact, not a formalization of anything said upstream. This review is added to the bundle as one more anonymous entry. Claude does not rank or adjudicate in Stage 2 (it holds the label map), and does not chair in Stage 3. Save it as `review-claude.md`. **Wave-degrade rules (Stage 1).** Read failures from the wave document — never silently ignore them: - All legs `complete` → proceed normally. - A leg ends `error`/`timeout`/`crashed`/`aborted` but **≥ 2 reviews survive** → proceed with the survivors; name the dead leg and its `error` when presenting; the bench shrinks accordingly. If this leaves exactly 2 surviving reviews, the run is now effectively a 2-model council — apply the thin-ranking disclosure (Stage 0 / Stage 4) from here on. - **Fewer than 2 reviews survive** → offer the user a re-run of the dead leg(s) (solo `amicus start --json`, same briefing file) or a disclosed downgrade to single-pass mode (Stage 2 and Stage 3 skipped, per the scale-down rules). --- ### Stage 2 (manual) This is the peer-validation step. Claude builds one shared anonymized bundle, distributes it to every council model for ranking and finding adjudication, then de-anonymizes for scoring. **Build the shared anonymized bundle.** After all Stage-1 reviews are in hand, Claude: 1. Assigns stable labels: **Review A**, **Review B**, **Review C**, … (one per review, including Claude's if the toggle is on). 2. Keeps a **private label↔model map** (e.g., `Review A → deepseek`, `Review B → gemini`, `Review C → claude`) that is never sent to any sidecar model. 3. Assembles one bundle document containing all labeled reviews. The bundle is identical for every judge. Each model **unknowingly ranks and adjudicates its own review** — this is the anti-favoritism mechanism, not a bug. Because no model knows which review is its own, self-bias washes out symmetrically across judges. **Distribute the same bundle to every council model** — this is exactly fanout's shared-prompt model. Write the bundle + judging instructions to `_tmp-bundle-stage2.md` and launch one wave: ``` amicus fanout --models "" --prompt-file /_tmp-bundle-stage2.md --json \ --agent Plan --no-context --summary-length verbose --timeout ``` (Background, same JSON handling as Stage 1.) Each judge's leg `summary` is its ranking + adjudication response. **Stage-2 degrade:** a judge leg dies → tally over the surviving judges (≥ 1) and disclose the reduced bench in `crossreview-matrix.md`; tier definitions are unchanged (they already count "judges engaged"). **Judge-briefing hardening (required).** Open `_tmp-bundle-stage2.md` with this preamble, verbatim, as its first line: > Do NOT use any tools or read any files; everything is in this message; begin immediately with A1: Plan-agent judges have wandered to tools mid-adjudication (reading files instead of judging and returning only narration), and a tool-capable judge can read the de-anonymized `review-.md` files in the run folder — an anonymization leak. The preamble closes both. **Scratch-cwd (optional second layer):** launch the Stage-2 wave (and the Stage-3 chair call) with `--cwd /_scratch/` — create the empty directory first — so even a wandering agent finds nothing to read. Caveat: those legs' session records then live under `_scratch/.claude/amicus_sessions/`, so any later `amicus read ` for them needs the same `--cwd`. Each judge is asked to do two things on the bundle: **Task A — Rank.** Order the reviews from most to least accurate and insightful. End the response with a parseable block in exactly this format (no other text on those lines): ``` FINAL RANKING: 1. Review C 2. Review A 3. Review B ``` **Task B — Adjudicate findings.** For every finding in the bundle, state: `agree | dispute | neutral` plus one-line reason. Reference each finding as **review-label + finding-id** — for example, `A2` means Review A's 2nd finding, `B1` means Review B's 1st finding. An "I missed this — it's valid" counts as `agree`. **When critic seat or expert lenses are ON:** the bundle and judging instructions must not mention seats, lenses, or briefs — judges rank and adjudicate on accuracy and insight only. The element briefs are Stage-1 information; leaking them into Stage 2 tells every judge which review is which. As each judge's ranking + adjudication response returns, collect it (the raw per-judge responses are working intermediates, not separate run-folder artifacts). Once all are in, **assemble the de-anonymized tally input** and then call `amicus council tally`: **Stage-2 → tally assembly recipe (Claude's work before calling `tally`):** 0. **Build `meta` and `findings[]` first — `tally` requires both** (missing either fails with `BAD_ARGS: Cannot read properties of undefined (reading 'map')`): - `meta` = `{ "runId": "", "models": [], "chair": "", "claudeInCouncil": }`. Optional extras: `runType`, `date`. - `findings[]` = one entry per finding across ALL reviews: `{ "id": "", "raiser": "", "severity": "" }` (`claim` may be carried along but is not required). 1. **Rewrite finding ids to run-global label ids.** Each Stage-1 review's local integer ids (`1`, `2`, `3`…) become `A1`, `A2`, `A3`… (where `A` is that review's anonymized label). The label↔model map (`Review A → deepseek`, etc.) is the key. 2. **Build `adjudications`** — for every judge across all findings: `findingId` = run-global label id; `judge` = the model id (de-anonymized via the map); `verdict ∈ {agree, dispute, neutral}`. Include every judge's verdict on every finding. The raiser's own adjudication of its own finding is **included in the input** (the tally engine excludes it when computing peers-only tiers — do not pre-filter it). ⚠️ **v4.8 — that exclusion is by SEAT when seat ids are present.** If your bench seats one model twice, add `seat` to each adjudication and `raiserSeat` to each finding (both optional, both string seat ids like `deepseek#1`), and the engine will drop only the raising *seat's* own vote instead of both twins'. Set them from what you actually observed — never invent a seat id to unlock the seat compare, and never set only one side: with a seat on the vote but not the finding (or vice versa) the engine deliberately falls back to the alias compare rather than guessing. 3. **Translate each judge's `FINAL RANKING:` block** — convert the label order (`1. Review C / 2. Review A / 3. Review B`) into a model `order` array via the same map (e.g. `{C→mistral, A→deepseek, B→gpt}` ⇒ `order: ["mistral","deepseek","gpt"]`). This is each entry in `rankings[]`. 4. **Populate `runStats`** from the per-leg run documents emitted by `fanout --json` (and any solo red-team/chair `start --json` docs): copy `model`, `status`, `durationMs`, `usage` verbatim. Any leg with no run doc gets `durationMs: null` and `usage: null` — never invent a value. Attach `role` (`council` | `redteam` | `claude`), `wasChair`, and `conformance` (`clean` | `repaired` | `unstructured`) as council-domain labels. ⚠️ **v4.7 CA-4 note:** the headless engine driver (`amicus council run`) now emits extra non-primary `runStats` rows (`chair-attempt`/`repair`/`superseded` — failed chair launches, repair solos, and superseded legs) alongside one seat-primary row per model. This manual orchestration path is unaffected and still produces exactly one seat-primary row per model as described above — no contract change here — but any code or report template reading `runStats` should be a **tolerant reader** (filter by role rather than assume one row per model), since an engine-produced tally.json can now carry rows this recipe never does. Hand-assembled `runStats` rows carry no `resolvedModel`; their ledger rows therefore aggregate as alias-keyed `legacy` groups in `council stats` (legacy-by-absence, by design) — expected, not an error. Add `resolvedModel` (the executable id that served) to a row only if you know it; never copy the alias into it. **Five-keys checklist — verify `tally-input.json` has ALL of:** `meta` (with `meta.models`), `findings`, `adjudications`, `rankings`, `runStats` (`runStats` may be `[]`; the other four are required). Do not call `tally` until all five are present. Then call, saving the printed `record` to `/tally.json` (Stage 5's `amicus council verdict` reads it back from disk): ``` amicus council tally /tally-input.json --json > /tally.json ``` **Ledger flags for optional elements:** when **expert lenses** are ON, always pass `--no-ledger` — lens runs never feed cross-run reliability stats. When **debate mode** is ON, this Stage-2 tally is *provisional* — pass `--no-ledger` here; the final, ledger-recorded tally happens at the end of Stage 2.5 (the critic seat and Claude-in-the-council change nothing about ledger handling). **Windows PowerShell 5.1 caveat:** that `>` redirect writes UTF-16 under legacy Windows PowerShell 5.1 (fine on pwsh 7+ or bash), which corrupts `tally.json` for Stage 5's `amicus council verdict` and surfaces as a confusing `BAD_ARGS` there instead of here — on 5.1 pipe through `| Out-File -Encoding utf8` (or run under pwsh 7+) instead of a bare `>`. The output `record` carries the deterministic tiers (Disputed / Confirmed / Contested / Singleton), `confidence` (`solid` | `thin`), both street-cred numbers (`withSelf` and `peersOnly`), the validated `runStats`, and `tierCounts`. **Claude may override a `thin`-confidence tier at the margins** before Stage 4 — record the override in `tierOverride: {from, to, reason}`; the matrix and `verdict.json` surface it. De-anonymize and write the tally results to `crossreview-matrix.md` — the adjudication grid plus the street-cred table. This data feeds Stage 3 (chair briefing) and is never re-anonymized or forwarded to any council model. --- ### Stage 2.5 (manual rebuttal round) One structured challenge round on the findings the bench did not settle: every **Contested** and **Disputed** finding goes back to its raiser to defend, amend, or withdraw; the judges that disputed it re-vote; then the final tally. **Exactly ONE round, ever** — never iterate further; whatever remains unsettled after the re-vote keeps its final tier. Briefing templates are in `SEAT-BRIEFS.md § Rebuttal-round templates`; every rebuttal briefing opens with the no-tools preamble, same as Stage 2. The Stage-2 tally above ran `--no-ledger` (provisional). If it produced **zero Contested + Disputed findings**, skip the rebuttal waves entirely: re-run the tally on the unchanged input *without* `--no-ledger` to record it, note "debate mode: nothing to debate" for `report.md`, and proceed to Stage 3. **1. Defense mini-wave.** For each raiser with ≥ 1 Contested/Disputed finding, write `_tmp-rebuttal-