create-merlin-brain 3.11.0 → 3.13.0

package/files/hooks/smart-approve.sh

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: smart-approve.sh
+# Event: PreToolUse (Bash only)
+#
+# Auto-approves safe read-only commands and blocks known-dangerous ones.
+# Unknown commands pass through (exit 0) to let Claude Code handle them.
+#
+# Exit codes:
+#   0 = allow (safe command or unknown — pass through)
+#   2 = block with JSON reason
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+[ -f "${HOOKS_DIR}/lib/analytics.sh" ] && . "${HOOKS_DIR}/lib/analytics.sh"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Read stdin
+# ─────────────────────────────────────────────────────────────────────────────
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && { echo '{}'; exit 0; }
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Extract the command string
+# ─────────────────────────────────────────────────────────────────────────────
+command_str=""
+if command -v jq >/dev/null 2>&1; then
+  command_str=$(echo "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+else
+  command_str=$(echo "$input" | grep -o '"command":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
+fi
+
+[ -z "$command_str" ] && { echo '{}'; exit 0; }
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────────────
+_block_cmd() {
+  local reason="$1"
+  if declare -f log_event >/dev/null 2>&1; then
+    log_event "smart_approve_block" "$(printf '{"reason":"%s"}' "$reason")"
+  fi
+  printf '{"decision":"block","reason":"%s"}\n' "$reason"
+  exit 2
+}
+
+# Extract the base (first) word of a command, stripping env var prefixes like KEY=val cmd
+_base_cmd() {
+  local segment="$1"
+  # Strip leading VAR=val pairs
+  local stripped
+  stripped=$(echo "$segment" | sed 's/^[A-Z_][A-Z0-9_]*=[^ ]* //g' | sed 's/^[A-Z_][A-Z0-9_]*=[^ ]* //g')
+  echo "$stripped" | awk '{print $1}'
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# DANGEROUS PATTERNS — check first, before safe list
+# These are hard blocks regardless of context.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Pipe-to-shell (curl/wget | bash/sh) — extremely dangerous, check raw command string
+if echo "$command_str" | grep -qE '(curl|wget)\s[^|]*\|\s*(bash|sh|zsh|python|ruby|perl)\b' 2>/dev/null; then
+  _block_cmd "Dangerous: pipe-to-shell execution detected (curl/wget | bash/sh)"
+fi
+
+# sudo / su privilege escalation
+if echo "$command_str" | grep -qE '(^|\s|;|&&|\|\|)(sudo|su)\s' 2>/dev/null; then
+  _block_cmd "Dangerous: privilege escalation (sudo/su) not permitted"
+fi
+
+# chmod 777 or chown root
+if echo "$command_str" | grep -qE '(^|\s|;|&&|\|\|)(chmod\s+777|chown\s+root)' 2>/dev/null; then
+  _block_cmd "Dangerous: unsafe permission change (chmod 777 / chown root)"
+fi
+
+# Global package installs
+if echo "$command_str" | grep -qE '(^|\s|;|&&|\|\|)npm\s+(install|i)\s+-g\b' 2>/dev/null; then
+  _block_cmd "Dangerous: global npm install (-g) requires explicit approval"
+fi
+if echo "$command_str" | grep -qE '(^|\s|;|&&|\|\|)pip\s+install\b' 2>/dev/null; then
+  # Allow pip install inside venv (if VIRTUAL_ENV is set — can't check at hook time, so just warn)
+  if ! echo "$command_str" | grep -qE '\-\-user\b|\bvenv\b|virtualenv' 2>/dev/null; then
+    _block_cmd "Dangerous: pip install outside virtualenv requires explicit approval"
+  fi
+fi
+if echo "$command_str" | grep -qE '(^|\s|;|&&|\|\|)gem\s+install\b' 2>/dev/null; then
+  _block_cmd "Dangerous: gem install requires explicit approval"
+fi
+
+# Network firewall mutation
+if echo "$command_str" | grep -qE '(^|\s|;|&&|\|\|)(iptables|ufw|firewall-cmd)\b' 2>/dev/null; then
+  _block_cmd "Dangerous: firewall modification requires explicit approval"
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# GIT DESTRUCTIVE SUBCOMMANDS — check before generic git safe list
+# ─────────────────────────────────────────────────────────────────────────────
+if echo "$command_str" | grep -qE '(^|\s|;|&&|\|\|)git\b' 2>/dev/null; then
+  # git push --force / --force-with-lease
+  if echo "$command_str" | grep -qE 'git\s+push\s+.*--force' 2>/dev/null; then
+    _block_cmd "Dangerous: git push --force can overwrite remote history"
+  fi
+  # git reset --hard
+  if echo "$command_str" | grep -qE 'git\s+reset\s+.*--hard' 2>/dev/null; then
+    _block_cmd "Dangerous: git reset --hard discards uncommitted changes"
+  fi
+  # git clean -f / -fd / -fx
+  if echo "$command_str" | grep -qE 'git\s+clean\s+.*-[a-z]*f' 2>/dev/null; then
+    _block_cmd "Dangerous: git clean -f deletes untracked files permanently"
+  fi
+  # git branch -D (force delete)
+  if echo "$command_str" | grep -qE 'git\s+branch\s+.*-D\b' 2>/dev/null; then
+    _block_cmd "Dangerous: git branch -D force-deletes without merge check"
+  fi
+  # git checkout . (discard all working dir changes)
+  if echo "$command_str" | grep -qE 'git\s+checkout\s+\.\s*$' 2>/dev/null; then
+    _block_cmd "Dangerous: git checkout . discards all working directory changes"
+  fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# rm DESTRUCTIVE — rm -rf or rm -r
+# ─────────────────────────────────────────────────────────────────────────────
+if echo "$command_str" | grep -qE '(^|\s|;|&&|\|\|)rm\s' 2>/dev/null; then
+  if echo "$command_str" | grep -qE '\brm\s+(-[a-z]*r[a-z]*f|--recursive.*--force|-rf|-fr)\b' 2>/dev/null; then
+    _block_cmd "Dangerous: rm -rf detected — destructive recursive delete"
+  fi
+  if echo "$command_str" | grep -qE '\brm\s+(-[a-z]*r|-R|--recursive)\b' 2>/dev/null; then
+    _block_cmd "Dangerous: rm -r detected — recursive delete requires explicit approval"
+  fi
+  if echo "$command_str" | grep -qE '\bshred\b' 2>/dev/null; then
+    _block_cmd "Dangerous: shred detected — permanent file destruction"
+  fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SAFE COMMANDS — auto-approve (exit 0, output {})
+# We split the command on pipe/semicolon/&& and check each segment.
+# A command is safe only if ALL segments are safe.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Safe base command list (exact match on first word)
+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
+GIT_SAFE_SUBS="status|log|diff|branch|show|stash|remote|tag|blame|describe|ls-files|ls-remote|rev-parse|symbolic-ref|config --get|config --list|shortlog|whatchanged"
+
+_is_safe_segment() {
+  local seg
+  seg=$(echo "$1" | xargs 2>/dev/null || echo "$1")  # trim whitespace
+  [ -z "$seg" ] && return 0
+
+  local base
+  base=$(_base_cmd "$seg")
+  [ -z "$base" ] && return 0
+
+  # Check if base is in safe list
+  if ! echo "$base" | grep -qE "^(${SAFE_CMDS})$" 2>/dev/null; then
+    return 1  # not in safe list — unknown
+  fi
+
+  # Additional checks for commands that are only safe in certain forms
+  case "$base" in
+    git)
+      # Only allow read-only git subcommands
+      local sub
+      sub=$(echo "$seg" | awk '{print $2}')
+      if ! echo "$sub" | grep -qE "^(status|log|diff|branch|show|stash|remote|tag|blame|describe|ls-files|ls-remote|rev-parse|symbolic-ref|shortlog|whatchanged|config)$" 2>/dev/null; then
+        return 1  # git write op — not in our safe list
+      fi
+      ;;
+    make)
+      # make with clean or install targets is risky — not safe
+      if echo "$seg" | grep -qE '\b(clean|install|uninstall|distclean|mrproper)\b' 2>/dev/null; then
+        return 1
+      fi
+      ;;
+    npm)
+      # Only safe for read commands
+      local npm_sub
+      npm_sub=$(echo "$seg" | awk '{print $2}')
+      if ! echo "$npm_sub" | grep -qE "^(list|ls|outdated|info|search|audit|run|test|exec)$" 2>/dev/null; then
+        return 1
+      fi
+      ;;
+    yarn)
+      local yarn_sub
+      yarn_sub=$(echo "$seg" | awk '{print $2}')
+      if ! echo "$yarn_sub" | grep -qE "^(list|info|why|audit|run|test)$" 2>/dev/null; then
+        return 1
+      fi
+      ;;
+    pnpm)
+      local pnpm_sub
+      pnpm_sub=$(echo "$seg" | awk '{print $2}')
+      if ! echo "$pnpm_sub" | grep -qE "^(list|ls|info|why|audit|run|test)$" 2>/dev/null; then
+        return 1
+      fi
+      ;;
+    cargo)
+      local cargo_sub
+      cargo_sub=$(echo "$seg" | awk '{print $2}')
+      if ! echo "$cargo_sub" | grep -qE "^(test|check|clippy|build|run|bench|doc|fmt|tree|search)$" 2>/dev/null; then
+        return 1
+      fi
+      ;;
+    go)
+      local go_sub
+      go_sub=$(echo "$seg" | awk '{print $2}')
+      if ! echo "$go_sub" | grep -qE "^(test|vet|build|run|fmt|doc|list|mod|env|version)$" 2>/dev/null; then
+        return 1
+      fi
+      ;;
+    top)
+      # top -l 1 (one snapshot, macOS) or top -n 1 (Linux) is safe; interactive top is not
+      if ! echo "$seg" | grep -qE 'top\s+(-l\s+1|-n\s+1|--lines=1)\b' 2>/dev/null; then
+        return 1
+      fi
+      ;;
+    tsc)
+      # Only safe in check mode
+      if ! echo "$seg" | grep -qE 'tsc\s+.*--noEmit\b' 2>/dev/null; then
+        return 1
+      fi
+      ;;
+    rustfmt)
+      if ! echo "$seg" | grep -qE 'rustfmt\s+.*--check\b' 2>/dev/null; then
+        return 1
+      fi
+      ;;
+    black)
+      if ! echo "$seg" | grep -qE 'black\s+.*--check\b' 2>/dev/null; then
+        return 1
+      fi
+      ;;
+  esac
+
+  return 0
+}
+
+# Split on pipe, semicolon, &&, || and check each segment
+# Replace separators with newlines, then iterate
+all_safe=true
+while IFS= read -r segment; do
+  [ -z "$segment" ] && continue
+  if ! _is_safe_segment "$segment"; then
+    all_safe=false
+    break
+  fi
+done < <(echo "$command_str" | tr '|;&' '\n')
+
+if $all_safe; then
+  if declare -f log_event >/dev/null 2>&1; then
+    log_event "smart_approve_safe" '{}'
+  fi
+  echo '{}'
+  exit 0
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Unknown command — pass through (let Claude Code decide)
+# ─────────────────────────────────────────────────────────────────────────────
+echo '{}'
+exit 0

package/files/hooks/teammate-idle-verify.sh

@@ -1,8 +1,15 @@
 #!/usr/bin/env bash
 #
 # Merlin Hook: TeammateIdle
-# When a teammate finishes work, verify quality against Sights patterns.
+# Fires when a teammate finishes or goes idle in Agent Teams mode.
+#
+# Responsibilities:
+#   1. Verify quality of completed work against Sights patterns
+#   2. Detect if a teammate has been idle for 2+ minutes and alert the Lead
+#   3. Log the event for analytics
+#
 # Advisory only — always exits 0, never blocks teammates.
+# Alert messages go to stderr (visible to Lead session).
 #
 set -euo pipefail
 trap 'echo "{}"; exit 0' ERR
@@ -11,31 +18,99 @@ HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Source shared libraries
 # shellcheck source=lib/analytics.sh
-. "${HOOKS_DIR}/lib/analytics.sh"
+[ -f "${HOOKS_DIR}/lib/analytics.sh" ] && . "${HOOKS_DIR}/lib/analytics.sh"
 
-# Read teammate work summary from stdin (JSON from Claude Code)
+# ---------------------------------------------------------------------------
+# Parse hook input (JSON from Claude Code Agent Teams runtime)
+# ---------------------------------------------------------------------------
 input=""
 if [ ! -t 0 ]; then
   input=$(cat 2>/dev/null || true)
 fi
 
-# Extract modified files if available
+teammate_id=""
+teammate_name=""
 modified_files=""
+idle_seconds=""
+status=""
+
 if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
-  modified_files=$(echo "$input" | jq -r '.files_modified // empty' 2>/dev/null || true)
+  teammate_id=$(echo "$input"   | jq -r '.teammate_id    // empty' 2>/dev/null || true)
+  teammate_name=$(echo "$input" | jq -r '.teammate_name  // empty' 2>/dev/null || true)
+  modified_files=$(echo "$input"| jq -r '.files_modified // empty' 2>/dev/null || true)
+  idle_seconds=$(echo "$input"  | jq -r '.idle_seconds   // empty' 2>/dev/null || true)
+  status=$(echo "$input"        | jq -r '.status         // empty' 2>/dev/null || true)
 fi
 
-# Log teammate idle event
-log_event "teammate_idle_verify" "$(printf '{"modified_files":"%s"}' "${modified_files:-none}")"
+# ---------------------------------------------------------------------------
+# Idle detection — alert Lead if teammate stuck for 2+ minutes (120 seconds)
+# ---------------------------------------------------------------------------
+IDLE_THRESHOLD=120   # seconds
+ALERT_ISSUED=false
+
+if [ -n "$idle_seconds" ] && [ "$idle_seconds" -ge "$IDLE_THRESHOLD" ] 2>/dev/null; then
+  IDLE_MINUTES=$(( idle_seconds / 60 ))
+  DISPLAY_NAME="${teammate_name:-${teammate_id:-unknown}}"
+
+  # Alert goes to stderr — visible to the Lead session in Agent Teams
+  echo "[merlin] Alert: Teammate \"${DISPLAY_NAME}\" has been idle for ${IDLE_MINUTES}+ minutes" >&2
+  echo "[merlin] Recommend: Check teammate status or consider aborting stuck session" >&2
+
+  # Write alert to a shared state file the Lead can poll
+  MERLIN_STATE_DIR="${HOME}/.claude/merlin/teams-state"
+  if [ -d "$MERLIN_STATE_DIR" ] || mkdir -p "$MERLIN_STATE_DIR" 2>/dev/null; then
+    ALERT_FILE="${MERLIN_STATE_DIR}/idle-alert-${teammate_id:-unknown}.json"
+    printf '{"teammate_id":"%s","teammate_name":"%s","idle_seconds":%s,"alert_time":"%s"}\n' \
+      "${teammate_id:-unknown}" \
+      "${DISPLAY_NAME}" \
+      "${idle_seconds}" \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      > "$ALERT_FILE" 2>/dev/null || true
+  fi
+
+  ALERT_ISSUED=true
+
+  # Log idle alert
+  if command -v log_event >/dev/null 2>&1; then
+    log_event "teammate_idle_alert" \
+      "$(printf '{"teammate_id":"%s","idle_seconds":%s}' \
+        "${teammate_id:-unknown}" "${idle_seconds}")"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Completion verification — run when teammate finishes (status = completed)
+# ---------------------------------------------------------------------------
+if [ "${status}" = "completed" ] || [ -z "$status" ]; then
+  # Log teammate idle/completion event
+  if command -v log_event >/dev/null 2>&1; then
+    log_event "teammate_idle_verify" \
+      "$(printf '{"teammate_id":"%s","modified_files":"%s","alert_issued":%s}' \
+        "${teammate_id:-none}" \
+        "${modified_files:-none}" \
+        "${ALERT_ISSUED}")"
+  fi
+
+  # If Merlin CLI is available, run quick Sights check on modified files
+  if [ -n "$modified_files" ] && command -v merlin >/dev/null 2>&1; then
+    merlin context "verify changes in ${modified_files}" >/dev/null 2>&1 &
+  fi
 
-# If Merlin CLI is available, run quick Sights check on modified files
-if [ -n "$modified_files" ] && command -v merlin >/dev/null 2>&1; then
-  merlin context "verify changes in ${modified_files}" >/dev/null 2>&1 &
+  # Clear any stale idle alert for this teammate (they finished)
+  if [ -n "$teammate_id" ]; then
+    MERLIN_STATE_DIR="${HOME}/.claude/merlin/teams-state"
+    rm -f "${MERLIN_STATE_DIR}/idle-alert-${teammate_id}.json" 2>/dev/null || true
+  fi
 fi
 
+# ---------------------------------------------------------------------------
 # Quick build check (non-blocking, advisory only)
-if command -v npm >/dev/null 2>&1; then
-  npm run build --if-present >/dev/null 2>&1 || true
+# Only run when not in Agent Teams context to avoid redundant checks
+# ---------------------------------------------------------------------------
+if [ -z "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-}" ]; then
+  if command -v npm >/dev/null 2>&1; then
+    npm run build --if-present >/dev/null 2>&1 || true
+  fi
 fi
 
 # Claude Code command hooks must output valid JSON to stdout

package/files/hooks/worktree-create.sh

@@ -2,7 +2,7 @@
 #
 # Merlin Hook: WorktreeCreate
 # Purpose: Propagate .merlin/ config into git worktrees so sub-agents
-# spawned in worktrees have Sights access.
+# spawned in worktrees have Sights access and full analytics continuity.
 #
 # Always exits 0 — never blocks Claude Code.
 #
@@ -23,7 +23,7 @@ if [ -z "$WORKTREE_PATH" ]; then
   exit 0
 fi
 
-# Copy Merlin config to worktree
+# Copy project-level Merlin config to worktree
 if [ -d ".merlin" ]; then
   cp -r .merlin "$WORKTREE_PATH/.merlin" 2>/dev/null || true
 fi
@@ -33,9 +33,26 @@ if [ -f "CLAUDE.md" ] && [ ! -f "$WORKTREE_PATH/CLAUDE.md" ]; then
   cp CLAUDE.md "$WORKTREE_PATH/CLAUDE.md" 2>/dev/null || true
 fi
 
+# Propagate essential Merlin state files so the worktree agent has
+# immediate access to Sights context without a cold start.
+MERLIN_DIR="${HOME}/.claude/merlin"
+if [ -d "$MERLIN_DIR" ]; then
+  WORKTREE_MERLIN_DIR="$WORKTREE_PATH/.merlin-session"
+  mkdir -p "$WORKTREE_MERLIN_DIR" 2>/dev/null || true
+
+  # Copy last-sights-check so pre-edit hook doesn't warn immediately
+  [ -f "$MERLIN_DIR/.last-sights-check" ] && \
+    cp "$MERLIN_DIR/.last-sights-check" "$WORKTREE_MERLIN_DIR/.last-sights-check" 2>/dev/null || true
+
+  # Copy selected repo state for Sights context
+  [ -f "$MERLIN_DIR/.selected-repo" ] && \
+    cp "$MERLIN_DIR/.selected-repo" "$WORKTREE_MERLIN_DIR/.selected-repo" 2>/dev/null || true
+fi
+
 # Log event if analytics available
 if declare -f log_event >/dev/null 2>&1; then
-  log_event "worktree_create" "$(printf '{"path":"%s","agent_id":"%s","agent_type":"%s"}' "$WORKTREE_PATH" "$AGENT_ID" "$AGENT_TYPE")"
+  log_event "worktree_create" "$(printf '{"path":"%s","agent_id":"%s","agent_type":"%s"}' \
+    "$WORKTREE_PATH" "$AGENT_ID" "$AGENT_TYPE")"
 fi
 
 echo "Merlin: propagated config to worktree ${WORKTREE_PATH} (agent: ${AGENT_TYPE})" >&2

package/files/hooks/worktree-remove.sh

@@ -2,6 +2,7 @@
 #
 # Merlin Hook: WorktreeRemove
 # Purpose: Cleanup Merlin state from removed worktrees.
+# Also logs worktree lifecycle duration to session analytics.
 #
 # Always exits 0 — never blocks Claude Code.
 #
@@ -22,15 +23,32 @@ if [ -z "$WORKTREE_PATH" ]; then
   exit 0
 fi
 
+# Calculate worktree lifetime if we can (from creation timestamp)
+CREATED_TS=""
+if [ -f "$WORKTREE_PATH/.merlin-session/.last-sights-check" ]; then
+  CREATED_TS=$(cat "$WORKTREE_PATH/.merlin-session/.last-sights-check" 2>/dev/null || echo "")
+fi
+REMOVED_TS=$(date +%s)
+LIFETIME_S=""
+if [ -n "$CREATED_TS" ] && [ "$CREATED_TS" -gt 0 ] 2>/dev/null; then
+  LIFETIME_S=$(( REMOVED_TS - CREATED_TS ))
+fi
+
 # Remove Merlin artifacts from worktree (if still present)
 rm -rf "$WORKTREE_PATH/.merlin" 2>/dev/null || true
+rm -rf "$WORKTREE_PATH/.merlin-session" 2>/dev/null || true
 
-# Log event if analytics available
+# Log worktree lifecycle event if analytics available
 if declare -f log_event >/dev/null 2>&1; then
-  log_event "worktree_remove" "$(printf '{"path":"%s","agent_id":"%s","agent_type":"%s"}' "$WORKTREE_PATH" "$AGENT_ID" "$AGENT_TYPE")"
+  LIFETIME_VAL="${LIFETIME_S:-null}"
+  log_event "worktree_remove" "$(printf \
+    '{"path":"%s","agent_id":"%s","agent_type":"%s","lifetime_seconds":%s}' \
+    "$WORKTREE_PATH" "$AGENT_ID" "$AGENT_TYPE" "$LIFETIME_VAL")"
 fi
 
-echo "Merlin: cleaned up worktree ${WORKTREE_PATH} (agent: ${AGENT_TYPE})" >&2
+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 '{}'
 exit 0

package/files/merlin/references/plan-format.md

@@ -345,11 +345,15 @@ Reference files that Claude needs to understand before implementing.
 </context_references>
 
 <verification_section>
-Overall phase verification (beyond individual task verification):
+Overall phase verification (beyond individual task verification).
+
+**Always use checkboxes** — VS Code plan view renders `- [ ]` as interactive checkboxes.
 
 ```markdown
 <verification>
-Before declaring phase complete:
+
+## Verification Checklist {#verification}
+
 - [ ] `npm run build` succeeds without errors
 - [ ] `npm test` passes all tests
 - [ ] No TypeScript errors
@@ -360,21 +364,45 @@ Before declaring phase complete:
 </verification_section>
 
 <success_criteria_section>
-Measurable criteria for phase completion:
+Measurable criteria for phase completion.
+
+**Always use checkboxes** — VS Code plan view renders these as trackable items.
+**Always tag code blocks** with a language identifier for /copy compatibility (e.g., ` ```bash `, ` ```typescript `).
 
 ```markdown
 <success_criteria>
 
-- All tasks completed
-- All verification checks pass
-- No errors or warnings introduced
-- JWT auth flow works end-to-end
-- Protected routes redirect unauthenticated users
-  </success_criteria>
+## Success Criteria {#success-criteria}
+
+- [ ] All tasks completed
+- [ ] All verification checks pass
+- [ ] No errors or warnings introduced
+- [ ] JWT auth flow works end-to-end
+- [ ] Protected routes redirect unauthenticated users
+</success_criteria>
 ```
 
 </success_criteria_section>
 
+<vscode_plan_view>
+PLAN.md files render in VS Code's plan view. To maximize compatibility:
+
+1. **Checkboxes for every trackable item** — use `- [ ]` in `<verification>` and `<success_criteria>` sections. VS Code renders these as interactive checkboxes.
+
+2. **Anchor headers for navigation** — use `## Section Name {#anchor}` for major sections so the plan view can jump to them.
+
+3. **Language-tagged code blocks** — always specify a language so /copy works cleanly:
+   ````markdown
+   ```bash
+   npm run build
+   ```
+   ````
+
+4. **Concise task names** — the plan view truncates long headings; keep `<name>` under 60 chars.
+
+These rules apply to all generated PLAN.md files.
+</vscode_plan_view>
+
 <output_section>
 Specify the SUMMARY.md structure:
 

package/files/merlin/sandbox.json

@@ -0,0 +1,9 @@
+{
+  "image": "merlin-sandbox:latest",
+  "network": false,
+  "cpu_limit": 2,
+  "memory_limit": "4g",
+  "mount_mode": "ro",
+  "auto_destroy": true,
+  "allowed_write_paths": ["/workspace-output"]
+}

package/files/merlin/security.json

@@ -0,0 +1,11 @@
+{
+  "injection_scanner": {
+    "enabled": true,
+    "custom_patterns": []
+  },
+  "smart_approve": {
+    "enabled": true,
+    "always_allow": [],
+    "always_block": []
+  }
+}

package/files/merlin/templates/ci/docs-update.yml

@@ -0,0 +1,81 @@
+# Merlin Docs Update
+# Auto-updates documentation when code changes are pushed to main.
+# Detects stale docs, updates them, and opens a PR.
+#
+# Setup:
+#   1. Add ANTHROPIC_API_KEY to your repo secrets (Settings > Secrets > Actions)
+#   2. Copy this file to .github/workflows/docs-update.yml
+#
+name: Merlin Docs Update
+
+on:
+  push:
+    branches: [main]
+    paths:
+      # Trigger when source code changes (not docs themselves)
+      - 'src/**'
+      - 'app/**'
+      - 'lib/**'
+      - 'packages/**'
+      - '*.ts'
+      - '*.js'
+      - '*.py'
+      - '*.go'
+
+jobs:
+  docs-update:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get changed files
+        id: changed
+        run: |
+          git diff --name-only HEAD~1 HEAD > /tmp/changed-files.txt
+          echo "Changed files:"
+          cat /tmp/changed-files.txt
+
+      - name: Merlin Docs Update
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            The following files changed in the last commit (see /tmp/changed-files.txt):
+
+            Review the changed source files and identify any documentation that is now stale or missing.
+
+            Update documentation as needed:
+            - README.md — if public API, CLI commands, or setup steps changed
+            - docs/ files — if architecture, guides, or references are affected
+            - Inline JSDoc/comments — if function signatures or behavior changed
+
+            Rules:
+            - Only update docs that are genuinely stale due to the code changes
+            - Do not rewrite docs that are still accurate
+            - Keep the existing writing style and tone
+            - If no docs need updating, output: "No documentation updates needed."
+
+            After making changes, summarize what you updated and why.
+
+      - name: Create PR if docs changed
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: 'docs: auto-update documentation for recent changes'
+          title: 'docs: auto-update documentation'
+          body: |
+            Automated documentation update triggered by changes to source files.
+
+            This PR was generated by the Merlin Docs Update workflow.
+            Review the changes and merge if accurate.
+          branch: merlin/docs-update-${{ github.run_number }}
+          delete-branch: true
+          labels: documentation,automated