chore(hooks): scope integ-local-gate to PRs that touch local-execution code

integ-local-gate.sh verified the integ-local marker UNCONDITIONALLY on
every `gh pr merge` / `git merge`, unlike its sibling integ-destroy-gate
and integ-broad-gate which first check whether the merged PR's diff
actually touches their scope. Because the integ-local marker is
file-scoped AND carries a 14d TTL, a marker that has aged out (or been
invalidated by an unrelated src/local change already on main) blocked
EVERY merge -- including pure src/provisioning PRs that touch no local
code at all.

Add the PR-diff scope guard the siblings already have: for
`gh pr merge <N>` the hook now fetches the PR file list via
`gh pr view <N> --json files` and passes the merge through when no path
matches the local-execution scope
(^src/local/|^src/cli/commands/local-*.ts$|^tests/integration/local-).
`git merge` and number-less `gh pr merge` fall through to the
unconditional verify since the incoming diff cannot be cheaply
enumerated. Fail-open on a `gh pr view` error (infra outage must not
block merges), mirroring integ-broad-gate.

Adds 4 smoke-test cases (non-local pass-through, src/local file gate,
tests/integration/local- file gate, gh-failure fail-open) and updates
the hooks.md gate description. No src change.

Author: go-to-k

.claude/hooks/integ-local-gate.sh

@@ -2,13 +2,22 @@
 # integ-local-gate.sh
 #
 # PreToolUse hook. Blocks `gh pr merge` (including --auto) and
-# `git merge` unless the `integ-local` markgate marker is fresh for
-# the current content state. The gate's scope (see .markgate.yml)
-# covers every code path that participates in the `cdkd local *`
-# family (Lambda RIE containers, ECS task emulation, HTTP server,
-# container pool, etc.); editing any of them invalidates the marker
-# and forces a successful Docker-based `/run-integ local-*` run
-# before the PR can be merged.
+# `git merge` when the merged PR actually touches local-execution code
+# AND the `integ-local` markgate marker is not fresh. The gate's scope
+# (see .markgate.yml) covers every code path that participates in the
+# `cdkd local *` family (Lambda RIE containers, ECS task emulation,
+# HTTP server, container pool, etc.); editing any of them invalidates
+# the marker and forces a successful Docker-based `/run-integ local-*`
+# run before the PR can be merged.
+#
+# IMPORTANT — PR-diff scope guard (see below): for `gh pr merge <N>`
+# the hook first checks whether the PR's file list actually touches
+# local-execution scope. A PR that touches NO local code passes
+# through even when the marker is stale, mirroring integ-destroy-gate
+# / integ-broad-gate (which already scope-check). Without this guard a
+# stale marker (14d TTL expiry, or an unrelated src/local change
+# already on main) would block EVERY merge, including pure
+# src/provisioning PRs — the over-fire this guard fixes.
 #
 # This is the structural counterpart for local-execution changes,
 # mirroring `integ-destroy-gate.sh` for deletion logic.
@@ -108,6 +117,66 @@ fi
 
 cd "$target_dir" 2>/dev/null || exit 0
 
+# --- PR-diff scope check (mirrors integ-destroy-gate.sh / integ-broad-gate.sh) ---
+# The markgate scope (.markgate.yml) is file-level, but markgate `verify`
+# cannot tell whether THIS PR's diff actually touches local-execution code.
+# Without this guard a stale `integ-local` marker (14d TTL expiry, or an
+# unrelated src/local change already on main) blocks EVERY merge — including
+# PRs that touch no local code at all (e.g. a pure src/provisioning fix).
+# The sibling gates integ-destroy / integ-broad already scope-check their
+# diff and pass non-matching PRs through; integ-local must do the same.
+#
+# Only applies to `gh pr merge <N>` where we can fetch the PR's file list.
+# `git merge` and number-less `gh pr merge` fall through to the
+# unconditional verify below (conservative — those are rarer and we
+# cannot cheaply enumerate the incoming diff).
+LOCAL_SCOPE_REGEX='^src/local/|^src/cli/commands/local-[A-Za-z0-9_-]*\.ts$|^tests/integration/local-'
+
+if printf '%s' "$cmd" | grep -qE 'gh([[:space:]]+-C[[:space:]]+[^[:space:]]+)?[[:space:]]+pr[[:space:]]+merge'; then
+  pr_number=""
+  args="${cmd#*merge}"
+  # shellcheck disable=SC2086
+  set -- $args
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --*=*) shift; continue ;;
+      --auto|--admin|--delete-branch|--squash|--merge|--rebase) shift; continue ;;
+      -*) shift; [ $# -gt 0 ] && shift; continue ;;
+      *)
+        if printf '%s' "$1" | grep -qE '^[0-9]+$'; then
+          pr_number="$1"
+          break
+        fi
+        shift
+        ;;
+    esac
+  done
+
+  if [ -n "$pr_number" ]; then
+    # Pass-through on any gh error so an unrelated infra outage does not
+    # block merges (mirrors integ-broad-gate.sh / pr-review-gate.sh).
+    pr_json=$(gh pr view "$pr_number" --json files 2>/dev/null) || {
+      printf 'integ-local-gate: gh pr view %s failed; allowing merge (infra fail-open)\n' "$pr_number" >&2
+      exit 0
+    }
+    paths=$(printf '%s' "$pr_json" | jq -r '.files[].path' 2>/dev/null || echo "")
+    touches_local=0
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      if printf '%s' "$f" | grep -qE "$LOCAL_SCOPE_REGEX"; then
+        touches_local=1
+        break
+      fi
+    done <<EOF_FILES
+$paths
+EOF_FILES
+    # No local-execution file in the PR diff -> this gate does not apply.
+    if [ "$touches_local" -eq 0 ]; then
+      exit 0
+    fi
+  fi
+fi
+
 # Prefer the `.mise.toml`-pinned version via `mise exec --` so the repo's
 # canonical markgate wins over an older PATH binary; see check-gate.sh for
 # the schema-bump rationale (0.3.0 markers are silently invisible to 0.3.1).

.claude/hooks/integ-local-gate.test.sh

@@ -142,6 +142,57 @@ run_case "gh issue body quoting 'gh pr merge' passes through" 0 \
 run_case "echo body quoting 'git merge' passes through" 0 \
   "$(printf '{"cwd":"%s","tool_input":{"command":"echo \"reminder: git merge origin/main when ready\""}}' "$fixture_repo")"
 
+# --- PR-DIFF SCOPE-CHECK cases (mirrors integ-destroy / integ-broad gates) ---
+#
+# For `gh pr merge <N>` WITH a PR number, the gate fetches the PR's file
+# list via `gh pr view <N> --json files` and passes through when no file
+# touches local-execution scope (src/local/** / src/cli/commands/local-*.ts
+# / tests/integration/local-*). A stub `gh` on PATH returns a controlled
+# file list; the real markgate (stale in this checkout) drives the
+# fires-when-relevant case to exit 2.
+GH_STUB_DIR="$TMPDIR/ghstub"
+mkdir -p "$GH_STUB_DIR"
+GH_FILES_PAYLOAD="$TMPDIR/gh-files.json"
+cat > "$GH_STUB_DIR/gh" <<'GH_EOF'
+#!/usr/bin/env bash
+if [ "${1:-} ${2:-}" = "pr view" ]; then
+  if [ "${GH_STUB_FAIL:-}" = "1" ]; then exit 1; fi
+  cat "$GH_FILES_PAYLOAD"
+  exit 0
+fi
+exit 0
+GH_EOF
+chmod +x "$GH_STUB_DIR/gh"
+export GH_FILES_PAYLOAD
+OLD_PATH="$PATH"
+export PATH="$GH_STUB_DIR:$PATH"
+
+# 17. PR with a number whose files are all NON-local -> scope check
+#     passes the merge through (exit 0) even though integ-local is stale.
+printf '{"files":[{"path":"src/provisioning/cloud-control-provider.ts"},{"path":"docs/changelog-cdkd.md"}]}' > "$GH_FILES_PAYLOAD"
+GH_STUB_FAIL="" run_case "gh pr merge <N> non-local files passes through" 0 \
+  "$(printf '{"cwd":"%s","tool_input":{"command":"gh pr merge 999 --squash --delete-branch"}}' "$fixture_repo")"
+
+# 18. PR with a number whose files include a local-execution file ->
+#     scope check engages, the (stale) marker blocks the merge (exit 2).
+printf '{"files":[{"path":"src/local/docker-runner.ts"},{"path":"docs/changelog-cdkd.md"}]}' > "$GH_FILES_PAYLOAD"
+GH_STUB_FAIL="" run_case "gh pr merge <N> with src/local file gate fires" 2 \
+  "$(printf '{"cwd":"%s","tool_input":{"command":"gh pr merge 999 --squash"}}' "$fixture_repo")"
+
+# 19. PR with a number whose files include a tests/integration/local-*
+#     fixture -> scope check engages, stale marker blocks (exit 2).
+printf '{"files":[{"path":"tests/integration/local-invoke/verify.sh"}]}' > "$GH_FILES_PAYLOAD"
+GH_STUB_FAIL="" run_case "gh pr merge <N> with tests/integration/local- file gate fires" 2 \
+  "$(printf '{"cwd":"%s","tool_input":{"command":"gh pr merge 999"}}' "$fixture_repo")"
+
+# 20. `gh pr view` failure -> fail-open (exit 0), an infra outage must
+#     not block merges (mirrors integ-broad-gate.sh).
+printf '{"files":[{"path":"src/local/docker-runner.ts"}]}' > "$GH_FILES_PAYLOAD"
+GH_STUB_FAIL="1" run_case "gh pr view failure fails open" 0 \
+  "$(printf '{"cwd":"%s","tool_input":{"command":"gh pr merge 999 --squash"}}' "$fixture_repo")"
+
+export PATH="$OLD_PATH"
+
 echo
 echo "Pass: $pass  Fail: $fail"
 if [[ "$fail" -gt 0 ]]; then

.claude/rules/hooks.md

@@ -48,6 +48,8 @@ All eleven produce actionable error messages with the exact replacement command.
 
 The seven markgate-backed gate hooks (`check-gate.sh`, `verify-pr-gate.sh`, `integ-destroy-gate.sh`, `integ-broad-gate.sh`, `integ-local-gate.sh`, `integ-schema-migration-gate.sh`, `pr-review-gate.sh`) are all **cwd-aware** post-#559. Each reads the PreToolUse payload's `cwd` field plus parses leading `cd <path>` and the last `git -C <path>` / `gh -C <path>` flag from the command, then `cd`s to that resolved target dir before invoking `markgate verify`. This restores markgate's per-worktree marker isolation — pre-#559 the hooks always landed in the main tree via `git rev-parse --git-common-dir`'s parent, forcing every parallel agent to converge on the main tree's marker store (the actual root cause of the cross-agent edit-race documented in memory rule `feedback_cross_agent_main_tree_contention.md`).
 
+**PR-diff scope guards (integ-destroy / integ-broad / integ-local).** The three integ gates that fire on `gh pr merge` first check whether the merged PR's diff actually touches their scope before consulting the marker — `integ-destroy-gate` greps the changed files against its delete-logic patterns, `integ-broad-gate` against `CROSS_CUTTING_REGEX`, and `integ-local-gate` against `^src/local/|^src/cli/commands/local-*\.ts$|^tests/integration/local-` (via `gh pr view <N> --json files`). A PR that touches none of a gate's scope passes that gate through even when its marker is stale. This matters because the integ markers carry a 14d TTL and are file-scoped: without the per-gate diff guard an expired (or unrelated-change-invalidated) marker would block EVERY merge, including PRs touching none of that gate's code. `integ-local-gate` gained this guard to match its siblings (it previously verified the marker unconditionally, so a stale `integ-local` blocked even pure `src/provisioning` merges); `git merge` and number-less `gh pr merge` still fall through to the unconditional verify since the incoming diff cannot be cheaply enumerated.
+
 **Convention shift (post-#559)**: `markgate set <gate>` must be run from the same worktree (cwd) where the gated command (`git commit` / `gh pr create` / `gh pr merge`) will eventually be invoked. Concurrent agents in different worktrees no longer collide because each worktree has its own markgate state dir (`<worktree>/.git/worktrees/<name>/markgate/` for side worktrees, `<main>/.git/markgate/` for the main tree). The `.markgate-pr-review-sha` sentinel is already per-worktree by construction (each worktree has its own root), so no change there.
 
 **Backward compat**: a user who does everything from the main tree (the historical default) sees no behavior change — `tool_input.cwd` resolves to the main tree, the hook reads the main tree's markgate state. Agents who previously relied on the "set marker from main tree, merge from anywhere" pattern need to update their flow to set markers from the worktree they merge from; the `/review-pr` skill was updated accordingly.