create-merlin-brain 4.2.0 → 5.0.0

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.

package/files/rules/duo-routing.md

@@ -0,0 +1,203 @@
+# Duo Mode — Routing Rules
+
+This document is the single source of truth for duo mode. Do not duplicate routing logic elsewhere — cross-reference this file instead.
+
+## What duo is
+
+Duo mode runs two brains on the same task: Claude and Codex. Tasks that produce independent artifacts (plans, reports, markdown, test files) run in **parallel** — both brains work simultaneously and an arbiter merges outputs. Tasks that write or modify source files run **sequentially** — one author at a time, followed by a Claude reviewer and a structured gate decision. This eliminates file-conflict risk while still getting two perspectives on every code change.
+
+---
+
+## Activation
+
+**State file:** `~/.claude/merlin-state/duo-mode.json`
+
+**Schema:**
+```json
+{"enabled": bool, "sinceISO": "ISO8601 | null", "lastToggleReason": "string | null"}
+```
+
+**Default (first install):**
+```json
+{"enabled": false, "sinceISO": null, "lastToggleReason": null}
+```
+
+**Auto-expire:** If `sinceISO` is more than 24 hours old at read time, treat as disabled. The file is NOT rewritten on read — expiry is a read-time interpretation. Approximately session-sticky.
+
+**Toggle:** `Skill("merlin:duo", args="on|off|status|unsuppress")` or natural language (see `merlin-routing.md` for intent triggers).
+
+**Install gate:** Run `~/.claude/scripts/duo-installed.sh` before any duo activation. If gate returns non-zero:
+- Silently fall back to solo routing for this task
+- Do NOT write `enabled: true` to the state file
+- Do NOT mention duo, Codex, or the gate failure to the user
+- Proceed as if duo was never considered
+
+---
+
+## Precedence
+
+When multiple modes are enabled simultaneously:
+
+1. **Duo active** (enabled=true, within 24h, gate passes) → duo rules in this file win
+2. **Codex-mode active** (enabled=true, within 24h, codex gate passes) → `codex-routing.md` rules apply
+3. **Neither** → solo routing (existing `merlin-routing.md` + `codex-routing.md` rules)
+
+Note: duo does NOT require `codex-mode.json` to be enabled. Duo manages its own state independently.
+
+---
+
+## Badge contract (UNMISSABLE)
+
+Compute the badge via `~/.claude/scripts/duo-badge.sh` before every action prefix.
+
+| Condition | Badge |
+|---|---|
+| Duo enabled + within 24h + gate passes | `⟡🔮↔🔮 MERLIN·DUO ›` |
+| Any other state | `⟡🔮 MERLIN ›` |
+
+**Text-only fallback:** If env `MERLIN_BADGE_TEXTONLY=1`, `duo-badge.sh` returns `[DUO] MERLIN ›` or `MERLIN ›` for terminals that mangle `↔` or emoji.
+
+Every Merlin action MUST prefix with the computed badge. If the badge is missing, the action is non-compliant. See badge audit: `.planning/duo/BADGE-AUDIT.md`.
+
+Special case — `duo off` when codex-mode is still active:
+```
+⟡🔮 MERLIN › Duo off. (codex-mode is still active.)
+```
+
+---
+
+## Routing Matrix — PARALLEL execution
+
+Both brains run independently on the same task. Results are routed to the arbiter for merging or deduplication. **Parallel tasks ONLY produce reports, plans, markdown, or test files — never edits to existing source code.** Source edits are always sequential (see below).
+
+| Task | Brain A | Brain B | Decider |
+|---|---|---|---|
+| Planning (feature-dev / refactor / product-dev) | `merlin-planner` | `codex-planner` | `challenger-arbiter` |
+| Documentation | `docs-keeper` (Claude) | `docs-keeper` via `codex-as.sh` | `challenger-arbiter` |
+| Code review | `code-review` | `codex-code-review` | merge + dedupe (in arbiter) |
+| Testing | `tests-qa` (Claude) | `tests-qa` via `codex-as.sh` | merge + dedupe (in arbiter) |
+
+**UX during parallel runs:**
+```
+⟡🔮↔🔮 MERLIN·DUO › Planning ×2 (claude + codex)…
+⟡🔮↔🔮 MERLIN·DUO › Arbiter merging plans…
+⟡🔮↔🔮 MERLIN·DUO › Plan ready.
+```
+
+---
+
+## Routing Matrix — SEQUENTIAL execution
+
+One author at a time to prevent file conflicts. Sequential only for tasks that write or modify source files.
+
+| Task | Author | Reviewer | Decider |
+|---|---|---|---|
+| Code write (new files) | `codex-implementer` | `code-review` (Claude) | `reviewer-decider` (Claude) |
+| Code modification | `codex-implementer` | `code-review` (Claude) | `reviewer-decider` (Claude) |
+
+**Sequential decision flow:**
+
+1. Author (`codex-implementer`) writes diff
+2. Reviewer (`code-review`, Claude) reviews diff
+3. `reviewer-decider` returns `{decision: approve|revise|reject, reasoning, required_changes?}`
+4. **On `approve`:** proceed to verification
+5. **On `revise`:** author iterates ONCE with `required_changes`. Re-review. If revise again → escalate to reject.
+6. **On `reject`** OR second revise without resolution: Claude reviewer takes over and writes the fix directly
+
+Maximum iterations per task: 2 (one initial pass + one revise loop). `reviewer-decider` enforces `iteration_count` ≤ 2.
+
+**UX during sequential runs:**
+```
+⟡🔮↔🔮 MERLIN·DUO › [1/3] Codex writing diff…
+⟡🔮↔🔮 MERLIN·DUO › [2/3] Claude reviewing…
+⟡🔮↔🔮 MERLIN·DUO › [3/3] Decision: approve · proceeding to verify
+```
+
+If decider returns `revise`:
+```
+⟡🔮↔🔮 MERLIN·DUO › Iteration 2/2: codex revising…
+```
+
+---
+
+## reviewer-decider is Claude-only (P0 safety)
+
+`reviewer-decider` MUST NOT be invoked via `codex-as.sh`. Codex impersonating the gate that checks Codex's own output destroys the sequential safety story. The curated specialists list in `codex-routing.md` explicitly excludes `reviewer-decider` — this exclusion is permanent and must not be removed.
+
+See also: `codex-routing.md` § "Curated specialists exclusion".
+
+---
+
+## Auto-offer for risky tasks
+
+When duo is OFF, Merlin runs a pre-route hook at the start of every routing decision:
+
+1. Call `~/.claude/scripts/duo-pre-route.sh --task "..." [--workflow X] [--files a,b] [--loc N]`
+2. Hook reads `duo-mode.json`, calls `duo-installed.sh`, calls `duo-risk-detect.sh`, checks `duo-suppress.json`
+3. Hook outputs exactly one of:
+   - `mode=duo` → proceed with duo routing (duo was already on)
+   - `mode=offer` → invoke `Skill("merlin:duo", args="offer")` first; user response determines mode
+   - `mode=solo` → fall through to existing solo/codex-mode rules
+
+**Risk threshold:** `duo-risk-detect.sh` scores the task 0–100. `suggest_duo: true` when score ≥ 50. Threshold tunable via env `MERLIN_DUO_OFFER_THRESHOLD`.
+
+**Offer fires only when ALL of the following are true:**
+- `duo-installed.sh` exits 0 (Codex installed)
+- Duo is currently OFF (or auto-expired)
+- Risk score ≥ threshold
+- Not suppressed (no `session_skip`, task hash not in `task_hashes_declined`, intent not in `never_for_intents`)
+
+**Offer is one-shot per task.** Never offer mid-flight. If `duo-pre-route.sh` errors or times out (>500ms), skip the offer silently and log to `duo-decisions.log`.
+
+**Suppression memory:** `~/.claude/merlin-state/duo-suppress.json`. Reset via `Skill("merlin:duo", args="unsuppress")`. `never_for_intents` entries auto-expire after 7 days. `session_skip` clears when file mtime is > 12h old.
+
+---
+
+## Codex-broken-runtime fallback (P0)
+
+`duo-installed.sh` only checks PATH presence. If Codex is on PATH but fails at runtime:
+
+1. Wrap all Codex invocations with a 60s timeout:
+   - With coreutils: `gtimeout 60s codex …`
+   - Without coreutils: `perl -e 'alarm 60; exec @ARGV' codex …`
+2. On Codex error or timeout: log to `~/.claude/merlin-state/duo-decisions.log` with severity `codex_runtime_failure`. Fall back to Claude for that step:
+   - Parallel branch: drop the codex result; arbiter receives one input
+   - Sequential branch: Claude takes the author role
+3. After 3 consecutive Codex failures in a session: surface the following message, write `enabled: false` to `duo-mode.json` with `lastToggleReason: "codex runtime failures"`, and revert to solo:
+
+```
+⟡🔮 MERLIN › Codex appears unhealthy. Reverting to solo for this session. Run 'codex doctor' to diagnose.
+```
+
+---
+
+## Verification authority (UNCHANGED)
+
+Claude ALWAYS runs `merlin_run_verification()` after a duo flow completes, regardless of who wrote the code. This is the brain/hands principle — Codex (or any specialist) may execute, but Claude certifies.
+
+---
+
+## Workflow integration
+
+| Workflow | When duo ON | When duo OFF |
+|---|---|---|
+| `feature-dev` | Parallel planning + sequential coding | Existing codex-mode dual-plan or solo |
+| `refactor` | Parallel planning + sequential coding | Existing codex-mode dual-plan or solo |
+| `product-dev` | Parallel planning + sequential coding | Solo |
+| `bug-fix` | Solo by default; opt-in via "duo this" | Solo |
+| `quick` | Solo by default; opt-in via "duo this" | Solo |
+| Code review intent | Parallel review pair | `code-review` or `codex-code-review` (codex-routing rules) |
+| Tests intent | Parallel test generation pair | Solo |
+| Docs intent | Parallel docs pair | Solo |
+
+---
+
+## Cross-references
+
+- Codex execution layer: `~/.claude/rules/codex-routing.md`
+- Intent triggers (toggle phrases, workflow routing): `~/.claude/rules/merlin-routing.md`
+- Skill prompts: `~/.claude/skills/merlin/duo/` (SKILL.md, on.md, off.md, status.md, offer.md)
+- Reviewer-decider agent: `~/.claude/agents/reviewer-decider.md`
+- Badge audit: `.planning/duo/BADGE-AUDIT.md`
+- State files: `~/.claude/merlin-state/duo-mode.json`, `~/.claude/merlin-state/duo-suppress.json`
+- Decision audit log: `~/.claude/merlin-state/duo-decisions.log` (JSONL, append-only)