@thebassclef/lite 1.0.1 → 1.0.3

package/dist/lite/.claude/hooks/session-reflection.d/90-secrets-expiry.sh

@@ -0,0 +1,104 @@
+# tier: lite
+# Secrets-expiry scan: parse substrate.secrets.md, surface BLOCKED
+# at session start when any secret is within alert_threshold_days.
+#
+# Schema:   standards/state-spine/schemas/substrate-secrets.schema.json
+# Standard: standards/secrets-lifecycle.md
+# Rule:     (paired with .claude/rules/substrate-config-schema.md cross-reference)
+# Refs:     bassclef#381
+#
+# Behavior:
+# - Silent when no substrate.secrets.md (graceful in repos without secrets)
+# - Silent when all secrets in OK state
+# - Surfaces BLOCKED block listing every WARN / ALERT / EXPIRED secret
+#   with rotation procedure path
+# - Override per-session: SKIP_SECRETS_EXPIRY_CHECK=1 (logged to stderr)
+
+# Per-session override
+if [ "${SKIP_SECRETS_EXPIRY_CHECK:-0}" = "1" ]; then
+  echo "[secrets-expiry: SKIP_SECRETS_EXPIRY_CHECK=1, skipping]" >&2
+  return 0 2>/dev/null || true
+fi
+
+SECRETS_FILE="${CWD:-$(pwd)}/substrate.secrets.md"
+
+# No file → graceful exit (consumer repo without secrets is fine)
+if [ ! -f "$SECRETS_FILE" ]; then
+  return 0 2>/dev/null || true
+fi
+
+# Locate the status script. Prefer consumer-repo path; fall back to
+# bassclef-vendored path if available.
+STATUS_SCRIPT="${CWD:-$(pwd)}/scripts/secrets-status.sh"
+if [ ! -x "$STATUS_SCRIPT" ] && [ -n "${BASSCLEF_DIR:-}" ]; then
+  STATUS_SCRIPT="${BASSCLEF_DIR}/scripts/secrets-status.sh"
+fi
+
+if [ ! -x "$STATUS_SCRIPT" ]; then
+  # Script missing — surface as BLOCKED with installation hint.
+  blocked_banner "secrets-expiry — scripts/secrets-status.sh not found
+
+substrate.secrets.md exists at $SECRETS_FILE but the status script is
+missing. The hook can't check expiry without it.
+
+Resolution:
+  - If this is bassclef: ensure scripts/secrets-status.sh is committed
+  - If this is a consumer repo: re-run /onboard-repo to vendor the script
+
+Override: SKIP_SECRETS_EXPIRY_CHECK=1 <command>
+Standard: standards/secrets-lifecycle.md"
+  return 0 2>/dev/null || true
+fi
+
+# Run status script in JSON mode for parseable output
+STATUS_JSON="$(SECRETS_FILE="$SECRETS_FILE" bash "$STATUS_SCRIPT" --json 2>/dev/null || echo '')"
+
+if [ -z "$STATUS_JSON" ]; then
+  return 0 2>/dev/null || true
+fi
+
+# Extract WARN / ALERT / EXPIRED entries via python3 (jq optional).
+# Each line of output is "STATE|NAME|EXPIRES|DAYS|PROCEDURE"
+PROBLEM_ENTRIES="$(echo "$STATUS_JSON" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+for s in d.get('secrets', []):
+    state = s.get('state', '')
+    if state in ('WARN', 'ALERT', 'EXPIRED'):
+        print(f\"{state}|{s.get('name','')}|{s.get('expires_at','')}|{s.get('days_remaining','')}|{s.get('rotation_procedure','')}\")
+" 2>/dev/null || echo '')"
+
+if [ -z "$PROBLEM_ENTRIES" ]; then
+  return 0 2>/dev/null || true
+fi
+
+# Build BLOCKED banner content
+MSG="secrets-expiry — at least one credential within alert window
+
+"
+
+while IFS='|' read -r state name expires days proc; do
+  case "$state" in
+    EXPIRED) glyph="💀 EXPIRED" ;;
+    ALERT)   glyph="🛑 ALERT  " ;;
+    WARN)    glyph="⚠️  WARN   " ;;
+    *)       glyph="$state" ;;
+  esac
+  MSG="$MSG  $glyph  $name  expires $expires ($days days)
+              rotate: $proc
+"
+done <<< "$PROBLEM_ENTRIES"
+
+MSG="$MSG
+Resolution paths:
+  1. Rotate the credential per its rotation_procedure runbook
+  2. Update substrate.secrets.md (last_rotated + expires_at) after rotation
+  3. Verify with: bash scripts/secrets-status.sh
+
+Override (per-session): SKIP_SECRETS_EXPIRY_CHECK=1 <command>
+Standard: standards/secrets-lifecycle.md"
+
+blocked_banner "$MSG"

package/dist/lite/.claude/hooks/session-reflection.d/95-settings-hook-verify.sh

@@ -0,0 +1,131 @@
+# tier: lite
+# Settings hook path verifier — fires at every SessionStart via
+# session-reflection.sh. Reads project settings.json (and user
+# settings.json when reachable), enumerates every hook command path,
+# checks each file exists on disk. Fires BLOCKED banner when any wired
+# hook path resolves to a missing file.
+#
+# Closes the silent staleness class per bassclef-upstream#888. When a
+# hook path in settings.json points at a file that got renamed, deleted,
+# or never installed, SessionStart today prints a non-blocking error and
+# the session continues. Adopters miss the signal. Substrate discipline
+# quietly disappears from that session's context.
+#
+# Sourced (not exec'd) by session-reflection.sh. Inherits:
+#   - blocked_banner() function
+#   - trace_log() function
+#   - BASSCLEF_DIR environment variable
+#   - CWD (project root; the harness sets it before source)
+#
+# Per @luminary saltzer-schroeder — complete mediation. Every settings
+# entry gets checked, not sampled.
+# Per @luminary linus-torvalds — we do not break adopters. A missing hook
+# is a silent break of the adopter contract; this check surfaces it.
+#
+# Override path — operator can bypass per-session.
+if [ "${SKIP_SETTINGS_HOOK_VERIFY:-0}" = "1" ]; then
+  trace_log "skip" "settings-hook-verify" "SKIP_SETTINGS_HOOK_VERIFY=1" 2>/dev/null || true
+  return 0 2>/dev/null || true
+fi
+
+# Require jq for JSON parsing. Skip silently when absent (rare).
+if ! command -v jq >/dev/null 2>&1; then
+  trace_log "skip" "settings-hook-verify" "jq not available" 2>/dev/null || true
+  return 0 2>/dev/null || true
+fi
+
+__shv_settings_files=""
+__shv_project_settings="${CWD:-${PWD}}/.claude/settings.json"
+if [ -f "$__shv_project_settings" ]; then
+  __shv_settings_files="$__shv_project_settings"
+fi
+__shv_user_settings="${HOME}/.claude/settings.json"
+if [ -f "$__shv_user_settings" ]; then
+  __shv_settings_files="${__shv_settings_files:+${__shv_settings_files}$'\n'}${__shv_user_settings}"
+fi
+
+if [ -z "$__shv_settings_files" ]; then
+  trace_log "skip" "settings-hook-verify" "no settings.json readable" 2>/dev/null || true
+  unset __shv_settings_files __shv_project_settings __shv_user_settings
+  return 0 2>/dev/null || true
+fi
+
+# Extract the first token of every hook command across every event class.
+# The command string may be plain path OR `path && next` OR `env=X path`.
+# We take the first whitespace-separated token.
+__shv_missing=""
+__shv_check_file() {
+  local raw_cmd="$1"
+  local source_file="$2"
+  # First token — everything up to the first space, tab, or ampersand.
+  local first_token
+  first_token=$(printf '%s' "$raw_cmd" | awk '{print $1}')
+  # Skip if empty or does not look like a path (starts with quote or brace).
+  case "$first_token" in
+    ''|'{'*|'['*) return 0 ;;
+  esac
+  # Expand known env vars. Leave others as-is (best effort).
+  local expanded="$first_token"
+  expanded="${expanded//\$HOME/$HOME}"
+  expanded="${expanded//\$\{HOME\}/$HOME}"
+  expanded="${expanded//\$CLAUDE_PROJECT_DIR/${CWD:-${PWD}}}"
+  expanded="${expanded//\$\{CLAUDE_PROJECT_DIR\}/${CWD:-${PWD}}}"
+  # If still has an unexpanded $VAR, skip (cannot verify with confidence).
+  case "$expanded" in
+    *'$'*) return 0 ;;
+  esac
+  # Absolute path required for the check.
+  case "$expanded" in
+    /*) : ;;
+    *) return 0 ;;
+  esac
+  if [ ! -f "$expanded" ]; then
+    __shv_missing="${__shv_missing:+${__shv_missing}$'\n'}  - ${expanded} (from ${source_file})"
+  fi
+}
+
+__shv_scan_settings() {
+  local settings="$1"
+  local raw
+  # Extract every .hooks.*[].hooks[].command as one line per command.
+  raw=$(jq -r '
+    .hooks // {}
+    | to_entries[]?
+    | .value[]?
+    | .hooks[]?
+    | select(.command != null)
+    | .command
+  ' "$settings" 2>/dev/null)
+  if [ -z "$raw" ]; then
+    return 0
+  fi
+  local line
+  while IFS= read -r line; do
+    [ -n "$line" ] && __shv_check_file "$line" "$settings"
+  done <<< "$raw"
+}
+
+# Scan each settings file.
+while IFS= read -r __shv_file; do
+  [ -n "$__shv_file" ] && __shv_scan_settings "$__shv_file"
+done <<< "$__shv_settings_files"
+
+if [ -n "$__shv_missing" ]; then
+  blocked_banner "settings-hook-verify" \
+    "Hooks wired in settings.json but missing on disk:" \
+    "$__shv_missing" \
+    "" \
+    "Cure paths:" \
+    "  1. Re-run bassclef-sync.sh to restore vendored/symlinked hooks" \
+    "  2. Edit the settings file and remove the stale entry" \
+    "  3. Override this session: SKIP_SETTINGS_HOOK_VERIFY=1" \
+    "" \
+    "Per bassclef-upstream#888."
+  trace_log "fired" "settings-hook-verify" "missing hooks detected" 2>/dev/null || true
+else
+  trace_log "pass" "settings-hook-verify" "all wired hooks resolve" 2>/dev/null || true
+fi
+
+unset __shv_settings_files __shv_project_settings __shv_user_settings \
+      __shv_missing __shv_file
+unset -f __shv_check_file __shv_scan_settings

package/dist/lite/.claude/hooks/session-reflection.d/95-telemetry-emit.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# .claude/hooks/session-reflection.d/95-telemetry-emit.sh
+# tier: lite
+# install-class: dual
+#
+# Session-start telemetry emit fragment (bet 2026-07-31f Step 4).
+#
+# Emits `session_start` event when opt-in is ON. If no prior events file
+# exists, also emits an `install_probe` event once — this is the first-
+# session marker used to correlate install source.
+#
+# Silent-fail per @luminary michael-nygard R1 — never crashes session start.
+
+# Coordinator-side helpers are provided by the parent session-reflection loop.
+# When sourced from that context, `blocked_banner` + `trace_log` + `BASSCLEF_DIR`
+# are already in scope. When run standalone, we no-op the helpers to stay safe.
+
+if ! declare -F trace_log >/dev/null 2>&1; then
+  trace_log() { :; }
+fi
+BASSCLEF_DIR="${BASSCLEF_DIR:-${CWD:-$PWD}}"
+
+# Probe bundled lib path first (dist/lite/ ship path per #1631 goal
+# 2026-09-14b), then $BASSCLEF_DIR fallback for synced adopters.
+# Pattern matches session-reflection.sh:13.
+_sd="$(dirname "${BASH_SOURCE[0]:-$0}")"
+TL_LIB=""
+for _c in "${_sd}/../../../lib/telemetry.sh" \
+          "$BASSCLEF_DIR/lib/telemetry.sh"; do
+  [ -f "$_c" ] && TL_LIB="$_c" && break
+done
+
+# Fire in a silent-fail block so any error here does not crash session start.
+{
+  # Only fire when the lib exists (adopter has telemetry enabled)
+  if [ -n "$TL_LIB" ]; then
+    # shellcheck source=/dev/null
+    source "$TL_LIB" 2>/dev/null || return 0 2>/dev/null || exit 0
+
+    if telemetry_is_enabled; then
+      sid=$(telemetry_session_id)
+      today=$(date -u +%Y%m%d)
+      events_dir="$BASSCLEF_DIR/state/telemetry"
+
+      # Install probe fires once per install — check if any prior events exist
+      if ! compgen -G "$events_dir/events-*.jsonl" >/dev/null 2>&1; then
+        # First session ever — emit install_probe (source: unknown for MVP)
+        install_source="unknown"
+        [ -d "$BASSCLEF_DIR/node_modules/@thebassclef" ] && install_source="npm"
+        [ -f "$BASSCLEF_DIR/.git/HEAD" ] && install_source="github-clone"
+
+        uid=$(uuidgen 2>/dev/null | tr '[:upper:]' '[:lower:]' || echo "00000000-0000-4000-8000-000000000000")
+        ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+        telemetry_emit "{\"event_type\":\"install_probe\",\"event_id\":\"$uid\",\"session_id\":\"$sid\",\"timestamp\":\"$ts\",\"tier\":\"lite\",\"payload\":{\"install_source\":\"$install_source\"}}"
+      fi
+
+      # Emit session_start
+      uid=$(uuidgen 2>/dev/null | tr '[:upper:]' '[:lower:]' || echo "00000000-0000-4000-8000-000000000001")
+      ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+      telemetry_emit "{\"event_type\":\"session_start\",\"event_id\":\"$uid\",\"session_id\":\"$sid\",\"timestamp\":\"$ts\",\"tier\":\"lite\",\"payload\":{}}"
+      trace_log "95-telemetry-emit: session_start emitted for session $sid"
+    fi
+  fi
+} 2>/dev/null || true
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/97-install-class-dispatch.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+#
+# 97-install-class-dispatch.sh — fragment that sources the install-class
+# dispatch libs so the source-graph closure walker discovers them at
+# build time (per scripts/build-adopter-tree.sh).
+#
+# Behavior today (V0 — goal 14c Steps 0-4 landed):
+#   - Sources lib/hook-header-parser.sh + lib/hook-installer.sh + lib/source-graph-walker.sh
+#   - Does NOT call install_by_class yet — Steps 5-6 extend this fragment
+#     to iterate substrate hooks and dispatch
+#
+# Why source-without-call:
+#   - Walker discovers libs via source-graph closure (per canvas Stage 2)
+#   - LITE_LIBS ships the 3 libs to dist/lite/lib/
+#   - Walker+LITE_LIBS sync check requires walker to find every LITE_LIBS entry
+#   - Sourcing without calling makes the libs walker-discoverable without
+#     changing SessionStart behavior — belt-and-braces for the Step 5-6 wire
+#
+# Silent-fail per ADR-050 R7 — never crash SessionStart on lib source failure
+
+_ICD_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source each dispatch lib. Bundled path first (dist/lite/lib/), $BASSCLEF_DIR fallback.
+# Static .sh literals so scripts/build-adopter-tree.sh source-graph walker discovers them.
+
+# hook-header-parser.sh
+if [ -f "$_ICD_SCRIPT_DIR/../../../lib/hook-header-parser.sh" ]; then
+  # shellcheck source=/dev/null
+  { source "$_ICD_SCRIPT_DIR/../../../lib/hook-header-parser.sh"; } 2>/dev/null || true
+elif [ -f "${BASSCLEF_DIR:-}/lib/hook-header-parser.sh" ]; then
+  # shellcheck source=/dev/null
+  { source "${BASSCLEF_DIR:-}/lib/hook-header-parser.sh"; } 2>/dev/null || true
+fi
+
+# hook-installer.sh
+if [ -f "$_ICD_SCRIPT_DIR/../../../lib/hook-installer.sh" ]; then
+  # shellcheck source=/dev/null
+  { source "$_ICD_SCRIPT_DIR/../../../lib/hook-installer.sh"; } 2>/dev/null || true
+elif [ -f "${BASSCLEF_DIR:-}/lib/hook-installer.sh" ]; then
+  # shellcheck source=/dev/null
+  { source "${BASSCLEF_DIR:-}/lib/hook-installer.sh"; } 2>/dev/null || true
+fi
+
+# source-graph-walker.sh
+if [ -f "$_ICD_SCRIPT_DIR/../../../lib/source-graph-walker.sh" ]; then
+  # shellcheck source=/dev/null
+  { source "$_ICD_SCRIPT_DIR/../../../lib/source-graph-walker.sh"; } 2>/dev/null || true
+elif [ -f "${BASSCLEF_DIR:-}/lib/source-graph-walker.sh" ]; then
+  # shellcheck source=/dev/null
+  { source "${BASSCLEF_DIR:-}/lib/source-graph-walker.sh"; } 2>/dev/null || true
+fi
+
+# Steps 5-6 will extend below with actual install_by_class calls per
+# goal 2026-09-14c step sequencing (docs/iteration-bets/2026-09-14c-*.md).
+# Today the fragment sources-without-calls to satisfy walker discovery.