@thebassclef/lite 1.0.0 → 1.0.1

package/dist/lite/.claude/hooks/artifact-ingestion-gate.sh

@@ -0,0 +1,357 @@
+#!/bin/bash
+# tier: lite
+# Artifact Ingestion Gate — fires on Write/Edit to generative artifact paths.
+# Enforces .claude/rules/artifact-ingestion.md: every substantive generative
+# output must include a "## Sources read" block (or a stated-from-scratch
+# rationale) so agents can't substitute training priors for staged artifacts.
+#
+# Exit codes:
+#   0 — allow (path doesn't match, or Sources-read block present, or override)
+#   2 — block (matcher hit, no Sources-read, no override)
+#
+# Override: set SKIP_ARTIFACT_INGESTION=1 to bypass (logged to trace).
+#
+# Rule: .claude/rules/artifact-ingestion.md
+# Issue: bassclef#116
+
+set +e  # never crash the tool call; fall through to allow on any unexpected error
+
+# === Hook liveness heartbeat (WU-3 of bet 2026-07-31d; closes #1002) ===
+# Silent-fail — a missing lib never crashes the hook.
+{
+  _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 "artifact-ingestion-gate" && break
+  done
+  unset _hb_sd _hb_c
+} 2>/dev/null || true
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+
+# Only fire on Write / Edit
+if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then
+  exit 0
+fi
+
+# No file path → allow (defensive)
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Matcher paths — generative artifacts requiring Sources-read block.
+# Narrow by design; expand carefully. Skip paths (.claude/, memory, configs,
+# release-notes, journals) are NOT matched here and pass through.
+MATCH=0
+case "$FILE_PATH" in
+  */strategy/canvases/*.md)              MATCH=1 ;;
+  */docs/specs/*.md)                     MATCH=1 ;;
+  */docs/iteration-bets/*.md)            MATCH=1 ;;
+  */architecture/decisions/ADR-*.md)     MATCH=1 ;;
+  */docs/prototypes/*/index.html)        MATCH=1 ;;
+  */docs/prototypes/*/*.html)            MATCH=1 ;;
+  */docs/decompositions/*.md)            MATCH=1 ;;
+esac
+
+if [ "$MATCH" -eq 0 ]; then
+  exit 0
+fi
+
+# Override hatch — log and allow
+if [ "${SKIP_ARTIFACT_INGESTION:-0}" = "1" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+  if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+    source "$SCRIPT_DIR/trace-helper.sh" 2>/dev/null || true
+    trace_log "artifact-ingestion-gate" "OVERRIDE $TOOL_NAME $FILE_PATH" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Assemble the content that WILL exist after this operation.
+# Write: tool_input.content is authoritative.
+# Edit: check existing file on disk (if any) + new_string together.
+FUTURE_CONTENT=""
+if [ "$TOOL_NAME" = "Write" ]; then
+  FUTURE_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""' 2>/dev/null)
+elif [ "$TOOL_NAME" = "Edit" ]; then
+  NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""' 2>/dev/null)
+  EXISTING=""
+  if [ -f "$FILE_PATH" ]; then
+    EXISTING=$(cat "$FILE_PATH" 2>/dev/null)
+  fi
+  FUTURE_CONTENT="${EXISTING}
+${NEW_STRING}"
+fi
+
+# Check for Sources-read block (case-insensitive, tolerant of heading depth).
+# Accepted forms:
+#   ## Sources read
+#   ### Sources read
+#   ## Sources Read
+#   ## SOURCES READ
+# Also accepts an explicit from-scratch rationale:
+#   "No prior artifacts" (per rule)
+HAS_SOURCES_READ=0
+if echo "$FUTURE_CONTENT" | grep -qiE '^#{1,6}[[:space:]]+sources[[:space:]]+read'; then
+  HAS_SOURCES_READ=1
+fi
+if echo "$FUTURE_CONTENT" | grep -qi 'no prior artifacts'; then
+  HAS_SOURCES_READ=1
+fi
+
+# Block if no Sources-read block at all.
+if [ "$HAS_SOURCES_READ" -eq 0 ]; then
+  EMIT_BLOCK=1
+fi
+
+# === Parent citation check (bassclef#334 — Layer A determinism gate) ===
+#
+# When the artifact's frontmatter declares parent_roadmap, parent_bet, or
+# parent_canvas, the "Sources read" block MUST cite those paths/ids. This
+# catches the case where an agent declares lineage in frontmatter but
+# doesn't actually read the parent (a determinism failure mode caught by
+# the operator 2026-04-27d when an agent missed parent_roadmap framing).
+#
+# Only fires when HAS_SOURCES_READ=1; if the Sources-read block is missing
+# entirely, the prior check covers it.
+PARENT_CITATION_BLOCK=""
+if [ "$HAS_SOURCES_READ" -eq 1 ]; then
+  # Extract YAML frontmatter (between leading --- ... ---)
+  FRONTMATTER=$(echo "$FUTURE_CONTENT" | awk '/^---$/{c++; if(c==2) exit; next} c==1')
+
+  # Extract Sources-read section content (everything from "## Sources read"
+  # heading to the next ## heading or end-of-file)
+  SOURCES_SECTION=$(echo "$FUTURE_CONTENT" | awk '
+    /^#{1,6}[[:space:]]+[Ss][Oo][Uu][Rr][Cc][Ee][Ss][[:space:]]+[Rr][Ee][Aa][Dd]/ { in_section=1; next }
+    in_section && /^#{1,6}[[:space:]]/ { exit }
+    in_section { print }
+  ')
+
+  # For each parent_* field set in frontmatter, verify it (or its slug/id)
+  # is referenced in the Sources-read section. Bash regex via grep -F for
+  # literal-string match (paths contain dots).
+  MISSING_CITATIONS=""
+  for parent_key in parent_roadmap parent_bet parent_canvas parent_decomposition; do
+    PARENT_VALUE=$(echo "$FRONTMATTER" | awk -v key="$parent_key" '
+      $0 ~ "^"key":" {
+        sub("^"key":[[:space:]]*", "")
+        # Strip leading/trailing whitespace and surrounding quotes
+        gsub(/^[[:space:]]+|[[:space:]]+$/, "")
+        gsub(/^"|"$|^'\''|'\''$/, "")
+        print
+        exit
+      }
+    ')
+    if [ -z "$PARENT_VALUE" ]; then
+      continue
+    fi
+
+    # Check if the parent path (or its basename without extension) appears
+    # in the Sources-read section. Accepts either:
+    #   - Full path (docs/roadmaps/foo.md)
+    #   - Slug/id (foo, no path/extension)
+    PARENT_BASENAME=$(basename "$PARENT_VALUE" .md)
+
+    if echo "$SOURCES_SECTION" | grep -qF "$PARENT_VALUE"; then
+      continue
+    fi
+    if echo "$SOURCES_SECTION" | grep -qF "$PARENT_BASENAME"; then
+      continue
+    fi
+
+    MISSING_CITATIONS="${MISSING_CITATIONS}  - ${parent_key}: ${PARENT_VALUE}\n"
+  done
+
+  if [ -n "$MISSING_CITATIONS" ]; then
+    PARENT_CITATION_BLOCK="$MISSING_CITATIONS"
+    EMIT_BLOCK=1
+  fi
+
+  # === Layer A composition (bassclef#337 WU-5) ===
+  #
+  # When parent_roadmap is cited, verify the citation includes the
+  # current last_event.ts OR last_event.event. This proves the agent
+  # read CURRENT roadmap state, not a stale snapshot. Closes the
+  # determinism loop: parent declared, parent path cited, current
+  # event referenced.
+  #
+  # Skips silently if no parent_roadmap was set (covered by prior loop).
+  STALE_EVENT_BLOCK=""
+  PARENT_ROADMAP=$(echo "$FRONTMATTER" | awk '
+    $0 ~ /^parent_roadmap:/ {
+      sub(/^parent_roadmap:[[:space:]]*/, "")
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "")
+      gsub(/^"|"$|^'\''|'\''$/, "")
+      print
+      exit
+    }
+  ')
+  if [ -n "$PARENT_ROADMAP" ] && [ -f "$PARENT_ROADMAP" ]; then
+    # Extract current last_event from roadmap frontmatter via Python
+    LAST_EVENT_TS=$(python3 -c "
+import sys, yaml
+try:
+  with open('$PARENT_ROADMAP', 'r') as f:
+    content = f.read()
+  parts = content.split('---', 2)
+  if len(parts) < 3:
+    sys.exit(0)
+  fm = yaml.safe_load(parts[1]) or {}
+  le = fm.get('last_event', {}) or {}
+  ts = le.get('ts', '')
+  print(str(ts))
+except Exception:
+  pass
+" 2>/dev/null)
+    LAST_EVENT_NAME=$(python3 -c "
+import sys, yaml
+try:
+  with open('$PARENT_ROADMAP', 'r') as f:
+    content = f.read()
+  parts = content.split('---', 2)
+  if len(parts) < 3:
+    sys.exit(0)
+  fm = yaml.safe_load(parts[1]) or {}
+  le = fm.get('last_event', {}) or {}
+  ev = le.get('event', '')
+  print(str(ev))
+except Exception:
+  pass
+" 2>/dev/null)
+
+    # If roadmap has a last_event, verify Sources cites ts or event name
+    if [ -n "$LAST_EVENT_TS" ] || [ -n "$LAST_EVENT_NAME" ]; then
+      EVENT_CITED=0
+      if [ -n "$LAST_EVENT_TS" ] && echo "$SOURCES_SECTION" | grep -qF "$LAST_EVENT_TS"; then
+        EVENT_CITED=1
+      fi
+      if [ -n "$LAST_EVENT_NAME" ] && echo "$SOURCES_SECTION" | grep -qF "$LAST_EVENT_NAME"; then
+        EVENT_CITED=1
+      fi
+      if [ "$EVENT_CITED" -eq 0 ]; then
+        STALE_EVENT_BLOCK="parent_roadmap=$PARENT_ROADMAP\n  current last_event.ts=$LAST_EVENT_TS\n  current last_event.event=$LAST_EVENT_NAME\n"
+        EMIT_BLOCK=1
+      fi
+    fi
+  fi
+fi
+
+# All checks passed → allow.
+if [ "${EMIT_BLOCK:-0}" -eq 0 ]; then
+  exit 0
+fi
+
+# Block — emit banner to stderr (Claude Code surfaces stderr on exit 2)
+if [ "$HAS_SOURCES_READ" -eq 0 ]; then
+  cat >&2 <<EOF
+
+============================================
+🛑 ARTIFACT-INGESTION GATE — BLOCKED 🛑
+============================================
+
+File:  $FILE_PATH
+Tool:  $TOOL_NAME
+
+Generative artifacts require a "## Sources read" block citing the
+artifacts you read before producing this output. This is per
+.claude/rules/artifact-ingestion.md — no Sources-read = no write.
+
+Required block (add near top of file):
+
+    ## Sources read
+
+    - [path]:[line range] — [what you took]
+    - ...
+
+    ## What I'm NOT reading (with reason)
+
+    - [path] — [deliberate exclusion reason]
+
+If producing genuinely from scratch, state:
+
+    "No prior artifacts; producing from scratch because [reason]."
+
+Override (logged):  SKIP_ARTIFACT_INGESTION=1 <command>
+
+Rule:  .claude/rules/artifact-ingestion.md
+Issue: bassclef#116
+============================================
+
+EOF
+elif [ -n "$STALE_EVENT_BLOCK" ]; then
+  cat >&2 <<EOF
+
+============================================
+🛑 STALE-EVENT GATE — BLOCKED 🛑
+============================================
+
+File:  $FILE_PATH
+Tool:  $TOOL_NAME
+
+This artifact cites parent_roadmap but the "Sources read" block
+doesn't reference the roadmap's CURRENT last_event. Citing the
+parent path proves you read the file; citing the current event
+proves you read the current state, not a stale snapshot.
+
+Roadmap state:
+
+$(printf "$STALE_EVENT_BLOCK")
+
+Add the current ts OR event name to your Sources-read entry. Example:
+
+    ## Sources read
+
+    - $PARENT_ROADMAP — current last_event ($LAST_EVENT_NAME at $LAST_EVENT_TS)
+    - ...
+
+Override (logged):  SKIP_ARTIFACT_INGESTION=1 <command>
+
+Rule:  .claude/rules/artifact-ingestion.md
+Issue: bassclef#337 WU-5 (Layer A composition)
+============================================
+
+EOF
+elif [ -n "$PARENT_CITATION_BLOCK" ]; then
+  cat >&2 <<EOF
+
+============================================
+🛑 PARENT-CITATION GATE — BLOCKED 🛑
+============================================
+
+File:  $FILE_PATH
+Tool:  $TOOL_NAME
+
+This artifact declares parent lineage in frontmatter but the
+"Sources read" block doesn't cite the parent path(s). Declaring a
+parent without reading it is a determinism failure — agent infers
+context instead of reading current state.
+
+Missing citations (parent declared in frontmatter, not cited in Sources read):
+
+$(printf "$PARENT_CITATION_BLOCK")
+
+Add each parent path to the "## Sources read" block. Example:
+
+    ## Sources read
+
+    - docs/roadmaps/<YYYY-MM-DD>-<slug>.md — parent_roadmap; current task list + last_event
+    - ...
+
+Override (logged):  SKIP_ARTIFACT_INGESTION=1 <command>
+
+Rule:  .claude/rules/artifact-ingestion.md
+Issue: bassclef#334 (Layer A determinism gate)
+============================================
+
+EOF
+fi
+
+# Trace the block (best-effort, don't let trace failure change the block signal)
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+  source "$SCRIPT_DIR/trace-helper.sh" 2>/dev/null || true
+  trace_log "artifact-ingestion-gate" "BLOCK $TOOL_NAME $FILE_PATH" 2>/dev/null || true
+fi
+
+exit 2

package/dist/lite/.claude/hooks/assert-verify-steering.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# assert-verify-steering.sh — UserPromptSubmit hook that injects
+# additionalContext steering the agent toward Toulmin's argument model
+# (claim + data + warrant) before any operator-facing assertion.
+#
+# Per bassclef-upstream#582 (parent ticket) + bassclef-upstream#559 (R8
+# mechanization umbrella) + bet 2026-07-01b WU-1.
+#
+# Adds argument-shape steering to the reasoning-boundary defense layer,
+# alongside .claude/hooks/plain-english-steering.sh (bassclef#443).
+#
+# The rule this hook pairs with: .claude/rules/assert-only-after-verify.md
+# The three luminaries anchoring the shape:
+#   - Stephen Toulmin (argument model — claim/data/warrant/qualifier/rebuttal)
+#   - Karl Popper (falsifiability — rebuttal cell)
+#   - Charles Sanders Peirce (abductive reasoning — alternative-consideration)
+#
+# Sibling pattern: .claude/hooks/plain-english-steering.sh
+# Envelope helper: lib/hook-inject.sh emit_additional_context
+#
+# Override per-call: SKIP_ASSERT_VERIFY_STEERING=1
+#
+# Tier 0 strict TDD: .claude/hooks/tests/assert-verify-steering.test.sh
+
+set +e
+
+# === Source install-class-aware lib (per standards/hook-install-class.md) ===
+# Hook is `dual` — runs under both project install (<repo>/.claude/hooks/)
+# and operator install ($HOME/.claude/hooks/). Uses layered resolution
+# per lib/hook-inject.sh convention.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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
+
+# Defensive: if lib not loaded, exit silent (fail-soft per Nygard)
+if ! declare -f emit_additional_context >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Override per-call
+if [ "${SKIP_ASSERT_VERIFY_STEERING:-0}" = "1" ]; then
+  exit 0
+fi
+
+# === Steering content ===
+STEERING_CONTENT="**Plain check:** Before I make a claim in this turn, I read the source first and cite it. If I cannot cite the source, I do not ship the claim.
+
+**Check my claims before I write them:**
+
+For any claim to the operator — a finding, a rating, a fix I recommend, why I think X caused Y, how many turns something will take, or a strong-word claim (wrong, broken, should, must, always) — I fill three parts:
+
+1. **My claim** — the assertion in one sentence.
+2. **Evidence** — the source I read, cited inline (file path, ticket number, git SHA, chronicle filename, standard section).
+3. **Why the evidence supports the claim** — one sentence tying the source to the claim.
+
+Add more when it helps:
+
+4. **Confidence plus how many observations back it** — from Toulmin, *The Uses of Argument* (1958).
+5. **What would falsify the claim** — from Popper, *The Logic of Scientific Discovery* (1959). A claim that cannot be falsified is a guess.
+6. **Two or three alternative explanations that fit the same data** — from Peirce, *Deduction, Induction, and Hypothesis* (1878). Name each option before you pick one.
+
+If I cannot fill all three, I do not ship the claim. I read the source first.
+
+Per bassclef#559 and .claude/rules/assert-only-after-verify.md."
+
+# === Emit envelope ===
+emit_additional_context "UserPromptSubmit" "$STEERING_CONTENT"
+exit 0

package/dist/lite/.claude/hooks/bassclef-source-config-validate.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# tier: lite
+# bassclef-source-config-validate.sh — PreToolUse hook validating
+# .bassclef-source.json writes against the bassclef schema.
+#
+# Wires per .claude/settings.json under hooks.PreToolUse with matcher
+# "Edit|Write|MultiEdit". Reads the tool's event JSON from stdin, detects
+# whether the target file is a `.bassclef-source.json`, validates against
+# the schema, and BLOCKs (exit non-zero) on failure.
+#
+# Per ADR-015: JSON Schema draft-2020-12 with format support via ajv-formats.
+# Pairs with: standards/bassclef-source-config.md
+#
+# Override: SKIP_BASSCLEF_SOURCE_VALIDATE=1 (logged to stderr).
+#
+# F77 fix (bassclef#743): probe ajv-cli before validation; distinguish
+# offline / install failure from schema validation failure so the operator
+# sees the real cause rather than a fake "validation failed" exit.
+#
+# F78 fix (bassclef#743): Edit/MultiEdit are PreToolUse — the file on disk
+# is still pre-edit content. Synthesize post-edit content by replaying the
+# event's edit operations against the on-disk content, then validate that.
+# Write is unchanged — tool_input.content is the post-content.
+
+set -u
+
+# === Override path ===
+
+if [ "${SKIP_BASSCLEF_SOURCE_VALIDATE:-}" = "1" ]; then
+  echo "[bassclef-source-config-validate.sh] SKIP_BASSCLEF_SOURCE_VALIDATE=1 — bypassing validation" >&2
+  exit 0
+fi
+
+# === Read PreToolUse event ===
+
+EVENT_JSON="$(cat)"
+TOOL_NAME="$(printf '%s' "$EVENT_JSON" | jq -r '.tool_name // empty')"
+TARGET_PATH="$(printf '%s' "$EVENT_JSON" | jq -r '.tool_input.file_path // empty')"
+
+# Tool filter: only Edit/Write/MultiEdit trigger validation
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# Empty path → pass-through
+if [ -z "$TARGET_PATH" ]; then
+  exit 0
+fi
+
+# Path filter: only .bassclef-source.json files trigger validation
+case "$TARGET_PATH" in
+  */.bassclef-source.json|.bassclef-source.json) ;;
+  *) exit 0 ;;
+esac
+
+# === Resolve project dir + schema path ===
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SCHEMA="${PROJECT_DIR}/standards/bassclef-source/schemas/bassclef-source.schema.json"
+
+# If schema not present locally (consumer repo without bassclef-side
+# files), pass-through — the hook is a defensive gate for bassclef-side
+# edits, not for consumer-side edits where the schema isn't available.
+if [ ! -f "$SCHEMA" ]; then
+  exit 0
+fi
+
+# === Temp-file cleanup trap ===
+
+TMP_JSON=""
+cleanup() {
+  [ -n "$TMP_JSON" ] && rm -f "$TMP_JSON" 2>/dev/null
+}
+trap cleanup EXIT
+
+# === F77 — Probe ajv-cli availability before validating ===
+#
+# Distinguish offline / install-failure from schema-validation failure.
+# Without this probe, the error filter at the end strips npm/npx warnings
+# and the operator sees what looks like a schema-validation failure even
+# when the real cause is network or install. Pass-through on probe failure
+# with a loud stderr explanation; do NOT block on infrastructure.
+
+# Probe uses `ajv help` because `ajv --version` exits non-zero in
+# ajv-cli@5's CLI parser (unrecognized option). help is the cheapest
+# parse-and-print that exits 0 when the binary is installed.
+AJV_PROBE_OUTPUT="$(npx -y -p ajv-cli@5 ajv help 2>&1)"
+AJV_PROBE_EXIT=$?
+if [ "$AJV_PROBE_EXIT" -ne 0 ]; then
+  echo >&2
+  echo "[bassclef-source-config-validate.sh] ajv-cli unavailable — validation skipped" >&2
+  echo "[bassclef-source-config-validate.sh] Likely cause: offline, npm registry unreachable, or first-run install failed." >&2
+  echo "[bassclef-source-config-validate.sh] Target: $TARGET_PATH" >&2
+  echo "[bassclef-source-config-validate.sh] Probe output (last 5 lines):" >&2
+  echo "$AJV_PROBE_OUTPUT" | tail -5 | sed 's/^/    /' >&2
+  echo "[bassclef-source-config-validate.sh] To pre-cache: run \`npx -y -p ajv-cli@5 -p ajv-formats@2 ajv --version\` while online." >&2
+  echo "[bassclef-source-config-validate.sh] To bypass deliberately: \`SKIP_BASSCLEF_SOURCE_VALIDATE=1 <command>\`" >&2
+  echo >&2
+  exit 0  # Pass-through; don't block on infrastructure
+fi
+
+# === F78 — Synthesize post-edit content per tool ===
+#
+# Write: tool_input.content IS the post-content (current shape OK).
+# Edit:  apply tool_input.{old_string, new_string, replace_all} to on-disk
+#        content; validate the result.
+# MultiEdit: apply each entry of tool_input.edits[] in order; validate the
+#            final result.
+
+case "$TOOL_NAME" in
+  Write)
+    # ajv-cli detects format from file extension; macOS mktemp -t
+    # appends random suffix AFTER the template, so .json must be
+    # explicitly added via mv to ensure it's the trailing extension.
+    TMP_JSON_RAW="$(mktemp -t bassclef-source-validate-XXXXXX)"
+    TMP_JSON="${TMP_JSON_RAW}.json"
+    mv "$TMP_JSON_RAW" "$TMP_JSON"
+    printf '%s' "$EVENT_JSON" | jq -r '.tool_input.content // empty' > "$TMP_JSON"
+    VALIDATE_TARGET="$TMP_JSON"
+    ;;
+  Edit|MultiEdit)
+    # Edit on non-existent file — the Edit tool will fail with its own
+    # error; pass-through quietly.
+    if [ ! -f "$TARGET_PATH" ]; then
+      exit 0
+    fi
+    # ajv-cli detects format from file extension; macOS mktemp -t
+    # appends random suffix AFTER the template, so .json must be
+    # explicitly added via mv to ensure it's the trailing extension.
+    TMP_JSON_RAW="$(mktemp -t bassclef-source-validate-XXXXXX)"
+    TMP_JSON="${TMP_JSON_RAW}.json"
+    mv "$TMP_JSON_RAW" "$TMP_JSON"
+
+    # Replay edits via python3. Pipes EVENT_JSON to python's stdin;
+    # passes target path + tool name as argv. python writes post-edit
+    # content to stdout, which bash captures into TMP_JSON.
+    #
+    # Exit code from python:
+    #   0 — replay succeeded; TMP_JSON has post-edit content
+    #   2 — old_string not in content; the Edit tool will fail with the
+    #       same error so pass-through quietly
+    #   other — unexpected; pass-through (don't block on hook bugs)
+    REPLAY_EXIT=0
+    printf '%s' "$EVENT_JSON" | python3 -c '
+import json, sys
+event = json.load(sys.stdin)
+target = sys.argv[1]
+tool_name = sys.argv[2]
+with open(target) as f:
+    content = f.read()
+if tool_name == "Edit":
+    edits = [event["tool_input"]]
+else:  # MultiEdit
+    edits = event["tool_input"].get("edits", [])
+for e in edits:
+    old = e.get("old_string", "")
+    new = e.get("new_string", "")
+    if old not in content:
+        sys.exit(2)
+    replace_all = e.get("replace_all", False)
+    content = content.replace(old, new) if replace_all else content.replace(old, new, 1)
+sys.stdout.write(content)
+' "$TARGET_PATH" "$TOOL_NAME" > "$TMP_JSON" 2>/dev/null || REPLAY_EXIT=$?
+
+    if [ "$REPLAY_EXIT" -ne 0 ]; then
+      # Replay failed — the underlying tool will fail too. Pass-through.
+      exit 0
+    fi
+    VALIDATE_TARGET="$TMP_JSON"
+    ;;
+esac
+
+# === Validate via ajv-cli ===
+
+VALIDATION_OUTPUT="$(npx -y -p ajv-cli@5 -p ajv-formats@2 ajv validate \
+  -s "$SCHEMA" \
+  -d "$VALIDATE_TARGET" \
+  --spec=draft2020 \
+  -c ajv-formats 2>&1)"
+EXIT_CODE=$?
+
+if [ "$EXIT_CODE" -eq 0 ]; then
+  exit 0
+fi
+
+# === BLOCK on validation failure ===
+
+# Strip noisy npm warnings; surface only ajv's actual error lines.
+# (Network failures already short-circuited above via the F77 probe.)
+ERR=$(echo "$VALIDATION_OUTPUT" | grep -vE '^npm |^npx |^$' | head -10)
+
+cat >&2 <<EOF
+
+🛑 BLOCKED — .bassclef-source.json validation failed
+
+Path: $TARGET_PATH
+Schema: standards/bassclef-source/schemas/bassclef-source.schema.json
+Standard: standards/bassclef-source-config.md
+
+ajv-cli error:
+$ERR
+
+Resolution paths:
+  1. Fix the data to match the schema (preferred)
+     — see standards/bassclef-source-config.md § Schema for field reference
+     — see scripts/tests/fixtures/bassclef-source/*.json for working examples
+  2. If the schema is genuinely wrong, open a PR amending it (rare)
+  3. Override with SKIP_BASSCLEF_SOURCE_VALIDATE=1 (logged; rare; not for normal work)
+
+Per .claude/rules/blocked-items.md: silence is not deferral.
+
+EOF
+
+exit 3