@muggleai/works 4.10.0 → 4.10.1

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

@@ -0,0 +1,244 @@
+# 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.
+
+## The contract
+
+Every decision in this doc follows the same shape:
+
+1. **Classify** — pick a bucket from a fixed taxonomy based on the available signals.
+2. **Suggest** — present the bucket-specific suggestion to the user via `AskUserQuestion`.
+3. **User decides** — the user always makes the final call. Never auto-act.
+4. **Emit telemetry** — record `(aiClassification, aiSuggestion, userAction, signals)` via `muggle-local-telemetry-event-emit` so the rules can be refined later from real data.
+
+The classification rules below are **starting heuristics**. Trust the AI's bucket only enough to phrase a default suggestion — let the user override freely.
+
+---
+
+## F. Run-level verdict taxonomy
+
+The buckets in sections A–C operate **per script** (one classification per test-case execution). This section defines the **single verdict** an acceptance-tester subagent returns to its orchestrator — one verdict per PR / per dispatched run, summarizing every test case it touched.
+
+### Verdicts
+
+| Verdict | Meaning |
+|---|---|
+| **PASS** | All relevant test cases ran and passed. The PR's user-visible change is exercised and works. |
+| **FAIL** | At least one test case demonstrated wrong behavior caused by the PR code. The PR is regressive. |
+| **PARTIAL** | Some relevant tests passed; some were INCONCLUSIVE (not failed). Useful coverage, with gaps. |
+| **INCONCLUSIVE** | All relevant tests were blocked by environment factors — script staleness, empty local DB, missing fixtures, tests out of date relative to current master UI. **Not a regression signal.** |
+| **BLOCKED** | An infra blocker prevented any meaningful execution: Auth0 tenant rejecting test emails, dev server unreachable, MCP service down, port wouldn't bind. **Not a regression signal.** |
+| **SKIPPED** | No code under test — placeholder branch, empty diff vs. master, deliberate no-op change. |
+
+PASS and FAIL are the only verdicts that say something about the PR itself. PARTIAL means "some coverage, some gaps." INCONCLUSIVE, BLOCKED, and SKIPPED all mean **don't draw a regression conclusion from this run** — they signal an environment, script, or input problem, not a product defect.
+
+### Mapping per-script buckets to run verdicts
+
+When the subagent aggregates per-script results from sections B and C into one verdict:
+
+| Per-script bucket | Section | Typical run verdict |
+|---|---|---|
+| `infra` (replay or regen) | B / C | **BLOCKED** |
+| `stale-script` (replay) | B | **INCONCLUSIVE** |
+| `product-defect` (replay) | B | **FAIL** |
+| `product-uxux` (regen) | C | **FAIL** |
+| `agent-course` (regen) | C | **INCONCLUSIVE** (agent couldn't complete, not a PR defect) |
+| `transient` (regen) | C | retry once; if still transient → **INCONCLUSIVE** |
+
+When a run mixes buckets across multiple test cases, take the most-significant verdict in this priority order: **FAIL > PARTIAL > BLOCKED > INCONCLUSIVE > SKIPPED > PASS**. If any one test case maps to FAIL, the run is FAIL. If some passed and some were INCONCLUSIVE, the run is PARTIAL.
+
+### How orchestrators consume the verdict
+
+Subagents return the verdict as part of a structured block, not free-form prose. The orchestrator parses this block to decide whether to post a "regression" PR comment, a "needs investigation" comment, or skip the PR. See `agents/acceptance-tester.md` for the exact block format the subagent must emit.
+
+---
+
+## 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.
+
+### Inputs
+
+- The change summary from `git diff` (file paths + diff content).
+- The test case (title, description, instructions, last passing run timestamp).
+- Existing test scripts for that test case from `muggle-remote-test-script-list`.
+
+### Rules (fire in order; first match wins)
+
+| # | Condition | Mode | Reason |
+|---|---|---|---|
+| 1 | No replayable/succeeded script exists for the test case | `regen` | Nothing to replay. |
+| 2 | A changed file looks like UI/markup mapped to this test case (component, page, route, template, JSX/TSX/Vue/Svelte/HTML, CSS that changes layout or selectors) | `regen` | Selectors likely broken — replay would fail on staleness. |
+| 3 | Last successful run was > **30 days** ago | `regen` | Drift accumulates; the saved script is stale even without a flagged change. |
+| 4 | Otherwise — changes are logic-only / backend / styling-without-DOM-impact | `replay` | Selectors should still work; replay catches real regressions. |
+
+### Mapping "changed file → test case"
+
+Use the test case's `instructions` and `goal` text plus filenames in the diff. Match heuristically — a test case titled "Submit signup form" plus a diff in `app/auth/signup/page.tsx` is a clear match. When in doubt, prefer `regen` (rule 2 wins) — a needless regen wastes budget; a stale replay fails the test for the wrong reason.
+
+### Telemetry
+
+Emit **`pre-execution-classification`** for every test case in the batch, before execution starts:
+
+```json
+{
+  "eventType": "pre-execution-classification",
+  "skillName": "muggle-test",
+  "aiClassification": "replay" | "regen",
+  "aiSuggestion": "<same as classification>",
+  "testCaseId": "<id>",
+  "projectId": "<id>",
+  "signals": ["rule-1-no-script" | "rule-2-ui-changed" | "rule-3-stale-30d" | "rule-4-default-replay"],
+  "metadata": { "lastPassedAgeDays": <n>, "changedFilesMatched": ["..."] }
+}
+```
+
+Skill MAY surface the per-test-case decision in the report (e.g., "regenerating 3, replaying 5") so the user can override before execution. If the user overrides, emit a follow-up event with `userAction` set to the overriding mode.
+
+---
+
+## B. Post-replay failure (used by all four skills with replays)
+
+Triggered when `muggle-local-execute-replay` returns `status: "failed"` (or non-zero Electron exit) **and** the run is not an orchestration timeout already covered in `muggle-test-feature-local/SKILL.md` Step 6.
+
+### Buckets
+
+| Bucket | Meaning |
+|---|---|
+| **infra** | Something is wrong inside Muggle Test itself (e.g., click didn't register on a clearly-clickable element, Electron crash, browser engine quirk). Not the user's fault and not a stale script. |
+| **stale-script** | The test script no longer matches the live UI (selectors moved, label paths changed, page renamed). The product still works; the script is out of date. |
+| **product-defect** | The script and infra are fine; the user's app actually misbehaved (assertion failure on previously-passing step, unexpected error, wrong page after action). This is the failure mode acceptance testing exists to catch. |
+
+### Initial signal heuristics
+
+Derive signals from the run's per-step results, error messages, and step screenshots (`muggle-local-run-result-get`):
+
+- **infra** signals: `electron-crash`, `chromium-error`, `click-no-effect-on-clickable-element`, `timeout-on-trivial-wait`, `internal-error-in-mcp-output`.
+- **stale-script** signals: `element-not-found`, `selector-timeout`, `label-path-mismatch`, `nav-target-404`, `aria-label-changed`.
+- **product-defect** signals: `assertion-failed-on-passing-step`, `unexpected-error-toast`, `wrong-page-after-action`, `network-500-from-app`, `form-validation-rejected-valid-input`.
+
+If signals span multiple buckets, pick the most specific one and list all signals in telemetry — the user can override.
+
+### Suggestions per bucket
+
+Present via `AskUserQuestion`. The first option is the AI's recommendation (label it `(Recommended)`); always include the others so the user can redirect. **Always include "Skip — just report" so the user can opt out without committing to anything.**
+
+| Bucket | Recommended suggestion | Other options |
+|---|---|---|
+| **infra** | Report bug to Muggle AI → invoke `muggle-feedback` skill with `category: "muggle-infra"` (and run id / signals). | Retry; muggle-feedback (different category); Skip. |
+| **stale-script** | Regenerate the script → call `muggle-local-execute-test-generation` (or remote equivalent) for this test case, then re-replay. | Retry as-is; muggle-feedback; Skip. |
+| **product-defect** | Surface as a real defect — show the failing step + screenshot + one-line summary; offer to share via email/SMS/file ticket (see "Sharing real defects" below). | muggle-feedback (if the script's *expectation* was wrong); Retry; Skip. |
+
+### Sharing real defects
+
+When the user picks "share / file ticket" on a `product-defect`:
+
+1. Build a one-paragraph summary: test case title, failing step, expected-vs-actual, screenshot path, run id.
+2. Ask `AskUserQuestion`: where to share?
+   - Email — open `mailto:` with the summary pre-filled.
+   - SMS — copy the summary to clipboard, instruct user to paste.
+   - File ticket — if `gh` is available and there's a repo, offer `gh issue create` with the summary as the body; otherwise copy summary and instruct user.
+   - Skip — just keep the report.
+3. Record the choice in telemetry (`userAction: "share-email" | "share-sms" | "share-ticket" | "skip"`).
+
+### Telemetry
+
+Emit **two events per failure**: one when the AI classifies (before asking the user) and one when the user picks an action.
+
+```json
+{
+  "eventType": "replay-failure-classified",
+  "skillName": "<this skill>",
+  "aiClassification": "infra" | "stale-script" | "product-defect",
+  "aiSuggestion": "report-bug" | "regenerate" | "share-defect",
+  "runId": "<local run id>",
+  "testCaseId": "<id>",
+  "projectId": "<id>",
+  "signals": ["element-not-found", "selector-timeout"],
+  "metadata": { "failingStep": "<step name>", "errorExcerpt": "<first 200 chars>" }
+}
+```
+
+```json
+{
+  "eventType": "replay-failure-resolved",
+  "skillName": "<this skill>",
+  "aiClassification": "<same as above>",
+  "aiSuggestion": "<same as above>",
+  "userAction": "regenerate" | "report-bug" | "share-email" | "retry" | "muggle-feedback" | "skip",
+  "runId": "<local run id>",
+  "testCaseId": "<id>",
+  "projectId": "<id>"
+}
+```
+
+The `(aiSuggestion, userAction)` pair is the metric we tune from — when they diverge, the classifier needs work.
+
+---
+
+## C. Post-regen failure (used by all four skills with generation)
+
+Triggered when `muggle-local-execute-test-generation` (or the remote equivalent) returns `failed`, exit 26, `goal_not_achievable`, or any other non-passing terminal state.
+
+### Buckets
+
+| Bucket | Meaning |
+|---|---|
+| **transient** | Network blip, single LLM call failed, intermittent flake. Likely succeeds on retry without changing anything. |
+| **infra** | A Muggle Test bug stopped generation from progressing (handler crash, schema validation in our code, deterministic LLM-pipeline failure). |
+| **agent-course** | The generation agent went down a wrong path (chose the wrong button, misread the goal, looped on a blocking modal). The product is fine and the test case is fine — the agent's *course* needs steering. |
+| **product-uxux** | The product itself blocks the test (broken page, missing element, server error). Agent can't proceed because the feature doesn't actually work. |
+
+### Initial signal heuristics
+
+From `muggle-local-run-result-get` (summary, structured summary, last steps, error):
+
+- **transient**: `network-error`, `llm-rate-limit`, `single-tool-call-error`, run had partial progress then died.
+- **infra**: `electron-mcp-handler-crash`, `internal-validation-error`, `pipeline-stuck`, identical failure repeated more than twice.
+- **agent-course**: `goal_not_achievable` with summary mentioning the agent picked a different element, looped on a modal, kept trying the same wrong action; many steps but no real progress.
+- **product-uxux**: server 5xx in step screenshots, "page not found" reached repeatedly, expected element provably absent (visible in screenshot), product clearly broken in the artifact log.
+
+### Suggestions per bucket
+
+Present via `AskUserQuestion`. **Always show the run summary first** so the user has context, then offer the bucket's recommended action plus alternatives.
+
+| Bucket | Recommended suggestion | Other options |
+|---|---|---|
+| **transient** | Retry as-is. | muggle-feedback; Edit test case; Skip. |
+| **infra** | Report bug to Muggle AI → `muggle-feedback` with `category: "muggle-infra"` (run id, signals, summary excerpt). | Retry; Skip. |
+| **agent-course** | Steer the agent → invoke `muggle-feedback` skill so the user describes what should have happened; the workflow re-runs with the corrected course. | Retry; Edit test case; Skip. |
+| **product-uxux** | Wait for fix — share the run summary + screenshot to the dev. Offer email / SMS / file ticket (see "Sharing real defects" in section B). | Retry once the fix lands; muggle-feedback; Skip. |
+
+### Telemetry
+
+Same two-event pattern as section B, with `eventType` values `regen-failure-classified` and `regen-failure-resolved`. `aiClassification` is one of the four bucket strings; `userAction` is the user's pick.
+
+```json
+{
+  "eventType": "regen-failure-classified",
+  "skillName": "<this skill>",
+  "aiClassification": "transient" | "infra" | "agent-course" | "product-uxux",
+  "aiSuggestion": "retry" | "report-bug" | "muggle-feedback" | "wait-and-share",
+  "runId": "<local run id>",
+  "testCaseId": "<id>",
+  "projectId": "<id>",
+  "signals": ["goal_not_achievable", "loop-on-modal"],
+  "metadata": { "summary": "<excerpt>", "stepsCompleted": <n> }
+}
+```
+
+---
+
+## D. Emitting telemetry — implementation notes
+
+- Tool: `muggle-local-telemetry-event-emit` (local-only, fire-and-forget).
+- Sink: `~/.muggle-ai/telemetry/failure-events.jsonl` (one JSON record per line, append-only).
+- Never block the skill on a telemetry call. If the tool errors, log and continue.
+- Always emit the **classified** event before asking the user, and the **resolved** event immediately after the user picks. Don't merge them into one event after the fact — the *latency* between AI suggestion and user choice is also data.
+- For the pre-execution classifier (section A), the event has no separate "resolved" pair unless the user actively overrides; if they do, emit a single follow-up `pre-execution-classification` event with `userAction` set.
+
+## E. What this doc deliberately does not bake in
+
+- **Quantitative thresholds** beyond rule A.3 (30-day drift). Bucket signal lists above are an initial best guess; once telemetry has data, the user will refine which signals reliably indicate which bucket.
+- **Auto-retry**. There is no "if X then automatically rerun" path anywhere. The user decides every time — that's the whole point of the contract.
+- **Cross-bucket fallbacks**. If the AI mis-classifies, the user picks a different option from the AskUserQuestion list; the AI does not retry classification.

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

@@ -0,0 +1,10 @@
+# Cleanup After the Change Is Merged
+
+Gated by [`autoCleanup`](../muggle-preferences/preference-gates/autoCleanup.md). Follow the standard procedure in [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md). Fire only after the PR is **merged** — never while it's still open.
+
+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}`.
+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/dist/plugin/skills/_shared/rebase-before-e2e.md

@@ -0,0 +1,15 @@
+# Rebase Onto the Default Branch Before Dev Server / E2E
+
+Gated by [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md). Follow the standard procedure in [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
+
+**Fire only when `behind > 0`:**
+
+```bash
+git fetch origin
+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.
+
+Stale branches produce false failures and false greens — that's why this gate exists.

package/dist/plugin/skills/_shared/telemetry-emit.md

@@ -0,0 +1,15 @@
+# Skill Telemetry — Shared Convention
+
+At the start of every `muggle-*` skill, call `muggle-local-telemetry-skill-emit` once. Fire-and-forget — never await, never let a telemetry failure block the skill.
+
+**Args:**
+
+- `skillName`: this skill's name (e.g. `"muggle-test"`)
+- `trigger`: one of
+  - `"user-slash"` — user typed `/<skill-name>` (the common case; default this)
+  - `"claude-proactive"` — Claude matched on the skill's description, not a slash command
+  - `"nested-skill"` — invoked from another skill via the `Skill` tool
+
+## Failure-mode events
+
+Skills that run replays or generations also emit structured failure-mode events through a separate tool — `muggle-local-telemetry-event-emit`. Don't reinvent the schema or sink in the skill; follow [`failure-mode-handling.md`](./failure-mode-handling.md), which defines the bucket taxonomies, the AI-classify → user-pick contract, and the exact event shape.

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

@@ -0,0 +1,53 @@
+# Worktrees for Dev Work
+
+Use this for feature development, local validation, and PR iteration.
+
+## Core guidance
+
+- **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.
+
+## 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>
+   ```
+3. Install dependencies and run setup in that worktree.
+4. Keep all edits and commits for the change in that same worktree.
+
+## Test in the worktree
+
+- Run lint, typecheck, and unit/integration tests from the worktree.
+- Run your local E2E acceptance flow from that same worktree for user-facing validation.
+- Run the dev server from the same worktree so code, env, and cache all match.
+- In parallel runs, ensure each worktree has a unique port and isolated test data.
+
+## E2E + worktree checklist
+
+1. Confirm command cwd, checked-out branch, and server source are the same worktree.
+2. Start the app from that worktree and verify readiness first (see [`dev-server-readiness.md`](dev-server-readiness.md)).
+3. Run local E2E acceptance checks in that same session.
+4. Isolate test data across parallel branches (separate users/accounts/orgs or resettable fixtures).
+5. Re-run E2E acceptance checks after meaningful code changes during PR review.
+
+## Common failure modes to avoid
+
+- **Mixed checkouts:** Test command and server run from different directories.
+- **Port collision:** Multiple branches share a dev-server port.
+- **Shared mutable state:** Parallel runs mutate the same account or fixtures.
+- **Stale server:** Old process still serves previous branch code.
+
+## Pull request workflow
+
+1. Commit on the branch tied to the worktree.
+2. Push the branch and open the PR.
+3. Keep review fixes in that same worktree.
+4. Re-run relevant checks before each push, including E2E acceptance checks for user-facing changes.
+
+## Tear down
+
+After merge, remove the worktree.  
+See [`post-merge-cleanup.md`](post-merge-cleanup.md).

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

@@ -1,6 +1,10 @@
-# E2E / acceptance agent (Stage 6/7)
+# E2E Acceptance Agent (Stage 6/7)
 
-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
 
@@ -12,23 +16,29 @@ Start the turn with:
 
 ## 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

@@ -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

@@ -41,6 +41,8 @@ You receive:
 
 For each repo with changes:
 
+0. **Apply the `autoCreatePR` gate** per [`../muggle-preferences/preference-gates/README.md`](../muggle-preferences/preference-gates/README.md) + [`autoCreatePR.md`](../muggle-preferences/preference-gates/autoCreatePR.md). On the skip path, record the reason in `result.md` and move to the next repo.
+
 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>`
@@ -57,10 +59,7 @@ For each repo with changes:
 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.
 
    ```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 -
    ```
 
 ## Rendering the E2E acceptance block via the shared skill
@@ -104,3 +103,13 @@ Back in this stage:
 - (repo name): comment posted to PR #(number)
 
 **Errors:** (any repos where PR creation or comment posting failed, with the error message)
+
+## Post-merge cleanup (gated by `autoCleanup`)
+
+Cleanup fires in a follow-up turn after merge — never from this stage. See [`../_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md).
+
+After printing PR URLs, append one short reminder tied to the gate's current value:
+
+- `always` → `Once merged, I'll run the cleanup sequence automatically.`
+- `never` → omit.
+- `ask` / absent → `Once merged, I'll check with you about cleanup.`