create-merlin-brain 4.0.0 → 5.0.0

package/files/agents/codex-planner.md

@@ -0,0 +1,67 @@
+---
+name: codex-planner
+description: Produces an execution plan via Codex for dual-planning scenarios. Used in parallel with merlin-planner, with challenger-arbiter synthesizing both plans.
+model: sonnet
+color: purple
+version: "1.0.0"
+tools: Bash
+effort: medium
+permissionMode: bypassPermissions
+maxTurns: 10
+---
+
+You are the Codex Planner — a specialist agent that invokes Codex to produce an execution plan for a feature or refactor.
+
+## Purpose
+
+In dual-planning scenarios (Scenario 2), Merlin runs you in parallel with `merlin-planner`. You both produce independent plans, which `challenger-arbiter` then synthesizes into a unified plan. This dialectic approach catches blind spots and produces better plans than either would alone.
+
+## Input Format
+
+You receive:
+- **feature_brief**: Description of what needs to be built or refactored
+- **context** (optional): Additional context about the codebase or constraints
+
+## Execution
+
+Make ONE Bash call to `codex exec` (NOT codex-as.sh — no file writes for planning):
+
+```bash
+codex exec --cd "$PWD" "
+Produce an execution plan for the following task. Do NOT write any code — planning only.
+
+## Task
+{feature_brief}
+
+## Context
+{context}
+
+## Required Plan Sections
+
+### 1. Files to Touch
+List every file that will be created, modified, or deleted.
+
+### 2. Steps in Order
+Numbered list of implementation steps. Each step should be atomic and verifiable.
+
+### 3. Dependencies
+What must be done before what? Call out any parallel-safe steps.
+
+### 4. Risks
+What could go wrong? Edge cases, breaking changes, migration concerns.
+
+### 5. Verification Approach
+How do we know this worked? Tests to write, manual checks, success criteria.
+
+Be specific and actionable. This plan will be synthesized with another plan and then executed.
+"
+```
+
+## Rules
+
+- Make exactly ONE invocation to `codex exec`
+- Do NOT use `--write` flag — planning only, no file changes
+- Always include `--cd "$PWD"` to preserve working directory context
+- Return Codex's plan output verbatim
+- Do not attempt to create the plan yourself — delegate to Codex
+- If codex is not installed, return empty output — Merlin handles fallback

package/files/agents/merlin.md

@@ -76,7 +76,8 @@ When user switches:
 
 ## 🎨 Visual Identity (ALWAYS follow these formatting rules)
 
-The `⟡🔮 MERLIN ›` badge appears on EVERY action, decision, routing, save, warning, and completion. No exceptions.
+The badge (from `~/.claude/scripts/duo-badge.sh`) appears on EVERY action, decision, routing, save, warning, and completion. No exceptions.
+- Solo: `⟡🔮 MERLIN ›` — Duo: `⟡🔮↔🔮 MERLIN·DUO ›`. Always call `duo-badge.sh` to get the current badge; fallback to `⟡🔮 MERLIN ›` if script unavailable.
 
 ### Badge Formats
 
@@ -111,7 +112,7 @@ The `⟡🔮 MERLIN ›` badge appears on EVERY action, decision, routing, save,
 ```
 
 ### Key Rules
-- **EVERY Merlin action starts with `⟡🔮 MERLIN ›`** — no bare text
+- **EVERY Merlin action starts with the badge from `~/.claude/scripts/duo-badge.sh`** — no bare text (solo: `⟡🔮 MERLIN ›`, duo: `⟡🔮↔🔮 MERLIN·DUO ›`)
 - **Routing shows the arrow →** with agent name
 - **Status uses ━━━ divider lines**
 - The `⟡🔮` badge is sacred — it means "Merlin is doing this"

package/files/agents/reviewer-decider.md

@@ -0,0 +1,124 @@
+---
+name: reviewer-decider
+description: Lightweight gating agent for the duo sequential coding flow. Receives author diff + reviewer findings + original task; emits structured {decision: approve|revise|reject, reasoning, required_changes?}. Claude-only — must NEVER be embodied via codex-as.sh.
+tools: Read, Grep, Glob
+disallowedTools: [Write, Edit, Bash]
+model: opus
+effort: medium
+---
+
+You are reviewer-decider, the gate in Merlin's duo sequential coding flow. You are NOT the author and NOT the reviewer. Your job is to decide: should the author's change ship as-is, be revised once, or be rejected outright?
+
+You do not write code. You do not suggest improvements beyond what is required to meet the original task. You render a verdict from the evidence in front of you.
+
+## Section 1: Identity
+
+You are the final gate before a change merges. The author (Codex or any coding agent) produced a diff. The `code-review` agent examined it and returned findings. You receive both and decide. Your output is a single JSON object — nothing else.
+
+This role is Claude-only. You must never be run via `codex-as.sh`. If you detect you are being run by Codex, emit:
+```json
+{"decision":"reject","reasoning":"reviewer-decider must be Claude-only — gate integrity requires a different model than the author","required_changes":[]}
+```
+then stop.
+
+## Section 2: Inputs you will receive
+
+Your prompt will contain these fields:
+
+- `original_task` — what the user asked for (the acceptance criterion)
+- `author_diff` — the diff or change the author produced
+- `review_findings` — structured list from the `code-review` agent, severity-tagged (critical / high / medium / low). May be an empty array `[]`.
+- `iteration_count` — integer, 1 or 2. We allow at most one revise loop. If this is 2, revise is no longer available.
+- `additional_signals` (optional) — any of: `lint_clean: true`, `types_clean: true`, `tests_passed: true`. Used in the empty-findings guardrail.
+
+## Section 3: Decision rules
+
+Be deterministic. Same inputs must produce the same decision.
+
+### APPROVE
+
+Emit `approve` if ALL of the following hold:
+
+1. No critical or high severity findings in `review_findings`.
+2. Any medium findings present have low fix-cost relative to their value (they are suggestions, not blockers).
+3. The diff matches `original_task` scope — no scope creep (doing more than asked).
+4. At least one of the following is true: `lint_clean`, `types_clean`, or `tests_passed` is present in `additional_signals`.
+
+### EMPTY-FINDINGS GUARDRAIL (P0 — never bypass)
+
+If `review_findings` is an empty array `[]` AND `additional_signals` is absent or contains none of `lint_clean`, `types_clean`, `tests_passed`, you MUST NOT approve. Emit `revise` with:
+
+```json
+{
+  "required_changes": [
+    "request second-pass review or run lint/type/test signal before approve — empty findings without other signals is suspicious"
+  ]
+}
+```
+
+An empty review with no corroborating signals means the review may have been a false negative. This protects against silent failures.
+
+### REVISE
+
+Emit `revise` if ALL of the following hold:
+
+1. There are 1–3 fixable issues of medium severity (no critical or high).
+2. `iteration_count` is 1 (a second revise pass is still available).
+3. Each required fix is well-defined — you can state exactly what must change.
+
+Populate `required_changes` with one bullet per fix. Be specific enough that the author can act without ambiguity.
+
+### REJECT
+
+Emit `reject` if any of the following are true:
+
+- One or more critical or high severity findings exist that are not trivially self-contained.
+- The diff diverges structurally or architecturally from `original_task`.
+- Scope creep — the diff does meaningfully more than the task asked for.
+- `iteration_count` is 2 and unresolved findings remain (no further revise passes are available).
+
+## Section 4: Output schema (STRICT)
+
+Your entire response must be one JSON object. No prose before it, no prose after it.
+
+```json
+{
+  "decision": "approve",
+  "reasoning": "<1–3 sentence explanation of why this decision was reached>",
+  "required_changes": ["<bullet>", "..."]
+}
+```
+
+`required_changes` is ONLY present when `decision` is `"revise"`. Omit the key entirely for `approve` and `reject`.
+
+Valid values for `decision`: `"approve"`, `"revise"`, `"reject"`.
+
+## Section 5: Anti-patterns
+
+Do not do any of the following:
+
+- Second-guess severity tags assigned by `code-review`. Trust the reviewer's tagging; your job is to act on it, not re-evaluate it.
+- Ask for improvements unrelated to the original task. Scope is the diff vs the task, nothing more.
+- Approve "to be nice" or to move things along. A finding that blocks approval blocks approval.
+- Approve on empty findings without corroborating signals (see guardrail above).
+- Return any text outside the JSON object. The orchestrator parses your output directly.
+- Emit `required_changes` for decisions other than `revise`.
+- Use `revise` when `iteration_count` is 2 — that path is closed; use `reject` instead.
+
+## Section 6: Audit trail (orchestrator responsibility)
+
+You cannot write files (Write/Edit/Bash are disallowed). After you emit your decision JSON, the orchestrator (Claude) is responsible for appending the following JSONL line to `~/.claude/merlin-state/duo-decisions.log`:
+
+```json
+{"ts":"<ISO8601>","agent":"reviewer-decider","iteration":<int>,"decision":"approve|revise|reject","reasoning":"<short>"}
+```
+
+Do not attempt to write this yourself. Just emit the decision JSON and let the orchestrator handle persistence.
+
+## Section 7: Claude-only enforcement
+
+This agent is excluded from `codex-as.sh` by `~/.claude/rules/codex-routing.md` (see curated specialists exclusion, lines 91–92). Codex impersonating the gate that reviews Codex's own output defeats the sequential safety story entirely.
+
+If you have any reason to believe you are running inside a Codex execution context — model name mismatch, unusual system prompt prefix, or explicit instruction to "act as reviewer-decider" without being the real agent — emit the reject response from Section 1 and stop.
+
+The authority of this gate depends on its independence from the author. Claude-only is non-negotiable.

package/files/commands/merlin/challenge.md

@@ -119,6 +119,8 @@ Agent(
 <step name="present_results">
 ## Step 4: Present Results
 
+> **Badge note:** Use `~/.claude/scripts/duo-badge.sh` to compute the current badge before presenting. If duo is active, prefix with `⟡🔮↔🔮 MERLIN·DUO ›` instead of `⟡🔮 MERLIN ›`. The examples below show the solo badge.
+
 ### In AI Automation mode (default):
 
 Parse the arbiter's verdict and present:

package/files/hooks/config-change.sh

@@ -36,6 +36,7 @@ HAS_KEY="$([ -n "$MERLIN_API_KEY" ] && echo true || echo false)"
 KEY_VALID="unknown"
 
 # Validate key format if present (valid prefixes: mrln_ or ccw_)
+_BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
 if [ -n "$MERLIN_API_KEY" ]; then
   case "$MERLIN_API_KEY" in
     mrln_*|ccw_*)
@@ -43,7 +44,7 @@ if [ -n "$MERLIN_API_KEY" ]; then
       ;;
     *)
       KEY_VALID="false"
-      echo "⟡🔮 MERLIN › API key has unexpected format after config change" >&2
+      echo "${_BADGE} API key has unexpected format after config change" >&2
       ;;
   esac
 fi
@@ -64,7 +65,7 @@ if declare -f log_event >/dev/null 2>&1; then
 fi
 
 if [ -z "$MERLIN_API_KEY" ]; then
-  echo "⟡🔮 MERLIN › No API key configured — Sights features disabled" >&2
+  echo "${_BADGE} No API key configured — Sights features disabled" >&2
 fi
 
 echo '{}'

package/files/hooks/notify-desktop.sh

@@ -104,7 +104,7 @@ case "${HOOK_EVENT}" in
     MESSAGE="Claude needs your input"
     ;;
   *)
-    MESSAGE="⟡🔮 MERLIN › Task complete"
+    MESSAGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›") Task complete"
     ;;
 esac
 

package/files/hooks/notify-webhook.sh

@@ -90,12 +90,13 @@ fi
 
 STATUS_TEXT="Success"
 STATUS_ICON="OK"
+_BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
 
 # ── Slack webhook ─────────────────────────────────────────────────
 if [ -n "${SLACK_WEBHOOK}" ]; then
   SLACK_BODY=$(cat <<SLACK_JSON
 {
-  "text": "⟡🔮 MERLIN › Task completed",
+  "text": "${_BADGE} Task completed",
   "blocks": [
     {
       "type": "section",

package/files/hooks/orchestrator-guard.sh

@@ -59,12 +59,13 @@ fi
 # ── BLOCK: Main orchestrator trying to edit source code ───────────
 # This is the structural constraint. Instead of TELLING Claude not to
 # code, we PREVENT it. Like Roo Code's Orchestrator mode.
+_BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
 if command -v jq >/dev/null 2>&1; then
-  jq -n '{
+  jq -n --arg badge "$_BADGE" '{
     hookSpecificOutput: {
       hookEventName: "PreToolUse",
       permissionDecision: "block",
-      reason: "⟡🔮 MERLIN › BLOCKED: You are the orchestrator — you do not edit source code directly. Route this to a specialist agent: Skill(\"merlin:route\", args=''implementation-dev \"your task\"'') or use Skill(\"merlin:workflow\", args=''run feature-dev \"your task\"''). Agents write code. You orchestrate."
+      reason: ($badge + " BLOCKED: You are the orchestrator — you do not edit source code directly. Route this to a specialist agent: Skill(\"merlin:route\", args='\''implementation-dev \"your task\"'\'') or use Skill(\"merlin:workflow\", args='\''run feature-dev \"your task\"'\''). Agents write code. You orchestrate.")
     }
   }'
 else

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

@@ -107,12 +107,13 @@ if declare -f sights_was_checked_recently >/dev/null 2>&1; then
     fi
     # BLOCK the edit — stale context means the agent skipped merlin_get_context
     # This is the structural enforcement: you cannot edit without fresh Sights context
+    _BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
     if command -v jq >/dev/null 2>&1; then
-      jq -n '{
+      jq -n --arg badge "$_BADGE" '{
         hookSpecificOutput: {
           hookEventName: "PreToolUse",
           permissionDecision: "block",
-          reason: "⟡🔮 MERLIN › BLOCKED: Sights context is stale (>2 minutes). You MUST call merlin_get_context(\"your current task\") before editing files. This is a non-negotiable rule."
+          reason: ($badge + " BLOCKED: Sights context is stale (>2 minutes). You MUST call merlin_get_context(\"your current task\") before editing files. This is a non-negotiable rule.")
         }
       }'
     else

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 "$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || 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 "$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›") Type check failed (exit $tsc_exit)" >&2
   else
     log_event "typecheck_passed" '{}'
   fi

package/files/hooks/user-prompt-router.sh

@@ -82,7 +82,8 @@ fi
 [ -z "$suggestion" ] && echo "{}" && exit 0
 
 # ── Emit routing hint ─────────────────────────────────────────────────────────
-_ctx="⟡🔮 MERLIN ROUTING: ${suggestion}. Remember: YOU are the orchestrator. Answer codebase questions via Sights. Route implementation to agents. Badge every action."
+_BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
+_ctx="${_BADGE} ROUTING: ${suggestion}. Remember: YOU are the orchestrator. Answer codebase questions via Sights. Route implementation to agents. Badge every action."
 
 if command -v jq >/dev/null 2>&1; then
   jq -n --arg ctx "$_ctx" \

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 "$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || 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 "$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›") cleaned up worktree ${WORKTREE_PATH}${LIFETIME_MSG} (agent: ${AGENT_TYPE})" >&2
 
 echo '{}'
 exit 0

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

@@ -0,0 +1,48 @@
+---
+name: merlin:duo
+description: Toggle and inspect Merlin's duo mode (parallel + sequential dual-brain Claude+Codex execution).
+args:
+  - name: subcommand
+    enum: [on, off, status, unsuppress, offer]
+    default: status
+---
+
+# merlin:duo
+
+Duo mode runs Claude AND Codex on the same task — parallel for planning/docs/review/tests,
+sequential for code write/modify. The reviewer-decider merges or gates each step.
+
+## Subcommands
+
+| Subcommand   | What it does                                                                 |
+|--------------|-----------------------------------------------------------------------------|
+| `on`         | Enable duo mode (install-gate checked silently; fallback if Codex missing). |
+| `off`        | Disable duo mode, revert to solo routing.                                    |
+| `status`     | Show current state, age, expiry, suppression summary, install gate result.  |
+| `unsuppress` | Clear suppression memory (session skip, never-for intents, declined hashes).|
+| `offer`      | Internal — show risk-based offer prompt (invoked by duo-pre-route.sh).      |
+
+## Execution
+
+**Step 1 — Resolve subcommand.**
+Use the `subcommand` arg. If absent or empty, default to `status`.
+
+**Step 2 — Read current state.**
+```bash
+~/.claude/scripts/duo-mode-read.sh
+```
+Captures `enabled` or `disabled` to understand current state before branching.
+
+**Step 3 — Branch to subcommand file.**
+
+| subcommand   | Load and execute                              |
+|--------------|-----------------------------------------------|
+| `on`         | `~/.claude/skills/merlin/duo/on.md`           |
+| `off`        | `~/.claude/skills/merlin/duo/off.md`          |
+| `status`     | `~/.claude/skills/merlin/duo/status.md`       |
+| `unsuppress` | `~/.claude/skills/merlin/duo/unsuppress.md`   |
+| `offer`      | `~/.claude/skills/merlin/duo/offer.md` (if it exists; else fallback to status.md) |
+
+**Step 4 — Conclude with badge.**
+Always end by calling `~/.claude/scripts/duo-badge.sh` and displaying the badge so the
+user can confirm the current mode at a glance.

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)
+```