@muggleai/works 5.1.0 → 5.3.0

package/dist/{chunk-2BHC6TQR.js → chunk-IGXNFT4M.js}

@@ -1,4 +1,4 @@
-import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, isFirstRun, writePreferences, DEFAULT_PREFERENCES, getDataDir, PREFERENCES_FILE_NAME, isElectronAppInstalled, getElectronAppChecksums, getChecksumForPlatform, verifyFileChecksum, calculateFileChecksum, initTelemetry, Surface, ServiceName, track, EventName, getQaTools, getLocalQaTools, performLogout, performLogin, toolRequiresAuth, getCallerCredentials, hasShownDisclosure, getDisclosureCopy, markDisclosureShown, getBundledElectronAppVersion, getElectronAppVersionSource, getCredentialsFilePath, buildElectronAppChecksumsUrl, __require } from './chunk-MOHR7QUN.js';
+import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, isFirstRun, writePreferences, DEFAULT_PREFERENCES, getDataDir, PREFERENCES_FILE_NAME, isElectronAppInstalled, getElectronAppChecksums, getChecksumForPlatform, verifyFileChecksum, calculateFileChecksum, initTelemetry, Surface, ServiceName, track, EventName, getQaTools, getLocalQaTools, performLogout, performLogin, toolRequiresAuth, getCallerCredentials, hasShownDisclosure, getDisclosureCopy, markDisclosureShown, getBundledElectronAppVersion, getElectronAppVersionSource, getCredentialsFilePath, buildElectronAppChecksumsUrl, __require } from './chunk-MPLQNDZX.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { v4 } from 'uuid';
@@ -736,7 +736,7 @@ async function resolveGsScreenshotUrls(report, opts) {
     if (gsUrls.length === 0) {
       return report;
     }
-    const mcps = await import('./src-SS2AL3O7.js');
+    const mcps = await import('./src-MQFKDZW5.js');
     const credentials = await mcps.getCallerCredentialsAsync();
     if (!credentials.bearerToken && !credentials.apiKey) {
       stderrWrite(
@@ -784,6 +784,9 @@ async function resolveGsScreenshotUrls(report, opts) {
 
 // src/cli/build-pr-section.ts
 var DEFAULT_MAX_BODY_BYTES = 6e4;
+var REPORT_SECTION_SENTINEL = "<!-- muggle-pr-section:v1 -->";
+var withSentinel = (s) => s ? `${REPORT_SECTION_SENTINEL}
+${s}` : s;
 async function readAll(stream) {
   const chunks = [];
   for await (const chunk of stream) {
@@ -828,8 +831,12 @@ ${err.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n")}
     return 1;
   }
   const resolvedReport = await resolveGsScreenshotUrls(report, { stderrWrite: opts.stderrWrite });
-  const result = buildPrSection(resolvedReport, { maxBodyBytes: opts.maxBodyBytes });
-  opts.stdoutWrite(JSON.stringify({ body: result.body, comment: result.comment }));
+  const sentinelCost = Buffer.byteLength(`${REPORT_SECTION_SENTINEL}
+`, "utf-8");
+  const result = buildPrSection(resolvedReport, { maxBodyBytes: opts.maxBodyBytes - sentinelCost });
+  opts.stdoutWrite(
+    JSON.stringify({ body: withSentinel(result.body), comment: withSentinel(result.comment) })
+  );
   return 0;
 }
 async function buildPrSectionCommand(options) {

package/dist/{chunk-MOHR7QUN.js → chunk-MPLQNDZX.js}

@@ -3938,7 +3938,8 @@ var TestCaseUpdateInputSchema = z.object({
 });
 var TestScriptListInputSchema = z.object({
   projectId: IdSchema.describe("Project ID (UUID) to list test scripts for"),
-  testCaseId: IdSchema.optional().describe("Optional test case ID (UUID) to filter scripts by")
+  testCaseId: IdSchema.optional().describe("Optional test case ID (UUID) to filter scripts by"),
+  runEnvironmentType: RunEnvironmentInputSchema
 }).merge(PaginationInputSchema);
 var TestScriptGetInputSchema = z.object({
   testScriptId: IdSchema.describe("Test script ID (UUID) to retrieve")
@@ -4912,7 +4913,7 @@ var bulkPreviewTools = [
 var testScriptTools = [
   {
     name: "muggle-remote-test-script-list",
-    description: "List test scripts for a project, optionally filtered by test case. Returns up to 10 items per page by default (max 100). Response includes pagination metadata (totalCount, totalPages, hasMore) \u2014 check `hasMore` to decide whether to fetch additional pages.",
+    description: "List test scripts for a project, optionally filtered by test case and by environment lane. Returns up to 10 items per page by default (max 100). Response includes pagination metadata (totalCount, totalPages, hasMore) \u2014 check `hasMore` to decide whether to fetch additional pages.",
     inputSchema: TestScriptListInputSchema,
     mapToUpstream: (input) => {
       const data = input;
@@ -4922,6 +4923,7 @@ var testScriptTools = [
         queryParams: {
           projectId: data.projectId,
           testCaseId: data.testCaseId,
+          runEnvironmentType: data.runEnvironmentType,
           page: data.page,
           pageSize: data.pageSize,
           sortBy: data.sortBy,
@@ -6236,6 +6238,11 @@ var PreferenceKey = /* @__PURE__ */ ((PreferenceKey2) => {
   PreferenceKey2["AutoRebase"] = "autoRebase";
   PreferenceKey2["AutoCleanup"] = "autoCleanup";
   PreferenceKey2["AutoE2ETest"] = "autoE2ETest";
+  PreferenceKey2["AutoResolveConflicts"] = "autoResolveConflicts";
+  PreferenceKey2["AutoReuseValidationContext"] = "autoReuseValidationContext";
+  PreferenceKey2["AutoRouteBuildToMuggleDo"] = "autoRouteBuildToMuggleDo";
+  PreferenceKey2["AutoWatchPR"] = "autoWatchPR";
+  PreferenceKey2["ReusePreparePlan"] = "reusePreparePlan";
   return PreferenceKey2;
 })(PreferenceKey || {});
 var PreferenceValue = /* @__PURE__ */ ((PreferenceValue2) => {
@@ -6252,23 +6259,28 @@ var PREFERENCES_FILE_NAME = "preferences.json";
 var PREFERENCES_PROJECT_DIR_NAME = ".muggle-ai";
 var PREFERENCES_VERSION = 1;
 var DEFAULT_PREFERENCES = {
-  ["autoLogin" /* AutoLogin */]: "ask" /* Ask */,
-  ["autoSelectProject" /* AutoSelectProject */]: "ask" /* Ask */,
-  ["autoSelectLocalHost" /* AutoSelectLocalHost */]: "ask" /* Ask */,
-  ["showElectronBrowser" /* ShowElectronBrowser */]: "ask" /* Ask */,
-  ["openTestResultsAfterRun" /* OpenTestResultsAfterRun */]: "ask" /* Ask */,
-  ["defaultExecutionMode" /* DefaultExecutionMode */]: "ask" /* Ask */,
-  ["suggestRelatedUseCases" /* SuggestRelatedUseCases */]: "ask" /* Ask */,
-  ["suggestRelatedTestCases" /* SuggestRelatedTestCases */]: "ask" /* Ask */,
-  ["autoDetectChanges" /* AutoDetectChanges */]: "ask" /* Ask */,
-  ["postPRVisualWalkthrough" /* PostPRVisualWalkthrough */]: "ask" /* Ask */,
-  ["autoCreatePR" /* AutoCreatePR */]: "ask" /* Ask */,
-  ["checkForUpdates" /* CheckForUpdates */]: "ask" /* Ask */,
-  ["verboseOutput" /* VerboseOutput */]: "ask" /* Ask */,
-  ["autoUseWorktree" /* AutoUseWorktree */]: "ask" /* Ask */,
-  ["autoRebase" /* AutoRebase */]: "ask" /* Ask */,
-  ["autoCleanup" /* AutoCleanup */]: "ask" /* Ask */,
-  ["autoE2ETest" /* AutoE2ETest */]: "always" /* Always */
+  ["autoLogin" /* AutoLogin */]: "always" /* Always */,
+  ["autoSelectProject" /* AutoSelectProject */]: "always" /* Always */,
+  ["autoSelectLocalHost" /* AutoSelectLocalHost */]: "always" /* Always */,
+  ["showElectronBrowser" /* ShowElectronBrowser */]: "always" /* Always */,
+  ["openTestResultsAfterRun" /* OpenTestResultsAfterRun */]: "always" /* Always */,
+  ["defaultExecutionMode" /* DefaultExecutionMode */]: "local" /* Local */,
+  ["suggestRelatedUseCases" /* SuggestRelatedUseCases */]: "always" /* Always */,
+  ["suggestRelatedTestCases" /* SuggestRelatedTestCases */]: "always" /* Always */,
+  ["autoDetectChanges" /* AutoDetectChanges */]: "always" /* Always */,
+  ["postPRVisualWalkthrough" /* PostPRVisualWalkthrough */]: "always" /* Always */,
+  ["autoCreatePR" /* AutoCreatePR */]: "always" /* Always */,
+  ["checkForUpdates" /* CheckForUpdates */]: "always" /* Always */,
+  ["verboseOutput" /* VerboseOutput */]: "never" /* Never */,
+  ["autoUseWorktree" /* AutoUseWorktree */]: "always" /* Always */,
+  ["autoRebase" /* AutoRebase */]: "always" /* Always */,
+  ["autoCleanup" /* AutoCleanup */]: "always" /* Always */,
+  ["autoE2ETest" /* AutoE2ETest */]: "always" /* Always */,
+  ["autoResolveConflicts" /* AutoResolveConflicts */]: "always" /* Always */,
+  ["autoReuseValidationContext" /* AutoReuseValidationContext */]: "always" /* Always */,
+  ["autoRouteBuildToMuggleDo" /* AutoRouteBuildToMuggleDo */]: "always" /* Always */,
+  ["autoWatchPR" /* AutoWatchPR */]: "always" /* Always */,
+  ["reusePreparePlan" /* ReusePreparePlan */]: "always" /* Always */
 };
 var ALWAYS_ASK_NEVER = [
   "always" /* Always */,
@@ -6301,7 +6313,12 @@ var PREFERENCE_ALLOWED_VALUES = {
   ["autoUseWorktree" /* AutoUseWorktree */]: ALWAYS_ASK_NEVER,
   ["autoRebase" /* AutoRebase */]: ALWAYS_ASK_NEVER,
   ["autoCleanup" /* AutoCleanup */]: ALWAYS_ASK_NEVER,
-  ["autoE2ETest" /* AutoE2ETest */]: ALWAYS_ASK
+  ["autoE2ETest" /* AutoE2ETest */]: ALWAYS_ASK,
+  ["autoResolveConflicts" /* AutoResolveConflicts */]: ALWAYS_ASK_NEVER,
+  ["autoReuseValidationContext" /* AutoReuseValidationContext */]: ALWAYS_ASK_NEVER,
+  ["autoRouteBuildToMuggleDo" /* AutoRouteBuildToMuggleDo */]: ALWAYS_ASK_NEVER,
+  ["autoWatchPR" /* AutoWatchPR */]: ALWAYS_ASK_NEVER,
+  ["reusePreparePlan" /* ReusePreparePlan */]: ALWAYS_ASK_NEVER
 };
 var PREFERENCES_SCHEMA = {
   ["autoLogin" /* AutoLogin */]: {
@@ -6354,6 +6371,21 @@ var PREFERENCES_SCHEMA = {
   },
   ["autoE2ETest" /* AutoE2ETest */]: {
     description: "Run Stage 6 (E2E acceptance) at the end of every /muggle-do cycle (default always \u2014 running E2E is the point of muggle-do; never is not an option)"
+  },
+  ["autoResolveConflicts" /* AutoResolveConflicts */]: {
+    description: "When a rebase onto the default branch hits conflicts, resolve them autonomously behind a verify-or-rollback gate instead of aborting and escalating"
+  },
+  ["autoReuseValidationContext" /* AutoReuseValidationContext */]: {
+    description: "When a prior session left an E2E validation context for this working tree, reuse it instead of re-asking the validation questions"
+  },
+  ["autoRouteBuildToMuggleDo" /* AutoRouteBuildToMuggleDo */]: {
+    description: "When a prompt looks like a build/implement/fix request, route it through the /muggle-do pipeline (requirements \u2192 build \u2192 impact \u2192 tests \u2192 E2E \u2192 PR \u2192 watcher)"
+  },
+  ["autoWatchPR" /* AutoWatchPR */]: {
+    description: "After a test run opens a PR, start a muggle-pr-followup watcher that polls for new reviews and hands them to /muggle-do"
+  },
+  ["reusePreparePlan" /* ReusePreparePlan */]: {
+    description: "Reuse the saved prepare plan for this stack (skip discovery, jump to check-running + smoke-test) instead of rediscovering from scratch"
   }
 };
 

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-2BHC6TQR.js';
-import './chunk-MOHR7QUN.js';
+import { runCli } from './chunk-IGXNFT4M.js';
+import './chunk-MPLQNDZX.js';
 
 // src/cli/main.ts
 runCli().catch((error) => {

package/dist/index.js

@@ -1,2 +1,2 @@
-export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-2BHC6TQR.js';
-export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-MOHR7QUN.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-IGXNFT4M.js';
+export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-MPLQNDZX.js';

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": "5.1.0",
+  "version": "5.3.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": "5.1.0",
+  "version": "5.3.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/hooks/README.md

@@ -9,18 +9,29 @@ Condition-triggered hooks that make Muggle Test's high-value handoffs fire path-
 - **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.
+A guardrail steers the model toward a Muggle Test flow; it never reimplements the flow.
 
-Design rationale: `muggle-ai-brain/architecture/2026-06-02-harness-pipeline-integration-design.md`.
+Design rationale: `muggle-ai-brain/architecture/2026-06-02-harness-pipeline-integration-design.md` (original advisory design; the E2E gate and report gate below now enforce rather than advise).
+
+## Advise vs enforce
+
+A guardrail emits one of two strengths:
+
+- **Advise** — `additionalContext` (PostToolUse/UserPromptSubmit) or a plain Stop message. A soft nudge the model can ignore.
+- **Enforce** — a `Stop` `decision: "block"` that refuses to end the turn, or a `PreToolUse` `permissionDecision: "deny"` that refuses a tool call. The model cannot proceed until the condition is met.
+
+Enforcement is reserved for the handoffs that were being skipped: the E2E acceptance run and posting a deterministically-rendered report. Each enforcing gate carries an escape so it can't trap a turn — the E2E gate releases to advisory after `MAX_E2E_BLOCKS` (3) blocks; the report gate only denies a body it can positively see is a hand-written report and fails open otherwise.
 
 ## 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.
+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` tracks what fired. Any *failure* degrades to `{}` (allow) — a gate blocks only by an explicit, tested decision, never by accident.
 
 ## 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) |
+| Hook event | Wrapper | Strength | Condition | Preference | Effect |
+| :--------- | :------ | :------- | :-------- | :--------- | :----- |
+| `PostToolUse` (Bash) | `guardrail-pr-opened.sh` | advise | a `gh pr create`/`gh pr ready` just succeeded | `autoWatchPR` | start a `muggle-pr-followup` watcher on the new PR |
+| `PostToolUse` (Bash + muggle execute/replay MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, or an E2E run happened | — | set `unitTestsGreen` / `e2eRun` session state |
+| `PreToolUse` (Bash) | `guardrail-report-format.sh` | **enforce** | a `gh pr comment\|create\|edit` body reads like an E2E report but lacks the `build-pr-section` sentinel | — | **deny** — render via `muggle build-pr-section` instead |
+| `Stop` | `guardrail-e2e-gate.sh` | **enforce** | unit tests passed this session and no E2E ran yet | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` (releases after 3 blocks) |
+| `UserPromptSubmit` | `guardrail-build-router.sh` | advise | 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

@@ -12,6 +12,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-report-format.sh\"",
+            "async": false
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Bash",
@@ -27,6 +39,16 @@
             "async": false
           }
         ]
+      },
+      {
+        "matcher": "mcp__.*muggle.*(execute|replay)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-tests.sh\"",
+            "async": false
+          }
+        ]
       }
     ],
     "Stop": [

package/dist/plugin/scripts/guardrail-report-format.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Report-format gate (PreToolUse, Bash). Denies a `gh pr comment|create|edit`
+# whose body reads like a hand-written E2E report — one that lacks the
+# build-pr-section sentinel — so every posted walkthrough goes through the
+# deterministic renderer. Degrades to {} so it never blocks an unrelated command.
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+node "${root}/scripts/guardrails.mjs" report-gate 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrails.mjs

@@ -1,5 +1,5 @@
 import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { isAbsolute, resolve, join } from 'path';
 import { homedir } from 'os';
 
 // src/guardrails/cli.ts
@@ -60,9 +60,26 @@ function isE2ERun(input2) {
 }
 
 // src/guardrails/shouldRunE2E.ts
+var MAX_E2E_BLOCKS = 3;
 function shouldRunE2E(state) {
   return state.unitTestsGreen === true && state.e2eRun !== true;
 }
+function applyRecordedRun(state, run) {
+  let next = state;
+  if (run.unitTestPassed) {
+    next = { ...next, unitTestsGreen: true, e2eRun: false, e2eBlockCount: 0 };
+  }
+  if (run.e2eRan) {
+    next = { ...next, e2eRun: true };
+  }
+  return next;
+}
+function e2eGateDecision(state, maxBlocks = MAX_E2E_BLOCKS) {
+  const blockCount = state.e2eBlockCount ?? 0;
+  if (!shouldRunE2E(state)) return { action: "none" /* None */, blockCount };
+  if (blockCount >= maxBlocks) return { action: "release" /* Release */, blockCount };
+  return { action: "block" /* Block */, blockCount: blockCount + 1 };
+}
 
 // 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;
@@ -74,6 +91,60 @@ function detectBuildIntent(prompt) {
   if (QUESTION.test(p)) return false;
   return BUILD.test(p) || DEVCYCLE.test(p);
 }
+var REPORT_SENTINEL = "muggle-pr-section";
+var PR_POST_CMD = /\bgh\s+pr\s+(comment|create|edit)\b/;
+var defaultReader = (path, cwd) => {
+  try {
+    const abs = isAbsolute(path) ? path : resolve(cwd ?? process.cwd(), path);
+    if (!existsSync(abs)) return null;
+    return readFileSync(abs, "utf-8");
+  } catch {
+    return null;
+  }
+};
+function unquote(s) {
+  const t = s.trim();
+  if (t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'")) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+function looksLikeE2EReport(text) {
+  const t = text.toLowerCase();
+  const statusEmojis = (text.match(/[✅❌⚠]/gu) ?? []).length;
+  const tally = /\b\d+\s+(tests?\s+)?passed\b/.test(t) && /\b\d+\s+(tests?\s+)?(failed|inconclusive)\b/.test(t);
+  const slashTally = /\bpassed\b\s*[/|]\s*\d*\s*(tests?\s*)?\bfailed\b/.test(t) || /\bfailed\b\s*[/|]\s*\d*\s*(tests?\s*)?\bpassed\b/.test(t);
+  const resultsStructure = /acceptance results/.test(t) || tally || slashTally || statusEmojis >= 2;
+  const muggleContext = /\bmuggle\b/.test(t) || /muggle-ai\.com/.test(t) || /\be2e\b/.test(t) || /\bacceptance\b/.test(t);
+  return resultsStructure && muggleContext;
+}
+function collectInspectableText(cmd, cwd, read) {
+  let text = cmd;
+  for (const m of cmd.matchAll(/--body-file[=\s]+("[^"]+"|'[^']+'|\S+)/g)) {
+    const p = unquote(m[1]);
+    if (p && p !== "-") {
+      const c = read(p, cwd);
+      if (c) text += "\n" + c;
+    }
+  }
+  for (const m of cmd.matchAll(/jq\b[^|]*?("[^"]+\.json"|'[^']+\.json'|\S+\.json)/g)) {
+    const c = read(unquote(m[1]), cwd);
+    if (c) text += "\n" + c;
+  }
+  return text;
+}
+function evaluateReportPost(input2, read = defaultReader) {
+  if (input2.tool_name !== "Bash") return { deny: false };
+  const cmd = input2.tool_input?.command ?? "";
+  if (!PR_POST_CMD.test(cmd)) return { deny: false };
+  const text = collectInspectableText(cmd, input2.cwd, read);
+  if (text.includes(REPORT_SENTINEL)) return { deny: false };
+  if (!looksLikeE2EReport(text)) return { deny: false };
+  return {
+    deny: true,
+    reason: "Blocked: this looks like a hand-written E2E test report. Muggle requires the deterministic renderer \u2014 build the run's E2eReport JSON and pipe it through `muggle build-pr-section` (or invoke /muggle:muggle-pr-visual-walkthrough), then post that output. Never hand-write the walkthrough markdown."
+  };
+}
 
 // src/guardrails/emit.ts
 function envelope(eventName, context, host2) {
@@ -83,6 +154,22 @@ function envelope(eventName, context, host2) {
     hookSpecificOutput: { hookEventName: eventName, additionalContext: context }
   });
 }
+function blockStop(reason, host2) {
+  if (!reason) return "{}";
+  if (host2 === "cursor") return JSON.stringify({ additional_context: reason });
+  return JSON.stringify({ decision: "block", reason });
+}
+function denyTool(reason, host2) {
+  if (!reason) return "{}";
+  if (host2 === "cursor") return JSON.stringify({ additional_context: reason });
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason
+    }
+  });
+}
 
 // src/guardrails/cli.ts
 function readStdin() {
@@ -108,25 +195,26 @@ Per the autoWatchPR preference, a muggle-pr-followup watcher should handle its i
 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);
+  const next = applyRecordedRun(state, {
+    unitTestPassed: isTestCommand(cmd) && testsPassed(input),
+    e2eRan: isE2ERun(input)
+  });
+  if (next !== state) writeState(next);
   return "{}";
 }
 function e2eGate() {
   const state = readState(sessionId);
-  if (!shouldRunE2E(state)) return "{}";
-  state.e2eRun = true;
+  const decision = e2eGateDecision(state);
+  if (decision.action === "none" /* None */ || decision.action === "release" /* Release */) return "{}";
+  state.e2eBlockCount = decision.blockCount;
   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);
+  const reason = `Do not end the turn yet. Unit tests passed this session but no E2E acceptance run has happened. Per the autoE2ETest preference (default: always), run change-driven E2E now via /muggle:muggle-test, then finish. If E2E genuinely cannot run here (no app, services down, no PR), say so explicitly to the user \u2014 this gate releases after ${MAX_E2E_BLOCKS} attempts.`;
+  return blockStop(reason, host);
+}
+function reportGate() {
+  const result = evaluateReportPost(input);
+  if (!result.deny || !result.reason) return "{}";
+  return denyTool(result.reason, host);
 }
 function buildRouter() {
   if (!detectBuildIntent(input.prompt ?? "")) return "{}";
@@ -141,6 +229,7 @@ var handlers = {
   "pr-opened": prOpened,
   "record-tests": recordTests,
   "e2e-gate": e2eGate,
+  "report-gate": reportGate,
   "build-router": buildRouter
 };
 process.stdout.write((handlers[sub] ?? (() => "{}"))());

package/dist/plugin/skills/_shared/dev-loop/run.md

@@ -23,7 +23,7 @@ One local browser exists, so **execution is sequential** — one test case at a
 Per test case, branch on `mode`:
 
 **Replay**
-1. `muggle-remote-test-script-get` (latest replayable script) → note `actionScriptId`.
+1. `muggle-remote-test-script-get` (latest replayable script — the lane-scoped one the caller resolved during classification per [`../failure-mode-handling.md`](../failure-mode-handling.md) §A) → note `actionScriptId`.
 2. `muggle-remote-action-script-get` with that id → full `actionScript` (see [`action-script.md`](action-script.md)).
 3. `muggle-local-execute-replay` with `testScript`, `actionScript`, `localUrl`, `cwd`, `showUi`, `freshSession` (see [`fresh-session.md`](fresh-session.md)), `timeoutMs` (see [`timeouts.md`](timeouts.md)).
 

package/dist/plugin/skills/_shared/failure-mode-handling.md

@@ -61,7 +61,7 @@ Run during change analysis, **per impacted test case**. Picks the initial execut
 
 - The change summary from `git diff` (file paths + diff content).
 - The test case (title, description, instructions, last passing run timestamp).
-- Existing test scripts for that test case from `muggle-remote-test-script-list`.
+- Existing test scripts for that test case from `muggle-remote-test-script-list`, scoped to the run's lane: pass `runEnvironmentType: "local"` in Local mode (Step 7A), `"remote"` in Remote mode (Step 7B). The lane is fixed at runtime — it selects the versioned runSettings the cloud resolves — so a local run keys replay-vs-regen off the localhost-lane script and a remote run off the deployed-lane script, never the other lane's.
 
 ### Rules (fire in order; first match wins)
 

package/dist/plugin/skills/do/e2e-acceptance.md

@@ -98,7 +98,7 @@ Based on the changed files and the requirements goal, determine which test cases
 
 ### Step 4: Run the dev loop, gather screenshots
 
-For each relevant test case, run the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): `muggle-remote-test-script-list` by `testCaseId` to pick [replay vs regen](../_shared/dev-loop/run.md), [execute with `timeoutMs`](../_shared/dev-loop/timeouts.md), [fetch the result](../_shared/dev-loop/failures.md) and [interpret failures](../_shared/dev-loop/failures.md), then read the studio-published [cloud refs and per-step screenshots](../_shared/dev-loop/publish.md) off the run result.
+For each relevant test case, run the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): `muggle-remote-test-script-list` by `testCaseId` with `runEnvironmentType: "local"` (this stage runs against localhost) to pick [replay vs regen](../_shared/dev-loop/run.md), [execute with `timeoutMs`](../_shared/dev-loop/timeouts.md), [fetch the result](../_shared/dev-loop/failures.md) and [interpret failures](../_shared/dev-loop/failures.md), then read the studio-published [cloud refs and per-step screenshots](../_shared/dev-loop/publish.md) off the run result.
 
 Inputs to the loop: `mode` from the script-exists check, `localUrl`/project from Step 1.7, `cwd` = the working tree recorded in `state.md`.
 

package/dist/plugin/skills/muggle-browser-task/SKILL.md

@@ -74,6 +74,7 @@ Tell the user: `Created test case: <id>`.
 Load and call `muggle-remote-test-script-list` with:
 - `projectId`: from Step 2
 - `testCaseId`: from Step 4
+- `runEnvironmentType`: `"local"` — this skill executes in the local browser, so it resolves the local-lane script. The lane is an explicit env type, exactly as the remote flow passes `"remote"`; the target URL is just the lane's url and never decides the lane.
 
 Tell the user which mutations will be applied: `Mutations: <mutations[]>` (or "no mutations" if empty).
 

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

@@ -16,16 +16,19 @@ which uses `local` / `remote` / `ask`).
 
 ## Gate behavior
 
-- `always` → take the pro-action, then print silent footer.
-- `never` → take the skip-action, then print silent footer.
+- `always` → take the pro-action, then **always** print the silent footer.
+- `never` → take the skip-action, then **always** print the silent footer.
 - `ask` (or absent) → run Picker 1 (per-key file) → Picker 2 (below).
 
 `defaultExecutionMode` uses `local`/`remote` instead of `always`/`never`.
 
-## Silent footer (whenever pickers are skipped)
+## Silent footer (mandatory whenever a prompt is skipped)
 
-The user must always be told **what happened**, **why it was silent**, and
-**how to change it**. Two lines:
+Whenever a gate resolves to a non-`ask` value and skips its picker, the footer
+below is **required** — every gate, every time, no exceptions. It tells the
+user **what happened**, **why it was silent**, and **how to change it**. The
+`preference-gates-lint` test enforces that this contract exists; omitting the
+footer when a gate fires is a bug. Two lines:
 
 ```
 ✓ <silent action from per-key file>

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

@@ -219,7 +219,7 @@ Wait for user confirmation before moving to execution.
 
 ### 6f: Classify execution mode per test case (replay vs regen)
 
-For each selected test case, decide whether the run should be a **replay** of an existing script or a fresh **regen**, using the rules in [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) section A. Inputs: the change summary from Step 2, the test case body, and the result of `muggle-remote-test-script-list` for that test case (last passing timestamp + whether any replayable script exists).
+For each selected test case, decide whether the run should be a **replay** of an existing script or a fresh **regen**, using the rules in [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) section A. Inputs: the change summary from Step 2, the test case body, and the result of `muggle-remote-test-script-list` for that test case (last passing timestamp + whether any replayable script exists). Scope that list call to the run's lane — `runEnvironmentType: "local"` in Local mode, `"remote"` in Remote mode (section A) — so replay reuses the script for the lane the run will execute against.
 
 Per test case, fire one `muggle-local-telemetry-event-emit` with `eventType: "pre-execution-classification"` capturing the picked mode, the rule that fired, and the matched changed-file paths.
 

package/dist/plugin/skills/muggle-test/execute-remote.md

@@ -28,7 +28,7 @@ Branch each test case on its `mode`, then issue **all** workflow-start calls in
 - `instructions`: From the test case
 - `expectedResult`: From the test case
 
-**Replay-mode test case** — `muggle-remote-workflow-start-test-script-replay` against the latest replayable script for that test case (resolve via `muggle-remote-test-script-list` if not already in hand from the classification step). Tag results with `mode: "replay"` so the router routes failures correctly.
+**Replay-mode test case** — `muggle-remote-workflow-start-test-script-replay` against the latest replayable script for that test case (resolve via `muggle-remote-test-script-list` with `runEnvironmentType: "remote"` if not already in hand from the classification step). Tag results with `mode: "replay"` so the router routes failures correctly.
 
 Store each returned workflow runtime ID along with its mode tag.
 

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

@@ -136,7 +136,7 @@ Before deciding the target's script, resolve its prerequisite chain from the bac
 
 ### 5. Existing scripts vs new generation
 
-`muggle-remote-test-script-list` with `testCaseId`.
+`muggle-remote-test-script-list` with `testCaseId` and `runEnvironmentType: "local"` — this skill always replays against localhost, so resolve the local-lane script (the remote-lane script carries the deployed URL).
 
 - **If any replayable/succeeded scripts exist:** use `AskUserQuestion` to present them as clickable options. Show: name, created/updated, step count per option. Include **"Generate new script"** as the last option.
 - **If none:** go straight to generation (no need to ask replay vs generate).

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "5.1.0",
-  "buildId": "run-53-1",
-  "commitSha": "3a0e7525c2c606afb9a64c2d78baffa5b400cf50",
-  "buildTime": "2026-06-11T20:57:59Z",
+  "release": "5.3.0",
+  "buildId": "run-55-1",
+  "commitSha": "b48301cf3c16a8ff043854510aa3584808f9a7c6",
+  "buildTime": "2026-06-17T02:44:35Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/{src-SS2AL3O7.js → src-MQFKDZW5.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-MOHR7QUN.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-MPLQNDZX.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "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",
@@ -38,17 +38,18 @@
     "lint:check": "eslint .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:gates:behavioral": "tsx internal/skill-gate-eval/src/run.ts"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.4.0",
+    "electronAppVersion": "1.5.1",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "9dd7ac0a378a1d5db908a102aec4f596741e943572a7d55b08e2a62f336981bc",
-      "darwin-x64": "70c9c6df21e03ad1529682e6cf8150ddfef306e1019e4b3bd2a4e7d025a98d64",
-      "linux-x64": "14ee27b3c22988bf72f13f3734e1594dcbb0fb94f699d5ad789ea8cf452dc7a1",
-      "win32-x64": "9e059917ba4605527b47d23b43bd78438cf59e7df38c4c9698f6b9487ed64a97"
+      "darwin-arm64": "70649bed80b3ae407893728abd426e32c54eeda03fde7856e530bb6f67e359cd",
+      "darwin-x64": "26a2176c0c926a6f20a4af99e4bc7362e8365ad260c3ca42d18bb1f6cf1b29d5",
+      "linux-x64": "69f33e49c6baa017604ffd49a4f4db2eba90260375c4fb5918326843c51d7bdd",
+      "win32-x64": "559d02c0e80860dec3ed5c82e8e1d3d4aa2c4dea4f73a2c62c149ad4bd6131d0"
     }
   },
   "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": "5.1.0",
+  "version": "5.3.0",
   "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": "5.1.0",
+  "version": "5.3.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/hooks/README.md

@@ -9,18 +9,29 @@ Condition-triggered hooks that make Muggle Test's high-value handoffs fire path-
 - **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.
+A guardrail steers the model toward a Muggle Test flow; it never reimplements the flow.
 
-Design rationale: `muggle-ai-brain/architecture/2026-06-02-harness-pipeline-integration-design.md`.
+Design rationale: `muggle-ai-brain/architecture/2026-06-02-harness-pipeline-integration-design.md` (original advisory design; the E2E gate and report gate below now enforce rather than advise).
+
+## Advise vs enforce
+
+A guardrail emits one of two strengths:
+
+- **Advise** — `additionalContext` (PostToolUse/UserPromptSubmit) or a plain Stop message. A soft nudge the model can ignore.
+- **Enforce** — a `Stop` `decision: "block"` that refuses to end the turn, or a `PreToolUse` `permissionDecision: "deny"` that refuses a tool call. The model cannot proceed until the condition is met.
+
+Enforcement is reserved for the handoffs that were being skipped: the E2E acceptance run and posting a deterministically-rendered report. Each enforcing gate carries an escape so it can't trap a turn — the E2E gate releases to advisory after `MAX_E2E_BLOCKS` (3) blocks; the report gate only denies a body it can positively see is a hand-written report and fails open otherwise.
 
 ## 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.
+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` tracks what fired. Any *failure* degrades to `{}` (allow) — a gate blocks only by an explicit, tested decision, never by accident.
 
 ## 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) |
+| Hook event | Wrapper | Strength | Condition | Preference | Effect |
+| :--------- | :------ | :------- | :-------- | :--------- | :----- |
+| `PostToolUse` (Bash) | `guardrail-pr-opened.sh` | advise | a `gh pr create`/`gh pr ready` just succeeded | `autoWatchPR` | start a `muggle-pr-followup` watcher on the new PR |
+| `PostToolUse` (Bash + muggle execute/replay MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, or an E2E run happened | — | set `unitTestsGreen` / `e2eRun` session state |
+| `PreToolUse` (Bash) | `guardrail-report-format.sh` | **enforce** | a `gh pr comment\|create\|edit` body reads like an E2E report but lacks the `build-pr-section` sentinel | — | **deny** — render via `muggle build-pr-section` instead |
+| `Stop` | `guardrail-e2e-gate.sh` | **enforce** | unit tests passed this session and no E2E ran yet | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` (releases after 3 blocks) |
+| `UserPromptSubmit` | `guardrail-build-router.sh` | advise | 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

@@ -12,6 +12,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-report-format.sh\"",
+            "async": false
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Bash",
@@ -27,6 +39,16 @@
             "async": false
           }
         ]
+      },
+      {
+        "matcher": "mcp__.*muggle.*(execute|replay)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-tests.sh\"",
+            "async": false
+          }
+        ]
       }
     ],
     "Stop": [

package/plugin/scripts/guardrail-report-format.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Report-format gate (PreToolUse, Bash). Denies a `gh pr comment|create|edit`
+# whose body reads like a hand-written E2E report — one that lacks the
+# build-pr-section sentinel — so every posted walkthrough goes through the
+# deterministic renderer. Degrades to {} so it never blocks an unrelated command.
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+node "${root}/scripts/guardrails.mjs" report-gate 2>/dev/null || printf '{}'

package/plugin/scripts/guardrails.mjs

@@ -1,5 +1,5 @@
 import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { isAbsolute, resolve, join } from 'path';
 import { homedir } from 'os';
 
 // src/guardrails/cli.ts
@@ -60,9 +60,26 @@ function isE2ERun(input2) {
 }
 
 // src/guardrails/shouldRunE2E.ts
+var MAX_E2E_BLOCKS = 3;
 function shouldRunE2E(state) {
   return state.unitTestsGreen === true && state.e2eRun !== true;
 }
+function applyRecordedRun(state, run) {
+  let next = state;
+  if (run.unitTestPassed) {
+    next = { ...next, unitTestsGreen: true, e2eRun: false, e2eBlockCount: 0 };
+  }
+  if (run.e2eRan) {
+    next = { ...next, e2eRun: true };
+  }
+  return next;
+}
+function e2eGateDecision(state, maxBlocks = MAX_E2E_BLOCKS) {
+  const blockCount = state.e2eBlockCount ?? 0;
+  if (!shouldRunE2E(state)) return { action: "none" /* None */, blockCount };
+  if (blockCount >= maxBlocks) return { action: "release" /* Release */, blockCount };
+  return { action: "block" /* Block */, blockCount: blockCount + 1 };
+}
 
 // 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;
@@ -74,6 +91,60 @@ function detectBuildIntent(prompt) {
   if (QUESTION.test(p)) return false;
   return BUILD.test(p) || DEVCYCLE.test(p);
 }
+var REPORT_SENTINEL = "muggle-pr-section";
+var PR_POST_CMD = /\bgh\s+pr\s+(comment|create|edit)\b/;
+var defaultReader = (path, cwd) => {
+  try {
+    const abs = isAbsolute(path) ? path : resolve(cwd ?? process.cwd(), path);
+    if (!existsSync(abs)) return null;
+    return readFileSync(abs, "utf-8");
+  } catch {
+    return null;
+  }
+};
+function unquote(s) {
+  const t = s.trim();
+  if (t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'")) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+function looksLikeE2EReport(text) {
+  const t = text.toLowerCase();
+  const statusEmojis = (text.match(/[✅❌⚠]/gu) ?? []).length;
+  const tally = /\b\d+\s+(tests?\s+)?passed\b/.test(t) && /\b\d+\s+(tests?\s+)?(failed|inconclusive)\b/.test(t);
+  const slashTally = /\bpassed\b\s*[/|]\s*\d*\s*(tests?\s*)?\bfailed\b/.test(t) || /\bfailed\b\s*[/|]\s*\d*\s*(tests?\s*)?\bpassed\b/.test(t);
+  const resultsStructure = /acceptance results/.test(t) || tally || slashTally || statusEmojis >= 2;
+  const muggleContext = /\bmuggle\b/.test(t) || /muggle-ai\.com/.test(t) || /\be2e\b/.test(t) || /\bacceptance\b/.test(t);
+  return resultsStructure && muggleContext;
+}
+function collectInspectableText(cmd, cwd, read) {
+  let text = cmd;
+  for (const m of cmd.matchAll(/--body-file[=\s]+("[^"]+"|'[^']+'|\S+)/g)) {
+    const p = unquote(m[1]);
+    if (p && p !== "-") {
+      const c = read(p, cwd);
+      if (c) text += "\n" + c;
+    }
+  }
+  for (const m of cmd.matchAll(/jq\b[^|]*?("[^"]+\.json"|'[^']+\.json'|\S+\.json)/g)) {
+    const c = read(unquote(m[1]), cwd);
+    if (c) text += "\n" + c;
+  }
+  return text;
+}
+function evaluateReportPost(input2, read = defaultReader) {
+  if (input2.tool_name !== "Bash") return { deny: false };
+  const cmd = input2.tool_input?.command ?? "";
+  if (!PR_POST_CMD.test(cmd)) return { deny: false };
+  const text = collectInspectableText(cmd, input2.cwd, read);
+  if (text.includes(REPORT_SENTINEL)) return { deny: false };
+  if (!looksLikeE2EReport(text)) return { deny: false };
+  return {
+    deny: true,
+    reason: "Blocked: this looks like a hand-written E2E test report. Muggle requires the deterministic renderer \u2014 build the run's E2eReport JSON and pipe it through `muggle build-pr-section` (or invoke /muggle:muggle-pr-visual-walkthrough), then post that output. Never hand-write the walkthrough markdown."
+  };
+}
 
 // src/guardrails/emit.ts
 function envelope(eventName, context, host2) {
@@ -83,6 +154,22 @@ function envelope(eventName, context, host2) {
     hookSpecificOutput: { hookEventName: eventName, additionalContext: context }
   });
 }
+function blockStop(reason, host2) {
+  if (!reason) return "{}";
+  if (host2 === "cursor") return JSON.stringify({ additional_context: reason });
+  return JSON.stringify({ decision: "block", reason });
+}
+function denyTool(reason, host2) {
+  if (!reason) return "{}";
+  if (host2 === "cursor") return JSON.stringify({ additional_context: reason });
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason
+    }
+  });
+}
 
 // src/guardrails/cli.ts
 function readStdin() {
@@ -108,25 +195,26 @@ Per the autoWatchPR preference, a muggle-pr-followup watcher should handle its i
 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);
+  const next = applyRecordedRun(state, {
+    unitTestPassed: isTestCommand(cmd) && testsPassed(input),
+    e2eRan: isE2ERun(input)
+  });
+  if (next !== state) writeState(next);
   return "{}";
 }
 function e2eGate() {
   const state = readState(sessionId);
-  if (!shouldRunE2E(state)) return "{}";
-  state.e2eRun = true;
+  const decision = e2eGateDecision(state);
+  if (decision.action === "none" /* None */ || decision.action === "release" /* Release */) return "{}";
+  state.e2eBlockCount = decision.blockCount;
   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);
+  const reason = `Do not end the turn yet. Unit tests passed this session but no E2E acceptance run has happened. Per the autoE2ETest preference (default: always), run change-driven E2E now via /muggle:muggle-test, then finish. If E2E genuinely cannot run here (no app, services down, no PR), say so explicitly to the user \u2014 this gate releases after ${MAX_E2E_BLOCKS} attempts.`;
+  return blockStop(reason, host);
+}
+function reportGate() {
+  const result = evaluateReportPost(input);
+  if (!result.deny || !result.reason) return "{}";
+  return denyTool(result.reason, host);
 }
 function buildRouter() {
   if (!detectBuildIntent(input.prompt ?? "")) return "{}";
@@ -141,6 +229,7 @@ var handlers = {
   "pr-opened": prOpened,
   "record-tests": recordTests,
   "e2e-gate": e2eGate,
+  "report-gate": reportGate,
   "build-router": buildRouter
 };
 process.stdout.write((handlers[sub] ?? (() => "{}"))());

package/plugin/skills/_shared/dev-loop/run.md

@@ -23,7 +23,7 @@ One local browser exists, so **execution is sequential** — one test case at a
 Per test case, branch on `mode`:
 
 **Replay**
-1. `muggle-remote-test-script-get` (latest replayable script) → note `actionScriptId`.
+1. `muggle-remote-test-script-get` (latest replayable script — the lane-scoped one the caller resolved during classification per [`../failure-mode-handling.md`](../failure-mode-handling.md) §A) → note `actionScriptId`.
 2. `muggle-remote-action-script-get` with that id → full `actionScript` (see [`action-script.md`](action-script.md)).
 3. `muggle-local-execute-replay` with `testScript`, `actionScript`, `localUrl`, `cwd`, `showUi`, `freshSession` (see [`fresh-session.md`](fresh-session.md)), `timeoutMs` (see [`timeouts.md`](timeouts.md)).
 

package/plugin/skills/_shared/failure-mode-handling.md

@@ -61,7 +61,7 @@ Run during change analysis, **per impacted test case**. Picks the initial execut
 
 - The change summary from `git diff` (file paths + diff content).
 - The test case (title, description, instructions, last passing run timestamp).
-- Existing test scripts for that test case from `muggle-remote-test-script-list`.
+- Existing test scripts for that test case from `muggle-remote-test-script-list`, scoped to the run's lane: pass `runEnvironmentType: "local"` in Local mode (Step 7A), `"remote"` in Remote mode (Step 7B). The lane is fixed at runtime — it selects the versioned runSettings the cloud resolves — so a local run keys replay-vs-regen off the localhost-lane script and a remote run off the deployed-lane script, never the other lane's.
 
 ### Rules (fire in order; first match wins)
 

package/plugin/skills/do/e2e-acceptance.md

@@ -98,7 +98,7 @@ Based on the changed files and the requirements goal, determine which test cases
 
 ### Step 4: Run the dev loop, gather screenshots
 
-For each relevant test case, run the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): `muggle-remote-test-script-list` by `testCaseId` to pick [replay vs regen](../_shared/dev-loop/run.md), [execute with `timeoutMs`](../_shared/dev-loop/timeouts.md), [fetch the result](../_shared/dev-loop/failures.md) and [interpret failures](../_shared/dev-loop/failures.md), then read the studio-published [cloud refs and per-step screenshots](../_shared/dev-loop/publish.md) off the run result.
+For each relevant test case, run the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): `muggle-remote-test-script-list` by `testCaseId` with `runEnvironmentType: "local"` (this stage runs against localhost) to pick [replay vs regen](../_shared/dev-loop/run.md), [execute with `timeoutMs`](../_shared/dev-loop/timeouts.md), [fetch the result](../_shared/dev-loop/failures.md) and [interpret failures](../_shared/dev-loop/failures.md), then read the studio-published [cloud refs and per-step screenshots](../_shared/dev-loop/publish.md) off the run result.
 
 Inputs to the loop: `mode` from the script-exists check, `localUrl`/project from Step 1.7, `cwd` = the working tree recorded in `state.md`.
 

package/plugin/skills/muggle-browser-task/SKILL.md

@@ -74,6 +74,7 @@ Tell the user: `Created test case: <id>`.
 Load and call `muggle-remote-test-script-list` with:
 - `projectId`: from Step 2
 - `testCaseId`: from Step 4
+- `runEnvironmentType`: `"local"` — this skill executes in the local browser, so it resolves the local-lane script. The lane is an explicit env type, exactly as the remote flow passes `"remote"`; the target URL is just the lane's url and never decides the lane.
 
 Tell the user which mutations will be applied: `Mutations: <mutations[]>` (or "no mutations" if empty).
 

package/plugin/skills/muggle-preferences/preference-gates/README.md

@@ -16,16 +16,19 @@ which uses `local` / `remote` / `ask`).
 
 ## Gate behavior
 
-- `always` → take the pro-action, then print silent footer.
-- `never` → take the skip-action, then print silent footer.
+- `always` → take the pro-action, then **always** print the silent footer.
+- `never` → take the skip-action, then **always** print the silent footer.
 - `ask` (or absent) → run Picker 1 (per-key file) → Picker 2 (below).
 
 `defaultExecutionMode` uses `local`/`remote` instead of `always`/`never`.
 
-## Silent footer (whenever pickers are skipped)
+## Silent footer (mandatory whenever a prompt is skipped)
 
-The user must always be told **what happened**, **why it was silent**, and
-**how to change it**. Two lines:
+Whenever a gate resolves to a non-`ask` value and skips its picker, the footer
+below is **required** — every gate, every time, no exceptions. It tells the
+user **what happened**, **why it was silent**, and **how to change it**. The
+`preference-gates-lint` test enforces that this contract exists; omitting the
+footer when a gate fires is a bug. Two lines:
 
 ```
 ✓ <silent action from per-key file>

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

@@ -219,7 +219,7 @@ Wait for user confirmation before moving to execution.
 
 ### 6f: Classify execution mode per test case (replay vs regen)
 
-For each selected test case, decide whether the run should be a **replay** of an existing script or a fresh **regen**, using the rules in [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) section A. Inputs: the change summary from Step 2, the test case body, and the result of `muggle-remote-test-script-list` for that test case (last passing timestamp + whether any replayable script exists).
+For each selected test case, decide whether the run should be a **replay** of an existing script or a fresh **regen**, using the rules in [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) section A. Inputs: the change summary from Step 2, the test case body, and the result of `muggle-remote-test-script-list` for that test case (last passing timestamp + whether any replayable script exists). Scope that list call to the run's lane — `runEnvironmentType: "local"` in Local mode, `"remote"` in Remote mode (section A) — so replay reuses the script for the lane the run will execute against.
 
 Per test case, fire one `muggle-local-telemetry-event-emit` with `eventType: "pre-execution-classification"` capturing the picked mode, the rule that fired, and the matched changed-file paths.
 

package/plugin/skills/muggle-test/execute-remote.md

@@ -28,7 +28,7 @@ Branch each test case on its `mode`, then issue **all** workflow-start calls in
 - `instructions`: From the test case
 - `expectedResult`: From the test case
 
-**Replay-mode test case** — `muggle-remote-workflow-start-test-script-replay` against the latest replayable script for that test case (resolve via `muggle-remote-test-script-list` if not already in hand from the classification step). Tag results with `mode: "replay"` so the router routes failures correctly.
+**Replay-mode test case** — `muggle-remote-workflow-start-test-script-replay` against the latest replayable script for that test case (resolve via `muggle-remote-test-script-list` with `runEnvironmentType: "remote"` if not already in hand from the classification step). Tag results with `mode: "replay"` so the router routes failures correctly.
 
 Store each returned workflow runtime ID along with its mode tag.
 

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

@@ -136,7 +136,7 @@ Before deciding the target's script, resolve its prerequisite chain from the bac
 
 ### 5. Existing scripts vs new generation
 
-`muggle-remote-test-script-list` with `testCaseId`.
+`muggle-remote-test-script-list` with `testCaseId` and `runEnvironmentType: "local"` — this skill always replays against localhost, so resolve the local-lane script (the remote-lane script carries the deployed URL).
 
 - **If any replayable/succeeded scripts exist:** use `AskUserQuestion` to present them as clickable options. Show: name, created/updated, step count per option. Include **"Generate new script"** as the last option.
 - **If none:** go straight to generation (no need to ask replay vs generate).