@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/hooks/turn-prose-kiss-check.sh

@@ -0,0 +1,434 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# Turn-prose /kiss check — Stop hook that scans the most recent assistant
+# message in the transcript against bassclef-internal jargon BLOCK terms.
+#
+# Per bassclef#1051: closes the bassclef#1027 "no hook can reach turn prose"
+# gap. Stop hooks receive transcript_path in stdin and CAN read the most
+# recent assistant message.
+#
+# Sibling pattern: .claude/hooks/pr-body-scrub-check.sh
+# Single source of truth for BLOCK terms: standards/bassclef-internal-jargon.md
+# Allowlist per bassclef#763: substrate, bassclef, cameo, Studio, Band, bandleader
+#
+# Input (stdin): JSON with transcript_path + session_id
+#   {"transcript_path": "/path/to/transcript.jsonl", "session_id": "..."}
+#
+# Toggle (env or .claude/bassclef-configs.jsonc):
+#   PROSE_DISCIPLINE_TOGGLE=true     — advisory (exit 0, findings to stderr)  [DEFAULT]
+#   PROSE_DISCIPLINE_TOGGLE=strict   — strict (exit 2, blocks stop, forces rewrite)
+#   PROSE_DISCIPLINE_TOGGLE=false    — silent (exit 0, no scan)
+#
+# Override per-call:
+#   SKIP_TURN_PROSE_KISS=1           — skip scan, exit 0
+#
+# Exit codes:
+#   0 — pass (no findings, advisory mode, toggle off, or override set)
+#   2 — block stop (strict mode + findings present)
+#
+# Reads:
+#   - $TRANSCRIPT_PATH (jsonl, one event per line)
+#   - standards/bassclef-internal-jargon.md (BLOCK terms)
+#   - .claude/bassclef-configs.jsonc (toggle when env not set)
+
+set +e
+
+# === Override path ===
+if [ "${SKIP_TURN_PROSE_KISS:-0}" = "1" ]; then
+  exit 0
+fi
+
+# === Source install-class-aware resolver lib (per standards/hook-install-class.md) ===
+# This hook is `dual` — runs under both project install (<repo>/.claude/hooks/)
+# and operator install ($HOME/.claude/hooks/). Pre-cure: SCRIPT_DIR/../../standards
+# was hardcoded; operator-install fell back to an 8-term defensive list. Cure:
+# resolve_standards_path + resolve_config_path from lib/hook-inject.sh.
+# Lib lookup layered: project-relative → HOME-relative (bassclef-sync convention).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# === Hook liveness heartbeat (WU-3 of bet 2026-07-31d; closes #1002) ===
+# Silent-fail — a missing lib never crashes the hook.
+{
+  for _hb_c in "${SCRIPT_DIR}/../../lib/hook-heartbeat.sh" "${HOME:-/}/lib/hook-heartbeat.sh"; do
+    [ -f "$_hb_c" ] && source "$_hb_c" && heartbeat_mark "turn-prose-kiss-check" && break
+  done
+  unset _hb_c
+} 2>/dev/null || true
+
+for _candidate in \
+  "${SCRIPT_DIR}/../../lib/hook-inject.sh" \
+  "${HOME_OVERRIDE:-${HOME:-/}}/lib/hook-inject.sh"; do
+  if [ -f "$_candidate" ]; then
+    # shellcheck disable=SC1090
+    source "$_candidate"
+    break
+  fi
+done
+unset _candidate
+
+# === Parse stdin JSON ===
+STDIN_JSON=$(cat 2>/dev/null || echo '{}')
+TRANSCRIPT_PATH=$(echo "$STDIN_JSON" | jq -r '.transcript_path // ""' 2>/dev/null)
+
+# Graceful skip if no transcript path provided
+if [ -z "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# Graceful skip if transcript file missing
+if [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# === Resolve config file (install-class-aware via lib) ===
+if declare -f resolve_config_path >/dev/null 2>&1; then
+  CONFIG_FILE=$(resolve_config_path 2>/dev/null) || CONFIG_FILE=""
+else
+  CONFIG_FILE="${SCRIPT_DIR}/../bassclef-configs.jsonc"
+fi
+
+# === Resolve toggle ===
+TOGGLE="${PROSE_DISCIPLINE_TOGGLE:-}"
+if [ -z "$TOGGLE" ]; then
+  if [ -n "$CONFIG_FILE" ] && [ -f "$CONFIG_FILE" ]; then
+    # Strip // comments before jq parses (jsonc is JSON + comments)
+    TOGGLE=$(sed 's|//.*||g' "$CONFIG_FILE" 2>/dev/null \
+      | jq -r '.prose_discipline.kiss_words_turn_prose // "true"' 2>/dev/null)
+  fi
+  TOGGLE="${TOGGLE:-true}"
+fi
+
+# Boolean true normalizes to "true" (advisory). false → silent. "strict" → strict.
+case "$TOGGLE" in
+  true|"true") MODE="advisory" ;;
+  strict|"strict") MODE="strict" ;;
+  false|"false") exit 0 ;;
+  *) MODE="advisory" ;;
+esac
+
+# bassclef#1171 — read per-place strict escalation list. When global mode is
+# advisory but the message matches a named place pattern AND has BLOCK findings,
+# the hook escalates that message to strict (exit 2).
+# Env var precedence over config: explicit empty string (env set to "") means
+# "no places, do not consult config". Unset means "fall back to config".
+if [ -n "${PROSE_DISCIPLINE_STRICT_PLACES+set}" ]; then
+  STRICT_PLACES="$PROSE_DISCIPLINE_STRICT_PLACES"
+else
+  STRICT_PLACES=""
+  if [ -f "$CONFIG_FILE" ]; then
+    STRICT_PLACES=$(sed 's|//.*||g' "$CONFIG_FILE" 2>/dev/null \
+      | jq -r '.prose_discipline.kiss_words_strict_places // [] | join(",")' 2>/dev/null)
+  fi
+fi
+
+# === Extract most recent assistant message ===
+# Transcript is JSONL: one event per line. Last line with type=assistant.
+# Content is an array of content blocks; collect text from:
+#   - "text" blocks (assistant prose to operator)
+#   - "tool_use" blocks where name == "AskUserQuestion" (option text the
+#     operator reads — same operator-facing surface as prose). Pulls the
+#     question, each option label, and each option description.
+# Other tool_use blocks (Bash, Read, Edit, etc.) are NOT scanned — their
+# inputs are not operator-facing prose.
+LAST_ASSISTANT_LINE=$(grep '"type":"assistant"' "$TRANSCRIPT_PATH" 2>/dev/null | tail -1)
+if [ -z "$LAST_ASSISTANT_LINE" ]; then
+  # No assistant message in transcript yet — graceful skip
+  exit 0
+fi
+
+MESSAGE_TEXT=$(echo "$LAST_ASSISTANT_LINE" \
+  | jq -r '.message.content[]? |
+      if .type == "text" then
+        .text
+      elif .type == "tool_use" and .name == "AskUserQuestion" then
+        [
+          (.input.questions[]?
+           | (.question // ""),
+             (.options[]? | (.label // ""), (.description // "")))
+        ] | join("\n")
+      else
+        empty
+      end' 2>/dev/null)
+if [ -z "$MESSAGE_TEXT" ]; then
+  exit 0
+fi
+
+# === Strip code blocks + inline backtick spans + URLs ===
+# Same logic as pr-body-scrub-check.sh — technical refs are not prose
+SCRUBBED=$(echo "$MESSAGE_TEXT" | awk '
+  BEGIN { in_code = 0 }
+  /^```/ { in_code = !in_code; next }
+  in_code { next }
+  { print }
+' | sed -E 's/`[^`]*`//g; s|https?://[^ )]+||g')
+
+# === Load BLOCK terms from standards/bassclef-internal-jargon.md ===
+# Pattern matches pr-body-scrub-check.sh — read BLOCK-tier rows from the table.
+# Path resolution via lib's resolve_standards_path (project → env → user → fail).
+# Falls back to legacy SCRIPT_DIR-relative path when none of the lib's 3 layers
+# resolve — preserves project-class behavior under direct invocation without
+# CLAUDE_PROJECT_DIR set (operator-install always sets CLAUDE_PROJECT_DIR).
+STANDARDS_FILE=""
+if declare -f resolve_standards_path >/dev/null 2>&1; then
+  STANDARDS_FILE=$(resolve_standards_path "bassclef-internal-jargon.md" 2>/dev/null) || STANDARDS_FILE=""
+fi
+if [ -z "$STANDARDS_FILE" ] || [ ! -f "$STANDARDS_FILE" ]; then
+  STANDARDS_FILE="${KISS_STANDARDS_FILE:-${SCRIPT_DIR}/../../standards/bassclef-internal-jargon.md}"
+fi
+
+JARGON_TERMS=()
+if [ -f "$STANDARDS_FILE" ]; then
+  while IFS= read -r line; do
+    JARGON_TERMS+=("$line")
+  done < <(awk -F'|' '
+    /^\| [a-zA-Z0-9-]+ / && /BLOCK *\|$/ {
+      gsub(/^ +| +$/, "", $2)
+      print $2
+    }
+  ' "$STANDARDS_FILE")
+fi
+
+# Defensive fallback if standards file missing or empty
+if [ ${#JARGON_TERMS[@]} -eq 0 ]; then
+  JARGON_TERMS=(
+    "composer"
+    "primitive"
+    "tier-preset"
+    "load-bearing"
+    "blast radius"
+    "compose-with"
+    "scope-bounded"
+    "operationalize"
+  )
+fi
+
+# === Scan for BLOCK terms ===
+FINDINGS=""
+FINDING_COUNT=0
+for term in "${JARGON_TERMS[@]}"; do
+  # Case-insensitive whole-word match
+  count=$(echo "$SCRUBBED" | grep -ioE "\b${term}\b" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$count" -gt 0 ]; then
+    FINDINGS="${FINDINGS}- \`${term}\` (${count}x)"$'\n'
+    FINDING_COUNT=$((FINDING_COUNT + count))
+  fi
+done
+
+# === Scan for hyphenated-proper-noun + structural-metaphor suffix (bassclef#101) ===
+# Pattern: Capitalized-Word + "-" + Capitalized-Word (one or more hyphen pairs)
+# + space + one of (triangle | pyramid | spectrum | hexagon | gate)
+# Catches dense compound phrases like "Saltzer-Schroeder triangle",
+# "Linus-Torvalds gate", "Beck-Cunningham pyramid" — academic/architectural
+# jargon shape that slips past individual-word checks.
+# Negative cases preserved: "API gateway" (not hyphenated proper noun),
+# "circuit breaker" (suffix not in list).
+PROPER_NOUN_SHAPE_MATCHES=$(echo "$SCRUBBED" | grep -oE \
+  '[A-Z][a-z]+(-[A-Z][a-z]+)+ (triangle|pyramid|spectrum|hexagon|gate)\b' \
+  2>/dev/null)
+if [ -n "$PROPER_NOUN_SHAPE_MATCHES" ]; then
+  shape_count=$(echo "$PROPER_NOUN_SHAPE_MATCHES" | wc -l | tr -d ' ')
+  FINDINGS="${FINDINGS}- dense compound shape (${shape_count}x) — proper-noun + structural-metaphor — see bassclef#101 — rewrite in plain English"$'\n'
+  FINDING_COUNT=$((FINDING_COUNT + shape_count))
+fi
+
+# === Scan for option-label Greek (bassclef#1286) ===
+# Pattern: (option|shape|pick|tier|approach|step|item|path|alternative) + whitespace + Greek letter
+# Greek lowercase α-ω: α-ω ; Greek uppercase Α-Ω: Α-Ω
+# Using ripgrep-compatible PCRE class via grep -P (GNU grep) when available; falling
+# back to a literal alternation of common Greek letters for portability.
+OPTION_LABEL_GREEK_MATCHES=$(echo "$SCRUBBED" | grep -ioE \
+  '(option|shape|pick|tier|approach|step|item|path|alternative)[[:space:]]+(α|β|γ|δ|ε|ζ|η|θ|ι|κ|λ|μ|ν|ξ|ο|π|ρ|σ|τ|υ|φ|χ|ψ|ω|Α|Β|Γ|Δ|Ε|Ζ|Η|Θ|Ι|Κ|Λ|Μ|Ν|Ξ|Ο|Π|Ρ|Σ|Τ|Υ|Φ|Χ|Ψ|Ω)' \
+  2>/dev/null)
+if [ -n "$OPTION_LABEL_GREEK_MATCHES" ]; then
+  option_label_count=$(echo "$OPTION_LABEL_GREEK_MATCHES" | wc -l | tr -d ' ')
+  FINDINGS="${FINDINGS}- option-label Greek (${option_label_count}x) — see bassclef#1286 + .claude/rules/option-label-discipline.md — use a/b/c or 1/2/3 instead"$'\n'
+  FINDING_COUNT=$((FINDING_COUNT + option_label_count))
+fi
+
+# === Scan for retired WU-N vocab in new prose (bassclef-web#202) ===
+# ADR-040 D1 renamed "WU-N" → "Step N". Grace window through 2026-10-31 preserves
+# READ compatibility via standards/vocabulary-migration.json — historical refs in
+# closed PRs, past chronicles, memory files stay as-is. NEW authored prose uses
+# the new terms. Backticked refs like `WU-3` are stripped by SCRUBBED at L164 so
+# quoted historical goal IDs pass through cleanly. Only unbacked WU-N in prose fires.
+WU_N_VOCAB_MATCHES=$(echo "$SCRUBBED" | grep -oE '\bWU-[0-9]+\b' 2>/dev/null)
+if [ -n "$WU_N_VOCAB_MATCHES" ]; then
+  wu_n_count=$(echo "$WU_N_VOCAB_MATCHES" | wc -l | tr -d ' ')
+  FINDINGS="${FINDINGS}- retired WU-N vocab (${wu_n_count}x) — see bassclef-web#202 + ADR-040 D1 rename table — say Step N in new prose; wrap historical goal IDs in backticks"$'\n'
+  FINDING_COUNT=$((FINDING_COUNT + wu_n_count))
+fi
+
+# === Per-place strict escalation (bassclef#1171) ===
+# When global mode is advisory + BLOCK findings exist + the message matches
+# a named strict-place pattern, escalate that message to strict (exit 2).
+#
+# Two detection paths per place:
+#   1. Marker file at state/markers/turn-prose-surface/<surface>.marker —
+#      the SKILL.md procedure touches this before posting; precise. (bassclef#1304)
+#   2. Content pattern grep on SCRUBBED — heuristic fallback for the V1
+#      3 places (closeout_blocks, summary_tables, next_pickup).
+EFFECTIVE_MODE="$MODE"
+ESCALATING_PLACE=""
+
+# Repo root for marker lookup
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+SURFACE_MARKER_DIR="${REPO_ROOT}/state/markers/turn-prose-surface"
+
+if [ "$MODE" = "advisory" ] && [ "$FINDING_COUNT" -gt 0 ] && [ -n "$STRICT_PLACES" ]; then
+  IFS=',' read -ra PLACE_ARRAY <<< "$STRICT_PLACES"
+  for place in "${PLACE_ARRAY[@]}"; do
+    place_trimmed=$(echo "$place" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+    # Path 1: marker-file detection (precise; bassclef#1304)
+    if [ -f "${SURFACE_MARKER_DIR}/${place_trimmed}.marker" ]; then
+      EFFECTIVE_MODE="strict"
+      ESCALATING_PLACE="${place_trimmed} (marker)"
+      break
+    fi
+
+    # Path 2: content-pattern heuristics (V1 fallback)
+    case "$place_trimmed" in
+      closeout_blocks)
+        if echo "$SCRUBBED" | grep -qE '^## Closeout audit'; then
+          EFFECTIVE_MODE="strict"
+          ESCALATING_PLACE="closeout_blocks"
+          break
+        fi
+        ;;
+      summary_tables)
+        if echo "$SCRUBBED" | grep -qE '^## Status[[:space:]]*$'; then
+          EFFECTIVE_MODE="strict"
+          ESCALATING_PLACE="summary_tables"
+          break
+        fi
+        ;;
+      next_pickup)
+        if echo "$SCRUBBED" | grep -qE '^## Next pickup'; then
+          EFFECTIVE_MODE="strict"
+          ESCALATING_PLACE="next_pickup"
+          break
+        fi
+        ;;
+    esac
+  done
+fi
+
+# === Skill-dispatch citation check (V1 ADVISORY — bassclef-upstream#374) ===
+# When a /longrun-surface marker exists at state/markers/turn-prose-surface/
+# <surface>.marker, scan the message for a skill-dispatch citation per
+# operator-facing-prose.md Rule 3. Emit ADVISORY if citation missing.
+# Named surfaces: longrun_prep_proposal, longrun_checkpoint, longrun_closeout, status_update.
+SKILL_CITATION_MISSING=""
+for surface in longrun_prep_proposal longrun_checkpoint longrun_closeout status_update; do
+  if [ -f "${SURFACE_MARKER_DIR}/${surface}.marker" ]; then
+    # Citation patterns: backtick-wrapped /skill mention, or named discipline blocks.
+    if ! echo "$MESSAGE_TEXT" | grep -qE '(via `/[a-z][a-z -]*`|per `/[a-z][a-z -]*`|\(via /[a-z-]+\)|drafted by `/[a-z][a-z -]*`|## /temperance \+ /luminary \+ /loop discipline|\*\*/temperance\*\*|\*\*/luminary\*\*|\*\*Flash \(via `|via /[a-z-]+ )'; then
+      SKILL_CITATION_MISSING="${SKILL_CITATION_MISSING}${surface} "
+    fi
+  fi
+done
+
+if [ -n "$SKILL_CITATION_MISSING" ]; then
+  cat >&2 <<EOF
+[turn-prose-kiss-check: ADVISORY — skill-dispatch citation missing on surface(s): ${SKILL_CITATION_MISSING}]
+  Per .claude/rules/operator-facing-prose.md Rule 3 (bassclef-upstream#374):
+  every /longrun-dispatched session-conversation surface declares the
+  dispatched skill via inline citation (e.g., "via \`/value-prop flash\`",
+  "drafted by \`/state-a-problem brief\`") or a short discipline-marker line.
+  V1 advisory; V2 (deferred) BLOCKs net-new surfaces without citation.
+EOF
+fi
+
+# === Appositive presence check (V1 ADVISORY — bassclef-upstream#1313) ===
+# Per .claude/rules/operator-facing-prose.md Rule 1 broader appositive
+# amendment. Scans for shorthand patterns and checks each match for an
+# adjacent appositive (parenthetical, comma phrase, em-dash) within 40
+# characters. Emits ADVISORY line per shorthand without adjacent
+# appositive. Structural check only — operator judgment catches
+# shorthand-inside-appositive.
+#
+# Override per-call: SKIP_APPOSITIVE_CHECK=1
+if [ "${SKIP_APPOSITIVE_CHECK:-0}" != "1" ]; then
+  APPOSITIVE_FINDINGS=$(printf '%s' "$MESSAGE_TEXT" | python3 -c '
+import re, sys
+
+text = sys.stdin.read()
+
+# Shorthand patterns — session-invented or bassclef substrate refs
+patterns = [
+    (r"(?<![a-zA-Z0-9_/])#(\d+)\b", "ticket"),
+    (r"\bBucket\s+[A-Z]\d?[a-z]?\b", "Bucket label"),
+    (r"\bOption\s+[a-z]\b", "Option letter"),
+    (r"\bShip\s+\d+\b", "Ship label"),
+    (r"\bWave\s+\d+\b", "Wave label"),
+]
+
+# Appositive shapes within 40 chars after the shorthand:
+#   \s*(          — optional whitespace then
+#     \(          — parenthetical
+#     |,\s+\w     — comma + space + word
+#     |—\s*\w     — em-dash + word
+#     |:\s+\w     — colon + word
+#     |\s—\s+\w   — spaced em-dash + word
+#   )
+appositive_re = re.compile(r"^\s*(\(|,\s+\w|—\s*\w|:\s+\w|-\s+\w)")
+
+flagged = []
+for pattern, label in patterns:
+    for m in re.finditer(pattern, text):
+        end = m.end()
+        following = text[end:end+40]
+        if not appositive_re.match(following):
+            # Extract surrounding context for the finding
+            context_start = max(0, m.start() - 10)
+            context_end = min(len(text), m.end() + 30)
+            snippet = text[context_start:context_end].replace("\n", " ")
+            flagged.append(f"{label} \"{m.group(0)}\" — no adjacent appositive (context: \"...{snippet}...\")")
+
+for f in flagged[:5]:  # cap at 5 findings per turn to avoid noise
+    print(f)
+' 2>/dev/null)
+
+  if [ -n "$APPOSITIVE_FINDINGS" ]; then
+    cat >&2 <<EOF
+[turn-prose-kiss-check: ADVISORY — appositive discipline (bassclef-upstream#1313)]
+Shorthand without adjacent appositive found:
+
+${APPOSITIVE_FINDINGS}
+
+Per .claude/rules/operator-facing-prose.md Rule 1 broader appositive amendment:
+every shorthand at any mention benefits from a comma phrase, parenthetical,
+or em-dash appositive that renames or explains it. Appositive text must be
+plain-language for a cold reader (not more shorthand).
+Override one-time: SKIP_APPOSITIVE_CHECK=1.
+V1 advisory; V2 (deferred) BLOCKs after calibration.
+EOF
+  fi
+fi
+
+# === Emit findings + exit per mode ===
+if [ "$FINDING_COUNT" -gt 0 ]; then
+  PLACE_NOTE=""
+  if [ -n "$ESCALATING_PLACE" ]; then
+    PLACE_NOTE=$'\n''Escalated to strict by named place: '"${ESCALATING_PLACE}"' (bassclef#1171).'
+  fi
+  cat >&2 <<EOF
+🛑 /kiss turn-prose check — ${FINDING_COUNT} BLOCK-term finding(s) in your most recent message:
+
+${FINDINGS}
+Rewrite using plain-English alternatives from standards/bassclef-internal-jargon.md.
+Reserved allowlist holds: substrate, bassclef, cameo, Studio, Band, bandleader.
+
+Mode: ${EFFECTIVE_MODE}. Toggle: .claude/bassclef-configs.jsonc → prose_discipline.kiss_words_turn_prose.${PLACE_NOTE}
+Override one-time: SKIP_TURN_PROSE_KISS=1.
+
+Closes bassclef#1027 wrong-premise (hook surfaces CAN reach turn prose via Stop event).
+EOF
+  if [ "$EFFECTIVE_MODE" = "strict" ]; then
+    exit 2
+  fi
+  exit 0
+fi
+
+exit 0

package/substrate/.claude/hooks/vocabulary-migration-check.sh

@@ -0,0 +1,171 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# vocabulary-migration-check.sh — PreToolUse Edit|Write gate on
+# .claude/skills/*/SKILL.md. Reads old vocabulary terms from
+# standards/vocabulary-migration.json and BLOCKs when a SKILL edit
+# contains an old term outside code blocks and HTML comments.
+#
+# Fills the gap #764 named — /skill's new-composition path runs
+# vocabulary checks, but direct Edit calls on existing SKILL bodies
+# bypass them. This hook adds a dedicated gate at the edit surface.
+#
+# Composes with:
+# - skill-body-grade-gate.sh (grade cap)
+# - compound-noun-scrub.sh (hyphenated jargon)
+# - substrate-clarity-gate.sh (INSTEAD-block + description shape)
+#
+# Input (stdin): JSON — tool_name, tool_input.file_path, tool_input.new_string / .content
+# Exit: 0 pass, 2 block
+#
+# Override per-call: SKIP_VOCABULARY_MIGRATION=1
+#
+# Per @luminary tony-hoare (precondition contracts)
+# + @luminary kent-beck (Tier 0 strict TDD)
+
+set +e
+
+# === Override path ===
+if [ "${SKIP_VOCABULARY_MIGRATION:-0}" = "1" ]; then
+  exit 0
+fi
+
+# === Parse stdin JSON ===
+STDIN_JSON=$(cat 2>/dev/null || echo '{}')
+
+# Bail on unparseable JSON
+if ! echo "$STDIN_JSON" | jq -e . >/dev/null 2>&1; then
+  exit 0
+fi
+
+TOOL_NAME=$(echo "$STDIN_JSON" | jq -r '.tool_name // ""' 2>/dev/null)
+FILE_PATH=$(echo "$STDIN_JSON" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+
+# Only fire on Write or Edit
+if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then
+  exit 0
+fi
+
+# Only fire on .claude/skills/*/SKILL.md
+case "$FILE_PATH" in
+  *".claude/skills/"*"/SKILL.md")
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# === Locate vocabulary-migration.json ===
+# Try project-relative path first, then via hook-inject helpers if available.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MIGRATION_FILE=""
+for candidate in \
+  "${CLAUDE_PROJECT_DIR:-}/standards/vocabulary-migration.json" \
+  "${SCRIPT_DIR}/../../standards/vocabulary-migration.json" \
+  "$(pwd)/standards/vocabulary-migration.json"; do
+  if [ -n "$candidate" ] && [ -f "$candidate" ]; then
+    MIGRATION_FILE="$candidate"
+    break
+  fi
+done
+
+# If we cannot find the migration file, pass through (soft dep)
+if [ -z "$MIGRATION_FILE" ]; then
+  exit 0
+fi
+
+# === Extract old terms + new mappings ===
+# Read old→new pairs into an associative array-ish shell layout.
+# Format: OLD_TERMS is a newline-separated list of "old|new" pairs.
+OLD_TERMS=$(jq -r '.renames[] | "\(.old)|\(.new)"' "$MIGRATION_FILE" 2>/dev/null)
+if [ -z "$OLD_TERMS" ]; then
+  exit 0
+fi
+
+# === Extract candidate content ===
+# For Edit: new_string is what lands in the file.
+# For Write: content is the whole file.
+CONTENT=$(echo "$STDIN_JSON" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+if [ -z "$CONTENT" ]; then
+  exit 0
+fi
+
+# === Strip YAML frontmatter, code blocks, inline code, HTML comments, file paths ===
+# YAML frontmatter (first --- ... --- block) is structured metadata, not prose
+STRIPPED=$(echo "$CONTENT" | awk '
+  BEGIN { in_fm = 0; fm_done = 0 }
+  NR == 1 && /^---[[:space:]]*$/ { in_fm = 1; next }
+  in_fm && /^---[[:space:]]*$/ { in_fm = 0; fm_done = 1; next }
+  in_fm { next }
+  { print }
+')
+STRIPPED=$(echo "$STRIPPED" | awk '
+  BEGIN { in_code = 0 }
+  /^```/ { in_code = !in_code; next }
+  in_code { next }
+  { print }
+')
+# Strip inline code (backtick-wrapped)
+STRIPPED=$(echo "$STRIPPED" | sed -E 's/`[^`]*`//g')
+# Strip HTML comments (single-line variant covers most cases)
+STRIPPED=$(echo "$STRIPPED" | sed -E 's/<!--[^>]*-->//g')
+# Strip file paths (contain slashes + extensions)
+STRIPPED=$(echo "$STRIPPED" | sed -E 's|[a-zA-Z0-9_./-]*\.(md\|json\|sh\|yml\|py\|js\|jsonc)||g')
+
+# === Scan for old terms ===
+FOUND_HITS=""
+while IFS='|' read -r OLD NEW; do
+  [ -z "$OLD" ] && continue
+  # Skip 1-2 letter renames (false positive risk)
+  if [ "${#OLD}" -lt 3 ]; then
+    continue
+  fi
+  # Context-aware check for "shape" — only flag when it labels an operator choice
+  # Per standards/vocabulary-migration.json L77: rename applies ONLY when 'shape'
+  # labels an operator pick like "shape a", "shape b", "pick shape α"
+  if [ "$OLD" = "shape" ]; then
+    if echo "$STRIPPED" | grep -qiE "\\bshape [a-fA-F1-9αβγδε]\\b|pick shape\\b|choose shape\\b|shape [ABCDEF]\\b"; then
+      FOUND_HITS="${FOUND_HITS}${OLD} → ${NEW} (labels an operator choice)\n"
+    fi
+    continue
+  fi
+  # Standard word-boundary match for other terms
+  if echo "$STRIPPED" | grep -qiE "\\b${OLD}\\b"; then
+    FOUND_HITS="${FOUND_HITS}${OLD} → ${NEW}\n"
+  fi
+done <<< "$OLD_TERMS"
+
+if [ -z "$FOUND_HITS" ]; then
+  exit 0
+fi
+
+# === BLOCK ===
+cat >&2 <<EOF
+
+============================================
+🛑 VOCABULARY-MIGRATION GATE — BLOCKED 🛑
+============================================
+
+File:  $FILE_PATH
+Tool:  $TOOL_NAME
+
+Old vocabulary term(s) found in edit. Rename per
+standards/vocabulary-migration.json (ADR-040 D1):
+
+$(printf "$FOUND_HITS" | sed 's/^/  - /')
+
+Cure paths:
+  1. Rewrite the sentence using the new term (preferred)
+  2. If the old term is a verbatim quote from a historical artifact,
+     wrap in an HTML comment or code fence
+  3. Override with SKIP_VOCABULARY_MIGRATION=1 (logged) — rare
+
+Per .claude/rules/we-dont-break-adopters.md — grace window on
+old vocabulary through 2026-10-31; but new writes should land in
+the new vocabulary.
+
+Per ADR-040 Decision 1 (planning-skill vocabulary rewrite).
+============================================
+EOF
+
+exit 2