@bongos/core 1.19.332 → 1.19.333

package/modules/grading/grader-config.js

@@ -0,0 +1,98 @@
+// modules/grading/grader-config.js — the rubric + tuning constants the grader is
+// configured by, and the two DETERMINISTIC pre-passes (permission-path and
+// route-rank) that run before any model does.
+//
+// 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 RUBRIC = JSON.parse(
+  fs.readFileSync(path.join(__dirname, 'grader-rubric.json'), 'utf8')
+);
+
+// V4 = the active panel-based gate. V3 / V1 are kept under their fields for
+// the two paths that still read them: V3 = the trivial-diff multi-shot grader
+// (ship.js #513), V1 = the audit-ships.js retroactive deterministic path. The
+// v2 binding + its rubric block were dead (no reader) and removed in task 466.
+const V4 = RUBRIC.v4;
+const V3 = RUBRIC.v3;
+const V1 = RUBRIC.v1;
+const THRESHOLD = V4.threshold;
+const VERSION = V4.version;
+const LOW_CONFIDENCE = V4.low_confidence_threshold;
+// DEFAULT_SHOTS is kept for the v3 multi-shot path (still exported for
+// diagnostics); v4 doesn't use shots — it uses workers.
+const DEFAULT_SHOTS = V3.shots || 3;
+const ASSUMED_BUILDER_MODEL = V4.assumed_builder_model || 'claude-fable-5';
+const DEFAULT_GRADER_MODEL = V4.default_model || 'claude-sonnet-5';
+const FALLTHROUGH_CONFIDENCE = V4.fallthrough_confidence ?? 0.3;
+// task 1002660: per-worker model tier overrides (rubric-configured). The
+// Quality worker was 41% of panel spend with 75% nit findings — its cq/economy
+// judgment doesn't need the full cross-model tier. Keys are worker kinds;
+// values are model ids. workerModelFor guards the cross-model invariant.
+const WORKER_MODEL_TIERS = V4.worker_model_tiers || {};
+const workers = require('./grader-workers');
+const generatedProvenance = require('./generated-provenance'); // task 1002795
+// Carved into modules/grading/ (BV1.R73 / ADR 0091 §1+§4): the two deterministic
+// trust classifiers are KERNEL (KERNEL_FILES, R70) — reached through the doorway,
+// never a deep core require. The worker panel + extract-json are intra-module.
+const api = require('../../src/module-api');
+const routeRankCheck = api.routeRankCheck;
+const permissionPathCheck = api.permissionPathCheck;
+
+// Deterministic pre-pass: the sub-Metic permission-path gate (SEC #863). Runs
+// ONLY when the change set touches a permission-sensitive path AND the builder
+// rank resolves below Metic — otherwise null (zero cost / no finding). Like the
+// route-rank pre-pass, the result is a pseudo-worker appended to the panel so
+// aggregatePanel's any-fail gate hard-fails a sub-Metic ship of protected code
+// with no gate-logic change. builderRank comes from the caller's live /me read
+// (ship.js) or req.builder.rank (server); unknown rank fails OPEN here (the
+// post-push main audit, which reads the real author rank from the DB, owns the
+// unknown/dishonest case).
+function permissionPathPrePass(changedFiles, builderRank) {
+  const result = permissionPathCheck.checkPermissionPaths({ changedFiles, builderRank });
+  if (!result.hardFail) return null;
+  return { findings: result.findings, workerResult: permissionPathCheck.toWorkerResult(result) };
+}
+
+// Deterministic pre-pass: the route-rank invariant (#475 / C7). Runs ONLY when
+// a src/bongos/routes/ file is in the change set (zero cost otherwise). Returns
+// the findings (fed to the Hacker worker as input) plus a pseudo-worker result
+// appended to the panel so aggregatePanel's any-fail gate handles it directly.
+// Shared verbatim by gradeSubagent (ship-time) and conductor-dispatch.js
+// (mid-flight) so the route-parsing logic lives in exactly one place.
+function routeRankPrePass(changedFiles) {
+  const touched = (changedFiles || []).some((f) => routeRankCheck.ROUTE_FILE_RE.test(f));
+  if (!touched) return null;
+  const result = routeRankCheck.checkRouteRanks();
+  return { findings: result.findings, workerResult: routeRankCheck.toWorkerResult(result) };
+}
+
+
+module.exports = {
+  ASSUMED_BUILDER_MODEL,
+  DEFAULT_GRADER_MODEL,
+  DEFAULT_SHOTS,
+  FALLTHROUGH_CONFIDENCE,
+  LOW_CONFIDENCE,
+  RUBRIC,
+  THRESHOLD,
+  V1,
+  V3,
+  V4,
+  VERSION,
+  WORKER_MODEL_TIERS,
+  api,
+  generatedProvenance,
+  permissionPathCheck,
+  permissionPathPrePass,
+  routeRankCheck,
+  routeRankPrePass,
+  workers,
+};

package/modules/grading/grader-model.js

@@ -0,0 +1,150 @@
+// modules/grading/grader-model.js — small numeric helpers, the trivial-diff
+// detector, and model selection for the grader and its panel workers.
+//
+// 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 { ASSUMED_BUILDER_MODEL, DEFAULT_GRADER_MODEL, WORKER_MODEL_TIERS, api } = require('./grader-config.js');
+
+function r1(n) {
+  return Math.round(Number(n) * 10) / 10;
+}
+
+function clamp(n, lo, hi) {
+  return Math.max(lo, Math.min(hi, n));
+}
+
+function median(arr) {
+  const v = arr.filter((n) => Number.isFinite(n)).slice().sort((a, b) => a - b);
+  if (v.length === 0) return null;
+  const mid = Math.floor(v.length / 2);
+  return v.length % 2 ? r1(v[mid]) : r1((v[mid - 1] + v[mid]) / 2);
+}
+
+// ---------- v4.1: trivial-diff fast-path (#513) ----------
+//
+// The #506 post-mortem: a +1/-1 welcome-copy tweak ran the full 4-worker
+// adversarial Opus/Sonnet panel — disproportionate cost for a one-word change.
+// isTrivialDiff classifies a change as "copy/docs only, small, and touching no
+// logic path". ship.js routes those to a SINGLE generalist grader shot instead
+// of the panel ("lighter, not skipped" — the 1-shot still scores ff+cq+economy
+// +confidence so the server gate applies, and the deterministic scanner + smoke
+// + route-rank checks run regardless). Everything else keeps the full panel.
+//
+// Deliberately conservative — defaults to "not trivial" (full panel) whenever
+// in doubt (missing diffStats, zero files, any logic-path file, oversized diff).
+const TRIVIAL_MAX_FILES = 3;
+const TRIVIAL_MAX_LINES = 30;
+// Copy/docs/front-end surfaces eligible for the lighter single-shot grade.
+// (Both web surfaces moved under modules/<key>/public/: the status dashboard to
+// modules/status-ui/public/ in BV1.R84 and the hall to modules/hall-ui/public/ in
+// BV1.R85.)
+const TRIVIAL_PATH_RE = /(?:^|\/)[^/]+\.md$|^docs\/|^public\/|^modules\/hall-ui\/public\/|^modules\/status-ui\/public\//;
+// Logic / infra / test surfaces that force the full panel even on a tiny diff —
+// these are where a subtle one-liner can do real damage, so they never qualify.
+const LOGIC_PATH_RE = /^src\/|^scripts\/|^migrations\/|^server\.js$|^tests\/|^\.claude\//;
+// Executable code AND config are NEVER trivial, even under public*/ (#513
+// Hacker). A copy tweak and an XSS / client-authz regression are
+// indistinguishable to a path+size heuristic, and the builders-hall + game
+// front-ends carry auth flows and game logic — so any code extension forces the
+// full adversarial panel. Config/data files (.json/.yaml/.env/…) are excluded
+// too: a client-side config change is security-relevant and shouldn't get the
+// lighter shot. Only genuinely static content (markdown, CSS/HTML, images,
+// plain text) takes the single shot.
+// HTML and SVG are executable in a browser (inline <script>, on* handlers,
+// <svg onload>), so they are NOT "static" for grading purposes — a small
+// edit could introduce client-side XSS that only the full panel's Hacker
+// would catch. Excluded alongside code + config (#513 Hacker).
+const NON_TRIVIAL_EXT_RE = /\.(?:js|mjs|cjs|jsx|ts|tsx|py|sh|bash|rb|go|sql|json|ya?ml|toml|ini|env|html?|svg)$|(?:^|\/)\.env(?:\.|$)/;
+
+function isTrivialDiff({ changedFiles, diffStats } = {}) {
+  if (!diffStats || typeof diffStats !== 'object') return false;
+  const files = Array.isArray(changedFiles) ? changedFiles.filter(Boolean) : [];
+  if (files.length === 0) return false;
+  const fc = Number(diffStats.files_changed);
+  const lines = (Number(diffStats.lines_added) || 0) + (Number(diffStats.lines_removed) || 0);
+  // Cap on BOTH the shortstat count and the actual file-list length — a rename
+  // can disagree between the two, so take the stricter of the two (#513 nit).
+  if (!Number.isFinite(fc) || fc <= 0 || fc > TRIVIAL_MAX_FILES) return false;
+  if (files.length > TRIVIAL_MAX_FILES) return false;
+  if (lines <= 0 || lines > TRIVIAL_MAX_LINES) return false;
+  // Every changed file must be a copy/docs path, none in a logic path, and none
+  // an executable-code or config file (those always get the full panel).
+  return files.every((f) =>
+    TRIVIAL_PATH_RE.test(f) && !LOGIC_PATH_RE.test(f) && !NON_TRIVIAL_EXT_RE.test(f));
+}
+
+// ---------- v3: cross-family model selection (ADR 0024) ----------
+
+// Returns the grader model given the builder's model — a DIFFERENT model from
+// the builder is the cross-model adversarial guarantee (ADR 0024). With no
+// builderModel the caller assumes the owner-top-model builder (CLAUDE.md §2),
+// resolving to the default grader — the path selectGraderModel({}) takes.
+//
+// task 1002659 (Claude 5 refresh): top-tier builders (fable/mythos, opus)
+// grade on the current mid tier; sonnet/haiku builders grade on the tier
+// above. #117's throw-on-unknown is reversed: the throw fired INSIDE the
+// grade step, stranding any ship whose builder id lacked an opus/sonnet/haiku
+// substring (claude-fable-5 was exactly that) — a worse failure than the
+// misconfiguration it guarded. Unknown ids now warn loudly and grade on
+// DEFAULT_GRADER_MODEL; the id still reaches signals.builder_model_assumed,
+// so /grader-health can spot the drift.
+function selectGraderModel({ builderModel } = {}) {
+  const bm = (builderModel || ASSUMED_BUILDER_MODEL).toLowerCase();
+  if (bm.includes('fable') || bm.includes('mythos')) return 'claude-sonnet-5';
+  if (bm.includes('opus')) return 'claude-sonnet-5';
+  if (bm.includes('sonnet')) return 'claude-opus-5';
+  if (bm.includes('haiku')) return 'claude-opus-5';
+  console.error(
+    `selectGraderModel: unrecognized builder model ${JSON.stringify(builderModel)} — ` +
+    `no 'fable'/'mythos'/'opus'/'sonnet'/'haiku' token; grading on the default ` +
+    `${DEFAULT_GRADER_MODEL} (cross-model unverifiable — task 1002659, was a #117 throw)`
+  );
+  return DEFAULT_GRADER_MODEL;
+}
+
+// task 1002660: resolve one worker's model — the rubric tier override when one
+// exists, else the panel's cross-model pick. The override is refused (falls
+// back to graderModel) when it lands on the BUILDER's own family: tiering is
+// a cost lever, never a hole in the ADR 0024 cross-model guarantee.
+const MODEL_FAMILY_TOKENS = ['fable', 'mythos', 'opus', 'sonnet', 'haiku'];
+function workerModelFor(kind, graderModel, builderModel) {
+  const tier = WORKER_MODEL_TIERS[kind];
+  if (!tier) return graderModel;
+  const bm = String(builderModel || ASSUMED_BUILDER_MODEL).toLowerCase();
+  const tierFamily = MODEL_FAMILY_TOKENS.find((t) => String(tier).toLowerCase().includes(t));
+  if (tierFamily && bm.includes(tierFamily)) return graderModel;
+  return tier;
+}
+
+// ---------- v3: prompt builder (default-fail framing) ----------
+
+// The instance's project name, injected into the grader's identity line so a
+// non-OTB Cloud Bongos instance is graded against ITS OWN project, never a
+// hardcoded "Off the Boats" (ADR 0062 §3/§5; the branding contract's
+// llmProjectName field). Reached through the doorway like every other host-
+// context read in this module — never a deep core require. Resolved once at
+// module load (the brand is a per-process singleton); falls back to a neutral
+// phrase if branding fails to resolve so the gate never crashes on a config error.
+const LLM_PROJECT = (() => {
+  try { return api.branding().llmProjectName || 'this project'; }
+  catch { return 'this project'; }
+})();
+
+
+module.exports = {
+  LLM_PROJECT,
+  MODEL_FAMILY_TOKENS,
+  TRIVIAL_MAX_FILES,
+  TRIVIAL_MAX_LINES,
+  clamp,
+  isTrivialDiff,
+  median,
+  r1,
+  selectGraderModel,
+  workerModelFor,
+};

package/modules/grading/grader-prompt.js

@@ -0,0 +1,139 @@
+// modules/grading/grader-prompt.js — the adversarial reviewer prompt and the
+// per-grade prompt builder.
+//
+// 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 { V3, generatedProvenance, workers } = require('./grader-config.js');
+const { LLM_PROJECT } = require('./grader-model.js');
+
+const PROMPT_HEADER = `You are an adversarial code-review subagent for the ${LLM_PROJECT} project. You are reviewing one shipped change to decide whether it deserves to ship.
+
+Your job is to FIND WHAT IS WRONG with this change. **The default verdict is FAIL.** To return a PASS, you must affirmatively conclude — after a careful read of the diff and (using your Read tool) the relevant post-merge files — that no material problems remain.
+
+Begin by hunting for these specific failure modes. When you find one, CITE the diff line or name the failing acceptance criterion:
+
+- TODOs, FIXMEs, "for now", "temporary" or "stub" comments left in shipped code.
+- Hardcoded shortcuts: assuming one builder, one user, one project root, one tenant, one environment, or one identity. Look for literal "lars", "lars589", absolute /Users paths, hardcoded ports, hardcoded IDs.
+- Scope gaps: acceptance criteria in the description that the diff DOES NOT satisfy. Read the description's "Acceptance" section line by line.
+- Demo / dummy / mock code that lies: returns a fixed value, fakes a successful result, mocks at the wrong layer, or pretends to call something it doesn't.
+- Missing tests for new logic: any non-trivial new function, route handler, branch, or aggregation that ships without a covering test.
+- Broken invariants: methodology rules in CLAUDE.md, cross-verified Python/JS autotile lookups, ground-vs-object cell split per ADR 0012, the "every change is backed by a claimed GDS task" rule, the trust-boundary rule per ADR 0016 ("server-enforced permissions"), the no-hardcoded-Archon-identity rule per V3.R12 #236.
+- Dead code: helpers, exports, branches, or files added but never called from anywhere in the post-merge tree. Use Read on the receiving site if unsure.
+- Reads/writes outside the declared touches[]: if the diff edits files the task didn't claim, that's a scope creep — call it out.
+
+You return three scores (0-10), notes, an issues array, and a confidence value:
+
+1. functional_fidelity (0-10): did the diff implement what the description scoped? 10 = every acceptance criterion satisfied by code or explicitly out-of-scope per the description. 6 = mostly there with one NAMED gap. Below 6 = scope gaps, broken acceptance criteria, or demo code that lies.
+2. code_quality (0-10): is the code well-written for THIS codebase? 10 = production-quality, would-merge-without-comment. 6 = ships but with a clear improvement a reviewer would suggest. Below 6 = broken style, dead code, broken invariants, missing tests where warranted.
+3. economy (0-10, ADVISORY): is the change as small and simple as the task warrants? 10 = minimal and focused. 6 = a bit more than necessary. Below 6 = bloated, speculative abstraction, duplicated logic.
+
+**The hard gate** (applied downstream, you do not enforce it yourself; just score honestly): functional_fidelity >= 6 AND code_quality >= 6 AND confidence >= 0.4. Below 6 on either axis is a FAIL. Economy is advisory only.
+
+**For every issue you list:** include severity (blocker | major | minor | nit), the file path, and a one-line summary that quotes the offending diff line or names the failing acceptance criterion. Vague summaries like "code quality could be better" are not acceptable — be specific or omit it.
+
+**Sanity checks:**
+- A PASS with no issues[] entries is suspicious. If you found nothing material wrong, briefly say WHY in notes_md: which acceptance criteria you verified, which files you Read, which could-have-gone-wrong didn't.
+- A FAIL with no issues[] entries is invalid. At least one concrete issue must explain the verdict.
+- A score below 6 with no issue at severity major or blocker is inconsistent — name the major problem.
+
+**Confidence:** 0-1, your self-reported confidence in your two scores. If you cannot judge (description too vague to grade against, diff too large to fit comfortably in context, key context missing), set confidence LOW (< 0.4). Low confidence falls through to manual confirm — be honest about uncertainty rather than guessing.
+
+Return ONLY JSON matching this schema — no prose before or after, no markdown fences:
+{
+  "functional_fidelity": <number 0-10>,
+  "code_quality":        <number 0-10>,
+  "economy":             <number 0-10>,
+  "notes_md":            <string>,
+  "confidence":          <number 0-1>,
+  "issues": [{"severity": "blocker"|"major"|"minor"|"nit", "file": <path>, "summary": <string>}, ...]
+}
+
+You have a Read tool. Spend reads checking that removed code is unreferenced elsewhere, that new helpers match surrounding style, that the diff's value_summary matches what the diff actually does, and that acceptance criteria you can't verify from the diff alone are actually satisfied in the post-merge file. Do not run tests, do not edit files, do not call the network.`;
+
+function buildPrompt({ task, valueSummary, diff, changedFiles, diffStats, generatedProvenance: prov = null }) {
+  const t = task || {};
+  const desc = (t.description || '(no description)').trim();
+  const title = (t.title || '(no title)').trim();
+  const vs = (valueSummary || '(no value summary)').trim();
+  const files = Array.isArray(changedFiles) ? changedFiles : [];
+  const diffText = (diff || '(empty diff)').trim();
+
+  const lines = [];
+  lines.push(PROMPT_HEADER);
+  lines.push('');
+  lines.push('---');
+  lines.push('## Task');
+  lines.push('');
+  lines.push(`**ID:** ${t.id ?? '(unknown)'}`);
+  lines.push(`**Title:** ${title}`);
+  lines.push(`**Kind:** ${t.kind ?? 'unclassified'}  ·  **Discipline:** ${t.discipline ?? 'unclassified'}`);
+  lines.push(`**Estimated effort:** ${t.est_minutes != null ? `${t.est_minutes} min` : '(not estimated)'}  — use this to judge whether the diff size is proportionate to the work scoped.`);
+  if (t.version_id) lines.push(`**Version:** ${t.version_id}`);
+  lines.push('');
+  lines.push('**Description:**');
+  lines.push('');
+  lines.push(desc);
+  lines.push('');
+  lines.push('---');
+  lines.push('## Builder\'s value summary');
+  lines.push('');
+  lines.push(vs);
+  lines.push('');
+  lines.push('---');
+  lines.push(`## Changed files (${files.length})`);
+  lines.push('');
+  for (const f of files) lines.push(`- ${f}`);
+  if (files.length === 0) lines.push('(no files changed — this is suspicious)');
+  lines.push('');
+  lines.push('You can Read any of these files to see their post-merge state.');
+  lines.push('');
+  lines.push('---');
+  lines.push('## Diff size (for the economy axis)');
+  lines.push('');
+  if (diffStats && typeof diffStats === 'object') {
+    const fc = diffStats.files_changed ?? '?';
+    const la = diffStats.lines_added ?? '?';
+    const lr = diffStats.lines_removed ?? '?';
+    lines.push(`- files changed: ${fc}`);
+    lines.push(`- lines added: ${la}`);
+    lines.push(`- lines removed: ${lr}`);
+    lines.push('');
+    lines.push('Weigh this against the task description, kind, and estimated effort above when scoring economy. A diff much larger than the scoped work warrants — or one padded with speculative abstraction, duplication, or dead code — should score low on economy.');
+  } else {
+    lines.push('(diff stats unavailable — score economy from the diff itself.)');
+  }
+  lines.push('');
+  lines.push('---');
+  lines.push('## Unified diff');
+  lines.push('');
+  lines.push('```diff');
+  lines.push(diffText);
+  lines.push('```');
+  lines.push('', ...(prov ? [generatedProvenance.provenanceSection(prov)].filter(Boolean) : [])); // task 1002795 — the trivial path is where a docs-only ship lands
+  lines.push('Now grade. Default-fail unless your read of the diff and post-merge files turns up no material problems. Output ONLY the JSON object — nothing before or after it.');
+  return lines.join('\n');
+}
+
+// ---------- v3: per-shot validator (same as v2 logic) ----------
+
+// Tries to extract a JSON object from a subagent response. The subagent is
+// instructed to return ONLY JSON, but in practice models sometimes wrap it
+// in markdown fences or add a line of prose. Be tolerant.
+// #79 (#380, completed #493): robust JSON extraction now lives in the shared
+// leaf module so grader.js AND every worker module use ONE implementation.
+// Re-exported here for back-compat (validateAndScore + tests use
+// grader.extractJson).
+const { extractJson } = require('./grader-workers/extract-json');
+
+
+module.exports = {
+  PROMPT_HEADER,
+  buildPrompt,
+  extractJson,
+};