@thebassclef/lite 1.0.0 → 1.0.2

package/dist/lite/.claude/hooks/pre-build-gate.sh

@@ -0,0 +1,511 @@
+#!/bin/bash
+# tier: lite
+set -e
+
+# Pre-Build Gate — fires on first Edit/Write per session.
+# Requires visible SDLC evidence before writing code.
+# Loads relevant design diagrams contextually based on file being edited.
+
+# === Hook liveness heartbeat (WU-3 of bet 2026-07-31d; closes #1002) ===
+# Silent-fail — a missing lib never crashes the hook. Discipline: ADR-048 +
+# standards/hook-cadence.json.
+{
+  _hb_sd="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _hb_c in "${_hb_sd}/../../lib/hook-heartbeat.sh" "${HOME:-/}/lib/hook-heartbeat.sh"; do
+    [ -f "$_hb_c" ] && source "$_hb_c" && heartbeat_mark "pre-build-gate" && break
+  done
+  unset _hb_sd _hb_c
+} 2>/dev/null || true
+
+INPUT=$(cat)
+# Per bassclef#1125: fail-soft on jq parse failure (malformed stdin JSON
+# returns jq exit 5; set -e would crash the hook).
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null || echo "unknown")
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null || echo "unknown")
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null || echo "")
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."' 2>/dev/null || echo ".")
+
+# === Substrate-defect path detection (bassclef#277) ===
+# Paths where a fix proposal ripples to every adopter via /release.
+# These paths MUST NOT be skipped — the luminary gate (below) enforces
+# /temperance + /luminary discipline on this class of work per ADR-031.
+SUBSTRATE_DEFECT_PATH=0
+if echo "$FILE_PATH" | grep -qE '\.claude/hooks/.*\.sh$|\.claude/skills/.*/SKILL\.md$|\.claude/rules/.*\.md$|\.claude/luminaries/.*\.md$|lib/state\.sh$|scripts/migrate-adopter-references\.sh$|scripts/bassclef-orphan-parking\.sh$|scripts/bassclef-migrate-summary\.sh$|presence/install/.*\.sh$|standards/state-spine/schemas/.*\.schema\.json$|bassclef-sync\.sh$'; then
+  SUBSTRATE_DEFECT_PATH=1
+fi
+
+# Skip for non-source files (hooks, config, docs, memory, github workflows)
+# UNLESS this is a substrate-defect path — those always run the gate.
+if [ "$SUBSTRATE_DEFECT_PATH" -eq 0 ] && echo "$FILE_PATH" | grep -qE '\.(sh|json)$|/\.claude/|/memory/|/docs/|/\.github/|CLAUDE\.md|MEMORY\.md'; then
+  exit 0
+fi
+
+# Trace log
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/trace-helper.sh"
+trace_log "pre-build" "$TOOL_NAME $FILE_PATH"
+
+# --- Feature branch enforcement ---
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
+  echo ""
+  echo "============================================"
+  echo "WRITING TO MAIN BRANCH — CREATE A FEATURE BRANCH"
+  echo "============================================"
+  echo ""
+  echo "You are editing source code directly on main."
+  echo "All work should happen on a feature branch:"
+  echo "  git checkout -b feature/ISSUE-NNN-description"
+  echo "============================================"
+  echo ""
+fi
+
+# --- Durable marker convention (dual-read: /tmp flag OR git-tracked marker) ---
+# Per .claude/rules/mobile-ephemeral-session.md §2 and
+# standards/deferred-actions-schema.md. Either form satisfies the gate;
+# durable form lets mobile firings cross sandbox boundaries.
+BRANCH_SLUG=$(echo "$CURRENT_BRANCH" | tr '/' '-')
+DURABLE_DIAG_MARKER="$CWD/state/markers/diagnose/${BRANCH_SLUG}.marker"
+DURABLE_TEMP_MARKER="$CWD/state/markers/temperance/${BRANCH_SLUG}.marker"
+
+# --- DIAGNOSIS GATE (fix branches MUST show diagnosis) ---
+if echo "$CURRENT_BRANCH" | grep -qiE '^fix/'; then
+  DIAG_FLAG="/tmp/claude-diagnosis-done-${SESSION_ID}-$(echo "$CURRENT_BRANCH" | md5 -q 2>/dev/null || echo "$CURRENT_BRANCH" | md5sum 2>/dev/null | cut -d' ' -f1)"
+  if [ ! -f "$DIAG_FLAG" ] && [ ! -f "$DURABLE_DIAG_MARKER" ]; then
+    # Per bassclef#1060: BLOCK (exit 2), not advise. Sister fix to
+    # the temperance block; both gates were advisory which is the
+    # same shape as bassclef#1027 turn-prose (methodology-only fails).
+    if [ "${SKIP_DIAGNOSE:-0}" = "1" ]; then
+      echo "" >&2
+      echo "DIAGNOSIS — skipped via SKIP_DIAGNOSE=1 (logged)" >&2
+      [ -f "$SCRIPT_DIR/trace-helper.sh" ] && \
+        bash -c "source $SCRIPT_DIR/trace-helper.sh && trace_log diagnose-skip override 2>/dev/null" || true
+    else
+      cat >&2 <<EOF
+
+🛑 DIAGNOSIS — BLOCK (fix/ branch with no diagnosis evidence)
+
+You are on a fix/ branch but have NOT run /diagnose.
+
+Before writing ANY code:
+
+  0. Reproduce — exact command / URL / action that triggers the failure
+                 (skip only for typo / missing env var / off-by-one — state why)
+  1. Is / Is Not table — what fails? what similar thing works?
+  2. Five Whys — trace to root cause, not symptom
+  3. Hypothesis — one sentence, with a falsifiable test
+
+Run /diagnose. When done, write the marker:
+  touch state/markers/diagnose/${BRANCH_SLUG}.marker
+
+Override per-call: SKIP_DIAGNOSE=1 <command>  (logged via trace-helper)
+
+The POA incident (2026-04-05) showed agents jumping straight to code
+without understanding the problem. This gate prevents that.
+
+EOF
+      exit 2
+    fi
+  fi
+fi
+
+# --- TEMPERANCE GATE (scope-decision boundaries; per .claude/rules/sdlc-gates.md) ---
+# In stacked-PR work, branches are pre-shaped in a stack manifest. The
+# scope decision was made at manifest-write time. Re-firing per-branch
+# is ceremony, not gate. When the current branch is declared in any
+# stack manifest, suppress per-branch temperance — phase-level firing
+# (session kickoff, phase boundary, post-compaction, scope-drift) is
+# the load-bearing trigger. Per bassclef#272.
+
+TEMP_FLAG="/tmp/claude-temperance-done-${SESSION_ID}-$(echo "$CURRENT_BRANCH" | md5 -q 2>/dev/null || echo "$CURRENT_BRANCH" | md5sum 2>/dev/null | cut -d' ' -f1)"
+
+# Detect: is current branch declared in any stack manifest?
+BRANCH_IN_STACK=0
+STACK_MANIFEST=""
+if [ "$CURRENT_BRANCH" != "main" ] && [ "$CURRENT_BRANCH" != "master" ] && [ "$CURRENT_BRANCH" != "unknown" ]; then
+  for stack_dir in "$CWD/docs/stacks" "$CWD/docs/branch-stacks"; do
+    if [ -d "$stack_dir" ]; then
+      MATCH=$(grep -lF "$CURRENT_BRANCH" "$stack_dir"/*.md 2>/dev/null | head -1)
+      if [ -n "$MATCH" ]; then
+        BRANCH_IN_STACK=1
+        STACK_MANIFEST="$MATCH"
+        break
+      fi
+    fi
+  done
+fi
+
+if [ "$BRANCH_IN_STACK" -eq 1 ]; then
+  # Suppress: branch is pre-shaped in stack manifest. Phase-level firing covers this.
+  if [ ! -f "$DURABLE_TEMP_MARKER" ]; then
+    echo ""
+    echo "============================================"
+    echo "TEMPERANCE — suppressed (stacked branch)"
+    echo "============================================"
+    echo ""
+    echo "Branch '$CURRENT_BRANCH' is declared in:"
+    echo "  $STACK_MANIFEST"
+    echo ""
+    echo "Scope decision was made at manifest-write time."
+    echo "Per .claude/rules/sdlc-gates.md, temperance fires at"
+    echo "scope-decision boundaries (session kickoff, phase boundary,"
+    echo "post-compaction, scope-drift), not per-branch."
+    echo "============================================"
+    echo ""
+    # Auto-write the durable marker so /verify and other consumers see it.
+    mkdir -p "$(dirname "$DURABLE_TEMP_MARKER")" 2>/dev/null
+    echo "auto-suppressed-stacked $(date -u +"%Y-%m-%dT%H:%M:%SZ")" > "$DURABLE_TEMP_MARKER" 2>/dev/null || true
+    touch "$TEMP_FLAG" 2>/dev/null || true
+  fi
+elif [ ! -f "$TEMP_FLAG" ] && [ ! -f "$DURABLE_TEMP_MARKER" ]; then
+  # Non-stacked work — fire the standard per-branch gate.
+  # Per bassclef#1060: BLOCK (exit 2), not advise. Methodology-only
+  # enforcement has 0% adoption — last 15 PRs shipped without markers.
+  # Override via SKIP_TEMPERANCE=1 env (logged to trace) for genuine cases.
+  if [ "${SKIP_TEMPERANCE:-0}" = "1" ]; then
+    echo "" >&2
+    echo "TEMPERANCE — skipped via SKIP_TEMPERANCE=1 (logged)" >&2
+    [ -f "$SCRIPT_DIR/trace-helper.sh" ] && \
+      bash -c "source $SCRIPT_DIR/trace-helper.sh && trace_log temperance-skip override 2>/dev/null" || true
+  else
+    cat >&2 <<EOF
+
+🛑 TEMPERANCE — BLOCK (mandatory pause before first edit)
+
+Before your first edit on this branch, STOP and answer:
+
+  0. RIGHT THING?  Does this trace to a real need?
+  1. SIMPLEST?     Is this the simplest correct approach?
+  2. BRUTE FORCE?  Am I guessing instead of understanding?
+  3. BLAST RADIUS? What else could this break?
+  4. VERIFICATION? How will I know this works?
+  5. REVERSIBLE?   If wrong, how hard to undo?
+
+State your approach in ONE sentence, then write the marker:
+  touch state/markers/temperance/${BRANCH_SLUG}.marker
+
+This gate fires once per branch (non-stacked work).
+Stacked branches are pre-shaped in a manifest — the gate suppresses.
+Override per-call: SKIP_TEMPERANCE=1 <command>  (logged via trace-helper)
+
+EOF
+    exit 2
+  fi
+fi
+
+# --- MARKER ENRICHMENT (V1 advisory; per bassclef-upstream#438 + bet 28a WU-5) ---
+# Per .claude/rules/marker-enrichment-discipline.md: gate-marker files
+# should carry body content (date + branch + decision/lens/thread context),
+# not just exist as empty touch files. V1 advisory; flips to BLOCK in V2
+# after the allowlist baseline is cleared.
+MARKER_ENRICHMENT_ALLOWLIST="$CWD/.claude/hooks/marker-enrichment-allowlist.txt"
+check_marker_enriched() {
+  local marker_path="$1"
+  local marker_class="$2"  # temperance / luminary / arc-walk / orientation-gate / roadmap-reconcile-gate
+  [ "${SKIP_MARKER_ENRICHMENT:-0}" = "1" ] && return 0
+  [ ! -f "$marker_path" ] && return 0
+  [ -s "$marker_path" ] && return 0
+  # Empty marker. Check allowlist.
+  if [ -f "$MARKER_ENRICHMENT_ALLOWLIST" ]; then
+    local relative_path="${marker_path#$CWD/}"
+    if grep -qxF "$relative_path" "$MARKER_ENRICHMENT_ALLOWLIST" 2>/dev/null; then
+      return 0  # grandfathered
+    fi
+  fi
+  # Empty marker, not in allowlist — ADVISORY warn (V1 doesn't block)
+  echo "" >&2
+  echo "⚠️  MARKER ENRICHMENT — ADVISORY (V1; per .claude/rules/marker-enrichment-discipline.md)" >&2
+  echo "" >&2
+  echo "  $marker_class marker is empty: $marker_path" >&2
+  echo "  Per bet 28a WU-5: gate markers should carry body content" >&2
+  echo "  (date + branch + decision/lens/thread context)." >&2
+  echo "" >&2
+  echo "  Add body via heredoc in the same WU/PR. V2 will flip to BLOCK." >&2
+  echo "" >&2
+}
+# Check the marker that just cleared the temperance gate
+[ -f "$DURABLE_TEMP_MARKER" ] && check_marker_enriched "$DURABLE_TEMP_MARKER" "temperance"
+DURABLE_LUMINARY_MARKER_EARLY="$CWD/state/markers/luminary/${BRANCH_SLUG}.marker"
+[ -f "$DURABLE_LUMINARY_MARKER_EARLY" ] && check_marker_enriched "$DURABLE_LUMINARY_MARKER_EARLY" "luminary"
+DURABLE_ARC_WALK_MARKER="$CWD/state/markers/arc-walk/${BRANCH_SLUG}.marker"
+[ -f "$DURABLE_ARC_WALK_MARKER" ] && check_marker_enriched "$DURABLE_ARC_WALK_MARKER" "arc-walk"
+
+# --- LUMINARY GATE (substrate-defect paths require BOTH temperance + luminary markers) ---
+# Per bassclef#277. Substrate-defect fixes ripple to every adopter via
+# /release. Methodology-only failed — operator asked 3 times in one
+# session for /temperance + /luminary before fix proposals. This gate
+# enforces the discipline at the mechanical layer per memory
+# feedback_hooks_beat_methodology_for_substrate_quality.
+#
+# Primary lens for the gate's own design: Hyrum Wright — every adopter
+# branch that lacks a luminary marker at the moment this gate ships
+# would break under strict enforcement. The grandfather allowlist
+# (.claude/hooks/luminary-gate-allowlist.txt) gives existing branches
+# a deprecation window per ADR-031.
+
+if [ "$SUBSTRATE_DEFECT_PATH" -eq 1 ]; then
+  DURABLE_LUMINARY_MARKER="$CWD/state/markers/luminary/${BRANCH_SLUG}.marker"
+  ALLOWLIST="$CWD/.claude/hooks/luminary-gate-allowlist.txt"
+
+  # Hyrum grandfather window — branches matching any line in the
+  # allowlist bypass the gate during the deprecation window. Lines
+  # support shell glob patterns (feature/*, fix/*, bet-*, etc.) via
+  # bash's case/esac matching. Lines starting with # are ignored.
+  # Exact branch names also work — they're a degenerate-case glob.
+  IN_ALLOWLIST=0
+  if [ -f "$ALLOWLIST" ]; then
+    while IFS= read -r pattern || [ -n "$pattern" ]; do
+      # Skip comments and blank lines
+      case "$pattern" in
+        ''|\#*) continue ;;
+      esac
+      # Trim trailing whitespace defensively
+      pattern="${pattern%"${pattern##*[![:space:]]}"}"
+      # Glob match against current branch
+      case "$CURRENT_BRANCH" in
+        $pattern)
+          IN_ALLOWLIST=1
+          break
+          ;;
+      esac
+    done < "$ALLOWLIST"
+  fi
+
+  if [ "$IN_ALLOWLIST" -eq 0 ] && [ ! -f "$DURABLE_LUMINARY_MARKER" ]; then
+    if [ "${SKIP_LUMINARY_GATE:-0}" = "1" ]; then
+      echo "" >&2
+      echo "LUMINARY GATE — skipped via SKIP_LUMINARY_GATE=1 (logged)" >&2
+      [ -f "$SCRIPT_DIR/trace-helper.sh" ] && \
+        bash -c "source $SCRIPT_DIR/trace-helper.sh && trace_log luminary-gate-skip override 2>/dev/null" || true
+    else
+      cat >&2 <<EOF
+
+🛑 LUMINARY GATE — BLOCK (substrate-defect path without luminary marker)
+
+You are editing a substrate path: $FILE_PATH
+
+Substrate-defect fixes ripple to every adopter via /release. Per
+ADR-031 (we don't break adopters), every substrate-defect fix needs
+BOTH /temperance AND /luminary applied before code lands.
+
+/temperance marker — found.
+/luminary marker — missing at state/markers/luminary/${BRANCH_SLUG}.marker
+
+Before writing code at this path:
+
+  1. /luminary --primary — which lenses pin this work?
+     Common pins: Hyrum (api-stability), Linus (adopter-compat),
+     Beck (TDD red-green), Hoare (pre/post conditions),
+     Ousterhout (deep modules), Saltzer-Schroeder (defensive bash).
+
+  2. Write the marker:
+     mkdir -p state/markers/luminary
+     cat > state/markers/luminary/${BRANCH_SLUG}.marker <<'MARKER'
+     session: <session-id>
+     branch: ${CURRENT_BRANCH}
+     primary_lens: <luminary slug>
+     compatibility_anchor: <luminary slug>
+     reason: <one line>
+     MARKER
+
+Override per-call: SKIP_LUMINARY_GATE=1 <command>  (logged via trace-helper)
+
+Hyrum grandfather: add branch to .claude/hooks/luminary-gate-allowlist.txt
+for deprecation-window bypass. The allowlist exists so this gate landing
+does not break in-flight branches that pre-date the discipline.
+
+Source incident: operator asked 3 times in one session (2026-06-22) for
+/temperance + /luminary before substrate-defect fix proposals. Methodology
+alone (rules + memory) did not hold. Filed as bassclef#277.
+
+EOF
+      exit 2
+    fi
+  fi
+fi
+
+# --- Budget awareness (cost governance) ---
+MANIFEST="$CWD/substrate.config.md"
+if [ -f "$MANIFEST" ]; then
+  # Prefer accessor (state_iteration_bet_active returns frontmatter as JSON);
+  # fall back to grep for repos pre-spine-v0 OR for bets that store turn_limit
+  # in body markdown rather than frontmatter.
+  TURN_LIMIT=""
+  if [ -f "$CWD/lib/state.sh" ]; then
+    # shellcheck source=/dev/null
+    source "$CWD/lib/state.sh" 2>/dev/null && \
+      TURN_LIMIT=$(state_iteration_bet_active 2>/dev/null | \
+        jq -r '.appetite.turn_limit // .turn_limit // empty' 2>/dev/null)
+  fi
+  if [ -z "$TURN_LIMIT" ]; then
+    TURN_LIMIT=$(grep 'turn_limit:' "$CWD/docs/iteration-bets/"*.md 2>/dev/null | tail -1 | grep -oE '[0-9]+' | head -1)
+  fi
+  if [ -n "$TURN_LIMIT" ]; then
+    # Count edits this session as a proxy for turns consumed.
+    # Dual-write: /tmp (existing) + durable (mobile-ephemeral-session.md §2).
+    EDIT_FLAG="/tmp/claude-edit-count-${SESSION_ID}"
+    DURABLE_EDIT_DIR="$CWD/state/markers/edit-count"
+    DURABLE_EDIT_FLAG="$DURABLE_EDIT_DIR/${SESSION_ID}.count"
+    EDIT_COUNT=0
+    if [ -f "$DURABLE_EDIT_FLAG" ]; then
+      EDIT_COUNT=$(cat "$DURABLE_EDIT_FLAG")
+    elif [ -f "$EDIT_FLAG" ]; then
+      EDIT_COUNT=$(cat "$EDIT_FLAG")
+    fi
+    EDIT_COUNT=$((EDIT_COUNT + 1))
+    echo "$EDIT_COUNT" > "$EDIT_FLAG"
+    mkdir -p "$DURABLE_EDIT_DIR" 2>/dev/null
+    echo "$EDIT_COUNT" > "$DURABLE_EDIT_FLAG" 2>/dev/null
+
+    THRESHOLD=$((TURN_LIMIT * 75 / 100))
+    if [ "$EDIT_COUNT" -ge "$TURN_LIMIT" ]; then
+      echo ""
+      echo "============================================"
+      echo "BUDGET: TURN LIMIT REACHED ($EDIT_COUNT / $TURN_LIMIT)"
+      echo "============================================"
+      echo "Pause. Report state. Propose descoped continuation."
+      echo "============================================"
+      echo ""
+    elif [ "$EDIT_COUNT" -ge "$THRESHOLD" ]; then
+      echo ""
+      echo "BUDGET: 75% of turn limit ($EDIT_COUNT / $TURN_LIMIT)"
+      echo ""
+    fi
+  fi
+fi
+
+# Fire full gate first time per session, lightweight reminder on subsequent edits
+FLAG_FILE="/tmp/claude-pre-build-gate-${SESSION_ID}"
+DOCS_DIR="$CWD/docs/design"
+
+if [ -f "$FLAG_FILE" ]; then
+  # Subsequent edit — lightweight per-task reminder
+  cat <<'PERTASK'
+============================================
+PRE-BUILD — PER-TASK CHECK
+============================================
+
+Before this edit, confirm:
+- Building against: [ticket # or "trivial — logged in commit"]
+- Temperance: Simplest correct approach? Brute-forcing?
+- UI surface impacted? If yes, is IA/state diagram current?
+- Env vars needed? Set?
+============================================
+PERTASK
+
+else
+  # First edit this session — full SDLC checkpoint
+  touch "$FLAG_FILE"
+
+  cat <<'GATE'
+============================================
+PRE-BUILD GATE — MANDATORY BEFORE WRITING CODE
+============================================
+
+You are about to write/edit source code. STOP.
+
+YOUR RESPONSE must contain ALL of the following sections as visible text
+BEFORE this Edit/Write and any subsequent code changes:
+
+## SDLC Checkpoint
+- Building against: [ticket #NNN — title, or "no ticket" with justification]
+- Spec current?: [yes/no — if no, what needs updating first?]
+- Design diagrams: [which need updating and why, or "none — because X"]
+- Engineering principles: [any SoC/abstraction/cohesion concerns? or "clean"]
+
+## Environment Check
+- External credentials needed?: [OAuth, API keys, tokens, etc.]
+- Are they set?: [check NOW — if empty, flag blocker before writing code]
+
+## Requirements Check
+- New requirements surfaced?: [yes → where logged | no]
+- Untracked work?: [am I coding something not on any ticket? if yes, log it first]
+
+## Test Plan
+- Testable logic?: [yes/no — pure functions, utilities, parsers = yes]
+- Test approach: [which test file will cover this? new or existing?]
+
+If this is a bug fix, you must ALSO have completed the Bug Diagnosis
+(Is/Is Not + Five Whys) before proceeding.
+
+Only after writing these sections may you proceed to write code.
+============================================
+GATE
+fi
+
+# === Contextual diagram loading ===
+echo ""
+echo "=== RELEVANT DESIGN DIAGRAMS (verify against these) ==="
+echo ""
+
+LOADED=0
+
+# Schema / Prisma / migration → load ERD
+if echo "$FILE_PATH" | grep -qiE 'prisma|schema|model|migration'; then
+  [ -f "$DOCS_DIR/erd.md" ] && { echo "### ERD (triggered by: schema/model file)"; head -80 "$DOCS_DIR/erd.md" 2>/dev/null; echo ""; LOADED=1; }
+fi
+
+# Queue / worker / agent → load Sequence + Component diagrams
+if echo "$FILE_PATH" | grep -qiE 'worker|queue|agent|job|bull|cron|ingest'; then
+  [ -f "$DOCS_DIR/sequences/"*.md ] 2>/dev/null && { echo "### Sequence diagrams (triggered by: worker/agent file)"; ls "$DOCS_DIR/sequences/"*.md 2>/dev/null; echo ""; LOADED=1; }
+  [ -f "$DOCS_DIR/component-diagram.md" ] && { echo "### Component Diagram"; head -60 "$DOCS_DIR/component-diagram.md" 2>/dev/null; echo ""; LOADED=1; }
+fi
+
+# Docker / deploy / infra → load Component + Deployment diagrams
+if echo "$FILE_PATH" | grep -qiE 'docker|deploy|infra|compose|Dockerfile|workflow'; then
+  [ -f "$DOCS_DIR/component-diagram.md" ] && { echo "### Component Diagram (triggered by: infra file)"; head -60 "$DOCS_DIR/component-diagram.md" 2>/dev/null; echo ""; LOADED=1; }
+fi
+
+# Auth / user / role → load Use Case diagram
+if echo "$FILE_PATH" | grep -qiE 'auth|user|role|permission|session'; then
+  [ -f "$DOCS_DIR/use-cases.md" ] && { echo "### Use Cases (triggered by: auth/role file)"; head -60 "$DOCS_DIR/use-cases.md" 2>/dev/null; echo ""; LOADED=1; }
+fi
+
+# Page route → UX check + E2E reminder
+if echo "$FILE_PATH" | grep -qiE 'src/app/.*/page\.tsx'; then
+  echo "### UX Check (triggered by: page route file)"
+  echo "- Does a state diagram exist for this page?"
+  echo "- Is this page in the entity model / screen map?"
+  echo "- Are components named after domain objects?"
+  echo "- Run /ia-model if navigation or screen structure is changing."
+  echo ""
+  echo "### E2E Smoke Test"
+  echo "User-facing pages MUST be covered by E2E smoke tests."
+  echo ""
+  LOADED=1
+fi
+
+# API route → E2E reminder
+if echo "$FILE_PATH" | grep -qiE 'src/app/api/.*/route\.ts'; then
+  echo "### E2E Smoke Test (triggered by: API route file)"
+  echo "API routes MUST be covered by E2E smoke tests."
+  echo "- Protected route: add auth gate test"
+  echo "- Public route: add response shape test"
+  echo ""
+  LOADED=1
+fi
+
+# Schema change → entity model + migration reminder
+if echo "$FILE_PATH" | grep -qiE 'prisma/schema'; then
+  echo "### Entity Model Check (triggered by: schema file)"
+  echo "- Has the entity been added to the object model?"
+  echo "- Does this entity need a UI surface?"
+  echo "- Run /ia-model if adding a new entity."
+  echo ""
+  echo "### MIGRATION REQUIRED"
+  echo "After editing schema, run: npx prisma migrate dev --name descriptive_name"
+  echo "NEVER use prisma db push. It causes schema drift."
+  echo ""
+  LOADED=1
+fi
+
+if [ "$LOADED" -eq 0 ]; then
+  echo "(No diagram matched: $FILE_PATH)"
+  echo "If this change introduces new objects, async flows, or lifecycle changes,"
+  echo "manually read the relevant diagram from docs/design/ before proceeding."
+fi
+
+echo ""
+echo "=== END DIAGRAMS ==="
+
+exit 0