@muggleai/works 4.10.0 → 4.11.0

package/plugin/skills/_shared/pr-followup-helpers.md

@@ -0,0 +1,150 @@
+# PR follow-up helpers
+
+Generic operational guidance for running a PR-comment follow-up loop on GitHub: reviewer allow-list resolution, reply routing across the different comment endpoints, and a classification rule for reviewer comments with worked examples and a borderline test. Caller-agnostic — any loop that picks one comment per tick and decides what to do with it can drive off this doc.
+
+The classification produces an **action shape** (in-place change, deep-cycle through the caller's implementation pipeline, reply only, escalate, etc.) — the caller maps each shape to its specific routing (which stage to dispatch, which terminal-message template to use, which reply endpoint to hit).
+
+## Resolving the reviewer allow-list
+
+Stage 8 only acts on comments authored by users in the **allow-list** = (requested reviewers ∪ CODEOWNERS) − bots − PR author. Re-resolve every tick (decision 9 in the design doc).
+
+### Step 1: requested reviewers
+
+```bash
+gh pr view <number> --repo <owner>/<repo> --json reviewRequests,author
+```
+
+`reviewRequests` is an array of `{ login? , slug? }`. User reviewers have `login`; team reviewers have `slug` (and `name`). Expand teams to member logins:
+
+```bash
+gh api orgs/<org>/teams/<slug>/members --jq '.[].login'
+```
+
+Record `prAuthor = author.login` for the exclusion step.
+
+### Step 2: CODEOWNERS
+
+Look for the file in this order — first hit wins:
+
+1. `.github/CODEOWNERS`
+2. `CODEOWNERS`
+3. `docs/CODEOWNERS`
+
+Read from the PR's **head branch** (not master), because a PR that adds CODEOWNERS should be allowed to take effect once merged but is informational while open. In practice this means:
+
+```bash
+gh api repos/<owner>/<repo>/contents/.github/CODEOWNERS?ref=<head_sha> --jq '.content' | base64 -d
+```
+
+Parse line-by-line:
+
+- Skip blank lines and lines starting with `#`.
+- Each line is `<pattern> <owner1> <owner2> ...`.
+- Owners are either `@user` or `@org/team`. Strip the leading `@`.
+- For our purposes we don't need to match `<pattern>` against changed files — CODEOWNERS membership for the *repo* is enough. Collect the union of all owners across all lines.
+
+Expand `@org/team` to member logins via the orgs/teams/members endpoint (same as Step 1).
+
+If no CODEOWNERS file exists in any of the three locations, the CODEOWNERS contribution is empty. Don't fail.
+
+### Step 3: filter
+
+Allow-list = (requested reviewers ∪ CODEOWNERS) − `{prAuthor}` − bot logins.
+
+Bot logins are any login matching:
+
+- Ends with `[bot]` (e.g. `dependabot[bot]`)
+- Exact match in the standard list: `dependabot`, `github-actions`, `renovate`, `mergify`
+
+A comment author not in the allow-list is silently ignored — do not reply, do not address.
+
+## Reply routing
+
+GitHub's PR APIs are not uniform across comment types. Route by parent type.
+
+### Line-level review comment
+
+A comment attached to a specific file:line that belongs to a review thread. This is the **most common** path.
+
+```bash
+gh api \
+  --method POST \
+  -H "Accept: application/vnd.github+json" \
+  /repos/<owner>/<repo>/pulls/<number>/comments/<comment_id>/replies \
+  -f body="Done in $(git rev-parse --short HEAD) — renamed \`fooBar\` to \`foo_bar\`."
+```
+
+The reply lands in the same review thread. The reply itself becomes a new line-level comment with `in_reply_to_id = <comment_id>`.
+
+### Review body (CHANGES_REQUESTED with no inline comments)
+
+A reviewer left a summary review with `state: CHANGES_REQUESTED` and a body, but **no** inline comments. GitHub has no "reply to review body" endpoint — post a top-level PR comment that references the review:
+
+```bash
+gh pr comment <number> --repo <owner>/<repo> --body "Re: review #<review_id> — done in $(git rev-parse --short HEAD)."
+```
+
+### Failing CI check
+
+No reply. The fix commit IS the response. Include the failing check name in the commit subject so the connection is obvious in `git log`:
+
+```
+fix(ci): typecheck — narrow type of foo
+fix(ci): lint — remove unused import
+```
+
+### Never
+
+- Never post a top-level comment in reply to a line-level comment. It loses thread context and pollutes the PR conversation tab.
+- Never `gh pr review --comment` for replies — that endpoint is for *new* reviews, not replies.
+- Never reply twice to the same comment. The cursor in `last_seen.json` is the only re-entry guard; advance it after every reply.
+
+## Classify
+
+Classify the **review as a unit**, not individual comments.
+
+| Class | Signal | Action |
+| :---- | :----- | :----- |
+| **actionable** | Review names at least one concrete change or asks an answerable question. Soft phrasing counts when there's a concrete referent. | Treat as amended requirements; run the caller's implementation cycle; reply with one summary referencing the new SHA. |
+| **ambiguous** | No actionable signal — pure vibes, contradictory, or depends on knowledge the loop can't access. | Escalate once with two interpretations; pause the PR. |
+
+Default to **actionable**. CI catches wrong attempts; reviewers correct on the next round. Escalation is a round-trip with an absent user — reserve it.
+
+Reply summary shape:
+
+- **actionable**: `Addressed review <review_id> in <sha> — cycle ran clean (or: with <N> failures, see walkthrough).`
+- **ambiguous**: no bot reply.
+
+### Worked examples — Actionable reviews
+
+| Review (summarized) | Why actionable |
+| :------------------ | :------------- |
+| 3 comments: "rename `fooBar` to `foo_bar`", "use `const` here", "fix this typo" | Three concrete edits |
+| 1 comment: "could the procedure be simpler?" | Soft-phrased but the intent is clear — simplify; pick the best interpretation, run the cycle, reply with what was changed |
+| Review body: "Mostly looks good. Two things: extract the validation into a helper, and add a null check before the lookup." Plus 0 line comments. | Two concrete directives in the body |
+| 4 comments: "why this approach?", "is this called from X?", "does this need to handle empty array?", "what's the perf here?" | All questions but each is answerable; cycle dispatches an "answer + maybe-fix" pass and the reply summary captures each answer |
+| 1 comment: "rewrite this module — the architecture doesn't match the spec" | Substantive rebuild, but the direction is clear: redo the module per the spec |
+| 1 comment: "I'd lean toward the bar.ts pattern" | Concrete referent (bar.ts) — apply that pattern |
+
+The single review goes through one full cycle regardless of comment count.
+
+### Worked examples — Ambiguous reviews
+
+| Review (summarized) | Why ambiguous |
+| :------------------ | :------------ |
+| 1 comment: "👀" / "hmm" / ":thinking:" | No signal at all |
+| 1 comment: "this is wrong" with no target or direction | Asserts a problem but doesn't propose a fix |
+| 2 comments: "use X" + "but actually don't use X" | Self-contradicting — can't reconcile without the reviewer |
+| 1 comment: "we discussed this offline — please address" | References context the loop doesn't have |
+| 1 comment: "won't this break the prod migration we did last week?" | Implicit change request gated on knowledge the loop can't access |
+| Mixed: 2 concrete directives + 1 comment "but also, rethink the whole approach" | The "rethink the whole approach" subverts the other two; escalate to confirm scope |
+
+Escalate per the caller's escalation procedure (write the review id to the cursor's escalated set, emit one terminal message with both interpretations, pause the PR until the user resolves).
+
+### Borderline rule
+
+If you can paraphrase the review's intent as **"do X"** with X being a concrete change (one or several) — it's actionable. Pick the best interpretation and dispatch the cycle.
+
+If you can paraphrase it only as **"the reviewer is dissatisfied but I can't tell with what"** — it's ambiguous.
+
+When the review mixes both ("3 concrete directives + 1 dissatisfaction"), the safer move is usually to action the concrete directives and ask about the dissatisfaction in the reply summary. Pure ambiguity means *nothing* in the review is actionable.

package/plugin/skills/_shared/rebase-before-e2e.md

@@ -0,0 +1,15 @@
+# Rebase Onto the Default Branch Before Dev Server / E2E
+
+Gated by [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md). Follow the standard procedure in [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
+
+**Fire only when `behind > 0`:**
+
+```bash
+git fetch origin
+default=$(git symbolic-ref refs/remotes/origin/HEAD --short | sed 's|origin/||')
+behind=$(git rev-list --count "HEAD..origin/${default}")
+```
+
+Pass `{behind}` and `{default}` to the picker prompts. On `always`, run `git rebase origin/${default}`; stop and report on conflicts — never auto-resolve.
+
+Stale branches produce false failures and false greens — that's why this gate exists.

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

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

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

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

package/plugin/skills/do/build.md

@@ -0,0 +1,51 @@
+# Build Agent (Stage 3)
+
+Implement the code change for this dev cycle. Read the frozen requirements from stage 2, produce the edits in each affected repo's worktree, and commit.
+
+## Turn preamble
+
+```
+**Stage 3 — Build** — implementing the change per the frozen requirements.
+```
+
+## Inputs
+
+- `requirements.md` from stage 2: goal, acceptance criteria, affected repos.
+- `state.md` from pre-flight: worktree path per repo, target branch, anything else the build needs to know about the environment.
+
+## Your job
+
+For each affected repo:
+
+1. **Re-read `requirements.md`.** Treat goal + AC as frozen. If something is unclear at this stage, that's a pre-flight bug — escalate, do not improvise.
+2. **Apply the change** in the repo's worktree. Edit existing files first; create new files only when the requirements demand it. Match the surrounding code's style, naming, and file layout.
+3. **Don't add what wasn't asked for.** No speculative abstractions, no extra logging, no "while I'm here" refactors. Three similar lines is better than a premature abstraction.
+4. **Commit** with a conventional-commit subject:
+   - `feat(<scope>): <short>` for new behavior
+   - `fix(<scope>): <short>` for bug fixes
+   - `refactor(<scope>): <short>` for reshape
+   - `docs(...)`, `chore(...)`, `test(...)` as appropriate
+
+   The body explains *why* when the why is non-obvious. The diff already says *what*.
+
+## Output
+
+Per repo:
+
+**Repo:** name
+- Files edited / created: list
+- Commit subject: `<conventional commit>`
+- Notable choices: anything that needed a judgment call (briefly)
+
+**Overall:** READY for impact analysis | BLOCKED — reason
+
+If a requirement is fundamentally unimplementable as written, halt and escalate with the specific blocker — do not ship a half-finished implementation.
+
+## Re-entry from stage 8
+
+Stage 8 (PR follow-up) may dispatch back to this stage when a reviewer comment requires real implementation work rather than an in-place doc edit. When re-entered:
+
+- The dispatch from stage 8 carries the comment(s) that triggered the re-build as additional context; treat them as amendments to the goal/AC for this iteration.
+- Continue on the existing branch — do not re-create the worktree.
+- Cycle forward through impact analysis → unit tests → E2E → open PR (which is a no-op since the PR already exists; just push).
+- Stage 8 resumes polling after the push lands.

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

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

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

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