kodelyth-ecc 2.5.4 → 2.7.0

package/scripts/arena/arena.js

@@ -0,0 +1,280 @@
+// scripts/arena/arena.js
+// The Arena — GOD builds, EVIL attacks, repeat until the attacker gives up.
+//
+// This is a STATE MACHINE, not an agent dispatcher. It decides what should
+// happen next and grades what comes back; the actual agent invocations are made
+// by the AI driving `/arena`. Keeping dispatch out of here is what makes the
+// loop testable without spending a single token.
+//
+//   round N:  god_build  ->  evil_hunt  ->  evil_verify  ->  round_close
+//                                                              |
+//                            converged / out of budget? --------+
+//                                   |                    no -> round N+1
+//                                  yes
+//                                   v
+//                                 report
+
+'use strict';
+
+const god = require('./god');
+const evil = require('./evil');
+const state = require('./state');
+const { dedupe, effectiveRisk, VERDICT } = require('./contract');
+
+// ── Phases within a round ────────────────────────────────────────────────────
+
+const PHASE = {
+  GOD_BUILD: 'god_build',
+  EVIL_HUNT: 'evil_hunt',
+  EVIL_VERIFY: 'evil_verify',
+  ROUND_CLOSE: 'round_close',
+  REPORT: 'report',
+};
+
+// ── Starting a run ───────────────────────────────────────────────────────────
+
+function startArena({ task, scope = '.', flags = [], limits = {} } = {}) {
+  const run = state.createRun({ task, limits });
+  run.scope = scope;
+  run.flags = flags;
+  run.phase = PHASE.GOD_BUILD;
+  run.pending = { artifacts: [], findings: [], addressedIds: [] };
+  state.save(run);
+  return run;
+}
+
+// ── The state machine ────────────────────────────────────────────────────────
+// Given a run, what happens next? Returns an actionable step with the brief the
+// AI should execute, plus a cost estimate the budget can veto.
+
+function nextAction(run) {
+  if (!run) throw new Error('arena: no run');
+
+  // A finished run has nothing left but its report.
+  if (run.status !== 'running') {
+    return { action: PHASE.REPORT, reason: run.stopReason, run: state.summarize(run) };
+  }
+
+  const round = run.rounds.length + 1;
+  const carried = carriedFindings(run);
+
+  switch (run.phase) {
+    case PHASE.GOD_BUILD: {
+      const plan = god.planBuild({ task: run.task, findings: carried, round });
+      return {
+        action: PHASE.GOD_BUILD,
+        round,
+        stages: plan.stages,
+        // Round 1 builds; later rounds are fixing what EVIL proved.
+        intent: round === 1 ? 'build' : 'fix',
+        carriedFindings: carried.length,
+        estimatedTokens: plan.estimatedTokens,
+      };
+    }
+
+    case PHASE.EVIL_HUNT: {
+      const plan = evil.planSweep({
+        scope: run.scope,
+        flags: run.flags,
+        round,
+        knownFindingIds: run.seenFindingIds,
+      });
+      return {
+        action: PHASE.EVIL_HUNT,
+        round,
+        crew: plan.crew,
+        briefs: plan.briefs,
+        estimatedTokens: plan.estimatedTokens,
+      };
+    }
+
+    case PHASE.EVIL_VERIFY: {
+      const targets = evil.selectForVerification(run.pending.findings);
+      return {
+        action: PHASE.EVIL_VERIFY,
+        round,
+        targets: targets.map(f => ({ id: f.id, title: f.title, brief: evil.verifyBrief(f) })),
+        // Verification is cheap per finding but must stay bounded.
+        estimatedTokens: targets.length * 3000,
+      };
+    }
+
+    case PHASE.ROUND_CLOSE:
+    default:
+      return { action: PHASE.ROUND_CLOSE, round };
+  }
+}
+
+// Findings GOD still has to answer for: open, real, high-signal, worst first.
+function carriedFindings(run) {
+  const last = run.rounds[run.rounds.length - 1];
+  if (!last) return [];
+  return evil.actionable(last.findings).slice(0, 10);
+}
+
+// ── Recording each phase ─────────────────────────────────────────────────────
+
+function submitGodWork(run, { artifacts = [], addressedIds = [], tokensSpent = 0, elapsedMs = 0 } = {}) {
+  requirePhase(run, PHASE.GOD_BUILD);
+  run.pending.artifacts = artifacts;
+  run.pending.addressedIds = addressedIds;
+  run.spent.tokens += Math.max(0, Number(tokensSpent) || 0);
+  run.spent.ms += Math.max(0, Number(elapsedMs) || 0);
+  run.phase = PHASE.EVIL_HUNT;
+  state.save(run);
+  return run;
+}
+
+function submitEvilHunt(run, { findings = [], tokensSpent = 0, elapsedMs = 0 } = {}) {
+  requirePhase(run, PHASE.EVIL_HUNT);
+  run.pending.findings = dedupe(findings);
+  run.spent.tokens += Math.max(0, Number(tokensSpent) || 0);
+  run.spent.ms += Math.max(0, Number(elapsedMs) || 0);
+  run.phase = PHASE.EVIL_VERIFY;
+  state.save(run);
+  return run;
+}
+
+function submitVerdicts(run, { verdicts = {}, tokensSpent = 0, elapsedMs = 0 } = {}) {
+  requirePhase(run, PHASE.EVIL_VERIFY);
+  run.pending.findings = evil.applyVerdicts(run.pending.findings, verdicts);
+  run.spent.tokens += Math.max(0, Number(tokensSpent) || 0);
+  run.spent.ms += Math.max(0, Number(elapsedMs) || 0);
+  run.phase = PHASE.ROUND_CLOSE;
+  state.save(run);
+  return run;
+}
+
+// Close the round: grade GOD's work, record the verdict, decide whether to
+// run another round. state.recordRound() owns convergence + hard stops.
+function closeRound(run) {
+  requirePhase(run, PHASE.ROUND_CLOSE);
+
+  const completion = god.roundComplete({
+    artifacts: run.pending.artifacts,
+    findings: run.pending.findings,
+    addressedIds: run.pending.addressedIds,
+  });
+
+  const verdict = state.recordRound(run, {
+    findings: run.pending.findings,
+    artifacts: run.pending.artifacts,
+    tokensSpent: 0,   // already accrued per-phase; do not double count
+    elapsedMs: 0,
+  });
+
+  // Attach whether GOD actually finished its side of the round.
+  verdict.godComplete = completion.complete;
+  verdict.unverifiedArtifacts = completion.unverifiedArtifacts;
+  verdict.outstandingFindings = completion.outstandingFindings;
+  run.rounds[run.rounds.length - 1] = verdict;
+
+  run.pending = { artifacts: [], findings: [], addressedIds: [] };
+  run.phase = run.status === 'running' ? PHASE.GOD_BUILD : PHASE.REPORT;
+  state.save(run);
+  return verdict;
+}
+
+function requirePhase(run, expected) {
+  if (run.phase !== expected) {
+    throw new Error(`arena: expected phase "${expected}" but run is in "${run.phase}"`);
+  }
+}
+
+// ── Budget guard ─────────────────────────────────────────────────────────────
+// Called before dispatching an action. The arena aborts cleanly rather than
+// overspending — a partial result you can read beats a surprise bill.
+
+function affordOrAbort(run, action) {
+  const est = action.estimatedTokens || 0;
+  const check = state.canAffordRound(run, est);
+  if (check.ok) return { ok: true, ...check };
+  run.status = 'aborted';
+  run.stopReason = `budget guard: next step needs ~${est.toLocaleString()} tokens, only ${check.remaining.toLocaleString()} left`;
+  run.phase = PHASE.REPORT;
+  state.save(run);
+  return { ok: false, ...check };
+}
+
+// ── Report ───────────────────────────────────────────────────────────────────
+
+function buildReport(run) {
+  const s = state.summarize(run);
+  const lines = [];
+
+  lines.push(`# Arena report — ${s.task}`, '');
+  lines.push(`- **Run:** \`${s.runId}\``);
+  lines.push(`- **Status:** ${s.status}${s.stopReason ? ` — ${s.stopReason}` : ''}`);
+  lines.push(`- **Rounds:** ${s.rounds}`);
+  lines.push(`- **Tokens:** ${s.tokensSpent.toLocaleString()}`);
+  lines.push('');
+
+  // The curve that matters: new findings per round should fall to zero.
+  lines.push('## Did the attacker give up?', '');
+  if (s.trend.length) {
+    const max = Math.max(...s.trend, 1);
+    for (let i = 0; i < s.trend.length; i++) {
+      const n = s.trend[i];
+      const bar = '█'.repeat(Math.round((n / max) * 24)) || '·';
+      lines.push(`round ${i + 1}  ${String(n).padStart(3)} new  ${bar}`);
+    }
+    lines.push('');
+    lines.push(s.status === 'converged'
+      ? '**Converged** — two consecutive rounds surfaced nothing new.'
+      : `**Not converged** (${s.stopReason || 'still running'}). Remaining risk is unproven, not absent.`);
+  } else {
+    lines.push('_No rounds completed._');
+  }
+  lines.push('');
+
+  // Per-round detail
+  lines.push('## Rounds', '');
+  for (const r of run.rounds) {
+    const verified = (r.artifacts || []).filter(a => a.verified).length;
+    lines.push(`### Round ${r.round}`);
+    lines.push(`- GOD: ${(r.artifacts || []).length} artifact(s), ${verified} verified` +
+      (r.godComplete === false ? ' — **round incomplete**' : ''));
+    if (r.unverifiedArtifacts?.length) {
+      lines.push(`  - unverified: ${r.unverifiedArtifacts.join(', ')}`);
+    }
+    if (r.outstandingFindings?.length) {
+      lines.push(`  - not addressed: ${r.outstandingFindings.join(', ')}`);
+    }
+    lines.push(`- EVIL: ${r.counts.total} finding(s) — ${r.counts.new} new, ${r.counts.confirmed} confirmed, ${r.counts.refuted} refuted`);
+    lines.push(`- Open risk after round: ${r.openRisk}`);
+    lines.push('');
+  }
+
+  // What is still standing
+  const last = run.rounds[run.rounds.length - 1];
+  const open = last ? evil.actionable(last.findings, { minRisk: 0 }) : [];
+  lines.push('## Still open', '');
+  if (!open.length) {
+    lines.push('_Nothing open. Every finding was either fixed or refuted._');
+  } else {
+    for (const f of open) {
+      lines.push(`- **[${effectiveRisk(f)}] ${f.title}** — ${f.severity}/${f.confidence}` +
+        (f.file ? ` · \`${f.file}:${f.line ?? '?'}\`` : ''));
+      if (f.repro) lines.push(`  - repro: ${String(f.repro).split('\n')[0].slice(0, 160)}`);
+      if (f.fix) lines.push(`  - fix: ${String(f.fix).split('\n')[0].slice(0, 160)}`);
+    }
+  }
+  lines.push('');
+
+  // Refuted — kept visible so the same false positive isn't re-litigated.
+  const refuted = last ? last.findings.filter(f => f.verdict === VERDICT.REFUTED) : [];
+  if (refuted.length) {
+    lines.push('## Refuted (checked, not real)', '');
+    for (const f of refuted) lines.push(`- ~~${f.title}~~`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  PHASE,
+  startArena, nextAction, carriedFindings,
+  submitGodWork, submitEvilHunt, submitVerdicts, closeRound,
+  affordOrAbort, buildReport,
+};

package/scripts/arena/contract.js

@@ -0,0 +1,169 @@
+// scripts/arena/contract.js
+// The shared data contract between GOD mode (builds) and EVIL mode (attacks).
+//
+// Without one schema both crews agree on, they cannot exchange results:
+// EVIL produces Findings, GOD consumes them and produces Artifacts, and the
+// Arena scores both to decide whether to run another round.
+//
+// Pure data + validation. Zero dependencies, no I/O.
+
+'use strict';
+
+// ── Severity / confidence scales ─────────────────────────────────────────────
+// Severity is what it costs if real. Confidence is how sure we are it IS real.
+// Exploitability is how hard it is to actually trigger. Risk multiplies all three
+// so a "critical but almost certainly a false positive" ranks below a
+// "high, confirmed, trivially exploitable".
+
+const SEVERITY = { critical: 10, high: 7, medium: 4, low: 2, info: 1 };
+const CONFIDENCE = { confirmed: 1.0, likely: 0.7, suspected: 0.4, speculative: 0.15 };
+const EXPLOITABILITY = { trivial: 1.0, moderate: 0.7, hard: 0.4, theoretical: 0.2 };
+
+const VERDICT = {
+  CONFIRMED: 'confirmed',       // verification reproduced it
+  REFUTED: 'refuted',           // verification proved it is a false positive
+  UNVERIFIED: 'unverified',     // not yet challenged
+  NEEDS_CONTEXT: 'needs_context', // can't tell without runtime/secrets we don't have
+};
+
+// ── Finding ──────────────────────────────────────────────────────────────────
+// One thing EVIL mode believes is wrong. `repro` is what makes a finding
+// actionable rather than an opinion — GOD mode cannot fix what it cannot reproduce.
+
+function makeFinding(input = {}) {
+  const f = {
+    id: input.id || null,          // stable hash, assigned by dedupe
+    agent: input.agent || 'unknown',
+    title: String(input.title || '').slice(0, 200),
+    severity: SEVERITY[input.severity] ? input.severity : 'medium',
+    confidence: CONFIDENCE[input.confidence] ? input.confidence : 'suspected',
+    exploitability: EXPLOITABILITY[input.exploitability] ? input.exploitability : 'moderate',
+    file: input.file || null,
+    line: Number.isInteger(input.line) ? input.line : null,
+    evidence: String(input.evidence || '').slice(0, 2000),
+    repro: input.repro ? String(input.repro).slice(0, 2000) : null,
+    fix: input.fix ? String(input.fix).slice(0, 2000) : null,
+    verdict: VERDICT[String(input.verdict || '').toUpperCase()] || input.verdict || VERDICT.UNVERIFIED,
+    round: Number.isInteger(input.round) ? input.round : 0,
+  };
+  f.id = f.id || fingerprint(f);
+  f.risk = riskScore(f);
+  return f;
+}
+
+// Stable identity: same issue in the same place is the same finding across
+// rounds, even if the wording of the title drifts between agents.
+function fingerprint(f) {
+  const basis = [
+    (f.file || 'nofile').toLowerCase(),
+    f.line == null ? 'noline' : String(f.line),
+    normalizeTitle(f.title),
+  ].join('::');
+  // FNV-1a — deterministic, dependency-free, good enough for dedupe keys.
+  let h = 0x811c9dc5;
+  for (let i = 0; i < basis.length; i++) {
+    h ^= basis.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+function normalizeTitle(title) {
+  return String(title || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9 ]+/g, ' ')
+    .replace(/\b(a|an|the|is|are|in|on|of|to|for|with|at|by)\b/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 80);
+}
+
+// risk = severity × confidence × exploitability  → 0..10
+function riskScore(f) {
+  const s = SEVERITY[f.severity] || SEVERITY.medium;
+  const c = CONFIDENCE[f.confidence] || CONFIDENCE.suspected;
+  const e = EXPLOITABILITY[f.exploitability] || EXPLOITABILITY.moderate;
+  return Math.round(s * c * e * 100) / 100;
+}
+
+// Refuted findings carry no risk — that is the whole point of verification.
+function effectiveRisk(f) {
+  return f.verdict === VERDICT.REFUTED ? 0 : riskScore(f);
+}
+
+// ── Dedupe / diff across rounds ──────────────────────────────────────────────
+
+function dedupe(findings = []) {
+  const byId = new Map();
+  for (const raw of findings) {
+    const f = raw && raw.id && raw.risk != null ? raw : makeFinding(raw || {});
+    const prev = byId.get(f.id);
+    // Keep the strongest claim when two agents report the same thing.
+    if (!prev || effectiveRisk(f) > effectiveRisk(prev)) byId.set(f.id, f);
+  }
+  return [...byId.values()].sort((a, b) => effectiveRisk(b) - effectiveRisk(a));
+}
+
+// What EVIL found this round that it had never found before.
+function newFindings(current = [], seenIds = []) {
+  const seen = new Set(seenIds);
+  return dedupe(current).filter(f => !seen.has(f.id));
+}
+
+// ── Artifact (what GOD produces) ─────────────────────────────────────────────
+// GOD must emit something checkable. `verified` is only true when a command
+// actually ran and passed — claims alone never count.
+
+function makeArtifact(input = {}) {
+  return {
+    kind: ['code', 'test', 'doc', 'config', 'benchmark'].includes(input.kind) ? input.kind : 'code',
+    files: Array.isArray(input.files) ? input.files.slice(0, 50) : [],
+    summary: String(input.summary || '').slice(0, 1000),
+    verifyCommand: input.verifyCommand ? String(input.verifyCommand).slice(0, 300) : null,
+    verified: input.verified === true,
+    round: Number.isInteger(input.round) ? input.round : 0,
+  };
+}
+
+// ── Round verdict ────────────────────────────────────────────────────────────
+
+function makeRoundVerdict(input = {}) {
+  const findings = dedupe(input.findings || []);
+  const fresh = Array.isArray(input.newFindingIds) ? input.newFindingIds : [];
+  const open = findings.filter(f => f.verdict !== VERDICT.REFUTED);
+  const confirmed = findings.filter(f => f.verdict === VERDICT.CONFIRMED);
+  return {
+    round: Number.isInteger(input.round) ? input.round : 0,
+    findings,
+    newFindingIds: fresh,
+    counts: {
+      total: findings.length,
+      open: open.length,
+      confirmed: confirmed.length,
+      refuted: findings.length - open.length,
+      new: fresh.length,
+    },
+    // Total unmitigated risk still standing after verification.
+    openRisk: Math.round(open.reduce((sum, f) => sum + effectiveRisk(f), 0) * 100) / 100,
+    artifacts: (input.artifacts || []).map(makeArtifact),
+  };
+}
+
+// ── Convergence ──────────────────────────────────────────────────────────────
+// The arena stops when the attacker gives up: N consecutive rounds where EVIL
+// found nothing genuinely new. Not "zero findings" — findings may remain open
+// and accepted; what matters is that attacking harder stops yielding anything.
+
+function hasConverged(roundVerdicts = [], quietRoundsRequired = 2) {
+  if (roundVerdicts.length < quietRoundsRequired) return false;
+  return roundVerdicts
+    .slice(-quietRoundsRequired)
+    .every(r => (r.counts?.new || 0) === 0);
+}
+
+module.exports = {
+  SEVERITY, CONFIDENCE, EXPLOITABILITY, VERDICT,
+  makeFinding, fingerprint, riskScore, effectiveRisk,
+  dedupe, newFindings,
+  makeArtifact, makeRoundVerdict, hasConverged,
+};

package/scripts/arena/evil.js

@@ -0,0 +1,175 @@
+// scripts/arena/evil.js
+// EVIL mode — the adversarial half of the arena.
+//
+// The 8 devil-mode agents already hunt well (real ripgrep/jq detection commands).
+// What they lacked was judgment: everything came back as an undifferentiated pile
+// with no way to tell a confirmed exploit from a hunch.
+//
+// This module adds the three missing pieces:
+//   1. SCORING        — severity x confidence x exploitability, so noise sinks
+//   2. VERIFICATION   — each finding gets challenged: prove it, or it is refuted
+//   3. LOOP-UNTIL-DRY — keep sweeping until two rounds turn up nothing new
+//
+// It does not call an LLM itself. It builds the agent briefs the orchestrator
+// dispatches, and it grades what comes back. That keeps this file testable.
+
+'use strict';
+
+const { makeFinding, dedupe, VERDICT, effectiveRisk } = require('./contract');
+
+// ── The crew ─────────────────────────────────────────────────────────────────
+// `core` fires on every sweep. The rest are opt-in via flags, because each one
+// costs a full agent invocation and not every task needs a license audit.
+
+const CREW = {
+  'prompt-injection-hunter': { core: true,  hunts: 'jailbreaks, indirect injection, system-prompt leaks, tool-call hijacking' },
+  'supply-chain-auditor':    { core: true,  hunts: 'typosquats, malicious install scripts, lockfile drift, unsigned packages' },
+  'secret-hunter':           { core: true,  hunts: 'live credentials, git-history leaks, encoded keys, client-bundled env vars' },
+  'backdoor-hunter':         { core: true,  hunts: 'obfuscated payloads, network beacons, time bombs, eval/exec abuse' },
+  'license-violation-finder':{ core: false, flag: '--license',   hunts: 'GPL contamination, missing attribution, copyleft risk' },
+  'code-stealer-detector':   { core: false, flag: '--theft',     hunts: 'copy-paste provenance, leaked private code, AI-gen origin' },
+  'jailbreak-tester':        { core: false, flag: '--jailbreak', hunts: 'live AI-feature red-team, refusal bypass, overrefusal' },
+  'chaos-engineer':          { core: false, flag: '--chaos',     hunts: 'fault injection, resource exhaustion, hidden assumptions' },
+};
+
+const PRESETS = {
+  default:       ['--core'],
+  '--all':       Object.keys(CREW),
+  '--pre-public':['--core', '--license', '--theft'],
+  '--pre-launch':['--core', '--jailbreak', '--chaos'],
+};
+
+function selectCrew(flags = []) {
+  const set = new Set(Object.entries(CREW).filter(([, m]) => m.core).map(([n]) => n));
+  if (flags.includes('--all')) return Object.keys(CREW);
+  for (const [name, meta] of Object.entries(CREW)) {
+    if (meta.flag && flags.includes(meta.flag)) set.add(name);
+  }
+  for (const preset of ['--pre-public', '--pre-launch']) {
+    if (flags.includes(preset)) {
+      for (const f of PRESETS[preset]) {
+        if (f === '--core') continue;
+        const hit = Object.entries(CREW).find(([, m]) => m.flag === f);
+        if (hit) set.add(hit[0]);
+      }
+    }
+  }
+  return [...set];
+}
+
+// ── Stage 1: hunt briefs ─────────────────────────────────────────────────────
+// Each agent is told to report in the Finding contract, and — critically — that
+// a finding without a reproduction is worth less than no finding at all.
+
+function huntBrief({ agent, scope, round, knownFindingIds = [] }) {
+  const meta = CREW[agent] || { hunts: 'issues' };
+  return [
+    `You are ${agent}. Hunt: ${meta.hunts}.`,
+    `Scope: ${scope || 'the whole repository'}.`,
+    `Round ${round}.`,
+    knownFindingIds.length
+      ? `Already-reported findings (${knownFindingIds.length}) are known — do NOT re-report them. Hunt for what a previous sweep MISSED. Go deeper: different files, different attack classes, indirect paths.`
+      : `First sweep — cover your full detection surface.`,
+    '',
+    'Report every finding as JSON matching this shape:',
+    '{ "title", "severity": critical|high|medium|low|info, "confidence": confirmed|likely|suspected|speculative,',
+    '  "exploitability": trivial|moderate|hard|theoretical, "file", "line", "evidence", "repro", "fix" }',
+    '',
+    'Rules that decide whether your finding survives review:',
+    '- `evidence` must quote the actual offending code, not describe it.',
+    '- `repro` must be concrete steps or a command. A finding you cannot reproduce is `speculative` at best.',
+    '- Do not pad. Five confirmed findings beat forty guesses — unverifiable findings get refuted and count against you.',
+    '- Only claim `confirmed` when you have actually reproduced it.',
+  ].join('\n');
+}
+
+// ── Stage 2: verification briefs ─────────────────────────────────────────────
+// The adversarial-verification trick: the verifier is told to REFUTE, not to
+// confirm. Default-to-refuted kills the false positives that otherwise waste
+// GOD mode's entire next round.
+
+function verifyBrief(finding) {
+  return [
+    `Adversarially verify this finding. Your job is to REFUTE it.`,
+    '',
+    `Title: ${finding.title}`,
+    `Claimed severity: ${finding.severity} (${finding.confidence}, ${finding.exploitability})`,
+    `Location: ${finding.file || 'unknown'}:${finding.line ?? '?'}`,
+    `Evidence: ${finding.evidence || '(none given)'}`,
+    `Claimed repro: ${finding.repro || '(none given)'}`,
+    '',
+    'Do this:',
+    '1. Read the actual code at that location. Does the quoted evidence match reality?',
+    '2. Check whether guards, framework behaviour, or callers already neutralise it.',
+    '3. Try to reproduce it. If you cannot, say so plainly.',
+    '',
+    'Return JSON: { "verdict": "confirmed"|"refuted"|"needs_context", "why": "...", "repro": "..."|null }',
+    '',
+    'Default to "refuted" when uncertain. A finding that cannot be demonstrated is not a finding.',
+    'Use "needs_context" only when verification genuinely requires runtime access or secrets you do not have.',
+  ].join('\n');
+}
+
+// ── Stage 3: grade the returns ───────────────────────────────────────────────
+
+function normalizeFindings(rawList = [], { agent, round }) {
+  const out = [];
+  for (const raw of rawList) {
+    if (!raw || !raw.title) continue;
+    out.push(makeFinding({ ...raw, agent, round }));
+  }
+  return out;
+}
+
+// Apply verification verdicts back onto the findings. A refuted finding stays in
+// the record (so the same false positive is not re-litigated next round) but its
+// effective risk drops to zero.
+function applyVerdicts(findings = [], verdicts = {}) {
+  return findings.map(f => {
+    const v = verdicts[f.id];
+    if (!v) return f;
+    const next = { ...f, verdict: v.verdict || f.verdict };
+    if (v.repro && !next.repro) next.repro = String(v.repro).slice(0, 2000);
+    if (v.why) next.evidence = `${next.evidence}\n[verification] ${v.why}`.slice(0, 2000);
+    // Confirming a finding raises certainty; refuting zeroes it out via effectiveRisk.
+    if (next.verdict === VERDICT.CONFIRMED) next.confidence = 'confirmed';
+    return makeFinding(next);
+  });
+}
+
+// Which findings are worth spending a verification pass on. Verifying an
+// already-confirmed or clearly-trivial item is wasted tokens.
+function selectForVerification(findings = [], { max = 12, minRisk = 1.0 } = {}) {
+  return dedupe(findings)
+    .filter(f => f.verdict === VERDICT.UNVERIFIED && f.risk >= minRisk)
+    .slice(0, max);
+}
+
+// What GOD mode actually has to fix: open, verified-or-plausible, worst first.
+function actionable(findings = [], { minRisk = 2.0 } = {}) {
+  return dedupe(findings)
+    .filter(f => f.verdict !== VERDICT.REFUTED)
+    .filter(f => effectiveRisk(f) >= minRisk)
+    .sort((a, b) => effectiveRisk(b) - effectiveRisk(a));
+}
+
+// ── Sweep plan ───────────────────────────────────────────────────────────────
+// The orchestrator asks for a plan, dispatches the agents, and feeds results back.
+
+function planSweep({ scope, flags = [], round = 1, knownFindingIds = [] } = {}) {
+  const crew = selectCrew(flags);
+  return {
+    round,
+    crew,
+    briefs: crew.map(agent => ({ agent, brief: huntBrief({ agent, scope, round, knownFindingIds }) })),
+    estimatedTokens: crew.length * 12000, // rough: one agent sweep ≈ 12k
+  };
+}
+
+module.exports = {
+  CREW, PRESETS,
+  selectCrew, planSweep,
+  huntBrief, verifyBrief,
+  normalizeFindings, applyVerdicts,
+  selectForVerification, actionable,
+};