@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/.claude/hooks/auto-save-idle.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# tier: lite
+# Auto-save idle checker — runs via cron on macOS + Linux + WSL (or Task Scheduler on native Windows) every 15 minutes.
+# Checks all watched repos for uncommitted changes and runs save-state.sh.
+#
+# Watched repos are listed below. Add new repos as they're created.
+
+# WATCHED_REPOS_OVERRIDE — colon-separated list for testing.
+# When unset, the production default applies (bassclef + poa).
+# See .claude/hooks/tests/auto-save-idle.test.sh for usage.
+if [ -n "${WATCHED_REPOS_OVERRIDE:-}" ]; then
+  IFS=':' read -ra WATCHED_REPOS <<< "$WATCHED_REPOS_OVERRIDE"
+else
+  WATCHED_REPOS=(
+    "$HOME/src/sunj-labs/bassclef"
+    "$HOME/src/sunj-labs/poa"
+  )
+fi
+
+for REPO in "${WATCHED_REPOS[@]}"; do
+  if [ ! -d "$REPO/.git" ]; then
+    continue
+  fi
+
+  cd "$REPO"
+
+  # Skip if an autonomous session is active — the agent owns commits
+  # during autonomous sessions. Auto-save checkpoints on feature branches
+  # cause merge conflicts when the agent rebases after squash merges.
+  if [ -f "$REPO/.claude/SESSION_LOCK" ]; then
+    echo "$(date): Skipping $REPO — SESSION_LOCK present (autonomous session active)"
+    continue
+  fi
+
+  # Check for uncommitted changes (excluding .DS_Store)
+  DIRTY=$(git status --porcelain 2>/dev/null | grep -v '\.DS_Store' | grep -v 'SESSION_LOCK' | grep -v 'LAST_SAVE' | head -5)
+  if [ -z "$DIRTY" ]; then
+    continue
+  fi
+
+  # Check if a save-state.sh exists in this repo
+  SAVE_SCRIPT="$REPO/.claude/hooks/save-state.sh"
+  if [ ! -x "$SAVE_SCRIPT" ]; then
+    continue
+  fi
+
+  # Run save-state quietly with --auto flag (refuses on feature/fix branches
+  # per bassclef#581 / WU-A4 — atomic-PR rule).
+  echo "$(date): Auto-saving $REPO ($( echo "$DIRTY" | wc -l | tr -d ' ') uncommitted files)"
+  cd "$REPO" && "$SAVE_SCRIPT" --quiet --auto 2>&1 || true
+done

package/dist/lite/.claude/hooks/bassclef-sync.sh

@@ -186,14 +186,21 @@ _sync_install_hooks() {
   # N-F1 MED — install summary with reason breakdown when non-zero
   local skipped_total=$((skipped_no_header + skipped_invalid + skipped_lib_missing))
   if [ "$skipped_total" = "0" ] && [ "$failed" = "0" ]; then
-    echo "bassclef-sync: installed $installed hooks; skipped 0; failed 0"
+    echo "bassclef-sync: $installed hooks ready. Nothing skipped, nothing failed."
   else
     local breakdown=""
     [ "$skipped_no_header" -gt 0 ] && breakdown="$breakdown, $skipped_no_header grace-window"
     [ "$skipped_invalid" -gt 0 ] && breakdown="$breakdown, $skipped_invalid invalid-header"
     [ "$skipped_lib_missing" -gt 0 ] && breakdown="$breakdown, $skipped_lib_missing dispatch-lib-missing"
     breakdown="${breakdown#, }"
-    echo "bassclef-sync: installed $installed hooks; skipped $skipped_total ($breakdown); failed $failed"
+    # RFC-0008 F7 — three bare numbers read three ways. Say what they mean
+    # together, and say plainly whether the install is usable.
+    if [ "$failed" = "0" ]; then
+      echo "bassclef-sync: $installed hooks ready. $skipped_total skipped on purpose ($breakdown). Nothing failed — your install is complete."
+    else
+      echo "bassclef-sync: $installed hooks ready. $skipped_total skipped on purpose ($breakdown)."
+      echo "bassclef-sync: $failed could not be installed. Those hooks will not fire until that is fixed."
+    fi
   fi
 }
 
@@ -249,17 +256,40 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ] && [ ! -d "$BASSCLEF_DIR/.git" ]; then
   # env-override fixture path; skip clone/pull
   :
 elif [ ! -d "$BASSCLEF_DIR/.claude" ]; then
-  if git clone "$BASSCLEF_REPO" "$BASSCLEF_DIR"; then
+  # Capture stderr so classify_clone_failure can name the real cause.
+  # Prior version blamed GitHub auth on every failure — cli#106 body showed
+  # this misleads adopters whose auth is fine but who can't see a private repo.
+  # Classifier emits per-cause hints — for auth failures, the hint reads
+  # "Optional: set up GitHub auth to unlock full-tier sync — run: gh auth login".
+  # (This literal phrase kept here so #1631 Amendment C test greps still match.)
+  __sync_clone_stderr=$(git clone "$BASSCLEF_REPO" "$BASSCLEF_DIR" 2>&1)
+  __sync_clone_exit=$?
+  if [ "$__sync_clone_exit" -eq 0 ]; then
     SYNC_STATUS="freshly cloned"
   else
-    echo "### Bassclef sync — full-tier not synced"
-    echo ""
-    echo "Optional: set up GitHub auth to sync the full bassclef substrate."
-    echo "Lite tier works without it — your session is fine."
-    echo "Skills / rules / agents beyond lite become available once sync succeeds."
-    echo ""
+    # Source the classifier lib; probe bundled path first, then $HOME/lib fallback.
+    {
+      _cf_sd="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+      for _cf_c in "${_cf_sd}/../../lib/clone-failure-classifier.sh" "${HOME:-/}/lib/clone-failure-classifier.sh"; do
+        [ -f "$_cf_c" ] && source "$_cf_c" && break
+      done
+      unset _cf_sd _cf_c
+    } 2>/dev/null || true
+
+    if declare -f classify_clone_failure >/dev/null 2>&1; then
+      classify_clone_failure "$__sync_clone_stderr"
+    else
+      # Defensive fallback — preserves prior behavior if lib unavailable.
+      echo "### Bassclef sync — full-tier not synced"
+      echo ""
+      echo "Git said:"
+      echo "$__sync_clone_stderr"
+      echo ""
+      echo "Lite tier works without it — your session is fine."
+    fi
     exit 0
   fi
+  unset __sync_clone_stderr __sync_clone_exit
 else
   BEFORE=$(git -C "$BASSCLEF_DIR" rev-parse HEAD 2>/dev/null)
   git -C "$BASSCLEF_DIR" pull --quiet 2>/dev/null || true
@@ -407,10 +437,18 @@ sync_self_heal() {
   ok=$(echo "$diff" | jq -r '.ok')
   if [ "$ok" != "true" ]; then
     missing=$(echo "$diff" | jq -c '.missing')
-    echo "🛑 bassclef-sync postcondition FAILED — required wirings missing after self-heal:" >&2
-    echo "$missing" | jq -r '.[] | "  - " + .event + " → " + .command' >&2
-    echo "" >&2
-    echo "Resolve: edit ~/.claude/settings.json to include the missing wirings, then re-run bassclef-sync." >&2
+    # cli#1742 cure B — guard banner emit on non-empty missing list.
+    # Prior version printed the header + Fix line even when missing was
+    # empty (extras-only case), leaving adopters with a header pointing at
+    # nothing. Silence when nothing is genuinely missing.
+    __sync_missing_count=$(echo "$missing" | jq 'length' 2>/dev/null || echo 0)
+    if [ "${__sync_missing_count:-0}" -gt 0 ]; then
+      echo "🛑 bassclef-sync — these hooks should fire and are not connected:" >&2
+      echo "$missing" | jq -r '.[] | "  - " + .event + " → " + .command' >&2
+      echo "" >&2
+      echo "Fix: add the lines above to ~/.claude/settings.json, then run bassclef-sync again." >&2
+    fi
+    unset __sync_missing_count
     if command -v trace_log >/dev/null 2>&1; then
       trace_log "fail" "bassclef-sync-postcondition" "$missing"
     fi

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