@muggleai/works 4.15.1 → 5.0.1

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

@@ -1,6 +1,6 @@
 # Watcher Per-Tick Contract
 
-The procedure for the **tick mode** of `muggle-pr-followup` — one polling iteration scoped to one PR. The watcher is a dumb pipe: it polls for new submitted reviews and CI checks, dispatches `/muggle-do` if there's review feedback or fixable red CI, and exits. It does not classify, fix, amend requirements, post replies, run cycles, or escalate.
+The procedure for the **tick mode** of `muggle-pr-followup` — one polling iteration scoped to one PR. The watcher is a dumb pipe: it polls for new submitted reviews, CI checks, and merge-conflict state, dispatches `/muggle-do` if there's review feedback, fixable red CI, or an unmergeable branch, and exits. It does not classify, fix, resolve, amend requirements, post replies, run cycles, or escalate.
 
 Routing into this mode is documented in [`SKILL.md`](SKILL.md#routing). The architectural rationale lives in the brain doc `architecture/2026-05-08-muggle-do-pr-comment-loop-design.md`.
 
@@ -25,35 +25,43 @@ If either file is missing or the PR is not in `prs.json`, the tick is a no-op. L
 
 ## Procedure
 
+### Step 0 — Stale-fire guard
+
+If `prs.json[0].state` on disk is already `merged` or `closed`, this slot was finalized by a prior tick and this is a stale (queued) fire — per-minute cron fires enqueued while the session was busy still drain after the cron is cancelled. Defensively cancel any lingering cron for this slug (`CronList` → the job whose command ends with `/muggle:muggle-pr-followup <slug> <n>` → `CronDelete`; no-op if none), append a `stale-tick` line to `followup.log`, and exit. Do not re-fetch or re-finalize.
+
 ### Step 1 — Refresh PR state
 
-Per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md). Update `prs.json[0].head_sha` and `prs.json[0].state` from the response.
+Per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md). Update `prs.json[0].head_sha` and `prs.json[0].state` from the response; keep `mergeable` / `mergeStateStatus` from the same call for Step 5.
 
 ### Step 2 — Termination check
 
 If `state` is `MERGED` or `CLOSED`:
 
 1. Finalize the slot per [`finalize.md`](finalize.md) — mark terminal, write `result.md`, log + telemetry, unschedule this watcher's cron.
-2. **If `MERGED`**, hand off post-merge cleanup as the last action of the turn (skip on `CLOSED` — unmerged, leave the branch and any worktree intact):
+2. Hand off the terminal wrap-up as the last action of the turn — for both `MERGED` and `CLOSED`:
 
    ```
-   /muggle-do post-merge cleanup slug=<slug>
+   /muggle-do post-merge cleanup slug=<slug> state=<merged|closed>
    ```
 
-   `/muggle-do` owns the worktree/branch knowledge and honors the `autoCleanup` gate. This is a runtime dispatch, not a doc dependency on `/muggle-do` — see the one-way rule in [`../CLAUDE.md`](../CLAUDE.md).
+   `/muggle-do` owns the worktree/branch knowledge: it runs teardown only on `merged` (honoring the `autoCleanup` gate — `closed` is unmerged, so the branch and any worktree stay intact), then suggests the next step. This is a runtime dispatch, not a doc dependency on `/muggle-do` — see the one-way rule in [`../CLAUDE.md`](../CLAUDE.md).
 3. Exit. The watcher has unscheduled itself; no future ticks fire for this PR.
 
 
 ### Step 3 — Fetch new submitted reviews
 
-Per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md). **Also exclude review ids that appear in `last_seen.escalated_review_ids`** — those have already been escalated and the watcher must not re-dispatch them.
+Per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md). Exclude two kinds of review id:
+
+- ids in `last_seen.escalated_review_ids` — already escalated; the watcher must not re-dispatch them.
+- **echo reviews** per [`../_shared/pr-followup-helpers/echo-skip.md`](../_shared/pr-followup-helpers/echo-skip.md) — a review whose every comment carries the loop marker is the loop's own reply, surfaced by GitHub as a new review. Advance `last_seen.reviewId` past it and skip; never dispatch, or the watcher replies to itself forever.
 
 ### Step 4 — If one or more new reviews → dispatch (reviews preempt CI)
 
 The watcher does **not** classify. Classification, batching, replying, escalation, and cycle execution all live in `/muggle-do`. The watcher's job is to hand over the list of new review ids and exit.
 
 1. Reset `last_seen.idle_tick_count` to 0.
-2. Dispatch `/muggle-do` with an *address-reviews* directive carrying:
+2. **Stop this watcher (single-thread).** Cancel its cron so no tick fires while the dev cycle runs: `CronList`, find the job whose command ends with `/muggle:muggle-pr-followup <slug> <n>` (exact two-arg match), `CronDelete` it. `/muggle-do` respawns the watcher when the cycle finishes — exactly one cron ever, and no tick overlaps a running cycle.
+3. Dispatch `/muggle-do` with an *address-reviews* directive carrying:
    - PR URL (from `prs.json[0].url`)
    - Session slug (from the invocation arguments)
    - Every new review id from Step 3, as a space-separated list
@@ -62,11 +70,26 @@ The watcher does **not** classify. Classification, batching, replying, escalatio
    ```
    /muggle-do address reviews <id1> <id2> ... on <pr-url> slug=<slug>
    ```
-3. Append a dispatching line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
-4. Emit a `tick` event with `reviews_seen: <count>`, `dispatched_review_ids: [<id>, ...]`.
-5. Exit. **Reviews preempt CI** — when reviews land, this tick dispatches address-reviews and never polls CI. The cron keeps firing; the next tick still arrives. The watcher only self-unschedules in Step 2 (terminal).
+4. Append a dispatching line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+5. Emit a `tick` event with `reviews_seen: <count>`, `dispatched_review_ids: [<id>, ...]`.
+6. Exit. **Reviews preempt CI** — when reviews land, this tick dispatches address-reviews and never polls CI. The watcher is now stopped; the dev cycle owns the PR and restarts the watcher when it finishes. (The watcher also self-unschedules in Step 2, terminal.)
+
+### Step 5 — No new reviews → check mergeability
+
+Read `mergeable` / `mergeStateStatus` from the Step 1 metadata. If `mergeable == CONFLICTING` (or `mergeStateStatus == DIRTY`), **and** `conflict_resolve_attempts[head_sha] < 2`, **and** `head_sha` ∉ `conflict_escalated_shas` → dispatch and exit:
+
+  1. Reset `last_seen.idle_tick_count` to 0.
+  2. **Stop this watcher (single-thread):** cancel its cron exactly as in Step 4 — `/muggle-do`'s resolve-conflicts respawns it when the cycle is done.
+  3. Dispatch `/muggle-do` with a *resolve-conflicts* directive (PR URL + slug; no review ids, no check names):
+     ```
+     /muggle-do resolve conflicts on <pr-url> slug=<slug>
+     ```
+  4. Append a dispatching line to `followup.log`; emit a `tick` event with `conflicting: true`, `dispatched_resolve_conflicts: true`.
+  5. Exit. The dev cycle owns the PR; its respawn restarts the watcher, whose next tick re-checks mergeability on the new head — the rebase is its own verify loop, bounded by the per-SHA attempt budget.
+
+`mergeable == MERGEABLE` / `UNKNOWN` (GitHub still computing — treat as not-conflicting this tick), or budget spent (`conflict_resolve_attempts[head_sha] >= 2` or `head_sha` ∈ `conflict_escalated_shas`) → fall through to CI.
 
-### Step 5 — No new reviews → poll CI for the head SHA
+### Step 6 — No new reviews, mergeable → poll CI for the head SHA
 
 Fetch the check-run rollup for `prs.json[0].head_sha` per [`../_shared/github-cli-recipes/pr-checks.md`](../_shared/github-cli-recipes/pr-checks.md), then:
 
@@ -74,17 +97,18 @@ Fetch the check-run rollup for `prs.json[0].head_sha` per [`../_shared/github-cl
 - **All checks green / skipped, or no checks** → idle (green path).
 - **One or more checks red** (`bucket == "fail"`), **and** `ci_fix_attempts[head_sha] < 3`, **and** `head_sha` ∉ `ci_escalated_shas` → dispatch and exit:
   1. Reset `last_seen.idle_tick_count` to 0.
-  2. Dispatch `/muggle-do` with a *fix-ci* directive carrying the PR URL, slug, and the red check names (no review ids):
+  2. **Stop this watcher (single-thread):** cancel its cron exactly as in Step 4 — `/muggle-do`'s fix-ci respawns it when the cycle is done.
+  3. Dispatch `/muggle-do` with a *fix-ci* directive carrying the PR URL, slug, and the red check names (no review ids):
      ```
      /muggle-do fix ci <check-1> <check-2> ... on <pr-url> slug=<slug>
      ```
-  3. Append a dispatching line to `followup.log`; emit a `tick` event with `checks_red: <count>`, `dispatched_ci_fix: true`.
-  4. Exit. The next tick re-checks CI on the new head SHA — CI itself is the verify loop.
+  4. Append a dispatching line to `followup.log`; emit a `tick` event with `checks_red: <count>`, `dispatched_ci_fix: true`.
+  5. Exit. The dev cycle owns the PR; its respawn restarts the watcher, whose next tick re-checks CI on the new head SHA — CI itself is the verify loop.
 - **One or more red, but `ci_fix_attempts[head_sha] >= 3` or `head_sha` ∈ `ci_escalated_shas`** → idle. The fix budget is spent; `/muggle-do`'s fix-ci stage already recorded the escalation. The watcher does not re-dispatch.
 
-### Step 6 — Idle
+### Step 7 — Idle
 
-Any idle branch (Steps 4–5 that did not dispatch): increment `last_seen.idle_tick_count`, append an idle line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md), emit a `tick` event with `idle: true`, `reviews_seen: 0`, `dispatched_review_ids: []`, `checks_red: <count or 0>`, `dispatched_ci_fix: false`. Exit. The next tick fires in 1 min via `/loop`.
+Any idle branch (Steps 4–6 that did not dispatch): increment `last_seen.idle_tick_count`, append an idle line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md), emit a `tick` event with `idle: true`, `reviews_seen: 0`, `dispatched_review_ids: []`, `conflicting: <bool>`, `dispatched_resolve_conflicts: false`, `checks_red: <count or 0>`, `dispatched_ci_fix: false`. Exit. The next tick fires in 1 min via `/loop`.
 
 ## Output
 

package/dist/plugin/skills/muggle-pr-followup/state-schemas.md

@@ -41,7 +41,9 @@ Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
     "escalated_review_ids": [<int>, ...],
     "pushed_shas": ["<sha>", ...],
     "ci_fix_attempts": { "<sha>": <int> },
-    "ci_escalated_shas": ["<sha>", ...]
+    "ci_escalated_shas": ["<sha>", ...],
+    "conflict_resolve_attempts": { "<sha>": <int> },
+    "conflict_escalated_shas": ["<sha>", ...]
   }
 }
 ```
@@ -54,6 +56,8 @@ Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
 - `pushed_shas`: every SHA `/muggle-do` has pushed for this PR. Append-only. Used by the resolve-reminder stage to recognize threads addressed by the loop.
 - `ci_fix_attempts`: per-SHA count of fix-ci cycles `/muggle-do` has run. The watcher stops dispatching fix-ci for a SHA once its count reaches 3. Keyed by head SHA.
 - `ci_escalated_shas`: head SHAs whose CI the fix-ci stage gave up on (attempts exhausted or only out-of-scope checks). The watcher excludes these from CI dispatch so a hopeless SHA is never re-fixed.
+- `conflict_resolve_attempts`: per-SHA count of resolve-conflicts cycles `/muggle-do` has run. The watcher stops dispatching resolve-conflicts for a SHA once its count reaches 2. Keyed by head SHA.
+- `conflict_escalated_shas`: head SHAs whose merge conflict resolve-conflicts gave up on (attempts exhausted, or `autoResolveConflicts=never`). The watcher excludes these from conflict dispatch so an unresolvable SHA is never re-attempted.
 
 ## `state.md`
 

package/dist/plugin/skills/muggle-preferences/preference-gates/autoRouteBuildToMuggleDo.md

@@ -0,0 +1,13 @@
+# `autoRouteBuildToMuggleDo`
+
+When the user asks to build, implement, or fix something, controls whether the front-door guardrail routes the work through `/muggle-do` — the orchestrator that runs requirements → build (delegated to superpowers' design→plan→review) → impact → unit tests → E2E → PR → watcher — or lets the request proceed however the model would otherwise handle it. Fires once per session, on the first build-intent prompt (UserPromptSubmit guardrail).
+
+**Picker 1** — header `Route to muggle-do?`, question `"This looks like a build request — run it through /muggle-do (E2E + PR + watcher, build delegated to superpowers)?"`
+- `Route it` — `Enter the /muggle-do pipeline.` → `always`
+- `Ask me next time` — `Decide per request.` → `ask`
+- `No — proceed normally` — `Handle it without /muggle-do.` → `never`
+
+**Silent action**
+- `always` → `Routing build requests through /muggle-do`
+- `ask` → `Asking about routing to muggle-do`
+- `never` → `Not routing to muggle-do`

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

@@ -113,13 +113,15 @@ If no changes detected (clean tree), tell the user and ask what they want to tes
 
 ## Step 3: Authenticate
 
-1. Call `muggle-remote-auth-status`
-2. If **authenticated and not expired** → gate `autoLogin` (per `preference-gates/README.md`):
-   - `always` → reuse saved session.
+1. Call `muggle-remote-auth-status`. Three states: **valid** (`authenticated: true`), **expired** (`authenticated: false` + `isExpired: true`, `email` still present), **absent** (`authenticated: false`, no `email`).
+2. **Valid OR expired** (any stored identity) → gate `autoLogin` (per `preference-gates/README.md`). An expired token is NOT a reason to silently re-login the same account — surface the switch choice:
+   - `always` → reuse if valid; if expired, re-login the **same** account (`muggle-remote-auth-login`, then `muggle-remote-auth-poll`).
    - `never` → `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
    - `ask` → run Picker 1 from `preference-gates/autoLogin.md` via `AskUserQuestion`; map the answer back to one of the actions above.
-3. If **not authenticated or expired** → call `muggle-remote-auth-login`
-4. If login pending → call `muggle-remote-auth-poll`
+3. **Absent** (no stored identity) → `muggle-remote-auth-login` directly, then `muggle-remote-auth-poll`.
+4. If login pending → call `muggle-remote-auth-poll`.
+
+**Account-switch caveat (`never` / "Switch account").** The device flow has no `prompt=select_account`; switching relies on `forceNewSession` first clearing the Auth0 session via `/v2/logout?returnTo=<device-activation URL>`. That redirect only works if the activation URL is in the app's Auth0 *Allowed Logout URLs* — otherwise the browser shows an Auth0 error page and the session is silently reused. If that happens, tell the user to complete login in a **fresh incognito window** (no live SSO session) so Auth0 presents an account login.
 
 If auth fails repeatedly, suggest: `muggle logout && muggle login` from terminal.
 

package/dist/plugin/skills/muggle-test-feature-local/SKILL.md

@@ -147,14 +147,16 @@ Run the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md
 
 Caller glue: `mode` is the path chosen in §5; `localUrl` from §4; `cwd` = the repo root, or the prepared worktree when one is in use.
 
-### 7. Execute (no approval prompt; `showUi` gated by `showElectronBrowser`)
+### 7. Execute (`showUi` gated by `showElectronBrowser`)
 
-Call `muggle-local-execute-test-generation` or `muggle-local-execute-replay` directly. **Do not** ask the user to re-approve the Electron launch — the user choosing this skill in the first place is the approval.
+Resolve the `showElectronBrowser` gate **first**, then call `muggle-local-execute-test-generation` or `muggle-local-execute-replay`. **Do not** ask the user to re-approve the Electron launch itself — choosing this skill is the approval. That run-approval suppression does **not** extend to the gate below: when `showElectronBrowser=ask` you must still fire its picker.
 
-Gate `showElectronBrowser` (per `preference-gates/README.md`). Reuse choice within a session.
-- `always` → omit `showUi`.
+Gate `showElectronBrowser` (per `preference-gates/README.md`). Reuse the choice within a session.
+- `always` → omit `showUi` (the browser shows by default).
 - `never` → pass `showUi: false`.
-- `ask` → run Picker 1 from `preference-gates/showElectronBrowser.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+- `ask` → you **must** call `AskUserQuestion` (Picker 1 from `preference-gates/showElectronBrowser.md`) **before** the execute call, then map the answer to the `always`/`never` action above. Do not decide for the user.
+
+`showUi` is only ever omitted or `false` — never pass `showUi: true`.
 
 ### 8. Upload run to cloud (every completed run; open `viewUrl` gated by `openTestResultsAfterRun`)
 

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.15.1",
-  "buildId": "run-47-1",
-  "commitSha": "4bac13c8822d5c6b6989a3d800dc983f63556ab1",
-  "buildTime": "2026-06-02T22:17:47Z",
+  "release": "5.0.1",
+  "buildId": "run-49-1",
+  "commitSha": "a12a3252381af4fb34b79598208ba62f9764154d",
+  "buildTime": "2026-06-04T17:35:40Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/{src-ECRJW2LY.js → src-2O5UH4FA.js}

@@ -1 +1 @@
-export { DEFAULT_PREFERENCES, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PREFERENCE_ALLOWED_VALUES, PreferenceKey, PreferenceValue, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, formatPreferencesOneLiner, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, isFirstRun, loadApiKeyData, loadCredentials, local_exports as localQa, mcp_exports as mcp, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, readGlobalPreferences, readProjectPreferences, resetConfig, resetLogger, resetPreference, resolveElectronAppPathOrNull, resolvePreferences, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences } from './chunk-YKR2TQ24.js';
+export { DEFAULT_PREFERENCES, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PREFERENCE_ALLOWED_VALUES, PreferenceKey, PreferenceValue, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, formatPreferencesOneLiner, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, isFirstRun, loadApiKeyData, loadCredentials, local_exports as localQa, mcp_exports as mcp, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, readGlobalPreferences, readProjectPreferences, resetConfig, resetLogger, resetPreference, resolveElectronAppPathOrNull, resolvePreferences, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences } from './chunk-KDRSEHK5.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "4.15.1",
+  "version": "5.0.1",
   "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
   "type": "module",
   "main": "dist/index.js",
@@ -41,14 +41,14 @@
     "test:watch": "vitest"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.0.109",
+    "electronAppVersion": "1.0.116",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "9c2fa21b4e090c8b6f1acedf1bdbd824f0032a5d91d6f9abd3ca25cebee7f417",
-      "darwin-x64": "3369988c627be5d362d5d9c8312f9902063a98a53d308695b40873211960501c",
-      "linux-x64": "a986757132b45a4299a44c3dd1f3945ba6814d299e677380e2061f18da44b511",
-      "win32-x64": "29ab5400d7dca049e4a3e75b76bc3e06398b88743f0a49d38fa6ae531fc980fe"
+      "darwin-arm64": "382466a6eefe49cddc5662556cb6b744c60c2eed9984e520df9f62726bc468a0",
+      "darwin-x64": "9c57b10b1ed03bcd6629cb36abd5c0e0b5d095a27a38305ad4272c77cd6334af",
+      "linux-x64": "d6b10a829f99027747349ab37521b765041343676f59e59792afcec1de024080",
+      "win32-x64": "77981c9d77dd49a786cfca7156ce326f56a75716cf911adad270521230435f75"
     }
   },
   "dependencies": {

package/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.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/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.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/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/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/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/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/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/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/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/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/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/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/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/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/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: