kodelyth-ecc 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.7.0 — The Arena: GOD vs EVIL loop (phase 3) (August 2026)
+
+The two crews now fight. GOD builds, EVIL attacks, verified findings return to GOD as mandatory work, and the loop repeats **until the attacker gives up**.
+
+### Added — `scripts/arena/arena.js` + `/arena`
+
+A **state machine**, not an agent dispatcher — it decides what happens next and grades what comes back, so the entire loop is testable without spending a token. Agent invocation is driven by the AI through `/arena`.
+
+```
+round N:  god_build → evil_hunt → evil_verify → round_close
+                                                     │
+                   converged / out of budget / out of rounds? ──→ report
+```
+
+- **`nextAction(run)`** — the loop's brain. Returns the next step, its briefs, and a token estimate the budget can veto.
+- **Findings carry forward.** Round 1 builds; every later round *fixes what EVIL proved*, with the findings injected into GOD's brief as mandatory items. **Refuted findings are never carried** — a false positive can no longer consume an entire fix round.
+- **Later EVIL rounds know what's already known** and are told to hunt what the last pass missed.
+- **Phase guards** — submitting out of order throws instead of silently corrupting a run.
+- **`affordOrAbort()`** — aborts cleanly *before* an unaffordable step. A readable partial result beats a surprise bill.
+- **Resumable** — a crash mid-loop reloads from disk with phase and spend intact.
+- **`buildReport()`** — markdown report with the trend histogram, per-round detail, still-open findings ranked by real risk, and a refuted section so the same false positive is never re-litigated.
+
+### Added — CLI
+
+```bash
+kodelythecc arena start --task "harden the webhook" --scope src/ --max-rounds 3
+kodelythecc arena next <run-id>          # what the loop wants next (JSON)
+kodelythecc arena report <run-id> --md   # full markdown report
+```
+
+### Verified end-to-end
+
+Simulated a realistic run at true cost (~191k tokens/round):
+
+```
+round 1    3 new  ████████████████████████
+round 2    1 new  ████████
+round 3    0 new  ·
+round 4    0 new  ·
+**Converged** — two consecutive rounds surfaced nothing new.
+```
+
+- Convergence fires on 2 quiet rounds; a fresh finding **restarts** the streak
+- Rounds where GOD left an artifact unproven or a critical unaddressed are flagged **incomplete** in the report
+- A refuting verdict zeroed the finding and kept `openRisk` honest
+- **The budget guard fired for real** — an earlier run at the 400k default aborted at round 3 with a clean partial report, exactly as designed
+- **463 tests, 0 failures** across 33 files (up from 444) — 19 new arena-loop tests
+
+### Honest cost note
+
+~200k tokens per round (GOD ≈ 90k + EVIL ≈ 96k + verification). Defaults are deliberately conservative: **3 rounds, 400k tokens, 45 min**. Use `/god-mode` or `/evil-mode` alone when you don't need the full loop — the arena is for work that must not break.
+
+### Assets
+
+`social/card-arena.svg`; SVG badges → v2.7.0; 8K PNGs re-rendered.
+
 ## 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.

package/VERSION

@@ -1 +1 @@
-2.6.0
+2.7.0

package/bin/kodelyth-ecc.js

@@ -482,7 +482,46 @@ if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
 
     // arena
     const state = require(path.join(ROOT, 'scripts', 'arena', 'state.js'));
+    const arena = require(path.join(ROOT, 'scripts', 'arena', 'arena.js'));
     const sub = rest[0] || 'list';
+
+    if (sub === 'start') {
+      const task = flag('task') || rest.slice(1).find(a => !a.startsWith('--'));
+      if (!task) { process.stderr.write('usage: kodelythecc arena start --task "<goal>" [--scope src/] [--max-rounds 3] [--budget 400000]\n'); process.exit(2); }
+      const limits = {};
+      if (flag('max-rounds')) limits.maxRounds = Number(flag('max-rounds'));
+      if (flag('budget')) limits.tokenBudget = Number(flag('budget'));
+      const run = arena.startArena({
+        task,
+        scope: flag('scope', '.'),
+        flags: rest.filter(a => ['--all', '--license', '--theft', '--jailbreak', '--chaos', '--pre-public', '--pre-launch'].includes(a)),
+        limits,
+      });
+      const first = arena.nextAction(run);
+      if (wantJson) { w(JSON.stringify({ run: state.summarize(run), next: first }, null, 2)); process.exit(0); }
+      w('');
+      w(`\x1b[1mArena started\x1b[0m — ${run.task}`);
+      w(`  run id:   \x1b[36m${run.runId}\x1b[0m`);
+      w(`  scope:    ${run.scope}`);
+      w(`  limits:   ${run.limits.maxRounds} rounds · ${run.limits.tokenBudget.toLocaleString()} tokens · ${Math.round(run.limits.wallClockMs / 60000)} min`);
+      w(`  next:     \x1b[32m${first.action}\x1b[0m (round ${first.round}, ~${((first.estimatedTokens || 0) / 1000).toFixed(0)}k tokens)`);
+      w('');
+      w(`Drive the loop in your AI tool: \x1b[36m/arena ${run.task}\x1b[0m`);
+      w(`Inspect anytime:                kodelythecc arena report ${run.runId}`);
+      w('');
+      process.exit(0);
+    }
+
+    if (sub === 'next') {
+      const runId = rest[1];
+      if (!runId) { process.stderr.write('usage: kodelythecc arena next <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 action = arena.nextAction(run);
+      w(JSON.stringify(action, null, 2));
+      process.exit(0);
+    }
+
     if (sub === 'list') {
       const runs = state.listRuns();
       if (!runs.length) { w('No arena runs yet.'); process.exit(0); }
@@ -502,6 +541,7 @@ if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
       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); }
+      if (rest.includes('--md')) { w(arena.buildReport(run)); process.exit(0); }
       w('');
       w(`\x1b[1mArena report\x1b[0m — ${s.runId}`);
       w(`  task:        ${s.task}`);

package/commands/arena.md

@@ -0,0 +1,101 @@
+---
+description: The Arena — GOD builds, EVIL attacks, repeat until the attacker gives up. The adversarial loop with scored findings, verification, convergence detection, and hard budget stops.
+argument-hint: "<goal> [--scope src/] [--max-rounds 3] [--all]"
+---
+
+# /arena — GOD vs EVIL, until the attacker gives up
+
+The two crews fight over your code. GOD builds and hardens. EVIL attacks and tries to break it. Verified findings go back to GOD. Repeat until **two consecutive rounds surface nothing new** — then you ship, knowing an adversary already tried and failed.
+
+> **This is the expensive one.** ~200k tokens per round (GOD ≈ 90k + EVIL ≈ 96k + verification). Defaults are 3 rounds / 400k tokens, and the budget guard aborts *before* overspending. Use `/god-mode` or `/evil-mode` alone when you don't need the full loop.
+
+## The loop
+
+```
+round N:  GOD builds/fixes  →  EVIL hunts  →  EVIL verifies  →  close round
+                                                                    │
+                          converged? out of budget? out of rounds? ─┤
+                                    no → round N+1                  │
+                                                                   yes → report
+```
+
+**Convergence = the win condition.** Not "zero findings" — findings may remain open and accepted. It means attacking harder stopped yielding anything new.
+
+## Usage
+
+```
+/arena harden the payment webhook
+/arena add rate limiting --scope src/api --max-rounds 2
+/arena prepare this repo for open-source --all
+```
+
+Start and inspect from the terminal:
+```bash
+kodelythecc arena start --task "harden the webhook" --scope src/ --max-rounds 3
+kodelythecc arena next <run-id>          # what the loop wants next (JSON)
+kodelythecc arena report <run-id> --md   # full markdown report
+kodelythecc arena list
+```
+
+## Instructions to the assistant
+
+### 0. Start the run
+```bash
+kodelythecc arena start --task "<goal>" --scope "<path>" [--max-rounds N]
+```
+Capture the **run id**. Every step below is driven by:
+```bash
+kodelythecc arena next <run-id>
+```
+which returns the next action, its briefs, and a token estimate. **Follow it — do not improvise the order.**
+
+### 1. `god_build`
+Run the GOD-mode stages from the action's `stages` array (see `/god-mode`). Round 1 builds; later rounds **fix what EVIL proved** — those findings arrive in the brief as mandatory work items.
+
+Finish by reporting artifacts, each with a `verifyCommand` you **actually ran**.
+
+### 2. `evil_hunt`
+Launch the crew from `briefs` **in parallel** via the Task tool. On round 2+, agents are told what's already known and to hunt what the last pass missed.
+
+### 3. `evil_verify`
+For each target, launch a **fresh** agent with the supplied refute-brief. Its job is to **disprove** the finding. Default to `refuted` when uncertain.
+
+### 4. `round_close`
+Record the round. The state machine decides whether to loop again or stop.
+
+### 5. `report`
+When the action is `report`, print the full markdown:
+```bash
+kodelythecc arena report <run-id> --md
+```
+
+## Rules that keep this honest
+
+- **Never skip verification.** Unverified findings waste GOD's next entire round — that's the expensive failure mode this design exists to prevent.
+- **Never claim a fix you didn't prove.** An artifact counts only when its command exited clean. A round with an unverified artifact is flagged incomplete in the report.
+- **Never invent findings to look thorough.** An empty confirmed list is a good result.
+- **Respect the budget guard.** If it aborts, report the partial result — a readable partial beats a surprise bill.
+- Convergence is the goal, not zero findings. Accepted risk, stated plainly, is a legitimate outcome.
+
+## Reading the report
+
+The trend line is the whole story:
+
+```
+round 1   12 new  ████████████████████████
+round 2    4 new  ████████
+round 3    0 new  ·
+round 4    0 new  ·
+**Converged** — two consecutive rounds surfaced nothing new.
+```
+
+Falling to zero means the attacker ran out of ideas. A flat or rising line means **stop and think** — either the code has deep problems, or EVIL is finding new surface each pass because the scope is too broad.
+
+## When to use which
+
+| Situation | Command |
+|---|---|
+| Build something properly | `/god-mode` |
+| Audit what already exists | `/evil-mode` |
+| Ship something that must not break | `/arena` |
+| Before open-sourcing | `/arena --all` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.6.0",
+  "version": "2.7.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/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,
+};