create-merlin-brain 5.4.5 → 5.4.6

package/bin/install.cjs

@@ -351,6 +351,29 @@ function removeFile(filePath) {
   return false;
 }
 
+// Non-destructive cleanup: move a legacy dir into a timestamped backup instead
+// of hard-deleting it, so any custom files a user kept there stay recoverable.
+// Dest names are flattened (commands/gsd -> commands__gsd) to avoid collisions.
+function moveDirToBackup(dir, backupRoot) {
+  if (!fs.existsSync(dir)) return false;
+  const rel = dir.startsWith(CLAUDE_DIR + path.sep)
+    ? dir.slice(CLAUDE_DIR.length + 1)
+    : path.basename(dir);
+  const dest = path.join(backupRoot, rel.split(path.sep).join('__'));
+  try {
+    fs.mkdirSync(backupRoot, { recursive: true });
+    fs.renameSync(dir, dest);
+    return true;
+  } catch (e) {
+    // rename can fail across devices — copy then remove; never lose data silently
+    try {
+      fs.mkdirSync(dest, { recursive: true });
+      copyDirRecursive(dir, dest);
+    } catch (e2) { /* best effort backup */ }
+    return removeDirRecursive(dir);
+  }
+}
+
 function setupShellIntegration() {
   const shell = process.env.SHELL || '/bin/zsh';
   const isZsh = shell.includes('zsh');
@@ -657,9 +680,12 @@ function cleanupLegacy() {
     path.join(CLAUDE_DIR, 'ralph-loop'),
   ];
 
+  // Back up legacy dirs instead of hard-deleting (recoverable if a user kept
+  // custom files in commands/gsd, workflows, templates, ccwiki, etc.).
+  const legacyBackupDir = path.join(CLAUDE_DIR, 'backups', 'legacy-' + Date.now());
   for (const dir of dirsToRemove) {
-    if (removeDirRecursive(dir)) {
-      cleaned.push('Removed ' + dir.replace(os.homedir(), '~'));
+    if (moveDirToBackup(dir, legacyBackupDir)) {
+      cleaned.push('Archived ' + dir.replace(os.homedir(), '~') + ' → ' + legacyBackupDir.replace(os.homedir(), '~'));
     }
   }
 
@@ -1071,6 +1097,22 @@ async function install() {
     logWarn('Skills not found in package');
   }
 
+  // Step 7c: Install top-level native Claude Code skills (~/.claude/skills/<name>/)
+  // These register as first-class skills (LLM-recommended via their description),
+  // unlike the nested merlin/ tree. Source: files/skills/<name>/SKILL.md + refs.
+  const nativeSkillsSrc = path.join(filesDir, 'skills');
+  if (fs.existsSync(nativeSkillsSrc)) {
+    const skillsRoot = path.join(CLAUDE_DIR, 'skills');
+    ensureDir(skillsRoot);
+    let nativeCount = 0;
+    for (const entry of fs.readdirSync(nativeSkillsSrc, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === 'merlin') continue; // merlin tree handled in 7b
+      copyDirRecursive(path.join(nativeSkillsSrc, entry.name), path.join(skillsRoot, entry.name));
+      nativeCount++;
+    }
+    if (nativeCount > 0) logSuccess(`Installed ${nativeCount} native skill(s) (incl. ultimate-code-review)`);
+  }
+
   // Step 8: Install commands
   logStep('8/14', 'Installing /merlin:* commands...');
   const commandsSrc = path.join(filesDir, 'commands', 'merlin');
@@ -1240,6 +1282,14 @@ async function install() {
       hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/post-edit-logger.sh' }]
     });
 
+    // PostToolUse hook (ALL tools): user-visible Merlin feed marker — prints
+    // "⟡🔮 MERLIN › <tool>" in the feed for every action so it is always clear
+    // work is driven by Merlin. Opt out per-session with MERLIN_NO_ACTION_MARKER=1.
+    addHookIfMissing(settings.hooks.PostToolUse, {
+      matcher: '*',
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/merlin-action-marker.sh' }]
+    });
+
     // Stop hook (session end)
     settings.hooks.Stop = settings.hooks.Stop || [];
     addHookIfMissing(settings.hooks.Stop, {

package/files/commands/merlin/ultimate-code-review.md

@@ -0,0 +1,48 @@
+---
+name: merlin:ultimate-code-review
+description: Run the Ultimate Code Review — map → parallel subagent review → classify findings → STOP for human approval → execute only approved fixes in minimum-risk order with verified proof. For a feature, subsystem, or product area (not quick single-file PRs).
+argument-hint: "[subsystem / folder / feature to audit]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Agent
+  - AskUserQuestion
+  - Skill
+---
+
+<objective>
+Invoke the `ultimate-code-review` skill and run it end to end on the target the
+user names in arguments. This is the slash-command entry point; the skill itself
+holds the full method (Phases 0–7 + verification gate).
+</objective>
+
+<process>
+1. **Load the skill.** Call `Skill("ultimate-code-review")` and follow its phases
+   exactly. If the Skill tool is unavailable in this harness, read the skill
+   directly from `~/.claude/skills/ultimate-code-review/SKILL.md` (and its
+   `references/*.md`) and follow it verbatim.
+
+2. **Scope.** Use the argument as the area to audit (subsystem, folder, feature).
+   If no argument is given, ask the user what to review — do not guess scope.
+
+3. **Honor the hard gate.** The entire review half is READ-ONLY. Map → batch
+   (≤5000 lines/group) → spawn one read-only subagent per group IN PARALLEL →
+   classify findings → synthesize → present the **decision artifact** and STOP.
+   Edit nothing until the human approves per-batch.
+
+4. **Execute only what's approved**, in the skill's minimum-risk order
+   (safety/truth → correctness → contract collapse → tests → graveyard →
+   enhancement), passing the verification gate after each change.
+
+5. **Badge every action** with `~/.claude/scripts/duo-badge.sh` output, per the
+   Merlin orchestrator contract.
+</process>
+
+<notes>
+- This is heavyweight and explicit-invocation only. For a quick single-file or
+  PR-level pass, use the lighter `/code-review` instead.
+- The orchestrator must NOT write code during the review half — route fixes
+  through the approved-batch execution phase.
+</notes>

package/files/hooks/merlin-action-marker.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: PostToolUse (ALL tools) — user-visible feed marker.
+#
+# Prints a "⟡🔮 MERLIN › <tool>" line into the Claude transcript/feed on every
+# tool action, so it is always clear that work is being driven by Merlin.
+#
+# Mechanism: Claude Code renders a hook's `systemMessage` field to the USER (the
+# feed) — unlike `additionalContext`, which only the model sees. Fires once per
+# tool call (matcher "*").
+#
+# Contract: pure bash, <50ms, no network, always exits 0. Emits valid JSON.
+# Opt-out: set MERLIN_NO_ACTION_MARKER=1 to silence (hook stays installed).
+#
+set -uo pipefail
+
+# Opt-out escape hatch — emit nothing actionable, stay silent.
+if [ "${MERLIN_NO_ACTION_MARKER:-}" = "1" ]; then
+  echo "{}"
+  exit 0
+fi
+
+input=$(cat 2>/dev/null || true)
+
+# ── Tool name (jq if present, grep fallback) ──
+tool=""
+if command -v jq >/dev/null 2>&1; then
+  tool=$(printf '%s' "$input" | jq -r '.tool_name // .tool // empty' 2>/dev/null || true)
+else
+  tool=$(printf '%s' "$input" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/' 2>/dev/null || true)
+fi
+[ -z "$tool" ] && tool="action"
+
+# ── Badge (duo-aware), cached ~10min to avoid spawning duo-badge.sh every call ──
+badge="⟡🔮 MERLIN ›"
+cache="${TMPDIR:-/tmp}/.merlin-action-badge"
+if [ -f "$cache" ] && [ -n "$(find "$cache" -mmin -10 2>/dev/null || true)" ]; then
+  badge=$(cat "$cache" 2>/dev/null || echo "⟡🔮 MERLIN ›")
+elif [ -x "$HOME/.claude/scripts/duo-badge.sh" ]; then
+  badge=$("$HOME/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")
+  printf '%s' "$badge" > "$cache" 2>/dev/null || true
+fi
+
+msg="${badge} ${tool}"
+
+# ── Emit user-visible marker. suppressOutput hides the raw stdout echo but the
+#    systemMessage still renders in the feed. ──
+if command -v jq >/dev/null 2>&1; then
+  jq -n --arg m "$msg" '{systemMessage:$m, suppressOutput:true}'
+else
+  esc=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr -d '\000-\037')
+  printf '{"systemMessage":"%s","suppressOutput":true}\n' "$esc"
+fi
+exit 0

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

@@ -37,8 +37,12 @@ fi
 # ── Intent matching (order matters — most specific first) ─────────────────────
 suggestion=""
 
+# Ultimate Code Review — explicit, heavyweight audit-and-fix (most specific, check first)
+if echo "$prompt" | grep -qiE "ultimate code review|audit (this|the) (subsystem|codebase|module|feature|service|area)|full review.?and.?fix|review.?and.?fix pass|deep code audit"; then
+  suggestion='Detected: ultimate code review. Use: Skill("ultimate-code-review") or /merlin:ultimate-code-review (read-only review → approval gate → approved fixes only)'
+
 # Resume — check before generic "plan" or "build"
-if echo "$prompt" | grep -qiE "I'm back|im back|resume|pick up|continue|where were we"; then
+elif echo "$prompt" | grep -qiE "I'm back|im back|resume|pick up|continue|where were we"; then
   suggestion='Detected: resume. Use: Skill("merlin:resume-work")'
 
 # Progress / status

package/files/scripts/codex-as.sh

@@ -114,6 +114,15 @@ ${TASK_TEXT}"
 # and codex-implementer returning empty diffs). Closing stdin tells Codex "no extra input"
 # and lets it proceed with just the prompt arg.
 #
+# Merlin feed marker — Codex has no hook/feed-injection API (unlike Claude Code's
+# PostToolUse systemMessage), so the best available signal is a stderr line shown
+# in the feed whenever Merlin routes an action to Codex. Honest, wrapper-level.
+if [ "${MERLIN_NO_ACTION_MARKER:-}" != "1" ]; then
+  _BADGE="⟡🔮 MERLIN ›"
+  [ -x "$HOME/.claude/scripts/duo-badge.sh" ] && _BADGE="$("$HOME/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
+  printf '%s Codex ▸ %s\n' "$_BADGE" "$AGENT_NAME" >&2
+fi
+
 # Wrap with timeout using the portable with-timeout.sh wrapper.
 WITH_TIMEOUT="$(dirname "${BASH_SOURCE[0]}")/with-timeout.sh"
 if [[ -x "$WITH_TIMEOUT" ]]; then

package/files/skills/ultimate-code-review/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ultimate-code-review
+description: End-to-end audit, refactor strategy, and approval-gated remediation for large or complex codebases. Use ONLY when explicitly invoked (e.g. "run the ultimate code review", "audit this subsystem", "do a full review-and-fix pass on X"). Requires Claude Code with subagents. The skill maps every related file, splits them into parallel review groups, runs line-by-line subagent reviews, classifies findings (bugs vs architecture vs dead code vs test gaps vs product gaps), produces a product-level decision artifact, STOPS for human approval, then executes only the approved fixes in minimum-risk order with verified proof of behavior. Do not trigger for ordinary single-file reviews or quick PR feedback.
+---
+
+# Ultimate Code Review
+
+Run a disciplined audit-and-fix pass on a feature, subsystem, or product area. Two halves, separated by a hard gate:
+
+1. **Review half (read-only):** map → batch → parallel review → synthesize → present a decision artifact.
+2. **Fix half (write):** execute ONLY what the human approved, in minimum-risk order, each change proven.
+
+The skill is invoked explicitly. It assumes Claude Code with subagents — the parallel review depends on them. It is stack-agnostic: detect the project's real tools before assuming any command.
+
+## The One Rule That Matters Most
+
+**Nothing is edited before the human approves.** The entire review half is read-only. The output of the review half is not a refactor — it is a decision the human can make using product logic: what is broken, what could break if touched, in what order to fix, and which batches to greenlight. Treat any urge to "just fix this small thing while I'm here" as a violation.
+
+## Operating Principles
+
+- Read-only until approval. Map, batch, review, synthesize, present — then wait.
+- Every review group is at or below 5000 physical lines. One subagent reviewer per group, one group per reviewer.
+- Group files by ownership boundary: feature, runtime layer, data flow, or source-of-truth contract.
+- Review line by line with concrete file references and behavioral reasoning, never by vibes.
+- Separate current-state bugs from structural issues and from missing capabilities. These get fixed in different orders and carry different risk.
+- Prefer deleting or collapsing duplicate paths over adding another abstraction.
+- Fix toward enforceable contracts, not advisory guidance.
+- The goal is not a giant refactor. It is a sequence of small, verified changes that steadily removes uncertainty.
+
+## Phase 0: Stack Detection
+
+Before any search or command, detect what this codebase actually uses. Never assume `rg`, `pnpm`, `vitest`, or any specific toolchain. See `references/verification-gate.md` for the detection checklist.
+
+Establish and record:
+- primary language(s) and where source lives;
+- the fast search tool available (`rg`, else `grep -r`);
+- the test runner and how to invoke a single test;
+- the build/type-check command;
+- the repo's own conventions (file-size limits, folder structure, lint rules) — adopt them, do not impose your own.
+
+If you cannot determine the test or build command, ask the human once. Do not guess and run.
+
+## Phase 1: Scope Discovery
+
+Identify every file related to the requested area. Search source, tests, prompts/resources, schemas/manifests, docs, scripts, build config, UI surfaces, and any telemetry/policy/scheduler/persistence code.
+
+Record *why* each file is in scope and classify it: primary, secondary, test, doc/resource, or possible graveyard. Do not pull in a file just because a keyword appears once.
+
+## Phase 2: Line Count And Grouping
+
+Count lines for every in-scope file. Build virtual groups, each ≤5000 total lines.
+
+- Keep strongly coupled files together.
+- Split large areas by contract: routing, approval, scheduler, persistence, prompts, UI, tests, tools.
+- A single file over 5000 lines becomes its own exception group, flagged as too large.
+- Include tests with the code they prove when the group stays under budget; otherwise a separate test group.
+- Keep generated/stale docs separate from executable code.
+
+For each group record: id, purpose, included files, total lines, the review question, expected source-of-truth contracts, and adjacent groups to cross-check.
+
+## Phase 3: Parallel Reviewer Assignment
+
+Spawn one subagent per group, in parallel, in the same turn. Give each the prompt in `references/reviewer-prompt.md`. Every reviewer is read-only and returns structured findings using the taxonomy in `references/findings-taxonomy.md`.
+
+If there are more groups than is practical to spawn at once, batch the spawns — but never collapse two groups into one reviewer, and never let a reviewer exceed its 5000-line budget.
+
+## Phase 4: Line-By-Line Review Standard
+
+This standard governs what reviewers look for. It is spelled out in `references/reviewer-prompt.md` so it can be handed to subagents verbatim. The core questions: what state does this read/write, is it authoritative or a cache, who else claims that truth, is this path reachable in production, does the test exercise real behavior, can success be marked before work is durable, can a schema/approval/UI claim something enforcement does not guarantee.
+
+## Phase 5: Synthesis
+
+Merge group reports into one architecture picture and the document set defined in `references/synthesis-docs.md` (index, architecture, review-batches, findings, graveyard-and-duplication, testing-gaps, product-gap-analysis, remediation-guide). Keep each doc small; split anything approaching the repo's file-size rule.
+
+Classify every finding using `references/findings-taxonomy.md`. Be consistent — the fix order in the next phase depends entirely on correct classification.
+
+## ⛔ Phase 6: The Approval Gate
+
+This is the center of the skill. Stop here. Present a **decision artifact** — not the full doc set, not diffs. The human reasons in product logic, so speak in product logic.
+
+For each proposed fix or fix-batch, present:
+- **What** changes, in one plain sentence (no code).
+- **Why** it matters — the user-facing or correctness consequence of leaving it.
+- **Blast radius** — what else touches this, what could break, reversibility.
+- **Class** — safety/truth bug, correctness, contract collapse, test repair, dead-code prune, or enhancement.
+- **Order rank** — where it falls in the minimum-risk sequence.
+
+Then present the ranked sequence and ask the human to approve, defer, or reject **each batch**. Offer a recommended default (usually: approve safety/truth and correctness now, hold enhancement). Explicitly state non-goals — what you will NOT touch.
+
+Wait for an explicit yes. Approval is per-batch and does not generalize. If the human approves only some batches, execute only those.
+
+## Phase 7: Execute Approved Fixes
+
+Fix only approved batches, in this order (skip any class the human deferred):
+
+1. **Safety & truth bugs** — approval gaps, irreversible side effects, external sends, destructive actions, premature success/cursor advancement.
+2. **Execution correctness** — scheduler completion, timeouts, retries, persistence/migrations.
+3. **Contract collapse** — one registry, one routing envelope, one executable schema, one status stream.
+4. **Test reliability** — stale tests, tests mirroring helpers, missing contract tests.
+5. **Graveyard pruning** — dead paths, stale resources, old shims (only after confirming unreachability).
+6. **Enhancement** — new capability, polish — only after the contracts above are stable.
+
+Never build new capability on top of conflicting contracts. After each change, pass the verification gate in `references/verification-gate.md` before moving on. Respect the repo's file-size and structure conventions detected in Phase 0.
+
+## Verification Gate
+
+No finding is closed until: the bug it addressed is named, the source of truth removed/enforced/validated is named, the line-level evidence of the old behavior is cited, a test or command proves the new behavior, and any remaining risk is stated. Full standard and commands in `references/verification-gate.md`. If verification cannot run, state exactly what was not run and why.
+
+## Final Handoff
+
+End with: batch coverage summary, highest-risk bugs found, duplicated contracts collapsed, dead-code pruned or quarantined, tests repaired, what was executed vs deferred vs rejected, remaining product gaps, and explicit non-goals.

package/files/skills/ultimate-code-review/references/findings-taxonomy.md

@@ -0,0 +1,57 @@
+# Findings Taxonomy
+
+Classify every finding into exactly one category. The fix order in Phase 7 depends on correct classification, so be strict about the boundaries.
+
+## Bug
+
+Current behavior can produce wrong state, unsafe state, data loss, incorrect UI truth, failed execution, or misleading success.
+
+Examples:
+- success recorded before execution completes;
+- approval shown as final before the side effect runs;
+- a cursor or offset advanced before downstream success;
+- schema accepts a field the runtime never implements;
+- a test passes while the production path it claims to cover is never exercised.
+
+## Architecture Issue
+
+The structure itself causes repeated bugs or blocks safe change. The code may "work" today but is shaped to break.
+
+Examples:
+- the same role/tool/permission policy duplicated in two places;
+- multiple approval queues that can disagree;
+- two schedulers, two status stores, two routing paths;
+- prompt assembled one way in docs, another way at runtime;
+- several UI surfaces each inferring truth from a different store.
+
+## Dead / Graveyard Code
+
+Code that appears stale, unreachable, superseded, compatibility-only, or actively misleading.
+
+Before recommending deletion:
+- search across all languages, prompts, docs, tests, build files, and runtime assets;
+- check generated text and resource bundles;
+- if reintroduction would be dangerous, recommend adding a test that locks the removal;
+- if removal changes user-facing behavior, require a migration or explicit fallback.
+
+## Test Gap
+
+Tests are missing, stale, unregistered, mirror helper logic instead of production logic, or assert something misleading.
+
+## Product Gap
+
+A capability the intended experience needs but the code does not provide. This is not a bug — nothing is wrong; something is absent. Kept separate because it is fixed last and only after contracts are stable.
+
+## Stabilize (the reliable path)
+
+Changes that make the *current* product reliable, explainable, and safe. Stabilize work usually converges the system toward:
+- one enforced lifecycle;
+- one authoritative registry;
+- one routing envelope;
+- one executable schema;
+- one status stream;
+- tests that prove the drift cannot return.
+
+## Enhance (the capable path)
+
+New capability that makes the product feel obviously better, not merely less broken. Enhance work starts only after stabilize-level contracts exist — otherwise you are building on sand. Examples: reliable automation with evidence and recovery, approval-and-rollback for changes, scoped secure builders, a unified status/control surface.

package/files/skills/ultimate-code-review/references/reviewer-prompt.md

@@ -0,0 +1,48 @@
+# Reviewer Subagent Prompt
+
+Hand this to each review subagent verbatim, filling in the bracketed fields. One reviewer per group. The reviewer is **read-only** — it must not edit any file.
+
+---
+
+## Prompt Template
+
+You are reviewing one group of files as part of a larger codebase audit. Do not edit anything. Your job is to understand how this code actually behaves today and report structured findings.
+
+**Group:** [group id]
+**Purpose of this group:** [one line]
+**Review question:** [the specific question this group must answer]
+**Files (read every one, line by line):**
+[list with line counts]
+**Expected source-of-truth contracts:** [what this group is supposed to own]
+**Adjacent groups to keep in mind:** [for cross-checking]
+
+### How to review
+
+Read every function, type, prompt, schema, test, and state transition. For each, ask:
+
+- What state does this read or write?
+- Is that state authoritative, or a cache of truth owned elsewhere?
+- What other file claims to own the same truth?
+- Is this path actually reachable in production, or is it dead/legacy/compat?
+- Does the test exercise real production behavior, or mirror helper logic?
+- Can this mark success before the work is durable?
+- Can an approval, policy, prompt, or UI claim something that enforcement does not actually guarantee?
+- Does a schema accept fields the runtime ignores?
+- Can cancellation, retries, migrations, or async delivery race?
+- Does the UI read from the same truth as the runtime?
+
+Cite concrete file paths and line references. Distinguish confirmed findings from hypotheses. Do not draw broad conclusions without a concrete code path.
+
+### Return findings in this structure
+
+- **Bugs** — behavior is wrong or unsafe now.
+- **Architecture Issues** — duplicated, conflicting, or missing source-of-truth contracts.
+- **Dead / Graveyard** — unused, stale, legacy, or compatibility-only paths.
+- **Test Gaps** — missing, stale, unregistered, or misleading tests.
+- **Product Gaps** — capability missing for the intended experience.
+- **Stabilize** — narrow changes that make current behavior reliable.
+- **Enhance** — future capability, only meaningful after stabilize work lands.
+
+For each finding give: the file + lines, what actually happens today, why it matters, and (for bugs/architecture) what would need to be true for a safe fix.
+
+Definitions for classifying findings are in `findings-taxonomy.md`.

package/files/skills/ultimate-code-review/references/synthesis-docs.md

@@ -0,0 +1,53 @@
+# Synthesis Documents
+
+After all reviewers return, merge their reports into one architecture picture plus the document set below. Keep each document small — if one approaches the repo's file-size rule, split it. Write them to a `review/` folder (or the repo's docs location).
+
+## The Document Set
+
+- **README.md** — index, read order, one-paragraph system summary, and the source-of-truth map (which file owns which truth).
+- **architecture.md** — current data flows and runtime layers, as they actually are, not as intended.
+- **review-batches.md** — every group, its files, line counts, and headline findings.
+- **findings.md** — consolidated bugs and risks grouped by theme.
+- **graveyard-and-duplication.md** — dead paths and duplicate concepts.
+- **testing-gaps.md** — stale tests and missing contract coverage.
+- **product-gap-analysis.md** — what is missing versus the intended product.
+- **remediation-guide.md** — a clean handoff a fresh agent could execute.
+
+These are the *evidence*. They are not what you put in front of the human at the gate.
+
+## The Decision Artifact (Phase 6)
+
+This is the only thing the human reads to decide. It is built from the docs above but contains no code and no diffs. Use this exact shape:
+
+```
+# Decision: <area> review
+
+## What I found (one paragraph, plain language)
+<the system in 3-4 sentences: what works, what's fragile, the single biggest risk>
+
+## Proposed fixes, ranked by minimum risk
+
+### Batch 1 — <name>  [Class: safety/truth]
+- What: <one plain sentence, no code>
+- Why it matters: <user-facing or correctness consequence of leaving it>
+- Blast radius: <what else touches this; what could break; reversible?>
+- Recommend: APPROVE NOW
+
+### Batch 2 — <name>  [Class: correctness]
+...
+
+### Batch N — <name>  [Class: enhancement]
+- Recommend: DEFER until contracts stable
+
+## What I will NOT touch (non-goals)
+<explicit list>
+
+## Your call
+Approve / defer / reject each batch. My default recommendation: <...>
+```
+
+Rules for the artifact:
+- One sentence of "what" per fix. If it needs a paragraph, the human can ask — keep the surface clean.
+- Always state blast radius and reversibility; that is what the human reasons about.
+- Always give a recommended default so the human can say "go with your defaults."
+- Never include batches the human hasn't seen classified. No surprises at execution time.

package/files/skills/ultimate-code-review/references/verification-gate.md

@@ -0,0 +1,62 @@
+# Stack Detection & Verification Gate
+
+## Phase 0: Stack Detection Checklist
+
+Detect, never assume. Run these before any other work and record the answers.
+
+**Language & layout**
+- Look for manifest files: `package.json`, `pyproject.toml` / `requirements.txt`, `Cargo.toml`, `go.mod`, `*.xcodeproj` / `Package.swift`, `pom.xml` / `build.gradle`, `Gemfile`, `composer.json`.
+- The manifest tells you the language, the package manager, and usually the scripts.
+
+**Search tool**
+- Prefer `rg` if present (`command -v rg`). Otherwise fall back to `grep -rn`.
+
+**Test runner** (read the manifest's scripts/config first)
+- JS/TS: check `package.json` scripts for `test`; detect `vitest` / `jest` / `mocha`. Find how to run ONE test file.
+- Python: `pytest` vs `unittest`; how to run one test.
+- Rust: `cargo test`. Go: `go test ./...`. Swift: `xcodebuild test` or `swift test`.
+- Never invent a runner — if the manifest doesn't reveal one, ask the human.
+
+**Build / type-check**
+- TS: `tsc --noEmit` or the project's build script. Python: type checker if configured (`mypy`, `pyright`). Rust: `cargo build`. Swift: `xcodebuild`.
+
+**Repo conventions**
+- Look for `.editorconfig`, lint configs, a `CLAUDE.md` or `CONTRIBUTING.md`, and any stated file-size or folder-structure rules. Adopt the repo's rules; do not impose external ones.
+
+If test or build commands can't be determined, ask once. Do not guess and run a command that could mutate state.
+
+## Verification Gate
+
+No finding is closed until every answer is clear:
+
+- What bug or issue did this address?
+- What source of truth was removed, enforced, or validated?
+- What line-level evidence showed the old behavior?
+- What test or command proves the new behavior?
+- What UI, event, or status now tells the truth?
+- What graveyard path was deleted, quarantined, or intentionally left?
+- What risk remains?
+
+## Verify narrowly, then broadly
+
+After a change, prove it locally before widening:
+
+```sh
+# 1. confirm the changed symbol/contract's call sites
+<search-tool> -n "changedSymbol"
+
+# 2. type-check / build (use the detected command)
+<build-command>
+
+# 3. run the single most relevant test first
+<test-runner> <one-test>
+
+# 4. then the surrounding suite
+<test-runner> <suite>
+```
+
+Use the repo's actual detected commands, not these placeholders. If full verification cannot run (missing credentials, no device, slow integration suite), state exactly what was not run and why, and what residual risk that leaves.
+
+## Order of execution (mirror of Phase 7)
+
+Fix safety/truth → correctness → contract collapse → test reliability → graveyard pruning → enhancement. Each step passes this gate before the next begins. Never build enhancement on unstable contracts.

package/package.json

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