feat: add gh-aw compilation hooks for workflow editing

- PostToolUse hook reminds to compile after .md workflow edits
- Stop hook blocks if workflows have stale/missing lock files
- Both hooks detect version drift between installed gh-aw and lock files

Author: zircote

hooks/check-uncompiled-workflows.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Stop hook: check for uncompiled gh-aw workflow changes before Claude finishes.
+# Blocks if any .github/workflows/*.md files have been modified but their
+# corresponding .lock.yml files are stale or missing.
+
+set -euo pipefail
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+
+if [[ -z "$CWD" ]]; then
+	exit 0
+fi
+
+cd "$CWD"
+
+# Check if this repo has any gh-aw workflow .md files
+WORKFLOW_DIR=".github/workflows"
+if [[ ! -d "$WORKFLOW_DIR" ]]; then
+	exit 0
+fi
+
+# Find .md workflow files (skip if none exist)
+MD_FILES=$(find "$WORKFLOW_DIR" -maxdepth 1 -name '*.md' -type f 2>/dev/null || true)
+if [[ -z "$MD_FILES" ]]; then
+	exit 0
+fi
+
+# Check for modified .md files whose .lock.yml is older or missing
+STALE=()
+MISSING=()
+
+while IFS= read -r md; do
+	wf_id=$(basename "$md" .md)
+	lock="${WORKFLOW_DIR}/${wf_id}.lock.yml"
+
+	if [[ ! -f "$lock" ]]; then
+		MISSING+=("$wf_id")
+	elif [[ "$md" -nt "$lock" ]]; then
+		STALE+=("$wf_id")
+	fi
+done <<<"$MD_FILES"
+
+# Also check version drift
+INSTALLED=""
+if command -v gh &>/dev/null && gh extension list 2>/dev/null | grep -q 'gh-aw'; then
+	INSTALLED=$(gh aw version 2>&1 | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || true)
+fi
+
+DRIFT=()
+if [[ -n "$INSTALLED" ]]; then
+	while IFS= read -r md; do
+		wf_id=$(basename "$md" .md)
+		lock="${WORKFLOW_DIR}/${wf_id}.lock.yml"
+		if [[ -f "$lock" ]]; then
+			lock_ver=$(grep -oE 'compiler_version":"v[0-9]+\.[0-9]+\.[0-9]+"' "$lock" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || true)
+			if [[ -n "$lock_ver" && "$lock_ver" != "$INSTALLED" ]]; then
+				DRIFT+=("${wf_id} (${lock_ver})")
+			fi
+		fi
+	done <<<"$MD_FILES"
+fi
+
+# If nothing to report, exit clean
+if [[ ${#STALE[@]} -eq 0 && ${#MISSING[@]} -eq 0 && ${#DRIFT[@]} -eq 0 ]]; then
+	exit 0
+fi
+
+# Build report
+MSG="[gh-aw] Uncompiled workflow changes detected:"
+
+if [[ ${#MISSING[@]} -gt 0 ]]; then
+	MSG+="\n  MISSING lock files (never compiled):"
+	for wf in "${MISSING[@]}"; do
+		MSG+="\n    - ${wf}.md (run: gh aw compile ${wf})"
+	done
+fi
+
+if [[ ${#STALE[@]} -gt 0 ]]; then
+	MSG+="\n  STALE lock files (.md newer than .lock.yml):"
+	for wf in "${STALE[@]}"; do
+		MSG+="\n    - ${wf}.md (run: gh aw compile ${wf})"
+	done
+fi
+
+if [[ ${#DRIFT[@]} -gt 0 ]]; then
+	MSG+="\n  VERSION DRIFT (compiled with older gh-aw, installed: ${INSTALLED}):"
+	for wf in "${DRIFT[@]}"; do
+		MSG+="\n    - ${wf}"
+	done
+fi
+
+# Output the report — Claude will see this and can act on it
+echo -e "$MSG"
+
+# Return structured decision to keep Claude working
+cat <<'EOF'
+{"decision": "block", "reason": "gh-aw workflow .md files have uncompiled changes or version drift. Run `gh aw compile <workflow-id>` for each stale workflow and stage the resulting .lock.yml files before finishing."}
+EOF
+
+exit 0

hooks/check-workflow-edit.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# PostToolUse hook: remind to compile gh-aw workflows after .md edits
+# and check for version drift between installed gh-aw and lock files.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only fire for .github/workflows/*.md files
+if ! echo "$FILE_PATH" | grep -qE '\.github/workflows/.*\.md$'; then
+	exit 0
+fi
+
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+WF_ID=$(basename "$FILE_PATH" .md)
+LOCK_FILE=".github/workflows/${WF_ID}.lock.yml"
+
+# Resolve paths
+if [[ -n "$CWD" ]]; then
+	LOCK_PATH="${CWD}/${LOCK_FILE}"
+	ACTIONS_LOCK="${CWD}/.github/aw/actions-lock.json"
+else
+	LOCK_PATH="$LOCK_FILE"
+	ACTIONS_LOCK=".github/aw/actions-lock.json"
+fi
+
+# Get installed gh-aw version
+INSTALLED=""
+if command -v gh &>/dev/null && gh extension list 2>/dev/null | grep -q 'gh-aw'; then
+	INSTALLED=$(gh aw version 2>&1 | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || true)
+fi
+
+# Get lock file compiler version
+LOCK_VER=""
+if [[ -f "$LOCK_PATH" ]]; then
+	LOCK_VER=$(grep -oE 'compiler_version":"v[0-9]+\.[0-9]+\.[0-9]+"' "$LOCK_PATH" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || true)
+fi
+
+# Get actions-lock.json pinned version
+PINNED=""
+if [[ -f "$ACTIONS_LOCK" ]]; then
+	PINNED=$(grep -oE '"github/gh-aw/actions/setup@v[0-9]+\.[0-9]+\.[0-9]+"' "$ACTIONS_LOCK" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || true)
+fi
+
+# Build reminder
+MSG="[gh-aw] Workflow source modified: ${WF_ID}.md"
+MSG+="\n  Run: gh aw compile ${WF_ID}"
+
+if [[ -n "$INSTALLED" ]]; then
+	MSG+="\n  Installed gh-aw: ${INSTALLED}"
+fi
+
+if [[ -n "$LOCK_VER" && -n "$INSTALLED" && "$LOCK_VER" != "$INSTALLED" ]]; then
+	MSG+="\n  VERSION DRIFT: ${LOCK_FILE} compiled with ${LOCK_VER}, installed is ${INSTALLED}"
+fi
+
+if [[ -n "$PINNED" && -n "$INSTALLED" && "$PINNED" != "$INSTALLED" ]]; then
+	MSG+="\n  VERSION DRIFT: actions-lock.json pins ${PINNED}, installed is ${INSTALLED}"
+fi
+
+if [[ ! -f "$LOCK_PATH" ]]; then
+	MSG+="\n  WARNING: No lock file exists yet — compilation required before commit"
+fi
+
+echo -e "$MSG"
+exit 0

hooks/hooks.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/check-workflow-edit.sh",
+            "statusMessage": "Checking gh-aw workflow status..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/check-uncompiled-workflows.sh",
+            "statusMessage": "Checking for uncompiled gh-aw workflows..."
+          }
+        ]
+      }
+    ]
+  }
+}