amicus 4.0.1 → 4.1.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.0.1",
+  "version": "4.1.1",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -5,6 +5,175 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [4.1.1] - 2026-07-21
+
+### Fixed
+
+- **The integration tier is tested again, and now something actually watches it.** All 14
+  `tests/**/*.integration.test.js` files were unreachable from every gate — `jest.config.js` excludes
+  them from `npm test`, no workflow ran `npm run test:integration`, and the pre-push hook ran only the
+  unit suite. Six tests had been failing unnoticed behind a single dead model alias: three E2E suites
+  passed `--model gemini-flash`, which is not a live alias (`tryResolveModel('gemini-flash')` returns
+  `Unknown model alias`). They now pass `gemini`.
+- **`--claude-review` reports no longer grow a blank `claude` judge column, or a false self-vote `*`.**
+  `report.js`'s `toModel()` reused `verdict.council` (the street-cred universe, which legitimately
+  includes `claude` on a `--claude-review` run) as the adjudication-matrix judge roster too. Claude is
+  judged but never judges, so the matrix grew an extra column that always rendered blank, or a bare
+  `*` on a row Claude itself raised — asserting Claude voted for its own finding, the opposite of the
+  documented guarantee. `judges` is now filtered out of `council` independently (gated on the
+  `claudeInCouncil` flag plus the `claude` name, never on whether a model cast any adjudications, so a
+  genuinely dead/unstructured bench judge with zero votes still keeps its blank column).
+- **`debate-revote` now checkpoints `skipped`, not a false `complete`, when the re-vote wave never
+  launches** (nothing was defended/amended, or the cost ceiling skipped it). **This is a
+  consumer-visible `run.json` value change**: anything parsing `stages[].status` for this stage — the
+  Council Review Action's stage-ladder footer, `amicus status`, or a user script — now sees `skipped`
+  instead of `complete` on a run that hits this path. Neither the Action's footer nor `amicus
+  status`'s human/JSON renderers special-case `complete`, so both already print whatever value is
+  there correctly; a script that hard-coded an expectation of `complete` for this stage should treat
+  `skipped` as the equivalent no-op, the same way `run-chair.js`'s existing chair-skipped-over-budget
+  convention already works.
+- **`amicus council verdict --render` now writes `report.html` at `0o600`**, matching every sibling
+  writer (`run-assemble.js`, `mcp-server.js`'s `amicus_verdict` `render:true` path, `run-launch.js`).
+  It previously wrote with no explicit mode, which falls back to the process umask (typically `0o644`
+  on POSIX — group/world-readable) whenever the target directory had no pre-existing `report.html`,
+  i.e. exactly the fresh-`--out-dir` case, for a file that holds model output.
+- **Dropped the false `amicus wait` CLI claim.** `docs/usage.md` and `docs/council.md` both documented
+  `amicus status|wait|abort <councilRunId>` as working CLI commands. There is no CLI `wait` (verified
+  against `bin/amicus.js`'s command dispatch) — only `status` and `abort` genuinely resolve council
+  runs via the sessions-dir pointer file. Both docs now point readers at the MCP `amicus_wait` tool
+  instead.
+
+### Added
+
+- **Keyless integration job in CI.** `.github/workflows/ci.yml` gained an `integration` job that runs
+  `npm run test:integration` with no secrets on every push and PR, so the tier is permanently watched
+  for free (~51 assertions, ~10s). `npm run test:integration` now goes through
+  `scripts/run-integration-keyless.js`, which strips every provider credential and sandboxes
+  `HOME`/`USERPROFILE` before spawning jest — the money-spending suites self-skip and the script cannot
+  bill even on a machine with keys on disk. The scrub derives its key names from the engine's own
+  `PROVIDER_ENV_MAP`, so it covers providers and paid suites added later without maintenance.
+- **`npm run test:integration:live`** — the paid rail, split out so the CI job cannot silently start
+  billing if secrets are ever added to it. Run by the new `.github/workflows/integration-live.yml`
+  (`workflow_dispatch` only, carries `secrets.OPENROUTER_API_KEY`) and by the release checklist in
+  `docs/publishing.md`.
+
+### Fixed (docs)
+
+- `docs/testing.md` and `CLAUDE.md` both claimed a pre-push integration gate that has never existed;
+  the pre-push hook runs the unit suite only, deliberately, so a local push never spends money. Both
+  now describe the real rails, and `.husky/pre-push`'s stale "until the 'Fix integration tests' task
+  lands" comment is replaced with the reason the hook stays unit-only.
+- **`amicus doctor` no longer warns about Amicus's own shipped defaults — on a fresh install, and in
+  the keyless `model-drift.yml` CI check.** Both previously reported `⚠ Model aliases: 2 stale: opus,
+  haiku` (and the scheduled Model Drift Check ran red) with no user config involved.
+  `toDefaultAliases()` built each alias's pinned id by string-stripping the `openrouter/` prefix
+  instead of routing through the module's own `directFormFor()`, so it emitted OpenRouter's dot ids
+  for Anthropic — `anthropic/claude-opus-4.8`, `anthropic/claude-haiku-4.5` — which the direct API
+  rejects, and invented a bare `anthropic/claude-fable-5` for a model OpenRouter serves exclusively.
+  Defaults now come from `toGatewayRoutes()`, so an alias resolves to its authored direct form when
+  one exists (`anthropic/claude-opus-4-8`, `anthropic/claude-haiku-4-5-20251001`) and to its
+  OpenRouter route when none does (`openrouter/anthropic/claude-fable-5`). `fable`'s *recorded* form
+  changes, but this is **not a routing change** — OpenRouter was already the only gateway that serves
+  it, so a `fable` run resolves and routes identically before and after; only the id `doctor`/`amicus
+  models` display and compare against is different. Council artifacts are unaffected either way — they
+  record alias strings, not resolved ids.
+  - **This fix does not reach everyone who already ran `amicus setup`.** `createDefaultConfig()`
+    (`src/sidecar/setup.js`) persists the *entire* default alias map into `config.json` at setup time,
+    and `getEffectiveAliases()` lets that persisted user config win over the shipped defaults — so
+    anyone who ran `amicus setup` on Amicus ≤4.1.0 has the old, broken ids frozen on disk
+    (`source: user-config`), which `findStaleAliases()` never suppresses. Measured: such a user sees
+    **4 stale** aliases after upgrading to 4.1.1 — `opus`, `haiku`, `fable` (the pre-fix ids) plus
+    `gemini` (this release's own pin move, see Changed below) — not zero, and `amicus doctor` /
+    the Model Drift Check will keep warning for them. **There is no code fix for this in 4.1.1**; a
+    self-healing config migration is a 4.2 candidate. If `amicus doctor` still warns after upgrading,
+    re-run `amicus setup`, or fix individual aliases by hand, e.g.
+    `amicus setup --add-alias opus=anthropic/claude-opus-4-8`.
+- The offline Anthropic model floor now also lists `anthropic/claude-haiku-4-5-20251001`, the dated id
+  Anthropic's own listing returns. Without it, keyless and OpenRouter-only users saw the shipped
+  `haiku` default reported stale against the shipped floor.
+
+### Changed
+
+- **Curated `gemini` pin moves from Gemini 3.5 Flash to Gemini 3.6 Flash on both gateways.** This is a
+  **silent model change, not merely a drift-notice cleanup**: a user with no `gemini` alias override of
+  their own starts talking to a different underlying model the next time they use the `gemini` alias
+  after upgrading. It also clears the pinned-fallback drift notice from `amicus models --check`.
+
+## [4.1.0] - 2026-07-21
+
+The `second-opinion` skill stops hand-driving councils. Stages 1–3 and the Stage-5 artifacts
+collapse into a single `amicus council run`, leaving Claude only the stages that genuinely need
+judgement — intake, decisions, and lessons. The engine gains an optional rebuttal round so a
+finding's author can answer the reviewers who disputed it, and Claude can now enter its own review
+into the bundle without ever being launched as a model leg.
+
+### Added
+
+- **Skill fast path.** `skills/second-opinion/SKILL.md` now delegates Stages 1–3 (and the Stage-5
+  artifact materialization) to one `amicus council run` invocation; the human stages (0 intake,
+  4 decisions, 6 lessons) stay Claude-orchestrated. The manual mechanics are preserved verbatim in
+  the new `skills/second-opinion/MANUAL-ORCHESTRATION.md` as the documented fallback for when the
+  engine is unavailable or a case the fast path cannot express.
+- **Headless debate mode** — `amicus council run --debate` / `amicus_council_run {debate:true}`.
+  A Stage-2.5 rebuttal round runs between cross-review and the final tally: findings that came out
+  Contested or Disputed go back to the model that raised them, which defends, amends, or withdraws
+  each; the judges who disputed them then re-vote; a final tally folds the outcome in. Exactly one
+  round, structurally — there is no edge back into a debate stage. `run.json` gains an additive
+  `debate` summary, tally/verdict findings gain a `debate` decoration, and both report renderers
+  gain a "Debate round" section. The Council Review Action gains a `debate` input (default off),
+  and withdrawn findings are excluded from its PR annotations.
+- **`--claude-review <file>` / `claudeReviewFile`.** Enters Claude's own review as judged review
+  N+1 from a file. No model leg is ever launched for it and it may never chair — `claude` is a
+  reserved seat name that is rejected pre-flight in `--models`, `--chair` and `--critic` on such a
+  run.
+- **`--render` on `council verdict`, `render:true` on `amicus_verdict`.** Refreshes `report.html`
+  from the decided verdict. The MCP tool also returns the markdown rendering; it writes only when
+  an `outDir` inside the project is supplied, and its `readOnlyHint` is now correctly `false`.
+- **`--no-cost-gate` on `council run`.** Disables the per-leg price gate for the whole run —
+  repairs, chair chain and debate legs included — in one place instead of per invocation.
+
+### Fixed
+
+- **The Council Review Action no longer defaults to a bench that cannot lose a leg.** Its default
+  `models` were `deepseek,gemini,glm` with `deepseek` as chair; because the chair is excluded from
+  the bench, that left **two** seats against a quorum minimum of two, so one stalled leg failed the
+  entire review. The default is now four seats (`glm,qwen,minimax,qwen-coder`), leaving real slack.
+- **`postinstall` now installs `SEAT-BRIEFS.md`.** It shipped in the tarball but was never copied
+  into `~/.claude/skills/second-opinion/`, so the seat briefing reference has been missing from
+  every installation to date.
+- **`amicus council verdict` no longer discards the chair's verdict.** Writing the decided verdict
+  over the engine's one dropped `overallVerdict` to `null`, because the tally record it is built
+  from does not carry it. `runVerdict` now recovers it from the run folder — the engine's
+  `verdict.json` when present (guarded on `runId`, so a foreign file cannot inject another run's
+  verdict), otherwise by re-parsing `chair-output.md` with the engine's own chair parser. A run
+  whose chair was skipped still yields `null`; nothing is ever invented. `amicus_verdict` had the
+  same loss on the Cowork path and gains an explicit optional `overallVerdict` input, since the MCP
+  tool receives a record inline with no run folder to recover from.
+
+### Documentation
+
+- **The skill's Stage 4 and Stage 5 now name where finding claims actually live.** Both stages
+  instructed the reader to show each finding's claim while pointing only at `tally.json`, whose
+  findings carry tiers and adjudications but no `claim`. The claim and location live in
+  `tally-input.json`; both stages now state the join (on finding `id`) explicitly.
+
+### Changed
+
+- **`claude` can no longer be promoted as fallback chair on any run.** When a configured chair
+  dies, the engine promotes another model by reliability; `claude` is now excluded unconditionally.
+  This affects runs that never use `--claude-review`, because the reliability ledger has no way to
+  distinguish a file-sourced `claude` row from a real leg — and promoting it would select a chair
+  the engine cannot launch.
+- **`npm i -g amicus@4.1` rewrites the installed `SKILL.md`** to the fast path (existing
+  product-code overwrite policy). `MODEL-NOTES.md` remains machine-local and is never overwritten.
+  Rollback is a reinstall of 4.0.x.
+
+### Notes
+
+- All changes are additive: the council document family stays `schemaVersion: 2`, the MCP tool
+  count stays 15 (new inputs only), and a run using none of the new flags produces byte-identical
+  artifacts to 4.0.1. No migration is required.
+
 ## [4.0.1] - 2026-07-20
 
 Follow-up fixes to the v4.0.0 council engine: `amicus abort` and `amicus status` now see every

package/README.md

@@ -301,7 +301,7 @@ amicus update
 | `amicus spend` | Cross-run cost rollup from the spend ledger — total + per-model spend, tokens, and source mix, most-expensive first (`--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
 | `amicus key` | Manage API keys non-interactively: `amicus key <provider> <key>` saves after live validation; `--remove`; bare `amicus key` lists providers. |
 | `amicus council` | Council math: `tally <input.json>` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report <verdict.json> [--md\|--html]`, `validate <file>` (findings-block check, exit 0/2/1), `verdict <tally.json> [--decisions <d.json>] [-o <out.json>]` (build + write verdict.json). Presets: `save <name> --models a,b,c`, `list [--json]`, `show <name> [--json]` — see [The Council](#the-council) for the built-in `free`/`budget`/`frontier` benches. |
-| `amicus council run` | The headless council engine (v4.0): Stage-1 reviews → anonymized cross-review → deterministic tally → non-Claude chair verdict, in one command with no Claude runtime. Writes a run directory with `verdict.json` (including `overallVerdict`) and `report.html` — see [docs/council.md](./docs/council.md#amicus-council-run). |
+| `amicus council run` | The headless council engine: Stage-1 reviews → anonymized cross-review → deterministic tally → non-Claude chair verdict, in one command with no Claude runtime. Add `--debate` for a Stage-2.5 rebuttal round (raisers defend/amend/withdraw, disputing judges re-vote) and `--claude-review <file>` to enter Claude's own review as judged review N+1. Writes a run directory with `verdict.json` (including `overallVerdict`) and `report.html` — see [docs/council.md](./docs/council.md#amicus-council-run). |
 | `amicus abort` | Abort a running session (or `--all`). |
 | `amicus setup` | Configure default model, API keys, and aliases. |
 | `amicus update` | Update to the latest version. |
@@ -329,7 +329,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.0.1",
+  "version": "4.1.1",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -352,7 +352,7 @@ amicus models --search gemini # filter by substring
 
 ### Routing
 
-- **Bare `provider/model`** (e.g. `openai/gpt-5.5`, `anthropic/claude-opus-4.8`, `google/gemini-3.5-flash`) is the canonical, policy-routed form — Amicus routes it **direct-first**: your direct provider key when one is configured, falling back to OpenRouter automatically when only an OpenRouter key exists.
+- **Bare `provider/model`** (e.g. `openai/gpt-5.5`, `anthropic/claude-opus-4-8`, `google/gemini-3.6-flash`) is the canonical, policy-routed form — Amicus routes it **direct-first**: your direct provider key when one is configured, falling back to OpenRouter automatically when only an OpenRouter key exists.
 - **`openrouter/provider/model`** is an explicit override that always forces OpenRouter, even when a direct key is present — reach for it deliberately, or for gateway-only vendors with no direct integration (Qwen, Grok, Mistral, GLM, …).
 - **`--gateway auto|direct|openrouter`** (CLI, also on the MCP tools) overrides routing for one call; `auto` is the direct-first default. `routing.prefer` in `config.json` (`"direct"` by default, or `"openrouter"`) sets the global default.
 - **One-time migration notice:** if you hold both an OpenRouter key and a direct key for a vendor, the first launch that resolves to that vendor under **`auto`** routing (the default) prints a one-time notice that routing moved to direct API; set `routing.prefer: "openrouter"` to restore the old all-OpenRouter behavior. The notice never fires when you explicitly pass `--gateway direct` — that's your own choice, not a migration.
@@ -380,7 +380,7 @@ The MCP server is auto-registered on install (Claude Code and Claude Desktop / C
 | `amicus_fanout` | Launch a same-prompt wave; returns `{ waveId, taskIds[] }`. |
 | `amicus_council_tally` | Aggregate a council wave's reviews into a scored tally. |
 | `amicus_council_stats` | Reviewer-reliability stats from past council runs. |
-| `amicus_verdict` | Build the final council verdict from a tally + decisions. |
+| `amicus_verdict` | Build the final council verdict from a tally + decisions; writes `<outDir>/report.html` when `render:true` and `outDir` are given. |
 | `amicus_council_run` | Run the full headless council engine (Stage-1 reviews → anonymized cross-review → tally → chair verdict); returns `{ runId, runDir }`, async. |
 
 The async pattern is **start → status → read** — `amicus_start`/`amicus_fanout` return immediately, then you poll `amicus_status` and call `amicus_read`; `amicus_wait` collapses that poll loop into one blocking call.

package/commands/council.md

@@ -17,13 +17,13 @@ the **analysis request**, and the **criteria**. If any of the three is missing o
 ambiguous, ask for it before launching any model (the skill's Stage 0 covers this —
 don't re-ask for what is already present).
 
-Then follow the second-opinion skill end to end, in pipeline order: Stage 0
+Then follow the second-opinion skill's engine fast path, in pipeline order: Stage 0
 intake/prep and run-folder setup, then council selection with a cost estimate
-and explicit user confirmation; Stage 1 independent reviews, running
-`amicus council validate` on each leg's findings block as it lands; Stage 2
-cross-review, followed by `amicus council tally` once cross-review settles;
-Stage 3 council-chair synthesis; Stage 4 the accept/deny decision pass; and
-Stage 5, which runs `amicus council verdict` to write the final `verdict.json`.
+and explicit user confirmation; one `amicus council run` call — the engine runs
+validate, cross-review, tally, and chair internally, covering the Stage-1
+independent reviews through the Stage-3 chair synthesis with no Claude runtime
+in between; Stage 4, the accept/deny decision pass, once the run returns; and
+Stage 5, which runs `amicus council verdict` to write the decided `verdict.json`.
 
 The user may also name **optional council elements** in the arguments (critic seat,
 expert lenses, debate mode, verdict scale, Claude in the council). All elements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.0.1",
+  "version": "4.1.1",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [
@@ -49,7 +49,8 @@
   "scripts": {
     "start": "node --experimental-top-level-await --experimental-vm-modules bin/amicus.js",
     "test": "jest",
-    "test:integration": "jest --testPathIgnorePatterns='worktrees' --testMatch='**/tests/**/*.integration.test.js'",
+    "test:integration": "node scripts/run-integration-keyless.js",
+    "test:integration:live": "jest --testPathIgnorePatterns='worktrees' --testMatch='**/tests/**/*.integration.test.js'",
     "test:all": "jest --testPathIgnorePatterns='/node_modules/' --testPathIgnorePatterns='worktrees' && node scripts/mark-test-passed.js",
     "test:e2e:mcp": "jest tests/mcp-repomix-e2e.integration.test.js --testTimeout=180000 --forceExit",
     "posttest": "node scripts/mark-test-passed.js",

package/schemas/council-run.schema.json

@@ -33,6 +33,20 @@
     "labelMap": { "type": ["object", "null"], "additionalProperties": { "type": "string" } },
     "options": { "type": "object" },
     "usage": { "type": "object" },
-    "exitCode": { "type": ["number", "null"] }
+    "exitCode": { "type": ["number", "null"] },
+    "debate": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "outcome": { "enum": ["ran", "nothing-to-debate", "skipped-cost-ceiling"] },
+        "contested": { "type": "integer" }, "disputed": { "type": "integer" },
+        "defended": { "type": "integer" }, "amended": { "type": "integer" },
+        "withdrawn": { "type": "integer" }, "noResponse": { "type": "integer" },
+        "revoteJudges": { "type": "integer" }, "revoteApplied": { "type": "integer" },
+        "verdictChanges": { "type": "integer" }
+      },
+      "required": ["enabled"],
+      "additionalProperties": false
+    }
   }
 }

package/schemas/council-tally.schema.json

@@ -51,7 +51,16 @@
           },
           "confidence": { "enum": ["thin", "solid"] },
           "tierOverride": { "type": ["object", "null"] },
-          "adjudications": { "type": "array", "items": { "type": "object" } }
+          "adjudications": { "type": "array", "items": { "type": "object" } },
+          "debate": {
+            "type": "object",
+            "properties": {
+              "action": { "enum": ["defended", "amended", "withdrawn", "no-response"] },
+              "previousTier": { "type": ["string", "null"] }
+            },
+            "required": ["action"],
+            "additionalProperties": false
+          }
         }
       }
     },

package/schemas/council-verdict.schema.json

@@ -36,7 +36,16 @@
           "duplicateOf": { "type": ["string", "null"] },
           "adjudications": { "type": "array" },
           "decision": { "type": ["string", "null"] },
-          "applied": { "type": "boolean" }
+          "applied": { "type": "boolean" },
+          "debate": {
+            "type": "object",
+            "properties": {
+              "action": { "enum": ["defended", "amended", "withdrawn", "no-response"] },
+              "previousTier": { "type": ["string", "null"] }
+            },
+            "required": ["action"],
+            "additionalProperties": false
+          }
         }
       }
     },

package/schemas/error.schema.json

@@ -13,7 +13,7 @@
       "type": "object",
       "required": ["code", "message"],
       "properties": {
-        "code": { "enum": ["BAD_ARGS", "MISSING_PROMPT", "BAD_MODEL", "MISSING_KEY", "BAD_SESSION", "BUDGET_EXCEEDED", "INTERNAL"] },
+        "code": { "enum": ["BAD_ARGS", "MISSING_PROMPT", "BAD_MODEL", "MISSING_KEY", "BAD_SESSION", "BUDGET_EXCEEDED", "INTERNAL", "COUNCIL_QUORUM", "COST_EXCEEDED", "COUNCIL_CLAUDE_REVIEW_INVALID"] },
         "message": { "type": "string" },
         "hint": { "type": ["string", "null"] },
         "command": { "type": ["string", "null"] }

package/scripts/postinstall.js

@@ -25,12 +25,15 @@ const PROVISION_TIMEOUT_MS = 15000;
 const SKILL_SOURCE = path.join(__dirname, '..', 'skills', 'sidecar', 'SKILL.md');
 const COUNCIL_SOURCE_DIR = path.join(__dirname, '..', 'skills', 'second-opinion');
 
-/** Council files + per-file install semantics: SKILL/COUNCIL-DESIGN are product code
- * (overwrite on update); MODEL-NOTES is user data — its reviewer-reliability table evolves
- * per-run, so it is seeded once and never clobbered. */
+/** Council files + per-file install semantics: SKILL/COUNCIL-DESIGN/SEAT-BRIEFS are
+ * product code (overwrite on update, so upgrades keep them in sync with the package);
+ * MODEL-NOTES is user data — its reviewer-reliability table evolves per-run, so it is
+ * seeded once and never clobbered. */
 const COUNCIL_FILES = [
   { file: 'SKILL.md', mode: 'overwrite' },
   { file: 'COUNCIL-DESIGN.md', mode: 'overwrite' },
+  { file: 'SEAT-BRIEFS.md', mode: 'overwrite' },
+  { file: 'MANUAL-ORCHESTRATION.md', mode: 'overwrite' },
   { file: 'MODEL-NOTES.md', mode: 'if-missing' },
 ];
 

package/skills/second-opinion/COUNCIL-DESIGN.md

@@ -36,6 +36,10 @@ non-Claude chairman + per-model inspectable artifacts.
   is now engine-native — each review wave is ONE `amicus fanout --json` call returning structured
   run documents — but scoring, tallying, anonymization, and synthesis remain Claude's manual work.
   No backend, no parsing code beyond reading JSON fields. Deterministic arithmetic/formatting/schema helpers under `amicus council` (findings validation, tier tally, street-cred, ledger) are sanctioned; judgment, synthesis, anonymization, and de-anonymization remain Claude's inline work.
+  _(v4.1 annotation — superseded by the engine in the fast path: `amicus council run` now performs
+  the anonymization, scoring, tallying, and chair-dispatch steps above headlessly, with no Claude
+  runtime in the loop. This v3 note remains an accurate historical record of the design this repo
+  shipped from v3 through v4.0's manual path; see §13.)_
 
 ## 3. What changes vs. v1
 
@@ -156,6 +160,9 @@ The cross-review matrix shows both; the ledger and Stage-0 bench recommendations
 - Default: Claude **recommends a non-Claude chair** from the council each run (often the
   strongest reasoner / best reviewer-reliability) and the user confirms at launch.
 - The chair **may** also be a Stage-1 council member (it sees the anonymized bundle + scores).
+  _(v4.1 annotation: the engine fast path's `amicus council run` rejects this — the chair must
+  NOT be a bench seat, checked pre-flight, exit 1 before any spend. This flexibility survives only
+  in the manual path; see `MANUAL-ORCHESTRATION.md` and §13.)_
 - **Fallback order if the chair fails:** re-run → promote next-best council model →
   **Claude chairs only as last resort, with explicit disclosure** that the verdict is no longer
   fully independent.
@@ -291,3 +298,36 @@ The debate agent's parallel-panels + cross-panel synthesis maps to two full coun
 different benches or lens-sets plus a super-chair synthesis of where the panels agree,
 disagree, and what each missed. Deferred: cost doubles and the run-folder conventions need
 namespacing. Revisit if lens runs prove valuable.
+
+## 13. v4.1 — the engine fast path
+
+`amicus council run` (v4.0; extended in v4.1 with `--debate`, `--claude-review`, and `council
+verdict --render`) is the **headless realization of Stages 1–3 plus the Stage-5 deterministic
+artifacts** described above: the Stage-1 review wave, per-leg findings validation and bounded
+repair, anonymization and run-global finding-id rewriting, the identical judge bundle, the
+Stage-2 cross-review wave, the optional Stage-2.5 debate round (§12.3), the tally, the chair
+synthesis, and the deterministic `verdict.json` (undecided) + `report.html` — all as **one
+command with no Claude runtime** in the loop. `SKILL.md`'s engine fast path drives this directly.
+The hand-driven Stage 1 → 2 → 3 waves this document describes above remain available as
+`MANUAL-ORCHESTRATION.md` — the fallback for the engine being unavailable/misbehaving, a fully
+custom per-seat brief beyond `--critic`/`--lenses`, or deliberate mid-stage inspection.
+
+**Stage 4 stays human, always.** The engine is report-only: `amicus council run` never
+fabricates an accept/deny decision. Claude still drives Stage 4 (§4) and finalizes the verdict via
+`amicus council verdict --decisions <decisions.json> --render` (§4, Stage 5) — the fast path
+changes the *transport* for Stages 1–3 plus the Stage-5 artifacts, not the decision authority of
+Stage 4.
+
+**§12.4 (chair verdict scale) is standard-on in the fast path.** What was an opt-in menu item in
+the manual path is now baked into `amicus council run`'s chair packet unconditionally — every
+headless chair closes with the hard questions and a parseable `VERDICT:` line, surfaced as
+`overallVerdict` in `verdict.json`. There is no toggle for it on the engine path; it is always on.
+
+**§12.3 (debate mode) headless realization: `--debate` on `council run`.** The Stage-2.5 rebuttal
+round described in §12.3 is implemented headlessly in `src/council/run-debate.js`
+(orchestration) + `src/council/debate.js` (pure tally-input reassembly) +
+`src/council/briefings-debate.js` (rebuttal/re-vote prompt templates) — same mechanics, same
+exactly-one-round rule, same withdrawn-findings-auto-denied outcome (§12.3), now driven by the
+engine instead of Claude's hand-launched solos/waves. The round's summary lands in `run.json`'s
+`debate` object and each affected finding's `findings[].debate` decoration — see
+[docs/council.md](../../docs/council.md) for the field-by-field reference.