@muggleai/works 4.10.0 → 4.11.0

package/dist/plugin/skills/muggle-feedback/ops/submit.md

@@ -0,0 +1,130 @@
+# Submit feedback
+
+Resolve the action script being commented on, render it for review, collect feedback against one or more steps and/or the whole script, then submit each piece as its own server-side row.
+
+## 1. Resolve the action script (the "anchor")
+
+Pick the first applicable path. Stop at the first that yields an `actionScriptId`.
+
+### 1a. Dashboard URL in user's prompt
+
+A Muggle dashboard URL looks like `https://app.muggle-ai.com/muggleTestV0/dashboard/projects/<projectId>/...`. Scan the user's recent message for any `https://app.muggle-ai.com/...` URL.
+
+- Extract any UUID-shaped path segments. If `/projects/<uuid>` is present, capture as `projectId`. If `/test-scripts/<uuid>` is present, capture as `testScriptId`.
+- If a `testScriptId` was captured: call `muggle-remote-test-script-get` to get the script and read `actionScriptId` off it. Done — proceed to step 2.
+- If only a `projectId` was captured: use it as the project for path 1c and continue to picker.
+- If parsing yields nothing actionable: fall through to 1b.
+
+### 1b. Recent local run (chained or just-finished)
+
+If this skill was invoked by another skill (`muggle-test`, `muggle-test-feature-local`) the caller MUST pass the just-finished `runId` as context. If you have a `runId`:
+
+1. `muggle-local-run-result-get` with the `runId`.
+2. The result includes the test case context. If the run was already published (`muggle-local-publish-test-script` was called), the resulting `testScriptId` gives you the cloud `actionScriptId` via `muggle-remote-test-script-get`.
+3. **If the run was NOT published**, upload it first via `muggle-remote-local-run-upload` (passing the `runId`'s test case context and `actionScript` payload). Use the returned cloud `actionScriptId`.
+
+If no `runId` was passed but the user is plausibly continuing from a recent test:
+
+1. `muggle-local-list-sessions` and pick sessions completed in the last 10 minutes for the current project.
+2. If exactly one fresh session exists, offer it as the default via `AskUserQuestion` ("Feedback on the run from <X> minutes ago?" with **Yes / Pick a different run**).
+3. If multiple, present the top 3 via `AskUserQuestion` (most recent first).
+4. Once picked, follow the publish-or-upload path above.
+
+If neither chained nor recent fits, fall through to 1c.
+
+### 1c. Picker (project → test case → run)
+
+1. **Project.** Read `muggle-local-last-project-get`. If set, use it. Else `muggle-remote-project-list` with `AskUserQuestion` (top 5 by recency, plus "Show full list"). Persist the pick with `muggle-local-last-project-set`.
+2. **Test case.** `muggle-remote-test-case-list` with `projectId`, then `AskUserQuestion`. Top 5 by recency plus "Show full list". Rank by relevance if the user mentioned anything specific.
+3. **Run / script.** `muggle-remote-test-script-list` with `testCaseId`. Show via `AskUserQuestion` with: name + status + updatedAt. Top 5 by recency.
+4. `muggle-remote-test-script-get` on the picked one → note `actionScriptId`.
+
+## 2. Render the script for review
+
+Always render before asking for feedback — the user must see the steps to reference them by index.
+
+`muggle-remote-action-script-get` with the resolved `actionScriptId`.
+
+Print:
+
+- **Header** — project name, test case title, script name, status, run url (if available). For remote, include the dashboard link.
+- **Steps** — numbered list, **1-based**, in order:
+  - `Step <n>: <action label> on <element text or id> — <briefExplanation>`
+  - If `screenshotPath` is present (local) or `screenshotUrl` (remote), append `[screenshot: <path>]` so the user can open it manually.
+- **Summary** — print `summary` from the action script if present, else "No summary recorded".
+
+## 3. Collect feedback (batch)
+
+### 3a. Pick the scope (entity type)
+
+Use `AskUserQuestion` to scope which targets:
+
+> "Where is the problem?"
+> - One specific step
+> - Multiple steps
+> - The whole script's outcome / summary
+> - Multiple steps **and** the whole outcome
+
+### 3b. Pick the step(s) — clickable picker
+
+When 3a includes any step-level scope, present the rendered steps as a **clickable `AskUserQuestion` picker** — never as a typed number.
+
+- **Option format** — Label: `Step <n>: <action label> on <element text or id>` (≤80 chars). Description: the step's `briefExplanation` (≤120 chars).
+- **Multi-select** — `multiSelect: true` for "Multiple steps" or "Multiple steps and the whole outcome"; `multiSelect: false` for "One specific step".
+- **Long scripts (>10 steps)** — rank by keyword overlap with the user's prompt (label or briefExplanation); fall back to the first 10 if no match. Append **"Show all steps"** as a final option that re-asks with the full list — never silently truncate.
+
+For each selected step, prompt in plain text:
+
+> "What should step `<n>` have done instead?"
+
+For the whole-script scope, prompt:
+
+> "What's wrong with the overall outcome?"
+
+Validate each paragraph is non-empty (re-prompt if blank). Build an in-memory list of feedback pieces:
+
+```
+[
+  { kind: "step", stepNumber: 3, text: "..." },
+  { kind: "step", stepNumber: 7, text: "..." },
+  { kind: "actionScript",            text: "..." },
+]
+```
+
+Before submitting, re-confirm the full set with the user via `AskUserQuestion`:
+
+> "Submit these <N> feedback entries?" — **Submit / Edit / Cancel**.
+
+## 4. Submit
+
+For each piece, call `muggle-remote-user-feedback-create` once. Map fields:
+
+| Piece kind | `target.targetType` | `target.targetId` |
+|---|---|---|
+| Step `n` (1-based) | `"step"` | `` `${actionScriptId}:${n - 1}` `` (convert to 0-based) |
+| Whole script | `"actionScript"` | `actionScriptId` |
+
+Always pass `projectId` and `feedbackText`. Capture each response — note `feedback.id` and `feedbackAnalysisWorkflowRuntimeId` (may be undefined).
+
+If a single create call fails, log the error, continue with the rest, and report the failure at the end. Do not abort the batch.
+
+## 5. Report
+
+Print one line per submitted feedback in this shape:
+
+```
+✓ feedback <id> — <target description> [analysis runtime: <id>]
+```
+
+End with a one-line note:
+
+> "Regeneration runs in the background. Re-run this test case later to use the updated script."
+
+If any pieces failed, list them under a `Failed:` header with the error.
+
+## Non-negotiables
+
+- Always render the script (step 2) before collecting feedback.
+- One create call per feedback piece — never concatenate paragraphs across targets.
+- Convert step numbers from 1-based (UI) to 0-based (wire) at submit time.
+- If the user came from a non-uploaded local run, do the upload silently before submit; do not ask for permission for the upload itself.

package/dist/plugin/skills/muggle-pr-followup/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: muggle-pr-followup
+description: Generic per-PR follow-up loop. One polling tick per dispatch. Watches one PR for new submitted reviews; when an actionable review lands, invokes the caller's implementation cycle (build/test/walkthrough/push handler the caller declares), then resumes polling. Use as `/loop 1m /muggle:muggle-pr-followup <session-slug> <pr-number>`. Caller-agnostic — `muggle-do` is the first caller but not the last.
+disable-model-invocation: true
+---
+
+# Muggle PR Follow-up
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-followup"`.
+
+A generic loop that babysits one open PR until it's merged or closed. Polls for submitted reviews; on an actionable review, dispatches the caller's implementation cycle to re-build, re-test, refresh the walkthrough, and push.
+
+**Per-PR isolation.** One dispatch per PR, not per session. Multi-PR work runs N independent loops.
+
+## Input
+
+`$ARGUMENTS = <session-slug> <pr-number>`. The session-slug is the directory basename under `.muggle-<caller>/sessions/` (e.g. `.muggle-do/sessions/`) that this loop reads its state from. The pr-number identifies which PR in that session's manifest this loop watches.
+
+- Empty / `help` / `?` → list active `(slug, pr-number)` pairs across known callers, exit.
+- One argument → ambiguous; list PRs under that slug, exit.
+- Two arguments → resolve and run one tick.
+
+## Contract
+
+The per-tick contract — termination check, allow-list resolution, review polling, classify, cycle dispatch, escalation, telemetry — lives in [`contract.md`](contract.md). Read it before driving a tick.
+
+## Caller-supplied implementation cycle
+
+The skill itself is caller-agnostic. When an actionable review lands, it invokes the **implementation cycle** declared by the caller in the session's `cycle.json`:
+
+```json
+{
+  "cycleName": "muggle-do dev cycle",
+  "steps": [
+    { "stage": 3, "file": "../do/build.md" },
+    { "stage": 4, "file": "../do/impact-analysis.md" },
+    { "stage": 5, "file": "../do/unit-tests.md" },
+    { "stage": 6, "file": "../do/e2e-acceptance.md" },
+    { "name": "post-walkthrough", "skill": "muggle-pr-visual-walkthrough", "mode": "A" }
+  ],
+  "pushHandler": "git push origin <branch>"
+}
+```
+
+The cycle's job: read the amended `requirements.md`, run each declared step, push to the existing branch. The cycle returns one of `pushed | escalated | failed`. The skill doesn't care what's inside the steps — it just iterates them, captures the outcome, and writes a reply summary referencing the new SHA.
+
+Callers without a `cycle.json` are rejected with `no cycle declared — caller must seed cycle.json at dispatch time`.
+
+## Subagent dispatch (optional)
+
+A caller may declare `"useSubagent": true` in `cycle.json`. When set, the implementation cycle runs as a separate Claude subagent rather than inline in the loop's tick — gives stronger isolation per PR but adds overhead per cycle. Default is inline (which is itself isolated per-tick via `/loop`).
+
+## Design adjustment escalation
+
+When the implementation cycle reports back that the review requires not just code change but a **design adjustment** beyond what the current requirements support (e.g. the build stage discovers the requested change conflicts with a load-bearing assumption), the cycle returns `failed: design-adjustment`. The loop treats this like an ambiguous escalation but with a different terminal message that points at the design conflict and asks the user to decide.
+
+## Why a separate skill (and not e.g. inside the caller's own skill folder)
+
+`/loop` dispatches via slash command; slash commands resolve to top-level skills under `plugin/skills/`. A per-tick loop driven by `/loop` therefore has to live as a top-level skill. Putting the loop's content directly inside a caller-specific folder would make `/loop`-dispatch impossible (or fragile via shell-only entry points). Keeping the loop generic and caller-agnostic is what lets `/loop` dispatch into it cleanly.

package/dist/plugin/skills/muggle-pr-followup/contract.md

@@ -0,0 +1,191 @@
+# PR follow-up per-tick contract
+
+Caller-agnostic per-tick contract for the [muggle-pr-followup](SKILL.md) skill. One tick = one polling iteration scoped to one PR.
+
+## Turn preamble
+
+```
+**PR follow-up** — polling <repo>#<pr-number>, tick #<K>.
+```
+
+Resolve `<K>` from `idle_tick_count + cycles_completed` in this PR's state slot.
+
+## When this contract may break the caller's "no questions" rule
+
+Most callers' forward pipelines never ask the user mid-cycle. This loop, however, may emit a single escalation message when a submitted review is ambiguous (see [classify](#step-6-classify-the-review) below). By the time the loop is polling, the user has walked away from the forward pipeline; forcing a guess on an ambiguous review is worse than pausing.
+
+Escalation is the **only** user-facing path. Otherwise the cycle runs silently end to end.
+
+## Inputs
+
+Read these from `.muggle-<caller>/sessions/<slug>/` (the caller's session dir):
+
+- `state.md` — session metadata (for context when classifying reviews).
+- `prs.json` — list of `{repo, number, url, head_sha, state, escalated?, cycling?}`. This loop touches only the entry whose `number` matches the dispatched PR number.
+- `last_seen.json` — keyed by `"<owner>/<repo>#<n>"`. For this PR: `{reviewId, last_pushed_sha, idle_tick_count, cycles_completed, escalated_review_ids[]}`.
+- `cycle.json` — caller's declared implementation cycle (see [SKILL.md](SKILL.md#caller-supplied-implementation-cycle)).
+
+If any of these don't exist or the PR isn't in `prs.json`, the tick is a no-op — log an error to `followup.log` and exit.
+
+## Per-tick contract
+
+### Step 1: Refresh this PR's state
+
+```bash
+gh pr view <number> --repo <repo> --json state,mergedAt,closedAt,headRefOid
+```
+
+If `state` is `MERGED` or `CLOSED`, mark this entry terminal in `prs.json`. Update `head_sha` if it changed.
+
+### Step 2: Termination check
+
+If this PR is terminal: write a per-PR section into `result.md` (URL, final state, `cycles_completed`, count escalated, final SHA), emit final telemetry, **do not schedule another tick**. Other PRs in the session have their own loops; they terminate independently.
+
+### Step 3: Resolve the reviewer allow-list (every tick)
+
+```bash
+gh pr view <number> --repo <repo> --json reviewRequests,author
+```
+
+Add requested reviewers. Add CODEOWNERS by parsing `.github/CODEOWNERS` (or `CODEOWNERS` / `docs/CODEOWNERS`) from the PR's head branch. Remove the PR author and any bot accounts (logins ending in `[bot]`, plus the standard list: `dependabot`, `github-actions`, `renovate`, `mergify`).
+
+### Step 4: Pull new submitted reviews
+
+```bash
+gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate
+```
+
+Filter to reviews where:
+
+- `submitted_at` is non-null (skip drafts — `PENDING` reviews are still being composed).
+- `id > last_seen.reviewId`.
+- `user.login` is in the allow-list.
+- `id` is not in `escalated_review_ids`.
+- `state` is `CHANGES_REQUESTED` or `COMMENTED`, OR `APPROVED` with at least one line comment or a non-empty body.
+
+### Step 5: Pick the oldest new review
+
+If no new review past the cursor: increment `idle_tick_count`, append a heartbeat line to `followup.log`, exit. Next tick fires in 1 min via `/loop`.
+
+If one or more: take the oldest by `submitted_at`. Fetch its associated line comments (`gh api repos/<owner>/<repo>/pulls/<n>/comments` filtered by `pull_request_review_id`). Reset `idle_tick_count` to 0.
+
+**At most one review per tick.** If two reviews land between ticks, the second waits.
+
+### Step 6: Classify the review
+
+Apply the classify rule in [`../_shared/pr-followup-helpers.md`](../_shared/pr-followup-helpers.md). The rule applies to the **review as a unit**. Two outcomes:
+
+- **Actionable** → continue to Step 7.
+- **Ambiguous** → continue to Step 8.
+
+### Step 7: Dispatch the implementation cycle
+
+When the review is actionable:
+
+1. **Pause polling** for this PR (set `cycling: true` on this PR's entry in `prs.json`).
+2. **Amend `requirements.md`** in the session dir with a new `## Amendment — review <review_id> by <login> (<timestamp>)` section pasting the review body and each comment (with `<file>:<line>` context).
+3. **Invoke the implementation cycle** declared in the caller's `cycle.json`. Iterate the `steps[]` in order. Each step is either a markdown file to follow, a skill to invoke, or a shell command (per the `cycle.json` schema in SKILL.md). When a step fails, the cycle returns `failed: <step-name>`; the loop escalates per Step 8 with the failure as the reason.
+4. **Push** via `cycle.json`'s `pushHandler`. Set `last_seen.last_pushed_sha` to the new HEAD.
+5. **Reply** with one summary via `gh pr comment <n>`:
+   ```
+   Addressed review <review_id> in <sha> — cycle ran clean (or: with <N> failures, see walkthrough).
+   ```
+6. **Resume polling**: clear `cycling: true`, increment `cycles_completed`, advance `last_seen.reviewId` past this review.
+7. Emit per-cycle telemetry.
+
+If the cycle returns `failed: design-adjustment` (the cycle discovered the review can't be implemented without rethinking the design itself, not just the code), escalate per Step 8 with a `design-adjustment` reason — the terminal message asks the user to confirm the design intent before retrying.
+
+### Step 8: Escalate
+
+When the review is ambiguous, or the cycle failed:
+
+1. Add the review id to `last_seen.escalated_review_ids`.
+2. Append a `followup.log` entry describing the review and the reason.
+3. Pause this PR's loop by writing `escalated: true` against this PR's entry in `prs.json`.
+4. End the turn with a **single terminal message** to the user:
+
+```
+**PR follow-up escalation — <repo>#<number> — review <review_id>**
+
+<reviewer-login> submitted a review I can't act on coherently:
+
+> <quoted review body, or "(no body)" if empty>
+
+Comments:
+- <file>:<line> — <quoted comment body>
+
+[For ambiguous]
+Best two interpretations:
+1. <one-line interpretation A>
+2. <one-line interpretation B>
+
+[For cycle failure]
+The implementation cycle failed at <step-name>: <reason>.
+
+Reply on the review yourself, leave a follow-up comment, or tell me which way to go.
+```
+
+The user clears the escalation by replying on GitHub (next tick sees a new submitted review past the cursor) or by giving a directive in this terminal session.
+
+### Step 9: Emit tick-summary telemetry and exit
+
+Emit one tick event per `muggle-local-telemetry-skill-emit`. Exit the turn.
+
+## Reply routing
+
+- **Summary reply on a review**: `gh pr comment <number> --body "..."` referencing the review id and the new SHA. There's no "reply to a review" endpoint.
+- **Reply to a specific line comment** (optional): `POST /repos/{owner}/{repo}/pulls/{n}/comments/{comment_id}/replies`.
+- **Never post the same summary twice** — `last_seen.reviewId` is the only re-entry guard.
+
+## Telemetry
+
+**Per-cycle** (one event per actionable review handled):
+
+```json
+{
+  "skill": "muggle-pr-followup",
+  "event": "cycle",
+  "caller": "<caller>",
+  "session_slug": "<slug>",
+  "repo": "<repo>",
+  "pr_number": <n>,
+  "review_id": <id>,
+  "outcome": "pushed|escalated|failed:<step>",
+  "comment_count": <count>,
+  "head_sha_before": "<sha>",
+  "head_sha_after": "<sha-or-null>"
+}
+```
+
+**Per-tick summary** (always one, even idle):
+
+```json
+{
+  "skill": "muggle-pr-followup",
+  "event": "tick",
+  "session_slug": "<slug>",
+  "repo": "<repo>",
+  "pr_number": <n>,
+  "reviews_seen": <count>,
+  "review_picked": true|false,
+  "cycle_dispatched": true|false,
+  "tick_duration_ms": <ms>
+}
+```
+
+## Output
+
+This stage produces no console output beyond:
+- The turn preamble (always).
+- An escalation terminal message (only when escalating).
+- The final `result.md` summary section for this PR (only on the terminating tick — written to disk, not printed).
+
+## Self-check before ending the turn
+
+- [ ] `last_seen.json` advanced for any review handled.
+- [ ] `prs.json` reflects current state (terminal marked; `escalated`/`cycling` flags consistent).
+- [ ] `followup.log` has at minimum a heartbeat or per-review line for this tick.
+- [ ] Telemetry events emitted (per-cycle when applicable + per-tick).
+- [ ] If pushed, `last_pushed_sha` is set and `cycles_completed` incremented.
+- [ ] If escalated, `escalated_review_ids` contains the review id.
+- [ ] If terminal, the loop is NOT continued.

package/dist/plugin/skills/muggle-pr-visual-walkthrough/SKILL.md

@@ -1,19 +1,22 @@
 ---
 name: muggle-pr-visual-walkthrough
-description: Renders and posts a visual walkthrough of Muggle AI E2E acceptance test results to a PR — per-test-case dashboard links, step-by-step screenshots, and pass/fail summary — using the `muggle build-pr-section` CLI for deterministic formatting with automatic fit-vs-overflow. Use at the end of any Muggle test run (local or remote) to give PR reviewers clickable visual evidence that user flows work. Triggers on 'post results to PR', 'attach walkthrough to PR', 'share E2E screenshots on the PR', 'add visual walkthrough to PR'.
+description: Renders and posts a visual walkthrough of Muggle AI E2E acceptance test results to a PR — per-test-case dashboard links, step-by-step screenshots, and pass/fail summary — using the `muggle build-pr-section` CLI for deterministic formatting with automatic fit-vs-overflow. Use at the end of any Muggle Test test run (local or remote) to give PR reviewers clickable visual evidence that user flows work. Triggers on 'post results to PR', 'attach walkthrough to PR', 'share E2E screenshots on the PR', 'add visual walkthrough to PR'.
 ---
 
-# Muggle PR Visual Walkthrough
+# Muggle Test PR Visual Walkthrough
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-visual-walkthrough"`.
 
 Renders a visual walkthrough of Muggle AI E2E acceptance test results and posts it to a PR. Each test case is linked to its detail page on the Muggle AI dashboard, so PR reviewers can click through to see step-by-step screenshots and action scripts — not just a pass/fail flag.
 
-This is the **canonical PR-walkthrough workflow** shared across every Muggle entry point:
+This is the **canonical PR-walkthrough workflow** shared across every Muggle Test entry point:
 
 | Caller | Mode | When to invoke |
 | :--- | :--- | :--- |
-| `muggle-test` | **Mode A** (post to existing PR) | After publishing results, user opts in via `AskQuestion` |
-| `muggle-test-feature-local` | **Mode A** (post to existing PR) | After publishing the run, user opts in via `AskQuestion` |
+| `muggle-test` | **Mode A** (post to existing PR) | After publishing results, user opts in via `AskUserQuestion` |
+| `muggle-test-feature-local` | **Mode A** (post to existing PR) | After publishing the run, user opts in via `AskUserQuestion` |
 | `muggle-do` / `open-prs.md` | **Mode B** (render-only for embedding) | During PR creation — caller embeds `body` in `gh pr create` and posts `comment` as follow-up |
+| `muggle-test` Mode C / `acceptance-tester` agent | **Mode C** (embed in verdict comment) | Inside a open-PR sweep orchestrator — caller folds the rendered body into a single per-PR verdict comment instead of posting separately |
 
 Rendering is always done by `muggle build-pr-section`, a battle-tested CLI that handles deterministic markdown layout, per-step screenshots, and automatic fit-vs-overflow (oversized content spills into a follow-up comment). Never hand-write the walkthrough markdown.
 
@@ -64,42 +67,48 @@ Every caller must build an `E2eReport` JSON object and have it in conversation c
       "failureStepIndex": 2,
       "error": "Element not found: Click checkout button",
       "artifactsDir": "/Users/.../~/.muggle-ai/sessions/<runId>"
+    },
+    {
+      "name": "Clear search input restores full list",
+      "description": "Verify clearing the search input restores all options.",
+      "useCaseName": "Filter Dropdowns",
+      "testCaseId": "<UUID>",
+      "runId": "<UUID>",
+      "viewUrl": "https://www.muggle-ai.com/...",
+      "status": "inconclusive",
+      "steps": [],
+      "reason": "No replayable script exists yet — needs first generation run."
     }
   ]
 }
 ```
 
-Required fields per test: `name`, `testCaseId`, `runId`, `viewUrl`, `status`, `steps[]` with `{stepIndex, action, screenshotUrl}`. Failed tests additionally require `failureStepIndex` and `error`.
+Required fields per test: `name`, `testCaseId`, `runId`, `viewUrl`, `status`, `steps[]` with `{stepIndex, action, screenshotUrl}`.
 
-**Optional but recommended** per test:
-- `description` — a one-line summary of what the test case verifies. Shown in the collapsible header for each test and helps reviewers understand the test without expanding it. Pull from the test case's `title`/`description` via `muggle-remote-test-case-get`.
-- `useCaseName` — the parent use case title. When present on any test, the overview list is grouped by use case; otherwise it is rendered as a flat list. Pull from `muggle-remote-use-case-get` using the test case's parent use-case id.
-- `testScriptId` and `artifactsDir` are also optional.
-
-If any required field is missing, stop and tell the caller exactly what's missing. Never fabricate data.
+- **Failed** tests additionally require `failureStepIndex` and `error`.
+- **Inconclusive** tests additionally require `reason` (one short sentence on why the result is neither pass nor fail). `steps[]` may be empty — that's fine. Inconclusive is for runs that couldn't be classified pass/fail (no replayable script, environment precondition unmet, infra error blocked execution, agent stalled before reaching the assertion). **Never silently drop these — always emit them as `inconclusive`.** The CLI counts them in the overview and renders an `⚠️` row with the dashboard link so reviewers can click through. If you find yourself wanting to skip a test or hand-write a comment because the schema "doesn't fit," that is the schema fitting — use `inconclusive`.
 
-## Step 1: Gather the `E2eReport`
+### Verdict
 
-How to assemble the JSON depends on which caller you are:
+The renderer computes a verdict from the tests and emits a `**Verdict:** ✅ PASS | ❌ FAIL | ⚠️ INCONCLUSIVE` line at the top of the overview. The policy is strict:
 
-### From `muggle-test` / `muggle-test-feature-local` (local mode)
+- Any failed test → **FAIL** (regardless of how many passed or are inconclusive).
+- No failures but any inconclusive → **INCONCLUSIVE**.
+- All passed → **PASS**.
+- Empty report → no verdict line.
 
-After `muggle-local-publish-test-script` returns `{testScriptId, viewUrl, ...}` for each run:
+You do not compute or render the verdict yourself — the CLI does. Never write a "Verdict: PASS" line into a hand-edited summary; it will conflict with the CLI's computed verdict.
 
-1. Call `muggle-remote-test-script-get` with `testScriptId` to fetch the published script.
-2. Extract `steps[]` — for each step, build `{stepIndex: <index>, action: operation.action, screenshotUrl: operation.screenshotUrl}`.
-3. Determine `status` from the local run result (`muggle-local-run-result-get`).
-4. For failures, read `failureStepIndex`, `error`, and `artifactsDir` from the run result.
-5. Assemble the `E2eReport` with `projectId` from the test run.
-6. Populate `description` (test case title/description) and `useCaseName` (parent use case title) on each report entry — optional but strongly recommended; they drive the grouped overview and the per-test collapsible headers. Prefer values already in your conversation context from earlier steps (e.g. a test case you just created or selected, or a use case you confirmed); only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` for anything you don't already have.
-
-### From `muggle-do` (`open-prs.md`)
+**Optional but recommended** per test:
+- `description` — a one-line summary of what the test case verifies. Shown in the collapsible header for each test and helps reviewers understand the test without expanding it. Pull from the test case's `title`/`description` via `muggle-remote-test-case-get`.
+- `useCaseName` — the parent use case title. When present on any test, the overview list is grouped by use case; otherwise it is rendered as a flat list. Pull from `muggle-remote-use-case-get` using the test case's parent use-case id.
+- `testScriptId` and `artifactsDir` are also optional.
 
-The `e2e-acceptance.md` stage already produces an `E2eReport` with the exact shape above — that is the report's native output format. Pass it through unchanged.
+If any required field is missing, stop and tell the caller exactly what's missing. Never fabricate data.
 
-### Direct invocation (user asked to post existing results)
+## Step 1: Assemble the `E2eReport`
 
-The caller must have already executed tests and published them. If the `E2eReport` is not in context, stop and tell the user to run `muggle-test` or `muggle-test-feature-local` first.
+Read `plugin/skills/muggle-pr-visual-walkthrough/e2e-report-assembly.md` for the full assembly guide.
 
 ## Step 2: Render via `muggle build-pr-section`
 
@@ -126,7 +135,7 @@ gh pr view --json number,url,title 2>/dev/null
 ```
 
 - **PR exists** → continue to 3A.2
-- **No PR exists** → use `AskQuestion`:
+- **No PR exists** → use `AskUserQuestion`:
   - "Create a new PR with the visual walkthrough in the body"
   - "Skip posting"
   - If the user chooses to create a new PR, switch to Mode B and return the rendered `body`/`comment` to the caller for embedding in `gh pr create`. Do not create the PR directly from this skill unless the caller has no better way to do it.
@@ -134,20 +143,16 @@ gh pr view --json number,url,title 2>/dev/null
 
 ### 3A.2: Post the body as a PR comment
 
+Extract the `body` field with `jq -r` (not `sed`) so JSON escape sequences are properly decoded, then pipe to `--body-file -`:
+
 ```bash
-gh pr comment <pr-number> --body "$(cat <<'EOF'
-<contents of body field from CLI output>
-EOF
-)"
+jq -r '.body' /tmp/muggle-pr-section.json | gh pr comment <pr-number> --body-file -
 ```
 
 ### 3A.3: Post the overflow comment only if the CLI emitted one
 
 ```bash
-gh pr comment <pr-number> --body "$(cat <<'EOF'
-<contents of comment field from CLI output>
-EOF
-)"
+jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <pr-number> --body-file -
 ```
 
 **Skip this step entirely if `comment` is `null`** — do not post a placeholder. The CLI decides fit-vs-overflow; never post the overflow comment speculatively.
@@ -169,16 +174,35 @@ Instead of posting, **return** the CLI output to the caller's context so they ca
 3. **Post `comment` as a follow-up only if the CLI emitted one:**
 
    ```bash
-   gh pr comment <new-pr-number> --body "$(cat <<'EOF'
-   <contents of comment field>
-   EOF
-   )"
+   jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <new-pr-number> --body-file -
    ```
 
    Skip if `comment` is `null`.
 
 In Mode B, this skill does not call `gh pr comment` or `gh pr create` itself — the caller owns PR creation because it also owns branch pushing, title building (including `[E2E FAILING]` prefix on failures), and multi-repo orchestration.
 
+## Step 3 — Mode C: Embed mode for open-PR sweep orchestrators
+
+Used when invoked as a sub-step of a open-PR sweep orchestrator (see `plugin/skills/muggle-test/SKILL.md` Mode C) rather than as a top-level user invocation. The orchestrator's `acceptance-tester` subagent (see `plugin/agents/acceptance-tester.md`) composes a **single per-PR verdict comment** and folds the walkthrough into it — posting separately would create 2–3 disparate comments per test cycle and clutter the PR.
+
+### 3C.1: Detect embed mode
+
+The caller passes `mode: "embed"` as a skill argument. Default behavior (no `mode` passed, or `mode: "post"`) is Mode A — unchanged.
+
+### 3C.2: Render but do not post
+
+Run `muggle build-pr-section` exactly as in Step 2. Then, **instead of calling `gh pr comment`**:
+
+1. **Return** the CLI output (`{ body, comment }`) to the caller as this skill's result.
+2. Do **not** find a PR, do **not** post a standalone comment, do **not** prompt the user.
+3. If `comment` is non-null (overflow case), return it alongside `body` — the orchestrator decides how to handle overflow (typically: inline `body` in the verdict comment, post `comment` as a follow-up).
+
+### 3C.3: Hand off
+
+The orchestrator (`acceptance-tester`) concatenates the returned `body` into its verdict comment template alongside the verdict summary, change-list, and any other sections it owns, then posts a single `gh pr comment` itself. This skill's job ends at returning the rendered markdown.
+
+In Mode C, the same fit-vs-overflow contract from Step 2 applies — never modify the CLI's output, never fabricate fields, never post anything. The caller owns posting.
+
 ## Tool Reference
 
 | Phase | Tool |
@@ -188,14 +212,15 @@ In Mode B, this skill does not call `gh pr comment` or `gh pr create` itself —
 | Find existing PR (Mode A) | `gh pr view` |
 | Post comment(s) (Mode A) | `gh pr comment` |
 | Create new PR (Mode B, caller handles) | `gh pr create` |
-| User confirmation (Mode A no-PR branch) | `AskQuestion` |
+| User confirmation (Mode A no-PR branch) | `AskUserQuestion` |
 
 ## Guardrails
 
-- **Never hand-write the walkthrough markdown** — always call `muggle build-pr-section`. The CLI is the single source of truth for formatting.
+- **Never hand-write the walkthrough markdown** — always call `muggle build-pr-section`. The CLI is the single source of truth for formatting. If a test outcome doesn't fit `passed | failed`, that's what `inconclusive` is for — never fall back to a hand-written summary, a custom table, a "Verdict: PASS" header, a `Tested on:`/`Project:` footer, or any other freeform text. The CLI already emits per-test-case dashboard links (no project-level link), uses `https://www.muggle-ai.com/...` URLs (never the test target's `localhost` URL), and computes the verdict — anything you would manually add is wrong by construction.
 - **Never modify the CLI's output** — post `body` and (if present) `comment` verbatim. Any reformatting defeats the fit-vs-overflow budget math.
 - **Never invent report fields** — if `projectId`, a per-test `viewUrl`, or per-step `screenshotUrl` is missing, stop and report what's missing. Do not fabricate URLs or fill in placeholders.
 - **Never post the overflow comment when `comment` is `null`** — the CLI decides fit-vs-overflow.
 - **Never create a PR without confirmation in Mode A** — if no PR exists, ask the user or switch to Mode B and hand back to the caller.
 - **Don't run tests** — this skill only renders and posts existing results. If the `E2eReport` is not in context, redirect the caller to `muggle-test`, `muggle-test-feature-local`, or `muggle-do`.
-- **Mode A vs Mode B is chosen by the caller, not the user** — `muggle-test` always uses Mode A; `muggle-do` always uses Mode B. Don't ask the user which mode to use.
+- **Mode is chosen by the caller, not the user** — `muggle-test` top-level uses Mode A; `muggle-do` uses Mode B; open-PR sweep orchestrators (`muggle-test` Mode C / `acceptance-tester`) pass `mode: "embed"` for Mode C. Don't ask the user which mode to use.
+- **Never post in Mode C** — when `mode: "embed"` is passed, return the rendered body to the caller and stop. The orchestrator owns the single verdict comment.