@muggleai/works 5.10.0 → 5.11.0

package/dist/plugin/scripts/guardrails.mjs

@@ -1,6 +1,8 @@
 import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync } from 'fs';
-import { isAbsolute, resolve, join } from 'path';
+import { join, isAbsolute, resolve, dirname } from 'path';
 import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { execFileSync } from 'child_process';
 
 // src/guardrails/cli.ts
 var baseDir = (override) => override ?? join(homedir(), ".muggle-ai", "guardrails");
@@ -47,8 +49,23 @@ 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_WALKTHROUGH_BLOCKS = 3;
+var GH_LOOKUP_TIMEOUT_MS = 1e4;
 var MUGGLE_SKILL_EMIT_TOOL = /muggle-local-telemetry-skill-emit/i;
 var MUGGLE_TEST_SKILL_NAME = "muggle-test";
+var MANDATORY_STAGES_FRONTMATTER_KEY = "mandatoryStages";
+var SKILL_NAME_INPUT_KEYS = ["skill", "skillName", "name", "command"];
+var MAX_STAGE_BLOCKS = 3;
+var MAX_DEBUG_BLOCKS = 3;
+var ANY_TEST_CASE = "*";
+var MUGGLE_EXECUTION_TOOL = /muggle-local-(execute-test-generation|execute-replay)/i;
+var MUGGLE_EVENT_EMIT_TOOL = /muggle-local-telemetry-event-emit/i;
+var MUGGLE_FEEDBACK_CREATE_TOOL = /muggle-remote-user-feedback-create/i;
+var PRE_EXECUTION_CLASSIFICATION_EVENT = "pre-execution-classification";
+var FAILURE_DIAGNOSIS_EVENT = /-failure-(classified|resolved)$/;
+var MUGGLE_RUN_ID_LINE = /\*\*Run ID:\*\*\s*([^\s*]+)/;
+var MUGGLE_RUN_STATUS_LINE = /\*\*Status:\*\*\s*([A-Za-z_]+)/;
+var MUGGLE_RUN_PASSED_STATUS = "passed";
 
 // src/guardrails/prTerminal.ts
 function detectPrTerminal(input2) {
@@ -115,6 +132,207 @@ function prTerminalGateDecision(state, maxBlocks = MAX_PR_TERMINAL_BLOCKS) {
   }
   return { action: "block" /* Block */, blockCount: blockCount + 1 };
 }
+var FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+var SEQUENCE_ENTRY = /^\s*-\s*(.+?)\s*$/;
+var FLOW_LIST = /^\s*\[(.*)\]\s*$/;
+var STAGE_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_STAGE_SKIP\b/;
+var SKILLS_DIR_NAME = "skills";
+var SKILLS_PATH_SEGMENT = `/${SKILLS_DIR_NAME}/`;
+var SINGLE_PATH_SEGMENT = /^[A-Za-z0-9._-]+$/;
+var unquote = (raw) => raw.trim().replace(/^["']|["']$/g, "").trim();
+function parseDeclaredStages(skillMarkdown) {
+  const frontmatter = FRONTMATTER.exec(skillMarkdown)?.[1];
+  if (!frontmatter) return [];
+  const lines = frontmatter.split(/\r?\n/);
+  const keyIndex = lines.findIndex(
+    (line) => line.startsWith(`${MANDATORY_STAGES_FRONTMATTER_KEY}:`)
+  );
+  if (keyIndex < 0) return [];
+  const inlineValue = lines[keyIndex].slice(MANDATORY_STAGES_FRONTMATTER_KEY.length + 1).trim();
+  const flowEntries = FLOW_LIST.exec(inlineValue)?.[1];
+  if (flowEntries !== void 0) {
+    return flowEntries.split(",").map(unquote).filter((entry) => entry.length > 0);
+  }
+  const declared = [];
+  for (const line of lines.slice(keyIndex + 1)) {
+    const entry = SEQUENCE_ENTRY.exec(line);
+    if (!entry) break;
+    declared.push(unquote(entry[1]));
+  }
+  return declared;
+}
+function normalizeStagePath(filePath) {
+  return filePath.replaceAll("\\", "/").toLowerCase();
+}
+function stageLabel(normalizedStagePath) {
+  const insideSkills = normalizedStagePath.lastIndexOf(SKILLS_PATH_SEGMENT);
+  if (insideSkills < 0) return normalizedStagePath;
+  return normalizedStagePath.slice(insideSkills + SKILLS_PATH_SEGMENT.length);
+}
+function resolvePluginSkillsRoot() {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || process.env.CURSOR_PLUGIN_ROOT;
+  if (pluginRoot) return join(pluginRoot, SKILLS_DIR_NAME);
+  return join(dirname(dirname(fileURLToPath(import.meta.url))), SKILLS_DIR_NAME);
+}
+function resolveSkillNameFromToolInput(toolInput) {
+  if (!toolInput) return void 0;
+  const indexed = toolInput;
+  for (const inputKey of SKILL_NAME_INPUT_KEYS) {
+    const value = indexed[inputKey];
+    if (typeof value !== "string" || value.trim().length === 0) continue;
+    const skillName = value.trim().split(":").pop()?.replace(/^\//, "") ?? "";
+    return SINGLE_PATH_SEGMENT.test(skillName) ? skillName : void 0;
+  }
+  return void 0;
+}
+function resolveSkillStagePaths(skillName, skillsRootDir) {
+  const skillDir = join(skillsRootDir, skillName);
+  const skillFile = join(skillDir, "SKILL.md");
+  if (!existsSync(skillFile)) return [];
+  const normalizedRoot = normalizeStagePath(skillsRootDir);
+  const staysInsideSkillsTree = (candidate) => normalizeStagePath(candidate).startsWith(`${normalizedRoot}/`);
+  const resolved = [];
+  for (const declared of parseDeclaredStages(readFileSync(skillFile, "utf-8"))) {
+    if (isAbsolute(declared)) continue;
+    const stagePath = [resolve(skillDir, declared), resolve(skillsRootDir, declared)].find(
+      (candidate) => staysInsideSkillsTree(candidate) && existsSync(candidate)
+    );
+    if (!stagePath) continue;
+    const normalized = normalizeStagePath(stagePath);
+    if (!resolved.includes(normalized)) resolved.push(normalized);
+  }
+  return resolved;
+}
+function applySkillInvocation(state, skillName, stagePaths) {
+  const merged = [...state.mandatoryStages ?? []];
+  for (const stagePath of stagePaths) if (!merged.includes(stagePath)) merged.push(stagePath);
+  if (state.lastInvokedSkillName === skillName && merged.length === (state.mandatoryStages?.length ?? 0)) {
+    return state;
+  }
+  return { ...state, lastInvokedSkillName: skillName, mandatoryStages: merged };
+}
+function applyStageRead(state, filePath) {
+  const stagePath = normalizeStagePath(filePath);
+  if ((state.stagesRead ?? []).includes(stagePath)) return state;
+  return { ...state, stagesRead: [...state.stagesRead ?? [], stagePath] };
+}
+function unreadMandatoryStages(state) {
+  const read = new Set(state.stagesRead ?? []);
+  return (state.mandatoryStages ?? []).filter((stagePath) => !read.has(stagePath));
+}
+function isStageSkipMarker(command) {
+  return STAGE_SKIP_MARKER.test(command);
+}
+function applyStageSkip(state, skipped) {
+  if (!skipped || state.stageSkipped === true) return state;
+  return { ...state, stageSkipped: true };
+}
+function stageGateDecision(state, unreadStagePaths, maxBlocks = MAX_STAGE_BLOCKS) {
+  const blockCount = state.stageBlockCount ?? 0;
+  if (state.stageSkipped === true || unreadStagePaths.length === 0) {
+    return { action: "none" /* None */, blockCount, unread: unreadStagePaths };
+  }
+  if (blockCount >= maxBlocks) {
+    return { action: "release" /* Release */, blockCount, unread: unreadStagePaths };
+  }
+  return { action: "block" /* Block */, blockCount: blockCount + 1, unread: unreadStagePaths };
+}
+
+// src/guardrails/preExecutionClassification.ts
+var CLASSIFICATION_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_CLASSIFY_SKIP\b/;
+function detectClassifiedTestCaseId(input2) {
+  if (!MUGGLE_EVENT_EMIT_TOOL.test(input2.tool_name ?? "")) return void 0;
+  if (input2.tool_input?.eventType !== PRE_EXECUTION_CLASSIFICATION_EVENT) return void 0;
+  return input2.tool_input?.testCaseId ?? ANY_TEST_CASE;
+}
+function applyClassifiedTestCase(state, testCaseId) {
+  if ((state.classifiedTestCaseIds ?? []).includes(testCaseId)) return state;
+  return { ...state, classifiedTestCaseIds: [...state.classifiedTestCaseIds ?? [], testCaseId] };
+}
+function resolveExecutionTargetTestCaseId(input2) {
+  if (!MUGGLE_EXECUTION_TOOL.test(input2.tool_name ?? "")) return void 0;
+  return input2.tool_input?.testCase?.id ?? input2.tool_input?.testScript?.testCaseId;
+}
+function isClassificationSkipMarker(command) {
+  return CLASSIFICATION_SKIP_MARKER.test(command);
+}
+function applyClassificationSkip(state, skipped) {
+  if (!skipped || state.classificationSkipped === true) return state;
+  return { ...state, classificationSkipped: true };
+}
+function classificationGateDecision(state, input2) {
+  if (state.lastInvokedSkillName !== MUGGLE_TEST_SKILL_NAME) return { deny: false };
+  if (state.classificationSkipped === true) return { deny: false };
+  const testCaseId = resolveExecutionTargetTestCaseId(input2);
+  if (!testCaseId) return { deny: false };
+  const classified = state.classifiedTestCaseIds ?? [];
+  if (classified.includes(ANY_TEST_CASE) || classified.includes(testCaseId)) return { deny: false };
+  return { deny: true, testCaseId };
+}
+
+// src/guardrails/debugPath.ts
+var DEBUG_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_DEBUG_SKIP\b/;
+var serialize = (input2) => `${JSON.stringify(input2.tool_input ?? {})}
+${JSON.stringify(input2.tool_response ?? {})}`;
+function renderedResult(toolResponse) {
+  const rendered = [];
+  const collect = (value) => {
+    if (typeof value === "string") rendered.push(value);
+    else if (Array.isArray(value)) value.forEach(collect);
+    else if (value && typeof value === "object") Object.values(value).forEach(collect);
+  };
+  collect(toolResponse);
+  return rendered.join("\n");
+}
+function detectFailedRunId(input2) {
+  if (!MUGGLE_EXECUTION_TOOL.test(input2.tool_name ?? "")) return void 0;
+  const rendered = renderedResult(input2.tool_response);
+  const status = MUGGLE_RUN_STATUS_LINE.exec(rendered)?.[1];
+  if (!status || status.toLowerCase() === MUGGLE_RUN_PASSED_STATUS) return void 0;
+  return MUGGLE_RUN_ID_LINE.exec(rendered)?.[1];
+}
+function applyFailedRun(state, runId) {
+  if ((state.failedRuns ?? []).includes(runId)) return state;
+  return { ...state, failedRuns: [...state.failedRuns ?? [], runId] };
+}
+function detectDebugEvidenceRunIds(input2, owedRunIds) {
+  const toolName = input2.tool_name ?? "";
+  const isDiagnosisEmit = MUGGLE_EVENT_EMIT_TOOL.test(toolName) && FAILURE_DIAGNOSIS_EVENT.test(input2.tool_input?.eventType ?? "");
+  if (!isDiagnosisEmit && !MUGGLE_FEEDBACK_CREATE_TOOL.test(toolName)) return [];
+  const payload = serialize(input2);
+  return owedRunIds.filter((runId) => payload.includes(runId));
+}
+function applyDebugEvidence(state, runIds) {
+  const debugged = [...state.debuggedRuns ?? []];
+  for (const runId of runIds) if (!debugged.includes(runId)) debugged.push(runId);
+  if (debugged.length === (state.debuggedRuns ?? []).length) return state;
+  return { ...state, debuggedRuns: debugged };
+}
+function isDebugSkipMarker(command) {
+  return DEBUG_SKIP_MARKER.test(command);
+}
+function applyDebugSkip(state, command) {
+  if (!isDebugSkipMarker(command)) return state;
+  const namedRuns = (state.failedRuns ?? []).filter((runId) => command.includes(runId));
+  if (namedRuns.length > 0) return applyDebugEvidence(state, namedRuns);
+  if (state.debugSkipped === true) return state;
+  return { ...state, debugSkipped: true };
+}
+function undebuggedFailedRuns(state) {
+  const debugged = new Set(state.debuggedRuns ?? []);
+  return (state.failedRuns ?? []).filter((runId) => !debugged.has(runId));
+}
+function debugGateDecision(state, maxBlocks = MAX_DEBUG_BLOCKS) {
+  const blockCount = state.debugBlockCount ?? 0;
+  const undebugged = undebuggedFailedRuns(state);
+  if (state.debugSkipped === true || undebugged.length === 0) {
+    return { action: "none" /* None */, blockCount, undebugged };
+  }
+  if (blockCount >= maxBlocks) {
+    return { action: "release" /* Release */, blockCount, undebugged };
+  }
+  return { action: "block" /* Block */, blockCount: blockCount + 1, undebugged };
+}
 
 // src/guardrails/testsGreen.ts
 var TEST_CMD = /\b(pnpm|npm|yarn)\s+(run\s+)?test\b|\b(jest|vitest|pytest)\b|\bgo\s+test\b|\bcargo\s+test\b/;
@@ -204,20 +422,12 @@ function watchGateDecision(state, untrackedPrUrls, maxBlocks = MAX_WATCH_BLOCKS)
     untracked: untrackedPrUrls
   };
 }
-
-// src/guardrails/detectBuildIntent.ts
-var BUILD = /\b(implement|build|add|create|write|fix|refactor|wire up|hook up|make (a|the|it)|change the)\b/i;
-var DEVCYCLE = /\bresolve\b[^.?!]{0,40}\bconflicts?\b|\bget\b[^.?!]{0,40}\bpr\b[^.?!]{0,40}\b(green|merged?|passing)\b/i;
-var QUESTION = /^\s*(why|what|how|when|where|who|is|are|does|do|can you (explain|tell)|explain)\b/i;
-function detectBuildIntent(prompt) {
-  const p = (prompt ?? "").trim();
-  if (!p || p.startsWith("/")) return false;
-  if (QUESTION.test(p)) return false;
-  return BUILD.test(p) || 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) => {
+var PR_PROSE_CMD = /\bgh\s+pr\s+(comment|create|edit)\b/;
+var GH_API_CMD = /\bgh\s+api\b/;
+var ISSUE_COMMENT_PATH = /\bissues\/comments\/\d+/;
+var PATCH_METHOD = /(?:--method|-X)[=\s]+PATCH\b/;
+var defaultFileReader = (path, cwd) => {
   try {
     const abs = isAbsolute(path) ? path : resolve(cwd ?? process.cwd(), path);
     if (!existsSync(abs)) return null;
@@ -226,13 +436,115 @@ var defaultReader = (path, cwd) => {
     return null;
   }
 };
-function unquote(s) {
+function unquote2(s) {
   const t = s.trim();
   if (t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'")) {
     return t.slice(1, -1);
   }
   return t;
 }
+function isCommentEditCommand(cmd) {
+  return GH_API_CMD.test(cmd) && ISSUE_COMMENT_PATH.test(cmd) && PATCH_METHOD.test(cmd);
+}
+function isPrReportPostCommand(cmd) {
+  return PR_PROSE_CMD.test(cmd) || isCommentEditCommand(cmd);
+}
+function collectPrPostText(cmd, cwd, read) {
+  let text = cmd;
+  for (const match of cmd.matchAll(/(?:--body-file|--input)[=\s]+("[^"]+"|'[^']+'|\S+)/g)) {
+    const path = unquote2(match[1]);
+    if (path && path !== "-") {
+      const contents = read(path, cwd);
+      if (contents) text += "\n" + contents;
+    }
+  }
+  for (const match of cmd.matchAll(/jq\b[^|]*?("[^"]+\.json"|'[^']+\.json'|\S+\.json)/g)) {
+    const contents = read(unquote2(match[1]), cwd);
+    if (contents) text += "\n" + contents;
+  }
+  return text;
+}
+
+// src/guardrails/walkthroughPosted.ts
+var WALKTHROUGH_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_WALKTHROUGH_SKIP\b/;
+function isWalkthroughSkipMarker(cmd) {
+  return WALKTHROUGH_SKIP_MARKER.test(cmd);
+}
+function detectWalkthroughPost(input2, read = defaultFileReader) {
+  if (input2.tool_name !== "Bash") return false;
+  const cmd = input2.tool_input?.command ?? "";
+  if (!isPrReportPostCommand(cmd)) return false;
+  return collectPrPostText(cmd, input2.cwd, read).includes(REPORT_SENTINEL);
+}
+function applyWalkthroughPosted(state, posted) {
+  if (!posted || state.walkthroughPosted === true) return state;
+  return { ...state, walkthroughPosted: true };
+}
+function applyWalkthroughSkip(state, skipped) {
+  if (!skipped || state.walkthroughSkipped === true) return state;
+  return { ...state, walkthroughSkipped: true };
+}
+function runGh(args) {
+  try {
+    return execFileSync("gh", args, {
+      encoding: "utf-8",
+      timeout: GH_LOOKUP_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return null;
+  }
+}
+var defaultPrWalkthroughLookup = {
+  branchPrUrl: () => {
+    const url = runGh(["pr", "view", "--json", "url", "-q", ".url"])?.trim();
+    return url && url.startsWith("http") ? url : null;
+  },
+  // Scans the description as well as the comments: muggle-do embeds the
+  // walkthrough in the body at PR-creation time, and a comments-only check
+  // would report that PR as owing one it already carries.
+  prCarriesWalkthrough: (prUrl) => {
+    const rendered = runGh(["pr", "view", prUrl, "--json", "body,comments"]);
+    if (rendered === null) return true;
+    return rendered.includes(REPORT_SENTINEL);
+  }
+};
+function scanForOwedWalkthroughs(state, lookup = defaultPrWalkthroughLookup) {
+  const candidates = new Set(state.prsHandled);
+  const branchPrUrl = lookup.branchPrUrl();
+  if (branchPrUrl) candidates.add(branchPrUrl);
+  const owed = [];
+  const verified = [];
+  for (const prUrl of candidates) {
+    if (lookup.prCarriesWalkthrough(prUrl)) verified.push(prUrl);
+    else owed.push(prUrl);
+  }
+  return { owed, verified };
+}
+function walkthroughGateDecision(state, owedPrUrls, maxBlocks = MAX_WALKTHROUGH_BLOCKS) {
+  const blockCount = state.walkthroughBlockCount ?? 0;
+  const alreadySettled = state.walkthroughPosted === true || state.walkthroughSkipped === true || state.e2eRun !== true;
+  if (alreadySettled || owedPrUrls.length === 0) {
+    return { action: "none" /* None */, blockCount, owed: owedPrUrls };
+  }
+  if (blockCount >= maxBlocks) {
+    return { action: "release" /* Release */, blockCount, owed: owedPrUrls };
+  }
+  return { action: "block" /* Block */, blockCount: blockCount + 1, owed: owedPrUrls };
+}
+
+// src/guardrails/detectBuildIntent.ts
+var BUILD = /\b(implement|build|add|create|write|fix|refactor|wire up|hook up|make (a|the|it)|change the)\b/i;
+var DEVCYCLE = /\bresolve\b[^.?!]{0,40}\bconflicts?\b|\bget\b[^.?!]{0,40}\bpr\b[^.?!]{0,40}\b(green|merged?|passing)\b/i;
+var QUESTION = /^\s*(why|what|how|when|where|who|is|are|does|do|can you (explain|tell)|explain)\b/i;
+function detectBuildIntent(prompt) {
+  const p = (prompt ?? "").trim();
+  if (!p || p.startsWith("/")) return false;
+  if (QUESTION.test(p)) return false;
+  return BUILD.test(p) || DEVCYCLE.test(p);
+}
+
+// src/guardrails/reportGate.ts
 function looksLikeE2EReport(text) {
   const t = text.toLowerCase();
   const statusEmojis = (text.match(/[✅❌⚠]/gu) ?? []).length;
@@ -242,26 +554,11 @@ function looksLikeE2EReport(text) {
   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) {
+function evaluateReportPost(input2, read = defaultFileReader) {
   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 (!isPrReportPostCommand(cmd)) return { deny: false };
+  const text = collectPrPostText(cmd, input2.cwd, read);
   if (text.includes(REPORT_SENTINEL)) return { deny: false };
   if (!looksLikeE2EReport(text)) return { deny: false };
   return {
@@ -358,10 +655,81 @@ function recordTests() {
     e2eRan: isE2ERun(input),
     e2eSkipped: isE2ESkipMarker(cmd)
   });
-  const next = applyWatchSkip(recorded, isWatchSkipMarker(cmd));
+  const withWatchSkip = applyWatchSkip(recorded, isWatchSkipMarker(cmd));
+  const withWalkthroughPost = applyWalkthroughPosted(withWatchSkip, detectWalkthroughPost(input));
+  const withWalkthroughSkip = applyWalkthroughSkip(withWalkthroughPost, isWalkthroughSkipMarker(cmd));
+  const failedRunId = detectFailedRunId(input);
+  const next = failedRunId ? applyFailedRun(withWalkthroughSkip, failedRunId) : withWalkthroughSkip;
+  if (next !== state) writeState(next);
+  return "{}";
+}
+function skillStages() {
+  const skillName = resolveSkillNameFromToolInput(input.tool_input);
+  if (!skillName) return "{}";
+  const state = readState(sessionId);
+  const next = applySkillInvocation(
+    state,
+    skillName,
+    resolveSkillStagePaths(skillName, resolvePluginSkillsRoot())
+  );
+  if (next !== state) writeState(next);
+  const unread = unreadMandatoryStages(next);
+  if (unread.length === 0) return "{}";
+  const ctx = `The ${skillName} skill declares required reading: ${unread.map(stageLabel).join(", ")}. Read those files now, before working through the skill's steps \u2014 they carry mandatory steps SKILL.md only links to, and treating them as optional elaboration is how those steps get silently dropped. A Stop gate holds the turn open until they are opened.`;
+  return envelope("PostToolUse", ctx, host);
+}
+function recordStageRead() {
+  const filePath = input.tool_input?.file_path;
+  if (!filePath) return "{}";
+  const state = readState(sessionId);
+  const next = applyStageRead(state, filePath);
+  if (next !== state) writeState(next);
+  return "{}";
+}
+function recordStageSignals() {
+  const cmd = input.tool_input?.command ?? "";
+  const state = readState(sessionId);
+  const withStageSkip = applyStageSkip(state, isStageSkipMarker(cmd));
+  const withClassificationSkip = applyClassificationSkip(
+    withStageSkip,
+    isClassificationSkipMarker(cmd)
+  );
+  const withDebugSkip = applyDebugSkip(withClassificationSkip, cmd);
+  const classifiedTestCaseId = detectClassifiedTestCaseId(input);
+  const withClassification = classifiedTestCaseId ? applyClassifiedTestCase(withDebugSkip, classifiedTestCaseId) : withDebugSkip;
+  const next = applyDebugEvidence(
+    withClassification,
+    detectDebugEvidenceRunIds(input, undebuggedFailedRuns(withClassification))
+  );
   if (next !== state) writeState(next);
   return "{}";
 }
+function classifyGate() {
+  const decision = classificationGateDecision(readState(sessionId), input);
+  if (!decision.deny) return "{}";
+  const reason = `Test case ${decision.testCaseId} has no pre-execution classification this session. Run muggle-test Step 6f for it first: classify replay-vs-regen per _shared/failure-mode-handling.md \xA7A, then emit one muggle-local-telemetry-event-emit with eventType "pre-execution-classification" for this test case. That step is what calls muggle-remote-test-script-list, which is the only place this run learns the test case has never passed or has failed repeatedly \u2014 cheap now, ~5 minutes of browser time to rediscover after the fact. If this execution genuinely has no classification step (a single user-picked target), say why and run \`echo "MUGGLE_CLASSIFY_SKIP: <reason>"\` \u2014 that records the skip for the rest of the session.`;
+  return denyTool(reason, host);
+}
+function stageGate() {
+  const state = readState(sessionId);
+  const decision = stageGateDecision(state, unreadMandatoryStages(state));
+  if (decision.action !== "block" /* Block */) return "{}";
+  state.stageBlockCount = decision.blockCount;
+  writeState(state);
+  const stageList = decision.unread.map(stageLabel).join(", ");
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. A skill invoked this session declares mandatory stages that were never opened: ${stageList}. Read them and carry out what they require \u2014 they are steps, not background reading, and SKILL.md only links to them. If they genuinely do not apply to this run, say why and run \`echo "MUGGLE_STAGE_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `Mandatory stages still unread (reminder ${decision.blockCount}/${MAX_STAGE_BLOCKS}): ${stageList}. Read them, or record a legitimate skip via \`echo "MUGGLE_STAGE_SKIP: <reason>"\`.`;
+  return blockStop(reason, host);
+}
+function debugPathGate() {
+  const state = readState(sessionId);
+  const decision = debugGateDecision(state);
+  if (decision.action !== "block" /* Block */) return "{}";
+  state.debugBlockCount = decision.blockCount;
+  writeState(state);
+  const runList = decision.undebugged.join(", ");
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. These runs failed and never went through the debug path: ${runList}. muggle-test Step 7C makes that mandatory \u2014 route each through _shared/debug-failed-run.md: gather the attempted steps and the failing screenshot, diagnose the bucket per _shared/failure-mode-handling.md \xA7B/\xA7C with its classified telemetry emit, and present the offer in which "give feedback & rerun" is always available. A summarized-and-dropped failure is the run a reviewer most needs to see. If a run genuinely cannot be debugged, run \`echo "MUGGLE_DEBUG_SKIP: <runId> <reason>"\` \u2014 that clears just that run.` : `Failed runs still owe the debug path (reminder ${decision.blockCount}/${MAX_DEBUG_BLOCKS}): ${runList}. Route each through _shared/debug-failed-run.md, or record a legitimate skip via \`echo "MUGGLE_DEBUG_SKIP: <runId> <reason>"\`.`;
+  return blockStop(reason, host);
+}
 function e2eGate() {
   const state = readState(sessionId);
   const decision = e2eGateDecision(state);
@@ -384,6 +752,24 @@ 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 walkthroughGate() {
+  const state = readState(sessionId);
+  if (state.e2eRun !== true || state.walkthroughPosted === true || state.walkthroughSkipped === true) {
+    return "{}";
+  }
+  const scan = scanForOwedWalkthroughs(state);
+  if (scan.owed.length === 0) {
+    if (scan.verified.length > 0) writeState({ ...state, walkthroughPosted: true });
+    return "{}";
+  }
+  const decision = walkthroughGateDecision(state, scan.owed);
+  if (decision.action !== "block" /* Block */) return "{}";
+  state.walkthroughBlockCount = decision.blockCount;
+  writeState(state);
+  const prList = decision.owed.join(", ");
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. An E2E acceptance run happened this session but no visual walkthrough has reached ${prList}. Per the postPRVisualWalkthrough preference (default: always), post it now via /muggle:muggle-pr-visual-walkthrough \u2014 include the failed runs, which are the ones reviewers most need to see. If this result genuinely should not be posted (postPRVisualWalkthrough=never, someone else's PR, nothing renderable), tell the user why and run \`echo "MUGGLE_WALKTHROUGH_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `Walkthrough still owed for ${prList} (reminder ${decision.blockCount}/${MAX_WALKTHROUGH_BLOCKS}): post via /muggle:muggle-pr-visual-walkthrough, or record a legitimate skip via \`echo "MUGGLE_WALKTHROUGH_SKIP: <reason>"\`.`;
+  return blockStop(reason, host);
+}
 function reportGate() {
   const reportPostVerdict = evaluateReportPost(input);
   if (!reportPostVerdict.deny || !reportPostVerdict.reason) return "{}";
@@ -406,7 +792,14 @@ var handlers = {
   "e2e-gate": e2eGate,
   "terminal-gate": terminalGate,
   "watch-gate": watchGate,
+  "walkthrough-gate": walkthroughGate,
   "report-gate": reportGate,
-  "build-router": buildRouter
+  "build-router": buildRouter,
+  "skill-stages": skillStages,
+  "record-stage-read": recordStageRead,
+  "record-stage-signals": recordStageSignals,
+  "classify-gate": classifyGate,
+  "stage-gate": stageGate,
+  "debug-path-gate": debugPathGate
 };
 process.stdout.write((handlers[sub] ?? (() => "{}"))());

package/dist/plugin/scripts/pr-watch-events.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+
+# Wake conditions for the muggle-pr-followup watch loop — the single definition
+# of what makes a quiet watcher speak. Sourced by pr-watch-loop.sh.
+#
+# These live in a file, rather than in the prose an arming session reads, because
+# a re-derived loop silently loses conditions. Observed across four slots on one
+# machine: two implemented the behind-base wake and two did not, and the two that
+# did not left their PRs permanently unmergeable under a watcher that looked
+# healthy — alive, heartbeating, no fetch errors, and nothing to say. A dropped
+# wake has no failure mode that anyone notices.
+#
+# Every function is pure: arguments in, one event line on stdout, no I/O and no
+# provider calls. That keeps each condition directly testable, which is the
+# property prose never had. Exit 0 means "woke and emitted", 1 means "stay quiet".
+# Each caller owns its own floor and advances it only on a real wake, so one
+# occurrence fires exactly once.
+
+# Splits the tab-separated state line into its fields, one per line, preserving
+# empty ones. Not a wake, but every wake below reads its arguments out of this.
+#
+# `IFS=$'\t' read` cannot do it: tab is an IFS *whitespace* character, so bash
+# collapses runs of tabs into a single delimiter, and the two adjacent tabs an
+# empty field produces silently shift every later field left. With no unresolved
+# thread — the common case, and also what a push leaves behind once its thread
+# goes outdated — the thread field is empty, so the pending-check count lands in
+# unresolved_threads and fires a thread wake for a PR with no threads, while the
+# check digest lands in failed_checks and leaves red-CI detection reading a
+# string where it expects a count. awk with an explicit FS does not collapse.
+watch_split_state() {
+    printf '%s\n' "$1" | awk -F'\t' '{for (i = 1; i <= NF; i++) print $i}'
+}
+
+# A submitted review newer than the floor. Monotonic ids, so `>` is the whole
+# test. PENDING (unsubmitted) reviews are excluded by the caller's query — they
+# are the reviewer's own drafts and are not feedback until submitted.
+watch_wake_review() {
+    local pr="$1" latest="$2" floor="$3"
+    [ "${latest:-0}" -gt "${floor:-0}" ] 2>/dev/null || return 1
+    echo "EVENT pr=$pr new submitted review id=$latest"
+}
+
+# A thread comment newer than the floor. Same monotonic-id reasoning as reviews.
+watch_wake_comment() {
+    local pr="$1" latest="$2" floor="$3"
+    [ "${latest:-0}" -gt "${floor:-0}" ] 2>/dev/null || return 1
+    echo "EVENT pr=$pr new thread comment id=$latest"
+}
+
+# A thread that is unresolved and not already known to be. `known` is the
+# semicolon-joined THREADS floor; membership is the test, not ordering, because
+# thread ids are opaque strings rather than a monotonic sequence.
+watch_wake_thread() {
+    local pr="$1" thread_id="$2" known="$3"
+    [ -n "$thread_id" ] || return 1
+    case ";${known};" in
+        *";${thread_id};"*) return 1 ;;
+    esac
+    echo "EVENT pr=$pr thread newly unresolved id=$thread_id"
+}
+
+# The head's checks having **settled** red: nothing still pending and at least
+# one failure. Pending-with-a-failure is not a wake — a run in flight may still
+# go green, and the tick would idle on it anyway.
+#
+# The floor is the head SHA rather than a monotonic id because a check rollup is
+# not monotonic: it flips green to red and resets on every push. Keying on the
+# red head fires once per red head and re-arms on the next push.
+watch_wake_ci_red() {
+    local pr="$1" pending_count="$2" failed_count="$3" head_sha="$4" floor="$5"
+    [ -n "$head_sha" ] || return 1
+    [ "$head_sha" != "$floor" ] || return 1
+    [ "${pending_count:-0}" -eq 0 ] 2>/dev/null || return 1
+    [ "${failed_count:-0}" -gt 0 ] 2>/dev/null || return 1
+    echo "EVENT pr=$pr checks settled red head=$head_sha"
+}
+
+# The branch needing a rebase onto its base — conflicting with it, or merely
+# behind it.
+#
+# Behind is the half that regenerated loops kept dropping, and it is invisible
+# from the signals a conflict check uses: a behind-but-clean branch reports
+# mergeable=MERGEABLE, exactly like a current one. `mergeStateStatus` cannot
+# stand in either — it is one enum with precedence, and BLOCKED (review
+# required) masks BEHIND on any PR still awaiting approval, which is most of
+# them. Behind-ness has to be measured, so the caller passes `behind_count` from
+# a compare call.
+#
+# The floor is the rebase key `<head_sha>..<base_tip_sha>`, pairing both sides:
+# staleness is a function of the pair, so a head-only key would wedge
+# permanently the first time the base advanced (nothing can move the head while
+# the branch sits blocked). Pairing re-arms whenever either side moves.
+watch_wake_rebase() {
+    local pr="$1" mergeable="$2" behind_count="$3" rebase_key="$4" floor="$5"
+    [ -n "$rebase_key" ] || return 1
+    [ "$rebase_key" != "$floor" ] || return 1
+    if [ "$mergeable" = "CONFLICTING" ]; then
+        echo "EVENT pr=$pr branch conflicting with base key=$rebase_key"
+        return 0
+    fi
+    [ -n "$behind_count" ] && [ "$behind_count" -gt 0 ] 2>/dev/null || return 1
+    echo "EVENT pr=$pr branch behind base by $behind_count — rebase due key=$rebase_key"
+}
+
+# A blocked watch whose CI signature moved at all. This is a resume probe, not a
+# failure probe: it is dormant unless `blocked_digest` is set, and it wakes on
+# any move away from that value rather than only on red, so a block waiting on a
+# green pass, a rerun, or an external deploy check resumes as promptly as one
+# waiting on a failure.
+watch_wake_blocked_resume() {
+    local pr="$1" digest="$2" blocked_digest="$3"
+    [ -n "$blocked_digest" ] || return 1
+    [ -n "$digest" ] || return 1
+    [ "$digest" != "$blocked_digest" ] || return 1
+    echo "EVENT pr=$pr ci digest moved while blocked — resume check"
+}