@muggleai/works 4.10.1 → 4.11.0

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

@@ -32,7 +32,8 @@ If intent is ambiguous, use `AskUserQuestion` once with options **Submit / List
 
 ## Non-negotiables (all ops)
 
-- Use `AskUserQuestion` for every selection (project, test case, run, target type, confirm). Never ask the user to "reply with a number" in plain text.
+- Use `AskUserQuestion` for every selection (project, test case, run, target type, which step(s), confirm). Step selection must be a clickable picker built from the rendered steps (see [`ops/submit.md`](ops/submit.md) §3b) — never ask the user to type a number.
+- Always render the run's steps and summary (§2) **before** collecting feedback — users can only point at what they can see.
 - Convert step numbers between 1-based (rendered to user) and 0-based (wire format) at the boundary. Never expose 0-based indices to the user.
 - One MCP submit/delete call per feedback piece — never batch into a single call.
 - Surface the `feedbackAnalysisWorkflowRuntimeId` returned by submit so the user knows regeneration is running. Do not poll it from this skill.

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

@@ -55,6 +55,8 @@ Print:
 
 ## 3. Collect feedback (batch)
 
+### 3a. Pick the scope (entity type)
+
 Use `AskUserQuestion` to scope which targets:
 
 > "Where is the problem?"
@@ -63,10 +65,21 @@ Use `AskUserQuestion` to scope which targets:
 > - The whole script's outcome / summary
 > - Multiple steps **and** the whole outcome
 
-For each chosen target, prompt for the feedback paragraph in plain text. Keep prompts specific:
+### 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:
 
-- For a step: "What should step `<n>` have done instead?"
-- For the whole script: "What's wrong with the overall outcome?"
+> "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:
 

package/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/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/plugin/skills/muggle-test-feature-local/SKILL.md

@@ -215,6 +215,19 @@ If the user picks `muggle-feedback` from any bucket's options, invoke the `muggl
 
 Skip silently when the run passed cleanly — failure-mode events are by definition about failures.
 
+### 9b. Remind the user to guide the agent (every Electron invocation)
+
+Fires after **every** Electron run, pass or fail. A run can technically pass while still containing steps the user would correct — a misclick, wrong element, or a summary that doesn't match intent. This is the user's chance to flag it before regeneration picks up elsewhere.
+
+**Skip if 9a already routed the user into `muggle-feedback` for this run.** Otherwise ask via `AskUserQuestion`:
+
+> "Did the agent miss or do anything wrong on this run? Your feedback regenerates the affected scripts."
+
+- **Yes — give feedback** → invoke `muggle-feedback` via the `Skill` tool, passing the just-finished `runId` so the submit flow opens on this run's steps and summary.
+- **No — looks good** → continue to Step 10.
+
+Non-blocking — one click to dismiss. Do not re-ask for the same `runId` within a session.
+
 ### 10. Offer to post a visual walkthrough to the PR
 
 After reporting results:
@@ -231,6 +244,7 @@ After reporting results:
 - **Never prompt for Electron launch approval** before execution — invoking this skill is the approval. Just run.
 - If replayable scripts exist, do not default to generation without user choice.
 - No hiding failures: surface errors and artifact paths.
+- **Always offer the agent-guidance reminder after every Electron run** (Step 9b) — pass or fail — unless 9a already routed the user into `muggle-feedback`. Never silently end a run without giving the user a one-click path to flag what was wrong.
 - Replay: never hand-built or simplified `actionScript` — only from `muggle-remote-action-script-get`.
 - Use `AskUserQuestion` for every selection — project, use case, test case, script. Never ask the user to type a number.
 - Project, use case, and test case selection lists must always include "Create new ...". Include "Show full list" whenever the API returned at least one row for that step; omit "Show full list" when the list is empty (offer "Create new ..." only). For creates, use preview tools (`muggle-remote-use-case-prompt-preview`, `muggle-remote-test-case-generate-from-prompt`) before persisting.

package/dist/plugin/skills/do/pr-followup.md

@@ -1,225 +0,0 @@
-# PR follow-up agent (Stage 8/8)
-
-You are babysitting one or more open pull requests opened by stage 7. Each invocation of this stage is **one polling tick** dispatched by `/loop 5m /muggle:muggle-do-pr-followup <slug>`. The tick is short, idempotent, and addresses **at most one item per PR**.
-
-The loop ends when every PR in the session is merged or closed.
-
-## Turn preamble
-
-Start the turn with:
-
-```
-**Stage 8/8 — PR follow-up** — polling <N> PR(s), tick #<K>.
-```
-
-Resolve `<N>` from `prs.json` (non-terminal entries only) and `<K>` from the tick counter in `state.md`.
-
-## Stage-8 exception to the no-mid-cycle-questions rule
-
-Stages 2–7 never ask the user mid-cycle. **Stage 8 may escalate** when a reviewer comment is ambiguous (see [Decision rule: classify](#decision-rule-classify) below). This is deliberate — the user has already walked away by the time stage 8 starts, and forcing a guess on an ambiguous design comment is worse than pausing.
-
-Escalation is the **only** user-facing path in stage 8. Anything else — directives, questions, CI failures, retries — runs silently.
-
-## Inputs
-
-Read these from `.muggle-do/sessions/<slug>/`:
-
-- `state.md` — current tick counter, session metadata, the pre-flight answers (for context when classifying comments).
-- `prs.json` — list of `{repo, number, url, head_sha, state}`. Entries with `state: "merged"` or `state: "closed"` are skipped.
-- `last_seen.json` — per-PR cursor: `{commentId, reviewId, checkRunCompletedAt, last_pushed_sha, idle_tick_count, escalated_comment_ids[]}`.
-
-If any of these don't exist, the tick is a no-op — log an error to `followup.log` and exit.
-
-## Per-tick contract
-
-Do these steps in order. **Do not batch — at most one actionable item per PR.**
-
-### Step 1: Refresh PR states
-
-For each PR in `prs.json` not already terminal:
-
-```bash
-gh pr view <number> --repo <repo> --json state,mergedAt,closedAt,headRefOid
-```
-
-If `state` is `MERGED` or `CLOSED`, mark the entry terminal in `prs.json`. Update `head_sha` if it changed.
-
-### Step 2: Termination check
-
-If every entry in `prs.json` is now terminal:
-
-1. Write `result.md` with one section per PR (URL, final state, count of items addressed, count escalated, final commit SHA).
-2. **Do not schedule the next tick.** End the turn with no `ScheduleWakeup`-equivalent — `/loop` ends naturally.
-3. Emit the final tick-summary telemetry event (see [Telemetry](#telemetry)) with `prs_terminal == pr_count`.
-
-### Step 3: Resolve the reviewer allow-list (every tick)
-
-For each non-terminal PR, compute the set of GitHub logins allowed to drive changes:
-
-```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`).
-
-This is per-tick by design (decision 9): reviewers added or removed after the PR opened take effect on the next poll.
-
-### Step 4: Pull new actionable items
-
-For each non-terminal PR, fetch items newer than the cursor in `last_seen.json`:
-
-- **Line-level review comments**:
-  ```bash
-  gh api repos/<owner>/<repo>/pulls/<number>/comments --paginate
-  ```
-  Filter to comments with `id > last_seen.commentId` AND `user.login` in the allow-list AND not already in `escalated_comment_ids` (avoid re-escalating).
-
-- **CHANGES_REQUESTED review bodies** (only when the review has a non-empty body and no associated line comments):
-  ```bash
-  gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate
-  ```
-  Filter to reviews with `id > last_seen.reviewId` AND `state == "CHANGES_REQUESTED"` AND `user.login` in the allow-list AND `body` is non-empty.
-
-- **Failing CI checks** (apply the `head_sha` guard, decision 11):
-  ```bash
-  gh pr checks <number> --repo <repo> --json name,state,completedAt,detailsUrl,workflow
-  ```
-  Filter to checks where `state == "FAILURE"` AND `completedAt > last_seen.checkRunCompletedAt`. **Skip any check whose target SHA equals `last_pushed_sha`** — CI is still digesting our last push, addressing it again would double-handle.
-
-### Step 5: Pick one item per PR
-
-If a PR has zero actionable items, increment `idle_tick_count` for that PR. Otherwise sort the PR's items by timestamp ascending and take the **oldest one**. Reset `idle_tick_count` to 0 for that PR.
-
-If every PR has zero actionable items this tick:
-- Append a one-line heartbeat to `followup.log`: `<ts> tick #<K> idle (PRs: #A, #B, ...)`.
-- If `idle_tick_count >= 12` for any PR, also rewrite `state.md` with `idle since <ts>, last poll <ts>` for that PR (decision 12).
-- Emit tick-summary telemetry, exit the turn (next tick fires in 5 min via `/loop`).
-
-### Step 6: Classify and route
-
-For each picked item, classify it:
-
-#### Decision rule: classify
-
-| Class | Signals | Action |
-| :---- | :------ | :----- |
-| **directive** | Imperative verb on a concrete target: "rename X to Y", "extract this", "add a null check", "remove this branch", "use `const` here", "this should be `async`", "delete this comment". Includes review-body summaries that read as a list of changes. | Fix → commit → push → reply `Done in <sha> — <one-line>`. |
-| **question** | Ends with `?` and is not a rhetorical disguise. "Why this approach?", "Is this called from X?", "Does this need to handle Z?". | Reply inline with the answer. No code change. No push. |
-| **CI failure** | Source is a failing check, not a comment. | Read the failing job log, fix, commit, push. No reply. |
-| **ambiguous** (default) | Proposes an alternative without instructing ("I think we should use Z instead", "Have you considered Y?"), conflicts with a deliberate choice in the PR description or design doc, or is a multi-part comment mixing question and change request. | **Escalate.** See [Step 7: Escalate](#step-7-escalate). |
-
-When the comment matches neither **directive** nor **question** cleanly, default to **ambiguous**. Do not guess. The cost of escalating a directive that could have been auto-handled is small; the cost of pushing a wrong change because we guessed is large.
-
-#### Decision rule: reply text (adaptive, decision 6)
-
-- **directive**: short, one-line. `Done in <sha> — renamed \`fooBar\` to \`foo_bar\` per request.` Use the [reply-routing helper](#reply-routing) to hit the correct endpoint.
-- **question**: answer inline. Pull surrounding-code context if needed. Reply length matches the question's complexity — don't write three paragraphs to answer a yes/no.
-- **CI failure**: no comment to reply to. The fix commit is the response. The commit message should reference the failing check by name (e.g. `fix(ci): typecheck — narrow type of foo`).
-- **ambiguous**: no reply written by the bot. The escalation goes to the user, who replies to the comment themselves.
-
-### Step 7: Escalate
-
-When the picked item is **ambiguous**:
-
-1. Add the comment id to `last_seen.escalated_comment_ids` so it isn't re-picked next tick.
-2. Append an entry to `followup.log` describing the comment and why it was classified ambiguous.
-3. Pause this PR's loop by writing `escalated: true` against the PR's entry in `prs.json`. Subsequent ticks skip this PR until the user clears the escalation.
-4. End the turn with a **single terminal message** to the user:
-
-```
-**Stage 8 escalation — <repo>#<number>**
-
-<reviewer-login> left an ambiguous comment on <file>:<line>:
-
-> <quoted comment body>
-
-Classifying it as a directive would mean: <one-line interpretation>
-Classifying it as a question would mean: <one-line alternative>
-
-Reply to that GitHub comment yourself, or tell me which way to go. I'll resume polling once the comment is either resolved or has a follow-up from you.
-```
-
-The user clears the escalation by either resolving the GitHub thread (the next tick sees it resolved and removes it from `escalated_comment_ids`) or by replying in this terminal session with a directive that the next tick will pick up.
-
-### Step 8: Update cursors and push
-
-After addressing a non-escalated item:
-
-- Advance `last_seen.commentId` / `last_seen.reviewId` / `last_seen.checkRunCompletedAt` past the addressed item.
-- If a push happened, set `last_seen.last_pushed_sha` to the new HEAD SHA. This arms the `head_sha` guard for the next tick (decision 11).
-- Emit per-item telemetry (see [Telemetry](#telemetry)).
-
-### Step 9: Emit tick-summary telemetry and exit
-
-Emit one `muggle-local-telemetry-skill-emit` event per tick (see [Telemetry](#telemetry)). Exit the turn. Next tick fires in 5 min via `/loop`.
-
-## Reply routing
-
-GitHub's PR comment APIs are not uniform. Route by parent type:
-
-- **Reply to a line-level review comment** (most common): `POST /repos/{owner}/{repo}/pulls/{n}/comments/{comment_id}/replies` with `{"body": "..."}`. The reply lands in the same review thread.
-- **Reply to a CHANGES_REQUESTED review body** (no inline comment to reply to): post a fresh top-level PR comment via `gh pr comment <number> --body "..."` referencing the review. There is no "reply to review body" endpoint.
-- **Failing CI**: no reply. The fix commit is the response.
-
-Never post the same reply twice — the cursor in `last_seen.json` is the only re-entry guard.
-
-## Telemetry
-
-Two telemetry shapes per tick (decision 14):
-
-**Per-item** (one event per addressed/escalated item):
-
-```json
-{
-  "skill": "muggle-do-pr-followup",
-  "event": "item",
-  "session_slug": "<slug>",
-  "repo": "<repo>",
-  "pr_number": <n>,
-  "item_type": "directive|question|ci_failure|ambiguous",
-  "outcome": "fixed_and_pushed|replied|escalated",
-  "comment_id": <id-or-null>,
-  "head_sha": "<sha-or-null>"
-}
-```
-
-**Per-tick summary** (always one, even on idle ticks):
-
-```json
-{
-  "skill": "muggle-do-pr-followup",
-  "event": "tick",
-  "session_slug": "<slug>",
-  "tick": <K>,
-  "pr_count": <total>,
-  "prs_terminal": <count>,
-  "items_seen": <count>,
-  "items_addressed": <count>,
-  "items_escalated": <count>,
-  "pushed": true|false,
-  "tick_duration_ms": <ms>
-}
-```
-
-## Output
-
-This stage produces no console output beyond:
-- The turn preamble (always).
-- An escalation terminal message (only when an item is classified ambiguous).
-- The final `result.md` summary (only on the terminating tick — written to disk, not printed).
-
-Everything else lives in `followup.log` and `last_seen.json`.
-
-## Self-check before ending the turn
-
-Before exiting, confirm:
-
-- [ ] `last_seen.json` was advanced for every item handled.
-- [ ] `prs.json` reflects current PR states (terminal entries marked).
-- [ ] `followup.log` has at minimum a heartbeat or per-item line for this tick.
-- [ ] Telemetry events were emitted (per-item + per-tick).
-- [ ] If pushed, `last_pushed_sha` is set.
-- [ ] If escalated, `escalated_comment_ids` contains the comment id.
-- [ ] If terminal, the loop is NOT continued (do not schedule another tick).
-
-If any are missing, fix before exit — a dropped cursor causes double-handling next tick.

package/dist/plugin/skills/do/validate-code.md

@@ -1,38 +0,0 @@
-# Code Validation Agent (Stage 4/7)
-
-You are validating that each repository's git state is ready for the dev cycle pipeline.
-
-## Turn preamble
-
-Start the turn with:
-
-```
-**Stage 4/7 — Validate code** — checking branch and commit state for each repo with changes.
-```
-
-## Input
-
-You receive:
-- A list of repos with changes (from impact analysis), including their paths and branch names
-
-## Your Job
-
-For each repo:
-
-1. **Verify the branch is a feature branch** (not main/master/the default branch). This should already be validated by impact analysis, but double-check.
-2. **Check for uncommitted changes:** Run `git status --porcelain` in the repo. If there are uncommitted changes, warn the user — uncommitted changes won't be included in PRs.
-3. **Get the branch diff:** Run `git diff <default-branch>...HEAD --stat` for a summary of changes.
-4. **Verify commits exist on the branch:** Run `git log <default-branch>..HEAD --oneline` to confirm there are commits to push.
-
-## Output
-
-Per repo:
-
-**Repo: (name)**
-- Branch: (name)
-- Commits on branch: (count and one-line summaries)
-- Uncommitted changes: yes/no (with warning if yes)
-- Diff stat: (file change summary)
-- Status: READY | WARNING | ERROR
-
-**Overall:** READY to proceed / BLOCKED (with reasons)

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

@@ -1,37 +0,0 @@
----
-name: muggle-do-pr-followup
-description: One polling tick of /muggle-do stage 8 — addresses reviewer comments and CI failures on PRs opened by an earlier /muggle-do session. Dispatched by `/loop 5m /muggle:muggle-do-pr-followup <slug>` after stage 7; also re-runnable by hand on any session slug.
-disable-model-invocation: true
----
-
-# Muggle Test Do — PR follow-up
-
-> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do-pr-followup"`.
-
-This skill is the **dispatch entry** for stage 8 of /muggle-do. It is intentionally thin — the actual per-tick logic lives in [`../do/pr-followup.md`](../do/pr-followup.md), the single source of truth.
-
-## Input routing
-
-`$ARGUMENTS` is the **session slug** (the directory name under `.muggle-do/sessions/`).
-
-- Empty / `help` / `?` → list available session slugs from `.muggle-do/sessions/` that have a non-empty `prs.json` with at least one non-terminal entry, then exit. Do not start a poll.
-- Otherwise → resolve `.muggle-do/sessions/<slug>/`. If the directory or its `prs.json` is missing, log the error to `followup.log` (creating it if needed) and exit. Do **not** ask the user.
-
-## Run one tick
-
-With a valid session slug, follow [`../do/pr-followup.md`](../do/pr-followup.md) exactly. That file owns:
-
-- The turn preamble.
-- The 9-step per-tick contract.
-- The classify rule (directive / question / CI failure / ambiguous → escalate).
-- Reply routing.
-- Telemetry shape.
-- The self-check before exit.
-
-This skill file adds nothing beyond the slug resolution above.
-
-## Why a separate entry exists
-
-- `/loop 5m /muggle:muggle-do-pr-followup <slug>` (dispatched by stage 7 of /muggle-do) needs a slash-addressable target.
-- Manual re-attach: if `/loop` was killed and the user wants to resume, they can run `/muggle:muggle-do-pr-followup <slug>` once to drive a single tick, or re-dispatch the `/loop` themselves.
-- Isolated debugging: a single tick is reproducible against a real session dir.