@muggleai/works 4.10.0 → 4.11.0

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

@@ -1,34 +1,44 @@
-# E2E / acceptance agent (Stage 6/7)
+# E2E Acceptance Agent (Stage 6)
 
-You are running **end-to-end (E2E) acceptance** test cases against code changes using Muggle AI's local testing infrastructure. These tests simulate real users in a browser — they are not unit tests.
+You are executing E2E acceptance validation for the muggle-do cycle.
+
+Stage 6 of `muggle-do`. Runs browser acceptance tests against code changes and records evidence for downstream PR rendering.
+
+Standalone subagent (different invocation path, used by `muggle-test` Mode C): [`../../agents/acceptance-tester.md`](../../agents/acceptance-tester.md).
 
 ## Turn preamble
 
 Start the turn with:
 
 ```
-**Stage 6/7 — E2E acceptance** — running browser tests against the validation target from pre-flight.
+**Stage 6 — E2E acceptance** — running browser tests against the validation target from pre-flight.
 ```
 
 ## Design
 
-E2E acceptance testing runs **locally** using the `test-feature-local` approach:
+This stage is **mode-driven by pre-flight**:
+
+- `local-e2e` runs the local browser flow (`test-feature-local` approach).
+- `unit-only` or `skip` does not execute browser runs and must emit an explicit non-pass verdict (`SKIPPED` / `UNIT-ONLY` equivalent in downstream reporting).
+- `staging-replay` is not executed in this stage path and should be surfaced as `INCONCLUSIVE` unless the caller has already routed to a dedicated staging runner.
+
+For local runs, the tool boundaries are:
 
 | Scope | MCP tools |
 | :---- | :-------- |
 | Cloud (projects, cases, scripts, auth) | `muggle-remote-*` |
 | Local (Electron run, publish, results) | `muggle-local-*` |
 
-This guarantees E2E acceptance tests always run — no dependency on cloud replay service availability.
+This keeps execution deterministic: local runs do not depend on cloud replay execution availability.
 
 ## Input
 
 You receive everything from `state.md` already — pre-flight resolved it:
 
-- `localUrl` — the locally running dev server URL
-- `projectId` — the chosen Muggle project
+- `localUrl` — the running validation target URL (typically localhost in local mode)
+- `projectId` — the chosen Muggle Test project
 - The validation strategy (`local-e2e`, `staging-replay`, `unit-only`, `skip`)
-- Test-user credential status (existing / new / skip)
+- Test-user credential status (existing / new / skip), when credentials are needed
 - The list of changed repos, files, and a summary of changes
 - The requirements goal
 
@@ -36,23 +46,41 @@ You receive everything from `state.md` already — pre-flight resolved it:
 
 ### Step 0: Consume pre-flight (no user questions)
 
-Read `state.md`. If the validation strategy is `unit-only` or `skip`, **do not run this stage** — skip to stage 7 and record the skip reason. Otherwise use `localUrl` directly; **do not ask the user** for it.
+Read `state.md`. Resolve [`autoE2ETest`](../muggle-preferences/preference-gates/autoE2ETest.md) first — `always` (default, including when unset) runs this stage. `ask` should already have been resolved by pre-flight Q13. Use the resolved validation mode (`local-e2e`, `staging-replay`, `unit-only`, `skip`) to pick execution vs early-exit behavior.
 
-If `localUrl` or `projectId` is missing from `state.md`, that is a pre-flight bug. **Do not paper over it by asking the user** — escalate once with the session path and halt. The fix is to expand `pre-flight.md`, not to grow a new question here.
+Use `localUrl`, `projectId`, and `worktreePath` from `state.md`. Missing any → pre-flight bug; escalate with the session path and halt; do not ask the user.
 
 ### Step 0.5: Pre-flight verification probes
 
-Before launching Electron, run these live checks and fail loudly if any fails:
+Before launching the local runner:
 
-1. `curl -s -o /dev/null -w "%{http_code}" <localUrl>` — expect 2xx or 3xx. If the dev server isn't up, halt with the exact command the user needs to start it.
-2. If a backend URL is recorded, probe its health endpoint. A 5xx or unreachable backend means the dashboard will render in an error state and test results will be meaningless — halt.
-3. `muggle-remote-auth-status` — must be `authenticated`. If not, the pre-flight missed this; escalate.
-4. If test credentials were marked `existing`, confirm the Auth0 tenant in the repo's env matches the tenant the secrets were created under (recorded in `state.md`). Tenant mismatch → halt with "existing secrets target tenant X, local dev targets tenant Y — update pre-flight to collect new credentials."
+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.
+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.
 
 ### Step 1: Authentication already verified
 
 Pre-flight handled auth. If `muggle-remote-auth-status` somehow shows expired here (session clock skew, etc.), re-auth silently via `muggle-remote-auth-login` + `muggle-remote-auth-poll` — but do not ask the user "continue with this account?" again.
 
+If validation is `unit-only` or `skip`, emit a `SKIPPED` report with a one-line reason and exit cleanly.
+
+If validation is `staging-replay`, emit `INCONCLUSIVE` with reason `staging replay not handled in Stage 6 local runner path` and exit cleanly.
+
+### Step 1.5: Placeholder branch detection
+
+Read `pathClassification` from the impact-analysis output (emitted by `do/impact-analysis.md`). If it is `none` — i.e. `git diff <default-branch>...HEAD --stat` was empty after rebase — there is no code under test and running test cases would only re-test master. Write a one-paragraph SKIPPED result to the E2E report (or return a SKIPPED verdict to the caller) and exit the stage cleanly. **Do not** synthesize test cases or run anything.
+
+### Step 1.7: Route + project classification
+
+Consume `pathClassification` from impact-analysis and resolve the dispatch target:
+
+- `surface-a` → use the classification-specific route + project mapping defined by impact-analysis output
+- `surface-b` → use the classification-specific route + project mapping defined by impact-analysis output
+- `mixed` → run once per classification mapping (route + project), or surface as INCONCLUSIVE if running both is over the wall-time budget
+- `none` → already handled in Step 1.5
+
+The `devServerUrl` and project resolved here override any defaults in `state.md` for the remainder of this stage. Treat classification labels as routing hints provided by impact-analysis; do not hardcode product-specific paths in this stage.
+
 ### Step 2: Get Test Cases
 
 Use `muggle-remote-test-case-list` with the project ID to fetch all test cases.
@@ -93,7 +121,7 @@ For each relevant test case:
 
 ### Local Execution Timeout (`timeoutMs`)
 
-The MCP client often uses a **default wait of 300000 ms (5 minutes)**. **Exploratory script generation** (Auth0 login, dashboards, multi-step wizards, many LLM iterations) routinely **runs longer than 5 minutes** while Electron is still healthy.
+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**.
@@ -135,7 +163,7 @@ For each published test script:
 For each test case:
 - Record pass or fail from the run result
 - If failed, capture the error message, failure step index, and `artifactsDir` for local debugging
-- Every test case must be executed — generate a new script if none exists (no skips)
+- In `local-e2e` mode, every relevant test case must be executed — generate a new script if none exists (no skips)
 
 ## Output
 
@@ -160,10 +188,26 @@ For each test case:
   - steps: `[{ stepIndex, action, screenshotUrl }, ...]`
   - artifactsDir: `<path>` (for local debugging)
 
+**Inconclusive:** (count) — use for runs that couldn't yield a pass/fail signal: no replayable script, environment precondition unmet, infra error, agent stalled on auth/cookie banner before reaching the assertion, missing secrets. The product is **not** implicated — that's `failed`, not `inconclusive`.
+- (test case name):
+  - testCaseId: `<id>`
+  - runId: `<id>` (synthesize a UUID if no run started)
+  - viewUrl: `<url>` (project-level run-results fallback when no specific run URL exists)
+  - reason: `<one short sentence>`
+  - steps: `[{ stepIndex, action, screenshotUrl }, ...]` (may be empty)
+
 **Metadata:**
 - projectId: `<projectId>`
 
-**Overall:** ALL PASSED | FAILURES DETECTED
+**Overall:** PASS | FAIL | PARTIAL | INCONCLUSIVE | BLOCKED | SKIPPED — see [`../_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) section F for the canonical taxonomy.
+
+## Hard constraints
+
+- **Do NOT shut down the dev server.** The caller manages dev-server lifecycle.
+- **Do NOT delete or move workspace config/state files** (for example `.muggle-ai/`, `.env.local`, or equivalent runtime config artifacts) in the worktree.
+- **Do NOT call destructive remote MCP tools** — no `*-delete`, `*-revoke`, `*-cancel`, or `*-update` against remote-owned definitions.
+- **One replacement script generation max per stage cycle.**
+- **Honor `wallTimeBudgetSec` from the caller** — on approach, write a PARTIAL report; never silently exceed.
 
 ## Non-negotiables
 
@@ -171,5 +215,6 @@ For each test case:
 - 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.
 - No hiding failures: surface errors, exit codes, and artifact paths.
-- Every test case must be executed — generate a new script if none exists (no skips).
+- 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.
+- **Never drop a test case from the report because it "couldn't run cleanly."** A test that didn't reach its assertion is `inconclusive`, not absent. Dropping it produces misleading verdicts and pushes downstream PR-comment renderers to hand-write the comment — which is the failure mode this stage exists to prevent.

package/dist/plugin/skills/do/impact-analysis.md

@@ -1,4 +1,4 @@
-# Impact Analysis Agent (Stage 3/7)
+# Impact Analysis Agent (Stage 4)
 
 You are analyzing git repositories to determine which ones have actual code changes that need to go through the dev cycle pipeline.
 
@@ -7,7 +7,7 @@ You are analyzing git repositories to determine which ones have actual code chan
 Start the turn with:
 
 ```
-**Stage 3/7 — Impact analysis** — diffing each affected repo against its default branch.
+**Stage 4 — Impact analysis** — diffing each affected repo against its default branch.
 ```
 
 ## Input
@@ -15,22 +15,34 @@ Start the turn with:
 You receive:
 - A list of repos with their local filesystem paths
 - The requirements goal and affected repos from the requirements stage
+- Pre-flight state, including `worktreePath` when a worktree was selected (see [`../_shared/use-worktrees.md`](../_shared/use-worktrees.md))
 
 ## Your Job
 
 For each repo path provided:
 
-1. **Check the current branch:** Run `git branch --show-current` in the repo. If it returns empty (detached HEAD), report an error for that repo.
-2. **Detect the default branch:** Run `git symbolic-ref refs/remotes/origin/HEAD --short` to find the default branch (e.g., `origin/main`). Strip the `origin/` prefix. If this fails, check if `main` or `master` exist locally via `git rev-parse --verify`.
-3. **Verify it's a feature branch:** The current branch must NOT be the default branch. If it is, report an error.
-4. **List changed files:** Run `git diff --name-only <default-branch>...HEAD` to find files changed on this branch relative to the default branch. If no merge base exists, fall back to `git diff --name-only HEAD`.
-5. **Get the diff:** Run `git diff <default-branch>...HEAD` for the full diff.
+1. **Resolve analysis path with worktree awareness:**
+   - If `worktreePath` exists for this repo/session, run all git commands from `worktreePath`.
+   - Otherwise run from the repo path.
+   - Never mix command cwd across base repo + worktree in one analysis pass.
+2. **Detect worktree context:** Run `git worktree list --porcelain` and determine whether the analysis path is:
+   - a linked worktree checkout, or
+   - the primary checkout.
+   Record this in output as `checkoutType`.
+3. **Check the current branch:** Run `git branch --show-current` in the resolved analysis path. If it returns empty (detached HEAD), report an error for that repo.
+4. **Detect the default branch:** Run `git symbolic-ref refs/remotes/origin/HEAD --short` to find the default branch (e.g., `origin/main`). Strip the `origin/` prefix. If this fails, check if `main` or `master` exist locally via `git rev-parse --verify`.
+5. **Verify it's a feature branch:** The current branch must NOT be the default branch. If it is, report an error.
+6. **List changed files:** Run `git diff --name-only <default-branch>...HEAD` to find files changed on this branch relative to the default branch. If no merge base exists, fall back to `git diff --name-only HEAD`.
+7. **Get the diff:** Run `git diff <default-branch>...HEAD` for the full diff.
+8. **Classify changed paths** to drive downstream test routing — emit `pathClassification` (see "Output state — pathClassification" below).
 
 ## Output
 
 Report per repo:
 
 **Repo: (name)**
+- Analysis path: (resolved path used for git commands)
+- Checkout type: `worktree` | `primary`
 - Branch: (current branch name)
 - Default branch: (detected default branch)
 - Changed files: (list)
@@ -40,3 +52,31 @@ Report per repo:
 **Summary:** (which repos have changes, which don't, any errors)
 
 If NO repos have any changes, clearly state: "No changes detected in any repo."
+
+## Output state — pathClassification
+
+Per repo, emit one additional field that the E2E acceptance stage (`do/e2e-acceptance.md` Steps 1.5 and 1.7) consumes to pick routing + project mapping without hardcoding product paths:
+
+```
+pathClassification: <surface-a | surface-b | mixed | none>
+```
+
+Definitions:
+- **`surface-a`** — all changed files match the repo's configured pattern set A.
+- **`surface-b`** — all changed files match the repo's configured pattern set B.
+- **`mixed`** — at least one file matches pattern set A and at least one file matches pattern set B.
+- **`none`** — empty diff (placeholder branch — see standardized output below).
+
+Pattern sets must be treated as repo-configured routing buckets (for example, marketing-vs-app areas), not global hardcoded paths in this stage.
+
+### Standardized "no changes" output (placeholder branch)
+
+If `git diff <default>...HEAD --stat` is empty for a repo, emit:
+
+```
+pathClassification: none
+filesChanged: []
+recommendation: SKIPPED — placeholder branch, no code under test
+```
+
+`do/e2e-acceptance.md` Step 1.5 reads this and exits the stage cleanly with a SKIPPED verdict — do not silently run tests against master.

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

@@ -1,106 +1,104 @@
-# PR Creation Agent (Stage 7/7)
+# PR Creation Agent (Stage 7 — Open PR)
 
-You are creating pull requests for each repository that has changes after a successful dev cycle run.
+Open a pull request for each repo that has changes. If an E2E walkthrough report is available from the previous stage, attach it. Honor preference gates. Hand off to stage 8 once done.
 
 ## Turn preamble
 
-Start the turn with:
-
 ```
-**Stage 7/7 — Open PR** — rendering the visual walkthrough and pushing the PR.
+**Stage 7 — Open PR** — pushing the branch and opening the PR.
 ```
 
-## Non-negotiable: visual walkthrough is required
-
-**You MUST invoke `muggle-pr-visual-walkthrough` (Mode B) to render the E2E section of the PR body.** Hand-writing the PR body with a text summary and `gh pr create` is a stage failure — reviewers rely on the dashboard links and per-step screenshots the walkthrough produces.
-
-If the E2E stage was skipped (validation was `unit-only` or `skip`), you may omit the walkthrough section — but mark the PR title with `[UNVERIFIED]` or `[UNIT-ONLY]` accordingly, and record the reason in the PR body under `## Validation`.
+## Inputs
 
-Before calling `gh pr create`, self-check:
+- Per-repo: name, path, branch.
+- Requirements: goal, acceptance criteria.
+- **Optional** E2E acceptance report from stage 6 — only present when validation ran. Produced by [`e2e-acceptance.md`](e2e-acceptance.md); schema is canonical in [`muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) (Zod-validated by the CLI).
 
-- [ ] `muggle-pr-visual-walkthrough` was invoked (or the skip reason is recorded).
-- [ ] The `body` returned by the skill is embedded verbatim in the PR body.
-- [ ] If `comment` is non-null, it will be posted as a follow-up after the PR is created.
+## Per repo
 
-If you cannot check all three, **halt** — do not create the PR. Fix the upstream stage first.
+0. **`autoCreatePR` gate** — apply per [`../muggle-preferences/preference-gates/autoCreatePR.md`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip, record the reason in `result.md` and move on.
 
-## Input
+1. **Push:** `git push -u origin <branch>` in the repo directory.
 
-You receive:
-- Per-repo: repo name, path, branch name
-- Requirements: goal, acceptance criteria
-- E2E acceptance report: passed/failed test cases, each with:
-  - `testCaseId`, `testScriptId`, `runId`, `projectId`
-  - `viewUrl`: link to view run on muggle-ai.com
-  - `steps`: array of `{ stepIndex, action, screenshotUrl }`
-  - `failureStepIndex` and `error` (if failed)
-  - `artifactsDir` (for local debugging)
-  - `description` and `useCaseName` (optional but recommended) — test case one-liner and parent use case title; drive the grouped overview and the per-test collapsible headers in the rendered walkthrough. Prefer values already in the `e2e-acceptance.md` stage's conversation context; only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` for anything you don't already have.
+2. **Title** (under 70 chars):
+   - E2E report exists and has failures → `[E2E FAILING] <goal>`
+   - No E2E report at all (validation was `unit-only` or `skip`) → `[UNVERIFIED] <goal>` or `[UNIT-ONLY] <goal>` to match the validation strategy
+   - Otherwise → `<goal>`
 
-## Your Job
+3. **Body** — assemble in order:
+   - `## Goal` — from requirements.
+   - `## Acceptance Criteria` — bulleted; omit section if empty.
+   - `## Changes` — summary of what changed in this repo.
+   - `## Validation` — one line: link to E2E report, or `unit-only`, or `skip — <reason>`.
+   - **If an E2E report exists,** invoke [`muggle-pr-visual-walkthrough`](../muggle-pr-visual-walkthrough/SKILL.md) Mode B to render the walkthrough block. Embed the returned `body` verbatim (it brings its own `## E2E Acceptance Results` heading). If no report, skip this block entirely.
 
-For each repo with changes:
-
-1. **Push the branch** to origin: `git push -u origin <branch-name>` in the repo directory.
-2. **Build the PR title:**
-   - If E2E acceptance tests have failures: `[E2E FAILING] <goal>`
-   - Otherwise: `<goal>`
-   - Keep under 70 characters
-3. **Render the E2E acceptance block** by invoking the shared `muggle-pr-visual-walkthrough` skill in **Mode B** (render-only for embedding). See "Rendering the E2E acceptance block via the shared skill" below. You receive `{body, comment}` where `body` is the E2E markdown block and `comment` is a non-null overflow comment only when the content exceeds the CLI's byte budget.
-4. **Build the PR body** by concatenating, in order:
-   - `## Goal` — the requirements goal
-   - `## Acceptance Criteria` — bulleted list (omit section if empty)
-   - `## Changes` — summary of what changed in this repo
-   - The `body` field from the skill output (already contains its own `## E2E Acceptance Results` header — do not add another)
-5. **Create the PR** using `gh pr create --title "..." --body "..." --head <branch>` in the repo directory.
-6. **Capture the PR URL** and extract the PR number.
-7. **Post the overflow `comment` only if it is non-null.** In the common case, `comment` is `null` and nothing is posted. Never post speculatively.
+4. **Create:** `gh pr create --title "..." --body "..." --head <branch>`. Capture the PR URL and number.
 
+5. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once:
    ```bash
-   gh pr comment <PR#> --body "$(cat <<'EOF'
-   <comment field contents>
-   EOF
-   )"
+   jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <PR#> --body-file -
    ```
+   Never post when `comment` is `null`.
 
-## Rendering the E2E acceptance block via the shared skill
-
-**Do not hand-write the `## E2E Acceptance Results` markdown, and do not call `muggle build-pr-section` directly from this stage.** The rendering workflow is owned by the shared **`muggle-pr-visual-walkthrough`** skill (see `plugin/skills/muggle-pr-visual-walkthrough/SKILL.md`), which wraps the CLI and enforces the `E2eReport` input contract with a Zod schema.
-
-### Input — the `E2eReport` JSON
+## Stage 8 handoff
 
-The `e2e-acceptance.md` stage already produces an `E2eReport` with the exact shape the skill expects (`projectId` + `tests[]` with per-test `name`, `testCaseId`, `testScriptId`, `runId`, `viewUrl`, `status`, and `steps[]` of `{stepIndex, action, screenshotUrl}`; failed tests additionally have `failureStepIndex`, `error`, and optionally `artifactsDir`; every test may additionally carry `description` and `useCaseName` — optional but recommended — which drive the grouped overview and per-test collapsible headers in the rendered walkthrough). Pass it through unchanged — do not reshape it. The full schema is documented in the shared skill.
+After every repo is processed, build the manifest and dispatch **one follow-up loop per opened PR**. The dispatches are the LAST action this stage takes — once they fire, the original session is free.
 
-### Invocation — Mode B (render-only)
+Write `.muggle-do/sessions/<slug>/prs.json` with one entry per **opened** PR (skip repos where `autoCreatePR` short-circuited or PR creation failed):
 
-Invoke `muggle-pr-visual-walkthrough` via the `Skill` tool with the `E2eReport` already in context. The skill will:
+```json
+[{ "repo": "owner/repo", "number": 142, "url": "...", "head_sha": "...", "state": "open" }]
+```
 
-1. Validate the `E2eReport` and call `muggle build-pr-section` (piping the JSON to stdin).
-2. Parse the CLI's `{body, comment}` stdout.
-3. **Return `{body, comment}` to this stage's conversation** without posting anything — because Mode B is render-only. `body` is the E2E markdown block; `comment` is a non-null overflow follow-up comment only when content exceeds the byte budget, otherwise `null`.
+Seed `.muggle-do/sessions/<slug>/last_seen.json` keyed by `"<owner>/<repo>#<n>"` with the empty-cursor shape (full shape in [`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md)). Stage 7 only seeds; each per-PR loop owns advancing its own cursor.
+
+Also seed `.muggle-do/sessions/<slug>/cycle.json` — the muggle-do implementation cycle declaration the follow-up loop will invoke on each actionable review:
+
+```json
+{
+  "cycleName": "muggle-do dev cycle",
+  "steps": [
+    { "stage": 3, "file": "../do/build.md" },
+    { "stage": 4, "file": "../do/impact-analysis.md" },
+    { "stage": 5, "file": "../do/unit-tests.md" },
+    { "stage": 6, "file": "../do/e2e-acceptance.md" },
+    { "name": "post-walkthrough", "skill": "muggle-pr-visual-walkthrough", "mode": "A" }
+  ],
+  "pushHandler": "git push origin <branch>",
+  "useSubagent": false
+}
+```
 
-Mode A (where the skill itself finds an existing PR and posts a `gh pr comment`) is **not used by `muggle-do`** — it's for interactive callers like `muggle-test` that are mid-development with a PR already open. `muggle-do` always creates new PRs, so it always uses Mode B.
+For each entry in `prs.json`, dispatch its own loop as the final action:
+```
+/loop 1m /muggle:muggle-pr-followup <slug> <pr-number>
+```
+Resolve `<slug>` from the session directory's basename. One loop per PR — multi-repo sessions opening N PRs result in N independent loops, each tracking its own PR's review thread.
 
-### After rendering
+If `prs.json` is empty (all repos skipped, or all PR creations failed), **do not dispatch** — record the reason in `result.md` and exit.
 
-Back in this stage:
+## Self-check before exit
 
-- Embed `body` in the `gh pr create --body` body (see step 4 above).
-- Post the overflow `comment` as a follow-up **only when it is non-null** (see step 7 above).
-- If the CLI exited non-zero, the skill surfaces the stderr error — do not swallow it, surface it to the user.
+- [ ] Every non-skipped repo got `gh pr create` to succeed.
+- [ ] When an E2E report existed, the walkthrough block was rendered via Mode B (not hand-written).
+- [ ] Overflow `comment` was posted only when non-null.
+- [ ] `prs.json` and `last_seen.json` reflect the PRs actually opened.
+- [ ] If `prs.json` is non-empty, the `/loop` dispatch was the last action.
 
-### Notes on fit vs. overflow
+## Output
 
-- **Common case (fit):** the full evidence (summary, per-test rows, collapsible failure details) lives in the PR description, `comment` is `null`, no follow-up comment is posted.
-- **Overflow case:** the CLI detects the full body would exceed its byte budget; `body` contains the summary, per-test rows, and a pointer line; `comment` contains the overflow details. Post both.
-- You do not make the fit-vs-overflow decision — the CLI does. Never post the comment when it is `null`.
+**PRs Created:** repo → URL
+**Skipped:** repo → reason (when `autoCreatePR` short-circuited)
+**Overflow comments posted:** repo → PR #
+**Stage 8:** `Watching <N> PR(s) — one /loop 1m /muggle:muggle-pr-followup <slug> <pr#> per PR` | `No PRs to watch — stage 8 not dispatched`
+**Errors:** repo → message
 
-## Output
+## Post-merge cleanup
 
-**PRs Created:**
-- (repo name): (PR URL)
+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).
 
-**E2E acceptance overflow comments posted:** (only include repos where an overflow comment was actually posted)
-- (repo name): comment posted to PR #(number)
+Append one short reminder tied to the gate value:
 
-**Errors:** (any repos where PR creation or comment posting failed, with the error message)
+- `always` → `Once merged, I'll run the cleanup sequence automatically.`
+- `never` → omit.
+- `ask` / absent → `Once merged, I'll check with you about cleanup.`

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

@@ -1,4 +1,4 @@
-# Pre-flight Agent (Stage 1/7)
+# Pre-flight Agent (Stage 1)
 
 You are running the **only user-facing stage** of the muggle-do dev cycle. Your job is to consolidate every ambiguity — task scope, repos, validation strategy, environment, credentials, PR target — into a **single turn** so the rest of the cycle can run unattended.
 
@@ -9,7 +9,7 @@ You are running the **only user-facing stage** of the muggle-do dev cycle. Your
 Start the turn with:
 
 ```
-**Stage 1/7 — Pre-flight** — consolidating everything the cycle needs before going silent.
+**Stage 1 — Pre-flight** — consolidating everything the cycle needs before going silent.
 ```
 
 ## Input
@@ -17,7 +17,7 @@ Start the turn with:
 You receive:
 
 - The user's task description (from `$ARGUMENTS`).
-- The list of configured repos (names + paths) from the Muggle config.
+- The list of configured repos (names + paths) from the Muggle Test config.
 - Any session directory that already exists (resumption case).
 
 ## Silent detection (do this first — no user prompts)
@@ -26,31 +26,38 @@ 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.** Scan common dev ports — `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|3999|4200|5173|8080)'` — and hit `/` with `curl -s -o /dev/null -w "%{http_code}"` to confirm 2xx.
-4. **Running backend.** If the repo's `.env.local` (or equivalent) declares a backend URL (e.g. `REACT_APP_BACKEND_BASE_URL=http://localhost:5050`), probe the health endpoint; note up/down.
-5. **Muggle MCP auth.** Call `muggle-remote-auth-status`. If expired, you will ask to re-auth in the questionnaire.
-6. **Candidate Muggle 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 project, call `muggle-remote-secret-list` and note whether `managed_profile_email` / `managed_profile_password` exist.
+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.
+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.
 8. **Auth0 tenant in use for local dev.** Grep the repo's env file for `*AUTH0_DOMAIN*`; record the tenant. This tells the user whether the staging-tenant test user will work or not.
+9. **Branch hygiene signals** for the `autoUseWorktree` and `autoRebase` gates (see [`../_shared/use-worktrees.md`](../_shared/use-worktrees.md), [`../_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)):
+   - Is the current checkout already a worktree? `git -C <repo> rev-parse --is-inside-work-tree` plus `git -C <repo> worktree list`.
+   - How many commits behind `origin/<default>`? `git -C <repo> fetch origin && git -C <repo> rev-list --count "HEAD..origin/$(git -C <repo> symbolic-ref refs/remotes/origin/HEAD --short | sed 's|origin/||')"`.
+10. **`autoE2ETest` preference.** Read the session-context preferences line. Unset → treat as `always` (this gate's default — opposite of the system-wide `ask` default). `ask` → surface in Q13. `always` → no question; stage 6 runs.
 
 ## The consolidated questionnaire
 
-Present **one `AskQuestion`** (or the platform's structured-selection equivalent) that collects every remaining decision. Use detected values as defaults whenever possible. Questions to include, in this order:
+Present **one `AskUserQuestion`** (or the platform's structured-selection equivalent) that collects every remaining decision. Use detected values as defaults whenever possible. Questions to include, in this order:
 
 1. **Task scope clarification** — only if the task description is genuinely ambiguous. Offer 2–3 interpretations as options plus "Other — type a clarification." If the task is unambiguous, omit.
 2. **Repo(s) to modify** — pre-selected with the best silent match. "Confirm <repo>" / "Change repo" / "Multi-repo (list them)".
 3. **Branch name** — default: `users/<user>/<slug>` derived from the task. "Use default" / "Use different name (type)".
 4. **Validation strategy** — the single most important question. Options:
-   - **Local E2E** (Muggle Electron against a running localhost) — default if a dev server was detected.
+   - **Local E2E** (Muggle Test Electron against a running localhost) — default if a dev server was detected.
    - **Staging replay** — for changes already deployed to a preview URL.
    - **Unit tests only** — skip E2E, acceptable for pure refactors or backend-only changes.
    - **Skip validation** — explicit opt-out; the PR title gets `[UNVERIFIED]`.
 5. **Local URL** — only if validation is Local E2E. Default: the detected port. "Confirm `<detected>`" / "Type a different URL".
 6. **Backend reachable?** — only if validation is Local E2E and a backend URL is declared. If the health probe failed, ask "Start the backend now and I'll re-probe" / "Proceed anyway" / "Skip to unit tests only".
-7. **Muggle project** — pre-selected with the best silent match. "Use <top match>" / "Use a different existing project (list)" / "Create new".
+7. **Muggle Test project** — pre-selected with the best silent match. "Use <top match>" / "Use a different existing project (list)" / "Create new".
 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 MCP?** — only if auth was missing/expired. "Log in now" / "Abort".
+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.
+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.
 
 If fewer than two of the above need the user, still gather them in a single turn — never open a second round.
 
@@ -73,7 +80,7 @@ After the user answers, write **`state.md`** with every resolved value, verbatim
 - Validation: <strategy>
 - Local URL: <url or N/A>
 - Backend status: <up | down | N/A>
-- Muggle project: <name> (<uuid>)
+- Muggle Test project: <name> (<uuid>)
 - Test credentials: <existing | new | skip>
 - PR target: <branch>
 - Auth status: <ok | re-authed | N/A>
@@ -87,7 +94,7 @@ Also initialize `iterations/001.md` with a header:
 ```markdown
 # Iteration 001 — <ISO-8601 timestamp>
 
-### Stage 1/7 — Pre-flight (<timestamp>)
+### Stage 1 — Pre-flight (<timestamp>)
 
 <verbatim copy of pre-flight answers>
 ```

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

@@ -1,4 +1,4 @@
-# Requirements Analysis Agent (Stage 2/7)
+# Requirements Analysis Agent (Stage 2)
 
 You are analyzing a user's task description to extract structured requirements for an autonomous development cycle.
 
@@ -7,7 +7,7 @@ You are analyzing a user's task description to extract structured requirements f
 Start the turn with:
 
 ```
-**Stage 2/7 — Requirements** — extracting structured goals from the pre-flight-clarified task.
+**Stage 2 — Requirements** — extracting structured goals from the pre-flight-clarified task.
 ```
 
 Pre-flight already resolved ambiguity via the consolidated questionnaire. **Do not ask the user any questions here** — infer silently and record assumptions in Notes.

package/dist/plugin/skills/do/unit-tests.md

@@ -1,4 +1,4 @@
-# Unit Test Runner Agent (Stage 5/7)
+# Unit Test Runner Agent (Stage 5)
 
 You are running unit tests for each repository that has changes in the dev cycle pipeline.
 
@@ -7,7 +7,7 @@ You are running unit tests for each repository that has changes in the dev cycle
 Start the turn with:
 
 ```
-**Stage 5/7 — Unit tests** — running each repo's test suite.
+**Stage 5 — Unit tests** — running each repo's test suite.
 ```
 
 ## Input

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

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

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

@@ -0,0 +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.
+---
+
+# mdo — alias for muggle-do-task
+
+Invoke the `muggle-do-task` skill via the Skill tool. Forward any user-provided arguments unchanged.

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

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

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

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

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

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

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

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