@muggleai/works 5.9.0 → 5.10.0

package/plugin/scripts/guardrails.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync } from 'fs';
 import { isAbsolute, resolve, join } from 'path';
 import { homedir } from 'os';
 
@@ -43,6 +43,7 @@ ${input2.tool_response?.output ?? ""}`;
 // src/guardrails/constants.ts
 var GH_PR_MERGED_LINE = /\b(?:Merged|Squashed and merged|Rebased and merged) pull request [\w./-]*#(\d+)/;
 var GH_PR_CLOSED_LINE = /\bClosed pull request [\w./-]*#(\d+)/;
+var GH_PR_REOPENED_LINE = /\bReopened pull request [\w./-]*#(\d+)/;
 var PR_MONITOR_TERMINAL_LINE = /\bTERMINAL pr=(\d+): (MERGED|CLOSED)\b/;
 var MAX_PR_TERMINAL_BLOCKS = 3;
 var MAX_WATCH_BLOCKS = 3;
@@ -71,6 +72,23 @@ function detectPrTerminal(input2) {
   }
   return null;
 }
+function detectPrReopened(input2) {
+  if (input2.tool_name !== "Bash") return null;
+  const response = input2.tool_response;
+  const haystack = [response?.stdout, response?.stderr, response?.output, response?.content].filter((part) => typeof part === "string").join("\n");
+  const reopenedMatch = haystack.match(GH_PR_REOPENED_LINE);
+  return reopenedMatch ? Number(reopenedMatch[1]) : null;
+}
+function applyPrReopened(state, prNumber) {
+  const pending = state.terminalPending ?? [];
+  const handled = state.terminalHandled ?? [];
+  if (!pending.includes(prNumber) && !handled.includes(prNumber)) return state;
+  return {
+    ...state,
+    terminalPending: pending.filter((number) => number !== prNumber),
+    terminalHandled: handled.filter((number) => number !== prNumber)
+  };
+}
 function applyPrTerminalDetected(state, prNumber) {
   const pending = state.terminalPending ?? [];
   const handled = state.terminalHandled ?? [];
@@ -144,7 +162,6 @@ function e2eGateDecision(state, maxBlocks = MAX_E2E_BLOCKS) {
   if (blockCount >= maxBlocks) return { action: "release" /* Release */, blockCount };
   return { action: "block" /* Block */, blockCount: blockCount + 1 };
 }
-var HEARTBEAT_FRESH_MS = 15 * 60 * 1e3;
 var WATCH_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_WATCH_SKIP\b/;
 function isWatchSkipMarker(cmd) {
   return WATCH_SKIP_MARKER.test(cmd);
@@ -153,38 +170,13 @@ function applyWatchSkip(state, skipped) {
   if (!skipped || state.watchSkipped === true) return state;
   return { ...state, watchSkipped: true };
 }
-function slotHasArmedWatcher(slotDir) {
-  if (existsSync(join(slotDir, "result.md"))) return true;
-  const pidFile = join(slotDir, "watch.pid");
-  if (existsSync(pidFile)) {
-    const pid = Number.parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
-    if (Number.isInteger(pid) && pid > 0) {
-      try {
-        process.kill(pid, 0);
-        return true;
-      } catch (err) {
-        if (err.code === "EPERM") return true;
-      }
-    }
-  }
-  const beat = join(slotDir, "watch-heartbeat");
-  if (existsSync(beat)) {
-    try {
-      if (Date.now() - statSync(beat).mtimeMs < HEARTBEAT_FRESH_MS) return true;
-    } catch {
-      return false;
-    }
-  }
-  return false;
-}
-function findUnarmedHandledPrs(handledUrls, sessionsDirOverride) {
+function findUntrackedHandledPrs(handledUrls, sessionsDirOverride) {
   if (handledUrls.length === 0) return [];
   const sessionsDir = join(homedir(), ".muggle-ai", "muggle-do", "sessions");
   if (!existsSync(sessionsDir)) return [...handledUrls];
-  const watchedUrls = /* @__PURE__ */ new Set();
+  const trackedUrls = /* @__PURE__ */ new Set();
   for (const slug of readdirSync(sessionsDir)) {
-    const slotDir = join(sessionsDir, slug);
-    const prsFile = join(slotDir, "prs.json");
+    const prsFile = join(sessionsDir, slug, "prs.json");
     if (!existsSync(prsFile)) continue;
     let slotUrl;
     try {
@@ -194,21 +186,23 @@ function findUnarmedHandledPrs(handledUrls, sessionsDirOverride) {
     } catch {
       continue;
     }
-    if (slotUrl && handledUrls.includes(slotUrl) && slotHasArmedWatcher(slotDir)) {
-      watchedUrls.add(slotUrl);
-    }
+    if (slotUrl) trackedUrls.add(slotUrl);
   }
-  return handledUrls.filter((url) => !watchedUrls.has(url));
+  return handledUrls.filter((url) => !trackedUrls.has(url));
 }
-function watchGateDecision(state, owedUrls, maxBlocks = MAX_WATCH_BLOCKS) {
+function watchGateDecision(state, untrackedPrUrls, maxBlocks = MAX_WATCH_BLOCKS) {
   const blockCount = state.watchBlockCount ?? 0;
-  if (state.watchSkipped === true || owedUrls.length === 0) {
-    return { action: "none" /* None */, blockCount, owed: owedUrls };
+  if (state.watchSkipped === true || untrackedPrUrls.length === 0) {
+    return { action: "none" /* None */, blockCount, untracked: untrackedPrUrls };
   }
   if (blockCount >= maxBlocks) {
-    return { action: "release" /* Release */, blockCount, owed: owedUrls };
+    return { action: "release" /* Release */, blockCount, untracked: untrackedPrUrls };
   }
-  return { action: "block" /* Block */, blockCount: blockCount + 1, owed: owedUrls };
+  return {
+    action: "block" /* Block */,
+    blockCount: blockCount + 1,
+    untracked: untrackedPrUrls
+  };
 }
 
 // src/guardrails/detectBuildIntent.ts
@@ -323,6 +317,13 @@ Per the autoWatchPR preference, a muggle-pr-followup watcher should handle its i
   return envelope("PostToolUse", ctx, host);
 }
 function prTerminal() {
+  const reopenedPrNumber = detectPrReopened(input);
+  if (reopenedPrNumber !== null) {
+    const state2 = readState(sessionId);
+    const next2 = applyPrReopened(state2, reopenedPrNumber);
+    if (next2 !== state2) writeState(next2);
+    return "{}";
+  }
   const terminalEvent = detectPrTerminal(input);
   if (!terminalEvent) return "{}";
   const state = readState(sessionId);
@@ -372,21 +373,21 @@ function e2eGate() {
 }
 function watchGate() {
   const state = readState(sessionId);
-  const owed = findUnarmedHandledPrs(state.prsHandled);
-  const decision = watchGateDecision(state, owed);
+  const untrackedPrUrls = findUntrackedHandledPrs(state.prsHandled);
+  const decision = watchGateDecision(state, untrackedPrUrls);
   if (decision.action === "none" /* None */ || decision.action === "release" /* Release */) {
     return "{}";
   }
   state.watchBlockCount = decision.blockCount;
   writeState(state);
-  const prList = decision.owed.join(", ");
-  const reason = decision.blockCount === 1 ? `Do not end the turn yet. A PR was opened this session but has no armed watcher: ${prList}. muggle-do Stage 8 seeds the watcher slot and arms one watcher per opened PR \u2014 arm it now with /muggle:muggle-pr-followup ${decision.owed[0]} (or reconcile). If this PR should NOT be watched (autoWatchPR=never, a manually-opened PR, one handed off elsewhere, or already merged/closed), tell the user why and run \`echo "MUGGLE_WATCH_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `Watcher hand-off still owed for ${prList} (reminder ${decision.blockCount}/${MAX_WATCH_BLOCKS}): arm via /muggle:muggle-pr-followup, or record a legitimate skip via \`echo "MUGGLE_WATCH_SKIP: <reason>"\`.`;
+  const prList = decision.untracked.join(", ");
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. A PR was opened this session but no muggle-do session slot tracks it: ${prList}. Seed the slot and hand off per muggle-do Stage 8 \u2014 /muggle:muggle-pr-followup ${decision.untracked[0]} does both. Seeding is what matters: once a slot exists, reconcile arms it at the next session start and finalizes it when the PR goes terminal, so an unarmed slot is fine but no slot means nothing ever picks this PR up. If it genuinely should not be tracked (autoWatchPR=never, handed off elsewhere), tell the user why and run \`echo "MUGGLE_WATCH_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `PR hand-off still owed for ${prList} (reminder ${decision.blockCount}/${MAX_WATCH_BLOCKS}): seed a slot via /muggle:muggle-pr-followup, or record a legitimate skip via \`echo "MUGGLE_WATCH_SKIP: <reason>"\`.`;
   return blockStop(reason, host);
 }
 function reportGate() {
-  const result = evaluateReportPost(input);
-  if (!result.deny || !result.reason) return "{}";
-  return denyTool(result.reason, host);
+  const reportPostVerdict = evaluateReportPost(input);
+  if (!reportPostVerdict.deny || !reportPostVerdict.reason) return "{}";
+  return denyTool(reportPostVerdict.reason, host);
 }
 function buildRouter() {
   if (!detectBuildIntent(input.prompt ?? "")) return "{}";

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

@@ -25,6 +25,7 @@ Resolve without prompting; use as questionnaire defaults:
 3. Candidate projects — `muggle-remote-project-list`, ranked against the repo's dev URL and the PR title.
 4. Existing test-user secrets — `muggle-remote-secret-list` per candidate project (`managed_profile_email` / `managed_profile_password`).
 5. Auth0 tenant for local dev — grep the repo env file for `*AUTH0_DOMAIN*`.
+6. E2E run instructions — read `~/.muggle-ai/e2e-instructions/<key>.md` when it exists, keyed on this stack's identity. It records startup order, manual steps, and local gotchas. Treat it as read-only input: surface its gotchas rather than re-deriving them, and never re-ask what it already answers. Absent is normal — proceed without it.
 
 ## Questions
 

package/plugin/skills/muggle/SKILL.md

@@ -12,7 +12,7 @@ Use this as the top-level Muggle Test command router.
 
 ## Preferences
 
-User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: defaults → `~/.muggle-ai/preferences.json` (global) → `<repo>/.muggle-ai/preferences.json` (project). Treat absent prefs as `ask`.
+User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: defaults → `~/.muggle-ai/preferences.json`. Preferences are user-level and apply to every repo. Treat absent prefs as `ask`.
 
 This router skill itself does not gate any decision on a preference — it just routes user intent to a downstream skill. Each downstream skill consults its own preferences. For example, `checkForUpdates` is consulted by `muggle-status` (Check 4), not here.
 

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

@@ -29,4 +29,4 @@ Pick the operation, then read its op file for the procedure.
 - **Current values**: session-context line `Muggle Test Preferences key=value …`. Default `ask`.
 - **Per-key files**: `preference-gates/<key>.md`. Key list = `ls preference-gates/*.md` minus `README.md`.
 - **Allowed values**: `always`/`never`/`ask` (or `local`/`remote`/`ask` for `defaultExecutionMode`).
-- **Scope**: `global` default; `project` if user says "for this project" / "just this repo" (pass `cwd`).
+- **Scope**: preferences are user-level. Every write lands in `~/.muggle-ai/preferences.json` and applies to every repo. If the user asks for a per-project setting, say it isn't supported and confirm before setting it everywhere.

package/plugin/skills/muggle-preferences/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "muggle-preferences",
+  "notes": "These evals test the PLAN behavior after per-project preferences were removed. Preferences resolve from defaults overlaid by ~/.muggle-ai/preferences.json only; muggle-local-preferences-set rejects a `scope` argument. The prompts ask for a step-by-step plan rather than execution, since writing preferences mutates the user's home directory. Assertions check that the plan never offers a per-project scope, never passes `scope`, and confirms before applying a setting the user framed as project-specific.",
+  "evals": [
+    {
+      "id": 0,
+      "eval_name": "per-project-request-must-not-be-honoured-silently",
+      "prompt": "For this repo only, I want the Electron browser to actually show up when tests run — it's a UI-heavy project and I like watching it. Leave my other projects alone. Walk me through what you'd do.",
+      "files": [],
+      "assertions": [
+        { "name": "states_preferences_are_user_level", "text": "Plan states that preferences are user-level and apply to every repo, so a per-repo setting is not supported." },
+        { "name": "does_not_offer_project_scope", "text": "Plan does NOT offer a 'this project only' option, and does not claim a project-scoped preferences file can be written." },
+        { "name": "no_scope_argument", "text": "Plan does not pass a `scope` argument to muggle-local-preferences-set; it calls the tool with key and value only." },
+        { "name": "confirms_before_global_write", "text": "Plan explicitly confirms with the user before writing, because the user asked for one repo and the write will affect all of them." },
+        { "name": "names_the_correct_key", "text": "Plan identifies showElectronBrowser as the key to set." },
+        { "name": "does_not_invent_a_workaround", "text": "Plan does not invent a per-repo mechanism (env var, local override file, wrapper script) to simulate project scope." }
+      ]
+    },
+    {
+      "id": 1,
+      "eval_name": "list-shows-user-level-resolution",
+      "prompt": "show me my muggle settings and where they're stored",
+      "files": [],
+      "assertions": [
+        { "name": "resolution_is_two_layer", "text": "Plan describes resolution as defaults overlaid by ~/.muggle-ai/preferences.json, with no third per-project layer." },
+        { "name": "names_the_global_path", "text": "Plan names ~/.muggle-ai/preferences.json as the storage location." },
+        { "name": "no_project_file_mentioned", "text": "Plan does not tell the user that a preferences file inside the repo is read or honoured." },
+        { "name": "reads_from_session_context_or_tool", "text": "Plan reads current values from the session-context preferences line or the preferences tool rather than guessing." }
+      ]
+    },
+    {
+      "id": 2,
+      "eval_name": "stale-in-repo-file-explained",
+      "prompt": "I've got a .muggle-ai/preferences.json checked into my repo with autoLogin set to never, but muggle keeps logging me in automatically. Why isn't it being picked up?",
+      "files": [],
+      "assertions": [
+        { "name": "explains_file_is_not_read", "text": "Plan explains that a preferences file inside the project is no longer read — preferences are user-level." },
+        { "name": "points_at_global_file", "text": "Plan points the user at ~/.muggle-ai/preferences.json as the file that actually takes effect." },
+        { "name": "offers_to_reapply_globally", "text": "Plan offers to re-apply the affected key globally, noting it will then apply to every repo." },
+        { "name": "does_not_delete_user_file", "text": "Plan does not delete or rewrite the user's in-repo preferences file without asking." },
+        { "name": "no_scope_argument", "text": "Plan does not attempt to pass a `scope` argument to make the project file work." }
+      ]
+    }
+  ]
+}

package/plugin/skills/muggle-preferences/ops/change-one.md

@@ -2,7 +2,7 @@
 
 1. Verify `preference-gates/<key>.md` exists. If not, list `preference-gates/*.md` and ask.
 2. Read it. Run **Picker 1** with the options defined in the gate file, plus an additional `Ask me each time` (sub: `Prompt me at decision time.`) → `ask`.
-3. `muggle-local-preferences-set` with the mapped value, `scope: "global"`.
+3. `muggle-local-preferences-set` with the mapped value.
 4. Confirm: `Set <key> to <value>.`
 
 Skip Picker 2 — user explicitly asked to change.

package/plugin/skills/muggle-preferences/ops/configure.md

@@ -33,18 +33,17 @@ For each option: label = key name, description = first paragraph of `preference-
 - `multiSelect: true`, `header: "Branch hygiene"` — `autoUseWorktree`, `autoRebase`, `autoCleanup`
 - `multiSelect: false`, `header: "E2E acceptance"` — `autoE2ETest`. Options: `Always run Stage 6 at the end` (`always` — default), `Ask each cycle` (`ask`). No `never` option.
 - `multiSelect: false`, `header: "Default mode"` — `defaultExecutionMode`. Options: `Local — run on my computer` (`local`), `Remote — run in the Muggle Test cloud` (`remote`), `Ask each time` (don't change).
-- `multiSelect: false`, `header: "Scope"` — final scope question. Options: `Global (all repos)` (~/.muggle-ai/), `This project only` (.muggle-ai/ in repo).
 
-`AskUserQuestion` accepts up to 4 questions per call — split into two calls if needed (categories first, scope second).
+`AskUserQuestion` accepts up to 4 questions per call — split across calls.
 
 ## Step 4 — apply selections
 
-For each toggled key (multi-select questions): `muggle-local-preferences-set` with `value: "always"`. For `defaultExecutionMode`: only set if user picked Local/Remote (skip "Ask each time"). Pass `scope` from the scope question; pass `cwd` when scope is `project`.
+For each toggled key (multi-select questions): `muggle-local-preferences-set` with `value: "always"`. For `defaultExecutionMode`: only set if user picked Local/Remote (skip "Ask each time").
 
 ## Step 5 — `never` follow-up
 
-Ask: `Want any of these set to "never" (auto-skip without asking)? Name them, e.g. "never on showElectronBrowser", or say "no".`. For named keys, call `muggle-local-preferences-set` with `value: "never"`, same scope.
+Ask: `Want any of these set to "never" (auto-skip without asking)? Name them, e.g. "never on showElectronBrowser", or say "no".`. For named keys, call `muggle-local-preferences-set` with `value: "never"`.
 
 ## Step 6 — confirm
 
-One-liner summary: `Set autoLogin=always, openTestResultsAfterRun=always (global).`
+One-liner summary: `Set autoLogin=always, openTestResultsAfterRun=always.`

package/plugin/skills/muggle-preferences/ops/list.md

@@ -5,5 +5,5 @@
 3. Footer:
    ```
    Values: always · ask · never (defaultExecutionMode: local/remote/ask)
-   Scope:  global (~/.muggle-ai/) or project (.muggle-ai/ in repo root)
+   Stored: ~/.muggle-ai/preferences.json — applies to every repo
    ```

package/plugin/skills/muggle-preferences/ops/set.md

@@ -1,10 +1,9 @@
 # Set — direct (key + value)
 
-Trigger: user names both key and value (e.g. "set autoLogin to always", "make showElectronBrowser never for this project").
+Trigger: user names both key and value (e.g. "set autoLogin to always", "make showElectronBrowser never").
 
 1. Parse `key` and `value`.
 2. Verify `preference-gates/<key>.md` exists. If not, list `preference-gates/*.md` and ask.
 3. Validate `value` per Shared context.
-4. Resolve scope per Shared context.
-5. `muggle-local-preferences-set`.
-6. Confirm: `Set {key} to {value} ({scope}).`
+4. `muggle-local-preferences-set`.
+5. Confirm: `Set {key} to {value}.`

package/plugin/skills/muggle-preferences/preference-gates/README.md

@@ -11,8 +11,8 @@ which uses `local` / `remote` / `ask`).
 ## Resolution
 
 `SessionStart` injects a `Muggle Test Preferences` line (`key=value` pairs) from
-`~/.muggle-ai/preferences.json` (global) overlaid by
-`<repo>/.muggle-ai/preferences.json` (project). Absent → treat as `ask`.
+`~/.muggle-ai/preferences.json`. Preferences are user-level — there is no
+per-project layer. Absent → treat as `ask`.
 
 ## Gate behavior
 
@@ -48,7 +48,7 @@ Header `Remember this choice?`. Question: `"Always <restate Picker 1 choice in
 plain language> from now on, without asking?"`. Never put the raw key or
 `=` in the user-visible text.
 
-- `Yes, always` (sub: `You can change this later in muggle preferences.`) → `muggle-local-preferences-set` with the value Picker 1 mapped to, `scope: "global"`.
+- `Yes, always` (sub: `You can change this later in muggle preferences.`) → `muggle-local-preferences-set` with the value Picker 1 mapped to.
 - `Just this once` (sub: `I'll ask again next time.`) → don't save.
 
 A few keys override this template (their per-key file says how).

package/plugin/skills/muggle-preferences/preference-gates/autoSelectLocalHost.md

@@ -2,7 +2,7 @@
 
 Reuse the saved local dev server URL for this repo, or pick one each run. Substitute `{lastHost}` (the URL used in the previous run for this repo — omit the option entirely when no cache exists) and `{suggestedHost}` (auto-detected from running ports, e.g. `http://localhost:3000`).
 
-Cache lives at `<cwd>/.muggle-ai/last-host.json`. The calling skill **always** updates the cache after the user picks/types a URL — independent of Picker 2 — so `Use {lastHost}` reflects the most recent run.
+Cache lives in `~/.muggle-ai/last-host.json`, in the entry keyed on `<cwd>`. The calling skill **always** updates the cache after the user picks/types a URL — independent of Picker 2 — so `Use {lastHost}` reflects the most recent run.
 
 **Picker 1** — header `Local server`, question `"Which local URL should the test target?"`
 - `Use {lastHost}` — `From your last run in this repo.` → reuse cached URL. *Skip this option when no cache exists.*
@@ -11,7 +11,7 @@ Cache lives at `<cwd>/.muggle-ai/last-host.json`. The calling skill **always** u
 
 **Picker 2 — overrides shared template.** Fires after the user picks a URL.
 - Header `Remember this URL?`, question `"Always use {chosenHost} for this repo from now on, without asking?"`
-- `Yes, always` (sub: `You can change this later in muggle preferences.`) → `muggle-local-preferences-set` (`autoSelectLocalHost=always`, global). The cache is already up to date.
+- `Yes, always` (sub: `You can change this later in muggle preferences.`) → `muggle-local-preferences-set` (`autoSelectLocalHost=always`). The cache is already up to date.
 - `Just this once` (sub: `I'll ask again next time.`) → don't save the preference. The cache still updates.
 
 **Silent action**

package/plugin/skills/muggle-preferences/preference-gates/autoSelectProject.md

@@ -8,7 +8,7 @@ tail options like "Show full list" / "Create new project" are skill-defined).
 **Picker 2 — overrides shared template.** Fires only after picking an
 *existing* project; skip if user picked "Create new project".
 - Header `Reuse this project next time?`, question `"Always reuse {projectName} for this repo from now on, without asking?"`
-- `Yes, always` (sub: `You can change this later in muggle preferences.`) → call BOTH `muggle-local-preferences-set` (`autoSelectProject=always`, global) AND `muggle-local-last-project-set` (`cwd`, `projectId`, `projectUrl`, `projectName`).
+- `Yes, always` (sub: `You can change this later in muggle preferences.`) → call BOTH `muggle-local-preferences-set` (`autoSelectProject=always`) AND `muggle-local-last-project-set` (`cwd`, `projectId`, `projectUrl`, `projectName`).
 - `Just this once` (sub: `I'll ask again next time.`) → don't save.
 
 **Silent action**

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

@@ -128,7 +128,7 @@ If auth fails repeatedly, suggest: `muggle logout && muggle login` from terminal
 
 A **project** is where all your test results, use cases, and test scripts are grouped on the Muggle AI dashboard. Pick the project that matches what you're working on.
 
-The per-repo cache lives at `<cwd>/.muggle-ai/last-project.json` (managed via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for the `Muggle Test Last Project: id=… url=… name="…"` line in session context — if present, that's this repo's cached pick.
+The per-repo cache lives in `~/.muggle-ai/last-project.json`, in the entry keyed on `<cwd>` (managed via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for the `Muggle Test Last Project: id=… url=… name="…"` line in session context — if present, that's this repo's cached pick.
 
 Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line.
 - `always` + cache → use cached `projectId`, skip to Step 5. No cache → fall through to `ask`.

package/plugin/skills/muggle-test/execute-local.md

@@ -12,6 +12,8 @@
 
 Before anything else, invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md) — the readiness/service-start owner (idempotent; halt on what it surfaces). The URL gate below only *selects* the target; prepare is what guarantees something is listening and compiled.
 
+Then read `~/.muggle-ai/e2e-instructions/<key>.md` when it exists — this stack's recorded startup order, manual steps, and local gotchas. Use it to interpret what you see: a gotcha listed there explains a symptom that would otherwise read as a failure. Absent is normal.
+
 ## Pre-flight question — Local URL (gated by `autoSelectLocalHost`)
 
 Skill responsibilities (the rest is in `preference-gates/autoSelectLocalHost.md`):

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

@@ -29,6 +29,8 @@ Three gates apply, each per the standard procedure in [`preference-gates/README.
 
 Before any workflow step, invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md). Halt on what it surfaces.
 
+Then read `~/.muggle-ai/e2e-instructions/<key>.md` when it exists — this stack's recorded startup order, manual steps, and local gotchas. A gotcha listed there explains a symptom that would otherwise read as a failure. Absent is normal.
+
 ## UX Guidelines — Minimize Typing
 
 **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.
@@ -67,7 +69,7 @@ Gates run per `preference-gates/README.md`.
 
 ### 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 Test Last Project: id=… url=… name="…"` in session context.
+The per-repo project cache lives in `~/.muggle-ai/last-project.json`, in the entry keyed on `<cwd>` (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 Test Last Project` session line.
 - `always` + cache → use cached `projectId`, skip to use case selection. No cache → fall through to `ask`.

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

@@ -151,7 +151,7 @@ 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 Test Last Project: id=… url=… name="…"` in session context.
+The per-repo project cache lives in `~/.muggle-ai/last-project.json`, in the entry keyed on `<cwd>` (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 Test Last Project` session line.
 - `always` + cache → use cached `projectId`, skip to Step 6. No cache → fall through to `ask`.

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

@@ -48,7 +48,11 @@ All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
 
 `testing_scope` records what the user is testing (from [scope](./steps/scope.md)). `excluded_services` records services the user said can't run locally (from [viability-check](./steps/viability-check.md)).
 
-This file is **ephemeral runtime state**, not the saved recipe. The durable plan lives at `<repo>/.muggle-ai/prepare-plan.json` (or the parent-dir-keyed entry in `~/.muggle-ai/prepare-plans.json`) and is consulted in [reuse-plan](./steps/reuse-plan.md) before any other stage. The two files never merge. The `test-prepare-runner` agent writes this file during execution; the triage below and Cleanup read it.
+This file is **ephemeral runtime state**, not the saved recipe. The durable plan lives in `~/.muggle-ai/prepare-plans.json`, under the entry keyed on this stack, and is consulted in [reuse-plan](./steps/reuse-plan.md) before any other stage. The two files never merge. The `test-prepare-runner` agent writes this file during execution; the triage below and Cleanup read it.
+
+The prose companion to the plan is `~/.muggle-ai/e2e-instructions/<key>.md`, written by [e2e-instructions](./steps/e2e-instructions.md), holding startup order, manual steps, and local gotchas. The plan remains the single source of truth for each service's start command; the markdown never restates one.
+
+**Everything this skill saves is machine-local, user-level data and lives under the Muggle home directory — never inside the user's project.** A project directory is shared, versioned, and cloned onto machines set up differently; a local run recipe is none of those things. Both files are keyed on the same stack identity, so they stay in lockstep.
 
 **On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), `AskUserQuestion`:
 - Option 1: "Keep them running — skip to testing"
@@ -64,7 +68,7 @@ Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-ga
 | Preference | Gates |
 |------------|-------|
 | `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 |
+| `reusePreparePlan` | [reuse-plan](./steps/reuse-plan.md) — reuse the saved prepare plan for this stack, or rediscover; also [e2e-instructions](./steps/e2e-instructions.md), which goes stale for the same reason |
 | `autoSelectLocalHost` | [check-running](./steps/check-running.md) — reuse the recorded dev-server URL silently, or confirm it each run |
 
 ## Workflow
@@ -78,8 +82,9 @@ Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-ga
 | 2 | [scope](./steps/scope.md) | Frontend / backend / full stack |
 | 3 | [viability-check](./steps/viability-check.md) | Exclude services that can't run locally |
 | 4 | [identify-services](./steps/identify-services.md) | Pick required services + startup mode |
+| 5 | [e2e-instructions](./steps/e2e-instructions.md) | Capture startup order, manual steps, local gotchas (gated); persisted for reuse |
 
-The Decide phase's output is the **resolved prepare plan**: `services[]` (name, dir, start command, expected port, `external` flag, approval granted), `testingScope`, `excludedServices[]`, the recorded dev-server URL, and resolved gate outcomes.
+The Decide phase's output is the **resolved prepare plan**: `services[]` (name, dir, start command, expected port, `external` flag, approval granted), `testingScope`, `excludedServices[]`, the recorded dev-server URL, the E2E run instructions, and resolved gate outcomes.
 
 **Execute (agent).** Dispatch the `test-prepare-runner` agent (subagent type `muggle:test-prepare-runner`; bare `test-prepare-runner` where the plugin namespace is absent), synchronously, passing the resolved plan; it returns `READY` / `DEGRADED` plus the readiness table. The agent's own definition lists its stage files; in a harness with no agent/subagent facility, run the execute-phase stages ([check-running](./steps/check-running.md) through [readiness-report](./steps/readiness-report.md)) inline instead.
 
@@ -114,12 +119,13 @@ 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).
+- **Never invent or default a host/port** — the dev-server URL is a recorded value, not a guess. Read it from the last-host cache via `muggle-local-last-host-get` (the [`autoSelectLocalHost`](../muggle-preferences/preference-gates/autoSelectLocalHost.md) cache) before probing ports; a framework default like `:3000` is never a fallback. The cache's own storage location belongs to that tool — don't restate it here. 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** — approvals are granted in Decide and travel in the plan; the agent starts nothing outside it.
 - **Never read file contents outside confirmed directories** — folder names are discoverable; file contents require explicit user selection.
+- **Never write a credential into the E2E run instructions** — plaintext notes are not a secret store, and this is the file a user pastes when asking why their stack won't start. Record the env-var or secret name, never its value.
 - **Never leave orphan processes untracked** — every background PID goes into the tracking file.
 - **Never kill a process the user started independently** — `external: true` survives cleanup.
 - **Never assume start commands** — verify via indicator file; confirm with user.

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

@@ -4,7 +4,7 @@
 
 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.
+1. Read the cached host with `muggle-local-last-host-get`. It reads the entry keyed on `<cwd>` in `~/.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.

package/plugin/skills/muggle-test-prepare/steps/e2e-instructions.md

@@ -0,0 +1,100 @@
+# Stage 5 — E2E run instructions
+
+Capture what `prepare-plan.json` cannot express: the order services must come up in, steps that aren't a single command, and the local gotchas that make a healthy stack look broken. Persisted under `~/.muggle-ai/e2e-instructions/` and reused on later runs.
+
+Runs after [identify-services](./identify-services.md) — startup order and per-service gotchas are unanswerable until the service set is known.
+
+## Scope boundary
+
+`prepare-plan.json` owns the per-service start command. Never restate a command here; reference the plan. This file holds only what the plan has no field for:
+
+| Belongs here | Belongs in `prepare-plan.json` |
+|:-------------|:-------------------------------|
+| Order and dependencies between services | Each service's `name`, `dir`, `command`, `port` |
+| Steps that aren't one command (a migration to run first, a tunnel to open, a container to bring up by hand) | — |
+| Gotchas — slow first build, a port that isn't the framework default, a rate limit, a warning that is safe to ignore | — |
+
+## Resolve the saved file
+
+This is machine-local, user-level data. It lives under the Muggle home directory and never inside the user's project — a project directory is shared, versioned, and cloned by people whose machines are set up differently, and none of that is true of a local run recipe.
+
+One file per stack:
+
+```
+~/.muggle-ai/e2e-instructions/<key>.md
+```
+
+`<key>` is the absolute path of the working directory's parent — the same stack identity the global prepare plan keys its entries on — reduced to a filename-safe token by replacing every path separator, and any drive-letter colon, with `-`. Derive it from the resolved absolute path rather than assuming a separator character; they differ per platform.
+
+Missing → no saved instructions; run the capture below.
+
+## Gate `reusePreparePlan`
+
+Same gate as [reuse-plan](./reuse-plan.md) — this content goes stale for the same reason the service plan does, so one answer governs both. Only fires when a saved file was loaded.
+
+- `always` → reuse silently. Print `Reusing saved E2E run instructions`.
+- `never` → discard and run the capture.
+- `ask` → print the saved file, then Picker 1 from the gate contract. Reuse on `Reuse this plan`, capture on `Rediscover from scratch`.
+
+On the [reuse-plan](./reuse-plan.md) short-circuit path this stage is skipped along with the rest of the Decide phase; the saved file is loaded there and carried forward unchanged.
+
+## Capture
+
+Print the resolved service list first so the user answers against concrete names, then ask one `AskUserQuestion`, multi-select:
+
+> "Anything Muggle should know about running these locally?"
+
+- `Startup order matters` — `One service must be up before another, or something fails.`
+- `Manual steps` — `Something has to happen that isn't one of the start commands.`
+- `Known gotchas` — `Behaviour that looks like a failure but isn't, or a trap to avoid.`
+- `Nothing special` — `They start independently and just work.`
+
+`Nothing special` (or no selection) → write the sentinel from [Sentinel](#sentinel) and return. Do not re-ask on later runs; the sentinel is a recorded answer, not an empty file.
+
+Otherwise ask once more, free-text, naming only the selected categories. One turn — never a question per category.
+
+## Written format
+
+Fixed headings. Omit a section the user had nothing for; never emit an empty one.
+
+```markdown
+# E2E run instructions
+
+<!-- Managed by muggle-test-prepare. Hand-edits are preserved — re-run the skill to revise. -->
+
+**Updated:** 2026-08-04T12:00:00Z
+
+## Startup order
+
+api → worker → ui. The UI 500s on /dashboard when api isn't listening yet.
+
+## Manual steps
+
+Run `pnpm db:migrate` once after a fresh clone; the dev servers don't migrate on boot.
+
+## Local gotchas
+
+- First build after a clean install takes ~4 min. It is not hung.
+- UI is on :3999, not the Next.js default :3000.
+- Auth0 dev tenant rate-limits past ~20 logins/hour.
+```
+
+### Sentinel
+
+```markdown
+# E2E run instructions
+
+<!-- Managed by muggle-test-prepare. Hand-edits are preserved — re-run the skill to revise. -->
+
+**Updated:** 2026-08-04T12:00:00Z
+
+Nothing special — services start independently.
+```
+
+## Secrets
+
+Never write a credential value. A password, token, API key, or connection string with embedded credentials belongs in a secret store or an env file — not in plaintext notes. Living outside the project keeps this file out of version control, but it is still readable on disk and is exactly the kind of file a user pastes into an issue when asking why their stack won't come up.
+
+Record a **pointer** instead: the env-var name, or the name of the Muggle secret. `Set LOCAL_TEST_PASSWORD before running` is fine; the password is not.
+
+If the user's free text contains something that looks like a credential, drop it, write the pointer form, and say so in one line.

package/plugin/skills/muggle-test-prepare/steps/readiness-report.md

@@ -41,10 +41,7 @@ jq '{
 }' /tmp/muggle-test-prepare.json
 ```
 
-Resolve the write location:
-
-- If `git rev-parse --show-toplevel` succeeds (call the result `$REPO`) → write `$REPO/.muggle-ai/prepare-plan.json`. Create `$REPO/.muggle-ai/` if missing.
-- Else → upsert the entry under key `$(dirname "$PWD")` (absolute) in `~/.muggle-ai/prepare-plans.json`. Create the file as `{}` if missing.
+Upsert it under the stack's key — the absolute path of the working directory's parent — in `~/.muggle-ai/prepare-plans.json`, creating the file as `{}` if missing. The plan is machine-local, user-level data: it never goes inside the user's project, and resolving it requires no version-control tool.
 
 Then print, once:
 
@@ -54,3 +51,11 @@ Then print, once:
 ```
 
 If this run short-circuited via [reuse-plan](./reuse-plan.md), don't rewrite — but **do** refresh `updated` and any `command` that was re-derived during validation. Skip the announcement on the refresh path.
+
+## Save the E2E run instructions
+
+The instructions arrive resolved in the dispatch prompt — captured while the user was present, in [e2e-instructions](./e2e-instructions.md). Write them verbatim, in that stage's format, to the location it resolves: `~/.muggle-ai/e2e-instructions/<key>.md`. Create the directory if missing. This file is machine-local and never goes inside the user's project.
+
+Nothing resolved in the plan → write nothing. An absent file is a stage that has not run yet; an empty one would read as "nothing to say" and suppress the question forever.
+
+Never write a credential value here — pointers only, per that stage's Secrets rule.

package/plugin/skills/muggle-test-prepare/steps/reuse-plan.md

@@ -6,12 +6,13 @@ A previously saved **prepare plan** is the durable recipe for this stack. Distin
 
 In order; first hit wins.
 
-1. **Project plan.** If `git rev-parse --show-toplevel` succeeds (call the result `$REPO`) and `$REPO/.muggle-ai/prepare-plan.json` exists → load it.
-2. **Global plan.** Else if `~/.muggle-ai/prepare-plans.json` exists, read the entry keyed by `$(dirname "$PWD")` (absolute path). If present → load that entry's value.
-3. **No plan found** → exit this step; the workflow continues at [rebase-check](./rebase-check.md).
+1. **Saved plan.** If `~/.muggle-ai/prepare-plans.json` exists, read the entry keyed on this stack — the absolute path of the working directory's parent. If present → load that entry's value. The plan is machine-local and is never read from, or written to, the user's project.
+2. **No plan found** → exit this step; the workflow continues at [rebase-check](./rebase-check.md).
 
 A loaded plan is a JSON object with `version`, `updated`, `testing_scope`, `excluded_services`, `services`. Reject and treat as "no plan" if `version != 1` or `services` is empty.
 
+Load the prose companion per [e2e-instructions](./e2e-instructions.md) — `~/.muggle-ai/e2e-instructions/<key>.md`, keyed on the same stack identity as the global plan entry. It is independent of the plan: a missing companion is not a missing plan, and vice versa.
+
 ## Gate `reusePreparePlan`
 
 Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/preference-gates/README.md). Read the current value from the `Muggle Test Preferences` session-context line; absent → `ask`.
@@ -37,7 +38,7 @@ Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/p
    - The indicator file that produced `command` still exists in `dir` (e.g. `package.json` for an `npm`/`node` command; see the indicator table in [start-commands](./start-commands.md)) → keep. Else re-derive **just that one entry** by running the indicator-detection from [start-commands](./start-commands.md) against `dir`, and replace its `command`. Log `"Re-derived <name>: <old> → <new>"`.
 2. **All entries dropped** → discard the plan; continue at [rebase-check](./rebase-check.md). Otherwise proceed with surviving + re-derived entries.
 3. **Hydrate** `/tmp/muggle-test-prepare.json` with the surviving entries (no PIDs yet, `testing_scope` from the plan, `excluded_services` from the plan).
-4. **Short-circuit** to [check-running](./check-running.md). The skipped stages are [scope](./scope.md), [viability-check](./viability-check.md), [identify-services](./identify-services.md), [start-commands](./start-commands.md) — the reused plan supplies their answers. The remaining stages run normally: [env-file](./env-file.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md) (only for entries not already listening), [smoke-test](./smoke-test.md), [readiness-report](./readiness-report.md).
+4. **Short-circuit** to [check-running](./check-running.md). The skipped stages are [scope](./scope.md), [viability-check](./viability-check.md), [identify-services](./identify-services.md), [start-commands](./start-commands.md), [e2e-instructions](./e2e-instructions.md) — the reused plan and its companion supply their answers. Carry the loaded instructions forward unchanged; the user is not re-asked. When the companion is absent, run [e2e-instructions](./e2e-instructions.md) once to capture it, then continue the short-circuit. The remaining stages run normally: [env-file](./env-file.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md) (only for entries not already listening), [smoke-test](./smoke-test.md), [readiness-report](./readiness-report.md).
 
 ## Rediscover path