@muggleai/works 5.11.1 → 5.12.0-staging.73

package/dist/plugin/scripts/pr-watch-loop.sh

@@ -45,6 +45,12 @@ for lib in pr-watch-guards.sh pr-watch-events.sh; do
     . "${script_dir}/${lib}"
 done
 
+# Same reasoning as the guards: a missing projection means the plugin moved or
+# upgraded underneath this loop, so step down rather than poll with no state to
+# compare against.
+[ -f "${script_dir}/pr-watch-state.jq" ] || exit 0
+state_projection="$(cat "${script_dir}/pr-watch-state.jq")"
+
 echo "$$" > "${slot}/watch.pid"
 started=$(date +%s)
 fails=0
@@ -88,39 +94,18 @@ query($owner: String!, $name: String!, $number: Int!) {
           }
         }
       }
-      reviews(last: 20, states: [COMMENTED, APPROVED, CHANGES_REQUESTED, DISMISSED]) { nodes { databaseId } }
+      reviews(last: 20, states: [COMMENTED, APPROVED, CHANGES_REQUESTED, DISMISSED]) { nodes { databaseId body } }
       reviewThreads(first: 100) {
         nodes {
           id
           isResolved
           isOutdated
-          comments(last: 1) { nodes { databaseId pullRequestReview { state } } }
+          comments(last: 1) { nodes { databaseId body pullRequestReview { databaseId state } } }
         }
       }
     }
   }
-}' --jq '
-.data.repository.pullRequest as $pr
-| (($pr.commits.nodes[0].commit.statusCheckRollup.contexts.nodes) // []) as $contexts
-| ($contexts | map(
-    if .__typename == "CheckRun"
-    then {name: .name, verdict: (if .status != "COMPLETED" then "PENDING" else (.conclusion // "NEUTRAL") end)}
-    else {name: .context, verdict: (.state // "PENDING")}
-    end)) as $checks
-| [
-    $pr.state,
-    $pr.headRefOid,
-    $pr.baseRefOid,
-    $pr.mergeable,
-    (([$pr.reviews.nodes[].databaseId] | max) // 0),
-    (([$pr.reviewThreads.nodes[] | select(.isResolved == false) | .comments.nodes[]
-       | select((.pullRequestReview.state // "SUBMITTED") != "PENDING") | .databaseId] | max) // 0),
-    ([$pr.reviewThreads.nodes[] | select(.isResolved == false) | select(.isOutdated == false)
-      | select((.comments.nodes[0].pullRequestReview.state // "SUBMITTED") != "PENDING") | .id] | join(";")),
-    ($checks | map(select(.verdict == "PENDING")) | length),
-    ($checks | map(select(.verdict == "FAILURE" or .verdict == "ERROR" or .verdict == "TIMED_OUT" or .verdict == "STARTUP_FAILURE")) | length),
-    ($checks | sort_by(.name) | map(.name + ":" + .verdict) | join(","))
-  ] | @tsv' 2>>"${slot}/watch-fetch.log"
+}' --jq "$state_projection" 2>>"${slot}/watch-fetch.log"
 }
 
 # behind_by needs its own call — see watch_wake_rebase for why no field on the

package/dist/plugin/scripts/pr-watch-state.jq

@@ -0,0 +1,52 @@
+# Projects one PR's GraphQL snapshot into the tab-separated state line the watch
+# loop compares against its floors. Lives in its own file so it can be exercised
+# directly against fixtures — embedded in the loop it was unreachable by tests,
+# which is how the echo wake below survived unnoticed.
+#
+# Field order is the contract pr-watch-loop.sh reads positionally:
+#   state, headRefOid, baseRefOid, mergeable, latest-review, latest-comment,
+#   unresolved-thread-ids, pending-checks, failed-checks, check-digest
+
+def loop_marked: ((.body // "") | contains("<!-- muggle-do:bot -->"));
+
+.data.repository.pullRequest as $pr
+| (($pr.commits.nodes[0].commit.statusCheckRollup.contexts.nodes) // []) as $contexts
+| ($contexts | map(
+    if .__typename == "CheckRun"
+    then {name: .name, verdict: (if .status != "COMPLETED" then "PENDING" else (.conclusion // "NEUTRAL") end)}
+    else {name: .context, verdict: (.state // "PENDING")}
+    end)) as $checks
+
+# Every comment on a live thread that belongs to a submitted review. A PENDING
+# review is the reviewer's own draft and is not feedback yet.
+| [$pr.reviewThreads.nodes[]
+   | select(.isResolved == false)
+   | .comments.nodes[]
+   | select((.pullRequestReview.state // "SUBMITTED") != "PENDING")] as $liveComments
+
+# Posting a threaded reply also mints a review envelope around it. That envelope
+# is the loop's own echo: without excluding it the loop wakes itself every time
+# it answers a comment, and the tick it triggers can only idle.
+| ($liveComments | map(select(loop_marked) | .pullRequestReview.databaseId | values)) as $loopOwnedReviews
+| ($liveComments | map(select(loop_marked | not) | .pullRequestReview.databaseId | values)) as $humanOwnedReviews
+# `index` evaluates its argument against the array it is indexing, so the review
+# has to be bound before either membership test can name its id.
+| def is_echo_review:
+    . as $review
+    | ((($review.body // "") == "") or ($review | loop_marked))
+      and (($loopOwnedReviews | index($review.databaseId)) != null)
+      and (($humanOwnedReviews | index($review.databaseId)) == null);
+
+[
+  $pr.state,
+  $pr.headRefOid,
+  $pr.baseRefOid,
+  $pr.mergeable,
+  (([$pr.reviews.nodes[] | select(is_echo_review | not) | .databaseId] | max) // 0),
+  (($liveComments | map(select(loop_marked | not) | .databaseId) | max) // 0),
+  ([$pr.reviewThreads.nodes[] | select(.isResolved == false) | select(.isOutdated == false)
+    | select((.comments.nodes[0].pullRequestReview.state // "SUBMITTED") != "PENDING") | .id] | join(";")),
+  ($checks | map(select(.verdict == "PENDING")) | length),
+  ($checks | map(select(.verdict == "FAILURE" or .verdict == "ERROR" or .verdict == "TIMED_OUT" or .verdict == "STARTUP_FAILURE")) | length),
+  ($checks | sort_by(.name) | map(.name + ":" + .verdict) | join(","))
+] | @tsv

package/dist/plugin/skills/_shared/identity-and-inbox.md

@@ -0,0 +1,39 @@
+# Identity and inbox
+
+Muggle drives a real browser under a real identity. That is the capability a bare Playwright or Cypress harness lacks, and the reason an email-gated or login-gated flow is ordinary work here rather than a blocker.
+
+## Receiving email
+
+Every managed login profile is minted its own live inbox. A generated script reaches it with a `readEmail` step, which opens the newest message in that mailbox and answers a question about it, so the code, link, or confirmation lands back in the run as a value later steps use.
+
+Testable end to end, with no mail stub, no local catcher (MailHog, Mailpit, Mailtrap), and no test-only backdoor in the product:
+
+- Magic-link and sign-in-link login
+- Emailed OTP and one-time codes
+- Email-based two-factor challenges
+- Address-verification and confirmation mail
+- Password-reset links
+
+The product sends real mail to a real address. Nothing in the app under test needs a test hook for this to work.
+
+## Credentials
+
+Managed login profiles carry stored secrets, injected at run time. A flow behind a password, a paywall, or a seat licence is reachable — "there is no logged-in session" is not a reason to decline, nor to narrow scope to logged-out pages.
+
+## CAPTCHA
+
+A `solveCaptcha` step handles reCAPTCHA v2 and v3, hCaptcha, image, and slider challenges.
+
+## Out of scope
+
+Genuine limits. Say so plainly when one of them is what blocks a flow, and never promise a run that cannot happen:
+
+- SMS and phone-call OTP — no phone number is minted
+- Authenticator-app TOTP
+- OAuth-only social login (Google, GitHub) where the flow does not explicitly require it
+
+A non-email second factor routes to a user-intervene step rather than completing on its own.
+
+## Wrong conclusions
+
+Before writing that a flow is untestable, unreachable, or needs a stub, check the lists above. The recurring error is declaring a magic-link or email-verification flow un-E2E-able and falling back to unit tests: the flow is supported, and the fallback silently drops the acceptance coverage the user asked for.

package/dist/plugin/skills/_shared/sync-branch-with-base.md

@@ -0,0 +1,29 @@
+# Sync the Branch With Its Base
+
+Bring the working branch up to date with the branch it merges into — before a dev server or E2E run, and before any push that opens or updates a change. Gated by [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md). Follow the standard procedure in [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
+
+## Resolving the base
+
+`base` is the branch the work merges into, which is not automatically the remote default — pre-flight lets the user target a different branch, and once a change exists its `baseRefName` is authoritative. A caller holding a base passes it in; fall back to the remote default only when no target was chosen.
+
+**Fire only when `behind > 0`:**
+
+```bash
+git fetch origin
+base="${base:-$(git symbolic-ref refs/remotes/origin/HEAD --short | sed 's|origin/||')}"
+behind=$(git rev-list --count "HEAD..origin/${base}")
+```
+
+Pass `{behind}` and `{base}` to the picker prompts. On `always`:
+
+1. Capture the rollback point: `pre_rebase_sha=$(git rev-parse HEAD)`.
+2. `git rebase origin/${base}`.
+3. On conflict, branch by [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md):
+   - `never` → `git rebase --abort`; stop and report, naming the conflicted files. Never auto-resolve.
+   - `always` → hand off to [`resolve-rebase-conflicts.md`](resolve-rebase-conflicts.md) with `pre_rebase_sha` to resolve the conflicts, then run the [`verify-or-rollback-gate.md`](verify-or-rollback-gate.md) with `pre_rebase_sha`; it either proceeds or restores `pre_rebase_sha` and escalates.
+
+## Branches already on the remote
+
+The rebase rewrites history, so a branch the remote already has needs a force-push to land it. Never force-push from here. A caller in that position hands the sync to its own rebase mode, which owns the per-SHA attempt budget and the verify-or-rollback gate wrapped around the force-push.
+
+Stale branches produce false failures and false greens, and a branch that goes stale between validation and push opens a change that cannot merge — that is why this gate exists.

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

@@ -1,6 +1,6 @@
 # `muggle-do:escalation`
 
-Zero or one per address-reviews invocation. Fires when `/muggle-do` emits a terminal escalation message to the user.
+Zero or one per address-reviews invocation, plus zero or one per forward cycle that waives a failing E2E run. Fires when `/muggle-do` emits a terminal escalation message to the user.
 
 ```json
 {
@@ -9,7 +9,7 @@ Zero or one per address-reviews invocation. Fires when `/muggle-do` emits a term
   "session_slug": "<slug>",
   "repo": "<owner>/<repo>",
   "pr_number": <int>,
-  "kind": "ambiguous-review" | "design-adjustment" | "rebase-conflict",
+  "kind": "ambiguous-review" | "design-adjustment" | "rebase-conflict" | "e2e-unrepairable",
   "review_ids": [<int>, ...]
 }
 ```
@@ -18,3 +18,4 @@ Zero or one per address-reviews invocation. Fires when `/muggle-do` emits a term
 - `"ambiguous-review"` — one or more reviews classified ambiguous in this batch.
 - `"design-adjustment"` — mid-cycle, the work surfaced a design-level conflict.
 - `"rebase-conflict"` — an opt-in auto-rebase hit conflicts that couldn't be resolved and verified; the branch was restored to its pre-rebase SHA. `review_ids` may be empty.
+- `"e2e-unrepairable"` — the E2E repair loop shipped with failures it could not fix: the user waived, an unattended run had nobody to ask, or the iteration cap ran out. `review_ids` is empty.

package/dist/plugin/skills/_shared/vcs/github/unresolved-threads.md

@@ -37,3 +37,5 @@ Filter client-side to `isResolved == false`. Walk each thread's comments in `cre
 Each comment exposes its owning review as `pullRequestReview.databaseId` — the watcher collects this from an actionable thread's newest comment to build its dispatch list.
 
 A loop comment also cites a `<short-sha>` from `last_seen.pushed_shas[]` in its body, which tells *which* push addressed the thread.
+
+Resolving a thread is the reviewer's act, never the loop's: the marker classification above already retires an addressed thread, so a `resolveReviewThread` mutation would only hide it before the reviewer has verified the fix. A `PreToolUse` guardrail denies the call.

package/dist/plugin/skills/_shared/vcs/gitlab/unresolved-discussions.md

@@ -15,4 +15,6 @@ Walk each unresolved thread's `notes[]` in `created_at` order and classify by th
 - **Unaddressed human comment** — the newest note lacks the marker and is newer than the thread's newest loop-marked note (or the thread has none yet). → actionable: the round should address it.
 - **Not addressed** — indeterminate (e.g. no notes).
 
-Each thread carries its `id` (the `discussion_id`) — the watcher collects this from an actionable thread to build its dispatch list and to target the resolve call later.
+Each thread carries its `id` (the `discussion_id`) — the watcher collects this from an actionable thread to build its dispatch list.
+
+Marking a discussion resolved is the reviewer's act, never the loop's: the marker classification above already retires an addressed thread, so a resolve would only hide it. A `PreToolUse` guardrail denies the call.

package/dist/plugin/skills/_shared/vcs/gitlab.md

@@ -18,7 +18,6 @@ Skills assume a working `glab auth status`. Auth errors surface verbatim from `g
 | [`unresolved-discussions`](gitlab/unresolved-discussions.md) | Unresolved-discussion state — watcher's dispatch trigger + resolve-reminder. |
 | [`reply-discussion`](gitlab/reply-discussion.md) | POST a threaded reply on a discussion. |
 | [`mr-note`](gitlab/mr-note.md) | POST a top-level MR note — resolve-reminder + overflow. |
-| [`resolve-discussion`](gitlab/resolve-discussion.md) | Mark a discussion thread resolved. |
 | [`mr-edit`](gitlab/mr-edit.md) | Refresh title or description when address-reviews mode flips state. |
 | [`mr-create`](gitlab/mr-create.md) | Open an MR + capture its URL for handoff. |
 | [`loop-user-identity`](gitlab/loop-user-identity.md) | Resolve the GitLab username of the loop user. |

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

@@ -29,7 +29,7 @@ Read from `~/.muggle-ai/muggle-do/sessions/<slug>/`:
 
 ### Step 0 — Track the default branch
 
-Before assembling work, rebase onto the latest default branch so the cycle addresses reviews against current master, not a stale base. Run [`../_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md) — gated by [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), fires only when `behind > 0`. Conflict handling follows [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md): the default `never` aborts and escalates (`kind: "rebase-conflict"`); `always` resolves behind the verify-or-rollback gate. If the rebase escalates, stop the cycle — do not push, do not address reviews — but **skip to Step 6 to respawn the watcher**. Escalating the rebase does not end the PR; the poller must keep running (it will remind on the `conflict_escalated` block), so skipping respawn here is exactly the silent-stop bug [`respawn-watcher.md`](respawn-watcher.md) exists to prevent.
+Before assembling work, rebase onto the latest default branch so the cycle addresses reviews against current master, not a stale base. Run [`../_shared/sync-branch-with-base.md`](../_shared/sync-branch-with-base.md) — gated by [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), fires only when `behind > 0`. Conflict handling follows [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md): the default `never` aborts and escalates (`kind: "rebase-conflict"`); `always` resolves behind the verify-or-rollback gate. If the rebase escalates, stop the cycle — do not push, do not address reviews — but **skip to Step 6 to respawn the watcher**. Escalating the rebase does not end the PR; the poller must keep running (it will remind on the `conflict_escalated` block), so skipping respawn here is exactly the silent-stop bug [`respawn-watcher.md`](respawn-watcher.md) exists to prevent.
 
 ### Step 1 — Assemble the work set
 
@@ -46,6 +46,8 @@ Resolve the provider per [`../_shared/vcs/detect-vcs.md`](../_shared/vcs/detect-
 
 Group (a) and (b) into one combined batch.
 
+**Claim each thread in the batch.** Claiming is what records that this round took the thread as work; the reply gate settles from claims, not from whether a push happened. Release the claims when the round ends. A claim whose holder died is not a claim — the entry reads unprocessed again and the next round re-claims it — so a crashed round leaves nothing to clean up.
+
 **`gitlab`** — single source (no review-id watermark; discussion state is the sole authority). Fetch unresolved discussions per [`../_shared/vcs/gitlab/unresolved-discussions.md`](../_shared/vcs/gitlab/unresolved-discussions.md) (drop to [`../_shared/vcs/gitlab/mr-discussions.md`](../_shared/vcs/gitlab/mr-discussions.md) for raw notes where classification needs them). The input ids are discussion ids; the batch is every discussion classified **unaddressed human comment** — newest note lacks the marker and post-dates the loop's last marked note. **Exclude** discussions whose id is in `last_seen.escalated_review_ids`. A discussion is the unit of work in place of GitHub's review + line-comment pair.
 
 ### Step 2 — Classify each review
@@ -62,6 +64,7 @@ Build two sets: `actionable_review_ids` and `ambiguous_review_ids`. Their union
 For each id in `ambiguous_review_ids`:
 
 1. Append it to `last_seen.escalated_review_ids` so the watcher won't re-dispatch it.
+2. Run `echo "MUGGLE_REPLY_SKIP: <comment-id> deferred to the user"` naming its comment ids (`gitlab`: discussion ids). An escalated thread is deferred, not answered, so the reply gate in [`per-comment-replies.md`](per-comment-replies.md) would otherwise hold the turn open waiting on a reply that is not coming. The deferral is recorded against those comments durably, so it still holds after this session ends; a marker naming no tracked comment falls back to a session-wide skip.
 
 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).
 
@@ -97,7 +100,7 @@ Invoke [`open-prs/update.md`](open-prs/update.md) (pass the PR URL + slug + exis
 
 #### 4f. Post per-comment inline replies
 
-Invoke [`per-comment-replies.md`](per-comment-replies.md) with the actionable reviews (`gitlab`: discussions) and the new SHA. One reply per comment, in its own thread, describing what was done for it; on `gitlab` the same step also resolves each fully-addressed discussion.
+Invoke [`per-comment-replies.md`](per-comment-replies.md) with the actionable reviews (`gitlab`: discussions) and the new SHA. One reply per comment, in its own thread, describing what was done for it. The reply is the whole of it — neither provider's threads get resolved by the loop.
 
 (The resolve-reminder runs once per round in Step 5.5 below — not only after a push — so a round that pushed nothing still nudges addressed-but-unresolved threads.)
 

package/dist/plugin/skills/do/build.md

@@ -56,3 +56,12 @@ The address-reviews orchestrator ([`address-reviews.md`](address-reviews.md)) in
 - Continue on the existing branch — do not re-create the worktree.
 - 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.
+
+## Re-entry from the E2E repair loop
+
+[`e2e-repair.md`](e2e-repair.md) invokes this stage when a failing acceptance run root-causes to a product defect the change introduced. When re-entered:
+
+- The loop passes the named defects — failing step, expected-versus-actual, and the implicated code path — as the requirements amendment for this iteration. Treat them as additions to the goal/AC.
+- Continue on the existing branch; the worktree and the PR already exist.
+- After this stage, the loop runs unit-tests → a re-run scoped to the affected test cases → `open-prs/update.md`. Impact analysis does not re-run.
+- If the defect can't be fixed without rethinking design, return `failed: design-adjustment`. The loop routes it to its user decision instead of burning an iteration on it.

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

@@ -147,6 +147,8 @@ For each test case:
 
 **Overall:** PASS | FAIL | PARTIAL | INCONCLUSIVE | BLOCKED | SKIPPED — see [`../_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) section F for the canonical taxonomy.
 
+A non-passing verdict does not end the cycle. [`e2e-repair.md`](e2e-repair.md) consumes this report at Stage 7.5 and root-causes every Failed and Inconclusive entry before a watcher is armed, so write those blocks in full — the bucket, failing step, and `artifactsDir` recorded here are that stage's entire input.
+
 Failed runs use the same evidence + diagnosis assembly as the interactive debug path ([`../_shared/debug-failed-run.md`](../_shared/debug-failed-run.md) Steps 1–2) — write that evidence into the **Failed** block above. This stage is autonomous, so it skips Step 3's interactive offer.
 
 ## Hard constraints

package/dist/plugin/skills/do/e2e-repair.md

@@ -0,0 +1,98 @@
+# E2E Repair Loop (Stage 7.5)
+
+Runs between Stage 7's posted walkthrough and Stage 8's watcher dispatch. A failing acceptance run means the change is not ready for a reviewer, so this stage root-causes every failure and either repairs it in-pipeline or puts one decision in front of the user. The watcher is armed only once this stage clears.
+
+## Turn preamble
+
+```
+**Stage 7.5 — E2E repair** — root-causing the failing acceptance runs before handing off to the watcher.
+```
+
+## Inputs
+
+- The Stage 6 acceptance report from [`e2e-acceptance.md`](e2e-acceptance.md) — its Failed and Inconclusive blocks and the run-level verdict.
+- `state.md` — validation strategy, per-repo worktree path, project id.
+- The PR opened by [`open-prs/forward.md`](open-prs/forward.md) — repo and number, for the escalation event and the refresh path.
+- `repairIteration` — how many times this stage has already run in this session, read from `iterations/<NNN>.md`.
+
+## Step 0: Clearance check
+
+Read the Stage 6 run-level verdict, defined in [`../_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) section F.
+
+- `PASS` or `SKIPPED` → nothing to repair. Append `e2e-repair: clear (<verdict>)` to the iteration log and hand to Stage 8.
+- A verdict the user waived earlier in this session → clear on the recorded waiver; never re-ask.
+- `FAIL`, `PARTIAL`, `INCONCLUSIVE`, or `BLOCKED` → the loop runs over every entry in the Failed and Inconclusive blocks.
+
+## Step 1: Root-cause each failure
+
+Per failing test case, assemble evidence and a diagnosis with [`../_shared/debug-failed-run.md`](../_shared/debug-failed-run.md) Steps 1–2 — attempted steps, halt reason, the failing step's screenshot, then the bucket. That doc's Step 3 is the interactive debug card; this stage is autonomous and does not run it.
+
+Stage 6 already wrote this evidence into its Failed block. Re-derive a bucket only for entries that arrived without one.
+
+The bucket is the root cause. Anything that does not land in a bucket is `unclassified` — never force-fit one to reach an auto-repair disposition.
+
+## Step 2: Disposition
+
+Map each bucket to exactly one disposition. Buckets are defined in [`../_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) sections B and C.
+
+| Bucket | Disposition | Why |
+| :----- | :---------- | :-- |
+| `product-defect` (replay) | `repair` | The change broke a flow that used to work. That is this pipeline's own bug to fix. |
+| `product-uxux` (regen) | `repair` | The product blocks the agent because the feature does not work. |
+| `stale-script` (replay) | `regenerate` | Selectors moved; the product is fine. Regenerating is self-healing, not a code change. |
+| `transient` (regen) | `retry` | Once, then re-bucket the second result. A twice-transient failure is `infra`. |
+| `infra` (either) | `ask` | A Muggle Test bug. Nothing in this repo fixes it. |
+| `agent-course` (regen) | `ask` | The agent needs steering, which is the user's `muggle-feedback` call to make. |
+| `unclassified` | `ask` | No bucket, no automatic action. |
+
+A `repair` disposition requires a named defect: the failing step, expected-versus-actual, and the code path it implicates. Without one it is `ask`, whatever the bucket said.
+
+## Step 3: Act
+
+Process dispositions in order — `retry`, then `regenerate`, then `repair` — so cheap self-healing runs before any code change.
+
+- **`retry`** — re-execute the case unchanged through the Stage 6 loop. Re-bucket the result and fold it back into Step 2.
+- **`regenerate`** — regenerate the script for that test case, then re-replay. One regeneration per test case per iteration, matching Stage 6's own cap.
+- **`repair`** — re-enter [`build.md`](build.md) with the named defects as this iteration's requirements amendment, then run [`unit-tests.md`](unit-tests.md) and refresh the PR through [`open-prs/update.md`](open-prs/update.md). Impact analysis does not re-run; the change is scoped to a known defect.
+- **`ask`** — collect every `ask` failure and present **one** `AskUserQuestion` (Step 4). Never one picker per failure.
+
+## Step 4: The user decision
+
+One question, listing each unrepairable failure with its bucket, failing step, and dashboard link. Options:
+
+1. **Repair anyway** — the user names what the fix should be; the loop treats it as a `repair` disposition and re-enters Step 3.
+2. **Give feedback and rerun** — invoke `muggle-feedback` for the run, then re-execute in regen mode. The right answer for `agent-course`.
+3. **Waive and ship** — record the waiver in `state.md`, retitle the PR `[E2E FAILING]`, and clear to Stage 8.
+4. **Stop here** — leave the PR open and unwatched; the user takes it from there.
+
+**Unattended runs.** When the cycle was started autonomously there is nobody to ask. Do not skip the loop — run Steps 1–3 in full, then treat a surviving `ask` as an automatic waive: emit the escalation event, retitle `[E2E FAILING]`, and clear to Stage 8. Silently arming the watcher on a red run is the failure this stage exists to prevent.
+
+## Step 5: Close the loop
+
+After a `repair`, `regenerate`, or `retry` pass, re-run [`e2e-acceptance.md`](e2e-acceptance.md) over the affected test cases only, increment `repairIteration`, and return to Step 0.
+
+The loop is bounded at **3** repair iterations, the same bound the cycle guardrail already applies to E2E failures. On the third exhausted iteration, waive automatically: retitle `[E2E FAILING]`, record the surviving failures in `result.md`, and clear to Stage 8. A PR a reviewer can see is worth more than a loop that never terminates.
+
+## Telemetry
+
+Steps 1–3 emit the `*-classified` / `*-resolved` pair per [`../_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) section D, with `userAction` set to the disposition this stage took (`repair`, `regenerate`, `retry`) rather than a human pick. A failure that reaches Step 4 records the user's actual choice.
+
+Every waive — user-picked, unattended, or iteration-capped — also emits `muggle-do:escalation` with `kind: "e2e-unrepairable"` per [`../_shared/telemetry-events/muggle-do-escalation.md`](../_shared/telemetry-events/muggle-do-escalation.md).
+
+## Output
+
+**Verdict in:** `<Stage 6 verdict>`
+**Repair iterations:** `<n>` of 3
+**Repaired:** test case → root cause → commit subject
+**Regenerated:** test case → new script id
+**Waived:** test case → bucket → reason
+**Verdict out:** `<verdict after the final re-run>`
+**Clearance:** `green` | `waived — <reason>` | `iteration-cap`
+
+## Invariants
+
+- Stage 8 is unreachable while clearance is unresolved — the only exits are green, waived, or iteration-capped.
+- No bucket auto-repairs without a named defect.
+- One `AskUserQuestion` per stage run, never one per failure.
+- An unattended run still executes Steps 1–3; only Step 4 collapses.
+- Re-runs are scoped to the affected test cases, never the whole suite.

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

@@ -1,6 +1,6 @@
 # Open PR — forward mode
 
-Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fresh feature. Opens the change — a PR on GitHub (`gh pr create`) or an MR on GitLab (`glab mr create`), provider resolved in Step 4 — then seeds session state and dispatches the first watcher.
+Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fresh feature. Opens the change — a PR on GitHub (`gh pr create`) or an MR on GitLab (`glab mr create`), provider resolved in Step 5 — then seeds session state and dispatches the first watcher.
 
 ## Turn preamble
 
@@ -18,14 +18,16 @@ Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fres
 
 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:** Execute per [`../../_shared/vcs/common/push-to-branch.md`](../../_shared/vcs/common/push-to-branch.md) — the tool-agnostic instruction for pushing commits (handles the signing gate and directs to provider-specific recipes).
+1. **Sync with the base:** run [`../../_shared/sync-branch-with-base.md`](../../_shared/sync-branch-with-base.md) with `base` set to the PR target recorded in `state.md` — gated by [`autoRebase`](../../muggle-preferences/preference-gates/autoRebase.md), fires only when `behind > 0`. The branch is not on the remote yet, so the rebase lands without a force-push. Sync here rather than trusting stage 6: a `unit-only` or `skip` run never reaches the E2E stage's sync at all, and on a run that does, the base moves freely while stages 3–6 build and test. If the sync escalates — conflicts under `autoResolveConflicts=never`, or a resolution that fails the verify-or-rollback gate — stop and report; never open a PR on a tree that did not verify.
 
-2. **Title** (under 70 chars):
+2. **Push:** Execute per [`../../_shared/vcs/common/push-to-branch.md`](../../_shared/vcs/common/push-to-branch.md) — the tool-agnostic instruction for pushing commits (handles the signing gate and directs to provider-specific recipes).
+
+3. **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:
+4. **Body** — assemble in order:
    - `## Goal` — from requirements.
    - `## Acceptance Criteria` — bulleted; omit if empty.
    - `## Changes` — summary of what changed in this repo.
@@ -33,15 +35,19 @@ Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fres
    - **Walkthrough block** — only when an E2E report exists. Fire [`postPRVisualWalkthrough`](../../muggle-preferences/preference-gates/postPRVisualWalkthrough.md); on skip, omit this block. Otherwise invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode B and embed the returned `body` verbatim. No report → skip the block.
    - **Signature** — write the assembled body to a file and sign it with `--command /muggle-do --mode editable` per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). The signature lands last, after the walkthrough block; `editable` is the mode a description carries so later refreshes replace it instead of stacking.
 
-4. **Create:** resolve the provider per [`../../_shared/vcs/detect-vcs.md`](../../_shared/vcs/detect-vcs.md).
-   - `github` → `gh pr create --title "..." --body-file <signed-file> --head <branch>`, passing the file signed in Step 3. Capture the PR URL and number.
+5. **Create:** resolve the provider per [`../../_shared/vcs/detect-vcs.md`](../../_shared/vcs/detect-vcs.md).
+   - `github` → `gh pr create --title "..." --body-file <signed-file> --head <branch>`, passing the file signed in Step 4. Capture the PR URL and number.
    - `gitlab` → open the change via [`../../_shared/vcs/gitlab/mr-create.md`](../../_shared/vcs/gitlab/mr-create.md): `glab mr create --source-branch <branch> --target-branch <base> --title "..." --description "..."`. Capture the MR URL and iid.
 
-5. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once using the provider resolved in Step 4 — `github` per [`../../_shared/vcs/github/top-level-comment.md`](../../_shared/vcs/github/top-level-comment.md), `gitlab` per [`../../_shared/vcs/gitlab/mr-note.md`](../../_shared/vcs/gitlab/mr-note.md). End the posted body with the signature line (command `/muggle-do`) per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). Never post when `comment` is `null`.
+6. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once using the provider resolved in Step 5 — `github` per [`../../_shared/vcs/github/top-level-comment.md`](../../_shared/vcs/github/top-level-comment.md), `gitlab` per [`../../_shared/vcs/gitlab/mr-note.md`](../../_shared/vcs/gitlab/mr-note.md). End the posted body with the signature line (command `/muggle-do`) per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). Never post when `comment` is `null`.
+
+## Stage 7.5 gate
+
+The E2E repair loop ([`../e2e-repair.md`](../e2e-repair.md)) runs once this stage has created the PR and posted the walkthrough, and before the handoff below. Proceed only on its `green`, `waived`, or `iteration-cap` clearance — handing a red run to a watcher puts it in front of reviewers with nobody looking at the failures. When Stage 6 recorded `PASS` or `SKIPPED` the loop clears in its own Step 0 at no cost, so there is never a reason to skip it.
 
 ## 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.
+After every repo is processed and Stage 7.5 has cleared, build the watcher manifest and dispatch one watcher loop per opened PR. The dispatches are the LAST action this stage takes.
 
 Write `~/.muggle-ai/muggle-do/sessions/<slug>/prs.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#prsjson):
 
@@ -62,13 +68,15 @@ If `prs.json` is empty, **do not dispatch** — record the reason in `result.md`
 
 ## 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.
+- Branch synced with its base before the push, never after; PR creation per non-skipped repo; walkthrough block via Mode B; `prs.json`+`last_seen.json` seeded (no `cycle.json`, no `requirements.md`); Stage 7.5 cleared before the dispatch; `/loop` dispatch is the last action.
 
 ## Output
 
+**Synced with base:** repo → `rebased onto <base> (<n> behind)` | `already up to date` | `skipped (autoRebase)`
 **PRs Created:** repo → URL
 **Skipped:** repo → reason (when `autoCreatePR` short-circuited)
 **Overflow comments posted:** repo → PR #
+**Stage 7.5:** `green` | `waived — <reason>` | `iteration-cap`
 **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
 

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

@@ -22,7 +22,13 @@ Skip `autoCreatePR` (it gates creation, not update). The PR's title is left inta
 
 Resolve the provider once per [`../../_shared/vcs/detect-vcs.md`](../../_shared/vcs/detect-vcs.md). Wherever Steps 3–4 below edit title/description: `github` uses `gh pr edit` per [`../../_shared/vcs/github/pr-edit.md`](../../_shared/vcs/github/pr-edit.md); `gitlab` uses `glab mr update --title --description` per [`../../_shared/vcs/gitlab/mr-edit.md`](../../_shared/vcs/gitlab/mr-edit.md).
 
-1. **Push:** per [`../../_shared/vcs/common/push-to-branch.md`](../../_shared/vcs/common/push-to-branch.md). Capture the new SHA.
+0. **Sync with the base:** `git fetch origin`, then count `behind` against the base branch recorded in `state.md`. [`../address-reviews.md`](../address-reviews.md) syncs at the top of the cycle, but stages 3–6 build, test, and run E2E in between — by the time this stage pushes, that sync is old and the PR can land behind its base.
+
+   When `behind > 0`, run Steps 2–3 of [`../resolve-conflicts.md`](../resolve-conflicts.md) — rebase onto the base, then the verify-or-rollback gate — and force-push in Step 1, since the rebase rewrote commits the remote already has. Borrow that mode's procedure only; do not dispatch the mode itself, which force-pushes and respawns the watcher on its own, and the address-reviews orchestrator already owns the respawn for this cycle.
+
+   If the rebase escalates — conflicts under `autoResolveConflicts=never`, or a resolution that fails verification — stop without pushing and let the orchestrator escalate. A PR sitting behind its base is recoverable: the watcher re-detects it and dispatches the rebase mode properly. A force-pushed unverified tree is not.
+
+1. **Push:** per [`../../_shared/vcs/common/push-to-branch.md`](../../_shared/vcs/common/push-to-branch.md), with `git push --force-with-lease` when Step 0 rebased. 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. Both are whole-file rewrites (Read → change field → Write) per [`../../_shared/session-state-writes.md`](../../_shared/session-state-writes.md) — never the Edit tool.
 
@@ -44,11 +50,12 @@ Return control to `/muggle-do`'s address-reviews orchestrator. The orchestrator
 
 ## Invariants
 
-- Push; new SHA appended to `pushed_shas`; title/body refreshed only on state change; walkthrough comment via Mode A.
+- Branch synced with its base before the push, never after; 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
 
+**Synced with base:** `rebased onto <base> (<n> behind, force-pushed)` | `already up to date` | `skipped (autoRebase)`
 **PR updated:** URL (new SHA: `<short-sha>`)
 **Title refreshed:** yes | no
 **Body refreshed:** yes | no

package/dist/plugin/skills/do/per-comment-replies.md

@@ -29,7 +29,7 @@ For each comment id with a description, post the reply with the resolved provide
 
 - **`github`** — nested reply on the line comment, one per actionable comment, per [`../_shared/vcs/github/reply-line-comment.md`](../_shared/vcs/github/reply-line-comment.md).
 
-- **`gitlab`** — one threaded note per actionable discussion per [`../_shared/vcs/gitlab/reply-discussion.md`](../_shared/vcs/gitlab/reply-discussion.md) (the discussion id stands in for the comment id), then resolve each fully-addressed thread per [`../_shared/vcs/gitlab/resolve-discussion.md`](../_shared/vcs/gitlab/resolve-discussion.md). The loop-marked reply is the addressed signal; the resolve is GitLab's equivalent of a reviewer closing the thread, which the loop can do directly. Resolving folds the discussion out of the next tick's actionable set, so no separate resolve-reminder nudge is needed for it.
+- **`gitlab`** — one threaded note per actionable discussion per [`../_shared/vcs/gitlab/reply-discussion.md`](../_shared/vcs/gitlab/reply-discussion.md) (the discussion id stands in for the comment id). Reply only: **never resolve the discussion.** GitLab classifies by the same `<!-- muggle-do:bot -->` marker GitHub does ([`../_shared/vcs/gitlab/unresolved-discussions.md`](../_shared/vcs/gitlab/unresolved-discussions.md)), so the marked note alone folds it out of the next tick's actionable set — the resolve adds nothing the reply has not already done, and MRs that gate merging on "all threads resolved" would have the loop clearing its own merge gate.
 
 Reply body uses the template in [`../muggle-pr-followup/output-templates/inline-reply.md`](../muggle-pr-followup/output-templates/inline-reply.md):
 
@@ -57,7 +57,19 @@ Posted per [`../_shared/vcs/github/top-level-comment.md`](../_shared/vcs/github/
 - `gh api` returns an error for an individual reply → log to `followup.log`, continue with the remaining comments. Do not abort the whole step over one failure; the push has already happened and other replies still need posting.
 - All replies fail → surface the most-recent `gh` error to the user, but do not abort the overall `/muggle-do` invocation. The resolve-reminder stage still runs; the watcher still respawns. The next cycle on this PR will produce more replies and the missing ones can be picked up by the human reviewer.
 
+## Enforcement
+
+A Stop-hook guardrail (`guardrail-comment-reply-gate.sh`) holds the turn open when this session claimed a review thread and left it unanswered. It settles from signals this cycle already produces — the unresolved-thread fetch [`address-reviews.md`](address-reviews.md) Step 1 runs, which claims each thread, and the reply calls Step 2 makes — so running this step is what clears it; nothing extra is owed.
+
+Two properties worth knowing while writing replies:
+
+- **A comment is answered only when the provider confirms the reply.** A reply that fails leaves the obligation open, which is why the failure mode above says to log and continue rather than assume the thread is settled.
+- **One reply may answer several comments.** A thread carrying three consecutive questions is three obligations; a single reply that addresses all three settles all three, while a reply addressing only the newest leaves the other two open and named.
+
+A thread the round deferred to the user instead of answering (the ambiguous escalation in [`address-reviews.md`](address-reviews.md) Step 3) is cleared with `echo "MUGGLE_REPLY_SKIP: <comment-id> <reason>"`. The deferral is recorded durably against those comments, so it survives the session; naming no tracked comment degrades to a session-wide skip.
+
 ## Invariants
 
 - One reply per line comment (`gitlab`: per discussion). No per-review summary reply anywhere.
+- The loop never resolves a review thread, on either provider. A `PreToolUse` guardrail denies both calls.
 - Every reply body contains the new SHA's 7-char prefix (which push addressed it) and ends with the loop signature block — the `<!-- muggle-do:bot -->` marker, not the author login, is what identifies loop-authored comments.

package/dist/plugin/skills/do/pre-flight.md

@@ -32,7 +32,7 @@ Before asking anything, gather every fact you can resolve without the user:
 6. **Candidate Muggle Test projects.** Call `muggle-remote-project-list` and rank by semantic match against the task description and the repo's dev URL.
 7. **Existing test-user secrets.** For each candidate Muggle Test project, call `muggle-remote-secret-list` and note whether `managed_profile_email` / `managed_profile_password` exist.
 8. **Auth0 tenant in use for local dev.** Grep the repo's env file for `*AUTH0_DOMAIN*`; record the tenant. This tells the user whether the staging-tenant test user will work or not.
-9. **Branch hygiene signals** for the `autoUseWorktree` and `autoRebase` gates (see [`../_shared/use-worktrees.md`](../_shared/use-worktrees.md), [`../_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)):
+9. **Branch hygiene signals** for the `autoUseWorktree` and `autoRebase` gates (see [`../_shared/use-worktrees.md`](../_shared/use-worktrees.md), [`../_shared/sync-branch-with-base.md`](../_shared/sync-branch-with-base.md)):
    - Is the current checkout already a worktree? `git -C <repo> rev-parse --is-inside-work-tree` plus `git -C <repo> worktree list`.
    - How many commits behind `origin/<default>`? `git -C <repo> fetch origin && git -C <repo> rev-list --count "HEAD..origin/$(git -C <repo> symbolic-ref refs/remotes/origin/HEAD --short | sed 's|origin/||')"`.
 10. **`autoE2ETest` preference.** Read the session-context preferences line. Unset → treat as `always` (this gate's default — opposite of the system-wide `ask` default). `ask` → surface in Q13. `always` → no question; stage 6 runs.
@@ -56,7 +56,7 @@ Present **one `AskUserQuestion`** (or the platform's structured-selection equiva
 9. **PR target branch** — default: the repo's default branch. "Use default" / "Target a different branch".
 10. **Re-auth Muggle Test MCP?** — only if auth was missing/expired. "Log in now" / "Abort".
 11. **Worktree for this change?** — gate: [`autoUseWorktree`](../muggle-preferences/preference-gates/autoUseWorktree.md). Options: create a dedicated worktree (per [`../_shared/use-worktrees.md`](../_shared/use-worktrees.md)), or work in the current checkout.
-12. **Rebase onto `origin/<default>` first?** — gate: [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), only if `behind > 0`. Options: rebase before stage 6, or run as-is.
+12. **Sync onto the base branch first?** — gate: [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), only if `behind > 0`. The answer governs every sync this cycle, not just one: before the dev server / E2E, and again immediately before stage 7 pushes. Options: sync with the base, or run as-is.
 13. **Run E2E at the end of every cycle?** — gate: [`autoE2ETest`](../muggle-preferences/preference-gates/autoE2ETest.md), only if step 10's silent detection resolved to `ask`. Options: always run stage 6, or ask each cycle.
 
 If fewer than two of the above need the user, still gather them in a single turn — never open a second round.