kodelyth-ecc 2.20.0 → 2.21.0

package/CHANGELOG.md

@@ -2,6 +2,88 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.21.0 — the hooks were never actually turned on (September 2026)
+
+Every hook ECC ships has been inert since the shell installer was written. Not
+misconfigured — never registered.
+
+### What was broken
+
+`install_hooks()` in `install.sh` did exactly one thing:
+
+```bash
+cp "$SCRIPT_DIR/hooks/hooks.json" "$dest/hooks.json"
+```
+
+Claude Code does not read that file. It reads `hooks` out of `settings.json`.
+So the manifest landed on disk and nothing was ever wired up.
+
+It also copied only the manifest, not the `hooks/memory/` and `hooks/safety/`
+scripts every command inside it points at. Of the 12 files under `hooks/`, an
+install copied **1**.
+
+Measured on a fresh install into a throwaway `HOME`:
+
+```
+                          before        after
+settings.json events           1            8
+settings.json entries          1           45
+hook scripts on disk           0            9
+entries whose script exists    n/a    36 of 36
+```
+
+That one `PreToolUse` entry was RTK's — its installer writes `settings.json`
+for its own hook. Nothing ECC ships was in there.
+
+So none of this had ever run: memory inject on `SessionStart`, memory capture
+and correction encoding on `Stop`, auto-recall on `UserPromptSubmit`, the
+prompt-injection guard, the token-budget enforcer. The compound-memory
+behaviour described in the docs could not have worked, because the hook that
+implements it was never registered.
+
+Correct merge logic already existed in `scripts/lib/install/apply.js` — but the
+CLI shells out to `install.sh` and never reaches it. Instrumenting the function
+during a real install confirmed zero calls.
+
+### The fix
+
+`install_hooks()` now copies the whole `hooks/` tree and calls a new registrar,
+`scripts/install/register-hooks.js`, which merges the manifest into
+`settings.json` through that same tested merge:
+
+- **Idempotent** — three consecutive installs give 45, 45, 45 entries.
+- **Non-destructive** — RTK's hook and the user's own survive; verified.
+- **Scoped** — only the `hooks` key changes; `model`, `theme` and `permissions`
+  are left alone.
+- **Atomic** — temp file plus rename, so an interrupted install cannot leave a
+  truncated `settings.json` and a broken editor.
+- **Permission-preserving** — an existing file keeps its mode; a new one is
+  `0600`, because `settings.json` can carry tokens.
+- **Degrades honestly** — no Node, or a corrupt `settings.json`, prints what to
+  run rather than failing the install or losing the hooks.
+
+`doctor` now reports `8 hook events wired` instead of warning that three are
+missing.
+
+### Corrected
+
+The installer banner claimed **194 skills, 97 commands, 22+ hooks**. Actual:
+196, 103, and 44 hook entries across 8 events. It is the first thing every user
+sees, and all three numbers were wrong. Fixed in `install.sh`, `install.ps1`
+and the CLI header.
+
+One of those tests then broke Windows CI on its own terms: it asserted the
+substituted root by searching `JSON.stringify(settings)` for the path. A Windows
+root is `D:\a\repo`, which stringify escapes to `D:\\a\\repo`, so the match
+failed even though the substitution was correct. It now asserts on the parsed
+command strings. Reproduced locally with a Windows-shaped path before and after:
+old assertion `false`, new assertion `true`.
+
+**647 tests passing** — 14 new, covering idempotency, third-party hook
+preservation, unrelated-key preservation, corrupt-config recovery, file modes,
+and two that guard the regression directly: every event in the shipped manifest
+must register, and every script it references must exist in the repo.
+
 ## v2.20.0 — 2.19.0 shipped 21 MB instead of 5; here is the guard (September 2026)
 
 **Upgrade from 2.19.0.** That release is 4× the size it should be and carries

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/       → 633 passing tests across 41 test files
+tests/       → 647 passing tests across 42 test files
 ```
 
 ## Running Tests

package/VERSION

@@ -1 +1 @@
-2.20.0
+2.21.0

package/bin/kodelyth-ecc.js

@@ -141,7 +141,7 @@ if (args[1] === '--help' || args[1] === '-h') {
 
 // ── Subcommand: mcp (start MCP server over stdio) ────────────────────────────
 // Usage: npx kodelyth-ecc mcp
-// Exposes 70 agents, 194 skills, 97 commands, the routing rule, and the local
+// Exposes 70 agents, 196 skills, 103 commands, the routing rule, and the local
 // memory store to any MCP-compatible client (Claude Desktop, LangGraph, etc.).
 if (args[0] === 'mcp') {
   // Hand off entirely to the MCP server — it owns stdio from here on.

package/install.ps1

@@ -61,7 +61,7 @@ if ($Bundle) {
 # -- Banner --------------------------------------------------------------------
 Write-Host ""
 Write-Host "  Kodelyth ECC -- Production-grade AI coding agent toolkit" -ForegroundColor Cyan
-Write-Host "  70 agents (8 devil-mode) | 194 skills | 97 commands | 22+ hooks | intent routing | local memory" -ForegroundColor Gray
+Write-Host "  70 agents (8 devil-mode) | 196 skills | 103 commands | 44 hooks | intent routing | local memory" -ForegroundColor Gray
 Write-Host ""
 
 # $PSScriptRoot is always the directory containing this .ps1 file,
@@ -344,7 +344,7 @@ Powered by Kodelyth ECC -- github.com/sifxprime/kodelyth-ecc
             $geminiText = @'
 # Kodelyth ECC -- Gemini CLI context
 
-This project uses Kodelyth ECC -- 70 specialist agents, 194 skills, 97 commands, intent routing, and self-learning memory.
+This project uses Kodelyth ECC -- 70 specialist agents, 196 skills, 103 commands, intent routing, and self-learning memory.
 
 The full toolkit is installed under this directory:
 

package/install.sh

@@ -47,7 +47,7 @@ echo -e "${RED}${BOLD}  ║   DANGER LEVEL: GOD TIER    ·    NOT FOR JUNIOR DEV
 echo -e "${RED}${BOLD}  ╚══════════════════════════════════════════════════════════════╝${RESET}"
 echo ""
 echo -e "${BOLD}  Kodelyth ECC — The most dangerous AI coding toolkit on the planet${RESET}"
-echo -e "${CYAN}  70 specialist agents (8 devil-mode)  ·  194 skills  ·  97 commands  ·  22+ hooks  ·  intent routing  ·  compound memory${RESET}"
+echo -e "${CYAN}  70 specialist agents (8 devil-mode)  ·  196 skills  ·  103 commands  ·  44 hooks  ·  intent routing  ·  compound memory${RESET}"
 echo -e "${CYAN}  Any language  ·  Any framework  ·  Any scale  ·  300B-level quality${RESET}"
 echo ""
 echo -e "  github.com/sifxprime/kodelyth-ecc"
@@ -435,7 +435,8 @@ install_flat() {
 }
 
 install_hooks() {
-  local src="$SCRIPT_DIR/hooks/hooks.json"
+  local src_dir="$SCRIPT_DIR/hooks"
+  local src="$src_dir/hooks.json"
   local dest="$1"
 
   if [[ -z "$dest" ]] || [[ ! -f "$src" ]]; then
@@ -443,8 +444,39 @@ install_hooks() {
   fi
 
   mkdir -p "$dest"
-  cp "$src" "$dest/hooks.json"
-  echo -e "  ${GREEN}✓${RESET} Hooks ${BLUE}(→ $dest/hooks.json)${RESET}"
+
+  # Copy the whole tree, not just hooks.json. Every command inside hooks.json
+  # points at ${CLAUDE_PLUGIN_ROOT}/hooks/{memory,safety}/*.js — copying the
+  # manifest alone registered hooks whose scripts were never installed.
+  cp -r "$src_dir"/. "$dest/"
+  local script_count
+  script_count=$(find "$dest" -name '*.js' -type f 2>/dev/null | wc -l | tr -d ' ')
+
+  echo -e "  ${GREEN}✓${RESET} Hooks ${BLUE}(→ $dest, $script_count scripts)${RESET}"
+
+  # Registering into settings.json is the step that actually activates them.
+  # Claude Code reads hooks from settings.json; a hooks.json sitting on disk
+  # does nothing. Node ships with this package, but install.sh can also be run
+  # standalone, so degrade with a clear message rather than failing the install.
+  local registrar="$SCRIPT_DIR/scripts/install/register-hooks.js"
+  local target_root="${dest%/hooks}"
+
+  if [[ ! -f "$registrar" ]]; then
+    return
+  fi
+  if ! command -v node >/dev/null 2>&1; then
+    echo -e "  ${YELLOW}!${RESET} Hooks copied but not registered — node not found"
+    echo -e "    ${BLUE}Run after installing Node:${RESET} node \"$registrar\" \"$target_root\""
+    return
+  fi
+
+  local summary
+  if summary=$(node "$registrar" "$target_root" 2>&1); then
+    echo -e "  ${GREEN}✓${RESET} Hooks registered ${BLUE}($summary)${RESET}"
+  else
+    echo -e "  ${YELLOW}!${RESET} Hook registration failed: $summary"
+    echo -e "    ${BLUE}Retry with:${RESET} node \"$registrar\" \"$target_root\""
+  fi
 }
 
 # Generate a single .windsurfrules file from all common rule .md files
@@ -621,7 +653,7 @@ AIDER_EOF
       cat > "$GEMINI_FILE" <<'GEMINI_EOF'
 # Kodelyth ECC — Gemini CLI context
 
-This project uses Kodelyth ECC — 70 specialist agents, 194 skills, 97 commands, intent routing, and self-learning memory.
+This project uses Kodelyth ECC — 70 specialist agents, 196 skills, 103 commands, intent routing, and self-learning memory.
 
 The full toolkit is installed under this directory:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.20.0",
+  "version": "2.21.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/rules/common/shell-portability.md

@@ -28,6 +28,7 @@ Every row below was checked on a stock macOS shell. These are not theoretical.
 | `grep -c` under `set -e` | **any OS** — exits 1 on zero matches | `grep -c x f \|\| echo 0` |
 | `for x in $VAR` | **macOS/zsh** — no word splitting, loops once | list items literally, or `for x in "${ARR[@]}"` |
 | `execFileSync('npm', …)` | **Windows** — ENOENT bare (no PATHEXT), EINVAL on `.cmd` since Node 18.20.2 | `execSync` with one literal command string |
+| `JSON.stringify(x).includes(winPath)` | **Windows** — stringify escapes `\\` to `\\\\` | assert on parsed values, never on JSON text |
 
 ## Measured, not assumed
 

package/rules/shell-portability.md

@@ -28,6 +28,7 @@ Every row below was checked on a stock macOS shell. These are not theoretical.
 | `grep -c` under `set -e` | **any OS** — exits 1 on zero matches | `grep -c x f \|\| echo 0` |
 | `for x in $VAR` | **macOS/zsh** — no word splitting, loops once | list items literally, or `for x in "${ARR[@]}"` |
 | `execFileSync('npm', …)` | **Windows** — ENOENT bare (no PATHEXT), EINVAL on `.cmd` since Node 18.20.2 | `execSync` with one literal command string |
+| `JSON.stringify(x).includes(winPath)` | **Windows** — stringify escapes `\\` to `\\\\` | assert on parsed values, never on JSON text |
 
 ## Measured, not assumed
 

package/scripts/install/register-hooks.js

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * Register ECC's hooks into a Claude-compatible settings.json.
+ *
+ * Why this exists
+ * ---------------
+ * `install.sh` copied `hooks/hooks.json` into `<target>/hooks/hooks.json` and
+ * stopped there. Claude Code does not read that file — it reads `hooks` out of
+ * `settings.json`. So every hook ECC ships was placed on disk and never
+ * activated: memory inject (SessionStart), memory capture and correction
+ * encoding (Stop), the prompt-injection guard, the token-budget enforcer.
+ *
+ * The only entry that ever appeared in settings.json came from RTK's own
+ * installer, which writes that file for its own hook.
+ *
+ * A correct merge already existed in scripts/lib/install/apply.js, but the CLI
+ * shells out to install.sh and never reaches it. This script is the bridge:
+ * install.sh calls it, and it uses that same tested merge.
+ *
+ * Guarantees
+ * ----------
+ * - Idempotent. Re-running adds nothing; entries dedupe by content signature.
+ * - Non-destructive. Hooks already in settings.json are kept, including
+ *   another tool's (RTK's) and the user's own.
+ * - Scoped. Only the `hooks` key is touched; every other setting is preserved.
+ * - Atomic. Written via a temp file and rename, so an interrupted install
+ *   cannot leave a truncated settings.json — which would break the editor.
+ *
+ * Usage:  node scripts/install/register-hooks.js <targetRoot> [hooksJsonPath]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { mergeHookEntries } = require('../lib/install/apply.js');
+const { replaceFilePreservingMode } = require('../lib/safe-fs.js');
+
+function readJsonOrNull(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} targetRoot      e.g. ~/.claude
+ * @param {string} [hooksJsonPath] defaults to <targetRoot>/hooks/hooks.json
+ * @returns {{status:string, events:number, added:number, total:number, settingsPath:string}}
+ */
+function registerHooks(targetRoot, hooksJsonPath) {
+  if (!targetRoot) throw new Error('registerHooks: targetRoot is required');
+
+  const hooksPath = hooksJsonPath || path.join(targetRoot, 'hooks', 'hooks.json');
+  const config = readJsonOrNull(hooksPath);
+  if (!config) {
+    return { status: 'no-hooks-config', events: 0, added: 0, total: 0, settingsPath: '' };
+  }
+
+  const incoming = config.hooks && typeof config.hooks === 'object' && !Array.isArray(config.hooks)
+    ? config.hooks
+    : null;
+  if (!incoming) {
+    return { status: 'invalid-hooks-config', events: 0, added: 0, total: 0, settingsPath: '' };
+  }
+
+  const settingsPath = path.join(targetRoot, 'settings.json');
+  const settings = readJsonOrNull(settingsPath) || {};
+  const existing = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
+    ? settings.hooks
+    : {};
+
+  const before = countEntries(existing);
+  const merged = { ...existing };
+
+  for (const [event, entries] of Object.entries(incoming)) {
+    const current = Array.isArray(existing[event]) ? existing[event] : [];
+    const next = Array.isArray(entries) ? entries : [];
+    // targetRoot is the plugin root: hooks.json references
+    // ${CLAUDE_PLUGIN_ROOT}/scripts/hooks/... which resolves under it.
+    merged[event] = mergeHookEntries(current, next, targetRoot);
+  }
+
+  const after = countEntries(merged);
+  const body = JSON.stringify({ ...settings, hooks: merged }, null, 2) + '\n';
+
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  // Keeps the file's existing permissions when it is already there — this is a
+  // user config and the installer has no business widening or narrowing it.
+  // 0o600 for a new one: settings.json can carry tokens.
+  replaceFilePreservingMode(settingsPath, body, 0o600);
+
+  return {
+    status: 'ok',
+    events: Object.keys(merged).length,
+    added: after - before,
+    total: after,
+    settingsPath,
+  };
+}
+
+function countEntries(hooksObject) {
+  let n = 0;
+  for (const entries of Object.values(hooksObject || {})) {
+    if (Array.isArray(entries)) {
+      for (const entry of entries) n += Array.isArray(entry.hooks) ? entry.hooks.length : 1;
+    }
+  }
+  return n;
+}
+
+module.exports = { registerHooks, countEntries };
+
+if (require.main === module) {
+  const [targetRoot, hooksJsonPath] = process.argv.slice(2);
+  if (!targetRoot) {
+    console.error('usage: node scripts/install/register-hooks.js <targetRoot> [hooksJsonPath]');
+    process.exit(2);
+  }
+  try {
+    const r = registerHooks(targetRoot, hooksJsonPath);
+    if (r.status !== 'ok') {
+      // Not fatal: a target without a hooks config is a valid configuration.
+      console.error(`hooks not registered (${r.status})`);
+      process.exit(0);
+    }
+    console.log(`${r.total} hook entries across ${r.events} events (+${r.added} new)`);
+  } catch (err) {
+    // An install must not die here. Report loudly and let the rest complete —
+    // but exit non-zero so a caller that checks can surface it.
+    console.error(`hook registration failed: ${err.message}`);
+    process.exit(1);
+  }
+}

package/scripts/lib/install/apply.js

@@ -261,5 +261,10 @@ function applyInstallPlan(plan) {
 }
 
 module.exports = {
+  // Exported so the shell installer can register hooks through the same tested
+  // merge as the JS install path — install.sh copied hooks.json but never wrote
+  // settings.json, so none of the hooks were ever active (fixed in 2.21.0).
+  mergeHookEntries,
+  replacePluginRootPlaceholders,
   applyInstallPlan,
 };