@muggleai/works 4.11.4 → 4.12.1

package/dist/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/dist/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/dist/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. |

package/dist/plugin/skills/do/address-reviews.md

@@ -0,0 +1,137 @@
+# Address-Reviews Orchestrator
+
+The entry procedure for `/muggle-do`'s **address-reviews** mode — invoked by the watcher loop ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md)) when new submitted reviews land on a PR. Orchestrates the cycle: read reviews → classify → execute work on actionables → escalate ambiguous → push and refresh PR → reply per comment → resolve-reminder → respawn watcher.
+
+## Turn preamble
+
+```
+**/muggle-do address-reviews** — handling <count> review(s) on <owner>/<repo>#<n>.
+```
+
+## Input
+
+`$ARGUMENTS` carries:
+- PR URL: `<owner>/<repo>#<n>` derivable from the URL.
+- Session slug: `<slug>`.
+- List of review ids: one or more integers.
+
+Exact phrasing comes from the watcher's dispatch (see [`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md#step-5-if-one-or-more-new-reviews-dispatch)). Parse all three out of the directive text.
+
+## Inputs from disk
+
+Read from `.muggle-do/sessions/<slug>/`:
+
+- `prs.json` — to locate the PR's local checkout path (the `repo` field maps to a configured local repo) and capture `head_sha_before`.
+- `last_seen.json` — for `pushed_shas[]` (used by the resolve-reminder stage) and to update the cursor.
+- `state.md` — for the cached `loop_user` login (used by resolve-reminder thread classification).
+
+## Procedure
+
+### Step 1 — Read every listed review off GitHub
+
+For each review id in the input:
+
+- Fetch reviews per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md) (cursor 0; filter to the specific id).
+- Fetch its line comments per [`../_shared/github-cli-recipes/line-comments-for-review.md`](../_shared/github-cli-recipes/line-comments-for-review.md).
+
+Group into one combined batch.
+
+### Step 2 — Classify each review
+
+Apply the classify rule in [`../_shared/pr-followup-helpers/classify.md`](../_shared/pr-followup-helpers/classify.md). Two outcomes per review:
+
+- **Actionable** — at least one concrete change request, or an answerable question with a target.
+- **Ambiguous** — no actionable signal.
+
+Build two sets: `actionable_review_ids` and `ambiguous_review_ids`. Their union is the input list.
+
+### Step 3 — Handle ambiguous (if any)
+
+For each id in `ambiguous_review_ids`:
+
+1. Append it to `last_seen.escalated_review_ids` so the watcher won't re-dispatch it.
+
+Emit **one** terminal escalation message (not one per ambiguous review) per [`../muggle-pr-followup/output-templates/escalation.md`](../muggle-pr-followup/output-templates/escalation.md) (ambiguous template). The message lists every ambiguous review and its comments inline. Emit an event with `kind: "ambiguous-review"` per [`../_shared/telemetry-events/muggle-do-escalation.md`](../_shared/telemetry-events/muggle-do-escalation.md).
+
+The user clarifies on GitHub by submitting a new review. The next watcher tick picks it up.
+
+### Step 4 — Handle actionables (if any)
+
+If `actionable_review_ids` is empty, skip Steps 4 and 5; proceed to Step 6 (cursor + respawn). Otherwise:
+
+#### 4a. Flatten the work
+
+The actionable reviews together carry a flat list of change items, one per line comment plus any directive in the review body. Each item is design, code logic, or test in nature; the cycle does **not** treat each item as a separate cycle iteration — it plans them together and runs the work **once** for the whole batch.
+
+#### 4b. Apply design + code-logic changes
+
+Invoke [`build.md`](build.md) with the review-derived requirements: for each comment, what to change and where. `build.md` makes the edits in the working tree but does not commit.
+
+If `build.md` reports that the requested work requires rethinking the design (e.g. the requested change conflicts with a load-bearing invariant), exit early per Step 7 (design-adjustment escalation).
+
+#### 4c. Create or update unit tests
+
+Invoke [`unit-tests.md`](unit-tests.md). Cover the surface that just changed; respect existing test conventions.
+
+#### 4d. Run ONE E2E acceptance pass
+
+Invoke [`e2e-acceptance.md`](e2e-acceptance.md). One pass covering all related test cases for this PR, not one pass per comment. Use the `autoE2ETest` gate per its usual contract.
+
+#### 4e. Create or update the PR
+
+Invoke [`open-prs/update.md`](open-prs/update.md) (pass the PR URL + slug + existing PR number). It pushes, refreshes title/description on state change, posts a fresh walkthrough comment, and appends the new SHA to `last_seen.pushed_shas[]`. Capture the new `head_sha`.
+
+#### 4f. Post per-comment inline replies
+
+Invoke [`per-comment-replies.md`](per-comment-replies.md) with the actionable reviews and the new SHA. One reply per comment, in its own thread, describing what was done for it.
+
+#### 4g. Run the resolve-reminder stage
+
+Invoke [`resolve-reminder.md`](resolve-reminder.md). Scans unresolved threads, classifies, and posts a top-level PR comment listing addressed-by-loop thread ids.
+
+### Step 5 — Update session state
+
+- `last_seen.cycles_completed` += 1
+- `last_seen.last_pushed_sha` = the new head SHA (update.md already wrote this; verify)
+- `last_seen.reviewId` = max(input review ids ∪ last_seen.reviewId)
+
+### Step 6 — Respawn the watcher
+
+Refresh PR state per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md). If the PR is now merged or closed:
+
+1. Write `result.md` per [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md#resultmd).
+2. Do **not** respawn the watcher.
+
+Otherwise, dispatch the next watcher as the last action of this turn:
+
+```
+/loop 1m /muggle:muggle-pr-followup <slug> <n>
+```
+
+### Step 7 — Telemetry
+
+Emit one event per [`../_shared/telemetry-events/muggle-do-cycle.md`](../_shared/telemetry-events/muggle-do-cycle.md). `outcome` is one of:
+
+- `"pushed"` — actionables ran and at least one push succeeded.
+- `"escalated"` — only ambiguous; no push.
+- `"mixed"` — both branches ran.
+- `"no-op"` — every input id was already in `escalated_review_ids` (the watcher shouldn't have dispatched, but defensive coverage).
+
+Emit additional events as Steps fired them (escalation event in Step 3; resolve-reminder event in Step 4g).
+
+## Design-adjustment escalation (Step 4b early exit)
+
+When `build.md` returns `failed: design-adjustment`:
+
+1. Append the affected review ids to `last_seen.escalated_review_ids`.
+2. Emit one terminal message per [`../muggle-pr-followup/output-templates/escalation.md`](../muggle-pr-followup/output-templates/escalation.md) (design-adjustment template).
+3. Emit the `escalation` telemetry event with `kind: "design-adjustment"`.
+4. Skip to Step 6 (respawn watcher). The watcher continues polling — the user can override the design conflict by submitting a new review.
+
+Do **not** push, do **not** post replies, do **not** run resolve-reminder. The cycle ended on a design conflict; the work was not applied.
+
+## Invariants
+
+- One `/muggle-do` invocation = at most one push and one resolve-reminder, regardless of how many reviews are in the batch.
+- Every input review id ends up in either the cursor (handled) or `escalated_review_ids` (skipped) — never both, never neither.
+- The watcher is respawned exactly when the PR is still open at the end of the cycle.

package/dist/plugin/skills/do/build.md

@@ -41,11 +41,11 @@ Per repo:
 
 If a requirement is fundamentally unimplementable as written, halt and escalate with the specific blocker — do not ship a half-finished implementation.
 
-## Re-entry from stage 8
+## Re-entry from the address-reviews flow
 
-Stage 8 (PR follow-up) may dispatch back to this stage when a reviewer comment requires real implementation work rather than an in-place doc edit. When re-entered:
+The address-reviews orchestrator ([`address-reviews.md`](address-reviews.md)) invokes this stage when reviewers submit comments that require code/design changes. When re-entered:
 
-- The dispatch from stage 8 carries the comment(s) that triggered the re-build as additional context; treat them as amendments to the goal/AC for this iteration.
+- The orchestrator passes the actionable reviews' bodies + line comments as the requirements amendment for this iteration. Treat them as additions to the goal/AC.
 - Continue on the existing branch — do not re-create the worktree.
-- Cycle forward through impact analysis → unit tests → E2E → open PR (which is a no-op since the PR already exists; just push).
-- Stage 8 resumes polling after the push lands.
+- After this stage, the orchestrator runs unit-tests → ONE E2E pass → create-or-update PR (push to the existing branch; refresh title/desc if state changed) → per-comment inline replies → resolve-reminder → respawn the watcher.
+- If the requested work cannot be implemented without rethinking design (e.g. a load-bearing invariant must change), return `failed: design-adjustment` and let the orchestrator escalate via the design-adjustment terminal message. Do not partially implement.

package/dist/plugin/skills/do/open-prs/forward.md

@@ -0,0 +1,80 @@
+# Open PR — forward mode
+
+Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fresh feature. Creates the PR via `gh pr create`, seeds session state, dispatches the first watcher.
+
+## Turn preamble
+
+```
+**Stage 7 — Create PR** — pushing the branch and opening the PR.
+```
+
+## Inputs
+
+- Per-repo: name, path, branch.
+- Requirements: goal, acceptance criteria.
+- **Optional** E2E acceptance report from stage 6. Produced by [`../e2e-acceptance.md`](../e2e-acceptance.md); schema in [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md).
+
+## Per repo
+
+0. **`autoCreatePR` gate** — apply per [`../../muggle-preferences/preference-gates/autoCreatePR.md`](../../muggle-preferences/preference-gates/autoCreatePR.md). On skip, record the reason in `result.md` and move on.
+
+1. **Push:** `git push -u origin <branch>` in the repo directory.
+
+2. **Title** (under 70 chars):
+   - E2E report exists and has failures → `[E2E FAILING] <goal>`
+   - No E2E report (validation was `unit-only` or `skip`) → `[UNVERIFIED] <goal>` or `[UNIT-ONLY] <goal>` to match the validation strategy
+   - Otherwise → `<goal>`
+
+3. **Body** — assemble in order:
+   - `## Goal` — from requirements.
+   - `## Acceptance Criteria` — bulleted; omit if empty.
+   - `## Changes` — summary of what changed in this repo.
+   - `## Validation` — one line: link to E2E report, `unit-only`, or `skip — <reason>`.
+   - **If an E2E report exists,** invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode B to render the walkthrough block. Embed the returned `body` verbatim. If no report, skip this block entirely.
+
+4. **Create:** `gh pr create --title "..." --body "..." --head <branch>`. Capture the PR URL and number.
+
+5. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once per [`../../_shared/github-cli-recipes/top-level-comment.md`](../../_shared/github-cli-recipes/top-level-comment.md). Never post when `comment` is `null`.
+
+## Stage 8 handoff
+
+After every repo is processed, build the watcher manifest and dispatch one watcher loop per opened PR. The dispatches are the LAST action this stage takes.
+
+Write `.muggle-do/sessions/<slug>/prs.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#prsjson):
+
+```json
+[{ "repo": "owner/repo", "number": 142, "url": "...", "head_sha": "...", "state": "open" }]
+```
+
+Seed `.muggle-do/sessions/<slug>/last_seen.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#last_seenjson) — empty cursor shape with `pushed_shas: []`. Forward mode never has prior reviews to skip, so `reviewId: 0`.
+
+**Do not** seed `cycle.json` or `requirements.md`. The watcher is a dumb pipe; `/muggle-do` reads reviews off GitHub.
+
+For each entry in `prs.json`, dispatch its watcher:
+```
+/loop 1m /muggle:muggle-pr-followup <slug> <pr-number>
+```
+
+If `prs.json` is empty, **do not dispatch** — record the reason in `result.md` and exit.
+
+## Invariants
+
+- PR creation per non-skipped repo; walkthrough block via Mode B; `prs.json`+`last_seen.json` seeded (no `cycle.json`, no `requirements.md`); `/loop` dispatch is the last action.
+
+## Output
+
+**PRs Created:** repo → URL
+**Skipped:** repo → reason (when `autoCreatePR` short-circuited)
+**Overflow comments posted:** repo → PR #
+**Stage 8:** `Watching <N> PR(s) — one /loop 1m /muggle:muggle-pr-followup <slug> <pr#> per PR` | `No PRs to watch — stage 8 not dispatched`
+**Errors:** repo → message
+
+## Post-merge cleanup
+
+Gated by `autoCleanup`. Fires in a follow-up turn after merge — never from this stage. See [`../../_shared/post-merge-cleanup.md`](../../_shared/post-merge-cleanup.md).
+
+Append one short reminder tied to the gate value:
+
+- `always` → `Once merged, I'll run the cleanup sequence automatically.`
+- `never` → omit.
+- `ask` / absent → `Once merged, I'll check with you about cleanup.`

package/dist/plugin/skills/do/open-prs/update.md

@@ -0,0 +1,54 @@
+# Update PR — address-reviews mode
+
+Invoked by `/muggle-do`'s address-reviews orchestrator after stages 3–6 ran on the existing PR. The PR already exists; this stage pushes the branch, refreshes title/description if state changed, and posts a fresh walkthrough.
+
+Does **not** create a PR, seed session state, or dispatch a watcher (`/muggle-do` respawns the watcher at the end of its address-reviews cycle).
+
+## Turn preamble
+
+```
+**Stage 7 — Update PR** — pushing the branch and refreshing the PR.
+```
+
+## Inputs
+
+- Per-repo: path, branch (head ref name).
+- The existing PR URL + number from `.muggle-do/sessions/<slug>/prs.json`.
+- **Optional** E2E acceptance report from stage 6. Produced by [`../e2e-acceptance.md`](../e2e-acceptance.md); schema in [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md).
+
+## Procedure
+
+Skip `autoCreatePR` (it gates creation, not update). The PR's title is left intact unless state changed in Step 3.
+
+1. **Push:** per [`../../_shared/github-cli-recipes/push-to-branch.md`](../../_shared/github-cli-recipes/push-to-branch.md). Capture the new SHA.
+
+2. **Append new SHA** to `last_seen.json[<key>].pushed_shas` (the resolve-reminder stage uses this to recognize threads addressed by the loop). Set `last_seen.last_pushed_sha` to the new SHA too.
+
+3. **Refresh title if state changed.** Compare the new state against the current PR title prefix:
+   - E2E now passing, current title has `[E2E FAILING]` → strip the prefix per [`../../_shared/github-cli-recipes/pr-edit.md`](../../_shared/github-cli-recipes/pr-edit.md).
+   - E2E now failing, current title has no `[E2E FAILING]` → add the prefix.
+   - Validation now ran (was unit-only/skip, now has E2E report) → strip `[UNVERIFIED]` or `[UNIT-ONLY]`.
+   - Otherwise → no title change.
+
+4. **Refresh body when validation outcome changed** — only when the `## Validation` section's content differs from what's in the body. Use the `--body-file` form in [`../../_shared/github-cli-recipes/pr-edit.md`](../../_shared/github-cli-recipes/pr-edit.md). Preserve `## Goal` and `## Acceptance Criteria` verbatim.
+
+5. **Visual walkthrough comment** — if an E2E report exists, invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode A. Always a fresh comment per cycle; do not edit prior walkthrough comments.
+
+6. **Overflow comment** — same rule as forward mode: post when the walkthrough skill returns non-null `comment`, via [`../../_shared/github-cli-recipes/top-level-comment.md`](../../_shared/github-cli-recipes/top-level-comment.md).
+
+## Handoff
+
+Return control to `/muggle-do`'s address-reviews orchestrator. The orchestrator runs the remaining stages (per-comment replies → resolve-reminder → respawn watcher).
+
+## Invariants
+
+- Push; new SHA appended to `pushed_shas`; title/body refreshed only on state change; walkthrough comment via Mode A.
+- No `gh pr create`, no `/loop` dispatch.
+
+## Output
+
+**PR updated:** URL (new SHA: `<short-sha>`)
+**Title refreshed:** yes | no
+**Body refreshed:** yes | no
+**Walkthrough comment:** posted | skipped (no report)
+**Overflow comment:** posted | skipped

package/dist/plugin/skills/do/open-prs.md

@@ -1,104 +1,8 @@
-# PR Creation Agent (Stage 7 — Open PR)
+# Create-or-Update PR (Stage 7)
 
-Open a pull request for each repo that has changes. If an E2E walkthrough report is available from the previous stage, attach it. Honor preference gates. Hand off to stage 8 once done.
+Two modes, set by the `/muggle-do` invocation. Each consumer loads only its mode's file.
 
-## Turn preamble
-
-```
-**Stage 7 — Open PR** — pushing the branch and opening the PR.
-```
-
-## Inputs
-
-- Per-repo: name, path, branch.
-- Requirements: goal, acceptance criteria.
-- **Optional** E2E acceptance report from stage 6 — only present when validation ran. Produced by [`e2e-acceptance.md`](e2e-acceptance.md); schema is canonical in [`muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) (Zod-validated by the CLI).
-
-## Per repo
-
-0. **`autoCreatePR` gate** — apply per [`../muggle-preferences/preference-gates/autoCreatePR.md`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip, record the reason in `result.md` and move on.
-
-1. **Push:** `git push -u origin <branch>` in the repo directory.
-
-2. **Title** (under 70 chars):
-   - E2E report exists and has failures → `[E2E FAILING] <goal>`
-   - No E2E report at all (validation was `unit-only` or `skip`) → `[UNVERIFIED] <goal>` or `[UNIT-ONLY] <goal>` to match the validation strategy
-   - Otherwise → `<goal>`
-
-3. **Body** — assemble in order:
-   - `## Goal` — from requirements.
-   - `## Acceptance Criteria` — bulleted; omit section if empty.
-   - `## Changes` — summary of what changed in this repo.
-   - `## Validation` — one line: link to E2E report, or `unit-only`, or `skip — <reason>`.
-   - **If an E2E report exists,** invoke [`muggle-pr-visual-walkthrough`](../muggle-pr-visual-walkthrough/SKILL.md) Mode B to render the walkthrough block. Embed the returned `body` verbatim (it brings its own `## E2E Acceptance Results` heading). If no report, skip this block entirely.
-
-4. **Create:** `gh pr create --title "..." --body "..." --head <branch>`. Capture the PR URL and number.
-
-5. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once:
-   ```bash
-   jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <PR#> --body-file -
-   ```
-   Never post when `comment` is `null`.
-
-## Stage 8 handoff
-
-After every repo is processed, build the manifest and dispatch **one follow-up loop per opened PR**. The dispatches are the LAST action this stage takes — once they fire, the original session is free.
-
-Write `.muggle-do/sessions/<slug>/prs.json` with one entry per **opened** PR (skip repos where `autoCreatePR` short-circuited or PR creation failed):
-
-```json
-[{ "repo": "owner/repo", "number": 142, "url": "...", "head_sha": "...", "state": "open" }]
-```
-
-Seed `.muggle-do/sessions/<slug>/last_seen.json` keyed by `"<owner>/<repo>#<n>"` with the empty-cursor shape (full shape in [`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md)). Stage 7 only seeds; each per-PR loop owns advancing its own cursor.
-
-Also seed `.muggle-do/sessions/<slug>/cycle.json` — the muggle-do implementation cycle declaration the follow-up loop will invoke on each actionable review:
-
-```json
-{
-  "cycleName": "muggle-do dev cycle",
-  "steps": [
-    { "stage": 3, "file": "../do/build.md" },
-    { "stage": 4, "file": "../do/impact-analysis.md" },
-    { "stage": 5, "file": "../do/unit-tests.md" },
-    { "stage": 6, "file": "../do/e2e-acceptance.md" },
-    { "name": "post-walkthrough", "skill": "muggle-pr-visual-walkthrough", "mode": "A" }
-  ],
-  "pushHandler": "git push origin <branch>",
-  "useSubagent": false
-}
-```
-
-For each entry in `prs.json`, dispatch its own loop as the final action:
-```
-/loop 1m /muggle:muggle-pr-followup <slug> <pr-number>
-```
-Resolve `<slug>` from the session directory's basename. One loop per PR — multi-repo sessions opening N PRs result in N independent loops, each tracking its own PR's review thread.
-
-If `prs.json` is empty (all repos skipped, or all PR creations failed), **do not dispatch** — record the reason in `result.md` and exit.
-
-## Self-check before exit
-
-- [ ] Every non-skipped repo got `gh pr create` to succeed.
-- [ ] When an E2E report existed, the walkthrough block was rendered via Mode B (not hand-written).
-- [ ] Overflow `comment` was posted only when non-null.
-- [ ] `prs.json` and `last_seen.json` reflect the PRs actually opened.
-- [ ] If `prs.json` is non-empty, the `/loop` dispatch was the last action.
-
-## Output
-
-**PRs Created:** repo → URL
-**Skipped:** repo → reason (when `autoCreatePR` short-circuited)
-**Overflow comments posted:** repo → PR #
-**Stage 8:** `Watching <N> PR(s) — one /loop 1m /muggle:muggle-pr-followup <slug> <pr#> per PR` | `No PRs to watch — stage 8 not dispatched`
-**Errors:** repo → message
-
-## Post-merge cleanup
-
-Gated by `autoCleanup`. Fires in a follow-up turn after merge — never from this stage. See [`../_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md).
-
-Append one short reminder tied to the gate value:
-
-- `always` → `Once merged, I'll run the cleanup sequence automatically.`
-- `never` → omit.
-- `ask` / absent → `Once merged, I'll check with you about cleanup.`
+| Mode | When | Procedure |
+| :--- | :--- | :-------- |
+| Forward | After stages 1–6 of a fresh feature (called by `/muggle-do`'s forward pipeline). Creates the PR, seeds state, dispatches the first watcher. | [`open-prs/forward.md`](open-prs/forward.md) |
+| Update | The PR already exists; the address-reviews orchestrator called this stage to push + refresh title/description/walkthrough. | [`open-prs/update.md`](open-prs/update.md) |

package/dist/plugin/skills/do/per-comment-replies.md

@@ -0,0 +1,61 @@
+# Per-Comment Inline Replies
+
+A `/muggle-do` step invoked from [`address-reviews.md`](address-reviews.md) (Step 4f) after the push has succeeded. Posts one inline nested reply on each line comment from the actionable reviews, describing what was done for that comment and referencing the new SHA.
+
+This is **not** a top-level "summary reply on the review." Each comment thread gets its own reply, in context, via GitHub's `/comments/{id}/replies` endpoint.
+
+## Inputs
+
+- `actionable_reviews` — the list of reviews classified actionable in `address-reviews.md` Step 2.
+- `new_sha` — the SHA `open-prs/update.md` just pushed.
+- The PR's owner, repo, number.
+
+## Procedure
+
+### Step 1 — Build the comment-to-change map
+
+For each comment in each actionable review, the cycle's `build.md` produced (or should have produced) a one-line note describing what was changed for that specific comment. Two sources, in order:
+
+1. If `build.md` returned a `comment_changes` map keyed by comment id → short description, use it directly.
+2. If not (legacy `build.md` that doesn't return that shape yet), infer from the diff + the comment's body: which file/line did the comment refer to, and what changed at or near it. The inferred description is best-effort; better to be brief than wrong.
+
+If a comment has no associated change in either source (e.g. the comment was a question, not a change request), use the comment's body to compose a one-sentence answer.
+
+### Step 2 — Post one reply per comment
+
+For each comment id with a description:
+
+```bash
+gh api --method POST \
+  -H "Accept: application/vnd.github+json" \
+  repos/<owner>/<repo>/pulls/<n>/comments/<comment-id>/replies \
+  -f body="<reply-body>"
+```
+
+Reply body uses the template in [`../muggle-pr-followup/output-templates/inline-reply.md`](../muggle-pr-followup/output-templates/inline-reply.md):
+
+```
+Addressed in <short-sha>: <one-line summary of the change made for THIS comment>.
+```
+
+`<short-sha>` is the first 7 chars of `new_sha`. The body must contain the literal `<short-sha>` substring — the resolve-reminder stage greps for it to classify threads as addressed-by-loop.
+
+### Step 3 — Handle review-body-only comments
+
+If an actionable review has a non-empty `body` and **zero** line comments, GitHub has no `/replies` endpoint for the review body itself (the API has been inconsistent on this and the only reliable path is a top-level PR comment that references the review). Use the *top-level reference* form:
+
+```
+Re: review #<review_id> — addressed in <short-sha>: <one-line summary>.
+```
+
+Posted per [`../_shared/github-cli-recipes/top-level-comment.md`](../_shared/github-cli-recipes/top-level-comment.md). Fires at most once per actionable review-with-no-line-comments. Does not fire if the review has line comments — Step 2 covers those.
+
+## Failure modes
+
+- `gh api` returns an error for an individual reply → log to `followup.log`, continue with the remaining comments. Do not abort the whole step over one failure; the push has already happened and other replies still need posting.
+- All replies fail → surface the most-recent `gh` error to the user, but do not abort the overall `/muggle-do` invocation. The resolve-reminder stage still runs; the watcher still respawns. The next cycle on this PR will produce more replies and the missing ones can be picked up by the human reviewer.
+
+## Invariants
+
+- One reply per line comment. No per-review summary reply anywhere.
+- Every reply body contains the new SHA's 7-char prefix — the resolve-reminder stage greps for it.

package/dist/plugin/skills/do/resolve-reminder.md

@@ -0,0 +1,70 @@
+# Resolve-Reminder Stage
+
+A `/muggle-do` stage that runs in **address-reviews mode only**, after per-comment inline replies have been posted. Scans every unresolved comment thread on the PR, classifies them, and posts ONE top-level PR comment listing the threads the loop addressed in this push.
+
+Runs zero or one times per `/muggle-do` invocation:
+
+- Runs when at least one actionable review was processed (i.e. the cycle actually pushed).
+- Does not run when the entire input batch was ambiguous (no push, nothing to remind about).
+- Does not run in the forward pipeline (a fresh PR has no review threads to remind about).
+
+## Turn preamble (inline within `/muggle-do` cycle)
+
+This stage does not print a turn preamble — it runs inside `/muggle-do`'s address-reviews cycle, immediately after per-comment replies and before respawning the watcher.
+
+## Inputs
+
+- The current PR (URL, owner, repo, number) from the session's `prs.json`.
+- `last_seen.pushed_shas[]` from `last_seen.json` — the list of every SHA `/muggle-do` has pushed for this PR.
+- The loop user's GitHub login (cached in `state.md` under `Loop user:` — re-resolve per [`../_shared/github-cli-recipes/loop-user-identity.md`](../_shared/github-cli-recipes/loop-user-identity.md) if missing).
+
+## Procedure
+
+### Step 1 — Fetch unresolved comment threads
+
+Per [`../_shared/github-cli-recipes/unresolved-threads.md`](../_shared/github-cli-recipes/unresolved-threads.md). Filter client-side to `isResolved == false`. Each thread carries its line comments with `author.login`, `body`, and `databaseId`.
+
+If the API call fails, log the error to `followup.log` and skip the stage. Do not surface a user-facing error — the resolve reminder is a nice-to-have, not load-bearing. The reply summaries on the threads themselves still happen.
+
+### Step 2 — Classify each thread
+
+For each unresolved thread, walk its comments in chronological order. Classify by the **first match** that applies:
+
+- **Addressed by the loop** — at least one comment authored by the loop user **and** that comment's body cites a SHA prefix in `last_seen.pushed_shas[]`. Bodies use the form *"Addressed in `<short-sha>`: ..."* per [`../muggle-pr-followup/output-templates/inline-reply.md`](../muggle-pr-followup/output-templates/inline-reply.md), so a substring match on any `pushed_shas[i][:7]` works.
+- **Addressed by a human** — at least one comment authored by a non-loop-user identity created after the original comment's timestamp, and no addressed-by-loop signal.
+- **Not addressed** — neither of the above.
+
+The classification considers only the unresolved threads' comments. Do not cross-reference timeline events from outside the threads.
+
+### Step 3 — Build the resolve-reminder list
+
+Collect the thread `databaseId` of every thread classified as **addressed by the loop in this push** (i.e. citing a SHA in `pushed_shas[]` where that SHA was added by the current invocation; older SHAs were already covered by prior cycles' reminders).
+
+Note: the watcher does not maintain a "addressed-this-cycle" set; this stage derives it by comparing thread comments to the most-recent appended SHA. The simplest deterministic rule: include a thread iff at least one of its bot replies cites the **most recent** `pushed_shas[-1]`. Earlier SHAs were already addressed in past reminders.
+
+### Step 4 — Post the top-level reminder comment
+
+If the resolve-reminder list is non-empty, post **one** top-level PR comment using the template in [`../muggle-pr-followup/output-templates/resolve-reminder.md`](../muggle-pr-followup/output-templates/resolve-reminder.md) per [`../_shared/github-cli-recipes/top-level-comment.md`](../_shared/github-cli-recipes/top-level-comment.md).
+
+If the list is empty (the push didn't end up addressing any threads — e.g. the actionable work was on lines that had no comment threads), post **nothing**. Still emit telemetry so the stage's run is observable.
+
+### Step 5 — Emit telemetry
+
+Emit one event per [`../_shared/telemetry-events/muggle-do-resolve-reminder.md`](../_shared/telemetry-events/muggle-do-resolve-reminder.md). Include:
+
+- `addressed_by_loop` — count of threads added to the reminder list in Step 3.
+- `addressed_by_human` — count from Step 2's other category.
+- `not_addressed` — count from Step 2's "not addressed" category.
+- `comment_posted` — true iff Step 4 actually posted a comment.
+
+## Failure modes
+
+This stage is best-effort. Any failure is logged to `followup.log` and silently skipped — the reviewer still gets the per-comment inline replies (the canonical signal that work was done), and the cycle continues to respawn the watcher.
+
+The one exception: do not silently swallow a `gh pr comment` failure if Step 4 ran. The comment is a user-visible artifact; if it fails, surface the underlying `gh` error to the user so they know the reminder didn't post.
+
+## Invariants
+
+- Telemetry fires once per invocation, even when no comment is posted.
+- The reminder only covers threads addressed by the **most recent** push — older SHAs were covered by prior cycles' reminders.
+- This stage suggests; it does not resolve threads on the reviewer's behalf.