@bookedsolid/rea 0.1.0

package/hooks/attribution-advisory.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+# PreToolUse hook: attribution-advisory.sh
+# Fires BEFORE every Bash tool call.
+#
+# OPT-IN: Only enforces when .rea/policy.yaml contains:
+#   block_ai_attribution: true
+#
+# When disabled (default), this hook does nothing.
+# When enabled, BLOCKS (exit 2) gh pr create/edit and git commit commands
+# that contain structural AI attribution markers.
+#
+# Exit codes:
+#   0 = allow (disabled, no attribution found, or not a relevant command)
+#   2 = block (attribution detected, or HALT is active)
+
+set -uo pipefail
+
+# ── 1. Read ALL stdin immediately before doing anything else ──────────────────
+INPUT=$(cat)
+
+# ── 2. Dependency check ───────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REA ERROR: jq is required but not installed.\n' >&2
+  printf 'Install: brew install jq  OR  apt-get install -y jq\n' >&2
+  exit 2
+fi
+
+# ── 3. HALT check ─────────────────────────────────────────────────────────────
+REA_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REA_ROOT}/.rea/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REA HALT: %s\nAll agent operations suspended. Run: rea unfreeze\n' \
+    "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
+  exit 2
+fi
+
+# ── 4. Check if attribution blocking is enabled ──────────────────────────────
+POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
+if [ ! -f "$POLICY_FILE" ]; then
+  exit 0
+fi
+if ! grep -qE '^block_ai_attribution:[[:space:]]*true' "$POLICY_FILE" 2>/dev/null; then
+  exit 0
+fi
+
+# ── 5. Parse tool_input.command from the hook payload ─────────────────────────
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [[ -z "$CMD" ]]; then
+  exit 0
+fi
+
+# ── 6. Check if this is a relevant command ────────────────────────────────────
+IS_RELEVANT=0
+
+if printf '%s' "$CMD" | grep -qiE 'gh[[:space:]]+pr[[:space:]]+(create|edit)'; then
+  IS_RELEVANT=1
+fi
+
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+commit'; then
+  IS_RELEVANT=1
+fi
+
+if [[ $IS_RELEVANT -eq 0 ]]; then
+  exit 0
+fi
+
+# ── 7. Check for structural AI attribution markers ───────────────────────────
+
+FOUND=0
+
+# Co-Authored-By with noreply@ email
+if printf '%s' "$CMD" | grep -qiE 'Co-Authored-By:.*noreply@'; then
+  FOUND=1
+fi
+
+# Co-Authored-By with known AI names
+if printf '%s' "$CMD" | grep -qiE 'Co-Authored-By:.*\b(Claude|Sonnet|Opus|Haiku|Copilot|GPT|ChatGPT|Gemini|Cursor|Codeium|Tabnine|Amazon Q|CodeWhisperer|Devin|Windsurf|Cline|Aider|Anthropic|OpenAI|GitHub Copilot)\b'; then
+  FOUND=1
+fi
+
+# "Generated/Built/Powered with/by [AI Tool]" lines
+if printf '%s' "$CMD" | grep -qiE '(Generated|Created|Built|Powered|Authored|Written|Produced)[[:space:]]+(with|by)[[:space:]]+(Claude|Copilot|GPT|ChatGPT|Gemini|Cursor|Codeium|Tabnine|CodeWhisperer|Devin|Windsurf|Cline|Aider|AI|an? AI)\b'; then
+  FOUND=1
+fi
+
+# Markdown-linked attribution
+if printf '%s' "$CMD" | grep -qiE '\[Claude Code\]|\[GitHub Copilot\]|\[ChatGPT\]|\[Gemini\]|\[Cursor\]'; then
+  FOUND=1
+fi
+
+# Emoji attribution
+if printf '%s' "$CMD" | grep -qE '🤖.*[Gg]enerated'; then
+  FOUND=1
+fi
+
+if [[ $FOUND -eq 1 ]]; then
+  {
+    printf '\n'
+    printf '═══════════════════════════════════════════════════════════════════\n'
+    printf '  BLOCKED: AI attribution detected in command\n'
+    printf '═══════════════════════════════════════════════════════════════════\n'
+    printf '\n'
+    printf '  Your command contains structural AI attribution markers.\n'
+    printf '\n'
+    printf '  What gets BLOCKED (structural attribution):\n'
+    printf '    - Co-Authored-By with AI names or noreply@ emails\n'
+    printf '    - "Generated with/by [AI Tool]" footer lines\n'
+    printf '    - Markdown-linked tool names: [Claude Code](...)\n'
+    printf '    - Emoji attribution: 🤖 Generated...\n'
+    printf '\n'
+    printf '  What is ALLOWED (legitimate references):\n'
+    printf '    - "Fix Claude API integration"\n'
+    printf '    - "Update OpenAI SDK version"\n'
+    printf '    - "Add Copilot config"\n'
+    printf '\n'
+    printf '  Remove the attribution markers and rewrite the command.\n'
+    printf '  To disable: set block_ai_attribution: false in .rea/policy.yaml\n'
+    printf '═══════════════════════════════════════════════════════════════════\n'
+    printf '\n'
+  } >&2
+  exit 2
+fi
+
+# No attribution found — allow
+exit 0

package/hooks/blocked-paths-enforcer.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+# PreToolUse hook: blocked-paths-enforcer.sh
+# Fires BEFORE every Write or Edit tool call.
+# Reads blocked_paths from .rea/policy.yaml and blocks matching writes.
+#
+# This enforces the policy layer at the hook level — even if an agent ignores
+# the CLAUDE.md rules or skips the orchestrator, the hook will catch it.
+#
+# Exit codes:
+#   0 = allow (path not blocked)
+#   2 = block (path matches a blocked_paths entry)
+
+set -uo pipefail
+
+# ── 1. Read ALL stdin immediately ─────────────────────────────────────────────
+INPUT=$(cat)
+
+# ── 2. Dependency check ──────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REA ERROR: jq is required but not installed.\n' >&2
+  printf 'Install: brew install jq  OR  apt-get install -y jq\n' >&2
+  exit 2
+fi
+
+# ── 3. HALT check ────────────────────────────────────────────────────────────
+REA_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REA_ROOT}/.rea/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REA HALT: %s\nAll agent operations suspended. Run: rea unfreeze\n' \
+    "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
+  exit 2
+fi
+
+# ── 4. Extract file path from payload ─────────────────────────────────────────
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# ── 5. Load blocked_paths from policy ─────────────────────────────────────────
+POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
+
+if [[ ! -f "$POLICY_FILE" ]]; then
+  exit 0
+fi
+
+# Parse blocked_paths using grep + sed (avoid yaml parser dependency)
+# Handles both inline array [] and block sequence - "..." formats
+BLOCKED_PATHS=()
+IN_BLOCK=0
+while IFS= read -r line; do
+  # Check if we're entering blocked_paths section
+  if printf '%s' "$line" | grep -qE '^blocked_paths:'; then
+    # Check for inline empty array
+    if printf '%s' "$line" | grep -qE 'blocked_paths:[[:space:]]*\[\]'; then
+      break
+    fi
+    # Check for inline array with values
+    if printf '%s' "$line" | grep -qE 'blocked_paths:[[:space:]]*\['; then
+      # Extract inline array items
+      items=$(printf '%s' "$line" | sed 's/.*\[//; s/\].*//; s/,/ /g')
+      for item in $items; do
+        cleaned=$(printf '%s' "$item" | sed "s/^[[:space:]]*[\"']//; s/[\"'][[:space:]]*$//")
+        if [[ -n "$cleaned" ]]; then
+          BLOCKED_PATHS+=("$cleaned")
+        fi
+      done
+      break
+    fi
+    IN_BLOCK=1
+    continue
+  fi
+
+  if [[ $IN_BLOCK -eq 1 ]]; then
+    # Block sequence items start with "  - "
+    if printf '%s' "$line" | grep -qE '^[[:space:]]+-'; then
+      cleaned=$(printf '%s' "$line" | sed 's/^[[:space:]]*-[[:space:]]*//; s/^"//; s/"$//; s/^'"'"'//; s/'"'"'$//')
+      if [[ -n "$cleaned" ]]; then
+        BLOCKED_PATHS+=("$cleaned")
+      fi
+    else
+      # Non-indented line means we've left the block
+      break
+    fi
+  fi
+done < "$POLICY_FILE"
+
+if [[ ${#BLOCKED_PATHS[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+# ── 6. Agent-writable allowlist ───────────────────────────────────────────────
+# These paths under .rea/ must always be writable by agents regardless of
+# what blocked_paths says. Blocking the whole .rea/ directory in policy
+# is a common default, but tasks.jsonl is the PM data store — agents must
+# write there. Settings-protection.sh guards the sensitive files explicitly.
+AGENT_WRITABLE=(
+  '.rea/tasks.jsonl'
+  '.rea/audit/'
+)
+
+normalize_path() {
+  local p="$1"
+  local root="$REA_ROOT"
+  if [[ "$p" == "$root"/* ]]; then
+    p="${p#$root/}"
+  fi
+  p=$(printf '%s' "$p" | sed 's/%2[Ff]/\//g; s/%2[Ee]/./g; s/%20/ /g')
+  p="${p#./}"
+  printf '%s' "$p"
+}
+
+NORMALIZED=$(normalize_path "$FILE_PATH")
+
+for writable in "${AGENT_WRITABLE[@]}"; do
+  if [[ "$NORMALIZED" == "$writable" ]] || [[ "$NORMALIZED" == "$writable"* && "$writable" == */ ]]; then
+    exit 0
+  fi
+done
+
+# ── 7. Match against blocked_paths ───────────────────────────────────────────
+LOWER_NORM=$(printf '%s' "$NORMALIZED" | tr '[:upper:]' '[:lower:]')
+
+for blocked in "${BLOCKED_PATHS[@]}"; do
+  LOWER_BLOCKED=$(printf '%s' "$blocked" | tr '[:upper:]' '[:lower:]')
+
+  # Directory match (blocked path ends with /)
+  if [[ "$LOWER_BLOCKED" == */ ]]; then
+    if [[ "$LOWER_NORM" == "$LOWER_BLOCKED"* ]] || [[ "$LOWER_NORM" == "${LOWER_BLOCKED%/}" ]]; then
+      {
+        printf 'BLOCKED PATH: Write denied by policy\n'
+        printf '\n'
+        printf '  File: %s\n' "$FILE_PATH"
+        printf '  Blocked by: %s\n' "$blocked"
+        printf '  Source: .rea/policy.yaml → blocked_paths\n'
+        printf '\n'
+        printf '  This path is protected by policy. To modify it, a human must\n'
+        printf '  either update blocked_paths in policy.yaml or edit the file directly.\n'
+      } >&2
+      exit 2
+    fi
+    continue
+  fi
+
+  # Glob pattern match (contains *)
+  if [[ "$blocked" == *'*'* ]]; then
+    # Convert glob to regex: . → \., * → .*
+    regex=$(printf '%s' "$LOWER_BLOCKED" | sed 's/\./\\./g; s/\*/.*/g')
+    if printf '%s' "$LOWER_NORM" | grep -qE "^${regex}$"; then
+      {
+        printf 'BLOCKED PATH: Write denied by policy\n'
+        printf '\n'
+        printf '  File: %s\n' "$FILE_PATH"
+        printf '  Blocked by: %s (glob pattern)\n' "$blocked"
+        printf '  Source: .rea/policy.yaml → blocked_paths\n'
+      } >&2
+      exit 2
+    fi
+    continue
+  fi
+
+  # Exact match
+  if [[ "$LOWER_NORM" == "$LOWER_BLOCKED" ]]; then
+    {
+      printf 'BLOCKED PATH: Write denied by policy\n'
+      printf '\n'
+      printf '  File: %s\n' "$FILE_PATH"
+      printf '  Blocked by: %s\n' "$blocked"
+      printf '  Source: .rea/policy.yaml → blocked_paths\n'
+    } >&2
+    exit 2
+  fi
+done
+
+exit 0

package/hooks/changeset-security-gate.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# changeset-security-gate.sh — PreToolUse: Write|Edit
+#
+# Guards .changeset/*.md files against two failure modes:
+#
+# 1. SECURITY DISCLOSURE LEAK — GHSA IDs or CVE numbers written to a changeset
+#    file before the advisory is published. Changeset files are committed to git
+#    and appear verbatim in CHANGELOG.md — referencing a GHSA ID pre-publish
+#    creates public pre-disclosure in git history.
+#
+# 2. MISSING OR MALFORMED FRONTMATTER — changeset files without proper frontmatter
+#    are silently ignored by the changesets tool, wasting the release entry.
+#
+# Triggered by: PreToolUse — Write and Edit tools
+
+set -euo pipefail
+
+# shellcheck source=_lib/common.sh
+source "$(dirname "$0")/_lib/common.sh"
+
+check_halt
+
+INPUT="$(cat)"
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+# Only handle Write and Edit
+if [[ "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only care about .changeset/*.md files — exclude README.md (changeset tool metadata)
+if ! echo "$FILE_PATH" | grep -qE '\.changeset/[^/]+\.md$' || echo "$FILE_PATH" | grep -qE '\.changeset/README\.md$'; then
+  exit 0
+fi
+
+require_jq
+
+# Extract the content being written
+if [[ "$TOOL_NAME" == "Write" ]]; then
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
+else
+  # For Edit: check the new_string being inserted
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""')
+fi
+
+# ─── 1. SECURITY DISCLOSURE CHECK ───────────────────────────────────────────
+#
+# These patterns in a changeset mean security details are about to be committed
+# to git history BEFORE the advisory is published — creating pre-disclosure.
+# GHSA IDs and CVE numbers must NEVER appear in changeset files.
+
+DISCLOSURE_PATTERNS=(
+  'GHSA-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}'
+  'CVE-[0-9]{4}-[0-9]+'
+)
+
+MATCHED_PATTERN=""
+for PATTERN in "${DISCLOSURE_PATTERNS[@]}"; do
+  if echo "$CONTENT" | grep -qE "$PATTERN"; then
+    MATCHED_PATTERN="$PATTERN"
+    break
+  fi
+done
+
+if [[ -n "$MATCHED_PATTERN" ]]; then
+  json_output "block" \
+    "CHANGESET SECURITY GATE: This changeset contains a security advisory identifier (matched: '${MATCHED_PATTERN}').
+
+Do NOT reference GHSA IDs or CVE numbers in changeset files before the advisory is published.
+Changeset files are committed to git — this creates pre-disclosure in public history and CHANGELOG.
+
+CORRECT approach for security fix changesets:
+  Use vague language only — no identifiers, no vulnerability details.
+
+  WRONG:  'fix(hooks): patch GHSA-3w3m-7gg4-f82g — symlink-guard now covers Edit tool'
+  RIGHT:  'security: extend symlink protection to cover all write-capable tools'
+
+  WRONG:  'security: fix CVE-2026-1234 prompt injection via tool descriptions'
+  RIGHT:  'security: harden middleware chain against indirect instruction attacks'
+
+After the release ships:
+  1. Publish the GitHub Security Advisory (Security tab → Advisories → Publish)
+  2. The GHSA becomes the detailed public disclosure document
+  3. Optionally update CHANGELOG.md post-publish to add the GHSA reference"
+fi
+
+# ─── 2. FRONTMATTER VALIDATION ───────────────────────────────────────────────
+#
+# A changeset without valid frontmatter is silently ignored by the changesets
+# tool — the package bump and CHANGELOG entry never appear in the release.
+
+# Must start with ---
+if ! echo "$CONTENT" | head -1 | grep -qE '^---'; then
+  json_output "block" \
+    "CHANGESET FORMAT GATE: Missing frontmatter block.
+
+Every changeset must start with a frontmatter block specifying which package to bump:
+
+---
+'@bookedsolid/rea': patch
+---
+
+Brief description of what changed and why (close #N if applicable).
+
+Bump types: patch (bug fix/security), minor (new feature), major (breaking change)"
+fi
+
+# Must have at least one package bump entry and a closing ---
+FRONTMATTER=$(echo "$CONTENT" | awk '/^---/{count++; if(count==2){exit} next} count==1{print}')
+if ! echo "$FRONTMATTER" | grep -qE "^'.+': (patch|minor|major)"; then
+  json_output "block" \
+    "CHANGESET FORMAT GATE: Frontmatter does not contain a valid package bump entry.
+
+The frontmatter must include at least one package/bump pair:
+
+---
+'@bookedsolid/rea': patch
+---
+
+Valid bump types: patch | minor | major"
+fi
+
+# Must have a non-empty description after the closing ---
+DESCRIPTION=$(echo "$CONTENT" | awk 'BEGIN{count=0} /^---/{count++; next} count>=2{print}' | grep -v '^[[:space:]]*$' | head -1 || true)
+if [[ -z "$DESCRIPTION" ]]; then
+  json_output "block" \
+    "CHANGESET FORMAT GATE: Missing description after frontmatter.
+
+Add a meaningful description explaining what changed and why:
+
+---
+'@bookedsolid/rea': patch
+---
+
+fix(gateway): policy-loader now uses async I/O with 500ms TTL cache
+
+Previously, loadPolicy used fs.readFileSync on every tool invocation, blocking
+the event loop under concurrency. Closes #34."
+fi
+
+exit 0

package/hooks/commit-review-gate.sh

@@ -0,0 +1,166 @@
+#!/bin/bash
+# PreToolUse hook: commit-review-gate.sh
+# Fires BEFORE every Bash tool call that matches "git commit".
+# Implements a triage-based review gate:
+#   - trivial (<20 changed lines, non-sensitive paths) → pass immediately
+#   - standard (20-200 lines) → check review cache, pass if cached
+#   - significant (>200 lines or sensitive paths) → block, request agent review
+#
+# Exit codes:
+#   0 = allow (trivial change, or cached review found)
+#   2 = block (needs review — returns additionalContext for agent)
+
+set -uo pipefail
+
+# ── 1. Read ALL stdin immediately ─────────────────────────────────────────────
+INPUT=$(cat)
+
+# ── 2. Dependency check ──────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REA ERROR: jq is required but not installed.\n' >&2
+  printf 'Install: brew install jq  OR  apt-get install -y jq\n' >&2
+  exit 2
+fi
+
+# ── 3. HALT check ────────────────────────────────────────────────────────────
+REA_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REA_ROOT}/.rea/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REA HALT: %s\nAll agent operations suspended. Run: rea unfreeze\n' \
+    "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
+  exit 2
+fi
+
+# ── 4. Parse command ──────────────────────────────────────────────────────────
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [[ -z "$CMD" ]]; then
+  exit 0
+fi
+
+# Only trigger on git commit commands
+if ! printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+commit'; then
+  exit 0
+fi
+
+# Skip --amend (reviewing amendments is a future feature)
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+commit.*--amend'; then
+  exit 0
+fi
+
+# ── 5. Check if quality gates are enabled ─────────────────────────────────────
+# Fail-open if policy doesn't exist or doesn't have quality_gates
+POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
+if [[ -f "$POLICY_FILE" ]]; then
+  if grep -qE '^quality_gates:' "$POLICY_FILE" 2>/dev/null; then
+    if grep -qE 'commit_review:[[:space:]]*false' "$POLICY_FILE" 2>/dev/null; then
+      exit 0
+    fi
+  fi
+fi
+
+# ── 6. Compute diff stats ────────────────────────────────────────────────────
+# Get staged diff (what would be committed)
+DIFF_OUTPUT=$(cd "$REA_ROOT" && git diff --cached --stat 2>/dev/null || echo "")
+DIFF_FULL=$(cd "$REA_ROOT" && git diff --cached 2>/dev/null || echo "")
+
+if [[ -z "$DIFF_OUTPUT" ]]; then
+  # No staged changes — let git commit handle the error
+  exit 0
+fi
+
+# Count changed lines (additions + deletions)
+LINE_COUNT=$(printf '%s' "$DIFF_FULL" | grep -cE '^\+[^+]|^-[^-]' 2>/dev/null || echo "0")
+
+# Check for sensitive paths
+SENSITIVE=0
+SENSITIVE_FILES=""
+if printf '%s' "$DIFF_FULL" | grep -qE '^\+\+\+ .*(\.rea/|\.claude/|\.env|auth|security|\.github/workflows)'; then
+  SENSITIVE=1
+  SENSITIVE_FILES=$(printf '%s' "$DIFF_FULL" | grep -oE '^\+\+\+ .*(\.rea/|\.claude/|\.env|auth|security|\.github/workflows)[^ ]*' | sed 's/^\+\+\+ [ab]\//  /' | head -5)
+fi
+
+# ── 7. Triage scoring ────────────────────────────────────────────────────────
+TRIVIAL_THRESHOLD=20
+SIGNIFICANT_THRESHOLD=200
+
+if [[ $SENSITIVE -eq 1 ]] || [[ $LINE_COUNT -gt $SIGNIFICANT_THRESHOLD ]]; then
+  SCORE="significant"
+elif [[ $LINE_COUNT -ge $TRIVIAL_THRESHOLD ]]; then
+  SCORE="standard"
+else
+  SCORE="trivial"
+fi
+
+# ── 8. Trivial → pass immediately ─────────────────────────────────────────────
+if [[ "$SCORE" == "trivial" ]]; then
+  exit 0
+fi
+
+# ── 9. Resolve rea CLI ────────────────────────────────────────────────────
+# Try local installs first, then dist build, then global PATH install.
+REA_CLI_ARGS=()
+if [[ -f "${REA_ROOT}/node_modules/.bin/rea" ]]; then
+  REA_CLI_ARGS=(node "${REA_ROOT}/node_modules/.bin/rea")
+elif [[ -f "${REA_ROOT}/dist/cli/index.js" ]]; then
+  REA_CLI_ARGS=(node "${REA_ROOT}/dist/cli/index.js")
+elif command -v rea >/dev/null 2>&1; then
+  REA_CLI_ARGS=(rea)
+fi
+
+# ── 10. Check review cache for all non-trivial commits ────────────────────────
+# Compute SHA and branch here so both standard and significant tiers share them.
+STAGED_SHA=$(cd "$REA_ROOT" && git diff --cached | shasum -a 256 | cut -d' ' -f1 2>/dev/null || echo "")
+BRANCH=$(cd "$REA_ROOT" && git branch --show-current 2>/dev/null || echo "")
+CACHE_FILE="${REA_ROOT}/.rea/review-cache.json"
+
+if [[ -n "$STAGED_SHA" ]]; then
+  CACHE_HIT=false
+
+  # Primary: use CLI when available — handles TTL, expiry, and branch-scoped keys
+  if [[ ${#REA_CLI_ARGS[@]} -gt 0 ]]; then
+    CACHE_RESULT=$("${REA_CLI_ARGS[@]}" cache check "$STAGED_SHA" --branch "$BRANCH" 2>/dev/null || echo '{"hit":false}')
+    if printf '%s' "$CACHE_RESULT" | jq -e '.hit == true' >/dev/null 2>&1; then
+      CACHE_HIT=true
+    fi
+  fi
+
+  # Fallback: read cache JSON directly — works when rea is not on PATH.
+  # Checks branch-scoped key ("branch:sha") first, then bare SHA (empty-branch case).
+  if [[ "$CACHE_HIT" == "false" ]] && [[ -f "$CACHE_FILE" ]]; then
+    CACHE_KEY="${BRANCH}:${STAGED_SHA}"
+    DIRECT_HIT=$(jq -r --arg k1 "$CACHE_KEY" --arg k2 "$STAGED_SHA" \
+      '(.entries[$k1] // .entries[$k2]) | if . == null then "miss" elif .result == "pass" then "hit" else "miss" end' \
+      "$CACHE_FILE" 2>/dev/null || echo "miss")
+    if [[ "$DIRECT_HIT" == "hit" ]]; then
+      CACHE_HIT=true
+    fi
+  fi
+
+  if [[ "$CACHE_HIT" == "true" ]]; then
+    exit 0
+  fi
+fi
+
+# ── 11. Block and request review ──────────────────────────────────────────────
+{
+  printf 'COMMIT REVIEW GATE: Review required before committing\n'
+  printf '\n'
+  printf '  Score: %s (%s changed lines)\n' "$SCORE" "$LINE_COUNT"
+  if [[ $SENSITIVE -eq 1 ]]; then
+    printf '  Sensitive paths detected:\n'
+    printf '%s\n' "$SENSITIVE_FILES"
+  fi
+  printf '\n'
+  printf '  YOU (the agent) are the reviewer. Do not ask the user to commit manually.\n'
+  printf '  Review the staged diff, make a pass/fail decision, then proceed:\n'
+  printf '\n'
+  printf '  1. Inspect:  git diff --cached\n'
+  printf '  2. Decide:   Is this safe to commit? (initial commits, refactors, and\n'
+  printf '               feature work are normal — use judgement, not ceremony)\n'
+  printf '  3. Approve:  rea cache set %s pass\n' "$STAGED_SHA"
+  printf '  4. Retry the git commit command\n'
+  printf '\n'
+  printf '  Only escalate to the user if you find a genuine problem in the diff.\n'
+} >&2
+exit 2