@muggleai/works 5.9.0 → 5.11.0

package/plugin/scripts/guardrail-record-stage-read.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# stage-read observer (PostToolUse/Read). Records that a file in the skills tree
+# was opened, which is how the Stop gate tells a mandatory stage that was read
+# from one that was skipped. Emits no directive.
+#
+# Read fires constantly, so only a markdown file living under a `skills/`
+# directory reaches Node — a mandatory stage can be any file in that tree, but
+# never one outside it, so source reads and repo docs return {} in-shell. Both
+# path separators are accepted: a Windows payload carries escaped backslashes.
+# Degrades to {}.
+payload="$(cat)"
+
+if ! grep -Eiq '"file_path"[[:space:]]*:[[:space:]]*"[^"]*[/\\]+skills[/\\]+[^"]*\.md"' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" record-stage-read 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-record-stage-signals.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# stage-signal observer (PostToolUse/Bash + muggle telemetry and feedback tools).
+# Records the three things the stage gates settle from: a Step 6f
+# pre-execution-classification emit, debug-path evidence for a failed run (a
+# failure-classified emit or feedback naming it), and the skip markers each gate
+# documents as its way out. Emits no directive — the gates read the state.
+#
+# The marker arm matches the MUGGLE_<GATE>_SKIP shape, never one token: a gate
+# whose marker is missing from a hand-listed set instructs the user to run an
+# echo that can never register, then blocks the turn anyway. Anchoring the
+# marker to a leading `echo` stays in guardrails.mjs; over-matching here only
+# costs a needless spawn. Degrades to {}.
+payload="$(cat)"
+
+if ! grep -Eiq 'MUGGLE_[A-Z0-9_]+_SKIP|muggle.*(telemetry-event-emit|user-feedback-create)' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" record-stage-signals 2>/dev/null || printf '{}'

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

@@ -10,12 +10,19 @@ set -uo pipefail
 # 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, 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 {}.
+# emit (registers a clean-SKIP verdict as an E2E run), a skip marker, or a PR
+# publish carrying a rendered walkthrough reaches guardrails.mjs, which then
+# inspects the output for pass/fail and updates state. Degrades to {}.
+#
+# The marker arm matches the MUGGLE_<GATE>_SKIP shape, never one token: every
+# Stop gate documents its own marker as the escape hatch, and a per-token list
+# left the watcher and walkthrough markers unreachable — the gates instructed
+# the user to run an echo that could never reach the recorder, then blocked the
+# turn anyway. Anchoring the marker to a leading `echo` stays in guardrails.mjs;
+# over-matching here only costs a needless spawn.
 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-local-telemetry-skill-emit|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_[A-Z0-9_]+_SKIP|gh[[:space:]]+pr[[:space:]]+(comment|create|edit)|issues/comments/[0-9]' <<<"$payload"; then
   printf '{}'
   exit 0
 fi

package/plugin/scripts/guardrail-report-format.sh

@@ -7,14 +7,18 @@ set -uo pipefail
 # deterministic renderer.
 #
 # This must stay synchronous (only a sync PreToolUse hook can deny), and it fires
-# before every Bash call. A keyword pre-filter for the three PR-posting commands
+# before every Bash call. A keyword pre-filter for the PR-publishing commands
 # keeps Node off the hot path: a plain `ls`/`git status`/build command returns {}
-# in-shell and never pays cold-start. Only a `gh pr comment|create|edit` reaches
-# guardrails.mjs, which reads the body (incl. --body-file) and decides. Degrades
-# to {} so it never blocks an unrelated command.
+# in-shell and never pays cold-start. Only a `gh pr comment|create|edit` or a
+# `gh api` comment edit reaches guardrails.mjs, which reads the body (incl.
+# --body-file) and decides. The comment-edit arm matters as much as the post
+# arm: guardrails.mjs gates that path precisely so a sanctioned walkthrough
+# can't be overwritten with hand-written markdown afterwards, and a pre-filter
+# on `gh pr` alone left that bypass wide open. Degrades to {} so it never blocks
+# an unrelated command.
 payload="$(cat)"
 
-if ! grep -Eiq 'gh[[:space:]]+pr[[:space:]]+(comment|create|edit)' <<<"$payload"; then
+if ! grep -Eiq 'gh[[:space:]]+pr[[:space:]]+(comment|create|edit)|issues/comments/[0-9]' <<<"$payload"; then
   printf '{}'
   exit 0
 fi

package/plugin/scripts/guardrail-skill-stages.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# mandatory-stage recorder (PostToolUse/Skill). Records which skill is running
+# and, when its SKILL.md declares `mandatoryStages`, returns those files as
+# required reading at the moment of use. The Stop gate
+# (guardrail-stage-gate.sh) blocks the turn end while any of them is unread.
+#
+# Skill calls are rare, so the pre-filter is a file test rather than a keyword
+# scan: the invoked name is pulled out of the payload and Node runs only when it
+# resolves to a skill this plugin actually ships. Another plugin's skill, or an
+# input with no skill name, returns {} in-shell. Every key the resolver reads is
+# accepted here — a key matched in one and missed in the other makes the gate
+# dead code on exactly the harness that names it that way. Degrades to {}.
+payload="$(cat)"
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+
+for candidate in $(printf '%s' "$payload" \
+  | grep -oE '"(skill|skillName|name|command)"[[:space:]]*:[[:space:]]*"[^"]*"' \
+  | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/'); do
+  # A namespaced invocation (`muggle:muggle-test`) and a slash command
+  # (`/muggle-test`) both name the same skill directory.
+  skill="${candidate##*:}"
+  skill="${skill#/}"
+  case "$skill" in
+    "" | *[!A-Za-z0-9._-]*) continue ;;
+  esac
+  if [ -f "$root/skills/$skill/SKILL.md" ]; then
+    printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" skill-stages 2>/dev/null || printf '{}'
+    exit 0
+  fi
+done
+
+printf '{}'

package/plugin/scripts/guardrail-stage-gate.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# mandatory-stage gate (Stop). When a skill invoked this session declared
+# `mandatoryStages` in its SKILL.md and any of those files was never opened,
+# block the turn end naming them (or the MUGGLE_STAGE_SKIP escape hatch). This
+# is the root fix for a skill read as a single page: the SKILL.md links out to
+# steps that are mandatory, nothing forced them open, and the steps were
+# silently dropped.
+#
+# Mirrors guardrail-watch-gate.sh: synchronous (only a sync Stop hook can block
+# the turn end), fires on EVERY turn end, and pre-filters in shell so Node spawns
+# only when a stage is actually owed. On the overwhelming majority of turns no
+# skill declared stages, so the state file is absent or mandatoryStages is empty
+# and we return {} in-shell. The read-vs-declared comparison runs in
+# guardrails.mjs. Degrades to {}.
+payload="$(cat)"
+
+raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
+[ -n "$raw_sid" ] || raw_sid="unknown"
+sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+
+# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
+# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
+# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
+home="${HOME:-}"
+if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
+  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
+fi
+
+# Empty array serializes as `"mandatoryStages": []` (one line); a non-empty array
+# spans lines, so the empty match reliably tells them apart.
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"mandatoryStages"' "$state_file" \
+  || grep -q '"mandatoryStages": \[\]' "$state_file" \
+  || grep -q '"stageSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" stage-gate 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-walkthrough-gate.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# acceptance-run → walkthrough gate (Stop). When an E2E acceptance run happened
+# this session and no visual walkthrough has reached the PR, block the turn end
+# until it does or a skip is declared. Fires once per session per PR.
+#
+# This must stay synchronous (only a sync Stop hook can block the turn end), and
+# it fires on EVERY turn end. There is no command payload to key off, so the
+# pre-filter reads the same per-session state file guardrails.mjs uses and only
+# spawns Node when the gate could actually fire — i.e. an acceptance run is
+# recorded and the walkthrough is neither posted nor skipped. On the
+# overwhelming majority of turns (no E2E this session) the state file is absent
+# or e2eRun is unset, so we return {} in-shell and never pay Node cold-start —
+# which also means the gate's `gh` lookups only ever run on turns that could
+# genuinely owe a walkthrough. Degrades to {}.
+payload="$(cat)"
+
+raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
+[ -n "$raw_sid" ] || raw_sid="unknown"
+sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+
+# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
+# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
+# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
+home="${HOME:-}"
+if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
+  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
+fi
+
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"e2eRun": true' "$state_file" \
+  || grep -q '"walkthroughPosted": true' "$state_file" \
+  || grep -q '"walkthroughSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" walkthrough-gate 2>/dev/null || printf '{}'