kodelyth-ecc 2.18.0 → 2.20.0

package/CHANGELOG.md

@@ -2,6 +2,173 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## 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**
+against a throwaway `HOME` and a throwaway working directory. Three of them did
+not work.
+
+### Fixed — commands that failed
+
+| Documented | What actually happened |
+|---|---|
+| `--target cursor` | **`Unknown target: cursor`** — the real id is `cursor-project` |
+| `mcp-register --status` | **`unknown subcommand`** — the real command is `mcp-list` |
+| "759 shipped files" | the real dry-run total is **777**, and every row of the table was wrong |
+
+Anyone following the Cursor instruction hit a hard error. Anyone following the
+verify step hit another.
+
+### Added — the distinction that was never explained
+
+Targets install to one of two places, and the docs never said which:
+
+- **Home-scoped** (`claude-code`, `codex-home`, `windsurf-home`, `gemini-home`) —
+  run from anywhere, applies machine-wide.
+- **Project-scoped** (`cursor-project`, `antigravity`, `windsurf-project`,
+  `gemini-project`, `opencode`, `cline`, `roocode`, `aider`, `kimi`) — writes into
+  the directory you are standing in. Run one from your home folder and ECC files
+  scatter there instead of into your project.
+
+The scope of each was determined by running the installer and counting where the
+files landed, not by reading the source. Two targets that existed but were never
+documented — `windsurf-project` and `gemini-project` — are now listed.
+
+### Changed — the install page
+
+Restructured into three numbered steps, with `kodelythecc doctor` as the single
+verification command instead of five separate status calls (the individual ones
+are still there, behind a disclosure). Adds the thing that trips people up most:
+**restart your AI tool** — it reads the config directory at startup, so a running
+session sees none of it. Ends with the support channels, since a failed install
+is exactly when someone needs them.
+
+### Corrected — the uninstall table
+
+Every row was stale. Regenerated from a live dry-run on a fresh install:
+
+```
+agents 70 · skills 302 · commands 103 · hooks 12 · rules 106 · scripts 184
+total 777   (was documented as 759)
+```
+
+**604 tests passing.**
+
 ## v2.18.0 — Support channels, shell portability, honest counts (September 2026)
 
 ### Added — Support

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

package/README.md

@@ -573,7 +573,7 @@ Type `kodelythecc` alone in a real terminal → arrow-key menu opens.
 
 ### Uninstall
 
-The menu's **Uninstall ECC completely** row runs an interactive full cleanup: removes the 759 ECC-installed files from `~/.claude/`, unwires RTK from your AI tool, removes codebase-memory-mcp agent configs, removes ECC's MCP entry from Claude Code + Claude Desktop, and deletes `~/.kodelythecc/` (memory + ledgers). Prompts confirm before anything is deleted; a dry-run mode previews what would be removed without touching anything.
+The menu's **Uninstall ECC completely** row runs an interactive full cleanup: removes the 777 ECC-installed files from `~/.claude/`, unwires RTK from your AI tool, removes codebase-memory-mcp agent configs, removes ECC's MCP entry from Claude Code + Claude Desktop, and deletes `~/.kodelythecc/` (memory + ledgers). Prompts confirm before anything is deleted; a dry-run mode previews what would be removed without touching anything.
 
 You can also run it non-interactively:
 

package/VERSION

@@ -1 +1 @@
-2.18.0
+2.20.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.18.0",
+  "version": "2.20.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,53 @@ 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 |
+
+## 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
 

package/rules/shell-portability.md

@@ -23,6 +23,53 @@ 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 |
+
+## 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
 

package/scripts/portability/rules.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Shell-portability rules for the shipped markdown corpus.
+ *
+ * Every rule below corresponds to a difference that was MEASURED on a stock
+ * macOS shell, not inferred from a man page. The `evidence` field records what
+ * was actually observed, so a future maintainer can re-verify rather than
+ * trust the comment.
+ *
+ * Scope: these apply to shell text only — fenced code blocks tagged as a shell
+ * (or untagged) and inline code spans. Prose is never scanned, because
+ * "we set a timeout of 30s" is not a portability defect.
+ */
+
+const RULES = [
+  {
+    id: 'gnu-timeout',
+    re: /(^|[;|&\s])timeout\s+\d/,
+    why: '`timeout` is GNU coreutils and is not installed on macOS',
+    fix: 'drop it, or `command -v timeout || gtimeout`',
+    evidence: 'macOS 25.5: `command -v timeout` → empty',
+  },
+  {
+    id: 'gnu-stat-c',
+    re: /\bstat\s+(?:-[a-zA-Z]+\s+)*-c\b/,
+    why: '`stat -c` is GNU; BSD stat uses -f',
+    fix: '`wc -c < file` works on both',
+    evidence: 'macOS: `stat -c %s f` → "stat: illegal option -- c"',
+  },
+  {
+    id: 'gnu-sed-i',
+    re: /\bsed\s+(?:-[a-zA-Z]*\s+)*-i\s+(?!['"])/,
+    why: '`sed -i` requires an explicit backup suffix on BSD',
+    fix: "`sed -i '' 's/a/b/' f` on BSD, or write to a temp file and mv",
+    evidence: 'macOS: `sed -i s/a/b/ f` → "invalid command code"',
+  },
+  {
+    id: 'gnu-grep-p',
+    re: /\bgrep\s+(?:-[a-zA-Z]+\s+)*-[a-zA-Z]*P\b/,
+    why: '`grep -P` needs PCRE, absent from BSD grep',
+    fix: '`grep -E` with a POSIX class',
+    evidence: 'macOS: `grep -P` → "this version does not support -P"',
+  },
+  {
+    id: 'gnu-readlink-f',
+    re: /\breadlink\s+-f\b/,
+    why: '`readlink -f` is absent on older BSD',
+    fix: '`cd "$(dirname "$f")" && pwd -P`',
+    evidence: 'documented BSD difference; present on macOS 25 but not portable back',
+  },
+  {
+    id: 'gnu-date-d',
+    re: /\bdate\s+-d\b/,
+    why: '`date -d` is GNU; BSD date uses -j -f',
+    fix: 'do date math in the language runtime instead',
+    evidence: 'macOS: `date -d yesterday` → "illegal time format"',
+  },
+  {
+    id: 'gnu-find-printf',
+    re: /\bfind\b[^\n`]*-printf\b/,
+    why: '`-printf` is GNU find only',
+    fix: '`-print0 | xargs -0`, or `-exec`',
+    evidence: 'macOS: `find . -printf %p` → "unknown primary or operator"',
+  },
+  {
+    id: 'assumes-ripgrep',
+    re: /(^|[;|&\s])rg\s+[^\n`]/,
+    why: 'ripgrep is not preinstalled on macOS, Linux or Windows',
+    fix: 'guard with `command -v rg` and fall back to grep/find',
+    guardedBy: 'rg', // one `command -v rg` anywhere in the file clears the file
+    evidence: 'not present in any default install image',
+  },
+  {
+    id: 'hardcoded-tmp',
+    re: /(^|[\s;|&="'(>])\/tmp\//,
+    why: 'there is no /tmp on Windows',
+    fix: 'bare `mktemp` / `mktemp -d`, or the runtime tempdir',
+    evidence: 'Windows has %TEMP%; /tmp does not exist',
+  },
+  {
+    id: 'homebrew-prefix',
+    re: /(^|[\s;|&="'(])\/usr\/local\/bin\//,
+    why: '/usr/local/bin is Intel-Homebrew only — Apple Silicon uses /opt/homebrew',
+    fix: '`$(command -v tool)`',
+    evidence: 'Apple Silicon default prefix is /opt/homebrew',
+  },
+  {
+    // Hit live while writing this file: a cleanup loop silently ran once
+    // instead of eleven times, and reported success for work it never did.
+    id: 'zsh-word-splitting',
+    re: /\bfor\s+\w+\s+in\s+\$[A-Za-z_][A-Za-z0-9_]*\s*;?\s*do\b/,
+    why: 'zsh does not word-split an unquoted expansion; bash does — macOS defaults to zsh',
+    fix: 'list the items literally, or use an array: `for d in "${ARR[@]}"`',
+    evidence: 'measured: `V="a b c"; for d in $V` → 1 iteration in zsh, 3 in bash',
+  },
+  {
+    id: 'grep-c-under-set-e',
+    re: /(^|[;|&\s])grep\s+(?:-[a-zA-Z]+\s+)*-[a-zA-Z]*c\b(?![^\n]*\|\|)/,
+    why: '`grep -c` exits 1 on a zero count, killing a `set -e` script on the good outcome',
+    fix: 'append `|| echo 0`',
+    evidence: 'measured: `grep -c X empty` prints 0, exits 1',
+  },
+];
+
+module.exports = { RULES };

package/scripts/portability/scan.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { RULES } = require('./rules.js');
+
+const SHELL_LANGS = new Set(['', 'bash', 'sh', 'shell', 'zsh', 'console', 'terminal']);
+
+/**
+ * Extract only the executable-looking regions of a markdown file.
+ *
+ * Prose is deliberately excluded. A sentence like "we raised the timeout to 30"
+ * is not a portability defect, and flagging it trains people to ignore the
+ * scanner — which is worse than not having one.
+ */
+function shellLines(src) {
+  const out = [];
+  let m;
+
+  const fence = /```(\w*)\n([\s\S]*?)```/g;
+  while ((m = fence.exec(src)) !== null) {
+    if (SHELL_LANGS.has((m[1] || '').toLowerCase())) out.push(...m[2].split('\n'));
+  }
+
+  const inline = /`([^`\n]+)`/g;
+  while ((m = inline.exec(src)) !== null) out.push(m[1]);
+
+  return out;
+}
+
+/**
+ * A line that is itself teaching the anti-pattern is not a violation.
+ * The shell-portability rule documents `timeout 30 npm test` as the WRONG form;
+ * flagging its own documentation would make the scanner permanently red.
+ */
+function isTeachingExample(line) {
+  return /^\s*#/.test(line) || /\bWRONG\b|\bBreaks on\b|not installed|illegal option/i.test(line);
+}
+
+/**
+ * A line that CHECKS for a tool is the fix, not the defect. Without this the
+ * scanner flags its own recommended remedy, which is the fastest way to teach
+ * people that the scanner is wrong.
+ */
+function isGuard(line) {
+  return /command\s+-v\s+\S+|which\s+\S+\s*>\/dev\/null|\|\|\s*(echo|gtimeout|true)/.test(line);
+}
+
+/** A bare command name in prose backticks — `grep -c` — is a reference, not a call. */
+function isBareMention(line) {
+  return /^[a-z-]+(\s+-{1,2}[a-zA-Z-]+)*$/.test(line.trim());
+}
+
+function walk(dir, acc = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    if (e.isSymbolicLink()) continue; // never follow — a link out of the tree escapes scope
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name !== 'node_modules' && e.name !== '.git') walk(p, acc);
+    } else if (e.name.endsWith('.md')) {
+      acc.push(p);
+    }
+  }
+  return acc;
+}
+
+/**
+ * @param {string[]} dirs      directories to scan
+ * @param {object}   [opts]
+ * @param {string[]} [opts.exclude]  path substrings to skip entirely
+ * @returns {{file:string, rule:string, why:string, fix:string, line:string}[]}
+ */
+function scan(dirs, opts = {}) {
+  const exclude = opts.exclude || [];
+  const findings = [];
+
+  for (const dir of dirs) {
+    for (const file of walk(dir)) {
+      if (exclude.some((x) => file.includes(x))) continue;
+
+      let src;
+      try {
+        src = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+
+      const lines = shellLines(src);
+
+      // File-level guards. A file that checks for a tool once at the top has
+      // handled it for every later use; flagging those uses individually would
+      // demand a guard on all twenty lines, which nobody would write.
+      const guardedTools = new Set();
+      for (const l of lines) {
+        const m = /command\s+-v\s+([a-z0-9_-]+)/i.exec(l);
+        if (m) guardedTools.add(m[1].toLowerCase());
+      }
+
+      for (const rule of RULES) {
+        if (rule.guardedBy && guardedTools.has(rule.guardedBy)) continue;
+        const hit = lines.find(
+          (l) => !isTeachingExample(l) && !isGuard(l) && !isBareMention(l) && rule.re.test(l)
+        );
+        if (hit) {
+          findings.push({
+            file,
+            rule: rule.id,
+            why: rule.why,
+            fix: rule.fix,
+            line: hit.trim().slice(0, 100),
+          });
+        }
+      }
+    }
+  }
+
+  return findings;
+}
+
+module.exports = { scan, shellLines, isTeachingExample, isGuard, isBareMention, walk };
+
+if (require.main === module) {
+  const dirs = process.argv.slice(2);
+  if (dirs.length === 0) {
+    console.error('usage: node scripts/portability/scan.js <dir> [dir...]');
+    process.exit(2);
+  }
+  const findings = scan(dirs, { exclude: ['shell-portability.md'] });
+  if (findings.length === 0) {
+    console.log(`portability: clean across ${dirs.join(', ')}`);
+    process.exit(0);
+  }
+  for (const f of findings) {
+    console.log(`${f.file}\n  [${f.rule}] ${f.why}\n  fix: ${f.fix}\n  > ${f.line}\n`);
+  }
+  console.log(`${findings.length} portability finding(s)`);
+  process.exit(1);
+}

package/skills/agent-sort/SKILL.md

@@ -62,8 +62,15 @@ Use repo-local evidence before making any classification:
 Useful commands include:
 
 ```bash
-rg --files
-rg -n "typescript|react|next|supabase|django|spring|flutter|swift"
+# ripgrep is not preinstalled anywhere; fall back to find/grep when absent.
+if command -v rg >/dev/null; then
+  rg --files
+  rg -n "typescript|react|next|supabase|django|spring|flutter|swift"
+else
+  find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*'
+  grep -rEn "typescript|react|next|supabase|django|spring|flutter|swift" . \
+    --exclude-dir=node_modules --exclude-dir=.git
+fi
 cat package.json
 cat pyproject.toml
 cat Cargo.toml

package/skills/autonomous-loops/SKILL.md

@@ -514,10 +514,14 @@ evictionContext ─────────────────────
 
 ### Worktree Isolation
 
-Every unit runs in an isolated worktree (uses jj/Jujutsu, not git):
+Every unit runs in an isolated worktree (uses jj/Jujutsu, not git), created
+under the platform's temp directory:
 ```
-/tmp/workflow-wt-{unit-id}/
+$(mktemp -d)/workflow-wt-{unit-id}/
 ```
+Resolve the base once per run and reuse it — hardcoding `/tmp` breaks on
+Windows, and re-resolving it per stage would hand each stage a different
+directory, defeating the shared-state behaviour described below.
 
 Pipeline stages for the same unit **share** a worktree, preserving state (context files, plan files, code changes) across research → plan → implement → test → review.
 

package/skills/configure-ecc/SKILL.md

@@ -25,14 +25,19 @@ This skill must be accessible to Claude Code before activation. Two ways to boot
 
 ## Step 0: Clone ECC Repository
 
-Before any installation, clone the latest ECC source to `/tmp`:
+Before any installation, clone the latest ECC source to a scratch directory:
 
 ```bash
-rm -rf /tmp/kodelyth-ecc
-git clone https://github.com/sifxprime/kodelyth-ecc.git /tmp/kodelyth-ecc
+# mktemp -d resolves the platform's own temp location, so this line is the same
+# on macOS, Linux and Git Bash. A literal /tmp does not exist on Windows.
+ECC_ROOT="$(mktemp -d)/kodelyth-ecc"
+git clone --depth 1 https://github.com/sifxprime/kodelyth-ecc.git "$ECC_ROOT"
 ```
 
-Set `ECC_ROOT=/tmp/kodelyth-ecc` as the source for all subsequent copy operations.
+`$ECC_ROOT` is the source for every copy operation below. Because `mktemp -d`
+returns a fresh directory each time, there is no stale clone to `rm -rf` first —
+which also removes the one line in this skill capable of deleting the wrong
+path if the variable were ever empty.
 
 If the clone fails (network issues, etc.), use `AskUserQuestion` to ask the user to provide a local path to an existing ECC clone.
 
@@ -318,10 +323,13 @@ Options:
 
 ## Step 6: Installation Summary
 
-Clean up the cloned repository from `/tmp`:
+Clean up the cloned repository:
 
 ```bash
-rm -rf /tmp/kodelyth-ecc
+# Guard the expansion. An empty $ECC_ROOT makes this `rm -rf ""`, which is a
+# no-op on the rm we tested — but the same unguarded pattern with a path
+# built by concatenation is how people delete the wrong directory.
+[ -n "$ECC_ROOT" ] && [ -d "$ECC_ROOT" ] && rm -rf "$ECC_ROOT"
 ```
 
 Then print a summary report:

package/skills/dmux-workflows/SKILL.md

@@ -48,7 +48,7 @@ Split research and implementation into parallel tracks:
 ```
 Pane 1 (Research): "Research best practices for rate limiting in Node.js.
   Check current libraries, compare approaches, and write findings to
-  /tmp/rate-limit-research.md"
+  $OUT_DIR/rate-limit-research.md"
 
 Pane 2 (Implement): "Implement rate limiting middleware for our Express API.
   Start with a basic token bucket, we'll refine after research completes."

package/skills/openclaw-persona-forge/SKILL.md

@@ -60,7 +60,7 @@ origin: community
 
 **调用方式**（仅在已安装且已审核时）：
 1. 先将龙虾名字规整为安全片段：仅保留字母、数字和连字符，其余字符统一替换为 `-`
-2. 将提示词写入临时文件 `/tmp/openclaw-<safe-name>-prompt.md`
+2. 将提示词写入临时文件 `$(mktemp -d)/openclaw-<safe-name>-prompt.md`
 3. 使用当前环境允许的生图 skill，传入提示词文件和输出路径
 
 **接口约定**：

package/skills/openclaw-persona-forge/references/avatar-style.md

@@ -84,7 +84,7 @@ The key silhouette recognition points at small size are:
 ### 路径 A：已安装且已审核的生图 skill
 
 1. 先将龙虾名字规整为安全片段：仅保留字母、数字和连字符，其余字符替换为 `-`
-2. 用 Write 工具写入：`/tmp/openclaw-<safe-name>-prompt.md`
+2. 用 Write 工具写入：`$(mktemp -d)/openclaw-<safe-name>-prompt.md`
 3. 调用当前环境允许的生图 skill 生成图片
 4. 用 Read 工具展示生成的图片给用户
 5. 问用户是否满意，不满意可调整变量重新生成

package/skills/session-replay/SKILL.md

@@ -43,7 +43,7 @@ The `--task` / `--agents` / `--harness` / `--base-ref` flags enrich the bundle's
 ```bash
 npx kodelyth-ecc session-import ~/Desktop/oauth-audit.bundle.json
 # or:
-npx kodelyth-ecc session-import oauth-audit.bundle.json --target /tmp/audit-restore --overwrite
+npx kodelyth-ecc session-import oauth-audit.bundle.json --target ./audit-restore --overwrite
 ```
 
 Restores the bundle into a coordination directory. Useful for inspecting handoffs locally before replaying.

package/skills/videodb/reference/capture.md

@@ -1,5 +1,15 @@
 # Capture Guide
 
+All session files live under one directory so a run can be cleaned up in a
+single step, and so nothing assumes `/tmp` exists (it does not on Windows).
+Resolve it once and export it before any command below:
+
+```bash
+export VIDEODB_DIR="${VIDEODB_DIR:-$(mktemp -d)}"
+echo "videodb session: $VIDEODB_DIR"
+```
+
+
 ## Overview
 
 VideoDB Capture enables real-time screen and audio recording with AI processing. Desktop capture currently supports **macOS** only.
@@ -10,7 +20,7 @@ For code-level details (SDK methods, event structures, AI pipelines), see [captu
 
 1. **Start WebSocket listener**: `python scripts/ws_listener.py --clear &`
 2. **Run capture code** (see Complete Capture Workflow below)
-3. **Events written to**: `/tmp/videodb_events.jsonl`
+3. **Events written to**: `$VIDEODB_DIR/events.jsonl`
 
 ---
 
@@ -32,9 +42,9 @@ No webhooks or polling required. WebSocket delivers all events including session
 
 6. **Start the session** with selected channels.
 
-7. **Wait for session active** by reading events until you see `capture_session.active`. This event contains the `rtstreams` array. Save session info (session ID, RTStream IDs) to a file (e.g. `/tmp/videodb_capture_info.json`) so other scripts can read it.
+7. **Wait for session active** by reading events until you see `capture_session.active`. This event contains the `rtstreams` array. Save session info (session ID, RTStream IDs) to a file (e.g. `$VIDEODB_DIR/capture_info.json`) so other scripts can read it.
 
-8. **Keep the process alive.** Use `asyncio.Event` with signal handlers for `SIGINT`/`SIGTERM` to block until explicitly stopped. Write a PID file (e.g. `/tmp/videodb_capture_pid`) so the process can be stopped later with `kill $(cat /tmp/videodb_capture_pid)`. The PID file should be overwritten on every run so reruns always have the correct PID.
+8. **Keep the process alive.** Use `asyncio.Event` with signal handlers for `SIGINT`/`SIGTERM` to block until explicitly stopped. Write a PID file (e.g. `$VIDEODB_DIR/capture.pid`) so the process can be stopped later with `kill $(cat $VIDEODB_DIR/capture.pid)`. The PID file should be overwritten on every run so reruns always have the correct PID.
 
 9. **Start AI pipelines** (in a separate command/script) on each RTStream for audio indexing and visual indexing. Read the RTStream IDs from the saved session info file.
 
@@ -48,7 +58,7 @@ No webhooks or polling required. WebSocket delivers all events including session
 
 12. **Wait for export** by reading events until you see `capture_session.exported`. This event contains `exported_video_id`, `stream_url`, and `player_url`. This may take several seconds after stopping capture.
 
-13. **Stop WebSocket listener** after receiving the export event. Use `kill $(cat /tmp/videodb_ws_pid)` to cleanly terminate it.
+13. **Stop WebSocket listener** after receiving the export event. Use `kill $(cat $VIDEODB_DIR/ws.pid)` to cleanly terminate it.
 
 ---
 
@@ -57,8 +67,8 @@ No webhooks or polling required. WebSocket delivers all events including session
 Proper shutdown order is important to ensure all events are captured:
 
 1. **Stop the capture session** — `client.stop_capture()` then `client.shutdown()`
-2. **Wait for export event** — poll `/tmp/videodb_events.jsonl` for `capture_session.exported`
-3. **Stop the WebSocket listener** — `kill $(cat /tmp/videodb_ws_pid)`
+2. **Wait for export event** — poll `$VIDEODB_DIR/events.jsonl` for `capture_session.exported`
+3. **Stop the WebSocket listener** — `kill $(cat $VIDEODB_DIR/ws.pid)`
 
 Do NOT kill the WebSocket listener before receiving the export event, or you will miss the final video URLs.
 
@@ -83,7 +93,7 @@ python scripts/ws_listener.py --clear &
 python scripts/ws_listener.py --clear /path/to/events &
 
 # Stop the listener
-kill $(cat /tmp/videodb_ws_pid)
+kill $(cat $VIDEODB_DIR/ws.pid)
 ```
 
 **Options:**