amicus 1.7.7 → 1.8.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.7",
+  "version": "1.8.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,75 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.8.1] - 2026-07-02
+
+Docs & skills accuracy sprint from the Phase-8 whole-branch review — no engine changes. Every item fixed a claim
+that actively misdirected Claude or users, plus one headless completion-state bugfix.
+
+### Changed
+- **`report.html` is now the default final council artifact**, and an inline verdict summary in chat is
+  MANDATORY at Stage 5 of the second-opinion skill.
+- **The `sidecar` skill's frontmatter dropped the "second opinion from another model" trigger** — those requests
+  now route to the `second-opinion` skill instead.
+- **MODEL-NOTES seed updated** with durable lessons from council runs 4-7 (new Grok/Kimi/Mistral/Claude-in-council
+  sections; shipped/local split defined). Existing installs: the machine-local copy is installed only-if-missing —
+  merge/refresh manually by pointing at the shipped file.
+- **Council mechanics hardened:** mandatory no-tools preamble for judges and chair (plus scratch-cwd advice);
+  `--max-cost` / `--no-cost-gate` pass-through documented for repair and chair calls (the false solo-start
+  cost-gate exemption was removed); `--models` lists quoted in every example; current-date injection rule for
+  time-sensitive artifacts.
+
+### Fixed
+- **Plugin quick-start now states the truth:** plugin installs do not put `amicus` on `PATH`; use
+  `npx -y amicus@latest <cmd>`. Both skills gained an npx-fallback/transport rule.
+- **README/usage now document `doctor`, `key`, and `council`;** troubleshooting leads with `amicus doctor`; the
+  false "`amicus list` shows active servers" claim is replaced with real `netstat`/`lsof` guidance.
+- **Headless runs that finish via idle detection no longer write `status:"error"` / `reason:"Incomplete"` to
+  `metadata.json`.** The poll loop's two genuine idle-completion exits — the SDK-authoritative `session.status`
+  idle signal and the stable-poll activity heuristic (both gated on real output, F1 #16) — broke out of the loop
+  without setting `completed`, so `resolveTerminalState` fell through to error and poisoned `amicus_list` /
+  `amicus_status` / wave rollups for successful runs, while the stdout `--json` doc correctly said
+  `status:"complete"`. Both exits now mark the run completed, matching the fold-marker branch. Dead-server
+  classification is unchanged: the consecutive-poll-failure fast-exit (F4) and crash paths still report an error.
+
+## [1.8.0] - 2026-07-02
+
+### Added
+- **`amicus_wait` MCP tool: blocking wait for a session or fan-out wave.** Blocks inside one tool call until the
+  target reaches a terminal state or the wait window closes, replacing the sleep+`amicus_status` polling loop with
+  a single call. Returns the same JSON shape as `amicus_status` plus `waitedMs` and `{timedOut: true}` (with a
+  `hint`) on expiry — re-call it while it keeps returning `timedOut: true`. Works for sessions or waves started by
+  other processes, not just the caller. Torn-read tolerant: a transient read of `metadata.json` mid-write is
+  treated as a missed poll tick, not a hard failure. Legacy alias `sidecar_wait` is available under
+  `AMICUS_LEGACY_ALIASES=1`.
+- **Agent-visible progress.** A new `amicus status <task_id>` (or `--wave <id>`) one-shot CLI command delegates
+  directly to the MCP status handler — same crash detection and wave-leg rollup, zero duplicated logic.
+  `amicus_status` and `amicus_list` are enriched with agent-facing `mode`, `phase`, `messageCount`,
+  `lastActivityAt`, and `latestPreview` (the pinned raw `stage` field is unchanged for back-compat; wave legs
+  additionally surface the raw `stage` alongside the coarse `phase`). Interactive (Electron GUI) runs now write
+  the same lifecycle progress stages headless runs always have (`initializing`, `server_ready`, `session_created`,
+  `prompt_sent`), and long-thinking turns emit periodic thinking-delta progress ticks instead of at most one ever
+  — so a live GUI run no longer reads "Starting up... | 0 messages" forever.
+- **`amicus doctor` duplicate-registration check.** A new `mcp-legacy` check flags plugin-channel installs
+  (`AMICUS_SKIP_POSTINSTALL=1`) that never ran the postinstall migration and still carry a duplicate legacy
+  `sidecar` MCP registration; `doctor --fix` cleans it up.
+
+### Fixed
+- **`amicus abort` now actually stops interactive sessions and wave legs.** Marker-first, honest output — reports
+  what really happened including the unkillable-pid case — and no-ops cleanly with a clear message when the
+  target isn't running.
+- **Legacy-MCP remediation's `claude mcp add-json` (CLI) path no longer drops a user's custom `env`** on
+  re-registration — it now merges the previous registration's `env` the same way the file-fallback path already did.
+
+### Changed
+- **Legacy `sidecar_*` MCP tool aliases are now opt-in** via `AMICUS_LEGACY_ALIASES=1` (breaking-adjacent —
+  carrying release must be a MINOR, v1.8.0). The default client-visible surface is the `amicus_*` toolset (14
+  tools as of this release); saved allowlists that still reference `mcp__amicus__sidecar_*` stop resolving unless
+  you opt back in.
+- **Postinstall no longer registers a separate `sidecar` MCP server** and auto-removes a verified-identical
+  duplicate left over from pre-1.8 installs. A customized `sidecar` entry or a sole `sidecar` registration (no
+  `amicus` twin) is never touched.
+
 ## [1.7.7] - 2026-07-01
 
 Correctness patch from the 2026-07-01 full product review (multi-agent review, every finding adversarially

package/README.md

@@ -57,7 +57,7 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 
 ## Quick start
 
-**Install** — pick whichever fits; all deliver the same CLI, MCP server, and both skills:
+**Install** — pick whichever fits. Every path delivers the MCP server and both skills; the `amicus`/`am` CLI lands on your PATH with the **npm and install-script paths** (the plugin path runs the CLI on demand via `npx -y amicus@latest <command>`):
 
 **As a Claude Code plugin** — the most native path if you use Claude Code:
 
@@ -67,7 +67,7 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 /reload-plugins
 ```
 
-Claude Code registers the MCP server and both skills for you — nothing to configure. (The standalone Electron window is npm-only, and the first council/sidecar call downloads the OpenCode engine.)
+Claude Code registers the MCP server and both skills for you — nothing to configure. (The plugin does not put `amicus` on your PATH — CLI calls go through `npx -y amicus@latest <command>`; the standalone Electron window is npm-only; and the first council/sidecar call downloads the OpenCode engine.)
 
 **With the install script** — macOS, Linux, or Windows (needs [Node.js](https://nodejs.org) ≥ 18):
 
@@ -96,6 +96,8 @@ For the **npm** and **install-script** paths, a postinstall auto-configures ever
 
 ```bash
 amicus setup
+# plugin-only install (no CLI on PATH):
+npx -y amicus@latest setup
 ```
 
 This opens a graphical wizard:
@@ -113,7 +115,7 @@ This opens a graphical wizard:
 
 > *council review this*
 
-Claude prepares the material, recommends a bench of models, discloses the run shape and cost, and orchestrates the rest. You make the accept/deny calls at the end. (The `second-opinion` skill installed in the previous step is what teaches Claude to recognize this — if nothing happens, confirm it landed in `~/.claude/skills/second-opinion/`.)
+Claude prepares the material, recommends a bench of models, discloses the run shape and cost, and orchestrates the rest. You make the accept/deny calls at the end. (The `second-opinion` skill is what teaches Claude to recognize this — if nothing happens, run `amicus doctor` (or `npx -y amicus@latest doctor`). npm/install-script installs place the skill at `~/.claude/skills/second-opinion/`; plugin installs keep it inside the plugin itself — check `/plugin` in Claude Code to confirm amicus is enabled.)
 
 **Your first sidecar.** The sidecar is the lower-level path — you can invoke it by phrase through Claude too, but the CLI gives you the flags directly:
 
@@ -259,7 +261,11 @@ amicus update
 | `amicus resume` | Reopen a previous session with full history. |
 | `amicus continue` | Start a new session building on a previous one. |
 | `amicus read` | Output a session's summary / conversation / metadata. |
+| `amicus status <id>` | One-shot status for a session or fan-out wave (human or `--json`; `--wave <id>` alternative spelling). |
 | `amicus models` | List, search, refresh the catalog, or audit aliases. |
+| `amicus doctor` | Diagnose your setup — keys, default model, catalog, aliases, OpenCode binary, Electron, skills, MCP registration, OpenRouter credit (`--json`; `--fix` self-heals what it can). |
+| `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]`. |
 | `amicus abort` | Abort a running session (or `--all`). |
 | `amicus setup` | Configure default model, API keys, and aliases. |
 | `amicus update` | Update to the latest version. |
@@ -303,7 +309,7 @@ The `am` alias is interchangeable with `amicus` everywhere.
 ### `amicus fanout` — same prompt, many models
 
 ```bash
-amicus fanout --models gemini,deepseek,gpt --prompt "Review this design" --json
+amicus fanout --models "gemini,deepseek,gpt" --prompt "Review this design" --json
 ```
 
 Fanout runs one **headless wave**: every leg gets the **same** prompt (this is the shared-prompt model the council's review stages are built on). When all legs are terminal it prints **one** JSON wave document on stdout.
@@ -329,6 +335,10 @@ amicus read <id> --conversation      # full conversation
 amicus read <id> --metadata          # session metadata
 amicus read <id> --json              # stable JSON (run or wave document)
 
+amicus status <id>                   # one-shot status for a session or wave
+amicus status --wave <id>            # alternative spelling for a wave ID
+amicus status <id> --json            # machine-readable output
+
 amicus resume <id>                   # reopen with full history
 amicus continue <id> --prompt "..."  # new session, previous one as read-only context
 
@@ -371,12 +381,13 @@ amicus models --check         # audit your aliases against the catalog
 
 ## MCP integration
 
-The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes ten tools:
+The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes fourteen tools:
 
 | Tool | What it does |
 |------|--------------|
 | `amicus_start` | Spawn a session; returns a task ID immediately. |
 | `amicus_status` | Poll a task (or a fanout wave) for completion. |
+| `amicus_wait` | Block inside one tool call until a session/wave finishes or the wait window closes. |
 | `amicus_read` | Read results: summary, conversation, metadata, or JSON. |
 | `amicus_list` | List past sessions. |
 | `amicus_resume` | Reopen a session. |
@@ -385,8 +396,11 @@ The MCP server is auto-registered on install (Claude Code and Claude Desktop / C
 | `amicus_setup` | Open the setup wizard. |
 | `amicus_guide` | Return usage guidance (model choice, briefings, polling). |
 | `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. |
 
-The async pattern is **start → status → read**: `amicus_start` (or `amicus_fanout`) returns immediately, you poll `amicus_status`, then `amicus_read` once it's done — so the calling agent never blocks.
+The async pattern is **start → status → read**: `amicus_start` (or `amicus_fanout`) returns immediately, you poll `amicus_status`, then `amicus_read` once it's done — so the calling agent never blocks. Prefer `amicus_wait` over manual sleep+status polling for headless runs: it collapses the poll loop into a single blocking call that returns as soon as the run finishes (or the wait window closes).
 
 To register manually (user scope):
 
@@ -394,7 +408,7 @@ To register manually (user scope):
 claude mcp add-json amicus '{"command":"npx","args":["-y","amicus@latest","mcp"]}' --scope user
 ```
 
-> Legacy `sidecar_*` tool names are still registered as aliases of each `amicus_*` tool for backward compatibility.
+> Legacy `sidecar_*` tool names are no longer registered by default (v1.8.0). To restore them, add `"env": {"AMICUS_LEGACY_ALIASES": "1"}` to the server entry. They will be removed entirely in the next major.
 
 ---
 

package/bin/amicus.js

@@ -94,6 +94,11 @@ async function main() {
       case 'list':
         await handleList(args);
         break;
+      case 'status': {
+        const { handleStatus } = require('../src/cli-handlers-status');
+        exitCode = await handleStatus(args);
+        break;
+      }
       case 'resume':
         exitCode = await handleResume(args);
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.7.7",
+  "version": "1.8.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",

package/scripts/postinstall.js

@@ -15,6 +15,7 @@ const { execFileSync } = require('child_process');
 
 const { repairElectron } = require('../src/sidecar/electron-install');
 const HINTS = require('../src/utils/remediation-hints');
+const { isAmicusMcpConfig } = require('../src/utils/mcp-self-identity');
 
 const SETUP_HOOKS_SCRIPT = path.join(__dirname, 'setup-hooks.js');
 
@@ -41,7 +42,18 @@ const MCP_CONFIG = { command: 'npx', args: ['-y', 'amicus@latest', 'mcp'] };
 
 /**
  * Add or update an MCP server in a JSON config file.
- * Always overwrites the entry to ensure upgrades apply the latest config.
+ *
+ * Refreshes command/args on every install/upgrade. If the EXISTING entry at
+ * this key is already amicus-shaped (per isAmicusMcpConfig — Phase 1's single
+ * source of truth for "this is amicus"), we MERGE instead of overwrite: the
+ * user's `env` (and any other extra keys, e.g. a future `cwd`) survive the
+ * refresh. Without this, `npm i -g amicus` silently wiped
+ * "env": {"AMICUS_LEGACY_ALIASES":"1"} — the exact opt-in escape hatch Phase 4
+ * tells users to add — on every upgrade.
+ *
+ * A NON-amicus-shaped entry at this key is overwritten as before: 'amicus' is
+ * a reserved registration name, so a foreign entry there is reclaimed rather
+ * than merged with.
  *
  * @param {string} configPath - Path to the JSON config file
  * @param {string} name - MCP server name
@@ -59,9 +71,10 @@ function addMcpToConfigFile(configPath, name, config) {
   if (!existing.mcpServers) { existing.mcpServers = {}; }
 
   const prev = existing.mcpServers[name];
-  const status = !prev ? 'added' : JSON.stringify(prev) !== JSON.stringify(config) ? 'updated' : 'unchanged';
+  const nextConfig = (prev && isAmicusMcpConfig(prev)) ? { ...prev, ...config } : config;
+  const status = !prev ? 'added' : JSON.stringify(prev) !== JSON.stringify(nextConfig) ? 'updated' : 'unchanged';
 
-  existing.mcpServers[name] = config;
+  existing.mcpServers[name] = nextConfig;
   if (status !== 'unchanged') {
     const dir = path.dirname(configPath);
     if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); }
@@ -111,28 +124,42 @@ function installCouncilSkill(sourceDir = COUNCIL_SOURCE_DIR) {
   }
 }
 
+/**
+ * Read the previous 'amicus' entry from ~/.claude.json, if any — used by the
+ * CLI add-json path to merge env the same way the file-fallback path does.
+ * Never throws: a missing/unreadable file just means "no previous entry".
+ * @returns {object|undefined}
+ */
+function readPrevClaudeCodeAmicusEntry() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf-8'));
+    return parsed && parsed.mcpServers ? parsed.mcpServers.amicus : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Register MCP server in Claude Code config */
 function registerClaudeCode() {
   // Try the CLI first
   try {
-    const mcpJson = JSON.stringify(MCP_CONFIG);
+    // Merge the PREVIOUS registration's env into the add-json payload — same
+    // merge semantics as addMcpToConfigFile's file-fallback path (`{ ...prev,
+    // ...config }`: prev env keys survive, canonical MCP_CONFIG keys win on
+    // collision). Without this, a user's custom env (API key, AMICUS_* tuning
+    // knobs) on the old registration was silently dropped whenever the
+    // `claude` CLI was present, because the CLI path built its JSON payload
+    // from the bare MCP_CONFIG and delegated overwrite semantics to the
+    // claude binary — which has no idea about the user's previous entry.
+    const prev = readPrevClaudeCodeAmicusEntry();
+    const nextConfig = (prev && isAmicusMcpConfig(prev)) ? { ...prev, ...MCP_CONFIG } : MCP_CONFIG;
+    const mcpJson = JSON.stringify(nextConfig);
     execFileSync('claude', ['mcp', 'add-json', 'amicus', mcpJson, '--scope', 'user'], {
       stdio: 'pipe',
       timeout: 10000,
     });
     console.log('[amicus] MCP registered in Claude Code (via CLI).');
 
-    // DEPRECATED(amicus-shim): also register 'sidecar' so existing clients that
-    // reference the old server name keep resolving. Remove in next major.
-    try {
-      execFileSync('claude', ['mcp', 'add-json', 'sidecar', mcpJson, '--scope', 'user'], {
-        stdio: 'pipe',
-        timeout: 10000,
-      });
-    } catch {
-      // Best-effort; ignore failures for the shim registration
-    }
-
     return;
   } catch {
     // CLI not available or failed — fall back to file edit
@@ -148,10 +175,6 @@ function registerClaudeCode() {
   } else {
     console.log('[amicus] MCP already registered in Claude Code.');
   }
-
-  // DEPRECATED(amicus-shim): also register 'sidecar' entry so existing clients
-  // that reference the old server name keep resolving. Remove in next major.
-  addMcpToConfigFile(claudeConfigPath, 'sidecar', MCP_CONFIG);
 }
 
 /** Register MCP server in Claude Desktop / Cowork config */
@@ -174,10 +197,33 @@ function registerClaudeDesktop() {
   } else {
     console.log('[amicus] MCP already registered in Claude Desktop.');
   }
+}
 
-  // DEPRECATED(amicus-shim): also register 'sidecar' entry so existing clients
-  // that reference the old server name keep resolving. Remove in next major.
-  addMcpToConfigFile(configPath, 'sidecar', MCP_CONFIG);
+/**
+ * One-shot migration: drop the duplicate legacy 'sidecar' MCP entry that
+ * pre-1.8 postinstalls registered alongside 'amicus' (same server twice —
+ * doubled the client-visible tool list). Only removes an entry whose command
+ * is an amicus MCP invocation; a customized 'sidecar' entry is left alone.
+ * Covers both files the three legacy registration paths wrote to:
+ * ~/.claude.json (CLI + file fallback) and claude_desktop_config.json.
+ * Never throws (postinstall must always exit 0).
+ */
+function migrateLegacyMcp(deps = {}) {
+  try {
+    const impl = deps.migrateLegacySidecar
+      || require('../src/utils/legacy-mcp-migration').migrateLegacySidecar;
+    for (const r of impl()) {
+      if (r.result === 'removed') {
+        console.log(`[amicus] Removed duplicate legacy 'sidecar' MCP entry from ${r.target} (same server — kept as 'amicus').`);
+      } else if (r.result === 'customized') {
+        console.log(`[amicus] Kept custom 'sidecar' MCP entry in ${r.target} (does not point at amicus).`);
+      } else if (r.result === 'write-failed') {
+        console.warn(`[amicus] Warning: could not remove the legacy 'sidecar' MCP entry from ${r.target} — run: amicus doctor --fix`);
+      }
+    }
+  } catch (err) {
+    console.warn(`[amicus] Warning: legacy MCP cleanup skipped: ${err && err.message}`);
+  }
 }
 
 /**
@@ -291,6 +337,7 @@ async function main(deps = {}) {
   const _installCouncilSkill = deps.installCouncilSkill || installCouncilSkill;
   const _registerClaudeCode = deps.registerClaudeCode || registerClaudeCode;
   const _registerClaudeDesktop = deps.registerClaudeDesktop || registerClaudeDesktop;
+  const _migrateLegacyMcp = deps.migrateLegacyMcp || migrateLegacyMcp;
   const _setupHooks = deps.setupHooks || setupHooks;
   const _provisionElectron = deps.provisionElectron || provisionElectron;
 
@@ -302,6 +349,7 @@ async function main(deps = {}) {
   _installCouncilSkill();
   _registerClaudeCode();
   _registerClaudeDesktop();
+  _migrateLegacyMcp(deps);
 
   // Non-fatal, cache-only: heal the optional Electron binary from local cache
   // or emit a deferred notice (GUI provisions on first use). Never throws.
@@ -336,4 +384,5 @@ if (require.main === module) {
   runCli();
 }
 
-module.exports = { main, runCli, addMcpToConfigFile, installSkill, installCouncilSkill, setupHooks, provisionElectron, COUNCIL_FILES };
+module.exports = { main, runCli, addMcpToConfigFile, installSkill, installCouncilSkill,
+  setupHooks, provisionElectron, registerClaudeCode, registerClaudeDesktop, migrateLegacyMcp, COUNCIL_FILES };

package/skills/second-opinion/MODEL-NOTES.md

@@ -4,7 +4,8 @@ This file is the `second-opinion` skill's evolving memory of **how to actually d
 well**. Read it before Stage 0 (council selection and launch); update it, with the user's
 approval, at the end of each run (Stage 6). Keep it tight — merge and prune rather than append.
 
-_Last updated: 2026-06-10 (v3 migration: engine workarounds pruned — see changelog)._
+_Last updated: 2026-07-02 (runs 4-7 folded back from the field ledger: PowerShell quoting, date
+injection, long-read failures, judge tool-wander; see changelog)._
 
 ## Global operating rules (all models)
 - **Council runs are headless by design** (autonomous batch work): `fanout` is headless by
@@ -26,6 +27,18 @@ _Last updated: 2026-06-10 (v3 migration: engine workarounds pruned — see chang
   model-specific signals. Never present a half-finished run as an answer.
 - **Credentials:** keys live in `~/.config/amicus/.env` (legacy `~/.config/sidecar/.env` still
   read). Configure with `amicus setup`.
+- **PowerShell `--models` quoting (Windows):** always quote comma-separated model lists —
+  `--models "gemini,gpt,deepseek"`. Unquoted, PowerShell splits on commas and amicus receives one
+  mangled alias → instant arg-parse failure. (Now baked into every SKILL.md example.)
+- **Inject the current date into briefings for time-sensitive artifacts** (resumes, dated plans).
+  Headless models don't reliably know "today": one run produced a false "future-dated" blocker two
+  judges then confirmed. (Now a Stage-0 rule in SKILL.md.)
+- **Very long artifacts (80k+ words) break the agent-reads-the-file transport for some models.**
+  gpt/deepseek/grok have handled 82k-word agentic reads; gemini(-flash) and kimi stalled (narrate-
+  stall / 25-min timeout / poller "Incomplete"). Pre-select proven long-read models or inline the
+  text for large-context models.
+- **Stage-6 approvals:** write the proposed MODEL-NOTES diff to a run-folder file and put that path
+  in the approval prompt — chat-text diffs can be hidden behind the approval dialog.
 
 ## Stage-2 cross-review briefing tips
 
@@ -36,6 +49,11 @@ _Last updated: 2026-06-10 (v3 migration: engine workarounds pruned — see chang
   finding referenced by run-global label id (e.g. `A2` = Review A's 2nd finding).
 - After de-anonymizing, assemble the tally input (see SKILL.md Stage 2 assembly recipe) and run
   `amicus council tally <input.json> --json` — do not hand-tally tiers or street-cred numbers.
+- Telling judges that **material severity inflation can justify a `dispute`** sharpens adjudications.
+- **Plan-agent judges can wander to tools** (reading run-folder files = anonymization leak). The
+  no-tools preamble is now mandatory in SKILL.md Stage 2/3 — keep it verbatim.
+- The tally input needs **all five keys** (`meta` incl. `meta.models`, `findings`, `adjudications`,
+  `rankings`, `runStats`) — see the SKILL.md Stage-2 recipe step 0.
 
 ## Per-model notes
 
@@ -45,17 +63,44 @@ _Last updated: 2026-06-10 (v3 migration: engine workarounds pruned — see chang
   structured output verbatim, without preamble. (Historical: its narrate-then-glob habit used to
   trip the old headless poller; the engine handles tool-call gaps now — F1.)
 - Don't trust its self-reported version string ("I am gemini-X") as ground truth.
+- **Red-team:** takes an adversarial brief well — high variance by design; use when consensus risk is high.
+- **Blind self-votes are inconsistent** (self-#1 in some runs, self-last in others) → discount self-votes either way.
+- Alias has resolved to **flash** tiers: fast, shallowest coverage, yet a recurring sharp fact/consistency checker (it alone refuted a bench-wide date error). Cheap cross-check value.
+- **Unreliable on long agentic reads** (see global rule) — inline the text or swap models for book-length material.
 
 ### DeepSeek  (`--model deepseek` → via OpenRouter)
 - **Strengths:** resilient; produces strong, well-structured, well-cited critical analysis. A good
   default reviewer and a proven chair.
 - **Quirk:** occasional transient 502 mid-run → re-run the leg.
+- Proven chair (5 clean chairings) — decisive, well-structured synthesis.
+- As a Stage-1 reviewer of human-facing documents it **over-escalates severity** (typos/tenure → "blocker"); discount its blocker labels against peers. Prune its self-retractions when tallying.
+- **"Agree-with-the-adversary" lean:** it has been the lone endorser of a red-team's harshest claims, turning them Contested — cross-check before treating its lone agreements as consensus.
 
 ### GPT  (`--model gpt` → via OpenRouter)
 - **Strengths:** reachable via the OpenRouter key; resilient; very thorough structured critique
   (25 findings on a 1-page framework). Cleanly separates the review criteria.
 - **Quirks:** verbose — peers dinged it for volume-over-judgment (good coverage, lower
   discrimination); **self-ranked its own review #1** in cross-review → discount self-votes.
+- Ranked genuine #1 by all judges (incl. non-self) in one run — thoroughness is real, not a self-vote artifact. Handled an 82k-word agentic read cleanly.
+- **Asserts context-dependent facts (dates, "is this future?") without verifying** — and self-confirms them in adjudication. Cross-check any time-dependent claim it raises.
+- A good calibration anchor in cross-review: confirms observational findings, disputes interpretive overreach.
+
+### Grok  (`--model grok` → via OpenRouter)
+- Very fast legs; credible judge and chair (rejected its own weak findings as chair; honest blind self-rank).
+- Strong red-team fit; handled an 82k-word agentic read. Weight its **observational** catches heavily and its **interpretive** verdicts cautiously (bench pattern: the former confirmed, the latter disputed).
+- Stage-1 non-red-team reviews skew to scope-inflated "missing content" majors.
+
+### Kimi  (`--model kimi` → via OpenRouter)
+- The bench's sharpest adjudicator (caught strawmen and misreads other judges waved through).
+- **Very slow legs (5-7 min)** — it gates wave wall-clock; budget timeouts around it.
+- Stalls on long agentic reads (poller "Incomplete" with only a preamble). Reserve for short-artifact adjudication.
+
+### Mistral  (`--model mistral` → via OpenRouter)
+- Fast, broad coverage, catches real issues.
+- **Hallucination risk is real:** has invented non-existent product models/specs, disputed independently by two judges. Cross-check every specific model number or product claim it introduces.
+
+### Claude  (in-council, when toggle on)
+- Consistently the most *calibrated* reviewer (no severity inflation; findings overwhelmingly Confirmed; bench-best street-cred in recent runs) but sometimes the least *original* — it can miss the boldest single catch. Treat as a reliability floor, not a discovery engine.
 
 ### (others — add as used)
 - Opus / o-series etc. are reachable via amicus **if their API keys are configured**. Add notes
@@ -114,3 +159,4 @@ This section keeps only per-model **qualitative quirks** and **structural-confor
   cap (superseded by `--prompt-file`), the absolute-path/cwd trap (fixed by F2), and the
   GUI-hangs-on-this-machine rule (resolved 2026-06-10; headless stays the council default by
   design). Config path updated to `~/.config/amicus/.env`.
+- **2026-07-02** — Folded back field lessons from runs 4-7 (AV-receiver, pork-shoulder, resume, novel ×2 councils): PowerShell `--models` quoting; current-date injection; long-read model selection; judge no-tools preamble; severity-inflation-justifies-dispute; five-keys tally schema; new Grok/Kimi/Mistral/Claude-in-council sections. Quantitative history stays in the ledger (`amicus council stats`).

package/skills/second-opinion/SKILL.md

@@ -18,6 +18,8 @@ Operating lessons from each run fold back into `MODEL-NOTES.md` (with approval),
 
 **Before launching any model, READ `MODEL-NOTES.md`** (next to this file). It holds the operating rules and per-model quirks that decide whether a run succeeds or silently fails. These were learned the hard way; skipping them wastes runs and produces empty results that look like answers.
 
+**Transport rule — CLI not on PATH:** every command below assumes the `amicus` CLI. If `amicus` is not on PATH (typical for **plugin-only installs**), run the identical commands as `npx -y amicus@latest <args>` (e.g. `npx -y amicus@latest fanout --models "m1,m2,m3" --prompt-file <path> --json`), or use the equivalent MCP tools (`amicus_fanout`, `amicus_start`, `amicus_status`, `amicus_read`, `amicus_council_tally`, `amicus_council_stats`, `amicus_verdict`) — council briefings are always self-contained (`--no-context`), so MCP transport is equivalent.
+
 ## When to use
 
 - The user provides documents, artifacts, or links **and** an analysis request **and** criteria, and wants other models to weigh in independently.
@@ -53,6 +55,10 @@ in this run is written here. Use its absolute path in all `--prompt-file` argume
 - Write every briefing to a temp file (`_tmp-*.md` in the run folder) and pass it with
   `--prompt-file` — never inline a briefing as a CLI argument. All `_tmp-*` files are cleaned up
   after the run.
+- **Inject the current date into every briefing when the artifact is time-sensitive** (resumes, dated
+  plans, anything with start/end dates or 'present' ranges). Headless council models do not reliably
+  know "today" and have raised false "future-dated" blockers; state the date explicitly, e.g.
+  "Today's date is YYYY-MM-DD."
 
 **Pick the council.** Default: **3 models from different families (non-Claude)**. Recommend them ranked by fit, consulting both the reviewer-reliability data from `amicus council stats` (the authoritative quantitative source — runs, avg peers-only street-cred, confirm-rate, fact-error rate) and the qualitative quirks in `MODEL-NOTES.md`. State the estimated cost. The estimate is the budget gate's pre-flight figure (per-$/Mtok pricing from the cached catalog; direct-provider legs without catalog pricing are disclosed as "cost unknown"). State it as an estimate, not a guarantee. **Disclose the run shape up front** before asking for confirmation — e.g.:
 
@@ -97,10 +103,12 @@ Each council model reviews **the artifact** independently. Write one Stage-1 bri
 (`_tmp-briefing-stage1.md` in the run folder) and launch the whole wave as ONE background call:
 
 ```
-amicus fanout --models <m1,m2,m3> --prompt-file <run-folder>/_tmp-briefing-stage1.md --json \
+amicus fanout --models "<m1,m2,m3>" --prompt-file <run-folder>/_tmp-briefing-stage1.md --json \
   --agent Plan --no-context --summary-length verbose --timeout <minutes>
 ```
 
+Always quote the `--models` list — unquoted, PowerShell splits on commas and the CLI receives one mangled alias (instant arg-parse failure).
+
 Run it in the background (`run_in_background: true`); you are notified on completion — do not
 poll. `fanout` is headless by definition. The command exits when every leg is terminal and prints
 ONE JSON wave document on stdout (`schemaVersion: 1`; the wave's id field is `waveId`, each leg's id is `taskId`): check `status` (`complete` | `partial` |
@@ -145,7 +153,7 @@ equivalent.
 Instruct models to emit the structured JSON verbatim after the prose, without preamble, so it parses cleanly.
 
 **After the wave returns, validate each leg's findings block** using `validateFindings` (Unit A — `src/council/findings.js`). If a leg's JSON fails validation:
-1. Issue a **solo `start --json`** re-prompt to that one model: "re-emit only the findings JSON, fixing: \<errors\>." Keep the first-pass prose. (Solo `start` is **not** subject to the WS-2 fanout cost gate, so a repair cannot be refused mid-council.)
+1. Issue a **solo `start --json`** re-prompt to that one model: "re-emit only the findings JSON, fixing: \<errors\>." Keep the first-pass prose. (Solo `start` passes through the **same budget gate** as `fanout`. If launching the wave required `--max-cost <$>` or `--no-cost-gate`, pass the **same flag on every repair re-prompt and on the chair call** — otherwise the gate can refuse a repair or the chair mid-council.)
 2. If still malformed, retry **once more** (cap = **2** re-prompts total).
 3. If still malformed after 2 retries, mark the review `unstructured` and hand-parse its prose into the schema. The review proceeds — never dropped for a formatting miss.
 
@@ -182,7 +190,7 @@ Each model **unknowingly ranks and adjudicates its own review** — this is the
 model. Write the bundle + judging instructions to `_tmp-bundle-stage2.md` and launch one wave:
 
 ```
-amicus fanout --models <m1,m2,m3> --prompt-file <run-folder>/_tmp-bundle-stage2.md --json \
+amicus fanout --models "<m1,m2,m3>" --prompt-file <run-folder>/_tmp-bundle-stage2.md --json \
   --agent Plan --no-context --summary-length verbose --timeout <minutes>
 ```
 
@@ -191,6 +199,12 @@ adjudication response. **Stage-2 degrade:** a judge leg dies → tally over the
 (≥ 1) and disclose the reduced bench in `crossreview-matrix.md`; tier definitions are unchanged
 (they already count "judges engaged"). Each judge is asked to do two things on the bundle:
 
+**Judge-briefing hardening (required).** Open `_tmp-bundle-stage2.md` with this preamble, verbatim, as its first line:
+
+> Do NOT use any tools or read any files; everything is in this message; begin immediately with A1:
+
+Plan-agent judges have wandered to tools mid-adjudication (reading files instead of judging and returning only narration), and a tool-capable judge can read the de-anonymized `review-<model>.md` files in the run folder — an anonymization leak. The preamble closes both. **Scratch-cwd (optional second layer):** launch the Stage-2 wave (and the Stage-3 chair call) with `--cwd <run-folder>/_scratch/` — create the empty directory first — so even a wandering agent finds nothing to read. Caveat: those legs' session records then live under `_scratch/.claude/amicus_sessions/`, so any later `amicus read <taskId>` for them needs the same `--cwd`.
+
 **Task A — Rank.** Order the reviews from most to least accurate and insightful. End the response with a parseable block in exactly this format (no other text on those lines):
 
 ```
@@ -205,11 +219,16 @@ FINAL RANKING:
 As each judge's ranking + adjudication response returns, collect it (the raw per-judge responses are working intermediates, not separate run-folder artifacts). Once all are in, **assemble the de-anonymized tally input** and then call `amicus council tally`:
 
 **Stage-2 → tally assembly recipe (Claude's work before calling `tally`):**
+0. **Build `meta` and `findings[]` first — `tally` requires both** (missing either fails with `BAD_ARGS: Cannot read properties of undefined (reading 'map')`):
+   - `meta` = `{ "runId": "<run-folder stem>", "models": [<every reviewed model id, including "claude" when the toggle is on — this is the street-cred universe>], "chair": "<confirmed chair model id>", "claudeInCouncil": <Stage-0 toggle> }`. Optional extras: `runType`, `date`.
+   - `findings[]` = one entry per finding across ALL reviews: `{ "id": "<run-global label id from step 1, e.g. A1>", "raiser": "<de-anonymized model that raised it>", "severity": "<from the review JSON>" }` (`claim` may be carried along but is not required).
 1. **Rewrite finding ids to run-global label ids.** Each Stage-1 review's local integer ids (`1`, `2`, `3`…) become `A1`, `A2`, `A3`… (where `A` is that review's anonymized label). The label↔model map (`Review A → deepseek`, etc.) is the key.
 2. **Build `adjudications`** — for every judge across all findings: `findingId` = run-global label id; `judge` = the model id (de-anonymized via the map); `verdict ∈ {agree, dispute, neutral}`. Include every judge's verdict on every finding. The raiser's own adjudication of its own finding is **included in the input** (the tally engine excludes it when computing peers-only tiers — do not pre-filter it).
 3. **Translate each judge's `FINAL RANKING:` block** — convert the label order (`1. Review C / 2. Review A / 3. Review B`) into a model `order` array via the same map (e.g. `{C→mistral, A→deepseek, B→gpt}` ⇒ `order: ["mistral","deepseek","gpt"]`). This is each entry in `rankings[]`.
 4. **Populate `runStats`** from the per-leg run documents emitted by `fanout --json` (and any solo red-team/chair `start --json` docs): copy `model`, `status`, `durationMs`, `usage` verbatim. Any leg with no run doc gets `durationMs: null` and `usage: null` — never invent a value. Attach `role` (`council` | `redteam` | `claude`), `wasChair`, and `conformance` (`clean` | `repaired` | `unstructured`) as council-domain labels.
 
+**Five-keys checklist — verify `tally-input.json` has ALL of:** `meta` (with `meta.models`), `findings`, `adjudications`, `rankings`, `runStats` (`runStats` may be `[]`; the other four are required). Do not call `tally` until all five are present.
+
 Then call:
 
 ```
@@ -240,11 +259,15 @@ amicus start --model <chair> --no-ui --json \
   --agent Plan --no-context --summary-length verbose --timeout <minutes>
 ```
 
+(The budget gate applies to this solo call too — if Stage 0 needed `--max-cost <$>` or `--no-cost-gate` to launch the wave, the chair call needs the same flag.)
+
 The run document's `summary` is the verdict. The packet contains:
 - All Stage-1 reviews (de-anonymized — model attribution restored)
 - All cross-review ranking outputs (with model attribution)
 - All adjudication outputs (with model attribution and `agree | dispute | neutral` verdicts per finding)
 
+Open `_tmp-chair-packet.md` with the no-tools preamble, adjusted for the chair: *'Do NOT use any tools or read any files; everything is in this message; begin immediately with the verdict.'* The packet is complete by construction — the chair must never go looking for files.
+
 Instruct the chair to write a **synthesized verdict** that:
 - Weighs each reviewer's findings by their peer-validated standing (street-cred rank and adjudication pattern)
 - Distinguishes findings the bench broadly endorsed from contested or singleton claims
@@ -307,15 +330,17 @@ Do not advance to Stage 5 until every finding in both tiers has a recorded decis
   — exact for `reported`, `~` for `estimated`, `?` for `unknown` — and never
   invent a figure. Add a wave **total cost** row from the wave document's
   `usage.cost` (`source: reported|estimated|mixed|unknown`). Any leg with no run doc → `durationMs: null`, `usage: null`; never invent a value.
-  - **Renderer:** once `verdict.json` is written, generate the human report with
-    `amicus council report <run-folder>/verdict.json --md > <run-folder>/report.md`
-    (use `--html` for a self-contained, shareable page). This emits the
+  - **Renderer:** once `verdict.json` is written, generate BOTH renderings:
+    `amicus council report <run-folder>/verdict.json --md > <run-folder>/report.md` and
+    `amicus council report <run-folder>/verdict.json --html > <run-folder>/report.html`.
+    **`report.html` is the default final artifact to hand the user** — a self-contained,
+    shareable page. This emits the
     adjudication matrix (finding × judge), the peers-only street-cred table, the
     findings-by-tier groupings (Disputed-first), and the per-model + wave cost —
     deterministic data only. Prefer it over hand-assembling the matrix; reserve
     prose for the chair's synthesis and the decision log.
 
-Tell the user exactly which files were written and where.
+Tell the user exactly which files were written and where, leading with `report.html`, **and present the verdict inline in chat** — the chair's overall assessment (verbatim or lightly trimmed) plus the tier counts (Confirmed/Disputed/Contested/Singleton) and what was applied. Never hand over only file paths.
 
 ---
 
@@ -323,6 +348,8 @@ Tell the user exactly which files were written and where.
 
 This stage updates `MODEL-NOTES.md` to make future runs better. **Nothing is written until the user approves a specific diff.**
 
+The `MODEL-NOTES.md` **next to this file** is your machine-local run ledger: npm updates never overwrite it (it is installed only if missing), so lessons accumulate per machine. Durable, machine-independent lessons get folded back into the version-controlled copy in the amicus repo at release time (see the release checklist in `docs/publishing.md`).
+
 **Reflect on this run.** Review the run for:
 - Failures, near-misses, and mitigations that worked (poller traps, empty responses, timeout issues, briefing problems)
 - Briefing wording that produced **richer or poorer** structured output than expected
@@ -432,6 +459,7 @@ Always **rank recommendations by fit**, state the trade-off for each option, and
     — exact for `reported`, `~` for `estimated`, `?` for `unknown` — and never
     invent a figure. Add a wave **total cost** row from the wave document's
     `usage.cost` (`source: reported|estimated|mixed|unknown`). Any leg with no run doc → `durationMs: null`, `usage: null`.
+  - `report.html` — the same report rendered as a self-contained page (`amicus council report <verdict.json> --html`); the default artifact to share.
 - Reviewed copy: `<stem>-reviewed.<ext>`, next to the source.
 - Temp working files (`_tmp-*.md`: extracts, stage briefings, red-team brief, bundle, chair packet, proposed
   MODEL-NOTES diff) live in the run folder and are cleaned up at the end of the run — the proposed-diff file
@@ -441,5 +469,5 @@ Always **rank recommendations by fit**, state the trade-off for each option, and
 
 ## Files
 
-- `MODEL-NOTES.md` — operating rules, per-model qualitative quirks, cost guardrail, and structural-conformance notes. **Read it before Stage 0 (council selection and launch); update qualitative notes (with approval) in Stage 6.** Quantitative reliability data (runs, avg street-cred, confirm-rate, fact-error rate) comes from `amicus council stats`, not this file.
+- `MODEL-NOTES.md` — operating rules, per-model qualitative quirks, cost guardrail, and structural-conformance notes. **Read it before Stage 0 (council selection and launch); update qualitative notes (with approval) in Stage 6.** Quantitative reliability data (runs, avg street-cred, confirm-rate, fact-error rate) comes from `amicus council stats`, not this file. This copy is machine-local (never overwritten on update); the shipped seed lives in the amicus repo and absorbs durable lessons at release time.
 - `COUNCIL-DESIGN.md` — the design spec this skill implements (v3 + WS-3). Consult it if a mechanics question arises that the skill prose does not resolve.