@muggleai/works 4.15.1 → 5.0.0

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "4.15.1",
+  "version": "5.0.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "4.15.1",
+  "version": "5.0.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/hooks/README.md

@@ -0,0 +1,26 @@
+# Guardrail hooks
+
+Condition-triggered hooks that make Muggle Test's high-value handoffs fire path-independently — no matter whether a change was built via muggle-do, superpowers, or ad-hoc edits.
+
+## Two layers
+
+"Harness" spans two layers, and the distinction is load-bearing:
+
+- **Claude Code layer** — the agent runtime that fires these hooks. A guardrail is a Claude-Code-layer trigger, nothing more.
+- **Muggle Test layer** — the product (muggle-do, muggle-test, the watcher). This is what a guardrail *invokes*.
+
+A guardrail injects an advisory directive (`additionalContext`); the model then runs the Muggle Test flow. The guardrail never reimplements the flow.
+
+Design rationale: `muggle-ai-brain/architecture/2026-06-02-harness-pipeline-integration-design.md`.
+
+## Mechanism
+
+Each guardrail is a thin bash wrapper in `../scripts/` registered in `hooks.json`. The wrapper pipes the event payload (stdin JSON) to the bundled `../scripts/guardrails.mjs <subcommand>`, which holds the decision logic (built from `src/guardrails/`, vitest-covered). Per-session state in `~/.muggle-ai/guardrails/<session_id>.json` makes each guardrail fire once. Any failure degrades to `{}` — a guardrail must never block a turn.
+
+## Guardrails
+
+| Hook event | Wrapper | Condition | Preference | Flow invoked |
+| :--------- | :------ | :-------- | :--------- | :----------- |
+| `PostToolUse` (Bash) | `guardrail-pr-opened.sh` | a `gh pr create`/`gh pr ready` just succeeded | `autoWatchPR` | start a `muggle-pr-followup` watcher on the new PR |
+| `Stop` | `guardrail-e2e-gate.sh` | unit tests passed this session and no E2E ran yet (recorded by `guardrail-record-tests.sh`) | `autoE2ETest` | run change-driven E2E via `muggle-test` before finishing |
+| `UserPromptSubmit` | `guardrail-build-router.sh` | a build/implement/fix request (first one this session) | `autoRouteBuildToMuggleDo` | route the work through `muggle-do` (build delegated to superpowers) |

package/dist/plugin/hooks/hooks.json

@@ -11,6 +11,45 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-pr-opened.sh\"",
+            "async": false
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-tests.sh\"",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-e2e-gate.sh\"",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-build-router.sh\"",
+            "async": false
+          }
+        ]
+      }
     ]
   }
 }

package/dist/plugin/scripts/ensure-electron-app.sh

@@ -109,7 +109,7 @@ if [ -f "$prefs_global_file" ]; then
         postPRVisualWalkthrough:'ask', autoCreatePR:'ask',
         checkForUpdates:'ask', verboseOutput:'ask',
         autoUseWorktree:'ask', autoRebase:'ask', autoCleanup:'ask',
-        autoE2ETest:'always'
+        autoE2ETest:'always', autoRouteBuildToMuggleDo:'ask'
       };
       const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
       const pPath = require('path').join(cwd, '.muggle-ai', 'preferences.json');

package/dist/plugin/scripts/guardrail-build-router.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Front-door router (UserPromptSubmit). On the first build/implement/fix prompt
+# of a session, offers to route the work through /muggle-do (build delegated to
+# superpowers), gated by autoRouteBuildToMuggleDo. Fires once per session.
+# Degrades to {} so it never blocks a turn.
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+node "${root}/scripts/guardrails.mjs" build-router 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrail-e2e-gate.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# tests-green → E2E gate (Stop). When unit tests passed this session and no E2E
+# acceptance run has happened, offer to run change-driven E2E (gated by
+# autoE2ETest). Fires once per session. Degrades to {} so it never blocks a turn.
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+node "${root}/scripts/guardrails.mjs" e2e-gate 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrail-pr-opened.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PR-opened guardrail (PostToolUse/Bash). When a `gh pr create`/`gh pr ready`
+# just succeeded, offer to start a muggle-pr-followup watcher on the new PR
+# (gated by autoWatchPR, deduped per session). Decision logic lives in the
+# bundled guardrails.mjs; this wrapper just pipes the event payload through and
+# degrades to {} so a guardrail can never block a turn.
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+node "${root}/scripts/guardrails.mjs" pr-opened 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrail-record-tests.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# tests-green observer (PostToolUse/Bash). Records in per-session state when a
+# unit-test command passed (and when a muggle E2E run happened). Emits no
+# directive — the Stop gate (guardrail-e2e-gate.sh) reads the state. Degrades
+# to {} so it never blocks a turn.
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+node "${root}/scripts/guardrails.mjs" record-tests 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrails.mjs

@@ -0,0 +1,143 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// src/guardrails/cli.ts
+var baseDir = (override) => override ?? join(homedir(), ".muggle-ai", "guardrails");
+var fileFor = (sessionId2, override) => join(baseDir(override), `${sessionId2.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+function readState(sessionId2, dirOverride) {
+  const f = fileFor(sessionId2, dirOverride);
+  if (!existsSync(f)) return { sessionId: sessionId2, prsHandled: [] };
+  try {
+    const raw = JSON.parse(readFileSync(f, "utf-8"));
+    return { ...raw, sessionId: sessionId2, prsHandled: raw.prsHandled ?? [] };
+  } catch {
+    return { sessionId: sessionId2, prsHandled: [] };
+  }
+}
+function writeState(state, dirOverride) {
+  mkdirSync(baseDir(dirOverride), { recursive: true });
+  writeFileSync(fileFor(state.sessionId, dirOverride), JSON.stringify(state, null, 2));
+}
+function markPrHandled(sessionId2, prUrl, dirOverride) {
+  const state = readState(sessionId2, dirOverride);
+  if (!state.prsHandled.includes(prUrl)) state.prsHandled.push(prUrl);
+  writeState(state, dirOverride);
+}
+
+// src/guardrails/prOpened.ts
+var PR_URL = /https:\/\/github\.com\/[^/\s]+\/[^/\s]+\/pull\/\d+/;
+var CREATE_CMD = /\bgh\s+pr\s+(create|ready)\b/;
+function detectPrOpened(input2) {
+  if (input2.tool_name !== "Bash") return null;
+  const cmd = input2.tool_input?.command ?? "";
+  if (!CREATE_CMD.test(cmd)) return null;
+  const out = `${input2.tool_response?.stdout ?? ""}
+${input2.tool_response?.output ?? ""}`;
+  const m = out.match(PR_URL);
+  return m ? m[0] : null;
+}
+
+// src/guardrails/testsGreen.ts
+var TEST_CMD = /\b(pnpm|npm|yarn)\s+(run\s+)?test\b|\b(jest|vitest|pytest)\b|\bgo\s+test\b|\bcargo\s+test\b/;
+var FAIL = /\b\d+\s+failed\b|\bFAIL\b|✗/;
+var E2E_RUN = /\bmuggle\b[^\n]*\b(execute|test)\b/i;
+function isTestCommand(cmd) {
+  return TEST_CMD.test(cmd);
+}
+function testsPassed(input2) {
+  const out = `${input2.tool_response?.stdout ?? ""}
+${input2.tool_response?.stderr ?? ""}`;
+  if (!out.trim()) return false;
+  return !FAIL.test(out);
+}
+function isE2ERun(input2) {
+  const cmd = input2.tool_input?.command ?? "";
+  const tool = input2.tool_name ?? "";
+  return E2E_RUN.test(cmd) || /muggle.*(execute|test-generation|replay)/i.test(tool);
+}
+
+// src/guardrails/shouldRunE2E.ts
+function shouldRunE2E(state) {
+  return state.unitTestsGreen === true && state.e2eRun !== true;
+}
+
+// src/guardrails/detectBuildIntent.ts
+var BUILD = /\b(implement|build|add|create|write|fix|refactor|wire up|hook up|make (a|the|it)|change the)\b/i;
+var QUESTION = /^\s*(why|what|how|when|where|who|is|are|does|do|can you (explain|tell)|explain)\b/i;
+function detectBuildIntent(prompt) {
+  const p = (prompt ?? "").trim();
+  if (!p || p.startsWith("/")) return false;
+  if (QUESTION.test(p)) return false;
+  return BUILD.test(p);
+}
+
+// src/guardrails/emit.ts
+function envelope(eventName, context, host2) {
+  if (!context) return "{}";
+  if (host2 === "cursor") return JSON.stringify({ additional_context: context });
+  return JSON.stringify({
+    hookSpecificOutput: { hookEventName: eventName, additionalContext: context }
+  });
+}
+
+// src/guardrails/cli.ts
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+var host = process.env.CURSOR_PLUGIN_ROOT ? "cursor" : "claude";
+var sub = process.argv[2];
+var input = readStdin();
+var sessionId = input.session_id ?? "unknown";
+function prOpened() {
+  const url = detectPrOpened(input);
+  if (!url) return "{}";
+  if (readState(sessionId).prsHandled.includes(url)) return "{}";
+  markPrHandled(sessionId, url);
+  const ctx = `A pull request was just opened: ${url}
+Per the autoWatchPR preference, a muggle-pr-followup watcher should handle its incoming reviews. If autoWatchPR=always, start it now by invoking /muggle:muggle-pr-followup with the PR URL; if =ask, offer it to the user; if =never, do nothing.`;
+  return envelope("PostToolUse", ctx, host);
+}
+function recordTests() {
+  const cmd = input.tool_input?.command ?? "";
+  const state = readState(sessionId);
+  let changed = false;
+  if (isTestCommand(cmd) && testsPassed(input)) {
+    state.unitTestsGreen = true;
+    changed = true;
+  }
+  if (isE2ERun(input)) {
+    state.e2eRun = true;
+    changed = true;
+  }
+  if (changed) writeState(state);
+  return "{}";
+}
+function e2eGate() {
+  const state = readState(sessionId);
+  if (!shouldRunE2E(state)) return "{}";
+  state.e2eRun = true;
+  writeState(state);
+  const ctx = `Unit tests passed this session and no E2E acceptance run has happened yet. Per the autoE2ETest preference (default: always), run change-driven E2E now via /muggle:muggle-test before finishing. If autoE2ETest=never, skip.`;
+  return envelope("Stop", ctx, host);
+}
+function buildRouter() {
+  if (!detectBuildIntent(input.prompt ?? "")) return "{}";
+  const state = readState(sessionId);
+  if (state.buildIntentRouted) return "{}";
+  state.buildIntentRouted = true;
+  writeState(state);
+  const ctx = `This looks like a build/implement/fix request. Per the autoRouteBuildToMuggleDo preference, route it through /muggle-do \u2014 which runs requirements \u2192 build (delegated to superpowers' design\u2192plan\u2192review) \u2192 impact \u2192 unit tests \u2192 E2E \u2192 PR \u2192 watcher. If autoRouteBuildToMuggleDo=always, enter that flow; if =ask, offer it; if =never, proceed normally.`;
+  return envelope("UserPromptSubmit", ctx, host);
+}
+var handlers = {
+  "pr-opened": prOpened,
+  "record-tests": recordTests,
+  "e2e-gate": e2eGate,
+  "build-router": buildRouter
+};
+process.stdout.write((handlers[sub] ?? (() => "{}"))());

package/dist/plugin/skills/_shared/github-cli-recipes/pr-metadata.md

@@ -4,9 +4,10 @@ Fetch the fields the watcher and bootstrap need in one call.
 
 ```bash
 gh pr view <pr-number> --repo <owner>/<repo> \
-  --json url,number,headRefOid,headRefName,baseRefName,state,mergedAt,closedAt,body,title,author
+  --json url,number,headRefOid,headRefName,baseRefName,state,mergeable,mergeStateStatus,mergedAt,closedAt,body,title,author
 ```
 
 - `state` is one of `OPEN`, `MERGED`, `CLOSED`.
 - `headRefOid` is the current head SHA — store as `head_sha` in `prs.json`.
 - `headRefName` is the branch — must match the working tree's branch in bootstrap.
+- `mergeable` is `MERGEABLE`, `CONFLICTING`, or `UNKNOWN` (GitHub still computing — treat as not-conflicting this tick). `mergeStateStatus` (`DIRTY` = conflicts, `BEHIND`, `CLEAN`, …) corroborates it. The watcher uses these to detect a merge-conflict that no review or CI signal would surface.

package/dist/plugin/skills/_shared/pr-followup-helpers/echo-skip.md

@@ -0,0 +1,16 @@
+# Reply-echo skip
+
+When `/muggle-do` posts a threaded reply to a review comment, GitHub surfaces that reply as a **new submitted review** under the same account. Left unchecked, the next watcher tick reads that review as fresh feedback and dispatches another cycle — which posts another reply, which becomes another review. The loop never converges.
+
+## Rule
+
+A submitted review is an **echo** when **every** comment in it carries the loop marker `<!-- muggle-do:bot -->` (see [`loop-signature.md`](loop-signature.md)). An echo is the loop's own reply wearing a review's clothing, never human intent.
+
+On an echo review, the watcher must:
+
+1. Advance `last_seen.reviewId` past the echo's id (so it is not seen again), and
+2. **Skip it** — never dispatch `/muggle-do` for it.
+
+## Detection
+
+Classify by the marker, never by `author.login` — under a shared account the loop posts as the PR author, so the login cannot tell echo from human. Fetch the review's comments; if the set is non-empty and every comment body contains `<!-- muggle-do:bot -->`, it is an echo. A review with at least one marker-less comment is human feedback and must be processed normally.

package/dist/plugin/skills/_shared/pr-followup-helpers.md

@@ -12,3 +12,4 @@ Each section is its own file — load only what the current step needs.
 | [`reply-routing`](pr-followup-helpers/reply-routing.md) | Pick the right reply endpoint per comment type (line, body-only, CI failure). |
 | [`classify`](pr-followup-helpers/classify.md) | Per-review binary label: actionable vs ambiguous, with worked examples + borderline rule. |
 | [`loop-signature`](pr-followup-helpers/loop-signature.md) | The signature every loop-posted comment carries, and how to detect loop vs human comments by it. |
+| [`echo-skip`](pr-followup-helpers/echo-skip.md) | Skip reviews that are the loop's own replies (every comment loop-marked), so the watcher never re-triggers on itself. |

package/dist/plugin/skills/do/address-reviews.md

@@ -114,7 +114,7 @@ Refresh PR state per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared
 1. Write `result.md` per [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md#resultmd).
 2. Do **not** respawn the watcher.
 
-Otherwise, dispatch the next watcher as the last action of this turn:
+Otherwise, dispatch the next watcher as the last action of this turn. The watcher cancelled its own cron when it dispatched this cycle ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md) Step 4), so this restart is the single live watcher — never a duplicate:
 
 ```
 /loop 1m /muggle:muggle-pr-followup <slug> <n>

package/dist/plugin/skills/do/build.md

@@ -29,6 +29,10 @@ For each affected repo:
 
    The body explains *why* when the why is non-obvious. The diff already says *what*.
 
+## Delegation
+
+For a non-trivial change — multiple files, real design surface, or anything you would otherwise brainstorm before coding — run the implementation through superpowers' design → plan → subagent-driven build, then return to this stage's Output. That is a runtime hand-off (an action), not a doc dependency; do not encode superpowers' internals here. Routing a build request into this pipeline (the `autoRouteBuildToMuggleDo` front-door guardrail) exists to combine superpowers' design rigor with this pipeline's impact analysis, E2E, PR, and watcher — neither delivers both alone.
+
 ## Output
 
 Per repo:

package/dist/plugin/skills/do/cleanup.md

@@ -1,14 +1,15 @@
 # Post-Merge Cleanup Stage
 
-Invoked by `/muggle-do` when the watcher forwards a PR's terminal (`merged`) state. This stage only resolves the session's workspace and **delegates** teardown to the shared procedure — it does not restate the teardown steps. Never runs while the PR is open.
+Invoked by `/muggle-do` when the watcher forwards a PR's terminal state. On `merged` it resolves the session's workspace and **delegates** teardown to the shared procedure (it does not restate the teardown steps); on `closed` (unmerged) it skips teardown. Either way it ends by suggesting the next step. Never runs while the PR is open.
 
 ## Input
 
-`$ARGUMENTS` carries the session slug as `slug=<slug>`. No PR URL, no review ids.
+`$ARGUMENTS` carries `slug=<slug>` and `state=<merged|closed>` (default `merged`). No PR URL, no review ids.
 
 ## Procedure
 
 1. Read `~/.muggle-ai/muggle-do/sessions/<slug>/`: `prs.json` (PR `repo`, `number`, observed `state`) and `state.md` (`worktreePath` if a worktree was used, and the target branch `headRefName`).
-2. Confirm `prs.json` shows the PR `merged`. If it is still open or was closed unmerged, do nothing and exit — this stage is post-merge only.
-3. Run [`../_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md) with `{worktreePath}` and `{branch}`. That file owns the teardown sequence **and its safety rules** — including skipping worktree-remove and local branch deletion when no worktree was used. This stage adds no teardown logic of its own.
-4. Append a cleanup line to the session's `followup.log`.
+2. If `prs.json` shows the PR still open, do nothing and exit — this stage is terminal-only.
+3. **Teardown (`merged` only).** When the PR is `merged`, run [`../_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md) with `{worktreePath}` and `{branch}`. That file owns the teardown sequence **and its safety rules** — including skipping worktree-remove and local branch deletion when no worktree was used. This stage adds no teardown logic of its own. On `closed`, skip teardown — the branch and any worktree stay intact.
+4. Append a cleanup line to the session's `followup.log`, recording whether teardown ran.
+5. Suggest the next step per [`next-step.md`](next-step.md), passing whether teardown ran. This is the stage's last action.

package/dist/plugin/skills/do/fix-ci.md

@@ -40,7 +40,7 @@ Commit per the `fix(ci): <check> — <what>` convention ([`../_shared/pr-followu
 ### Step 5 — Update state + respawn
 
 - Increment `last_seen.ci_fix_attempts[red_sha]`.
-- Respawn the watcher: `/loop 1m /muggle:muggle-pr-followup <slug> <n>`. CI on the new SHA is the verify loop — a still-red SHA returns as a fresh dispatch, bounded by the per-SHA fix budget (Step 6).
+- Respawn the watcher: `/loop 1m /muggle:muggle-pr-followup <slug> <n>`. The watcher cancelled its own cron when it dispatched this fix-ci cycle ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md) Step 5), so this restart is the single live watcher. CI on the new SHA is the verify loop — a still-red SHA returns as a fresh dispatch, bounded by the per-SHA fix budget (Step 6).
 
 ### Step 6 — Escalate (budget spent or out of scope)
 

package/dist/plugin/skills/do/input-routing.md

@@ -1,12 +1,13 @@
 # Input routing
 
-How `/muggle-do` resolves `$ARGUMENTS` to a mode. Modes 1–3 are programmatic — dispatched by the watcher — so never ask on those. Inspect in order:
+How `/muggle-do` resolves `$ARGUMENTS` to a mode. Modes 1–4 are programmatic — dispatched by the watcher — so never ask on those. Inspect in order:
 
 1. **Address-reviews** — a `github.com/.../pull/<n>` URL **and** one or more review ids (integers ≥ 100000000) → [`address-reviews.md`](address-reviews.md).
 2. **Fix-CI** — a `github.com/.../pull/<n>` URL **and** a `fix ci` / `fix-ci` directive with failing check names (no review ids) → [`fix-ci.md`](fix-ci.md).
-3. **Post-merge cleanup** — a `cleanup` token and `slug=<slug>` (no PR URL, no review ids) → [`cleanup.md`](cleanup.md).
-4. **Empty / `help` / `menu` / `?`** → menu + session selector.
-5. **Task automation** (perform an action on a website) → `muggle:muggle-browser-task`.
-6. **Otherwise** → forward pipeline at Stage 1.
+3. **Resolve-conflicts** — a `github.com/.../pull/<n>` URL **and** a `resolve conflicts` / `resolve-conflicts` directive (no review ids, no check names) → [`resolve-conflicts.md`](resolve-conflicts.md).
+4. **Post-merge cleanup** — a `cleanup` token and `slug=<slug>` (no PR URL, no review ids), optionally `state=<merged|closed>` (default `merged`) → [`cleanup.md`](cleanup.md).
+5. **Empty / `help` / `menu` / `?`** → menu + session selector.
+6. **Task automation** (perform an action on a website) → `muggle:muggle-browser-task`.
+7. **Otherwise** → forward pipeline at Stage 1.
 
-When in doubt between #5 and #6, ask one question.
+When in doubt between #6 and #7, ask one question.

package/dist/plugin/skills/do/next-step.md

@@ -0,0 +1,18 @@
+# Next-Step Suggestion
+
+Closing step of a terminal `/muggle-do` turn (post-merge or post-close). Advances silently when the session still has a plan, stops and asks when it doesn't.
+
+## Input
+
+- `slug` — the session.
+- `teardownRan` — whether [`cleanup.md`](cleanup.md) already ran teardown (true on `merged` + `autoCleanup: always`; false on `closed` or a skipped gate).
+
+## Procedure
+
+1. Read the session plan — the current session's TodoWrite list.
+2. **Pending items remain** → do not prompt. Append `next-step: plan has <N> pending — advancing` to `followup.log` and continue to the next pending item. The user set a course; honor it.
+3. **No pending items** → stop and ask for directions with one `AskUserQuestion` selector:
+   - **Clean up now** — offer only when `teardownRan` is false (a `closed` PR, or `merged` with `autoCleanup` not `always`). Runs the shared teardown [`../_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md) for this slug, under its own safety rules.
+   - **Move on / next task** — start a fresh `/muggle-do` forward run, or pick another open session.
+   - **Done — stop here** — exit with no further action.
+4. Append the chosen outcome to `followup.log`.

package/dist/plugin/skills/do/open-prs/forward.md

@@ -78,3 +78,5 @@ Append one short reminder tied to the gate value:
 - `always` → `Once merged, I'll run the cleanup sequence automatically.`
 - `never` → omit.
 - `ask` / absent → `Once merged, I'll check with you about cleanup.`
+
+Regardless of the gate, also append: `Once it's merged or closed, I'll move to the next plan item — or ask where to go next if there's no plan.`

package/dist/plugin/skills/do/resolve-conflicts.md

@@ -0,0 +1,62 @@
+# Resolve-Conflicts (watcher-dispatched)
+
+Rebase a PR whose branch conflicts with its base, resolve the conflicts behind a verify-or-rollback gate, and force-push — so a mergeable-blocked PR doesn't sit idle forever. A dumb-pipe dispatch like fix-ci: the watcher detects `mergeable == CONFLICTING` and hands off; the executor owns the rebase + resolution, never the decision to dispatch.
+
+## Turn preamble
+
+```
+**/muggle-do resolve-conflicts** — rebasing <owner>/<repo>#<n> onto <base> to clear merge conflicts.
+```
+
+## Input
+
+`$ARGUMENTS` carries a `github.com/.../pull/<n>` URL, `slug=<slug>`, and a `resolve conflicts` directive (no review ids, no failing check names). Parse all three.
+
+## Inputs from disk
+
+From `~/.muggle-ai/muggle-do/sessions/<slug>/`: `prs.json` (PR + branch + `head_sha`), `last_seen.json` (`conflict_resolve_attempts`, `conflict_escalated_shas`, `pushed_shas`), `state.md` (worktree path, validation strategy, base branch).
+
+## Procedure
+
+### Step 1 — Re-attach
+
+Materialize the PR branch in its worktree per [`../_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md) (or use `state.md`'s `worktreePath`). Capture `conflict_sha = prs.json[0].head_sha` and the base branch (`baseRefName` from [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md)).
+
+### Step 2 — Rebase onto base + resolve
+
+Run [`../_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md) against the base branch (it fires because a conflicting PR is behind). Conflict handling follows [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md):
+
+- default `never` → abort and escalate per Step 5 (`kind: "rebase-conflict"`). The watcher keeps polling; the user resolves on GitHub, or opts into `autoResolveConflicts=always`.
+- `always` → resolve behind the verify-or-rollback gate in [`../_shared/resolve-rebase-conflicts.md`](../_shared/resolve-rebase-conflicts.md).
+
+### Step 3 — Verify the resolution
+
+Build (typecheck + lint on the changed surface) + unit suite must pass. Run E2E per [`e2e-acceptance.md`](e2e-acceptance.md) when app logic changed and the session carries validation context. A resolution that does not verify is rolled back → escalate per Step 5. **Never push an unverified merge.**
+
+### Step 4 — Force-push + respawn
+
+Push with `--force-with-lease` (the rebase rewrote history). Append the new SHA to `last_seen.pushed_shas`; increment `last_seen.conflict_resolve_attempts[conflict_sha]`. Respawn the watcher as the last action:
+
+```
+/loop 1m /muggle:muggle-pr-followup <slug> <n>
+```
+
+The watcher cancelled its own cron when it dispatched this cycle ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md) Step 5b), so this restart is the single live watcher. Its next tick re-checks mergeability on the new head — the rebase is its own verify loop, bounded by the per-SHA attempt budget.
+
+### Step 5 — Escalate (can't resolve / budget spent)
+
+When `autoResolveConflicts=never`, the resolution failed verification, or `conflict_resolve_attempts[conflict_sha]` has reached 2:
+
+1. Add `conflict_sha` to `last_seen.conflict_escalated_shas` so the watcher does not re-dispatch this SHA.
+2. Emit one terminal escalation naming the PR and the conflicting files.
+3. Respawn the watcher (last action) — it keeps polling for the user's manual resolution or any new reviews.
+
+### Step 6 — Telemetry
+
+Emit one `muggle-do:cycle` event ([`../_shared/telemetry-events/muggle-do-cycle.md`](../_shared/telemetry-events/muggle-do-cycle.md)) with `outcome: "conflicts-resolved"` (a verified rebase pushed) or `"conflicts-escalated"`.
+
+## Guardrails
+
+- Max 2 resolve attempts per SHA; then escalate rather than churn.
+- Never push an unverified merge — verify-or-rollback always.
+- The default `autoResolveConflicts=never` escalates to the user rather than guessing a merge. Auto-resolution is strictly opt-in.

package/dist/plugin/skills/muggle-do/SKILL.md

@@ -55,7 +55,7 @@ When invoked with the directive (PR URL + slug + review ids), routes to [`../do/
 
 ## Input routing
 
-`/muggle-do` serves one interactive mode (the forward pipeline, from a fresh task) and three programmatic modes the watcher dispatches (address-reviews, fix-ci, post-merge cleanup). Resolve `$ARGUMENTS` to a mode per [`../do/input-routing.md`](../do/input-routing.md) before doing anything else.
+`/muggle-do` serves one interactive mode (the forward pipeline, from a fresh task) and four programmatic modes the watcher dispatches (address-reviews, fix-ci, resolve-conflicts, post-merge cleanup). Resolve `$ARGUMENTS` to a mode per [`../do/input-routing.md`](../do/input-routing.md) before doing anything else.
 
 ## Preferences
 
@@ -63,6 +63,7 @@ When invoked with the directive (PR URL + slug + review ids), routes to [`../do/
 | :--------- | :--- |
 | `autoE2ETest` | Stage 6 — run E2E every cycle (default `always`), or fold into pre-flight |
 | `autoResolveConflicts` | On rebase conflict — resolve autonomously behind a verify-or-rollback gate (opt-in), or abort + escalate (default `never`) |
+| `autoRouteBuildToMuggleDo` | Front-door guardrail — route build/implement/fix requests through this pipeline (build delegated to superpowers); fired by the UserPromptSubmit guardrail, default `ask` |
 
 `autoUseWorktree`, `autoRebase`, `autoResolveConflicts`, `autoCreatePR`, `autoCleanup` fire from per-stage files.
 

package/dist/plugin/skills/muggle-pr-followup/SKILL.md

@@ -7,7 +7,7 @@ description: Use this skill when the user wants a pull request's incoming review
 
 > Telemetry first step: see [`../_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-followup"`.
 
-A watcher that babysits one open PR's review thread and CI. Polls for new submitted reviews and check-run state; when review feedback lands or CI goes red, hands the work to `/muggle-do` and exits. On merge, it hands off post-merge cleanup to `/muggle-do` the same way. `/muggle-do` is the executor — it classifies the reviews or fixes the failing checks, pushes, replies per comment, and respawns the watcher.
+A watcher that babysits one open PR's review thread, CI, and merge-conflict state. Polls for new submitted reviews, check-run state, and mergeability; when review feedback lands, CI goes red, or the branch conflicts with its base, hands the work to `/muggle-do` and exits. On merge or close, it hands the terminal wrap-up to `/muggle-do` the same way — teardown when merged, then a next-step suggestion. `/muggle-do` is the executor — it classifies the reviews, fixes the failing checks, or rebases-and-resolves the conflict, pushes, replies per comment, and respawns the watcher.
 
 **The watcher is a dumb pipe.** It does not classify reviews, iterate cycles, post replies, or escalate. All of that lives in `/muggle-do`. See [stage-8 design](../../../../muggle-ai-brain/architecture/2026-05-08-muggle-do-pr-comment-loop-design.md) for the rationale.