@bongos/core 1.17.0

package/modules/grading/grader-workers/quality.js

@@ -0,0 +1,198 @@
+// MAS Phase 2.0 (#410) — Quality worker.
+//
+// Specialty: code quality + economy (advisory). Preserves the cq + economy
+// axes from the v3 generalist grader while Narc takes over functional_fidelity.
+// Phase 2.1 / 2.2 will further decompose this into Hacker (security) and
+// Efficiency Monger (cost / latency).
+//
+// Worker contract is the same shape as Narc — see grader-workers/index.js
+// for the registry and the unified WorkerResult shape.
+
+// THRESHOLD + LOW_CONF come from the shared rubric module (task 1090, C6).
+const { THRESHOLD, LOW_CONF } = require('./rubric');
+
+// SR-15 / G1 (#995): scrub + fence all builder-controlled inputs. The shared
+// scaffold (worker-prompt) owns fenceBlock/scrubUntrusted/NOFOLLOW_PREAMBLE.
+const { buildWorkerPrompt, LLM_PROJECT } = require('./worker-prompt');
+const { failResult, parseCommon, finalizeVerdict } = require('./worker-verdict');
+
+const KIND = 'quality';
+const NAME = 'Quality';
+const SPECIALTY = 'code quality (idiom, readability, tests, invariants) + economy (advisory)';
+
+const PROMPT_HEADER = `You are the **Quality** specialist — an adversarial subagent for the ${LLM_PROJECT} project. You exist to catch the second most common form of shipped-but-broken work: code that implements the right behavior but is hostile to maintenance, breaks codebase invariants, leaves dead code, or over-writes.
+
+You do NOT score whether the description was implemented — that's the Narc's job. Your verdict is about code quality and economy.
+
+**The default verdict is FAIL.** You PASS only after a careful read of the diff and (via your Read tool) the relevant post-merge files turns up no material problems.
+
+## What you check
+
+You begin by hunting for these specific failure modes. When you find one, CITE the diff line or quote the offending code:
+
+- TODOs, FIXMEs, "for now", "temporary" or "stub" comments left in shipped code.
+- Hardcoded shortcuts assuming one builder, one user, one project root, one tenant. Look for literal "lars", "lars589", absolute /Users paths, hardcoded ports, hardcoded IDs that should be lookups.
+- 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.
+- Broken invariants: methodology rules in CLAUDE.md (the "every change is backed by a claimed GDS task" rule, no-hardcoded-Archon-identity per V3.R12, server-enforced permissions per ADR 0016), cross-verified Python/JS lookups, ground-vs-object cell split per ADR 0012.
+- Missing tests for new logic: any non-trivial new function, route handler, branch, or aggregation that ships without a covering test.
+- Non-idiomatic style: helpers that don't match surrounding patterns, copy-paste that should have been extracted (or — opposite — premature abstraction that should have been left inline).
+- Reads/writes outside the declared touches[]: if the diff edits files the task didn't claim, call it out.
+
+## Two scores
+
+1. **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. (Threshold for passing the gate.)
+   - Below 6 = broken style, dead code, broken invariants, missing tests where warranted.
+
+2. **economy** (0-10, ADVISORY) — is the change as small and simple as the task warrants?
+   - 10 = minimal and focused — exactly what was needed, no fat.
+   - 6 = a bit more than necessary; a reviewer would suggest trimming.
+   - Below 6 = bloated, speculative abstraction, duplicated logic.
+   - Note: a legitimately large feature can still score high here if every line earns its place. Economy is about WASTE, not size.
+
+## Confidence (0-1)
+
+If the diff is too large to comfortably fit in context, the description is too vague to anchor against, or you can't reach key files via Read — set confidence LOW (< 0.4). The downstream system treats low confidence as fall-through to manual confirm.
+
+## Sanity checks
+
+- A PASS with no \`issues\` entries is suspicious. If you found nothing material wrong, briefly say WHY in notes_md: which files you Read, what could-have-gone-wrong didn't.
+- A FAIL with no \`issues\` is invalid — name at least one concrete problem.
+- A score below 6 must be accompanied by at least one major-or-blocker issue.
+- Don't moralize about style preferences if the surrounding code follows the same pattern — that's idiomatic for THIS codebase, even if it's unconventional elsewhere.
+
+## Return ONLY JSON
+
+No prose, no markdown fences:
+
+\`\`\`
+{
+  "code_quality": <number 0-10>,
+  "economy": <number 0-10>,
+  "confidence": <number 0-1>,
+  "issues": [
+    { "severity": "blocker"|"major"|"minor"|"nit", "file": "<path>", "summary": "<one line, quotes diff line>" }
+  ],
+  "notes_md": "<short markdown — what you checked and what stood out>"
+}
+\`\`\`
+
+You have a Read tool. Spend reads checking that removed code is unreferenced elsewhere, that new helpers match surrounding style, and that invariants the diff touches are still preserved in the post-merge state. Do not run tests, do not edit files, do not call the network.`;
+
+function buildPrompt({ task, valueSummary, diff, changedFiles, diffStats }) {
+  const t = task || {};
+
+  // Quality owns a diff-size section (the economy axis) before the diff.
+  const diffSizeLines = ['---', '## Diff size (for the economy axis)', ''];
+  if (diffStats && typeof diffStats === 'object') {
+    const fc = diffStats.files_changed ?? '?';
+    const la = diffStats.lines_added ?? '?';
+    const lr = diffStats.lines_removed ?? '?';
+    diffSizeLines.push(`- files changed: ${fc}`);
+    diffSizeLines.push(`- lines added: ${la}`);
+    diffSizeLines.push(`- lines removed: ${lr}`);
+    diffSizeLines.push('');
+    diffSizeLines.push('Weigh this against the task\'s scope (est_minutes, kind) when scoring economy.');
+  } else {
+    diffSizeLines.push('(diff stats unavailable — score economy from the diff itself.)');
+  }
+  diffSizeLines.push('');
+
+  return buildWorkerPrompt({
+    header: PROMPT_HEADER,
+    task: t,
+    valueSummary,
+    diff,
+    changedFiles,
+    taskHeader: '## Task (for context — the Narc judges completion; you judge quality)',
+    descLabel: '**Description:**',
+    emptyFilesText: '(no files changed — this is suspicious)',
+    readFilesHint: 'You can Read any of these files to see their post-merge state.',
+    finalInstruction: 'Now judge the code. Default-fail unless your read turns up no material problems. Output ONLY the JSON object.',
+    afterKindLines: [`**Estimated effort:** ${t.est_minutes != null ? `${t.est_minutes} min` : '(not estimated)'}  — use this to judge whether the diff size is proportionate.`],
+    beforeDiffLines: diffSizeLines,
+  });
+}
+
+// #79 (#493): delegate to the shared robust extractor so the v4 panel path
+// gets the same parse-resilience (whole-string -> fenced -> balanced-brace) as
+// grader.js, instead of the brittle first-{-to-last-} copy that flaked.
+const { extractJson } = require('./extract-json');
+
+// Quality's per-worker verdict. Inputs/outputs match Narc's contract.
+//   - 'fail' if any blocker issue, cq < threshold, parse/schema/subprocess error
+//   - 'concerns' if low confidence OR economy < threshold (advisory nudge) OR
+//                any major issue with cq right at threshold
+//   - 'pass' otherwise
+function computeVerdict(parsed, meta = {}) {
+  if (meta.subprocess_error) {
+    return failResult({ notesMd: `Quality: subagent error (${meta.subprocess_error}).`, error: meta.subprocess_error });
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return failResult({ notesMd: 'Quality: could not parse subagent output as JSON.', error: 'parse_error' });
+  }
+
+  const cq = Number(parsed.code_quality);
+  const economyRaw = Number(parsed.economy);
+  const economy = Number.isFinite(economyRaw) && economyRaw >= 0 && economyRaw <= 10
+    ? economyRaw
+    : null;
+  const { conf, issues, notesFromSubagent } = parseCommon(parsed);
+
+  if (!Number.isFinite(cq) || cq < 0 || cq > 10) {
+    return failResult({ issues, notesMd: `Quality: code_quality was non-numeric or out of range (got ${parsed.code_quality}).`, error: 'schema_error' });
+  }
+
+  const r1 = (n) => Math.round(n * 10) / 10;
+  const cqR = r1(cq);
+  const economyR = economy != null ? r1(economy) : null;
+
+  const blockerCount = issues.filter((i) => i.severity === 'blocker').length;
+  const majorCount = issues.filter((i) => i.severity === 'major').length;
+  const lowConfidence = conf != null && conf < LOW_CONF;
+  const lowEconomy = economyR != null && economyR < THRESHOLD;
+
+  let verdict;
+  let notesPrefix;
+  if (blockerCount > 0 || cqR < THRESHOLD) {
+    verdict = 'fail';
+    notesPrefix = `Quality — FAIL (cq=${cqR}/10`
+      + (blockerCount > 0 ? `, ${blockerCount} blocker issue${blockerCount === 1 ? '' : 's'}` : '')
+      + `)`;
+  } else if (lowConfidence || lowEconomy || majorCount > 0) {
+    verdict = 'concerns';
+    notesPrefix = `Quality — CONCERNS (cq=${cqR}/10`
+      + (economyR != null ? `, econ=${economyR}/10` : '')
+      + (lowConfidence ? `, low confidence ${conf}` : '')
+      + (majorCount > 0 ? `, ${majorCount} major issue${majorCount === 1 ? '' : 's'}` : '')
+      + `)`;
+  } else {
+    verdict = 'pass';
+    notesPrefix = `Quality — PASS (cq=${cqR}/10`
+      + (economyR != null ? `, econ=${economyR}/10` : '')
+      + `, conf=${conf ?? '?'})`;
+  }
+
+  return finalizeVerdict({
+    verdict,
+    scores: {
+      code_quality: cqR,
+      economy: economyR,
+    },
+    issues,
+    notesPrefix,
+    notesFromSubagent,
+    confidence: conf,
+  });
+}
+
+module.exports = {
+  KIND,
+  NAME,
+  SPECIALTY,
+  PROMPT_HEADER,
+  buildPrompt,
+  extractJson,
+  computeVerdict,
+};

package/modules/grading/grader-workers/rubric.js

@@ -0,0 +1,20 @@
+// src/bongos/grader-workers/rubric.js
+//
+// Single source for the v4 rubric + thresholds (task 1090, C6). The four worker
+// modules (narc / quality / hacker / efficiency) each loaded grader-rubric.json
+// with a byte-identical block; this centralizes that load so a bump to the
+// rubric drives every per-worker verdict without code edits.
+//
+// Read DIRECTLY from the JSON file (not via grader.js) to avoid a circular
+// require: grader.js -> grader-workers/index.js -> the workers -> here.
+const path = require('node:path');
+const fs = require('node:fs');
+
+const RUBRIC = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'grader-rubric.json'), 'utf8')
+);
+const V4 = RUBRIC.v4;
+const THRESHOLD = V4.threshold;
+const LOW_CONF = V4.low_confidence_threshold;
+
+module.exports = { RUBRIC, V4, THRESHOLD, LOW_CONF };

package/modules/grading/grader-workers/worker-prompt.js

@@ -0,0 +1,89 @@
+// src/bongos/grader-workers/worker-prompt.js
+//
+// Shared prompt scaffold for the four grader workers (task 1090, C6). All four
+// build the SAME fenced structure — NOFOLLOW_PREAMBLE emitted once, the title
+// run through scrubUntrusted, and the four untrusted artifacts wrapped in
+// fenceBlock (TASK DESCRIPTION, BUILDER VALUE SUMMARY, CHANGED FILE LIST,
+// UNIFIED DIFF). Centralizing it keeps the SR-15/#995 prompt-injection fencing
+// in ONE auditable place. Per-worker text (header, section labels, the final
+// instruction) is passed in; a worker that needs an extra block — Quality's /
+// Efficiency's diff-size section, or Hacker's deterministic-findings section —
+// builds those lines itself (with its OWN extra scrub where required, e.g.
+// Hacker's safe()) and passes them via `afterKindLines` (inserted right after
+// the Kind/Discipline line) or `beforeDiffLines` (inserted right before the
+// Unified diff). Behavior-neutral: produces the identical string the inlined
+// builders produced for the same inputs.
+const { fenceBlock, scrubUntrusted, NOFOLLOW_PREAMBLE } = require('./fence');
+
+// The instance's project name for the worker identity lines, so a non-OTB Cloud
+// Bongos instance is graded against ITS OWN project instead of a hardcoded "Off
+// the Boats" (ADR 0062 §3/§5; the branding contract's llmProjectName field).
+// Resolved through the published doorway — the ONE core surface a module may
+// require (the modules/grading boundary rule) — never a deep core require.
+// Centralized here, the shared scaffold, so all four workers read one source.
+// Resolved once at module load (the brand is a per-process singleton); falls back
+// to a neutral phrase if branding fails to resolve so a config error never crashes
+// the gate.
+const LLM_PROJECT = (() => {
+  try { return require('../../../src/module-api').branding().llmProjectName || 'this project'; }
+  catch { return 'this project'; }
+})();
+
+function buildWorkerPrompt({
+  header, task, valueSummary, diff, changedFiles,
+  taskHeader, descLabel, emptyFilesText, readFilesHint, finalInstruction,
+  afterKindLines = [], beforeDiffLines = [],
+}) {
+  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(header);
+  lines.push('');
+  lines.push('---');
+  lines.push(NOFOLLOW_PREAMBLE);
+  lines.push('');
+  lines.push('---');
+  lines.push(taskHeader);
+  lines.push('');
+  lines.push(`**ID:** ${t.id ?? '(unknown)'}`);
+  lines.push(`**Title:** ${scrubUntrusted(title)}`);
+  lines.push(`**Kind:** ${t.kind ?? 'unclassified'}  ·  **Discipline:** ${t.discipline ?? 'unclassified'}`);
+  lines.push(...afterKindLines);
+  if (t.version_id) lines.push(`**Version:** ${t.version_id}`);
+  lines.push('');
+  lines.push(descLabel);
+  lines.push('');
+  lines.push(...fenceBlock('TASK DESCRIPTION', desc));
+  lines.push('');
+  lines.push('---');
+  lines.push('## Builder\'s value summary');
+  lines.push('');
+  lines.push(...fenceBlock('BUILDER VALUE SUMMARY', vs));
+  lines.push('');
+  lines.push('---');
+  lines.push(`## Changed files (${files.length})`);
+  lines.push('');
+  if (files.length === 0) {
+    lines.push(emptyFilesText);
+  } else {
+    lines.push(...fenceBlock('CHANGED FILE LIST', files.map((f) => `- ${f}`).join('\n')));
+  }
+  lines.push('');
+  lines.push(readFilesHint);
+  lines.push('');
+  lines.push(...beforeDiffLines);
+  lines.push('---');
+  lines.push('## Unified diff');
+  lines.push('');
+  lines.push(...fenceBlock('UNIFIED DIFF', diffText));
+  lines.push('');
+  lines.push(finalInstruction);
+  return lines.join('\n');
+}
+
+module.exports = { buildWorkerPrompt, LLM_PROJECT };

package/modules/grading/grader-workers/worker-verdict.js

@@ -0,0 +1,50 @@
+// src/bongos/grader-workers/worker-verdict.js
+//
+// Shared computeVerdict boilerplate for the four grader workers (task 1090, C6).
+// The error short-circuits, the common parsed-field extraction, and the success
+// return assembly are byte-identical across narc / quality / hacker / efficiency
+// (only the worker NAME + score field differ). This module owns ONLY that
+// surrounding boilerplate — each worker keeps its SCORING and FAIL/CONCERNS
+// TRIGGER logic inline, so no per-worker security trigger is ever flattened
+// (the audit's explicit warning). Behavior-neutral: the objects produced here
+// are identical (same keys, same order, same values) to the inlined copies.
+
+// The { verdict:'fail', scores:{}, confidence:0, ... } shape every error
+// short-circuit returns. `issues` defaults to [] (the subprocess_error and
+// parse_error paths) and is the parsed issues array on the schema_error path
+// (all four workers forward the parsed issues there, not []).
+function failResult({ notesMd, error, issues = [] }) {
+  return { verdict: 'fail', scores: {}, issues, notes_md: notesMd, confidence: 0, error };
+}
+
+// The three identical extractions every worker does after the parse guard:
+// confidence (null-tolerant), the bounded issues array, and the subagent notes.
+function parseCommon(parsed) {
+  const conf = parsed.confidence == null
+    ? null
+    : Number.isFinite(Number(parsed.confidence)) ? Number(parsed.confidence) : null;
+  const issues = Array.isArray(parsed.issues)
+    ? parsed.issues.filter((i) => i && typeof i === 'object').slice(0, 50)
+    : [];
+  const notesFromSubagent = typeof parsed.notes_md === 'string' ? parsed.notes_md : '';
+  return { conf, issues, notesFromSubagent };
+}
+
+// The success-return assembly: `${notesPrefix}\n${notes}`.trim() + the
+// per-worker scores / issues / extra keys + confidence + error:null. `extra`
+// carries the worker-specific key (narc ac_checklist, hacker surfaces_checked,
+// efficiency expensive_patterns_checked) at the same position (after issues,
+// before notes_md) the inlined returns used.
+function finalizeVerdict({ verdict, scores, issues, extra = {}, notesPrefix, notesFromSubagent, confidence }) {
+  return {
+    verdict,
+    scores,
+    issues,
+    ...extra,
+    notes_md: `${notesPrefix}\n${notesFromSubagent.trim()}`.trim(),
+    confidence,
+    error: null,
+  };
+}
+
+module.exports = { failResult, parseCommon, finalizeVerdict };