@muggleai/works 4.10.0 → 4.10.1

package/plugin/skills/muggle-test-feature-local/SKILL.md

@@ -5,7 +5,9 @@ description: Run a real-browser end-to-end (E2E) acceptance test against localho
 
 # Muggle Test Feature Local
 
-**Goal:** Run or generate an end-to-end test against a **local URL** using Muggle's Electron browser.
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-feature-local"`.
+
+**Goal:** Run or generate an end-to-end test against a **local URL** using Muggle Test's Electron browser.
 
 | Scope | MCP tools |
 | :---- | :-------- |
@@ -15,11 +17,23 @@ description: Run a real-browser end-to-end (E2E) acceptance test against localho
 
 The local URL only changes where the browser opens; it does not change the remote project or test definitions.
 
+## Branch hygiene
+
+Three gates apply, each per the standard procedure in [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md):
+
+- `autoUseWorktree` at pre-flight (see [`_shared/use-worktrees.md`](../_shared/use-worktrees.md)).
+- `autoRebase` before Step 7 (Execute) when `behind > 0` (see [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)).
+- `autoCleanup` after the PR is merged (see [`_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md)).
+
+## Local environment prerequisites
+
+Before any workflow step, invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md). Halt on what it surfaces.
+
 ## UX Guidelines — Minimize Typing
 
-**Every selection-based question MUST use the `AskQuestion` tool** (or the platform's equivalent structured selection tool). Never ask the user to "reply with a number" in a plain text message — always present clickable options.
+**Every selection-based question MUST use the `AskUserQuestion` tool** (or the platform's equivalent structured selection tool). Never ask the user to "reply with a number" in a plain text message — always present clickable options.
 
-- **Selections** (project, use case, test case, script): Use `AskQuestion` with labeled options the user can click.
+- **Selections** (project, use case, test case, script): Use `AskUserQuestion` with labeled options the user can click.
 - **Free-text inputs** (URLs, descriptions): Only use plain text prompts when there is no finite set of options. Even then, offer a detected/default value when possible.
 
 ## Preferences
@@ -29,10 +43,15 @@ Gates run per `preference-gates/README.md`.
 | Preference | Step | Decision it gates |
 |------------|------|-------------------|
 | `autoLogin` | 1 | Reuse saved credentials when auth is required |
-| `autoSelectProject` | 2 | Reuse last-used Muggle project for this repo |
+| `autoSelectProject` | 2 | Reuse last-used Muggle Test project for this repo |
+| `autoSelectLocalHost` | 4 | Reuse last-used local dev server URL for this repo |
+| `autoUseWorktree` | 0 (pre-flight) | Isolate dev work in a worktree (see [`_shared/use-worktrees.md`](../_shared/use-worktrees.md)) |
+| `autoRebase` | 0 (pre-flight) | Rebase onto `origin/<default>` before Step 7 (Execute) (see [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)) |
 | `showElectronBrowser` | 7 | Show Electron browser window during local E2E tests |
-| `openTestResultsAfterRun` | 8 | Open results page on Muggle dashboard after run |
+| `openTestResultsAfterRun` | 8 | Open results page on Muggle Test dashboard after run |
 | `postPRVisualWalkthrough` | 10 | Post visual walkthrough to PR after results |
+| `autoCreatePR` | 10 (if no PR) | Auto-create the PR when posting the walkthrough has no PR to target |
+| `autoCleanup` | post-merge | Run cleanup after the PR for this work is merged (see [`_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md)) |
 
 ## Workflow
 
@@ -40,15 +59,16 @@ Gates run per `preference-gates/README.md`.
 
 - `muggle-remote-auth-status`
 - If **authenticated**: gate `autoLogin` (per `preference-gates/README.md`):
-  - Pro-action: proceed with saved session.
-  - Skip-action: `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+  - `always` → proceed with saved session.
+  - `never` → `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+  - `ask` → run Picker 1 from `preference-gates/autoLogin.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 - If **not signed in or expired**: call `muggle-remote-auth-login` then `muggle-remote-auth-poll`. Do not skip or assume auth.
 
 ### 2. Targets (user must confirm)
 
-The per-repo project cache lives at `<cwd>/.muggle-ai/last-project.json` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Last Project: id=… url=… name="…"` in session context.
+The per-repo project cache lives at `<cwd>/.muggle-ai/last-project.json` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Test Last Project: id=… url=… name="…"` in session context.
 
-Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Last Project` session line.
+Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line.
 - `always` + cache → use cached `projectId`, skip to use case selection. No cache → fall through to `ask`.
 - `never` → full project list; skip Picker 2.
 - `ask` → project list picker (see gate file for spec + Picker 2 override). Skip Picker 2 if "Create new project".
@@ -59,7 +79,7 @@ Ask the user to pick **project**, **use case**, and **test case** (do not infer)
 - `muggle-remote-use-case-list` (with `projectId`)
 - `muggle-remote-test-case-list-by-use-case` (with `useCaseId`)
 
-**Selection UI (mandatory):** Every selection MUST use `AskQuestion` with clickable options. Never ask the user to "reply with the number" in plain text.
+**Selection UI (mandatory):** Every selection MUST use `AskUserQuestion` with clickable options. Never ask the user to "reply with the number" in plain text.
 
 **Project selection context:** A **project** groups all your test results, use cases, and test scripts on the Muggle AI dashboard. Include the project URL in each option label so the user can identify the right one.
 
@@ -69,18 +89,18 @@ Prompt for projects: "Pick the project to group this test into:"
 
 - Do **not** dump the full list by default.
 - Rank items by semantic relevance to the user's stated goal (title first, then description / user story / acceptance criteria).
-- Show only the **top 3-5** most relevant options via `AskQuestion`, plus these fixed tail options:
-  - **"Show full list"** — present the complete list in a new `AskQuestion` call. **Skip this option** if the API returned zero rows.
+- Show only the **top 3-5** most relevant options via `AskUserQuestion`, plus these fixed tail options:
+  - **"Show full list"** — present the complete list in a new `AskUserQuestion` call. **Skip this option** if the API returned zero rows.
   - **"Create new ..."** — never omitted. Label per step: "Create new project", "Create new use case", or "Create new test case".
 
 **Create new — tools and flow (use these MCP tools; preview before persist):**
 
 - **Project — Create new project:** Collect `projectName`, `description`, and `url` (may be the local app URL, e.g. `http://localhost:3999`). Call `muggle-remote-project-create`. Use the returned `projectId` and continue.
 - **Use case — Create new use case:** User provides a natural-language instruction (or you reuse their testing goal).
-  1. `muggle-remote-use-case-prompt-preview` with `projectId`, `instruction` — show preview; get confirmation via `AskQuestion`.
+  1. `muggle-remote-use-case-prompt-preview` with `projectId`, `instruction` — show preview; get confirmation via `AskUserQuestion`.
   2. `muggle-remote-use-case-create-from-prompts` with `projectId` and `instructions: ["<the user's natural-language instruction>"]` — persist. Use the created use case id and continue to test-case selection.
 - **Test case — Create new test case** (requires a chosen `useCaseId`): User provides an instruction describing what to test.
-  1. `muggle-remote-test-case-generate-from-prompt` with `projectId`, `useCaseId`, `instruction` — **preview only** (server test-case prompt preview); show the returned draft(s); get confirmation via `AskQuestion`.
+  1. `muggle-remote-test-case-generate-from-prompt` with `projectId`, `useCaseId`, `instruction` — **preview only** (server test-case prompt preview); show the returned draft(s); get confirmation via `AskUserQuestion`.
   2. Persist the accepted draft with `muggle-remote-test-case-create`, mapping preview fields into the required properties (`title`, `description`, `goal`, `expectedResult`, `url`, etc.). Then continue from **section 5** with that `testCaseId`.
 
 ### 3. Ensure Local Services Are Ready
@@ -94,13 +114,16 @@ Before detecting the local URL, verify that the services the user needs are actu
 
 This step is especially important when the user's app depends on sibling services (a backend API, an auth service, etc.) that may not be running yet. The prepare skill handles discovery, startup, and cleanup so this skill doesn't have to.
 
-### 4. Local URL
+**Compile-gate (do not skip)** — after `muggle-test-prepare` reports ready, run the two-stage readiness probe per [`_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md) before dispatching any test. Halt on any failure it surfaces; do not dispatch against a broken bundle.
 
-Try to auto-detect the dev server URL by checking running terminals or common ports (e.g., `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)'`). If a likely URL is found, present it as a clickable default via `AskQuestion`:
-- Option 1: "http://localhost:3000" (or whatever was detected)
-- Option 2: "Other — let me type a URL"
+### 4. Local URL (gated by `autoSelectLocalHost`)
 
-If nothing detected, ask as free text: "Your local app should be running. What's the URL? (e.g., http://localhost:3000)"
+Skill responsibilities (the rest is in `preference-gates/autoSelectLocalHost.md`):
+- **Read the cache**: `Muggle Test Last Host: <url>` session-context line, or `muggle-local-last-host-get`. Pass as `{lastHost}` substitution.
+- **Auto-detect a suggested URL**: `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)'`. Pass as `{suggestedHost}`.
+- **Save the cache**: call `muggle-local-last-host-set` after the user picks (the gate file requires this on every pick).
+
+Gate `autoSelectLocalHost` per `preference-gates/README.md` + `preference-gates/autoSelectLocalHost.md`.
 
 Remind them: local URL is only the execution target, not tied to cloud project config.
 
@@ -108,7 +131,7 @@ Remind them: local URL is only the execution target, not tied to cloud project c
 
 `muggle-remote-test-script-list` with `testCaseId`.
 
-- **If any replayable/succeeded scripts exist:** use `AskQuestion` to present them as clickable options. Show: name, created/updated, step count per option. Include **"Generate new script"** as the last option.
+- **If any replayable/succeeded scripts exist:** use `AskUserQuestion` to present them as clickable options. Show: name, created/updated, step count per option. Include **"Generate new script"** as the last option.
 - **If none:** go straight to generation (no need to ask replay vs generate).
 
 ### 6. Load data for the chosen path
@@ -154,69 +177,53 @@ The MCP client often uses a **default wait of 300000 ms (5 minutes)** for `muggl
 Call `muggle-local-execute-test-generation` or `muggle-local-execute-replay` directly. **Do not** ask the user to re-approve the Electron launch — the user choosing this skill in the first place is the approval.
 
 Gate `showElectronBrowser` (per `preference-gates/README.md`). Reuse choice within a session.
-- Pro-action: omit `showUi`.
-- Skip-action: pass `showUi: false`.
+- `always` → omit `showUi`.
+- `never` → pass `showUi: false`.
+- `ask` → run Picker 1 from `preference-gates/showElectronBrowser.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+
+### 8. Upload run to cloud (every completed run; open `viewUrl` gated by `openTestResultsAfterRun`)
 
-### 8. After successful generation only (open `viewUrl` gated by `openTestResultsAfterRun`)
+Upload pass-or-fail. Failed runs still need cloud-hosted screenshots and per-step actions for the PR walkthrough — without them reviewers see only a generic "failed" link. The `status` field in the upload payload tells the backend whether to promote the run's action script as the test case's canonical replay script (passed → promote; failed → record only).
 
 - `muggle-local-publish-test-script`
 - Gate `openTestResultsAfterRun` (per `preference-gates/README.md`):
-  - Pro-action: open `viewUrl` automatically (`open "<viewUrl>"` on macOS or OS equivalent).
-  - Skip-action: print the URL only.
+  - `always` → open `viewUrl` automatically (`open "<viewUrl>"` on macOS or OS equivalent).
+  - `never` → print the URL only.
+  - `ask` → run Picker 1 from `preference-gates/openTestResultsAfterRun.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+
+If publish rejects with `has no generated actionScript steps to publish` (true zero-step runs — Electron never produced an action), fall back to `muggle-remote-local-run-upload` directly with whatever data exists (`summaryStep`, `errorMessage`, empty `actionScript`). This still gets the failure summary and any goal-not-achievable verdict onto the dashboard so reviewers can see why the run failed. Capture the returned `actionScriptId` and `viewUrl` from this fallback path the same way you would from publish.
 
 ### 9. Report
 
 - `muggle-local-run-result-get` with the run id from execute.
 - Include: status, duration, pass/fail summary, per-step summary, artifact/screenshot paths, errors if failed, and script view URL when publishing ran.
 
-### 10. Offer to post a visual walkthrough to the PR
-
-After reporting results, gather the required input and hand off to the shared **`muggle:muggle-pr-visual-walkthrough`** skill, which renders the walkthrough via `muggle build-pr-section` and posts it to the current branch's open PR.
-
-#### 10a: Gather per-step screenshots
+### 9a. Route failures through the failure-mode handler
 
-The shared skill takes an **`E2eReport` JSON** that includes per-step screenshot URLs. After step 8 has called `muggle-local-publish-test-script` and you have the `testScriptId`:
+If the run's status is `failed` or any non-passing terminal state, follow [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md):
 
-1. Call `muggle-remote-test-script-get` with the `testScriptId`.
-2. Extract per step: `steps[].operation.action` and `steps[].operation.screenshotUrl`.
-3. Build the `steps` array: `[{ stepIndex: 0, action: "...", screenshotUrl: "..." }, ...]`.
-4. If the run failed, capture `failureStepIndex`, `error`, and the local `artifactsDir` from the run result in step 9.
-5. Populate `description` (test case title/description) and `useCaseName` (parent use case title) on the report entry — optional but strongly recommended; they drive the grouped overview and the per-test collapsible headers. Prefer values already in your conversation context from earlier steps (e.g. the test case you just created or selected, or the use case you confirmed); only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` for anything you don't already have.
+- **Replay-mode run failed** (the user picked an existing script in Step 5) → section B (buckets: `infra` / `stale-script` / `product-defect`).
+- **Regen-mode run failed** (the user picked "Generate new script" or no script existed) → section C (buckets: `transient` / `infra` / `agent-course` / `product-uxux`).
 
-Assemble the `E2eReport`:
+Steps:
+1. Read the run via `muggle-local-run-result-get` and extract signals per the heuristics in the shared doc.
+2. Emit `replay-failure-classified` or `regen-failure-classified` via `muggle-local-telemetry-event-emit` **before** asking the user.
+3. Present the recommended action via `AskUserQuestion` with the alternatives the shared doc lists for that bucket.
+4. After the user picks, emit the matching `*-resolved` event with `userAction`.
 
-```json
-{
-  "projectId": "<projectId from step 2 (Targets)>",
-  "tests": [
-    {
-      "name": "<test case title>",
-      "description": "<one-line description of what this test verifies (optional but recommended)>",
-      "useCaseName": "<parent use case title (optional but recommended)>",
-      "testCaseId": "<id>",
-      "testScriptId": "<id from publish>",
-      "runId": "<runId from execute>",
-      "viewUrl": "<viewUrl from publish>",
-      "status": "passed",
-      "steps": [{ "stepIndex": 0, "action": "...", "screenshotUrl": "..." }]
-    }
-  ]
-}
-```
+If the user picks `muggle-feedback` from any bucket's options, invoke the `muggle-feedback` skill via the `Skill` tool, passing the just-finished `runId` so the submit flow opens with this run preloaded.
 
-See the `muggle:muggle-pr-visual-walkthrough` skill for the full schema including the failed-test shape.
+Skip silently when the run passed cleanly — failure-mode events are by definition about failures.
 
-#### 10b: Detect the PR, then apply the `postPRVisualWalkthrough` gate
-
-Run `gh pr view --json number,title,url 2>/dev/null` first (mandatory). Then gate `postPRVisualWalkthrough` (per `preference-gates/README.md` + gate file):
-- **Case A (PR found)** — `always` → proceed to 10c; `never`/skip → stop.
-- **Case B (no PR)** — always run Picker 1 regardless of saved value; "Create a PR and post" → create PR then proceed to 10c; "Skip" → stop.
-
-#### 10c: Invoke the shared skill in Mode A
+### 10. Offer to post a visual walkthrough to the PR
 
-Invoke the `muggle:muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` in context, the skill renders the markdown block via the CLI, posts `body` as a comment to the PR, posts the overflow `comment` only if the CLI emitted one, and confirms the PR URL to the user.
+After reporting results:
 
-Always use **Mode A** (post to existing PR) from this skill. Never hand-write the walkthrough markdown or call `gh pr comment` directly — delegate to `muggle:muggle-pr-visual-walkthrough`.
+1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → end.
+2. `gh pr view --json number,title,url 2>/dev/null` — find the PR.
+3. If no PR: fire [`autoCreatePR`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip → end.
+4. Assemble the `E2eReport` — see [`../muggle-pr-visual-walkthrough/e2e-report-assembly.md`](../muggle-pr-visual-walkthrough/e2e-report-assembly.md).
+5. Invoke [`../muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) Mode A with the `E2eReport`.
 
 ## Non-negotiables
 
@@ -225,6 +232,6 @@ Always use **Mode A** (post to existing PR) from this skill. Never hand-write th
 - If replayable scripts exist, do not default to generation without user choice.
 - No hiding failures: surface errors and artifact paths.
 - Replay: never hand-built or simplified `actionScript` — only from `muggle-remote-action-script-get`.
-- Use `AskQuestion` for every selection — project, use case, test case, script. Never ask the user to type a number.
+- Use `AskUserQuestion` for every selection — project, use case, test case, script. Never ask the user to type a number.
 - Project, use case, and test case selection lists must always include "Create new ...". Include "Show full list" whenever the API returned at least one row for that step; omit "Show full list" when the list is empty (offer "Create new ..." only). For creates, use preview tools (`muggle-remote-use-case-prompt-preview`, `muggle-remote-test-case-generate-from-prompt`) before persisting.
 - PR posting is always optional and always delegated to the `muggle:muggle-pr-visual-walkthrough` skill — never inline the walkthrough markdown or call `gh pr comment` directly from this skill.

package/plugin/skills/muggle-test-import/SKILL.md

@@ -4,19 +4,21 @@ description: >
   Bring existing tests and test artifacts INTO Muggle Test — from Playwright, Cypress, PRDs,
   Gherkin feature files, test plan docs, Notion exports, or any source.
   TRIGGER when: user wants to import/migrate/load/upload/add/convert existing test files or
-  test docs into Muggle — e.g. "import my playwright tests", "migrate from cypress to muggle",
+  test docs into Muggle Test — e.g. "import my playwright tests", "migrate from cypress to muggle",
   "upload my PRD to muggle", "add my e2e specs to our muggle project", "load these test cases
   into muggle", "turn this feature file into muggle test cases", "create muggle test cases from
   my PRD", "track my specs in muggle", or any .spec.ts/.cy.js/.feature/.md file + muggle.
-  DO NOT TRIGGER when: user wants to run/replay Muggle scripts, scan a site, generate new
+  DO NOT TRIGGER when: user wants to run/replay Muggle Test scripts, scan a site, generate new
   tests from scratch, or check existing test results.
 ---
 
 # Muggle Test Import
 
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-import"`.
+
 This skill migrates existing test artifacts into Muggle Test. It reads your source files,
 structures them into use cases and test cases, gets your approval, then creates everything
-in a Muggle project via the API.
+in a Muggle Test project via the API.
 
 ## Preferences
 
@@ -25,7 +27,7 @@ Gates run per `preference-gates/README.md`.
 | Preference | Step | Decision it gates |
 |------------|------|-------------------|
 | `autoLogin` | 4 | Reuse saved credentials when auth is required |
-| `autoSelectProject` | 5 | Reuse last-used Muggle project for this repo |
+| `autoSelectProject` | 5 | Reuse last-used Muggle Test project for this repo |
 | `suggestRelatedUseCases` | 8a | Suggest related use cases after import |
 | `suggestRelatedTestCases` | 8b | Suggest related test cases after import |
 
@@ -61,7 +63,7 @@ The extraction strategy depends on the file type. Choose the right path before r
 
 ### Path A — PRD / design documents (preferred for document sources)
 
-Muggle has a native PRD processing workflow that extracts use cases more accurately than
+Muggle Test has a native PRD processing workflow that extracts use cases more accurately than
 manual parsing. Use this path for `.md`, `.txt`, `.pdf`, or any prose document.
 
 After authentication and project selection (Steps 4–5), come back and:
@@ -125,13 +127,13 @@ Found 3 use cases with 8 test cases:
    ✦ [HIGH]   Checkout fails with invalid payment info
 ```
 
-Use `AskQuestion` to confirm:
+Use `AskUserQuestion` to confirm:
 - "Looks good — proceed with import"
 - "I want to make changes first"
 
 If the user wants changes, incorporate feedback, then ask again. Only proceed after explicit approval.
 
-> For Path A (native PRD upload): present the use case/test case list that Muggle extracted
+> For Path A (native PRD upload): present the use case/test case list that Muggle Test extracted
 > after the processing workflow completes, and ask the user to confirm before adding any
 > extra test cases manually.
 
@@ -142,8 +144,9 @@ If the user wants changes, incorporate feedback, then ask again. Only proceed af
 Call `muggle-remote-auth-status` first.
 
 If **already authenticated** → gate `autoLogin` (per `preference-gates/README.md`):
-- Pro-action: skip to Step 5.
-- Skip-action: `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+- `always` → skip to Step 5.
+- `never` → `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`.
+- `ask` → run Picker 1 from `preference-gates/autoLogin.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
 If **not authenticated**:
 1. Tell the user a browser window is about to open.
@@ -157,9 +160,9 @@ If **not authenticated**:
 
 A **project** is where all your imported use cases, test cases, and future test results are grouped on the Muggle AI dashboard.
 
-The per-repo project cache lives at `<cwd>/.muggle-ai/last-project.json` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Last Project: id=… url=… name="…"` in session context.
+The per-repo project cache lives at `<cwd>/.muggle-ai/last-project.json` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Test Last Project: id=… url=… name="…"` in session context.
 
-Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Last Project` session line.
+Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line.
 - `always` + cache → use cached `projectId`, skip to Step 6. No cache → fall through to `ask`.
 - `never` → full project list; skip Picker 2.
 - `ask` → project list picker (see gate file for spec + Picker 2 override). Skip Picker 2 if "Create new project".
@@ -167,7 +170,7 @@ Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Last
 ### Logic
 
 1. Call `muggle-remote-project-list` (only when not satisfied by the `always` cache).
-2. Use `AskQuestion` to present all projects as clickable options. Include the project URL in each label. Always include a "Create new project" option at the end.
+2. Use `AskUserQuestion` to present all projects as clickable options. Include the project URL in each label. Always include a "Create new project" option at the end.
 
    Prompt: `"Pick the project to import into:"`
 
@@ -184,12 +187,12 @@ Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Last
 
 Import in two passes using bulk-preview. Show progress to the user as you go.
 
-Both passes use Muggle's async bulk-preview MCP tools, which route prompts through OpenAI's
+Both passes use Muggle Test's async bulk-preview MCP tools, which route prompts through OpenAI's
 Batch API for roughly ~50% of normal LLM cost. The flow is always: **submit → poll → persist**.
 
 ### Path A — Native PRD upload (for document files)
 
-If the source is a PRD or design document, use Muggle's built-in processing pipeline:
+If the source is a PRD or design document, use Muggle Test's built-in processing pipeline:
 
 1. Read the file and base64-encode its content:
    ```bash
@@ -273,7 +276,7 @@ Failed items:
 
 Proceed with the <N> successful items, or cancel to review?
 ```
-Use `AskQuestion` with options "Proceed with successful items" / "Cancel import". Only continue
+Use `AskUserQuestion` with options "Proceed with successful items" / "Cancel import". Only continue
 if the user chooses to proceed.
 
 If you need to abort an in-flight job, call `muggle-remote-bulk-preview-job-cancel` — the
@@ -365,7 +368,7 @@ When all imports are done, print a clean summary. Include:
 - A link to the project overview
 - If any items failed during preview (partial status), list them so the user can retry
 
-Construct view URLs using the Muggle dashboard URL pattern:
+Construct view URLs using the Muggle Test dashboard URL pattern:
 - Project test cases: `https://www.muggle-ai.com/muggleTestV0/dashboard/projects/<projectId>/testcases`
 - Use case within project: `https://www.muggle-ai.com/muggleTestV0/dashboard/projects/<projectId>/testcases?useCaseId=<useCaseId>`
 
@@ -401,14 +404,15 @@ Two preferences gate optional follow-ups: `suggestRelatedUseCases` and `suggestR
 The query is: "from the use cases already in this project, which ones are *not* in the import set but look related to it?" — surface them so the user can decide whether their import missed something the project already tracks.
 
 Gate `suggestRelatedUseCases` (per `preference-gates/README.md`):
-- Pro-action: run the query below.
-- Skip-action: skip.
+- `always` → run the query below.
+- `never` → skip.
+- `ask` → run Picker 1 from `preference-gates/suggestRelatedUseCases.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
 When running the query:
 1. Call `muggle-remote-use-case-list` for the project.
 2. Filter out any use case whose `useCaseId` is in the set you just imported in Step 6 (Pass 1).
 3. Rank the remainder by semantic relevance to the imported titles/descriptions (substring overlap, shared keywords — best-effort, no LLM call needed).
-4. Present the top 3-5 via `AskQuestion` with `allow_multiple: true`. Label each with `<title> — <one-line description>`.
+4. Present the top 3-5 via `AskUserQuestion` with `allow_multiple: true`. Label each with `<title> — <one-line description>`.
 5. For any the user selects, prompt to add follow-up test cases (treat each as a Pass 2 invocation: `muggle-remote-test-case-bulk-preview-submit` → poll → persist via `muggle-remote-test-case-create`).
 6. If the filtered list is empty (the import covers everything in the project), say so and skip.
 
@@ -417,12 +421,13 @@ When running the query:
 For each use case the user just created, surface other test cases already attached that the import didn't add — same idea, scoped to a single use case.
 
 Gate `suggestRelatedTestCases` (per `preference-gates/README.md`):
-- Pro-action: run the query below.
-- Skip-action: skip.
+- `always` → run the query below.
+- `never` → skip.
+- `ask` → run Picker 1 from `preference-gates/suggestRelatedTestCases.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
 When running the query, for each use case in the import:
 1. Call `muggle-remote-test-case-list-by-use-case` with that `useCaseId`.
 2. Filter out any test case you just created in Pass 2 of Step 6.
-3. Present the remainder via `AskQuestion` with `allow_multiple: true`, labeled `[<priority>] <title> — <goal>`.
-4. For any the user selects: nothing to create (they already exist) — just confirm to the user that those tests are now part of their Muggle project alongside the imported ones.
+3. Present the remainder via `AskUserQuestion` with `allow_multiple: true`, labeled `[<priority>] <title> — <goal>`.
+4. For any the user selects: nothing to create (they already exist) — just confirm to the user that those tests are now part of their Muggle Test project alongside the imported ones.
 5. If a use case has no extra test cases, skip it silently.

package/plugin/skills/muggle-test-prepare/SKILL.md

@@ -5,6 +5,8 @@ description: "Make sure dev servers and sibling services are ready on the user's
 
 # Muggle Test Prepare
 
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-prepare"`.
+
 Make sure the local services a user needs for E2E acceptance testing are up and ready. Check what's already running, discover sibling service directories by folder name, and offer to start anything that's missing — always with the user in control.
 
 Some users start their own services (tmux scripts, docker-compose, a terminal per service). Others want help launching them. This skill handles both: it verifies readiness first, and only offers to start things when something is missing.
@@ -45,18 +47,30 @@ The `testing_scope` field records what the user is testing (from Step 1). The `e
 
 **On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), present the running services and ask:
 
-Use `AskQuestion`:
+Use `AskUserQuestion`:
 - Option 1: "Keep them running — skip to testing"
 - Option 2: "Tear down and start fresh"
 - Option 3: "Add more services to the running set"
 
 Prune any dead PIDs silently (the process crashed on its own — no point asking about it).
 
+## Preferences
+
+Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
+
+| Preference | Step | Decision it gates |
+|------------|------|-------------------|
+| `autoRebase` | 0 | Rebase onto `origin/<default>` before starting dev servers (see [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)) |
+
 ## Workflow
 
+### Step 0: Rebase check (gated by `autoRebase`)
+
+Fire per [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md) when `behind > 0`. Otherwise skip silently.
+
 ### Step 1: What Are You Testing?
 
-Before discovering services, understand the shape of the testing so you can scope correctly. Use `AskQuestion`:
+Before discovering services, understand the shape of the testing so you can scope correctly. Use `AskUserQuestion`:
 
 > "What are you testing locally?"
 
@@ -72,7 +86,7 @@ Some services can't run on a developer's machine by design — they need product
 
 **If the user already volunteered this information** in their initial message (e.g., "the payment-gateway can't run locally"), acknowledge it and skip the question — don't re-ask what they already answered.
 
-Otherwise, use `AskQuestion`:
+Otherwise, use `AskUserQuestion`:
 
 > "Are there any services in your stack that **can't** run locally? (e.g., needs production secrets, specific certificates, or cloud-only infra)"
 
@@ -98,7 +112,7 @@ Figure out which services need to be running. Start by listing folder names in t
 ls -d "$(dirname "$PWD")"/*/ | xargs -I{} basename {}
 ```
 
-Present folder names only (not contents) as candidates. Use `AskQuestion` with `multiSelect: true`:
+Present folder names only (not contents) as candidates. Use `AskUserQuestion` with `multiSelect: true`:
 
 > "Which of these need to be running for your tests?"
 
@@ -112,7 +126,7 @@ If the user provides manual paths, verify they exist before continuing. If a pat
 
 **Immediately after the user selects services**, ask how they want to handle startup. This avoids making someone who prefers their own scripts wait through command detection before they get to say "I'll handle it."
 
-Use `AskQuestion`:
+Use `AskUserQuestion`:
 
 > "How do you want to handle these?"
 
@@ -125,24 +139,53 @@ If the user picks **option 1**: proceed through Steps 4-7 as normal.
 
 ### Step 4: Check What's Already Running
 
-Before offering to start anything, check what's already listening on common dev ports:
-
-```bash
-lsof -iTCP -sTCP:LISTEN -nP 2>/dev/null | grep -E ':(3000|3001|3002|4200|5173|5174|8080|8081|8000|8888|4000|9000)'
-```
-
-Cross-reference against the selected service directories. If a selected service appears to already be running (match by port or by the process's working directory), report it as ready:
+Run port detection and (when the app declares a backend URL) backend-health probe per [`_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md). Cross-reference hits against the selected service directories. If a selected service appears to already be running (match by port or by the process's working directory), report it as ready:
 
 > "**backend-api** is already listening on port 3001 (PID 54321) — looks good."
 
 If **all** required services are already running, report readiness and skip straight to Step 7. No need to go through Steps 5-6.
 
-If some are running and some aren't, acknowledge the running ones and continue to Step 5 only for the missing services. Use `AskQuestion` for any already-running service the user might want restarted:
+If some are running and some aren't, acknowledge the running ones and continue to Step 5 only for the missing services. Use `AskUserQuestion` for any already-running service the user might want restarted:
 - Option 1: "It's fine, keep it"
 - Option 2: "Restart it"
 
 For services that are already running and the user wants to keep, add them to the PID tracking file so cleanup can find them later, but mark them as `external: true` so cleanup knows not to kill them (the user started them independently).
 
+**Port already held** — when the user wants a port that is currently held by a process they did **not** select (typically a stale dev server from a sibling worktree). Surface the conflict via `AskUserQuestion`:
+
+> "Port 3999 is held by PID 87421 (you didn't select this process). How do you want to proceed?"
+
+- Option 1: "Use the next available port" (recommended — non-destructive)
+- Option 2: "Force-kill PID 87421 and claim port 3999"
+- Option 3: "Abort"
+
+**Option 1 — next available port:** probe `3999 + N` for `N = 1, 2, 3, ...` until `Test-NetConnection`/`lsof -i :<port>` returns nothing listening. Record the new port (and the env file edit, if `PORT=` is set in `.env.local` etc.) so downstream steps use it. The dev server may need a restart to pick up the new value.
+
+**Option 2 — force-kill (destructive):**
+- **Windows PowerShell:** `Get-NetTCPConnection -LocalPort <port> -ErrorAction SilentlyContinue | ForEach-Object { try { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue } catch { } }`
+- **POSIX:** `lsof -ti:<port> 2>/dev/null | xargs -r kill -9`
+
+Re-verify the port is free before continuing.
+
+### Step 4.5: Environment File Sanity
+
+The env file is **per-repo** — don't hardcode `.env.local`. Detect it: scan `package.json` `scripts/*` for `.env*` literals and known port vars (`PORT=`, `VITE_PORT=`); check framework config (`next.config.*`, `vite.config.*`).
+
+When a dependency on an env file exists:
+
+1. Check whether `<cwd>/<envfile>` exists. If yes, no-op.
+2. If absent, `git worktree list --porcelain` and check each sibling for the same filename.
+3. If found, surface via `AskUserQuestion`:
+
+   > "`<envfile>` is missing in this worktree but exists at `<sibling>/<envfile>`. Copy it before starting services?"
+
+   - Option 1: "Yes — copy from `<sibling>`"
+   - Option 2: "No — I'll provide it another way"
+
+4. If not found anywhere, report and ask how to proceed.
+
+Skip silently when no env file is referenced. The point is to catch the common worktree-bootstrap miss, not to mandate any specific file.
+
 ### Step 5: Determine Start Commands
 
 For each required service that isn't already running, figure out how to start it. Propose the command so there's a shared understanding.
@@ -174,12 +217,33 @@ frontend             ~/Github/frontend                  npm run dev
 ────────────────────────────────────────────────────────────────
 ```
 
-Use `AskQuestion`:
+Use `AskUserQuestion`:
 - Option 1: "Looks good, start them"
 - Option 2: "I need to edit some commands"
 
 If the user needs edits, collect corrections and re-present.
 
+### Step 5.5: Fresh-Worktree Install Probe
+
+Before launching `npm run dev` (or equivalent) in a Node service, check whether `node_modules/` is present and current. Stale or missing `node_modules/` causes silent runtime failures that look like the service is broken when actually the install is just missing.
+
+For each Node service the user selected:
+
+1. If `<service-dir>/node_modules/` is missing entirely → install is required.
+2. If `<service-dir>/package-lock.json` is newer than `<service-dir>/node_modules/.package-lock.json` → install is stale.
+3. Otherwise → install is current, no action needed.
+
+When install is required or stale, propose via `AskUserQuestion`:
+
+> "`<service-name>` needs a fresh `npm install` before starting (node_modules is missing/stale). Run `npm install --prefer-offline --no-audit --no-fund` now?"
+
+- Option 1: "Yes — install now"
+- Option 2: "No — skip; I know it's fine"
+
+**Never symlink `node_modules/` from a sibling worktree.** webpack's `resolve.symlinks: true` default rewrites paths to the shared real location; asset-identity tracking fails with `Can't handle conflicting asset info for sourceFilename`. Run a real per-worktree install.
+
+For non-Node services (Go, Rust, Python), skip this probe — their build systems handle dependency caching differently.
+
 ### Step 6: Start Services
 
 For each service, launch in the background:
@@ -191,10 +255,7 @@ echo $!
 
 Capture the PID. Write all service entries to `/tmp/muggle-test-prepare.json`.
 
-**Startup verification** — after a short pause (~3-5 seconds per service), check:
-
-1. PID is alive: `kill -0 <pid> 2>/dev/null`
-2. Port is listening (if known): `lsof -iTCP:<port> -sTCP:LISTEN -nP 2>/dev/null`
+**Startup verification** — first confirm the PID is alive (`kill -0 <pid> 2>/dev/null`), then run the two-stage readiness probe per [`_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md) against `/tmp/muggle-prepare-<service-name>.log`. Cap log-tail at 60s. Halt on whatever it surfaces; do not re-implement the ready-signal patterns here.
 
 If a service's PID dies immediately, read the last 20 lines of its log and show the user: