@muggleai/works 5.7.0 → 5.8.1

package/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/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/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/CLAUDE.md

@@ -1,36 +1,39 @@
-# Skill authoring conventions
-
-Rules for every skill under `plugin/skills/`. Read before adding or editing one.
-
-## One-way dependencies — no reverse references
-
-Skill cross-references form a one-way graph. If any file in skill **A** references skill **B** — a markdown link to B's files, or a documented dependency on B's internals — then **no file in B may reference A back**. Reference *downward*, toward the more general / lower-level skill you depend on; pass anything the other direction needs as input, not as a link.
-
-A reverse reference (A → B and B → A) couples the depended-on skill to its caller, creates a cycle no one can reason about in isolation, and makes every edit ripple both ways. The lower-level skill must stay reusable by callers it has never heard of.
-
-**Runtime dispatch is not a doc reference.** A dumb-pipe skill may *fire* another skill's slash command at runtime (hand off and forget) — that is an action, not a dependency. What the rule forbids is a procedure file **linking to** or **encoding the internals of** the skill it hands off to.
-
-**Worked example.** `muggle-pr-followup` (the dumb-pipe watcher) is lower-level than `muggle-do` (the executor that orchestrates it). `muggle-do` references `muggle-pr-followup`; `muggle-pr-followup`'s files must not link back to `muggle-do`. A watcher tick still dispatches `/muggle-do …` at runtime — allowed — but no watcher file links a `do/` file or restates its steps, and shared primitives like `muggle-pr-followup/finalize.md` stay dispatch-free so any caller can reuse them.
-
-When you feel the urge to link "up" to a caller, that is the smell — restructure so the caller passes what is needed in.
-
-### Enforcement
-
-`scripts/check-skill-deps.mjs` derives the cross-skill link graph and fails on any cycle. A "reference" is a markdown file-link into another skill's directory — runtime slash-command dispatch is not a link and is not counted. It runs three ways: the `skill-deps` CI job on every PR, a `PreToolUse` hook (`.claude/settings.json`) that blocks the write mid-session with the offending link named, and `pnpm run verify:skill-deps` locally.
-
-`plugin/skills/skill-deps.config.json` declares support dirs grouped into their owning skill (`do/` → `muggle-do`), shared namespaces exploded to per-file nodes (`_shared`), and `knownReverseDeps` — pre-existing violations grandfathered so CI stays green. That list is debt: fix each link and delete its entry. A new reverse dependency is blocked whether or not it is on the list.
-
-## Model tiers
-
-Each skill sets a `model:` in its `SKILL.md` frontmatter sized to its cognitive load. `model:` is a native Claude Code field — the override applies while the skill is active and reverts to the session model when it exits. Cheaper, faster models run the mechanical skills; the default (Opus) is reserved for the ones that actually reason. Cost and latency scale with the model, and these skills run often (the watcher fires every minute), so the tier is a real lever, not cosmetics.
-
-| Model | Skills | Why this tier |
-|-------|--------|---------------|
-| `haiku` | `muggle`, `muggle-status`, `muggle-repair`, `muggle-upgrade`, `muggle-preferences`, `muggle-feedback`, `muggle-pr-followup` | Routers and dumb pipes. They follow an explicit procedure with no open-ended reasoning: route intent to a downstream skill, run a fixed CLI sequence, CRUD a config file, format a status report, or poll provider state and branch on conditions. `muggle-pr-followup` is the canonical case — a watcher that reads GitHub state and dispatches; all judgment lives in the `muggle-do` it hands off to. |
-| `sonnet` | `muggle-pr-visual-walkthrough`, `muggle-test-regenerate-missing` | Multi-step orchestration with light judgment, short of deep reasoning: assemble run data and build a PR section with fit-vs-overflow handling; scan, filter, bulk-dispatch, and classify per-item failures into buckets. More moving parts than a router, but each step is well-defined. |
-| `opus` (explicit pin) | `muggle-test-prepare` | Pinned for **reliability**, not raw reasoning load: it's flaky on smaller models, and since other skills gate on the environment it readies, a wrong call is expensive. Pin explicitly rather than leaving `model:` unset so it stays on Opus even when the user's session runs a cheaper model. |
-| default (Opus) — no `model:` set | `muggle-do`, `muggle-test`, `muggle-test-feature-local`, `muggle-browser-task`, `muggle-test-import` | Reasoning-heavy. Authoring code to a PR, mapping a code diff to affected user flows and interpreting E2E results, reasoning about an arbitrary website's flow to drive a browser, translating Playwright/Cypress/PRD artifacts into Muggle test cases. Leave `model:` unset so the skill inherits the session model. |
-
-**Choosing a tier for a new skill.** Ask what the skill actually does. Pure routing / fixed procedure / CRUD / reporting → `haiku`. Several well-defined steps with some judgment or classification → `sonnet`. Open-ended reasoning, code authoring, or interpreting ambiguous real-world state → leave `model:` unset (Opus). When unsure between two tiers, pick the cheaper one and watch for misbehavior — the likeliest to need a bump is anything doing AI-based classification. If a skill proves flaky on its tier and reliability matters more than cost (other skills depend on it, or a wrong call is expensive), pin it up explicitly — `model: opus` — rather than leaving it unset, so the floor holds regardless of the user's session model.
-
-**Never set `model:` on aliases or commands.** The alias skills (`m`, `mstatus`, …) and `plugin/commands/*.md` are thin routers that re-invoke the canonical skill via the `Skill` tool. The canonical `SKILL.md`'s `model:` takes effect once it loads, so a model on the alias would only apply to the negligible one-line hand-off — and risks drifting from the canonical value.
+# Skill authoring conventions
+
+Rules for every skill under `plugin/skills/`. Read before adding or editing one.
+
+## One-way dependencies — no reverse references
+
+Skill cross-references form a one-way graph. If any file in skill **A** references skill **B** — a markdown link to B's files, or a documented dependency on B's internals — then **no file in B may reference A back**. Reference *downward*, toward the more general / lower-level skill you depend on; pass anything the other direction needs as input, not as a link.
+
+A reverse reference (A → B and B → A) couples the depended-on skill to its caller, creates a cycle no one can reason about in isolation, and makes every edit ripple both ways. The lower-level skill must stay reusable by callers it has never heard of.
+
+**Runtime dispatch is not a doc reference.** A dumb-pipe skill may *fire* another skill's slash command at runtime (hand off and forget) — that is an action, not a dependency. What the rule forbids is a procedure file **linking to** or **encoding the internals of** the skill it hands off to.
+
+**Worked example.** `muggle-pr-followup` (the dumb-pipe watcher) is lower-level than `muggle-do` (the executor that orchestrates it). `muggle-do` references `muggle-pr-followup`; `muggle-pr-followup`'s files must not link back to `muggle-do`. A watcher tick still dispatches `/muggle-do …` at runtime — allowed — but no watcher file links a `do/` file or restates its steps, and shared primitives like `muggle-pr-followup/finalize.md` stay dispatch-free so any caller can reuse them.
+
+When you feel the urge to link "up" to a caller, that is the smell — restructure so the caller passes what is needed in.
+
+### Enforcement
+
+`scripts/check-skill-deps.mjs` derives the cross-skill link graph and fails on any cycle. A "reference" is a markdown file-link into another skill's directory — runtime slash-command dispatch is not a link and is not counted. It runs three ways: the `skill-deps` CI job on every PR, a `PreToolUse` hook (`.claude/settings.json`) that blocks the write mid-session with the offending link named, and `pnpm run verify:skill-deps` locally.
+
+`plugin/skills/skill-deps.config.json` declares support dirs grouped into their owning skill (`do/` → `muggle-do`), shared namespaces exploded to per-file nodes (`_shared`), and `knownReverseDeps` — pre-existing violations grandfathered so CI stays green. That list is debt: fix each link and delete its entry. A new reverse dependency is blocked whether or not it is on the list.
+
+## Model tiers
+
+Each skill sets a `model:` in its `SKILL.md` frontmatter sized to its cognitive load. `model:` is a native Claude Code field — the override applies while the skill is active and reverts to the session model when it exits. Cheaper, faster models run the mechanical skills; the default (Opus) is reserved for the ones that actually reason. Cost and latency scale with the model, and these skills run often (the watcher fires every minute), so the tier is a real lever, not cosmetics.
+
+| Model | Skills | Why this tier |
+|-------|--------|---------------|
+| `haiku` | `muggle`, `muggle-status`, `muggle-repair`, `muggle-upgrade`, `muggle-preferences`, `muggle-feedback`, `muggle-pr-followup` | Routers and dumb pipes. They follow an explicit procedure with no open-ended reasoning: route intent to a downstream skill, run a fixed CLI sequence, CRUD a config file, format a status report, or poll provider state and branch on conditions. `muggle-pr-followup` is the canonical case — a watcher that reads GitHub state and dispatches; all judgment lives in the `muggle-do` it hands off to. |
+| `sonnet` | `muggle-pr-visual-walkthrough` (executes via the `visual-walkthrough-builder` agent), `muggle-test-regenerate-missing` | Multi-step orchestration with light judgment, short of deep reasoning: assemble run data and build a PR section with fit-vs-overflow handling; scan, filter, bulk-dispatch, and classify per-item failures into buckets. More moving parts than a router, but each step is well-defined. |
+| `opus` (explicit pin) | `muggle-test-prepare` (executes via the `test-prepare-runner` agent) | Pinned for **reliability**, not raw reasoning load: it's flaky on smaller models, and since other skills gate on the environment it readies, a wrong call is expensive. Pin explicitly rather than leaving `model:` unset so it stays on Opus even when the user's session runs a cheaper model. |
+
+| default (Opus) — no `model:` set | `muggle-do`, `muggle-test`, `muggle-test-feature-local`, `muggle-browser-task`, `muggle-test-import` | Reasoning-heavy. Authoring code to a PR, mapping a code diff to affected user flows and interpreting E2E results, reasoning about an arbitrary website's flow to drive a browser, translating Playwright/Cypress/PRD artifacts into Muggle test cases. Leave `model:` unset so the skill inherits the session model. |
+
+**A `SKILL.md` `model:` only bites when the skill starts a fresh session; invoked mid-session the session model keeps running.** A skill whose pin must hold regardless resolves its user interaction in the `SKILL.md`, then dispatches a `plugin/agents/*` agent that carries the pin — the harness applies an agent's `model:` on every dispatch. That is why `muggle-pr-visual-walkthrough`, `muggle-test-prepare`, and `muggle-pr-followup` execute through agents. Agents have no user channel; an unresolved decision comes back as `needs-input:` for the skill to resolve.
+
+**Choosing a tier for a new skill.** Ask what the skill actually does. Pure routing / fixed procedure / CRUD / reporting → `haiku`. Several well-defined steps with some judgment or classification → `sonnet`. Open-ended reasoning, code authoring, or interpreting ambiguous real-world state → leave `model:` unset (Opus). When unsure between two tiers, pick the cheaper one and watch for misbehavior — the likeliest to need a bump is anything doing AI-based classification. If a skill proves flaky on its tier and reliability matters more than cost (other skills depend on it, or a wrong call is expensive), pin it up explicitly — `model: opus` — rather than leaving it unset, so the floor holds regardless of the user's session model.
+
+**Never set `model:` on aliases or commands.** The alias skills (`m`, `mstatus`, …) and `plugin/commands/*.md` are thin routers that re-invoke the canonical skill via the `Skill` tool. The canonical `SKILL.md`'s `model:` takes effect once it loads, so a model on the alias would only apply to the negligible one-line hand-off — and risks drifting from the canonical value.

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).