@muggleai/works 5.7.0 → 5.8.0

package/plugin/scripts/guardrails.mjs

@@ -45,6 +45,8 @@ var GH_PR_MERGED_LINE = /\b(?:Merged|Squashed and merged|Rebased and merged) pul
 var GH_PR_CLOSED_LINE = /\bClosed pull request [\w./-]*#(\d+)/;
 var PR_MONITOR_TERMINAL_LINE = /\bTERMINAL pr=(\d+): (MERGED|CLOSED)\b/;
 var MAX_PR_TERMINAL_BLOCKS = 3;
+var MUGGLE_SKILL_EMIT_TOOL = /muggle-local-telemetry-skill-emit/i;
+var MUGGLE_TEST_SKILL_NAME = "muggle-test";
 
 // src/guardrails/prTerminal.ts
 function detectPrTerminal(input2) {
@@ -113,7 +115,8 @@ ${input2.tool_response?.stderr ?? ""}`;
   return !FAIL.test(out);
 }
 function isE2ERun(input2) {
-  return E2E_TOOL.test(input2.tool_name ?? "");
+  if (E2E_TOOL.test(input2.tool_name ?? "")) return true;
+  return MUGGLE_SKILL_EMIT_TOOL.test(input2.tool_name ?? "") && input2.tool_input?.skillName === MUGGLE_TEST_SKILL_NAME;
 }
 
 // src/guardrails/shouldRunE2E.ts
@@ -124,10 +127,10 @@ function shouldRunE2E(state) {
 function applyRecordedRun(state, run) {
   let next = state;
   if (run.unitTestPassed) {
-    next = { ...next, unitTestsGreen: true, e2eRun: false, e2eBlockCount: 0 };
+    next = { ...next, unitTestsGreen: true, e2eRun: false };
   }
   if (run.e2eRan) {
-    next = { ...next, e2eRun: true };
+    next = { ...next, e2eRun: true, e2eBlockCount: 0 };
   }
   if (run.e2eSkipped) {
     next = { ...next, e2eSkipped: true };

package/plugin/scripts/pr-watch-guards.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+# Self-termination guards for the muggle-pr-followup watch loop. Sourced by the
+# per-slot watch.sh that arm-watcher writes, and the single source of truth for
+# the two conditions that stop a watcher from leaking across sessions.
+#
+# A bare `while true` monitor leaks on Windows: the OS does not stop a detached
+# Git Bash loop when the Claude session that launched it ends, so orphaned
+# watchers accumulate and each keeps spawning gh calls forever. Two guards bound
+# that, and together with arm-watcher's pre-arm dedup keep at most one live
+# watcher per PR:
+#
+#   watcher_superseded    — <slot>/watch.pid holds the PID of the watcher that
+#                           owns the slot. A loop whose PID no longer matches has
+#                           been replaced by a newer arm and must exit.
+#   watcher_lifetime_exceeded — a loop exits after MUGGLE_PR_WATCH_MAX_LIFETIME
+#                           regardless, so an orphan nothing supersedes still dies
+#                           on its own; reconcile re-arms an open PR inside a live
+#                           session.
+
+MUGGLE_PR_WATCH_MAX_LIFETIME="${MUGGLE_PR_WATCH_MAX_LIFETIME:-21600}"
+MUGGLE_PR_WATCH_POLL_INTERVAL="${MUGGLE_PR_WATCH_POLL_INTERVAL:-60}"
+
+# True when watch.pid exists and names a PID other than this loop's — a newer arm
+# has taken ownership of the slot. Absent/empty watch.pid is not superseded: a
+# loop that has not yet claimed the slot keeps running.
+watcher_superseded() {
+    local slot="$1" mypid="$2" owner
+    [ -f "${slot}/watch.pid" ] || return 1
+    owner=$(cat "${slot}/watch.pid" 2>/dev/null)
+    [ -n "$owner" ] && [ "$owner" != "$mypid" ]
+}
+
+watcher_lifetime_exceeded() {
+    local started="$1" now="$2" max="${3:-$MUGGLE_PR_WATCH_MAX_LIFETIME}"
+    [ $((now - started)) -ge "$max" ]
+}
+
+# True when pid names a running process. `kill -0` sends no signal; EPERM means
+# the process exists but is foreign, which still counts as alive. Used by
+# arm-watcher's pre-arm dedup to decide whether a watcher already owns the slot.
+watcher_pid_alive() {
+    local pid="$1"
+    [ -n "$pid" ] || return 1
+    kill -0 "$pid" 2>/dev/null
+}

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

@@ -8,11 +8,11 @@ Append these two lines as the end of every loop-posted comment body:
 
 ```
 <!-- muggle-do:bot -->
-🤖 _Automated reply from muggle-do._
+🤖 _Posted by `/muggle-do` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_
 ```
 
-- `<!-- muggle-do:bot -->` — hidden HTML marker; GitHub renders it invisibly and humans never type it. This is the **detection token**.
-- The visible line makes the automation clear to a reader.
+- `<!-- muggle-do:bot -->` — hidden HTML marker; GitHub renders it invisibly and humans never type it. This is the **detection token**. It must stay exactly as written — echo-protection and addressed-by-loop classification read this literal string.
+- The visible line is the shared Muggle Works signature ([`../vcs/post-signature.md`](../vcs/post-signature.md)) with `/muggle-do` as the command. It links a reader back to the tool and names the command that posted the comment.
 
 ## Detection
 

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

@@ -1,9 +1,10 @@
 # VCS provider recipes
 
-Provider-agnostic seam for the watcher and dev-cycle skills. A caller resolves one provider token via [`detect-vcs.md`](detect-vcs.md) — `github` (`gh`) or `gitlab` (`glab`) — then loads the matching provider's recipe for each agnostic step. The two recipe sets mirror each other call-for-call; callers branch on the token, never fork procedure.
+Provider-agnostic seam for the watcher and dev-cycle skills. A caller resolves one provider token via [`detect-vcs.md`](detect-vcs.md) — `github` (`gh`) or `gitlab` (`glab`) — then loads the matching provider's recipe for each agnostic step. The two recipe sets mirror each other call-for-call; callers branch on the token, never fork procedure. Provider-agnostic entry points live once in `common/`, indexed by both TOCs: a **dispatcher** owns the `github`-vs-`gitlab` branch so a caller links it alone instead of naming both recipes side by side (`ci-rollup`, `branch-standing`, `push-to-branch`), and a recipe with no provider-specific procedure lives there too (`verify-working-tree`).
 
 ## Index
 
 - [`detect-vcs.md`](detect-vcs.md) — resolve `github` | `gitlab` from a URL argument or the origin remote.
 - [`github.md`](github.md) — `gh` / `git` recipe TOC; per-recipe files in [`github/`](github/).
 - [`gitlab.md`](gitlab.md) — `glab` / `git` recipe TOC; per-recipe files in [`gitlab/`](gitlab/).
+- `common/` — provider-agnostic entry points (`ci-rollup`, `branch-standing`, `push-to-branch`, `verify-working-tree`), indexed by both provider TOCs.

package/plugin/skills/_shared/vcs/common/branch-standing.md

@@ -0,0 +1,19 @@
+# Branch standing vs base (tool-agnostic)
+
+The single instruction the rebase trigger references for **conflict** and **out-of-date** detection — sites link here and never name a provider's metadata recipe inline. Both signals read from the metadata snapshot the caller already fetched; this file only says which field each provider reads.
+
+Resolve the provider per [`../detect-vcs.md`](../detect-vcs.md).
+
+## Conflict with the base
+
+- `github` → `mergeable == CONFLICTING`, corroborated by `mergeStateStatus == DIRTY` ([`../github/pr-metadata.md`](../github/pr-metadata.md)).
+- `gitlab` → `detailed_merge_status` in `{broken_status, conflict}` ([`../gitlab/mr-metadata.md`](../gitlab/mr-metadata.md)).
+
+A still-computing state — `github`'s `mergeable == UNKNOWN`, `gitlab`'s `checking` / `unchecked` — counts as **not conflicting** this tick.
+
+## Out of date (behind the base)
+
+Read from **commit ancestry**, never from the merge-state field: GitHub masks `BEHIND` behind `DIRTY` / `BLOCKED`, and GitLab reports `need_rebase` only under fast-forward-merge — both hide a stale branch. The compare is exact even while the conflict state is still computing.
+
+- `github` → the compare call in [`../github/pr-metadata.md`](../github/pr-metadata.md#behind-by-out-of-date-detection); `behind_by > 0` ⇒ out of date.
+- `gitlab` → the compare call in [`../gitlab/mr-metadata.md`](../gitlab/mr-metadata.md#behind-by-out-of-date-detection); any base commit the head lacks ⇒ out of date.

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.