@muggleai/works 5.7.0 → 5.8.0

package/dist/plugin/scripts/guard-run.mjs

@@ -0,0 +1,327 @@
+import { spawn, spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+import { extname, join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// src/guard-run/cli.ts
+
+// src/guard-run/buildLaunchPlan.ts
+function quoteWindowsArgument(argument) {
+  if (argument !== "" && !/[ \t"]/.test(argument)) return argument;
+  let quoted = '"';
+  let backslashCount = 0;
+  for (const character of argument) {
+    if (character === "\\") {
+      backslashCount += 1;
+      continue;
+    }
+    if (character === '"') {
+      quoted += "\\".repeat(backslashCount * 2 + 1) + '"';
+      backslashCount = 0;
+      continue;
+    }
+    quoted += "\\".repeat(backslashCount) + character;
+    backslashCount = 0;
+  }
+  return quoted + "\\".repeat(backslashCount * 2) + '"';
+}
+function buildWindowsCommandLine(command) {
+  return command.map(quoteWindowsArgument).join(" ");
+}
+function buildWindowsJobObjectPlan(input) {
+  const bareCommandLine = buildWindowsCommandLine(input.options.command);
+  const commandLine = input.commandNeedsCmdShell ? `cmd.exe /d /s /c "${bareCommandLine}"` : bareCommandLine;
+  return {
+    executable: "powershell.exe",
+    args: [
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-File",
+      input.jobObjectShimPath,
+      String(input.options.activeProcessLimit),
+      input.options.isServiceMode ? "persist" : "kill",
+      String(input.launcherPid),
+      // Base64 survives the node→powershell→CreateProcessW arg relays that
+      // would otherwise re-interpret quotes.
+      Buffer.from(commandLine, "utf8").toString("base64")
+    ],
+    spawnDetached: false,
+    killsProcessGroupOnExit: false,
+    stopsScopeUnitOnExit: null
+  };
+}
+function buildLinuxSystemdScopePlan(args) {
+  return {
+    // pids.max (cgroup v2): the excess fork fails with EAGAIN in the kernel.
+    executable: "systemd-run",
+    args: [
+      "--user",
+      "--scope",
+      "--quiet",
+      "--collect",
+      `--unit=${args.scopeUnitName}`,
+      "-p",
+      `TasksMax=${args.options.activeProcessLimit}`,
+      "--",
+      ...args.options.command
+    ],
+    spawnDetached: false,
+    killsProcessGroupOnExit: false,
+    // Catchable launcher death stops the scope; after an untrappable SIGKILL
+    // the scope lives on but stays TasksMax-bounded, so the cap always holds.
+    stopsScopeUnitOnExit: args.options.isServiceMode ? null : args.scopeUnitName
+  };
+}
+function buildLinuxPrlimitProcessGroupPlan(args) {
+  return {
+    executable: "prlimit",
+    args: [`--nproc=${args.nprocCeiling}`, "--", ...args.options.command],
+    spawnDetached: true,
+    killsProcessGroupOnExit: !args.options.isServiceMode,
+    stopsScopeUnitOnExit: null
+  };
+}
+function buildDarwinUlimitProcessGroupPlan(args) {
+  return {
+    executable: "/bin/sh",
+    args: ["-c", `ulimit -u ${args.nprocCeiling}; exec "$@"`, "guard-run", ...args.options.command],
+    spawnDetached: true,
+    killsProcessGroupOnExit: !args.options.isServiceMode,
+    stopsScopeUnitOnExit: null
+  };
+}
+function buildBackendLaunchPlan(args) {
+  if (args.backend === "windows-job-object" /* WindowsJobObject */) {
+    return buildWindowsJobObjectPlan({
+      options: args.options,
+      jobObjectShimPath: args.jobObjectShimPath ?? "",
+      launcherPid: args.launcherPid ?? 0,
+      commandNeedsCmdShell: args.commandNeedsCmdShell ?? false
+    });
+  }
+  if (args.backend === "linux-systemd-scope" /* LinuxSystemdScope */) {
+    return buildLinuxSystemdScopePlan({
+      options: args.options,
+      scopeUnitName: args.scopeUnitName ?? ""
+    });
+  }
+  if (args.backend === "linux-prlimit-process-group" /* LinuxPrlimitProcessGroup */) {
+    return buildLinuxPrlimitProcessGroupPlan({
+      options: args.options,
+      nprocCeiling: args.nprocCeiling ?? 0
+    });
+  }
+  return buildDarwinUlimitProcessGroupPlan({
+    options: args.options,
+    nprocCeiling: args.nprocCeiling ?? 0
+  });
+}
+
+// src/guard-run/headroom.ts
+function countProcessListLines(psOutput) {
+  return psOutput.split("\n").filter((line) => line.trim() !== "").length;
+}
+function computeNprocCeiling(args) {
+  return args.currentUserProcessCount + args.activeProcessLimit;
+}
+
+// src/guard-run/constants.ts
+var GUARD_RUN_DEFAULT_ACTIVE_PROCESS_LIMIT = 64;
+var GUARD_RUN_USAGE = "usage: guard-run [--limit N] [--service] -- <command...>\n  Runs <command> with its whole process tree kernel-capped at N processes\n  (default 64). Default mode also ties the tree to the launcher: killing\n  guard-run reaps every descendant. --service keeps the cap but lets the\n  tree outlive the launcher (for dev servers).";
+
+// src/guard-run/parseArguments.ts
+function parseError(errorMessage) {
+  return { options: null, errorMessage: `${errorMessage}
+${GUARD_RUN_USAGE}` };
+}
+function parsePositiveInteger(rawValue) {
+  if (rawValue === void 0 || !/^\d+$/.test(rawValue)) return null;
+  const parsed = Number(rawValue);
+  return parsed >= 1 ? parsed : null;
+}
+function parseGuardRunArguments(argv) {
+  let activeProcessLimit = GUARD_RUN_DEFAULT_ACTIVE_PROCESS_LIMIT;
+  let isServiceMode = false;
+  let index = 0;
+  while (index < argv.length) {
+    const token = argv[index];
+    if (token === "--") {
+      index += 1;
+      break;
+    }
+    if (token === "--service") {
+      isServiceMode = true;
+      index += 1;
+      continue;
+    }
+    if (token === "--limit" || token.startsWith("--limit=")) {
+      const rawLimit = token === "--limit" ? argv[index + 1] : token.slice("--limit=".length);
+      const parsedLimit = parsePositiveInteger(rawLimit);
+      if (parsedLimit === null) return parseError("--limit requires a positive integer");
+      activeProcessLimit = parsedLimit;
+      index += token === "--limit" ? 2 : 1;
+      continue;
+    }
+    if (token.startsWith("--")) return parseError(`unknown flag: ${token}`);
+    break;
+  }
+  const command = argv.slice(index);
+  if (command.length === 0) return parseError("no command given");
+  return {
+    options: {
+      activeProcessLimit,
+      isServiceMode,
+      command
+    },
+    errorMessage: null
+  };
+}
+
+// src/guard-run/selectBackend.ts
+var SYSTEMD_USABLE_MANAGER_STATES = /* @__PURE__ */ new Set(["running", "degraded"]);
+function selectGuardRunBackend(probe) {
+  if (probe.platform === "win32") {
+    return { backend: "windows-job-object" /* WindowsJobObject */, errorMessage: null };
+  }
+  if (probe.platform === "linux") {
+    const managerState = (probe.systemdUserManagerState ?? "").trim();
+    if (probe.hasSystemdRun && SYSTEMD_USABLE_MANAGER_STATES.has(managerState)) {
+      return { backend: "linux-systemd-scope" /* LinuxSystemdScope */, errorMessage: null };
+    }
+    if (probe.hasPrlimit) {
+      return { backend: "linux-prlimit-process-group" /* LinuxPrlimitProcessGroup */, errorMessage: null };
+    }
+    return {
+      backend: null,
+      errorMessage: "no process-cap backend available (need a systemd user manager or prlimit); refusing to run the command unguarded"
+    };
+  }
+  if (probe.platform === "darwin") {
+    return { backend: "darwin-ulimit-process-group" /* DarwinUlimitProcessGroup */, errorMessage: null };
+  }
+  return {
+    backend: null,
+    errorMessage: `unsupported platform "${probe.platform}"; refusing to run the command unguarded`
+  };
+}
+
+// src/guard-run/cli.ts
+var JOB_OBJECT_SHIM_FILENAME = "guard-run-job-object.ps1";
+function fail(message) {
+  process.stderr.write(`guard-run: ${message}
+`);
+  process.exit(2);
+}
+function commandSucceeds(executable, args) {
+  const probe = spawnSync(executable, args, { stdio: "ignore", timeout: 1e4 });
+  return probe.error === void 0 && probe.status === 0;
+}
+function probedSystemdUserManagerState() {
+  const probe = spawnSync("systemctl", ["--user", "is-system-running"], {
+    encoding: "utf-8",
+    timeout: 1e4
+  });
+  if (probe.error !== void 0 || typeof probe.stdout !== "string") return null;
+  return probe.stdout.trim();
+}
+function resolveJobObjectShimPath() {
+  const bundledSibling = join(dirname(fileURLToPath(import.meta.url)), JOB_OBJECT_SHIM_FILENAME);
+  if (existsSync(bundledSibling)) return bundledSibling;
+  const pluginTreePath = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "plugin",
+    "scripts",
+    JOB_OBJECT_SHIM_FILENAME
+  );
+  if (existsSync(pluginTreePath)) return pluginTreePath;
+  return fail(`cannot locate ${JOB_OBJECT_SHIM_FILENAME}; refusing to run the command unguarded`);
+}
+function windowsCommandNeedsCmdShell(firstCommandToken) {
+  const knownExtension = extname(firstCommandToken).toLowerCase();
+  if (knownExtension === ".cmd" || knownExtension === ".bat") return true;
+  if (knownExtension !== "") return false;
+  const lookup = spawnSync("where.exe", [firstCommandToken], {
+    encoding: "utf-8",
+    timeout: 1e4
+  });
+  if (lookup.error !== void 0 || lookup.status !== 0) return false;
+  const resolvedExtension = extname(lookup.stdout.split(/\r?\n/)[0] ?? "").toLowerCase();
+  return resolvedExtension === ".cmd" || resolvedExtension === ".bat";
+}
+function currentUserProcessCount() {
+  const uid = typeof process.getuid === "function" ? String(process.getuid()) : "";
+  const listing = spawnSync("ps", ["-u", uid, "-o", "pid="], {
+    encoding: "utf-8",
+    timeout: 1e4
+  });
+  if (listing.error !== void 0 || listing.status !== 0) {
+    return fail("cannot count current user processes for the nproc ceiling");
+  }
+  return countProcessListLines(listing.stdout);
+}
+function registerTreeCleanup(plan2, childPid) {
+  if (!plan2.killsProcessGroupOnExit && plan2.stopsScopeUnitOnExit === null) return;
+  let cleanedUp = false;
+  const cleanup = () => {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    if (plan2.killsProcessGroupOnExit && childPid !== void 0) {
+      try {
+        process.kill(-childPid, "SIGKILL");
+      } catch {
+      }
+    }
+    if (plan2.stopsScopeUnitOnExit !== null) {
+      spawnSync("systemctl", ["--user", "stop", plan2.stopsScopeUnitOnExit], {
+        stdio: "ignore",
+        timeout: 1e4
+      });
+    }
+  };
+  process.on("exit", cleanup);
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => {
+      cleanup();
+      process.exit(128 + (signal === "SIGINT" ? 2 : signal === "SIGTERM" ? 15 : 1));
+    });
+  }
+}
+var parseResult = parseGuardRunArguments(process.argv.slice(2));
+if (parseResult.options === null) fail(parseResult.errorMessage ?? "invalid arguments");
+var options = parseResult.options;
+var isLinux = process.platform === "linux";
+var selection = selectGuardRunBackend({
+  platform: process.platform,
+  hasSystemdRun: isLinux && commandSucceeds("systemd-run", ["--version"]),
+  systemdUserManagerState: isLinux ? probedSystemdUserManagerState() : null,
+  hasPrlimit: isLinux && commandSucceeds("prlimit", ["--version"])
+});
+if (selection.backend === null) fail(selection.errorMessage ?? "no backend");
+var backend = selection.backend;
+var needsNprocCeiling = backend === "linux-prlimit-process-group" /* LinuxPrlimitProcessGroup */ || backend === "darwin-ulimit-process-group" /* DarwinUlimitProcessGroup */;
+var plan = buildBackendLaunchPlan({
+  backend,
+  options,
+  jobObjectShimPath: backend === "windows-job-object" /* WindowsJobObject */ ? resolveJobObjectShimPath() : void 0,
+  launcherPid: process.pid,
+  commandNeedsCmdShell: backend === "windows-job-object" /* WindowsJobObject */ ? windowsCommandNeedsCmdShell(options.command[0]) : false,
+  scopeUnitName: `muggle-guard-${process.pid}-${Date.now()}.scope`,
+  nprocCeiling: needsNprocCeiling ? computeNprocCeiling({
+    currentUserProcessCount: currentUserProcessCount(),
+    activeProcessLimit: options.activeProcessLimit
+  }) : void 0
+});
+var child = spawn(plan.executable, plan.args, {
+  stdio: "inherit",
+  detached: plan.spawnDetached,
+  windowsHide: true
+});
+child.on("error", (error) => fail(`failed to launch backend: ${String(error)}`));
+registerTreeCleanup(plan, child.pid);
+child.on("exit", (code, signal) => {
+  process.exitCode = code ?? (signal === "SIGKILL" ? 137 : signal === "SIGTERM" ? 143 : 1);
+});

package/dist/plugin/scripts/guardrail-record-tests.sh

@@ -9,12 +9,13 @@ set -uo pipefail
 # Fires after every Bash call and every muggle execute/replay, so a keyword
 # pre-filter for test runners and the muggle E2E tool names keeps Node off the
 # hot path. Only a `test` command (npm/pnpm/yarn/jest/vitest/pytest/go/cargo),
-# a muggle execute/replay/test-generation event, or an E2E skip marker reaches
-# guardrails.mjs, which then inspects the output for pass/fail and updates
-# state. Degrades to {}.
+# a muggle execute/replay/test-generation event, a muggle-test skill telemetry
+# emit (registers a clean-SKIP verdict as an E2E run), or an E2E skip marker
+# reaches guardrails.mjs, which then inspects the output for pass/fail and
+# updates state. Degrades to {}.
 payload="$(cat)"
 
-if ! grep -Eiq '(pnpm|npm|yarn)[[:space:]]+(run[[:space:]]+)?test|jest|vitest|pytest|go[[:space:]]+test|cargo[[:space:]]+test|muggle.*(execute|test-generation|replay)|MUGGLE_E2E_SKIP' <<<"$payload"; then
+if ! grep -Eiq '(pnpm|npm|yarn)[[:space:]]+(run[[:space:]]+)?test|jest|vitest|pytest|go[[:space:]]+test|cargo[[:space:]]+test|muggle.*(execute|test-generation|replay)|muggle-local-telemetry-skill-emit|MUGGLE_E2E_SKIP' <<<"$payload"; then
   printf '{}'
   exit 0
 fi

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/{plugin/skills/_shared/vcs/github → dist/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/dist/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/dist/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/dist/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/dist/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).