@muggleai/works 4.13.1 → 4.15.0

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "4.13.1",
+  "version": "4.15.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "4.13.1",
+  "version": "4.15.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/README.md

@@ -33,7 +33,7 @@ Type `muggle` to discover the full command family.
 | `/muggle:muggle-repair` | Diagnose and fix broken installation automatically. |
 | `/muggle:muggle-upgrade` | Update Electron browser test runner and MCP server to latest version. |
 
-Each skill above also ships a short alias to save typing — `m` (router), `mtest`, `mdo`, `mpr`, `mprefs`, `mstatus`, `mrepair`, `mupgrade`, `mfeedback`, `mimport`, `mtestlocal`, `mtestprep`, `mregen`, `mrelease`. Type `/m` (Claude Code) or `m` (Cursor) to open the menu, or jump straight to one (e.g. `/mtest`).
+Each skill above also ships a short alias to save typing — `m` (router), `mtest`, `mdo`, `mpr`, `mprefs`, `mstatus`, `mrepair`, `mupgrade`, `mfeedback`, `mimport`, `mtestlocal`, `mtestprep`, `mregen`. Type `/m` (Claude Code) or `m` (Cursor) to open the menu, or jump straight to one (e.g. `/mtest`).
 
 ## MCP Tools
 

package/plugin/agents/acceptance-tester.md

@@ -22,6 +22,8 @@ You operate through skills — never call raw MCP tools directly.
 
 Select the skill based on what the orchestrator asks you to do. If the task doesn't clearly map to one skill, ask for clarification.
 
+The run loop these skills execute (replay/regen, timeouts, publish, screenshots) lives in [`../skills/_shared/dev-loop/run.md`](../skills/_shared/dev-loop/run.md) — you reach it through `muggle-test`, never by calling MCP tools yourself.
+
 ## Input Contract
 
 The orchestrator provides a dispatch prompt with:

package/plugin/commands/mbt.md

@@ -0,0 +1,7 @@
+---
+description: Run a browser automation task on a website in natural language (alias for /muggle-browser-task)
+argument-hint: [task description and target site]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-browser-task` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/plugin/commands/mdo.md

@@ -1,7 +1,7 @@
 ---
-description: Run a browser automation task on a website in natural language (alias for /muggle-do-task)
-argument-hint: [task description and target site]
+description: Muggle AI autonomous workflow entry point (alias for /muggle-do)
+argument-hint: [what to build, or a directive]
 allowed-tools: [Skill]
 ---
 
-Invoke the `muggle-do-task` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.
+Invoke the `muggle-do` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/plugin/commands/mprfollowup.md

@@ -0,0 +1,7 @@
+---
+description: Watch a PR for review follow-ups (alias for /muggle-pr-followup)
+argument-hint: [PR url | slug pr-number | empty to auto-track]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-pr-followup` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/plugin/skills/CLAUDE.md

@@ -0,0 +1,15 @@
+# Skill authoring conventions
+
+Rules for every skill under `plugin/skills/`. Read before adding or editing one.
+
+## One-way dependencies — no reverse references
+
+Skill cross-references form a one-way graph. If any file in skill **A** references skill **B** — a markdown link to B's files, or a documented dependency on B's internals — then **no file in B may reference A back**. Reference *downward*, toward the more general / lower-level skill you depend on; pass anything the other direction needs as input, not as a link.
+
+A reverse reference (A → B and B → A) couples the depended-on skill to its caller, creates a cycle no one can reason about in isolation, and makes every edit ripple both ways. The lower-level skill must stay reusable by callers it has never heard of.
+
+**Runtime dispatch is not a doc reference.** A dumb-pipe skill may *fire* another skill's slash command at runtime (hand off and forget) — that is an action, not a dependency. What the rule forbids is a procedure file **linking to** or **encoding the internals of** the skill it hands off to.
+
+**Worked example.** `muggle-pr-followup` (the dumb-pipe watcher) is lower-level than `muggle-do` (the executor that orchestrates it). `muggle-do` references `muggle-pr-followup`; `muggle-pr-followup`'s files must not link back to `muggle-do`. A watcher tick still dispatches `/muggle-do …` at runtime — allowed — but no watcher file links a `do/` file or restates its steps, and shared primitives like `muggle-pr-followup/finalize.md` stay dispatch-free so any caller can reuse them.
+
+When you feel the urge to link "up" to a caller, that is the smell — restructure so the caller passes what is needed in.

package/plugin/skills/_aliases.json

@@ -3,6 +3,7 @@
         "m",
         "mtest",
         "mdo",
+        "mbt",
         "mpr",
         "mprefs",
         "mstatus",
@@ -13,6 +14,6 @@
         "mtestlocal",
         "mtestprep",
         "mregen",
-        "mrelease"
+        "mprfollowup"
     ]
 }

package/plugin/skills/_shared/ci-check-to-command.md

@@ -0,0 +1,10 @@
+# CI check → local fix command
+
+Map a red CI check to the local command that reproduces and fixes it. Repo-agnostic — read the repo's `package.json` scripts; never hardcode script names.
+
+| Failing check | Local action |
+| :------------ | :----------- |
+| lint / format | Run the repo's lint `--fix` / formatter; restage. |
+| typecheck | Run the typecheck script; read the errors; edit the types. |
+| unit / test | Run the suite; read the failures; fix the code or the test. |
+| out of scope — E2E-in-CI, build/deploy infra, flaky / non-deterministic, or unknown | Do **not** attempt; record for escalation. |

package/plugin/skills/_shared/dev-loop/action-script.md

@@ -0,0 +1,3 @@
+# Dev Loop — Action Script
+
+On the replay path use the `muggle-remote-action-script-get` response **as-is** — never edit, shorten, or rebuild `actionScript`; replay needs the full `label` paths for element lookup. For batches, fan the script fetches out in parallel before the sequential execute loop.

package/plugin/skills/_shared/dev-loop/failures.md

@@ -0,0 +1,14 @@
+# Dev Loop — Reading the Result
+
+For each `runId`, call `muggle-local-run-result-get` and read **structured fields**, never `execute`'s stdout tail (a truncated display excerpt). Order: `Status` → `Error` → `Artifacts`. Retain per test case: `testCaseId`, `testScriptId` (if any), `runId`, `status`, `artifactsDir`.
+
+## Artifacts
+
+The `Artifacts` section is present after any completed run; it names `artifactsDir` and lists files. On pass, `results.md` is the step-by-step verdict (read it before summarizing). On failure, `stdout.log` + `stderr.log` are always present; `action-script.json` appears when generation reached step-emission (typical for `goal_not_achievable`); `results.md` and per-step screenshots are absent on the failure path — don't hunt for them.
+
+## Common failures
+
+- `Electron execution timed out after 300000ms` → orchestration wait too short; see [`timeouts.md`](timeouts.md).
+- **Exit code 26** (with "LLM failed to generate / replay action script") is usually a completed exploration whose outcome was **goal not achievable** (`goal_not_achievable`, summary with `halt`) — e.g. asserting "view a completed run" on an account that has none. Read the summary; don't assume a crash. Fix the precondition: pick a project/account that already has the needed state, or narrow the goal so generation isn't forced to create resources from scratch.
+
+Then route via [`../failure-mode-handling.md`](../failure-mode-handling.md).

package/plugin/skills/_shared/dev-loop/fresh-session.md

@@ -0,0 +1,10 @@
+# Dev Loop — Fresh Session
+
+Pass `freshSession: true` for a test case that needs clean browser state (no prior cookies, localStorage, or login):
+
+- Registration / sign-up.
+- Login / authentication when the flow itself is under test (not a test that merely uses login as a prerequisite).
+- Cookie-consent / GDPR first-visit banners.
+- Onboarding / first-run experiences.
+
+Otherwise omit it (defaults `false`, preserving session state). Evaluate per test case — in a batch some need it and some don't.

package/plugin/skills/_shared/dev-loop/publish.md

@@ -0,0 +1,13 @@
+# Dev Loop — Publish & Screenshots
+
+## Publish
+
+After every completed run — pass or fail — publish: failed runs still need cloud-hosted screenshots and per-step actions for the walkthrough, and the upload `status` tells the backend whether to promote the action script as the canonical replay script (pass → promote; fail → record only).
+
+`muggle-local-publish-test-script` with `runId` and `cloudTestCaseId`. Retain `testScriptId`, `actionScriptId`, `viewUrl`. Batch publishes in parallel.
+
+If publish rejects with `has no generated actionScript steps to publish` (a true zero-step run), fall back to `muggle-remote-local-run-upload` with whatever exists (`summaryStep`, `errorMessage`, empty `actionScript`); capture `actionScriptId` and `viewUrl` the same way.
+
+## Screenshots
+
+Per published script, `muggle-remote-test-script-get` with the `testScriptId` from publish → per step `operation.screenshotUrl` and `operation.action`. Retain `{ stepIndex, action, screenshotUrl }`. Batch in parallel. These feed the `E2eReport` consumed by [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) — the dev loop does not post to the PR.

package/plugin/skills/_shared/dev-loop/run.md

@@ -0,0 +1,34 @@
+# Dev Loop — Run a Test
+
+> The local dev loop: run one test case in the browser (replay an existing script, or regenerate from the case), then record the result. Source of truth for the run mechanics; the sibling files in this folder own each invariant. Used by `muggle-test`, `muggle-test-feature-local`, `muggle-do` Stage 6 ([`../../do/e2e-acceptance.md`](../../do/e2e-acceptance.md)), and the `acceptance-tester` agent.
+
+Not owned here — the caller resolves and passes in: which test cases to run, replay-vs-regen classification and failure routing ([`../failure-mode-handling.md`](../failure-mode-handling.md)), dev-server readiness ([`../dev-server-readiness.md`](../dev-server-readiness.md)), validation context ([`../resolve-e2e-validation-context.md`](../resolve-e2e-validation-context.md)), and PR posting ([`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md)).
+
+## Inputs
+
+The caller resolves these before the loop and supplies them per test case:
+
+- `mode` — `replay` or `regen`, already chosen (by the user, or by [`../failure-mode-handling.md`](../failure-mode-handling.md) for change-driven callers).
+- `localUrl` — local execution target. Local-only; never changes the cloud project or test definitions.
+- `cwd` — absolute path of the active working tree (PR-branch worktree if one exists, else repo root). Drives the cross-worktree single-flight lock so concurrent runs serialize.
+- `testCase` / `cloudTestCaseId` — the cloud test case and its id.
+- `showUi` — from the caller's `showElectronBrowser` resolution: omit for visible, `false` for headless.
+
+The tool boundary is fixed: cloud reads (`muggle-remote-*`) resolve definitions and scripts; local tools (`muggle-local-*`) run the browser, fetch results, and publish.
+
+## Sequence
+
+One local browser exists, so **execution is sequential** — one test case at a time, in the caller's order. The pre/post fetches are independent across test cases and should be issued in parallel batches around the sequential execute calls.
+
+Per test case, branch on `mode`:
+
+**Replay**
+1. `muggle-remote-test-script-get` (latest replayable script) → note `actionScriptId`.
+2. `muggle-remote-action-script-get` with that id → full `actionScript` (see [`action-script.md`](action-script.md)).
+3. `muggle-local-execute-replay` with `testScript`, `actionScript`, `localUrl`, `cwd`, `showUi`, `freshSession` (see [`fresh-session.md`](fresh-session.md)), `timeoutMs` (see [`timeouts.md`](timeouts.md)).
+
+**Regen**
+1. `muggle-remote-test-case-get` → full test case object.
+2. `muggle-local-execute-test-generation` with `testCase`, `localUrl`, `cwd`, `showUi`, `freshSession`, `timeoutMs`.
+
+Store the returned `runId`, tagged with its `mode`. If a run fails, log it and continue the batch — never abort. Read the result per [`failures.md`](failures.md), then [`publish.md`](publish.md).

package/plugin/skills/_shared/dev-loop/timeouts.md

@@ -0,0 +1,6 @@
+# Dev Loop — Timeouts
+
+The MCP client default wait is **300000 ms (5 min)**. Exploratory generation (identity login, multi-step flows, many LLM iterations) routinely runs longer while the browser is still healthy.
+
+- **Always pass `timeoutMs`** — `600000` (10 min) or `900000` (15 min) — unless the test case is known simple or the user wants a short cap.
+- `Electron execution timed out after 300000ms` while logs show the run still progressing (steps, screenshots, LLM calls) is an **orchestration timeout, not a browser defect** — increase `timeoutMs` and retry.

package/plugin/skills/_shared/failure-mode-handling.md

@@ -1,6 +1,6 @@
 # Failure-Mode Handling — Shared Reference
 
-> Source of truth for **(a)** the pre-execution replay-vs-regen choice and **(b)** the post-execution failure router used by `muggle-test`, `muggle-test-feature-local`, `muggle-do-task`, and `muggle-test-regenerate-missing`. Skills MUST link here rather than restate the rules.
+> Source of truth for **(a)** the pre-execution replay-vs-regen choice and **(b)** the post-execution failure router used by `muggle-test`, `muggle-test-feature-local`, `muggle-browser-task`, and `muggle-test-regenerate-missing`. Skills MUST link here rather than restate the rules.
 
 ## The contract
 
@@ -55,7 +55,7 @@ Subagents return the verdict as part of a structured block, not free-form prose.
 
 ## A. Pre-execution: replay vs regen (used by `muggle-test`)
 
-Run during change analysis, **per impacted test case**. Picks the initial execution mode before Step 7. Other skills with a single user-picked target (`muggle-test-feature-local`, `muggle-do-task`) skip this section — the user already chose.
+Run during change analysis, **per impacted test case**. Picks the initial execution mode before Step 7. Other skills with a single user-picked target (`muggle-test-feature-local`, `muggle-browser-task`) skip this section — the user already chose.
 
 ### Inputs
 

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

@@ -0,0 +1,22 @@
+# PR check-run rollup
+
+Fetch the CI check state for a PR's head — what the watcher polls to detect red CI.
+
+```bash
+gh pr checks <pr-number> --repo <owner>/<repo> --json name,state,bucket,link
+```
+
+Each row:
+
+- `name` — the check's name (e.g. `lint`, `typecheck`, `unit`, `build`).
+- `state` — `SUCCESS` / `FAILURE` / `PENDING` / `SKIPPED` / `CANCELLED` / `NEUTRAL` (gh folds status + conclusion into one field).
+- `bucket` — `pass` / `fail` / `pending` / `skipping` / `cancel`; the coarse rollup — filter on this.
+- `link` — the check's details URL, for pulling logs in the fix-ci stage.
+
+Classify for the watcher:
+
+- **pending** — any row with `bucket == "pending"`. Checks haven't settled → idle.
+- **red** — any row with `bucket == "fail"` (`state` FAILURE / CANCELLED / TIMED_OUT). Candidate for fix-ci.
+- **green** — every row `pass` / `skipping`, or no rows at all.
+
+The fix-ci dispatch carries the `name`s of the red rows. `gh pr checks` exits non-zero when any check fails — capture output regardless of exit code.

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

@@ -10,6 +10,7 @@ Skills assume a working `gh auth status`. Auth errors surface verbatim from `gh`
 | :----- | :------- |
 | [`pr-metadata`](github-cli-recipes/pr-metadata.md) | Snapshot PR state, head SHA, branch — watcher + bootstrap. |
 | [`submitted-reviews`](github-cli-recipes/submitted-reviews.md) | Fetch reviews past a cursor — watcher's poll. |
+| [`pr-checks`](github-cli-recipes/pr-checks.md) | Check-run rollup for the head SHA — watcher's CI poll. |
 | [`line-comments-for-review`](github-cli-recipes/line-comments-for-review.md) | Pull a review's line comments — `/muggle-do` per-comment routing. |
 | [`unresolved-threads`](github-cli-recipes/unresolved-threads.md) | GraphQL fetch of unresolved comment threads — resolve-reminder. |
 | [`reply-line-comment`](github-cli-recipes/reply-line-comment.md) | POST a threaded reply on a line comment. |

package/plugin/skills/_shared/post-merge-cleanup.md

@@ -5,6 +5,6 @@ Gated by [`autoCleanup`](../muggle-preferences/preference-gates/autoCleanup.md).
 On `always`, the four steps below run as one pre-authorized sequence (no per-step prompts). Stop on the first failure; do not force.
 
 1. `git worktree remove {worktreePath}` — only if a worktree was used.
-2. `git branch -d {branch}` then `git push origin --delete {branch}`.
+2. `git branch -d {branch}` — **skip when no worktree was used**: the branch is the user's current live checkout (a bootstrap/auto-track watcher), and the checked-out branch must never be deleted. Then `git push origin --delete {branch}`.
 3. Clear `.muggle-ai/` session folders for this branch's runs and stale `/tmp/muggle-prepare-*.log` files. Cloud results stay.
 4. Invoke `commit-commands:clean_gone` via the `Skill` tool.

package/plugin/skills/_shared/pr-branch-worktree.md

@@ -4,7 +4,7 @@
 
 ## When this applies
 
-A skill receives a GitHub PR URL of the form `github.com/<org>/<repo>/pull/<n>` and needs the PR's branch checked out to test against it locally.
+A skill receives a GitHub PR URL of the form `github.com/<org>/<repo>/pull/<n>` and needs the PR's branch checked out to test against it locally. For worktree principles (one-per-branch, port/data isolation, teardown) see [`use-worktrees.md`](use-worktrees.md) — this file owns only the materialize-an-existing-PR-branch operation.
 
 ## Steps
 

package/plugin/skills/_shared/rebase-before-e2e.md

@@ -10,6 +10,12 @@ default=$(git symbolic-ref refs/remotes/origin/HEAD --short | sed 's|origin/||')
 behind=$(git rev-list --count "HEAD..origin/${default}")
 ```
 
-Pass `{behind}` and `{default}` to the picker prompts. On `always`, run `git rebase origin/${default}`; stop and report on conflicts — never auto-resolve.
+Pass `{behind}` and `{default}` to the picker prompts. On `always`:
+
+1. Capture the rollback point: `pre_rebase_sha=$(git rev-parse HEAD)`.
+2. `git rebase origin/${default}`.
+3. On conflict, branch by [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md):
+   - `never` (default) → `git rebase --abort`; stop and report, naming the conflicted files. Never auto-resolve.
+   - `always` → hand off to [`resolve-rebase-conflicts.md`](resolve-rebase-conflicts.md) with `pre_rebase_sha`; it resolves, runs the verify-or-rollback gate, and either proceeds or restores `pre_rebase_sha` and escalates.
 
 Stale branches produce false failures and false greens — that's why this gate exists.

package/plugin/skills/_shared/resolve-e2e-validation-context.md

@@ -8,7 +8,7 @@ The sections below are the steps in order: reuse an existing context if one is o
 
 ## Reuse an existing context
 
-If a `## Pre-flight answers` block already exists for this working tree — the current session slot, or the most recent sibling session under `.muggle-do/sessions/*` — fire the [`autoReuseValidationContext`](../muggle-preferences/preference-gates/autoReuseValidationContext.md) gate before gathering anything:
+If a `## Pre-flight answers` block already exists for this working tree — the current session slot, or the most recent sibling session under `~/.muggle-ai/muggle-do/sessions/*` — fire the [`autoReuseValidationContext`](../muggle-preferences/preference-gates/autoReuseValidationContext.md) gate before gathering anything:
 
 - `always` → copy the existing block into this session; skip the questionnaire.
 - `never` → ignore it; run the full gather below.

package/plugin/skills/_shared/resolve-rebase-conflicts.md

@@ -0,0 +1,60 @@
+# Auto-Resolve Rebase Conflicts
+
+The autonomous conflict-resolution body, run when a rebase onto `origin/{default}` reports conflicts **and** [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md) is `always`. Under the default `never` the caller aborts and escalates instead, and this file never runs. The caller hands off the inputs below; this file names no caller — the dependency runs one way.
+
+Contract: never push an auto-resolved rebase that has not passed the verify gate, and always keep the branch restorable to its pre-rebase state.
+
+## Inputs
+
+- `pre_rebase_sha` — branch HEAD captured by the caller **before** `git rebase`; the rollback point.
+- `default` — the branch being rebased onto.
+- Session context: slug, PR url/number, and the persisted validation strategy (for the E2E step).
+
+## Procedure
+
+### Step 1 — Enumerate and classify conflicts
+
+```bash
+git diff --name-only --diff-filter=U
+```
+
+Classify each conflicted path:
+
+- **Mechanical** — lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Cargo.lock`, …), generated output (`dist/`, build artifacts, snapshots), or pure formatting / import-order churn.
+- **Semantic** — anything carrying logic: source, behavior-changing config, tests.
+
+### Step 2 — Resolve
+
+- **Mechanical** → resolve deterministically: regenerate the lockfile with the repo's package manager; regenerate or take-incoming for generated files; run the repo's formatter. Never hand-merge a lockfile.
+- **Semantic** → a reasoned 3-way resolution preserving the intent of **both** sides (ours = the PR's change, theirs = the new default-branch line). If intent in load-bearing logic can't be confidently reconciled, do not guess → Step 5.
+
+Then `git add -A && git rebase --continue`, and repeat Steps 1–2 for each remaining conflicted commit until the rebase completes.
+
+### Step 3 — Verify gate (mandatory)
+
+Each must pass, in order:
+
+1. **Build** — typecheck + lint on the changed surface, per [`../do/build.md`](../do/build.md).
+2. **Unit suite** — per [`../do/unit-tests.md`](../do/unit-tests.md); record PASS.
+3. **E2E** — per [`../do/e2e-acceptance.md`](../do/e2e-acceptance.md) and the persisted [`autoE2ETest`](../muggle-preferences/preference-gates/autoE2ETest.md) strategy. A poll-only session with no validation context reports `SKIPPED`, same as the normal cycle.
+
+### Step 4 — Pass → proceed
+
+Return success. The caller resumes the normal flow; the push happens downstream, so a resolved rebase ships only after it has verified.
+
+### Step 5 — Fail → restore + escalate
+
+On an unreconcilable semantic conflict (Step 2) or any verify failure (Step 3):
+
+```bash
+git rebase --abort 2>/dev/null || true
+git reset --hard <pre_rebase_sha>
+```
+
+The branch is now byte-for-byte its pre-rebase state. Emit one terminal escalation per [`../muggle-pr-followup/output-templates/escalation.md`](../muggle-pr-followup/output-templates/escalation.md) naming the conflicted files and the failing step, plus the `muggle-do:escalation` event with `kind: "rebase-conflict"` ([`telemetry-events/muggle-do-escalation.md`](telemetry-events/muggle-do-escalation.md)). Do not push.
+
+## Invariants
+
+- A push never follows a verify failure.
+- The branch is always restorable to `pre_rebase_sha`.
+- This file runs only under `autoResolveConflicts = always`; `never` is the caller's unchanged abort-and-escalate path.

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

@@ -12,9 +12,12 @@ One per address-reviews invocation, regardless of outcome.
   "review_ids_in": [<int>, ...],
   "review_ids_actionable": [<int>, ...],
   "review_ids_ambiguous": [<int>, ...],
+  "ci_checks_in": ["<check-name>", ...],
+  "ci_checks_fixed": ["<check-name>", ...],
+  "ci_checks_escalated": ["<check-name>", ...],
   "head_sha_before": "<sha-or-null>",
   "head_sha_after": "<sha-or-null>",
-  "outcome": "pushed" | "escalated" | "mixed" | "no-op" | "self-loop-skip"
+  "outcome": "pushed" | "escalated" | "mixed" | "no-op" | "self-loop-skip" | "ci-fixed" | "ci-escalated"
 }
 ```
 
@@ -24,3 +27,7 @@ One per address-reviews invocation, regardless of outcome.
 - `"mixed"` — both branches happened in the same invocation.
 - `"no-op"` — every input id was already in the escalated set; no work.
 - `"self-loop-skip"` — review was a synthetic wrapper around the agent's own reply (every line comment is a reply carrying the loop marker `<!-- muggle-do:bot -->`). Cursor advanced silently; no work, no escalation.
+- `"ci-fixed"` — a watcher-dispatched fix-ci cycle pushed a fix for one or more red checks.
+- `"ci-escalated"` — fix-ci exhausted its 3 attempts for the SHA or the failing checks were out of scope; the SHA was added to `ci_escalated_shas`. No further auto-fix on it.
+
+For fix-ci cycles (`ci-fixed` / `ci-escalated`) the `review_ids_*` arrays are empty and the `ci_checks_*` arrays carry the data: `ci_checks_in` (red checks dispatched), `ci_checks_fixed` (made green and pushed), `ci_checks_escalated` (out-of-scope or unresolved).

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

@@ -9,7 +9,7 @@ Zero or one per address-reviews invocation. Fires when `/muggle-do` emits a term
   "session_slug": "<slug>",
   "repo": "<owner>/<repo>",
   "pr_number": <int>,
-  "kind": "ambiguous-review" | "design-adjustment",
+  "kind": "ambiguous-review" | "design-adjustment" | "rebase-conflict",
   "review_ids": [<int>, ...]
 }
 ```
@@ -17,3 +17,4 @@ Zero or one per address-reviews invocation. Fires when `/muggle-do` emits a term
 `kind`:
 - `"ambiguous-review"` — one or more reviews classified ambiguous in this batch.
 - `"design-adjustment"` — mid-cycle, the work surfaced a design-level conflict.
+- `"rebase-conflict"` — an opt-in auto-rebase hit conflicts that couldn't be resolved and verified; the branch was restored to its pre-rebase SHA. `review_ids` may be empty.

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

@@ -11,6 +11,8 @@ One per watcher iteration (idle or not).
   "pr_number": <int>,
   "reviews_seen": <int>,
   "dispatched_review_ids": [<int>, ...],
+  "checks_red": <int>,
+  "dispatched_ci_fix": true | false,
   "terminal": true | false,
   "idle": true | false,
   "tick_duration_ms": <int>
@@ -19,5 +21,7 @@ One per watcher iteration (idle or not).
 
 - `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.
+- `checks_red`: count of failing checks on the head SHA. `0` when reviews were dispatched (reviews preempt the CI poll) or CI was green/pending.
+- `dispatched_ci_fix`: true when this tick dispatched `/muggle-do` with a fix-ci directive.
 - `terminal`: true when this tick observed the PR merged or closed and wrote `result.md`.
 - `idle`: true when no reviews were dispatched this tick.

package/plugin/skills/_shared/use-worktrees.md

@@ -7,13 +7,14 @@ Use this for feature development, local validation, and PR iteration.
 - **One worktree per branch.** Never switch branches inside a long-lived checkout.
 - **Isolate runtime resources.** Parallel worktrees need unique ports and isolated mutable test state.
 - **Keep worktrees disposable.** Create for focused work, remove after merge.
+- **Existing PR branch?** Materialize it via [`pr-branch-worktree.md`](pr-branch-worktree.md) — same `<repo>/.claude/worktrees/` path scheme, checking out the existing branch instead of creating a new one.
 
 ## Start new change work
 
 1. Update the base branch (usually `main`).
 2. Create a new worktree and branch:
    ```bash
-   git worktree add <repo>-worktrees/<slug> -b <branch>
+   git worktree add <repo>/.claude/worktrees/<sanitized-branch> -b <branch>
    ```
 3. Install dependencies and run setup in that worktree.
 4. Keep all edits and commits for the change in that same worktree.

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

@@ -19,7 +19,7 @@ Exact phrasing comes from the watcher's dispatch (see [`../muggle-pr-followup/co
 
 ## Inputs from disk
 
-Read from `.muggle-do/sessions/<slug>/`:
+Read from `~/.muggle-ai/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.
@@ -27,6 +27,10 @@ Read from `.muggle-do/sessions/<slug>/`:
 
 ## Procedure
 
+### Step 0 — Track the default branch
+
+Before assembling work, rebase onto the latest default branch so the cycle addresses reviews against current master, not a stale base. Run [`../_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md) — gated by [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), fires only when `behind > 0`. Conflict handling follows [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md): the default `never` aborts and escalates (`kind: "rebase-conflict"`); `always` resolves behind the verify-or-rollback gate. If the rebase escalates, stop the cycle — do not push.
+
 ### Step 1 — Assemble the work set
 
 Two sources, combined into one batch (dedupe by comment id):
@@ -63,6 +67,8 @@ The user clarifies on GitHub by submitting a new review. The next watcher tick p
 
 If `actionable_review_ids` is empty, skip the rest of Step 4 and Step 5; proceed to Step 5.5 (resolve-reminder) then Step 6. Otherwise:
 
+Before any edits, ensure the PR's branch workspace is the working directory. If `state.md` carries a `worktreePath` (forward-mode session), use it. Otherwise materialize the PR branch per [`../_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md) — the single owner of checking out a PR branch in isolation — so a bootstrap or auto-track watcher never edits the user's live checkout. If the resolved tree is dirty with unrelated work, escalate per Step 7 rather than editing it.
+
 #### 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.

package/plugin/skills/do/build.md

@@ -20,7 +20,8 @@ For each affected repo:
 1. **Re-read `requirements.md`.** Treat goal + AC as frozen. If something is unclear at this stage, that's a pre-flight bug — escalate, do not improvise.
 2. **Apply the change** in the repo's worktree. Edit existing files first; create new files only when the requirements demand it. Match the surrounding code's style, naming, and file layout.
 3. **Don't add what wasn't asked for.** No speculative abstractions, no extra logging, no "while I'm here" refactors. Three similar lines is better than a premature abstraction.
-4. **Commit** with a conventional-commit subject:
+4. **Cover new logic with tests.** If you added or changed non-trivial logic (a hook, reducer, parser, state machine, branching util), write its unit tests now — Stage 5 only *runs* the suite, it never authors tests. Untested new logic is a Definition-of-Done failure, not a Stage-5 gap.
+5. **Commit** with a conventional-commit subject:
    - `feat(<scope>): <short>` for new behavior
    - `fix(<scope>): <short>` for bug fixes
    - `refactor(<scope>): <short>` for reshape

package/plugin/skills/do/cleanup.md

@@ -0,0 +1,14 @@
+# Post-Merge Cleanup Stage
+
+Invoked by `/muggle-do` when the watcher forwards a PR's terminal (`merged`) state. This stage only resolves the session's workspace and **delegates** teardown to the shared procedure — it does not restate the teardown steps. Never runs while the PR is open.
+
+## Input
+
+`$ARGUMENTS` carries the session slug as `slug=<slug>`. No PR URL, no review ids.
+
+## Procedure
+
+1. Read `~/.muggle-ai/muggle-do/sessions/<slug>/`: `prs.json` (PR `repo`, `number`, observed `state`) and `state.md` (`worktreePath` if a worktree was used, and the target branch `headRefName`).
+2. Confirm `prs.json` shows the PR `merged`. If it is still open or was closed unmerged, do nothing and exit — this stage is post-merge only.
+3. Run [`../_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md) with `{worktreePath}` and `{branch}`. That file owns the teardown sequence **and its safety rules** — including skipping worktree-remove and local branch deletion when no worktree was used. This stage adds no teardown logic of its own.
+4. Append a cleanup line to the session's `followup.log`.

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