@muggleai/works 4.11.4 → 4.12.0

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

@@ -0,0 +1,40 @@
+# Reply routing
+
+GitHub's PR APIs are not uniform across comment types. Route by parent type.
+
+## Line-level review comment (most common)
+
+A comment attached to a specific file:line that belongs to a review thread.
+
+```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 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:
+
+```
+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.
+- Never `gh pr review --comment` for replies — that endpoint is for *new* reviews.
+- Never reply twice to the same comment. The cursor in `last_seen.json` is the only re-entry guard; advance it after every reply.

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

@@ -1,151 +1,13 @@
 # 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.
+Generic operational guidance for PR-review follow-up. Caller-agnostic — the watcher fetches reviews, the caller (today: `/muggle-do` in address-reviews mode) reads these files to classify and decide what to do.
 
-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).
+Each section is its own file — load only what the current step needs.
 
-## Resolving the reviewer allow-list
+## Index
 
-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** — but reply per line comment (threaded), not per review.
-
-| 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 **one** implementation cycle for the whole review; reply **threaded per line comment** referencing the new SHA (top-level only when the review is body-only). |
-| **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 shape (all replies for one review reference the same SHA):
-
-- **threaded** (default): `Done in <sha> — <attribution>. (Review #<review_id>, cycle <status>.)`
-- **top-level** (fallback, body-only reviews): `Re: review #<review_id> — addressed in <sha>, cycle <status>.`
-- **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.
+| Section | Use case |
+| :------ | :------- |
+| [`allow-list`](pr-followup-helpers/allow-list.md) | Resolve who counts as a reviewer (requested reviewers ∪ CODEOWNERS − bots − author). |
+| [`reply-routing`](pr-followup-helpers/reply-routing.md) | Pick the right reply endpoint per comment type (line, body-only, CI failure). |
+| [`classify`](pr-followup-helpers/classify.md) | Per-review binary label: actionable vs ambiguous, with worked examples + borderline rule. |

package/plugin/skills/_shared/telemetry-events/muggle-do-cycle.md

@@ -0,0 +1,25 @@
+# `muggle-do:cycle`
+
+One per address-reviews invocation, regardless of outcome.
+
+```json
+{
+  "skill": "muggle-do",
+  "event": "cycle",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "review_ids_in": [<int>, ...],
+  "review_ids_actionable": [<int>, ...],
+  "review_ids_ambiguous": [<int>, ...],
+  "head_sha_before": "<sha-or-null>",
+  "head_sha_after": "<sha-or-null>",
+  "outcome": "pushed" | "escalated" | "mixed" | "no-op"
+}
+```
+
+`outcome`:
+- `"pushed"` — at least one actionable, no ambiguous, push succeeded.
+- `"escalated"` — all reviews were ambiguous; no push.
+- `"mixed"` — both branches happened in the same invocation.
+- `"no-op"` — every input id was already in the escalated set; no work.

package/plugin/skills/_shared/telemetry-events/muggle-do-escalation.md

@@ -0,0 +1,19 @@
+# `muggle-do:escalation`
+
+Zero or one per address-reviews invocation. Fires when `/muggle-do` emits a terminal escalation message to the user.
+
+```json
+{
+  "skill": "muggle-do",
+  "event": "escalation",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "kind": "ambiguous-review" | "design-adjustment",
+  "review_ids": [<int>, ...]
+}
+```
+
+`kind`:
+- `"ambiguous-review"` — one or more reviews classified ambiguous in this batch.
+- `"design-adjustment"` — mid-cycle, the work surfaced a design-level conflict.

package/plugin/skills/_shared/telemetry-events/muggle-do-resolve-reminder.md

@@ -0,0 +1,19 @@
+# `muggle-do:resolve-reminder`
+
+Zero or one per cycle. Fires after the resolve-reminder stage scans threads — only when actionables ran.
+
+```json
+{
+  "skill": "muggle-do",
+  "event": "resolve-reminder",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "addressed_by_loop": <int>,
+  "addressed_by_human": <int>,
+  "not_addressed": <int>,
+  "comment_posted": true | false
+}
+```
+
+- `comment_posted`: false when there were zero addressed-by-loop threads; telemetry still emits so dashboards see the scan happened.

package/plugin/skills/_shared/telemetry-events/pr-followup-bootstrap.md

@@ -0,0 +1,20 @@
+# `muggle-pr-followup:bootstrap`
+
+One per successful bootstrap, after state seeding and before the first watcher dispatches.
+
+```json
+{
+  "skill": "muggle-pr-followup",
+  "event": "bootstrap",
+  "caller": "<caller-name>",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "cursor_review_id": <int>,
+  "resume": true | false
+}
+```
+
+- `caller`: `"user"` for direct invocation; another skill name if relayed.
+- `cursor_review_id`: `0` if no prior submitted reviews; otherwise the highest existing review id.
+- `resume`: true when `--resume` was used.

package/plugin/skills/_shared/telemetry-events/pr-followup-tick.md

@@ -0,0 +1,23 @@
+# `muggle-pr-followup:tick`
+
+One per watcher iteration (idle or not).
+
+```json
+{
+  "skill": "muggle-pr-followup",
+  "event": "tick",
+  "session_slug": "<slug>",
+  "repo": "<owner>/<repo>",
+  "pr_number": <int>,
+  "reviews_seen": <int>,
+  "dispatched_review_ids": [<int>, ...],
+  "terminal": true | false,
+  "idle": true | false,
+  "tick_duration_ms": <int>
+}
+```
+
+- `reviews_seen`: count of new submitted reviews past the cursor, **after** filtering by the escalated set.
+- `dispatched_review_ids`: review ids handed to `/muggle-do`. Empty when idle.
+- `terminal`: true when this tick observed the PR merged or closed and wrote `result.md`.
+- `idle`: true when no reviews were dispatched this tick.

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

@@ -0,0 +1,15 @@
+# Telemetry Event Catalog
+
+Canonical shapes for `muggle-local-telemetry-event-emit` events. Emission mechanics: [`telemetry-emit.md`](telemetry-emit.md).
+
+All events share two top-level fields: `skill` and `event`. The rest is event-specific — read only the file for the event you're emitting.
+
+## Index
+
+| Event | When |
+| :---- | :--- |
+| [`muggle-pr-followup:tick`](telemetry-events/pr-followup-tick.md) | Every watcher iteration (idle or not). |
+| [`muggle-pr-followup:bootstrap`](telemetry-events/pr-followup-bootstrap.md) | Successful bootstrap, before first watcher dispatches. |
+| [`muggle-do:cycle`](telemetry-events/muggle-do-cycle.md) | Every address-reviews invocation, regardless of outcome. |
+| [`muggle-do:escalation`](telemetry-events/muggle-do-escalation.md) | When `/muggle-do` emits a terminal escalation message. |
+| [`muggle-do:resolve-reminder`](telemetry-events/muggle-do-resolve-reminder.md) | After the resolve-reminder stage scans threads. |

package/plugin/skills/do/address-reviews.md

@@ -0,0 +1,137 @@
+# Address-Reviews Orchestrator
+
+The entry procedure for `/muggle-do`'s **address-reviews** mode — invoked by the watcher loop ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md)) when new submitted reviews land on a PR. Orchestrates the cycle: read reviews → classify → execute work on actionables → escalate ambiguous → push and refresh PR → reply per comment → resolve-reminder → respawn watcher.
+
+## Turn preamble
+
+```
+**/muggle-do address-reviews** — handling <count> review(s) on <owner>/<repo>#<n>.
+```
+
+## Input
+
+`$ARGUMENTS` carries:
+- PR URL: `<owner>/<repo>#<n>` derivable from the URL.
+- Session slug: `<slug>`.
+- List of review ids: one or more integers.
+
+Exact phrasing comes from the watcher's dispatch (see [`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md#step-5-if-one-or-more-new-reviews-dispatch)). Parse all three out of the directive text.
+
+## Inputs from disk
+
+Read from `.muggle-do/sessions/<slug>/`:
+
+- `prs.json` — to locate the PR's local checkout path (the `repo` field maps to a configured local repo) and capture `head_sha_before`.
+- `last_seen.json` — for `pushed_shas[]` (used by the resolve-reminder stage) and to update the cursor.
+- `state.md` — for the cached `loop_user` login (used by resolve-reminder thread classification).
+
+## Procedure
+
+### Step 1 — Read every listed review off GitHub
+
+For each review id in the input:
+
+- Fetch reviews per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md) (cursor 0; filter to the specific id).
+- Fetch its line comments per [`../_shared/github-cli-recipes/line-comments-for-review.md`](../_shared/github-cli-recipes/line-comments-for-review.md).
+
+Group into one combined batch.
+
+### Step 2 — Classify each review
+
+Apply the classify rule in [`../_shared/pr-followup-helpers/classify.md`](../_shared/pr-followup-helpers/classify.md). Two outcomes per review:
+
+- **Actionable** — at least one concrete change request, or an answerable question with a target.
+- **Ambiguous** — no actionable signal.
+
+Build two sets: `actionable_review_ids` and `ambiguous_review_ids`. Their union is the input list.
+
+### Step 3 — Handle ambiguous (if any)
+
+For each id in `ambiguous_review_ids`:
+
+1. Append it to `last_seen.escalated_review_ids` so the watcher won't re-dispatch it.
+
+Emit **one** terminal escalation message (not one per ambiguous review) per [`../muggle-pr-followup/output-templates/escalation.md`](../muggle-pr-followup/output-templates/escalation.md) (ambiguous template). The message lists every ambiguous review and its comments inline. Emit an event with `kind: "ambiguous-review"` per [`../_shared/telemetry-events/muggle-do-escalation.md`](../_shared/telemetry-events/muggle-do-escalation.md).
+
+The user clarifies on GitHub by submitting a new review. The next watcher tick picks it up.
+
+### Step 4 — Handle actionables (if any)
+
+If `actionable_review_ids` is empty, skip Steps 4 and 5; proceed to Step 6 (cursor + respawn). Otherwise:
+
+#### 4a. Flatten the work
+
+The actionable reviews together carry a flat list of change items, one per line comment plus any directive in the review body. Each item is design, code logic, or test in nature; the cycle does **not** treat each item as a separate cycle iteration — it plans them together and runs the work **once** for the whole batch.
+
+#### 4b. Apply design + code-logic changes
+
+Invoke [`build.md`](build.md) with the review-derived requirements: for each comment, what to change and where. `build.md` makes the edits in the working tree but does not commit.
+
+If `build.md` reports that the requested work requires rethinking the design (e.g. the requested change conflicts with a load-bearing invariant), exit early per Step 7 (design-adjustment escalation).
+
+#### 4c. Create or update unit tests
+
+Invoke [`unit-tests.md`](unit-tests.md). Cover the surface that just changed; respect existing test conventions.
+
+#### 4d. Run ONE E2E acceptance pass
+
+Invoke [`e2e-acceptance.md`](e2e-acceptance.md). One pass covering all related test cases for this PR, not one pass per comment. Use the `autoE2ETest` gate per its usual contract.
+
+#### 4e. Create or update the PR
+
+Invoke [`open-prs/update.md`](open-prs/update.md) (pass the PR URL + slug + existing PR number). It pushes, refreshes title/description on state change, posts a fresh walkthrough comment, and appends the new SHA to `last_seen.pushed_shas[]`. Capture the new `head_sha`.
+
+#### 4f. Post per-comment inline replies
+
+Invoke [`per-comment-replies.md`](per-comment-replies.md) with the actionable reviews and the new SHA. One reply per comment, in its own thread, describing what was done for it.
+
+#### 4g. Run the resolve-reminder stage
+
+Invoke [`resolve-reminder.md`](resolve-reminder.md). Scans unresolved threads, classifies, and posts a top-level PR comment listing addressed-by-loop thread ids.
+
+### Step 5 — Update session state
+
+- `last_seen.cycles_completed` += 1
+- `last_seen.last_pushed_sha` = the new head SHA (update.md already wrote this; verify)
+- `last_seen.reviewId` = max(input review ids ∪ last_seen.reviewId)
+
+### Step 6 — Respawn the watcher
+
+Refresh PR state per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md). If the PR is now merged or closed:
+
+1. Write `result.md` per [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md#resultmd).
+2. Do **not** respawn the watcher.
+
+Otherwise, dispatch the next watcher as the last action of this turn:
+
+```
+/loop 1m /muggle:muggle-pr-followup <slug> <n>
+```
+
+### Step 7 — Telemetry
+
+Emit one event per [`../_shared/telemetry-events/muggle-do-cycle.md`](../_shared/telemetry-events/muggle-do-cycle.md). `outcome` is one of:
+
+- `"pushed"` — actionables ran and at least one push succeeded.
+- `"escalated"` — only ambiguous; no push.
+- `"mixed"` — both branches ran.
+- `"no-op"` — every input id was already in `escalated_review_ids` (the watcher shouldn't have dispatched, but defensive coverage).
+
+Emit additional events as Steps fired them (escalation event in Step 3; resolve-reminder event in Step 4g).
+
+## Design-adjustment escalation (Step 4b early exit)
+
+When `build.md` returns `failed: design-adjustment`:
+
+1. Append the affected review ids to `last_seen.escalated_review_ids`.
+2. Emit one terminal message per [`../muggle-pr-followup/output-templates/escalation.md`](../muggle-pr-followup/output-templates/escalation.md) (design-adjustment template).
+3. Emit the `escalation` telemetry event with `kind: "design-adjustment"`.
+4. Skip to Step 6 (respawn watcher). The watcher continues polling — the user can override the design conflict by submitting a new review.
+
+Do **not** push, do **not** post replies, do **not** run resolve-reminder. The cycle ended on a design conflict; the work was not applied.
+
+## Invariants
+
+- One `/muggle-do` invocation = at most one push and one resolve-reminder, regardless of how many reviews are in the batch.
+- Every input review id ends up in either the cursor (handled) or `escalated_review_ids` (skipped) — never both, never neither.
+- The watcher is respawned exactly when the PR is still open at the end of the cycle.

package/plugin/skills/do/build.md

@@ -41,11 +41,11 @@ Per repo:
 
 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
+## Re-entry from the address-reviews flow
 
-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 address-reviews orchestrator ([`address-reviews.md`](address-reviews.md)) invokes this stage when reviewers submit comments that require code/design changes. 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.
+- The orchestrator passes the actionable reviews' bodies + line comments as the requirements amendment for this iteration. Treat them as additions to the goal/AC.
 - 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.
+- After this stage, the orchestrator runs unit-tests → ONE E2E pass → create-or-update PR (push to the existing branch; refresh title/desc if state changed) → per-comment inline replies → resolve-reminder → respawn the watcher.
+- If the requested work cannot be implemented without rethinking design (e.g. a load-bearing invariant must change), return `failed: design-adjustment` and let the orchestrator escalate via the design-adjustment terminal message. Do not partially implement.

package/plugin/skills/do/open-prs/forward.md

@@ -0,0 +1,80 @@
+# Open PR — forward mode
+
+Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fresh feature. Creates the PR via `gh pr create`, seeds session state, dispatches the first watcher.
+
+## Turn preamble
+
+```
+**Stage 7 — Create PR** — pushing the branch and opening the PR.
+```
+
+## Inputs
+
+- Per-repo: name, path, branch.
+- Requirements: goal, acceptance criteria.
+- **Optional** E2E acceptance report from stage 6. Produced by [`../e2e-acceptance.md`](../e2e-acceptance.md); schema in [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md).
+
+## Per repo
+
+0. **`autoCreatePR` gate** — apply per [`../../muggle-preferences/preference-gates/autoCreatePR.md`](../../muggle-preferences/preference-gates/autoCreatePR.md). On skip, record the reason in `result.md` and move on.
+
+1. **Push:** `git push -u origin <branch>` in the repo directory.
+
+2. **Title** (under 70 chars):
+   - E2E report exists and has failures → `[E2E FAILING] <goal>`
+   - No E2E report (validation was `unit-only` or `skip`) → `[UNVERIFIED] <goal>` or `[UNIT-ONLY] <goal>` to match the validation strategy
+   - Otherwise → `<goal>`
+
+3. **Body** — assemble in order:
+   - `## Goal` — from requirements.
+   - `## Acceptance Criteria` — bulleted; omit if empty.
+   - `## Changes` — summary of what changed in this repo.
+   - `## Validation` — one line: link to E2E report, `unit-only`, or `skip — <reason>`.
+   - **If an E2E report exists,** invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode B to render the walkthrough block. Embed the returned `body` verbatim. If no report, skip this block entirely.
+
+4. **Create:** `gh pr create --title "..." --body "..." --head <branch>`. Capture the PR URL and number.
+
+5. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once per [`../../_shared/github-cli-recipes/top-level-comment.md`](../../_shared/github-cli-recipes/top-level-comment.md). Never post when `comment` is `null`.
+
+## Stage 8 handoff
+
+After every repo is processed, build the watcher manifest and dispatch one watcher loop per opened PR. The dispatches are the LAST action this stage takes.
+
+Write `.muggle-do/sessions/<slug>/prs.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#prsjson):
+
+```json
+[{ "repo": "owner/repo", "number": 142, "url": "...", "head_sha": "...", "state": "open" }]
+```
+
+Seed `.muggle-do/sessions/<slug>/last_seen.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#last_seenjson) — empty cursor shape with `pushed_shas: []`. Forward mode never has prior reviews to skip, so `reviewId: 0`.
+
+**Do not** seed `cycle.json` or `requirements.md`. The watcher is a dumb pipe; `/muggle-do` reads reviews off GitHub.
+
+For each entry in `prs.json`, dispatch its watcher:
+```
+/loop 1m /muggle:muggle-pr-followup <slug> <pr-number>
+```
+
+If `prs.json` is empty, **do not dispatch** — record the reason in `result.md` and exit.
+
+## Invariants
+
+- PR creation per non-skipped repo; walkthrough block via Mode B; `prs.json`+`last_seen.json` seeded (no `cycle.json`, no `requirements.md`); `/loop` dispatch is the last action.
+
+## Output
+
+**PRs Created:** repo → URL
+**Skipped:** repo → reason (when `autoCreatePR` short-circuited)
+**Overflow comments posted:** repo → PR #
+**Stage 8:** `Watching <N> PR(s) — one /loop 1m /muggle:muggle-pr-followup <slug> <pr#> per PR` | `No PRs to watch — stage 8 not dispatched`
+**Errors:** repo → message
+
+## Post-merge cleanup
+
+Gated by `autoCleanup`. Fires in a follow-up turn after merge — never from this stage. See [`../../_shared/post-merge-cleanup.md`](../../_shared/post-merge-cleanup.md).
+
+Append one short reminder tied to the gate value:
+
+- `always` → `Once merged, I'll run the cleanup sequence automatically.`
+- `never` → omit.
+- `ask` / absent → `Once merged, I'll check with you about cleanup.`

package/plugin/skills/do/open-prs/update.md

@@ -0,0 +1,54 @@
+# Update PR — address-reviews mode
+
+Invoked by `/muggle-do`'s address-reviews orchestrator after stages 3–6 ran on the existing PR. The PR already exists; this stage pushes the branch, refreshes title/description if state changed, and posts a fresh walkthrough.
+
+Does **not** create a PR, seed session state, or dispatch a watcher (`/muggle-do` respawns the watcher at the end of its address-reviews cycle).
+
+## Turn preamble
+
+```
+**Stage 7 — Update PR** — pushing the branch and refreshing the PR.
+```
+
+## Inputs
+
+- Per-repo: path, branch (head ref name).
+- The existing PR URL + number from `.muggle-do/sessions/<slug>/prs.json`.
+- **Optional** E2E acceptance report from stage 6. Produced by [`../e2e-acceptance.md`](../e2e-acceptance.md); schema in [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md).
+
+## Procedure
+
+Skip `autoCreatePR` (it gates creation, not update). The PR's title is left intact unless state changed in Step 3.
+
+1. **Push:** per [`../../_shared/github-cli-recipes/push-to-branch.md`](../../_shared/github-cli-recipes/push-to-branch.md). Capture the new SHA.
+
+2. **Append new SHA** to `last_seen.json[<key>].pushed_shas` (the resolve-reminder stage uses this to recognize threads addressed by the loop). Set `last_seen.last_pushed_sha` to the new SHA too.
+
+3. **Refresh title if state changed.** Compare the new state against the current PR title prefix:
+   - E2E now passing, current title has `[E2E FAILING]` → strip the prefix per [`../../_shared/github-cli-recipes/pr-edit.md`](../../_shared/github-cli-recipes/pr-edit.md).
+   - E2E now failing, current title has no `[E2E FAILING]` → add the prefix.
+   - Validation now ran (was unit-only/skip, now has E2E report) → strip `[UNVERIFIED]` or `[UNIT-ONLY]`.
+   - Otherwise → no title change.
+
+4. **Refresh body when validation outcome changed** — only when the `## Validation` section's content differs from what's in the body. Use the `--body-file` form in [`../../_shared/github-cli-recipes/pr-edit.md`](../../_shared/github-cli-recipes/pr-edit.md). Preserve `## Goal` and `## Acceptance Criteria` verbatim.
+
+5. **Visual walkthrough comment** — if an E2E report exists, invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode A. Always a fresh comment per cycle; do not edit prior walkthrough comments.
+
+6. **Overflow comment** — same rule as forward mode: post when the walkthrough skill returns non-null `comment`, via [`../../_shared/github-cli-recipes/top-level-comment.md`](../../_shared/github-cli-recipes/top-level-comment.md).
+
+## Handoff
+
+Return control to `/muggle-do`'s address-reviews orchestrator. The orchestrator runs the remaining stages (per-comment replies → resolve-reminder → respawn watcher).
+
+## Invariants
+
+- Push; new SHA appended to `pushed_shas`; title/body refreshed only on state change; walkthrough comment via Mode A.
+- No `gh pr create`, no `/loop` dispatch.
+
+## Output
+
+**PR updated:** URL (new SHA: `<short-sha>`)
+**Title refreshed:** yes | no
+**Body refreshed:** yes | no
+**Walkthrough comment:** posted | skipped (no report)
+**Overflow comment:** posted | skipped