@muggleai/works 5.14.0-staging.96 → 5.14.0-staging.97

package/dist/plugin/hooks/hooks.json

@@ -190,6 +190,12 @@
             "async": false,
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-build-followthrough-gate.sh\"",
+            "async": false,
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-walkthrough-gate.sh\"",

package/dist/plugin/scripts/guardrail-build-followthrough-gate.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# build-followthrough gate (Stop). When the front-door router took a
+# build/implement/fix prompt this session but no PR was ever opened, block the
+# turn end and point at /muggle-do (or the MUGGLE_BUILD_SKIP escape hatch). The
+# router's offer is advisory and a session that finds the root cause can still
+# end without shipping it — the fix then lives only in a transcript that dies
+# with the session, and no other gate catches it: the watcher gate only fires on
+# a PR that already exists.
+#
+# 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 build request was routed and no PR was handled. On the
+# overwhelming majority of turns no build intent was detected, so the state file
+# is absent or the flag is unset and we return {} in-shell, never paying Node
+# cold-start. 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
+
+# A non-empty prsHandled array spans lines, so the empty match reliably says no
+# PR was opened. Skip Node unless a build request was routed and nothing shipped.
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"buildIntentRouted": true' "$state_file" \
+  || ! grep -q '"prsHandled": \[\]' "$state_file" \
+  || grep -q '"buildSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" build-followthrough-gate 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrails.mjs

@@ -13,6 +13,7 @@ var GH_PR_REOPENED_LINE = /\bReopened pull request [\w./-]*#(\d+)/;
 var PR_MONITOR_TERMINAL_LINE = /\bTERMINAL pr=(\d+): (MERGED|CLOSED)\b/;
 var MAX_PR_TERMINAL_BLOCKS = 3;
 var MAX_WATCH_BLOCKS = 3;
+var MAX_BUILD_BLOCKS = 3;
 var MAX_WALKTHROUGH_BLOCKS = 3;
 var GH_LOOKUP_TIMEOUT_MS = 1e4;
 var MUGGLE_SKILL_EMIT_TOOL = /muggle-local-telemetry-skill-emit/i;
@@ -583,6 +584,25 @@ function watchGateDecision(state, untrackedPrUrls, maxBlocks = MAX_WATCH_BLOCKS)
     untracked: untrackedPrUrls
   };
 }
+
+// src/guardrails/buildFollowthrough.ts
+var BUILD_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_BUILD_SKIP\b/;
+function isBuildSkipMarker(cmd) {
+  return BUILD_SKIP_MARKER.test(cmd);
+}
+function applyBuildSkip(state, skipped) {
+  if (!skipped || state.buildSkipped === true) return state;
+  return { ...state, buildSkipped: true };
+}
+function buildFollowthroughDecision(state, maxBlocks = MAX_BUILD_BLOCKS) {
+  const blockCount = state.buildBlockCount ?? 0;
+  const owed = state.buildIntentRouted === true && state.buildSkipped !== true && state.prsHandled.length === 0;
+  if (!owed) return { action: "none" /* None */, blockCount };
+  if (blockCount >= maxBlocks) {
+    return { action: "release" /* Release */, blockCount };
+  }
+  return { action: "block" /* Block */, blockCount: blockCount + 1 };
+}
 var REPORT_SENTINEL = "muggle-pr-section";
 var PR_PROSE_CMD = /\bgh\s+pr\s+(comment|create|edit)\b/;
 var GH_API_CMD = /\bgh\s+api\b/;
@@ -1080,7 +1100,8 @@ function recordTests() {
     e2eSkipped: isE2ESkipMarker(cmd)
   });
   const withWatchSkip = applyWatchSkip(recorded, isWatchSkipMarker(cmd));
-  const withWalkthroughPost = applyWalkthroughPosted(withWatchSkip, detectWalkthroughPost(input));
+  const withBuildSkip = applyBuildSkip(withWatchSkip, isBuildSkipMarker(cmd));
+  const withWalkthroughPost = applyWalkthroughPosted(withBuildSkip, detectWalkthroughPost(input));
   const withWalkthroughSkip = applyWalkthroughSkip(withWalkthroughPost, isWalkthroughSkipMarker(cmd));
   const failedRunId = detectFailedRunId(input);
   const next = failedRunId ? applyFailedRun(withWalkthroughSkip, failedRunId) : withWalkthroughSkip;
@@ -1179,6 +1200,16 @@ function watchGate() {
   const reason = decision.blockCount === 1 ? `Do not end the turn yet. A PR was opened this session but no muggle-do session slot tracks it: ${prList}. Seed the slot and hand off per muggle-do Stage 8 \u2014 /muggle:muggle-pr-followup ${decision.untracked[0]} does both. Seeding is what matters: once a slot exists, reconcile arms it at the next session start and finalizes it when the PR goes terminal, so an unarmed slot is fine but no slot means nothing ever picks this PR up. If it genuinely should not be tracked (autoWatchPR=never, handed off elsewhere), tell the user why and run \`echo "MUGGLE_WATCH_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `PR hand-off still owed for ${prList} (reminder ${decision.blockCount}/${MAX_WATCH_BLOCKS}): seed a slot via /muggle:muggle-pr-followup, or record a legitimate skip via \`echo "MUGGLE_WATCH_SKIP: <reason>"\`.`;
   return blockStop(reason, host);
 }
+function buildFollowthroughGate() {
+  const state = readState(sessionId);
+  const decision = buildFollowthroughDecision(state);
+  if (decision.action === "release" /* Release */) return releaseGate("buildSkipped");
+  if (decision.action === "none" /* None */) return "{}";
+  state.buildBlockCount = decision.blockCount;
+  writeState(state);
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. This session took a build/implement/fix request but no PR was opened. A root cause written into the transcript ships nothing \u2014 once the session ends it is gone, and the watcher gate never fires because it only looks at PRs that exist. Carry the work to a PR via /muggle-do, which runs requirements \u2192 build \u2192 impact \u2192 unit tests \u2192 E2E \u2192 PR \u2192 watcher. If no PR is owed here (the user changed their mind, the fix landed in another repo, the answer was advice rather than a change), tell the user why and run \`echo "MUGGLE_BUILD_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `Build request still unanswered \u2014 no PR opened (reminder ${decision.blockCount}/${MAX_BUILD_BLOCKS}): carry it to a PR via /muggle-do, or record a legitimate skip via \`echo "MUGGLE_BUILD_SKIP: <reason>"\`.`;
+  return blockStop(reason, host);
+}
 function walkthroughGate() {
   const state = readState(sessionId);
   if (state.e2eRun !== true || state.walkthroughPosted === true || state.walkthroughSkipped === true) {
@@ -1302,6 +1333,7 @@ var handlers = {
   "e2e-gate": e2eGate,
   "terminal-gate": terminalGate,
   "watch-gate": watchGate,
+  "build-followthrough-gate": buildFollowthroughGate,
   "walkthrough-gate": walkthroughGate,
   "record-comment-replies": recordCommentReplies,
   "comment-reply-gate": commentReplyGate,

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "release": "5.13.0",
-  "buildId": "run-96-1",
-  "commitSha": "3a0a6a70d012faf3cc36cf1ac486fd5650c21da7",
-  "buildTime": "2026-09-05T00:42:20Z",
+  "buildId": "run-97-1",
+  "commitSha": "d59f28752c70cf7a5997accb6aabda88235570b7",
+  "buildTime": "2026-09-05T00:56:07Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.14.0-staging.96",
+  "version": "5.14.0-staging.97",
   "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",

package/plugin/hooks/hooks.json

@@ -190,6 +190,12 @@
             "async": false,
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-build-followthrough-gate.sh\"",
+            "async": false,
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-walkthrough-gate.sh\"",

package/plugin/scripts/guardrail-build-followthrough-gate.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# build-followthrough gate (Stop). When the front-door router took a
+# build/implement/fix prompt this session but no PR was ever opened, block the
+# turn end and point at /muggle-do (or the MUGGLE_BUILD_SKIP escape hatch). The
+# router's offer is advisory and a session that finds the root cause can still
+# end without shipping it — the fix then lives only in a transcript that dies
+# with the session, and no other gate catches it: the watcher gate only fires on
+# a PR that already exists.
+#
+# 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 build request was routed and no PR was handled. On the
+# overwhelming majority of turns no build intent was detected, so the state file
+# is absent or the flag is unset and we return {} in-shell, never paying Node
+# cold-start. 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
+
+# A non-empty prsHandled array spans lines, so the empty match reliably says no
+# PR was opened. Skip Node unless a build request was routed and nothing shipped.
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"buildIntentRouted": true' "$state_file" \
+  || ! grep -q '"prsHandled": \[\]' "$state_file" \
+  || grep -q '"buildSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" build-followthrough-gate 2>/dev/null || printf '{}'

package/plugin/scripts/guardrails.mjs

@@ -13,6 +13,7 @@ var GH_PR_REOPENED_LINE = /\bReopened pull request [\w./-]*#(\d+)/;
 var PR_MONITOR_TERMINAL_LINE = /\bTERMINAL pr=(\d+): (MERGED|CLOSED)\b/;
 var MAX_PR_TERMINAL_BLOCKS = 3;
 var MAX_WATCH_BLOCKS = 3;
+var MAX_BUILD_BLOCKS = 3;
 var MAX_WALKTHROUGH_BLOCKS = 3;
 var GH_LOOKUP_TIMEOUT_MS = 1e4;
 var MUGGLE_SKILL_EMIT_TOOL = /muggle-local-telemetry-skill-emit/i;
@@ -583,6 +584,25 @@ function watchGateDecision(state, untrackedPrUrls, maxBlocks = MAX_WATCH_BLOCKS)
     untracked: untrackedPrUrls
   };
 }
+
+// src/guardrails/buildFollowthrough.ts
+var BUILD_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_BUILD_SKIP\b/;
+function isBuildSkipMarker(cmd) {
+  return BUILD_SKIP_MARKER.test(cmd);
+}
+function applyBuildSkip(state, skipped) {
+  if (!skipped || state.buildSkipped === true) return state;
+  return { ...state, buildSkipped: true };
+}
+function buildFollowthroughDecision(state, maxBlocks = MAX_BUILD_BLOCKS) {
+  const blockCount = state.buildBlockCount ?? 0;
+  const owed = state.buildIntentRouted === true && state.buildSkipped !== true && state.prsHandled.length === 0;
+  if (!owed) return { action: "none" /* None */, blockCount };
+  if (blockCount >= maxBlocks) {
+    return { action: "release" /* Release */, blockCount };
+  }
+  return { action: "block" /* Block */, blockCount: blockCount + 1 };
+}
 var REPORT_SENTINEL = "muggle-pr-section";
 var PR_PROSE_CMD = /\bgh\s+pr\s+(comment|create|edit)\b/;
 var GH_API_CMD = /\bgh\s+api\b/;
@@ -1080,7 +1100,8 @@ function recordTests() {
     e2eSkipped: isE2ESkipMarker(cmd)
   });
   const withWatchSkip = applyWatchSkip(recorded, isWatchSkipMarker(cmd));
-  const withWalkthroughPost = applyWalkthroughPosted(withWatchSkip, detectWalkthroughPost(input));
+  const withBuildSkip = applyBuildSkip(withWatchSkip, isBuildSkipMarker(cmd));
+  const withWalkthroughPost = applyWalkthroughPosted(withBuildSkip, detectWalkthroughPost(input));
   const withWalkthroughSkip = applyWalkthroughSkip(withWalkthroughPost, isWalkthroughSkipMarker(cmd));
   const failedRunId = detectFailedRunId(input);
   const next = failedRunId ? applyFailedRun(withWalkthroughSkip, failedRunId) : withWalkthroughSkip;
@@ -1179,6 +1200,16 @@ function watchGate() {
   const reason = decision.blockCount === 1 ? `Do not end the turn yet. A PR was opened this session but no muggle-do session slot tracks it: ${prList}. Seed the slot and hand off per muggle-do Stage 8 \u2014 /muggle:muggle-pr-followup ${decision.untracked[0]} does both. Seeding is what matters: once a slot exists, reconcile arms it at the next session start and finalizes it when the PR goes terminal, so an unarmed slot is fine but no slot means nothing ever picks this PR up. If it genuinely should not be tracked (autoWatchPR=never, handed off elsewhere), tell the user why and run \`echo "MUGGLE_WATCH_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `PR hand-off still owed for ${prList} (reminder ${decision.blockCount}/${MAX_WATCH_BLOCKS}): seed a slot via /muggle:muggle-pr-followup, or record a legitimate skip via \`echo "MUGGLE_WATCH_SKIP: <reason>"\`.`;
   return blockStop(reason, host);
 }
+function buildFollowthroughGate() {
+  const state = readState(sessionId);
+  const decision = buildFollowthroughDecision(state);
+  if (decision.action === "release" /* Release */) return releaseGate("buildSkipped");
+  if (decision.action === "none" /* None */) return "{}";
+  state.buildBlockCount = decision.blockCount;
+  writeState(state);
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. This session took a build/implement/fix request but no PR was opened. A root cause written into the transcript ships nothing \u2014 once the session ends it is gone, and the watcher gate never fires because it only looks at PRs that exist. Carry the work to a PR via /muggle-do, which runs requirements \u2192 build \u2192 impact \u2192 unit tests \u2192 E2E \u2192 PR \u2192 watcher. If no PR is owed here (the user changed their mind, the fix landed in another repo, the answer was advice rather than a change), tell the user why and run \`echo "MUGGLE_BUILD_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `Build request still unanswered \u2014 no PR opened (reminder ${decision.blockCount}/${MAX_BUILD_BLOCKS}): carry it to a PR via /muggle-do, or record a legitimate skip via \`echo "MUGGLE_BUILD_SKIP: <reason>"\`.`;
+  return blockStop(reason, host);
+}
 function walkthroughGate() {
   const state = readState(sessionId);
   if (state.e2eRun !== true || state.walkthroughPosted === true || state.walkthroughSkipped === true) {
@@ -1302,6 +1333,7 @@ var handlers = {
   "e2e-gate": e2eGate,
   "terminal-gate": terminalGate,
   "watch-gate": watchGate,
+  "build-followthrough-gate": buildFollowthroughGate,
   "walkthrough-gate": walkthroughGate,
   "record-comment-replies": recordCommentReplies,
   "comment-reply-gate": commentReplyGate,