@bongos/core 1.19.332 → 1.19.334

package/modules/grading/grader-score.js

@@ -0,0 +1,706 @@
+// modules/grading/grader-score.js — turning a worker's raw JSON into a score:
+// shape validation, substantive-issue detection, the SERVER-side guards that a
+// model cannot talk its way past, and multi-shot aggregation.
+//
+// Carved out of modules/grading/grader.js by task 1003206 (goal 1000079, the R03
+// de-monolith plan) to bring the grader under the 1,500-line ratchet. A STRUCTURAL
+// move: bodies unchanged, grader.js requires every name back, so the grade port
+// surface and the panel's behaviour are exactly as before.
+
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { DEFAULT_GRADER_MODEL, FALLTHROUGH_CONFIDENCE, LOW_CONFIDENCE, THRESHOLD, VERSION, permissionPathCheck, routeRankCheck } = require('./grader-config.js');
+const { TRIVIAL_MAX_FILES, TRIVIAL_MAX_LINES, clamp, median, r1 } = require('./grader-model.js');
+const { extractJson } = require('./grader-prompt.js');
+
+function isNum(n) {
+  return Number.isFinite(n);
+}
+
+// #1002653 corroboration helpers for validateAndScore's null-ff lens branch.
+// A worker entry is untrusted input — w.issues may be any shape. Absent issues
+// on an errored worker is the normal outage shape (treated as none); a truthy
+// NON-ARRAY issues is malformed and must DISQUALIFY corroboration (fail-closed
+// schema_error downstream), never TypeError into a 500 on grade submission.
+const isNarcErroredClean = (w) => {
+  if (!w || w.kind !== 'narc' || !w.error) return false;
+  const issues = w.issues == null ? [] : w.issues;
+  if (!Array.isArray(issues)) return false;
+  return !issues.some((i) => i && (i.severity === 'blocker' || i.severity === 'major'));
+};
+const isNarcHealthy = (w) => !!w && w.kind === 'narc' && !w.error;
+
+// task 1002658 (ADR 0164): a SUBSTANTIVE issue is one a real panel emits — a
+// known severity + a non-empty summary. The old plausibility guard counted raw
+// issues[].length, so one fabricated `{}` defeated it; substance-counting
+// closes that lazy-forgery class using only the submitted body itself.
+const ISSUE_SEVERITIES = new Set(['blocker', 'major', 'minor', 'nit']);
+function isSubstantiveIssue(it) {
+  return !!it && typeof it === 'object'
+    && ISSUE_SEVERITIES.has(String(it.severity || '').toLowerCase())
+    && typeof it.summary === 'string' && it.summary.trim().length > 0;
+}
+
+// task 1002658 (ADR 0164): does the submitted signals block carry the full
+// per-worker shape a real panel run produces — ≥3 workers, each with a kind
+// and a legal verdict (or an error tag)? Client-forgeable like every
+// grade-time input (the ADR's documented honor-system residual for Metic+);
+// its job is separating "the panel ran and unanimously found nothing" (the
+// guard's confirmed false-positive class) from "no evidence at all".
+const WORKER_VERDICTS = new Set(['pass', 'concerns', 'fail']);
+function hasPanelEvidence(signals) {
+  const ws = Array.isArray(signals?.workers) ? signals.workers : null;
+  if (!ws || ws.length < 3) return false;
+  return ws.every((w) => !!w && typeof w === 'object'
+    && typeof w.kind === 'string' && w.kind.trim().length > 0
+    && (WORKER_VERDICTS.has(String(w.verdict || '').toLowerCase()) || !!w.error));
+}
+
+// Validates ONE shot's subagent JSON and produces a per-shot grade-result.
+// Never throws — malformed inputs produce a passed=false result with notes_md.
+// The downstream aggregateShots collapses N of these into a final verdict.
+function validateAndScore(rawSubagent, meta = {}) {
+  const parsed =
+    typeof rawSubagent === 'string' ? extractJson(rawSubagent) : rawSubagent;
+
+  const signals = {
+    grader_kind: 'subagent',
+    grader_version: VERSION,
+    model: meta.model || DEFAULT_GRADER_MODEL,
+    threshold: THRESHOLD,
+    ...meta,
+  };
+
+  if (!parsed || typeof parsed !== 'object') {
+    return {
+      score: 0,
+      passed: false,
+      threshold: THRESHOLD,
+      grader_kind: 'subagent',
+      grader_version: VERSION,
+      rubric_scores: {},
+      signals: { ...signals, parse_error: true },
+      notes_md: `Subagent grader ${VERSION}: could not parse subagent output as JSON.`,
+      issues: [],
+    };
+  }
+
+  // #1002653: Number(null) === 0, so an errored ADVISORY Narc forwarding an
+  // EXPLICIT ff:null fabricated "FAIL — functional_fidelity below 6" at
+  // (0+cq)/2. Explicit null = the lens did not run (the #395 confidence
+  // precedent): gate/score on the axes that ran. A bare null is NOT enough —
+  // a prompt-injected Narc emitting null must stay fail-closed — so the branch
+  // needs POSITIVE corroboration: workers[] carries an errored
+  // no-substantive-finding Narc (#473 missing-signal semantics) and no healthy
+  // Narc. Empty/narc-less/absent workers, ABSENT ff, and every other shape
+  // fall through to the fail-closed schema_error below. Quality has no such
+  // branch — gating lens, absence stays fail-closed.
+  // Trust note: workers[] is client-supplied like every SR-9 grade input — a
+  // forger gains nothing here they cannot get by sending ff:9 directly; the
+  // server-derivable-signals redesign is tracked separately (SR-9 residual).
+  const metaWorkers = Array.isArray(meta.workers) ? meta.workers : null;
+  const narcMissingSignal = !!metaWorkers &&
+    metaWorkers.some(isNarcErroredClean) && !metaWorkers.some(isNarcHealthy);
+  const ffExplicitNull = parsed.functional_fidelity === null;
+  const ffLensUnavailable = ffExplicitNull && narcMissingSignal;
+  const ff = ffExplicitNull ? null : Number(parsed.functional_fidelity);
+  const cq = Number(parsed.code_quality);
+  const economyRaw = Number(parsed.economy);
+  const economy =
+    isNum(economyRaw) && economyRaw >= 0 && economyRaw <= 10 ? economyRaw : null;
+  // MAS Phase 2.5 (#423): security_score (from Hacker, Phase 2.1) and
+  // efficiency_score (from Efficiency Monger, Phase 2.2). Both ADVISORY —
+  // recorded in rubric_scores but do not independently gate the ship. Same
+  // back-compat shape as economy: out-of-range / non-numeric / missing →
+  // recorded as null, no penalty. Older callers that don't forward these
+  // fields grade exactly as before.
+  const securityRaw = Number(parsed.security_score);
+  const securityScore =
+    isNum(securityRaw) && securityRaw >= 0 && securityRaw <= 10 ? securityRaw : null;
+  const efficiencyRaw = Number(parsed.efficiency_score);
+  const efficiencyScore =
+    isNum(efficiencyRaw) && efficiencyRaw >= 0 && efficiencyRaw <= 10 ? efficiencyRaw : null;
+  // Treat null/undefined confidence as ABSENT, not as 0. Number(null) === 0,
+  // and isNum(0) === true — a naive `isNum(Number(parsed.confidence))` check
+  // would accept null as a valid low-confidence signal and FAIL the ship for
+  // a missing field. The MAS Phase 1 self-ship (#395) hit this exactly when
+  // aggregateShots forwarded a null top-level confidence to the server's
+  // validateAndScore. Explicit null-check first; coerce only when present.
+  const confidence = parsed.confidence == null
+    ? null
+    : isNum(Number(parsed.confidence)) ? Number(parsed.confidence) : null;
+  const issues = Array.isArray(parsed.issues)
+    ? parsed.issues.filter((it) => it && typeof it === 'object').slice(0, 50)
+    : [];
+  const notesFromSubagent = typeof parsed.notes_md === 'string' ? parsed.notes_md : '';
+
+  signals.confidence = confidence;
+  signals.issue_count = issues.length;
+  if (ffLensUnavailable) signals.ff_lens_unavailable = true;
+
+  if ((!ffLensUnavailable && (!isNum(ff) || ff < 0 || ff > 10)) || !isNum(cq) || cq < 0 || cq > 10) {
+    return {
+      score: 0,
+      passed: false,
+      threshold: THRESHOLD,
+      grader_kind: 'subagent',
+      grader_version: VERSION,
+      rubric_scores: {},
+      signals: { ...signals, schema_error: true },
+      notes_md: `Subagent grader ${VERSION}: subagent returned scores outside [0,10] or non-numeric. Got functional_fidelity=${parsed.functional_fidelity}, code_quality=${parsed.code_quality}.`
+        + (ffExplicitNull && !narcMissingSignal
+          ? ' Explicit null functional_fidelity without a corroborated Narc outage in signals.workers is fail-closed.'
+          : ''),
+      issues,
+    };
+  }
+
+  const ffR = ffLensUnavailable ? null : r1(clamp(ff, 0, 10));
+  const cqR = r1(clamp(cq, 0, 10));
+  const economyR = economy != null ? r1(clamp(economy, 0, 10)) : null;
+  const securityR = securityScore != null ? r1(clamp(securityScore, 0, 10)) : null;
+  const efficiencyR = efficiencyScore != null ? r1(clamp(efficiencyScore, 0, 10)) : null;
+  const economyPenalty =
+    economyR != null ? Math.max(0, (THRESHOLD - economyR) / 2) : 0;
+  const cqEffective = economyR != null ? r1(clamp(cqR - economyPenalty, 0, 10)) : cqR;
+  // With the ff lens out, the score reflects only the axis that ran — never a
+  // blend with a synthetic 0 (the fabricated 4.5/10) or a synthetic threshold.
+  const blended = ffLensUnavailable ? cqR : r1((ffR + cqR) / 2);
+
+  // confidence must be present (not null) for a PASS. A subagent that omits
+  // confidence entirely silently bypassed the low-confidence gate under the
+  // old `confidence != null && confidence < LOW_CONFIDENCE` check — null made
+  // lowConfidence=false and let high ff/cq scores through unchecked (#489 / #56).
+  // Distinguishing "absent" from "low" gives a clear verdict message and leaves
+  // the aggregateShots #395 fix intact: shots that omit confidence now FAIL here,
+  // so aggregateShots can never reach unanimousPASS with a null confidenceMedian.
+  const confidenceAbsent = confidence === null;
+  const lowConfidence = !confidenceAbsent && confidence < LOW_CONFIDENCE;
+  // ffR is null when the lens is unavailable — it must not fail the gate
+  // (null < THRESHOLD is true via JS coercion), and must not appear in the
+  // verdict's below-threshold branches.
+  const ffBelow = !ffLensUnavailable && ffR < THRESHOLD;
+  const bothPass = !ffBelow && cqR >= THRESHOLD;
+  const passed = bothPass && !lowConfidence && !confidenceAbsent;
+
+  const verdict = passed
+    ? 'PASS'
+    : confidenceAbsent
+      ? 'FAIL — confidence absent'
+      : lowConfidence
+        ? 'FAIL — low confidence'
+        : bothPass
+          ? 'FAIL'
+          : ffBelow && cqR < THRESHOLD
+            ? `FAIL — both axes below ${THRESHOLD}`
+            : ffBelow
+              ? `FAIL — functional_fidelity below ${THRESHOLD}`
+              : `FAIL — code_quality below ${THRESHOLD}`;
+
+  const notesLines = [];
+  notesLines.push(`Shot ${signals.shot_index != null ? signals.shot_index : '?'} (${signals.model}) — ${verdict}`);
+  notesLines.push(`  ff=${ffLensUnavailable ? 'n/a (lens unavailable)' : `${ffR}/10`}  cq=${cqR}/10${economyR != null ? `  econ=${economyR}/10 (advisory)` : ''}  conf=${confidence ?? '?'}`);
+  if (notesFromSubagent) {
+    notesLines.push('');
+    notesLines.push(notesFromSubagent.trim());
+  }
+
+  return {
+    score: blended,
+    passed,
+    threshold: THRESHOLD,
+    grader_kind: 'subagent',
+    grader_version: VERSION,
+    rubric_scores: {
+      functional_fidelity: ffR,
+      code_quality: cqR,
+      economy: economyR,
+      code_quality_effective: cqEffective,
+      security_score: securityR,
+      efficiency_score: efficiencyR,
+    },
+    signals,
+    notes_md: notesLines.join('\n'),
+    issues,
+  };
+}
+
+// ---------- server-authoritative grade guards (SR-9 / SR-18 / F1 / G5) ----------
+//
+// THE FINDING (SR-9 / SR-18): POST /api/gds/tasks/:id/grade trusts the client.
+// validateAndScore only shape-validates the numbers — `passed` is computed from
+// the CLIENT's submitted scores. The real adversarial panel + the deterministic
+// route-rank / permission-path pre-passes run CLIENT-SIDE in scripts/gds/ship.js;
+// the server never re-runs them. So a builder can POST
+// {functional_fidelity:10, code_quality:10, confidence:1, issues:[]} to self-pass.
+// AND the credit/achievement side-effects (net-negative "Subtractor" bonus,
+// shipper badges) are driven by client-supplied signals.diff_stats +
+// committed_files the server never re-derives (SR-18).
+//
+// WHAT THE SERVER CAN AND CAN'T DO (the boundary — see report):
+//   * The web tier is checked out at `main`. The builder's feature-branch
+//     commits are NOT on the server at grade time (they only arrive when the
+//     task merges to main). So the server CANNOT independently re-derive the
+//     committed diff at the claimed head_sha. The diff, diff_stats, and
+//     committed_files in the request body remain CLIENT-SUPPLIED.
+//   * BUT the server DOES know the caller's LIVE, authoritative rank
+//     (req.builder.rank, read fresh from the DB per request — ADR 0016). So the
+//     deterministic permission-path pre-pass can run with a TRUSTED rank against
+//     the (client-supplied) committed_files — strictly raising the bar.
+//   * The route-rank pre-pass reads the route files in the server's OWN
+//     checkout (fs) — fully server-authoritative, independent of any client
+//     input. (NB: it audits `main`, not the feature branch — the post-push main
+//     audit owns feature-branch route changes. Re-running here still hard-fails
+//     a forged pass while `main` already carries an ungated write route.)
+//
+// THE GUARD (additive, fail-toward-reject-only): serverSideGuards re-runs the
+// two deterministic pre-passes server-side and applies plausibility/bounding
+// checks. It can ONLY downgrade a client PASS to a non-pass (hard FAIL or
+// manual-confirm); it NEVER upgrades a fail, never relaxes the existing gate,
+// and is a no-op on a client that already reported not-passed. A legitimate
+// honest grade is unaffected.
+//
+// The Archon / GRADER_BYPASS paths do not flow through /grade's passed-gate the
+// way an ordinary ship does (they confirm via /tasks/:id/confirm, which is a
+// separate route), so this guard does not touch them — see the route comment.
+
+// Plausibility threshold: a client PASS that reports NO issues on a NON-TRIVIAL
+// diff is not a credible adversarial-panel verdict — the panel is default-fail
+// and every worker must enumerate concrete issues before a pass; a clean pass on
+// a large diff with an empty issues[] is the exact shape of a forged
+// {ff:10,cq:10,issues:[]} self-pass (SR-9). We don't reject it outright (a small
+// honest change can legitimately have no issues) — we DOWNGRADE it to
+// manual-confirm so a human lands it via /confirm. Thresholds mirror the
+// trivial-diff fast-path's spirit (a change past these sizes is "real work"):
+//   - more than this many changed files, OR
+//   - more than this many added+removed lines
+// makes an empty-issues PASS implausible-as-automatic and forces manual-confirm.
+const IMPLAUSIBLE_PASS_MAX_FILES = TRIVIAL_MAX_FILES;   // 3 — same "small change" bar
+const IMPLAUSIBLE_PASS_MAX_LINES = TRIVIAL_MAX_LINES;   // 30
+
+// Re-derive the size of the change from the submitted committed_files +
+// diff_stats. Both are client-supplied (see boundary note) — we take the
+// STRICTER (larger) of the file-list length and the shortstat files_changed so a
+// forger can't shrink one to dodge the plausibility bar while the other betrays
+// a large diff. Returns { files, lines } with NaN coerced to 0.
+function changeMagnitude({ committedFiles, diffStats } = {}) {
+  const listLen = Array.isArray(committedFiles)
+    ? committedFiles.filter((f) => typeof f === 'string' && f.trim()).length
+    : 0;
+  const statFiles = diffStats && Number.isFinite(Number(diffStats.files_changed))
+    ? Number(diffStats.files_changed)
+    : 0;
+  const files = Math.max(listLen, statFiles);
+  const lines =
+    (Number(diffStats?.lines_added) || 0) + (Number(diffStats?.lines_removed) || 0);
+  return { files, lines };
+}
+
+// serverSideGuards — the server-authoritative hardening layer (SR-9 / SR-18).
+//
+// Inputs:
+//   gradeResult  — the output of validateAndScore on the SUBMITTED body. Its
+//                  `passed` is computed from the client's numbers. We may
+//                  override it (downgrade only).
+//   committedFiles — client-supplied list of committed paths (or null).
+//   builderRank  — the caller's LIVE rank (req.builder.rank — SERVER-KNOWN,
+//                  authoritative). Drives the permission-path pre-pass.
+//   diffStats    — client-supplied { files_changed, lines_added, lines_removed }
+//                  (gradeResult.signals.diff_stats if not passed explicitly).
+//   routesDir    — optional override for tests; defaults to the live routes dir.
+//
+// Returns a NEW grade-result (never mutates the input). When a guard trips, the
+// returned result has passed=false and a `server_guard` block in signals naming
+// every triggered guard + the residual notes. When no guard trips, the input is
+// returned with a passed-through `server_guard: { applied: [...], ok: true }`
+// audit marker so the trail shows the guards RAN (and found nothing) rather than
+// being silently absent.
+//
+// CONTRACT: downgrade-only. If the client already reported not-passed, we leave
+// it not-passed (no resurrection). We only ever flip true→false.
+function serverSideGuards(gradeResult, { committedFiles, builderRank, diffStats, routesDir } = {}) {
+  const base = gradeResult || {};
+  const ds = diffStats || base.signals?.diff_stats || null;
+  const guardsTripped = [];        // [{ guard, severity, summary }]
+  const extraIssues = [];          // surfaced into the result's issues[]
+  let downgradeTo = null;          // 'fail' | 'concerns' | null
+
+  // The guards only have teeth on a CLIENT PASS — a non-pass is already
+  // blocked/fallen-through by the existing gate, and downgrade-only means we
+  // never touch it. We still RUN the deterministic checks (their findings are a
+  // useful audit signal even on a fail) but only let them flip the verdict when
+  // base.passed === true.
+  const clientPassed = base.passed === true;
+
+  // --- Guard 1: deterministic pre-passes, server-side (SR-9 / F1) ---
+  // route-rank: reads the server's own route files (fs) — server-authoritative.
+  // permission-path: runs with the TRUSTED live rank against the (client) files.
+  // Either hard-fail flips a client PASS to a hard FAIL regardless of submitted
+  // scores — this is the core "re-run the deterministic checks server-side"
+  // hardening. A non-hardFail (e.g. an unclassified READ route → 'concerns') is
+  // recorded but does NOT block here: the client-side panel's Hacker already
+  // adjudicates read-route intent, and a server-side downgrade-to-concerns on a
+  // read route would be a behavior change with no SR-9 security value.
+  let routeRank = null;
+  try {
+    routeRank = routeRankCheck.checkRouteRanks(routesDir ? { routesDir } : {});
+  } catch (_) { routeRank = null; /* fs error → no server-side route finding; client panel + main audit still gate */ }
+  const permPath = permissionPathCheck.checkPermissionPaths({ changedFiles: committedFiles || [], builderRank });
+
+  if (routeRank && routeRank.hardFail) {
+    guardsTripped.push({ guard: 'route_rank', severity: 'blocker',
+      summary: 'server-side route-rank pre-pass hard-failed (an ungated write route exists) — a client PASS cannot override this (SR-9)' });
+    for (const f of routeRank.findings.filter((x) => x.severity === 'blocker')) {
+      extraIssues.push({ severity: 'blocker', file: f.file, summary: `[server route-rank] ${f.summary}`, worker: 'server-route-rank' });
+    }
+    if (clientPassed) downgradeTo = 'fail';
+  }
+  if (permPath && permPath.hardFail) {
+    guardsTripped.push({ guard: 'permission_path', severity: 'blocker',
+      summary: `server-side permission-path pre-pass hard-failed: rank '${builderRank}' is below Metic and the submitted committed_files touch protected machinery — a client PASS cannot override this (SR-9 / SEC #863)` });
+    for (const f of permPath.findings) {
+      extraIssues.push({ severity: 'blocker', file: f.file, summary: `[server permission-path] ${f.summary}`, worker: 'server-permission-path' });
+    }
+    if (clientPassed) downgradeTo = 'fail';
+  }
+
+  // --- Guard 1b: vacuous permission-path input (task 1002646 / report 1000021 G-1) ---
+  // The pre-pass above pairs the SERVER-known rank with CLIENT-supplied
+  // committed_files, so omitting the list (or sending []) made the sub-floor
+  // protected-path check pass VACUOUSLY — zero files, zero hits, hardFail:false —
+  // a trusted-rank check applied to an untrusted, omittable diff. The server
+  // still cannot re-derive the feature-branch diff at grade time (boundary note
+  // above; the task-1002645 published tip is recorded at ci-land, AFTER the
+  // grade), but it can refuse to treat "no input" as "no hits": a caller below
+  // the registry's lowest floor submitting NO file list makes the check
+  // UNPROVABLE → fail closed. Honest ships are unaffected (ship.js always sends
+  // the real committed list — task 878 — and a floor-clearing rank never enters
+  // this branch). The dishonest-LIST case (a sub-floor caller sending an
+  // innocuous list while touching protected paths) stays owned by gate-review CI
+  // + the post-push main audit, which read the REAL diff. Unknown rank keeps
+  // failing open at this layer (isBelowFloor → false) — the main audit reads the
+  // real author rank from the DB and owns that case, exactly as for the pre-pass.
+  const submittedFileCount = Array.isArray(committedFiles)
+    ? committedFiles.filter((f) => typeof f === 'string' && f.trim()).length
+    : 0;
+  if (permissionPathCheck.isBelowFloor(builderRank) && submittedFileCount === 0) {
+    // Resolve the floor label from the registry at runtime (the D-16/N-3
+    // stale-string rule) — never a hardcoded rank name.
+    const floorRank = Object.keys(permissionPathCheck.RANK_TIER)
+      .find((r) => permissionPathCheck.RANK_TIER[r] === permissionPathCheck.MIN_TIER) || 'the floor';
+    guardsTripped.push({ guard: 'permission_path_unprovable', severity: 'blocker',
+      summary: `rank '${builderRank}' is below the protected-path floor ('${floorRank}') and the grade submitted no committed_files — the permission-path check cannot run on an empty list, so a client PASS cannot stand (fail closed; task 1002646 / SR-9). Remedy: re-run the ship — ship.js submits the real committed file list; a genuinely file-less (DB-only) change needs a ${floorRank}+ builder to land it via /tasks/:id/confirm.` });
+    extraIssues.push({ severity: 'blocker', file: '(grade)', summary:
+      `[server permission-path] no committed_files submitted by a rank below the '${floorRank}' floor — the protected-path check is unprovable and fails closed (task 1002646)`, worker: 'server-permission-path' });
+    if (clientPassed) downgradeTo = 'fail';
+  }
+
+  // --- Guard 2: implausible client verdict (SR-9 / task 1002658, ADR 0164) ---
+  // Redesigned around what the submitted body itself can prove. The old form
+  // (raw issues.length === 0) was defeated by one fabricated `{}` AND fired on
+  // every honest unanimous zero-issue panel PASS (its only in-sample firings —
+  // eval 2-for-2, tasks 1002643 ×2 and 1002663 — were ALL false positives).
+  // Now: count only SUBSTANTIVE issues; a padded issues[] (entries but no
+  // substance) is the forgery signature and trips regardless of evidence; a
+  // genuinely empty issues[] trips only when the body ALSO lacks the full
+  // per-worker panel shape — a real panel that ran and unanimously found
+  // nothing is waived with an audit marker instead of a manual-confirm. The
+  // magnitude inputs remain client-supplied; the binding authority on the real
+  // diff is land-time (gate-review CI + post-push main audit) — ADR 0164.
+  const rawIssueCount = Array.isArray(base.issues) ? base.issues.length : 0;
+  const substantiveIssueCount = (Array.isArray(base.issues) ? base.issues : [])
+    .filter(isSubstantiveIssue).length;
+  const paddedIssues = rawIssueCount > 0 && substantiveIssueCount === 0;
+  const panelEvidence = hasPanelEvidence(base.signals);
+  const { files: changeFiles, lines: changeLines } = changeMagnitude({ committedFiles, diffStats: ds });
+  const nonTrivial = changeFiles > IMPLAUSIBLE_PASS_MAX_FILES || changeLines > IMPLAUSIBLE_PASS_MAX_LINES;
+  let implausiblePassWaived = null;
+  if (clientPassed && nonTrivial && substantiveIssueCount === 0 && (paddedIssues || !panelEvidence)) {
+    const shape = paddedIssues
+      ? `issues[] holds ${rawIssueCount} entr${rawIssueCount === 1 ? 'y' : 'ies'} with no substance (no known severity + summary) — the padded-issues forgery signature`
+      : 'empty issues[] with no per-worker panel evidence in signals';
+    guardsTripped.push({ guard: 'implausible_pass', severity: 'major',
+      summary: `client PASS on a non-trivial diff (${changeFiles} file(s), ${changeLines} line(s) > ${IMPLAUSIBLE_PASS_MAX_FILES}/${IMPLAUSIBLE_PASS_MAX_LINES}): ${shape} — not a credible default-fail panel verdict → manual-confirm (SR-9 / ADR 0164)` });
+    extraIssues.push({ severity: 'major', file: '(grade)', summary:
+      `[server plausibility] a passing grade with no substantive findings and no panel evidence on a ${changeFiles}-file / ${changeLines}-line change must be human-confirmed via /confirm`, worker: 'server-plausibility' });
+    if (downgradeTo !== 'fail') downgradeTo = 'concerns';
+  } else if (clientPassed && nonTrivial && rawIssueCount === 0 && panelEvidence) {
+    implausiblePassWaived = 'panel_evidence';
+  }
+
+  // --- Guard 3: bound the credit/achievement signals (SR-18) ---
+  // The net-negative "Subtractor" bonus + shipper badges key off client-supplied
+  // signals.diff_stats + committed_files the server can't re-derive. We can't
+  // make them server-authoritative without the feature-branch diff (residual,
+  // see report), but we CAN strip an OBVIOUSLY-FORGED net-negative claim:
+  // diff_stats that claims a net-negative (removed > added) while the submitted
+  // committed_files list is large is internally inconsistent with a real
+  // simplification, and is the cheap way to farm the Subtractor bonus. When the
+  // signals are internally implausible we NEUTRALIZE the net-negative reward by
+  // zeroing lines_removed in the forwarded diff_stats (so awardNetNegativeBonus
+  // sees removed<=added → bonus 0) WITHOUT altering the displayed/audited stats.
+  // Conservative: only fires on the inconsistent shape; an honest net-negative
+  // simplification (few files, removed>added) is untouched.
+  let sanitizedSignals = base.signals;
+  const claimsNetNegative =
+    ds && (Number(ds.lines_removed) || 0) > (Number(ds.lines_added) || 0);
+  const NET_NEGATIVE_MAX_FILES = 25; // a "simplification" touching >25 files is implausibly broad
+  if (claimsNetNegative && changeFiles > NET_NEGATIVE_MAX_FILES) {
+    guardsTripped.push({ guard: 'forged_net_negative', severity: 'minor',
+      summary: `net-negative diff_stats (removed ${ds.lines_removed} > added ${ds.lines_added}) across ${changeFiles} files is implausibly broad for a simplification — net-negative bonus neutralized (SR-18)` });
+    // Clone signals + zero the credit-driving field WITHOUT mutating the input
+    // or the displayed diff_stats audit value (we add a sibling marker instead).
+    sanitizedSignals = {
+      ...(base.signals || {}),
+      diff_stats: { ...ds, lines_removed: Number(ds.lines_added) || 0 },
+      diff_stats_reported: ds, // preserve what the client claimed for the audit trail
+    };
+  }
+
+  // No guard tripped (or only audit-level findings on a non-pass) → return the
+  // input with a passed-through audit marker so the trail shows guards ran.
+  if (downgradeTo == null && guardsTripped.length === 0 && sanitizedSignals === base.signals) {
+    return {
+      ...base,
+      signals: {
+        ...(base.signals || {}),
+        server_guard: {
+          applied: ['route_rank', 'permission_path', 'permission_path_unprovable', 'implausible_pass', 'forged_net_negative'],
+          ok: true,
+          tripped: [],
+          // task 1002658 / ADR 0164: the audit trail records WHY a zero-issue
+          // pass on a non-trivial diff stood (panel evidence), so /grade-audit
+          // can distinguish waived from never-evaluated.
+          ...(implausiblePassWaived ? { implausible_pass_waived: implausiblePassWaived } : {}),
+        },
+      },
+    };
+  }
+
+  // Build the downgraded result. Downgrade-only: if base wasn't passing we keep
+  // it not-passing; we never resurrect. Map the panel verdict onto the v3
+  // server gate the same way aggregatePanel does (fail → confidence 0; concerns
+  // → FALLTHROUGH_CONFIDENCE below the low-confidence cap; pass left as-is).
+  const newPassed = clientPassed && downgradeTo == null;
+  const forwardedConfidence =
+    downgradeTo === 'fail'
+      ? 0
+      : downgradeTo === 'concerns'
+        ? FALLTHROUGH_CONFIDENCE
+        : (base.signals?.confidence ?? null);
+
+  const guardNote = guardsTripped.length
+    ? `\n\nServer-authoritative guards (SR-9 / SR-18) ${downgradeTo ? `DOWNGRADED this grade to ${downgradeTo.toUpperCase()}` : 'flagged'}:\n`
+      + guardsTripped.map((g) => `  [${g.severity}] ${g.guard}: ${g.summary}`).join('\n')
+    : '';
+
+  return {
+    ...base,
+    passed: newPassed,
+    issues: [...(base.issues || []), ...extraIssues],
+    signals: {
+      ...sanitizedSignals,
+      // confidence drives the server-side gate alignment (validateAndScore on the
+      // body already ran; this is the authoritative post-hoc adjustment).
+      confidence: forwardedConfidence,
+      server_guard: {
+        applied: ['route_rank', 'permission_path', 'permission_path_unprovable', 'implausible_pass', 'forged_net_negative'],
+        ok: guardsTripped.length === 0,
+        downgraded_to: downgradeTo,
+        client_passed: clientPassed,
+        tripped: guardsTripped,
+        // task 1002614 (map P-2): a permission_path trip is an AUTHORIZATION
+        // refusal of the builder's rank over protected paths — not a verdict on
+        // the code. Named here so clients render it as a wall, not a quality
+        // FAIL the builder should fix-and-retry (the envelope used to teach
+        // exactly that wrong lesson). route_rank stays a code finding.
+        // task 1002646: permission_path_unprovable is the same wall — the rank
+        // floor refusing an unverifiable diff — so it renders the same way.
+        authorization_refusal: guardsTripped.some((g) => g.guard === 'permission_path' || g.guard === 'permission_path_unprovable'),
+        ...(implausiblePassWaived ? { implausible_pass_waived: implausiblePassWaived } : {}),
+      },
+    },
+    notes_md: `${base.notes_md || ''}${guardNote}`,
+  };
+}
+
+// ---------- v3: multi-shot aggregation ----------
+
+// Collapses N per-shot grade-results into the final v3 grade-result.
+// Pass requires unanimous PASS on all shots; anything else (any FAIL, any
+// error, any disagreement) → not passed. Issues are deduped across shots
+// by (file, summary). Displayed rubric_scores use the median across shots
+// so the trend dashboard stays one-number-per-task.
+function aggregateShots(shotResults, meta = {}) {
+  const N = shotResults.length;
+  const verdicts = shotResults.map((s) => ({
+    passed: s.passed,
+    ff: s.rubric_scores?.functional_fidelity ?? null,
+    cq: s.rubric_scores?.code_quality ?? null,
+    economy: s.rubric_scores?.economy ?? null,
+    cq_effective: s.rubric_scores?.code_quality_effective ?? null,
+    confidence: s.signals?.confidence ?? null,
+    model: s.signals?.model ?? null,
+    run_ms: s.signals?.run_ms ?? null,
+    shot_index: s.signals?.shot_index ?? null,
+    notes_md: s.notes_md,
+    issues: s.issues || [],
+    error:
+      s.signals?.parse_error
+        ? 'parse_error'
+        : s.signals?.schema_error
+          ? 'schema_error'
+          : s.signals?.subprocess_error || null,
+  }));
+
+  const ff = median(verdicts.map((v) => v.ff));
+  const cq = median(verdicts.map((v) => v.cq));
+  const economy = median(verdicts.map((v) => v.economy));
+  const cqEffective = median(verdicts.map((v) => v.cq_effective));
+  const blended = ff != null && cq != null ? r1((ff + cq) / 2) : 0;
+  // Top-level aggregated confidence = median of per-shot confidences. Without
+  // this, ship.js forwards a null top-level confidence to /tasks/:id/grade,
+  // and the server's validateAndScore (re-running on the POST body) hits the
+  // Number(null)=0 trap → FAIL even though every shot independently passed.
+  // Caught on the MAS Phase 1 self-ship (#395).
+  //
+  // Computed UNROUNDED (no r1()) — confidence sits near a 0.4 gate cap so
+  // rounding to one decimal could nudge a borderline value across the cap
+  // in either direction. Per-shot confidences are already 0-1 floats.
+  const confVals = verdicts
+    .map((v) => v.confidence)
+    .filter((n) => Number.isFinite(n))
+    .sort((a, b) => a - b);
+  const confidenceMedian = confVals.length === 0
+    ? null
+    : confVals.length % 2
+      ? confVals[(confVals.length - 1) / 2]
+      : (confVals[confVals.length / 2 - 1] + confVals[confVals.length / 2]) / 2;
+
+  // Dedupe issues across shots by (file, summary). Keep first-seen severity.
+  const seen = new Set();
+  const issues = [];
+  for (const v of verdicts) {
+    for (const it of v.issues) {
+      if (!it || typeof it !== 'object') continue;
+      const key = `${it.file ?? ''}::${(it.summary ?? '').trim()}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      issues.push(it);
+    }
+  }
+
+  const passCount = verdicts.filter((v) => v.passed === true).length;
+  const failCount = verdicts.filter((v) => v.passed === false && !v.error).length;
+  const errorCount = verdicts.filter((v) => v.error).length;
+  const allPassed = N > 0 && passCount === N;
+
+  let verdict;
+  let passed;
+  let aggregationKind;
+  if (errorCount > 0) {
+    passed = false;
+    verdict = `FAIL — ${errorCount}/${N} shot(s) errored`;
+    aggregationKind = 'errored';
+  } else if (allPassed) {
+    passed = true;
+    verdict = `PASS — ${N}/${N} shots unanimous`;
+    aggregationKind = 'unanimous_pass';
+  } else if (passCount === 0) {
+    passed = false;
+    verdict = `FAIL — ${failCount}/${N} shots`;
+    aggregationKind = 'unanimous_fail';
+  } else {
+    passed = false;
+    verdict = `FAIL — ${passCount} pass, ${failCount} fail (no unanimous pass)`;
+    aggregationKind = 'disagreement';
+  }
+
+  const lines = [];
+  lines.push(`Subagent grader ${VERSION} (multi-shot, ${N}× shots) — ${verdict}`);
+  lines.push(`  functional_fidelity (median): ${ff ?? '?'}/10`);
+  lines.push(`  code_quality (median):        ${cq ?? '?'}/10`);
+  if (economy != null) {
+    lines.push(`  economy (advisory, median):   ${economy}/10`);
+  }
+  lines.push(`  blended (median):             ${blended}/10  (threshold ${THRESHOLD}, both axes must clear on EVERY shot)`);
+  lines.push('');
+  lines.push('Per-shot:');
+  for (let i = 0; i < verdicts.length; i++) {
+    const v = verdicts[i];
+    const status = v.error ? 'ERROR' : v.passed === true ? 'PASS' : 'FAIL';
+    const ffStr = v.ff != null ? `${v.ff}` : '?';
+    const cqStr = v.cq != null ? `${v.cq}` : '?';
+    const confStr = v.confidence != null ? `  conf=${v.confidence}` : '';
+    const errStr = v.error ? `  (${v.error})` : '';
+    lines.push(`  shot[${i}] ${status}  ff=${ffStr}  cq=${cqStr}${confStr}  ${v.model ?? '?'}${errStr}`);
+  }
+  if (issues.length > 0) {
+    lines.push('');
+    lines.push(`Issues (${issues.length} unique across shots):`);
+    for (const it of issues.slice(0, 20)) {
+      const sev = String(it.severity || '?').padEnd(7);
+      const file = String(it.file || '?');
+      const summary = String(it.summary || '').replace(/\s+/g, ' ').trim();
+      lines.push(`  [${sev}] ${file} — ${summary}`);
+    }
+    if (issues.length > 20) {
+      lines.push(`  ... ${issues.length - 20} more (full set in signals.shots[].issues)`);
+    }
+  }
+
+  // #486 (ADR 0028 path 1): sum each shot's own subprocess cost (envelope
+  // total_cost_usd) so the trivial-diff path reports panel_cost_usd the same way
+  // the full panel does. The single-shot trivial path is the common case here.
+  const panelCostUsd = shotResults.reduce((s, r) => s + (Number(r.cost_usd) || 0), 0);
+
+  return {
+    score: blended,
+    passed,
+    threshold: THRESHOLD,
+    grader_kind: 'subagent-multishot',
+    grader_version: VERSION,
+    panel_cost_usd: panelCostUsd, // #486: panel's own API spend (USD)
+    rubric_scores: {
+      functional_fidelity: ff,
+      code_quality: cq,
+      economy,
+      code_quality_effective: cqEffective,
+    },
+    signals: {
+      grader_kind: 'subagent-multishot',
+      grader_version: VERSION,
+      threshold: THRESHOLD,
+      // Top-level confidence = median across shots. ship.js forwards this to
+      // POST /tasks/:id/grade so the server-side re-validation has a real
+      // number rather than null (see Number(null)=0 fix in validateAndScore).
+      confidence: confidenceMedian,
+      shots: verdicts,
+      shot_count: N,
+      pass_count: passCount,
+      fail_count: failCount,
+      error_count: errorCount,
+      shot_aggregation: aggregationKind,
+      ...meta,
+    },
+    notes_md: lines.join('\n'),
+    issues,
+  };
+}
+
+// ---------- v3: subagent subprocess invoker ----------
+
+// Unchanged from v2 — spawns `claude -p --print --model <model> --output-
+// format json` with stdin = prompt. The v3 caller varies `model` per shot
+// via opts.model (set by gradeSubagent below).
+
+module.exports = {
+  aggregateShots,
+  changeMagnitude,
+  hasPanelEvidence,
+  isSubstantiveIssue,
+  serverSideGuards,
+  validateAndScore,
+};