create-merlin-brain 3.13.0 → 3.15.0

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

@@ -1,11 +1,13 @@
 #!/usr/bin/env bash
 #
 # Merlin Hook: PreToolUse (Edit/Write)
-# Two responsibilities:
+# Three responsibilities:
 #   1. Secret detection — blocks writes that contain leaked credentials.
 #      Exit code 2 with a clear message. This is the only hard block.
-#   2. Sights consultation check — advisory warning if Sights was not
-#      consulted recently. Always exits 0 (never blocks on this).
+#   2. Guardian check — asks the MCP server's HTTP sidecar for session-aware
+#      enforcement. Returns additionalContext nudges when context is stale.
+#   3. File-based fallback — if guardian is unreachable, checks the timestamp
+#      file and returns additionalContext directly.
 #
 set -euo pipefail
 trap 'echo "{}"; exit 0' ERR
@@ -34,66 +36,89 @@ if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
 fi
 
 # ─────────────────────────────────────────────────────────────────────────────
-# SECRET DETECTION
-# Scans the content being written for common credential patterns.
-# Uses grep with POSIX ERE for speed (<5ms on typical file sizes).
+# 1. SECRET DETECTION (always local, always fast, always blocking)
 # ─────────────────────────────────────────────────────────────────────────────
 if [ -n "$content_to_write" ]; then
   SECRET_FOUND=""
   SECRET_TYPE=""
 
-  # AWS access key: AKIA followed by 16 uppercase alphanumeric chars
   if echo "$content_to_write" | grep -qE 'AKIA[0-9A-Z]{16}' 2>/dev/null; then
-    SECRET_FOUND=1
-    SECRET_TYPE="AWS access key (AKIA...)"
+    SECRET_FOUND=1; SECRET_TYPE="AWS access key (AKIA...)"
   fi
-
-  # OpenAI / Anthropic style API key: sk- followed by 48+ alphanumeric chars
   if [ -z "$SECRET_FOUND" ] && echo "$content_to_write" | grep -qE 'sk-[a-zA-Z0-9]{48,}' 2>/dev/null; then
-    SECRET_FOUND=1
-    SECRET_TYPE="API secret key (sk-...)"
+    SECRET_FOUND=1; SECRET_TYPE="API secret key (sk-...)"
   fi
-
-  # PEM private key header
   if [ -z "$SECRET_FOUND" ] && echo "$content_to_write" | \
       grep -qE '-----BEGIN (RSA|EC|DSA|OPENSSH|PRIVATE) KEY-----' 2>/dev/null; then
-    SECRET_FOUND=1
-    SECRET_TYPE="PEM private key"
+    SECRET_FOUND=1; SECRET_TYPE="PEM private key"
   fi
-
-  # Generic password assignment in config-like contexts
-  # Matches: password=, PASSWORD=, "password": "...", passwd=
-  # Requires the value to be non-empty and at least 8 chars to avoid false positives
   if [ -z "$SECRET_FOUND" ] && echo "$content_to_write" | \
       grep -qiE '(password|passwd|secret|api_key|apikey)\s*[=:]\s*["\x27]?[A-Za-z0-9@#$%^&*!_\-]{8,}' 2>/dev/null; then
-    # Exclude known placeholder patterns: <password>, ${PASSWORD}, %(password)s, REPLACE_ME, etc.
     if ! echo "$content_to_write" | \
         grep -qiE '(password|passwd|secret|api_key|apikey)\s*[=:]\s*["\x27]?(<[^>]+>|\$\{[^}]+\}|%\([^)]+\)s|REPLACE_ME|YOUR_|TODO|CHANGEME|example|placeholder|xxx+|test)' 2>/dev/null; then
-      SECRET_FOUND=1
-      SECRET_TYPE="credential assignment (password/secret/api_key)"
+      SECRET_FOUND=1; SECRET_TYPE="credential assignment (password/secret/api_key)"
     fi
   fi
 
   if [ -n "$SECRET_FOUND" ]; then
     if declare -f log_event >/dev/null 2>&1; then
-      log_event "secret_detected" "$(printf '{"file":"%s","type":"%s"}' \
-        "${file_path:-unknown}" "$SECRET_TYPE")"
+      log_event "secret_detected" "$(printf '{"file":"%s","type":"%s"}' "${file_path:-unknown}" "$SECRET_TYPE")"
     fi
-    echo "SECRET DETECTED: ${SECRET_TYPE} found in write to '${file_path:-unknown}'. Remove the secret before committing." >&2
-    # Output block decision — Claude Code reads this JSON when exit code is 2
+    echo "SECRET DETECTED: ${SECRET_TYPE} in '${file_path:-unknown}'. Remove the secret." >&2
     echo '{"decision":"block","reason":"Secret detected in file write. Remove the secret before committing."}'
     exit 2
   fi
 fi
 
 # ─────────────────────────────────────────────────────────────────────────────
-# SIGHTS CONSULTATION CHECK (advisory only)
+# 2. GUARDIAN CHECK — ask MCP server for session-aware enforcement
+# ─────────────────────────────────────────────────────────────────────────────
+GUARDIAN_RESPONSE=""
+MERLIN_DIR="${HOME}/.claude/merlin"
+PORT_FILE="${MERLIN_DIR}/.guardian-port"
+
+if [ -f "$PORT_FILE" ] && command -v jq >/dev/null 2>&1; then
+  GUARDIAN_PORT=$(jq -r '.port // empty' "$PORT_FILE" 2>/dev/null || true)
+  GUARDIAN_PID=$(jq -r '.pid // empty' "$PORT_FILE" 2>/dev/null || true)
+
+  # Verify the guardian process is still alive
+  if [ -n "$GUARDIAN_PORT" ] && [ -n "$GUARDIAN_PID" ] && kill -0 "$GUARDIAN_PID" 2>/dev/null; then
+    # 200ms timeout — hooks must be fast
+    GUARDIAN_RESPONSE=$(curl -s --max-time 0.2 "http://127.0.0.1:${GUARDIAN_PORT}/edit-check" 2>/dev/null || true)
+  fi
+fi
+
+if [ -n "$GUARDIAN_RESPONSE" ] && [ "$GUARDIAN_RESPONSE" != "{}" ]; then
+  # Guardian responded with enforcement data — use it directly
+  if declare -f log_event >/dev/null 2>&1; then
+    log_event "guardian_edit_check" "$(printf '{"file":"%s","response":"ok"}' "${file_path:-unknown}")"
+  fi
+  echo "$GUARDIAN_RESPONSE"
+  exit 0
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 3. FILE-BASED FALLBACK — guardian unreachable, use timestamp file
 # ─────────────────────────────────────────────────────────────────────────────
 if declare -f sights_was_checked_recently >/dev/null 2>&1; then
   if ! sights_was_checked_recently 120; then
     if declare -f log_event >/dev/null 2>&1; then
-      log_event "sights_skip_warning" "$(printf '{"file":"%s"}' "${file_path:-unknown}")"
+      log_event "sights_skip_warning" "$(printf '{"file":"%s","source":"fallback"}' "${file_path:-unknown}")"
+    fi
+    # Return additionalContext nudge — this is the key fix that was missing
+    if command -v jq >/dev/null 2>&1; then
+      jq -n '{
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "allow",
+          additionalContext: "⟡\uD83D\uDD2E MERLIN \u203A Sights context is stale (>2 minutes since last check). Call `merlin_get_context(\"your current task\")` before continuing edits to stay in sync with the codebase."
+        }
+      }'
+    else
+      # No jq — output a simpler JSON manually
+      printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","additionalContext":"Merlin: Sights context is stale. Call merlin_get_context before continuing edits."}}\n'
     fi
+    exit 0
   fi
 fi
 
@@ -102,6 +127,6 @@ if declare -f log_event >/dev/null 2>&1; then
   log_event "pre_edit" "$(printf '{"file":"%s"}' "${file_path:-unknown}")"
 fi
 
-# Claude Code command hooks must output valid JSON to stdout
+# All clear — allow the edit
 echo '{}'
 exit 0

package/files/hooks/task-completed-verify.sh

@@ -24,7 +24,7 @@ if [ -f "package.json" ] && command -v jq >/dev/null 2>&1; then
     build_exit=$?
     if [ "$build_exit" -ne 0 ]; then
       log_event "build_failed" "$(printf '{"exit_code":%d}' "$build_exit")"
-      echo "Merlin: Build check failed (exit $build_exit)" >&2
+      echo "⟡🔮 MERLIN › Build check failed (exit $build_exit)" >&2
     else
       log_event "build_passed" '{}'
     fi
@@ -37,7 +37,7 @@ if [ -f "tsconfig.json" ] && command -v npx >/dev/null 2>&1; then
   tsc_exit=$?
   if [ "$tsc_exit" -ne 0 ]; then
     log_event "typecheck_failed" "$(printf '{"exit_code":%d}' "$tsc_exit")"
-    echo "Merlin: Type check failed (exit $tsc_exit)" >&2
+    echo "⟡🔮 MERLIN › Type check failed (exit $tsc_exit)" >&2
   else
     log_event "typecheck_passed" '{}'
   fi

package/files/hooks/worktree-create.sh

@@ -55,7 +55,7 @@ if declare -f log_event >/dev/null 2>&1; then
     "$WORKTREE_PATH" "$AGENT_ID" "$AGENT_TYPE")"
 fi
 
-echo "Merlin: propagated config to worktree ${WORKTREE_PATH} (agent: ${AGENT_TYPE})" >&2
+echo "⟡🔮 MERLIN › propagated config to worktree ${WORKTREE_PATH} (agent: ${AGENT_TYPE})" >&2
 
 echo '{}'
 exit 0

package/files/hooks/worktree-remove.sh

@@ -48,7 +48,7 @@ fi
 
 LIFETIME_MSG=""
 [ -n "$LIFETIME_S" ] && LIFETIME_MSG=" (lifetime: ${LIFETIME_S}s)"
-echo "Merlin: cleaned up worktree ${WORKTREE_PATH}${LIFETIME_MSG} (agent: ${AGENT_TYPE})" >&2
+echo "⟡🔮 MERLIN › cleaned up worktree ${WORKTREE_PATH}${LIFETIME_MSG} (agent: ${AGENT_TYPE})" >&2
 
 echo '{}'
 exit 0

package/package.json

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

package/files/hooks/agent-sync.sh

@@ -1,50 +0,0 @@
-#!/usr/bin/env bash
-# Merlin Hook: Agent Sync (SessionStart, background)
-# Checks installed agents freshness and updates from cloud. Max once/hour.
-#
-# ASYNC: This hook should be registered as async (non-blocking)
-# Claude Code supports async hooks — register this one as background
-set -euo pipefail
-trap 'echo "{}"; exit 0' ERR
-
-AGENTS_DIR="${HOME}/.claude/agents"
-MERLIN_DIR="${HOME}/.claude/merlin"
-LAST_SYNC="${MERLIN_DIR}/.last-agent-sync"
-API_URL="${MERLIN_API_URL:-https://api.merlin.build}"
-
-[ -d "${AGENTS_DIR}" ] || { echo '{}'; exit 0; }
-
-# Skip if synced within the last hour
-if [ -f "${LAST_SYNC}" ]; then
-  last=$(cat "${LAST_SYNC}" 2>/dev/null || echo "0")
-  [ $(($(date +%s) - last)) -lt 3600 ] && { echo '{}'; exit 0; }
-fi
-
-sync_agents() {
-  local installed=""
-  for f in "${AGENTS_DIR}"/*.md; do
-    [ -f "${f}" ] || continue
-    local name hash
-    name=$(basename "${f}" .md)
-    hash=$(md5sum "${f}" 2>/dev/null | cut -c1-8 || md5 -q "${f}" 2>/dev/null | cut -c1-8 || echo "unknown")
-    installed="${installed}${name}:${hash},"
-  done
-  local response
-  response=$(curl -s --max-time 5 "${API_URL}/api/agents-sync/check?installed=${installed}" 2>/dev/null) || return 0
-  local stale_names
-  stale_names=$(echo "${response}" | grep -o '"name":"[^"]*"' | sed 's/"name":"//;s/"//' 2>/dev/null) || return 0
-  [ -z "${stale_names}" ] && { date +%s > "${LAST_SYNC}"; return 0; }
-  for agent_name in ${stale_names}; do
-    local content md_content
-    content=$(curl -s --max-time 5 "${API_URL}/api/agents-sync/${agent_name}" 2>/dev/null) || continue
-    md_content=$(echo "${content}" | python3 -c "import sys,json;print(json.load(sys.stdin).get('content',''))" 2>/dev/null) || continue
-    [ -n "${md_content}" ] && echo "${md_content}" > "${AGENTS_DIR}/${agent_name}.md"
-  done
-  date +%s > "${LAST_SYNC}"
-}
-
-sync_agents &
-
-# Claude Code command hooks must output valid JSON to stdout
-echo '{}'
-exit 0

package/files/hooks/pre-edit-sights-enforce.md

@@ -1 +0,0 @@
-Always allow this edit. Respond with ONLY: {"ok": true}

package/files/hooks/session-start-boot.md

@@ -1,69 +0,0 @@
-# You Are a Merlin-Powered Session
-
-You are not generic Claude. You are a **Merlin agent** — enhanced with codebase intelligence, specialist routing, and session continuity. Every action you take should reflect this.
-
-## BOOT NOW (do this immediately, before reading the user's message)
-
-1. `merlin_get_selected_repo` → Connect to Sights
-2. `merlin_get_project_status` → Load project state
-3. Display: `Merlin | [repo] | [X] done [Y] pending | Next: [action]`
-4. If checkpoint exists → offer to resume
-5. Show numbered options for what's next
-
-## YOUR IDENTITY THIS SESSION
-
-**You check Sights before every action.** Not sometimes. Every time. Before editing, before creating, before suggesting. You call `merlin_get_context`, `merlin_find_files`, or `merlin_search`. You show what you found: `Merlin | [what you checked] → [what you found]`
-
-**You route to specialists.** You don't do everything yourself. Complex tasks go to fresh 200K specialist agents:
-
-| Keywords in task | Specialist | Command |
-|---|---|---|
-| security, auth, login, password, encrypt, oauth, jwt | hardening-guard | `Skill("merlin:route", args='hardening-guard "..."')` |
-| ui, component, frontend, react, css, layout, tailwind | merlin-frontend | `Skill("merlin:route", args='merlin-frontend "..."')` |
-| api, endpoint, route, rest, graphql, webhook, middleware | merlin-api-designer | `Skill("merlin:route", args='merlin-api-designer "..."')` |
-| database, schema, model, migration, architecture | system-architect | `Skill("merlin:route", args='system-architect "..."')` |
-| test, spec, coverage, unit, integration, e2e, jest | tests-qa | `Skill("merlin:route", args='tests-qa "..."')` |
-| refactor, cleanup, dry, organize, split, extract | dry-refactor | `Skill("merlin:route", args='dry-refactor "..."')` |
-| deploy, infra, docker, env, ci, pipeline, railway | ops-railway | `Skill("merlin:route", args='ops-railway "..."')` |
-| docs, readme, documentation, jsdoc, changelog | docs-keeper | `Skill("merlin:route", args='docs-keeper "..."')` |
-| debug, fix, error, bug, crash, trace, investigate | merlin-debugger | `Skill("merlin:route", args='merlin-debugger "..."')` |
-| swift, swiftui, ios, macos, xcode | apple-swift-expert | route via merlin:route |
-| android, kotlin, compose, jetpack | android-expert | route via merlin:route |
-| electron, tauri, desktop, native | desktop-app-expert | route via merlin:route |
-| animation, motion, framer, gsap | animation-expert | route via merlin:route |
-| design-system, accessibility, ux, wireframe | ui-designer | route via merlin:route |
-| plan, roadmap, phase, milestone | Use /merlin:plan-phase or /merlin:discuss-milestone |
-| map, analyze, understand codebase | Use /merlin:map-codebase |
-
-**You suggest workflows.** When a user's task matches a workflow pattern, suggest it proactively:
-
-| User says | Suggest workflow |
-|---|---|
-| "build [feature]", "add [feature]" | `feature-dev` |
-| "build the whole thing", "full product" | `product-dev` |
-| "fix [bug]", "broken", "not working" | `bug-fix` |
-| "security", "audit", "vulnerabilities" | `security-audit` |
-| "refactor", "cleanup", "tech debt" | `refactor` |
-| "build UI", "frontend", "components" | `ui-build` |
-| "build API", "endpoints", "REST" | `api-build` |
-| "idea", "from scratch", "spec first" | `spec-to-code` |
-| Complex multi-step or unusual task | `/merlin:workflow create "..."` |
-
-Show as: `[1] Run **workflow-name** workflow (automated N-step pipeline)` — users don't need to know commands.
-
-**You maintain continuity.** You save checkpoints (`merlin_save_checkpoint`) so the next session picks up where this one left off. You commit work incrementally. You never let work disappear.
-
-**You verify before committing.** Call `merlin_run_verification` before every git commit. Build, types, lint must pass.
-
-**You show options.** At every decision point, show numbered choices. The user should never wonder "what can Merlin do here?"
-
-**You announce yourself.** Prefix Sights results with `Merlin |`. When routing to a specialist, say `Merlin | Routing to [agent]...`. When checking context, say `Merlin | Checking [area]...`. The user should SEE Merlin working throughout the session, not just at the start.
-
-## REFRESH CYCLE
-
-Every few minutes during active work:
-- Call `merlin_get_context` for the area you're working on
-- Check if patterns or files have changed
-- Adjust your approach based on fresh context
-
-This is what makes you different from raw Claude. You are always informed. Always connected. Always routing to the best specialist. Always maintaining continuity.

package/files/hooks/session-start-context.sh

@@ -1,23 +0,0 @@
-#!/usr/bin/env bash
-#
-# Merlin Hook: SessionStart (context injection)
-# Injects Merlin identity context into the session via additionalContext.
-# Uses the SessionStart command hook JSON output format.
-# Always exits 0 — never blocks Claude Code startup.
-#
-set -euo pipefail
-trap 'echo "{}"; exit 0' ERR
-
-# Output additionalContext JSON for Claude to see at session start.
-# This reminds Claude it's a Merlin-powered session.
-# Full boot instructions are in CLAUDE.md — this is a lightweight nudge.
-cat <<'CONTEXT_JSON'
-{
-  "hookSpecificOutput": {
-    "hookEventName": "SessionStart",
-    "additionalContext": "You are a Merlin-powered session. Before working: (1) call merlin_get_selected_repo to connect Sights, (2) call merlin_get_project_status to load state, (3) show numbered options. Check Sights before every edit. Route complex tasks to specialists via /merlin:route. Save checkpoints before stopping."
-  }
-}
-CONTEXT_JSON
-
-exit 0

package/files/hooks/stop-check.md

@@ -1,13 +0,0 @@
-You are evaluating whether Claude should stop working. Analyze the conversation context: $ARGUMENTS
-
-Check these criteria:
-1. Did the user's most recent request get fully addressed?
-2. Are there any obvious errors or broken code that should be fixed before stopping?
-3. Did Claude mention follow-up tasks it intended to complete but hasn't done yet?
-
-IMPORTANT: This is NOT about saving checkpoints or showing summaries — those are handled elsewhere.
-Only evaluate whether the core work is done.
-
-Respond with ONLY valid JSON, no other text:
-- If stopping is appropriate: {"ok": true}
-- If Claude should continue: {"ok": false, "reason": "brief explanation of what's unfinished"}

package/files/hooks/task-completed-verify.md

@@ -1,13 +0,0 @@
-You are evaluating whether a task should be marked as completed. Context: $ARGUMENTS
-
-Check these criteria:
-1. Was the task's stated objective accomplished based on the conversation?
-2. Were there any errors or test failures mentioned that haven't been resolved?
-3. Is the implementation reasonably complete (not a half-finished skeleton)?
-
-Be lenient — don't block completion for minor issues like missing docs or style nits.
-Only block if the core objective clearly wasn't met or there are unresolved errors.
-
-Respond with ONLY valid JSON, no other text:
-- Task is complete: {"ok": true}
-- Task is not complete: {"ok": false, "reason": "brief explanation of what's unfinished"}