create-merlin-brain 5.3.7 → 5.3.8

package/bin/install.cjs

@@ -1320,10 +1320,17 @@ async function install() {
       hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/user-prompt-router.sh' }]
     });
 
-    // PostToolUse: file size enforcement (implementation agents only)
-    addHookIfMissing(settings.hooks.PostToolUse, {
-      matcher: 'Edit|Write',
-      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/check-file-size.sh' }]
+    // PreToolUse: file size enforcement (400-LOC rule, blocks oversized writes)
+    // NOTE: Moved from PostToolUse to PreToolUse in v5.3.8 to BLOCK before write, not warn after.
+    addHookIfMissing(settings.hooks.PreToolUse, {
+      matcher: 'Edit|Write|MultiEdit',
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/check-file-size.sh', timeout: 10 }]
+    });
+
+    // Remove legacy PostToolUse check-file-size.sh (pre-5.3.8)
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(entry => {
+      const cmd = entry.hooks?.[0]?.command || '';
+      return !cmd.includes('check-file-size.sh');
     });
 
     // PreToolUse: security scanner (prompt injection, secrets, data exfiltration)
@@ -1760,6 +1767,12 @@ ${colors.cyan}Discovery-first (NEW in 5.3.7):${colors.reset}
   • ${colors.bright}/merlin:install <slug>${colors.reset} - One-keystroke install of any catalog agent
   • smart_route + discover_agents wired into the orchestrator protocol
 
+${colors.cyan}File-size enforcement (NEW in 5.3.8):${colors.reset}
+  • 400-LOC rule now enforced by PreToolUse hook (blocks oversized writes)
+  • ${colors.bright}/merlin:check-size${colors.reset} - Scan repo for violations
+  • Justify exceptions with: ${colors.yellow}// merlin:allow-large-file: <reason>${colors.reset}
+  • Override: MERLIN_SKIP_FILE_SIZE_CHECK=1 or MERLIN_FILE_SIZE_LIMIT=N
+
 ${colors.cyan}Merlin works with or without Sights:${colors.reset}
   • ${colors.green}With Sights${colors.reset}: Instant context, cross-session memory
   • ${colors.green}Without${colors.reset}: Full workflows, uses file exploration

package/files/CLAUDE.md

@@ -83,6 +83,7 @@ When user corrects you → `merlin_save_behavior`. When user says "always/never/
 - Never kill user processes (Xcode, VS Code, browsers) without explicit confirmation.
 - Never claim "done" without actually building/compiling/testing.
 - Badge on EVERY action — call `~/.claude/scripts/duo-badge.sh` to get the right badge. If the user can't see the badge, you're not doing your job.
+- No file may exceed 400 LOC. Enforced by ~/.claude/hooks/check-file-size.sh (PreToolUse hook). Override per-file with `// merlin:allow-large-file: <reason>` comment. Override per-session with MERLIN_SKIP_FILE_SIZE_CHECK=1.
 
 ## Codex Execution Mode
 

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/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "5.3.7",
+  "version": "5.3.8",
   "description": "Merlin - The Ultimate AI Brain for Claude Code, Codex, and other AI CLIs. One install: workflows, agents, loop, and Sights MCP server.",
   "type": "module",
   "main": "./dist/server/index.js",