@muggleai/works 4.11.3 → 4.12.0

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.

package/dist/plugin/skills/muggle-do/SKILL.md

@@ -1,72 +1,68 @@
 ---
 name: muggle-do
-description: Unified Muggle AI workflow entry point. Use when user types muggle do or asks for autonomous implementation to PR.
+description: Unified Muggle AI workflow entry point. Use when user types muggle do or asks for autonomous implementation to PR. Also handles the `address-reviews` directive (dispatched by the muggle-pr-followup watcher when new submitted reviews land on a PR).
 disable-model-invocation: true
 ---
 
 # Muggle Test Do
 
-> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do"`.
+> Telemetry first step: see [`../_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do"`.
 
-Runs an autonomous dev cycle from requirements to PR. **Fire and review:** the user answers one pre-flight questionnaire, then walks away.
+Runs an autonomous dev cycle from requirements to PR. **Fire and review:** user answers one pre-flight questionnaire, then walks away. The [muggle-pr-followup](../muggle-pr-followup/SKILL.md) watcher invokes `/muggle-do` again with the *address-reviews* directive when new reviews land.
 
-For maintenance, use the dedicated skills:
+## Forward pipeline (fresh feature)
 
-- `/muggle:muggle-status`
-- `/muggle:muggle-repair`
-- `/muggle:muggle-upgrade`
+| # | Stage | File |
+| :- | :---- | :--- |
+| 1 | Pre-flight (only user-facing stage) | [`../do/pre-flight.md`](../do/pre-flight.md) |
+| 2 | Requirements | [`../do/requirements.md`](../do/requirements.md) |
+| 3 | Build | [`../do/build.md`](../do/build.md) |
+| 4 | Impact analysis | [`../do/impact-analysis.md`](../do/impact-analysis.md) |
+| 5 | Unit tests | [`../do/unit-tests.md`](../do/unit-tests.md) |
+| 6 | E2E acceptance | [`../do/e2e-acceptance.md`](../do/e2e-acceptance.md) |
+| 7 | Create or update PR | [`../do/open-prs.md`](../do/open-prs.md) |
+| 8 | Hand off to watcher | [`../muggle-pr-followup/SKILL.md`](../muggle-pr-followup/SKILL.md) |
 
-## The pipeline
+Stage 7 dispatches one watcher per opened PR as its last action.
 
-| # | Stage | File | User-facing? |
-| :- | :---- | :--- | :----------- |
-| 1 | Pre-flight | [../do/pre-flight.md](../do/pre-flight.md) | **Yes — one consolidated turn** |
-| 2 | Requirements | [../do/requirements.md](../do/requirements.md) | No |
-| 3 | Build | [../do/build.md](../do/build.md) | No |
-| 4 | Impact analysis | [../do/impact-analysis.md](../do/impact-analysis.md) | No |
-| 5 | Unit tests | [../do/unit-tests.md](../do/unit-tests.md) | No |
-| 6 | E2E acceptance | [../do/e2e-acceptance.md](../do/e2e-acceptance.md) | No |
-| 7 | Open PR | [../do/open-prs.md](../do/open-prs.md) | No |
-| 8 | PR follow-up | [../muggle-pr-followup/SKILL.md](../muggle-pr-followup/SKILL.md) (generic) — invoked with muggle-do's cycle declaration | **Yes — only on ambiguous reviews** |
+## Address-reviews flow
 
-Stage 1 talks to the user once. Stages 2–7 run silently. Stage 7 dispatches **one Stage-8 follow-up loop per PR** it opens (not one per session); each loop polls its own PR independently for new submitted reviews. When a review lands, the loop cycles back through Stage 3 (Build) → 4 → 5 → 6 → fresh visual walkthrough → push to the existing branch, then resumes polling for the next round. Each loop may escalate once on an ambiguous review.
+When invoked with the directive (PR URL + slug + review ids), routes to [`../do/address-reviews.md`](../do/address-reviews.md). Shares stages 3–6 + walkthrough with the forward pipeline; skips pre-flight, requirements, and PR creation. See the orchestrator for the cycle's exact step order, classification rules, and respawn logic.
 
-**Each stage's file is the single source of truth for that stage** — definition, contract, inputs/outputs, preference gates, output format. Read each stage file directly for its rules. This file is only the orchestration spine.
+## Input routing
 
-## Preferences
+Inspect `$ARGUMENTS` in this order:
 
-| Preference | Stage | Decision it gates |
-|------------|-------|-------------------|
-| `autoE2ETest` | 6 (E2E acceptance) | Run E2E every cycle (default `always`), or fold the question into pre-flight |
+1. **Address-reviews** — input contains a `github.com/.../pull/<n>` URL **and** one or more integers ≥ 100000000 (review id shape) → [`../do/address-reviews.md`](../do/address-reviews.md). Programmatic; never ask.
+2. **Empty / `help` / `menu` / `?`** → menu + session selector.
+3. **Task automation** (perform an action on a website) → `muggle:muggle-do-task`.
+4. **Otherwise** → forward pipeline at Stage 1.
 
-Other gates that fire during this cycle (`autoUseWorktree`, `autoRebase`, `autoCreatePR`, `autoCleanup`) are owned by the per-stage files; see each stage for its contract.
+When in doubt between #3 and #4, ask one question.
 
-## Input routing
-
-Treat `$ARGUMENTS` as the user command:
+## Preferences
 
-- Empty / `help` / `menu` / `?` → show menu and session selector.
-- Anything else → infer intent:
-  - **Task automation** (perform an action on a website — post something, fill a form, click through a flow) → invoke `muggle:muggle-do-task` with the full prompt.
-  - **Feature development** (build / fix / refactor code) → start or resume a dev-cycle session.
+| Preference | Gate |
+| :--------- | :--- |
+| `autoE2ETest` | Stage 6 — run E2E every cycle (default `always`), or fold into pre-flight |
 
-When in doubt, ask one question: "Browser automation task, or code change?"
+`autoUseWorktree`, `autoRebase`, `autoCreatePR`, `autoCleanup` fire from per-stage files.
 
 ## Session model
 
-Every run writes to `.muggle-do/sessions/<slug>/`. Stages own the files they produce:
+`.muggle-do/sessions/<slug>/`. Schemas: [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md).
 
-| File | Owned by | Purpose |
-| :--- | :------- | :------ |
-| `state.md` | Stage 1 (rewritten by every transition) | Current stage, pre-flight answers, blockers |
-| `iterations/<NNN>.md` | Every stage | Append-only stage transition log |
-| `requirements.md` | Stage 2 | Frozen requirements |
-| `prs.json`, `last_seen.json`, `followup.log` | Stage 8 | See [`pr-followup.md`](../do/pr-followup.md) |
-| `result.md` | Stage 7 (seeded), Stage 8 (finalized) | Per-PR final state |
+| File | Owner |
+| :--- | :---- |
+| `state.md` | Stage 1 or bootstrap |
+| `iterations/<NNN>.md` | Every stage |
+| `requirements.md` | Stage 2 (forward only) |
+| `prs.json`, `last_seen.json`, `followup.log` | Stage 7 / watcher / `/muggle-do` |
+| `result.md` | Stage 7 (seeded), terminal tick (finalized) |
 
 ## Guardrails
 
-- **Stage 1 is the only forward-pipeline user-facing stage.** Stages 2–7 don't ask questions mid-cycle. If a stage hits a blocker pre-flight didn't cover, treat as a pre-flight bug — escalate once and expand `pre-flight.md` after the run.
-- **Stage 8 may escalate** once per ambiguous review comment, and may dispatch back to Stage 3 when needed — see [`pr-followup.md`](../do/pr-followup.md).
-- **If the same stage fails 3 times in a row, escalate** with details.
-- **If 3 cycle iterations reach E2E with failures**, ship with `[E2E FAILING]` per [`open-prs.md`](../do/open-prs.md). The walkthrough section keeps the failures reviewable.
+- Stage 1 is the only user-facing forward stage. Stages 2–7 don't ask mid-cycle; blocker → pre-flight bug.
+- Same stage failing 3× → escalate.
+- 3 cycle iterations reach E2E with failures → ship with `[E2E FAILING]`.
+- Address-reviews escalation (ambiguous or design-adjustment) does not block the watcher; user resolves on GitHub.

package/dist/plugin/skills/muggle-pr-followup/CLAUDE.md

@@ -0,0 +1,25 @@
+# muggle-pr-followup — folder TOC
+
+This folder holds the watcher loop for PR review follow-ups. The watcher is a **dumb pipe**: it polls for new submitted reviews and dispatches `/muggle-do` when there are any. Cycle execution, classification, replies, and escalation all live in `/muggle-do`'s address-reviews mode — see [stage-8 design](../../../../muggle-ai-brain/architecture/2026-05-08-muggle-do-pr-comment-loop-design.md) for the architectural rationale.
+
+## Files in this folder
+
+- [`SKILL.md`](SKILL.md) — public entry. Smart-inference routing between bootstrap mode (URL input) and tick mode (slug + PR number). Read first.
+- [`bootstrap.md`](bootstrap.md) — the bootstrap procedure (one-shot non-interactive seed + watcher dispatch).
+- [`contract.md`](contract.md) — the watcher per-tick procedure (poll → dispatch → exit).
+- [`state-schemas.md`](state-schemas.md) — canonical JSON shapes of session state files.
+- [`output-templates.md`](output-templates.md) — TOC of message templates; per-group files in `output-templates/`.
+
+## Cross-folder dependencies
+
+Shared with other skills, under `../_shared/`:
+
+- [`pr-followup-helpers.md`](../_shared/pr-followup-helpers.md) — TOC of allow-list / reply-routing / classify; per-section files in `_shared/pr-followup-helpers/`. Called by `/muggle-do`, not by this folder.
+- [`telemetry-emit.md`](../_shared/telemetry-emit.md) — how to emit a telemetry event.
+- [`telemetry-events.md`](../_shared/telemetry-events.md) — TOC of canonical event shapes; per-event files in `_shared/telemetry-events/`.
+- [`github-cli-recipes.md`](../_shared/github-cli-recipes.md) — TOC of reusable `gh` / `git` snippets; per-recipe files in `_shared/github-cli-recipes/`.
+
+Caller-specific, under `../do/`:
+
+- [`open-prs.md`](../do/open-prs.md) — TOC for the create-or-update PR stage; per-mode files in `do/open-prs/`.
+- [`resolve-reminder.md`](../do/resolve-reminder.md) — `/muggle-do`'s post-replies stage that posts the resolve-reminder top-level comment.

package/dist/plugin/skills/muggle-pr-followup/SKILL.md

@@ -1,59 +1,37 @@
 ---
 name: muggle-pr-followup
-description: Generic per-PR follow-up loop. One polling tick per dispatch. Watches one PR for new submitted reviews; when an actionable review lands, invokes the caller's implementation cycle (build/test/walkthrough/push handler the caller declares), then resumes polling. Use as `/loop 1m /muggle:muggle-pr-followup <session-slug> <pr-number>`. Caller-agnostic — `muggle-do` is the first caller but not the last.
+description: Watcher loop for PR review follow-ups. Polls one PR for new submitted reviews and dispatches `/muggle-do` (address-reviews mode) when there are any. A dumb pipe — no classification, no cycle execution, no replies. Use `/loop 1m /muggle:muggle-pr-followup <slug> <pr-number>` for ongoing polling, or `/muggle:muggle-pr-followup <pr-url>` to bootstrap a fresh watcher on an existing PR.
 disable-model-invocation: true
 ---
 
-# Muggle PR Follow-up
+# muggle-pr-followup
 
-> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-followup"`.
+> Telemetry first step: see [`../_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-followup"`.
 
-A generic loop that babysits one open PR until it's merged or closed. Polls for submitted reviews; on an actionable review, dispatches the caller's implementation cycle to re-build, re-test, refresh the walkthrough, and push.
+A watcher that babysits one open PR's review thread. Polls for new submitted reviews; when any land, hands them off to `/muggle-do` and exits. `/muggle-do` is the executor — it classifies the reviews, runs the work, pushes, replies per comment, and respawns the watcher.
 
-**Per-PR isolation.** One dispatch per PR, not per session. Multi-PR work runs N independent loops.
+**The watcher is a dumb pipe.** It does not classify reviews, iterate cycles, post replies, or escalate. All of that lives in `/muggle-do`. See [stage-8 design](../../../../muggle-ai-brain/architecture/2026-05-08-muggle-do-pr-comment-loop-design.md) for the rationale.
 
-## Input
+**Per-PR isolation.** One watcher per PR. Multi-PR work runs N independent watchers.
 
-`$ARGUMENTS = <session-slug> <pr-number>`. The session-slug is the directory basename under `.muggle-<caller>/sessions/` (e.g. `.muggle-do/sessions/`) that this loop reads its state from. The pr-number identifies which PR in that session's manifest this loop watches.
+## Routing
 
-- Empty / `help` / `?` → list active `(slug, pr-number)` pairs across known callers, exit.
-- One argument → ambiguous; list PRs under that slug, exit.
-- Two arguments → resolve and run one tick.
+The skill recognizes two modes by inspecting `$ARGUMENTS` and falling back to on-disk state. It never runs procedure inline — it identifies the mode and routes to the appropriate procedure file.
 
-## Contract
+| Input | On-disk check | Mode |
+| :---- | :------------ | :--- |
+| First arg matches `https?://github\.com/[^/]+/[^/]+/pull/\d+` | — | **bootstrap** → [`bootstrap.md`](bootstrap.md) |
+| `<slug> <pr-number>` | session dir for `<slug>` exists | **tick** → [`contract.md`](contract.md) |
+| `<slug> <pr-number>` | session dir missing | **error:** "no session at `<path>`; pass a PR URL to start one" |
+| `<pr-number>` alone | exactly one existing session contains it | **tick** for that PR |
+| `<pr-number>` alone | zero or multiple matches | **error:** ambiguous; list candidates and exit |
+| empty / `help` / `?` | — | **help:** list active loops per [`output-templates/help.md`](output-templates/help.md) |
 
-The per-tick contract — termination check, allow-list resolution, review polling, classify, cycle dispatch, escalation, telemetry — lives in [`contract.md`](contract.md). Read it before driving a tick.
+Bootstrap accepts two optional trailing flags:
 
-## Caller-supplied implementation cycle
+- `--slug=<name>` — override the default `<repo>-pr<n>` slug
+- `--resume` — opt in to reusing an existing session slot (default is refuse on conflict)
 
-The skill itself is caller-agnostic. When an actionable review lands, it invokes the **implementation cycle** declared by the caller in the session's `cycle.json`:
+## Folder TOC
 
-```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>"
-}
-```
-
-The cycle's job: read the amended `requirements.md`, run each declared step, push to the existing branch. The cycle returns one of `pushed | escalated | failed`. The skill doesn't care what's inside the steps — it just iterates them, captures the outcome, and writes a reply summary referencing the new SHA.
-
-Callers without a `cycle.json` are rejected with `no cycle declared — caller must seed cycle.json at dispatch time`.
-
-## Subagent dispatch (optional)
-
-A caller may declare `"useSubagent": true` in `cycle.json`. When set, the implementation cycle runs as a separate Claude subagent rather than inline in the loop's tick — gives stronger isolation per PR but adds overhead per cycle. Default is inline (which is itself isolated per-tick via `/loop`).
-
-## Design adjustment escalation
-
-When the implementation cycle reports back that the review requires not just code change but a **design adjustment** beyond what the current requirements support (e.g. the build stage discovers the requested change conflicts with a load-bearing assumption), the cycle returns `failed: design-adjustment`. The loop treats this like an ambiguous escalation but with a different terminal message that points at the design conflict and asks the user to decide.
-
-## Why a separate skill (and not e.g. inside the caller's own skill folder)
-
-`/loop` dispatches via slash command; slash commands resolve to top-level skills under `plugin/skills/`. A per-tick loop driven by `/loop` therefore has to live as a top-level skill. Putting the loop's content directly inside a caller-specific folder would make `/loop`-dispatch impossible (or fragile via shell-only entry points). Keeping the loop generic and caller-agnostic is what lets `/loop` dispatch into it cleanly.
+See [`CLAUDE.md`](CLAUDE.md) for the one-line index of every file in this folder.

package/dist/plugin/skills/muggle-pr-followup/bootstrap.md

@@ -0,0 +1,88 @@
+# Bootstrap Procedure
+
+The procedure for the **bootstrap mode** of `muggle-pr-followup` — invoked when a user dispatches the skill with a GitHub PR URL. Routing into this mode is documented in [`SKILL.md`](SKILL.md#routing).
+
+Bootstrap is **non-interactive**: it runs straight through, prompts the user for nothing, and ends with the first watcher dispatched. The first review the watcher sees triggers `/muggle-do`, where working-tree validation surfaces (via the existing E2E stage / muggle-test).
+
+## Turn preamble
+
+```
+**muggle-pr-followup bootstrap** — seeding state for <owner>/<repo>#<n>.
+```
+
+## Input
+
+`$ARGUMENTS = <pr-url> [--slug=<name>] [--resume]`
+
+- `<pr-url>` matches `https?://github\.com/[^/]+/[^/]+/pull/\d+` — required.
+- `--slug=<name>` overrides the default `<repo>-pr<n>` slug.
+- `--resume` opts into refreshing an existing slot instead of refusing on conflict.
+
+## Procedure
+
+### Step 1 — Parse the URL
+
+Extract `<owner>`, `<repo>`, `<pr-number>`. On malformed input, exit with the malformed-URL abort from [`output-templates/bootstrap.md`](output-templates/bootstrap.md).
+
+### Step 2 — Fetch PR metadata
+
+Per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md).
+
+If `state` is `MERGED` or `CLOSED`, exit with the terminal-PR abort. If the `gh` call fails (not found, auth missing), surface the underlying error verbatim and exit.
+
+### Step 3 — Verify the working tree
+
+Per [`../_shared/github-cli-recipes/verify-working-tree.md`](../_shared/github-cli-recipes/verify-working-tree.md). On any check failure, exit with the wrong-working-tree abort.
+
+### Step 4 — Resolve the slug
+
+Default: `<repo>-pr<n>` (e.g. `muggle-ai-works-pr154`). Override: `--slug=<name>`. Session dir is `.muggle-do/sessions/<slug>/` relative to the caller's working tree.
+
+### Step 5 — Idempotency check
+
+If `.muggle-do/sessions/<slug>/` exists:
+
+- Without `--resume` → exit with the slot-conflict abort. Both remedies (delete + re-run, or pass `--resume`) are spelled out in the message.
+- With `--resume` → refresh `prs.json[0].head_sha` to the current `headRefOid` from Step 2. Leave `last_seen.json`, `state.md`, and everything else untouched. Skip to Step 8 (no need to re-seed; no need to refetch the cursor).
+
+### Step 6 — Resolve the initial cursor
+
+Fetch reviews per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md) with cursor 0, then take `max(id)`. If none, the cursor is 0. The watcher only acts on `id > cursor`, so this pins forward-only.
+
+### Step 7 — Seed state files
+
+Identify the loop user once per [`../_shared/github-cli-recipes/loop-user-identity.md`](../_shared/github-cli-recipes/loop-user-identity.md); cache in `state.md`.
+
+Write under `.muggle-do/sessions/<slug>/`:
+
+**`prs.json`** — see [`state-schemas.md`](state-schemas.md#prsjson). One entry, `state` = `"open"`, `head_sha` from Step 2's `headRefOid`.
+
+**`last_seen.json`** — see [`state-schemas.md`](state-schemas.md#last_seenjson). One key (`"<owner>/<repo>#<n>"`), `reviewId` from Step 6, `last_pushed_sha: null`, `idle_tick_count: 0`, `cycles_completed: 0`, `escalated_review_ids: []`, `pushed_shas: []`.
+
+**`state.md`** — see [`state-schemas.md`](state-schemas.md#statemd). `Bootstrapped from URL: yes`. Cache the loop-user login.
+
+Do **not** write `cycle.json` or `requirements.md` — those files are no longer part of the session slot.
+
+Create `iterations/` subdir (empty) for future caller use.
+
+### Step 8 — Dispatch the first watcher
+
+The last action of this turn:
+
+```
+/loop 1m /muggle:muggle-pr-followup <slug> <n>
+```
+
+### Step 9 — Print the success summary
+
+Use the success-summary template from [`output-templates/bootstrap.md`](output-templates/bootstrap.md). Print it **before** the `/loop` dispatch so it's visible.
+
+### Step 10 — Emit telemetry
+
+Emit one event per [`../_shared/telemetry-events/pr-followup-bootstrap.md`](../_shared/telemetry-events/pr-followup-bootstrap.md). `caller = "user"` for direct invocation. Fire-and-forget per [`../_shared/telemetry-emit.md`](../_shared/telemetry-emit.md).
+
+## Invariants
+
+- All state writes happen in Step 7 — earlier aborts leave nothing on disk.
+- If Step 7 fails mid-write, surface the OS error and tell the user to `rm -rf <slot>` and re-run; do not dispatch the watcher.
+- Bootstrap never retries.