@muggleai/works 5.0.1 → 5.0.3

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

@@ -1,6 +1,6 @@
 ---
 name: muggle-test
-description: "Run change-driven E2E acceptance testing using Muggle AI — detect the user's recent code changes (local diff or a PR), map them to affected user flows, then run real-browser acceptance tests on localhost or a deployed preview/staging URL, publish results to the dashboard, and post a screenshot summary to the PR. Use this whenever the user wants to test, validate, check, or regression-test their own changes or work — 'test my changes', 'validate my changes', 'regression test my work', 'make sure I didn't break anything', 'did my recent commits/changes break anything or any user flows?', 'test before I push' — and especially as the acceptance-test gate before opening a pull request or merging (e.g. 'validate my changes before I open the PR' means run the acceptance suite, not just a completion checklist). The defining signal is change-driven validation of in-progress work tied to a commit, push, PR, or merge. For testing one specific named feature/flow use muggle-test-feature-local; this is not importing existing tests, configuring preferences, or replaying a single named script."
+description: "Change-driven E2E acceptance testing with Muggle AI: detect the user's recent code changes (local diff or a PR), map them to affected user flows, run real-browser tests on localhost or a preview/staging URL, publish results, and post a screenshot summary to the PR. Use whenever the user wants to test, validate, or regression-test their own in-progress changes or work — \"make sure I didn't break anything\", \"did my recent commits break any user flows?\", \"test before I push\" — especially as the acceptance gate before opening or merging a PR. The defining signal is change-driven validation tied to a commit, push, PR, or merge. For one specific named feature/flow use muggle-test-feature-local; not for importing existing tests, configuring preferences, or replaying a single named script."
 ---
 
 # Muggle Test — Change-Driven E2E Acceptance Router
@@ -415,53 +415,15 @@ Use `AskUserQuestion`:
 
 This is a suggestion, not automatic invocation. Skip silently if every test passed cleanly.
 
-## Tool Reference
-
-| Phase | Tool | Mode |
-|:------|:-----|:-----|
-| Auth | `muggle-remote-auth-status` | Both |
-| Auth | `muggle-remote-auth-login` | Both |
-| Auth | `muggle-remote-auth-poll` | Both |
-| Project | `muggle-remote-project-list` | Both |
-| Project | `muggle-remote-project-create` | Both |
-| Use Case | `muggle-remote-use-case-list` | Both |
-| Use Case | `muggle-remote-use-case-create-from-prompts` | Both |
-| Test Case | `muggle-remote-test-case-list-by-use-case` | Both |
-| Test Case | `muggle-remote-test-case-generate-from-prompt` | Both |
-| Test Case | `muggle-remote-test-case-create` | Both |
-| Test Case | `muggle-remote-test-case-get` | Both |
-| Execute (regen) | `muggle-local-execute-test-generation` | Local |
-| Execute (replay) | `muggle-local-execute-replay` | Local |
-| Replay action script fetch | `muggle-remote-test-script-get`, `muggle-remote-action-script-get` | Local replay |
-| Execute (regen) | `muggle-remote-workflow-start-test-script-generation` | Remote |
-| Execute (replay) | `muggle-remote-workflow-start-test-script-replay` | Remote |
-| Failure-mode telemetry | `muggle-local-telemetry-event-emit` | Both |
-| Results | `muggle-local-run-result-get` | Local |
-| Results | `muggle-remote-wf-get-ts-gen-latest-run`, `muggle-remote-wf-get-ts-replay-latest-run` | Remote |
-| Publish | `muggle-local-publish-test-script` | Local |
-| Per-step screenshots (for walkthrough) | `muggle-remote-test-script-get` | Both |
-| Browser | `open` (shell command) | Both |
-| PR walkthrough | `muggle-pr-visual-walkthrough` (shared skill) | Both |
-
-## Guardrails
-
-- **Always confirm intent first** — never assume local vs remote without asking
-- **PR URLs always run in a dedicated worktree** — never switch the user's main checkout. Materialize per [`_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md) and pass that path as `cwd` to local execute tools; the cross-worktree single-flight lock relies on it to serialize concurrent runs from different branches.
-- **User MUST select project** — present clickable options via `AskUserQuestion`, wait for explicit choice, never auto-select
-- **Best-effort shortlist use cases** — use the change summary to narrow the list to the most relevant 1–5 use cases and pre-check them; never dump every use case in the project on the user. Always leave an escape hatch to reveal the full list.
-- **Best-effort shortlist test cases** — same idea: pre-check the test cases most relevant to the change summary; never enumerate every test case attached to a use case. Always leave an escape hatch to reveal the full list.
-- **Use `AskUserQuestion` for every selection** — never ask the user to type a number; always present clickable options
-- **Auto-detect localhost URL when possible**; only fall back to free-text when nothing is listening on a common port
-- **Parallelize independent cloud jobs** — when creating N use cases, generating/creating N test cases, fetching N test case details, starting N remote workflows, polling N workflow runtimes, publishing N local runs, or fetching N per-step test scripts, issue all N calls in a single message so they fan out in parallel. The only tolerated sequential loop is local Electron execution (one browser, one test at a time). For use case creation specifically, use the native batch form of `muggle-remote-use-case-create-from-prompts` (all descriptions in one `instructions` array) instead of parallel calls.
-- **One atomic behavior per test case** — every test case verifies exactly one user-observable behavior. Never bundle signup/login/navigation/bootstrap/teardown into a test case body. Ordering and dependencies are Muggle Test's service responsibility, not the skill's.
-- **Never consolidate the generator's output** — if `muggle-remote-test-case-generate-from-prompt` returns N micro-tests, accept all N; never merge them into fewer test cases, even if "the plan" says 4 UC / 4 TC.
-- **Never skip the generate→review cycle** — always present generated test cases to the user before calling `muggle-remote-test-case-create`, even when you're confident. "I'll skip the review and create directly" is always wrong.
-- **Never silently drop test cases** — log failures and continue, then report them
-- **Never guess the URL** — always ask the user for localhost or preview URL
-- **Always publish before opening browser** — the dashboard needs the published data to show results
-- **Delegate PR posting to `muggle-pr-visual-walkthrough`** — never inline the walkthrough markdown or call `gh pr comment` directly from this skill; ask the user and hand off
-- **Can be invoked at any state** — if the user already has a project or use cases set up, skip to the relevant step rather than re-doing everything
-
-## Agent Dispatch
-
-When used in a multi-agent team (e.g., muggle-ai-teams), this skill is available through the **acceptance-tester** agent at `plugin/agents/acceptance-tester.md`. Orchestrators can dispatch it via `Agent()` instead of invoking this skill directly. The agent wraps this skill and four others (muggle-test-import, muggle-preferences, muggle-repair, muggle-status) and returns structured test results with blocking issues and suggested fixes for coding agents to act on.
+## Non-negotiables
+
+Each rule below is covered in-step above; these are the ones this skill most often violates, kept here as reinforcement:
+
+- **Test-case shape** — never skip the generate→review cycle, never consolidate the generator's micro-tests, one atomic behavior per test case. Creating test cases directly or merging the generator's output is the single most frequent mistake.
+- **Confirm intent before acting** — local vs remote; never guess the localhost/preview URL.
+- **PR URLs run in a dedicated worktree** — never switch the user's main checkout; pass that worktree as `cwd`.
+- **Every selection uses `AskUserQuestion`** — never ask the user to type a number; the user picks the project (never auto-select).
+- **Parallelize independent cloud jobs**; the only sequential loop is local Electron execution (one browser).
+- **Publish before opening the browser**, and delegate PR posting to `muggle-pr-visual-walkthrough` — never inline the walkthrough or call `gh pr comment` here.
+
+Phase→tool map and multi-agent (acceptance-tester) dispatch: [`reference.md`](reference.md).

package/plugin/skills/muggle-test/reference.md

@@ -0,0 +1,35 @@
+# muggle-test reference
+
+Lookup material pulled out of `SKILL.md` to keep the always-loaded body lean. Every tool here is also named inline in the step that uses it — consult this only when you want the full phase→tool map in one place.
+
+## Tool Reference
+
+| Phase | Tool | Mode |
+|:------|:-----|:-----|
+| Auth | `muggle-remote-auth-status` | Both |
+| Auth | `muggle-remote-auth-login` | Both |
+| Auth | `muggle-remote-auth-poll` | Both |
+| Project | `muggle-remote-project-list` | Both |
+| Project | `muggle-remote-project-create` | Both |
+| Use Case | `muggle-remote-use-case-list` | Both |
+| Use Case | `muggle-remote-use-case-create-from-prompts` | Both |
+| Test Case | `muggle-remote-test-case-list-by-use-case` | Both |
+| Test Case | `muggle-remote-test-case-generate-from-prompt` | Both |
+| Test Case | `muggle-remote-test-case-create` | Both |
+| Test Case | `muggle-remote-test-case-get` | Both |
+| Execute (regen) | `muggle-local-execute-test-generation` | Local |
+| Execute (replay) | `muggle-local-execute-replay` | Local |
+| Replay action script fetch | `muggle-remote-test-script-get`, `muggle-remote-action-script-get` | Local replay |
+| Execute (regen) | `muggle-remote-workflow-start-test-script-generation` | Remote |
+| Execute (replay) | `muggle-remote-workflow-start-test-script-replay` | Remote |
+| Failure-mode telemetry | `muggle-local-telemetry-event-emit` | Both |
+| Results | `muggle-local-run-result-get` | Local |
+| Results | `muggle-remote-wf-get-ts-gen-latest-run`, `muggle-remote-wf-get-ts-replay-latest-run` | Remote |
+| Publish | `muggle-local-publish-test-script` | Local |
+| Per-step screenshots (for walkthrough) | `muggle-remote-test-script-get` | Both |
+| Browser | `open` (shell command) | Both |
+| PR walkthrough | `muggle-pr-visual-walkthrough` (shared skill) | Both |
+
+## Agent Dispatch
+
+In a multi-agent team (e.g. muggle-ai-teams), this skill is reachable through the **acceptance-tester** agent at `plugin/agents/acceptance-tester.md`. Orchestrators dispatch it via `Agent()` instead of invoking the skill directly. The agent wraps this skill and four others (muggle-test-import, muggle-preferences, muggle-repair, muggle-status) and returns structured test results with blocking issues and suggested fixes for coding agents to act on.

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

@@ -1,15 +1,6 @@
 ---
 name: muggle-test-import
-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 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 Test scripts, scan a site, generate new
-  tests from scratch, or check existing test results.
+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 the user wants to import, migrate, load, or convert existing test files or docs into Muggle Test — import my playwright tests, migrate from cypress to muggle, upload my PRD to muggle, turn this feature file into muggle test cases, or any .spec.ts/.cy.js/.feature/.md file plus muggle. DO NOT trigger for running or replaying scripts, scanning a site, generating new tests from scratch, or checking results."
 ---
 
 # Muggle Test Import

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

@@ -1,6 +1,6 @@
 ---
 name: muggle-test-prepare
-description: "Use this skill to get a user's local environment ready before running E2E acceptance tests — verifying that the dev servers, APIs, and sibling services they need are actually up and responding, and offering to start whatever is missing (with approval at each step). Trigger whenever the user wants to confirm that specific ports or localhost URLs are listening/up before testing (e.g. 'check if localhost:3000 and the api on 8080 are listening', 'are my services up?'), make sure required services are running, spin up or prepare their local dev stack, or verify their setup — and whenever another muggle skill (muggle-test, muggle-do, muggle-test-feature-local) needs services running but they're not listening on the expected ports. This is environment readiness and service startup, not running the tests themselves."
+description: "Get a user's local environment ready before running E2E acceptance tests — verify the dev servers, APIs, and sibling services they need are up and responding, and offer to start whatever is missing (with approval per step). Trigger when the user wants to confirm specific ports or localhost URLs are listening before testing (check if localhost:3000 and the api on 8080 are up, are my services running), spin up their local dev stack, or verify their setup — and whenever another muggle skill (muggle-test, muggle-do, muggle-test-feature-local) needs services running but they're not. This is environment readiness and service startup, not running the tests."
 ---
 
 # Muggle Test Prepare
@@ -62,6 +62,7 @@ Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-ga
 |------------|-------|
 | `autoRebase` | [rebase-check](./steps/rebase-check.md) — rebase onto `origin/<default>` before starting dev servers |
 | `reusePreparePlan` | [reuse-plan](./steps/reuse-plan.md) — reuse the saved prepare plan for this stack, or rediscover |
+| `autoSelectLocalHost` | [check-running](./steps/check-running.md) — reuse the recorded dev-server URL silently, or confirm it each run |
 
 ## Workflow
 
@@ -111,6 +112,8 @@ After a test run, the caller can re-invoke for cleanup or leave services running
 
 ## Guardrails
 
+- **Never invent or default a host/port** — the dev-server URL is a recorded value, not a guess. Resolve it from `<repo>/.muggle-ai/last-host.json` (the [`autoSelectLocalHost`](../muggle-preferences/preference-gates/autoSelectLocalHost.md) cache) before probing ports; a framework default like `:3000` is never a fallback. See [check-running](./steps/check-running.md).
+- **No silent auto-selection without a gate** — when no preference authorizes a silent choice (host, restart, kill), confirm with the user. A gate set to `always` is the only license to skip the question; absent that, ask.
 - **Verify first, offer to start second** — check what's already running before proposing to start anything.
 - **The user may prefer to start services themselves** — always offer that option.
 - **Never start a process the user didn't approve.**

package/plugin/skills/muggle-test-prepare/steps/check-running.md

@@ -1,5 +1,18 @@
 # Check what's already running
 
+## Resolve the target host first
+
+The dev-server URL the tests will hit is a **recorded value, not a guess** — resolve it before probing anything.
+
+1. Read the cached host with `muggle-local-last-host-get`. It reads `<cwd>/.muggle-ai/last-host.json`; a worktree usually has **no cache of its own**, so when the worktree returns nothing, pass the **main** working-tree root as `cwd` — `git rev-parse --git-common-dir`, then its parent directory.
+2. Apply the [`autoSelectLocalHost`](../../muggle-preferences/preference-gates/autoSelectLocalHost.md) gate (read its value from the `Muggle Test Preferences` session-context line; absent → `ask`):
+   - `always` **and** a cache exists → use it silently: `Using saved local URL {lastHost}`.
+   - otherwise (`ask` / `never`, or no cache) → **confirm before using any host.** Run the gate's Picker 1 with `{lastHost}` (cached URL, omitted when absent) and `{suggestedHost}` (a port you actually detect listening). Never auto-pick, and never fall back to a framework default like `:3000`; if nothing is cached or detected, ask the user to type the URL.
+
+The resolved host fixes the **expected** dev-server port for the detection below — probe that port; don't infer the target from whichever port happens to be listening.
+
+## Detect listening services
+
 Run port detection and (when an app declares a backend URL) backend-health probe per [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md). Cross-reference hits against selected service directories.
 
 > "**backend-api** is already listening on port 3001 (PID 54321) — looks good."

package/plugin/skills/muggle-test-regenerate-missing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-test-regenerate-missing
-description: "Bulk-regenerate test scripts for every test case in a Muggle AI project that doesn't currently have an active script. Scans the project, finds test cases stuck in DRAFT or GENERATION_PENDING (no usable script attached), shows the user the list, and on approval kicks off bulk remote test script generation via the Muggle Test cloud. Use this skill whenever the user asks to 'regenerate missing scripts', 'fill in missing test scripts', 'generate scripts for test cases without one', 'regen all the test cases that don't have scripts', 'rebuild scripts for stale test cases', 'fix test cases with no script', 'bulk regenerate', or any phrasing that means 'kick off script generation across a project for the cases that need it'. Triggers on: 'regenerate missing test scripts', 'generate scripts for all empty test cases', 'fill the gaps in my test scripts', 'bulk test script regen', 'all my test cases without active scripts'. This is the go-to skill for project-wide script catch-up — it handles discovery, filtering, confirmation, and remote workflow dispatch end-to-end."
+description: "Bulk-regenerate test scripts for every test case in a Muggle AI project that has no active script. Scans the project, finds test cases stuck in DRAFT or GENERATION_PENDING, shows the user the list, and on approval kicks off bulk remote script generation via the Muggle Test cloud. Use when the user wants to regenerate missing scripts, fill in missing test scripts, generate scripts for test cases without one, rebuild scripts for stale test cases, or bulk regenerate across a project. Handles discovery, filtering, confirmation, and remote dispatch end-to-end."
 ---
 
 # Muggle Test — Regenerate Missing Test Scripts