@thebassclef/lite 1.0.0 → 1.0.2

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

@@ -0,0 +1,716 @@
+#!/bin/bash
+# tier: lite
+# Bassclef Substrate Sync — fires on SessionStart.
+# Operator-class hook: lives on bassclef-upstream operators' machines only.
+# Adopter consumers receive presence/install/bassclef-sync.template.sh instead
+# (sourced from canonical until the WU-0 absorb gap is closed).
+# Ensures bassclef standards are available regardless of device.
+#
+# 1. Clones/pulls bassclef repo
+# 2. Symlinks bassclef skills into project .claude/skills/ (auto-discovery)
+# 3. Installs general hooks + agents to ~/.claude/
+# 4. Writes ~/.claude/settings.json for user-level hook wiring (cloud)
+# 5. Sets env var for rules/CLAUDE.md inheritance
+
+# === Section 0a: SELF_MODE detection (#915) ===
+# Sister to Cure 1 in #901 (commit 4b6c258d) which added SELF_MODE
+# detection to the adopter template at presence/install/bassclef-sync.template.sh.
+# This is the operator-class SessionStart hook — it needs the same guard.
+#
+# Detection: git remote origin URL matches sunj-labs/(bassclef|bassclef-upstream)(\.git)?$
+# on both HTTPS and SSH URL shapes. When SELF_MODE=1, hook exits 0 early
+# to prevent the sync flow from re-symlinking tracked hooks in the
+# substrate source repo.
+#
+# Live proof of the class this cures: session 2026-07-26d WU-0 reverted 84
+# T + 1 M hooks caused by this SessionStart re-symlink in bassclef-upstream.
+#
+# Env override SKIP_SELF_MODE_DETECTION=1 forces SELF_MODE=0 regardless
+# of remote — for adopter forks of bassclef-upstream that legitimately
+# want the sync flow.
+#
+# Function is defined ABOVE the main-body INPUT read so tests can source
+# the hook with BASSCLEF_SYNC_TEST_MODE=1 and access the function without
+# triggering the sync flow.
+bassclef_detect_self_mode() {
+  local cwd="${1:-.}"
+
+  # Env override wins
+  if [ "${SKIP_SELF_MODE_DETECTION:-0}" = "1" ]; then
+    echo "0"
+    return 0
+  fi
+
+  # No git → not substrate source
+  command -v git >/dev/null 2>&1 || { echo "0"; return 0; }
+
+  # Get remote origin URL
+  local remote_url
+  remote_url=$(git -C "$cwd" config --get remote.origin.url 2>/dev/null)
+  if [ -z "$remote_url" ]; then
+    echo "0"
+    return 0
+  fi
+
+  # Match sunj-labs/(bassclef|bassclef-upstream) with optional .git suffix
+  # HTTPS: https://github.com/sunj-labs/bassclef.git
+  # SSH:   git@github.com:sunj-labs/bassclef-upstream.git
+  if echo "$remote_url" | grep -qE 'sunj-labs/(bassclef|bassclef-upstream)(\.git)?$'; then
+    echo "1"
+    return 0
+  fi
+
+  echo "0"
+  return 0
+}
+
+# === _sync_install_hooks (goal 14c Step 5) ===
+# Install a hard-coded list of substrate hooks to the operator's
+# ~/.claude/hooks/. For each name: if the source hook declares a
+# # install-class: header, route via lib/hook-installer.sh's
+# install_by_class (which honors operator|project|dual). If no header,
+# fall back to legacy operator-scope copy per ADR-058 c2 grace window
+# (through 2026-10-31).
+#
+# Args:
+#   $1 — BASSCLEF_DIR (source of hooks + lib)
+#   $2 — user-scope target dir (default $HOME/.claude/hooks)
+#
+# Discipline (per ADR-058 constraints 1-4):
+#   c1 — install_by_class wrapped in subshell; lib's strict mode
+#        stays contained; caller's strict-mode state preserved
+#   c2 — unheadered hooks install where they install today +
+#        one trace line `skipped-no-header <hook>` fires
+#   c3 — CLAUDE_PROJECT_DIR resolved (git rev-parse fallback) and
+#        exported before the loop so project/dual class routing works
+#   c4 — settings.json command strings unchanged; wiring self-heal
+#        continues at Section 4 (unrelated to this function)
+_sync_install_hooks() {
+  local bassclef_dir="$1"
+  local user_target_dir="${2:-$HOME/.claude/hooks}"
+
+  local hook_names=(
+    bug-diagnosis.sh
+    tool-failure-diagnosis.sh
+    trace-helper.sh
+    deploy-guard.sh
+    memory-write-audit.sh
+    turn-prose-kiss-check.sh
+    session-end.sh
+    bet-doc-gate.sh
+    substrate-clarity-gate.sh
+  )
+
+  mkdir -p "$user_target_dir" 2>/dev/null || true
+
+  local installer_lib="$bassclef_dir/lib/hook-installer.sh"
+  local dispatch_available=0
+  [ -f "$installer_lib" ] && dispatch_available=1
+
+  # ADR-058 c3 — resolve CLAUDE_PROJECT_DIR before loop
+  if [ -z "${CLAUDE_PROJECT_DIR:-}" ]; then
+    if command -v git >/dev/null 2>&1; then
+      CLAUDE_PROJECT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+    fi
+    if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+      export CLAUDE_PROJECT_DIR
+    fi
+  fi
+
+  for hook_name in "${hook_names[@]}"; do
+    local hook_src="$bassclef_dir/.claude/hooks/$hook_name"
+    if [ ! -f "$hook_src" ]; then
+      continue
+    fi
+
+    local has_header=0
+    if head -10 "$hook_src" 2>/dev/null | grep -qE '^# install-class:[[:space:]]*(operator|project|dual)[[:space:]]*$'; then
+      has_header=1
+    fi
+
+    if [ "$has_header" = "1" ] && [ "$dispatch_available" = "1" ]; then
+      # ADR-058 c1 — subshell wraps install_by_class so lib strict
+      # mode never leaks into this script. On subshell failure, fall
+      # back to legacy operator-scope copy to preserve adopter
+      # contract per c4 (settings.json command strings byte-identical).
+      # shellcheck disable=SC1090  # dynamic source path
+      if ! ( source "$installer_lib" 2>/dev/null && install_by_class "$hook_src" ) >/dev/null 2>&1; then
+        cp "$hook_src" "$user_target_dir/" 2>/dev/null || true
+        chmod +x "$user_target_dir/$hook_name" 2>/dev/null || true
+      fi
+    else
+      # ADR-058 c2 fallback — grace window through 2026-10-31.
+      cp "$hook_src" "$user_target_dir/" 2>/dev/null || true
+      chmod +x "$user_target_dir/$hook_name" 2>/dev/null || true
+      if [ "$has_header" = "0" ] && command -v trace_log >/dev/null 2>&1; then
+        trace_log "ok" "sync-install-hooks-skipped-no-header" "$hook_name"
+      fi
+    fi
+  done
+}
+
+# === Test-mode guard (#915) ===
+# Tests source this hook to access helpers without triggering main sync.
+# Early return under BASSCLEF_SYNC_TEST_MODE=1. Helpers defined ABOVE.
+if [ "${BASSCLEF_SYNC_TEST_MODE:-0}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# === Hook liveness heartbeat (WU-3 of bet 2026-07-31d; closes #1002) ===
+# Silent-fail — a missing lib never crashes the hook. Discipline: ADR-048 +
+# standards/hook-cadence.json. Session-start reflection module (WU-4.5) checks
+# marker mtime against expected cadence.
+{
+  _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 "bassclef-sync" && break
+  done
+  unset _hb_sd _hb_c
+} 2>/dev/null || true
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
+cd "$CWD"
+
+# === Section 0a fires: exit early if this repo is substrate source ===
+SELF_MODE=$(bassclef_detect_self_mode "$CWD")
+if [ "$SELF_MODE" = "1" ]; then
+  echo "SELF_MODE detected — skipping sync in substrate source repo." >&2
+  echo "  (Override with SKIP_SELF_MODE_DETECTION=1 for adopter forks.)" >&2
+  exit 0
+fi
+
+# Bassclef substrate location — peer clone at ../bassclef (post-rename).
+# Pre-rename ../canonical fallback removed 2026-06-24 per bassclef-upstream#317
+# Phase 0: zero adopters carry the canonical/ path; operator's local
+# ~/src/sunj-labs/canonical was removed before this cleanup.
+BASSCLEF_DIR="$CWD/../bassclef"
+BASSCLEF_REPO="https://github.com/sunj-labs/bassclef.git"
+SYNC_STATUS="up-to-date"
+SYNC_NEW=""
+
+# === 1. Clone or pull bassclef ===
+if [ ! -d "$BASSCLEF_DIR/.claude" ]; then
+  if git clone "$BASSCLEF_REPO" "$BASSCLEF_DIR"; 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 ""
+    exit 0
+  fi
+else
+  BEFORE=$(git -C "$BASSCLEF_DIR" rev-parse HEAD 2>/dev/null)
+  git -C "$BASSCLEF_DIR" pull --quiet 2>/dev/null || true
+  AFTER=$(git -C "$BASSCLEF_DIR" rev-parse HEAD 2>/dev/null)
+
+  if [ "$BEFORE" != "$AFTER" ]; then
+    SYNC_STATUS="updated"
+    SYNC_NEW=$(git -C "$BASSCLEF_DIR" log --oneline "$BEFORE".."$AFTER" 2>/dev/null)
+  fi
+fi
+
+# === 2. Symlink bassclef skills into project for auto-discovery ===
+mkdir -p "$CWD/.claude/skills" 2>/dev/null || true
+for SKILL_DIR in "$BASSCLEF_DIR/.claude/skills/"*/; do
+  SKILL_NAME=$(basename "$SKILL_DIR")
+  TARGET="$CWD/.claude/skills/$SKILL_NAME"
+  # Only symlink if not already an app-specific skill (real directory, not symlink)
+  if [ -L "$TARGET" ]; then
+    # Existing symlink — update it
+    rm "$TARGET"
+    ln -s "$SKILL_DIR" "$TARGET"
+  elif [ ! -d "$TARGET" ]; then
+    # Doesn't exist — create symlink
+    ln -s "$SKILL_DIR" "$TARGET"
+  fi
+  # If it's a real directory (app-specific), leave it alone
+done
+
+# === 2b. Park orphan ~/.claude/skills + agents + hooks symlinks (widened per ADR-033 + bassclef#278) ===
+# Uses the shared orphan-parking helper. Closes the skill / agent / hook
+# duplication-in-available-skills bug. The helper parks user-level
+# symlinks AND cp'd files whose basename appears in project-level —
+# preserves real directories untouched + EXCLUDES hooks wired in
+# settings.json at $HOME paths (per #294); backs up moved entries to
+# dated dirs that survive at least 30 days per Hyrum + Linus discipline.
+PARKING_HELPER="$BASSCLEF_DIR/scripts/bassclef-orphan-parking.sh"
+USER_SETTINGS="$HOME/.claude/settings.json"
+ORPHAN_COUNT=0
+if [ -f "$PARKING_HELPER" ]; then
+  for surface in skills agents hooks; do
+    USER_SURFACE="$HOME/.claude/$surface"
+    PROJECT_SURFACE="$CWD/.claude/$surface"
+    if [ -d "$USER_SURFACE" ] && [ -d "$PROJECT_SURFACE" ]; then
+      mkdir -p "$HOME/.claude" 2>/dev/null
+      # Pass user settings.json as 5th arg so wired hooks are excluded
+      # from parking. Per #294 — broke the Stop hook on this machine when
+      # parking removed session-end.sh that settings.json wires.
+      PARKED_LINE=$(bash "$PARKING_HELPER" "$USER_SURFACE" "$PROJECT_SURFACE" "$HOME/.claude" "$surface" "$USER_SETTINGS" 2>/dev/null || echo "")
+      if [ -n "$PARKED_LINE" ]; then
+        # Extract the count from "parked N <surface> orphans → <dir>"
+        COUNT_N=$(echo "$PARKED_LINE" | grep -oE 'parked [0-9]+' | grep -oE '[0-9]+' | head -1)
+        [ -n "$COUNT_N" ] && ORPHAN_COUNT=$((ORPHAN_COUNT + COUNT_N))
+      fi
+    fi
+  done
+fi
+
+# === 2c. Adopter self-heal — auto-migrate stale canonical references ===
+# Per ADR-031 we-dont-break-adopters + Nygard's Steady State pattern.
+# When this hook runs in an adopter repo (CWD is NOT bassclef-upstream and
+# does NOT have architecture/dual-repo-flow.md), invoke the migration script
+# to repair any stale ../canonical/ references in symlinks + settings.json
+# + dispatcher + statusline. Idempotent — no-op on already-migrated repos.
+#
+# Banner surfaces per-surface info (not just count) so adopters who
+# customized any of the migrated surfaces see exactly what changed.
+# Closes Yellow 2 of the 2026-06-22 release-readiness review.
+MIGRATE_SCRIPT="$BASSCLEF_DIR/scripts/migrate-adopter-references.sh"
+SUMMARY_HELPER="$BASSCLEF_DIR/scripts/bassclef-migrate-summary.sh"
+if [ -f "$MIGRATE_SCRIPT" ] && [ ! -f "$CWD/architecture/dual-repo-flow.md" ]; then
+  MIGRATE_OUT=$(bash "$MIGRATE_SCRIPT" --apply "$CWD" 2>&1)
+  MIGRATE_CHANGES=$(echo "$MIGRATE_OUT" | awk -F: '/^changes:/ {print $2}' | tr -d ' ')
+  if [ -n "$MIGRATE_CHANGES" ] && [ "$MIGRATE_CHANGES" -gt 0 ]; then
+    PER_SURFACE=""
+    # Check -f (file exists), not -x (executable). We invoke via `bash $HELPER`
+    # so the executable bit is irrelevant; the bit may not survive tarball
+    # fetches across adopter clones (per reviewer note on PR #291).
+    if [ -f "$SUMMARY_HELPER" ]; then
+      PER_SURFACE=$(echo "$MIGRATE_OUT" | bash "$SUMMARY_HELPER" 2>/dev/null)
+    fi
+    SYNC_NEW="${SYNC_NEW}
+Adopter self-heal: $MIGRATE_CHANGES surface(s) migrated. Old setup keeps working; new setup matches current bassclef substrate. Per ADR-031."
+    if [ -n "$PER_SURFACE" ]; then
+      SYNC_NEW="${SYNC_NEW}
+${PER_SURFACE}"
+    fi
+  fi
+fi
+
+# === 3. Install general hooks to ~/.claude/ ===
+# Delegates to _sync_install_hooks (goal 14c Step 5 per ADR-058).
+# The hard-coded 9-name list that lived here through v0.41.1 moved
+# into the function above. Each hook now routes by its own
+# # install-class: header when declared; unheadered hooks fall back
+# to legacy operator-scope copy per ADR-058 c2 grace window
+# (through 2026-10-31). Section 4 self-heal continues to preserve
+# adopter contract per c4 (settings.json command strings unchanged).
+_sync_install_hooks "$BASSCLEF_DIR" "$HOME/.claude/hooks"
+
+# === Install agents to ~/.claude/ ===
+mkdir -p ~/.claude/agents 2>/dev/null || true
+cp "$BASSCLEF_DIR/.claude/agents/"*.md ~/.claude/agents/ 2>/dev/null || true
+
+# === 4. Versioned self-heal of ~/.claude/settings.json ===
+# WU-3 of bet 2026-06-24a-settings-hardening (#313). Replaces the
+# brittle multi-grep + destructive heredoc rewrite with:
+#   1. Version-field comparison (read_settings_version).
+#   2. Additive merge that preserves operator's top-level keys (theme,
+#      statusLine, permissions, alwaysThinkingEnabled, etc.) and
+#      operator-only event types — bassclef wins per-event for events
+#      it ships.
+#   3. Hoare postcondition: after self-heal, drift detector MUST
+#      return clean (compare_wirings .ok == true). Else exit 1 with
+#      structured stderr — failure compounds across every adopter,
+#      so failing loud beats failing silent.
+# Closes the bug class diagnosed 2026-06-24 (operator's settings.json
+# never picked up substrate's new hook wirings).
+WIRINGS_LIB="$BASSCLEF_DIR/.claude/hooks/_lib/wirings.sh"
+PROJECT_SETTINGS="$BASSCLEF_DIR/.claude/settings.json"
+USER_SETTINGS="$HOME/.claude/settings.json"
+
+sync_self_heal() {
+  if [ ! -f "$WIRINGS_LIB" ] || [ ! -f "$PROJECT_SETTINGS" ]; then
+    # Substrate not fully synced yet OR project settings.json not
+    # checked out on this branch. Fall back silently — drift detector
+    # at next session-start will surface the gap.
+    return 0
+  fi
+  # shellcheck source=/dev/null
+  source "$WIRINGS_LIB"
+
+  local required_version user_version
+  required_version=$(read_settings_version "$PROJECT_SETTINGS")
+  user_version=$(read_settings_version "$USER_SETTINGS")
+
+  if [ ! -f "$USER_SETTINGS" ] || [ "$user_version" -lt "$required_version" ]; then
+    additive_merge_settings "$USER_SETTINGS" "$PROJECT_SETTINGS"
+  fi
+
+  # Hoare postcondition: required ⊆ loaded after self-heal.
+  local required loaded diff ok missing
+  required=$(read_required_wirings "$PROJECT_SETTINGS")
+  loaded=$(read_loaded_wirings)
+  diff=$(compare_wirings "$required" "$loaded")
+  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
+    if command -v trace_log >/dev/null 2>&1; then
+      trace_log "fail" "bassclef-sync-postcondition" "$missing"
+    fi
+    return 1
+  fi
+  if command -v trace_log >/dev/null 2>&1; then
+    trace_log "ok" "bassclef-sync-postcondition" "version=$required_version"
+  fi
+  return 0
+}
+
+sync_self_heal || exit 1
+
+# === 4b. PreToolUse template embedding — operator settings.json self-heal ===
+# Per bassclef-upstream#336 — ensure operator's ~/.claude/settings.json wires
+# the bassclef-managed PreToolUse hooks (substrate-clarity-gate + bet-doc-gate).
+# Mirrors §3c-hooks in presence/install/bassclef-sync.template.sh (consumer-side)
+# but targets ~/.claude/settings.json with $HOME-prefixed commands.
+#
+# Why this lives here even though §4 sync_self_heal runs additive-merge:
+# wirings.sh merges bassclef's project settings.json into operator's user
+# settings.json — but during a sync where wirings.sh itself is being upgraded,
+# OR when the operator's settings.json predates the wirings library entirely,
+# the merge may not fire. This §4b is the literal-text fallback: greppable
+# guards re-emit the PreToolUse template when entries are missing, regardless
+# of wirings.sh state. Bootstrap-pair discipline (per
+# .claude/rules/bootstrap-pair-discipline.md) — wiring ships in the same place
+# as the hook reference.
+#
+# Template (operator settings.json fragment, "PreToolUse": event):
+#   {
+#     "hooks": {
+#       "PreToolUse": [
+#         {
+#           "matcher": "Edit|Write|MultiEdit",
+#           "hooks": [
+#             {"type": "command", "command": "$HOME/.claude/hooks/substrate-clarity-gate.sh"},
+#             {"type": "command", "command": "$HOME/.claude/hooks/bet-doc-gate.sh"}
+#           ]
+#         }
+#       ]
+#     }
+#   }
+#
+# Idempotent via jq additive merge — re-runs detect existing entries and skip.
+# Skip paths:
+#   - SKIP_PRETOOLUSE_EMBED=1 — operator override (logged)
+#   - jq missing — graceful skip with stderr notice
+#   - ~/.claude/settings.json missing — skip (sync_self_heal handles creation)
+if [ "${SKIP_PRETOOLUSE_EMBED:-0}" != "1" ] && \
+   command -v jq >/dev/null 2>&1 && \
+   [ -f "$USER_SETTINGS" ]; then
+
+  # Guard re-emit when bet-doc-gate missing (existing-adopter self-heal)
+  if ! grep -q 'bet-doc-gate' ~/.claude/settings.json 2>/dev/null; then
+    BET_DOC_GATE_MISSING=1
+  else
+    BET_DOC_GATE_MISSING=0
+  fi
+  # Guard re-emit when substrate-clarity-gate missing
+  if ! grep -q 'substrate-clarity-gate' ~/.claude/settings.json 2>/dev/null; then
+    SUBSTRATE_CLARITY_GATE_MISSING=1
+  else
+    SUBSTRATE_CLARITY_GATE_MISSING=0
+  fi
+
+  if [ "$BET_DOC_GATE_MISSING" = "1" ] || [ "$SUBSTRATE_CLARITY_GATE_MISSING" = "1" ]; then
+    # Operator-class PreToolUse template — note the $HOME prefix (left literal
+    # in JSON; Claude Code expands at hook-fire time per presence/install
+    # consumer-side §4 line 820 precedent).
+    OPERATOR_PRETOOLUSE_JSON='[
+      {"matcher": "Edit|Write|MultiEdit", "command": "$HOME/.claude/hooks/substrate-clarity-gate.sh"},
+      {"matcher": "Edit|Write|MultiEdit", "command": "$HOME/.claude/hooks/bet-doc-gate.sh"}
+    ]'
+
+    # Additive jq merge — mirrors §3c-hooks logic but writes to USER_SETTINGS:
+    #   1. Ensure .hooks.PreToolUse array exists
+    #   2. For each bassclef hook:
+    #      - If matcher exists, ensure command is in the matcher's hooks array
+    #      - If matcher missing, create new matcher entry with the command
+    # Operator-managed entries (other matchers, other commands) stay untouched.
+    NEW_OPERATOR_SETTINGS=$(jq --argjson bassclef "$OPERATOR_PRETOOLUSE_JSON" '
+      .hooks //= {} |
+      .hooks.PreToolUse //= [] |
+      reduce $bassclef[] as $hook (
+        .;
+        if (.hooks.PreToolUse | map(.matcher) | index($hook.matcher)) != null then
+          .hooks.PreToolUse |= map(
+            if .matcher == $hook.matcher then
+              if (.hooks | map(.command) | index($hook.command)) == null then
+                .hooks += [{"type": "command", "command": $hook.command}]
+              else . end
+            else . end
+          )
+        else
+          .hooks.PreToolUse += [{
+            "matcher": $hook.matcher,
+            "hooks": [{"type": "command", "command": $hook.command}]
+          }]
+        end
+      )
+    ' "$USER_SETTINGS" 2>/dev/null)
+
+    if [ -n "$NEW_OPERATOR_SETTINGS" ]; then
+      echo "$NEW_OPERATOR_SETTINGS" > "$USER_SETTINGS.tmp" && \
+        mv "$USER_SETTINGS.tmp" "$USER_SETTINGS"
+      if command -v trace_log >/dev/null 2>&1; then
+        trace_log "ok" "bassclef-sync-pretooluse-embed" \
+          "added_bet_doc=$BET_DOC_GATE_MISSING added_substrate_clarity=$SUBSTRATE_CLARITY_GATE_MISSING"
+      fi
+    fi
+  fi
+fi
+
+# === 4c. Stop template embedding — operator settings.json self-heal ===
+# Same pattern as §4b but for the "Stop": event — wires
+# $HOME/.claude/hooks/turn-prose-kiss-check.sh so the per-turn /kiss scan
+# fires at session-stop boundaries. Per bassclef-upstream#336 sister gap
+# (Stop template embedding missing alongside PreToolUse).
+#
+# Template (operator settings.json fragment, "Stop": event):
+#   {
+#     "hooks": {
+#       "Stop": [
+#         {
+#           "matcher": "",
+#           "hooks": [
+#             {"type": "command", "command": "$HOME/.claude/hooks/turn-prose-kiss-check.sh", "timeout": 30}
+#           ]
+#         }
+#       ]
+#     }
+#   }
+#
+# Timeout 30s: turn-prose-kiss-check scans the most-recent assistant message
+# against the BLOCK wordlist; finishes well under 30s on any realistic
+# transcript. ≥5s minimum per session-artifacts rule (Stop hooks need
+# adequate timeout or they get killed mid-write).
+if [ "${SKIP_STOP_EMBED:-0}" != "1" ] && \
+   command -v jq >/dev/null 2>&1 && \
+   [ -f "$USER_SETTINGS" ]; then
+
+  # Guard re-emit when turn-prose entry missing
+  if ! grep -q 'turn-prose' ~/.claude/settings.json 2>/dev/null; then
+    TURN_PROSE_MISSING=1
+  else
+    TURN_PROSE_MISSING=0
+  fi
+
+  if [ "$TURN_PROSE_MISSING" = "1" ]; then
+    # Stop-event entry — empty matcher (Stop fires once per session-end;
+    # no per-tool matcher applies). Command uses $HOME-prefixed path
+    # (Claude Code expands at hook-fire time). Timeout 30 per above.
+    OPERATOR_STOP_JSON='[
+      {"matcher": "", "command": "$HOME/.claude/hooks/turn-prose-kiss-check.sh", "timeout": 30}
+    ]'
+
+    NEW_STOP_SETTINGS=$(jq --argjson bassclef "$OPERATOR_STOP_JSON" '
+      .hooks //= {} |
+      .hooks.Stop //= [] |
+      reduce $bassclef[] as $hook (
+        .;
+        if (.hooks.Stop | map(.matcher) | index($hook.matcher)) != null then
+          .hooks.Stop |= map(
+            if .matcher == $hook.matcher then
+              if (.hooks | map(.command) | index($hook.command)) == null then
+                .hooks += [{"type": "command", "command": $hook.command, "timeout": $hook.timeout}]
+              else . end
+            else . end
+          )
+        else
+          .hooks.Stop += [{
+            "matcher": $hook.matcher,
+            "hooks": [{"type": "command", "command": $hook.command, "timeout": $hook.timeout}]
+          }]
+        end
+      )
+    ' "$USER_SETTINGS" 2>/dev/null)
+
+    if [ -n "$NEW_STOP_SETTINGS" ]; then
+      echo "$NEW_STOP_SETTINGS" > "$USER_SETTINGS.tmp" && \
+        mv "$USER_SETTINGS.tmp" "$USER_SETTINGS"
+      if command -v trace_log >/dev/null 2>&1; then
+        trace_log "ok" "bassclef-sync-stop-embed" \
+          "added_turn_prose=$TURN_PROSE_MISSING"
+      fi
+    fi
+  fi
+fi
+
+# === 5. Set env var for rules/CLAUDE.md inheritance ===
+if [ -n "$CLAUDE_ENV_FILE" ]; then
+  echo "CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1" >> "$CLAUDE_ENV_FILE"
+fi
+
+# === Summary ===
+SKILL_COUNT=$(ls "$BASSCLEF_DIR/.claude/skills/" 2>/dev/null | wc -l | tr -d ' ')
+RULE_COUNT=$(ls "$BASSCLEF_DIR/.claude/rules/" 2>/dev/null | wc -l | tr -d ' ')
+AGENT_COUNT=$(ls ~/.claude/agents/ 2>/dev/null | wc -l | tr -d ' ')
+HOOK_COUNT=$(ls ~/.claude/hooks/*.sh 2>/dev/null | wc -l | tr -d ' ')
+
+echo ""
+echo "### BASSCLEF SUBSTRATE — SYNCED"
+echo ""
+echo "Status: $SYNC_STATUS"
+echo "Skills: ${SKILL_COUNT} (symlinked to .claude/skills/ for auto-discovery)"
+echo "Rules: ${RULE_COUNT} (loaded via additionalDirectories + env var)"
+echo "Agents: ${AGENT_COUNT} (installed to ~/.claude/agents/)"
+echo "Hooks: ${HOOK_COUNT} user-level (bug-diagnosis, tool-failure, trace-helper)"
+echo ""
+
+if [ -n "$SYNC_NEW" ]; then
+  echo "### NEW SINCE LAST SYNC — REVIEW BEFORE PROCEEDING"
+  echo ""
+  echo "$SYNC_NEW"
+  echo ""
+  echo "→ New bassclef standards detected. Ask the user to confirm"
+  echo "  before proceeding. These may change how this session operates."
+  echo ""
+fi
+
+if [ "$ORPHAN_COUNT" -gt 0 ]; then
+  echo "### USER-LEVEL SUBSTRATE CLEANUP (per ADR-033 + bassclef#278)"
+  echo ""
+  echo "Parked $ORPHAN_COUNT user-level entries (skills + agents + hooks; symlinks AND cp'd files)"
+  echo "whose basenames duplicated project-level entries. Backup dirs:"
+  echo "  ~/.claude/skills.orphans.$(date +%Y%m%d)/"
+  echo "  ~/.claude/agents.orphans.$(date +%Y%m%d)/"
+  echo "  ~/.claude/hooks.orphans.$(date +%Y%m%d)/"
+  echo ""
+  echo "Project-level entries now load without dedupe conflict."
+  echo "Backups survive 30 days minimum; restore if a script you wrote"
+  echo "depends on the user-level location."
+  echo ""
+fi
+
+echo "YOU MUST confirm to the user:"
+echo "  'Bassclef substrate synced: ${SKILL_COUNT} skills, ${RULE_COUNT} rules,"
+echo "   ${AGENT_COUNT} agents, ${HOOK_COUNT} hooks. Status: ${SYNC_STATUS}.'"
+echo ""
+
+# === 6. Worktree cleanup — prune stale worktrees from crashed parallel sessions ===
+STALE_WORKTREES=$(git -C "$CWD" worktree list --porcelain 2>/dev/null | grep "^worktree " | grep -v "$CWD$" | wc -l | tr -d ' ')
+if [ "$STALE_WORKTREES" -gt 0 ]; then
+  # Prune worktrees whose directories no longer exist
+  git -C "$CWD" worktree prune 2>/dev/null || true
+
+  # Clean up .claude/worktrees/ directory if it exists
+  if [ -d "$CWD/.claude/worktrees" ]; then
+    rm -rf "$CWD/.claude/worktrees" 2>/dev/null || true
+  fi
+
+  REMAINING=$(git -C "$CWD" worktree list --porcelain 2>/dev/null | grep "^worktree " | grep -v "$CWD$" | wc -l | tr -d ' ')
+  if [ "$REMAINING" -gt 0 ]; then
+    echo "### STALE WORKTREES DETECTED"
+    echo ""
+    echo "$REMAINING worktree(s) from a previous session still exist."
+    echo "These may hold branch locks. Review and remove:"
+    echo ""
+    git -C "$CWD" worktree list 2>/dev/null | grep -v "$CWD "
+    echo ""
+    echo "To remove: git worktree remove <path>"
+    echo ""
+  fi
+fi
+
+# === 7. Boot check — only report what's missing ===
+MISSING=""
+
+# Google service account (needed for journal → Google Docs)
+SA_KEY="$HOME/.config/gcloud/sunjay-google-ops.json"
+if [ ! -f "$SA_KEY" ]; then
+  MISSING="${MISSING}\n- Google Docs service account key missing at $SA_KEY (needed for /journal → Google Doc push)"
+fi
+
+# gh CLI auth (needed for /promote, issue creation)
+if ! command -v gh &>/dev/null; then
+  MISSING="${MISSING}\n- gh CLI not installed (needed for /promote, issue creation)"
+elif ! gh auth status &>/dev/null 2>&1; then
+  MISSING="${MISSING}\n- gh CLI not authenticated (run: gh auth login)"
+fi
+
+if [ -n "$MISSING" ]; then
+  echo "### SUBSTRATE DEPENDENCIES — OPTIONAL SETUP NEEDED"
+  echo ""
+  echo "The following are not blocking but limit some skills:"
+  echo -e "$MISSING"
+  echo ""
+  echo "Run: bassclef/scripts/boot-bassclef.sh for full setup guide."
+  echo "These are informational — proceed with your work."
+  echo ""
+fi
+
+# === 8. journal draft staleness check ===
+# Check both bassclef and the current repo for stale drafts.
+#
+# Fetch origin first (per bassclef-upstream#403): the staleness check
+# below reads local filesystem state + local git log, which diverges
+# from origin when another session has pushed since the last pull
+# (e.g., a prior session-end's commit). Without the fetch, the banner
+# shows wrong-now data (observed 2026-06-26c — local saw 2026-06-19
+# while origin had 2026-06-26.md from #401).
+#
+# Best-effort: || true keeps the check working when offline / no remote.
+CURRENT_BRANCH_FOR_FETCH=$(git -C "$CWD" symbolic-ref --short HEAD 2>/dev/null)
+if [ -n "$CURRENT_BRANCH_FOR_FETCH" ]; then
+  git -C "$CWD" fetch origin "$CURRENT_BRANCH_FOR_FETCH" --quiet 2>/dev/null || true
+fi
+
+DRAFT_DIRS=""
+if [ -d "$CWD/docs/operator-private/journals" ]; then
+  DRAFT_DIRS="$CWD/docs/operator-private/journals"
+elif [ -d "$CWD/docs/journals" ]; then
+  # Pre-2026-06-27 path — migrated to operator-private per bassclef-upstream#405
+  DRAFT_DIRS="$CWD/docs/journals"
+elif [ -d "$CWD/docs/linkedin-drafts" ]; then
+  # Legacy path — pre-/linkedin-→-/journal rename
+  DRAFT_DIRS="$CWD/docs/linkedin-drafts"
+fi
+if [ -d "$BASSCLEF_DIR/docs/operator-private/journals" ] && [ "$BASSCLEF_DIR" != "$CWD" ]; then
+  DRAFT_DIRS="$DRAFT_DIRS $BASSCLEF_DIR/docs/operator-private/journals"
+elif [ -d "$BASSCLEF_DIR/docs/journals" ] && [ "$BASSCLEF_DIR" != "$CWD" ]; then
+  DRAFT_DIRS="$DRAFT_DIRS $BASSCLEF_DIR/docs/journals"
+fi
+
+if [ -n "$DRAFT_DIRS" ]; then
+  LATEST_DRAFT=""
+  for DIR in $DRAFT_DIRS; do
+    LAST=$(ls -1 "$DIR"/*.md 2>/dev/null | sort | tail -1)
+    if [ -n "$LAST" ]; then
+      DRAFT_DATE=$(basename "$LAST" .md | head -c 10)
+      if [ -z "$LATEST_DRAFT" ] || [ "$DRAFT_DATE" \> "$LATEST_DRAFT" ]; then
+        LATEST_DRAFT="$DRAFT_DATE"
+      fi
+    fi
+  done
+
+  if [ -n "$LATEST_DRAFT" ]; then
+    TODAY=$(date +%Y-%m-%d)
+    # Count commits since last draft
+    COMMITS_SINCE=$(git -C "$CWD" log --oneline --since="$LATEST_DRAFT" 2>/dev/null | wc -l | tr -d ' ')
+
+    if [ "$LATEST_DRAFT" != "$TODAY" ] && [ "$COMMITS_SINCE" -gt 3 ]; then
+      DAYS_AGO=$(( ( $(date +%s) - $(date -j -f "%Y-%m-%d" "$LATEST_DRAFT" +%s 2>/dev/null || echo 0) ) / 86400 ))
+      echo "### JOURNAL DRAFTS OVERDUE (SHOULD — backfill before other work)"
+      echo ""
+      echo "Last draft: $LATEST_DRAFT ($DAYS_AGO days ago, $COMMITS_SINCE commits since)"
+      echo ""
+      echo "→ BACKFILL NOW — before starting new work."
+      echo "  1. Read chronicles since $LATEST_DRAFT"
+      echo "  2. Write drafts for each session with a notable decision or insight"
+      echo "  3. Push to Google Doc (oldest first)"
+      echo "  4. Then proceed with session work"
+      echo ""
+      echo "This is a SHOULD gate. Do not skip without documented rationale."
+      echo ""
+    fi
+  fi
+fi
+
+exit 0