amicus 1.1.0 → 1.2.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "bourbondog-amicus",
+  "owner": { "name": "Christian Wagner", "url": "https://github.com/BourbonDog" },
+  "metadata": { "description": "Amicus — multi-model LLM Council + parallel AI window for Claude Code." },
+  "plugins": [
+    {
+      "name": "amicus",
+      "source": "./",
+      "description": "Multi-model LLM Council + parallel AI window. 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" },
+      "keywords": ["claude-code", "multi-model", "llm", "council", "second-opinion"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "amicus",
+  "version": "1.2.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" },
+  "homepage": "https://bourbondog.github.io/amicus/",
+  "repository": "https://github.com/BourbonDog/amicus",
+  "bugs": "https://github.com/BourbonDog/amicus/issues",
+  "license": "MIT",
+  "keywords": ["claude-code", "multi-model", "llm", "council", "second-opinion", "sidecar", "gemini", "gpt", "deepseek"],
+  "skills": ["./skills/sidecar", "./skills/second-opinion"],
+  "mcpServers": {
+    "amicus": {
+      "command": "npx",
+      "args": ["-y", "amicus@latest", "mcp"],
+      "env": { "AMICUS_SKIP_POSTINSTALL": "1" }
+    }
+  }
+}

package/CHANGELOG.md

@@ -5,6 +5,69 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.2.1] - 2026-06-24
+
+### Fixed
+- **`amicus models --check` / `amicus doctor` stale deepseek warning is now clearable**: the
+  built-in deepseek direct fallback (`deepseek/deepseek-chat`) has been updated to
+  `deepseek/deepseek-v4-pro`. Additionally, stale curated-route warnings are now suppressed when
+  the same alias already resolves live via any other source (default openrouter route or a
+  user-set alias), so the suggested `--add-alias` fix actually clears the warning instead of
+  leaving it permanently unresolvable.
+
+## [1.2.0] - 2026-06-24
+
+A post-launch enhancement program: reliability and cost made real, the council's
+trust machinery turned from hand-math into deterministic code, plus first-run
+diagnostics, a Claude Code plugin, and an observable interactive surface.
+
+### Added
+- **`amicus doctor`**: a one-screen first-run health check — configured providers, default-model
+  resolution vs. the live catalog, catalog freshness, the OpenCode binary, Electron, installed
+  skills, and MCP registration. Each red line carries the exact fix command; `--json` lets skills
+  self-diagnose.
+- **Claude Code plugin**: Amicus is now installable from the marketplace —
+  `/plugin marketplace add BourbonDog/amicus` then `/plugin install amicus`. The plugin ships both
+  skills and the MCP server; npm stays the engine/CLI. (The plugin channel skips the global
+  postinstall via `AMICUS_SKIP_POSTINSTALL` so it can't double-register.)
+- **Per-leg cost & token telemetry**: the run/wave schema (now `schemaVersion: 2`) carries a
+  `usage` block — input/output/reasoning tokens and a `$` cost tagged by source (reported >
+  estimated > unknown). Surfaced in `fanout --json` and council run-stats.
+- **Enforced budget gate**: a per-`$/Mtok` threshold (on by default — blocks o3-pro-class models
+  before a wave launches) plus an optional `--max-cost` total ceiling. `--no-cost-gate` is the
+  explicit escape hatch.
+- **`amicus council tally|stats`**: deterministic council scoring — a structured findings
+  contract, a peers-only tier cascade with self-vote-corrected street-cred, a compounding
+  reviewer-reliability ledger, and a machine-readable `verdict.json`. The council stays a skill;
+  the engine owns only the arithmetic and schemas.
+- **Structured `--json` error envelope**: pre-flight failures now emit a typed
+  `{ ok: false, error: { code, message, hint } }` document on stdout (stable codes like
+  `MISSING_KEY`, `BAD_MODEL`, `BUDGET_EXCEEDED`) instead of bare text on stderr.
+
+### Changed
+- **Interactive GUI sessions now persist live**: `conversation.jsonl` and `progress.json` are
+  written as the session runs, so the CLI heartbeat, `amicus status`, and
+  `amicus read --conversation` work for GUI sessions — and **closing the window without folding no
+  longer loses the transcript**. Interactive runs also record token/cost usage. (Headless and
+  interactive now share one persistence transform.)
+- **Reliability**: a single source of truth for terminal state (exit code and `metadata.status`
+  always agree; the idle backstop no longer exits 0 with `running` metadata), and an
+  activity-driven interactive watchdog that won't kill an actively-working-but-quiet GUI session.
+- **CI**: a real matrix (Ubuntu / Windows / macOS × Node 18 / 20 / 22) plus lint, secret-scan, and
+  size-gate now gate every push and the publish.
+- Repo layout: the chat skill moved to `skills/sidecar/` (both skills live under `skills/`); npm
+  `homepage` now points at the live site; README and the landing page gained a "Prerequisites &
+  cost" section.
+
+### Fixed
+- **MCP stderr fd leak**: `spawnSidecarProcess` opened a `debug.log` descriptor for the child's
+  stderr but never closed the parent's copy — a descriptor leak that, on Windows, also held the
+  file open and blocked session-dir cleanup.
+- Platform-correct missing-key guidance (PowerShell `$PROFILE`/`setx` on Windows; leads with
+  `amicus key`); the committed-secret scan now knows all five providers; `amicus models` marks
+  your **actual** aliases (not curated defaults); OpenRouter's `-1` "variable pricing" sentinel
+  renders as `—` instead of a nonsense negative price.
+
 ## [1.1.0] - 2026-06-11
 
 ### Added

package/LICENSE

@@ -1,6 +1,27 @@
 MIT License
 
-Copyright (c) 2025 John Renaldi
+Copyright (c) 2025 John Renaldi Claude Sidecar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+Copyright (c) 2026 Christian Wagner Amicus
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,7 +6,7 @@
 
 ![Amicus: an LLM Council and a parallel AI window for Claude](./docs/hero.png)
 
-Hand Claude a document and say *council review this*: Amicus routes it through several models from different families, has them anonymously cross-review each other, and a non-Claude chair synthesizes a verdict you turn into accept/deny edits. Or skip the ceremony and **fork** a single conversation to Gemini, GPT, DeepSeek, or any other model — it works in parallel with full context, and you **fold** the result back when you're ready. Claude orchestrates throughout; you stay in your editor.
+Hand Claude a plan, a design, a diff, an architecture decision, a manuscript — anything — and say *council review this*: Amicus routes it through several models from different families, has them anonymously cross-review each other, and a non-Claude chair synthesizes a verdict you turn into accept/deny edits. Or skip the ceremony and **fork** a single conversation to Gemini, GPT, DeepSeek, or any other model — it works in parallel with full context, and you **fold** the result back when you're ready. Claude orchestrates throughout; you stay in your editor.
 
 [![npm version](https://img.shields.io/npm/v/amicus?color=D97757&labelColor=1A1C29)](https://www.npmjs.com/package/amicus)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?labelColor=1A1C29)](./LICENSE)
@@ -67,6 +67,16 @@ The postinstall step auto-configures everything — no manual registration:
 - Registers the **MCP server** in Claude Code and in Claude Desktop / Cowork, so the Amicus tools appear natively.
 - Installs **both skills** into `~/.claude/skills/` — `second-opinion` (the council) and `sidecar` (the chat skill).
 
+## Prerequisites & what it costs you
+
+Before your first run:
+
+- **Node.js ≥ 18** — `node --version` to check.
+- **An active Claude Code or Cowork session** — Amicus is orchestrated by Claude; it is not a standalone chatbot.
+- **At least one paid model API key** — OpenRouter (covers the most models) or a direct Google / OpenAI / Anthropic / DeepSeek key. Add one with `amicus setup` or `amicus key <provider> <key>`.
+
+**What a run costs.** A sidecar is a single model call. A full council is typically **~5–8 paid model calls** (e.g. 3 reviewers across 2 fan-out waves + 1 chair). Amicus shows an estimate before each council and enforces a built-in budget gate that refuses ultra-expensive models (o3-pro class) unless you opt in with `--no-cost-gate`. You pay your providers directly for the tokens; Amicus itself is free and open-source.
+
 **Configure:**
 
 ```bash
@@ -452,7 +462,7 @@ LOG_LEVEL=debug amicus start --model gemini --prompt "test" --no-ui
 | [docs/publishing.md](./docs/publishing.md) | Release and publish process. |
 | [docs/SHIMS.md](./docs/SHIMS.md) | Legacy `SIDECAR_*` → `AMICUS_*` compatibility shims. |
 | [skills/second-opinion/SKILL.md](./skills/second-opinion/SKILL.md) | The LLM Council skill. |
-| [skill/SKILL.md](./skill/SKILL.md) | The `sidecar` chat skill. |
+| [skills/sidecar/SKILL.md](./skills/sidecar/SKILL.md) | The `sidecar` chat skill. |
 | [evals/README.md](./evals/README.md) | End-to-end eval harness for LLM interactions. |
 
 ---

package/bin/amicus.js

@@ -11,10 +11,11 @@
 const { loadCredentials } = require('../src/utils/env-loader');
 loadCredentials();
 
-const { parseArgs, validateStartArgs, getUsage } = require('../src/cli');
+const { parseArgs, getUsage } = require('../src/cli');
 const { validateTaskId } = require('../src/utils/validators');
 const { resolveModelFromArgs, validateFallbackModel } = require('../src/utils/start-helpers');
 const { handleSetup, handleAbort, handleUpdate, handleMcp, handleKey } = require('../src/cli-handlers');
+const { handleStart, handleFanout, handleRead } = require('../src/cli-handlers-run');
 const { isOneShotCommand, armExitWatchdog } = require('../src/utils/lifecycle');
 const { logger } = require('../src/utils/logger');
 
@@ -73,7 +74,7 @@ async function main() {
   try {
     switch (command) {
       case 'start':
-        await handleStart(args);
+        exitCode = await handleStart(args);
         break;
       case 'fanout':
         exitCode = await handleFanout(args);
@@ -95,6 +96,16 @@ async function main() {
         exitCode = await handleModels(args);
         break;
       }
+      case 'council': {
+        const { handleCouncil } = require('../src/cli-handlers-council');
+        exitCode = await handleCouncil(args);
+        break;
+      }
+      case 'doctor': {
+        const { handleDoctor } = require('../src/cli-handlers-doctor');
+        exitCode = await handleDoctor(args);
+        break;
+      }
       case 'setup':
         await handleSetup(args);
         break;
@@ -129,135 +140,6 @@ async function main() {
   }
 }
 
-/**
- * Handle 'sidecar start' command
- * Spec Reference: §4.1
- */
-async function handleStart(args) {
-  // F4: --prompt-file support (XOR --prompt) and --json gating
-  if (args.prompt !== undefined || args['prompt-file'] !== undefined) {
-    const { resolvePromptSource } = require('../src/utils/prompt-source');
-    const promptRes = resolvePromptSource(args);
-    if (promptRes.error) {
-      console.error(promptRes.error);
-      process.exit(1);
-    }
-    args.prompt = promptRes.prompt;
-  }
-  if (args.json && !args['no-ui']) {
-    console.error('Error: --json requires --no-ui');
-    process.exit(1);
-  }
-
-  const { model, alias } = resolveModelFromArgs(args);
-  args.model = model;
-  args.model = await validateFallbackModel(args, alias);
-
-  // Normalize agent: --agent takes precedence, otherwise use --mode
-  args.agent = args.agent || args.mode;
-
-  const validation = validateStartArgs(args);
-  if (!validation.valid) {
-    console.error(validation.error);
-    process.exit(1);
-  }
-
-  const { startSidecar } = require('../src/index');
-
-  await startSidecar({
-    taskId: args['task-id'],
-    model: args.model,
-    prompt: args.prompt,
-    sessionId: args['session-id'],
-    cwd: args.cwd,
-    contextTurns: args['context-turns'],
-    contextSince: args['context-since'],
-    contextMaxTokens: args['context-max-tokens'],
-    noUi: args['no-ui'],
-    timeout: args.timeout,
-    agent: args.agent,
-    mcp: args.mcp,
-    mcpConfig: args['mcp-config'],
-    thinking: args.thinking,
-    summaryLength: args['summary-length'],
-    client: args.client,
-    sessionDir: args['session-dir'],
-    foldShortcut: args['fold-shortcut'],
-    opencodePort: args['opencode-port'],
-    noMcp: args['no-mcp'],
-    excludeMcp: args['exclude-mcp'],
-    coworkProcess: args['cowork-process'],
-    position: args.position,
-    json: !!args.json,
-    modelInput: alias || null,
-  });
-}
-
-/**
- * Handle 'amicus fanout' command (F4).
- * Returns the wave exit code: 0 all complete, 2 partial, 1 none/hard failure,
- * 130/143 when the wave was signal-aborted.
- */
-async function handleFanout(args) {
-  const { resolvePromptSource } = require('../src/utils/prompt-source');
-  const promptRes = resolvePromptSource(args);
-  if (promptRes.error) {
-    console.error(promptRes.error);
-    process.exit(1);
-  }
-  if (typeof args.models !== 'string' || !args.models.trim()) {
-    console.error('Error: --models is required (comma-separated aliases or provider/model IDs)');
-    process.exit(1);
-  }
-  if (args['wave-id']) {
-    const check = validateTaskId(String(args['wave-id']));
-    if (!check.valid) {
-      console.error(check.error);
-      process.exit(1);
-    }
-  }
-  if (args.agent && String(args.agent).toLowerCase() === 'chat') {
-    console.error('Error: --agent chat is interactive-only; fanout is headless');
-    process.exit(1);
-  }
-  if (args.timeout !== undefined && args.timeout <= 0) {
-    console.error('Error: --timeout must be a positive number');
-    process.exit(1);
-  }
-  const { parseModelsList } = require('../src/sidecar/fanout');
-  if (parseModelsList(args.models).length === 0) {
-    console.error('Error: --models must contain at least one non-empty entry');
-    process.exit(1);
-  }
-
-  // Direct require — the src/index.js public re-export is added later (Task 13)
-  const { runFanout } = require('../src/sidecar/fanout');
-  const { exitCode } = await runFanout({
-    models: args.models,
-    prompt: promptRes.prompt,
-    promptMeta: promptRes.promptMeta,
-    waveId: args['wave-id'],
-    project: args.cwd || process.cwd(),
-    agent: args.agent || args.mode,
-    thinking: args.thinking,
-    timeout: args.timeout,
-    summaryLength: args['summary-length'],
-    includeContext: !args['no-context'],
-    sessionId: args['session-id'],
-    contextTurns: args['context-turns'],
-    contextSince: args['context-since'],
-    contextMaxTokens: args['context-max-tokens'],
-    mcp: args.mcp,
-    mcpConfig: args['mcp-config'],
-    noMcp: args['no-mcp'],
-    excludeMcp: args['exclude-mcp'],
-    noValidateModel: args['no-validate-model'],
-    json: !!args.json,
-    client: args.client,
-  });
-  return exitCode;
-}
-
 /**
  * Handle 'sidecar list' command
  * Spec Reference: §4.2
@@ -348,36 +230,6 @@ async function handleContinue(args) {
   });
 }
 
-/**
- * Handle 'sidecar read' command
- * Spec Reference: §4.5
- */
-async function handleRead(args) {
-  const taskId = args._[1];
-
-  if (!taskId) {
-    console.error('Error: task_id is required for read');
-    console.error('Usage: sidecar read <task_id> [--summary|--conversation]');
-    process.exit(1);
-  }
-
-  const taskIdCheck = validateTaskId(taskId);
-  if (!taskIdCheck.valid) {
-    console.error(taskIdCheck.error);
-    process.exit(1);
-  }
-
-  const { readSidecar } = require('../src/index');
-
-  await readSidecar({
-    taskId,
-    conversation: args.conversation,
-    metadata: args.metadata,
-    json: args.json,
-    project: args.cwd
-  });
-}
-
 // Run main
 main().catch(err => {
   console.error(`Fatal error: ${err.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.1.0",
+  "version": "1.2.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.",
   "keywords": [
     "claude",
@@ -24,7 +24,7 @@
     "url": "git+https://github.com/BourbonDog/amicus.git"
   },
   "bugs": "https://github.com/BourbonDog/amicus/issues",
-  "homepage": "https://github.com/BourbonDog/amicus#readme",
+  "homepage": "https://bourbondog.github.io/amicus/",
   "bin": {
     "amicus": "./bin/amicus.js",
     "am": "./bin/amicus.js",
@@ -39,8 +39,8 @@
     "bin/",
     "src/",
     "electron/",
-    "skill/",
     "skills/",
+    ".claude-plugin/",
     "CHANGELOG.md",
     "scripts/postinstall.js",
     "scripts/setup-hooks.js"
@@ -63,7 +63,9 @@
     "generate-docs": "node scripts/generate-docs.js",
     "generate-docs:check": "node scripts/generate-docs.js --check",
     "validate-docs": "node scripts/validate-docs.js --full",
-    "prepare": "node scripts/setup-hooks.js"
+    "prepare": "node scripts/setup-hooks.js",
+    "check:secrets": "node scripts/check-secrets.js --all",
+    "check:sizes": "node scripts/check-file-sizes.js --all"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",

package/scripts/postinstall.js

@@ -13,7 +13,7 @@ const path = require('path');
 const os = require('os');
 const { execFileSync } = require('child_process');
 
-const SKILL_SOURCE = path.join(__dirname, '..', 'skill', 'SKILL.md');
+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
@@ -172,12 +172,21 @@ function registerClaudeDesktop() {
   addMcpToConfigFile(configPath, 'sidecar', MCP_CONFIG);
 }
 
-function main() {
+function main(deps = {}) {
+  if (process.env.AMICUS_SKIP_POSTINSTALL === '1') {
+    console.log('[amicus] AMICUS_SKIP_POSTINSTALL set — skipping global setup (plugin channel handles registration).');
+    return;
+  }
+  const _installSkill = deps.installSkill || installSkill;
+  const _installCouncilSkill = deps.installCouncilSkill || installCouncilSkill;
+  const _registerClaudeCode = deps.registerClaudeCode || registerClaudeCode;
+  const _registerClaudeDesktop = deps.registerClaudeDesktop || registerClaudeDesktop;
+
   console.log('[amicus] Installing...');
-  installSkill();
-  installCouncilSkill();
-  registerClaudeCode();
-  registerClaudeDesktop();
+  _installSkill();
+  _installCouncilSkill();
+  _registerClaudeCode();
+  _registerClaudeDesktop();
 
   console.log('');
   console.log('[amicus] Setup:');
@@ -190,4 +199,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { addMcpToConfigFile, installSkill, installCouncilSkill, COUNCIL_FILES };
+module.exports = { main, addMcpToConfigFile, installSkill, installCouncilSkill, COUNCIL_FILES };

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

@@ -35,7 +35,7 @@ non-Claude chairman + per-model inspectable artifacts.
   chair) is prose workflow Claude performs while driving the `amicus` CLI. v3 note: the *transport*
   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.
+  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.
 
 ## 3. What changes vs. v1
 
@@ -44,7 +44,7 @@ non-Claude chairman + per-model inspectable artifacts.
 | Independent reviews | ✅ Phase 2 parallel sidecars | ✅ Stage 1 — now emits a **structured findings list** |
 | Cross-review | ❌ none | ⭐ **Stage 2** — anonymized peer ranking **+** per-finding adjudication |
 | Synthesis | Claude synthesizes | ⭐ **Council-model chair** synthesizes; Claude only presents |
-| Decision tiers | Claude's consensus/divergence read | ⭐ **Peer-validated** tiers (Confirmed / Contested / Singleton) |
+| Decision tiers | Claude's consensus/divergence read | ⭐ **Peer-validated** tiers (Disputed / Confirmed / Contested / Singleton) |
 | Scoring | none | ⭐ Reviewer **street-cred** + per-finding **peer-confidence** |
 | Artifacts | reviewed copy + report | + per-model raw reviews, cross-review matrix, chair verdict (run folder) |
 | MODEL-NOTES | per-model quirks | + **reviewer-reliability** rolling table feeding recommendations |
@@ -106,11 +106,9 @@ Run as ordered phases; track as todos. **Three sequential waves of model calls**
 - Chair selection & fallback: §5.3.
 
 ### Stage 4 — Tiered decisions (peer-validated)
-- **Consensus tier** = **Confirmed** findings (peers agree) → offer one **bulk accept/deny**
-  (user may name exceptions).
-- **Judgment tier** = **Contested** (peers dispute/split) or **Singleton** (only the raiser)
-  findings → present **each individually**, showing the dissent and which model raised/disputed it.
-- Record every decision (accepted / denied / modified).
+- **Consensus tier** = **Confirmed** findings (≥ 2 peer agreements, agrees dominate) → offer one **bulk accept/deny** (user may name exceptions).
+- **Judgment tier** = **Disputed** (strong peer pushback), **Contested** (live dispute), or **Singleton** (only the raiser) → present **each individually**, showing the adjudication data and which model raised/disputed it.
+- Record every decision (accepted / denied / modified / deferred).
 
 ### Stage 5 — Outputs
 - **Editable source** → write `<stem>-reviewed.<ext>` next to the original (accepted changes
@@ -119,8 +117,8 @@ Run as ordered phases; track as todos. **Three sequential waves of model calls**
 
 ### Stage 6 — Capture lessons (compounding)
 - Reflect on failures/mitigations and briefing wording, as today.
-- **Additionally** update the per-model **reviewer-reliability** table (§7).
-- **Write the proposed MODEL-NOTES diff to a run-folder file and get approval before writing.**
+- **Ledger auto-appends** — `ledger.appendRun(record)` writes one row per (run × model) to `council-ledger.jsonl` automatically at finalize (shown in the run summary). No manual reliability-table update needed.
+- **Qualitative MODEL-NOTES update (approval-gated):** draft per-model quirk/conformance notes; write the proposed diff to `_tmp-proposed-model-notes-update.md`; present its path in the approval prompt; do not write until approved.
   The approval prompt carries the diff file's path; chat text alone is not sufficient (an approval
   dialog can hide the chat transcript). Keep it tight.
 
@@ -136,14 +134,23 @@ Run as ordered phases; track as todos. **Three sequential waves of model calls**
   and judged blind by the council models. Claude never ranks/adjudicates (it holds the map) —
   the asymmetry detailed in §5.4.
 
-### 5.2 Scoring (Claude tallies by hand — no code required)
-- **Street cred** = each model's **average rank position** across all judges' `FINAL RANKING:`
-  blocks (lower = better), exactly as LLM Council's aggregate. Surface as a small table.
-- **Per-finding peer-confidence** = qualitative tier from the adjudications:
-  - **Confirmed** — agrees clearly outweigh disputes (and ≥2 judges engaged).
-  - **Contested** — meaningful split or explicit disputes.
-  - **Singleton** — only the original raiser; others neutral/silent.
-  These tiers drive Stage 4. Claude exercises judgment at the margins; no rigid formula.
+### 5.2 Scoring (`amicus council tally` computes; Claude may override at the margins)
+
+**Street cred** — computed two ways by `amicus council tally`:
+- **withSelf** = each model's mean rank position across **all** judges' `FINAL RANKING:` blocks (lower = better).
+- **peersOnly** = mean rank across judges **other than** that model (self-vote excluded).
+The cross-review matrix shows both; the ledger and Stage-0 bench recommendations consume **peersOnly** only.
+
+**Per-finding peer-confidence tier** — determined by a **peers-only** cascade: for a finding raised by model R, peers are all judges except R (the raiser's own adjudication is excluded — consistent with the peers-only street-cred rule). Let `a` = peer agrees, `d` = peer disputes. The cascade is exhaustive and mutually exclusive:
+
+| Priority | Tier | Rule | Meaning |
+|---|---|---|---|
+| 1 | **Disputed** | `d ≥ 2` and `d > a` | Strong peer pushback — the finding itself is likely wrong |
+| 2 | **Confirmed** | `a ≥ 2` and `a > d` | ≥ 2 independent corroborations, agrees dominate |
+| 3 | **Contested** | `d ≥ 1` (whatever remains) | At least one live dispute — in question |
+| 4 | **Singleton** | else (`d = 0` and `a < 2`) | At most one endorsement, no pushback — thin |
+
+`confidence` is `thin` when total engaged peers `a + d ≤ 1` — cells `(0,0)`, `(1,0)`, and `(0,1)`. **Claude may override the tier at `thin` margins** (recorded as `tierOverride: {from, to, reason}` and surfaced in the matrix and `verdict.json`). These four tiers drive Stage 4. `amicus council tally` assigns them deterministically; judgment at the margins remains Claude's.
 
 ### 5.3 Chair selection & fallback
 - Default: Claude **recommends a non-Claude chair** from the council each run (often the
@@ -161,7 +168,7 @@ Lets you see how the bench judges Claude's *own* take.
 - **Which review: always fresh** — Claude does a new structured Stage-1 review on the artifact
   every time it's enabled (not a formalization of upstream feedback).
 - **Readout — "How Claude's review fared":** Claude's street-cred rank among peers and the
-  Confirmed/Contested/Singleton split of its findings, reported in the matrix and report.
+  Disputed/Confirmed/Contested/Singleton split of its findings, reported in the matrix and report.
 - **Integrity:** when Claude presents results, it reports the bench's verdict on its own review
   at face value — no defending or re-litigating.
 
@@ -171,22 +178,16 @@ One tidy run folder: `output/<stem>-council/` (or `./second-opinion/<stem>-counc
 - `review-<model>.md` ×N — raw Stage 1 reviews (plus `review-claude.md` when "Claude in the
   council" is on)
 - `crossreview-matrix.md` — adjudication grid + street-cred table (de-anonymized)
-- `verdict.md` — the chair's synthesis
+- `verdict.md` — the chair's synthesis (prose)
+- `verdict.json` — schema-stamped machine-readable record: tally output + Stage-4 decisions, written via `buildVerdict(record, decisions)` at Stage 5
 - `report.md` — synthesis + decision log + what was applied (+ the "How Claude's review fared"
   readout when "Claude in the council" is on)
 - `<stem>-reviewed.<ext>` — written **next to the original**, as today (editable sources only)
 - Temp extracts get a clearly-temporary name and are cleaned up at the end.
 
 ## 7. MODEL-NOTES reviewer-reliability
-Add a compact rolling table consulted in Stage 0 and updated (with approval) in Stage 6:
-
-| model | runs | avg street-cred | confirm-rate | notes |
-|---|---|---|---|---|
 
-- **avg street-cred** — running average rank when peer-ranked.
-- **confirm-rate** — share of this model's findings that ended up **Confirmed** by peers.
-- Used to justify recommendations ("DeepSeek findings peer-confirm ~80% → strong default
-  reviewer"). Kept tight per the existing no-bloat rule; merge/prune rather than append.
+The append-only `council-ledger.jsonl` (consumed via `amicus council stats`) is the **authoritative source of quantitative reviewer-reliability data** — runs, avg peers-only street-cred, confirm-rate, fact-error rate, conformance distribution. `MODEL-NOTES.md` keeps only *qualitative* per-model quirks and structural-conformance notes (`clean` / `repaired` / `unstructured`); it may embed a snapshot generated from `amicus council stats --json` but is no longer hand-edited for numbers. Stage-6 reliability updates are written by the ledger auto-append; the MODEL-NOTES prose update remains approval-gated.
 
 ## 8. Gating, cost, degradation & failure handling
 
@@ -207,23 +208,22 @@ Add a compact rolling table consulted in Stage 0 and updated (with approval) in
   - **Stage 3:** chair failure uses the same fallback chain (re-run → promote next-best non-Claude
     → Claude chairs with explicit disclosure).
 - **Run stats (v3):** `report.md` includes a per-leg table (model, status, durationMs) read from
-  the wave/run documents. The schema carries no cost data — never invent cost figures.
+  the wave/run documents. `durationMs` and `usage` are copied verbatim from the per-leg run docs; any leg with no run doc gets `durationMs: null` (and `usage: null`) — never invent a value. The schema carries no cost data — never invent cost figures.
 - **Transient failures:** provider 502s etc. → re-run the affected leg (solo `start --json`) or
   the wave; never present a half-finished run as an answer.
 
 ## 9. Non-goals (YAGNI)
 - No web UI, API server, or persistent conversation store (LLM Council's app shell).
-- No code/backend for scoring or parsing — Claude does it inline.
+- No code/backend for scoring or parsing — Claude does it inline. 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.
 - No automatic MODEL-NOTES writes — always approval-gated.
 - Claude is **not** a council member by default; it joins only via the opt-in toggle (§5.4),
   and even then it is judged-but-non-voting/non-chairing.
 
 ## 10. Open questions
 - None blocking. Possible later refinement: a numeric peer-confidence score instead of the
-  three qualitative tiers, if tiers prove too coarse in practice.
+  four qualitative tiers, if tiers prove too coarse in practice.
 
 ## 11. Implementation surface
-- `SKILL.md` — the Stage 0–6 council flow on the v3 transport.
-- `MODEL-NOTES.md` — reviewer-reliability table, per-model quirks, cost guardrail, Stage-2
-  briefing tips. Engine workarounds that F1/F2/F4 made obsolete were pruned at v3.
-- No other files.
+- `SKILL.md` — the Stage 0–6 council flow on the v3 transport (WS-3: findings contract, tally assembly recipe, `amicus council tally/stats`, `verdict.json`, ledger auto-append).
+- `MODEL-NOTES.md` — qualitative per-model quirks, structural-conformance notes, cost guardrail, Stage-2 briefing tips. Quantitative reliability data now generated by `amicus council stats` (ledger). Engine workarounds that F1/F2/F4 made obsolete were pruned at v3.
+- `src/council/` — the deterministic helpers (`findings.js`, `tally.js`, `verdict.js`, `ledger.js`). No other files.