@muggleai/works 5.10.0 → 5.11.1

package/dist/{chunk-7NC2DJTK.js → chunk-WUMAJOBT.js}

@@ -1,4 +1,4 @@
-import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, reconcileProjectPreferences, getDataDir, PREFERENCES_FILE_NAME, isFirstRun, writePreferences, DEFAULT_PREFERENCES, 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-OCLMXAVJ.js';
+import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, reconcileProjectPreferences, getDataDir, PREFERENCES_FILE_NAME, isFirstRun, writePreferences, DEFAULT_PREFERENCES, 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-MSPMXBO5.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { v4 } from 'uuid';
@@ -751,7 +751,7 @@ async function resolveGsScreenshotUrls(report, opts) {
     if (gsUrls.length === 0) {
       return report;
     }
-    const mcps = await import('./src-AWUORQZZ.js');
+    const mcps = await import('./src-B5OTAZKM.js');
     const credentials = await mcps.getCallerCredentialsAsync();
     if (!credentials.bearerToken && !credentials.apiKey) {
       stderrWrite(
@@ -848,9 +848,14 @@ ${err.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n")}
   const resolvedReport = await resolveGsScreenshotUrls(report, { stderrWrite: opts.stderrWrite });
   const sentinelCost = Buffer.byteLength(`${REPORT_SECTION_SENTINEL}
 `, "utf-8");
-  const result = buildPrSection(resolvedReport, { maxBodyBytes: opts.maxBodyBytes - sentinelCost });
+  const renderedSection = buildPrSection(resolvedReport, {
+    maxBodyBytes: opts.maxBodyBytes - sentinelCost
+  });
   opts.stdoutWrite(
-    JSON.stringify({ body: withSentinel(result.body), comment: withSentinel(result.comment) })
+    JSON.stringify({
+      body: withSentinel(renderedSection.body),
+      comment: withSentinel(renderedSection.comment)
+    })
   );
   return 0;
 }

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-7NC2DJTK.js';
-import './chunk-OCLMXAVJ.js';
+import { runCli } from './chunk-WUMAJOBT.js';
+import './chunk-MSPMXBO5.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-7NC2DJTK.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-OCLMXAVJ.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-WUMAJOBT.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-MSPMXBO5.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.10.0",
+  "version": "5.11.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.10.0",
+  "version": "5.11.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/agents/test-prepare-runner.md

@@ -38,7 +38,9 @@ Track every launched process in `/tmp/muggle-test-prepare.json` exactly per the
 
 ## Output contract
 
-Return the readiness-report table verbatim as your report, prefixed by one line: `READY` (all services green), `DEGRADED: <which service, why>` (something is up but failed its smoke test after the clean-restart loop), or `needs-input: <decision>`. The dispatcher relays this to its caller — other skills gate on it, so a wrong `READY` is expensive; when in doubt between READY and DEGRADED, pick DEGRADED and say why. `needs-input:` is only for a decision the plan failed to resolve (a missing URL, an unapproved start, an unknown directory) — a service that stays broken after the loop is `DEGRADED` with the diagnosis, never `needs-input:`, even when no further automated fix exists. Repairing the app's own source code is out of scope entirely: a source-level bug surfaced by the smoke test is a `DEGRADED` diagnosis to report, not a decision to escalate.
+Return the readiness-report table verbatim as your report, prefixed by one line: `READY` (all services green), `DEGRADED: <which service, why>` (something is up but failed its smoke test after the clean-restart loop), or `needs-input: <decision>`.
+
+Also return every problem you hit and what cleared it — signal, service, resolution — per [`../skills/muggle-test-prepare/steps/record-resolution.md`](../skills/muggle-test-prepare/steps/record-resolution.md). On a learning run the dispatcher folds these into the recipe gate; on a replay they confirm the recipe still holds. A problem you could not clear is not a resolution: report it as an exclusion with its reason. You persist none of this yourself — the dispatcher owns every write. The dispatcher relays this to its caller — other skills gate on it, so a wrong `READY` is expensive; when in doubt between READY and DEGRADED, pick DEGRADED and say why. `needs-input:` is only for a decision the plan failed to resolve (a missing URL, an unapproved start, an unknown directory) — a service that stays broken after the loop is `DEGRADED` with the diagnosis, never `needs-input:`, even when no further automated fix exists. Repairing the app's own source code is out of scope entirely: a source-level bug surfaced by the smoke test is a `DEGRADED` diagnosis to report, not a decision to escalate.
 
 ## Guardrails
 

package/dist/plugin/agents/visual-walkthrough-builder.md

@@ -31,15 +31,22 @@ echo "$REPORT_JSON" | muggle build-pr-section > /tmp/muggle-pr-section.json
 
 ## Deliver
 
-**Mode A (`post`)** — post `body` as a PR comment, then `comment` only if non-null. Append the Muggle Works signature to each posted body per [`../skills/_shared/vcs/post-signature.md`](../skills/_shared/vcs/post-signature.md) — this post is the walkthrough's own, so the command it names is `/muggle-pr-visual-walkthrough`:
+**Mode A (`post`)** — deliver `body`, then `comment` only if non-null. Sign each posted body per [`../skills/_shared/vcs/post-signature.md`](../skills/_shared/vcs/post-signature.md) with `--mode plain` — this post is the walkthrough's own, so the command it names is `/muggle-pr-visual-walkthrough`.
+
+**Update in place when this PR already carries a walkthrough.** A rerun after a failure must leave the PR with **one** walkthrough reflecting latest state, not a comment per attempt. Resolve which comment to update by reading the PR — never by remembering an id — so the behavior is idempotent across sessions and survives a lost session or a forgotten handle:
 
 ```bash
-sig='🤖 _Posted by `/muggle-pr-visual-walkthrough` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_'
-{ jq -r '.body' /tmp/muggle-pr-section.json; printf '\n\n%s\n' "$sig"; } | gh pr comment <prNumber> --body-file -
-{ jq -r '.comment' /tmp/muggle-pr-section.json; printf '\n\n%s\n' "$sig"; } | gh pr comment <prNumber> --body-file -   # skip when null
+sign() { bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command /muggle-pr-visual-walkthrough --mode plain; }
+existing=$(gh api "repos/<owner>/<repo>/issues/<prNumber>/comments" \
+  --jq '[.[] | select(.body | contains("muggle-pr-section")) | .id] | join(" ")')
 ```
 
-Report back: PR URL + whether an overflow comment was posted.
+- `existing` empty → post fresh: `jq -r '.body' … | sign | gh pr comment <prNumber> --body-file -`, then the same for `.comment` when non-null.
+- `existing` non-empty → update the first id with `body` via `gh api --method PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@-`, feeding the same signed text on stdin. Handle `comment` against the second id when both exist; post it fresh when the overflow is new, and delete a now-surplus overflow comment (`gh api --method DELETE …`) so a stale tail never outlives the run it described.
+
+Match only comments carrying the sentinel — never every comment the loop user wrote — so an unrelated reply is never overwritten.
+
+Report back: PR URL, whether an overflow comment was involved, and whether this was a fresh post or an update.
 
 **Modes B/C (`render-for-new-pr` / `embed`)** — do not post, do not touch `gh`. Return the CLI output verbatim as your report:
 

package/dist/plugin/commands/mtest.md

@@ -1,5 +1,5 @@
 ---
-description: Run change-driven E2E acceptance tests on your changes (alias for /muggle-test)
+description: Real-browser E2E on your changes — no Playwright code, screenshots on the PR (alias for /muggle-test)
 argument-hint: [optional context, e.g. "on staging"]
 allowed-tools: [Skill]
 ---

package/dist/plugin/hooks/README.md

@@ -26,24 +26,36 @@ Enforcement is reserved for the handoffs that were being skipped: the E2E accept
 
 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.
 
+Each wrapper short-circuits in shell first, so the common case never pays Node cold-start. That pre-filter is a second, looser copy of what `guardrails.mjs` matches, and it is the one place a guardrail can fail *silently*: a payload it drops — a skip marker, a reopen line, a comment edit — reaches no recorder, and the gate keeps demanding an action the user already took. Over-matching is free; under-matching is a dead escape hatch. `src/test/guardrails/hook-prefilter.test.ts` pins every payload each subcommand acts on against the wrapper guarding it, and derives the skip-marker tokens from source so a new marker is covered the moment it exists.
+
 ## Guardrails
 
 | 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/skill-emit MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, an E2E run happened (execute/replay call, or the muggle-test skill's own telemetry emit — which registers a clean SKIP verdict too), or an `echo "MUGGLE_E2E_SKIP: <reason>"` marker declared E2E un-runnable | — | set `unitTestsGreen` / `e2eRun` / `e2eSkipped` session state |
+| `PostToolUse` (Bash + muggle execute/replay/skill-emit MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, an E2E run happened (execute/replay call, or the muggle-test skill's own telemetry emit — which registers a clean SKIP verdict too), or an `echo "MUGGLE_E2E_SKIP: <reason>"` marker declared E2E un-runnable, or a walkthrough carrying the `build-pr-section` sentinel was posted / declared un-postable via `echo "MUGGLE_WALKTHROUGH_SKIP: <reason>"` | — | set `unitTestsGreen` / `e2eRun` / `e2eSkipped` / `walkthroughPosted` / `walkthroughSkipped` session state |
 | `PostToolUse` (Bash + Monitor) | `guardrail-pr-terminal.sh` | advise | a PR just went terminal — a `gh pr merge`/`gh pr close` success line or the watch monitor's `TERMINAL pr=N` exit line (never bare `"state":"MERGED"` metadata) | — | record `terminalPending`, direct the post-merge handoff: finalize the watcher slot, tear down per `autoCleanup`, offer next options via AskUserQuestion |
 | `PostToolUse` (AskUserQuestion) | `guardrail-offer-ran.sh` | record | a next-options offer ran while a terminal PR was pending | — | clear `terminalPending` — the only exit for the post-merge Stop gate |
-| `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 |
+| `PostToolUse` (Skill + muggle telemetry-skill-emit) | `guardrail-skill-stages.sh` | advise | a skill this plugin ships was invoked; its `SKILL.md` frontmatter may declare `mandatoryStages`. Registered on the skill's own MCP announcement too, so the declaration still lands if the Skill payload ever stops carrying a name | — | record `lastInvokedSkillName` + `mandatoryStages`, and name the declared files as required reading at the moment of use |
+| `PostToolUse` (Read) | `guardrail-record-stage-read.sh` | record | a markdown file under a `skills/` directory was opened | — | append to `stagesRead` — how the stage gate tells a stage that was read from one that was skipped |
+| `PostToolUse` (Bash + muggle telemetry-event-emit / user-feedback-create) | `guardrail-record-stage-signals.sh` | record | a Step 6f `pre-execution-classification` emit, debug-path evidence for a failed run (a `*-failure-classified\|resolved` emit or feedback naming it), or a `MUGGLE_STAGE_SKIP` / `MUGGLE_CLASSIFY_SKIP` / `MUGGLE_DEBUG_SKIP` marker | — | set `classifiedTestCaseIds` / `debuggedRuns` / the matching skip flag |
+| `PreToolUse` (Bash) | `guardrail-report-format.sh` | **enforce** | a `gh pr comment\|create\|edit` body — or a `gh api … issues/comments/<id>` PATCH editing one — reads like an E2E report but lacks the `build-pr-section` sentinel | — | **deny** — render via `muggle build-pr-section` instead |
+| `PreToolUse` (muggle local execute/replay) | `guardrail-classify-gate.sh` | **enforce** | `muggle-test` is the skill in play and the target test case has no `pre-execution-classification` this session | — | **deny** — run Step 6f first (it calls `muggle-remote-test-script-list`, which is where the run learns the case has never passed) or record a legitimate skip via `MUGGLE_CLASSIFY_SKIP`. Scoped to `muggle-test`, so the single-target skills that legitimately skip classification are untouched; fails open when the test case can't be resolved |
 | `Stop` | `guardrail-e2e-gate.sh` | **enforce** | unit tests passed this session, no E2E ran yet, and no skip was recorded | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` or a `MUGGLE_E2E_SKIP` marker records a legitimate skip (full message once, one-line reminders after; releases after 3 blocks) |
 | `Stop` | `guardrail-terminal-gate.sh` | **enforce** | a PR went terminal this session and the AskUserQuestion next-options offer hasn't run since | — | **block** the turn until the post-merge handoff runs (full message once, one-line reminders after; releases after 3 blocks; nothing but the offer resets the counter) |
+| `Stop` | `guardrail-watch-gate.sh` | **enforce** | a PR opened this session that no `muggle-do` session slot tracks | `autoWatchPR` | **block** the turn until a slot is seeded via `muggle-pr-followup` or a `MUGGLE_WATCH_SKIP` marker records a legitimate skip (releases after 3 blocks) |
+| `Stop` | `guardrail-walkthrough-gate.sh` | **enforce** | an E2E acceptance run happened this session and a PR in play — opened this session or on the working branch — carries no walkthrough in its body or comments | `postPRVisualWalkthrough` | **block** the turn until the walkthrough is posted via `muggle-pr-visual-walkthrough` or a `MUGGLE_WALKTHROUGH_SKIP` marker records a legitimate skip (releases after 3 blocks; an unreachable PR fails open to not-owed) |
+| `Stop` | `guardrail-stage-gate.sh` | **enforce** | a skill invoked this session declared `mandatoryStages` and one of those files was never opened | — | **block** the turn until the stages are read or a `MUGGLE_STAGE_SKIP` marker records a legitimate skip (releases after 3 blocks) |
+| `Stop` | `guardrail-debug-path-gate.sh` | **enforce** | a local execution returned a non-passing run this session and nothing routed it through `_shared/debug-failed-run.md` | — | **block** the turn until the run is diagnosed (its `*-failure-classified` emit or feedback naming it) or a `MUGGLE_DEBUG_SKIP: <runId> <reason>` marker clears that run (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) |
 
 ## Session-start reconcile nudge
 
 `SessionStart` (`scripts/reconcile-stale-watchers.sh`) — a standalone advisory, not part of the `guardrails.mjs` decision tree above.
 
-`muggle-pr-followup` watchers are session-only (a monitor or `/loop` cron); they die with their session, leaving open PRs with no live poller. This is by design — a review is addressed only inside a session that carries the context to address it. The skill's [`reconcile`](../skills/muggle-pr-followup/reconcile.md) procedure recovers them at the next session start — finalizes slots whose PR went terminal, sweeps orphan crons, re-arms silently-stopped open watchers — but re-arming needs Claude tools a shell hook can't call. So this hook nudges rather than acts: it scans `~/.muggle-ai/muggle-do/sessions/*/` for open slots (a `prs.json` with no `result.md`) and, **only when one or more exist**, injects `additionalContext` telling the agent to run `/muggle:muggle-pr-followup reconcile`. Zero open slots → it emits nothing. A pure directory scan (no `gh`, no writes), so it's cheap enough for every session start.
+`muggle-pr-followup` watchers are session-only (a monitor or `/loop` cron); they die with their session, leaving open PRs with no live poller. This is by design — a review is addressed only inside a session that carries the context to address it. The skill's [`reconcile`](../skills/muggle-pr-followup/reconcile.md) procedure recovers them at the next session start — finalizes slots whose PR went terminal, sweeps orphan crons, re-arms silently-stopped open watchers — but re-arming needs Claude tools a shell hook can't call. So this hook nudges rather than acts.
+
+The nudge counts only slots **this session owns**, and reports the rest as orphans it will not act on — ownership and the recovery rules it gates are defined in [`reconcile`](../skills/muggle-pr-followup/reconcile.md). Nothing owned and nothing orphaned → it emits nothing. A pure directory scan (no `gh`, no writes), so it's cheap enough for every session start.
 
 ## Session-start state GC
 

package/dist/plugin/hooks/hooks.json

@@ -36,6 +36,17 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "mcp__.*muggle.*(execute-test-generation|execute-replay)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-classify-gate.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -59,6 +70,12 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-pr-terminal.sh\"",
             "async": false,
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-stage-signals.sh\"",
+            "async": false,
+            "timeout": 10
           }
         ]
       },
@@ -73,6 +90,50 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__.*muggle.*(telemetry-event-emit|user-feedback-create)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-stage-signals.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-skill-stages.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*muggle.*telemetry-skill-emit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-skill-stages.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-stage-read.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Monitor",
         "hooks": [
@@ -116,6 +177,24 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-watch-gate.sh\"",
             "async": false,
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-walkthrough-gate.sh\"",
+            "async": false,
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-stage-gate.sh\"",
+            "async": false,
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-debug-path-gate.sh\"",
+            "async": false,
+            "timeout": 10
           }
         ]
       }

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

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# pre-execution-classification gate (PreToolUse/muggle local execution tools).
+# Denies a generation or replay whose test case was never classified per
+# muggle-test Step 6f. That step calls muggle-remote-test-script-list, which is
+# where the run finds out the test case has never passed or has failed
+# repeatedly — the check is free before dispatch and costs a full browser run
+# once skipped.
+#
+# The pre-filter re-states the execution tool names the gate acts on, so an
+# unrelated payload never pays Node cold-start. It stays cheap by construction:
+# an execution call happens minutes apart and burns a real browser, so the spawn
+# is noise against what it protects. Degrades to {}.
+payload="$(cat)"
+
+if ! grep -Eiq 'muggle-local-(execute-test-generation|execute-replay)' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" classify-gate 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrail-debug-path-gate.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# debug-path gate (Stop). When a run failed this session and never went through
+# _shared/debug-failed-run.md, block the turn end naming the run (or the
+# MUGGLE_DEBUG_SKIP escape hatch). muggle-test Step 7C marks that routing
+# mandatory and it was still routinely skipped, so failures were summarized and
+# dropped — the run a reviewer most needs to see is the one nobody looked at.
+#
+# Mirrors guardrail-watch-gate.sh: synchronous (only a sync Stop hook can block
+# the turn end), fires on EVERY turn end, and pre-filters in shell so Node spawns
+# only when a failed run is recorded and unresolved. On the overwhelming majority
+# of turns nothing failed, so the state file is absent or failedRuns is empty and
+# we return {} in-shell. The evidence join runs in guardrails.mjs. Degrades to {}.
+payload="$(cat)"
+
+raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
+[ -n "$raw_sid" ] || raw_sid="unknown"
+sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+
+# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
+# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
+# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
+home="${HOME:-}"
+if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
+  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
+fi
+
+# Empty array serializes as `"failedRuns": []` (one line); a non-empty array
+# spans lines, so the empty match reliably tells them apart.
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"failedRuns"' "$state_file" \
+  || grep -q '"failedRuns": \[\]' "$state_file" \
+  || grep -q '"debugSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" debug-path-gate 2>/dev/null || printf '{}'

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

@@ -9,10 +9,14 @@ set -uo pipefail
 # AskUserQuestion offer runs. Decision logic lives in the bundled guardrails.mjs.
 #
 # Fires after every Bash call, so a keyword pre-filter for the terminal output
-# shapes keeps Node off the hot path. Degrades to {} so it never blocks.
+# shapes keeps Node off the hot path. The reopen line belongs here too: it is
+# the one signal that retracts a terminal verdict, and while the pre-filter
+# dropped it a close+reopen — routine, to re-fire a lost workflow trigger — left
+# the handoff armed on a change that is open again. Degrades to {} so it never
+# blocks.
 payload="$(cat)"
 
-if ! grep -Eiq 'merged pull request|closed pull request|TERMINAL pr=' <<<"$payload"; then
+if ! grep -Eiq '(merged|closed|reopened) pull request|TERMINAL pr=' <<<"$payload"; then
   printf '{}'
   exit 0
 fi

package/dist/plugin/scripts/guardrail-record-stage-read.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# stage-read observer (PostToolUse/Read). Records that a file in the skills tree
+# was opened, which is how the Stop gate tells a mandatory stage that was read
+# from one that was skipped. Emits no directive.
+#
+# Read fires constantly, so only a markdown file living under a `skills/`
+# directory reaches Node — a mandatory stage can be any file in that tree, but
+# never one outside it, so source reads and repo docs return {} in-shell. Both
+# path separators are accepted: a Windows payload carries escaped backslashes.
+# Degrades to {}.
+payload="$(cat)"
+
+if ! grep -Eiq '"file_path"[[:space:]]*:[[:space:]]*"[^"]*[/\\]+skills[/\\]+[^"]*\.md"' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" record-stage-read 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrail-record-stage-signals.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# stage-signal observer (PostToolUse/Bash + muggle telemetry and feedback tools).
+# Records the three things the stage gates settle from: a Step 6f
+# pre-execution-classification emit, debug-path evidence for a failed run (a
+# failure-classified emit or feedback naming it), and the skip markers each gate
+# documents as its way out. Emits no directive — the gates read the state.
+#
+# The marker arm matches the MUGGLE_<GATE>_SKIP shape, never one token: a gate
+# whose marker is missing from a hand-listed set instructs the user to run an
+# echo that can never register, then blocks the turn anyway. Anchoring the
+# marker to a leading `echo` stays in guardrails.mjs; over-matching here only
+# costs a needless spawn. Degrades to {}.
+payload="$(cat)"
+
+if ! grep -Eiq 'MUGGLE_[A-Z0-9_]+_SKIP|muggle.*(telemetry-event-emit|user-feedback-create)' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" record-stage-signals 2>/dev/null || printf '{}'

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

@@ -10,12 +10,19 @@ set -uo pipefail
 # pre-filter for test runners and the muggle E2E tool names keeps Node off the
 # hot path. Only a `test` command (npm/pnpm/yarn/jest/vitest/pytest/go/cargo),
 # a muggle execute/replay/test-generation event, a muggle-test skill telemetry
-# emit (registers a clean-SKIP verdict as an E2E run), or an E2E skip marker
-# reaches guardrails.mjs, which then inspects the output for pass/fail and
-# updates state. Degrades to {}.
+# emit (registers a clean-SKIP verdict as an E2E run), a skip marker, or a PR
+# publish carrying a rendered walkthrough reaches guardrails.mjs, which then
+# inspects the output for pass/fail and updates state. Degrades to {}.
+#
+# The marker arm matches the MUGGLE_<GATE>_SKIP shape, never one token: every
+# Stop gate documents its own marker as the escape hatch, and a per-token list
+# left the watcher and walkthrough markers unreachable — the gates instructed
+# the user to run an echo that could never reach the recorder, then blocked the
+# turn anyway. Anchoring the marker to a leading `echo` stays in guardrails.mjs;
+# over-matching here only costs a needless spawn.
 payload="$(cat)"
 
-if ! grep -Eiq '(pnpm|npm|yarn)[[:space:]]+(run[[:space:]]+)?test|jest|vitest|pytest|go[[:space:]]+test|cargo[[:space:]]+test|muggle.*(execute|test-generation|replay)|muggle-local-telemetry-skill-emit|MUGGLE_E2E_SKIP' <<<"$payload"; then
+if ! grep -Eiq '(pnpm|npm|yarn)[[:space:]]+(run[[:space:]]+)?test|jest|vitest|pytest|go[[:space:]]+test|cargo[[:space:]]+test|muggle.*(execute|test-generation|replay)|muggle-local-telemetry-skill-emit|MUGGLE_[A-Z0-9_]+_SKIP|gh[[:space:]]+pr[[:space:]]+(comment|create|edit)|issues/comments/[0-9]' <<<"$payload"; then
   printf '{}'
   exit 0
 fi

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

@@ -7,14 +7,18 @@ set -uo pipefail
 # deterministic renderer.
 #
 # This must stay synchronous (only a sync PreToolUse hook can deny), and it fires
-# before every Bash call. A keyword pre-filter for the three PR-posting commands
+# before every Bash call. A keyword pre-filter for the PR-publishing commands
 # keeps Node off the hot path: a plain `ls`/`git status`/build command returns {}
-# in-shell and never pays cold-start. Only a `gh pr comment|create|edit` reaches
-# guardrails.mjs, which reads the body (incl. --body-file) and decides. Degrades
-# to {} so it never blocks an unrelated command.
+# in-shell and never pays cold-start. Only a `gh pr comment|create|edit` or a
+# `gh api` comment edit reaches guardrails.mjs, which reads the body (incl.
+# --body-file) and decides. The comment-edit arm matters as much as the post
+# arm: guardrails.mjs gates that path precisely so a sanctioned walkthrough
+# can't be overwritten with hand-written markdown afterwards, and a pre-filter
+# on `gh pr` alone left that bypass wide open. Degrades to {} so it never blocks
+# an unrelated command.
 payload="$(cat)"
 
-if ! grep -Eiq 'gh[[:space:]]+pr[[:space:]]+(comment|create|edit)' <<<"$payload"; then
+if ! grep -Eiq 'gh[[:space:]]+pr[[:space:]]+(comment|create|edit)|issues/comments/[0-9]' <<<"$payload"; then
   printf '{}'
   exit 0
 fi

package/dist/plugin/scripts/guardrail-skill-stages.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# mandatory-stage recorder (PostToolUse/Skill). Records which skill is running
+# and, when its SKILL.md declares `mandatoryStages`, returns those files as
+# required reading at the moment of use. The Stop gate
+# (guardrail-stage-gate.sh) blocks the turn end while any of them is unread.
+#
+# Skill calls are rare, so the pre-filter is a file test rather than a keyword
+# scan: the invoked name is pulled out of the payload and Node runs only when it
+# resolves to a skill this plugin actually ships. Another plugin's skill, or an
+# input with no skill name, returns {} in-shell. Every key the resolver reads is
+# accepted here — a key matched in one and missed in the other makes the gate
+# dead code on exactly the harness that names it that way. Degrades to {}.
+payload="$(cat)"
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+
+for candidate in $(printf '%s' "$payload" \
+  | grep -oE '"(skill|skillName|name|command)"[[:space:]]*:[[:space:]]*"[^"]*"' \
+  | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/'); do
+  # A namespaced invocation (`muggle:muggle-test`) and a slash command
+  # (`/muggle-test`) both name the same skill directory.
+  skill="${candidate##*:}"
+  skill="${skill#/}"
+  case "$skill" in
+    "" | *[!A-Za-z0-9._-]*) continue ;;
+  esac
+  if [ -f "$root/skills/$skill/SKILL.md" ]; then
+    printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" skill-stages 2>/dev/null || printf '{}'
+    exit 0
+  fi
+done
+
+printf '{}'

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

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# mandatory-stage gate (Stop). When a skill invoked this session declared
+# `mandatoryStages` in its SKILL.md and any of those files was never opened,
+# block the turn end naming them (or the MUGGLE_STAGE_SKIP escape hatch). This
+# is the root fix for a skill read as a single page: the SKILL.md links out to
+# steps that are mandatory, nothing forced them open, and the steps were
+# silently dropped.
+#
+# Mirrors guardrail-watch-gate.sh: synchronous (only a sync Stop hook can block
+# the turn end), fires on EVERY turn end, and pre-filters in shell so Node spawns
+# only when a stage is actually owed. On the overwhelming majority of turns no
+# skill declared stages, so the state file is absent or mandatoryStages is empty
+# and we return {} in-shell. The read-vs-declared comparison runs in
+# guardrails.mjs. Degrades to {}.
+payload="$(cat)"
+
+raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
+[ -n "$raw_sid" ] || raw_sid="unknown"
+sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+
+# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
+# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
+# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
+home="${HOME:-}"
+if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
+  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
+fi
+
+# Empty array serializes as `"mandatoryStages": []` (one line); a non-empty array
+# spans lines, so the empty match reliably tells them apart.
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"mandatoryStages"' "$state_file" \
+  || grep -q '"mandatoryStages": \[\]' "$state_file" \
+  || grep -q '"stageSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" stage-gate 2>/dev/null || printf '{}'

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

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# acceptance-run → walkthrough gate (Stop). When an E2E acceptance run happened
+# this session and no visual walkthrough has reached the PR, block the turn end
+# until it does or a skip is declared. Fires once per session per PR.
+#
+# This must stay synchronous (only a sync Stop hook can block the turn end), and
+# it fires on EVERY turn end. There is no command payload to key off, so the
+# pre-filter reads the same per-session state file guardrails.mjs uses and only
+# spawns Node when the gate could actually fire — i.e. an acceptance run is
+# recorded and the walkthrough is neither posted nor skipped. On the
+# overwhelming majority of turns (no E2E this session) the state file is absent
+# or e2eRun is unset, so we return {} in-shell and never pay Node cold-start —
+# which also means the gate's `gh` lookups only ever run on turns that could
+# genuinely owe a walkthrough. Degrades to {}.
+payload="$(cat)"
+
+raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
+[ -n "$raw_sid" ] || raw_sid="unknown"
+sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+
+# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
+# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
+# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
+home="${HOME:-}"
+if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
+  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
+fi
+
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"e2eRun": true' "$state_file" \
+  || grep -q '"walkthroughPosted": true' "$state_file" \
+  || grep -q '"walkthroughSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" walkthrough-gate 2>/dev/null || printf '{}'