amicus 4.0.0 → 4.1.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "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,124 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [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
+sub-wave a stage launched, a council run that dies before its first checkpoint is recoverable
+instead of stranded, and neither command can be thrown by a malformed wave record.
+
+### Fixed
+
+- **`amicus abort` now cascades to every in-flight council leg, not just the primary wave of
+  each stage.** A stage can own several sub-waves — the chair's `ch1..ch4` retry/fallback/repair
+  chain, one solo per lens, a critic solo beside the seat wave, and the bounded Stage-1/Stage-2
+  repair re-prompts — but only a single `waveId` was recorded per stage (and the chair stage
+  recorded none at all), so the targeted cascade skipped those legs and left them to the
+  `waitThenKill` process-tree fallback. They were still killed, so this was never a leak or a
+  hang; what was lost were the per-leg `aborted` markers, an accurate `legsAborted` count, and a
+  faithful per-stage audit trail in `run.json`. Stage entries now carry a `waveIds` array
+  recording every sub-wave at launch time (documented in `schemas/council-run.schema.json`), and
+  the cascade targets the union of `waveId` + `waveIds`. In lens mode `stage1` previously
+  advertised only a phantom `-s1` wave that never launches, so *no* Stage-1 leg was reachable;
+  lens runs no longer record that `waveId` at all.
+- **`amicus status` now rolls up council legs across every sub-wave of the active stage.** It
+  counted only the stage's primary `waveId`, so a lens run — which has no seat wave — always
+  reported `legsTotal: null`, and a run with a critic omitted the critic's leg from the count
+  (e.g. `2` instead of `3` for two seats plus a critic). Note that `legsTotal` can now rise
+  mid-stage when a bounded repair re-prompt launches, which is a real additional model call.
+- **A council run spawned through `amicus_council_run` that died before its first checkpoint no
+  longer strands an unrecoverable record.** The MCP handler wrote `run.json` with
+  `status: "running"` and no `pid`, leaving the spawned CLI child to record its own pid at
+  startup; a child that died inside that window left a pid-less `running` run that `amicus
+  status` skipped entirely (its crash detection is guarded on `run.pid`) and that `amicus abort`
+  could not fall back to killing, so the run was recoverable only by hand. The handler now
+  captures the pid from the spawned child and checkpoints it immediately — the same value the
+  engine writes itself, recorded a beat earlier. The pid is written to its own
+  `spawn.pid` file rather than patched into `run.json`: the spawning process and the engine
+  child both write `run.json`, and `checkpoint` is a read-merge-write with no cross-process
+  lock, so a pid patch could clobber (or be clobbered by) the child's first checkpoint. Readers
+  prefer `run.json`'s own pid and fall back to `spawn.pid`.
+- **A malformed wave `metadata.json` no longer throws out of `amicus status` or `amicus abort`.**
+  `countWaveLegs` and `cascadeWave` both assumed the `legs` field was an array if it was present
+  at all, so a half-written or hand-edited record raised a `TypeError` past its caller. Both now
+  treat a non-array `legs` as no legs. `cascadeWave`'s wave-level abort mark is also guarded, so
+  a failure there can no longer discard the count of legs it had already marked.
+
 ## [4.0.0] - 2026-07-20
 
 The **headless council engine** release. `amicus council run` (CLI) and `amicus_council_run`

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.0",
+  "version": "4.1.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -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.0",
+  "version": "4.1.0",
   "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": [

package/schemas/council-run.schema.json

@@ -21,6 +21,7 @@
           "startedAt": { "type": ["string", "null"] },
           "completedAt": { "type": ["string", "null"] },
           "waveId": { "type": "string" },
+          "waveIds": { "type": "array", "items": { "type": "string" } },
           "taskIds": { "type": "array", "items": { "type": "string" } }
         }
       }
@@ -32,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.