fix(claude-blocking-review): distinct skip reasons + SHA-scoped skip marker (v3.1.0)

[twistedmelonman]

Summary

Implements Part A1 of the reusable-workflows plan: two bug fixes to claude-blocking-review.yml, bumping to v3.1.0.

#86 — misleading skip log message. The Check review verdict step's short-circuit for skip paths used a single hardcoded "Doc-only skip" message regardless of which of three skip paths actually fired (workflow-self-modification, doc-only diff, Dependabot PR). Each skip path now writes its own skip/skip_reason output pair, and the verdict-check step logs the actual reason that fired.

#88 — unscoped skip marker silently bypasses all future runs. [skip-claude-review: reason] in the PR body was checked live with no scoping — once added, it silently bypassed every subsequent run on that PR, including runs against later, never-reviewed commits.

Fix (per the plan's adversarially-reviewed redesign, not the issue's original simpler suggestion):

• New syntax: [skip-claude-review sha=<short-sha>: reason], matched against github.event.pull_request.head.sha (not github.sha, which is a synthetic merge-commit SHA on pull_request events) with a minimum 7-character prefix requirement to prevent a trivial bypass like sha=a.
• Old-style unscoped markers continue to work exactly as today — unconditional skip, no SHA check. This is deliberate grandfathering, not a bug to "fix."
• A sha=-scoped marker that doesn't match the current head SHA now emits a visible ::notice:: (with both SHAs) instead of silently doing nothing.
• Documented (workflow header + README) that the correct way to make a freshly-added scoped marker take effect is gh run rerun <run-id> on the existing failed/blocked run — not a new commit/push, since a new push changes the head SHA and correctly invalidates a SHA-scoped marker (intentional anti-staleness behavior).

A second commit fixes the same escape-hatch check in the "Minimize PASS review comment" step, which the pre-push whole-codebase review caught was still using the pre-#88 regex and wouldn't recognize the new sha=-scoped form (closes #91, filed automatically by that review).

Both changes are additive/non-breaking — existing unscoped markers behave identically. Bumped to v3.1.0.

Changes

• .github/workflows/claude-blocking-review.yml:
  • skip_reason output added to all three skip-detection branches (workflow-self-mod, doc-only, Dependabot)
  • Check review verdict step reads per-path skip_reason and logs the actual cause
  • SHA-scoped skip marker parsing and matching logic (7+ char prefix, github.event.pull_request.head.sha)
  • ::notice:: emitted when a scoped marker exists but doesn't match current head
  • "Minimize PASS review comment" step's escape-hatch check aligned with the same scoped/unscoped logic
  • Header comment documents the new syntax, grandfathering, and the gh run rerun recovery procedure
• README.md: escape-hatch section expanded with the sha= syntax, scoping behavior, and the gh run rerun-not-a-new-commit guidance

Verification

• YAML validated with yamllint (clean)
• Shell logic extracted and checked with shellcheck -S info (only pre-existing-style SC2312 info notes, matching the file's established idiom)
• Standalone bash harness exercised all branches of the SHA-prefix matching (unscoped, scoped-match, scoped-mismatch, too-short-reject) — all behave as designed
• Local pre-commit/pre-push review (code-reviewer + adversarial-reviewer, with arbiter) passed on both commits
• No existing test suite in this repo (workflow-only, no build/test/lint commands per repo convention)

Tagging / release

Per repo convention (confirmed via git log/tag dates: v3.0.0/v3 were both created immediately after PR #62 merged, pointing at the merge commit on main), tagging happens after merge — not part of this PR. After merge, will create v3.1.0 + move floating v3 to it, and a matching GitHub Release with notes covering both fixes.

Closes #86
Closes #88

https://claude.ai/code/session_0143Nf4sXqnTp2Kx3LNbMvBA