kodelyth-ecc 2.19.0 → 2.21.0

package/CHANGELOG.md

@@ -2,6 +2,203 @@
 
 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
+2,570 files that do not belong to the package.
+
+### What happened
+
+Testing all 13 install targets meant running the 9 project-scoped ones, and
+project-scoped targets write into the directory you are standing in — which was
+the repo root. `git add -A` then swept the lot into the release commit:
+
+```
+.roo 488 · .kimi 488 · .aider-ecc 488 · .gemini 388 · .cursor 315
+.agent 194 · .clinerules 189 · .opencode 17 · + 3 stray files
+```
+
+```
+              files   unpacked
+2.18.0          794     5.01 MB
+2.19.0        3,364    20.89 MB    ← 4.2x
+2.20.0          796     4.80 MB    ← 2.18.0 + 2 new source files
+```
+
+Nothing caught it. Tests passed, CI was green, the version published. The only
+signal was the tarball size and nothing was watching it.
+
+### The guards
+
+Three, because the first two fail open:
+
+1. **`files` allowlist in package.json** — an allowlist excludes a new stray
+   directory by default. `.npmignore` alone is a denylist: it only stops what
+   someone thought to name. Note that `files` *overrides* `.npmignore`, so the
+   exclusions that file already encoded are restated as negations — adding an
+   allowlist without them silently starts shipping content someone had
+   deliberately excluded (it re-added 12 files here before that was caught).
+2. **`.gitignore`** for all 11 install-target outputs.
+3. **7 packaging tests** that pack the real tarball and assert on it — no
+   install-target output, no nested test fixtures, the bin entrypoint present,
+   and file count and size inside a band around the 2.18.0 baseline. Verified by
+   recreating the exact failure: with the allowlist, 24 planted stray files pack
+   as 0; without it, 24 pack and the tests go red.
+
+Worth stating plainly: these packaging tests broke Windows CI twice before they
+worked, which is itself the lesson. Spawning npm from Node on Windows has no
+obvious correct form:
+
+```
+execFileSync('npm', [...])      → ENOENT   npm is npm.cmd; no PATHEXT without a shell
+execFileSync('npm.cmd', [...])  → EINVAL   Node 18.20.2+ refuses .cmd/.bat without shell
+execFileSync(..., shell: true)  → works, but DEP0190: args are concatenated, not escaped
+execSync('npm pack ...')        → works, no deprecation
+```
+
+The first two were observed on this repo's CI one commit apart — the same class
+of defect the scanner below exists to catch, shipped inside the scanner's own
+companion test. Windows now goes through `execSync` with a single literal
+command string; POSIX still uses an argv array with no shell.
+
+Where npm or git genuinely cannot be spawned, the affected tests report why and
+skip instead of going red. A guard that fails for an unrelated reason gets
+disabled, and then it guards nothing. Both paths verified: full environment 7/7
+pass, npm and git hidden 2 pass and 5 skip with a stated reason.
+
+### Added — portability enforcement
+
+`npm run portability` scans the shipped markdown for shell constructs that break
+on a platform other than the author's, and the same scan runs as a test, so the
+corpus cannot regress.
+
+11 rules, each carrying the evidence it was derived from — measured on a stock
+macOS shell, not read off a man page. Two were found while writing it:
+
+- **macOS `mktemp` ignores `$TMPDIR`.** The process receives the variable and
+  Node and Python both honour it; `mktemp` uses `/var/folders/…` regardless. A
+  harness that sets `TMPDIR` to isolate itself isolates its Node and Python and
+  not its shell.
+- **`zsh` does not word-split an unquoted expansion; `bash` does.** macOS
+  defaults to zsh, so `for d in $DIRS` runs **once** on a Mac and N times on
+  Linux. This bit during this very release: a cleanup loop reported success for
+  work it never did.
+
+Also fixed: `grep -c` prints `0` but exits `1` on no matches, so under `set -e`
+a "count the failures" line kills the script on the outcome you wanted.
+
+### Fixed — 21 files across agents, commands and skills
+
+`git-rescue` had a real data-loss bug. Its pre-rescue snapshot was:
+
+```bash
+git reflog --all >  /tmp/reflog-$(date +%s).txt
+git stash list   >> /tmp/reflog-$(date +%s).txt
+```
+
+`$(date +%s)` runs twice. Straddle a second boundary and the append lands in a
+different file from the one the redirect created — so the stash list silently
+goes somewhere other than the snapshot, in the agent whose entire job is not
+losing your work. Reproduced, then replaced with one timestamp, one file,
+written into the repo rather than a temp dir a reboot can clear.
+
+Everything else: hardcoded `/tmp` (absent on Windows) across 12 files,
+`/usr/local/bin` (Intel-Homebrew only — Apple Silicon uses `/opt/homebrew`),
+20 unguarded `rg` invocations in `security-reviewer` that would have reported a
+clean codebase on any machine without ripgrep installed, and PowerShell forms
+plus secret-manager alternatives for `commands/jira.md`, which was telling
+people to paste an API token straight into shell history.
+
+### Corrected
+
+`CLAUDE.md` claimed 604 tests across 32 files. The 604 was current; the 32 was
+stale by seven. Now 633 across 41, and the hook count is stated exactly (44
+entries over 8 events, 9 scripts) rather than as "22+".
+
+**633 tests passing.**
+
 ## v2.19.0 — The install docs were wrong; every command is now tested (September 2026)
 
 The install instructions were checked by **running every command they advertise**

package/CLAUDE.md

@@ -9,7 +9,7 @@ Guidance for Claude Code when working with this repository.
 - **70 specialist agents** — debug-detective, incident-commander, load-tester, image-architect, kodelyth-memory, security-reviewer, plus 8 adversarial devil-mode agents
 - **196 skills** — domain knowledge, patterns, testing, security, intent routing, local memory, swarm orchestration, MCP integration
 - **103 commands** — slash workflows (`/tdd`, `/plan`, `/code-review`, `/team-review`, `/devil-mode`, `/debug-blitz`, `/security-audit`, ...)
-- **22+ hooks** — quality gates, memory inject + capture, correction encoding, prompt-injection guard, token-budget enforcer
+- **44 hook entries** across 8 events — quality gates, memory inject + capture, correction encoding, prompt-injection guard, token-budget enforcer
 - **15 rules** — always-on coding standards + semantic intent routing + memory protocol + self-improvement
 
 Works with Claude Code, Windsurf, Cursor, Codex CLI, Antigravity, OpenCode, Cline, Roo Code, Aider, Kimi, and Gemini CLI — **11 platforms** (13 install targets).
@@ -20,13 +20,13 @@ Works with Claude Code, Windsurf, Cursor, Codex CLI, Antigravity, OpenCode, Clin
 agents/      → 70 specialist subagents (planner, code-reviewer, debug-detective, devil-mode crew, ...)
 commands/    → 103 slash commands (8 parallel multi-agent, 1 adversarial loop, rest single-agent)
 skills/      → 196 workflow + domain knowledge files (loadable via slash commands)
-hooks/       → 22+ automations (pre-commit, session memory, prompt-injection guard, token-budget)
+hooks/       → 44 hook entries across 8 events, 9 scripts (memory inject/capture, prompt-injection guard, token-budget)
 rules/       → 15 always-on guidelines (agent-intent-routing, self-improvement, memory-protocol, ...)
 scripts/     → Node.js utilities: MCP server, dashboard, swarm, replay, router, memory, supply-chain
 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/       → 604 passing tests across 32 test files
+tests/       → 647 passing tests across 42 test files
 ```
 
 ## Running Tests

package/VERSION

@@ -1 +1 @@
-2.19.0
+2.21.0

package/agents/chaos-engineer.md

@@ -119,8 +119,11 @@ stress-ng --vm 4 --vm-bytes 80% --timeout 60s
 # Hypothesis: every endpoint validates its inputs and never panics/500s on malformed.
 # Tooling: ffuf, restler, schemathesis
 
+# The hypothesis database is what makes a re-run reproduce the failing input it
+# found last time. Keep it in the repo, not a temp dir — a reboot that wipes
+# /tmp throws away the shrunk counterexample you were about to debug.
 schemathesis run https://api.localhost/openapi.json --checks all --hypothesis-deadline 5000 \
-  --hypothesis-database /tmp/fuzz-state
+  --hypothesis-database .hypothesis/fuzz-state
 
 # Watch: 500 errors, panics, timeouts, memory leaks
 ```
@@ -144,10 +147,13 @@ wait
 
 ```bash
 # Hypothesis: app rotates certs 30 days before expiration.
-# Tooling: faketime
-faketime '+89 days' /usr/local/bin/your-app
+# Tooling: faketime (libfaketime). Resolve the binary rather than hardcoding a
+# prefix — /usr/local/bin is Intel-Homebrew only; Apple Silicon uses
+# /opt/homebrew/bin, and a Linux package manager uses /usr/bin.
+APP=$(command -v your-app) || { echo "your-app not on PATH"; exit 1; }
+faketime '+89 days' "$APP"
 # Watch: rotation event, cert refresh
-faketime '+91 days' /usr/local/bin/your-app
+faketime '+91 days' "$APP"
 # Watch: expiration handling, alert fires
 ```
 

package/agents/flake-hunter.md

@@ -39,13 +39,19 @@ You are Flake Hunter — the engineer who has debugged the test that fails 1 in
 ### Phase 1 — Get a flake rate
 
 ```bash
-# Run the suspect test 100 times and count failures
+# Run the suspect test 100 times and count failures.
+# Bare mktemp writes to whatever temp location the platform actually has
+# (/var/folders/... on macOS, /tmp on Linux), so it works everywhere a
+# hardcoded /tmp does not — Windows included. Note: macOS mktemp IGNORES
+# $TMPDIR (measured), so do not try to redirect it that way.
+LOG=$(mktemp)
 for i in $(seq 1 100); do
   <test command for this test> --silent || echo "FAIL $i"
-done | tee /tmp/flake-runs.log
+done | tee "$LOG"
 
-# Count
-grep -c FAIL /tmp/flake-runs.log
+# Count. `grep -c` exits 1 when the count is zero, so guard it or a
+# `set -e` script dies on the good outcome.
+grep -c FAIL "$LOG" || echo 0
 ```
 
 If 0/100 fails locally but it fails on CI: the environment is part of the flake. Move to Phase 2 with that constraint.

package/agents/gan-evaluator.md

@@ -200,10 +200,15 @@ Take screenshots only, analyze visually. Less thorough but works without MCP.
 For APIs/libraries: run tests, check build, analyze code quality. No browser.
 
 ```bash
-# Code-only evaluation
-npm run build 2>&1 | tee /tmp/build-output.txt
-npm test 2>&1 | tee /tmp/test-output.txt
-npx eslint . 2>&1 | tee /tmp/lint-output.txt
+# Code-only evaluation. Bare mktemp -d resolves to the platform's real temp
+# location, so this runs unchanged on macOS, Linux and Git Bash; a hardcoded
+# /tmp does not exist on Windows. Echo the path — on macOS it is under
+# /var/folders/... and you will not guess it.
+OUT=$(mktemp -d)
+npm run build 2>&1 | tee "$OUT/build.txt"
+npm test      2>&1 | tee "$OUT/test.txt"
+npx eslint .  2>&1 | tee "$OUT/lint.txt"
+echo "evaluation output: $OUT"
 ```
 
 Score based on: test pass rate, build success, lint issues, code coverage, API response correctness.

package/agents/git-rescue.md

@@ -29,11 +29,20 @@ Before any rescue command:
 
 ```bash
 # Make a safety branch from HEAD's current state — costs nothing
-git branch backup/rescue-$(date +%s)
-
-# Capture the full reflog — your map back home
-git reflog --all > /tmp/reflog-$(date +%s).txt
-git stash list >> /tmp/reflog-$(date +%s).txt
+STAMP=$(date +%Y%m%d-%H%M%S)
+git branch "backup/rescue-$STAMP"
+
+# Capture the full reflog — your map back home.
+# Write it INSIDE the repo, not a temp dir: a rescue snapshot that a reboot
+# can delete is not a snapshot. Add the file to .git/info/exclude if the
+# working tree must stay clean.
+SNAPSHOT="git-rescue-$STAMP.txt"
+{
+  echo "=== reflog --all ==="; git reflog --all
+  echo; echo "=== stash list ==="; git stash list
+  echo; echo "=== branches ==="; git branch -avv
+} > "$SNAPSHOT"
+echo "snapshot: $SNAPSHOT"
 ```
 
 ### Phase 1 — Diagnose

package/agents/license-violation-finder.md

@@ -39,16 +39,18 @@ Real-world risks you hunt:
 ### 1. Inventory all dependency licenses
 
 ```bash
-# Node
-npx license-checker --json --production > /tmp/licenses.json
+# Node. Write the report into the repo, not a temp dir — a compliance
+# artifact you intend to attach to a review should survive a reboot.
+npx license-checker --json --production > licenses.json
 npx license-checker --summary
 
 # Python
 pip-licenses --format=json
 pip-licenses --summary
 
-# Go
-go-licenses report ./... --template /tmp/template.tpl
+# Go (--template takes a path to a Go text/template you supply; point it at a
+# file in the repo so the command is reproducible for the next person)
+go-licenses report ./... --template ./licenses.tpl
 
 # Rust
 cargo about generate about.hbs

package/agents/security-reviewer.md

@@ -23,6 +23,17 @@ You are an expert security specialist focused on identifying and remediating vul
 You are a hunter, not a passive reviewer. On any security task, sweep the codebase with these before reasoning. Each is copy-paste ready (ripgrep; fall back to `grep -rn` if `rg` is absent). Triage every hit — most are real, some are false positives (see that section).
 
 ```bash
+# ripgrep is NOT preinstalled on macOS, Linux or Windows. Check first, or every
+# scan below silently reports nothing and you conclude the code is clean.
+command -v rg >/dev/null || {
+  echo "ripgrep missing — install it:"
+  echo "  macOS:   brew install ripgrep"
+  echo "  Debian:  apt install ripgrep"
+  echo "  Windows: winget install BurntSushi.ripgrep.MSVC"
+  echo "Or substitute 'grep -rEn' for 'rg -n' below and drop the --glob flags"
+  echo "(use --exclude/--exclude-dir instead)."
+}
+
 # ── Dependency + lint baseline ──────────────────────────────────────────────
 npm audit --audit-level=high 2>/dev/null || pnpm audit || yarn audit
 npx eslint . --plugin security --quiet 2>/dev/null

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/commands/jira.md

@@ -84,10 +84,26 @@ Add `jira` to your `mcpServers` config (see `mcp-configs/mcp-servers.json` for t
 
 **Option B — Environment variables:**
 ```bash
+# macOS/Linux
 export JIRA_URL="https://yourorg.atlassian.net"
 export JIRA_EMAIL="your.email@example.com"
 export JIRA_API_TOKEN="your-api-token"
 ```
+```powershell
+# Windows PowerShell
+$env:JIRA_URL       = "https://yourorg.atlassian.net"
+$env:JIRA_EMAIL     = "your.email@example.com"
+$env:JIRA_API_TOKEN = "your-api-token"
+```
+
+Typing the token directly writes it to your shell history in plaintext, where
+it stays until the history file rolls over. Put it in a `.env` the shell sources
+(and that `.gitignore` covers), or read it from a secret manager:
+
+```bash
+export JIRA_API_TOKEN=$(op read "op://Private/Jira/token")   # 1Password
+export JIRA_API_TOKEN=$(security find-generic-password -w -s jira)  # macOS Keychain
+```
 
 If credentials are missing, stop and direct the user to set them up.
 

package/commands/santa-loop.md

@@ -80,7 +80,10 @@ command -v gemini >/dev/null 2>&1 && echo "gemini" || true
 
 Build the reviewer prompt (identical rubric + instructions as Reviewer A) and write it to a unique temp file:
 ```bash
-PROMPT_FILE=$(mktemp /tmp/santa-reviewer-b-XXXXXX.txt)
+# No path argument: mktemp resolves the platform's own temp location, which
+# exists on macOS, Linux and Git Bash. A literal /tmp template fails outright
+# on Windows.
+PROMPT_FILE=$(mktemp)
 cat > "$PROMPT_FILE" << 'EOF'
 ... full rubric + file contents + reviewer instructions ...
 EOF

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.19.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",
@@ -62,12 +62,42 @@
   },
   "scripts": {
     "test": "node tests/run-all.js",
-    "mcp": "node scripts/mcp/server.js"
+    "mcp": "node scripts/mcp/server.js",
+    "portability": "node scripts/portability/scan.js agents commands skills hooks rules scripts"
   },
   "optionalDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4"
   },
   "engines": {
     "node": ">=18.0.0"
-  }
+  },
+  "files": [
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "CLAUDE.md",
+    "CONTRIBUTING.md",
+    "GITHUB_SETUP.md",
+    "KODELYTH.md",
+    "SECURITY.md",
+    "SOUL.md",
+    "VERSION",
+    "install.ps1",
+    "install.sh",
+    "actions/",
+    "agents/",
+    "bin/",
+    "bundles/",
+    "commands/",
+    "contexts/",
+    "hooks/",
+    "rules/",
+    "scripts/",
+    "skills/",
+    "tasks/",
+    "wiki/",
+    "!scripts/openclaw-twitter/",
+    "!**/tests/",
+    "!**/*.log",
+    "!**/.DS_Store"
+  ]
 }

package/rules/common/shell-portability.md

@@ -23,6 +23,54 @@ Every row below was checked on a stock macOS shell. These are not theoretical.
 | `rg` | **any OS** — ripgrep is not preinstalled | `grep -rn` |
 | `date -d` | **macOS/BSD** | `date -j` on BSD, or do date math in the language |
 | `find -printf` | **macOS/BSD** | `find ... -exec stat ...` or `-print0 \| xargs` |
+| `TMPDIR=x mktemp` | **macOS** — mktemp ignores TMPDIR entirely | pass a template path, or use the runtime's tempdir |
+| `/tmp/foo` hardcoded | **Windows** — no /tmp | bare `mktemp` / `mktemp -d`, or `os.tmpdir()` |
+| `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
+
+The `TMPDIR` row above surprised us, so here is the evidence. On macOS the
+subprocess receives the variable and every runtime honours it — but `mktemp`
+does not:
+
+```bash
+$ env TMPDIR=/tmp/probe sh -c 'echo $TMPDIR'
+/tmp/probe                                     # the process sees it
+$ env TMPDIR=/tmp/probe sh -c 'mktemp'
+/var/folders/90/.../T/tmp.AlQWd6r4T9           # mktemp ignores it
+$ env TMPDIR=/tmp/probe node -e 'console.log(require("os").tmpdir())'
+/tmp/probe                                     # Node honours it
+$ env TMPDIR=/tmp/probe python3 -c 'import tempfile;print(tempfile.gettempdir())'
+/tmp/probe                                     # Python honours it
+```
+
+The practical consequence: a test harness that sets `TMPDIR` to isolate itself
+will isolate its Node and Python code but **not** its shell `mktemp` calls. If
+isolation matters, pass an explicit template path to `mktemp` rather than
+setting the variable and trusting it.
+
+`grep -c` is the other one worth internalising: it prints `0` and exits `1` when
+nothing matches. Under `set -e`, a "count the failures" line kills the script on
+the outcome you were hoping for.
+
+### The one that cost us a release
+
+`zsh` does not word-split an unquoted parameter expansion. `bash` does. macOS
+has defaulted to zsh since Catalina, so the same loop does two different things:
+
+```bash
+$ zsh  -c 'V="a b c"; for d in $V; do echo "[$d]"; done'
+[a b c]                      # one iteration
+$ bash -c 'V="a b c"; for d in $V; do echo "[$d]"; done'
+[a] [b] [c]                  # three iterations
+```
+
+The failure is quiet. A cleanup loop written this way runs once against a
+nonsense path, every command inside it succeeds, and the script reports done
+having removed nothing. Write the list literally, or use a real array.
 
 ## Before running a tool that may be absent