@muggleai/works 4.11.4 → 4.12.1

package/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/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/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/plugin/skills/_shared/pr-followup-helpers/allow-list.md

@@ -0,0 +1,55 @@
+# Reviewer allow-list
+
+The address-reviews flow only acts on reviews submitted by users in the **allow-list** = (requested reviewers ∪ CODEOWNERS ∪ {PR author}) − bots. Re-resolve every invocation — never cache across cycles.
+
+The PR author is implicitly a valid reviewer: in single-account workflows, the human running the agent and the PR's author are the same identity, and the agent must honor their reviews. The agent itself never appears in the submitted-reviews list (it pushes commits and posts inline replies; it does not submit GitHub reviews), so there's no self-loop risk from including the author.
+
+## 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 inclusion 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/plugin/skills/_shared/pr-followup-helpers/classify.md

@@ -0,0 +1,63 @@
+# Classify
+
+Classify the **review as a unit** — but reply per line comment (threaded), not per review.
+
+## Pre-check: self-loop filter
+
+GitHub auto-creates a synthetic review every time the agent posts `POST /comments/<id>/replies`. That review has the loop user as author, an empty body, and contains only the agent's own reply comments (`in_reply_to_id != null`). It carries no reviewer intent and must not trigger another cycle.
+
+A review is a **self-loop** iff:
+
+- `body` is empty, AND
+- every line comment under it has `in_reply_to_id != null`
+
+Self-loops bypass the actionable/ambiguous decision entirely. Action: advance the cursor silently. No push, no reply, no resolve-reminder, no escalation, no entry in `escalated_review_ids`. Telemetry: emit one `cycle` event with `outcome: "self-loop-skip"`.
+
+Only reviews that survive the self-loop check proceed to classify below.
+
+## Actionable vs ambiguous
+
+| 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/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/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. |

package/plugin/skills/_shared/telemetry-events/muggle-do-cycle.md

@@ -0,0 +1,26 @@
+# `muggle-do:cycle`
+
+One per address-reviews invocation, regardless of outcome.
+
+```json
+{
+  "skill": "muggle-do",
+  "event": "cycle",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "review_ids_in": [<int>, ...],
+  "review_ids_actionable": [<int>, ...],
+  "review_ids_ambiguous": [<int>, ...],
+  "head_sha_before": "<sha-or-null>",
+  "head_sha_after": "<sha-or-null>",
+  "outcome": "pushed" | "escalated" | "mixed" | "no-op" | "self-loop-skip"
+}
+```
+
+`outcome`:
+- `"pushed"` — at least one actionable, no ambiguous, push succeeded.
+- `"escalated"` — all reviews were ambiguous; no push.
+- `"mixed"` — both branches happened in the same invocation.
+- `"no-op"` — every input id was already in the escalated set; no work.
+- `"self-loop-skip"` — review was a synthetic wrapper around the agent's own reply (empty body + all line comments are replies). Cursor advanced silently; no work, no escalation.

package/plugin/skills/_shared/telemetry-events/muggle-do-escalation.md

@@ -0,0 +1,19 @@
+# `muggle-do:escalation`
+
+Zero or one per address-reviews invocation. Fires when `/muggle-do` emits a terminal escalation message to the user.
+
+```json
+{
+  "skill": "muggle-do",
+  "event": "escalation",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "kind": "ambiguous-review" | "design-adjustment",
+  "review_ids": [<int>, ...]
+}
+```
+
+`kind`:
+- `"ambiguous-review"` — one or more reviews classified ambiguous in this batch.
+- `"design-adjustment"` — mid-cycle, the work surfaced a design-level conflict.

package/plugin/skills/_shared/telemetry-events/muggle-do-resolve-reminder.md

@@ -0,0 +1,19 @@
+# `muggle-do:resolve-reminder`
+
+Zero or one per cycle. Fires after the resolve-reminder stage scans threads — only when actionables ran.
+
+```json
+{
+  "skill": "muggle-do",
+  "event": "resolve-reminder",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "addressed_by_loop": <int>,
+  "addressed_by_human": <int>,
+  "not_addressed": <int>,
+  "comment_posted": true | false
+}
+```
+
+- `comment_posted`: false when there were zero addressed-by-loop threads; telemetry still emits so dashboards see the scan happened.

package/plugin/skills/_shared/telemetry-events/pr-followup-bootstrap.md

@@ -0,0 +1,20 @@
+# `muggle-pr-followup:bootstrap`
+
+One per successful bootstrap, after state seeding and before the first watcher dispatches.
+
+```json
+{
+  "skill": "muggle-pr-followup",
+  "event": "bootstrap",
+  "caller": "<caller-name>",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "cursor_review_id": <int>,
+  "resume": true | false
+}
+```
+
+- `caller`: `"user"` for direct invocation; another skill name if relayed.
+- `cursor_review_id`: `0` if no prior submitted reviews; otherwise the highest existing review id.
+- `resume`: true when `--resume` was used.

package/plugin/skills/_shared/telemetry-events/pr-followup-tick.md

@@ -0,0 +1,23 @@
+# `muggle-pr-followup:tick`
+
+One per watcher iteration (idle or not).
+
+```json
+{
+  "skill": "muggle-pr-followup",
+  "event": "tick",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "reviews_seen": <int>,
+  "dispatched_review_ids": [<int>, ...],
+  "terminal": true | false,
+  "idle": true | false,
+  "tick_duration_ms": <int>
+}
+```
+
+- `reviews_seen`: count of new submitted reviews past the cursor, **after** filtering by the escalated set.
+- `dispatched_review_ids`: review ids handed to `/muggle-do`. Empty when idle.
+- `terminal`: true when this tick observed the PR merged or closed and wrote `result.md`.
+- `idle`: true when no reviews were dispatched this tick.

package/plugin/skills/_shared/telemetry-events.md

@@ -0,0 +1,15 @@
+# Telemetry Event Catalog
+
+Canonical shapes for `muggle-local-telemetry-event-emit` events. Emission mechanics: [`telemetry-emit.md`](telemetry-emit.md).
+
+All events share two top-level fields: `skill` and `event`. The rest is event-specific — read only the file for the event you're emitting.
+
+## Index
+
+| Event | When |
+| :---- | :--- |
+| [`muggle-pr-followup:tick`](telemetry-events/pr-followup-tick.md) | Every watcher iteration (idle or not). |
+| [`muggle-pr-followup:bootstrap`](telemetry-events/pr-followup-bootstrap.md) | Successful bootstrap, before first watcher dispatches. |
+| [`muggle-do:cycle`](telemetry-events/muggle-do-cycle.md) | Every address-reviews invocation, regardless of outcome. |
+| [`muggle-do:escalation`](telemetry-events/muggle-do-escalation.md) | When `/muggle-do` emits a terminal escalation message. |
+| [`muggle-do:resolve-reminder`](telemetry-events/muggle-do-resolve-reminder.md) | After the resolve-reminder stage scans threads. |