kodelyth-ecc 2.5.4 → 2.6.0

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.6.0 — GOD mode + EVIL mode v2 (Arena phases 0-2) (August 2026)
+
+The foundation of the **adversarial arena**: two opposed crews that will eventually fight each other until the attacker gives up. Phases 0-2 of 6 — the contract, the adversary, and the builder. The arena loop itself lands in a later release, only once it is verified end-to-end.
+
+### Added — Phase 0: the contract (`scripts/arena/`)
+
+- **`contract.js`** — the shared schema GOD and EVIL exchange. `Finding` (severity × confidence × exploitability → risk), `Artifact`, `RoundVerdict`, stable FNV-1a fingerprints so the same issue dedupes across rounds even when wording drifts, and `hasConverged()`.
+  - **Refuted findings carry zero effective risk** — verification can genuinely zero out a false positive.
+  - Certainty outweighs raw severity: a *confirmed/high/trivial* outranks a *speculative/critical/theoretical*, so noise sinks.
+- **`state.js`** — resumable run state in `~/.kodelythecc/arena/`. Rounds are appended, so a crash or budget abort never loses rounds already paid for.
+  - **Hard stops, not advisory:** max rounds, token budget, wall-clock. `canAffordRound()` refuses *before* spending.
+
+### Added — Phase 1: EVIL mode v2 (`scripts/arena/evil.js`, `/evil-mode`)
+
+The 8 adversarial agents already hunted well; what they lacked was judgment.
+
+- **Scoring** — every finding gets a risk score instead of landing in a flat pile.
+- **Adversarial verification** — each top finding is challenged by a fresh agent told to **REFUTE it**, defaulting to refuted when uncertain. False positives die before they can waste GOD mode's next round.
+- **Loop-until-dry** — later rounds tell each agent what is already known and to hunt what the last pass *missed*.
+- `selectForVerification()` is budget-bounded (default 12) and skips settled or near-zero-risk findings.
+- `/devil-mode` still works — `/evil-mode` is the upgraded entry point.
+
+### Added — Phase 2: GOD mode (`scripts/arena/god.js`, `/god-mode`)
+
+Not "fire nine agents at once" — that is `/project-launch`. A six-stage pipeline with three things the parallel commands lack:
+
+| Stage | Agents |
+|---|---|
+| **Recall** | — (memory lookup; never invents a memory) |
+| **Design** ∥ | `architect` + `code-architect` |
+| **Build** → | `pair-programmer` + `tdd-guide` |
+| **Self-critique** ∥ | `type-design-analyzer` + `api-guardian` + `ux-reviewer` |
+| **Harden** ∥ | `performance-optimizer` + `refactor-cleaner` |
+| **Prove** | — (runs the verification command) |
+
+- **It recalls before it builds.**
+- **Proof gate:** `verifyArtifacts()` marks work verified only when a command actually ran and exited clean — a truthy claim is explicitly not proof.
+- **`roundComplete()` blocks** on any unverified artifact or unaddressed critical/high finding. A refuted finding never blocks.
+
+### Added — CLI
+
+```bash
+kodelythecc god  --task "add rate limiting"    # plan + cost estimate
+kodelythecc evil src/auth --all                # crew + cost estimate
+kodelythecc arena list                         # past runs
+kodelythecc arena report <run-id>              # rounds, trend, open risk
+```
+
+### Verified
+
+- **444 tests, 0 failures** across 32 files (up from 388) — 56 new arena tests
+- Simulated a 4-round run: new-findings trend **[2, 1, 0, 0] → converged**, stop reason *"attacker gave up"*
+- Both CLI surfaces render real plans with real cost estimates
+- Traversal-safe run ids, budget refusal, and convergence-streak reset all covered by tests
+
+### Assets
+
+- `social/card-god.svg` + `social/card-evil.svg`; SVG badges → v2.6.0; 8K PNGs re-rendered.
+
 ## v2.5.4 — Memory: direct capture CLI + aggressive auto-capture (July 2026)
 
 Two memory improvements after an end-to-end verification pass confirmed the pipeline works but only captured when the user said "thanks".

package/VERSION

@@ -1 +1 @@
-2.5.4
+2.6.0

package/bin/kodelyth-ecc.js

@@ -424,6 +424,103 @@ if (args[0] === 'memory') {
   } catch (e) { process.stderr.write(`[memory] ${e.message}\n`); process.exit(1); }
 }
 
+// ── Subcommand: god / evil / arena (the adversarial arena) ──────────────────
+// Usage:
+//   kodelythecc god  --task "<task>" [--json]        plan a GOD-mode build
+//   kodelythecc evil [scope] [--all|--license|...]   plan an EVIL-mode sweep
+//   kodelythecc arena list                           list past arena runs
+//   kodelythecc arena report <run-id>                show a run's report
+if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
+  const mode = args[0];
+  const rest = args.slice(1);
+  const w = (m) => process.stdout.write(m + '\n');
+  const wantJson = rest.includes('--json');
+  function flag(name, dflt) {
+    const i = rest.indexOf('--' + name);
+    return i >= 0 && rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[i + 1] : dflt;
+  }
+  try {
+    if (mode === 'god') {
+      const god = require(path.join(ROOT, 'scripts', 'arena', 'god.js'));
+      const task = flag('task') || rest.find(a => !a.startsWith('--'));
+      if (!task) { process.stderr.write('usage: kodelythecc god --task "<what to build>"\n'); process.exit(2); }
+      const plan = god.planBuild({ task });
+      if (wantJson) { w(JSON.stringify(plan, null, 2)); process.exit(0); }
+      w('');
+      w(`\x1b[1mGOD mode\x1b[0m — ${plan.task}`);
+      w('─'.repeat(60));
+      for (const s of plan.stages) {
+        const agents = s.agents.length ? s.agents.join(', ') : '(no agent — local operation)';
+        w(`\x1b[32m${String(s.id).padEnd(9)}\x1b[0m ${s.label.padEnd(14)} ${s.parallel ? '∥' : '→'} ${agents}`);
+      }
+      w('─'.repeat(60));
+      w(`${plan.stages.length} stages · est. ~${(plan.estimatedTokens / 1000).toFixed(0)}k tokens`);
+      w(`Run it in your AI tool with: \x1b[36m/god-mode ${plan.task}\x1b[0m`);
+      w('');
+      process.exit(0);
+    }
+
+    if (mode === 'evil') {
+      const evil = require(path.join(ROOT, 'scripts', 'arena', 'evil.js'));
+      const scope = rest.find(a => !a.startsWith('--')) || '.';
+      const plan = evil.planSweep({ scope, flags: rest.filter(a => a.startsWith('--')) });
+      if (wantJson) { w(JSON.stringify(plan, null, 2)); process.exit(0); }
+      w('');
+      w(`\x1b[1mEVIL mode\x1b[0m — adversarial sweep of \x1b[33m${scope}\x1b[0m`);
+      w('─'.repeat(60));
+      for (const agent of plan.crew) {
+        w(`\x1b[31m✗\x1b[0m ${agent.padEnd(26)} ${evil.CREW[agent].hunts}`);
+      }
+      w('─'.repeat(60));
+      w(`${plan.crew.length} hunters · est. ~${(plan.estimatedTokens / 1000).toFixed(0)}k tokens`);
+      w('Findings are scored (severity × confidence × exploitability) and');
+      w('adversarially verified — unreproducible findings get refuted.');
+      w(`Run it in your AI tool with: \x1b[36m/evil-mode ${scope}\x1b[0m`);
+      w('');
+      process.exit(0);
+    }
+
+    // arena
+    const state = require(path.join(ROOT, 'scripts', 'arena', 'state.js'));
+    const sub = rest[0] || 'list';
+    if (sub === 'list') {
+      const runs = state.listRuns();
+      if (!runs.length) { w('No arena runs yet.'); process.exit(0); }
+      w('');
+      w(`\x1b[1mArena runs\x1b[0m (${runs.length})`);
+      for (const r of runs.slice(0, 20)) {
+        const icon = r.status === 'converged' ? '\x1b[32m✓\x1b[0m' : r.status === 'running' ? '\x1b[33m•\x1b[0m' : '\x1b[31m✗\x1b[0m';
+        w(`  ${icon} ${r.runId}  ${String(r.rounds).padStart(2)} rounds  risk ${String(r.openRisk).padStart(6)}  ${r.task.slice(0, 40)}`);
+      }
+      w('');
+      process.exit(0);
+    }
+    if (sub === 'report') {
+      const runId = rest[1];
+      if (!runId) { process.stderr.write('usage: kodelythecc arena report <run-id>\n'); process.exit(2); }
+      const run = state.load(runId);
+      if (!run) { process.stderr.write(`no such run: ${runId}\n`); process.exit(1); }
+      const s = state.summarize(run);
+      if (wantJson) { w(JSON.stringify({ summary: s, rounds: run.rounds }, null, 2)); process.exit(0); }
+      w('');
+      w(`\x1b[1mArena report\x1b[0m — ${s.runId}`);
+      w(`  task:        ${s.task}`);
+      w(`  status:      ${s.status}${s.stopReason ? ` (${s.stopReason})` : ''}`);
+      w(`  rounds:      ${s.rounds}`);
+      w(`  new/round:   ${s.trend.join(' → ') || '—'}   ${s.trend.length > 1 && s.trend[s.trend.length - 1] === 0 ? '\x1b[32m(attacker gave up)\x1b[0m' : ''}`);
+      w(`  open issues: ${s.openFindings} (${s.confirmed} confirmed) · open risk ${s.openRisk}`);
+      w(`  tokens:      ${s.tokensSpent.toLocaleString()}`);
+      w('');
+      process.exit(0);
+    }
+    process.stderr.write('unknown arena subcommand. try: list | report <run-id>\n');
+    process.exit(2);
+  } catch (e) {
+    process.stderr.write(`[${mode}] ${e.message}\n`);
+    process.exit(1);
+  }
+}
+
 if (args[0] === 'doctor') {
   const { run, PASS, WARN, FAIL } = require(path.join(ROOT, 'scripts', 'doctor-health.js'));
   const report = run();

package/commands/evil-mode.md

@@ -0,0 +1,106 @@
+---
+description: EVIL mode — adversarial sweep with scored findings, adversarial verification, and loop-until-dry. The upgrade of /devil-mode — unreproducible findings get refuted instead of padding the report.
+argument-hint: "[scope] [--all|--license|--theft|--jailbreak|--chaos|--pre-public|--pre-launch]"
+---
+
+# /evil-mode — Attack Your Own Code
+
+Eight red-team specialists hunt your repository the way an attacker would. Unlike a plain sweep, EVIL mode **grades its own findings** and then **tries to disprove them** — so what reaches you is what survived scrutiny, not everything anyone thought of.
+
+> Findings will be uncomfortable. That is the point. This attacks **your own** codebase so real attackers find nothing left.
+
+## What makes this different from a one-shot scan
+
+| | Plain sweep | EVIL mode |
+|---|---|---|
+| Output | Flat list | Scored: severity × confidence × exploitability |
+| False positives | You triage them | **Adversarially refuted** before you see them |
+| Coverage | One pass | **Loops until two rounds find nothing new** |
+| Handoff | Prose | Structured findings `/god-mode` can consume |
+
+## The crew
+
+**Core (always):** `prompt-injection-hunter` · `supply-chain-auditor` · `secret-hunter` · `backdoor-hunter`
+
+**Opt-in:** `--license` · `--theft` · `--jailbreak` · `--chaos` · `--all`
+
+**Presets:** `--pre-public` (license + theft) · `--pre-launch` (jailbreak + chaos)
+
+## Usage
+
+```
+/evil-mode                      # core 4 on the whole repo
+/evil-mode src/auth             # focus a module
+/evil-mode --all                # all 8 hunters
+/evil-mode --pre-public         # before open-sourcing
+```
+
+Preview crew and cost first:
+```bash
+kodelythecc evil src/auth --all
+```
+
+## Instructions to the assistant
+
+### Stage 1 — Hunt (parallel)
+Launch the selected crew **simultaneously** via the Task tool. Give each agent its scope and tell it:
+
+- `evidence` must **quote the actual offending code**, not describe it.
+- `repro` must be concrete steps or a command.
+- Only claim `confirmed` when you have actually reproduced it.
+- **Do not pad.** Five confirmed findings beat forty guesses.
+
+Each finding comes back as:
+```json
+{ "title", "severity": "critical|high|medium|low|info",
+  "confidence": "confirmed|likely|suspected|speculative",
+  "exploitability": "trivial|moderate|hard|theoretical",
+  "file", "line", "evidence", "repro", "fix" }
+```
+
+### Stage 2 — Verify (the part that matters)
+Take the top findings by risk and, for each, launch a **fresh** agent whose job is to **REFUTE it**:
+
+1. Read the actual code — does the evidence match reality?
+2. Do guards, framework behaviour, or callers already neutralise it?
+3. Try to reproduce it.
+
+Return `confirmed` / `refuted` / `needs_context`. **Default to `refuted` when uncertain.** A finding that cannot be demonstrated is not a finding.
+
+Refuted findings stay in the record (so the same false positive isn't re-litigated) but count as **zero risk**.
+
+### Stage 3 — Loop until dry
+If this is an arena run, sweep again — telling each agent which findings are already known and to hunt what the last pass **missed**. Stop when two consecutive rounds surface nothing new.
+
+### Stage 4 — Report
+
+```
+EVIL MODE — <scope> — round <n>
+  swept:     <agents>
+  found:     <n> · confirmed <n> · refuted <n>
+  open risk: <sum of surviving risk>
+
+CONFIRMED (fix these)
+  [risk] title — file:line
+         repro: <command or steps>
+         fix:   <what to change>
+
+REFUTED (checked, not real)
+  title — why it is not exploitable
+```
+
+Order strictly by risk. Never lead with a `speculative` finding.
+
+## Rules
+
+- **Never invent findings to look thorough.** An empty confirmed list is a valid, good result.
+- **Never report a finding you could not reproduce** without marking it `speculative`.
+- This is for auditing **code you own or are authorised to test**. It is a defensive tool.
+
+## Handoff
+
+```
+/god-mode fix the confirmed findings from the EVIL sweep
+```
+
+GOD mode treats confirmed findings as mandatory work items — each must be fixed or explicitly accepted as risk.

package/commands/god-mode.md

@@ -0,0 +1,85 @@
+---
+description: GOD mode — the constructive crew. Recalls past solutions, designs, builds test-first, self-critiques, hardens, and proves the work with a command that actually runs.
+argument-hint: "<what to build or harden>"
+---
+
+# /god-mode — Build It Properly
+
+Nine specialists in a six-stage pipeline. This is **not** `/project-launch` (which fires everyone at once) — GOD mode is sequential where sequence matters, parallel where it doesn't, and it refuses to call anything done that it hasn't proven.
+
+## The pipeline
+
+| Stage | Agents | What happens |
+|---|---|---|
+| **Recall** | — | Search local memory for prior solutions to this problem |
+| **Design** ∥ | `architect` + `code-architect` | Blueprint: files, interfaces, data flow, build order |
+| **Build** → | `pair-programmer` + `tdd-guide` | Implement test-first; tests must actually run |
+| **Self-critique** ∥ | `type-design-analyzer` + `api-guardian` + `ux-reviewer` | Attack our own work before anyone else can |
+| **Harden** ∥ | `performance-optimizer` + `refactor-cleaner` | Hot spots and dead weight, no behaviour change |
+| **Prove** | — | Run the verification commands |
+
+∥ = parallel · → = sequential
+
+## Usage
+
+```
+/god-mode add rate limiting to the payments API
+/god-mode harden the webhook signature verification
+/god-mode                      # asks what to build
+```
+
+Preview the plan and cost from the terminal first:
+```bash
+kodelythecc god --task "add rate limiting to the payments API"
+```
+
+## Instructions to the assistant
+
+Run the stages **in order**. Do not skip Recall and do not skip Prove.
+
+### Stage 1 — Recall (do this first, always)
+Search local memory for prior work on this problem:
+- Use the `recall_memory` MCP tool, or `kodelythecc memory recall "<task>"`.
+- For each relevant hit, state: the past problem, the approach that worked, and whether it applies here.
+- **If nothing relevant exists, say so plainly.** Never invent a memory.
+
+### Stage 2 — Design (parallel)
+Launch `architect` and `code-architect` together via the Task tool. Produce one concrete blueprint: exact files, interfaces, data flow, build order. No hand-waving.
+
+### Stage 3 — Build (sequential)
+Launch `pair-programmer` and `tdd-guide`. Write the test first, watch it fail, implement, watch it pass. Report which files you created or changed.
+
+### Stage 4 — Self-critique (parallel)
+Launch `type-design-analyzer`, `api-guardian`, and `ux-reviewer` together. Be genuinely adversarial about your own output — it is far cheaper to find a problem here than to let `/evil-mode` find it later.
+
+### Stage 5 — Harden (parallel)
+Launch `performance-optimizer` and `refactor-cleaner`. Improve without changing behaviour. Tests must stay green.
+
+### Stage 6 — Prove (mandatory)
+**Run the verification command.** A test suite, a build, a benchmark — something that exits 0.
+
+- If it passes: report the command and its output.
+- If it fails: **the round is not complete.** Fix it and re-run. Do not report success.
+- "Should work" / "looks correct" is a failure of this stage.
+
+## The output contract
+
+End every GOD-mode run with:
+
+```
+GOD MODE — <task>
+  files:    <what you created or changed>
+  verified: <the command you ran> → <pass/fail + evidence>
+  memory:   <what you recalled, or "no prior art">
+  open:     <anything you deliberately did not do, and why>
+```
+
+## Handoff
+
+When the work touches security, auth, payments, user input, or dependencies, follow with:
+
+```
+/evil-mode <the files you changed>
+```
+
+That is the adversarial half — it will try to break exactly what you just built.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.5.4",
+  "version": "2.6.0",
   "description": "Production-grade AI coding toolkit — 70 agents (incl. devil-mode adversarial crew), 194 skills, 97 commands, parallel multi-agent commands, semantic intent routing, self-learning memory, and a built-in MCP server (16 tools / 6 prompts / 377 resources) that bridges to Claude Desktop, LangGraph, AutoGen, CrewAI, and OpenAI Agents SDK. Works with Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, RooCode, Aider, Kimi, and Gemini CLI.",
   "author": "Kodelyth <github.com/sifxprime>",
   "license": "MIT",

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,
+};

package/scripts/arena/god.js

@@ -0,0 +1,208 @@
+// scripts/arena/god.js
+// GOD mode — the constructive half of the arena.
+//
+// This is deliberately NOT "fire nine agents at once" — /project-launch already
+// does that. GOD mode is a pipeline with three properties the parallel commands
+// do not have:
+//
+//   1. It RECALLS before it builds       — past solutions inform the design
+//   2. It must emit VERIFIABLE artifacts — a claim is not a result; a passing
+//                                          command is
+//   3. It SELF-CRITIQUES before shipping — it attacks its own work before EVIL
+//                                          gets the chance
+//
+// In arena mode it additionally consumes EVIL's verified findings and must
+// address them before the round can close.
+
+'use strict';
+
+const { makeArtifact } = require('./contract');
+
+// ── The pipeline ─────────────────────────────────────────────────────────────
+// Stages run in order. Each names the specialists it draws on; the orchestrator
+// dispatches them (in parallel where the stage allows it).
+
+const STAGES = [
+  {
+    id: 'recall',
+    label: 'Recall',
+    parallel: false,
+    agents: [],                       // no agent — this is a memory lookup
+    goal: 'Find what we already know about this problem before designing anything new.',
+  },
+  {
+    id: 'design',
+    label: 'Design',
+    parallel: true,
+    agents: ['architect', 'code-architect'],
+    goal: 'Produce a concrete blueprint: files, interfaces, data flow, build order.',
+  },
+  {
+    id: 'build',
+    label: 'Build',
+    parallel: false,
+    agents: ['pair-programmer', 'tdd-guide'],
+    goal: 'Implement the blueprint test-first. Tests must actually run and pass.',
+  },
+  {
+    id: 'critique',
+    label: 'Self-critique',
+    parallel: true,
+    agents: ['type-design-analyzer', 'api-guardian', 'ux-reviewer'],
+    goal: 'Attack our own work: weak types, breaking contracts, unusable flows.',
+  },
+  {
+    id: 'harden',
+    label: 'Harden',
+    parallel: true,
+    agents: ['performance-optimizer', 'refactor-cleaner'],
+    goal: 'Remove hot spots and dead weight without changing behaviour.',
+  },
+  {
+    id: 'prove',
+    label: 'Prove',
+    parallel: false,
+    agents: [],                       // no agent — this runs commands
+    goal: 'Run the verification commands. Nothing ships unproven.',
+  },
+];
+
+function stage(id) {
+  return STAGES.find(s => s.id === id) || null;
+}
+
+// ── Briefs ───────────────────────────────────────────────────────────────────
+
+function recallBrief({ task }) {
+  return [
+    `Before building anything, search local memory for prior work related to:`,
+    `"${task}"`,
+    '',
+    'Use the memory store (BM25 recall). For each relevant hit, report:',
+    '- what the past problem was',
+    '- what approach actually worked',
+    '- whether it applies here, or why this case differs',
+    '',
+    'If nothing relevant exists, say so plainly and move on. Do not invent a memory.',
+  ].join('\n');
+}
+
+function stageBrief({ stageId, task, blueprint = null, findings = [], round = 1 }) {
+  const s = stage(stageId);
+  if (!s) throw new Error(`god: unknown stage "${stageId}"`);
+
+  const lines = [
+    `GOD mode — stage: ${s.label} (round ${round}).`,
+    `Task: ${task}`,
+    `Goal of this stage: ${s.goal}`,
+  ];
+
+  if (blueprint) {
+    lines.push('', 'Blueprint from the design stage:', blueprint);
+  }
+
+  // Arena mode: EVIL's verified findings are non-negotiable work items.
+  if (findings.length) {
+    lines.push(
+      '',
+      `EVIL mode found ${findings.length} verified issue(s) in the last round. These are NOT suggestions — each must be fixed or explicitly justified as accepted risk:`,
+      ...findings.map((f, i) =>
+        `  ${i + 1}. [${f.severity}/${f.confidence}] ${f.title}` +
+        `${f.file ? ` (${f.file}:${f.line ?? '?'})` : ''}` +
+        `${f.repro ? `\n     repro: ${String(f.repro).split('\n')[0].slice(0, 160)}` : ''}`),
+    );
+  }
+
+  lines.push(
+    '',
+    'Output contract:',
+    '- State exactly which files you changed or created.',
+    '- Give a `verifyCommand` that PROVES the work (a test run, a build, a benchmark).',
+    '- Do not claim success you have not observed. "Should work" is a failure of this stage.',
+  );
+
+  if (stageId === 'critique') {
+    lines.push(
+      '',
+      'Be genuinely adversarial about our own output. It is cheaper to find it here than to let EVIL find it next round.',
+    );
+  }
+
+  return lines.join('\n');
+}
+
+// ── Verification ─────────────────────────────────────────────────────────────
+// The heart of GOD mode: an artifact only counts as verified when a command
+// actually ran and exited clean. `runner` is injected so this stays testable
+// and so callers control what is allowed to execute.
+
+function verifyArtifacts(artifacts = [], runner) {
+  if (typeof runner !== 'function') {
+    throw new Error('god: verifyArtifacts requires a runner(command) -> {ok, output}');
+  }
+  return artifacts.map(a => {
+    const art = makeArtifact(a);
+    if (!art.verifyCommand) {
+      return { ...art, verified: false, verifyResult: 'no verify command supplied' };
+    }
+    let result;
+    try {
+      result = runner(art.verifyCommand);
+    } catch (err) {
+      return { ...art, verified: false, verifyResult: `runner threw: ${err.message}` };
+    }
+    const ok = !!(result && result.ok);
+    return {
+      ...art,
+      verified: ok,
+      verifyResult: ok
+        ? 'passed'
+        : `failed: ${String((result && result.output) || 'no output').slice(0, 300)}`,
+    };
+  });
+}
+
+// A round only closes when every artifact proved itself AND every high-risk
+// finding was addressed. This is what stops "I fixed it" from being enough.
+function roundComplete({ artifacts = [], findings = [], addressedIds = [] } = {}) {
+  const unverified = artifacts.filter(a => !a.verified);
+  const addressed = new Set(addressedIds);
+  const mustFix = findings.filter(f =>
+    f.verdict !== 'refuted' && (f.severity === 'critical' || f.severity === 'high'));
+  const outstanding = mustFix.filter(f => !addressed.has(f.id));
+
+  return {
+    complete: unverified.length === 0 && outstanding.length === 0,
+    unverifiedArtifacts: unverified.map(a => a.summary || a.kind),
+    outstandingFindings: outstanding.map(f => f.title),
+  };
+}
+
+// ── Plan ─────────────────────────────────────────────────────────────────────
+
+function planBuild({ task, findings = [], round = 1, skipStages = [] } = {}) {
+  if (!task || !String(task).trim()) throw new Error('god: task is required');
+  const active = STAGES.filter(s => !skipStages.includes(s.id));
+  return {
+    round,
+    task,
+    stages: active.map(s => ({
+      id: s.id,
+      label: s.label,
+      parallel: s.parallel,
+      agents: s.agents,
+      brief: s.id === 'recall'
+        ? recallBrief({ task })
+        : stageBrief({ stageId: s.id, task, findings, round }),
+    })),
+    // Only agent stages cost tokens; recall and prove are local operations.
+    estimatedTokens: active.reduce((n, s) => n + s.agents.length * 10000, 0),
+  };
+}
+
+module.exports = {
+  STAGES, stage,
+  recallBrief, stageBrief,
+  verifyArtifacts, roundComplete,
+  planBuild,
+};

package/scripts/arena/state.js

@@ -0,0 +1,195 @@
+// scripts/arena/state.js
+// Persistent, resumable state for an arena run.
+//
+// An arena run is expensive (multiple agent crews × multiple rounds), so it must
+// survive a crash, a Ctrl-C, or a budget abort without losing the rounds already
+// paid for. Every round is appended to a run file under ~/.kodelythecc/arena/.
+//
+// Also owns the hard stops: max rounds, token budget, wall-clock. These are not
+// advisory — the arena aborts cleanly and reports partial results.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { makeRoundVerdict, hasConverged, dedupe } = require('./contract');
+
+const DIR = process.env.KODELYTH_ARENA_DIR
+  || path.join(os.homedir(), '.kodelythecc', 'arena');
+
+const DEFAULTS = {
+  maxRounds: 3,          // deliberately low — see docs/arena.md on cost
+  tokenBudget: 400000,
+  wallClockMs: 45 * 60 * 1000,
+  quietRoundsRequired: 2,
+};
+
+function ensureDir() {
+  fs.mkdirSync(DIR, { recursive: true });
+}
+
+function runPath(runId) {
+  // runId is generated internally; still refuse traversal in case a caller
+  // passes one in from a CLI flag.
+  const safe = String(runId).replace(/[^A-Za-z0-9._-]/g, '');
+  return path.join(DIR, `${safe}.json`);
+}
+
+function newRunId(now = Date.now(), rand = Math.random) {
+  const stamp = new Date(now).toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const suffix = Math.floor(rand() * 0xffff).toString(16).padStart(4, '0');
+  return `arena-${stamp}-${suffix}`;
+}
+
+// ── Lifecycle ────────────────────────────────────────────────────────────────
+
+function createRun({ task, limits = {}, runId = null, now = Date.now() } = {}) {
+  if (!task || !String(task).trim()) throw new Error('arena: task is required');
+  const run = {
+    runId: runId || newRunId(now),
+    task: String(task).slice(0, 1000),
+    startedAt: new Date(now).toISOString(),
+    limits: { ...DEFAULTS, ...limits },
+    spent: { tokens: 0, rounds: 0, ms: 0 },
+    rounds: [],
+    seenFindingIds: [],
+    status: 'running',          // running | converged | exhausted | aborted
+    stopReason: null,
+  };
+  save(run);
+  return run;
+}
+
+function save(run) {
+  ensureDir();
+  fs.writeFileSync(runPath(run.runId), JSON.stringify(run, null, 2));
+  return run;
+}
+
+function load(runId) {
+  const p = runPath(runId);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+function listRuns() {
+  if (!fs.existsSync(DIR)) return [];
+  return fs.readdirSync(DIR)
+    .filter(f => f.endsWith('.json'))
+    .map(f => {
+      try {
+        const r = JSON.parse(fs.readFileSync(path.join(DIR, f), 'utf8'));
+        return {
+          runId: r.runId,
+          task: r.task,
+          status: r.status,
+          rounds: r.rounds?.length || 0,
+          openRisk: r.rounds?.length ? r.rounds[r.rounds.length - 1].openRisk : 0,
+          startedAt: r.startedAt,
+        };
+      } catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)));
+}
+
+// ── Recording a round ────────────────────────────────────────────────────────
+
+function recordRound(run, { findings = [], artifacts = [], tokensSpent = 0, elapsedMs = 0 } = {}) {
+  const roundNo = run.rounds.length + 1;
+  const seen = new Set(run.seenFindingIds);
+  const deduped = dedupe(findings);
+  const newIds = deduped.filter(f => !seen.has(f.id)).map(f => f.id);
+
+  const verdict = makeRoundVerdict({
+    round: roundNo,
+    findings: deduped,
+    newFindingIds: newIds,
+    artifacts,
+  });
+
+  run.rounds.push(verdict);
+  run.seenFindingIds = [...new Set([...run.seenFindingIds, ...deduped.map(f => f.id)])];
+  run.spent.rounds = run.rounds.length;
+  run.spent.tokens += Math.max(0, Number(tokensSpent) || 0);
+  run.spent.ms += Math.max(0, Number(elapsedMs) || 0);
+
+  const stop = shouldStop(run);
+  run.status = stop.stop ? stop.status : 'running';
+  run.stopReason = stop.stop ? stop.reason : null;
+
+  save(run);
+  return verdict;
+}
+
+// ── Hard stops + convergence ─────────────────────────────────────────────────
+
+function shouldStop(run) {
+  const { limits, spent } = run;
+
+  if (hasConverged(run.rounds, limits.quietRoundsRequired)) {
+    return {
+      stop: true,
+      status: 'converged',
+      reason: `no new findings in ${limits.quietRoundsRequired} consecutive rounds — attacker gave up`,
+    };
+  }
+  if (spent.rounds >= limits.maxRounds) {
+    return { stop: true, status: 'exhausted', reason: `max rounds reached (${limits.maxRounds})` };
+  }
+  if (spent.tokens >= limits.tokenBudget) {
+    return {
+      stop: true,
+      status: 'aborted',
+      reason: `token budget exhausted (${spent.tokens.toLocaleString()} / ${limits.tokenBudget.toLocaleString()})`,
+    };
+  }
+  if (spent.ms >= limits.wallClockMs) {
+    return {
+      stop: true,
+      status: 'aborted',
+      reason: `wall-clock limit reached (${Math.round(spent.ms / 60000)} min)`,
+    };
+  }
+  return { stop: false };
+}
+
+// Budget check BEFORE spending on another round, so we never blow past the cap.
+function canAffordRound(run, estimatedTokens) {
+  const remaining = run.limits.tokenBudget - run.spent.tokens;
+  return {
+    ok: remaining >= estimatedTokens,
+    remaining,
+    estimated: estimatedTokens,
+  };
+}
+
+// ── Summary for reports / dashboard ──────────────────────────────────────────
+
+function summarize(run) {
+  const last = run.rounds[run.rounds.length - 1] || null;
+  const open = last ? last.findings.filter(f => f.verdict !== 'refuted') : [];
+  return {
+    runId: run.runId,
+    task: run.task,
+    status: run.status,
+    stopReason: run.stopReason,
+    rounds: run.rounds.length,
+    tokensSpent: run.spent.tokens,
+    openFindings: open.length,
+    openRisk: last ? last.openRisk : 0,
+    confirmed: open.filter(f => f.verdict === 'confirmed').length,
+    // Round-over-round new-finding counts — the curve that should trend to zero.
+    trend: run.rounds.map(r => r.counts.new),
+    artifacts: run.rounds.reduce((n, r) => n + (r.artifacts?.length || 0), 0),
+  };
+}
+
+module.exports = {
+  DIR, DEFAULTS,
+  newRunId, createRun, save, load, listRuns,
+  recordRound, shouldStop, canAffordRound, summarize,
+};