feat(claude): add 6 lifecycle hooks reinforcing template hard rules

Project-level Claude Code hooks committed to .claude/settings.json with
scripts under .claude/hooks/. Three tiers:

Tier 1 — hard guards (exit 2 to block the tool call):
- bash-guard.sh: blocks bypass flags (verify-skip, sign-skip), forceful
  push variants, destructive resets, force clean, working-tree-wipe
  checkouts/restores, force branch delete, amend, and rm -rf against
  root or home. Reinforces CLAUDE.md Git Safety Protocol.
- generator-first-nudge.sh: blocks creating a new top-level
  packages/<name> or apps/<name> directory by hand. Allows working
  inside an existing package. Reinforces the non-negotiable
  generator-first rule.

Tier 2 — context injection (stdout becomes additional context):
- session-start.sh: prints glossary, AGENTS.md, workflow CLI, and
  conformance pointers on session boot.
- prompt-context.sh: keyword-matches the user prompt against eight
  concept groups (events, realtime, audit, instrumentation, manifest,
  workflow, DI, boundaries) and injects the relevant ADR + rule
  pointers for the turn.

Tier 3 — side-effect automation:
- post-manifest-edit.sh: when Edit/Write touches feature.manifest.ts,
  prints the manifest-first ordering reminder plus the per-feature
  verify commands.
- stop-check-manifest-tests.sh: at agent Stop time, if the working
  tree has manifest changes but no sibling test changes, exits 2 to
  force continuation. Loop-guarded via stop_hook_active.

All hooks are bash + jq, use CLAUDE_PROJECT_DIR for safety, and were
smoke-tested end-to-end (block + allow paths both verified).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.claude/hooks/bash-guard.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Tier 1 — blocks dangerous shell invocations the agent shouldn't run
+# autonomously. Reads PreToolUse JSON on stdin; exits 2 with stderr to block,
+# 0 to allow. Reinforces the Git Safety Protocol in CLAUDE.md.
+
+set -euo pipefail
+
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')
+
+blocks=(
+  '(^|[[:space:]])--no-verify([[:space:]]|$)'
+  '(^|[[:space:]])--no-gpg-sign([[:space:]]|$)'
+  'git[[:space:]]+push[[:space:]]+([^&|;]*[[:space:]])?(-f|--force)([[:space:]]|$)'
+  'git[[:space:]]+reset[[:space:]]+[^&|;]*--hard'
+  'git[[:space:]]+clean[[:space:]]+-[a-zA-Z]*f'
+  'git[[:space:]]+checkout[[:space:]]+\.([[:space:]]|$)'
+  'git[[:space:]]+restore[[:space:]]+\.([[:space:]]|$)'
+  'git[[:space:]]+branch[[:space:]]+-D'
+  'git[[:space:]]+commit[[:space:]]+[^&|;]*--amend'
+  'rm[[:space:]]+-rf?[[:space:]]+/'
+  'rm[[:space:]]+-rf?[[:space:]]+~'
+  'rm[[:space:]]+-rf?[[:space:]]+\$HOME'
+)
+
+for pattern in "${blocks[@]}"; do
+  if [[ "$cmd" =~ $pattern ]]; then
+    cat >&2 <<EOF
+BLOCKED by .claude/hooks/bash-guard.sh
+
+This template forbids the agent from running this autonomously:
+  Pattern: ${pattern}
+  Command: ${cmd}
+
+If the user has explicitly authorized this action this turn, ask them to
+run it themselves (\`! <command>\` in the prompt) or document the override
+in their request. See CLAUDE.md → "Executing actions with care" and the
+Git Safety Protocol section.
+EOF
+    exit 2
+  fi
+done
+
+exit 0

.claude/hooks/generator-first-nudge.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Tier 1 — enforces the generator-first rule. Blocks hand-rolled scaffolding
+# under packages/ or apps/ via mkdir/cp/touch. Use `pnpm turbo gen <kind>`.
+
+set -euo pipefail
+
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')
+
+# Match creation of a NEW top-level packages/<name>/ or apps/<name>/ directory.
+# Allows working inside an existing package (e.g. `mkdir -p packages/blog/src/foo`).
+patterns=(
+  'mkdir[[:space:]]+(-p[[:space:]]+)?packages/[a-zA-Z0-9_-]+/?([[:space:]]|$)'
+  'mkdir[[:space:]]+(-p[[:space:]]+)?apps/[a-zA-Z0-9_-]+/?([[:space:]]|$)'
+  'cp[[:space:]]+-[rR][[:space:]]+packages/[^[:space:]]+[[:space:]]+packages/[a-zA-Z0-9_-]+/?([[:space:]]|$)'
+)
+
+for pattern in "${patterns[@]}"; do
+  if [[ "$cmd" =~ $pattern ]]; then
+    cat >&2 <<EOF
+BLOCKED by .claude/hooks/generator-first-nudge.sh
+
+This template enforces "generator-first" — hand-rolled scaffolding under
+packages/ or apps/ is forbidden. Use a generator:
+
+  pnpm turbo gen feature              # new vertical feature
+  pnpm turbo gen core-package <name>  # optional core (events|realtime|audit|trpc|ui)
+  pnpm turbo gen event                # event contract or handler
+  pnpm turbo gen job                  # background job
+  pnpm turbo gen realtime             # realtime channel or handler
+  pnpm turbo gen core-ui-component    # atomic-design UI component
+
+If you're modifying an existing package (e.g. \`mkdir -p packages/blog/src/x\`)
+this hook will not block you. If you genuinely need to bypass (e.g. fixing
+the generator itself), ask the user to authorize and re-state the intent.
+
+Command: ${cmd}
+EOF
+    exit 2
+  fi
+done
+
+exit 0

.claude/hooks/post-manifest-edit.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Tier 3 — when a feature.manifest.ts is edited, remind the agent to surface
+# drift and follow manifest-first ordering. Non-blocking (stderr exit 0 is
+# visible in transcript; we don't want this to kill the agent's flow).
+
+set -euo pipefail
+
+input=$(cat)
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // ""')
+
+if [[ "$file_path" != *"feature.manifest.ts" ]]; then
+  exit 0
+fi
+
+feature=$(echo "$file_path" | sed -nE 's|.*packages/([^/]+)/src/feature\.manifest\.ts$|\1|p')
+
+cat >&2 <<EOF
+[post-manifest-edit] feature.manifest.ts changed (${feature:-unknown feature})
+
+Manifest-first ordering reminder:
+  (1) manifest entry      ← you just did this
+  (2) contracts           — xInputSchema, xOutputSchema, IXUseCase
+  (3) tests (red)         — colocated *.test.ts
+  (4) implementation      — use-case + controller + DI binding
+
+Surface drift now:
+  pnpm --filter @repo/${feature:-<feature>} test typecheck lint
+  pnpm conformance
+EOF
+
+exit 0

.claude/hooks/prompt-context.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Tier 2 — injects relevant ADR + workflow pointers when the user's prompt
+# mentions concepts covered by an ADR or a hard ordering rule.
+# stdout is appended to the agent's context for this turn.
+
+set -euo pipefail
+
+input=$(cat)
+prompt=$(printf '%s' "$input" | jq -r '.prompt // ""' | tr '[:upper:]' '[:lower:]')
+
+inject=()
+
+if echo "$prompt" | grep -qE 'event|publish|consume|cross-feature|job queue'; then
+  inject+=('Events/jobs: ADR-015 + docs/guides/events-and-jobs.md. Rules E0 (events for cross-feature only), E1 (handlers private), J0 (jobs for deferred work).')
+fi
+if echo "$prompt" | grep -qE 'realtime|socket\.io|channel|broadcast|presence'; then
+  inject+=('Realtime: ADR-016 + docs/guides/realtime.md. Rules R0 (state delivery only), R1 (handlers private), R2 (socket.io in core-realtime only).')
+fi
+if echo "$prompt" | grep -qE 'audit|compliance|gdpr|dpa|erasure'; then
+  inject+=('Audit: ADR-018 + docs/guides/audit-and-compliance.md. Optional core; scaffold with pnpm turbo gen core-package audit.')
+fi
+if echo "$prompt" | grep -qE 'sentry|otel|opentelemetry|tracing|instrumentation|pii|scrub'; then
+  inject+=('Instrumentation: ADR-014 (interfaces) + ADR-017 (OTel migration). PII rules non-negotiable: sendDefaultPii=false, server-side scrub at OTel processor layer.')
+fi
+if echo "$prompt" | grep -qE 'use case|use-case|controller|repository|feature\.manifest|new feature|scaffold'; then
+  inject+=('Manifest-first ordering: (1) manifest → (2) contracts (xInputSchema, xOutputSchema, IXUseCase) → (3) tests (red) → (4) impl (green). Use pnpm turbo gen feature/event/job/realtime — never hand-roll.')
+fi
+if echo "$prompt" | grep -qE 'prd|epic|story|task|sandcastle|dispatch|orchestrat'; then
+  inject+=('Workflow: docs/architecture/agent-first-workflow-and-conformance.md + ADR-019. PRDs live in docs/work/prds/ — use the to-prd skill. Stress-test plans with grill-with-docs.')
+fi
+if echo "$prompt" | grep -qE 'di container|inject|bind-production|bind-dev-seed|symbols'; then
+  inject+=('DI: ADR-008 (per-feature containers). Binders take ctx from core-shared/di. Use .toDynamicValue() for factory bindings. Tests inject mocks directly — no container rebinding.')
+fi
+if echo "$prompt" | grep -qE 'boundary|boundaries|cross-package|cross feature'; then
+  inject+=('Boundaries: ADR-006 + ADR-010. Five tags (app|core|core-composition|feature|tooling). Features may only depend on core + tooling. Enforced by ESLint + Turborepo boundaries.')
+fi
+
+if [ ${#inject[@]} -gt 0 ]; then
+  echo "=== context-relevant pointers (from .claude/hooks/prompt-context.sh) ==="
+  printf -- '- %s\n' "${inject[@]}"
+fi
+
+exit 0

.claude/hooks/session-start.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Tier 2 — surfaces a fresh session's "where to look first" pointers.
+# Output on stdout is injected as additional context.
+
+cat <<'EOF'
+=== template-vertical session pointers ===
+Canonical vocabulary: docs/glossary.md  (resolve "what does X mean here?" first)
+Architecture: AGENTS.md, docs/architecture/overview.md, docs/architecture/agent-first-workflow-and-conformance.md
+Workflow: pnpm work status | pnpm work next | pnpm work dispatch (ADR-019)
+Generator-first: pnpm turbo gen <kind> beats hand-rolled scaffolding (non-negotiable)
+Conformance: pnpm conformance + pnpm fallow (5-gate drift detection)
+Skills: to-prd, grill-with-docs, grill-me, handoff (.claude/skills/)
+EOF
+
+exit 0

.claude/hooks/stop-check-manifest-tests.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Tier 3 — when the agent tries to stop, check whether feature.manifest.ts
+# changes have matching test changes. If manifest moved without tests,
+# nudge the agent to continue (exit 2 forces continuation).
+
+set -euo pipefail
+
+input=$(cat)
+
+# Loop guard — Claude Code sets stop_hook_active when a Stop hook already
+# forced continuation; don't loop infinitely.
+already_stopped=$(printf '%s' "$input" | jq -r '.stop_hook_active // false')
+if [ "$already_stopped" = "true" ]; then
+  exit 0
+fi
+
+# Only run inside the repo
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  exit 0
+fi
+
+manifest_changed=$(git diff --name-only HEAD 2>/dev/null | grep -E 'feature\.manifest\.ts$' || true)
+
+if [ -z "$manifest_changed" ]; then
+  exit 0
+fi
+
+tests_changed=$(git diff --name-only HEAD 2>/dev/null | grep -E '\.test\.(ts|tsx)$' || true)
+
+if [ -n "$tests_changed" ]; then
+  exit 0
+fi
+
+cat >&2 <<EOF
+[stop-check] Manifest changes detected without matching test changes:
+
+${manifest_changed}
+
+Manifest-first ordering says: contracts + a red test must land before
+implementation. If you already shipped tests in a previous commit on this
+branch (and only the manifest changed this turn), say so and re-stop —
+this hook tracks unstaged + uncommitted-on-HEAD diffs only and can't tell.
+
+Otherwise, write the sibling test file(s) for any new use case before stopping.
+EOF
+
+exit 2

.claude/settings.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash-guard.sh"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/generator-first-nudge.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-manifest-edit.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-context.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-check-manifest-tests.sh"
+          }
+        ]
+      }
+    ]
+  }
+}