amicus 4.0.1 → 4.1.1

package/src/council/report.js

@@ -20,7 +20,19 @@ function toModel(verdict, wave) {
   if (!verdict || !Array.isArray(verdict.findings)) {
     throw new Error('verdict.json must have a findings[] array');
   }
-  const judges = verdict.council || [];
+  const council = verdict.council || [];
+  // 'council' (verdict.council / meta.models) is the street-cred universe and
+  // legitimately includes 'claude' on a --claude-review run (run-assemble.js:
+  // 123-125, docs/council.md:326). 'judges' is the adjudication-matrix column
+  // set: SKILL.md:482 / run-stages.js:162-163 guarantee Claude is judged but
+  // never judges, so its reserved seat must never grow a matrix column — filter
+  // it out ONLY when claudeInCouncil is true. This is name+flag gated, not
+  // vote-derived: a bench judge that cast zero adjudications (dead/unstructured
+  // leg, run-stages.js:204-207) is still in council/judges and must still get
+  // its (blank) column — deriving the roster from "who actually voted" would
+  // silently delete that column too and break the byte-unchanged-artifact
+  // contract for degraded v4.0.1-shaped runs.
+  const judges = verdict.claudeInCouncil === true ? council.filter(j => j !== 'claude') : council;
   const findings = verdict.findings.map((f) => {
     const byJudge = {};
     for (const j of judges) { byJudge[j] = null; }
@@ -28,9 +40,30 @@ function toModel(verdict, wave) {
     return {
       id: f.id, severity: f.severity, raiser: f.raiser, tier: f.tier,
       basis: f.basis || { a: 0, d: 0, n: 0 }, decision: f.decision || null,
-      applied: f.applied === true, byJudge,
+      applied: f.applied === true, byJudge, debate: f.debate || null,
     };
   });
+  // 'movements' is deliberately re-vote-only (defended/amended): a withdrawn or
+  // no-response finding is never bundled into the re-vote (run-debate.js's
+  // bundleFor()), so its tier — even if it happens to differ from previousTier —
+  // was never "moved after re-vote". Listing it there would read as "still live,
+  // just downgraded" when it was actually retracted; withdrawn findings get their
+  // own list below so a reader can tell the two apart.
+  // no-response findings (spec §5.7: a dead defense leg, or one still
+  // unstructured after its single repair, makes that raiser's bundled
+  // findings all 'no-response') get their own list, same idiom as withdrawn —
+  // silently dropping them would leave a "## Debate round" heading with
+  // nothing beneath it whenever a run's only debating raiser never responded.
+  const debate = {
+    present: findings.some(f => f.debate) === true,
+    withdrawn: verdict.findings.filter(f => f.debate && f.debate.action === 'withdrawn')
+      .map(f => ({ id: f.id, previousTier: f.debate.previousTier, tier: f.tier })),
+    movements: verdict.findings.filter(f => f.debate && f.debate.action !== 'withdrawn' && f.debate.action !== 'no-response'
+        && f.debate.previousTier && f.debate.previousTier !== f.tier)
+      .map(f => ({ id: f.id, action: f.debate.action, previousTier: f.debate.previousTier, tier: f.tier })),
+    noResponse: verdict.findings.filter(f => f.debate && f.debate.action === 'no-response')
+      .map(f => ({ id: f.id, previousTier: f.debate.previousTier, tier: f.tier })),
+  };
   const runStats = verdict.runStats || [];
   const costRows = runStats.map(r => ({
     model: r.model, status: r.status, durationMs: r.durationMs,
@@ -40,10 +73,10 @@ function toModel(verdict, wave) {
   return {
     header: {
       runType: verdict.runType || 'review', runId: verdict.runId, date: verdict.date,
-      chair: verdict.chair, council: judges, claudeInCouncil: verdict.claudeInCouncil === true,
+      chair: verdict.chair, council, claudeInCouncil: verdict.claudeInCouncil === true,
     },
     tierCounts: verdict.tierCounts || { Confirmed: 0, Contested: 0, Singleton: 0, Disputed: 0 },
-    judges, findings,
+    judges, findings, debate,
     streetCred: verdict.streetCred || [],
     cost: { rows: costRows, total },
   };
@@ -92,6 +125,33 @@ function renderMd(m) {
     out.push('');
   }
 
+  // Defensive: never emit the heading unless at least one grouping has
+  // content — a heading over nothing is worse than no heading.
+  if (m.debate.present && (m.debate.withdrawn.length || m.debate.movements.length || m.debate.noResponse.length)) {
+    out.push('\n## Debate round\n');
+    if (m.debate.withdrawn.length) {
+      out.push('**Withdrawn by raiser:**');
+      for (const w of m.debate.withdrawn) {
+        const arrow = w.previousTier && w.previousTier !== w.tier ? `${w.previousTier} → ${w.tier}` : (w.previousTier || w.tier);
+        out.push(`- ${w.id}: ${arrow} (withdrawn — no longer live)`);
+      }
+      out.push('');
+    }
+    if (m.debate.movements.length) {
+      out.push('**Tier movements after re-vote:**');
+      for (const mv of m.debate.movements) { out.push(`- ${mv.id}: ${mv.previousTier} → ${mv.tier} (${mv.action})`); }
+      out.push('');
+    }
+    if (m.debate.noResponse.length) {
+      out.push('**No response (raiser did not defend):**');
+      for (const nr of m.debate.noResponse) {
+        const arrow = nr.previousTier && nr.previousTier !== nr.tier ? `${nr.previousTier} → ${nr.tier}` : (nr.previousTier || nr.tier);
+        out.push(`- ${nr.id}: ${arrow} (no response — original stands)`);
+      }
+      out.push('');
+    }
+  }
+
   out.push('## Cost\n');
   out.push('| Model | Status | Duration | Cost |\n|---|---|---|---|');
   for (const r of m.cost.rows) { out.push(`| ${r.model} | ${r.status} | ${fmtDur(r.durationMs)} | ${formatCost(r.cost)} |`); }

package/src/council/run-assemble.js

@@ -3,13 +3,17 @@
 
 /**
  * @module council/run-assemble
- * Pure assembly + artifact emission for the headless council engine (spec §5):
- * the five-keys tally input (meta pins: claudeInCouncil false, models = bench
- * seats exactly — critic included, chair excluded — runType 'headless'),
- * runStats rows copied verbatim from leg docs, and the run-dir artifact set
- * (tally-input.json, tally.json, verdict.json with overallVerdict, report.html,
- * chair-output.md). Raiser self-votes are INCLUDED in adjudications — exclusion
- * is tally's job (tally.js:95); judged is tally's job (tally.js:110).
+ * Assembly + artifact emission for the headless council engine (spec §5), plus
+ * the `--claude-review` pre-flight it now also owns: the five-keys tally input
+ * (meta pins: claudeInCouncil false, models = bench seats exactly — critic
+ * included, chair excluded — runType 'headless'), runStats rows copied
+ * verbatim from leg docs, the run-dir artifact set (tally-input.json,
+ * tally.json, verdict.json with overallVerdict, report.html, chair-output.md),
+ * v4.1 §4.4 pre-flight validation of the file-sourced Claude review
+ * (preflightClaudeReview — the reserved-seat/chair/critic guards), its review-N+1
+ * labelling (labelClaudeReview), and its synthesized null-usage runStats row
+ * (claudeRunStatsRow). Raiser self-votes are INCLUDED in adjudications —
+ * exclusion is tally's job (tally.js:95); judged is tally's job (tally.js:110).
  */
 
 const fs = require('fs');
@@ -17,9 +21,15 @@ const path = require('path');
 const { writeFileAtomic } = require('../utils/atomic-write');
 const { buildVerdict, writeVerdictAtomic } = require('./verdict');
 const { buildReport } = require('./report');
+const { validateFindings } = require('./findings');
+const { toGlobalFindings } = require('./anonymize');
 
 const CONFORMANCE_RANK = { clean: 0, repaired: 1, unstructured: 2 };
 
+/** v4.1 §4.4: the reserved seat name for the file-sourced Claude review. */
+const CLAUDE_SEAT = 'claude';
+const CLAUDE_REVIEW_ERROR = 'COUNCIL_CLAUDE_REVIEW_INVALID';
+
 /** Worst-wins merge of Stage-1 findings conformance and Stage-2 judge conformance. */
 function worseConformance(a, b) {
   return (CONFORMANCE_RANK[a] || 0) >= (CONFORMANCE_RANK[b] || 0) ? a : b;
@@ -43,14 +53,79 @@ function buildRunStatsEntry({ leg, model, role, wasChair, conformance }) {
   };
 }
 
+/**
+ * Pre-flight for `--claude-review <path>` (v4.1 §4.4). Runs AFTER initRun (so the
+ * error doc lands in a run dir that exists) and BEFORE any launch, so an invalid
+ * file costs zero spend. The orchestrator authored the file, so there is no repair
+ * loop — fix and relaunch is free.
+ * @param {{claudeReviewFile: ?string, chair: ?string, critic: ?string, models: ?Array<string>}} o run options
+ * @returns {{claudeReview: object|null, error: ?{code: string, message: string}}}
+ */
+function preflightClaudeReview(o) {
+  if (!o.claudeReviewFile) { return { claudeReview: null, error: null }; }
+  const bad = (detail) => ({ claudeReview: null,
+    error: { code: CLAUDE_REVIEW_ERROR, message: `council_claude_review_invalid: ${detail}` } });
+  if (o.chair === CLAUDE_SEAT) {
+    return bad('claude may not chair (it is judged, never votes or chairs)');
+  }
+  if (o.critic === CLAUDE_SEAT) {
+    return bad("'claude' is a reserved seat name and cannot be the critic");
+  }
+  if (Array.isArray(o.models) && o.models.includes(CLAUDE_SEAT)) {
+    // 'claude' is a reserved seat name for the file-sourced review N+1 (it
+    // joins meta.models synthetically — see buildTallyInput). A real bench
+    // leg ALSO named 'claude' would collide on that same key: labelMap gets
+    // two 'claude' entries, and ledger.js's Map join lets the synthesized
+    // claude row overwrite the real leg's role/conformance/wasChair and
+    // double-count findingsRaised — permanently, since the ledger is
+    // append-only. Reject it here so every entry point (CLI, MCP, GitHub
+    // Action, direct require('./council/run')) is covered, not just the
+    // CLI's option whitelist.
+    return bad("'claude' is a reserved seat name and cannot also appear in --models");
+  }
+  let text = '';
+  try { text = fs.readFileSync(o.claudeReviewFile, 'utf-8'); }
+  catch (e) { return bad(`cannot read ${o.claudeReviewFile}: ${e.message}`); }
+  const v = validateFindings(text);
+  if (!v.ok) { return bad(v.errors.map(e => `${e.code}: ${e.detail}`).join('; ')); }
+  return { claudeReview: { model: CLAUDE_SEAT, text, findings: v.findings }, error: null };
+}
+
+/**
+ * Stamp the file-sourced Claude review with its label (always the LAST entry —
+ * review N+1) and its run-global finding ids. Mutates + returns the new ids so
+ * run.js can concat them onto the bench's globalFindings in one expression.
+ * @returns {Array<object>} claude's run-global findings
+ */
+function labelClaudeReview(claudeReview, labels) {
+  const e = labels.entries[labels.entries.length - 1];
+  claudeReview.label = e.label;
+  claudeReview.globalFindings = toGlobalFindings(e.letter, CLAUDE_SEAT, claudeReview.findings);
+  return claudeReview.globalFindings;
+}
+
+/**
+ * The synthesized runStats row for a review that never ran a leg (v4.1 §4.4).
+ * durationMs/usage are null per the never-invent rule — nothing was launched.
+ */
+function claudeRunStatsRow() {
+  return { model: CLAUDE_SEAT, role: CLAUDE_SEAT, wasChair: false, conformance: 'clean',
+    status: 'complete', durationMs: null, usage: null };
+}
+
 /**
  * Assemble the five-keys tally input (spec §5 / SKILL.md Stage-2 recipe).
  * @param {{runId: string, date: string, bench: string[], chair: string,
  *   reviews: Array<{model, role, conformance, leg, globalFindings}>,
  *   judgeResults: Array<{judge, ok, order, adjudications}>,
- *   chairStats: object|null}} args
+ *   chairStats: object|null, claudeReview?: object|null}} args
+ *   `claudeReview` (v4.1 §4.4) amends the v4.0 meta pin: present ⇒ claudeInCouncil
+ *   true, 'claude' joins meta.models (the street-cred universe), its findings join
+ *   the pool and it gets the synthesized null-usage runStats row. Absent ⇒ v4.0
+ *   output byte-for-byte.
  */
-function buildTallyInput({ runId, date, bench, chair, reviews, judgeResults, chairStats }) {
+function buildTallyInput({ runId, date, bench, chair, reviews, judgeResults, chairStats,
+  claudeReview }) {
   const meta = {
     runId, date, runType: 'headless',
     models: bench.slice(),          // bench seats exactly: critic included, chair excluded
@@ -65,6 +140,12 @@ function buildTallyInput({ runId, date, bench, chair, reviews, judgeResults, cha
   const runStats = reviews.map(r => buildRunStatsEntry({
     leg: r.leg, model: r.model, role: r.role, wasChair: false, conformance: r.conformance,
   }));
+  if (claudeReview) {
+    meta.models.push(CLAUDE_SEAT);      // last, mirroring its review-N+1 label
+    meta.claudeInCouncil = true;
+    findings.push(...claudeReview.globalFindings);
+    runStats.push(claudeRunStatsRow());
+  }
   if (chairStats) { runStats.push(chairStats); }
   return { meta, findings, adjudications, rankings, runStats };
 }
@@ -97,4 +178,5 @@ function writeVerdictFiles({ runDir, record, overallVerdict, chairText }) {
 
 module.exports = {
   buildRunStatsEntry, worseConformance, buildTallyInput, writeTallyFiles, writeVerdictFiles,
+  preflightClaudeReview, labelClaudeReview, claudeRunStatsRow, CLAUDE_SEAT,
 };

package/src/council/run-chair.js

@@ -0,0 +1,145 @@
+// src/council/run-chair.js
+'use strict';
+
+/**
+ * @module council/run-chair
+ * Chair synthesis + VERDICT-line repair for the headless council driver,
+ * lifted VERBATIM out of run.js for the 300-line gate (v4.1 Task 0.5). Pure
+ * refactor: same launches, same waveIds, same run.json checkpoints, same
+ * degradation rules. Launchers come in through `ctx` exactly as run-stages.js
+ * takes them; run.js keeps the chair-packet build, the tally sequencing, the
+ * signal bookkeeping and finalize().
+ *
+ * `isSignalled` is a GETTER, not a snapshot: run.js's signal handler mutates
+ * its `signalled` local between awaits and the v4.0 code re-read it after every
+ * chair launch. Passing the value instead would silently drop those aborts.
+ */
+
+const stage2 = require('./briefings-stage2');
+const { parseChairVerdict } = require('./parse-stage2');
+const runState = require('./run-state');
+const { isAbortExit } = require('./run-stages');
+
+/**
+ * Chair fallback promotion (spec §4): the highest peers-only street-cred
+ * model from `council stats` that is not a bench seat and not the failed
+ * chair. "Highest street-cred" = BEST = numerically LOWEST mean rank
+ * (deriveReliability's avgStreetCredPeersOnly; lower is better).
+ *
+ * The reserved seat name 'claude' is never eligible (v4.1 §4.4 "never chairs"):
+ * a --claude-review run puts a real 'claude' row in the ledger, so without this
+ * filter a LATER run could promote it and walk straight past the pre-flight
+ * --chair claude guard — with no Claude leg to launch.
+ * @returns {string|null}
+ */
+function pickFallbackChair(statsRows, bench, failedChair) {
+  const benchSet = new Set(bench);
+  const candidates = (statsRows || [])
+    .filter(r => r.model !== 'claude' && !benchSet.has(r.model) && r.model !== failedChair
+      && typeof r.avgStreetCredPeersOnly === 'number')
+    .sort((a, b) => a.avgStreetCredPeersOnly - b.avgStreetCredPeersOnly);
+  return candidates.length ? candidates[0].model : null;
+}
+
+/**
+ * Chair chain (attempt → retry → ledger-promoted fallback → give up) plus the
+ * single VERDICT-line repair re-prompt.
+ * @param {object} ctx run.js's {o, launchers, addWave, overBudget, scratchDir}
+ * @param {{packet: string, degraded: {value: boolean}, statsFn: Function,
+ *   isSignalled: function(): (number|null)}} args
+ * @returns {Promise<{aborted: number|null, chairLeg: object|null,
+ *   actualChair: string|null, chairText: string|null,
+ *   chairConformance: string, overallVerdict: string|null}>}
+ */
+async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
+  const { o, launchers, addWave, overBudget } = ctx;
+  const now = () => new Date().toISOString();
+  const bail = (code) => ({
+    aborted: code, chairLeg: null, actualChair: null, chairText: null,
+    chairConformance: 'clean', overallVerdict: null,
+  });
+
+  const attemptChair = async (model, waveId) => {
+    runState.appendStageWave(o.runDir, 'chair', waveId);
+    const solo = await launchers.launchSolo({
+      model, prompt: packet, project: o.runDir, waveId,
+      timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
+      // v4.1 §4.5d: the chair chain (ch1/ch2/ch3) and the ch4 VERDICT repair
+      // below are the launches a re-armed price gate would refuse LAST, after
+      // the whole bench has already been paid for.
+      noCostGate: o.noCostGate,
+    });
+    addWave(solo.wave);
+    const ok = solo.leg && solo.leg.status === 'complete'
+      && solo.leg.summary && solo.leg.summary.trim();
+    return { leg: ok ? solo.leg : null, exitCode: solo.exitCode };
+  };
+
+  let chairLeg = null;
+  let actualChair = null;
+  if (overBudget()) {
+    // Ceiling hit after the tally is computable: skip the chair, write the
+    // verdict with overallVerdict null, exit 2 (spec §4 degradation table).
+    // Never abort in-flight legs for cost — this only stops NEW launches.
+    degraded.value = true;
+    runState.updateStage(o.runDir, 'chair', { status: 'skipped', completedAt: now() });
+  } else {
+    runState.updateStage(o.runDir, 'chair', { status: 'running', startedAt: now(), project: o.runDir });
+    // Fallback chain (spec §4): retry same chair once → promote best
+    // non-bench model from the ledger → give up (no Claude fallback headless).
+    let attempt = await attemptChair(o.chair, `${o.runId}-ch1`);
+    if (isAbortExit(attempt.exitCode) || isSignalled()) { return bail(attempt.exitCode || isSignalled()); }
+    if (!attempt.leg && !overBudget()) {
+      attempt = await attemptChair(o.chair, `${o.runId}-ch2`);
+      if (isAbortExit(attempt.exitCode) || isSignalled()) { return bail(attempt.exitCode || isSignalled()); }
+    }
+    if (attempt.leg) { actualChair = o.chair; }
+    else if (!overBudget()) {
+      let statsRows = [];
+      try { statsRows = statsFn(); } catch { /* no ledger yet */ }
+      const fallback = pickFallbackChair(statsRows, o.models, o.chair);
+      if (fallback) {
+        attempt = await attemptChair(fallback, `${o.runId}-ch3`);
+        if (isAbortExit(attempt.exitCode) || isSignalled()) { return bail(attempt.exitCode || isSignalled()); }
+        if (attempt.leg) { actualChair = fallback; }
+      }
+    }
+    chairLeg = attempt.leg;
+    runState.updateStage(o.runDir, 'chair',
+      { status: chairLeg ? 'complete' : 'error', completedAt: now() });
+    // The chair chain may have promoted a fallback (or given up) — checkpoint
+    // the ACTUAL chair into run.json now so status/`--json`/the human summary
+    // never report the originally-requested chair after a promotion. Mirrors
+    // mkInput's actualChair || o.chair (a give-up with no actual chair keeps
+    // the requested chair).
+    runState.checkpoint(o.runDir, { chair: actualChair || o.chair });
+  }
+  const chairText = chairLeg ? chairLeg.summary : null;
+  let chairConformance = 'clean';
+
+  // ---- Chair VERDICT line (one repair re-prompt, spec §5) ----
+  let overallVerdict = chairText ? parseChairVerdict(chairText) : null;
+  if (chairText && !overallVerdict && !overBudget()) {
+    runState.appendStageWave(o.runDir, 'chair', `${o.runId}-ch4`);
+    const repair = await launchers.launchSolo({
+      model: actualChair, prompt: stage2.buildChairRepairPrompt(),
+      project: o.runDir, waveId: `${o.runId}-ch4`,
+      timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
+      noCostGate: o.noCostGate,
+    });
+    addWave(repair.wave);
+    if (isAbortExit(repair.exitCode) || isSignalled()) { return bail(repair.exitCode || isSignalled()); }
+    overallVerdict = parseChairVerdict((repair.leg && repair.leg.summary) || '');
+    chairConformance = overallVerdict ? 'repaired' : 'unstructured';
+  }
+  // A completed chair whose verdict never parsed is 'unstructured' even when
+  // the repair was skipped (e.g. the chair leg itself tripped --max-cost).
+  if (chairText && !overallVerdict) { chairConformance = 'unstructured'; }
+  if (!chairLeg || !overallVerdict) { degraded.value = true; } // spec table: exit 2 rows
+
+  return {
+    aborted: null, chairLeg, actualChair, chairText, chairConformance, overallVerdict,
+  };
+}
+
+module.exports = { runChair, pickFallbackChair };