amicus 3.2.3 → 4.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "3.2.3",
+  "version": "4.0.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,69 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-07-20
+
+The **headless council engine** release. `amicus council run` (CLI) and `amicus_council_run`
+(MCP) execute the full adjudicated pipeline — Stage-1 independent reviews → anonymized peer
+cross-review → deterministic tally → non-Claude chair verdict — with **no Claude runtime**,
+reusing the existing pure primitives (`validateFindings`, `tally`, `buildVerdict`, the report
+renderers, the ledger) under a run-directory state machine. On top of it, the **Council Review
+GitHub Action v2** posts a real adjudicated verdict on labeled PRs (check run + annotations,
+sticky comment, evidence artifact, opt-in gating). The major bump exists for the three trust
+changes below — see **Migration**.
+
+### Migration (v3 → v4)
+
+| v3 behavior | v4 behavior / remedy |
+| --- | --- |
+| MCP council tools (`amicus_council_tally`, `amicus_council_stats`, `amicus_verdict`) returned **bare JSON** tool text | Their JSON is now wrapped in the `<untrusted_sidecar_output>` fence (same mechanism as `amicus_read`), and the new `amicus_council_run` returns fenced text too. MCP consumers that parse the tool text must unwrap the fence first; the JSON inside is byte-intact. **CLI `--json` output is unchanged and stays the byte-stable programmatic channel.** |
+| `amicus council stats --json` printed a **bare array** of per-model rows | It now prints `{"schemaVersion": 2, "type": "council-stats", "models": [...]}` — the one breaking shape change in the envelope unification. Update scripts to read `.models`. Every other envelope change is additive (`schemaVersion`/`type` injected onto existing docs; council family bumps 1 → 2; `verdict.json` gains nullable `overallVerdict`). |
+| Some `--json` failure paths printed **plain text on stderr** (no model configured, model-selection cancelled, route errors, `status` with a missing/invalid task id; MCP validation/route errors as unstructured text) | Under `--json` these now emit the standard **error envelope on stdout** with the documented exit codes; MCP error text is error-doc-shaped (`{schemaVersion, type: "error", ...}`). Scripts that scraped stderr strings must read the stdout envelope. Human-mode (no `--json`) stderr behavior is unchanged. |
+| Bare `[SIDECAR_FOLD]` markers were still written/parsed on legacy internal paths | The fold marker is **nonce-required** end to end: the bare literal survives only as the prefix inside the nonced form, resume replay strips residual fold-marker lines, and the internal legacy bare-marker finder/writer fallbacks are removed (`docs/SHIMS.md` updated). Wire-format consumers of the **nonced** form are unaffected. |
+| Council Review Action v1 (fanout + synthesis; `max_cost` default `1.00`) | Action v2 runs `amicus council run` and posts an adjudicated verdict. `workflow_call` callers: new optional inputs `chair` (default `deepseek`), `critic`, `fail_on` (`none`\|`fix`\|`rethink`, default `none` = report-only); **`max_cost` default is now `2.00`** (a council is ~2 waves + chair + repairs vs v1's wave + synthesis) — pass `max_cost: '1.00'` explicitly to keep the old ceiling. `models`/`require_label`/secrets semantics unchanged. A chair listed in `models` is excluded from the bench at run time (the engine requires the chair not to be seated). |
+
+### Added
+
+- **`amicus council run`** — the headless council engine (CLI): `--prompt-file` briefing,
+  `--models`/`--council` bench (≥2 seats), `--chair` (default `deepseek`, never a bench seat),
+  optional `--critic` / `--lenses` (mutually exclusive), whole-run `--max-cost`, per-leg
+  `--timeout`, durable `--out-dir` run directory (`review-*.md`, `bundle-stage2.md`,
+  `judge-*.md`, `chair-output.md`, `tally-input.json`, `tally.json`, `verdict.json` with
+  **`overallVerdict`**, `report.html`, `run.json`), exit contract `0` full / `2` degraded /
+  `1` failed, SIGINT/SIGTERM finalization, and `status`/`wait`/`list`/`abort` integration via a
+  sessions-dir pointer file. Stage 4 stays human: the engine is report-only.
+- **`amicus_council_run`** MCP tool (15th tool): briefing-via-file like `amicus_fanout`, returns
+  `{runId, runDir}` immediately (async).
+- **Council Review GitHub Action v2** (`.github/workflows/council-review.yml`): adjudicated
+  verdict as a **check run** ("Council Review") with Confirmed-finding annotations (best-effort
+  `file:line` parse, 50-per-request chunking, file-level fallback, unmapped findings listed in
+  the summary), **sticky comment v2** (chair verdict line, tier table, per-tier lists,
+  street-cred table, cost line, artifact link), **evidence artifact** (the full run directory),
+  and opt-in gating via `fail_on`. Label gate, fork soft-skip, no-checkout, and the duplicated
+  `neutralize()` rules carry forward from v1.
+- **Published JSON Schemas** (`schemas/`, draft 2020-12, one file per doc type) shipped in the
+  npm tarball and documented in `docs/schemas.md`; every builder's real output is
+  schema-validated in tests (ajv as a devDependency only).
+- `docs/council.md` § `amicus council run` (headless reference), usage.md/README coverage, and a
+  headless-context pointer in the `second-opinion` skill.
+
+### Changed
+
+- **Unified JSON envelope convention:** every emitted doc carries `{schemaVersion, type}`; the
+  council family bumps **1 → 2** (additive fields, no re-nesting); `council validate --json`
+  gains the envelope fields; CLI `status --json` gains `schemaVersion`; MCP success returns get
+  `schemaVersion`/`type` injected additively. Ledger JSONL stays internal at v1 (documented
+  exclusion). Interactive-only commands (`setup`, `update`, `key`) are documented envelope
+  exclusions.
+- `--json` failure paths routed through the error envelope on stdout (see Migration).
+- MCP council-tool JSON is fenced with `<untrusted_sidecar_output>` (see Migration);
+  `untrusted-fence.js`'s module doc and the skill's Cowork-transport note updated to match.
+
+### Removed
+
+- The legacy bare fold-marker internals: `findLegacyBareTrailingMarker` and the bare-writer
+  fallback in `formatFoldOutput` (`nonce` is now a required argument). See Migration.
+
 ## [3.2.3] - 2026-07-18
 
 ### Fixed

package/README.md

@@ -227,6 +227,15 @@ Then the council waits for your confirmation.
 
 The skill lives at **[`skills/second-opinion/SKILL.md`](./skills/second-opinion/SKILL.md)**; the design spec behind it is **[`skills/second-opinion/COUNCIL-DESIGN.md`](./skills/second-opinion/COUNCIL-DESIGN.md)**. For what `amicus council tally|verdict|report|stats` actually take as input and produce — field-by-field schemas, verdict.json's provenance, and a full worked example run against the real CLI — see **[docs/council.md](./docs/council.md)**.
 
+**Headless council (CI).** The same pipeline runs with no Claude runtime at all: `amicus council
+run --prompt-file briefing.md --models gemini,glm --chair deepseek --json` executes the review
+waves, the anonymized cross-review, the tally, and the chair verdict in one command, and writes
+the full run directory (`verdict.json` with the chair's parsed `overallVerdict`, `report.html`,
+every review and judge output). That is what powers the repo's own **Council Review GitHub Action
+v2** — on PRs labeled `council-review` it posts an adjudicated verdict as a check run plus a
+sticky comment, uploads the run directory as an evidence artifact, and can optionally gate merges
+via its `fail_on` input (default: report-only). Reference: [docs/council.md](./docs/council.md#amicus-council-run).
+
 **Free council (zero-cost).** Want the cross-examination without the model spend? `amicus setup` offers a **Free OpenRouter council** mode — readline wizard option 2, and the Electron **Models** step. It detects the free `:free` models live from the catalog, lets you multi-pick (Enter takes a vendor-diverse default), and saves them as `councils.free` — a first-class `councils` config primitive seeded under collision-safe `free-*` aliases. Your `config.default` is left untouched, and all you need is an `OPENROUTER_API_KEY`.
 
 Run it anywhere a council runs:
@@ -292,6 +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 abort` | Abort a running session (or `--all`). |
 | `amicus setup` | Configure default model, API keys, and aliases. |
 | `amicus update` | Update to the latest version. |
@@ -319,7 +329,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "3.2.3",
+  "version": "4.0.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -353,7 +363,7 @@ Full details, the API-key/prefix table, and the migration notice are in **[docs/
 
 ## MCP integration
 
-The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes fourteen tools:
+The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes fifteen tools:
 
 | Tool | What it does |
 |------|--------------|
@@ -371,6 +381,7 @@ The MCP server is auto-registered on install (Claude Code and Claude Desktop / C
 | `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_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.
 
@@ -400,7 +411,7 @@ With `--json`, Amicus emits stable, versioned run/wave documents on stdout — b
 }
 ```
 
-The wave-document shape (for `fanout`), field meanings, and the full exit-code table are in **[docs/usage.md § JSON Output](./docs/usage.md#json-output)**.
+The wave-document shape (for `fanout`), field meanings, and the full exit-code table are in **[docs/usage.md § JSON Output](./docs/usage.md#json-output)**. Every `--json` document also has a published JSON Schema — see **[docs/schemas.md](./docs/schemas.md)** (shipped in the npm tarball under `schemas/`).
 
 ---
 
@@ -450,6 +461,7 @@ LOG_LEVEL=debug amicus start --model gemini --prompt "test" --no-ui
 |-----|-------------|
 | [docs/usage.md](./docs/usage.md) | The complete CLI & MCP reference — every flag, every subcommand, every example. |
 | [docs/council.md](./docs/council.md) | Council pipeline reference: `tally`/`verdict`/`report` schemas, provenance, and a worked example. |
+| [docs/schemas.md](./docs/schemas.md) | Published JSON Schemas for every `--json` document (result + council families). |
 | [docs/configuration.md](./docs/configuration.md) | Full configuration and environment reference. |
 | [docs/architecture.md](./docs/architecture.md) | How the engine, Electron shell, and context sharing fit together. |
 | [docs/opencode-integration.md](./docs/opencode-integration.md) | How Amicus drives the OpenCode runtime. |

package/electron/main.js

@@ -74,7 +74,10 @@ const WINDOW_POSITION = process.env.AMICUS_WINDOW_POSITION || 'right';
 // 15b.3: per-run fold nonce (#BL-7 residual). Set by the interactive launcher
 // (src/sidecar/interactive-process.js buildElectronEnv) from the SAME value
 // baked into the system prompt's fold instruction. undefined when a launcher
-// predates this env var — fold.js falls back to the legacy bare marker.
+// predates this env var — fold.js then falls back to a freshly generated nonce
+// (createFoldHandler: `state.nonce || generateFoldNonce()`), NOT the legacy bare
+// marker. That's safe here because the GUI fold write is exit-code driven, not
+// marker-detected, so an un-advertised fallback nonce can't be exploited.
 const FOLD_NONCE = process.env.AMICUS_FOLD_NONCE;
 
 const OPENCODE_URL = `http://localhost:${OPENCODE_PORT}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "3.2.3",
+  "version": "4.0.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": [
@@ -37,6 +37,7 @@
   "files": [
     "bin/",
     "src/",
+    "schemas/",
     "electron/",
     "skills/",
     "commands/",
@@ -83,6 +84,7 @@
     "electron": "^43.1.1"
   },
   "devDependencies": {
+    "ajv": "^8.20.0",
     "chrome-remote-interface": "^0.33.3",
     "eslint": "^8.0.0",
     "jest": "^29.0.0",

package/schemas/abort.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/abort.schema.json",
+  "title": "amicus abort result document",
+  "description": "`abort <taskId|--all> --json` result.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "ok", "scope", "aborted", "count"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "abort" },
+    "ok": { "type": "boolean" },
+    "scope": { "enum": ["session", "wave", "all", "council-run"] },
+    "taskId": { "type": ["string", "null"] },
+    "aborted": { "type": "array", "items": { "type": "string" } },
+    "count": { "type": "number" }
+  }
+}

package/schemas/alias-audit.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/alias-audit.schema.json",
+  "title": "amicus alias-audit document",
+  "description": "`models --check --json` result.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "catalogAvailable", "staleCount", "stale"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "alias-audit" },
+    "catalogAvailable": { "type": "boolean" },
+    "staleCount": { "type": "number" },
+    "stale": { "type": "array", "items": { "type": "object" } },
+    "gatewayFindingsCount": { "type": "number" },
+    "gatewayFindings": { "type": "array", "items": { "type": "object" } }
+  }
+}

package/schemas/council-run.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/council-run.schema.json",
+  "title": "amicus council-run manifest",
+  "description": "Headless council run manifest (run.json, spec 2026-07-19 §4). Authored ahead of the engine (v4.0 Plan B) — the run-state writer must satisfy this schema.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "runId", "status", "stages", "bench", "chair"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "council-run" },
+    "runId": { "type": "string" },
+    "status": { "type": "string" },
+    "stages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "status"],
+        "properties": {
+          "name": { "type": "string" },
+          "status": { "type": "string" },
+          "startedAt": { "type": ["string", "null"] },
+          "completedAt": { "type": ["string", "null"] },
+          "waveId": { "type": "string" },
+          "taskIds": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "bench": { "type": "array", "items": { "type": "string" } },
+    "chair": { "type": "string" },
+    "critic": { "type": ["string", "null"] },
+    "lenses": { "type": ["array", "null"], "items": { "type": "string" } },
+    "labelMap": { "type": ["object", "null"], "additionalProperties": { "type": "string" } },
+    "options": { "type": "object" },
+    "usage": { "type": "object" },
+    "exitCode": { "type": ["number", "null"] }
+  }
+}

package/schemas/council-stats.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/council-stats.schema.json",
+  "title": "amicus council-stats document",
+  "description": "Ledger-derived reviewer reliability (`council stats --json`, amicus_council_stats). v2 wraps the pre-4.0 bare array in {schemaVersion, type, models} — THE one breaking council shape change.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "models"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "council-stats" },
+    "models": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["model", "runs", "lowN"],
+        "properties": {
+          "model": { "type": "string" },
+          "runs": { "type": "number" },
+          "lowN": { "type": "boolean" },
+          "avgStreetCredPeersOnly": { "type": ["number", "null"] },
+          "lifetimeConfirmRate": { "type": ["number", "null"] },
+          "lifetimeFactErrorRate": { "type": ["number", "null"] },
+          "conformance": { "type": "object" }
+        }
+      }
+    }
+  }
+}

package/schemas/council-tally.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/council-tally.schema.json",
+  "title": "amicus council-tally document",
+  "description": "Deterministic council tally (`council tally --json`, amicus_council_tally). Council family v2.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "meta", "judged", "streetCred", "findings", "runStats", "tierCounts"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "council-tally" },
+    "meta": {
+      "type": "object",
+      "required": ["runId", "models"],
+      "properties": {
+        "runId": { "type": "string" },
+        "runType": { "type": "string" },
+        "date": { "type": "string" },
+        "models": { "type": "array", "items": { "type": "string" } },
+        "chair": { "type": ["string", "null"] },
+        "claudeInCouncil": { "type": "boolean" }
+      }
+    },
+    "judged": { "type": "boolean" },
+    "streetCred": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["model"],
+        "properties": {
+          "model": { "type": "string" },
+          "withSelf": { "type": ["number", "null"] },
+          "peersOnly": { "type": ["number", "null"] },
+          "perJudgeRank": { "type": "object" }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "tier", "basis", "confidence"],
+        "properties": {
+          "id": { "type": "string" },
+          "raiser": { "type": ["string", "null"] },
+          "severity": { "type": ["string", "null"] },
+          "tier": { "enum": ["Confirmed", "Contested", "Singleton", "Disputed"] },
+          "basis": {
+            "type": "object",
+            "required": ["a", "d", "n"],
+            "properties": { "a": { "type": "number" }, "d": { "type": "number" }, "n": { "type": "number" } }
+          },
+          "confidence": { "enum": ["thin", "solid"] },
+          "tierOverride": { "type": ["object", "null"] },
+          "adjudications": { "type": "array", "items": { "type": "object" } }
+        }
+      }
+    },
+    "runStats": { "type": "array", "items": { "type": "object" } },
+    "tierCounts": {
+      "type": "object",
+      "required": ["Confirmed", "Contested", "Singleton", "Disputed"],
+      "properties": {
+        "Confirmed": { "type": "number" },
+        "Contested": { "type": "number" },
+        "Singleton": { "type": "number" },
+        "Disputed": { "type": "number" }
+      }
+    }
+  }
+}

package/schemas/council-validate.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/council-validate.schema.json",
+  "title": "amicus council-validate document",
+  "description": "Stage-1 findings validation (`council validate --json`). Tri-state exit: 0 ok, 2 parsed-but-invalid, 1 BAD_ARGS error doc.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "ok", "findings", "errors"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "council-validate" },
+    "ok": { "type": "boolean" },
+    "findings": { "type": "array", "items": { "type": "object" } },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["code", "detail"],
+        "properties": { "code": { "type": "string" }, "detail": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/council-verdict.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/council-verdict.schema.json",
+  "title": "amicus council-verdict document",
+  "description": "Verdict record (`council verdict --json`, amicus_verdict, verdict.json). overallVerdict is the chair's parsed VERDICT line — null in every Stage-4 manual path, populated by the headless engine.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "runId", "council", "overallVerdict", "findings", "streetCred", "runStats", "tierCounts"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "council-verdict" },
+    "runId": { "type": "string" },
+    "runType": { "type": ["string", "null"] },
+    "date": { "type": ["string", "null"] },
+    "chair": { "type": ["string", "null"] },
+    "council": { "type": "array", "items": { "type": "string" } },
+    "claudeInCouncil": { "type": "boolean" },
+    "overallVerdict": {
+      "oneOf": [
+        { "enum": ["Ship it", "Fix these first", "Fundamental rethink"] },
+        { "type": "null" }
+      ]
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "tier", "decision", "applied"],
+        "properties": {
+          "id": { "type": "string" },
+          "raiser": { "type": ["string", "null"] },
+          "severity": { "type": ["string", "null"] },
+          "tier": { "enum": ["Confirmed", "Contested", "Singleton", "Disputed"] },
+          "basis": { "type": "object" },
+          "confidence": { "enum": ["thin", "solid"] },
+          "tierOverride": { "type": ["object", "null"] },
+          "duplicateOf": { "type": ["string", "null"] },
+          "adjudications": { "type": "array" },
+          "decision": { "type": ["string", "null"] },
+          "applied": { "type": "boolean" }
+        }
+      }
+    },
+    "streetCred": { "type": "array", "items": { "type": "object" } },
+    "runStats": { "type": "array", "items": { "type": "object" } },
+    "tierCounts": { "type": "object" }
+  }
+}

package/schemas/doctor.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/doctor.schema.json",
+  "title": "amicus doctor document",
+  "description": "`doctor --json` health-check result.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "ok", "version", "timestamp", "checks"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "doctor" },
+    "ok": { "type": "boolean" },
+    "version": { "type": "string" },
+    "timestamp": { "type": "string" },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "status"],
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "status": { "type": "string" },
+          "message": { "type": ["string", "null"] },
+          "hint": { "type": ["string", "null"] }
+        }
+      }
+    }
+  }
+}

package/schemas/error.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/error.schema.json",
+  "title": "amicus error document",
+  "description": "Structured failure envelope: every pre-flight/validation/route failure under --json (stdout) and every MCP error tool-text.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "ok", "error"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "error" },
+    "ok": { "const": false },
+    "error": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "enum": ["BAD_ARGS", "MISSING_PROMPT", "BAD_MODEL", "MISSING_KEY", "BAD_SESSION", "BUDGET_EXCEEDED", "INTERNAL"] },
+        "message": { "type": "string" },
+        "hint": { "type": ["string", "null"] },
+        "command": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/schemas/model-catalog.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/model-catalog.schema.json",
+  "title": "amicus model-catalog document",
+  "description": "`models [--search|--refresh] --json` result.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "count", "models"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "model-catalog" },
+    "fetchedAt": { "type": ["number", "null"] },
+    "refreshed": { "type": "boolean" },
+    "search": { "type": ["string", "null"] },
+    "count": { "type": "number" },
+    "models": { "type": "array", "items": { "type": "object" } },
+    "lastRefreshAttempt": { "type": ["number", "null"] },
+    "lastRefreshError": { "type": ["string", "null"] }
+  }
+}

package/schemas/run.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/run.schema.json",
+  "title": "amicus run result document",
+  "description": "Single-session result (`start|read|resume|continue --json`; every wave leg). Fields are only ADDED within a schemaVersion.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "taskId", "status"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "run" },
+    "taskId": { "type": "string" },
+    "waveId": { "type": ["string", "null"] },
+    "model": { "type": ["string", "null"] },
+    "modelInput": { "type": ["string", "null"] },
+    "agent": { "type": ["string", "null"] },
+    "status": { "type": "string" },
+    "summary": { "type": ["string", "null"] },
+    "error": { "type": ["string", "null"] },
+    "createdAt": { "type": ["string", "null"] },
+    "completedAt": { "type": ["string", "null"] },
+    "durationMs": { "type": ["number", "null"] },
+    "sessionDir": { "type": ["string", "null"] },
+    "opencodeSessionId": { "type": ["string", "null"] },
+    "usage": { "type": ["object", "null"] }
+  }
+}

package/schemas/spend.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/BourbonDog/amicus/main/schemas/spend.schema.json",
+  "title": "amicus spend document",
+  "description": "`spend --json` aggregation.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "total", "byModel"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "type": { "const": "spend" },
+    "windowDays": { "type": ["number", "null"] },
+    "total": { "type": "object" },
+    "byModel": { "type": "array", "items": { "type": "object" } },
+    "credit": { "type": ["object", "null"] }
+  }
+}

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.