chore(template): clean-slate template snapshot from bb4a0c7

Curated, product-agnostic snapshot of the post-story-04 tree: demo
content deleted, auth-only reference feature, web-next shell, all gates
green. Product-specific docs, ADRs 027-029, PRDs/epics/archive, editor
library traces, and product naming are curated out; generic template
repairs (coverage provider devDeps, root test:coverage script, live
lint fixes, root-only release-please) are kept. See TEMPLATE.md for
provenance, curation list, and usage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK

.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/library-policy-nudge.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Advisory — nudges the agent to run /evaluate-library before adding runtime
+# dependencies. Non-blocking (exit 0). Stdout is injected as system-reminder
+# context by the harness.
+#
+# Dispatches on payload shape:
+#   .tool_input.command   → PreToolUse / Bash  (pnpm add / pnpm i <pkg>)
+#   .tool_input.file_path → PostToolUse / Edit|Write (**/package.json edits)
+
+set -euo pipefail
+
+input=$(cat)
+
+# --- PreToolUse / Bash path ---
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')
+if [[ -n "$cmd" ]]; then
+  # Match: pnpm add <...> or pnpm i <pkg> — must have a space after keyword
+  if [[ "$cmd" =~ (^|[[:space:]])pnpm[[:space:]]+(add[[:space:]]|i[[:space:]]) ]]; then
+    # Skip dev-dependency installs — no policy evaluation needed for devDeps
+    if [[ ! "$cmd" =~ (^|[[:space:]])(-D|--save-dev)([[:space:]]|$) ]]; then
+      cat <<'EOF'
+[library-policy-nudge] Runtime dependency detected — evaluate before adding.
+
+Run the evaluate-library skill first:
+  /evaluate-library <name> --tier <feature|core|app> --target <package-path>
+
+This ensures the dependency is logged in docs/decisions/ before the pre-commit gate fires.
+EOF
+    fi
+  fi
+  exit 0
+fi
+
+# --- PostToolUse / Edit|Write path ---
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // ""')
+if [[ "$file_path" == */package.json ]]; then
+  cat <<'EOF'
+[library-policy-nudge] package.json edited — verify any new runtime dependencies are evaluated.
+
+If you added a runtime dependency, run the evaluate-library skill:
+  /evaluate-library <name> --tier <feature|core|app> --target <package-path>
+
+This ensures the dependency is logged in docs/decisions/ before the pre-commit gate fires.
+EOF
+fi
+
+exit 0

.claude/hooks/library-policy-nudge.test.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Smoke tests for library-policy-nudge.sh
+# Usage: bash .claude/hooks/library-policy-nudge.test.sh
+
+set -euo pipefail
+
+SCRIPT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/library-policy-nudge.sh"
+MARKER="/evaluate-library"
+PASS=0
+FAIL=0
+
+assert_contains() {
+  local name="$1"
+  local input="$2"
+  local output
+  output=$(printf '%s' "$input" | bash "$SCRIPT" 2>/dev/null)
+  if echo "$output" | grep -qF "$MARKER"; then
+    echo "  PASS: $name"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $name"
+    echo "    Expected stdout to contain: $MARKER"
+    echo "    Got: ${output:-<empty>}"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_no_output() {
+  local name="$1"
+  local input="$2"
+  local output
+  output=$(printf '%s' "$input" | bash "$SCRIPT" 2>/dev/null)
+  if ! echo "$output" | grep -qF "$MARKER"; then
+    echo "  PASS: $name"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $name"
+    echo "    Expected no $MARKER in stdout, got: $output"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "library-policy-nudge.sh smoke tests"
+echo "------------------------------------"
+
+# pnpm add <pkg> → reminder (runtime dep)
+assert_contains \
+  "pnpm add foo triggers reminder" \
+  '{"tool_input":{"command":"pnpm add foo"}}'
+
+# pnpm add -D <pkg> → no reminder (dev dep)
+assert_no_output \
+  "pnpm add -D foo produces no reminder" \
+  '{"tool_input":{"command":"pnpm add -D foo"}}'
+
+# pnpm add --save-dev <pkg> → no reminder (dev dep, long flag)
+assert_no_output \
+  "pnpm add --save-dev foo produces no reminder" \
+  '{"tool_input":{"command":"pnpm add --save-dev foo"}}'
+
+# Edit on non-package.json → no reminder
+assert_no_output \
+  "Edit on feature.manifest.ts produces no reminder" \
+  '{"tool_input":{"file_path":"/workspace/packages/auth/src/feature.manifest.ts"}}'
+
+# Edit on package.json → reminder
+assert_contains \
+  "Edit on package.json triggers reminder" \
+  '{"tool_input":{"file_path":"/workspace/packages/auth/package.json"}}'
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 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,55 @@
+#!/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 echo "$prompt" | grep -qE 'coverage|uncovered|lcov|mutation|stryker|coverage band'; then
+  inject+=('Coverage: ADR-020 + docs/guides/coverage.md (cookbook). 4 layers — L0 vitest thresholds, L1 pnpm coverage:diff (cover-the-diff), L2 coverage/summary.json (committed trend), L3 pnpm mutate (Stryker on entities + use-cases). Manifest-driven: feature.manifest.ts coverage.bands is the single source of truth.')
+fi
+if echo "$prompt" | grep -qE 'commit|message|changelog|conventional'; then
+  inject+=('Conventional Commits (non-negotiable): <type>(<scope>): <imperative subject> (≤72 chars). Types: feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert. Use `!` for breaking changes. Body explains WHY if non-obvious. Examples: feat(auth): hash password before persisting; refactor(docs)!: consolidate scaffolding into guides. See CLAUDE.md Key Conventions.')
+fi
+if echo "$prompt" | grep -qE 'release|version|bump|semver|tag\b'; then
+  inject+=('Releases: ADR-021 + docs/guides/releasing.md. Hybrid versioning — root template (template-v...) + 5 feature packages (auth-v..., blog-v..., etc.) version independently from 0.1.0. release-please reads Conventional Commits and opens a rolling release PR on every push to main; merging cuts per-package tags. Bump targeting is by commit-path, not (scope). Pre-1.0 policy: feat: -> patch, feat!: -> minor.')
+fi
+if echo "$prompt" | grep -qE 'refactor|deepening|shallow|architecture|seam|adapter|interface design|design it twice'; then
+  inject+=('Architecture refactors: invoke the improve-codebase-architecture skill (.claude/skills/improve-codebase-architecture/SKILL.md). Vocabulary: module (= feature by default in this repo) / interface / seam / adapter / depth / leverage / locality. Process: Explore -> Present numbered candidates -> Grilling loop. Hard constraints: respect ADRs 001-021 (factory-function shape, per-feature DI, manifest-first, generator-first, boundary tags, vendor isolation). Companion files: DEEPENING.md (dependency categories), INTERFACE-DESIGN.md (parallel sub-agent design pattern), LANGUAGE.md (vocab + this-repo identifier mapping).')
+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,17 @@
+#!/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)
+Conventional Commits (non-negotiable): <type>(<scope>): <subject> — see CLAUDE.md Key Conventions
+Releases: release-please reads commits + opens rolling release PR on merge to main (ADR-021)
+Skills: to-prd, grill-with-docs, grill-me, handoff, improve-codebase-architecture, evaluate-library (.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