amicus 4.5.4 → 4.6.1

package/.claude-plugin/plugin.json

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

@@ -3,6 +3,119 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [Unreleased]
+
+## [4.6.1] - 2026-08-03
+
+### Added
+
+- **The MCP channel finally hears about new versions** (spec 2026-08-03). The MCP server now
+  runs the update check at startup and appends one flavor-aware notice block to the first
+  successful tool result of each server process (once per session, latched); `amicus_guide`
+  carries an always-on update line, and one `[amicus] update available` line lands in the
+  client's MCP log on stderr. The instruction is chosen config-first (`npx -y amicus@latest`
+  registrations are told a restart suffices; cached/pinned npx copies get the re-point-or-
+  clear-cache hint in the unverified voice; global installs get `npm install -g amicus`, from
+  where #33's stale-version warning takes over). Words only — no auto-update over MCP, no
+  periodic re-check; `NO_UPDATE_NOTIFIER=1` still disables the check entirely.
+- **A lost Stage-1 seat gets one more chance (SL-2).** A council sub-wave that dies before
+  its legs exist, or a leg that ends with no usable output, is relaunched exactly once —
+  serially, after the surviving launches settle. Recovery announces in the one voice
+  (`Recovered: seat X reviewed on retry — …`, a `stage1-retry` heal on
+  `run.json`/`verdict.json` `degrades[]`) and the run stays exit 0; a seat still dead after
+  its retry degrades exactly as before, with both attempts named in the why. Unconditional;
+  gated on the run's `--max-cost` position (an over-budget run skips the retry and records
+  the loss byte-identically to v4.6.0). Retry legs and their spend-ledger rows carry
+  `retryOfWaveId`. A healed critic counts as seated in `verdict.seatLoss`.
+
+### Changed
+
+- **The shipped second-opinion MODEL-NOTES seed was corrected and enriched** (owner-ruled
+  fold-back, PR #93): the haiku "hard-404" warning re-caused to the `ANTHROPIC_BASE_URL` `/v1`
+  convention split, GLM's stale reliability caution withdrawn on the v4.4.1 fence-extractor
+  replay evidence, pre-degrade-era claims re-grounded in the current announce/retry contract,
+  and three model sections plus the "peer consensus ≠ evidence on published numbers" rule added
+  from the field.
+
+### Removed
+
+- **The unused `rebuildElectron` remediation hint** (owner ruling 2026-08-03, closing Plan 3's
+  queued hint-voice question). It had no live call site — `doctor --fix`, the in-place Electron
+  self-heal, is its stated convergence target — and its prose asserted unverified causes ("after
+  an ABI mismatch or partial unpack"). Absence-pinned in `tests/remediation-hints.test.js`; a
+  reintroduction must adopt the unverified-cause voice. The same ruling keeps
+  `sweepSessionIndexTmp`'s confident voice: its cause is definitional (an atomic-write tmp orphan
+  has no other producer), not a guess.
+
+## [4.6.0] - 2026-08-02
+
+### Added (v4.6 milestone — the degrade announcement invariant, plans 1-4)
+
+- **The ten-channel degrade announcement contract.** A council run can no longer degrade its
+  exit code without announcing what was lost: every loss routes through one sink
+  (`src/council/run-degrade.js`, the only code allowed to flip `degraded.value` — enforced by a
+  source-scan invariant test) and lands with mandatory *what/why/effect* on stderr,
+  `run.json.degrades[]`, `verdict.json.degrades[]`, and the report's new **"What was lost"**
+  section, all rendered in one voice.
+- **`verdict.seatLoss` is now derived from the degrade records** (closes #84) — a dead critic
+  *leg* finally flips `criticSeated`, and `seatLoss` can no longer disagree with `degrades[]`.
+  The v4.5.2 seatLoss shape is unchanged (its tests passed byte-unedited).
+- **Stage-2 judge legs get `runStats` rows** (closes #83) — per-leg cost attribution for ~38%
+  of a run's spend that had none, judge-tagged in the report's cost table.
+- **`doctor` speaks the same language**: `doctor --json` gains additive `degrades[]`;
+  `doctor --fix` prints `Recovered:` lines for every repair; the engine hints state causes as
+  **unverified** instead of asserting an antivirus guess.
+- **The Workspace is discoverable from the CLI**: `watch` usage names `--ui` (closes #80), and
+  a CLI council run with Electron present prints how to open the live Workspace (closes #81 —
+  the silence half; auto-open parity remains a product decision).
+
+### Changed (v4.6 — deliberate behavior changes)
+
+- **A dropped preset member now degrades the run to exit 2 on every transport** (was: exit 0
+  with a `--json`-blind stderr notice). The loss is announced per-member with its reason.
+- **A shared-server acquisition failure now exits degraded (2)** (was: stderr + run.json only,
+  exit 0) — the per-wave fallback is the racy configuration and the run says so.
+- **Reported cost totals rise** for identical runs versus v4.5.x: judge legs now appear in
+  `runStats`. Consumers keying `runStats` by model must exclude `role: 'judge'` (as the
+  ledger's reliability join now does).
+- In-run degrade notices hedge the exit-code claim truthfully ("will exit degraded (2)");
+  `engineMissing`/`reinstallEngineAv` hint prose changed to the unverified voice (commands
+  byte-identical).
+
+### Fixed (v4.6)
+
+- **A dead Stage-1 leg was announced on no surface at all** (closes #85) — the only trace was
+  its absence from the stage entry's `taskIds`. Now named everywhere, with a regression pin.
+- **The Stage-5 verdict rebuild silently destroyed `seatLoss`/`degrades[]`** (closes #87) —
+  `tally.json` carries neither, so the decisions flow dropped both; now preserved from the run
+  folder's verdict the same way the chair's synthesis already was, on both CLI and MCP.
+- **`watch --ui` against an `--out-dir` run failed with a symptom, not a cause** (closes #82) —
+  the error now names the launch-directory pointer and the working invocation.
+
+### Fixed
+
+- **`/amicus:council` lost all of its frontmatter at load time.** `commands/council.md`'s
+  `argument-hint` value began with `[material, path, or URL] [...]`, which YAML reads as a flow
+  sequence followed by a second, unexpected `[` — the whole block failed to parse, so the command
+  loaded with empty metadata: no description, no argument hint, and `disable-model-invocation:
+  true` silently dropped (the command was model-invocable, the opposite of the intent). The value
+  is now single-quoted. Present since `3900429` (Phase 9a, 2026-07-02); `claude plugin validate
+  .claude-plugin/plugin.json` failed on it, non-strict, that entire time.
+- **The preflight that should have caught it was validating the wrong file.** With `.claude-plugin/`
+  holding both manifests, `claude plugin validate .` resolves the *marketplace* manifest and
+  reports `✔ Validation passed` without ever inspecting the plugin. `docs/DISTRIBUTION.md` §2 now
+  documents the path trap, prescribes `claude plugin validate .claude-plugin/plugin.json`, and
+  records why `--strict` is expected to fail here (the deliberately retained root-`CLAUDE.md`
+  warning).
+
+### Changed
+
+- **`tests/plugin-commands.test.js` now YAML-parses frontmatter** for `commands/council.md` and
+  both skills, asserting `description`, `argument-hint` (as a *string*), and
+  `disable-model-invocation: true` survive parsing. The previous
+  `expect(md).toContain('argument-hint:')` substring checks passed happily against a file that
+  could not parse. `yaml` added as a devDependency for this.
+
 ## [4.5.4] - 2026-08-01
 
 ### Fixed

package/README.md

@@ -441,7 +441,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.5.4",
+  "version": "4.6.1",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/commands/council.md

@@ -1,6 +1,6 @@
 ---
 description: Run a structured multi-model LLM council review of the given material — wraps the second-opinion skill (independent reviews → anonymous cross-review → non-Claude chair verdict → accept/deny decisions).
-argument-hint: [material, path, or URL] [analysis request + criteria] [optional elements — e.g. "with a critic seat", "debate mode", "expert lenses", "chair verdict scale"]
+argument-hint: '[material, path, or URL] [analysis request + criteria] [optional elements — e.g. "with a critic seat", "debate mode", "expert lenses", "chair verdict scale"]'
 disable-model-invocation: true
 ---
 

package/docs/DISTRIBUTION.md

@@ -50,17 +50,36 @@ users only see a version bump when we bump it, not on every commit. Treat
 ### Preflight (run before every submission or major post-listing update)
 
 ```bash
-claude plugin validate . --strict
+claude plugin validate .claude-plugin/plugin.json    # the PLUGIN check — see the path trap below
+claude plugin validate .                             # the marketplace manifest (separate check)
 claude --plugin-dir .   # smoke: /amicus:council, /amicus:sidecar, /amicus:second-opinion, MCP tools
 npm test
 ```
 
-- `claude plugin validate . --strict` is the same structural check the
-  review pipeline runs; `--strict` promotes unrecognized-field warnings to
-  errors so nothing slips through that CI would later flag. It needs the
-  Claude Code CLI installed locally — it is **not** wired into this repo's
-  CI (runners have no `claude` auth), so `tests/plugin-manifest.test.js` is
-  the CI-side proxy for manifest completeness.
+- **Path trap — `claude plugin validate .` does NOT validate the plugin.**
+  This repo's `.claude-plugin/` holds *both* `marketplace.json` and
+  `plugin.json`; given `.`, the CLI resolves the marketplace manifest, prints
+  `Validating marketplace manifest:` / `✔ Validation passed`, and never looks
+  at the plugin, its commands, or its skills. Always pass
+  `.claude-plugin/plugin.json` explicitly for the plugin check — that is the
+  surface the review pipeline evaluates. (This masked a real defect for a
+  month: `commands/council.md` shipped an unparseable `argument-hint` from
+  2026-07-02 until 2026-08-01 while `.` reported clean. Read the first line
+  of the output — it names which manifest was actually checked.)
+- `claude plugin validate` is the same structural check the review pipeline
+  runs. It needs the Claude Code CLI installed locally — it is **not** wired
+  into this repo's CI (runners have no `claude` auth), so
+  `tests/plugin-manifest.test.js` and `tests/plugin-commands.test.js` are the
+  CI-side proxies. The latter now YAML-parses the command and skill
+  frontmatter (`yaml` is a devDependency for exactly this); substring
+  assertions like `toContain('argument-hint:')` cannot see a parse failure,
+  which is how the `council.md` defect passed CI.
+- **`--strict` is expected to FAIL here, by design.** It promotes the
+  root-`CLAUDE.md` warning ("not loaded as project context") to an error. The
+  plugin root is the repo root, and `CLAUDE.md` is this repo's development
+  context — we keep it deliberately. Use the non-strict run as the gate and
+  read the warning list by eye; a *new* warning is the signal, not the
+  `CLAUDE.md` one.
 - `claude --plugin-dir .` loads the plugin from the working tree so you can
   manually confirm `/amicus:council`, `/amicus:sidecar`, and
   `/amicus:second-opinion` all appear in the command picker exactly once,
@@ -68,10 +87,18 @@ npm test
 - `npm test` must be green, specifically `tests/plugin-manifest.test.js`
   and `tests/plugin-commands.test.js`.
 
-**Known current-tree preflight result (checked 2026-07-02, `p9/distribution`
-at a1bea3c):** `claude plugin validate . --strict` passes clean, exit 0.
-(History: `--strict` previously flagged an unknown `plugin.json → bugs`
-field; that field was removed in commit `4207485`, so the warning is gone.)
+**Known current-tree preflight result (checked 2026-08-01, on
+`fix/plugin-frontmatter-validation`):**
+`claude plugin validate .claude-plugin/plugin.json` → exit 0,
+`✔ Validation passed with warnings` (the one retained root-`CLAUDE.md`
+warning). With `--strict` → exit 1 on that same warning, as documented above.
+`claude plugin validate .` → exit 0 on the marketplace manifest.
+
+History of this line: it previously read "`claude plugin validate . --strict`
+passes clean, exit 0" as of 2026-07-02 — measured against the *marketplace*
+manifest via the path trap above, while the plugin itself had a hard
+frontmatter error in `commands/council.md`. Older still: `--strict` flagged an
+unknown `plugin.json → bugs` field, removed in commit `4207485`.
 
 ### Submit
 

package/docs/ROADMAP.md

@@ -7,12 +7,14 @@ major jump, gated on funding/cofounder. The observability arc is split so the **
 first (v4.3)** and the **Electron "Council Workspace" (v4.4)** rides on top of it. `--dry-run` cost
 preview dropped to the backlog.
 
-Amicus is at **v4.5.0** (tagged 2026-07-28). Each 4.x rev below leads with the benefit, not the
+Amicus is at **v4.6.0** (tagged 2026-08-02). Each 4.x rev below leads with the benefit, not the
 plumbing.
 
-**Status:** v4.0 through **v4.5.0** have **shipped** — everything down to the v4.6 heading is a
-record of what landed, not a plan. **v4.6 (composition + tagging + GUI ergonomics) is the next
-rev.** v5.0 remains forward-looking.
+**Status:** v4.0 through **v4.6.0** have **shipped** — everything down to the v4.7 heading is a
+record of what landed, not a plan. **v4.7 (composition + tagging + GUI ergonomics) is the next
+planned rev** — that scope carried the number v4.6 here until the degrade-announcement-invariant
+milestone took the v4.6.0 release (2026-08-02); renumbered, not descoped. v5.0 remains
+forward-looking.
 
 > 📁 **Reading this from an npm install?** Some references below point at working documents that
 > live in the git repository and are deliberately **not** in the published package — anything under
@@ -95,7 +97,7 @@ stops hiding. Design: `docs/superpowers/specs/2026-07-27-v4.5-save-and-share-des
   client best able to show it. *(S–M; the pieces exist — see the design notes below.)*
 - **Council policy packs + full run-profiles** (bench + lenses + options + briefing template, invoke by name) — B7/F5 *(M)*
 - **Briefing templates + library** (F9) *(S–M)* — the foundation packs reference; the `{{input}}`
-  chaining variable and the `critique`/`refine` built-ins arrive with v4.6
+  chaining variable and the `critique`/`refine` built-ins arrive with the composition rev (now v4.7)
 - **Ride-along fixes** — FR-1 (a failed council seat can render perpetually live), the FR-2 ruling,
   RN-1/RN-5/RN-11 Workspace renderer fixes, TST-3 real-CDP abort pass *(S each; dispositions for
   all 17 open items are tabled in the design doc's §8)*
@@ -103,7 +105,37 @@ stops hiding. Design: `docs/superpowers/specs/2026-07-27-v4.5-save-and-share-des
 > Why here: save/share velocity multipliers that only pay off once councils are a command (v4.0)
 > and observable (v4.3/v4.4); auto-open makes the v4.4 surface discoverable on its best client.
 
-## v4.6 — "Compose your councils" *(specced after v4.5 ships — anti-rot rule)*
+## v4.6 — "A loss announces itself" *(the degrade announcement invariant)* — ✅ SHIPPED v4.6.0, 2026-08-02
+**Benefit:** a council run can no longer degrade quietly — every loss states what was lost, why,
+and what it does to the run, in one voice, on every surface (stderr, `run.json`, `verdict.json`,
+the report, `doctor`). The north star made mechanical: a correct-but-silent degrade fails the bar
+as hard as a crash.
+- **The ten-channel degrade announcement contract** — every loss routes through one sink
+  (`src/council/run-degrade.js`, the only code allowed to flip `degraded.value`, enforced by a
+  source-scan invariant test) and lands with mandatory what/why/effect on every surface, including
+  the report's new **"What was lost"** section — #85 *(L)*
+- **`verdict.seatLoss` derived from the degrade records** (#84 — a dead critic *leg* finally flips
+  `criticSeated`; the v4.5.2 seatLoss suites passed byte-unedited) + **Stage-2 judge legs get
+  `runStats` cost rows** (#83 — per-leg attribution for ~38% of a run's spend that had none) *(M)*
+- **`doctor` speaks the vocabulary** — `doctor --json` gains additive `degrades[]`, `--fix` prints
+  `Recovered:` lines in the one voice, and the engine hints state causes as **unverified** instead
+  of asserting an antivirus guess *(M)*
+- **Workspace discoverability from the CLI** — `watch` usage names `--ui` (#80), a CLI council run
+  with Electron present prints how to open the live Workspace (#81), `watch --ui` against an
+  `--out-dir` run names its cause (#82), and the Stage-5 verdict rebuild preserves
+  `seatLoss`/`degrades[]` (#87) *(S each)*
+- **Deliberate behavior changes** — dropped preset members and shared-server acquisition failures
+  now exit degraded (2) on every transport; judge rows raise reported cost totals vs v4.5.x
+  (`runStats` consumers keying by model must exclude `role: 'judge'`).
+- **Docs** — the full record is `CHANGELOG.md` §4.6.0; spec
+  `docs/superpowers/specs/2026-08-01-degrade-announcement-invariant-design.md`; plans 1–4 under
+  `docs/superpowers/plans/` (`2026-08-0*-v4.6-degrade-invariant-plan-*.md`).
+> Why it jumped the queue (2026-08-01): the v4.5.x field reports showed the engine was not losing
+> legs (11 four-seat council runs on v4.5.4, 10 clean) — but when a seat *was* lost, nothing told
+> the user which one. That silent-degrade class was ruled a north-star violation and took the rev
+> number; the composition scope below moved to v4.7.
+
+## v4.7 — "Compose your councils" *(renumbered from v4.6, 2026-08-02 — spec + fresh plan at kickoff per the anti-rot rule)*
 **Benefit:** councils chain — generate → critique → refine with no manual copy-paste — and history
 becomes navigable.
 - **Composable/chained waves** (`--input-from <id>` / `--prompt-file -` pipe + per-source digests) —
@@ -115,8 +147,8 @@ becomes navigable.
   remainder of TST-7
 - **README + docs update** *(S)*
 > The 2026-07-19 combined spec (`2026-07-19-v4.5-policy-packs-composition-design.md`) holds the
-> approved chaining/tagging/F10 design detail and is the primary input to the v4.6 brainstorm; it
-> is NOT executed as-written — v4.6 gets its own spec + fresh plan once v4.5 ships.
+> approved chaining/tagging/F10 design detail and is the primary input to the v4.7 brainstorm; it
+> is NOT executed as-written — v4.7 gets its own spec + fresh plan at kickoff.
 
 ### Deferred out of v4.4.1 into v4.5 (2026-07-27)
 

package/docs/publishing.md

@@ -48,7 +48,7 @@ Provenance is implied under trusted publishing.
 
 Run top-to-bottom before `npm version`:
 
-1. **MODEL-NOTES fold-back:** diff the machine-local ledger (`~/.claude/skills/second-opinion/MODEL-NOTES.md`) against the shipped seed (`skills/second-opinion/MODEL-NOTES.md`); port durable, machine-independent lessons into the shipped file (merge/prune, keep it tight — no run-ledger numbers, those live in `amicus council stats`).
+1. **MODEL-NOTES fold-back:** diff the machine-local ledger (`~/.claude/skills/second-opinion/MODEL-NOTES.md`) against the shipped seed (`skills/second-opinion/MODEL-NOTES.md`); cherry-pick generalizable lessons from the local ledger into the shipped seed — **per-section judgment, both directions, never a bulk copy** (the divergence is two-directional: adopt seed-side corrections back into the local ledger too). Merge/prune, keep it tight — no run-ledger numbers, those live in `amicus council stats`. Standing practice per the owner's ruling, 2026-08-03: shipped = curated seed, local = lab notebook.
 2. `npm test` green; `npm run lint` clean.
 3. **Integration tier, both rails:**
    - `npm run test:integration` (keyless) — must be **0 failures**. This is the same thing the `integration` job in `ci.yml` runs on every push, so it should already be green.

package/docs/usage.md

@@ -443,7 +443,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.5.4",
+  "version": "4.6.1",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.5.4",
+  "version": "4.6.1",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [
@@ -95,7 +95,8 @@
     "lint-staged": "^16.3.2",
     "puppeteer": "^24.36.0",
     "sharp": "^0.35.3",
-    "ws": "^8.19.0"
+    "ws": "^8.19.0",
+    "yaml": "^2.9.0"
   },
   "engines": {
     "node": ">=22.12.0"

package/schemas/council-run.schema.json

@@ -82,6 +82,26 @@
         "at": { "type": "string" }
       }
     },
+    "degrades": {
+      "description": "v4.6 Plan 1: every degrade/heal the sink announced — additive, written by run-degrade.js.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "channel", "what", "why", "effect"],
+        "properties": {
+          "kind": { "enum": ["degrade", "heal"] },
+          "channel": { "type": "string" },
+          "what": { "type": "string" },
+          "why": { "type": "string" },
+          "effect": { "type": "string" },
+          "remedy": { "type": "string" },
+          "data": {
+            "type": "object",
+            "description": "v4.6 Plan 2: optional structured facts for derivations (e.g. dead-leg {seat,status,reason}, dead-wave {waveId,models,reason}). Prose fields stay the human surface."
+          }
+        }
+      }
+    },
     "debate": {
       "type": "object",
       "properties": {

package/schemas/council-verdict.schema.json

@@ -205,6 +205,26 @@
         "criticRequested",
         "criticSeated"
       ]
+    },
+    "degrades": {
+      "description": "v4.6 Plan 2: what this run lost — copied verbatim from the sink at verdict assembly. Additive; absent on a clean run.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "channel", "what", "why", "effect"],
+        "properties": {
+          "kind": { "enum": ["degrade", "heal"] },
+          "channel": { "type": "string" },
+          "what": { "type": "string" },
+          "why": { "type": "string" },
+          "effect": { "type": "string" },
+          "remedy": { "type": "string" },
+          "data": {
+            "type": "object",
+            "description": "v4.6 Plan 2: optional structured facts for derivations (e.g. dead-leg {seat,status,reason}, dead-wave {waveId,models,reason}). Prose fields stay the human surface."
+          }
+        }
+      }
     }
   }
 }

package/schemas/doctor.schema.json

@@ -21,7 +21,29 @@
           "name": { "type": "string" },
           "status": { "type": "string" },
           "message": { "type": ["string", "null"] },
-          "hint": { "type": ["string", "null"] }
+          "hint": { "type": ["string", "null"] },
+          "fixed": { "type": "boolean" },
+          "fixDetail": { "type": "string" }
+        }
+      }
+    },
+    "degrades": {
+      "description": "v4.6 Plan 3: failed checks and --fix repairs in the shared degrade/heal vocabulary — additive, absent when clean.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "channel", "what", "why", "effect"],
+        "properties": {
+          "kind": { "enum": ["degrade", "heal"] },
+          "channel": { "type": "string" },
+          "what": { "type": "string" },
+          "why": { "type": "string" },
+          "effect": { "type": "string" },
+          "remedy": { "type": "string" },
+          "data": {
+            "type": "object",
+            "description": "v4.6 Plan 3: optional structured facts for derivations (doctor: {checkId}). Prose fields stay the human surface."
+          }
         }
       }
     }