create-merlin-brain 4.2.0 → 5.0.0

package/files/rules/merlin-routing.md

@@ -58,6 +58,10 @@ Call `merlin_smart_route(task="...")` FIRST (searches 500+ community agents). Th
 | "remind me" / "add a todo" | `Skill("merlin:add-todo")` |
 | "check todos" / "pending items" | `Skill("merlin:check-todos")` |
 | New project, no PROJECT.md | `Skill("merlin:map-codebase")` then `Skill("merlin:new-project")` |
+| "duo on" / "enable duo" / "go duo" | `Skill("merlin:duo", args="on")` |
+| "duo off" / "disable duo" / "back to solo" | `Skill("merlin:duo", args="off")` |
+| "duo status" / "am I in duo" / "is duo on" | `Skill("merlin:duo", args="status")` |
+| "stop duo for this kind of task" / "never duo for X" | `Skill("merlin:duo", args="unsuppress")` |
 
 ## Planning Intents
 
@@ -124,3 +128,5 @@ See `~/.claude/rules/codex-routing.md` for full details.
 
 - `feature-dev` and `refactor` workflows: If Codex installed, use dual-plan flow (merlin-planner + codex-planner → challenger-arbiter → codex-implementer execution)
 - `bug-fix` and `quick`: No dual-plan — normal flow, but failed-fix escalation to codex-escalator is available
+
+> When duo mode is active, `feature-dev`, `refactor`, and `product-dev` workflows automatically use parallel planning + sequential coding. See `duo-routing.md`.

package/files/scripts/duo-badge.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# duo-badge.sh — outputs the Merlin badge string to stdout
+# Usage: duo-badge.sh [step-phrase]
+# Env: MERLIN_BADGE_TEXTONLY=1 for ASCII-only output
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+STEP_PHRASE="${1:-}"
+
+# Determine if duo is active: gate passes AND mode is enabled
+DUO_ACTIVE=false
+if "${SCRIPT_DIR}/duo-installed.sh" 2>/dev/null; then
+    if [[ "$("${SCRIPT_DIR}/duo-mode-read.sh" 2>/dev/null)" == "enabled" ]]; then
+        DUO_ACTIVE=true
+    fi
+fi
+
+# Build badge
+if [[ "${MERLIN_BADGE_TEXTONLY:-0}" == "1" ]]; then
+    if [[ "$DUO_ACTIVE" == "true" ]]; then
+        BADGE="[DUO] MERLIN ›"
+    else
+        BADGE="MERLIN ›"
+    fi
+else
+    if [[ "$DUO_ACTIVE" == "true" ]]; then
+        BADGE="⟡🔮↔🔮 MERLIN·DUO ›"
+    else
+        BADGE="⟡🔮 MERLIN ›"
+    fi
+fi
+
+# Append optional step phrase
+if [[ -n "$STEP_PHRASE" ]]; then
+    printf '%s %s\n' "$BADGE" "$STEP_PHRASE"
+else
+    printf '%s\n' "$BADGE"
+fi

package/files/scripts/duo-codex-call.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# duo-codex-call.sh — timeout-wrapped codex invocation with 3-strike fallback
+# Usage: duo-codex-call.sh <codex-command> [args...]
+# Exit 0: success (stdout/stderr forwarded)
+# Exit 75 (TEMPFAIL): codex failed or timed out — caller should fall back to Claude
+# Always exits — never hangs beyond 60s
+
+set -euo pipefail
+
+FAILURES_FILE="${HOME}/.claude/merlin-state/.duo-codex-failures"
+DECISIONS_LOG="${HOME}/.claude/merlin-state/duo-decisions.log"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# --- Counter helpers ---
+_read_counter() {
+    # Reset counter if file is > 6h old (session boundary)
+    if [[ -f "$FAILURES_FILE" ]]; then
+        AGE=$(python3 -c "import os,time; print(int(time.time() - os.path.getmtime('$FAILURES_FILE')))" 2>/dev/null || echo "99999")
+        if [[ "$AGE" -gt 21600 ]]; then
+            rm -f "$FAILURES_FILE"
+            echo 0; return
+        fi
+        cat "$FAILURES_FILE" 2>/dev/null || echo 0
+    else
+        echo 0
+    fi
+}
+
+_write_counter() {
+    echo "$1" > "$FAILURES_FILE"
+}
+
+_log_failure() {
+    local exit_code="$1"
+    local ts
+    ts=$(python3 -c "from datetime import datetime,timezone; print(datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'))" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+    # Mask command to avoid leaking sensitive args (show only first token)
+    local masked_cmd
+    masked_cmd=$(echo "${*:2}" | awk '{print $1}')
+    printf '{"ts":"%s","event":"codex_runtime_failure","exit_code":%d,"command":"%s"}\n' \
+        "$ts" "$exit_code" "$masked_cmd" >> "$DECISIONS_LOG" 2>/dev/null || true
+}
+
+_auto_disable_duo() {
+    "${SCRIPT_DIR}/duo-mode-write.sh" off "codex runtime failures (3 in session)" 2>/dev/null || true
+    echo "⟡🔮 MERLIN › Codex appears unhealthy. Reverting to solo for this session. Run 'codex doctor' to diagnose." >&2
+    _write_counter 0
+}
+
+# --- Build timeout command ---
+_TIMEOUT=""
+if command -v gtimeout >/dev/null 2>&1; then
+    _TIMEOUT="gtimeout 60"
+elif timeout --version >/dev/null 2>&1; then
+    _TIMEOUT="timeout 60"
+fi
+
+# --- Execute (capture exit code without triggering set -e) ---
+EXIT_CODE=0
+if [[ -n "$_TIMEOUT" ]]; then
+    $_TIMEOUT "$@" || EXIT_CODE=$?
+else
+    # perl alarm fallback for macOS without coreutils
+    perl -e 'alarm 60; exec @ARGV or exit 127' -- "$@" || EXIT_CODE=$?
+fi
+
+if [[ $EXIT_CODE -eq 0 ]]; then
+    # Success — reset failure counter
+    _write_counter 0
+    exit 0
+fi
+
+# Failure path
+_log_failure "$EXIT_CODE" "$@"
+
+COUNT=$(( $(_read_counter) + 1 ))
+_write_counter "$COUNT"
+
+if [[ $COUNT -ge 3 ]]; then
+    _auto_disable_duo
+fi
+
+exit 75

package/files/scripts/duo-installed.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# duo-installed.sh — composite install gate for duo mode
+# Returns 0 only if codex-installed.sh (sibling) returns 0
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+"${SCRIPT_DIR}/codex-installed.sh"

package/files/scripts/duo-mode-read.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# duo-mode-read.sh — reads duo-mode.json, applies 24h auto-expire (read-time only, never modifies file)
+# Prints exactly "enabled" or "disabled" to stdout
+
+set -euo pipefail
+
+STATE_FILE="${HOME}/.claude/merlin-state/duo-mode.json"
+
+# If state file missing, default to disabled
+if [[ ! -f "$STATE_FILE" ]]; then
+    echo "disabled"
+    exit 0
+fi
+
+python3 - "$STATE_FILE" <<'PYEOF'
+import sys
+import json
+from datetime import datetime, timezone, timedelta
+
+state_path = sys.argv[1]
+
+try:
+    with open(state_path, "r") as f:
+        data = json.load(f)
+except (json.JSONDecodeError, OSError):
+    print("disabled")
+    sys.exit(0)
+
+enabled = data.get("enabled", False)
+since_iso = data.get("sinceISO")
+
+if not enabled or since_iso is None:
+    print("disabled")
+    sys.exit(0)
+
+# Parse sinceISO and apply 24h auto-expire (read-time interpretation, no file write)
+try:
+    # Handle both Z suffix and +00:00 format
+    since_str = since_iso.replace("Z", "+00:00")
+    since_dt = datetime.fromisoformat(since_str)
+    now_dt = datetime.now(timezone.utc)
+    if (now_dt - since_dt) > timedelta(hours=24):
+        print("disabled")
+        sys.exit(0)
+except (ValueError, TypeError):
+    # Unparseable timestamp — treat as expired
+    print("disabled")
+    sys.exit(0)
+
+print("enabled")
+PYEOF

package/files/scripts/duo-mode-write.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# duo-mode-write.sh — atomic write to duo-mode.json
+# Usage: duo-mode-write.sh on "<reason>" | off "<reason>"
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+    echo "Usage: duo-mode-write.sh on|off \"<reason>\"" >&2
+    exit 1
+fi
+
+ACTION="$1"
+REASON="$2"
+STATE_FILE="${HOME}/.claude/merlin-state/duo-mode.json"
+STATE_DIR="$(dirname "$STATE_FILE")"
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+case "$ACTION" in
+    on)
+        ENABLED="true"
+        ;;
+    off)
+        ENABLED="false"
+        ;;
+    *)
+        echo "Error: first argument must be 'on' or 'off', got: $ACTION" >&2
+        exit 1
+        ;;
+esac
+
+# Use python3 for JSON serialization and atomic write via mktemp + mv (same FS = atomic)
+python3 - "$STATE_FILE" "$ENABLED" "$REASON" <<'PYEOF'
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+
+state_path = sys.argv[1]
+enabled = sys.argv[2] == "true"
+reason = sys.argv[3]
+
+now_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") if enabled else None
+
+data = {
+    "enabled": enabled,
+    "sinceISO": now_iso,
+    "lastToggleReason": reason,
+}
+
+state_dir = os.path.dirname(state_path)
+fd, tmp_path = tempfile.mkstemp(dir=state_dir, suffix=".tmp")
+try:
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    os.replace(tmp_path, state_path)
+except Exception:
+    try:
+        os.unlink(tmp_path)
+    except OSError:
+        pass
+    raise
+PYEOF

package/files/scripts/duo-pre-route.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# duo-pre-route.sh — pre-routing hook for workflow dispatch
+# Usage: duo-pre-route.sh --task "<text>" [--workflow <name>] [--files <comma-list>] [--loc <int>]
+# Outputs one of: mode=duo | mode=offer | mode=solo
+# Always exits 0 — never blocks routing
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+TASK=""
+WORKFLOW=""
+FILES=""
+LOC=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --task)     TASK="${2:-}";     shift 2 ;;
+        --workflow) WORKFLOW="${2:-}"; shift 2 ;;
+        --files)    FILES="${2:-}";    shift 2 ;;
+        --loc)      LOC="${2:-}";      shift 2 ;;
+        *)          shift ;;
+    esac
+done
+
+# Branch 1: duo explicitly enabled by user (and not expired)
+DUO_STATE=$("${SCRIPT_DIR}/duo-mode-read.sh" 2>/dev/null || echo "disabled")
+if [[ "$DUO_STATE" == "enabled" ]]; then
+    echo "mode=duo"
+    exit 0
+fi
+
+# Branch 2: Codex absent — stay solo silently (never mention duo)
+if ! "${SCRIPT_DIR}/duo-installed.sh" 2>/dev/null; then
+    echo "mode=solo"
+    exit 0
+fi
+
+# Branch 3: risk-detect suggestion
+RISK_DETECT="${SCRIPT_DIR}/duo-risk-detect.sh"
+if [[ ! -x "$RISK_DETECT" ]]; then
+    echo "mode=solo"
+    exit 0
+fi
+
+# Run risk detector — it handles its own 500ms timeout internally
+RISK_JSON=$("$RISK_DETECT" --task "$TASK" --workflow "$WORKFLOW" --files "$FILES" --loc "$LOC" 2>/dev/null \
+    || echo '{"score":0,"reasons":[],"suggest_duo":false}')
+
+# Parse suggest_duo from JSON (python3, no jq dep)
+SUGGEST_DUO=$(python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.argv[1])
+    print('true' if d.get('suggest_duo', False) else 'false')
+except Exception:
+    print('false')
+" "$RISK_JSON" 2>/dev/null || echo "false")
+
+if [[ "$SUGGEST_DUO" != "true" ]]; then
+    echo "mode=solo"
+    exit 0
+fi
+
+# Branch 3a: suppression check — use a temp python script to avoid heredoc-in-subshell issues
+REASONS_JSON=$(python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.argv[1])
+    print(json.dumps(d.get('reasons', [])))
+except Exception:
+    print('[]')
+" "$RISK_JSON" 2>/dev/null || echo "[]")
+
+SUPPRESS_SCRIPT=$(mktemp /tmp/duo-suppress-check.XXXXXX.py)
+trap 'rm -f "$SUPPRESS_SCRIPT"' EXIT
+
+cat > "$SUPPRESS_SCRIPT" << 'PYEOF'
+import sys, json, os, time, hashlib, re
+
+task      = os.environ.get("_DUO_TASK", "")
+workflow  = os.environ.get("_DUO_WORKFLOW", "")
+reasons   = json.loads(os.environ.get("_DUO_REASONS", "[]"))
+
+path = os.path.expanduser("~/.claude/merlin-state/duo-suppress.json")
+try:
+    d = json.load(open(path))
+except Exception:
+    d = {}
+
+# session_skip: check file mtime < 12h
+mtime = os.path.getmtime(path) if os.path.exists(path) else 0
+if d.get("session_skip") and (time.time() - mtime) < 43200:
+    print("true"); sys.exit(0)
+
+# task_hash check
+normalized = re.sub(r'[\s\'"`]+', ' ', task.lower()).strip()[:120]
+task_hash  = hashlib.sha1(f"{workflow}:{normalized}".encode()).hexdigest()
+if task_hash in d.get("task_hashes_declined", []):
+    print("true"); sys.exit(0)
+
+# intent fingerprint check (7d expiry)
+top3 = sorted(reasons[:3])
+intent_fp = hashlib.sha1(f"{workflow}:{':'.join(top3)}".encode()).hexdigest()
+now = time.time()
+for entry in d.get("never_for_intents", []):
+    if isinstance(entry, dict):
+        if entry.get("fp") == intent_fp and (now - entry.get("ts", 0)) < 604800:
+            print("true"); sys.exit(0)
+
+print("false")
+PYEOF
+
+IS_SUPPRESSED=$(export _DUO_TASK="$TASK" _DUO_WORKFLOW="$WORKFLOW" _DUO_REASONS="$REASONS_JSON"; \
+    python3 "$SUPPRESS_SCRIPT" 2>/dev/null || echo "false")
+
+if [[ "$IS_SUPPRESSED" == "true" ]]; then
+    echo "mode=solo"
+    exit 0
+fi
+
+# Risk fires, not suppressed — ask user
+echo "mode=offer"
+exit 0

package/files/scripts/duo-risk-detect.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# duo-risk-detect.sh — heuristic risk scorer for duo auto-offer
+# Usage: duo-risk-detect.sh --task "<text>" [--workflow <name>] [--files <comma,sep>] [--loc <int>]
+# Output: single JSON line {"score":<0-100>,"reasons":[...],"suggest_duo":<bool>}
+# Always exits 0 — never blocks routing. Times out at 500ms.
+
+set -euo pipefail
+
+TASK=""
+WORKFLOW=""
+FILES=""
+LOC=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --task)     TASK="${2:-}";     shift 2 ;;
+        --workflow) WORKFLOW="${2:-}"; shift 2 ;;
+        --files)    FILES="${2:-}";    shift 2 ;;
+        --loc)      LOC="${2:-}";      shift 2 ;;
+        *)          shift ;;
+    esac
+done
+
+THRESHOLD="${MERLIN_DUO_OFFER_THRESHOLD:-50}"
+
+# Write the scorer to a temp file so timeout can exec it cleanly (no eval of user input)
+TMPSCRIPT=$(mktemp /tmp/duo-risk-score.XXXXXX.py)
+trap 'rm -f "$TMPSCRIPT"' EXIT
+
+cat > "$TMPSCRIPT" << 'PYEOF'
+import os, sys, json, re
+
+task      = os.environ.get("_DUO_TASK", "")
+workflow  = os.environ.get("_DUO_WORKFLOW", "")
+files     = os.environ.get("_DUO_FILES", "")
+loc_raw   = os.environ.get("_DUO_LOC", "")
+threshold = int(os.environ.get("_DUO_THRESHOLD", "50"))
+
+score   = 0
+reasons = []
+
+# Keyword scoring: +20 each, cap +40
+KEYWORDS = [
+    "auth", "password", "payment", "billing", "migration", "schema",
+    "production", "prod", "security", "crypto", "token", "secret",
+    "permission", "role", "admin", "delete", "drop", "force"
+]
+task_lower = task.lower()
+kw_score = 0
+for kw in KEYWORDS:
+    if re.search(r"\b" + re.escape(kw) + r"\b", task_lower):
+        if kw_score < 40:
+            add = min(20, 40 - kw_score)
+            kw_score += add
+            reasons.append(f"keyword:{kw}")
+score += kw_score
+
+# File path scoring: +25 each, cap +50
+PATH_PATTERNS = [
+    ("migrations/",          "path:migrations/"),
+    ("auth/",                "path:auth/"),
+    ("payment/",             "path:payment/"),
+    ("billing/",             "path:billing/"),
+    ("security/",            "path:security/"),
+    ("database/migrations/", "path:database/migrations/"),
+    ("infra/",               "path:infra/"),
+    (".github/workflows/",   "path:.github/workflows/"),
+    ("Dockerfile",           "path:Dockerfile"),
+    (".sql",                 "path:*.sql"),
+]
+path_score = 0
+for pattern, tag in PATH_PATTERNS:
+    if pattern in files:
+        if path_score < 50:
+            add = min(25, 50 - path_score)
+            path_score += add
+            reasons.append(tag)
+score += path_score
+
+# Workflow scoring: +30
+HIGH_RISK_WORKFLOWS = {"security-audit", "refactor", "migration"}
+if workflow.lower() in HIGH_RISK_WORKFLOWS:
+    score += 30
+    reasons.append(f"workflow:{workflow.lower()}")
+
+# LOC delta scoring (>500 replaces >200)
+try:
+    loc = int(loc_raw.strip()) if loc_raw.strip() else 0
+except ValueError:
+    loc = 0
+
+if loc > 500:
+    score += 35
+    reasons.append("loc:>500")
+elif loc > 200:
+    score += 20
+    reasons.append("loc:>200")
+
+# Files count: +15
+if files.strip():
+    file_list = [f for f in files.split(",") if f.strip()]
+    if len(file_list) > 10:
+        score += 15
+        reasons.append("files:>10")
+
+# Production/critical keywords: +25 (first match only)
+PROD_WORDS = ["production", "ship", "release", "critical"]
+for word in PROD_WORDS:
+    if re.search(r"\b" + re.escape(word) + r"\b", task_lower):
+        score += 25
+        reasons.append(f"keyword:{word}")
+        break
+
+# Dep-manifest files: +15 (first match only)
+DEP_FILES = ["package.json", "go.mod", "Cargo.toml", "requirements.txt"]
+for dep in DEP_FILES:
+    if dep in files:
+        score += 15
+        reasons.append(f"dep:{dep}")
+        break
+
+# Cap at 100, keep top 5 reasons
+score   = min(score, 100)
+reasons = reasons[:5]
+
+print(json.dumps({"score": score, "reasons": reasons, "suggest_duo": score >= threshold}))
+PYEOF
+
+# Export all inputs via env — never interpolated into code
+export _DUO_TASK="$TASK"
+export _DUO_WORKFLOW="$WORKFLOW"
+export _DUO_FILES="$FILES"
+export _DUO_LOC="$LOC"
+export _DUO_THRESHOLD="$THRESHOLD"
+
+# Run with 500ms timeout — try gtimeout (macOS Homebrew coreutils), then timeout, then perl alarm
+_TIMEOUT_CMD=""
+if command -v gtimeout >/dev/null 2>&1; then
+    _TIMEOUT_CMD="gtimeout 0.5"
+elif timeout --version >/dev/null 2>&1; then
+    _TIMEOUT_CMD="timeout 0.5"
+fi
+
+if [[ -n "$_TIMEOUT_CMD" ]]; then
+    OUT=$($_TIMEOUT_CMD python3 "$TMPSCRIPT" 2>/dev/null) || OUT=""
+else
+    OUT=$(perl -e 'alarm 1; exec @ARGV' -- python3 "$TMPSCRIPT" 2>/dev/null) || OUT=""
+fi
+
+# Validate JSON; fall back to safe default
+if python3 -c "import json,sys; json.loads(sys.stdin.read())" <<< "$OUT" 2>/dev/null; then
+    echo "$OUT"
+else
+    echo '{"score":0,"reasons":["timeout"],"suggest_duo":false}'
+fi
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "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",