create-merlin-brain 4.2.0 → 5.0.1

package/files/merlin/skills/duo/off.md

@@ -0,0 +1,32 @@
+# duo/off — disable duo mode
+
+## Steps
+
+**Step 1 — Write disabled state.**
+```bash
+~/.claude/scripts/duo-mode-write.sh off "<user's phrase that triggered disable>"
+```
+
+**Step 2 — Check codex-mode status.**
+```bash
+python3 -c "
+import json, os
+f = os.path.expanduser('~/.claude/merlin-state/codex-mode.json')
+try:
+    d = json.load(open(f))
+    if d.get('enabled'): print('codex-mode-active')
+except: pass
+"
+```
+
+**Step 3 — Emit confirmation.**
+
+If codex-mode is active (step 2 output = `codex-mode-active`):
+```
+⟡🔮 MERLIN › Duo off. (codex-mode is still active.)
+```
+
+Otherwise:
+```
+⟡🔮 MERLIN › Duo off. Back to solo routing.
+```

package/files/merlin/skills/duo/offer.md

@@ -0,0 +1,158 @@
+---
+name: duo-offer
+description: Auto-offer prompt for enabling duo mode on risky tasks. Invoked by duo-pre-route.sh when risk score >= threshold and Codex is installed and duo is off and task is not suppressed.
+type: skill
+subcommand: offer
+---
+
+# Duo Auto-Offer
+
+You are executing the duo auto-offer flow. Follow every step in sequence.
+
+## Step 1 — Idempotency guard
+
+Run `~/.claude/scripts/duo-mode-read.sh`. If output is `enabled`, exit silently — duo is already on, no offer needed.
+
+## Step 2 — Install gate
+
+Run `~/.claude/scripts/duo-installed.sh`. If exit code != 0, exit silently — do not mention duo or Codex.
+
+## Step 3 — Read context
+
+Read from environment or caller args:
+- `DUO_OFFER_TASK` — original task description
+- `DUO_OFFER_WORKFLOW` — workflow name (default: "general")
+- `DUO_OFFER_FILES` — comma-separated file paths
+- `DUO_OFFER_LOC` — estimated LOC delta
+- `DUO_OFFER_SCORE` — pre-computed score (if available; otherwise run detector)
+- `DUO_OFFER_REASONS` — pre-computed reasons JSON array (if available)
+
+## Step 4 — Risk check (if score not pre-provided)
+
+Run:
+```
+~/.claude/scripts/duo-risk-detect.sh \
+  --task "$DUO_OFFER_TASK" \
+  --workflow "$DUO_OFFER_WORKFLOW" \
+  --files "$DUO_OFFER_FILES" \
+  --loc "$DUO_OFFER_LOC"
+```
+
+Parse JSON output. If `suggest_duo` is false, exit silently.
+
+## Step 5 — Suppression check
+
+Read `~/.claude/merlin-state/duo-suppress.json` using python3 (flock not needed for read):
+
+```python
+import json, os, time
+path = os.path.expanduser("~/.claude/merlin-state/duo-suppress.json")
+try:
+    d = json.load(open(path))
+except Exception:
+    d = {}
+
+# session_skip: honor if 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:
+    exit(0)  # suppressed
+
+# task_hash check
+import hashlib, re
+task = os.environ.get("DUO_OFFER_TASK", "")
+workflow = os.environ.get("DUO_OFFER_WORKFLOW", "")
+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", []):
+    exit(0)  # already declined this task
+
+# intent fingerprint check (never_for_intents, 7d expiry)
+reasons = json.loads(os.environ.get("DUO_OFFER_REASONS", "[]"))
+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:
+            exit(0)  # suppressed intent
+```
+
+If any check triggers exit(0), exit silently.
+
+## Step 6 — Display the offer
+
+Map reasons to human-readable category labels (never display raw file paths):
+- `keyword:auth`, `keyword:password`, `keyword:crypto`, `keyword:token`, `keyword:secret`, `keyword:permission`, `keyword:role`, `keyword:admin` → "authentication"
+- `keyword:payment`, `keyword:billing` → "payments"
+- `keyword:migration`, `keyword:schema`, `path:migrations/`, `path:database/migrations/`, `path:*.sql` → "database migrations"
+- `keyword:production`, `keyword:prod`, `keyword:security`, `path:security/` → "production/security"
+- `keyword:delete`, `keyword:drop`, `keyword:force` → "destructive operations"
+- `workflow:refactor` → "large refactor"
+- `workflow:security-audit` → "security audit"
+- `workflow:migration` → "migration"
+- `loc:>200`, `loc:>500` → "large change"
+- `files:>10` → "many files"
+- `keyword:ship`, `keyword:release`, `keyword:critical` → "release-critical"
+- `dep:package.json`, `dep:go.mod`, `dep:Cargo.toml`, `dep:requirements.txt` → "dependency changes"
+
+Display (show at most 3 categories, never raw paths):
+
+```
+⟡🔮 MERLIN › This task looks risky (score <SCORE>/100).
+  • Areas: <comma-separated categories>
+  • Workflow: <workflow or "general">
+  Codex would write, Claude would review (sequential).
+
+Reply: yes (enable duo) · no (solo) · skip session · never
+(default = solo if you don't reply explicitly)
+```
+
+## Step 7 — Parse user reply (case-insensitive)
+
+Wait for the user's response, then:
+
+| Reply contains | Action |
+|---|---|
+| `yes` / `enable duo` / `do it` | Call `~/.claude/scripts/duo-mode-write.sh on "auto-offer accepted: <reasons>"` then set `DUO_OFFER_OUTCOME=yes` |
+| `skip session` / `skip this session` | Set `session_skip:true` in duo-suppress.json (atomic, flock), set `DUO_OFFER_OUTCOME=skip-session` |
+| `never` | Add intent fingerprint to `never_for_intents` (FIFO cap 20, with timestamp), set `DUO_OFFER_OUTCOME=never` |
+| `no` / anything else / silence | Add task_hash to `task_hashes_declined` (FIFO cap 100), set `DUO_OFFER_OUTCOME=no` |
+
+**Default is solo — if the reply is ambiguous or empty, treat as "no". Never auto-enable.**
+
+### Atomic write for suppression updates (use flock):
+
+```bash
+flock -x ~/.claude/merlin-state/.duo-suppress.lock -c '
+python3 - <<EOF
+import json, os, time, hashlib, re, tempfile
+
+path = os.path.expanduser("~/.claude/merlin-state/duo-suppress.json")
+try:
+    d = json.load(open(path))
+except Exception:
+    d = {"session_skip": False, "never_for_intents": [], "task_hashes_declined": []}
+
+# Apply the chosen suppression...
+# (populated by caller based on outcome)
+
+tmp = path + ".tmp"
+with open(tmp, "w") as f:
+    json.dump(d, f, indent=2)
+os.replace(tmp, path)
+EOF
+'
+```
+
+## Step 8 — Audit log
+
+Append to `~/.claude/merlin-state/duo-decisions.log` (create if missing, JSONL):
+
+```json
+{"ts":"<ISO8601>","event":"offer","score":<N>,"reasons":[...],"response":"<yes|no|skip-session|never|silent>","action":"<enable|solo|suppress-session|suppress-intent|suppress-task>"}
+```
+
+## Step 9 — Continue
+
+- If outcome is `yes`: proceed with duo routing (the caller will re-read duo-mode.json and route accordingly)
+- All other outcomes: proceed with solo routing

package/files/merlin/skills/duo/on.md

@@ -0,0 +1,50 @@
+# duo/on — enable duo mode
+
+## Steps
+
+**Step 1 — Check install gate.**
+```bash
+~/.claude/scripts/duo-installed.sh
+EXIT_CODE=$?
+```
+
+**Step 2 — Gate failed (Codex not installed).**
+If exit code != 0:
+```bash
+~/.claude/scripts/duo-mode-write.sh off "install gate failed (silent fallback)"
+```
+Do NOT mention duo mode, Codex, or this branch to the user. Continue with whatever
+the user originally requested as if this skill was never invoked. Stop here.
+
+**Step 3 — Gate passed. Enable duo.**
+```bash
+~/.claude/scripts/duo-mode-write.sh on "<user's phrase that triggered enable>"
+BADGE=$(~/.claude/scripts/duo-badge.sh)
+```
+
+**Step 4 — Emit confirmation.**
+```
+⟡🔮↔🔮 MERLIN·DUO › Duo mode enabled.
+• Parallel: planning, docs, code review, tests
+• Sequential: code write/modify (codex writes → claude reviews → decider gates)
+• Verification stays with Claude
+• Auto-expires in 24h
+
+Try: "plan the next phase" to see dual-planning.
+```
+
+**Step 5 — Codex-mode coexistence check.**
+```bash
+python3 -c "
+import json, os, sys
+f = os.path.expanduser('~/.claude/merlin-state/codex-mode.json')
+try:
+    d = json.load(open(f))
+    if d.get('enabled'): print('codex-mode-active')
+except: pass
+"
+```
+If output is `codex-mode-active`, append to the confirmation block:
+```
+(codex-mode also active — duo wins per precedence rule)
+```

package/files/merlin/skills/duo/status.md

@@ -0,0 +1,95 @@
+# duo/status — report current duo state
+
+## Steps
+
+**Step 1 — Parse duo-mode.json with 24h expiry logic.**
+```bash
+python3 - <<'PYEOF'
+import json, os, sys
+from datetime import datetime, timezone, timedelta
+
+state_path = os.path.expanduser("~/.claude/merlin-state/duo-mode.json")
+try:
+    data = json.load(open(state_path))
+except:
+    data = {"enabled": False, "sinceISO": None, "lastToggleReason": None}
+
+enabled = data.get("enabled", False)
+since_iso = data.get("sinceISO")
+reason = data.get("lastToggleReason") or "never enabled"
+
+age_str = ""
+status_label = "OFF"
+expired = False
+
+if enabled and since_iso:
+    try:
+        since_dt = datetime.fromisoformat(since_iso.replace("Z", "+00:00"))
+        now_dt = datetime.now(timezone.utc)
+        delta = now_dt - since_dt
+        if delta > timedelta(hours=24):
+            expired = True
+            status_label = "AUTO-EXPIRED"
+        else:
+            status_label = "ON"
+            total_s = int(delta.total_seconds())
+            age_str = f"{total_s // 3600:02d}:{(total_s % 3600) // 60:02d}"
+    except:
+        expired = True
+        status_label = "AUTO-EXPIRED"
+
+print(f"status={status_label}")
+print(f"since={since_iso or 'n/a'}")
+print(f"age={age_str or 'n/a'}")
+print(f"reason={reason}")
+print(f"expired={expired}")
+PYEOF
+```
+
+**Step 2 — Check Codex install gate.**
+```bash
+~/.claude/scripts/duo-installed.sh 2>/dev/null && echo "gate=pass" || echo "gate=fail"
+```
+
+**Step 3 — Parse duo-suppress.json.**
+```bash
+python3 - <<'PYEOF'
+import json, os
+f = os.path.expanduser("~/.claude/merlin-state/duo-suppress.json")
+try:
+    d = json.load(open(f))
+except:
+    d = {"session_skip": False, "never_for_intents": [], "task_hashes_declined": []}
+
+print(f"session_skip={d.get('session_skip', False)}")
+print(f"intents_count={len(d.get('never_for_intents', []))}")
+print(f"hashes_count={len(d.get('task_hashes_declined', []))}")
+PYEOF
+```
+
+**Step 4 — Emit status output.**
+
+Use the values above to emit ONE of these formats:
+
+If status=ON:
+```
+⟡🔮↔🔮 MERLIN·DUO › Duo: ON · since {sinceISO} · age {hh:mm} · reason: {lastToggleReason}
+```
+
+If status=OFF:
+```
+⟡🔮 MERLIN › Duo: OFF (last reason: {lastToggleReason})
+```
+
+If status=AUTO-EXPIRED:
+```
+⟡🔮 MERLIN › Duo: AUTO-EXPIRED (was on since {sinceISO}, exceeded 24h). Treating as off.
+```
+
+Then append install gate and suppression lines:
+```
+Codex install gate: ✓ pass   (or ✗ fail — duo would silent-fallback to solo)
+Session skip: {true|false}
+Suppressed intents: {N}   (if N > 0, add: — run Skill("merlin:duo", args="unsuppress") to clear)
+Recently declined task hashes: {N}
+```

package/files/merlin/skills/duo/unsuppress.md

@@ -0,0 +1,122 @@
+# duo/unsuppress — interactive suppression memory clearer
+
+## Steps
+
+**Step 1 — Read suppression state with exclusive lock.**
+```bash
+SUPPRESS_FILE="${HOME}/.claude/merlin-state/duo-suppress.json"
+LOCK_FILE="${HOME}/.claude/merlin-state/.duo-suppress.lock"
+
+flock -x "$LOCK_FILE" -c "python3 - '$SUPPRESS_FILE'" <<'PYEOF'
+import json, sys
+
+state_path = sys.argv[1]
+try:
+    data = json.load(open(state_path))
+except:
+    data = {"session_skip": False, "never_for_intents": [], "task_hashes_declined": []}
+
+session_skip = data.get("session_skip", False)
+intents = data.get("never_for_intents", [])
+hashes = data.get("task_hashes_declined", [])
+
+print(f"session_skip={session_skip}")
+print(f"intents_count={len(intents)}")
+print(f"hashes_count={len(hashes)}")
+for i, intent in enumerate(intents):
+    print(f"intent_{i}={intent}")
+PYEOF
+```
+
+**Step 2 — Check for empty state.**
+If `session_skip=false` AND `intents_count=0` AND `hashes_count=0`:
+```
+⟡🔮 MERLIN › Nothing suppressed. Duo offers fire on all qualifying tasks.
+```
+Stop here.
+
+**Step 3 — Display current suppression state.**
+```
+⟡🔮 MERLIN › Duo suppression memory:
+• Session skip: {true|false}
+• Never-for intents ({N}): [{list of intents, or "none"}]
+• Recently declined task hashes ({N}): [{first 5 hashes then "...and X more" if >5}]
+```
+
+**Step 4 — Ask user for choice.**
+```
+Reply with:
+• "clear all"       — wipe everything
+• "clear session"   — un-set session_skip only
+• "clear intents"   — wipe never_for_intents only
+• "clear hashes"    — wipe task_hashes_declined only
+• "clear <fingerprint>" — remove one specific never_for_intents entry (paste from list above)
+• "cancel"          — leave as-is
+```
+
+**Step 5 — Apply chosen change atomically.**
+After user replies, execute the matching branch with atomic write:
+
+```bash
+SUPPRESS_FILE="${HOME}/.claude/merlin-state/duo-suppress.json"
+LOCK_FILE="${HOME}/.claude/merlin-state/.duo-suppress.lock"
+USER_CHOICE="<user reply>"
+
+flock -x "$LOCK_FILE" -c "python3 - '$SUPPRESS_FILE' '$USER_CHOICE'" <<'PYEOF'
+import json, sys, os, tempfile
+
+state_path = sys.argv[1]
+choice = sys.argv[2].strip().lower()
+
+try:
+    data = json.load(open(state_path))
+except:
+    data = {"session_skip": False, "never_for_intents": [], "task_hashes_declined": []}
+
+cleared = []
+
+if choice == "clear all":
+    data = {"session_skip": False, "never_for_intents": [], "task_hashes_declined": []}
+    cleared = ["session_skip", "never_for_intents", "task_hashes_declined"]
+elif choice == "clear session":
+    data["session_skip"] = False
+    cleared = ["session_skip"]
+elif choice == "clear intents":
+    data["never_for_intents"] = []
+    cleared = ["never_for_intents"]
+elif choice == "clear hashes":
+    data["task_hashes_declined"] = []
+    cleared = ["task_hashes_declined"]
+elif choice.startswith("clear "):
+    fingerprint = sys.argv[2][6:].strip()
+    before = len(data.get("never_for_intents", []))
+    data["never_for_intents"] = [x for x in data.get("never_for_intents", []) if x != fingerprint]
+    after = len(data["never_for_intents"])
+    cleared = [f"intent:{fingerprint}"] if after < before else []
+elif choice == "cancel":
+    print("cancelled")
+    sys.exit(0)
+else:
+    print("unrecognized — no changes made")
+    sys.exit(0)
+
+tmp = tempfile.NamedTemporaryFile(
+    mode="w", dir=os.path.dirname(state_path), delete=False, suffix=".tmp"
+)
+json.dump(data, tmp, indent=2)
+tmp.close()
+os.replace(tmp.name, state_path)
+
+print(f"cleared={','.join(cleared) if cleared else 'nothing'}")
+PYEOF
+```
+
+**Step 6 — Emit confirmation.**
+Show what was cleared, e.g.:
+```
+⟡🔮 MERLIN › Cleared: {cleared list}. Duo offers will fire normally for affected tasks.
+```
+If user said "cancel":
+```
+⟡🔮 MERLIN › No changes made.
+```

package/files/merlin-state/duo-mode.json

@@ -0,0 +1,5 @@
+{
+  "enabled": false,
+  "sinceISO": null,
+  "lastToggleReason": null
+}

package/files/merlin-state/duo-suppress.json

@@ -0,0 +1,5 @@
+{
+  "session_skip": false,
+  "never_for_intents": [],
+  "task_hashes_declined": []
+}

package/files/merlin-system-prompt.txt

@@ -1 +1 @@
-MANDATORY: You are Merlin, an orchestrator. Before processing any user request, call merlin_get_selected_repo, merlin_get_project_status, merlin_get_rules and merlin_get_brief. Route ALL implementation work to specialist agents via Skill("merlin:workflow") or merlin_route(). NEVER write, edit, or debug code yourself. Prefix every action with the ⟡🔮 MERLIN › badge. Run independent agents in PARALLEL. Before editing code, call merlin_get_context first.
+MANDATORY: You are Merlin, an orchestrator. Before processing any user request, call merlin_get_selected_repo, merlin_get_project_status, merlin_get_rules and merlin_get_brief. Route ALL implementation work to specialist agents via Skill("merlin:workflow") or merlin_route(). NEVER write, edit, or debug code yourself. Prefix every action with the badge from ~/.claude/scripts/duo-badge.sh (solo: ⟡🔮 MERLIN ›, duo: ⟡🔮↔🔮 MERLIN·DUO ›). Run independent agents in PARALLEL. Before editing code, call merlin_get_context first.

package/files/rules/codex-routing.md

@@ -88,6 +88,9 @@ Codex can embody these roles via `codex-as.sh`:
 - `animation-expert` — Motion/animation
 - `code-review` — Production-readiness code review
 
+**Excluded from codex-as.sh:**
+- `reviewer-decider` — Claude-only by design (sequential gate authority)
+
 Any other specialist stays with Claude.
 
 ## Code Review Routing
@@ -100,3 +103,15 @@ Routing logic:
 3. Otherwise → route to `code-review` agent (Claude Opus)
 
 Both produce the same CODE_REVIEW.md report format. User can override by saying "use claude for code review" or "use codex for code review".
+
+---
+
+## Duo Mode — see `duo-routing.md`
+
+When duo is enabled (`~/.claude/merlin-state/duo-mode.json: enabled=true`, within 24h, install gate passes), duo routing in `duo-routing.md` SUPERSEDES the rules in this file. Codex-mode does not need to be on for duo to work — duo manages its own state.
+
+When duo is OFF, the rules in this file (codex-mode escalation, dual-plan, manual codex hands) apply normally.
+
+### Curated specialists exclusion (P0 safety)
+
+`reviewer-decider` is **Claude-only** and MUST NOT be added to the curated specialists list for `codex-as.sh`. Codex impersonating the gate that checks Codex defeats the sequential safety story.