kodelyth-ecc 2.13.0 → 2.15.0

package/CHANGELOG.md

@@ -2,6 +2,120 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.15.0 — Green CI, and the agents learn what the arena found (September 2026)
+
+### Fixed — CI had been red since v2.8.0
+
+Eight tests asserted POSIX file semantics on the Windows runner. Every release
+from 2.8.0 through 2.14.0 shipped with a failing badge, because `npm test` was
+only ever run on macOS — a green local run beside a red CI is exactly the trap
+this release also teaches `release-captain` to catch.
+
+On Windows `chmod` only toggles the read-only bit, `statSync().mode` is
+synthesized rather than real, `umask` is meaningless, and `symlinkSync` needs
+administrator rights or Developer Mode. The eight tests assert precisely those
+semantics.
+
+They are **skipped there with a stated reason, not deleted** — the behaviour they
+guard (mode preservation, umask independence, `O_EXCL` against planted symlinks)
+is real on Linux and macOS, which is where CI proves it.
+
+```
+tests/lib/safe-fs.test.js      5 guarded
+tests/terse/compress.test.js   3 guarded
+```
+
+All nine CI jobs now pass: Node 18/20/22 across Linux, macOS, and Windows.
+
+### Changed — three agents learned from three arena runs
+
+The arena confirmed the same defects repeatedly, and none of the 70 agents knew
+to look for them. Each addition below is a bug that was actually reproduced, not
+a hypothetical.
+
+**`security-reviewer`** gained three hunt blocks:
+
+- **Lexical-only path containment** — `path.join`/`resolve` normalise `..` but do
+  not resolve symlinks, so a link inside the root passes a `startsWith` check
+  while pointing anywhere on disk. Confirmed four times across three files.
+- **Prototype keys as map keys** — `map['constructor']` returns a truthy
+  function, so `if (!map[k])` never fires. Needs no attacker: one document
+  containing the word "constructor" bricked the memory store.
+- **Truncate-then-write on persistent state** — `writeFileSync` opens with `'w'`.
+  A 6.3 MB store was measured at 0 bytes mid-rewrite, 32 torn reads in 1423
+  samples.
+
+**`code-reviewer`** gained the same three as checklist items under Security.
+
+**`release-captain`** gained **Phase 1.5 — Prove the build is green where it
+actually runs**, with the `gh run list` / `gh run view --log-failed` commands and
+a table of one-platform traps (POSIX modes, umask, symlinks, path separators,
+BSD vs GNU flags). It states plainly: never cut a release on a red CI, and never
+report "all tests passing" when only your own platform is passing.
+
+### Fixed — repository metadata
+
+The GitHub About sidebar still advertised `194 skills · 97 commands`. Corrected
+to 196 / 102, and the arena added to the description.
+
+**572 tests passing on every supported platform.**
+
+## v2.14.0 — A false recurring class, and five more atomic writes (August 2026)
+
+### Fixed — the guard proposal was pointing at the wrong thing
+
+After three arena runs the classifier reported **`resource-exhaustion` ×5** as the
+top recurring class. Four of those five were not resource exhaustion at all:
+
+```
+resource-exhaustion  <- Prototype-key collision crashes indexing
+resource-exhaustion  <- A crash mid-append fuses the next memory into the torn row
+resource-exhaustion  <- A patch row surfaced as a phantom memory
+```
+
+The pattern contained the bare word `memory`, which matches every finding about
+the memory *store*. Acting on it would have meant building a guard nobody needed
+— exactly the waste the proposal mechanism exists to prevent. This is the second
+generic-word collision in this classifier; `permission` was the first.
+
+`resource-exhaustion` now requires an actual exhaustion signal (`heap`, `rss`,
+`oom`, `memory leak/usage/growth`, `allocates N`). A new **`data-integrity`**
+class covers the double-index / desync / phantom-row / torn-row family, and
+prototype-key findings now classify as `input-validation`. The 5 mis-tagged
+memories already in the store were re-tagged.
+
+The corrected picture across three runs:
+
+| class | count | status |
+|---|---|---|
+| `filesystem-symlink` | 4 | already guarded by `scripts/lib/safe-fs.js` |
+| `data-integrity` | 4 | all four in one file, all fixed |
+| `input-validation` | 2 | fixed |
+| everything else | 1 each | — |
+
+**No new abstraction was built for `data-integrity`.** All four members live in
+`store.js` and are already fixed, and no other subsystem keeps derived state with
+the same drift — so a shared guard would have been speculative.
+
+### Added — `replaceFilePreservingMode`, applied to five real writers
+
+What the sweep *did* find is the durability pattern in files holding state worth
+keeping. `fs.writeFileSync` opens with `'w'`, truncating to zero before writing,
+so a crash or a full disk part-way through leaves a truncated file and no copy of
+the original:
+
+- `scripts/codex/merge-mcp-config.js` — the user's **Codex IDE config**
+- `scripts/codex/merge-codex-config.js` — the user's **Codex IDE config**
+- `scripts/evolve/stats.js` — accumulated reuse and routing-miss stats
+- `scripts/mcp/client.js` — the MCP server registry
+- `scripts/memory/store.js` — the BM25 index
+
+All five now write through `safeFs.replaceFilePreservingMode`, which keeps the
+file's existing permissions and renames atomically. A crash leaves the original
+completely untouched.
+
+**572 tests passing**, up from 569.
+
 ## v2.13.0 — Arena run #3: eight bugs in the memory store (August 2026)
 
 Pointed the arena at `scripts/memory` — the persistent BM25 store every other

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 (arena.md, mcp.md, dashboard.md, swarm.md, replay.md, evolve.md, supply-chain.md)
-tests/       → 569 passing tests across 30 test files
+tests/       → 572 passing tests across 30 test files
 ```
 
 ## Running Tests

package/README.md

@@ -72,7 +72,7 @@ You never typed `use debug-detective`. You didn't have to. The toolkit read the
 |---|---|---|
 | **Intent routing** | Plain-language → right specialist via 10-tier priority rules | Mostly missing — you memorize names |
 | **70 agents** | Specialists with playbooks, severity calibration, real commands | Often persona-only ("you are a senior engineer...") |
-| **194 skills** | Domain knowledge files agents read on demand | Rarely separated from agents |
+| **196 skills** | Domain knowledge files agents read on demand | Rarely separated from agents |
 | **102 commands** | Slash workflows (`/tdd`, `/arena`, `/devil-mode`, `/team-review`) | Limited or none |
 | **8 parallel commands** | Fire 3-8 agents simultaneously, aggregate results | Rare |
 | **Compound memory** | BM25 local recall + auto-inject + project lessons | Cloud-only or absent |
@@ -118,7 +118,7 @@ kodelythecc --target claude-code --codebase-graph
 That's it. This single flow:
 
 1. Installs both binaries (`kodelyth-ecc` and short-form `kodelythecc`) to your PATH
-2. Copies 70 agents + 194 skills + 97 commands + 22 hooks + 14 rules into your AI tool's config dir
+2. Copies 70 agents + 196 skills + 102 commands + 22 hooks + 14 rules into your AI tool's config dir
 3. Auto-installs **RTK** binary and wires its PreToolUse hook (input compression starts on next AI restart)
 4. Installs **Terse mode** skill + `/terse` and `/terse-compress` slash commands (dormant — user types `/terse` to activate)
 5. Auto-installs **codebase-memory-mcp** and registers its MCP entries in your AI tool (with `--codebase-graph`)
@@ -220,7 +220,7 @@ npx kodelyth-ecc --bundle red-team        # Security engineer — devil-mode + a
 npx kodelyth-ecc --bundle enterprise      # Compliance / audit team — SBOM, license, supply chain
 ```
 
-Each bundle installs the full ECC toolkit (all 70 agents, 194 skills, 97 commands, 22+ hooks), adds a `BUNDLE.md` cheat sheet, and biases the AI toward audience-fit workflows on every session.
+Each bundle installs the full ECC toolkit (all 70 agents, 196 skills, 102 commands, 22+ hooks), adds a `BUNDLE.md` cheat sheet, and biases the AI toward audience-fit workflows on every session.
 
 Combine with any target:
 
@@ -417,7 +417,7 @@ What's inside:
 | **Overview** | Agent count, memory stats, session count, recent activity |
 | **Memory** | Browse, search, and manage your local BM25 memory store |
 | **Evolve** | Self-improving memory — review AI-proposed refinements |
-| **Catalog** | Full searchable index of all 70 agents, 194 skills, 97 commands |
+| **Catalog** | Full searchable index of all 70 agents, 196 skills, 102 commands |
 | **Sessions** | **Live IDE activity** (Claude Code, Windsurf, Windsurf-Next, Cursor, Antigravity) + orchestration/swarm sessions |
 
 Real-time:
@@ -888,7 +888,7 @@ The intent router will route you to the right one. The AI announces who's taking
 | Source | Destination | What it does |
 |---|---|---|
 | `agents/` | `~/.claude/agents/` | All 70 subagents available globally |
-| `skills/` | `~/.claude/skills/` | All 194 skills loadable via commands |
+| `skills/` | `~/.claude/skills/` | All 196 skills loadable via commands |
 | `hooks/hooks.json` | `~/.claude/hooks/` | Automated quality gates |
 | `rules/` | `~/.claude/rules/` | Always-on standards + intent routing |
 | `commands/` | `~/.claude/commands/` | Slash commands (`/tdd`, `/plan`, etc.) |

package/VERSION

@@ -1 +1 @@
-2.13.0
+2.15.0

package/agents/code-reviewer.md

@@ -37,6 +37,16 @@ These MUST be flagged — they can cause real damage:
 - **SQL injection** — String concatenation in queries instead of parameterized queries
 - **XSS vulnerabilities** — Unescaped user input rendered in HTML/JSX
 - **Path traversal** — User-controlled file paths without sanitization
+- **Lexical-only containment** — `startsWith(root)` after `path.join` catches `..` but NOT
+  symlinks: `path.resolve` does not resolve them, so a link inside the root passes the check
+  while pointing anywhere on disk. Demand `realpath` on both sides before the comparison.
+- **Prototype keys as map keys** — `map['constructor']` returns a truthy function, so
+  `if (!map[k])` never fires and the next line reads a property off it. Any object keyed by
+  user text (tokens, tags, headers, filenames) must be `Object.create(null)`. Words like
+  "constructor" and "toString" are ordinary vocabulary — this needs no attacker.
+- **Truncate-then-write on state worth keeping** — `fs.writeFileSync` opens with `'w'` and
+  truncates to zero before writing. A crash, a full disk, or a concurrent reader sees an
+  empty file. Config files, registries, ledgers and indexes need temp + rename.
 - **CSRF vulnerabilities** — State-changing endpoints without CSRF protection
 - **Authentication bypasses** — Missing auth checks on protected routes
 - **Insecure dependencies** — Known vulnerable packages

package/agents/release-captain.md

@@ -40,6 +40,31 @@ Read the diff since last tag. Classify each change:
 
 Be **strict** about MAJOR. Most teams under-call breaking changes and lose user trust.
 
+### Phase 1.5 — Prove the build is green where it actually runs
+
+A local `npm test` proves the suite passes **on your machine**. It says nothing
+about the other platforms CI covers, and a green local run beside a red badge is
+how a project ships eight broken releases in a row without noticing.
+
+```bash
+gh run list --workflow=CI --limit 5      # is the badge actually green?
+gh run view <id> --log-failed            # if not, what fails and on which OS?
+```
+
+**Never cut a release on a red CI.** If the failure is platform-specific, fix or
+explicitly guard it — do not delete the test, and do not tell the user "all tests
+passing" when only your platform is passing.
+
+Common one-platform traps:
+
+| Assumption | Breaks on |
+|---|---|
+| `chmod` / `statSync().mode` carry POSIX bits | Windows — only the read-only bit exists |
+| `process.umask()` is meaningful | Windows |
+| `symlinkSync` just works | Windows — needs admin or Developer Mode |
+| Paths use `/` | Windows — compare with `path.sep` |
+| `timeout`, `stat -f`, GNU flags exist | macOS ships BSD variants; Windows ships neither |
+
 ### Phase 2 — Generate the changelog
 
 Group entries by category, in this order:

package/agents/security-reviewer.md

@@ -55,6 +55,30 @@ rg -n 'Math\.random\(\)'                                          # non-CSPRNG f
 
 # ── Unsafe deserialization + prototype pollution (HIGH) ─────────────────────
 rg -n 'pickle\.loads|yaml\.load\(|Marshal\.load|JSON\.parse\([^)]*req\.|_\.merge\(\{\}|Object\.assign\(target'   # yaml.load: confirm it lacks SafeLoader
+
+# ── Lexical-only path containment (HIGH) ────────────────────────────────────
+# path.join/resolve normalise ".." but do NOT resolve symlinks. A link sitting
+# lexically inside the root passes a startsWith() check while its target is
+# anywhere on disk, and the read follows it. Confirmed four times across three
+# unrelated files in this codebase before the guard existed.
+rg -n 'startsWith\(.*(?:ROOT|DIR|BASE|root|base|dir).*sep|startsWith\(.*\+ .?/.?\)'   # then check: is there a realpathSync nearby?
+rg -n 'readFileSync|createReadStream|readdirSync' --context 3 | rg -n 'path\.(join|resolve)'  # read after a lexical check = the bug
+# The fix is realpath on BOTH sides before comparing, or an existing helper.
+
+# ── Prototype keys used as map keys (HIGH) ──────────────────────────────────
+# map['constructor'] returns Object.prototype.constructor — TRUTHY — so an
+# `if (!map[k])` guard never fires and the next line reads a property off a
+# function. "constructor" and "toString" are ordinary vocabulary, so this needs
+# no attacker: one document containing the word is enough.
+rg -n 'if \(!\w+\[\w+\]\)|\w+\[\w+\] = \w+\[\w+\] \|\|'   # any map keyed by user text
+rg -n '= \{\};' --context 2 | rg -n 'token|term|word|tag|key|freq|count'  # should be Object.create(null)
+
+# ── Truncate-then-write on persistent state (HIGH) ──────────────────────────
+# fs.writeFileSync opens with 'w', truncating to zero BEFORE writing. A crash,
+# a full disk, or a concurrent reader sees an empty file. Measured: a 6.3 MB
+# store observed at 0 bytes mid-rewrite, 32 torn reads in 1423 samples.
+rg -n 'writeFileSync\(' | rg -v 'tmp|\.tmp|test'   # then ask: does this file hold state worth keeping?
+# Config files, registries, ledgers, and indexes need temp+rename, not writeFileSync.
 ```
 
 Report every confirmed hit with: file:line, severity, the exact fix, and (for secrets) "rotate immediately."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.13.0",
+  "version": "2.15.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/learn.js

@@ -35,14 +35,15 @@ const CLASSES = [
   ['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],
+  ['resource-exhaustion', /\bheap\b|\brss\b|\boom\b|amplification|exhaust|out of memory|memory (?:leak|usage|growth|pressure)|allocates? ~?\d/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],
+  ['data-integrity',      /\bdouble-?index|desync|out of sync|phantom|corrupt|torn row|lost update|inconsisten|silently lost\b/i],
+  ['input-validation',    /validat|wrong shape|silently accept|malformed|type ?error|unsanitiz|prototype[- ]key|__proto__|prototype pollution/i],
   ['access-control',      /\bbypass(?:es|ed)? the|rebinding|host header|allowlist|authoriz|access control\b/i],
   ['supply-chain',        /\btyposquat|lockfile|install script|dependency confusion\b/i],
 ];
@@ -229,6 +230,7 @@ const GUARD_ADVICE = {
   '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.',
+  'data-integrity':      'Derive the secondary structure from the primary one and add a cheap staleness check, so drift self-heals instead of persisting.',
   'input-validation':    'Validate argument shape at every public boundary and throw — never silently coerce to a plausible default.',
   'access-control':      'Deny by default: an allowlist of permitted values, with every absent or empty case treated as invalid rather than waved through.',
   'supply-chain':        'Pin and verify dependencies; add a lockfile-drift check to CI.',

package/scripts/codex/merge-codex-config.js

@@ -13,6 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const safeFs = require('../lib/safe-fs.js');
 
 let TOML;
 try {
@@ -310,7 +311,7 @@ function main() {
     return;
   }
 
-  fs.writeFileSync(configPath, nextRaw, 'utf8');
+  safeFs.replaceFilePreservingMode(configPath, nextRaw);
   log('Done. Baseline Codex settings merged.');
 }
 

package/scripts/codex/merge-mcp-config.js

@@ -19,6 +19,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const safeFs = require('../lib/safe-fs.js');
 const { parseDisabledMcpServers } = require('../lib/mcp-config');
 
 let TOML;
@@ -319,7 +320,7 @@ function main() {
   if (updateMcp || hasRemovals) {
     for (const label of toRemoveLog) log(`  [update] ${label}`);
     const cleaned = raw.replace(/\n+$/, '\n');
-    fs.writeFileSync(configPath, cleaned + (toAppend.length > 0 ? appendText : ''), 'utf8');
+    safeFs.replaceFilePreservingMode(configPath, cleaned + (toAppend.length > 0 ? appendText : ''));
   } else {
     fs.appendFileSync(configPath, appendText, 'utf8');
   }

package/scripts/evolve/stats.js

@@ -29,6 +29,7 @@ const fs   = require('fs');
 const os   = require('os');
 const path = require('path');
 const crypto = require('crypto');
+const safeFs = require('../lib/safe-fs.js');
 
 const DEFAULT_DIR = process.env.KODELYTH_EVOLVE_DIR
   || path.join(os.homedir(), '.kodelythecc', 'evolve');
@@ -54,7 +55,7 @@ function safeReadJson(p, fallback) {
 
 function safeWriteJson(p, data) {
   try {
-    fs.writeFileSync(p, JSON.stringify(data, null, 2));
+    safeFs.replaceFilePreservingMode(p, JSON.stringify(data, null, 2));
     return true;
   } catch { return false; }
 }

package/scripts/lib/safe-fs.js

@@ -153,10 +153,29 @@ function replaceFileAtomic(absPath, contents, mode) {
   return absPath;
 }
 
+/**
+ * Replace an existing file's contents atomically, keeping whatever permissions
+ * it already had (or `fallbackMode` when it does not exist yet).
+ *
+ * This is the safe replacement for `fs.writeFileSync(path, data)` on any file
+ * that holds state worth keeping — a user's IDE config, an accumulated stats
+ * file, a registry. `writeFileSync` opens with 'w', truncating to zero before
+ * writing, so a crash or a full disk part-way through leaves the user with a
+ * truncated file and no copy of the original anywhere.
+ */
+function replaceFilePreservingMode(absPath, contents, fallbackMode = 0o644) {
+  let mode = fallbackMode;
+  try {
+    mode = fs.statSync(absPath).mode & 0o7777;
+  } catch { /* new file — use the fallback */ }
+  return replaceFileAtomic(absPath, contents, mode);
+}
+
 module.exports = {
   resolveContained,
   statRegularFile,
   safeConfigDir,
   writeNewFile,
   replaceFileAtomic,
+  replaceFilePreservingMode,
 };

package/scripts/mcp/client.js

@@ -30,6 +30,7 @@
 const fs   = require('fs');
 const os   = require('os');
 const path = require('path');
+const safeFs = require('../lib/safe-fs.js');
 
 const REGISTRY_DIR = process.env.KODELYTH_MCP_CLIENT_DIR
   || path.join(os.homedir(), '.kodelythecc');
@@ -54,7 +55,7 @@ function loadRegistry() {
 
 function saveRegistry(reg) {
   ensureDir(REGISTRY_DIR);
-  fs.writeFileSync(REGISTRY_FILE, JSON.stringify(reg, null, 2) + '\n');
+  safeFs.replaceFilePreservingMode(REGISTRY_FILE, JSON.stringify(reg, null, 2) + '\n');
 }
 
 // ── Registry mutations ───────────────────────────────────────────────────────

package/scripts/memory/store.js

@@ -18,6 +18,7 @@ const fs   = require('fs');
 const os   = require('os');
 const path = require('path');
 const crypto = require('crypto');
+const safeFs = require('../lib/safe-fs.js');
 
 // Auto-migrate legacy ~/.kodelyth/ → ~/.kodelythecc/ before we touch any path.
 try { require('../migrate-legacy').main(); } catch { /* best-effort */ }
@@ -142,7 +143,7 @@ function logSize() {
 
 function saveIndex(index) {
   ensureDir(PATHS.dir);
-  fs.writeFileSync(PATHS.index, JSON.stringify({ ...index, logSize: logSize() }, null, 2));
+  safeFs.replaceFilePreservingMode(PATHS.index, JSON.stringify({ ...index, logSize: logSize() }, null, 2));
 }
 
 // A patch row does not change any searchable text, so the index stays valid —