@muggleai/works 4.11.3 → 4.12.0

package/dist/{chunk-7WRAMBOS.js → chunk-2DVZ2LYO.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-AYWLYB3F.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-I4VLYJ7M.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { v4 } from 'uuid';
@@ -329,6 +329,11 @@ async function startStdioServer(server) {
   };
   process.on("SIGTERM", () => shutdown("SIGTERM"));
   process.on("SIGINT", () => shutdown("SIGINT"));
+  watchForParentDeath(shutdown);
+}
+function watchForParentDeath(shutdown) {
+  process.stdin.on("end", () => shutdown("stdin-end"));
+  process.stdin.on("close", () => shutdown("stdin-close"));
 }
 
 // src/cli/pr-section/render.ts
@@ -731,7 +736,7 @@ async function resolveGsScreenshotUrls(report, opts) {
     if (gsUrls.length === 0) {
       return report;
     }
-    const mcps = await import('./src-NJUUHKPW.js');
+    const mcps = await import('./src-ARTTHWNP.js');
     const credentials = await mcps.getCallerCredentialsAsync();
     if (!credentials.bearerToken && !credentials.apiKey) {
       stderrWrite(

package/dist/{chunk-AYWLYB3F.js → chunk-I4VLYJ7M.js}

@@ -1985,6 +1985,51 @@ function getRunResultStorageService() {
 function resetRunResultStorageService() {
   instance = null;
 }
+
+// packages/mcps/src/mcp/local/services/replay-url-rewrite.ts
+function rewriteActionScriptUrls(params) {
+  const { actionScript, originalUrl, localUrl } = params;
+  if (!originalUrl) {
+    return actionScript;
+  }
+  let originalHost;
+  let localOrigin;
+  try {
+    originalHost = new URL(originalUrl).hostname;
+    localOrigin = new URL(localUrl).origin;
+  } catch {
+    const serialized2 = JSON.stringify(actionScript);
+    const rewritten2 = serialized2.replace(new RegExp(escapeRegex(originalUrl), "g"), localUrl);
+    return JSON.parse(rewritten2);
+  }
+  const hostPattern = new RegExp(
+    `https?://(?:[a-z0-9-]+\\.)*${escapeRegex(originalHost)}(?=[/?#:"'\\\\]|$)`,
+    "gi"
+  );
+  const serialized = JSON.stringify(actionScript);
+  const rewritten = serialized.replace(hostPattern, localOrigin);
+  const result = JSON.parse(rewritten);
+  forceFirstNavigateUrl({ steps: result, localUrl });
+  return result;
+}
+function forceFirstNavigateUrl(params) {
+  for (const step of params.steps) {
+    if (!isPlainObject(step)) continue;
+    const operation = step["operation"];
+    if (!isPlainObject(operation)) continue;
+    if (operation["action"] !== "navigate") continue;
+    operation["url"] = params.localUrl;
+    return;
+  }
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// packages/mcps/src/mcp/local/services/execution-service.ts
 var logger4 = getLogger();
 var activeProcesses = /* @__PURE__ */ new Map();
 function getAuthenticatedUserId() {
@@ -2606,18 +2651,6 @@ ${executionResult.stderr}`;
     };
   }
 }
-function rewriteActionScriptUrls(params) {
-  const { actionScript, originalUrl, localUrl } = params;
-  if (!originalUrl) {
-    return actionScript;
-  }
-  const serialized = JSON.stringify(actionScript);
-  const rewritten = serialized.replace(new RegExp(escapeRegex(originalUrl), "g"), localUrl);
-  return JSON.parse(rewritten);
-}
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function cancelExecution(params) {
   const process2 = activeProcesses.get(params.runId);
   if (!process2) {

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-7WRAMBOS.js';
-import './chunk-AYWLYB3F.js';
+import { runCli } from './chunk-2DVZ2LYO.js';
+import './chunk-I4VLYJ7M.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-7WRAMBOS.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-AYWLYB3F.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-2DVZ2LYO.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-I4VLYJ7M.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": "4.11.3",
+  "version": "4.12.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": "4.11.3",
+  "version": "4.12.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/scripts/ensure-electron-app.sh

@@ -3,10 +3,35 @@
 set -euo pipefail
 
 # Ensure the Electron browser test runner is installed/up to date (silent, best-effort).
-if command -v muggle >/dev/null 2>&1; then
-  muggle setup >/dev/null 2>&1 || true
-else
-  npx -y @muggleai/works setup >/dev/null 2>&1 || true
+#
+# Bounded + cached: this script runs from a SessionStart hook on every Claude
+# session, so a hung `muggle setup` (e.g. one blocked by host security policy
+# on Windows) must not leak a ~100 MB orphan per session start. We cap the
+# attempt with `timeout` and skip the call entirely if we already checked
+# within the last day.
+ensure_marker_dir="${HOME}/.cache/muggle"
+ensure_marker="${ensure_marker_dir}/electron-app-checked"
+ensure_ttl=$((24 * 60 * 60))
+
+ensure_now=$(date +%s)
+ensure_last=0
+if [ -f "${ensure_marker}" ]; then
+    ensure_last=$(stat -f %m "${ensure_marker}" 2>/dev/null || stat -c %Y "${ensure_marker}" 2>/dev/null || echo 0)
+fi
+
+if [ $((ensure_now - ensure_last)) -ge "${ensure_ttl}" ]; then
+    if command -v timeout >/dev/null 2>&1; then
+        ensure_timeout="timeout -k 5 60"
+    else
+        ensure_timeout=""
+    fi
+    if command -v muggle >/dev/null 2>&1; then
+        ${ensure_timeout} muggle setup >/dev/null 2>&1 || true
+    else
+        ${ensure_timeout} npx -y @muggleai/works setup >/dev/null 2>&1 || true
+    fi
+    mkdir -p "${ensure_marker_dir}" 2>/dev/null || true
+    touch "${ensure_marker}" 2>/dev/null || true
 fi
 
 # --- Context injection ---

package/dist/plugin/skills/_shared/github-cli-recipes/line-comments-for-review.md

@@ -0,0 +1,8 @@
+# Line comments for a specific review
+
+For per-comment reply routing in `/muggle-do`.
+
+```bash
+gh api repos/<owner>/<repo>/pulls/<n>/comments --paginate \
+  --jq '[.[] | select(.pull_request_review_id == <review-id>)]'
+```

package/dist/plugin/skills/_shared/github-cli-recipes/loop-user-identity.md

@@ -0,0 +1,9 @@
+# Identify the loop user
+
+The GitHub identity that owns the authenticated `gh` token. Resolve-reminder thread classification and reply attribution need this.
+
+```bash
+gh api user --jq '.login'
+```
+
+Cache in `state.md` under `Loop user:`; re-resolve only when missing.

package/dist/plugin/skills/_shared/github-cli-recipes/pr-edit.md

@@ -0,0 +1,8 @@
+# Refresh the PR title or body
+
+For `open-prs/update.md` when E2E state flips (passing↔failing) or validation strategy changes.
+
+```bash
+gh pr edit <pr-number> --repo <owner>/<repo> --title "<new-title>"
+gh pr edit <pr-number> --repo <owner>/<repo> --body-file <file>
+```

package/dist/plugin/skills/_shared/github-cli-recipes/pr-metadata.md

@@ -0,0 +1,12 @@
+# PR metadata snapshot
+
+Fetch the fields the watcher and bootstrap need in one call.
+
+```bash
+gh pr view <pr-number> --repo <owner>/<repo> \
+  --json url,number,headRefOid,headRefName,baseRefName,state,mergedAt,closedAt,body,title,author
+```
+
+- `state` is one of `OPEN`, `MERGED`, `CLOSED`.
+- `headRefOid` is the current head SHA — store as `head_sha` in `prs.json`.
+- `headRefName` is the branch — must match the working tree's branch in bootstrap.

package/dist/plugin/skills/_shared/github-cli-recipes/push-to-branch.md

@@ -0,0 +1,10 @@
+# Push to the PR branch
+
+After the address-reviews cycle's work.
+
+```bash
+git -C <repo-path> push origin <head-ref-name>
+git -C <repo-path> rev-parse HEAD
+```
+
+Append the new SHA to `last_seen.pushed_shas[]` so resolve-reminder can recognize it.

package/dist/plugin/skills/_shared/github-cli-recipes/reply-line-comment.md

@@ -0,0 +1,10 @@
+# Reply to a line comment (threaded)
+
+Used by `/muggle-do` per-comment inline replies.
+
+```bash
+gh api --method POST \
+  -H "Accept: application/vnd.github+json" \
+  repos/<owner>/<repo>/pulls/<n>/comments/<comment-id>/replies \
+  -f body="<reply-text>"
+```

package/dist/plugin/skills/_shared/github-cli-recipes/submitted-reviews.md

@@ -0,0 +1,15 @@
+# Submitted reviews past a cursor
+
+For the watcher's poll and the address-reviews fetch.
+
+```bash
+gh api repos/<owner>/<repo>/pulls/<n>/reviews --paginate
+```
+
+Filter client-side:
+
+- `submitted_at != null` (skip PENDING drafts)
+- `id > last_seen.reviewId`
+- `id` not in `last_seen.escalated_review_ids`
+- `user.login` in the resolved allow-list
+- `state` in `{CHANGES_REQUESTED, COMMENTED}`, OR `APPROVED` with a non-empty body or at least one line comment

package/dist/plugin/skills/_shared/github-cli-recipes/top-level-comment.md

@@ -0,0 +1,7 @@
+# Top-level PR comment
+
+For the resolve-reminder stage and any non-threaded notice.
+
+```bash
+gh pr comment <pr-number> --repo <owner>/<repo> --body "<text>"
+```

package/dist/plugin/skills/_shared/github-cli-recipes/unresolved-threads.md

@@ -0,0 +1,33 @@
+# Unresolved comment threads
+
+For the resolve-reminder stage. GraphQL only — REST does not expose `isResolved`.
+
+```bash
+gh api graphql -F owner=<owner> -F name=<repo> -F number=<n> -f query='
+query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: 100) {
+        nodes {
+          id
+          isResolved
+          comments(first: 100) {
+            nodes {
+              databaseId
+              author { login }
+              body
+              createdAt
+            }
+          }
+        }
+      }
+    }
+  }
+}'
+```
+
+Filter client-side to `isResolved == false`. Classify each thread by inspecting its comments:
+
+- **Addressed by loop** — at least one comment authored by the loop user citing a SHA in `last_seen.pushed_shas[]`.
+- **Addressed by human** — at least one comment authored by a non-loop user after the original, and no addressed-by-loop signal.
+- **Not addressed** — otherwise.

package/dist/plugin/skills/_shared/github-cli-recipes/verify-working-tree.md

@@ -0,0 +1,17 @@
+# Verify the working tree matches the PR
+
+Bootstrap's environment check.
+
+```bash
+git rev-parse --show-toplevel        # cwd is a git working tree
+git remote get-url origin            # remote matches <owner>/<repo>
+git rev-parse --abbrev-ref HEAD      # current branch matches PR's headRefName
+```
+
+Accept any remote URL form for `<owner>/<repo>` (with or without trailing `.git`):
+
+- `https://github.com/<owner>/<repo>`
+- `git@github.com:<owner>/<repo>`
+- `ssh://git@github.com/<owner>/<repo>`
+
+Any mismatch → bootstrap aborts using the wrong-checkout template in [`../../muggle-pr-followup/output-templates/bootstrap.md`](../../muggle-pr-followup/output-templates/bootstrap.md).

package/dist/plugin/skills/_shared/github-cli-recipes.md

@@ -0,0 +1,20 @@
+# GitHub CLI Recipes
+
+Reusable `gh` / `git` snippets used by `muggle-pr-followup` (watcher + bootstrap) and `/muggle-do` (address-reviews + open-prs). Each recipe is one file — load only what you need.
+
+Skills assume a working `gh auth status`. Auth errors surface verbatim from `gh`.
+
+## Index
+
+| Recipe | Use case |
+| :----- | :------- |
+| [`pr-metadata`](github-cli-recipes/pr-metadata.md) | Snapshot PR state, head SHA, branch — watcher + bootstrap. |
+| [`submitted-reviews`](github-cli-recipes/submitted-reviews.md) | Fetch reviews past a cursor — watcher's poll. |
+| [`line-comments-for-review`](github-cli-recipes/line-comments-for-review.md) | Pull a review's line comments — `/muggle-do` per-comment routing. |
+| [`unresolved-threads`](github-cli-recipes/unresolved-threads.md) | GraphQL fetch of unresolved comment threads — resolve-reminder. |
+| [`reply-line-comment`](github-cli-recipes/reply-line-comment.md) | POST a threaded reply on a line comment. |
+| [`top-level-comment`](github-cli-recipes/top-level-comment.md) | POST a top-level PR comment — resolve-reminder + overflow. |
+| [`push-to-branch`](github-cli-recipes/push-to-branch.md) | Push + capture new SHA after address-reviews work. |
+| [`verify-working-tree`](github-cli-recipes/verify-working-tree.md) | Three checks bootstrap runs before seeding state. |
+| [`pr-edit`](github-cli-recipes/pr-edit.md) | Refresh title or body when address-reviews mode flips state. |
+| [`loop-user-identity`](github-cli-recipes/loop-user-identity.md) | Resolve the GitHub login of the loop user. |

package/dist/plugin/skills/_shared/pr-followup-helpers/allow-list.md

@@ -0,0 +1,53 @@
+# Reviewer allow-list
+
+The address-reviews flow only acts on reviews submitted by users in the **allow-list** = (requested reviewers ∪ CODEOWNERS) − bots − PR author. Re-resolve every invocation — never cache across cycles.
+
+## Step 1: requested reviewers
+
+```bash
+gh pr view <number> --repo <owner>/<repo> --json reviewRequests,author
+```
+
+`reviewRequests` is an array of `{ login? , slug? }`. User reviewers have `login`; team reviewers have `slug` (and `name`). Expand teams to member logins:
+
+```bash
+gh api orgs/<org>/teams/<slug>/members --jq '.[].login'
+```
+
+Record `prAuthor = author.login` for the exclusion step.
+
+## Step 2: CODEOWNERS
+
+Look for the file in this order — first hit wins:
+
+1. `.github/CODEOWNERS`
+2. `CODEOWNERS`
+3. `docs/CODEOWNERS`
+
+Read from the PR's **head branch** (not master) — a PR that adds CODEOWNERS should be informational while open, load-bearing once merged:
+
+```bash
+gh api repos/<owner>/<repo>/contents/.github/CODEOWNERS?ref=<head_sha> --jq '.content' | base64 -d
+```
+
+Parse line-by-line:
+
+- Skip blank lines and lines starting with `#`.
+- Each line is `<pattern> <owner1> <owner2> ...`.
+- Owners are either `@user` or `@org/team`. Strip the leading `@`.
+- Collect the union of all owners across all lines (don't match patterns against changed files — repo-level membership is enough).
+
+Expand `@org/team` to member logins via the orgs/teams/members endpoint.
+
+If no CODEOWNERS file exists in any location, the CODEOWNERS contribution is empty. Don't fail.
+
+## Step 3: filter
+
+Allow-list = (requested reviewers ∪ CODEOWNERS) − `{prAuthor}` − bot logins.
+
+Bot logins:
+
+- Ends with `[bot]` (e.g. `dependabot[bot]`)
+- Exact match: `dependabot`, `github-actions`, `renovate`, `mergify`
+
+A comment author not in the allow-list is silently ignored — do not reply, do not address.

package/dist/plugin/skills/_shared/pr-followup-helpers/classify.md

@@ -0,0 +1,48 @@
+# Classify
+
+Classify the **review as a unit** — but reply per line comment (threaded), not per review.
+
+| Class | Signal | Action |
+| :---- | :----- | :----- |
+| **actionable** | Review names at least one concrete change or asks an answerable question. Soft phrasing counts when there's a concrete referent. | Treat as amended requirements; run **one** implementation cycle for the whole review; reply **threaded per line comment** referencing the new SHA (top-level only when the review is body-only). |
+| **ambiguous** | No actionable signal — pure vibes, contradictory, or depends on knowledge the loop can't access. | Escalate once with two interpretations; pause the PR. |
+
+Default to **actionable**. CI catches wrong attempts; reviewers correct on the next round. Escalation is a round-trip with an absent user — reserve it.
+
+Reply shape (all replies for one review reference the same SHA):
+
+- **threaded** (default): `Done in <sha> — <attribution>. (Review #<review_id>, cycle <status>.)`
+- **top-level** (fallback, body-only reviews): `Re: review #<review_id> — addressed in <sha>, cycle <status>.`
+- **ambiguous**: no bot reply.
+
+## Worked examples — Actionable
+
+| Review (summarized) | Why actionable |
+| :------------------ | :------------- |
+| 3 comments: "rename `fooBar` to `foo_bar`", "use `const` here", "fix this typo" | Three concrete edits |
+| 1 comment: "could the procedure be simpler?" | Soft-phrased but the intent is clear — simplify |
+| Review body: "Two things: extract validation into a helper, add a null check before the lookup." + 0 line comments | Two concrete directives in the body |
+| 4 comments: "why this approach?", "is this called from X?", "does this need to handle empty array?", "what's the perf here?" | All questions, each answerable |
+| 1 comment: "rewrite this module — the architecture doesn't match the spec" | Substantive rebuild, but direction is clear |
+| 1 comment: "I'd lean toward the bar.ts pattern" | Concrete referent (bar.ts) — apply that pattern |
+
+## Worked examples — Ambiguous
+
+| Review (summarized) | Why ambiguous |
+| :------------------ | :------------ |
+| 1 comment: "👀" / "hmm" / ":thinking:" | No signal at all |
+| 1 comment: "this is wrong" with no target or direction | Asserts a problem but doesn't propose a fix |
+| 2 comments: "use X" + "but actually don't use X" | Self-contradicting |
+| 1 comment: "we discussed this offline — please address" | References context the loop doesn't have |
+| 1 comment: "won't this break the prod migration we did last week?" | Implicit change request gated on knowledge the loop can't access |
+| Mixed: 2 concrete directives + 1 "rethink the whole approach" | The "rethink" subverts the others; escalate to confirm scope |
+
+Escalate per the caller's procedure (add the review id to the cursor's escalated set, emit one terminal message, pause the PR).
+
+## Borderline rule
+
+If you can paraphrase the review's intent as **"do X"** (X concrete) → actionable. Pick the best interpretation; dispatch.
+
+If you can only paraphrase as **"the reviewer is dissatisfied but I can't tell with what"** → ambiguous.
+
+Mixed ("3 concrete + 1 dissatisfaction") usually splits: action the concrete; ask about the dissatisfaction in the reply summary. Pure ambiguity means *nothing* in the review is actionable.

package/dist/plugin/skills/_shared/pr-followup-helpers/reply-routing.md

@@ -0,0 +1,40 @@
+# Reply routing
+
+GitHub's PR APIs are not uniform across comment types. Route by parent type.
+
+## Line-level review comment (most common)
+
+A comment attached to a specific file:line that belongs to a review thread.
+
+```bash
+gh api \
+  --method POST \
+  -H "Accept: application/vnd.github+json" \
+  /repos/<owner>/<repo>/pulls/<number>/comments/<comment_id>/replies \
+  -f body="Done in $(git rev-parse --short HEAD) — renamed \`fooBar\` to \`foo_bar\`."
+```
+
+The reply lands in the same review thread with `in_reply_to_id = <comment_id>`.
+
+## Review body (CHANGES_REQUESTED with no inline comments)
+
+A reviewer left a summary review with `state: CHANGES_REQUESTED` and a body, but **no** inline comments. GitHub has no "reply to review body" endpoint — post a top-level PR comment that references the review:
+
+```bash
+gh pr comment <number> --repo <owner>/<repo> --body "Re: review #<review_id> — done in $(git rev-parse --short HEAD)."
+```
+
+## Failing CI check
+
+No reply. The fix commit IS the response. Include the failing check name in the commit subject:
+
+```
+fix(ci): typecheck — narrow type of foo
+fix(ci): lint — remove unused import
+```
+
+## Never
+
+- Never post a top-level comment in reply to a line-level comment. It loses thread context.
+- Never `gh pr review --comment` for replies — that endpoint is for *new* reviews.
+- Never reply twice to the same comment. The cursor in `last_seen.json` is the only re-entry guard; advance it after every reply.

package/dist/plugin/skills/_shared/pr-followup-helpers.md

@@ -1,151 +1,13 @@
 # PR follow-up helpers
 
-Generic operational guidance for running a PR-comment follow-up loop on GitHub: reviewer allow-list resolution, reply routing across the different comment endpoints, and a classification rule for reviewer comments with worked examples and a borderline test. Caller-agnostic — any loop that picks one comment per tick and decides what to do with it can drive off this doc.
+Generic operational guidance for PR-review follow-up. Caller-agnostic — the watcher fetches reviews, the caller (today: `/muggle-do` in address-reviews mode) reads these files to classify and decide what to do.
 
-The classification produces an **action shape** (in-place change, deep-cycle through the caller's implementation pipeline, reply only, escalate, etc.) — the caller maps each shape to its specific routing (which stage to dispatch, which terminal-message template to use, which reply endpoint to hit).
+Each section is its own file — load only what the current step needs.
 
-## Resolving the reviewer allow-list
+## Index
 
-Stage 8 only acts on comments authored by users in the **allow-list** = (requested reviewers ∪ CODEOWNERS) − bots − PR author. Re-resolve every tick (decision 9 in the design doc).
-
-### Step 1: requested reviewers
-
-```bash
-gh pr view <number> --repo <owner>/<repo> --json reviewRequests,author
-```
-
-`reviewRequests` is an array of `{ login? , slug? }`. User reviewers have `login`; team reviewers have `slug` (and `name`). Expand teams to member logins:
-
-```bash
-gh api orgs/<org>/teams/<slug>/members --jq '.[].login'
-```
-
-Record `prAuthor = author.login` for the exclusion step.
-
-### Step 2: CODEOWNERS
-
-Look for the file in this order — first hit wins:
-
-1. `.github/CODEOWNERS`
-2. `CODEOWNERS`
-3. `docs/CODEOWNERS`
-
-Read from the PR's **head branch** (not master), because a PR that adds CODEOWNERS should be allowed to take effect once merged but is informational while open. In practice this means:
-
-```bash
-gh api repos/<owner>/<repo>/contents/.github/CODEOWNERS?ref=<head_sha> --jq '.content' | base64 -d
-```
-
-Parse line-by-line:
-
-- Skip blank lines and lines starting with `#`.
-- Each line is `<pattern> <owner1> <owner2> ...`.
-- Owners are either `@user` or `@org/team`. Strip the leading `@`.
-- For our purposes we don't need to match `<pattern>` against changed files — CODEOWNERS membership for the *repo* is enough. Collect the union of all owners across all lines.
-
-Expand `@org/team` to member logins via the orgs/teams/members endpoint (same as Step 1).
-
-If no CODEOWNERS file exists in any of the three locations, the CODEOWNERS contribution is empty. Don't fail.
-
-### Step 3: filter
-
-Allow-list = (requested reviewers ∪ CODEOWNERS) − `{prAuthor}` − bot logins.
-
-Bot logins are any login matching:
-
-- Ends with `[bot]` (e.g. `dependabot[bot]`)
-- Exact match in the standard list: `dependabot`, `github-actions`, `renovate`, `mergify`
-
-A comment author not in the allow-list is silently ignored — do not reply, do not address.
-
-## Reply routing
-
-GitHub's PR APIs are not uniform across comment types. Route by parent type.
-
-### Line-level review comment
-
-A comment attached to a specific file:line that belongs to a review thread. This is the **most common** path.
-
-```bash
-gh api \
-  --method POST \
-  -H "Accept: application/vnd.github+json" \
-  /repos/<owner>/<repo>/pulls/<number>/comments/<comment_id>/replies \
-  -f body="Done in $(git rev-parse --short HEAD) — renamed \`fooBar\` to \`foo_bar\`."
-```
-
-The reply lands in the same review thread. The reply itself becomes a new line-level comment with `in_reply_to_id = <comment_id>`.
-
-### Review body (CHANGES_REQUESTED with no inline comments)
-
-A reviewer left a summary review with `state: CHANGES_REQUESTED` and a body, but **no** inline comments. GitHub has no "reply to review body" endpoint — post a top-level PR comment that references the review:
-
-```bash
-gh pr comment <number> --repo <owner>/<repo> --body "Re: review #<review_id> — done in $(git rev-parse --short HEAD)."
-```
-
-### Failing CI check
-
-No reply. The fix commit IS the response. Include the failing check name in the commit subject so the connection is obvious in `git log`:
-
-```
-fix(ci): typecheck — narrow type of foo
-fix(ci): lint — remove unused import
-```
-
-### Never
-
-- Never post a top-level comment in reply to a line-level comment. It loses thread context and pollutes the PR conversation tab.
-- Never `gh pr review --comment` for replies — that endpoint is for *new* reviews, not replies.
-- Never reply twice to the same comment. The cursor in `last_seen.json` is the only re-entry guard; advance it after every reply.
-
-## Classify
-
-Classify the **review as a unit** — but reply per line comment (threaded), not per review.
-
-| Class | Signal | Action |
-| :---- | :----- | :----- |
-| **actionable** | Review names at least one concrete change or asks an answerable question. Soft phrasing counts when there's a concrete referent. | Treat as amended requirements; run **one** implementation cycle for the whole review; reply **threaded per line comment** referencing the new SHA (top-level only when the review is body-only). |
-| **ambiguous** | No actionable signal — pure vibes, contradictory, or depends on knowledge the loop can't access. | Escalate once with two interpretations; pause the PR. |
-
-Default to **actionable**. CI catches wrong attempts; reviewers correct on the next round. Escalation is a round-trip with an absent user — reserve it.
-
-Reply shape (all replies for one review reference the same SHA):
-
-- **threaded** (default): `Done in <sha> — <attribution>. (Review #<review_id>, cycle <status>.)`
-- **top-level** (fallback, body-only reviews): `Re: review #<review_id> — addressed in <sha>, cycle <status>.`
-- **ambiguous**: no bot reply.
-
-### Worked examples — Actionable reviews
-
-| Review (summarized) | Why actionable |
-| :------------------ | :------------- |
-| 3 comments: "rename `fooBar` to `foo_bar`", "use `const` here", "fix this typo" | Three concrete edits |
-| 1 comment: "could the procedure be simpler?" | Soft-phrased but the intent is clear — simplify; pick the best interpretation, run the cycle, reply with what was changed |
-| Review body: "Mostly looks good. Two things: extract the validation into a helper, and add a null check before the lookup." Plus 0 line comments. | Two concrete directives in the body |
-| 4 comments: "why this approach?", "is this called from X?", "does this need to handle empty array?", "what's the perf here?" | All questions but each is answerable; cycle dispatches an "answer + maybe-fix" pass and the reply summary captures each answer |
-| 1 comment: "rewrite this module — the architecture doesn't match the spec" | Substantive rebuild, but the direction is clear: redo the module per the spec |
-| 1 comment: "I'd lean toward the bar.ts pattern" | Concrete referent (bar.ts) — apply that pattern |
-
-The single review goes through one full cycle regardless of comment count.
-
-### Worked examples — Ambiguous reviews
-
-| Review (summarized) | Why ambiguous |
-| :------------------ | :------------ |
-| 1 comment: "👀" / "hmm" / ":thinking:" | No signal at all |
-| 1 comment: "this is wrong" with no target or direction | Asserts a problem but doesn't propose a fix |
-| 2 comments: "use X" + "but actually don't use X" | Self-contradicting — can't reconcile without the reviewer |
-| 1 comment: "we discussed this offline — please address" | References context the loop doesn't have |
-| 1 comment: "won't this break the prod migration we did last week?" | Implicit change request gated on knowledge the loop can't access |
-| Mixed: 2 concrete directives + 1 comment "but also, rethink the whole approach" | The "rethink the whole approach" subverts the other two; escalate to confirm scope |
-
-Escalate per the caller's escalation procedure (write the review id to the cursor's escalated set, emit one terminal message with both interpretations, pause the PR until the user resolves).
-
-### Borderline rule
-
-If you can paraphrase the review's intent as **"do X"** with X being a concrete change (one or several) — it's actionable. Pick the best interpretation and dispatch the cycle.
-
-If you can paraphrase it only as **"the reviewer is dissatisfied but I can't tell with what"** — it's ambiguous.
-
-When the review mixes both ("3 concrete directives + 1 dissatisfaction"), the safer move is usually to action the concrete directives and ask about the dissatisfaction in the reply summary. Pure ambiguity means *nothing* in the review is actionable.
+| Section | Use case |
+| :------ | :------- |
+| [`allow-list`](pr-followup-helpers/allow-list.md) | Resolve who counts as a reviewer (requested reviewers ∪ CODEOWNERS − bots − author). |
+| [`reply-routing`](pr-followup-helpers/reply-routing.md) | Pick the right reply endpoint per comment type (line, body-only, CI failure). |
+| [`classify`](pr-followup-helpers/classify.md) | Per-review binary label: actionable vs ambiguous, with worked examples + borderline rule. |