amicus 4.8.1 → 4.9.0

package/src/council/verdict-seat-loss.js

@@ -0,0 +1,124 @@
+// src/council/verdict-seat-loss.js
+'use strict';
+
+/**
+ * @module council/verdict-seat-loss
+ * The verdict's seat-loss surface: `summarizeSeatLoss` (v4.5.2) and
+ * `deriveSeatLoss` (v4.6 Plan 2, spec D3) — lifted VERBATIM out of verdict.js
+ * for the 300-line gate (v4.9 PR #200 fix round 3), on the W4 chair-fallback
+ * precedent. The extraction itself was a pure MOVE: same bodies, same
+ * docblocks, same exports, and verdict.js re-exports both so no caller changes.
+ * (v4.9 W9 has since edited `deriveSeatLoss`'s body here — the identity pins
+ * below cover the MOVE, not a freeze.) Their behaviour stays pinned where it
+ * already was (tests/council/verdict-seat-loss.test.js,
+ * tests/council/verdict-degrades.test.js), both of which still import through
+ * verdict.js — if the move changed anything, those go red.
+ *
+ * Pure: no IO, no verdict-document knowledge. Nothing in this file requires
+ * verdict.js, so the dependency runs one way only.
+ */
+
+/**
+ * Describe which requested seats actually reviewed, for the verdict's own face.
+ *
+ * ⚠️ ADDED v4.5.2 from a field report. The critic is a SOLO wave with one leg,
+ * so losing it loses 100% of the adversarial role — and unlike a dead bench wave
+ * (which trips the quorum gate and fails the run loudly) a dead critic is
+ * survivable, so the run continues to a full verdict, tally and chair synthesis
+ * that never saw the critic's findings. Run `dfb6a692` did exactly that and the
+ * only record was `deadWaves` in run.json, a file nobody opens when the verdict
+ * reads clean. A user who typed `--critic` asked for adversarial review; a
+ * verdict produced without it must say so where the verdict is read.
+ *
+ * Returns null when no critic was requested — there is nothing to report, and an
+ * always-present block would train readers to ignore it.
+ *
+ * @param {{runId: string, critic: ?string,
+ *   deadWaves: Array<{waveId: string, models: string[], reason: string}>}} o
+ * @returns {?{criticRequested: string, criticSeated: boolean, reason: ?string,
+ *   deadBenchSeats: string[]}}
+ */
+function summarizeSeatLoss({ runId, critic, deadWaves = [] } = {}) {
+  if (!critic) { return null; }
+  // Match on EITHER carrier. The `-c1` suffix is the convention run-stages.js
+  // uses, but a wave that names the critic model is the critic wave whatever it
+  // is called — and relying on the id alone would silently under-report if that
+  // convention ever changes.
+  const isCriticWave = w =>
+    w.waveId === `${runId}-c1` || (w.models || []).includes(critic);
+  const dead = deadWaves.find(isCriticWave) || null;
+  return {
+    criticRequested: critic,
+    criticSeated: !dead,
+    reason: dead ? dead.reason : null,
+    deadBenchSeats: deadWaves.filter(w => !isCriticWave(w))
+      .flatMap(w => w.models || []),
+  };
+}
+
+/**
+ * seatLoss, derived from the sink's records (v4.6 Plan 2, spec D3 — closes #84).
+ *
+ * WHY A DERIVATION: two fields reporting lost seats can disagree; deriving one
+ * from the other makes contradiction inexpressible. `summarizeSeatLoss` stays
+ * exactly as v4.5.2 shipped it (its tests pass unedited — that is the proof the
+ * shape survived); this function rebuilds its wave input from `dead-wave`
+ * records and then adds the losses waves can never show: `dead-leg` records —
+ * a solo critic wave that STARTED but whose one leg died is invisible to
+ * deadWaves (#84's second half) — plus v4.9 W9's gated `seat-unbound` family.
+ *
+ * Reads ONLY record.data (Task 1's machine surface) — never the prose fields.
+ * @param {{runId: string, critic: ?string, degrades: Array<object>}} o
+ * @returns {?object} the summarizeSeatLoss shape, or null when no critic was requested
+ */
+function deriveSeatLoss({ runId, critic, degrades = [] } = {}) {
+  if (!critic) { return null; }
+  // v4.9 W9 (SI-02). ⚠️ THIRD spelling of one admission rule; its renderer twins are
+  // `live-dead-seats.js :: isSeatLoss` and `workspace-seats.js :: retriedSeats`, which cannot
+  // require src/ — all three move together, enforced only by workspace-seats.test.js's drift
+  // pin. `seat-unbound` is GATED: orphan-leg, re-vote and Stage-2 judge notes share it, are NOT
+  // seat losses, and carry no retry-family field. (R-W9a is CLOSED at the producer in the W9 fix
+  // round: `run-retry-notes.js :: skippedWaveNote` emits the `firstFailure` fact its record
+  // already carried, so this unchanged gate admits that real loss and still excludes the three.)
+  // ⚠️ The kind test admits a kind-LESS record as a degrade — W9 fix round, council C4. The
+  // POSITIVE-only spelling rested on an ASSERTED caller inventory (everything here comes from
+  // `makeDegrade`, which stamps the default), which is convention, not structure: one new
+  // caller, or one hand-written record, and a real seat loss vanishes silently. `report.js`
+  // learned it as mutant LEGACYDROP; the two renderers now spell it exactly as this line does.
+  // What all four agree on is that an ABSENT kind is a loss — their kind LISTS still differ,
+  // deliberately. `heal`/`info` name themselves here and are still excluded.
+  const gatedUnbound = d => d.channel === 'seat-unbound'
+    && (d.data.retryWaveId || d.data.firstFailure) && (d.data.seatId || d.data.seat);
+  const real = degrades.filter(d => (d.kind === undefined || d.kind === 'degrade') && d.data
+    && (d.channel === 'dead-leg' || d.channel === 'dead-wave' || gatedUnbound(d)));
+  const waves = real.filter(d => d.channel === 'dead-wave')
+    .map(d => ({ waveId: d.data.waveId, models: d.data.models || [], reason: d.data.reason }));
+  const base = summarizeSeatLoss({ runId, critic, deadWaves: waves });
+  const legs = real.filter(d => d.channel !== 'dead-wave');
+  // ⚠️ STAYS ALIAS-KEYED — decided and measured in v4.9 W9 (R4), not mirrored from the
+  // renderers' seat-key fix. `seats.js :: preflightSeats` REFUSES a critic alias occupying
+  // more than one bench seat, zero-spend, before any leg launches, so on every run this can see
+  // `data.seat === critic` names exactly one seat and alias equality IS seat equality; its only
+  // production caller, `run-verdict-files.js :: writeVerdictFiles`, is fed in-process records
+  // from that run's own sink. The renderers differ: they read run.json/verdict.json off DISK,
+  // any version or hand edit, where that refusal is not in force.
+  const criticLeg = legs.find(l => l.data.seat === critic) || null;
+  return {
+    ...base,
+    criticSeated: base.criticSeated && !criticLeg,
+    // SL-2 handoff: a reconciliation note (run-retry-notes.js's
+    // missingLegStillDeadNote) carries data.status: null when the retry
+    // produced no leg for the seat at all — there is no status to name, so
+    // the old `ended '${status}'` template rendered the literal string
+    // "ended 'null'". A status-carrying record keeps the original text.
+    reason: base.reason || (criticLeg
+      ? (criticLeg.data.reason || (criticLeg.data.status
+        ? `the critic leg ended '${criticLeg.data.status}' with no usable output`
+        : 'the critic leg produced no usable output'))
+      : null),
+    deadBenchSeats: [...base.deadBenchSeats,
+      ...legs.filter(l => l.data.seat !== critic).map(l => l.data.seat)],
+  };
+}
+
+module.exports = { summarizeSeatLoss, deriveSeatLoss };

package/src/council/verdict.js

@@ -2,100 +2,28 @@
 'use strict';
 const fs = require('fs');
 const path = require('path');
-const { parseChairVerdict } = require('./parse-stage2');
+const { parseChairTerminal, CHAIR_VERDICTS, CHAIR_ANSWERS } = require('./parse-stage2');
+// v4.9 PR #200 fix round 3: the seat-loss pair lives in its own leaf module (the
+// 300-line gate), re-exported below so every existing caller and pin is unchanged.
+const { summarizeSeatLoss, deriveSeatLoss } = require('./verdict-seat-loss');
 
 // v4.0 §7: council family v2 — verdict docs carry {schemaVersion, type} and a
-// nullable overallVerdict (the chair's Ship-it line; populated by the headless
-// engine in Plan B via opts.overallVerdict, null in every Stage-4 manual path).
+// nullable overallVerdict (the chair's terminal line — `VERDICT:` on a review
+// run, `ANSWER:` on a task one; populated by the headless engine in Plan B via
+// opts.overallVerdict, null in every Stage-4 manual path).
 const VERDICT_SCHEMA_VERSION = 2;
 
-/**
- * Describe which requested seats actually reviewed, for the verdict's own face.
- *
- * ⚠️ ADDED v4.5.2 from a field report. The critic is a SOLO wave with one leg,
- * so losing it loses 100% of the adversarial role — and unlike a dead bench wave
- * (which trips the quorum gate and fails the run loudly) a dead critic is
- * survivable, so the run continues to a full verdict, tally and chair synthesis
- * that never saw the critic's findings. Run `dfb6a692` did exactly that and the
- * only record was `deadWaves` in run.json, a file nobody opens when the verdict
- * reads clean. A user who typed `--critic` asked for adversarial review; a
- * verdict produced without it must say so where the verdict is read.
- *
- * Returns null when no critic was requested — there is nothing to report, and an
- * always-present block would train readers to ignore it.
- *
- * @param {{runId: string, critic: ?string,
- *   deadWaves: Array<{waveId: string, models: string[], reason: string}>}} o
- * @returns {?{criticRequested: string, criticSeated: boolean, reason: ?string,
- *   deadBenchSeats: string[]}}
- */
-function summarizeSeatLoss({ runId, critic, deadWaves = [] } = {}) {
-  if (!critic) { return null; }
-  // Match on EITHER carrier. The `-c1` suffix is the convention run-stages.js
-  // uses, but a wave that names the critic model is the critic wave whatever it
-  // is called — and relying on the id alone would silently under-report if that
-  // convention ever changes.
-  const isCriticWave = w =>
-    w.waveId === `${runId}-c1` || (w.models || []).includes(critic);
-  const dead = deadWaves.find(isCriticWave) || null;
-  return {
-    criticRequested: critic,
-    criticSeated: !dead,
-    reason: dead ? dead.reason : null,
-    deadBenchSeats: deadWaves.filter(w => !isCriticWave(w))
-      .flatMap(w => w.models || []),
-  };
-}
-
-/**
- * seatLoss, derived from the sink's records (v4.6 Plan 2, spec D3 — closes #84).
- *
- * WHY A DERIVATION: two fields reporting lost seats can disagree; deriving one
- * from the other makes contradiction inexpressible. `summarizeSeatLoss` stays
- * exactly as v4.5.2 shipped it (its tests pass unedited — that is the proof the
- * shape survived); this function rebuilds its wave input from `dead-wave`
- * records and then adds the losses waves can never show: `dead-leg` records —
- * a solo critic wave that STARTED but whose one leg died is invisible to
- * deadWaves, which is #84's second half.
- *
- * Reads ONLY record.data (Task 1's machine surface) — never the prose fields.
- * @param {{runId: string, critic: ?string, degrades: Array<object>}} o
- * @returns {?object} the summarizeSeatLoss shape, or null when no critic was requested
- */
-function deriveSeatLoss({ runId, critic, degrades = [] } = {}) {
-  if (!critic) { return null; }
-  const real = degrades.filter(d => d.kind !== 'heal' && d.data);
-  const waves = real.filter(d => d.channel === 'dead-wave')
-    .map(d => ({ waveId: d.data.waveId, models: d.data.models || [], reason: d.data.reason }));
-  const base = summarizeSeatLoss({ runId, critic, deadWaves: waves });
-  const legs = real.filter(d => d.channel === 'dead-leg');
-  const criticLeg = legs.find(l => l.data.seat === critic) || null;
-  return {
-    ...base,
-    criticSeated: base.criticSeated && !criticLeg,
-    // SL-2 handoff: a reconciliation note (run-retry-notes.js's
-    // missingLegStillDeadNote) carries data.status: null when the retry
-    // produced no leg for the seat at all — there is no status to name, so
-    // the old `ended '${status}'` template rendered the literal string
-    // "ended 'null'". A status-carrying record keeps the original text.
-    reason: base.reason || (criticLeg
-      ? (criticLeg.data.reason || (criticLeg.data.status
-        ? `the critic leg ended '${criticLeg.data.status}' with no usable output`
-        : 'the critic leg produced no usable output'))
-      : null),
-    deadBenchSeats: [...base.deadBenchSeats,
-      ...legs.filter(l => l.data.seat !== critic).map(l => l.data.seat)],
-  };
-}
-
 /**
  * Merge a tally record with Claude's Stage-4 decisions into the verdict record.
  * @param {object} record  tally() output
  * @param {Array<{id,decision,applied,duplicateOf,tierOverride}>} decisions
- * @param {{overallVerdict?: (string|null), seatLoss?: object, degrades?: Array<object>}} [opts]
- *   `overallVerdict` is the engine hook (Plan B): the parsed chair `VERDICT:`
- *   line; omitted/undefined → null. `seatLoss` (v4.5.2) and `degrades` (v4.6
- *   Plan 2) are additive and OPTIONAL — each lands on the verdict only when
+ * @param {{overallVerdict?: (string|null), intent?: (string|null),
+ *   seatLoss?: object, degrades?: Array<object>}} [opts]
+ *   `overallVerdict` is the engine hook (Plan B): the parsed chair terminal line
+ *   (`VERDICT:` on a review run, `ANSWER:` on a task run — v4.9 W5/W7);
+ *   omitted/undefined → null. `intent` is the Stage-5 rebuild's carrier (v4.9 fix
+ *   round 2 — see the emit-when-'task' line below). `seatLoss` (v4.5.2) and
+ *   `degrades` (v4.6 Plan 2) are additive and OPTIONAL — each lands only when
  *   truthy/non-empty, absent otherwise (never fabricated).
  */
 function buildVerdict(record, decisions = [], opts = {}) {
@@ -116,6 +44,22 @@ function buildVerdict(record, decisions = [], opts = {}) {
     // matching the `seatLoss` sibling below; PR5 codes against that name.
     ...(record.meta.seats ? { seats: record.meta.seats } : {}),
     claudeInCouncil: record.meta.claudeInCouncil,
+    // v4.9 W5.3: task-mode marker — emit-when-'task' (the W4/W5 plan's §7.5
+    // byte-identity ruling): a review record never materializes the key, so a
+    // review verdict.json is unchanged byte for byte, and an explicit
+    // meta.intent 'review' (hand-assembled input) is NOT forwarded either.
+    // ⚠️ v4.9 fix round 2 (council C1): `opts.intent` is a SECOND carrier, not a
+    // redundant one. MEASURED: the run dir's tally.json copies `meta` verbatim
+    // (tally.js), so the canonical Stage-5 rebuild already came through the first
+    // guard — but a hand-assembled or MCP-supplied record has none (mcp-tools.js
+    // :: amicus_verdict types `record` as `z.record(z.any())`), and on THAT leg
+    // the rebuild dropped the key, regressing the fold line and Workspace chip to
+    // review scale. Passed through `opts` rather than assigned after the call, so
+    // the key keeps its SLOT here and a rebuilt document's key order still
+    // matches the engine's (pinned, cli-council-verdict-chair-carry.test.js).
+    // PR #200 round-5 B3: parens on the whole disjunction — behaviour-identical.
+    ...(((record.meta && record.meta.intent === 'task') || opts.intent === 'task')
+      ? { intent: 'task' } : {}),
     overallVerdict: opts.overallVerdict === undefined ? null : opts.overallVerdict,
     findings: record.findings.map(f => {
       const d = byId.get(f.id) || {};
@@ -148,9 +92,9 @@ function buildVerdict(record, decisions = [], opts = {}) {
     // row's flat {model, seat} shape — model is the alias, seat is the seat
     // id, so on a unique-alias bench they are byte-equal and nothing is
     // emitted (same semantics as `seat.id !== seat.alias` one layer up,
-    // run-stats-entry.js:64). NOT a plain pass-through like `raiserSeat`
-    // above (:141) — that field's upstream producer already holds a real
-    // {id, alias} seat OBJECT at its own decision point (run.js:202:
+    // run-stats-entry.js :: buildRunStatsEntry). NOT a plain pass-through like `raiserSeat`
+    // in the findings literal above — that field's upstream producer already holds a real
+    // {id, alias} seat OBJECT at its own decision point (run.js:212:
     // `r.seat && r.seat.id !== r.seat.alias`), so passing its verdict
     // through here is safe. The street-cred producer never has such an object
     // at this point, only a flat row, so a pass-through here would leak `seat`
@@ -200,26 +144,62 @@ function buildVerdict(record, decisions = [], opts = {}) {
  * verdict belongs to the run, not to wherever the caller writes the result):
  *   1. `<runDir>/verdict.json` `overallVerdict` — the value the engine already
  *      parsed. Guarded by `runId`: a stale or foreign verdict.json sitting in
- *      the folder must never inject another run's chair line.
- *   2. `<runDir>/chair-output.md`, re-parsed with the engine's own
- *      `parseChairVerdict`, so there is no second parser to drift. This also
- *      recovers runs whose verdict.json was already nulled by the defect.
+ *      the folder must never inject another run's chair line. Guarded by SCALE
+ *      too (v4.9 fix round 3, council A1/B1 — see below).
+ *   2. `<runDir>/chair-output.md`, re-parsed with the engine's OWN parser, so
+ *      there is no second parser to drift. This also recovers runs whose
+ *      verdict.json was already nulled by the defect.
+ *
+ * ⚠️ ONE scale, chosen by the run's INTENT (v4.9 fix round 2, council B1/C2 —
+ * CORRECTING W7's MEDIUM F2, recorded because it was wrong instructively). W7 was
+ * right that a VERDICT-only fallback recovered null for every task run; its fix
+ * tried BOTH parsers unconditionally, justified thus — the two scales are
+ * DISJOINT by pinned construction (tests/council/chair-scale-drift.test.js), so
+ * neither can read the other's phrase and the order of the two calls cannot
+ * change an outcome. The premise is true; the conclusion does not follow.
+ * Disjointness is a property of the PHRASE SETS, not of the DOCUMENT: chair prose
+ * that quotes, contrasts or merely mentions the other scale carries BOTH keyword
+ * lines, and then order decides everything — measured red in both directions, now
+ * pinned in both (cli-council-verdict-chair-carry.test.js, SCALEFREEFALLBACK).
+ *
+ * So `intent` dispatches through `parseChairTerminal` — one parser, never both.
+ * W7 rejected that call believing a Stage-5 rebuild has no intent to pass; it has
+ * THREE, and the caller reads all of them (cli-handlers-council.js :: runVerdict):
+ * the record's `meta.intent`, `run.json`'s `intent` from the run folder this
+ * function already anchors on, and — since fix round 3, council C3 — the prior
+ * verdict.json's own `intent` (readPriorVerdictIntent below), which is the last
+ * carrier standing when the other two are absent. Absent — and anything but 'task' — is review,
+ * restoring pre-W7 review behaviour exactly. Never invents: an absent, skipped or
+ * unstructured chair yields null.
  *
- * Never invents: an absent, skipped, or unstructured chair yields null.
+ * ⚠️ AND THE CARRY OBEYS THE SAME SCALE (v4.9 fix round 3, council A1+B1 — one
+ * mechanism, one fix). Round 2 dispatched branch 2 and left branch 1 with no
+ * scale check at all, so the whole guard was inert whenever a prior verdict.json
+ * existed: `overallVerdict: 'Ship it'` was carried onto a task rebuild verbatim
+ * and every downstream surface then labelled a CHAIR_VERDICTS phrase `ANSWER:`
+ * — the defect round 2 measured on the prose leg, one branch earlier. So the
+ * carried phrase must be a member of the scale `intent` selects; off-scale is
+ * treated as NO CARRY and falls through to branch 2, which is intent-dispatched
+ * and therefore already right. This also subsumes the old string/non-empty
+ * check: every member of both scales is a non-empty string, and `includes`
+ * refuses a number, null or object without a separate typeof.
  * @param {string} runDir
  * @param {string} [runId] record.meta.runId — the run being rebuilt
- * @returns {string|null} a canonical chair verdict phrase, or null
+ * @param {?string} [intent] 'task' selects the ANSWER scale; anything else review
+ * @returns {string|null} a canonical chair verdict OR answer phrase, or null
  */
-function readOverallVerdict(runDir, runId) {
+function readOverallVerdict(runDir, runId, intent) {
+  const scale = intent === 'task' ? CHAIR_ANSWERS : CHAIR_VERDICTS;
   try {
     const prior = JSON.parse(fs.readFileSync(path.join(runDir, 'verdict.json'), 'utf-8'));
-    if (typeof prior.overallVerdict === 'string' && prior.overallVerdict
+    if (scale.includes(prior.overallVerdict)
       && (!runId || prior.runId === runId)) {
       return prior.overallVerdict;
     }
   } catch { /* no prior verdict.json, or unreadable — try the chair prose */ }
   try {
-    return parseChairVerdict(fs.readFileSync(path.join(runDir, 'chair-output.md'), 'utf-8'));
+    const text = fs.readFileSync(path.join(runDir, 'chair-output.md'), 'utf-8');
+    return parseChairTerminal(text, intent);
   } catch { /* no chair-output.md — the chair genuinely produced nothing */ }
   return null;
 }
@@ -247,6 +227,35 @@ function readPriorVerdictSurfaces(runDir, runId) {
   return { seatLoss: null, degrades: null };
 }
 
+/**
+ * The run's intent as the prior verdict.json records it (v4.9 fix round 3,
+ * council C3) — the THIRD carrier for a Stage-5 rebuild, after the record's
+ * `meta.intent` and run.json's checkpoint.
+ *
+ * A SEPARATE function rather than a fourth key on readPriorVerdictSurfaces
+ * directly above: intent has to be resolved BEFORE readOverallVerdict runs
+ * (it selects that call's scale), while the loss surfaces are recovered after
+ * the parse; and #87's pins assert that function's return shape exactly
+ * (verdict-degrades.test.js), so widening it would edit a pin to fit a change
+ * rather than the other way round.
+ *
+ * Same contract as both siblings: the run folder's own verdict.json, the same
+ * `!runId || prior.runId === runId` guard — waived only when the RECORD names
+ * no run, never when the DOCUMENT does not — and absence yields null.
+ * Emit-when-'task' at the source (buildVerdict), so ONLY 'task' is reported;
+ * anything else, including a hand-written `intent: 'review'`, is no vote.
+ * @param {string} runDir
+ * @param {string} [runId]
+ * @returns {'task'|null}
+ */
+function readPriorVerdictIntent(runDir, runId) {
+  try {
+    const prior = JSON.parse(fs.readFileSync(path.join(runDir, 'verdict.json'), 'utf-8'));
+    if ((!runId || prior.runId === runId) && prior.intent === 'task') { return 'task'; }
+  } catch { /* no prior verdict.json, or unreadable — no vote */ }
+  return null;
+}
+
 /** Atomic write: tmp + rename (matches the repo's wave.json convention). */
 function writeVerdictAtomic(filePath, verdict) {
   const tmp = `${filePath}.tmp-${process.pid}`;
@@ -256,5 +265,5 @@ function writeVerdictAtomic(filePath, verdict) {
 
 module.exports = {
   buildVerdict, summarizeSeatLoss, deriveSeatLoss, readOverallVerdict, readPriorVerdictSurfaces,
-  writeVerdictAtomic, VERDICT_SCHEMA_VERSION,
+  readPriorVerdictIntent, writeVerdictAtomic, VERDICT_SCHEMA_VERSION,
 };