@muggleai/works 5.7.0 → 5.8.1

package/plugin/skills/_shared/vcs/github/signed-commits.md

@@ -0,0 +1,28 @@
+# Signed commits without local signing
+
+**Never push unsigned commits.** When the machine has no working signing setup, do not fall back to unsigned `git commit` + `git push` — create the commits **remotely** with GraphQL `createCommitOnBranch`, which GitHub signs server-side. And never "fix" a signing failure by disabling it: no `--no-gpg-sign`, no `-c commit.gpgsign=false` — a broken signing setup is fixed or routed around via the remote path, not turned off.
+
+## Preflight
+
+```bash
+git -C <repo-path> log --format='%G?' origin/<branch>..HEAD   # unpushed branch: <base>..HEAD
+```
+
+Any `N` (no signature) among the commits about to leave the machine → the push is blocked; use the remote path below. `G`/`E`/`U` are signed commits (locally unverifiable is fine — GitHub-signed commits show `E` without GitHub's key in the local keyring). Signing configured and working → commit and push normally.
+
+## Remote signed commit
+
+1. The branch must exist on the remote; create it at the base if absent: `gh api repos/<owner>/<repo>/git/refs -f ref=refs/heads/<branch> -f sha=<base-sha>`.
+2. Stage the change (`git add <files>`), then take each file's canonical bytes from the **index** — `git cat-file blob :<path>` — and base64 them. Index blobs, never working-copy reads: the index holds git's normalized content (line endings, filters), so the remote tree matches what a local commit would have produced.
+3. One `createCommitOnBranch` mutation per commit: `branch {repositoryNameWithOwner, branchName}`, `message {headline, body}`, `expectedHeadOid` = the branch's current remote head (a concurrency lease — a concurrent push 409s instead of being clobbered), `fileChanges.additions` (path + base64 contents; removals via `fileChanges.deletions`).
+4. Sync the local branch to the result: `git fetch origin <branch>`, verify `git diff --cached origin/<branch>` is **empty** (remote tree identical to what was staged), then `git reset --hard origin/<branch>`. A non-empty diff means the payload missed a file — fix and re-commit; never leave local and remote diverged.
+
+## Rebase / force-push
+
+A local rebase mints new local commits — unsigned on this machine — so the `--force-with-lease` path is equally blocked. Replay instead:
+
+1. Create a temp ref at the new base tip.
+2. Re-create each branch commit on it via `createCommitOnBranch` (same per-commit file snapshots from `git cat-file blob <commit>:<path>`; conflicted files carry the resolved content).
+3. Move the branch ref with a lease: verify the branch's current remote head is still the expected pre-rebase SHA, then `gh api -X PATCH repos/<owner>/<repo>/git/refs/heads/<branch> -f sha=<new-head> -F force=true`. Delete the temp ref.
+
+The replayed commits are GitHub-signed; the guarded ref move is the only force operation.

package/plugin/skills/_shared/vcs/github/top-level-comment.md

@@ -5,3 +5,5 @@ For the resolve-reminder stage and any non-threaded notice.
 ```bash
 gh pr comment <pr-number> --repo <owner>/<repo> --body "<text>"
 ```
+
+The `<text>` you post must end with the Muggle Works signature — see [`../post-signature.md`](../post-signature.md).

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

@@ -1,39 +1,39 @@
-# Unresolved comment threads
-
-For the watcher's dispatch trigger and the resolve-reminder stage. GraphQL only — REST does not expose `isResolved`/`isOutdated`.
-
-```bash
-gh api graphql -F owner=<owner> -F name=<repo> -F number=<n> -f query='
-query($owner: String!, $name: String!, $number: Int!) {
-  repository(owner: $owner, name: $name) {
-    pullRequest(number: $number) {
-      reviewThreads(first: 100) {
-        nodes {
-          id
-          isResolved
-          isOutdated
-          comments(first: 100) {
-            nodes {
-              databaseId
-              pullRequestReview { databaseId }
-              author { login }
-              body
-              createdAt
-            }
-          }
-        }
-      }
-    }
-  }
-}'
-```
-
-Filter client-side to `isResolved == false`. Walk each thread's comments in `createdAt` order and classify by the loop marker (see [`../../pr-followup-helpers/loop-signature.md`](../../pr-followup-helpers/loop-signature.md)), not by `author.login` — the login is ambiguous under a shared account:
-
-- **Addressed, awaiting resolve** — the **newest** comment carries the loop marker `<!-- muggle-do:bot -->`. The loop has replied and nothing newer is waiting. → resolve-reminder.
-- **Unaddressed human comment** — the newest comment lacks the marker and is newer than the thread's newest loop-marked comment (or the thread has no loop comment yet). → actionable: the round should address it. The **watcher's dispatch trigger** additionally requires `isOutdated == false` — a thread whose anchored line has since changed is skipped, since re-surfacing a stale anchor risks answering a concern the change already mooted. The resolve-reminder stage ignores `isOutdated`.
-- **Not addressed** — indeterminate (e.g. no comments).
-
-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.
+# Unresolved comment threads
+
+For the watcher's dispatch trigger and the resolve-reminder stage. GraphQL only — REST does not expose `isResolved`/`isOutdated`.
+
+```bash
+gh api graphql -F owner=<owner> -F name=<repo> -F number=<n> -f query='
+query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: 100) {
+        nodes {
+          id
+          isResolved
+          isOutdated
+          comments(first: 100) {
+            nodes {
+              databaseId
+              pullRequestReview { databaseId }
+              author { login }
+              body
+              createdAt
+            }
+          }
+        }
+      }
+    }
+  }
+}'
+```
+
+Filter client-side to `isResolved == false`. Walk each thread's comments in `createdAt` order and classify by the loop marker (see [`../../pr-followup-helpers/loop-signature.md`](../../pr-followup-helpers/loop-signature.md)), not by `author.login` — the login is ambiguous under a shared account:
+
+- **Addressed, awaiting resolve** — the **newest** comment carries the loop marker `<!-- muggle-do:bot -->`. The loop has replied and nothing newer is waiting. → resolve-reminder.
+- **Unaddressed human comment** — the newest comment lacks the marker and is newer than the thread's newest loop-marked comment (or the thread has no loop comment yet). → actionable: the round should address it. This holds **regardless of `isOutdated`** — a thread whose anchored line has since moved (a rebase or a later push) still carries its unanswered question, and skipping it leaves that question unanswered for good. Whether the moved code already mooted the concern is a judgment for the round to make and reply to, not a reason to skip; the marker rule then stops re-dispatch on the next poll. Both the watcher's dispatch trigger and the resolve-reminder stage ignore `isOutdated`.
+- **Not addressed** — indeterminate (e.g. no comments).
+
+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.

package/plugin/skills/_shared/vcs/github.md

@@ -11,11 +11,14 @@ Skills assume a working `gh auth status`. Auth errors surface verbatim from `gh`
 | [`pr-metadata`](github/pr-metadata.md) | Snapshot PR state, head SHA, branch, conflict + `behind_by` out-of-date detection — watcher + bootstrap. |
 | [`submitted-reviews`](github/submitted-reviews.md) | Fetch a review by id / watcher's body-only-review check. |
 | [`pr-checks`](github/pr-checks.md) | Check-run rollup for the head SHA — watcher's CI poll. |
+| [`ci-rollup`](common/ci-rollup.md) | Tool-agnostic CI poll — dispatches to `pr-checks` / `mr-pipeline`, folds into red/pending/green. |
+| [`branch-standing`](common/branch-standing.md) | Tool-agnostic conflict + out-of-date detection — dispatches to `pr-metadata` / `mr-metadata`. |
 | [`line-comments-for-review`](github/line-comments-for-review.md) | Pull a review's line comments — `/muggle-do` per-comment routing. |
 | [`unresolved-threads`](github/unresolved-threads.md) | GraphQL unresolved-thread state — watcher's dispatch trigger + resolve-reminder. |
 | [`reply-line-comment`](github/reply-line-comment.md) | POST a threaded reply on a line comment. |
 | [`top-level-comment`](github/top-level-comment.md) | POST a top-level PR comment — resolve-reminder + overflow. |
-| [`push-to-branch`](github/push-to-branch.md) | Push + capture new SHA after address-reviews work. |
-| [`verify-working-tree`](github/verify-working-tree.md) | Three checks bootstrap runs before seeding state. |
+| [`push-to-branch`](common/push-to-branch.md) | Signing-gated push + capture new SHA after address-reviews work. |
+| [`signed-commits`](github/signed-commits.md) | Never-push-unsigned rule: `%G?` preflight, server-signed commits via `createCommitOnBranch`, rebase replay. |
+| [`verify-working-tree`](common/verify-working-tree.md) | Three checks bootstrap runs before seeding state. |
 | [`pr-edit`](github/pr-edit.md) | Refresh title or body when address-reviews mode flips state. |
 | [`loop-user-identity`](github/loop-user-identity.md) | Resolve the GitHub login of the loop user. |

package/plugin/skills/_shared/vcs/gitlab/loop-user-identity.md

@@ -3,7 +3,7 @@
 The GitLab identity that owns the authenticated `glab` token. Resolve-reminder thread classification and reply attribution need this.
 
 ```bash
-glab api user --jq '.username'
+glab api user | jq -r '.username'
 ```
 
 Cache in `state.md` under `Loop user:`; re-resolve only when missing.

package/plugin/skills/_shared/vcs/gitlab/mr-create.md

@@ -1,6 +1,6 @@
 # Open a merge request
 
-For `open-prs`. Push the branch first (see [`../github/push-to-branch.md`](../github/push-to-branch.md)), then open the MR.
+For `open-prs`. Push the branch first (see [`../common/push-to-branch.md`](../common/push-to-branch.md)), then open the MR.
 
 ```bash
 glab mr create -R <group>/<project> \

package/plugin/skills/_shared/vcs/gitlab/mr-discussions.md

@@ -3,7 +3,7 @@
 Incoming feedback for the watcher's poll and the address-reviews fetch. GitLab has **no review envelope** — there is no submitted-review object grouping a summary body with line comments. Feedback arrives as individual notes, each belonging to a discussion (a thread). This recipe is the `submitted-reviews` analogue.
 
 ```bash
-glab api projects/:id/merge_requests/:iid/discussions --paginate
+glab api projects/:id/merge_requests/<iid>/discussions --paginate
 ```
 
 Each discussion has `id` and a `notes[]` array; each note has `id`, `author.username`, `body`, `created_at`, `system` (a `true` flag marks GitLab's own activity entries — skip them).

package/plugin/skills/_shared/vcs/gitlab/mr-metadata.md

@@ -16,7 +16,7 @@ glab mr view <iid> -R <group>/<project> -F json
 `detailed_merge_status == "need_rebase"` reports a behind branch only when the project enforces "fast-forward merge"; otherwise it stays `mergeable` while behind. Detect out-of-date straight from commit ancestry instead — independent of merge-method config:
 
 ```bash
-glab api projects/:id/repository/compare?from=<target_branch>&to=<head_sha> --jq '.commits | length'
+glab api "projects/:id/repository/compare?from=<head_sha>&to=<target_branch>" | jq '.commits | length'
 ```
 
-GitLab's compare lists only the commits `to` is ahead by, so flip the direction: compare `from=<head_sha>&to=<target_branch>` and a non-empty `.commits` ⇒ the base has commits the head lacks ⇒ out of date. Empty ⇒ current with base.
+Compare lists the commits reachable from `to` but not `from`, so `from=<head_sha>&to=<target_branch>` yields exactly the base commits the head lacks — non-zero ⇒ out of date; zero ⇒ current with base.

package/plugin/skills/_shared/vcs/gitlab/mr-pipeline.md

@@ -9,7 +9,7 @@ glab ci status -R <group>/<project> -b <source_branch>
 Or straight from the API for the latest pipeline and its jobs:
 
 ```bash
-glab api projects/:id/merge_requests/:iid/pipelines --jq '.[0].id'
+glab api projects/:id/merge_requests/<iid>/pipelines | jq -r '.[0].id'
 glab api projects/:id/pipelines/<pipeline-id>/jobs --paginate
 ```
 

package/plugin/skills/_shared/vcs/gitlab/reply-discussion.md

@@ -4,6 +4,6 @@ Used by `/muggle-do` per-comment inline replies. A threaded reply is a new note
 
 ```bash
 glab api --method POST \
-  projects/:id/merge_requests/:iid/discussions/<discussion-id>/notes \
+  projects/:id/merge_requests/<iid>/discussions/<discussion-id>/notes \
   -f body="<reply-text>"
 ```

package/plugin/skills/_shared/vcs/gitlab/resolve-discussion.md

@@ -4,7 +4,7 @@ Mark a thread resolved once the loop's reply has addressed it — the resolve-re
 
 ```bash
 glab api --method PUT \
-  "projects/:id/merge_requests/:iid/discussions/<discussion-id>?resolved=true"
+  "projects/:id/merge_requests/<iid>/discussions/<discussion-id>?resolved=true"
 ```
 
 Resolves every resolvable note in the thread at once. Only resolvable (diff/line) threads accept this; a non-resolvable discussion returns an error.

package/plugin/skills/_shared/vcs/gitlab/signed-commits.md

@@ -0,0 +1,15 @@
+# Signed commits without local signing
+
+**Never push unsigned commits.** GitLab has no server-side signing analogue — commits created through its commits API are unsigned, so a broken local signing setup has no remote route around it. And never "fix" a signing failure by disabling it: no `--no-gpg-sign`, no `-c commit.gpgsign=false`.
+
+## Preflight
+
+```bash
+git -C <repo-path> log --format='%G?' origin/<branch>..HEAD   # unpushed branch: <base>..HEAD
+```
+
+Any `N` (no signature) among the commits about to leave the machine → the push is blocked. `G`/`E`/`U` are signed commits (locally unverifiable is fine). Signing configured and working → commit and push normally.
+
+## Blocked
+
+Unsigned commits bound for an MR branch → stop and escalate to the owner to configure local signing. A local rebase mints new unsigned commits, so the force-push path is equally blocked. Never push unsigned.

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

@@ -3,8 +3,8 @@
 For the watcher's dispatch trigger and the resolve-reminder stage. REST exposes resolution directly — no GraphQL needed, unlike GitHub.
 
 ```bash
-glab api projects/:id/merge_requests/:iid/discussions --paginate \
-  --jq '[.[] | select(.notes[0].resolvable == true) | select(any(.notes[]; .resolved == false))]'
+glab api projects/:id/merge_requests/<iid>/discussions --paginate \
+  | jq '[.[] | select(.notes[0].resolvable == true) | select(any(.notes[]; .resolved == false))]'
 ```
 
 A discussion is resolvable when its notes carry `resolvable == true` (diff/line threads are; the MR description and system notes are not). A thread is **unresolved** when any of its notes has `resolved == false`.

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

@@ -4,7 +4,7 @@ Reusable `glab` / `git` snippets used by `muggle-pr-followup` (watcher + bootstr
 
 Skills assume a working `glab auth status`. Auth errors surface verbatim from `glab`.
 
-The project ref `:id` is `<group>/<project>` — URL-encode it for `glab api` (`mygroup/myproj` → `mygroup%2Fmyproj`). `:iid` is the MR's per-project internal id (the `!123` number), not the global id.
+`glab api` fills `:id` itself with the URL-encoded path of the current directory's project — run recipes from the MR worktree and leave `:id` as written (elsewhere, substitute the encoded path yourself: `mygroup/myproj` → `mygroup%2Fmyproj`). `<iid>` is the MR's per-project internal id (the `!123` number), not the global id; glab has no placeholder for it — substitute it. `glab api` has no `--jq` flag — pipe to `jq`.
 
 ## Index
 
@@ -12,6 +12,8 @@ The project ref `:id` is `<group>/<project>` — URL-encode it for `glab api` (`
 | :----- | :------- |
 | [`mr-metadata`](gitlab/mr-metadata.md) | Snapshot MR state, head SHA, branch, conflict + out-of-date detection — watcher + bootstrap. |
 | [`mr-pipeline`](gitlab/mr-pipeline.md) | Pipeline-job rollup for the head SHA — watcher's CI poll. |
+| [`ci-rollup`](common/ci-rollup.md) | Tool-agnostic CI poll — dispatches to `pr-checks` / `mr-pipeline`, folds into red/pending/green. |
+| [`branch-standing`](common/branch-standing.md) | Tool-agnostic conflict + out-of-date detection — dispatches to `pr-metadata` / `mr-metadata`. |
 | [`mr-discussions`](gitlab/mr-discussions.md) | Fetch incoming notes/discussions — watcher's feedback poll. |
 | [`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. |
@@ -20,5 +22,6 @@ The project ref `:id` is `<group>/<project>` — URL-encode it for `glab api` (`
 | [`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. |
-| [`push-to-branch`](github/push-to-branch.md) | Push + capture new SHA after address-reviews work (provider-agnostic). |
-| [`verify-working-tree`](github/verify-working-tree.md) | Three checks bootstrap runs before seeding state (provider-agnostic). |
+| [`push-to-branch`](common/push-to-branch.md) | Signing-gated push + capture new SHA after address-reviews work. |
+| [`signed-commits`](gitlab/signed-commits.md) | Never-push-unsigned rule: `%G?` preflight; no server-side signing analogue → stop and escalate. |
+| [`verify-working-tree`](common/verify-working-tree.md) | Three checks bootstrap runs before seeding state. |

package/plugin/skills/_shared/vcs/post-signature.md

@@ -0,0 +1,31 @@
+# PR post signature
+
+Every pull-request / merge-request body, comment, and review-thread reply that muggle works posts ends with a signature line. Under a single-account workflow the automation posts as the repo owner, so the signature is what tells a reader — and a reviewer — that the post came from Muggle Works and which command produced it.
+
+## The line
+
+Append this as the last line of the posted body:
+
+```
+🤖 _Posted by `<command>` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_
+```
+
+`<command>` is the slash-command of the skill whose `gh` / `glab` call posts the body:
+
+- `/muggle-do` — PR/MR descriptions, per-comment thread replies, top-level reference replies, and resolve-reminders.
+- `/muggle-pr-visual-walkthrough` — a walkthrough comment the walkthrough skill posts itself (Mode A).
+
+Name the command that owns the post, not the one that generated the content. When the walkthrough hands its rendered block back for embedding (Mode B/C), the caller owns the post, so the caller's command is what the signature names.
+
+## Editable bodies (PR / MR description)
+
+A description is re-posted whenever state changes, so its signature must not stack. Precede the line with a hidden marker and treat the pair as one unit:
+
+```
+<!-- muggle-works:signature -->
+🤖 _Posted by `/muggle-do` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_
+```
+
+Before writing an edited body, delete everything from the `<!-- muggle-works:signature -->` marker to the end of the body, then append the block fresh. This keeps exactly one signature no matter how many times the description is refreshed.
+
+A comment or reply is posted once and never edited, so it needs no dedup marker — append the line alone. A loop-authored reply already carries the `<!-- muggle-do:bot -->` detection marker (defined in loop-signature.md) directly above this line; that marker stays, and this line replaces the old visible text.

package/plugin/skills/do/build.md

@@ -1,56 +1,58 @@
-# Build Agent (Stage 3)
-
-Implement the code change for this dev cycle. Read the frozen requirements from stage 2, produce the edits in each affected repo's worktree, and commit.
-
-## Turn preamble
-
-```
-**Stage 3 — Build** — implementing the change per the frozen requirements.
-```
-
-## Inputs
-
-- `requirements.md` from stage 2: goal, acceptance criteria, affected repos.
-- `state.md` from pre-flight: worktree path per repo, target branch, anything else the build needs to know about the environment.
-
-## Your job
-
-For each affected repo:
-
-1. **Re-read `requirements.md`.** Treat goal + AC as frozen. If something is unclear at this stage, that's a pre-flight bug — escalate, do not improvise.
-2. **Apply the change** in the repo's worktree. Edit existing files first; create new files only when the requirements demand it. Match the surrounding code's style, naming, and file layout.
-3. **Don't add what wasn't asked for.** No speculative abstractions, no extra logging, no "while I'm here" refactors. Three similar lines is better than a premature abstraction.
-4. **Cover new logic with tests.** If you added or changed non-trivial logic (a hook, reducer, parser, state machine, branching util), write its unit tests now — Stage 5 only *runs* the suite, it never authors tests. Untested new logic is a Definition-of-Done failure, not a Stage-5 gap.
-5. **Commit** with a conventional-commit subject:
-   - `feat(<scope>): <short>` for new behavior
-   - `fix(<scope>): <short>` for bug fixes
-   - `refactor(<scope>): <short>` for reshape
-   - `docs(...)`, `chore(...)`, `test(...)` as appropriate
-
-   The body explains *why* when the why is non-obvious. The diff already says *what*.
-
-## Delegation
-
-For a non-trivial change — multiple files, real design surface, or anything you would otherwise brainstorm before coding — run the implementation through superpowers' design → plan → subagent-driven build, then return to this stage's Output. That is a runtime hand-off (an action), not a doc dependency; do not encode superpowers' internals here. Routing a build request into this pipeline (the `autoRouteBuildToMuggleDo` front-door guardrail) exists to combine superpowers' design rigor with this pipeline's impact analysis, E2E, PR, and watcher — neither delivers both alone.
-
-## Output
-
-Per repo:
-
-**Repo:** name
-- Files edited / created: list
-- Commit subject: `<conventional commit>`
-- Notable choices: anything that needed a judgment call (briefly)
-
-**Overall:** READY for impact analysis | BLOCKED — reason
-
-If a requirement is fundamentally unimplementable as written, halt and escalate with the specific blocker — do not ship a half-finished implementation.
-
-## Re-entry from the address-reviews flow
-
-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 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.
-- 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.
+# Build Agent (Stage 3)
+
+Implement the code change for this dev cycle. Read the frozen requirements from stage 2, produce the edits in each affected repo's worktree, and commit.
+
+## Turn preamble
+
+```
+**Stage 3 — Build** — implementing the change per the frozen requirements.
+```
+
+## Inputs
+
+- `requirements.md` from stage 2: goal, acceptance criteria, affected repos.
+- `state.md` from pre-flight: worktree path per repo, target branch, anything else the build needs to know about the environment.
+
+## Your job
+
+For each affected repo:
+
+1. **Re-read `requirements.md`.** Treat goal + AC as frozen. If something is unclear at this stage, that's a pre-flight bug — escalate, do not improvise.
+2. **Apply the change** in the repo's worktree. Edit existing files first; create new files only when the requirements demand it. Match the surrounding code's style, naming, and file layout.
+3. **Don't add what wasn't asked for.** No speculative abstractions, no extra logging, no "while I'm here" refactors. Three similar lines is better than a premature abstraction.
+4. **Cover new logic with tests.** If you added or changed non-trivial logic (a hook, reducer, parser, state machine, branching util), write its unit tests now — Stage 5 only *runs* the suite, it never authors tests. Untested new logic is a Definition-of-Done failure, not a Stage-5 gap.
+5. **Commit** with a conventional-commit subject:
+   - `feat(<scope>): <short>` for new behavior
+   - `fix(<scope>): <short>` for bug fixes
+   - `refactor(<scope>): <short>` for reshape
+   - `docs(...)`, `chore(...)`, `test(...)` as appropriate
+
+   The body explains *why* when the why is non-obvious. The diff already says *what*.
+
+   **Signing:** never an unsigned commit. Commit through the signing gate in [`../_shared/vcs/common/push-to-branch.md`](../_shared/vcs/common/push-to-branch.md) — it routes a broken local signing setup to the provider's signed-commits recipe. Never `--no-gpg-sign` or disable signing to work around the failure.
+
+## Delegation
+
+For a non-trivial change — multiple files, real design surface, or anything you would otherwise brainstorm before coding — run the implementation through superpowers' design → plan → subagent-driven build, then return to this stage's Output. That is a runtime hand-off (an action), not a doc dependency; do not encode superpowers' internals here. Routing a build request into this pipeline (the `autoRouteBuildToMuggleDo` front-door guardrail) exists to combine superpowers' design rigor with this pipeline's impact analysis, E2E, PR, and watcher — neither delivers both alone.
+
+## Output
+
+Per repo:
+
+**Repo:** name
+- Files edited / created: list
+- Commit subject: `<conventional commit>`
+- Notable choices: anything that needed a judgment call (briefly)
+
+**Overall:** READY for impact analysis | BLOCKED — reason
+
+If a requirement is fundamentally unimplementable as written, halt and escalate with the specific blocker — do not ship a half-finished implementation.
+
+## Re-entry from the address-reviews flow
+
+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 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.
+- 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

@@ -1,84 +1,85 @@
-# 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.
-
-## 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>`.
-   - **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.
-
-4. **Create:** resolve the provider per [`../../_shared/vcs/detect-vcs.md`](../../_shared/vcs/detect-vcs.md).
-   - `github` → `gh pr create --title "..." --body "..." --head <branch>`. 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). 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-ai/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-ai/muggle-do/sessions/<slug>/last_seen.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#last_seenjson) — empty-watermark shape with `pushed_shas: []`. Forward mode never has prior reviews to skip, so `lastBodyReviewId: 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`. Triggered when the watcher's terminal tick observes the merge and dispatches `/muggle-do`'s cleanup directive ([`../cleanup.md`](../cleanup.md)) — 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.`
-
-Regardless of the gate, also append: `Once it's merged or closed, I'll move to the next plan item — or ask where to go next if there's no plan.`
+# 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.
+
+## 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:** 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).
+
+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>`.
+   - **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** — end the body with the Muggle Works signature, editable-body form (the `<!-- muggle-works:signature -->` marker + line, command `/muggle-do`) per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). It is the last thing in the body, after the walkthrough block.
+
+4. **Create:** resolve the provider per [`../../_shared/vcs/detect-vcs.md`](../../_shared/vcs/detect-vcs.md).
+   - `github` → `gh pr create --title "..." --body "..." --head <branch>`. 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`.
+
+## 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-ai/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-ai/muggle-do/sessions/<slug>/last_seen.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#last_seenjson) — empty-watermark shape with `pushed_shas: []`. Forward mode never has prior reviews to skip, so `lastBodyReviewId: 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`. Triggered when the watcher's terminal tick observes the merge and dispatches `/muggle-do`'s cleanup directive ([`../cleanup.md`](../cleanup.md)) — 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.`
+
+Regardless of the gate, also append: `Once it's merged or closed, I'll move to the next plan item — or ask where to go next if there's no plan.`