@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/hooks/bet-doc-gate.sh

@@ -0,0 +1,283 @@
+#!/usr/bin/env bash
+# tier: lite
+# bet-doc-gate.sh — PreToolUse Edit|Write|MultiEdit on docs/iteration-bets/*.md
+#
+# Composes two substrate disciplines at the bet-doc artifact-edit surface:
+#
+#   1. Thread-walk gate (per .claude/rules/arc-level-orientation-before-leaf.md)
+#      — marker required at state/markers/arc-walk/<goal-slug>.marker
+#      — closes bassclef-upstream#300
+#
+#   2. Produces/consumes substantive check (per .claude/rules/wu-sequencing-compounds.md)
+#      — Consumes cells in steps table must name concrete artifacts
+#        (file paths, marker paths, decision names, backtick-quoted refs)
+#        OR explicitly carry "parallel-safe (no consumer)"
+#        OR contain "session-start" / "union of" (prep / closeout shapes)
+#      — WARN on vague-prose ("WU-N's stable enforcement", "wired hook", etc.)
+#      — closes bassclef-upstream#21 (V2 mechanical layer of wu-sequencing-compounds)
+#
+# Closes the V1-methodology-only debt for both rules. Per memory
+# feedback_hooks_beat_methodology_for_substrate_quality.
+#
+# Behavior:
+#   - Fires on Edit|Write|MultiEdit PreToolUse when target matches docs/iteration-bets/*.md
+#   - Reads tool_name + tool_input.file_path from stdin JSON (PreToolUse contract)
+#     OR from BASSCLEF_BET_DOC_GATE_TEST_TOOL / BASSCLEF_BET_DOC_GATE_TEST_FILE env vars (testability)
+#   - Silent on non-matching paths or non-Edit tool calls
+#   - BLOCK (exit 2) when thread-walk marker missing or stale
+#   - WARN (exit 0 with stderr) when produces/consumes table has vague-prose cells (advisory V1; V3 escalates if drift persists)
+#   - Allowlist baseline at .claude/hooks/bet-doc-gate-allowlist.txt grandfathers existing un-walked goal docs
+#
+# Overrides (all logged via trace-helper):
+#   SKIP_BET_DOC_GATE=1             — bypass both checks
+#   SKIP_ARC_WALK_GATE=1             — bypass thread-walk only (P/C still runs)
+#   SKIP_PRODUCES_CONSUMES_CHECK=1   — bypass P/C only (thread-walk still runs)
+
+set -euo pipefail
+# Saltzer-Schroeder Discipline 1 (strict mode at the top) per .claude/rules/defensive-bash.md.
+# Non-fatal commands carry `|| true` per-line where their non-zero exit is the expected path.
+
+# === Override (logged) ===
+if [ "${SKIP_BET_DOC_GATE:-0}" = "1" ]; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "bet-doc-gate" "skipped via SKIP_BET_DOC_GATE=1" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# === Parse input: test env vars first, else stdin JSON ===
+TOOL_NAME="${BASSCLEF_BET_DOC_GATE_TEST_TOOL:-}"
+FILE_PATH="${BASSCLEF_BET_DOC_GATE_TEST_FILE:-}"
+
+if [ -z "$TOOL_NAME" ] && [ -z "$FILE_PATH" ]; then
+  if [ ! -t 0 ]; then
+    INPUT=$(cat)
+    if [ -n "$INPUT" ] && command -v jq >/dev/null 2>&1; then
+      TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+      FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+    fi
+  fi
+fi
+
+# === Tool matcher ===
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# === Path matcher (absolute or relative; both shapes accepted) ===
+case "$FILE_PATH" in
+  */docs/iteration-bets/*.md) ;;
+  docs/iteration-bets/*.md) ;;
+  *) exit 0 ;;
+esac
+
+# === Extract goal slug (basename without extension) ===
+BET_BASE=$(basename "$FILE_PATH" .md)
+
+# === Allowlist check ===
+ALLOWLIST=".claude/hooks/bet-doc-gate-allowlist.txt"
+if [ -f "$ALLOWLIST" ]; then
+  if grep -Fxq "$BET_BASE" "$ALLOWLIST" 2>/dev/null; then
+    exit 0
+  fi
+fi
+
+# === Arc-walk check (unless SKIP_ARC_WALK_GATE=1) ===
+ARC_MARKER="state/markers/arc-walk/${BET_BASE}.marker"
+if [ "${SKIP_ARC_WALK_GATE:-0}" != "1" ]; then
+  if [ ! -f "$ARC_MARKER" ]; then
+    cat >&2 <<EOF
+
+============================================
+🛑 BLOCKED: bet-doc-gate (thread-walk)
+============================================
+
+You are editing a goal doc without prior parent-goal walk evidence in this session.
+
+Goal: ${BET_BASE}
+Missing marker: state/markers/thread-walk/${BET_BASE}.marker
+                (writes resolve to state/markers/arc-walk/ per compat
+                 window through 2026-10-31; both paths accepted)
+
+Per .claude/rules/arc-level-orientation-before-leaf.md — walk the parent_bet
+chain up to the root before editing. Surface drivers plus open acceptance plus
+out-of-scope from each ancestor.
+
+To resolve:
+  1. Walk the chain: read docs/iteration-bets/${BET_BASE}.md frontmatter,
+     then follow parent_bet up to the root
+  2. Surface drivers plus open acceptance plus out_of_scope per ancestor
+  3. Touch the marker:
+       mkdir -p state/markers/thread-walk/
+       touch state/markers/thread-walk/${BET_BASE}.marker
+
+Overrides (logged via trace-helper):
+  SKIP_ARC_WALK_GATE=1  — skip the parent-goal walk check only
+  SKIP_BET_DOC_GATE=1   — skip both checks
+
+Closes bassclef-upstream#300 + #21 (composed).
+============================================
+EOF
+    if [ -x ".claude/hooks/trace-helper.sh" ]; then
+      bash .claude/hooks/trace-helper.sh "bet-doc-gate" "BLOCKED thread-walk on ${BET_BASE}" 2>/dev/null || true
+    fi
+    exit 2
+  fi
+fi
+
+# === Produces/consumes substantive check (unless SKIP_PRODUCES_CONSUMES_CHECK=1) ===
+if [ "${SKIP_PRODUCES_CONSUMES_CHECK:-0}" = "1" ]; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  # New file (Write before content lands); nothing to scan
+  exit 0
+fi
+
+# Find the steps table header line.
+# Accepts two shapes (per bassclef-upstream#688):
+#   3-col: | WU | Produces | Consumes (from prior WU) |
+#   6-col: | WU | Problem + value prop | Produces | Consumes (from prior WU) | How this step builds on the prior | Risk |
+# The optional group before "Produces" swallows the "Problem + value prop"
+# column when the six-column shape is used.
+HEADER_INFO=$(grep -nE '^\| WU \|( [^|]* \|)? Produces \| Consumes \(from prior WU\) \|' "$FILE_PATH" 2>/dev/null | head -1 || true)
+if [ -z "$HEADER_INFO" ]; then
+  # No steps table; nothing to scan
+  exit 0
+fi
+
+HEADER_LNUM=$(echo "$HEADER_INFO" | cut -d: -f1)
+# Detect column shape by counting pipes in the header line.
+# 3-col header has 4 pipes; 6-col header has 7 pipes.
+# Consumes cell is field 4 in 3-col; field 5 in 6-col (awk splits on '|'
+# and prepends an empty field before the first pipe).
+HEADER_LINE=$(sed -n "${HEADER_LNUM}p" "$FILE_PATH")
+PIPE_COUNT=$(echo "$HEADER_LINE" | tr -cd '|' | wc -c | tr -d ' ')
+if [ "$PIPE_COUNT" -ge 7 ]; then
+  CONSUMES_FIELD=5
+else
+  CONSUMES_FIELD=4
+fi
+# Skip header + separator (lines header_lnum and header_lnum+1)
+START=$((HEADER_LNUM + 2))
+
+# Scan rows until empty line or non-pipe line
+VAGUE_HITS=""
+LNUM=$START
+while IFS= read -r line; do
+  case "$line" in
+    "|"*)
+      # Pipe-separated row. Extract Consumes cell at CONSUMES_FIELD
+      # (field 4 in 3-col shape, field 5 in 6-col shape).
+      CONSUMES=$(echo "$line" | awk -F'|' -v f="$CONSUMES_FIELD" '{print $f}' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+      if [ -z "$CONSUMES" ]; then
+        LNUM=$((LNUM+1)); continue
+      fi
+
+      # PASS patterns: explicit parallel-safe, session-start, union-of-closeout,
+      # backtick-quoted reference, slash-path, .sh/.md/.json/.yml extension
+      if echo "$CONSUMES" | grep -qE 'parallel-safe \(no consumer\)|session-start|union of|`[^`]+`|/[a-zA-Z]|\.sh\b|\.md\b|\.json\b|\.yml\b'; then
+        LNUM=$((LNUM+1)); continue
+      fi
+
+      # WARN pattern: starts with WU-N or WU-N's followed by vague prose without
+      # any concrete artifact reference
+      if echo "$CONSUMES" | grep -qE "^WU-[0-9]+'?s?\b"; then
+        VAGUE_HITS="${VAGUE_HITS}  line ${LNUM}: ${CONSUMES}
+"
+      fi
+      ;;
+    "") break ;;
+    *) break ;;
+  esac
+  LNUM=$((LNUM+1))
+done < <(tail -n +"$START" "$FILE_PATH")
+
+if [ -n "$VAGUE_HITS" ]; then
+  cat >&2 <<EOF
+
+============================================
+⚠️  WARN: bet-doc-gate (produces/consumes)
+============================================
+
+Bet: ${BET_BASE}
+
+The following Consumes cells contain vague-prose references that may not
+name concrete artifacts the next WU's source actually reads:
+
+${VAGUE_HITS}
+Per .claude/rules/wu-sequencing-compounds.md — each Consumes cell should
+name a concrete artifact (file path, marker path, decision name) OR
+explicitly carry "parallel-safe (no consumer)" when the step is independent.
+
+This is advisory (V1). Flips to BLOCK if observable drift continues
+(V3 follow-on per feedback_hooks_beat_methodology_for_substrate_quality).
+
+Overrides (logged):
+  SKIP_PRODUCES_CONSUMES_CHECK=1  — skip P/C only
+  SKIP_BET_DOC_GATE=1             — skip both
+
+Closes bassclef-upstream#21.
+============================================
+EOF
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "bet-doc-gate" "WARN produces/consumes on ${BET_BASE}" 2>/dev/null || true
+  fi
+fi
+
+# === Closeout enforcement check (unless SKIP_CLOSEOUT_ENFORCE=1) ===
+# Fires when goal frontmatter marks the goal as complete AND no ## Closeout
+# section exists. Prevents the 103-orphan class from recurring — per
+# whereami operator_recap_2026-08-04e Phase 1b, 103 of 107 goal docs closed
+# without a Closeout section; metrics undercounted by 96% until backfilled.
+# V1 ADVISORY (WARN via stderr; exit 0 continues). V2 flips to BLOCK after
+# allowlist baseline clears. Per bassclef-upstream#1081 + .claude/rules/session-artifacts.md.
+if [ "${SKIP_CLOSEOUT_ENFORCE:-0}" != "1" ]; then
+  # Read status field from YAML frontmatter (first `status: X` line inside first --- block)
+  BET_STATUS=$(awk '/^---$/{c++; next} c==1 && /^status:/{sub(/^status: */, ""); sub(/[[:space:]]*$/, ""); print; exit}' "$FILE_PATH" 2>/dev/null || echo "")
+
+  case "$BET_STATUS" in
+    complete|shipped|closed|done)
+      # Bet marks itself complete; check for closeout section
+      if ! grep -qiE "^## Closeout" "$FILE_PATH" 2>/dev/null; then
+        cat >&2 <<EOF
+
+============================================
+⚠️  WARN: bet-doc-gate (closeout section)
+============================================
+
+Bet: ${BET_BASE}
+Status: ${BET_STATUS}
+
+The goal frontmatter marks this as complete but no "## Closeout" section
+exists in the body. Metrics velocity view undercounts closed work when the
+section is missing.
+
+Per .claude/rules/session-artifacts.md — completed goals ship a Closeout
+section documenting what landed + what deferred + retro links.
+
+This is advisory (V1). Flips to BLOCK after allowlist baseline clears
+(V2 per feedback_hooks_beat_methodology_for_substrate_quality).
+
+Overrides (logged):
+  SKIP_CLOSEOUT_ENFORCE=1         — skip closeout check only
+  SKIP_BET_DOC_GATE=1             — skip all bet-doc gate checks
+
+Closes bassclef-upstream#1081.
+============================================
+EOF
+        if [ -x ".claude/hooks/trace-helper.sh" ]; then
+          bash .claude/hooks/trace-helper.sh "bet-doc-gate" "WARN closeout missing on ${BET_BASE}" 2>/dev/null || true
+        fi
+      fi
+      ;;
+    *)
+      # Bet not marked complete (or status unset) — skip; only fires on complete bets
+      :
+      ;;
+  esac
+fi
+
+exit 0

package/dist/lite/.claude/hooks/bug-diagnosis.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# tier: lite
+set -e
+
+# Bug Diagnosis hook — fires on UserPromptSubmit.
+# Safety net: keyword detection injects diagnosis reminder.
+#
+# IMPORTANT: This hook is a SAFETY NET, not the process.
+# The agent is responsible for self-triggering diagnosis when
+# it recognizes a failure in any form — including screenshots,
+# implicit phrasing, and logs that this keyword matcher cannot detect.
+
+INPUT=$(cat)
+# Per bassclef#1125: fail-soft on jq parse failure (malformed stdin JSON
+# returns jq exit 5; set -e would crash the hook).
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""' 2>/dev/null | tr '[:upper:]' '[:lower:]' || echo "")
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Strong match: explicit defect/failure keywords → full diagnosis block
+if echo "$PROMPT" | grep -qiE '\b(bug|defect|regress(ion)?|flaky|intermittent)\b|\b(crash|panic|abort|sigkill|oom|segfault)\b|\b(broken|corrupt|stale|stuck|hung|hanging|frozen|deadlock|infinite.loop)\b|\b(404|500|502|503|504|redirect.loop|cors.error)\b|\b(timeout|timed.out|memory.leak|high.cpu)\b|\b(unreachable|not.responding|connection.refused)\b|\b(not.working|doesn.t.work|won.t.start|stopped.working|blank.page|white.screen)\b'; then
+  source "$SCRIPT_DIR/trace-helper.sh"
+  trace_log "bug-diagnosis" "defect keywords detected"
+  cat <<'DIAG'
+============================================
+BUG/FAILURE DETECTED — RUN /diagnose FIRST
+============================================
+
+The user's message describes a bug, error, or failure.
+Run the /diagnose skill BEFORE making ANY code changes.
+
+Do not Edit, Write, or run fix commands until you have written:
+1. Is / Is Not
+2. Five Whys
+3. Hypothesis + Test
+
+If this is actually a design discussion (not a bug), state that
+and proceed normally.
+============================================
+DIAG
+  exit 0
+fi
+
+# Weak match: phrases that often accompany failures — lighter reminder
+if echo "$PROMPT" | grep -qiE '(fix|re-run|re.run|how do we|throws|error|issue|wrong|problem|diagnose|screenshot|logs show|FAIL)'; then
+  cat <<'REMIND'
+============================================
+POSSIBLE FAILURE — CHECK BEFORE FIXING
+============================================
+
+This message may describe a failure (screenshot, log, or implicit).
+The hook cannot always detect failures — YOU must judge:
+
+- Is the user reporting something that isn't working as expected?
+- Are they showing a screenshot with errors or unexpected output?
+- Are they asking "how do we fix/re-run X"?
+
+If YES → run /diagnose BEFORE writing any fix.
+If NO → proceed normally.
+============================================
+REMIND
+fi
+
+exit 0

package/dist/lite/.claude/hooks/destructive-command-guard.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+# tier: lite
+# Destructive Command Guard — fires on Bash PreToolUse.
+# Detects destructive SIGNALS in any command, not specific tools.
+# Forces a temperance pause before proceeding.
+#
+# Design: signal-based, not command-specific. Instead of hardcoding
+# "prisma migrate reset", we detect the PATTERN of destruction:
+# destructive verbs + force flags + amplifiers. This catches tools
+# we haven't seen yet.
+#
+# Origin: operator manually invoked /temperance to prevent a prisma
+# migrate reset that would have destroyed dev data. A single DELETE
+# on a stale migration row was the actual fix.
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+
+# Skip empty commands
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# === Safe command allowlist (skip quickly for common operations) ===
+# These are high-frequency, never destructive — skip to avoid latency.
+if echo "$COMMAND" | grep -qE '^(git (status|diff|log|show|branch --show)|ls |cat |head |tail |wc |echo |which |test |pwd|cd )'; then
+  exit 0
+fi
+
+# === Signal-based destructive detection ===
+#
+# Three signal types, scored by severity:
+#   VERB:      destructive action word (reset, drop, delete, destroy, purge, etc.)
+#   FORCE:     flag that bypasses confirmation (--force, --hard, -f, -rf, --yes)
+#   AMPLIFIER: scope expansion (CASCADE, --all, --volumes, recursive, -r)
+#
+# Scoring:
+#   VERB alone        = MEDIUM (warn)
+#   VERB + FORCE      = HIGH (strong warn)
+#   VERB + AMPLIFIER  = HIGH
+#   VERB + FORCE + AMPLIFIER = CRITICAL
+
+VERB=""
+FORCE=""
+AMPLIFIER=""
+
+# --- Detect destructive verbs ---
+# These words signal intent to destroy state
+if echo "$COMMAND" | grep -qiE '\b(reset|drop|delete|destroy|purge|prune|wipe|clean|truncate|obliterate|nuke|flush|drain|evict|overwrite|revert|rollback|format|erase|clear|demolish|discard|abort|terminate|revoke|invalidate|expire|uninstall|deregister|detach)\b'; then
+  VERB=$(echo "$COMMAND" | grep -oiE '\b(reset|drop|delete|destroy|purge|prune|wipe|clean|truncate|obliterate|nuke|flush|drain|evict|overwrite|revert|rollback|format|erase|clear|demolish|discard|abort|terminate|revoke|invalidate|expire|uninstall|deregister|detach)\b' | head -1)
+fi
+# "remove" only counts with a force/recursive flag (otherwise it's just rm file.txt)
+if [ -z "$VERB" ] && echo "$COMMAND" | grep -qiE '\bremove\b' && echo "$COMMAND" | grep -qE '\-(r|f|rf|fr)\b|--force|--recursive'; then
+  VERB="remove"
+fi
+# "rm" only counts with a force/recursive flag (otherwise it's just rm file.txt)
+# Per bassclef goal 2026-06-17a Phase Z-2: hardening discovered the rm gap.
+if [ -z "$VERB" ] && echo "$COMMAND" | grep -qE '\brm\b' && echo "$COMMAND" | grep -qE '\-(r|f|rf|fr)\b|--force|--recursive'; then
+  VERB="rm"
+fi
+# "push" only counts with --force (otherwise it's just git push)
+if [ -z "$VERB" ] && echo "$COMMAND" | grep -qE 'push.*--force|push.*-f\b'; then
+  VERB="force-push"
+fi
+
+# No destructive verb → exit early
+if [ -z "$VERB" ]; then
+  exit 0
+fi
+
+# --- Detect force flags ---
+if echo "$COMMAND" | grep -qE '\-\-(force|hard|yes|no-verify|skip-seed|no-prompt)\b|\s-f\b|\s-rf\b|\s-fr\b'; then
+  FORCE=$(echo "$COMMAND" | grep -oE '\-\-(force|hard|yes|no-verify|skip-seed|no-prompt)\b|\s-f\b|\s-rf\b' | head -1 | tr -d ' ')
+fi
+
+# --- Detect amplifiers ---
+if echo "$COMMAND" | grep -qiE 'CASCADE|--all\b|--volumes\b|--recursive\b|\s-r\b|--include-untracked|system\b'; then
+  AMPLIFIER=$(echo "$COMMAND" | grep -oiE 'CASCADE|--all|--volumes|--recursive|-r\b|--include-untracked|system' | head -1)
+fi
+
+# === Score severity ===
+if [ -n "$VERB" ] && [ -n "$FORCE" ] && [ -n "$AMPLIFIER" ]; then
+  SEVERITY="CRITICAL — forced + amplified destruction"
+elif [ -n "$VERB" ] && ([ -n "$FORCE" ] || [ -n "$AMPLIFIER" ]); then
+  SEVERITY="HIGH — forced or amplified destruction"
+else
+  SEVERITY="MEDIUM — destructive verb detected"
+fi
+
+# === Classify the domain ===
+CATEGORY="DESTRUCTIVE COMMAND"
+if echo "$COMMAND" | grep -qiE 'prisma|psql|mysql|sqlite|mongo|DROP|TRUNCATE|migrate'; then
+  CATEGORY="DATABASE DESTRUCTION"
+elif echo "$COMMAND" | grep -qiE 'docker|compose|container|volume|image'; then
+  CATEGORY="CONTAINER DESTRUCTION"
+elif echo "$COMMAND" | grep -qiE '^git |^gh '; then
+  CATEGORY="GIT DESTRUCTION"
+elif echo "$COMMAND" | grep -qiE '^rm |^find.*-delete|xargs.*rm'; then
+  CATEGORY="FILE DESTRUCTION"
+elif echo "$COMMAND" | grep -qiE 'node_modules|\.next|dist/|build/|cache'; then
+  CATEGORY="BUILD CACHE WIPE"
+fi
+
+# === Output temperance prompt ===
+echo ""
+echo "============================================"
+echo "⚠️  DESTRUCTIVE COMMAND — TEMPERANCE REQUIRED"
+echo "============================================"
+echo ""
+echo "Category: $CATEGORY"
+echo "Severity: $SEVERITY"
+echo "Signals:  verb=$VERB${FORCE:+ force=$FORCE}${AMPLIFIER:+ amplifier=$AMPLIFIER}"
+echo "Command:  $COMMAND"
+echo ""
+echo "BEFORE PROCEEDING, answer:"
+echo ""
+echo "1. ROOT CAUSE — What specific problem requires destruction?"
+echo "   (Not 'it's broken' — what exactly is wrong?)"
+echo ""
+echo "2. SIMPLER FIX — Is there a targeted alternative?"
+echo "   Common traps:"
+echo "   • DB checksum mismatch → fix the row, don't reset the DB"
+echo "   • Schema drift → create a migration, don't db push"
+echo "   • Dirty git state → commit or stash, don't reset --hard"
+echo "   • Failing tests → diagnose the test, don't wipe state"
+echo "   • Container issues → restart the service, don't prune all"
+echo "   • Build errors → clear the specific cache, don't rm -rf"
+echo ""
+echo "3. RECOVERY — If you proceed, can you undo it?"
+echo "   (Backup? Seed data? Git reflog? Docker image cache?)"
+echo ""
+echo "The simplest fix is almost never the most destructive one."
+echo "============================================"
+echo ""
+
+exit 0

package/dist/lite/.claude/hooks/file-rename-discipline-check.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# tier: lite
+# install-class: project
+# file-rename-discipline-check — PreToolUse hook that blocks `git commit`
+# Bash invocations when the staged changes delete a file under the
+# rule's scope without a matching entry in standards/file-renames.json.
+#
+# Per .claude/rules/file-rename-discipline.md — every file rename in
+# bassclef registers a map entry AND ships a fixture test. The rule's
+# methodology layer says do it; this hook is the mechanical layer that
+# fires on every commit.
+#
+# Why this exists: the 2026-06-21 rename of canonical-source-config-validate.sh
+# shipped without registering itself anywhere. POA's session on 2026-06-29
+# surfaced the gap eight days later. Bet 29e WU-9 shipped the cure; this
+# hook prevents the next rename from repeating the failure.
+#
+# Exit codes:
+#   0 — allow (non-matching Bash, no scoped deletions, all deletions registered, override)
+#   2 — block (one or more scoped deletions missing from the rename map)
+#
+# Override: SKIP_FILE_RENAME_DISCIPLINE=1 (logged via trace-helper)
+
+set +e
+
+INPUT=$(cat 2>/dev/null)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+
+# Only fire on Bash tool calls
+[ "$TOOL_NAME" = "Bash" ] || exit 0
+
+# Only fire on `git commit` invocations (not git status, not git diff, etc)
+case "$COMMAND" in
+  *"git commit"*) : ;;
+  *) exit 0 ;;
+esac
+
+# Skip via override (logged)
+if [ "${SKIP_FILE_RENAME_DISCIPLINE:-0}" = "1" ]; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "file-rename-discipline" "skipped via SKIP_FILE_RENAME_DISCIPLINE=1" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Resolve the rename map (env-var override for tests + curl-pipe scenarios)
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+RENAME_MAP="${BASSCLEF_RENAME_MAP:-$REPO_ROOT/standards/file-renames.json}"
+
+# If the rename map does not exist on this repo, the hook is dormant.
+# (Adopter repos don't ship the map; only bassclef-upstream does.)
+[ -f "$RENAME_MAP" ] || exit 0
+
+# Read staged deletions. `git diff --cached --diff-filter=D --name-only`
+# lists files deleted in the staged change.
+DELETIONS=$(git diff --cached --diff-filter=D --name-only 2>/dev/null)
+[ -n "$DELETIONS" ] || exit 0
+
+# Scope filter — only check deletions under the rule's path list.
+SCOPED_PATHS=(
+  ".claude/hooks/"
+  ".claude/skills/"
+  ".claude/rules/"
+  ".claude/luminaries/"
+  ".claude/agents/"
+  "scripts/"
+  "lib/"
+  "standards/"
+  "presence/"
+  "architecture/decisions/"
+)
+
+# Build the list of registered old_names from the rename map.
+# Both the renames array AND the compat_shims_preserved list are
+# considered "registered" — the rule allows both shapes.
+REGISTERED_NAMES=$(jq -r '
+  ((.renames // [])[]?.old_name),
+  ((.compat_shims_preserved // [])[]?.old_name)
+' "$RENAME_MAP" 2>/dev/null | sort -u)
+
+# Walk the deletions; flag any scoped deletion whose basename is missing
+# from the registered list.
+UNREGISTERED=""
+while IFS= read -r path; do
+  [ -n "$path" ] || continue
+  # Scope filter: skip deletions outside the rule's paths
+  in_scope=0
+  for scope in "${SCOPED_PATHS[@]}"; do
+    case "$path" in
+      "$scope"*) in_scope=1; break ;;
+    esac
+  done
+  [ "$in_scope" = "1" ] || continue
+
+  base=$(basename "$path")
+  if ! echo "$REGISTERED_NAMES" | grep -qFx "$base"; then
+    UNREGISTERED="$UNREGISTERED  - $path (basename: $base)"$'\n'
+  fi
+done <<< "$DELETIONS"
+
+# No unregistered scoped deletions → allow
+[ -z "$UNREGISTERED" ] && exit 0
+
+# Block with a structured remediation message
+cat <<MSG >&2
+============================================
+🛑 FILE-RENAME DISCIPLINE — BLOCKED 🛑
+============================================
+
+The staged commit deletes one or more files under the rule's scope without
+a matching entry in standards/file-renames.json. Per .claude/rules/file-rename-discipline.md
+every file rename registers a map entry plus a fixture test.
+
+Unregistered deletions:
+$UNREGISTERED
+
+Three required moves:
+
+  1. Add an entry under \`.renames\` in standards/file-renames.json:
+
+       {
+         "old_name": "<basename-being-deleted>",
+         "new_name": "<basename-of-the-successor-file>",
+         "renamed_at": "$(date +%Y-%m-%d)",
+         "category": "<hook|skill|rule|agent|luminary|script|lib|standard|adr>"
+       }
+
+  2. Ship a fixture under .claude/hooks/tests/fixtures/adopter-$(date +%Y-%m-%d)-rename/
+     that mirrors the adopter state after the rename ships. The migrate
+     script's test suite reads the fixture; assertions pin the cure.
+
+  3. Cite the rename in the goal doc or chronicle for this commit.
+
+Compat-shim case — when the old name keeps working via a different
+mechanism (e.g., dispatcher's canonical-sync.sh via ADR-032 two-stage rocket):
+add the entry under \`.compat_shims_preserved\` instead, with a reason field.
+
+Override (logged via trace-helper):  SKIP_FILE_RENAME_DISCIPLINE=1 git commit ...
+
+Use only for migrating bulk content or emergency rescue; routine renames
+register the entry.
+
+============================================
+MSG
+
+exit 2