create-merlin-brain 5.3.7 → 5.4.0

package/files/commands/merlin/check-size.md

@@ -0,0 +1,152 @@
+---
+name: merlin:check-size
+description: Scan the repo for files exceeding the 400-LOC convention and surface violations
+argument-hint: "[path]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - AskUserQuestion
+  - mcp__merlin__merlin_route
+---
+
+<objective>
+Scan the current repository for files that exceed the 400-LOC project convention.
+Surface violations grouped by severity, identify opt-out markers, and offer to route to
+`code-organization-supervisor` for refactor proposals on the worst offenders.
+</objective>
+
+<context>
+Optional path argument: $ARGUMENTS
+If provided, scan only that directory. Otherwise scan from repo root (cwd).
+</context>
+
+<process>
+
+## Step 1: Discover Code Files
+
+Run a find command to locate all code files, excluding common generated/vendor directories:
+
+```bash
+find "${1:-.}" -type f \( \
+  -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
+  -o -name "*.py" -o -name "*.rs" -o -name "*.go" -o -name "*.sh" \
+  -o -name "*.cjs" -o -name "*.mjs" -o -name "*.swift" -o -name "*.kt" \
+  -o -name "*.java" -o -name "*.rb" -o -name "*.php" -o -name "*.c" \
+  -o -name "*.cpp" -o -name "*.h" -o -name "*.hpp" \
+\) \
+  -not -path "*/node_modules/*" \
+  -not -path "*/dist/*" \
+  -not -path "*/build/*" \
+  -not -path "*/.next/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/coverage/*" \
+  -not -path "*/.vite/*" \
+  -not -path "*/vendor/*" \
+  -not -path "*/__pycache__/*" \
+  2>/dev/null | xargs wc -l 2>/dev/null | awk '$1 > 400 && !/total$/' | sort -rn
+```
+
+Capture the output as VIOLATIONS.
+
+## Step 2: Group by Severity
+
+Parse VIOLATIONS and categorize:
+
+| Tier | LOC Range | Label |
+|------|-----------|-------|
+| Critical | 1000+ | files that urgently need splitting |
+| High | 600-999 | should be refactored soon |
+| Warn | 401-599 | approaching limit, watch closely |
+
+## Step 3: Check for Opt-Out Markers
+
+For each violation, check if the file contains the opt-out marker:
+
+```bash
+grep -l "merlin:allow-large-file:" <file>
+```
+
+Tag files that have the marker with "(justified)" in the output.
+
+## Step 4: Present Report
+
+Output a structured report:
+
+```
+============================================
+ FILE SIZE AUDIT — 400-LOC Convention
+============================================
+
+CRITICAL (1000+ LOC):
+  * path/to/file.ts — 1523 lines
+  * path/to/other.js — 1201 lines
+
+HIGH (600-999 LOC):
+  * path/to/module.py — 812 lines (justified: "generated parser tables")
+
+WARN (401-599 LOC):
+  * path/to/component.tsx — 456 lines
+
+--------------------------------------------
+Total violations: X files
+  - X critical, X high, X warn
+  - X have justification markers
+--------------------------------------------
+```
+
+If no violations found:
+```
+All files are within the 400-LOC convention.
+```
+
+## Step 5: Offer Refactor Help
+
+If there are critical-tier violations (1000+ LOC) without markers, ask:
+
+```
+The following files are critically oversized and lack justification:
+  * path/to/file.ts (1523 lines)
+  * path/to/other.js (1201 lines)
+
+Would you like me to route these to `code-organization-supervisor` for
+a proposed split? (y/n)
+```
+
+If user says yes, route to the agent:
+
+```
+Call: merlin_route
+Agent: code-organization-supervisor
+Task: "Propose a refactor plan to split these oversized files into smaller, focused modules:
+  - <file1>: <LOC> lines
+  - <file2>: <LOC> lines
+
+Each resulting module should be under 400 lines. Provide:
+1. Proposed module boundaries
+2. Which functions/classes go where
+3. Import graph after the split
+4. Step-by-step migration plan"
+```
+
+</process>
+
+<error_handling>
+
+| Condition | Action |
+|-----------|--------|
+| No code files found | Report "No code files found in <path>." |
+| Permission errors | Skip inaccessible files, note count skipped |
+| wc/find unavailable | Fall back to Glob + Read with manual line counting |
+| Path doesn't exist | Report error and suggest checking the path |
+
+</error_handling>
+
+<tips>
+- This command is advisory — it doesn't block anything
+- The PreToolUse hook (`~/.claude/hooks/check-file-size.sh`) does the actual blocking
+- Add `// merlin:allow-large-file: <reason>` to justify genuinely large files
+- Override the limit per-session with `MERLIN_FILE_SIZE_LIMIT=600`
+- Skip all checks with `MERLIN_SKIP_FILE_SIZE_CHECK=1`
+</tips>

package/files/hooks/check-file-size.sh

@@ -1,73 +1,181 @@
 #!/usr/bin/env bash
+# check-file-size.sh — Claude Code PreToolUse hook
 #
-# Merlin Hook: PostToolUse (Write/Edit)
-# Checks if the modified file exceeds the 400-line convention.
-# Exits with code 2 to inject feedback when file is too large.
+# Enforces the 400-LOC project rule. Blocks Edit/Write/MultiEdit when the
+# resulting file would exceed the limit, unless the file contains an opt-out
+# marker (`merlin:allow-large-file: <reason>`).
 #
-# Agent-type awareness: only enforce for implementation agents.
-# Non-code agents (docs, review, verify, etc.) are fully exempt.
+# Contract per hooks-rules.md + Claude Code hooks docs:
+#   - stdin: JSON {tool_name, tool_input, ...}
+#   - block: exit 0 + stdout JSON {"decision":"block","reason":"..."}
+#   - allow: exit 0 + stdout {} (or empty)
+#   - any other exit code is treated as pass; never exit 1 to block
 #
-set -euo pipefail
-trap 'echo "{}"; exit 0' ERR
+# Env opt-outs (allow legitimate overrides):
+#   MERLIN_SKIP_FILE_SIZE_CHECK=1  — skip entirely
+#   MERLIN_FILE_SIZE_LIMIT=N        — override 400 default
 
-# Read CLAUDE_AGENT_TYPE from env — support both var names
-AGENT_TYPE="${CLAUDE_AGENT_TYPE:-${CLAUDE_CODE_AGENT_TYPE:-main}}"
+set -uo pipefail
+# NO `set -e` and NO ERR trap — explicit exit codes only, so a stray non-zero
+# step (e.g. a grep that finds nothing) doesn't accidentally short-circuit the
+# decision.
 
-# Only enforce for implementation agents
-# Skip for all doc/review/verification/analysis agents
-case "$AGENT_TYPE" in
-  implementation-dev|merlin-executor)
-    # Enforcement is active for these agents — continue
-    ;;
-  docs-keeper|merlin-reviewer|merlin-verifier|merlin-milestone-auditor|\
-  merlin-integration-checker|merlin-work-verifier|code-organization-supervisor|\
-  context-guardian|dry-refactor|tests-qa|merlin-codebase-mapper)
-    echo '{}'
-    exit 0
-    ;;
-  *)
-    # For all other agents (including 'main'), skip enforcement
-    echo '{}'
-    exit 0
-    ;;
-esac
+allow() { echo '{}'; exit 0; }
+block() {
+  local reason="$1"
+  # Escape backslashes and double quotes for JSON.
+  local escaped="${reason//\\/\\\\}"
+  escaped="${escaped//\"/\\\"}"
+  escaped="${escaped//$'\n'/\\n}"
+  printf '{"decision":"block","reason":"%s"}\n' "$escaped"
+  exit 0
+}
+
+# Opt-out via env
+[ "${MERLIN_SKIP_FILE_SIZE_CHECK:-0}" = "1" ] && allow
+
+LIMIT="${MERLIN_FILE_SIZE_LIMIT:-400}"
 
-# Read tool input from stdin (Claude Code pipes JSON)
-input=""
+# Read stdin (defensive: never block on TTY)
+INPUT=""
 if [ ! -t 0 ]; then
-  input=$(cat 2>/dev/null || true)
+  INPUT=$(cat 2>/dev/null || true)
 fi
+[ -z "$INPUT" ] && allow
 
-# Extract file path from tool input
-file_path=""
-if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
-  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
-fi
+# Need python3 for reliable JSON parsing + line counting. If missing, allow.
+command -v python3 >/dev/null 2>&1 || allow
 
-# If no file path found, exit cleanly
-if [ -z "$file_path" ] || [ ! -f "$file_path" ]; then
-  echo '{}'
-  exit 0
-fi
+RESULT=$(MERLIN_LIMIT="$LIMIT" python3 - "$INPUT" <<'PYEOF' 2>/dev/null || echo "ERROR"
+import sys, json, os, fnmatch, re
 
-# Skip non-code files (images, binaries, configs, etc.)
-case "$file_path" in
-  *.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico|*.woff|*.woff2|*.ttf|*.eot) echo '{}'; exit 0 ;;
-  *.lock|*.json|*.yaml|*.yml|*.toml|*.env*) echo '{}'; exit 0 ;;
-  *node_modules*|*.git/*) echo '{}'; exit 0 ;;
-esac
+try:
+    payload = json.loads(sys.argv[1])
+except Exception:
+    print("ALLOW||json-error"); sys.exit(0)
 
-# Count lines in the file
-line_count=$(wc -l < "$file_path" 2>/dev/null || echo "0")
-line_count=$(echo "$line_count" | tr -d ' ')
+limit = int(os.environ.get("MERLIN_LIMIT", "400"))
+tool = payload.get("tool_name", "")
+ti = payload.get("tool_input") or {}
+fp = ti.get("file_path") or ""
 
-# If file exceeds 400 lines, send feedback via exit code 2
-if [ "$line_count" -gt 400 ]; then
-  echo "WARNING: ${file_path} is ${line_count} lines (convention is <400). Consider splitting into smaller, focused modules." >&2
-  echo '{}'
-  exit 2
-fi
+IGNORE_GLOBS = [
+    "*.lock", "*-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb",
+    "Cargo.lock", "Pipfile.lock", "composer.lock", "Gemfile.lock",
+    "*.min.*", "*.bundle.*",
+    "*.svg", "*.png", "*.jpg", "*.jpeg", "*.gif", "*.ico", "*.webp", "*.pdf",
+    "*.woff", "*.woff2", "*.ttf", "*.eot",
+    "*.snap", "*.csv", "*.tsv",
+    "*.md",
+]
+IGNORE_PATH_SUBSTRINGS = [
+    "/node_modules/", "/dist/", "/build/", "/.next/", "/.git/", "/out/",
+    "/coverage/", "/.vite/", "/migrations/", "/__fixtures__/", "/fixtures/",
+    "/__snapshots__/",
+]
+
+def is_ignored(path):
+    if not path: return True
+    base = os.path.basename(path).lower()
+    for g in IGNORE_GLOBS:
+        if fnmatch.fnmatchcase(base, g.lower()): return True
+    norm = path.replace("\\", "/")
+    for s in IGNORE_PATH_SUBSTRINGS:
+        if s in norm: return True
+    return False
+
+if is_ignored(fp):
+    print("ALLOW||ignored"); sys.exit(0)
+
+def read_existing():
+    try:
+        with open(fp, "r", encoding="utf-8") as f:
+            return f.read()
+    except Exception:
+        return ""
 
-# File is within limits
-echo '{}'
-exit 0
+if tool == "Write":
+    new_content = ti.get("content") or ""
+elif tool == "Edit":
+    existing = read_existing()
+    old = ti.get("old_string", "")
+    new = ti.get("new_string", "")
+    if not existing:
+        new_content = new
+    elif ti.get("replace_all"):
+        new_content = existing.replace(old, new)
+    else:
+        new_content = existing.replace(old, new, 1)
+elif tool == "MultiEdit":
+    cur = read_existing()
+    for e in ti.get("edits") or []:
+        old = e.get("old_string", "")
+        new = e.get("new_string", "")
+        if e.get("replace_all"):
+            cur = cur.replace(old, new)
+        else:
+            cur = cur.replace(old, new, 1)
+    new_content = cur
+else:
+    print("ALLOW||unknown-tool"); sys.exit(0)
+
+# Opt-out marker scan (first 50 + last 50 lines — let big middles still trigger)
+lines = new_content.split("\n")
+loc = len(lines)
+if loc > 100:
+    sample = "\n".join(lines[:50] + lines[-50:])
+else:
+    sample = new_content
+marker = re.search(r"merlin:allow-large-file:\s*([^\n\r]*)", sample)
+if marker:
+    reason = marker.group(1).strip()[:200].replace("|", "/")
+    print(f"ALLOW||marker:{reason}"); sys.exit(0)
+
+if loc > limit:
+    print(f"BLOCK||{loc}||{fp}"); sys.exit(0)
+
+print(f"ALLOW||{loc}"); sys.exit(0)
+PYEOF
+)
+
+# Defensive: any python error → allow
+[ "$RESULT" = "ERROR" ] && allow
+[ -z "$RESULT" ] && allow
+
+ACTION="${RESULT%%||*}"
+
+case "$ACTION" in
+  BLOCK)
+    REST="${RESULT#BLOCK||}"
+    LOC_COUNT="${REST%%||*}"
+    FILE_PATH="${REST#*||}"
+    REASON="File ${FILE_PATH} would be ${LOC_COUNT} LOC, exceeding the ${LIMIT}-LOC project rule.
+
+To proceed, either:
+
+1. REFACTOR — split this file into smaller modules by feature.
+   • Invoke the code-organization-supervisor agent for proposed splits
+   • Run /merlin:check-size to scan the whole repo for offenders
+
+2. JUSTIFY — add this comment in the first 50 lines of the file:
+     // merlin:allow-large-file: <one-line reason this file must stay long>
+   (Python/shell: # merlin:allow-large-file: <reason>)
+   (CSS: /* merlin:allow-large-file: <reason> */)
+   (HTML/JSX: <!-- merlin:allow-large-file: <reason> -->)
+   The reason is your audit trail — make it specific (e.g. 'generated by codegen', 'single-source-of-truth lookup table', 'vendored library').
+
+Override per-session: MERLIN_SKIP_FILE_SIZE_CHECK=1
+Override limit:        MERLIN_FILE_SIZE_LIMIT=600"
+    block "$REASON"
+    ;;
+  ALLOW)
+    REST="${RESULT#ALLOW||}"
+    if [[ "$REST" == marker:* ]]; then
+      echo "[merlin] Allowed large file with marker: ${REST#marker:}" >&2
+    fi
+    allow
+    ;;
+  *)
+    allow
+    ;;
+esac

package/files/hooks/pre-edit-sights-check.sh

@@ -99,14 +99,29 @@ fi
 
 # ─────────────────────────────────────────────────────────────────────────────
 # 3. FILE-BASED FALLBACK — guardian unreachable, use timestamp file
+#
+# IMPORTANT: Only block when a live Sights/guardian session genuinely existed
+# (i.e. the timestamp file is present and non-empty, meaning a prior check
+# happened this session) but is now stale.
+#
+# When there is NO guardian, NO API key, or the user is offline / running in
+# Lite mode (timestamp file absent), fall through to ALLOW — we must not brick
+# users who have no way to satisfy the "call merlin_get_context" instruction.
 # ─────────────────────────────────────────────────────────────────────────────
 if declare -f sights_was_checked_recently >/dev/null 2>&1; then
-  if ! sights_was_checked_recently 120; then
+  # Determine whether a Sights timestamp file exists at all (proxy for "active session")
+  SIGHTS_TS_FILE="${HOME}/.claude/merlin/.sights-last-check"
+  _sights_session_active=false
+  if [ -f "${SIGHTS_TS_FILE}" ] && [ -s "${SIGHTS_TS_FILE}" ]; then
+    _sights_session_active=true
+  fi
+
+  if $_sights_session_active && ! sights_was_checked_recently 120; then
     if declare -f log_event >/dev/null 2>&1; then
       log_event "sights_skip_warning" "$(printf '{"file":"%s","source":"fallback"}' "${file_path:-unknown}")"
     fi
-    # BLOCK the edit — stale context means the agent skipped merlin_get_context
-    # This is the structural enforcement: you cannot edit without fresh Sights context
+    # BLOCK the edit — a prior Sights check existed but context is now stale.
+    # The user HAS a working Sights setup and can satisfy the requirement.
     _BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
     if command -v jq >/dev/null 2>&1; then
       jq -n --arg badge "$_BADGE" '{
@@ -121,6 +136,7 @@ if declare -f sights_was_checked_recently >/dev/null 2>&1; then
     fi
     exit 0
   fi
+  # No timestamp file → offline/Lite/no-API-key user — fall through and allow.
 fi
 
 # Log the pre-edit event

package/files/hooks/security-scanner.sh

@@ -113,10 +113,9 @@ if echo "$content" | grep -qE 'sk-ant-[a-zA-Z0-9_\-]{90,}' 2>/dev/null; then
 fi
 
 # OpenAI key (sk- with 48+ chars, but not sk-ant-)
-if echo "$content" | grep -qE 'sk-(?!ant-)[a-zA-Z0-9]{48,}' 2>/dev/null; then
-  _block "OpenAI API key" "sk-..."
-elif echo "$content" | grep -qE 'sk-[a-zA-Z0-9]{48,}' 2>/dev/null; then
-  # Fallback for grep without PCRE: exclude sk-ant- manually
+# Uses ERE only (no PCRE lookahead — not portable across GNU and BSD grep).
+# Anthropic keys (sk-ant-) are already caught by the rule above; exclude them here.
+if echo "$content" | grep -qE 'sk-[a-zA-Z0-9_-]{48,}' 2>/dev/null; then
   if ! echo "$content" | grep -qE 'sk-ant-' 2>/dev/null; then
     _block "OpenAI API key" "sk-..."
   fi

package/files/hooks/session-end.sh

@@ -140,36 +140,39 @@ COST_FILE="${HOME}/.claude/merlin/session-cost.json"
 if [ -f "${COST_FILE}" ]; then
   COST_SUMMARY=""
   if command -v node >/dev/null 2>&1; then
-    COST_SUMMARY="$(node -e "
+    # Pass COST_FILE as process.argv[1] — never interpolate paths inside the script body.
+    COST_SUMMARY="$(node -e '
 try {
-  const d = JSON.parse(require('fs').readFileSync('${COST_FILE}', 'utf8'));
+  var f = process.argv[1];
+  var d = JSON.parse(require("fs").readFileSync(f, "utf8"));
   if (d.totalCalls > 0) {
-    const tot = (d.totalEstimatedCost || 0).toFixed(4);
-    const calls = d.totalCalls || 0;
-    const tc = d.tokenCounts || {};
-    const tokens = (tc.totalInput || 0) + (tc.totalOutput || 0);
-    const tokStr = tokens > 0 ? ', ' + Math.round(tokens/1000) + 'K tokens' : '';
-    process.stdout.write('Session cost: \$' + tot + ' (' + calls + ' call' + (calls !== 1 ? 's' : '') + tokStr + ')');
+    var tot = (d.totalEstimatedCost || 0).toFixed(4);
+    var calls = d.totalCalls || 0;
+    var tc = d.tokenCounts || {};
+    var tokens = (tc.totalInput || 0) + (tc.totalOutput || 0);
+    var tokStr = tokens > 0 ? ", " + Math.round(tokens/1000) + "K tokens" : "";
+    process.stdout.write("Session cost: $" + tot + " (" + calls + " call" + (calls !== 1 ? "s" : "") + tokStr + ")");
   }
 } catch(e) {}
-" 2>/dev/null || true)"
+' "$COST_FILE" 2>/dev/null || true)"
   elif command -v python3 >/dev/null 2>&1; then
-    COST_SUMMARY="$(python3 -c "
+    # Pass COST_FILE as sys.argv[1] — never interpolate paths inside the script body.
+    COST_SUMMARY="$(python3 -c '
 import json, sys
 try:
-    with open('${COST_FILE}') as f:
+    with open(sys.argv[1]) as f:
         d = json.load(f)
-    if d.get('totalCalls', 0) > 0:
-        tot = d.get('totalEstimatedCost', 0)
-        calls = d.get('totalCalls', 0)
-        tc = d.get('tokenCounts', {})
-        tokens = tc.get('totalInput', 0) + tc.get('totalOutput', 0)
-        tok_str = (', ' + str(round(tokens/1000)) + 'K tokens') if tokens > 0 else ''
-        plural = '' if calls == 1 else 's'
-        sys.stdout.write(f'Session cost: \${tot:.4f} ({calls} call{plural}{tok_str})')
+    if d.get("totalCalls", 0) > 0:
+        tot = d.get("totalEstimatedCost", 0)
+        calls = d.get("totalCalls", 0)
+        tc = d.get("tokenCounts", {})
+        tokens = tc.get("totalInput", 0) + tc.get("totalOutput", 0)
+        tok_str = (", " + str(round(tokens/1000)) + "K tokens") if tokens > 0 else ""
+        plural = "" if calls == 1 else "s"
+        sys.stdout.write("Session cost: ${:.4f} ({} call{}{})".format(tot, calls, plural, tok_str))
 except Exception:
     pass
-" 2>/dev/null || true)"
+' "$COST_FILE" 2>/dev/null || true)"
   fi
   if [ -n "${COST_SUMMARY}" ]; then
     echo "[merlin] ${COST_SUMMARY}" >&2
@@ -249,19 +252,29 @@ if command -v jq >/dev/null 2>&1 && command -v git >/dev/null 2>&1; then
     echo "${outcome_line}" >> "${OUTCOME_FILE}" 2>/dev/null || true
   fi
 
-  # Keep outcomes.jsonl bounded — drop lines older than 90 days
+  # Keep outcomes.jsonl bounded — drop lines older than 90 days.
+  # Single awk pass: no per-line subprocess, ISO-8601 UTC strings sort lexicographically.
+  # On any parse uncertainty, the line is KEPT (never silently dropped).
   if [ -f "${OUTCOME_FILE}" ]; then
-    cutoff_epoch="$(date -u -v-90d +%s 2>/dev/null || date -u -d '90 days ago' +%s 2>/dev/null || echo 0)"
-    if [ "${cutoff_epoch}" -gt 0 ] 2>/dev/null; then
-      tmp_out="${OUTCOME_FILE}.tmp"
-      while IFS= read -r line; do
-        line_ts="$(echo "${line}" | jq -r '.timestamp // ""' 2>/dev/null || echo "")"
-        if [ -z "${line_ts}" ]; then continue; fi
-        line_epoch="$(date -u -d "${line_ts}" +%s 2>/dev/null || date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "${line_ts}" +%s 2>/dev/null || echo 0)"
-        if [ "${line_epoch}" -ge "${cutoff_epoch}" ] 2>/dev/null; then
-          echo "${line}"
-        fi
-      done < "${OUTCOME_FILE}" > "${tmp_out}" 2>/dev/null && mv "${tmp_out}" "${OUTCOME_FILE}" 2>/dev/null || true
+    cutoff="$(date -u -v-90d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '90 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")"
+    if [ -n "${cutoff}" ]; then
+      tmp_out="${OUTCOME_FILE}.tmp.$$"
+      # 2-arg match() only — portable to BSD awk (macOS default) AND gawk.
+      # The gawk-only 3-arg form `match($0, re, arr)` is a syntax error on BSD
+      # awk and would make the whole rotation a silent no-op.
+      awk -v cutoff="${cutoff}" '
+        {
+          ts = ""
+          # "timestamp":"<value>"  → the literal prefix is 13 chars, trailing quote 1.
+          if (match($0, /"timestamp":"[^"]+"/)) {
+            ts = substr($0, RSTART + 13, RLENGTH - 14)
+          }
+          # Keep line if timestamp missing/unparseable OR >= cutoff (ISO string compare)
+          if (ts == "" || ts >= cutoff) print
+        }
+      ' "${OUTCOME_FILE}" > "${tmp_out}" 2>/dev/null \
+        && mv "${tmp_out}" "${OUTCOME_FILE}" 2>/dev/null \
+        || rm -f "${tmp_out}" 2>/dev/null || true
     fi
   fi
 fi

package/files/hooks/smart-approve.sh

@@ -146,6 +146,8 @@ fi
 # ─────────────────────────────────────────────────────────────────────────────
 
 # Safe base command list (exact match on first word)
+# NOTE: curl, wget, nc, scp, ssh, telnet are intentionally excluded — network egress
+# must never be auto-approved; even a seemingly-safe command could pipe to a network tool.
 SAFE_CMDS="cat|head|tail|less|more|wc|file|stat|du|df|which|type|whereis|man|echo|printf|ls|find|tree|fd|grep|rg|ag|ack|fzf|jest|vitest|mocha|pytest|cargo|go|npm|yarn|pnpm|make|tsc|prettier|eslint|rustfmt|black|flake8|mypy|rubocop|uname|hostname|whoami|id|env|printenv|date|uptime|ps|top|git|node|python|python3"
 
 # Git read-only subcommands
@@ -244,16 +246,22 @@ _is_safe_segment() {
   return 0
 }
 
-# Split on pipe, semicolon, &&, || and check each segment
-# Replace separators with newlines, then iterate
+# Split on shell operators (&&, ||, ;, |, &) treating two-char tokens first.
+# Strategy: normalize &&  and || to newlines first (so they are not left as stray &/|),
+# then normalize remaining ; | & to newlines.  Each resulting segment is checked
+# independently — the whole command is safe only when ALL segments are safe.
 all_safe=true
 while IFS= read -r segment; do
+  segment=$(echo "$segment" | xargs 2>/dev/null || echo "$segment")  # trim whitespace
   [ -z "$segment" ] && continue
   if ! _is_safe_segment "$segment"; then
     all_safe=false
     break
   fi
-done < <(echo "$command_str" | tr '|;&' '\n')
+done < <(echo "$command_str" | sed -E 's/\|\|/\
+/g; s/&&/\
+/g; s/[;|&]/\
+/g')
 
 if $all_safe; then
   if declare -f log_event >/dev/null 2>&1; then

package/files/hooks/user-prompt-router.sh

@@ -82,15 +82,36 @@ fi
 [ -z "$suggestion" ] && echo "{}" && exit 0
 
 # ── Emit routing hint ─────────────────────────────────────────────────────────
-_BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
+# Cache the badge for the session to avoid spawning duo-badge.sh on every prompt.
+# Cache key: the Claude Code session_id (stable for the whole session) parsed
+# from the stdin JSON we already captured. $$ is a FRESH pid per hook spawn —
+# it would never hit and would leak a temp file every prompt — so fall back to
+# $PPID (stable across prompts in one session), never $$.
+_SESSION_KEY=""
+if command -v jq >/dev/null 2>&1; then
+  _SESSION_KEY=$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null || true)
+else
+  _SESSION_KEY=$(printf '%s' "$input" | grep -o '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/' 2>/dev/null || true)
+fi
+[ -z "${_SESSION_KEY}" ] && _SESSION_KEY="ppid-${PPID}"
+# Sanitize the key so it is safe as a filename fragment.
+_SESSION_KEY=$(printf '%s' "${_SESSION_KEY}" | tr -c 'A-Za-z0-9._-' '_')
+_BADGE_CACHE="${TMPDIR:-/tmp}/.merlin-badge-${_SESSION_KEY}"
+if [ -f "${_BADGE_CACHE}" ]; then
+  _BADGE="$(cat "${_BADGE_CACHE}" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
+else
+  _BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
+  printf '%s' "${_BADGE}" > "${_BADGE_CACHE}" 2>/dev/null || true
+fi
+
 _ctx="${_BADGE} ROUTING: ${suggestion}. Remember: YOU are the orchestrator. Answer codebase questions via Sights. Route implementation to agents. Badge every action."
 
 if command -v jq >/dev/null 2>&1; then
   jq -n --arg ctx "$_ctx" \
     '{hookSpecificOutput:{hookEventName:"UserPromptSubmit",additionalContext:$ctx}}'
 else
-  # jq not available — emit via printf, escaping the double-quotes in suggestion
-  _ctx_escaped=$(printf '%s' "$_ctx" | sed 's/"/\\"/g')
+  # jq not available — escape backslashes first, then quotes, then strip control chars
+  _ctx_escaped=$(printf '%s' "$_ctx" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr -d '\000-\037')
   printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"%s"}}\n' "$_ctx_escaped"
 fi
 

package/files/merlin/VERSION

@@ -1 +1 @@
-3.22.0
+5.4.0

package/files/merlin-system-prompt.txt

@@ -34,4 +34,6 @@ wait
 
 TASK OPTIMIZATION: Before EVERY routing decision (workflows, agents, specialists), run ~/.claude/scripts/task-optimize.sh --task "<user text>". It returns {intent, skills[], agent, score, matched_phrases}. If score>=25, ALWAYS announce "⟡🔮 MERLIN › Intent: <X>. Loading <skills> + routing to <agent>." then route with skills prepended to context. Registry: ~/.claude/merlin/skills/TASK-OPTIMIZER.json. Slash commands /merlin:optimize, /merlin:design-audit, /merlin:polish, /merlin:redesign wrap common flows.
 
-DISCOVERY-FIRST: Before routing any non-trivial task to a built-in specialist, call `merlin_smart_route(task="...")` and `merlin_discover_agents(query="...")` to check the community catalog (1000+ indexed agents/skills). If a catalog match scores a higher grade (A+/A++) than the best built-in for the task, surface it: "⟡🔮 MERLIN › I found a community agent that fits better: <name> (Grade: <X>). Install with /merlin:install <slug> or stick with built-in <built-in>?" — then wait for user choice. NEVER install without confirmation. Skip discovery only for: trivial single-file edits, debug runs, doc updates, or when the user explicitly names an agent.
+DISCOVERY-FIRST: Before routing any non-trivial task to a built-in specialist, call `merlin_smart_route(task="...")` and `merlin_discover_agents(query="...")` to check the community catalog (1000+ indexed agents/skills). If a catalog match scores a higher grade (A+/A++) than the best built-in for the task, surface it: "⟡🔮 MERLIN › I found a community agent that fits better: <name> (Grade: <X>). Install with /merlin:install <slug> or stick with built-in <built-in>?" — then wait for user choice. NEVER install without confirmation. Skip discovery only for: trivial single-file edits, debug runs, doc updates, or when the user explicitly names an agent.
+
+FILE-SIZE ENFORCEMENT: Every Write/Edit/MultiEdit is blocked by ~/.claude/hooks/check-file-size.sh if the resulting file exceeds 400 LOC (configurable via MERLIN_FILE_SIZE_LIMIT). When blocked, EITHER refactor into smaller modules (preferred) OR add `// merlin:allow-large-file: <one-line reason>` in the first 50 lines if the size is genuinely justified (e.g., generated code, big lookup table, single-file library). Use /merlin:check-size to scan the whole repo at any time.