kodelyth-ecc 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.9.0 — Compound learning: the arena now remembers (phase 4) (August 2026)
+
+A finished arena run used to be knowledge thrown away. Every new run started from
+zero and EVIL re-derived the same bug classes forever. Phase 4 closes the loop.
+
+```
+arena run  ──▶  confirmed + refuted findings  ──▶  memories
+     ▲                                                │
+     └────────  prior-knowledge brief  ◀──────────────┘
+```
+
+### Added — `scripts/arena/learn.js`
+
+Pure functions, no I/O — the callers own the disk and the confirmation prompt, so
+the learning logic is testable without writing to a real memory store.
+
+- **Confirmed findings become memories** carrying the fix and the repro that proved
+  it, tagged by bug class, file, language, and scope.
+- **Refuted findings become memories too** — the more valuable half. Without them
+  the next run re-investigates the same non-bug and burns a real verification pass
+  proving the same negative.
+- **Unverified findings are deliberately skipped.** Storing a question as knowledge
+  would launder a guess into a fact, and future runs would recall it as settled.
+- **Bug classification** — a small, reviewable keyword map (not a classifier) that
+  groups findings well enough to see a class recurring across runs.
+
+### Added — the return path
+
+`arena start` now recalls arena-sourced memories for the scope and injects them
+into every round-1 EVIL brief, split into *"confirmed here before, verify these
+stayed fixed"* and *"already refuted, do not re-report without new evidence."*
+The run reports how many memories it recalled, because silent magic is
+untrustworthy. `--fresh` skips it.
+
+### Added — `arena learn` and guard proposals
+
+```bash
+kodelythecc arena learn <run-id>            # show what would be remembered
+kodelythecc arena learn <run-id> --commit   # store it
+```
+
+Nothing is written without `--commit`. Memory that writes itself silently is
+memory you cannot trust.
+
+When one bug **class** is confirmed repeatedly, `--commit` also files an
+`arena-guard` proposal into evolve. One symlink bug is an incident; two in the
+same file is a process gap — and the proposal says so, recommending a shared
+path-safety helper rather than patching the third one later. Proposal ids are
+deterministic, so re-running analysis never spawns duplicates.
+
+### Fixed — three bugs in the classifier, found by running it on real data
+
+- A bare `permission` matched *"widens permission thresholds"*, filing a semantics
+  bug under file modes.
+- `/\bvalidat/` could not match inside *"unvalidated"* — there is no word boundary
+  after `un`.
+- The injection class keyed on the word *"injection"*, so a finding phrased as a
+  missing trust boundary fell through to uncategorized.
+
+**516 tests passing**, up from 493.
+
 ## v2.8.0 — The Arena's first real run: 12 bugs found and fixed in `terse` (August 2026)
 
 The arena was pointed at `scripts/terse` — the markdown compressor that ships with

package/CLAUDE.md

@@ -26,7 +26,7 @@ scripts/     → Node.js utilities: MCP server, dashboard, swarm, replay, router
 bundles/     → 3 power bundles (indie-hacker, red-team, enterprise)
 actions/     → GitHub Action (CI/CD integration for PR review)
 docs/        → Feature docs (mcp.md, dashboard.md, swarm.md, replay.md, evolve.md, supply-chain.md)
-tests/       → 373 passing tests across 25 test files
+tests/       → 516 passing tests across 27 test files
 ```
 
 ## Running Tests

package/VERSION

@@ -1 +1 @@
-2.8.0
+2.9.0

package/bin/kodelyth-ecc.js

@@ -429,6 +429,7 @@ if (args[0] === 'memory') {
 //   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 learn <run-id> [--commit]      remember what the run proved
 //   kodelythecc arena report <run-id>                show a run's report
 if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
   const mode = args[0];
@@ -491,11 +492,27 @@ if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
       const limits = {};
       if (flag('max-rounds')) limits.maxRounds = Number(flag('max-rounds'));
       if (flag('budget')) limits.tokenBudget = Number(flag('budget'));
+      // Compound learning: pull what past runs proved about this scope and hand
+      // it to EVIL, so round 1 opens where the last run closed. --fresh skips it.
+      const scopeArg = flag('scope', '.');
+      let priorKnowledge = '';
+      let recalledCount = 0;
+      if (!rest.includes('--fresh')) {
+        try {
+          const learn = require(path.join(ROOT, 'scripts', 'arena', 'learn.js'));
+          const memStore = require(path.join(ROOT, 'scripts', 'memory', 'store.js'));
+          const hits = memStore.recall(`arena ${scopeArg} ${task}`, { limit: 20 })
+            .filter(m => (m.source || '') === 'arena');
+          recalledCount = hits.length;
+          priorKnowledge = learn.priorKnowledgeBrief(hits);
+        } catch { /* memory is optional — a missing store must never block a run */ }
+      }
       const run = arena.startArena({
         task,
-        scope: flag('scope', '.'),
+        scope: scopeArg,
         flags: rest.filter(a => ['--all', '--license', '--theft', '--jailbreak', '--chaos', '--pre-public', '--pre-launch'].includes(a)),
         limits,
+        priorKnowledge,
       });
       const first = arena.nextAction(run);
       if (wantJson) { w(JSON.stringify({ run: state.summarize(run), next: first }, null, 2)); process.exit(0); }
@@ -506,6 +523,10 @@ if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
       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('');
+      if (recalledCount) {
+        w(`  recalled: \x1b[36m${recalledCount}\x1b[0m memor${recalledCount === 1 ? 'y' : 'ies'} from past runs on this scope — EVIL starts informed`);
+      }
+      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('');
@@ -534,6 +555,71 @@ if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
       w('');
       process.exit(0);
     }
+    if (sub === 'learn') {
+      const runId = rest[1];
+      if (!runId) { process.stderr.write('usage: kodelythecc arena learn <run-id> [--commit]\n'); process.exit(2); }
+      const run = state.load(runId);
+      if (!run) { process.stderr.write(`no such run: ${runId}\n`); process.exit(1); }
+      const learn = require(path.join(ROOT, 'scripts', 'arena', 'learn.js'));
+      const memStore = require(path.join(ROOT, 'scripts', 'memory', 'store.js'));
+
+      const drafts = learn.runToMemories(run, { project: process.cwd() });
+      if (wantJson) { w(JSON.stringify({ drafts: drafts.map(d => d.memory) }, null, 2)); process.exit(0); }
+
+      if (!drafts.length) {
+        w('');
+        w('Nothing to learn from this run — no confirmed or refuted findings.');
+        w('Unverified findings are deliberately skipped: storing a question as');
+        w('knowledge would launder a guess into a fact.');
+        w('');
+        process.exit(0);
+      }
+
+      w('');
+      w(`\x1b[1mArena learn\x1b[0m — ${runId}`);
+      w('─'.repeat(64));
+      for (const d of drafts) {
+        const kind = d.finding.verdict === 'confirmed' ? '\x1b[32mconfirmed\x1b[0m' : '\x1b[33mrefuted  \x1b[0m';
+        w(`${kind} ${d.memory.problem}`);
+      }
+      w('─'.repeat(64));
+
+      const clusters = learn.recurringClasses(drafts.map(d => d.memory), { minRuns: 2 });
+      if (clusters.length) {
+        w('');
+        w('\x1b[1mRecurring classes\x1b[0m — one is an incident, several is a process gap:');
+        for (const c of clusters) w(`  ${String(c.count).padStart(2)}x  ${c.class}`);
+      }
+
+      // Capture is explicit. Showing the drafts and requiring --commit is the
+      // whole point: memory that writes itself silently is memory you cannot trust.
+      if (!rest.includes('--commit')) {
+        w('');
+        w(`${drafts.length} draft(s). Nothing was written.`);
+        w(`Store them with: \x1b[36mkodelythecc arena learn ${runId} --commit\x1b[0m`);
+        w('');
+        process.exit(0);
+      }
+
+      let stored = 0;
+      for (const d of drafts) {
+        try { memStore.capture(d.memory); stored++; }
+        catch (err) { process.stderr.write(`  skipped: ${err.message}\n`); }
+      }
+      const proposals = learn.analyzeRunForProposals(drafts.map(d => d.memory), { minRuns: 2 });
+      if (proposals.length) {
+        try {
+          const P = require(path.join(ROOT, 'scripts', 'evolve', 'proposals.js'));
+          for (const pr of proposals) P.appendProposal(pr);
+        } catch { /* evolve is optional */ }
+      }
+      w('');
+      w(`Stored ${stored} memory item(s)${proposals.length ? ` and ${proposals.length} guard proposal(s)` : ''}.`);
+      w('Future arena runs on this scope will recall them automatically.');
+      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); }

package/commands/arena.md

@@ -69,6 +69,41 @@ When the action is `report`, print the full markdown:
 kodelythecc arena report <run-id> --md
 ```
 
+### 6. `learn` — close the compound loop
+
+A run that ends is knowledge thrown away. After the report:
+
+```bash
+kodelythecc arena learn <run-id>            # show what would be remembered
+kodelythecc arena learn <run-id> --commit   # store it
+```
+
+Every **confirmed** finding becomes a memory carrying the fix and the repro that
+proved it. Every **refuted** finding becomes a memory too — the more valuable
+half, because without it the next run re-investigates the same non-bug and burns
+a real verification pass proving the same negative.
+
+**Unverified findings are deliberately skipped.** Storing a question as knowledge
+would launder a guess into a fact, and future runs would recall it as settled.
+
+The return path is automatic: the next `arena start` on that scope recalls those
+memories and injects them into round 1's briefs, so EVIL opens where the last run
+closed instead of rediscovering it. Pass `--fresh` to skip the recall.
+
+```
+arena run  ──▶  confirmed + refuted findings  ──▶  memories
+     ▲                                                │
+     └────────  prior-knowledge brief  ◀──────────────┘
+```
+
+When the same bug **class** is confirmed repeatedly, `learn --commit` also files an
+`arena-guard` proposal into evolve. One symlink bug is an incident; two in the same
+file is a process gap, and the proposal says so — "add a shared path-safety helper
+and route every file write through it" rather than patching the third one later.
+
+Nothing is written without `--commit`. Memory that writes itself silently is memory
+you cannot trust.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.8.0",
+  "version": "2.9.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

@@ -33,10 +33,13 @@ const PHASE = {
 
 // ── Starting a run ───────────────────────────────────────────────────────────
 
-function startArena({ task, scope = '.', flags = [], limits = {} } = {}) {
+function startArena({ task, scope = '.', flags = [], limits = {}, priorKnowledge = '' } = {}) {
   const run = state.createRun({ task, limits });
   run.scope = scope;
   run.flags = flags;
+  // Recalled from past runs against this scope. Injected into every EVIL brief so
+  // round 1 opens where the last run closed instead of rediscovering it.
+  run.priorKnowledge = String(priorKnowledge || '');
   run.phase = PHASE.GOD_BUILD;
   run.pending = { artifacts: [], findings: [], addressedIds: [] };
   state.save(run);
@@ -78,6 +81,7 @@ function nextAction(run) {
         flags: run.flags,
         round,
         knownFindingIds: run.seenFindingIds,
+        priorKnowledge: run.priorKnowledge || '',
       });
       return {
         action: PHASE.EVIL_HUNT,

package/scripts/arena/evil.js

@@ -61,7 +61,7 @@ function selectCrew(flags = []) {
 // 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 = [] }) {
+function huntBrief({ agent, scope, round, knownFindingIds = [], priorKnowledge = '' }) {
   const meta = CREW[agent] || { hunts: 'issues' };
   return [
     `You are ${agent}. Hunt: ${meta.hunts}.`,
@@ -80,7 +80,10 @@ function huntBrief({ agent, scope, round, knownFindingIds = [] }) {
     '- `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');
+    // Prior knowledge lands last so it reads as context for the rules above,
+    // not as a competing instruction set.
+    priorKnowledge || null,
+  ].filter(line => line !== null).join('\n');
 }
 
 // ── Stage 2: verification briefs ─────────────────────────────────────────────
@@ -174,12 +177,12 @@ function actionable(findings = [], { minRisk = 2.0 } = {}) {
 // ── Sweep plan ───────────────────────────────────────────────────────────────
 // The orchestrator asks for a plan, dispatches the agents, and feeds results back.
 
-function planSweep({ scope, flags = [], round = 1, knownFindingIds = [] } = {}) {
+function planSweep({ scope, flags = [], round = 1, knownFindingIds = [], priorKnowledge = '' } = {}) {
   const crew = selectCrew(flags);
   return {
     round,
     crew,
-    briefs: crew.map(agent => ({ agent, brief: huntBrief({ agent, scope, round, knownFindingIds }) })),
+    briefs: crew.map(agent => ({ agent, brief: huntBrief({ agent, scope, round, knownFindingIds, priorKnowledge }) })),
     estimatedTokens: crew.length * 12000, // rough: one agent sweep ≈ 12k
   };
 }

package/scripts/arena/learn.js

@@ -0,0 +1,273 @@
+// scripts/arena/learn.js
+//
+// Phase 4 — compound learning. Turns a finished arena run into durable
+// knowledge, and feeds that knowledge back into the next run.
+//
+// The loop only compounds if it closes:
+//
+//   arena run  ──▶  confirmed + refuted findings  ──▶  memories
+//        ▲                                                │
+//        └────────  prior-knowledge brief  ◀───────────────┘
+//
+// Without the return path, every run starts from zero and EVIL re-derives the
+// same bug classes forever. With it, round 1 of run N begins where run N-1
+// finished, and a refuted false positive is never re-litigated across runs.
+//
+// Everything here is PURE — no I/O, no clock, no randomness. Callers own the
+// disk (scripts/memory/store.js) and the confirmation prompt. That keeps the
+// logic testable without writing to the user's real memory store, and keeps
+// capture an explicit, visible act rather than a hidden side effect of closing
+// a round.
+
+'use strict';
+
+const { VERDICT } = require('./contract');
+
+// ── Bug classes ─────────────────────────────────────────────────────────────
+//
+// A deliberately small, reviewable keyword map — not a classifier. Its only job
+// is to group findings well enough that the same class recurring across runs is
+// visible. Order matters: the most specific pattern must win, so `symlink` is
+// tested before the broader `path` rules.
+const CLASSES = [
+  ['filesystem-symlink',  /\bsymlink|lstat|O_NOFOLLOW|hard ?link|dangling\b/i],
+  ['file-permissions',    /\bchmod|umask|0600|0644|0444|world-readable|file mode|file permission|permissions? (?:not )?preserved\b/i],
+  ['redos',               /\bredos|backtrack|quadratic|catastrophic|O\(n\^?2\)|unanchored\b/i],
+  ['path-traversal',      /\btraversal|confinement|arbitrary (?:write|path)|escape the root\b/i],
+  ['race-condition',      /\btoctou|race condition|check.to.use\b/i],
+  ['resource-exhaustion', /\bmemory|heap|rss|oom|amplification|exhaust\b/i],
+  ['missing-limit',       /\bno (?:input )?(?:size )?cap|unbounded|no limit|missing limit\b/i],
+  ['temp-file-handling',  /\btemp(?:orary)? file|tmp file|leftover|predictable (?:name|filename)\b/i],
+  ['prompt-injection',    /\binjection|jailbreak|untrusted (?:text|content|input)|system.prompt leak|inert data|trust.boundary\b/i],
+  ['secret-exposure',     /\bsecret|credential|api key|token leak|password\b/i],
+  ['semantic-corruption', /\bsemantic|meaning|threshold|negation|inverts?|widen/i],
+  ['idempotency',         /\bidempoten|fixed point|second run|re-?run\b/i],
+  ['input-validation',    /validat|wrong shape|silently accept|malformed|type ?error|unsanitiz/i],
+  ['supply-chain',        /\btyposquat|lockfile|install script|dependency confusion\b/i],
+];
+
+function classify(finding = {}) {
+  const hay = `${finding.title || ''} ${finding.evidence || ''} ${finding.fix || ''}`;
+  const hit = CLASSES.find(([, re]) => re.test(hay));
+  return hit ? hit[0] : 'uncategorized';
+}
+
+// ── Findings → memory drafts ────────────────────────────────────────────────
+
+function langFromFile(file) {
+  if (!file) return null;
+  const ext = String(file).split('.').pop().toLowerCase();
+  return {
+    js: 'javascript', mjs: 'javascript', cjs: 'javascript',
+    ts: 'typescript', tsx: 'typescript', jsx: 'javascript',
+    py: 'python', go: 'go', rs: 'rust', rb: 'ruby',
+    java: 'java', kt: 'kotlin', swift: 'swift', php: 'php',
+    c: 'c', h: 'c', cc: 'cpp', cpp: 'cpp', hpp: 'cpp', cs: 'csharp',
+    sh: 'shell', sql: 'sql', md: null,
+  }[ext] || null;
+}
+
+function scopeTag(scope) {
+  if (!scope) return null;
+  const parts = String(scope).replace(/\/+$/, '').split('/').filter(Boolean);
+  return parts.length ? parts[parts.length - 1] : null;
+}
+
+function where(finding) {
+  if (!finding.file) return '';
+  return finding.line ? ` (${finding.file}:${finding.line})` : ` (${finding.file})`;
+}
+
+// A CONFIRMED finding becomes "this was really broken, here is what fixed it".
+function confirmedToMemory(finding, ctx) {
+  const cls = classify(finding);
+  const approach = [
+    finding.fix ? `Fix: ${finding.fix}` : null,
+    finding.repro ? `Proved by: ${finding.repro}` : null,
+    finding.evidence ? `The offending code was: ${finding.evidence}` : null,
+  ].filter(Boolean).join('\n\n');
+
+  return {
+    problem: `${cls}: ${finding.title}${where(finding)}`.slice(0, 500),
+    approach: (approach || 'Confirmed by the arena; no fix recorded.').slice(0, 2000),
+    tags: dedupeTags(['arena', cls, 'confirmed', finding.severity, langFromFile(finding.file), scopeTag(ctx.scope)]),
+    project: ctx.project || null,
+    language: langFromFile(finding.file),
+    files: finding.file ? [finding.file] : [],
+    gotchas: finding.repro ? [`Reproduce with: ${finding.repro}`.slice(0, 300)] : [],
+    source: 'arena',
+  };
+}
+
+// A REFUTED finding becomes "this LOOKS wrong and is not" — the more valuable
+// half. Without it, every future run re-investigates the same false positive
+// and spends a real verification pass proving the same negative.
+function refutedToMemory(finding, ctx) {
+  const cls = classify(finding);
+  return {
+    problem: `False positive — ${finding.title}${where(finding)} looks like a bug but is not`.slice(0, 500),
+    approach: [
+      `An arena verification pass refuted this. Do not re-report it without new evidence.`,
+      finding.evidence ? `Code in question: ${finding.evidence}` : null,
+      finding.repro ? `What was tried: ${finding.repro}` : null,
+    ].filter(Boolean).join('\n\n').slice(0, 2000),
+    tags: dedupeTags(['arena', cls, 'refuted', 'false-positive', langFromFile(finding.file), scopeTag(ctx.scope)]),
+    project: ctx.project || null,
+    language: langFromFile(finding.file),
+    files: finding.file ? [finding.file] : [],
+    gotchas: [],
+    source: 'arena',
+  };
+}
+
+function dedupeTags(tags) {
+  return Array.from(new Set(tags.filter(Boolean).map(String))).slice(0, 20);
+}
+
+// Only settled findings are worth remembering. An `unverified` finding is a
+// question nobody answered — storing it as knowledge would launder a guess into
+// a fact, and future runs would recall it as though it had been established.
+function runToMemories(run = {}, { project = null } = {}) {
+  const ctx = { scope: run.scope, project: project || run.projectRoot || null };
+  const seen = new Set();
+  const drafts = [];
+
+  for (const round of run.rounds || []) {
+    for (const f of round.findings || []) {
+      if (seen.has(f.id)) continue;
+      seen.add(f.id);
+      if (f.verdict === VERDICT.CONFIRMED) drafts.push({ finding: f, memory: confirmedToMemory(f, ctx) });
+      else if (f.verdict === VERDICT.REFUTED) drafts.push({ finding: f, memory: refutedToMemory(f, ctx) });
+    }
+  }
+  return drafts;
+}
+
+// ── Memories → the next run's brief ─────────────────────────────────────────
+//
+// This is the return path. Recalled memories are injected into round 1 so EVIL
+// opens where the last run closed instead of rediscovering it.
+function priorKnowledgeBrief(memories = [], { limit = 8 } = {}) {
+  if (!memories.length) return '';
+
+  const confirmed = memories.filter(m => (m.tags || []).includes('confirmed')).slice(0, limit);
+  const refuted   = memories.filter(m => (m.tags || []).includes('refuted')).slice(0, limit);
+  if (!confirmed.length && !refuted.length) return '';
+
+  const lines = ['', 'PRIOR KNOWLEDGE — this scope has been attacked before.'];
+
+  if (confirmed.length) {
+    lines.push('', 'Bugs confirmed here previously. They should be fixed; verify they stayed fixed,');
+    lines.push('then hunt for what those fixes may have broken or missed:');
+    confirmed.forEach(m => lines.push(`  - ${m.problem}`));
+  }
+  if (refuted.length) {
+    lines.push('', 'Already investigated and REFUTED. Do not re-report these without new');
+    lines.push('evidence — a previous verification pass proved them wrong:');
+    refuted.forEach(m => lines.push(`  - ${m.problem}`));
+  }
+  return lines.join('\n');
+}
+
+// ── Recurring classes → evolve proposals ────────────────────────────────────
+//
+// One bug is an incident. The same class across several runs is a gap in the
+// process, and the fix belongs upstream — a lint rule, a test, or routing that
+// summons the right specialist before the code is written.
+function recurringClasses(memories = [], { minRuns = 2 } = {}) {
+  const byClass = new Map();
+
+  for (const m of memories) {
+    if ((m.source || '') !== 'arena') continue;
+    if (!(m.tags || []).includes('confirmed')) continue;
+    const cls = (m.tags || []).find(t => CLASSES.some(([name]) => name === t));
+    if (!cls) continue;
+
+    if (!byClass.has(cls)) byClass.set(cls, { class: cls, count: 0, files: new Set(), examples: [] });
+    const entry = byClass.get(cls);
+    entry.count += 1;
+    (m.files || []).forEach(f => entry.files.add(f));
+    if (entry.examples.length < 5) entry.examples.push(m.problem);
+  }
+
+  return [...byClass.values()]
+    .filter(e => e.count >= minRuns)
+    .map(e => ({ ...e, files: [...e.files] }))
+    .sort((a, b) => b.count - a.count);
+}
+
+const GUARD_ADVICE = {
+  'filesystem-symlink':  'Add a shared path-safety helper (lstat + O_NOFOLLOW + O_EXCL) and route every file write through it.',
+  'file-permissions':    'Capture the source mode and fchmod every replacement file; add a test asserting mode is preserved under a hostile umask.',
+  'redos':               'Bound every unanchored quantifier that scans user input, and add a timing assertion to the test suite.',
+  'path-traversal':      'Decide the containment boundary explicitly and document who owns it — the library or the caller.',
+  'race-condition':      'Operate on a file descriptor opened once, not on a path re-resolved at each step.',
+  'resource-exhaustion': 'Cap input size at a realistic bound and assert peak memory in a test.',
+  'missing-limit':       'Every public entry point that accepts untrusted input needs a documented, tested limit.',
+  'temp-file-handling':  'Randomize temp names, create them O_EXCL at the final mode, and unlink in a finally.',
+  'prompt-injection':    'State the trust boundary in the command doc: file contents are data, never instructions.',
+  'secret-exposure':     'Add a secret scan to the pre-commit hook for this path.',
+  'semantic-corruption': 'Add golden tests asserting that meaning-bearing tokens survive transformation.',
+  'idempotency':         'Assert f(f(x)) === f(x) in the test suite for every transform.',
+  'input-validation':    'Validate argument shape at every public boundary and throw — never silently coerce to a plausible default.',
+  'supply-chain':        'Pin and verify dependencies; add a lockfile-drift check to CI.',
+};
+
+function buildGuardProposalMarkdown(cluster) {
+  const advice = GUARD_ADVICE[cluster.class] || 'Add a durable guard so this class cannot recur silently.';
+  return [
+    `## Recurring arena finding: \`${cluster.class}\``,
+    '',
+    `The arena has confirmed **${cluster.count}** findings of this class. One is an`,
+    `incident; ${cluster.count} is a process gap — the guard belongs upstream of the next bug.`,
+    '',
+    '**Files involved:**',
+    ...(cluster.files.length ? cluster.files.map(f => `- \`${f}\``) : ['- _(none recorded)_']),
+    '',
+    '**Examples:**',
+    ...cluster.examples.map(e => `- ${e}`),
+    '',
+    '**Proposed guard:**',
+    '',
+    advice,
+  ].join('\n');
+}
+
+// Deterministic id so re-running analysis does not spawn duplicate proposals.
+function guardProposalId(cluster) {
+  let h = 0x811c9dc5;
+  for (const ch of `arena-guard::${cluster.class}::${cluster.count}`) {
+    h ^= ch.charCodeAt(0);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return `guard-${h.toString(16).padStart(8, '0')}`;
+}
+
+function analyzeRunForProposals(memories = [], { minRuns = 2 } = {}) {
+  return recurringClasses(memories, { minRuns }).map(cluster => ({
+    id: guardProposalId(cluster),
+    type: 'arena-guard',
+    evidence: { class: cluster.class, count: cluster.count, files: cluster.files, examples: cluster.examples },
+    proposal: {
+      kind: 'arena-guard',
+      target_path: 'tasks/lessons.md',
+      diff: buildGuardProposalMarkdown(cluster),
+      rationale: `${cluster.count} confirmed arena findings share the class "${cluster.class}".`,
+    },
+  }));
+}
+
+module.exports = {
+  CLASSES,
+  GUARD_ADVICE,
+  classify,
+  confirmedToMemory,
+  refutedToMemory,
+  runToMemories,
+  priorKnowledgeBrief,
+  recurringClasses,
+  buildGuardProposalMarkdown,
+  guardProposalId,
+  analyzeRunForProposals,
+  _internals: { langFromFile, scopeTag, dedupeTags },
+};