@muggleai/works 4.13.1 → 4.15.0

package/dist/plugin/skills/do/e2e-acceptance.md

@@ -58,7 +58,7 @@ For a `local-e2e` block, use `localUrl`, `projectId`, and the working-tree path
 
 Before launching the local runner:
 
-1. **Dev-server + backend readiness** — per [`../_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md) (port + compile log + backend health). Halt on any failure.
+1. **Dev-server + backend readiness** — invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md), the readiness/service-start owner (idempotent fast-exit when healthy; probes via `dev-server-readiness.md`). Halt on failure.
 2. **Auth** — `muggle-remote-auth-status` must be `authenticated`; else escalate.
 3. **Identity tenant/domain match** — if test credentials were marked `existing`, confirm the repo's configured identity tenant/domain matches the recorded tenant/domain. Mismatch → halt.
 
@@ -96,71 +96,11 @@ Based on the changed files and the requirements goal, determine which test cases
 - Test cases that cover areas potentially affected by the changes
 - When in doubt, include the test case (better to over-test than miss a regression)
 
-### Step 4: Execute Tests Locally
+### Step 4: Run the dev loop, publish, gather screenshots
 
-For each relevant test case:
+For each relevant test case, run the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): `muggle-remote-test-script-list` by `testCaseId` to pick [replay vs regen](../_shared/dev-loop/run.md), [execute with `timeoutMs`](../_shared/dev-loop/timeouts.md), [fetch the result](../_shared/dev-loop/failures.md) and [interpret failures](../_shared/dev-loop/failures.md), [publish](../_shared/dev-loop/publish.md), and gather [per-step screenshots](../_shared/dev-loop/publish.md).
 
-1. Call `muggle-remote-test-script-list` filtered by `testCaseId` to check for an existing script.
-
-2. **If a script exists** (replay path):
-   - `muggle-remote-test-script-get` with `testScriptId` → note `actionScriptId`
-   - `muggle-remote-action-script-get` with that id → full `actionScript`
-   - **Use the API response as-is.** Do not edit, shorten, or rebuild `actionScript`; replay needs full `label` paths for element lookup.
-   - `muggle-local-execute-replay` with:
-     - `testScript`: the full script object
-     - `actionScript`: the full action script object (from `muggle-remote-action-script-get`)
-     - `localUrl`: the resolved local URL
-     - `timeoutMs`: `600000` (10 min) or `900000` (15 min) for complex flows
-
-3. **If no script exists** (generation path):
-   - `muggle-remote-test-case-get` with `testCaseId` to fetch the full test case object.
-   - `muggle-local-execute-test-generation` with:
-     - `testCase`: the full test case object
-     - `localUrl`: the resolved local URL
-     - `timeoutMs`: `600000` (10 min) or `900000` (15 min) for complex flows
-
-4. When execution completes, call `muggle-local-run-result-get` with the `runId` returned by the execute call.
-
-5. **Retain per test case:** `testCaseId`, `testScriptId` (if present), `runId`, `status` (passed/failed), `artifactsDir`.
-
-### Local Execution Timeout (`timeoutMs`)
-
-The MCP client often uses a **default wait of 300000 ms (5 minutes)**. **Exploratory script generation** (identity login, multi-step app flows, many LLM iterations) routinely **runs longer than 5 minutes** while Electron is still healthy.
-
-- **Always pass `timeoutMs`** — `600000` (10 min) or `900000` (15 min) — unless the test case is known to be simple.
-- If the tool reports **`Electron execution timed out after 300000ms`** but Electron logs show the run still progressing (steps, screenshots, LLM calls), treat it as **orchestration timeout**, not an Electron app defect: **increase `timeoutMs` and retry**.
-
-### Interpreting Failures
-
-- **`Electron execution timed out after 300000ms`:** Orchestration wait too short — see `timeoutMs` above.
-- **Exit code 26** (and messages like **LLM failed to generate / replay action script**): Often corresponds to a completed exploration whose **outcome was goal not achievable** (`goal_not_achievable`, summary with `halt`). Use `muggle-local-run-result-get` and read the **summary / structured summary**; do not assume an Electron crash.
-- **Fix for precondition failures:** Choose a project/account that already has the needed state, or narrow the test goal so generation does not try to create resources from scratch unless intentional.
-
-### Step 5: Publish Test Scripts
-
-After each test execution completes (whether pass or fail):
-
-1. Call `muggle-local-publish-test-script` with:
-   - `runId`: the run ID from execution
-   - `cloudTestCaseId`: the test case ID
-
-2. **Retain from publish response:**
-   - `testScriptId`: the cloud test script ID
-   - `viewUrl`: the URL to view the run on muggle-ai.com
-
-This ensures all screenshots are uploaded to the cloud and accessible via URLs for PR comments.
-
-### Step 6: Fetch Screenshot URLs
-
-For each published test script:
-
-1. Call `muggle-remote-test-script-get` with the `testScriptId` from publish.
-
-2. Extract from the response:
-   - `steps[].operation.screenshotUrl`: cloud URL for each step's screenshot
-   - `steps[].operation.action`: the action description for each step
-
-3. **Retain per test case:** array of `{ stepIndex, action, screenshotUrl }`.
+Inputs to the loop: `mode` from the script-exists check, `localUrl`/project from Step 1.7, `cwd` = the working tree recorded in `state.md`.
 
 ### Step 7: Collect Results
 
@@ -216,8 +156,7 @@ For each test case:
 ## Non-negotiables
 
 - No silent auth skip; always verify with `muggle-remote-auth-status` first.
-- Replay: never hand-build or simplify `actionScript` — only use full response from `muggle-remote-action-script-get`.
-- Always pass `timeoutMs` for execution calls; do not rely on default 5-minute timeout.
+- Replay/timeout/result discipline per [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md) — never hand-build `actionScript`, always pass `timeoutMs`, read structured run-result fields.
 - No hiding failures: surface errors, exit codes, and artifact paths.
 - In `local-e2e` mode, every relevant test case must be executed — generate a new script if none exists (no skips).
 - Always publish after execution to ensure screenshots are cloud-accessible for PR comments.

package/dist/plugin/skills/do/fix-ci.md

@@ -0,0 +1,60 @@
+# Fix-CI (watcher-dispatched)
+
+Resolve red CI on a PR's head — lint/format, typecheck, and failing unit tests — verifying green before re-push. A dumb-pipe dispatch like address-reviews: the executor receives a PR URL, slug, and the failing check names, and fixes them — it owns the fix, not the decision to dispatch.
+
+## Turn preamble
+
+```
+**/muggle-do fix-ci** — fixing <count> red check(s) on <owner>/<repo>#<n>.
+```
+
+## Input
+
+`$ARGUMENTS` carries a `github.com/.../pull/<n>` URL, `slug=<slug>`, and the failing check names (no review ids). Parse all three.
+
+## Inputs from disk
+
+From `~/.muggle-ai/muggle-do/sessions/<slug>/`: `prs.json` (PR + local checkout / branch), `last_seen.json` (`ci_fix_attempts`, `ci_escalated_shas`, `pushed_shas`), `state.md` (worktree path, validation strategy).
+
+## Procedure
+
+### Step 1 — Re-attach
+
+Check out the PR branch in the session's working tree (per `state.md`). Capture `red_sha = prs.json[0].head_sha`.
+
+### Step 2 — Map each failing check to a local command
+
+Per [`../_shared/ci-check-to-command.md`](../_shared/ci-check-to-command.md). Fix the in-scope checks in the working tree; record out-of-scope checks for escalation (Step 6).
+
+### Step 3 — Verify before push
+
+- Build (typecheck + lint on the changed surface) + unit suite must pass.
+- Run E2E (per [`../muggle-preferences/preference-gates/autoE2ETest.md`](../muggle-preferences/preference-gates/autoE2ETest.md)) only if the fix touched app logic; lint/format-only fixes skip E2E.
+
+A fix that can't be made green locally is not pushed → Step 6.
+
+### Step 4 — Commit + push
+
+Commit per the `fix(ci): <check> — <what>` convention ([`../_shared/pr-followup-helpers/reply-routing.md`](../_shared/pr-followup-helpers/reply-routing.md)). Push. Append the new SHA to `last_seen.pushed_shas`. **No PR replies** — the fix commit is the response.
+
+### Step 5 — Update state + respawn
+
+- Increment `last_seen.ci_fix_attempts[red_sha]`.
+- Respawn the watcher: `/loop 1m /muggle:muggle-pr-followup <slug> <n>`. CI on the new SHA is the verify loop — a still-red SHA returns as a fresh dispatch, bounded by the per-SHA fix budget (Step 6).
+
+### Step 6 — Escalate (budget spent or out of scope)
+
+When the failing checks are all out of scope, or `ci_fix_attempts[red_sha]` has reached 3 with CI still red:
+
+1. Add `red_sha` to `last_seen.ci_escalated_shas` so the SHA is not re-fixed.
+2. Emit one terminal message naming the unresolved checks.
+3. Emit the cycle event with `outcome: "ci-escalated"` (Step 7). Do not loop further on this SHA.
+
+### Step 7 — Telemetry
+
+Emit one `muggle-do:cycle` event ([`../_shared/telemetry-events/muggle-do-cycle.md`](../_shared/telemetry-events/muggle-do-cycle.md)): `outcome: "ci-fixed"` when a fix pushed, `"ci-escalated"` when escalated — with `ci_checks_in` / `ci_checks_fixed` / `ci_checks_escalated`.
+
+## Guardrails
+
+- Max 3 fix attempts per SHA; out-of-scope checks escalate immediately rather than churn.
+- No PR replies; the fix commit is the response.

package/dist/plugin/skills/do/input-routing.md

@@ -0,0 +1,12 @@
+# Input routing
+
+How `/muggle-do` resolves `$ARGUMENTS` to a mode. Modes 1–3 are programmatic — dispatched by the watcher — so never ask on those. Inspect in order:
+
+1. **Address-reviews** — a `github.com/.../pull/<n>` URL **and** one or more review ids (integers ≥ 100000000) → [`address-reviews.md`](address-reviews.md).
+2. **Fix-CI** — a `github.com/.../pull/<n>` URL **and** a `fix ci` / `fix-ci` directive with failing check names (no review ids) → [`fix-ci.md`](fix-ci.md).
+3. **Post-merge cleanup** — a `cleanup` token and `slug=<slug>` (no PR URL, no review ids) → [`cleanup.md`](cleanup.md).
+4. **Empty / `help` / `menu` / `?`** → menu + session selector.
+5. **Task automation** (perform an action on a website) → `muggle:muggle-browser-task`.
+6. **Otherwise** → forward pipeline at Stage 1.
+
+When in doubt between #5 and #6, ask one question.

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

@@ -40,13 +40,13 @@ Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fres
 
 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):
+Write `~/.muggle-ai/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`.
+Seed `~/.muggle-ai/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.
 
@@ -71,7 +71,7 @@ If `prs.json` is empty, **do not dispatch** — record the reason in `result.md`
 
 ## 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).
+Gated by `autoCleanup`. Triggered when the watcher's terminal tick observes the merge and dispatches `/muggle-do`'s cleanup directive ([`../cleanup.md`](../cleanup.md)) — never from this stage. See [`../../_shared/post-merge-cleanup.md`](../../_shared/post-merge-cleanup.md).
 
 Append one short reminder tied to the gate value:
 

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

@@ -13,7 +13,7 @@ Does **not** create a PR, seed session state, or dispatch a watcher (`/muggle-do
 ## Inputs
 
 - Per-repo: path, branch (head ref name).
-- The existing PR URL + number from `.muggle-do/sessions/<slug>/prs.json`.
+- The existing PR URL + number from `~/.muggle-ai/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

package/dist/plugin/skills/do/pre-flight.md

@@ -26,8 +26,8 @@ Before asking anything, gather every fact you can resolve without the user:
 
 1. **Candidate repo(s).** Match keywords in the task description against configured repo names. If one repo is an obvious match, propose it as the default; if two or three are plausible, list them.
 2. **Current branch and default branch** for each candidate repo. Run `git -C <repo> symbolic-ref refs/remotes/origin/HEAD --short` and `git -C <repo> branch --show-current`. If the current branch is the default, the pre-flight must collect a new branch name.
-3. **Running dev server.** Detect listening ports and reconcile env-file URL/port using [`../_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md).
-4. **Running backend.** Probe backend health per [`../_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md) ("Backend health"). Note up/down.
+3. **Local environment readiness.** Invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md) — the owner of dev-server/backend detection and service start (idempotent; it probes via `dev-server-readiness.md` internally). Use what it reports as the dev-server/URL pre-flight signal.
+4. **Backend health.** Covered by the same `muggle-test-prepare` invocation above (it probes backend health); note up/down.
 5. **Muggle Test MCP auth.** Call `muggle-remote-auth-status`. If expired, you will ask to re-auth in the questionnaire.
 6. **Candidate Muggle Test projects.** Call `muggle-remote-project-list` and rank by semantic match against the task description and the repo's dev URL.
 7. **Existing test-user secrets.** For each candidate Muggle Test project, call `muggle-remote-secret-list` and note whether `managed_profile_email` / `managed_profile_password` exist.
@@ -55,7 +55,7 @@ Present **one `AskUserQuestion`** (or the platform's structured-selection equiva
 8. **Test-user credentials** — only if validation is Local E2E AND the Auth0 tenant in the repo differs from the tenant the managed secrets were created under. Options: "Reuse existing secrets (may fail if tenant mismatch — will surface failure)" / "Create new secrets for this tenant (provide email + password)" / "Switch to staging replay".
 9. **PR target branch** — default: the repo's default branch. "Use default" / "Target a different branch".
 10. **Re-auth Muggle Test MCP?** — only if auth was missing/expired. "Log in now" / "Abort".
-11. **Worktree for this change?** — gate: [`autoUseWorktree`](../muggle-preferences/preference-gates/autoUseWorktree.md). Options: create a sibling worktree, or work in the current checkout.
+11. **Worktree for this change?** — gate: [`autoUseWorktree`](../muggle-preferences/preference-gates/autoUseWorktree.md). Options: create a dedicated worktree (per [`../_shared/use-worktrees.md`](../_shared/use-worktrees.md)), or work in the current checkout.
 12. **Rebase onto `origin/<default>` first?** — gate: [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), only if `behind > 0`. Options: rebase before stage 6, or run as-is.
 13. **Run E2E at the end of every cycle?** — gate: [`autoE2ETest`](../muggle-preferences/preference-gates/autoE2ETest.md), only if step 10's silent detection resolved to `ask`. Options: always run stage 6, or ask each cycle.
 

package/dist/plugin/skills/mbt/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: mbt
+description: Explicit short alias for the `muggle-browser-task` skill. ONLY invoke when the user explicitly types `mbt` or `/mbt` — never auto-trigger from any other phrasing.
+---
+
+# mbt — alias for muggle-browser-task
+
+Invoke the `muggle-browser-task` skill via the Skill tool. Forward any user-provided arguments unchanged.

package/dist/plugin/skills/mdo/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: mdo
-description: Explicit short alias for the `muggle-do-task` skill. ONLY invoke when the user explicitly types `mdo` or `/mdo` — never auto-trigger from any other phrasing.
+description: Explicit short alias for the `muggle-do` skill. ONLY invoke when the user explicitly types `mdo` or `/mdo` — never auto-trigger from any other phrasing.
 ---
 
-# mdo — alias for muggle-do-task
+# mdo — alias for muggle-do
 
-Invoke the `muggle-do-task` skill via the Skill tool. Forward any user-provided arguments unchanged.
+Invoke the `muggle-do` skill via the Skill tool. Forward any user-provided arguments unchanged.

package/dist/plugin/skills/mprfollowup/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: mprfollowup
+description: Explicit short alias for the `muggle-pr-followup` skill. ONLY invoke when the user explicitly types `mprfollowup` or `/mprfollowup` — never auto-trigger from any other phrasing.
+---
+
+# mprfollowup — alias for muggle-pr-followup
+
+Invoke the `muggle-pr-followup` skill via the Skill tool. Forward any user-provided arguments unchanged.

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

@@ -37,6 +37,7 @@ If the user intent clearly matches one command, route directly — no menu neede
 - test localhost/validate single feature/test a feature → `muggle-test-feature-local`
 - build/implement from request/end-to-end → `muggle-do`
 - post results to PR/attach walkthrough/visual evidence on PR → `muggle-pr-visual-walkthrough`
+- watch my PR for reviews/follow up on PR reviews/babysit PR review thread → `muggle-pr-followup`
 - give feedback on a run/the test was wrong/step N didn't work/show my feedback/delete feedback → `muggle-feedback`
 
 If intent is ambiguous, use `AskUserQuestion` with the most likely options rather than asking the user to type a clarification.

package/{plugin/skills/muggle-do-task → dist/plugin/skills/muggle-browser-task}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: muggle-do-task
+name: muggle-browser-task
 description: Run a browser automation task on a website using natural language. Finds or creates the Muggle Test project, use case, test case, and script, then executes locally via the electron app. Use when the user wants to perform an action on a website (post, fill a form, click through a flow) rather than implement a code change.
 ---
 

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

@@ -25,32 +25,51 @@ Runs an autonomous dev cycle from requirements to PR. **Fire and review:** user
 
 Stage 7 dispatches one watcher per opened PR as its last action.
 
+## Execution protocol (non-negotiable)
+
+The pipeline table lists **pointers, not summaries**. Open each stage's file and execute from it — running a stage off its one-line row here is how tests, E2E, and session state get silently skipped. If you have not read a stage's file this run, you have not run that stage.
+
+**Bootstrap before any code, in order:**
+1. Emit telemetry — [`../_shared/telemetry-emit.md`](../_shared/telemetry-emit.md), `skillName: "muggle-do"`.
+2. Create `~/.muggle-ai/muggle-do/sessions/<slug>/` with `state.md` + `iterations/001.md` (pre-flight owns this; do it even when running unattended).
+3. `TodoWrite` one item per stage 1–8 — these stages are the checklist; never swap in your own decomposition.
+
+**Per stage:** read the file → execute it → append a marker to `iterations/<NNN>.md` citing the evidence that file requires (jest exit code, E2E verdict + `runId`, screenshot path). A stage is done only when its evidence is written, never on recollection.
+
+### "Autonomous" / "without my intervention" collapses exactly one thing
+Best-effort the Stage-1 questionnaire and don't ask. It does **not** license skipping telemetry, session artifacts, requirements, unit tests, E2E (`autoE2ETest` defaults to `always`), browser verification, the gate below, or the watcher hand-off. Run the whole pipeline silently — never a shortcut.
+
+### Definition of Done — gate before Stage 7
+Do not create or update a PR until each line holds, or is waived by a one-line reason written into `state.md` (silence is not a waiver):
+- `requirements.md` written (forward runs)
+- Build clean — typecheck + lint on changed files
+- New/changed logic carries unit tests (authored in Stage 3; Stage 5 only runs the suite)
+- Unit suite run, PASS recorded
+- E2E verdict recorded with `runId` per `autoE2ETest` — or `[E2E FAILING]` / `SKIPPED` + reason
+- UI changes verified in a real browser with evidence (screenshot path or muggle `runId`); `curl` + `grep` is not verification
+
+Opening a PR with an unchecked, unwaived line is a cycle failure.
+
 ## Address-reviews flow
 
 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.
 
 ## Input routing
 
-Inspect `$ARGUMENTS` in this order:
-
-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.
-
-When in doubt between #3 and #4, ask one question.
+`/muggle-do` serves one interactive mode (the forward pipeline, from a fresh task) and three programmatic modes the watcher dispatches (address-reviews, fix-ci, post-merge cleanup). Resolve `$ARGUMENTS` to a mode per [`../do/input-routing.md`](../do/input-routing.md) before doing anything else.
 
 ## Preferences
 
 | Preference | Gate |
 | :--------- | :--- |
 | `autoE2ETest` | Stage 6 — run E2E every cycle (default `always`), or fold into pre-flight |
+| `autoResolveConflicts` | On rebase conflict — resolve autonomously behind a verify-or-rollback gate (opt-in), or abort + escalate (default `never`) |
 
-`autoUseWorktree`, `autoRebase`, `autoCreatePR`, `autoCleanup` fire from per-stage files.
+`autoUseWorktree`, `autoRebase`, `autoResolveConflicts`, `autoCreatePR`, `autoCleanup` fire from per-stage files.
 
 ## Session model
 
-`.muggle-do/sessions/<slug>/`. Schemas: [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md).
+`~/.muggle-ai/muggle-do/sessions/<slug>/`. Schemas: [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md).
 
 | File | Owner |
 | :--- | :---- |

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

@@ -1,6 +1,6 @@
 ---
 name: muggle-feedback
-description: Capture feedback on a generated Muggle Test action script — either step-level or whole-script — and submit it so the system can analyze it and regenerate affected scripts. Use when the user has just run a Muggle Test (local or remote) and wants to flag what went wrong, when they paste a Muggle dashboard URL with a test script or run, or when they want to view or delete previously submitted feedback. Triggers on: '/muggle-feedback', 'give feedback on this run', 'the test was wrong', 'step N didn't work', 'the script clicked the wrong button', 'flag this run', 'the summary is wrong', 'show my feedback', 'list feedback', 'delete that feedback'. Skill auto-detects the run context from a recent local run, a remote run, or a Muggle dashboard URL in the prompt.
+description: Use when the user wants to flag that a generated Muggle Test action script — or one specific step in it — did the wrong thing, and have it captured so Muggle can analyze and regenerate affected scripts. Covers any report that a script or step is wrong, broken, or misbehaving (clicked the wrong element, bad summary, "step N didn't work", "broken at the submit step"), whether the user just ran a test locally or remotely or pastes a Muggle dashboard run/script URL and points at what failed. Also use to view, list, or delete previously submitted feedback. Triggers on '/muggle-feedback', 'give feedback on this run', 'the test was wrong', 'flag this run', 'show/list/delete my feedback'. Auto-detects run context from a recent local run, a remote run, or a dashboard URL in the prompt.
 ---
 
 # Muggle Test Feedback

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

@@ -1,6 +1,6 @@
 # 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.
+This folder holds the watcher loop for PR review follow-ups. The watcher is a **dumb pipe**: it polls for new submitted reviews and CI checks and dispatches `/muggle-do` when there's review feedback or fixable red CI. 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
 
@@ -8,6 +8,8 @@ This folder holds the watcher loop for PR review follow-ups. The watcher is a **
 - [`auto-track.md`](auto-track.md) — the no-args procedure: discovers PRs pushed this session (any repo) and seeds one poll-only watcher each. Seeds no E2E context — the watcher only watches.
 - [`bootstrap.md`](bootstrap.md) — the bootstrap procedure (asks once for the E2E validation context, seeds state, dispatches the first watcher).
 - [`contract.md`](contract.md) — the watcher per-tick procedure (poll → dispatch → exit).
+- [`finalize.md`](finalize.md) — shared termination sequence for a terminal PR (mark terminal, `result.md`, log/telemetry, unschedule cron, post-merge cleanup handoff). Called by `contract.md` and `reconcile.md`.
+- [`reconcile.md`](reconcile.md) — sweep that finalizes slots whose PR went terminal while polling lapsed; runs at the top of auto-track and on demand.
 - [`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/`.
 
@@ -21,7 +23,4 @@ Shared with other skills, under `../_shared/`:
 - [`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 per-round stage that nudges the reviewer to resolve addressed-but-still-open threads.
+Callers (e.g. `/muggle-do`) reference this folder, not the reverse — see [`../CLAUDE.md`](../CLAUDE.md) for the one-way-dependency rule.

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

@@ -1,14 +1,13 @@
 ---
 name: muggle-pr-followup
-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. Run it with no args to auto-track every PR you pushed this session (poll-only watchers, any repo). 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 (asks once for the E2E validation context, then runs unattended).
-disable-model-invocation: true
+description: Use this skill when the user wants a pull request's incoming review feedback handled for them — it watches one PR's review thread and, each time a reviewer submits new comments, dispatches the work to address them. Engage on PR-review-follow-up intent: "watch my PR and address review comments as they come in", "keep an eye on PR #123 and respond to reviewer feedback", "follow up on my PR's reviews", "babysit my PR's review thread", "auto-handle reviews on the PR I just opened", "I'm stepping away — handle my PR's reviews while I'm gone". Run with no args to track every PR you pushed this session (any repo); pass a PR URL to start watching a specific one. This is PR-review-specific automation: when the recurring thing the user wants handled is a PR's review comments, use this — not the generic `loop` skill. It only watches and dispatches; the actual edits and replies are `muggle-do`. Not for posting test results to a PR (use muggle-pr-visual-walkthrough).
 ---
 
 # muggle-pr-followup
 
 > Telemetry first step: see [`../_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-followup"`.
 
-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.
+A watcher that babysits one open PR's review thread and CI. Polls for new submitted reviews and check-run state; when review feedback lands or CI goes red, hands the work to `/muggle-do` and exits. On merge, it hands off post-merge cleanup to `/muggle-do` the same way. `/muggle-do` is the executor — it classifies the reviews or fixes the failing checks, pushes, replies per comment, and respawns the watcher.
 
 **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.
 
@@ -27,6 +26,9 @@ The skill recognizes its mode by inspecting `$ARGUMENTS` and falling back to on-
 | `<pr-number>` alone | zero or multiple matches | **error:** ambiguous; list candidates and exit |
 | empty | — | **auto-track** → [`auto-track.md`](auto-track.md) |
 | `help` / `?` | — | **help:** list active loops per [`output-templates/help.md`](output-templates/help.md) |
+| `reconcile` / `sweep` (optional `<slug>`) | — | **reconcile** → [`reconcile.md`](reconcile.md) |
+
+Auto-track runs **reconcile** first, so a no-arg invocation also finalizes any slot whose PR merged or closed while its watcher was down (expired cron, ended session). Reconcile never re-arms a watcher.
 
 Bootstrap accepts three optional trailing flags:
 

package/dist/plugin/skills/muggle-pr-followup/auto-track.md

@@ -2,7 +2,7 @@
 
 The procedure for the **auto-track mode** of `muggle-pr-followup` — invoked when the skill is dispatched with **no arguments**. Routing is in [`SKILL.md`](SKILL.md#routing).
 
-Auto-track discovers the PRs you pushed or opened during this Claude Code session — across **any repo** — and starts one **poll-only watcher** per PR. The watcher only watches: it seeds nothing about E2E. Running and posting E2E is `/muggle-do`'s job; a watcher with no validation context yields a `SKIPPED` E2E verdict when `/muggle-do` runs — see [`../do/e2e-acceptance.md`](../do/e2e-acceptance.md) Step 0.
+Auto-track discovers the PRs you pushed or opened during this Claude Code session — across **any repo** — and starts one **poll-only watcher** per PR. The watcher only watches: it seeds nothing about E2E. Running and posting E2E is `/muggle-do`'s job; a watcher with no validation context yields a `SKIPPED` E2E verdict when `/muggle-do` runs.
 
 ## Turn preamble
 
@@ -16,6 +16,10 @@ Auto-track discovers the PRs you pushed or opened during this Claude Code sessio
 
 ## Procedure
 
+### Step 0 — Reconcile existing slots
+
+Run [`reconcile.md`](reconcile.md) first. A no-arg invocation is the natural moment to finalize any slot whose PR merged or closed while its watcher was down — an expired `/loop` cron or an ended session leaves termination un-run (see reconcile's rationale). Then continue discovering new PRs below.
+
 ### Step 1 — Discover candidate PRs from session context
 
 A PR counts as **pushed this session** if, earlier in this conversation, you:

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

@@ -37,11 +37,13 @@ Per [`../_shared/github-cli-recipes/verify-working-tree.md`](../_shared/github-c
 
 ### 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.
+Default: `<repo>-pr<n>` (e.g. `muggle-ai-works-pr154`). Override: `--slug=<name>`. Session dir is `~/.muggle-ai/muggle-do/sessions/<slug>/` (under the user's home, shared across repos; the slug's repo-pr<n> prefix keeps it unique).
 
 ### Step 5 — Idempotency check
 
-If `.muggle-do/sessions/<slug>/` exists:
+**Legacy-slot migration.** Pre-move sessions lived at the repo-relative `.muggle-do/sessions/<slug>/` ([`state-schemas.md`](state-schemas.md#legacy-location)). If the new home-dir slot is absent but `<working-tree>/.muggle-do/sessions/<slug>/` exists (working tree from Step 3), move it to the new location first — this carries an in-flight watcher's cursor, `escalated_review_ids`, and `pushed_shas` across the upgrade. Bootstrap is the only stage that performs this: it is the one entry point that knows the old repo-relative path (the cwd), and it is the natural re-entry point after a plugin upgrade. A slot that fails to migrate loses nothing durable — GitHub holds the reviews, so a fresh bootstrap (cursor `0`) re-processes them.
+
+If `~/.muggle-ai/muggle-do/sessions/<slug>/` exists (including a slot just migrated above):
 
 - 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` and the cursor untouched. If `state.md` already has a `## Pre-flight answers` block, skip to Step 8; if not (older session), run Step 6.5 to backfill it, then skip to Step 8.
@@ -61,7 +63,7 @@ Capture the fields for Step 7. Do **not** run E2E now — the first watcher tick
 
 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>/`:
+Write under `~/.muggle-ai/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`.
 

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

@@ -1,6 +1,6 @@
 # Watcher Per-Tick Contract
 
-The procedure for the **tick mode** of `muggle-pr-followup` — one polling iteration scoped to one PR. The watcher is a dumb pipe: it polls for new submitted reviews, dispatches `/muggle-do` if there are any, and exits. It does not classify, amend requirements, post replies, run cycles, or escalate.
+The procedure for the **tick mode** of `muggle-pr-followup` — one polling iteration scoped to one PR. The watcher is a dumb pipe: it polls for new submitted reviews and CI checks, dispatches `/muggle-do` if there's review feedback or fixable red CI, and exits. It does not classify, fix, amend requirements, post replies, run cycles, or escalate.
 
 Routing into this mode is documented in [`SKILL.md`](SKILL.md#routing). The architectural rationale lives in the brain doc `architecture/2026-05-08-muggle-do-pr-comment-loop-design.md`.
 
@@ -16,7 +16,7 @@ Routing into this mode is documented in [`SKILL.md`](SKILL.md#routing). The arch
 
 ## Inputs from disk
 
-Read these from `.muggle-do/sessions/<slug>/`:
+Read these from `~/.muggle-ai/muggle-do/sessions/<slug>/`:
 
 - `prs.json` — see [`state-schemas.md`](state-schemas.md#prsjson). The watcher touches the single entry whose `number` matches the dispatched PR number.
 - `last_seen.json` — see [`state-schemas.md`](state-schemas.md#last_seenjson). Keyed by `"<owner>/<repo>#<n>"`.
@@ -33,25 +33,22 @@ Per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recip
 
 If `state` is `MERGED` or `CLOSED`:
 
-1. Mark the entry terminal in `prs.json`.
-2. Write `result.md` per [`state-schemas.md`](state-schemas.md#resultmd).
-3. Append a terminal line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
-4. Emit a `tick` event with `terminal: true` per [`../_shared/telemetry-events/pr-followup-tick.md`](../_shared/telemetry-events/pr-followup-tick.md).
-5. **Cancel the cron schedule that fires this watcher.** `/loop 1m ...` from bootstrap was registered via `CronCreate`; a fixed-interval cron keeps firing regardless of whether the skill re-dispatches. Call `CronList`, find any job whose command ends with `/muggle:muggle-pr-followup <slug> <pr-number>` (exact two-arg match), and `CronDelete` it. No-op if none matches — the tick may have been invoked manually rather than via `/loop`.
-6. Exit. The watcher has now unscheduled itself; no future ticks will fire for this PR.
+1. Finalize the slot per [`finalize.md`](finalize.md) — mark terminal, write `result.md`, log + telemetry, unschedule this watcher's cron.
+2. **If `MERGED`**, hand off post-merge cleanup as the last action of the turn (skip on `CLOSED` — unmerged, leave the branch and any worktree intact):
 
-### Step 3 — Fetch new submitted reviews
+   ```
+   /muggle-do post-merge cleanup slug=<slug>
+   ```
+
+   `/muggle-do` owns the worktree/branch knowledge and honors the `autoCleanup` gate. This is a runtime dispatch, not a doc dependency on `/muggle-do` — see the one-way rule in [`../CLAUDE.md`](../CLAUDE.md).
+3. Exit. The watcher has unscheduled itself; no future ticks fire for this PR.
 
-Per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md). **Also exclude review ids that appear in `last_seen.escalated_review_ids`** — those have already been escalated and the watcher must not re-dispatch them.
 
-### Step 4 — If zero new reviews → idle
+### Step 3 — Fetch new submitted reviews
 
-1. Increment `last_seen.idle_tick_count`.
-2. Append an idle line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
-3. Emit a `tick` event with `idle: true`, `reviews_seen: 0`, `dispatched_review_ids: []`.
-4. Exit. The next tick fires in 1 min via `/loop`.
+Per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md). **Also exclude review ids that appear in `last_seen.escalated_review_ids`** — those have already been escalated and the watcher must not re-dispatch them.
 
-### Step 5 — If one or more new reviews → dispatch
+### Step 4 — If one or more new reviews → dispatch (reviews preempt CI)
 
 The watcher does **not** classify. Classification, batching, replying, escalation, and cycle execution all live in `/muggle-do`. The watcher's job is to hand over the list of new review ids and exit.
 
@@ -67,7 +64,27 @@ The watcher does **not** classify. Classification, batching, replying, escalatio
    ```
 3. Append a dispatching line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
 4. Emit a `tick` event with `reviews_seen: <count>`, `dispatched_review_ids: [<id>, ...]`.
-5. Exit. The cron schedule from bootstrap keeps firing the watcher every minute, so the next tick still arrives even though this turn dispatched `/muggle-do`. The watcher only self-unschedules in Step 2 (terminal).
+5. Exit. **Reviews preempt CI** — when reviews land, this tick dispatches address-reviews and never polls CI. The cron keeps firing; the next tick still arrives. The watcher only self-unschedules in Step 2 (terminal).
+
+### Step 5 — No new reviews → poll CI for the head SHA
+
+Fetch the check-run rollup for `prs.json[0].head_sha` per [`../_shared/github-cli-recipes/pr-checks.md`](../_shared/github-cli-recipes/pr-checks.md), then:
+
+- **Any check still pending** (`bucket == "pending"`) → idle (wait for checks to settle).
+- **All checks green / skipped, or no checks** → idle (green path).
+- **One or more checks red** (`bucket == "fail"`), **and** `ci_fix_attempts[head_sha] < 3`, **and** `head_sha` ∉ `ci_escalated_shas` → dispatch and exit:
+  1. Reset `last_seen.idle_tick_count` to 0.
+  2. Dispatch `/muggle-do` with a *fix-ci* directive carrying the PR URL, slug, and the red check names (no review ids):
+     ```
+     /muggle-do fix ci <check-1> <check-2> ... on <pr-url> slug=<slug>
+     ```
+  3. Append a dispatching line to `followup.log`; emit a `tick` event with `checks_red: <count>`, `dispatched_ci_fix: true`.
+  4. Exit. The next tick re-checks CI on the new head SHA — CI itself is the verify loop.
+- **One or more red, but `ci_fix_attempts[head_sha] >= 3` or `head_sha` ∈ `ci_escalated_shas`** → idle. The fix budget is spent; `/muggle-do`'s fix-ci stage already recorded the escalation. The watcher does not re-dispatch.
+
+### Step 6 — Idle
+
+Any idle branch (Steps 4–5 that did not dispatch): increment `last_seen.idle_tick_count`, append an idle line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md), emit a `tick` event with `idle: true`, `reviews_seen: 0`, `dispatched_review_ids: []`, `checks_red: <count or 0>`, `dispatched_ci_fix: false`. Exit. The next tick fires in 1 min via `/loop`.
 
 ## Output
 

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

@@ -0,0 +1,29 @@
+# Finalize a Terminal PR
+
+The shared, **pure** termination sequence for a follow-up slot whose PR is `MERGED` or `CLOSED`. Called by [`contract.md`](contract.md) Step 2 (a tick observed the transition) and [`reconcile.md`](reconcile.md) (a sweep found a slot whose polling lapsed before the transition). One slot, run once.
+
+This step only finalizes — marks the slot terminal, writes the record, unschedules the cron. It **dispatches nothing**. Post-merge cleanup is a separate, caller-owned concern: the tick ([`contract.md`](contract.md)) hands it off; a reconcile backfill skips it.
+
+## Inputs
+
+- `<slug>`, `<owner>/<repo>`, `<n>` — the slot's PR.
+- `state` — `MERGED` or `CLOSED`, from a fresh [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md).
+- `mergeCommit` + `mergedAt` when `MERGED`.
+
+## Procedure
+
+### Step 1 — Mark the slot terminal
+
+Rewrite `prs.json[0].state` to `merged` / `closed` ([`state-schemas.md`](state-schemas.md#prsjson)). That state plus the `result.md` written next are the terminal marker — there is no separate flag.
+
+### Step 2 — Write `result.md`
+
+Once, per [`state-schemas.md`](state-schemas.md#resultmd). Pull `cycles_completed`, `pushed_shas`, and `escalated_review_ids` from `last_seen.json`.
+
+### Step 3 — Log and telemetry
+
+Append the terminal line per [`output-templates/watcher-log.md`](output-templates/watcher-log.md). Emit one `tick` event with `terminal: true` per [`../_shared/telemetry-events/pr-followup-tick.md`](../_shared/telemetry-events/pr-followup-tick.md).
+
+### Step 4 — Unschedule the cron
+
+Call `CronList`, find any job whose command ends with `/muggle:muggle-pr-followup <slug> <n>` (exact two-arg match), and `CronDelete` it. No-op when none matches — a manually-run tick, or a cron that already expired. Recurring `/loop` crons auto-expire after 7 days; that lapse is the gap [`reconcile.md`](reconcile.md) exists to catch.