reviewflow 3.8.1 → 3.10.0

package/scripts/hooks/no-barrel-exports.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Blocks creation or editing of barrel export files (index.ts).
+# Used as PreToolUse hook on Write|Edit.
+# Exit 0 = allow, Exit 2 = block with feedback to Claude.
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | "$HOOK_DIR/parse-json.sh" tool_input.file_path)
+
+is_barrel_export() {
+  local filename
+  filename=$(basename "$FILE_PATH")
+  [[ "$filename" == "index.ts" || "$filename" == "index.js" ]]
+}
+
+if is_barrel_export; then
+  echo "Barrel exports are forbidden. Import directly from the source file instead of using index.ts." >&2
+  exit 2
+fi
+
+exit 0

package/scripts/hooks/parse-json.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+# Extracts a value from JSON on stdin using a dot-separated path.
+# Usage: echo '{"a":{"b":"c"}}' | parse-json.sh a.b
+# Returns empty string if path not found. No external dependencies beyond python3.
+
+python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+path = sys.argv[1].split('.')
+for key in path:
+    if isinstance(data, dict) and key in data:
+        data = data[key]
+    else:
+        sys.exit(0)
+print(data if data is not None else '')
+" "$1"

package/scripts/hooks/pre-commit-gate.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Blocks git commit if tests fail.
+# Used as PreToolUse hook on Bash(git commit *).
+# Exit 0 = allow, Exit 2 = block with feedback to Claude.
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | "$HOOK_DIR/parse-json.sh" tool_input.command)
+
+is_commit_command() {
+  echo "$COMMAND" | grep -qE "git commit"
+}
+
+if ! is_commit_command; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(cd "$HOOK_DIR/../.." && pwd)}"
+
+cd "$PROJECT_DIR"
+
+if yarn test:ci 2>&1; then
+  exit 0
+else
+  echo "Tests failed. Fix them before committing." >&2
+  exit 2
+fi

package/scripts/hooks/protect-main-branch.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Blocks git commit on main/master branch.
+# Used as PreToolUse hook on Bash(git commit *).
+# Exit 0 = allow, Exit 2 = block with feedback to Claude.
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | "$HOOK_DIR/parse-json.sh" tool_input.command)
+
+is_commit_command() {
+  echo "$COMMAND" | grep -qE "git commit"
+}
+
+if ! is_commit_command; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(cd "$HOOK_DIR/../.." && pwd)}"
+CURRENT_BRANCH=$(cd "$PROJECT_DIR" && git branch --show-current 2>/dev/null || true)
+
+if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
+  echo "You are on '$CURRENT_BRANCH'. Create a feature branch or use /worktree add <name> first." >&2
+  exit 2
+fi
+
+exit 0

package/scripts/hooks/protect-main-push.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Blocks git push to main/master branch and force pushes.
+# Used as PreToolUse hook on Bash(git push *).
+# Exit 0 = allow, Exit 2 = block with feedback to Claude.
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | "$HOOK_DIR/parse-json.sh" tool_input.command)
+
+is_push_command() {
+  echo "$COMMAND" | grep -qE "git push"
+}
+
+if ! is_push_command; then
+  exit 0
+fi
+
+is_force_push() {
+  echo "$COMMAND" | grep -qE "\-\-force|\-f"
+}
+
+if is_force_push; then
+  echo "Force push is forbidden. Push normally to your feature branch instead." >&2
+  exit 2
+fi
+
+pushes_to_protected_branch() {
+  echo "$COMMAND" | grep -qE "git push.*(origin\s+(main|master)|origin/main|origin/master)"
+}
+
+if pushes_to_protected_branch; then
+  echo "Push to main/master is forbidden. Push to your feature branch instead." >&2
+  exit 2
+fi
+
+exit 0

package/scripts/hooks/require-spec.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Blocks feature-implementer agent if no spec file exists or spec is incomplete.
+# Used as PreToolUse hook on Agent.
+# Exit 0 = allow, Exit 2 = block with feedback to Claude.
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | "$HOOK_DIR/parse-json.sh" tool_input.prompt)
+
+is_feature_agent() {
+  echo "$PROMPT" | grep -qi "feature-implementer\|feature-planner"
+}
+
+if ! is_feature_agent; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(cd "$HOOK_DIR/../.." && pwd)}"
+
+spec_file_referenced() {
+  echo "$PROMPT" | grep -oP 'docs/specs/[a-z0-9-]+\.md' | head -1 || true
+}
+
+SPEC_REF=$(spec_file_referenced || true)
+
+if [[ -z "$SPEC_REF" ]]; then
+  echo "No spec file referenced in the prompt. Create a spec first with /product-manager." >&2
+  exit 2
+fi
+
+if [[ ! -f "$PROJECT_DIR/$SPEC_REF" ]]; then
+  echo "Spec file '$SPEC_REF' does not exist. Create it first with /product-manager." >&2
+  exit 2
+fi
+
+SPEC_CONTENT=$(cat "$PROJECT_DIR/$SPEC_REF")
+
+has_rules_section() {
+  echo "$SPEC_CONTENT" | grep -qE "^## (Rules|Business Rules|Remaining Scope|Functional Requirements)"
+}
+
+has_scenarios_section() {
+  echo "$SPEC_CONTENT" | grep -qE "^## (Scenarios|Acceptance Criteria|Gherkin Scenarios)"
+}
+
+if ! has_rules_section; then
+  echo "Spec '$SPEC_REF' is missing the '## Rules' (or '## Business Rules') section. Fix it before implementing." >&2
+  exit 2
+fi
+
+if ! has_scenarios_section; then
+  echo "Spec '$SPEC_REF' is missing the '## Scenarios' (or '## Acceptance Criteria') section. Fix it before implementing." >&2
+  exit 2
+fi
+
+exit 0

package/scripts/hooks/session-context.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Injects feature tracker status into session context on startup.
+# Used as SessionStart hook.
+# Outputs JSON with additionalContext field.
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(cd "$HOOK_DIR/../.." && pwd)}"
+TRACKER="$PROJECT_DIR/docs/feature-tracker.md"
+
+if [[ ! -f "$TRACKER" ]]; then
+  exit 0
+fi
+
+FEATURE_COUNT=$(tail -n +3 "$TRACKER" | grep -c '|' || true)
+
+if [[ "$FEATURE_COUNT" -eq 0 ]]; then
+  exit 0
+fi
+
+IMPLEMENTING=$(tail -n +3 "$TRACKER" | grep -c "| implementing |" || true)
+IMPLEMENTED=$(tail -n +3 "$TRACKER" | grep -c "| implemented |" || true)
+DRAFTED=$(tail -n +3 "$TRACKER" | grep -c "| drafted |" || true)
+PLANNED=$(tail -n +3 "$TRACKER" | grep -c "| planned |" || true)
+
+CONTEXT="Feature tracker: ${FEATURE_COUNT} features total"
+
+if [[ "$IMPLEMENTING" -gt 0 ]]; then
+  CONTEXT="$CONTEXT, ${IMPLEMENTING} in progress"
+fi
+if [[ "$PLANNED" -gt 0 ]]; then
+  CONTEXT="$CONTEXT, ${PLANNED} planned"
+fi
+if [[ "$DRAFTED" -gt 0 ]]; then
+  CONTEXT="$CONTEXT, ${DRAFTED} drafted"
+fi
+if [[ "$IMPLEMENTED" -gt 0 ]]; then
+  CONTEXT="$CONTEXT, ${IMPLEMENTED} implemented"
+fi
+
+CONTEXT="$CONTEXT. See docs/feature-tracker.md for details."
+
+python3 -c "
+import json, sys
+print(json.dumps({'additionalContext': sys.argv[1]}))
+" "$CONTEXT"

package/scripts/hooks/tests/run-tests.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Test runner for Claude Code hook scripts.
+# Run: bash scripts/hooks/tests/run-tests.sh
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEST_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASSED=0
+FAILED=0
+TOTAL=0
+
+green() { printf "\033[32m%s\033[0m\n" "$1"; }
+red() { printf "\033[31m%s\033[0m\n" "$1"; }
+bold() { printf "\033[1m%s\033[0m\n" "$1"; }
+
+assert_exit() {
+  local test_name="$1"
+  local expected_exit="$2"
+  local actual_exit="$3"
+  TOTAL=$((TOTAL + 1))
+
+  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
+    green "  PASS: $test_name (exit $actual_exit)"
+    PASSED=$((PASSED + 1))
+  else
+    red "  FAIL: $test_name (expected exit $expected_exit, got $actual_exit)"
+    FAILED=$((FAILED + 1))
+  fi
+}
+
+assert_stderr_contains() {
+  local test_name="$1"
+  local pattern="$2"
+  local stderr_output="$3"
+  TOTAL=$((TOTAL + 1))
+
+  if echo "$stderr_output" | grep -q "$pattern"; then
+    green "  PASS: $test_name (stderr contains '$pattern')"
+    PASSED=$((PASSED + 1))
+  else
+    red "  FAIL: $test_name (stderr missing '$pattern')"
+    red "    actual stderr: $stderr_output"
+    FAILED=$((FAILED + 1))
+  fi
+}
+
+# ─────────────────────────────────────────────
+bold "=== parse-json.sh ==="
+
+OUTPUT=$(echo '{"tool_input":{"command":"git commit -m test"}}' | "$HOOK_DIR/parse-json.sh" tool_input.command)
+TOTAL=$((TOTAL + 1))
+if [[ "$OUTPUT" == "git commit -m test" ]]; then
+  green "  PASS: extracts nested value"
+  PASSED=$((PASSED + 1))
+else
+  red "  FAIL: extracts nested value (got: $OUTPUT)"
+  FAILED=$((FAILED + 1))
+fi
+
+OUTPUT=$(echo '{"tool_input":{"command":"test"}}' | "$HOOK_DIR/parse-json.sh" tool_input.missing_key)
+TOTAL=$((TOTAL + 1))
+if [[ -z "$OUTPUT" ]]; then
+  green "  PASS: returns empty for missing key"
+  PASSED=$((PASSED + 1))
+else
+  red "  FAIL: returns empty for missing key (got: $OUTPUT)"
+  FAILED=$((FAILED + 1))
+fi
+
+# ─────────────────────────────────────────────
+bold "=== no-barrel-exports.sh ==="
+
+echo '{"tool_input":{"file_path":"/src/entities/index.ts"}}' | "$HOOK_DIR/no-barrel-exports.sh" > /dev/null 2>&1 || true
+EXIT_CODE=$(echo '{"tool_input":{"file_path":"/src/entities/index.ts"}}' | "$HOOK_DIR/no-barrel-exports.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "blocks index.ts" 2 "$EXIT_CODE"
+
+STDERR=$(echo '{"tool_input":{"file_path":"/src/entities/index.ts"}}' | "$HOOK_DIR/no-barrel-exports.sh" 2>&1 > /dev/null || true)
+assert_stderr_contains "error message mentions barrel" "Barrel exports" "$STDERR"
+
+EXIT_CODE=$(echo '{"tool_input":{"file_path":"/src/entities/review.ts"}}' | "$HOOK_DIR/no-barrel-exports.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "allows normal .ts file" 0 "$EXIT_CODE"
+
+EXIT_CODE=$(echo '{"tool_input":{"file_path":"/src/entities/index.js"}}' | "$HOOK_DIR/no-barrel-exports.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "blocks index.js" 2 "$EXIT_CODE"
+
+# ─────────────────────────────────────────────
+bold "=== protect-main-branch.sh ==="
+
+# Create temp git repo to test
+TEMP_REPO=$(mktemp -d)
+cd "$TEMP_REPO"
+git init -q
+git checkout -q -b master
+
+EXIT_CODE=$(echo '{"tool_input":{"command":"git commit -m test"}}' | CLAUDE_PROJECT_DIR="$TEMP_REPO" "$HOOK_DIR/protect-main-branch.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "blocks commit on master" 2 "$EXIT_CODE"
+
+STDERR=$(echo '{"tool_input":{"command":"git commit -m test"}}' | CLAUDE_PROJECT_DIR="$TEMP_REPO" "$HOOK_DIR/protect-main-branch.sh" 2>&1 > /dev/null || true)
+assert_stderr_contains "mentions master" "master" "$STDERR"
+
+git checkout -q -b feat/test
+EXIT_CODE=$(echo '{"tool_input":{"command":"git commit -m test"}}' | CLAUDE_PROJECT_DIR="$TEMP_REPO" "$HOOK_DIR/protect-main-branch.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "allows commit on feature branch" 0 "$EXIT_CODE"
+
+EXIT_CODE=$(echo '{"tool_input":{"command":"ls -la"}}' | CLAUDE_PROJECT_DIR="$TEMP_REPO" "$HOOK_DIR/protect-main-branch.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "ignores non-commit commands" 0 "$EXIT_CODE"
+
+rm -rf "$TEMP_REPO"
+
+# ─────────────────────────────────────────────
+bold "=== protect-main-push.sh ==="
+
+EXIT_CODE=$(echo '{"tool_input":{"command":"git push origin master"}}' | "$HOOK_DIR/protect-main-push.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "blocks push to master" 2 "$EXIT_CODE"
+
+EXIT_CODE=$(echo '{"tool_input":{"command":"git push origin main"}}' | "$HOOK_DIR/protect-main-push.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "blocks push to main" 2 "$EXIT_CODE"
+
+EXIT_CODE=$(echo '{"tool_input":{"command":"git push --force origin feat/test"}}' | "$HOOK_DIR/protect-main-push.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "blocks force push" 2 "$EXIT_CODE"
+
+EXIT_CODE=$(echo '{"tool_input":{"command":"git push origin feat/test"}}' | "$HOOK_DIR/protect-main-push.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "allows push to feature branch" 0 "$EXIT_CODE"
+
+EXIT_CODE=$(echo '{"tool_input":{"command":"ls -la"}}' | "$HOOK_DIR/protect-main-push.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "ignores non-push commands" 0 "$EXIT_CODE"
+
+# ─────────────────────────────────────────────
+bold "=== require-spec.sh ==="
+
+PROJECT_DIR="$HOOK_DIR/../.."
+
+# Test: no spec reference → block
+EXIT_CODE=$(echo '{"tool_input":{"prompt":"implement the feature-implementer for login"}}' | CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$HOOK_DIR/require-spec.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "blocks agent without spec reference" 2 "$EXIT_CODE"
+
+STDERR=$(echo '{"tool_input":{"prompt":"implement the feature-implementer for login"}}' | CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$HOOK_DIR/require-spec.sh" 2>&1 > /dev/null || true)
+assert_stderr_contains "suggests /product-manager" "product-manager" "$STDERR"
+
+# Test: non-feature agent → allow
+EXIT_CODE=$(echo '{"tool_input":{"prompt":"review the code in src/entities"}}' | CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$HOOK_DIR/require-spec.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "allows non-feature agents" 0 "$EXIT_CODE"
+
+# Test: valid spec reference with existing file
+EXIT_CODE=$(echo '{"tool_input":{"prompt":"run feature-planner with docs/specs/44-zod-guard-gitlab-webhook.md"}}' | CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$HOOK_DIR/require-spec.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "allows with valid spec reference" 0 "$EXIT_CODE"
+
+# Test: spec file does not exist
+EXIT_CODE=$(echo '{"tool_input":{"prompt":"run feature-implementer with docs/specs/999-nonexistent.md"}}' | CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$HOOK_DIR/require-spec.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "blocks with nonexistent spec" 2 "$EXIT_CODE"
+
+# ─────────────────────────────────────────────
+bold "=== session-context.sh ==="
+
+EXIT_CODE=$(CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$HOOK_DIR/session-context.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "runs without error" 0 "$EXIT_CODE"
+
+OUTPUT=$(CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$HOOK_DIR/session-context.sh" 2>/dev/null || true)
+TOTAL=$((TOTAL + 1))
+if echo "$OUTPUT" | python3 -c "import json,sys; json.load(sys.stdin)" 2>/dev/null; then
+  green "  PASS: outputs valid JSON"
+  PASSED=$((PASSED + 1))
+else
+  red "  FAIL: outputs valid JSON (got: $OUTPUT)"
+  FAILED=$((FAILED + 1))
+fi
+
+TOTAL=$((TOTAL + 1))
+if echo "$OUTPUT" | python3 -c "import json,sys; d=json.load(sys.stdin); assert 'additionalContext' in d" 2>/dev/null; then
+  green "  PASS: JSON contains additionalContext"
+  PASSED=$((PASSED + 1))
+else
+  red "  FAIL: JSON contains additionalContext (got: $OUTPUT)"
+  FAILED=$((FAILED + 1))
+fi
+
+# ─────────────────────────────────────────────
+echo ""
+bold "=== RESULTS ==="
+echo "Total: $TOTAL | Passed: $PASSED | Failed: $FAILED"
+
+if [[ "$FAILED" -gt 0 ]]; then
+  red "SOME TESTS FAILED"
+  exit 1
+else
+  green "ALL TESTS PASSED"
+  exit 0
+fi

package/scripts/hooks/tests/test-architecture-hooks.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Tests for the 3 Clean Architecture enforcement hooks.
+# Run: bash scripts/hooks/tests/test-architecture-hooks.sh
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PASSED=0
+FAILED=0
+TOTAL=0
+
+green() { printf "\033[32m%s\033[0m\n" "$1"; }
+red()   { printf "\033[31m%s\033[0m\n" "$1"; }
+bold()  { printf "\033[1m%s\033[0m\n" "$1"; }
+
+assert_exit() {
+  local name="$1" expected="$2" actual="$3"
+  TOTAL=$((TOTAL + 1))
+  if [[ "$actual" -eq "$expected" ]]; then
+    green "  PASS: $name (exit $actual)"
+    PASSED=$((PASSED + 1))
+  else
+    red "  FAIL: $name (expected exit $expected, got $actual)"
+    FAILED=$((FAILED + 1))
+  fi
+}
+
+payload() {
+  python3 -c "
+import json, sys
+print(json.dumps({'tool_input': {'file_path': sys.argv[1], 'content': sys.argv[2], 'new_string': ''}}))
+" "$1" "$2"
+}
+
+# ─────────────────────────────────────────────────────────────
+bold "=== enforce-dependency-rule.sh ==="
+
+# Entity importing interface-adapters → blocked
+EXIT=$(payload "/project/src/entities/foo/foo.gateway.ts" \
+  "import type { Bar } from '@/interface-adapters/gateways/bar.js'" \
+  | "$HOOK_DIR/enforce-dependency-rule.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "entity cannot import interface-adapters" 2 "$EXIT"
+
+# Entity importing usecases → blocked
+EXIT=$(payload "/project/src/entities/foo/foo.ts" \
+  "import type { Usecase } from '@/usecases/something.usecase.js'" \
+  | "$HOOK_DIR/enforce-dependency-rule.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "entity cannot import usecases" 2 "$EXIT"
+
+# Entity importing frameworks → blocked
+EXIT=$(payload "/project/src/entities/foo/foo.ts" \
+  "import type { Queue } from '@/frameworks/queue/pQueueAdapter.js'" \
+  | "$HOOK_DIR/enforce-dependency-rule.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "entity cannot import frameworks" 2 "$EXIT"
+
+# Entity importing within entities → allowed
+EXIT=$(payload "/project/src/entities/foo/foo.ts" \
+  "import type { Bar } from '@/entities/bar/bar.js'" \
+  | "$HOOK_DIR/enforce-dependency-rule.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "entity can import other entities" 0 "$EXIT"
+
+# Usecase importing interface-adapters → blocked
+EXIT=$(payload "/project/src/usecases/doSomething.usecase.ts" \
+  "import type { SomeGateway } from '@/interface-adapters/gateways/some.gateway.js'" \
+  | "$HOOK_DIR/enforce-dependency-rule.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "usecase cannot import interface-adapters" 2 "$EXIT"
+
+# Usecase importing frameworks → blocked
+EXIT=$(payload "/project/src/usecases/doSomething.usecase.ts" \
+  "import type { ReviewJob } from '@/frameworks/queue/pQueueAdapter.js'" \
+  | "$HOOK_DIR/enforce-dependency-rule.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "usecase cannot import frameworks" 2 "$EXIT"
+
+# Usecase importing entities (valid) → allowed
+EXIT=$(payload "/project/src/usecases/doSomething.usecase.ts" \
+  "import type { ReviewContextGateway } from '@/entities/reviewContext/reviewContext.gateway.js'" \
+  | "$HOOK_DIR/enforce-dependency-rule.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "usecase can import entities" 0 "$EXIT"
+
+# File outside src/ → always allowed
+EXIT=$(payload "/project/scripts/build.ts" \
+  "import type { Foo } from '@/interface-adapters/gateways/foo.js'" \
+  | "$HOOK_DIR/enforce-dependency-rule.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "non-src file always allowed" 0 "$EXIT"
+
+# ─────────────────────────────────────────────────────────────
+bold "=== enforce-gateway-port-purity.sh ==="
+
+# Entity gateway with interface → allowed
+EXIT=$(payload "/project/src/entities/review/reviewContext.gateway.ts" \
+  "export interface ReviewContextGateway { create(): void }" \
+  | "$HOOK_DIR/enforce-gateway-port-purity.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "entity gateway with interface is allowed" 0 "$EXIT"
+
+# Entity gateway with abstract class → allowed
+EXIT=$(payload "/project/src/entities/review/reviewContext.gateway.ts" \
+  "export abstract class ReviewContextGateway { abstract create(): void }" \
+  | "$HOOK_DIR/enforce-gateway-port-purity.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "entity gateway with abstract class is allowed" 0 "$EXIT"
+
+# Entity gateway with plain class → blocked
+EXIT=$(payload "/project/src/entities/review/reviewContext.gateway.ts" \
+  "export class ReviewContextGateway { create(): void {} }" \
+  | "$HOOK_DIR/enforce-gateway-port-purity.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "entity gateway with plain class is blocked" 2 "$EXIT"
+
+# Implementation in interface-adapters with plain class → allowed (not in entities/)
+EXIT=$(payload "/project/src/interface-adapters/gateways/reviewContext.fileSystem.gateway.ts" \
+  "export class ReviewContextFileSystemGateway implements ReviewContextGateway {}" \
+  | "$HOOK_DIR/enforce-gateway-port-purity.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "gateway impl in interface-adapters with plain class is allowed" 0 "$EXIT"
+
+# Non-gateway entity file → not checked
+EXIT=$(payload "/project/src/entities/review/reviewContext.ts" \
+  "export class ReviewContext { private constructor() {} }" \
+  | "$HOOK_DIR/enforce-gateway-port-purity.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "non-gateway entity file not checked" 0 "$EXIT"
+
+# ─────────────────────────────────────────────────────────────
+bold "=== enforce-presenter-class.sh ==="
+
+# Presenter with class ending in Presenter → allowed
+EXIT=$(payload "/project/src/interface-adapters/presenters/jobStatus.presenter.ts" \
+  "export class JobStatusPresenter { present(input: unknown) { return {} } }" \
+  | "$HOOK_DIR/enforce-presenter-class.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "presenter class *Presenter is allowed" 0 "$EXIT"
+
+# Presenter with class ending in Calculator → allowed
+EXIT=$(payload "/project/src/interface-adapters/presenters/score.presenter.ts" \
+  "export class ScoreCalculator { compute(input: unknown) { return 0 } }" \
+  | "$HOOK_DIR/enforce-presenter-class.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "presenter class *Calculator is allowed" 0 "$EXIT"
+
+# Presenter with function export → blocked
+EXIT=$(payload "/project/src/interface-adapters/presenters/jobStatus.presenter.ts" \
+  "export function presentJobStatus(input: unknown) { return {} }" \
+  | "$HOOK_DIR/enforce-presenter-class.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "presenter function export is blocked" 2 "$EXIT"
+
+# Non-presenter .ts file → not checked
+EXIT=$(payload "/project/src/interface-adapters/controllers/webhook.controller.ts" \
+  "export function handleWebhook() {}" \
+  | "$HOOK_DIR/enforce-presenter-class.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "non-presenter file not checked" 0 "$EXIT"
+
+# presenter.ts outside interface-adapters/presenters/ → not checked
+EXIT=$(payload "/project/src/entities/foo/foo.presenter.ts" \
+  "export function fooPresenter() {}" \
+  | "$HOOK_DIR/enforce-presenter-class.sh" > /dev/null 2>&1; echo $?) || true
+assert_exit "presenter outside interface-adapters/presenters/ not checked" 0 "$EXIT"
+
+# ─────────────────────────────────────────────────────────────
+echo ""
+bold "=== RESULTS ==="
+echo "Total: $TOTAL | Passed: $PASSED | Failed: $FAILED"
+
+if [[ "$FAILED" -gt 0 ]]; then
+  red "SOME TESTS FAILED"
+  exit 1
+else
+  green "ALL TESTS PASSED"
+  exit 0
+fi

package/scripts/hooks/verify-spec-updated.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Blocks git commit if staged files include src/ code but the corresponding
+# spec does not have "## Status: implemented" and the feature-tracker is stale.
+# Used as PreToolUse hook on Bash(git commit *).
+# Exit 0 = allow, Exit 2 = block with feedback to Claude.
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | "$HOOK_DIR/parse-json.sh" tool_input.command)
+
+is_commit_command() {
+  echo "$COMMAND" | grep -qE "git commit"
+}
+
+if ! is_commit_command; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(cd "$HOOK_DIR/../.." && pwd)}"
+cd "$PROJECT_DIR"
+
+STAGED_FILES=$(git diff --cached --name-only 2>/dev/null || true)
+
+if [[ -z "$STAGED_FILES" ]]; then
+  exit 0
+fi
+
+has_source_code() {
+  echo "$STAGED_FILES" | grep -q "^src/" 2>/dev/null
+}
+
+if ! has_source_code; then
+  exit 0
+fi
+
+TRACKER="$PROJECT_DIR/docs/feature-tracker.md"
+SPECS_DIR="$PROJECT_DIR/docs/specs"
+
+ERRORS=""
+
+if [[ -f "$TRACKER" ]]; then
+  DRAFTS_IN_TRACKER=$(grep -c "| drafted |" "$TRACKER" || true)
+  STAGED_HAS_TRACKER=$(echo "$STAGED_FILES" | grep -c "docs/feature-tracker.md" || true)
+
+  if [[ "$DRAFTS_IN_TRACKER" -gt 0 && "$STAGED_HAS_TRACKER" -eq 0 ]]; then
+    IMPLEMENTING=$(grep -c "| implementing |" "$TRACKER" || true)
+    if [[ "$IMPLEMENTING" -gt 0 ]]; then
+      ERRORS="${ERRORS}Feature tracker has features in 'implementing' status. Update docs/feature-tracker.md before committing.\n"
+    fi
+  fi
+fi
+
+if [[ -d "$SPECS_DIR" ]]; then
+  for SPEC_FILE in "$SPECS_DIR"/*.md; do
+    [[ -f "$SPEC_FILE" ]] || continue
+    SPEC_NAME=$(basename "$SPEC_FILE")
+
+    if grep -q "^## Status: implemented" "$SPEC_FILE" 2>/dev/null; then
+      continue
+    fi
+
+    if echo "$STAGED_FILES" | grep -q "$SPEC_NAME" 2>/dev/null; then
+      continue
+    fi
+  done
+fi
+
+if [[ -n "$ERRORS" ]]; then
+  echo -e "$ERRORS" >&2
+  exit 2
+fi
+
+exit 0