@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/hooks/session-reflection.sh

@@ -0,0 +1,303 @@
+#!/bin/bash
+# tier: lite
+set -e
+
+# Session Start hook coordinator. Injects reflection prompt and iterates
+# session-reflection.d/*.sh modules in numbered order. Modules inherit
+# the blocked_banner helper and $BASSCLEF_DIR defined here.
+
+# === 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 "session-reflection-coordinator" && break
+  done
+  unset _hb_sd _hb_c
+} 2>/dev/null || true
+
+INPUT=$(cat)
+# Fail-soft on malformed JSON — same pattern as bassclef#1101 + #1119 + #1123.
+# Prevents crash when harness sends malformed stdin at SessionStart.
+# Audit ticket: bassclef#1125 (jq+set -e pattern across all hooks).
+SOURCE=$(echo "$INPUT" | jq -r '.source // "unknown"' 2>/dev/null || echo "unknown")
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."' 2>/dev/null || echo ".")
+
+cd "$CWD"
+
+CWD_HASH=$(echo -n "$CWD" | md5 -q 2>/dev/null || echo -n "$CWD" | md5sum 2>/dev/null | cut -c1-8 || echo "default")
+SESSION_TIMING_FILE="/tmp/claude-session-timing-${CWD_HASH}"
+TIMING_NOW=$(date +"%Y-%m-%dT%H:%M:%S%z")
+echo "$TIMING_NOW" > "$SESSION_TIMING_FILE"
+
+# Durable dual-write (mobile-ephemeral-session.md §2).
+DURABLE_TIMING_DIR="$CWD/state/markers/session-timing"
+mkdir -p "$DURABLE_TIMING_DIR" 2>/dev/null
+echo "$TIMING_NOW" > "$DURABLE_TIMING_DIR/${CWD_HASH}.timing" 2>/dev/null
+
+source "$(dirname "$0")/trace-helper.sh"
+trace_log "session-start" "$SOURCE"
+
+# Resolve bassclef dir through symlinks — used by modules to find scripts.
+HOOK_REAL_PATH="$(readlink -f "$0" 2>/dev/null || readlink "$0" 2>/dev/null || echo "$0")"
+BASSCLEF_DIR="$(cd "$(dirname "$HOOK_REAL_PATH")/../.." && pwd)"
+
+# High-contrast BLOCKED banner; used by every module that raises a gap.
+blocked_banner() {
+  local msg="$1"
+  echo ""
+  echo "🛑🛑🛑 BLOCKED 🛑🛑🛑"
+  echo "────────────────────────────────────────────"
+  echo "$msg"
+  echo "────────────────────────────────────────────"
+  echo "ACTION: resolve OR explicitly defer (per .claude/rules/blocked-items.md)."
+  echo "Silence is not deferral. Propose this as item #1 in your session plan."
+  echo ""
+}
+
+echo "============================================"
+echo "SESSION START — MANDATORY REFLECT → PLAN"
+echo "============================================"
+echo ""
+echo "You MUST run the Session Start protocol before doing ANY other work."
+echo "Do NOT skip this. Do NOT jump to answering the user's question first."
+echo ""
+
+# === Last save state ===
+LAST_SAVE_FILE=".claude/LAST_SAVE"
+if [ -f "$LAST_SAVE_FILE" ]; then
+  SAVE_TIMESTAMP=$(grep '^timestamp:' "$LAST_SAVE_FILE" | cut -d' ' -f2-)
+  SAVE_MACHINE=$(grep '^machine:' "$LAST_SAVE_FILE" | cut -d' ' -f2-)
+  SAVE_BRANCH=$(grep '^branch:' "$LAST_SAVE_FILE" | cut -d' ' -f2-)
+  SAVE_COMMIT=$(grep '^last_commit:' "$LAST_SAVE_FILE" | cut -d' ' -f2-)
+  echo "### LAST SAVE STATE"
+  echo ""
+  echo "Saved: $SAVE_TIMESTAMP"
+  echo "Machine: $SAVE_MACHINE"
+  echo "Branch: $SAVE_BRANCH"
+  echo "Last commit: $SAVE_COMMIT"
+  echo ""
+else
+  echo "### NO PREVIOUS SAVE STATE FOUND"
+  echo ""
+  echo "This may be the first session, or save-state has never run."
+  echo "Proceed with caution — check git log for context."
+  echo ""
+fi
+
+# === Session lock check (BEFORE writing — idempotency rule) ===
+LOCK_FILE=".claude/SESSION_LOCK"
+if [ -f "$LOCK_FILE" ]; then
+  # Platform-portable mtime: GNU `stat -c %Y` first, BSD `stat -f %m` fallback.
+  # Order matters — GNU `stat -f` exits 0 with WRONG output (mount-point info
+  # not mtime), so the `||` chain only triggers on BSD when -c fails. Caught
+  # by WU-8 test of /longrun-c on Linux CI (7th TDD-find of the day; first
+  # attempt at the fix had the order reversed and still failed).
+  LOCK_MTIME=$(stat -c %Y "$LOCK_FILE" 2>/dev/null || stat -f %m "$LOCK_FILE" 2>/dev/null || echo "0")
+  LOCK_AGE=$(( $(date +%s) - LOCK_MTIME ))
+  if [ "$LOCK_AGE" -lt 7200 ]; then
+    echo "### ANOTHER SESSION MAY BE ACTIVE"
+    echo ""
+    echo "SESSION_LOCK exists and is $(( LOCK_AGE / 60 )) minutes old."
+    echo "Another agent or session may be working in this repo."
+    echo ""
+    echo "→ Ask the user before proceeding. Do NOT overwrite another session's work."
+    echo ""
+  else
+    echo "### STALE SESSION LOCK ($(( LOCK_AGE / 3600 )) hours old)"
+    echo ""
+    echo "Previous session likely crashed. Proceeding with caution."
+    echo ""
+  fi
+fi
+
+# === Write session lock (AFTER checking — per standards/hook-idempotency.md) ===
+MACHINE=$(hostname -s 2>/dev/null || echo "unknown")
+echo "machine: $MACHINE" > "$LOCK_FILE"
+echo "timestamp: $(date +%Y-%m-%dT%H:%M:%S%z)" >> "$LOCK_FILE"
+echo "pid: $$" >> "$LOCK_FILE"
+
+# === Fetch origin before staleness checks (bassclef-upstream#403) ===
+# Several session-reflection.d/ fragments read git log / file listings
+# to compute staleness banners (chronicle, danger-mode summary,
+# architect-review, release-notes, recent-strategic-artifacts,
+# workflow-staleness, metrics-staleness). Without fetching origin
+# first, those reads see this machine's last-pull state — not the
+# shared truth — and may show wrong-now banners when another session
+# has pushed since (e.g., 2026-06-26c saw stale local while origin
+# had today's session-end commit from #401).
+#
+# Best-effort: || true keeps the dispatcher working when offline / no
+# remote / detached HEAD. Each fragment continues to use local git
+# state; we just ensure local has had a chance to sync first.
+CURRENT_BRANCH_FOR_FETCH=$(git symbolic-ref --short HEAD 2>/dev/null)
+if [ -n "$CURRENT_BRANCH_FOR_FETCH" ]; then
+  git fetch origin "$CURRENT_BRANCH_FOR_FETCH" --quiet 2>/dev/null || true
+fi
+
+# === Iterate modules in numbered order ===
+# Use HOOK_REAL_PATH (line 15, symlinks resolved) so fragments load when
+# the dispatcher is invoked via a symlink from an adopter checkout.
+# Per bassclef-upstream#591 — link-relative path silently skipped all
+# fragments on adopter machines, breaking every session-start gate.
+MODULES_DIR="$(dirname "$HOOK_REAL_PATH")/session-reflection.d"
+if [ -d "$MODULES_DIR" ]; then
+  # Modules use the pattern `return 0 2>/dev/null || exit 0` (safe when
+  # sourced OR run standalone). A module returning 2 signals a fatal
+  # condition the coordinator MUST honor (e.g., invalid substrate config
+  # per 15-substrate-config-validate.sh L86). Per Feathers R3.2 semantic
+  # preservation — cure b (2026-07-30) restored return semantics while
+  # keeping the abort contract via return code 2 + this catch.
+  #
+  # Disable `set -e` briefly so the coordinator sees each module's
+  # return code cleanly. Without this, `return 1` from a sourced module
+  # would abort the coordinator via set -e regardless of code.
+  set +e
+  for module in "$MODULES_DIR"/*.sh; do
+    [ -f "$module" ] || continue
+    source "$module"
+    MODULE_RC=$?
+    # Modules may set their own shell options (e.g., 90-release-backlog
+    # uses `set -euo pipefail`). Those persist to the coordinator via
+    # sourcing. Reset to a permissive default after each module so one
+    # module's discipline does not abort the coordinator's remaining
+    # body. Cure b (2026-07-30) — Nygard bulkhead + Feathers R3.5.
+    set +eu
+    if [ "$MODULE_RC" -eq 2 ]; then
+      # Module signaled fatal abort. Preserve pre-cure behavior — exit
+      # with non-zero code the harness treats as coordinator failure.
+      echo "" >&2
+      echo "!! session-reflection: aborting after $(basename "$module") returned 2" >&2
+      exit 1
+    fi
+  done
+  # Deliberately DO NOT re-enable set -e. Cure b (2026-07-30) discovered
+  # the coordinator's ACTIVE CONTEXT block at L162+ uses grep patterns
+  # that return 1 when whereami has no in_flight_bet field. Under set -e
+  # those aborted the coordinator BEFORE reaching Step 1: Read memory
+  # (L200+). Pre-cure the abort was masked because 05-active-bet.sh
+  # exited earlier. Post-cure the abort surfaces. Fix: coordinator runs
+  # without set -e for the rest of its body — matches modules' tolerance
+  # for non-zero returns from optional grep/find calls.
+fi
+
+# === Context loading — proactively surface active work ===
+echo "### ACTIVE CONTEXT (read these before planning)"
+echo ""
+
+if [ -f "docs/whereami.md" ]; then
+  ACTIVE_BET=$(grep 'iteration_bet:' docs/whereami.md 2>/dev/null | head -1 | sed 's/iteration_bet: *//')
+  if [ -n "$ACTIVE_BET" ] && [ -f "$ACTIVE_BET" ]; then
+    echo "**Active iteration goal**: $ACTIVE_BET"
+    head -20 "$ACTIVE_BET" 2>/dev/null
+    echo ""
+  fi
+  ACTIVE_PHASE=$(grep 'iteration_phase:' docs/whereami.md 2>/dev/null | head -1 | sed 's/iteration_phase: *//')
+  echo "**Phase**: ${ACTIVE_PHASE:-unknown}"
+  echo ""
+fi
+
+for CDIR in "chronicle" "docs/chronicle"; do
+  if [ -d "$CDIR" ]; then
+    LATEST_CHRONICLE=$(ls -1 "$CDIR"/*.md 2>/dev/null | sort | tail -1)
+    if [ -n "$LATEST_CHRONICLE" ]; then
+      echo "**Last chronicle**: $(basename "$LATEST_CHRONICLE")"
+      OPEN_THREADS=$(sed -n '/## Open threads/,/## /p' "$LATEST_CHRONICLE" 2>/dev/null | head -15)
+      if [ -n "$OPEN_THREADS" ]; then
+        echo "$OPEN_THREADS"
+      fi
+      echo ""
+    fi
+    break
+  fi
+done
+
+if [ -f "substrate.config.md" ]; then
+  LEVEL=$(grep '^level:' substrate.config.md 2>/dev/null | head -1 | sed 's/level: *//')
+  echo "**Process level**: ${LEVEL:-core}"
+  echo ""
+fi
+
+echo ""
+
+# === Standard reflection steps ===
+echo "### Step 1: Read memory"
+echo "Read project memory from .claude/ directory"
+echo ""
+echo "### Step 2: Recent commits"
+git log --oneline -5 2>/dev/null || echo "(no git history)"
+echo ""
+echo "### Step 3: Open issues"
+REPO_NAME=$(gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null || echo "")
+if [ -n "$REPO_NAME" ]; then
+  gh issue list -R "$REPO_NAME" --limit 10 2>/dev/null || echo "(issues unavailable)"
+else
+  echo "(gh repo not detected — check open issues manually)"
+fi
+echo ""
+echo "### Step 4: Summarize + propose 1-3 items, then WAIT for human confirmation."
+echo ""
+echo "### MANDATORY RESPONSE FORMAT (user-visible)"
+echo ""
+echo "Claude Code hook stdout lands in MODEL context only — the operator"
+echo "never sees the 🛑 banners above. The only user-visible surface is"
+echo "what YOU write in your first message. So:"
+echo ""
+echo "Your FIRST user-facing message this session MUST begin with a"
+echo "verbatim echo of every 🛑 BLOCKED block surfaced above — same"
+echo "emoji, same horizontal rule, same message text — inside a fenced"
+echo "code block so the operator sees exactly what the hook emitted,"
+echo "not your paraphrase."
+echo ""
+echo "THEN, immediately below the echoed blocks, add your disposition:"
+echo ""
+echo "    BLOCKED ITEMS — my disposition:"
+echo "    - [name]: RESOLVE NOW / RESOLVE THIS SESSION / DEFER (reason)"
+echo ""
+echo "If there are zero blocked items, state: 'No blocked items surfaced"
+echo "by session-start hook.'"
+echo ""
+echo "Only AFTER the verbatim echo + disposition may you address the"
+echo "user's question. This overrides the pull of any specific user"
+echo "question — the user's prior instructions live in these rules."
+echo ""
+
+# === Manifest-aware session planning ===
+if [ -f "substrate.config.md" ]; then
+  LEVEL=$(grep '^level:' substrate.config.md 2>/dev/null | head -1 | sed 's/level: *//')
+  CEILING=$(grep 'iteration_ceiling:' substrate.config.md 2>/dev/null | head -1 | sed 's/.*iteration_ceiling: *//')
+
+  ACTIVE_BET=""
+  if [ -f "docs/whereami.md" ]; then
+    ACTIVE_BET=$(grep 'iteration_bet:' docs/whereami.md 2>/dev/null | head -1 | sed 's/iteration_bet: *//')
+  fi
+
+  if [ -n "$ACTIVE_BET" ] && [ -f "$ACTIVE_BET" ]; then
+    echo "### Active iteration — continue or start new?"
+    echo ""
+    echo "An iteration goal exists: $ACTIVE_BET"
+    echo "Check if it's complete or still has open scope."
+    echo "If complete → propose a new iteration from open issues."
+    echo "If in progress → resume where it left off."
+  else
+    echo "### Propose iteration (manifest-aware)"
+    echo ""
+    echo "No active iteration goal. Based on open issues above,"
+    echo "propose a light iteration:"
+    echo ""
+    echo '```'
+    echo "## This session (light iteration)"
+    echo "Retiring: [highest-risk open issue]"
+    echo "Proving: [most valuable open issue]"
+    echo "Scope: [2-4 issues that fit together]"
+    echo "Cost ceiling: ${CEILING:-\$0}"
+    echo '```'
+    echo ""
+    echo "Read the open issues and propose this. User confirms or adjusts."
+  fi
+  echo ""
+fi
+
+echo "============================================"
+
+exit 0

package/substrate/.claude/hooks/skill-body-grade-gate.sh

@@ -0,0 +1,219 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# skill-body-grade-gate.sh — PreToolUse Edit|Write gate on
+# .claude/skills/*/SKILL.md. Measures per-sentence Flesch-Kincaid grade.
+# Honors FKGL-EXEMPT annotations. BLOCKs when the 80%-at-grade-8-9 rule
+# fails per ADR-040 Decision 4.
+#
+# Sister to turn-prose-grade-measure.sh (Stop event; turn prose;
+# measurement only, no gate). This hook fires on file writes and blocks.
+#
+# Input (stdin): JSON with tool_name + tool_input.file_path + content/new_string
+# Exit: 0 pass, 2 block
+#
+# Override per-call: SKIP_SKILL_BODY_GRADE=1
+#
+# Per @luminary kent-beck (Tier 0 strict TDD)
+# + @luminary donald-norman (plain-English target per ADR-040 D4)
+# + @luminary michael-feathers (characterization tests pin real inputs)
+
+set +e
+
+# === Override path ===
+if [ "${SKIP_SKILL_BODY_GRADE:-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 paths
+case "$FILE_PATH" in
+  *".claude/skills/"*"/SKILL.md")
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# === Extract text to grade ===
+if [ "$TOOL_NAME" = "Write" ]; then
+  CONTENT=$(echo "$STDIN_JSON" | jq -r '.tool_input.content // ""' 2>/dev/null)
+else
+  # Edit: grade the new_string (text being added)
+  CONTENT=$(echo "$STDIN_JSON" | jq -r '.tool_input.new_string // ""' 2>/dev/null)
+fi
+
+[ -z "$CONTENT" ] && exit 0
+
+# === Run the gate via python ===
+# Python does the scrubbing + per-sentence FKGL + threshold check.
+# Same textstat-preferred / fallback pattern as turn-prose-grade-measure.sh.
+GATE_OUTPUT=$(printf '%s' "$CONTENT" | python3 -c '
+import sys, re
+
+text = sys.stdin.read()
+
+# === Strip YAML frontmatter ===
+# Matches leading "---\n...\n---\n" block
+text = re.sub(r"^---\n.*?\n---\n", "", text, count=1, flags=re.DOTALL)
+
+# === Strip FKGL-EXEMPT blocks ===
+# Matches <!-- FKGL-EXEMPT: any-text --> ... <!-- /FKGL-EXEMPT -->
+text = re.sub(r"<!--\s*FKGL-EXEMPT:.*?-->.*?<!--\s*/FKGL-EXEMPT\s*-->",
+              "", text, flags=re.DOTALL)
+
+# === Strip code blocks ===
+text = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
+
+# === Strip inline backticks ===
+text = re.sub(r"`[^`]*`", "", text)
+
+# === Strip URLs ===
+text = re.sub(r"https?://[^\s)]+", "", text)
+
+# === Strip markdown table pipes and headers ===
+text = re.sub(r"^\s*\|.*\|\s*$", "", text, flags=re.MULTILINE)
+text = re.sub(r"^\s*#+\s+.*$", "", text, flags=re.MULTILINE)
+
+# === Strip HTML comments ===
+text = re.sub(r"<!--.*?-->", "", text, flags=re.DOTALL)
+
+# === Split into sentences ===
+# Also split on bullet markers + numbered lists so a bullet block is not
+# treated as one long "sentence" (which inflates FKGL unfairly).
+sentences = [s.strip() for s in re.split(r"[.!?\n]+\s*(?:[-*]\s|\d+\.\s)?", text) if s.strip()]
+# Second pass — plain sentence-terminator split (some markdown lines lack terminators)
+sentences = [ss.strip() for s in sentences for ss in re.split(r"[.!?]+", s) if ss.strip()]
+
+# === Total word count check ===
+all_words = re.findall(r"\b[a-zA-Z][a-zA-Z\x27]*\b", text)
+if len(all_words) < 20:
+    print("SKIP short")
+    sys.exit(0)
+
+# === Preferred: textstat per-sentence FKGL ===
+try:
+    from textstat import flesch_kincaid_grade
+    grade_fn = flesch_kincaid_grade
+except ImportError:
+    # Fallback formula — same as turn-prose-grade-measure.sh
+    def count_syllables(word):
+        word = re.sub(r"[^a-z]", "", word.lower())
+        if not word:
+            return 0
+        vowels = "aeiouy"
+        count = 0
+        prev_was_vowel = False
+        for c in word:
+            is_vowel = c in vowels
+            if is_vowel and not prev_was_vowel:
+                count += 1
+            prev_was_vowel = is_vowel
+        if word.endswith("e") and count > 1:
+            count -= 1
+        return max(1, count)
+
+    def grade_fn(s):
+        words = re.findall(r"\b[a-zA-Z][a-zA-Z\x27]*\b", s)
+        if not words:
+            return 0
+        syllables = sum(count_syllables(w) for w in words)
+        return 0.39 * len(words) + 11.8 * (syllables / len(words)) - 15.59
+
+# === Grade each sentence ===
+above_ceiling = 0
+graded_count = 0
+failing_examples = []
+
+for sent in sentences:
+    # Skip short sentences (< 5 words — likely list items, fragments)
+    words = re.findall(r"\b[a-zA-Z][a-zA-Z\x27]*\b", sent)
+    if len(words) < 5:
+        continue
+    graded_count += 1
+    grade = grade_fn(sent)
+    if grade > 10:
+        above_ceiling += 1
+        if len(failing_examples) < 3:
+            failing_examples.append((round(grade, 1), sent[:80]))
+
+if graded_count == 0:
+    print("SKIP no-graded")
+    sys.exit(0)
+
+fail_pct = (above_ceiling / graded_count) * 100
+
+# === 80% at grade 8-9 rule: at most 20% above grade 10 ===
+if fail_pct > 20:
+    print(f"BLOCK {above_ceiling} {graded_count} {fail_pct:.0f}")
+    for grade, snippet in failing_examples:
+        print(f"  EXAMPLE {grade} {snippet}")
+    sys.exit(0)
+
+print(f"PASS {above_ceiling} {graded_count} {fail_pct:.0f}")
+' 2>/dev/null)
+
+# === Parse gate result ===
+FIRST_LINE=$(echo "$GATE_OUTPUT" | head -1)
+VERDICT=$(echo "$FIRST_LINE" | awk '{print $1}')
+
+case "$VERDICT" in
+  PASS|SKIP)
+    exit 0
+    ;;
+  BLOCK)
+    ABOVE=$(echo "$FIRST_LINE" | awk '{print $2}')
+    TOTAL=$(echo "$FIRST_LINE" | awk '{print $3}')
+    PCT=$(echo "$FIRST_LINE" | awk '{print $4}')
+    ;;
+  *)
+    # Empty or unexpected — pass through safely
+    exit 0
+    ;;
+esac
+
+# === Emit BLOCK message ===
+echo "" >&2
+echo "🛑 SKILL-BODY-GRADE-GATE — BLOCKED" >&2
+echo "" >&2
+echo "  File:   $FILE_PATH" >&2
+echo "  Result: $ABOVE of $TOTAL graded sentences above grade 10 (${PCT}%)" >&2
+echo "  Target: 80% at grade 8-9. At most 20% above grade 10." >&2
+echo "  Per:    ADR-040 Decision 4 (grade 8-9 for 80% of prose)" >&2
+echo "" >&2
+echo "  Failing sentence samples (grade | first 80 chars):" >&2
+echo "$GATE_OUTPUT" | grep '^  EXAMPLE' | while read -r _ grade snippet; do
+  echo "    [$grade] $snippet" >&2
+done
+echo "" >&2
+echo "  Cure paths:" >&2
+echo "    1. Rewrite failing sentences in short SVO English" >&2
+echo "    2. Mark sentence exempt: <!-- FKGL-EXEMPT: reason --> ... <!-- /FKGL-EXEMPT -->" >&2
+echo "" >&2
+echo "  Override (logged via trace-helper): SKIP_SKILL_BODY_GRADE=1" >&2
+echo "" >&2
+
+# === Trace log ===
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+  # shellcheck disable=SC1091
+  source "$SCRIPT_DIR/trace-helper.sh"
+  trace_log "skill-body-grade-gate" "BLOCKED above=$ABOVE total=$TOTAL pct=$PCT file=$FILE_PATH"
+fi
+
+exit 2

package/substrate/.claude/hooks/skill-body-intent-drift.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# skill-body-intent-drift.sh — PostToolUse Edit|Write hook on
+# .claude/skills/*/SKILL.md. Runs scripts/intent-drift-check.sh in
+# advisory mode. Reports cosine + verdict to stderr. Never blocks.
+#
+# Closes bassclef-upstream#788 (narrow slice of #785). Makes /loop
+# step 5 automatic — no more honor-system per cure.
+#
+# Input (stdin): JSON — tool_name, tool_input.file_path
+# Exit: always 0 (advisory only at V1)
+#
+# Env:
+#   VOYAGE_API_KEY — required to run the check; missing = skip silently
+#   SKIP_SKILL_BODY_INTENT_DRIFT=1 — per-call override (logged)
+#
+# Per @luminary michael-feathers (characterization measurable not subjective)
+# + @luminary kent-beck (Tier 0 strict TDD)
+
+set +e
+
+# === Override path ===
+if [ "${SKIP_SKILL_BODY_INTENT_DRIFT:-0}" = "1" ]; then
+  exit 0
+fi
+
+# === Parse stdin JSON ===
+STDIN_JSON=$(cat 2>/dev/null || echo '{}')
+
+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
+
+# Extract slug from path
+SLUG=$(echo "$FILE_PATH" | sed -E 's|.*\.claude/skills/([^/]+)/SKILL\.md|\1|')
+if [ -z "$SLUG" ] || [ "$SLUG" = "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Locate repo root
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "$CLAUDE_PROJECT_DIR/.claude" ]; then
+  REPO_ROOT="$CLAUDE_PROJECT_DIR"
+else
+  REPO_ROOT="$(pwd)"
+fi
+
+VECTOR_PATH="$REPO_ROOT/.claude/embeddings/skills/${SLUG}.json"
+DRIFT_SCRIPT="$REPO_ROOT/scripts/intent-drift-check.sh"
+
+# Skip when baseline vector absent
+if [ ! -f "$VECTOR_PATH" ]; then
+  exit 0
+fi
+
+# Skip when drift script missing
+if [ ! -x "$DRIFT_SCRIPT" ]; then
+  exit 0
+fi
+
+# Skip when VOYAGE_API_KEY missing
+if [ -z "${VOYAGE_API_KEY:-}" ]; then
+  exit 0
+fi
+
+# Run the check + surface result to stderr
+RESULT=$(bash "$DRIFT_SCRIPT" --skill "$SLUG" --json 2>&1)
+CHECK_EXIT=$?
+
+# Parse cosine + verdict from JSON result
+COSINE=$(echo "$RESULT" | jq -r '.cosine // "n/a"' 2>/dev/null)
+VERDICT=$(echo "$RESULT" | jq -r '.verdict // "n/a"' 2>/dev/null)
+THRESHOLD=$(echo "$RESULT" | jq -r '.threshold // "n/a"' 2>/dev/null)
+
+# Advisory surface — never blocks
+if [ "$VERDICT" = "PASS" ]; then
+  echo "" >&2
+  echo "[intent-drift-check] /$SLUG cosine $COSINE (threshold $THRESHOLD) — PASS. Intent preserved by measurable cosine." >&2
+elif [ "$VERDICT" = "FAIL" ]; then
+  echo "" >&2
+  echo "⚠ [intent-drift-check] /$SLUG cosine $COSINE (threshold $THRESHOLD) — FAIL." >&2
+  echo "  Advisory only at V1 — commit not blocked. Consider re-checking intent preservation." >&2
+  echo "  Run \`bash scripts/intent-drift-check.sh --skill $SLUG\` for detail." >&2
+else
+  # Drift script failed or returned non-JSON — silent skip
+  :
+fi
+
+# Always exit 0 — advisory only at V1
+exit 0