From 35da40b782ce5dc6a2027a78a30ef21baf70b630 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Wed, 13 May 2026 13:17:38 +0200 Subject: [PATCH] feat(claude): add 6 lifecycle hooks reinforcing template hard rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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/ or apps/ 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) --- .claude/hooks/bash-guard.sh | 44 +++++++++++++++ .claude/hooks/generator-first-nudge.sh | 43 +++++++++++++++ .claude/hooks/post-manifest-edit.sh | 31 +++++++++++ .claude/hooks/prompt-context.sh | 43 +++++++++++++++ .claude/hooks/session-start.sh | 15 +++++ .claude/hooks/stop-check-manifest-tests.sh | 47 ++++++++++++++++ .claude/settings.json | 64 ++++++++++++++++++++++ 7 files changed, 287 insertions(+) create mode 100755 .claude/hooks/bash-guard.sh create mode 100755 .claude/hooks/generator-first-nudge.sh create mode 100755 .claude/hooks/post-manifest-edit.sh create mode 100755 .claude/hooks/prompt-context.sh create mode 100755 .claude/hooks/session-start.sh create mode 100755 .claude/hooks/stop-check-manifest-tests.sh create mode 100644 .claude/settings.json diff --git a/.claude/hooks/bash-guard.sh b/.claude/hooks/bash-guard.sh new file mode 100755 index 0000000..a7fdbfb --- /dev/null +++ b/.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 <\` 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 diff --git a/.claude/hooks/generator-first-nudge.sh b/.claude/hooks/generator-first-nudge.sh new file mode 100755 index 0000000..c54bfba --- /dev/null +++ b/.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 `. + +set -euo pipefail + +input=$(cat) +cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""') + +# Match creation of a NEW top-level packages// or apps// 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 < # 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 diff --git a/.claude/hooks/post-manifest-edit.sh b/.claude/hooks/post-manifest-edit.sh new file mode 100755 index 0000000..3720538 --- /dev/null +++ b/.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 <} test typecheck lint + pnpm conformance +EOF + +exit 0 diff --git a/.claude/hooks/prompt-context.sh b/.claude/hooks/prompt-context.sh new file mode 100755 index 0000000..4101e91 --- /dev/null +++ b/.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 diff --git a/.claude/hooks/session-start.sh b/.claude/hooks/session-start.sh new file mode 100755 index 0000000..39af0f2 --- /dev/null +++ b/.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 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 diff --git a/.claude/hooks/stop-check-manifest-tests.sh b/.claude/hooks/stop-check-manifest-tests.sh new file mode 100755 index 0000000..e099dc0 --- /dev/null +++ b/.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 <