@muggleai/works 5.9.0 → 5.11.0

package/dist/plugin/scripts/pr-watch-events.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+
+# Wake conditions for the muggle-pr-followup watch loop — the single definition
+# of what makes a quiet watcher speak. Sourced by pr-watch-loop.sh.
+#
+# These live in a file, rather than in the prose an arming session reads, because
+# a re-derived loop silently loses conditions. Observed across four slots on one
+# machine: two implemented the behind-base wake and two did not, and the two that
+# did not left their PRs permanently unmergeable under a watcher that looked
+# healthy — alive, heartbeating, no fetch errors, and nothing to say. A dropped
+# wake has no failure mode that anyone notices.
+#
+# Every function is pure: arguments in, one event line on stdout, no I/O and no
+# provider calls. That keeps each condition directly testable, which is the
+# property prose never had. Exit 0 means "woke and emitted", 1 means "stay quiet".
+# Each caller owns its own floor and advances it only on a real wake, so one
+# occurrence fires exactly once.
+
+# Splits the tab-separated state line into its fields, one per line, preserving
+# empty ones. Not a wake, but every wake below reads its arguments out of this.
+#
+# `IFS=$'\t' read` cannot do it: tab is an IFS *whitespace* character, so bash
+# collapses runs of tabs into a single delimiter, and the two adjacent tabs an
+# empty field produces silently shift every later field left. With no unresolved
+# thread — the common case, and also what a push leaves behind once its thread
+# goes outdated — the thread field is empty, so the pending-check count lands in
+# unresolved_threads and fires a thread wake for a PR with no threads, while the
+# check digest lands in failed_checks and leaves red-CI detection reading a
+# string where it expects a count. awk with an explicit FS does not collapse.
+watch_split_state() {
+    printf '%s\n' "$1" | awk -F'\t' '{for (i = 1; i <= NF; i++) print $i}'
+}
+
+# A submitted review newer than the floor. Monotonic ids, so `>` is the whole
+# test. PENDING (unsubmitted) reviews are excluded by the caller's query — they
+# are the reviewer's own drafts and are not feedback until submitted.
+watch_wake_review() {
+    local pr="$1" latest="$2" floor="$3"
+    [ "${latest:-0}" -gt "${floor:-0}" ] 2>/dev/null || return 1
+    echo "EVENT pr=$pr new submitted review id=$latest"
+}
+
+# A thread comment newer than the floor. Same monotonic-id reasoning as reviews.
+watch_wake_comment() {
+    local pr="$1" latest="$2" floor="$3"
+    [ "${latest:-0}" -gt "${floor:-0}" ] 2>/dev/null || return 1
+    echo "EVENT pr=$pr new thread comment id=$latest"
+}
+
+# A thread that is unresolved and not already known to be. `known` is the
+# semicolon-joined THREADS floor; membership is the test, not ordering, because
+# thread ids are opaque strings rather than a monotonic sequence.
+watch_wake_thread() {
+    local pr="$1" thread_id="$2" known="$3"
+    [ -n "$thread_id" ] || return 1
+    case ";${known};" in
+        *";${thread_id};"*) return 1 ;;
+    esac
+    echo "EVENT pr=$pr thread newly unresolved id=$thread_id"
+}
+
+# The head's checks having **settled** red: nothing still pending and at least
+# one failure. Pending-with-a-failure is not a wake — a run in flight may still
+# go green, and the tick would idle on it anyway.
+#
+# The floor is the head SHA rather than a monotonic id because a check rollup is
+# not monotonic: it flips green to red and resets on every push. Keying on the
+# red head fires once per red head and re-arms on the next push.
+watch_wake_ci_red() {
+    local pr="$1" pending_count="$2" failed_count="$3" head_sha="$4" floor="$5"
+    [ -n "$head_sha" ] || return 1
+    [ "$head_sha" != "$floor" ] || return 1
+    [ "${pending_count:-0}" -eq 0 ] 2>/dev/null || return 1
+    [ "${failed_count:-0}" -gt 0 ] 2>/dev/null || return 1
+    echo "EVENT pr=$pr checks settled red head=$head_sha"
+}
+
+# The branch needing a rebase onto its base — conflicting with it, or merely
+# behind it.
+#
+# Behind is the half that regenerated loops kept dropping, and it is invisible
+# from the signals a conflict check uses: a behind-but-clean branch reports
+# mergeable=MERGEABLE, exactly like a current one. `mergeStateStatus` cannot
+# stand in either — it is one enum with precedence, and BLOCKED (review
+# required) masks BEHIND on any PR still awaiting approval, which is most of
+# them. Behind-ness has to be measured, so the caller passes `behind_count` from
+# a compare call.
+#
+# The floor is the rebase key `<head_sha>..<base_tip_sha>`, pairing both sides:
+# staleness is a function of the pair, so a head-only key would wedge
+# permanently the first time the base advanced (nothing can move the head while
+# the branch sits blocked). Pairing re-arms whenever either side moves.
+watch_wake_rebase() {
+    local pr="$1" mergeable="$2" behind_count="$3" rebase_key="$4" floor="$5"
+    [ -n "$rebase_key" ] || return 1
+    [ "$rebase_key" != "$floor" ] || return 1
+    if [ "$mergeable" = "CONFLICTING" ]; then
+        echo "EVENT pr=$pr branch conflicting with base key=$rebase_key"
+        return 0
+    fi
+    [ -n "$behind_count" ] && [ "$behind_count" -gt 0 ] 2>/dev/null || return 1
+    echo "EVENT pr=$pr branch behind base by $behind_count — rebase due key=$rebase_key"
+}
+
+# A blocked watch whose CI signature moved at all. This is a resume probe, not a
+# failure probe: it is dormant unless `blocked_digest` is set, and it wakes on
+# any move away from that value rather than only on red, so a block waiting on a
+# green pass, a rerun, or an external deploy check resumes as promptly as one
+# waiting on a failure.
+watch_wake_blocked_resume() {
+    local pr="$1" digest="$2" blocked_digest="$3"
+    [ -n "$blocked_digest" ] || return 1
+    [ -n "$digest" ] || return 1
+    [ "$digest" != "$blocked_digest" ] || return 1
+    echo "EVENT pr=$pr ci digest moved while blocked — resume check"
+}

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

@@ -18,11 +18,14 @@
 #                           on its own; reconcile re-arms an open PR inside a live
 #                           session.
 
-MUGGLE_PR_WATCH_MAX_LIFETIME="${MUGGLE_PR_WATCH_MAX_LIFETIME:-21600}"
+# Seconds a watch loop may live. 0 means unbounded — the `never` setting of the
+# watcherLifetime preference, which removes the only time-based reaper for a
+# loop whose session has gone. `watcher_superseded` is then the sole guard.
+MUGGLE_PR_WATCH_MAX_LIFETIME="${MUGGLE_PR_WATCH_MAX_LIFETIME:-604800}"
 MUGGLE_PR_WATCH_POLL_INTERVAL="${MUGGLE_PR_WATCH_POLL_INTERVAL:-60}"
 # Consecutive failed fetches before a loop gives up. A watcher must ride through
 # a GitHub / network outage — an observed drop lasted ~8 minutes — not die and
-# leave the PR unwatched until the next session start. With the backoff below, 60
+# leave the PR unwatched until its owning session next starts. With the backoff, 60
 # spans hours; only a genuinely persistent unreachable slot (deleted repo,
 # revoked auth) exhausts it.
 MUGGLE_PR_WATCH_MAX_FETCH_FAILURES="${MUGGLE_PR_WATCH_MAX_FETCH_FAILURES:-60}"
@@ -50,6 +53,9 @@ watcher_superseded() {
 
 watcher_lifetime_exceeded() {
     local started="$1" now="$2" max="${3:-$MUGGLE_PR_WATCH_MAX_LIFETIME}"
+    # 0 is unbounded, not "already expired" — the arithmetic below would other-
+    # wise make every loop exit on its first iteration.
+    [ "$max" -eq 0 ] 2>/dev/null && return 1
     [ $((now - started)) -ge "$max" ]
 }
 

package/dist/plugin/scripts/pr-watch-loop.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+
+# The muggle-pr-followup watch loop. One process per PR slot: polls provider
+# state, prints one line per new event, and exits when the PR goes terminal.
+#
+# Ships as a file so arming runs it rather than rewrites it. A loop re-derived
+# from prose on every arm drifts — the behind-base wake went missing from half
+# the slots on one machine that way, leaving PRs unmergeable under watchers that
+# looked healthy. The wake conditions live in pr-watch-events.sh; this file is
+# the I/O around them.
+#
+# Usage: pr-watch-loop.sh --slot <dir> --repo <owner/name> --pr <n> --base <branch>
+
+set -uo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+slot=""
+repo=""
+pr_number=""
+base_branch="master"
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --slot) slot="$2"; shift 2 ;;
+        --repo) repo="$2"; shift 2 ;;
+        --pr) pr_number="$2"; shift 2 ;;
+        --base) base_branch="$2"; shift 2 ;;
+        *) echo "pr-watch-loop: unknown argument $1" >&2; exit 2 ;;
+    esac
+done
+
+if [ -z "$slot" ] || [ -z "$repo" ] || [ -z "$pr_number" ]; then
+    echo "pr-watch-loop: --slot, --repo and --pr are required" >&2
+    exit 2
+fi
+
+# Resolved absolutely at arm time so they still load after the arming session is
+# gone. Guards missing means the plugin moved or upgraded underneath this loop —
+# a newer version's watcher owns the slot now, so step down rather than run on
+# without the supersede check.
+for lib in pr-watch-guards.sh pr-watch-events.sh; do
+    [ -f "${script_dir}/${lib}" ] || exit 0
+    # shellcheck source=/dev/null
+    . "${script_dir}/${lib}"
+done
+
+echo "$$" > "${slot}/watch.pid"
+started=$(date +%s)
+fails=0
+
+# In-memory floors, above the on-disk watermark. The watermark is advanced by
+# the session after it handles a wave; these stop the loop re-reporting an event
+# in the window before that write lands.
+floor_review=0
+floor_comment=0
+floor_threads=";"
+floor_ci_red=""
+floor_rebase=""
+floor_blocked_digest=""
+
+# Pin the token once: a detached loop can lose access to gh's OS keyring
+# mid-run, which surfaces as empty fetches rather than an error.
+pinned_token="$(gh auth token 2>/dev/null)"
+[ -n "$pinned_token" ] && export GH_TOKEN="$pinned_token"
+
+fetch_pr_state() {
+    gh api graphql -F owner="${repo%%/*}" -F name="${repo##*/}" -F number="$pr_number" -f query='
+query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      state
+      headRefOid
+      baseRefOid
+      mergeable
+      commits(last: 1) {
+        nodes {
+          commit {
+            statusCheckRollup {
+              contexts(first: 100) {
+                nodes {
+                  __typename
+                  ... on CheckRun { name status conclusion }
+                  ... on StatusContext { context state }
+                }
+              }
+            }
+          }
+        }
+      }
+      reviews(last: 20, states: [COMMENTED, APPROVED, CHANGES_REQUESTED, DISMISSED]) { nodes { databaseId } }
+      reviewThreads(first: 100) {
+        nodes {
+          id
+          isResolved
+          isOutdated
+          comments(last: 1) { nodes { databaseId pullRequestReview { state } } }
+        }
+      }
+    }
+  }
+}' --jq '
+.data.repository.pullRequest as $pr
+| (($pr.commits.nodes[0].commit.statusCheckRollup.contexts.nodes) // []) as $contexts
+| ($contexts | map(
+    if .__typename == "CheckRun"
+    then {name: .name, verdict: (if .status != "COMPLETED" then "PENDING" else (.conclusion // "NEUTRAL") end)}
+    else {name: .context, verdict: (.state // "PENDING")}
+    end)) as $checks
+| [
+    $pr.state,
+    $pr.headRefOid,
+    $pr.baseRefOid,
+    $pr.mergeable,
+    (([$pr.reviews.nodes[].databaseId] | max) // 0),
+    (([$pr.reviewThreads.nodes[] | select(.isResolved == false) | .comments.nodes[]
+       | select((.pullRequestReview.state // "SUBMITTED") != "PENDING") | .databaseId] | max) // 0),
+    ([$pr.reviewThreads.nodes[] | select(.isResolved == false) | select(.isOutdated == false)
+      | select((.comments.nodes[0].pullRequestReview.state // "SUBMITTED") != "PENDING") | .id] | join(";")),
+    ($checks | map(select(.verdict == "PENDING")) | length),
+    ($checks | map(select(.verdict == "FAILURE" or .verdict == "ERROR" or .verdict == "TIMED_OUT" or .verdict == "STARTUP_FAILURE")) | length),
+    ($checks | sort_by(.name) | map(.name + ":" + .verdict) | join(","))
+  ] | @tsv' 2>>"${slot}/watch-fetch.log"
+}
+
+# behind_by needs its own call — see watch_wake_rebase for why no field on the
+# PR carries it. Made only when the head/base pair moved, so the steady state
+# stays one request per iteration.
+fetch_behind_count() {
+    local head_sha="$1"
+    gh api "repos/${repo}/compare/${base_branch}...${head_sha}" --jq '.behind_by' 2>>"${slot}/watch-fetch.log"
+}
+
+read_watermark_value() {
+    local key="$1" line value=""
+    while IFS= read -r line || [ -n "$line" ]; do
+        line="${line%$'\r'}"
+        case "$line" in
+            "${key}="*)
+                value="${line#"${key}"=}"
+                value="${value%\"}"
+                value="${value#\"}"
+                ;;
+        esac
+    done < "${slot}/watch-watermark.env"
+    printf '%s' "$value"
+}
+
+while :; do
+    watcher_superseded "$slot" "$$" && exit 0
+    watcher_lifetime_exceeded "$started" "$(date +%s)" && exit 0
+    touch "${slot}/watch-heartbeat" 2>/dev/null
+
+    # No watermark yet means the arming session has not finished seeding. Wait
+    # rather than treat every floor as zero, which would fire the whole backlog.
+    if [ ! -f "${slot}/watch-watermark.env" ]; then
+        sleep "$MUGGLE_PR_WATCH_POLL_INTERVAL"
+        continue
+    fi
+
+    watermark_review=$(read_watermark_value REV)
+    watermark_comment=$(read_watermark_value COM)
+    watermark_threads=$(read_watermark_value THREADS)
+    watermark_ci_red=$(read_watermark_value CIRED)
+    watermark_rebase=$(read_watermark_value REBASED)
+    watermark_blocked_digest=$(read_watermark_value BLOCKED_CIDIGEST)
+
+    state_line=$(fetch_pr_state)
+    # One quick retry before counting a strike: a single flaky call should not
+    # advance the failure budget.
+    [ -z "$state_line" ] && { sleep 3; state_line=$(fetch_pr_state); }
+
+    if [ -z "$state_line" ]; then
+        fails=$((fails + 1))
+        echo "$(date -u +%FT%TZ) fetch empty (${fails}/${MUGGLE_PR_WATCH_MAX_FETCH_FAILURES})" >> "${slot}/watch-fetch.log"
+        if [ "$fails" -ge "$MUGGLE_PR_WATCH_MAX_FETCH_FAILURES" ]; then
+            echo "WATCH-FAIL pr=$pr_number ${fails} consecutive fetch failures — see watch-fetch.log"
+            exit 1
+        fi
+        sleep "$(watcher_fetch_backoff "$fails")"
+        continue
+    fi
+
+    mapfile -t state_fields < <(watch_split_state "$state_line")
+    pr_state="${state_fields[0]-}"
+    head_sha="${state_fields[1]-}"
+    base_sha="${state_fields[2]-}"
+    mergeable="${state_fields[3]-}"
+    latest_review="${state_fields[4]-}"
+    latest_comment="${state_fields[5]-}"
+    unresolved_threads="${state_fields[6]-}"
+    pending_checks="${state_fields[7]-}"
+    failed_checks="${state_fields[8]-}"
+    ci_digest="${state_fields[9]-}"
+
+    if [ "$pr_state" = "MERGED" ] || [ "$pr_state" = "CLOSED" ]; then
+        echo "TERMINAL pr=$pr_number state=$pr_state"
+        exit 0
+    fi
+
+    if [ "$pr_state" != "OPEN" ]; then
+        fails=$((fails + 1))
+        if [ "$fails" -ge "$MUGGLE_PR_WATCH_MAX_FETCH_FAILURES" ]; then
+            echo "WATCH-FAIL pr=$pr_number unreadable state after ${fails} tries"
+            exit 1
+        fi
+        sleep "$(watcher_fetch_backoff "$fails")"
+        continue
+    fi
+    fails=0
+
+    if watch_wake_review "$pr_number" "$latest_review" \
+        "$(( watermark_review > floor_review ? watermark_review : floor_review ))"; then
+        floor_review="$latest_review"
+    fi
+
+    if watch_wake_comment "$pr_number" "$latest_comment" \
+        "$(( watermark_comment > floor_comment ? watermark_comment : floor_comment ))"; then
+        floor_comment="$latest_comment"
+    fi
+
+    if [ -n "$unresolved_threads" ]; then
+        IFS=';' read -ra thread_ids <<< "$unresolved_threads"
+        for thread_id in "${thread_ids[@]}"; do
+            if watch_wake_thread "$pr_number" "$thread_id" "${watermark_threads};${floor_threads}"; then
+                floor_threads="${floor_threads}${thread_id};"
+            fi
+        done
+    fi
+
+    if watch_wake_ci_red "$pr_number" "$pending_checks" "$failed_checks" "$head_sha" \
+        "${floor_ci_red:-$watermark_ci_red}"; then
+        floor_ci_red="$head_sha"
+    fi
+
+    rebase_key="${head_sha}..${base_sha}"
+    if [ "$rebase_key" != "$watermark_rebase" ] && [ "$rebase_key" != "$floor_rebase" ]; then
+        behind_count=$(fetch_behind_count "$head_sha")
+        if watch_wake_rebase "$pr_number" "$mergeable" "$behind_count" "$rebase_key" ""; then
+            floor_rebase="$rebase_key"
+        fi
+    fi
+
+    # The tick owns clearing the block, and it may not run for a while. Holding
+    # the emitted digest stops the loop repeating itself every iteration in the
+    # meantime — the repeat nagging the design rules out — while a further move
+    # still wakes it.
+    if [ "$ci_digest" != "$floor_blocked_digest" ] \
+        && watch_wake_blocked_resume "$pr_number" "$ci_digest" "$watermark_blocked_digest"; then
+        floor_blocked_digest="$ci_digest"
+    fi
+
+    sleep "$MUGGLE_PR_WATCH_POLL_INTERVAL"
+done

package/dist/plugin/scripts/reconcile-stale-watchers.sh

@@ -2,13 +2,16 @@
 
 set -euo pipefail
 
-# muggle-pr-followup watchers are session-only crons — they die on session end
-# and on the 7-day /loop expiry, leaving open PRs with no live poller. Re-arming
-# needs CronCreate, a Claude tool a shell hook can't call, so this hook can't
-# recover a watcher itself. It nudges instead: on session start, if any open slot
-# exists, it tells the agent to run reconcile (which finalizes terminal slots and
-# re-arms silently-dead open watchers). A pure directory scan — no gh, no writes —
-# so it stays cheap enough to run on every session start.
+# muggle-pr-followup watchers are session-bound — they die on session end and on
+# the 7-day /loop expiry, leaving open PRs with no live poller. Re-arming needs
+# Claude tools a shell hook can't call, so this hook nudges rather than acts.
+#
+# The nudge is owner-scoped. Each slot records the session that armed it in
+# owner.json; only slots owned by THIS session are a recovery the agent should
+# run, because re-arming a stranger's PR would hand review work to a session with
+# no context for it. Slots owned by another session (or none) are reported as
+# orphans with the adopt command, never as work to pick up. A pure directory scan
+# — no gh, no writes — so it stays cheap enough for every session start.
 
 escape_for_json() {
     local s="$1"
@@ -20,31 +23,76 @@ escape_for_json() {
     printf '%s' "$s"
 }
 
-# A slot is a live-or-dead open watcher iff it has prs.json (a tracked PR) but no
-# result.md (not yet finalized). result.md is the terminal marker.
+# Extract the first "session_id": "..." from a JSON file or string. Deliberately
+# sed rather than jq: jq is not guaranteed present, and on Windows it appends CRLF
+# that makes an empty field compare non-empty.
+read_session_id() {
+    sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" 2>/dev/null | head -1 | tr -d '\r'
+}
+
+hook_payload=$(cat 2>/dev/null || true)
+current_session_id=$(printf '%s' "$hook_payload" | read_session_id /dev/stdin)
+
+# A slot is an open watcher iff it has prs.json (a tracked PR) and no result.md
+# (not yet finalized). A *.stopped dir is the owner's kill switch — it keeps its
+# prs.json, so the name check is the only thing that distinguishes a slot the
+# owner deliberately killed from one awaiting recovery. Counting those reports
+# stopped watchers back as work.
 sessions_dir="${HOME}/.muggle-ai/muggle-do/sessions"
-stale_count=0
+owned_count=0
+orphan_count=0
+first_orphan_slug=""
+
 if [ -d "$sessions_dir" ]; then
     for slot in "$sessions_dir"/*/; do
         [ -d "$slot" ] || continue
-        if [ -f "${slot}prs.json" ] && [ ! -f "${slot}result.md" ]; then
-            stale_count=$((stale_count + 1))
+        case "$slot" in *.stopped/) continue ;; esac
+        [ -f "${slot}prs.json" ] || continue
+        [ ! -f "${slot}result.md" ] || continue
+
+        slot_owner=""
+        if [ -f "${slot}owner.json" ]; then
+            slot_owner=$(read_session_id "${slot}owner.json")
+        fi
+
+        # Fail closed: an unidentifiable session owns nothing. Absent owner.json
+        # (legacy slot) is likewise foreign — never adopted by default.
+        if [ -n "$current_session_id" ] && [ "$slot_owner" = "$current_session_id" ]; then
+            owned_count=$((owned_count + 1))
+        else
+            orphan_count=$((orphan_count + 1))
+            if [ -z "$first_orphan_slug" ]; then
+                first_orphan_slug=$(basename "$slot")
+            fi
         fi
     done
 fi
 
-# Clean state: no open slots to reconcile → stay completely silent, never nudge.
-if [ "$stale_count" -eq 0 ]; then
+# Clean state: nothing of this session's to recover and no orphans → stay silent.
+if [ "$owned_count" -eq 0 ] && [ "$orphan_count" -eq 0 ]; then
     exit 0
 fi
 
-if [ "$stale_count" -eq 1 ]; then
-    slot_word="slot"
+if [ "$owned_count" -eq 1 ]; then
+    owned_word="watcher"
 else
-    slot_word="slots"
+    owned_word="watchers"
 fi
 
-context="muggle-pr-followup: ${stale_count} open watcher ${slot_word} found (a tracked PR with no result.md). Session-only watcher crons die on session end and after the 7-day /loop expiry, so these may have no live poller. Run \`/muggle:muggle-pr-followup reconcile\` to finalize any whose PR went terminal and re-arm silently-stopped open watchers. Reconcile is idempotent — it re-arms only genuinely dead watchers and stays quiet on the rest."
+if [ "$owned_count" -gt 0 ]; then
+    context="muggle-pr-followup: ${owned_count} open ${owned_word} owned by this session may have lost its poller. Run \`/muggle:muggle-pr-followup reconcile\` to finalize any whose PR went terminal and re-arm the silently-stopped ones. Reconcile is idempotent and re-arms only watchers this session armed itself."
+else
+    context="muggle-pr-followup: no watchers belong to this session — nothing to re-arm."
+fi
+
+if [ "$orphan_count" -gt 0 ]; then
+    if [ "$orphan_count" -eq 1 ]; then
+        orphan_word="slot is"
+    else
+        orphan_word="slots are"
+    fi
+    context="${context} ${orphan_count} open ${orphan_word} owned by other sessions; reconcile will finalize them if their PR already merged or closed, but will never re-arm them. Adopt one deliberately with \`/muggle:muggle-pr-followup adopt <slug>\` (e.g. ${first_orphan_slug}) only if the user asks — do not offer or adopt on your own."
+fi
 
 escaped_context=$(escape_for_json "$context")
 

package/dist/plugin/scripts/sign-body.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+#
+# Appends the Muggle Works signature to a body about to be posted to a PR/MR.
+#
+# Reads the unsigned body on stdin, writes the signed body on stdout:
+#
+#   sign-body.sh --command /muggle-do --mode loop < draft.md
+#
+# --command  slash-command of the skill whose post this is (owner of the post,
+#            not the producer of the content).
+# --mode     loop      thread replies and resolve-reminders: prefixes the
+#                      <!-- muggle-do:bot --> echo-detection marker.
+#            editable  PR/MR descriptions: prefixes the dedup marker, and cuts
+#                      any previous signature so refreshes never stack.
+#            plain     one-shot comments with no marker.
+#
+# Idempotent: an already-signed body is re-signed, not double-signed.
+
+set -euo pipefail
+
+readonly REPOSITORY_URL='https://github.com/multiplex-ai/muggle-ai-works'
+readonly SIGNATURE_PREFIX='🤖 _Posted by '
+readonly LOOP_MARKER='<!-- muggle-do:bot -->'
+readonly EDITABLE_MARKER='<!-- muggle-works:signature -->'
+
+usage() {
+  echo "usage: sign-body.sh --command <slash-command> --mode <loop|editable|plain>" >&2
+  exit 2
+}
+
+postedCommand=''
+signatureMode=''
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --command) postedCommand="${2-}"; shift 2 ;;
+    --mode) signatureMode="${2-}"; shift 2 ;;
+    -h|--help) usage ;;
+    *) echo "sign-body.sh: unknown argument '$1'" >&2; usage ;;
+  esac
+done
+
+[ -n "$postedCommand" ] || usage
+case "$signatureMode" in
+  loop|editable|plain) ;;
+  *) usage ;;
+esac
+
+# Cuts any signature the body already carries, so re-signing an edited body
+# replaces it instead of stacking a second one underneath.
+stripExistingSignature() {
+  awk -v editableMarker="$EDITABLE_MARKER" \
+      -v loopMarker="$LOOP_MARKER" \
+      -v signaturePrefix="$SIGNATURE_PREFIX" '
+    { lines[NR] = $0 }
+    END {
+      cut = NR + 1
+      for (i = 1; i <= NR; i++) {
+        if (lines[i] == editableMarker) { cut = i; break }
+      }
+      if (cut == NR + 1) {
+        for (i = NR; i >= 1; i--) {
+          if (lines[i] == "") continue
+          if (index(lines[i], signaturePrefix) == 1) {
+            cut = i
+            if (i > 1 && (lines[i - 1] == loopMarker || lines[i - 1] == editableMarker)) cut = i - 1
+          }
+          break
+        }
+      }
+      last = cut - 1
+      while (last >= 1 && lines[last] == "") last--
+      for (i = 1; i <= last; i++) print lines[i]
+    }
+  '
+}
+
+body="$(stripExistingSignature)"
+
+case "$signatureMode" in
+  loop) marker="$LOOP_MARKER" ;;
+  editable) marker="$EDITABLE_MARKER" ;;
+  plain) marker='' ;;
+esac
+
+printf '%s\n\n' "$body"
+[ -z "$marker" ] || printf '%s\n' "$marker"
+printf '%s`%s` · [Muggle Works](%s)_\n' "$SIGNATURE_PREFIX" "$postedCommand" "$REPOSITORY_URL"

package/dist/plugin/skills/CLAUDE.md

@@ -20,6 +20,22 @@ When you feel the urge to link "up" to a caller, that is the smell — restructu
 
 `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.
 
+## Mandatory stages
+
+A `SKILL.md` links out to the files that carry its steps, and nothing forces those links open. Read as a single page, a skill silently loses whatever its stage files required — the step is improvised instead of skipped visibly.
+
+Declare the files a skill cannot be run without in its frontmatter, paths relative to the skill directory:
+
+```yaml
+mandatoryStages:
+  - ../_shared/failure-mode-handling.md
+  - ../_shared/debug-failed-run.md
+```
+
+Invoking the skill names those files as required reading, and a Stop gate holds the turn open until each is opened (`guardrail-skill-stages.sh` / `guardrail-stage-gate.sh`, see [`../hooks/README.md`](../hooks/README.md)). The declaration is explicit rather than inferred from the prose: a gate guessing which links matter blocks on the wrong ones.
+
+The bar is "must be **read** before the skill runs", not "must be executed". A failure protocol qualifies: by the time a run fails, a skill that never read it is already improvising. What does not qualify is a file only one branch consults for its content — the gate cannot tell that the branch was not taken, so it would block work that legitimately never needed it. Aliases declare nothing; they invoke the canonical skill, which carries the declaration.
+
 ## 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.