@muggleai/works 5.6.0 → 5.8.0

package/plugin/skills/_shared/vcs/common/ci-rollup.md

@@ -0,0 +1,16 @@
+# CI rollup (tool-agnostic)
+
+The single instruction every CI-poll site references — sites link here and never name a provider's rollup recipe inline. Fetch the CI state for a PR/MR head and fold it into one of three buckets: **red**, **pending**, **green**.
+
+Resolve the provider per [`../detect-vcs.md`](../detect-vcs.md), then run its rollup recipe — the recipe owns the fetch command and the raw per-check/per-job states:
+
+- `github` → [`../github/pr-checks.md`](../github/pr-checks.md) — the check-run rollup for the head SHA.
+- `gitlab` → [`../gitlab/mr-pipeline.md`](../gitlab/mr-pipeline.md) — the pipeline-job rollup for the head.
+
+Both recipes fold into the same buckets, so a caller branches on the token only to fetch, then reasons on the bucket alone:
+
+- **red** — one or more entries in the `fail` bucket (a failed check-run; a `failed` job). Candidate for fix-ci; the dispatch carries the failing names.
+- **pending** — nothing failed but an entry has not settled (`pending` bucket; a `running` / `pending` / `created` job). The result may yet go green.
+- **green** — every entry passed, was skipped, or was cancelled, or there are none at all.
+
+The rollup is **non-monotonic** — it flips red↔green and resets on every push. A caller that records a red result keys it on the **head SHA**, not a monotonic id, so the record re-arms on the next push.

package/plugin/skills/_shared/vcs/common/push-to-branch.md

@@ -0,0 +1,16 @@
+# Push to branch (tool-agnostic)
+
+The single instruction every commit/push site references — sites link here and never embed provider commands inline.
+
+## Signing gate — never push unsigned commits
+
+Resolve the provider per [`../detect-vcs.md`](../detect-vcs.md), then run its signed-commits recipe — the recipe owns the preflight and the actual commands:
+
+- `github` → [`../github/signed-commits.md`](../github/signed-commits.md) — local signing working: commit and push normally; broken: create the commits server-signed (`createCommitOnBranch`) and skip the push (the remote already has them). Rebase/force-push follows the same recipe's replay path.
+- `gitlab` → [`../gitlab/signed-commits.md`](../gitlab/signed-commits.md) — local signing working: commit and push normally; broken: stop and escalate (no server-side signing).
+
+Never disable signing to make a push go through.
+
+## After the push
+
+Capture the new head SHA — from the local branch, or from the mutation response on the server-signed path — and append it to `last_seen.pushed_shas[]` so resolve-reminder can recognize it.

package/{dist/plugin/skills/_shared/vcs/github → plugin/skills/_shared/vcs/common}/verify-working-tree.md

@@ -8,10 +8,10 @@ git remote get-url origin            # remote matches <owner>/<repo>
 git rev-parse --abbrev-ref HEAD      # current branch matches PR's headRefName
 ```
 
-Accept any remote URL form for `<owner>/<repo>` (with or without trailing `.git`):
+Accept any remote URL form for `<owner>/<repo>`, with or without trailing `.git`, where `<host>` is the provider host (`github.com`, or the GitLab instance host):
 
-- `https://github.com/<owner>/<repo>`
-- `git@github.com:<owner>/<repo>`
-- `ssh://git@github.com/<owner>/<repo>`
+- `https://<host>/<owner>/<repo>`
+- `git@<host>:<owner>/<repo>`
+- `ssh://git@<host>/<owner>/<repo>`
 
 Any mismatch → abort; the calling skill reports the wrong checkout to the user with its own message.

package/plugin/skills/_shared/vcs/github/pr-edit.md

@@ -6,3 +6,5 @@ For `open-prs/update.md` when E2E state flips (passing↔failing) or validation
 gh pr edit <pr-number> --repo <owner>/<repo> --title "<new-title>"
 gh pr edit <pr-number> --repo <owner>/<repo> --body-file <file>
 ```
+
+The `<file>` body must end with the Muggle Works signature. Because the description is re-posted on each refresh, strip the old signature (from the `<!-- muggle-works:signature -->` marker to the end) before re-appending it — see [`../post-signature.md`](../post-signature.md).

package/plugin/skills/_shared/vcs/github/reply-line-comment.md

@@ -8,3 +8,5 @@ gh api --method POST \
   repos/<owner>/<repo>/pulls/<n>/comments/<comment-id>/replies \
   -f body="<reply-text>"
 ```
+
+The `<reply-text>` must end with the loop signature block — the `<!-- muggle-do:bot -->` detection marker above the Muggle Works line. See [`../post-signature.md`](../post-signature.md).

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.