kodelyth-ecc 2.5.4 → 2.7.0

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