@thebassclef/lite 1.0.2 → 1.0.3

package/dist/lite/.claude/hooks/session-reflection.d/75-prior-r8-findings.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# 75-prior-r8-findings.sh — SessionStart fragment that surfaces prior R8
+# catches from recent chronicles. Primes the agent on the pattern early
+# in the session so claim-shape prose without cited sources gets caught
+# at authoring time, not just at end-of-turn (Surface 4) or write (Surface 5)
+# or Bash (Surface 6).
+#
+# Per bet 2026-07-03a WU-4 + ADR-035 (surface 7 of 9-hook taxonomy)
+# Sister surfaces: assert-verify-steering.sh (1), kiss-expansion-inject.sh (2),
+#   posttooluse-reprime.sh (3), stop-assertion-shape-scan.sh (4),
+#   substrate-clarity-gate.sh (5), pre-gh-git-claim-shape-scrub.sh (6)
+#
+# Behavior:
+#   - Fires at SessionStart via session-reflection.d dispatcher
+#   - Reads chronicle/ or docs/chronicle/ from CWD
+#   - Scans last 7 chronicles for R8-shape patterns
+#   - When matches found: emits summary block; when zero: silent
+#   - Always exit 0
+#
+# Override: SKIP_PRIOR_R8_FINDINGS=1
+
+set +e
+
+if [ "${SKIP_PRIOR_R8_FINDINGS:-0}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Locate chronicle dir
+CHRON_DIR=""
+if [ -d "chronicle" ]; then
+  CHRON_DIR="chronicle"
+elif [ -d "docs/chronicle" ]; then
+  CHRON_DIR="docs/chronicle"
+else
+  return 0 2>/dev/null || exit 0
+fi
+
+# Recent chronicles (last 7 by name-sort)
+RECENT_LIST=""
+if [ -d "$CHRON_DIR" ]; then
+  RECENT_LIST=$(ls -1 "$CHRON_DIR"/*.md 2>/dev/null | sort -r | head -7)
+fi
+
+if [ -z "$RECENT_LIST" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# R8 pattern set
+R8_PATTERN='R8|assertion-shape|claim-shape|claim without source|assert without validation|assert without verification'
+
+FINDINGS=""
+TOTAL_MATCHES=0
+FILES_WITH_MATCHES=0
+
+while IFS= read -r chron; do
+  [ -z "$chron" ] && continue
+  # -a treats binary as text; -c counts occurrences
+  matches=$(grep -a -c -iE "$R8_PATTERN" "$chron" 2>/dev/null || echo 0)
+  matches=${matches//[^0-9]/}
+  matches=${matches:-0}
+  if [ "$matches" -gt 0 ]; then
+    TOTAL_MATCHES=$((TOTAL_MATCHES + matches))
+    FILES_WITH_MATCHES=$((FILES_WITH_MATCHES + 1))
+    fname=$(basename "$chron")
+    FINDINGS="${FINDINGS}
+- ${fname} — ${matches} R8-related mentions"
+  fi
+done <<< "$RECENT_LIST"
+
+if [ "$TOTAL_MATCHES" -eq 0 ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+cat <<EOF
+
+### PRIOR R8 FINDINGS
+
+Recent sessions carry ${TOTAL_MATCHES} R8-related mentions across ${FILES_WITH_MATCHES} chronicles:
+${FINDINGS}
+
+R8 = agent asserts without validation. Umbrella: bassclef-upstream#559.
+
+Surface coverage now shipped:
+  1. UserPromptSubmit — bet 2026-07-01b
+  2. UserPromptExpansion — bet 2026-07-01e
+  3. PostToolUse re-priming — bet 2026-07-03a WU-2
+  4. Stop assertion-shape scan — bet 2026-07-03a WU-1
+  5. substrate-clarity-gate claim-shape scan — bet 2026-07-01e
+  6. Bash scrub claim-shape extension — bet 2026-07-03a WU-3
+  7. SessionStart prior findings (this fragment) — bet 2026-07-03a WU-4
+
+Cure: every operator-facing assertion carries My claim + Evidence + Why the evidence supports the claim (Toulmin's original vocabulary: claim + data + warrant).
+Read the source first; cite it inline (file path, ticket #, ADR ref).
+
+Override: SKIP_PRIOR_R8_FINDINGS=1
+EOF
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/80-hook-heartbeat-check.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# tier: lite
+# Hook heartbeat check — reads standards/hook-cadence.json, calls
+# heartbeat_check per named hook, emits BLOCKED banner for any hook
+# silent past its expected max_age.
+#
+# This is the mediator that closes the ADR-048 loop:
+#   WU-2: interface (lib/hook-heartbeat.sh + manifest + ADR)
+#   WU-3: producers (7 critical hooks call heartbeat_mark on entry)
+#   WU-4.5 (this file): consumer (session-start scanner reads state)
+#
+# Sourced by session-reflection.sh coordinator. Uses `return 0 2>/dev/null
+# || exit 0` per bassclef-upstream#992 fragment-coordinator-class cure +
+# test-sufficiency criterion 12 — works cleanly both sourced AND standalone.
+#
+# Rule: .claude/rules/substrate-as-system.md — the mediator closes the
+# runtime-cadence axis (per ADR-035 tenet).
+#
+# Anchors: @luminary michael-nygard (steady-state), @luminary
+# jerome-saltzer-and-michael-schroeder (complete mediation).
+
+MANIFEST="${BASSCLEF_DIR:-.}/standards/hook-cadence.json"
+
+# 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}")"
+HB_LIB=""
+for _c in "${_sd}/../../../lib/hook-heartbeat.sh" \
+          "${BASSCLEF_DIR:-.}/lib/hook-heartbeat.sh"; do
+  [ -f "$_c" ] && HB_LIB="$_c" && break
+done
+
+# Guards — silent-return if either half missing (adopter mid-sync).
+if [ ! -f "$MANIFEST" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+if [ -z "$HB_LIB" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# jq is required to parse the manifest.
+if ! command -v jq >/dev/null 2>&1; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# shellcheck source=/dev/null
+source "$HB_LIB"
+
+# Iterate critical hooks. Each entry has: name, max_age_seconds.
+STALE_ENTRIES=""
+
+while IFS=$'\t' read -r hook_name max_age rationale; do
+  [ -z "$hook_name" ] && continue
+
+  # heartbeat_check returns 1 or 2 for stale/missing. Under set -e in the
+  # parent coordinator that would abort the whole session-reflection chain.
+  # Wrap in if/then/else so non-zero returns are expected + captured.
+  if heartbeat_check "$hook_name" "$max_age"; then
+    rc=0
+  else
+    rc=$?
+  fi
+
+  case "$rc" in
+    0) ;;  # fresh; nothing to report
+    1)
+      STALE_ENTRIES="${STALE_ENTRIES}\n  - ${hook_name}: silent > ${max_age}s (${rationale})"
+      ;;
+    2)
+      STALE_ENTRIES="${STALE_ENTRIES}\n  - ${hook_name}: never fired (${rationale})"
+      ;;
+  esac
+done < <(jq -r '.critical_hooks[] | [.name, .max_age_seconds, .rationale] | @tsv' "$MANIFEST" 2>/dev/null)
+
+if [ -n "$STALE_ENTRIES" ]; then
+  NL=$'\n'
+  MSG="hook liveness — stale hook(s) detected:$(echo -e "$STALE_ENTRIES")${NL}${NL}Cadence per standards/hook-cadence.json. Discipline per ADR-048 + .claude/rules/substrate-as-system.md.${NL}${NL}Resolve — run each named hook manually (check .claude/settings.json for its trigger event) OR file a substrate-defect ticket if the hook cannot be fired."
+  if declare -f blocked_banner >/dev/null 2>&1; then
+    blocked_banner "$MSG"
+  else
+    printf "BLOCKED: %b\n" "$MSG" >&2
+  fi
+fi
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/80-workflow-staleness.sh

@@ -0,0 +1,141 @@
+# tier: lite
+# Workflow-staleness — surfaces silent bassclef workflow failures at
+# session-start so the agent doesn't operate against stale-substrate-state
+# state for days without notice.
+#
+# Triggered by 2026-04-27d operator screenshots that surfaced
+# bassclef-template-sync.yml failing for 6 days (last success
+# 2026-04-20; 2 consecutive failures since 2026-04-26 08:37) — only
+# discovered when operator pursued "why is hook drift this much?" The
+# silent-failure class needs upstream surfacing.
+#
+# Detection: queries `gh run list --workflow=<workflow>.yml --limit 1` for
+# the most recent run. If conclusion is failure AND age >24h, BLOCKED.
+# If failure <24h, WARN (transient flake possible). Otherwise silent.
+#
+# Scope: fires only in the bassclef repo itself (the workflow lives here).
+# Consumer repos rely on bassclef-hook-drift-blocker.md for propagated
+# drift detection — complementary, not redundant.
+#
+# Inherits from session-reflection.sh: blocked_banner, $BASSCLEF_DIR, trace_log.
+#
+# Env overrides:
+#   SKIP_WORKFLOW_STALENESS=1   — disable this session
+#   WORKFLOW_STALENESS_HOURS=N  — failure-age threshold (default 24)
+#
+# Issue: bassclef#NNN (filed at WU-9d ship — see docs/iteration-bets/2026-04-27d)
+
+# Skip via env
+if [ "${SKIP_WORKFLOW_STALENESS:-0}" = "1" ]; then
+  type trace_log >/dev/null 2>&1 && trace_log "80-workflow-staleness" "SKIP via SKIP_WORKFLOW_STALENESS=1"
+  return 0 2>/dev/null || exit 0
+fi
+
+# Only fire in bassclef repo (workflow lives here; consumer drift covered
+# by bassclef-hook-drift-blocker.md).
+ORIGIN_URL=$(git remote get-url origin 2>/dev/null || echo "")
+case "$ORIGIN_URL" in
+  *sunj-labs/bassclef*) ;;  # fire
+  *)
+    type trace_log >/dev/null 2>&1 && trace_log "80-workflow-staleness" "SKIP non-bassclef repo"
+    return 0 2>/dev/null || exit 0
+    ;;
+esac
+
+# gh CLI required; silent skip when absent or unauthenticated (cleanest
+# graceful-degradation path — consumer repos in CI / fresh clones may
+# lack gh; not their concern).
+if ! command -v gh >/dev/null 2>&1; then
+  type trace_log >/dev/null 2>&1 && trace_log "80-workflow-staleness" "SKIP gh not on PATH"
+  return 0 2>/dev/null || exit 0
+fi
+if ! gh auth status >/dev/null 2>&1; then
+  type trace_log >/dev/null 2>&1 && trace_log "80-workflow-staleness" "SKIP gh not authenticated"
+  return 0 2>/dev/null || exit 0
+fi
+
+# Workflows monitored. Add to this list as new sync-class workflows ship.
+# bassclef-template-sync.yml retired 2026-05-03 (PR #445, thin-pointer
+# default ships bassclef fetch via .bassclef-source.json — workflow
+# dispatch no longer needed).
+# bassclef-s3-publish.yml retired 2026-05-13 (bassclef#446 LR8.5 WU-2)
+# once every consumer migrated from .bassclef-url to .bassclef-source.json.
+# Hook is now dormant — no workflows to monitor — until a future
+# distribution workflow ships. Consider deleting in a follow-up if the
+# dormant state persists past 30 days.
+WORKFLOWS=()
+
+THRESHOLD_HOURS="${WORKFLOW_STALENESS_HOURS:-24}"
+THRESHOLD_SECS=$((THRESHOLD_HOURS * 3600))
+NOW_EPOCH=$(date +%s)
+
+ANY_BLOCKED=0
+ANY_WARN=0
+DETAILS=""
+
+for workflow in "${WORKFLOWS[@]}"; do
+  # Use timeout if available (Linux/coreutils); fall through to direct
+  # gh call on macOS without coreutils. gh's own client behavior
+  # bounds runtime in practice; this hook isn't on a hot critical path.
+  if command -v timeout >/dev/null 2>&1; then
+    RUN_JSON=$(timeout 5 gh run list --workflow="$workflow" --limit 1 \
+      --json status,conclusion,createdAt,databaseId,url 2>/dev/null || echo "[]")
+  else
+    RUN_JSON=$(gh run list --workflow="$workflow" --limit 1 \
+      --json status,conclusion,createdAt,databaseId,url 2>/dev/null || echo "[]")
+  fi
+
+  # Empty result → workflow doesn't exist in this repo or query failed
+  if [ "$RUN_JSON" = "[]" ] || [ -z "$RUN_JSON" ]; then
+    continue
+  fi
+
+  STATUS=$(echo "$RUN_JSON" | jq -r '.[0].status // ""' 2>/dev/null)
+  CONCLUSION=$(echo "$RUN_JSON" | jq -r '.[0].conclusion // ""' 2>/dev/null)
+  CREATED_AT=$(echo "$RUN_JSON" | jq -r '.[0].createdAt // ""' 2>/dev/null)
+  RUN_URL=$(echo "$RUN_JSON" | jq -r '.[0].url // ""' 2>/dev/null)
+
+  # Still running → silent (workflows take time)
+  if [ "$STATUS" != "completed" ]; then
+    continue
+  fi
+
+  # Success → silent (green path)
+  if [ "$CONCLUSION" = "success" ]; then
+    continue
+  fi
+
+  # Skipped or cancelled → silent (operator decision, not failure)
+  case "$CONCLUSION" in
+    skipped|cancelled|neutral) continue ;;
+  esac
+
+  # failure / timed_out / action_required / startup_failure → assess age
+  CREATED_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$CREATED_AT" +%s 2>/dev/null || \
+                  date -d "$CREATED_AT" +%s 2>/dev/null || echo "")
+  if [ -z "$CREATED_EPOCH" ]; then
+    continue  # date parse failed; don't fire false-positive
+  fi
+  AGE_SECS=$((NOW_EPOCH - CREATED_EPOCH))
+  AGE_HOURS=$((AGE_SECS / 3600))
+
+  if [ "$AGE_SECS" -ge "$THRESHOLD_SECS" ]; then
+    ANY_BLOCKED=1
+    DETAILS="${DETAILS}- ${workflow}: ${CONCLUSION} ${AGE_HOURS}h ago (${CREATED_AT}) — ${RUN_URL}\n"
+  else
+    ANY_WARN=1
+    DETAILS="${DETAILS}- ${workflow}: ${CONCLUSION} ${AGE_HOURS}h ago (within ${THRESHOLD_HOURS}h grace) — ${RUN_URL}\n"
+  fi
+done
+
+# Surface findings
+if [ "$ANY_BLOCKED" = "1" ]; then
+  MSG="workflow-staleness — bassclef workflow(s) failed >${THRESHOLD_HOURS}h ago without recovery:\n$(echo -e "$DETAILS")\nThis is the silent-failure class WU-9d retires. Read the failed run logs (gh run view <id>); root-cause + fix or operator-confirm deferral. Do not silently ignore."
+  blocked_banner "$MSG"
+elif [ "$ANY_WARN" = "1" ]; then
+  echo "### WORKFLOW-STALENESS — WARN (within ${THRESHOLD_HOURS}h grace)"
+  echo ""
+  echo -e "$DETAILS"
+  echo "Watch for next run. If it fails again, this becomes BLOCKED next session."
+  echo ""
+fi

package/dist/lite/.claude/hooks/session-reflection.d/81-hook-manifest-staleness.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# tier: lite
+# Hook manifest staleness — flags standards/hook-cadence.json when it
+# has not been updated since a new .claude/hooks/*.sh file landed.
+# Nygard "who monitors the monitor?" reflex: the backstop itself can
+# rot silently if the manifest drifts.
+#
+# Sourced by session-reflection.sh coordinator. Uses `return 0 2>/dev/null
+# || exit 0` per bassclef-upstream#992 + test-sufficiency criterion 12 —
+# works cleanly both sourced AND standalone. Silent-fail on missing
+# manifest or missing jq.
+
+MANIFEST="${BASSCLEF_DIR:-.}/standards/hook-cadence.json"
+HOOKS_DIR="${BASSCLEF_DIR:-.}/.claude/hooks"
+
+if [ ! -f "$MANIFEST" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+if [ ! -d "$HOOKS_DIR" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Read last_manifest_update (YYYY-MM-DD).
+LAST_UPDATE=$(jq -r '.last_manifest_update // ""' "$MANIFEST" 2>/dev/null)
+if [ -z "$LAST_UPDATE" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Convert to epoch. Portable macOS + Linux.
+LAST_UPDATE_EPOCH=$(date -j -f "%Y-%m-%d" "$LAST_UPDATE" +%s 2>/dev/null || \
+                    date -d "$LAST_UPDATE" +%s 2>/dev/null || \
+                    echo 0)
+
+if [ "$LAST_UPDATE_EPOCH" = "0" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Find any hook file newer than the manifest update date.
+NEW_HOOKS=""
+while IFS= read -r hook_path; do
+  [ -z "$hook_path" ] && continue
+  # GNU stat first (Linux default; `stat -f` on GNU is filesystem-info mode).
+  hook_mtime=$(stat -c %Y "$hook_path" 2>/dev/null || stat -f %m "$hook_path" 2>/dev/null || echo 0)
+  if [ "$hook_mtime" -gt "$LAST_UPDATE_EPOCH" ]; then
+    hook_base=$(basename "$hook_path" .sh)
+    if ! jq -e --arg name "$hook_base" '.critical_hooks[] | select(.name == $name)' "$MANIFEST" >/dev/null 2>&1; then
+      NEW_HOOKS="${NEW_HOOKS}\n  - ${hook_base}"
+    fi
+  fi
+done < <(find "$HOOKS_DIR" -maxdepth 1 -name '*.sh' -type f 2>/dev/null)
+
+if [ -n "$NEW_HOOKS" ]; then
+  NL=$'\n'
+  MSG="hook-cadence manifest staleness — new hook(s) landed since last_manifest_update=${LAST_UPDATE} but manifest does not list them:$(echo -e "$NEW_HOOKS")${NL}${NL}Resolve — decide per hook whether it is critical (add to standards/hook-cadence.json + bump last_manifest_update) OR non-critical (no action; the manifest tracks only critical hooks by design)."
+  if declare -f blocked_banner >/dev/null 2>&1; then
+    blocked_banner "$MSG"
+  else
+    printf "BLOCKED: %b\n" "$MSG" >&2
+  fi
+fi
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/90-release-backlog.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# tier: lite
+# install-class: project
+# 90-release-backlog.sh
+#
+# Per bet 2026-06-29c WU-1. Surfaces release pipeline state at SessionStart.
+# The release pipeline crosses two repos. Substrate ships from bassclef-upstream
+# to public bassclef via /release. The pipeline correctly refuses to run when a
+# prior release PR is open. Before this hook the refusal was silent because
+# /release wasn't being invoked — work could pile up for days unnoticed.
+#
+# Behavior:
+#   - Fires only when current repo is bassclef-upstream (remote contains
+#     "bassclef-upstream" in URL)
+#   - Silent on adopter repos (they don't run /release)
+#   - Silent when SKIP_RELEASE_BACKLOG=1
+#   - Silent when gh binary missing OR gh API call fails (network failure)
+#
+#   - Queries public bassclef for open release PRs (branch starts with "release-")
+#     - If any open release PR > 24h old → BLOCKED banner (operator must address)
+#     - If open release PR ≤ 24h → silent (still pending, normal)
+#
+#   - If no open release PR + commits-ahead > 0:
+#     - If active iteration goal in_flight → silent (mid-bet work; don't pressure release)
+#     - Else → INFO banner suggesting /release
+#
+# Resolution:
+#   1. Address the stuck release PR (close + re-release, or fix the failure)
+#   2. OR run /release --supersede to ship a fresh release
+#   3. OR explicitly defer: "skip release-backlog this session"
+#
+# Override (logged):
+#   SKIP_RELEASE_BACKLOG=1 <command>
+#
+# Closes bet 2026-06-29c WU-1.
+
+set -euo pipefail
+
+# Override path — silent, log via trace-helper if present
+if [ "${SKIP_RELEASE_BACKLOG:-0}" = "1" ]; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "release-backlog" "skipped via SKIP_RELEASE_BACKLOG=1" 2>/dev/null || true
+  fi
+  return 0 2>/dev/null || exit 0
+fi
+
+# Detect bassclef-upstream — silent on other repos
+REMOTE_URL=$(git config --get remote.origin.url 2>/dev/null || echo "")
+case "$REMOTE_URL" in
+  *bassclef-upstream*) ;;
+  *) return 0 2>/dev/null || exit 0 ;;
+esac
+
+# Need gh + jq
+command -v gh >/dev/null 2>&1 || { return 0 2>/dev/null || exit 0; }
+command -v jq >/dev/null 2>&1 || { return 0 2>/dev/null || exit 0; }
+
+# Query open release PRs on public bassclef
+RELEASE_PRS=$(gh pr list -R sunj-labs/bassclef --state open --json number,title,createdAt,headRefName 2>/dev/null || echo "[]")
+[ -z "$RELEASE_PRS" ] && RELEASE_PRS="[]"
+
+# Filter to release- branches
+STALE_PR=$(echo "$RELEASE_PRS" | jq -r '
+  .[] | select(.headRefName | startswith("release-")) |
+  "\(.number)|\(.createdAt)|\(.title)"
+' 2>/dev/null | head -1)
+
+if [ -n "$STALE_PR" ]; then
+  PR_NUM=$(echo "$STALE_PR" | cut -d'|' -f1)
+  PR_DATE=$(echo "$STALE_PR" | cut -d'|' -f2)
+  PR_TITLE=$(echo "$STALE_PR" | cut -d'|' -f3)
+
+  # Compute age in hours
+  PR_EPOCH=$(date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$PR_DATE" +%s 2>/dev/null || date -u -d "$PR_DATE" +%s 2>/dev/null || echo "")
+  NOW_EPOCH=$(date -u +%s)
+  if [ -n "$PR_EPOCH" ]; then
+    AGE_HOURS=$(( (NOW_EPOCH - PR_EPOCH) / 3600 ))
+    if [ "$AGE_HOURS" -gt 24 ]; then
+      cat <<EOF
+============================================
+🛑 BLOCKED — release pipeline stuck
+============================================
+
+Open release PR on public bassclef has been sitting $AGE_HOURS hours.
+
+PR #$PR_NUM: $PR_TITLE
+URL: https://github.com/sunj-labs/bassclef/pull/$PR_NUM
+
+Either address it or re-release fresh. Substrate work merged here
+since the PR opened is not reaching adopters until this clears.
+
+Three resolution paths:
+  1. Review + merge the PR if CI is green
+  2. Diagnose + fix the failure if CI is red
+  3. Close + run /release --supersede from current HEAD
+
+To skip this check for one session:
+  SKIP_RELEASE_BACKLOG=1
+============================================
+EOF
+      return 0 2>/dev/null || exit 0
+    fi
+  fi
+  # Fresh release PR — silent
+  return 0 2>/dev/null || exit 0
+fi
+
+# No open release PR. Check commits-ahead vs last shipped release.
+# Last release SHA lives in public bassclef-version.json
+# COMMITS_AHEAD_OVERRIDE is a test-only knob — when set, skip git rev-list + use the value
+if [ -n "${COMMITS_AHEAD_OVERRIDE:-}" ]; then
+  COMMITS_AHEAD="$COMMITS_AHEAD_OVERRIDE"
+else
+  LAST_SHA=$(gh api repos/sunj-labs/bassclef/contents/bassclef-version.json --jq '.content' 2>/dev/null | base64 -d 2>/dev/null | jq -r '.release_sha // empty' 2>/dev/null || echo "")
+  [ -z "$LAST_SHA" ] && { return 0 2>/dev/null || exit 0; }
+  COMMITS_AHEAD=$(git rev-list --count "$LAST_SHA"..HEAD 2>/dev/null || echo "0")
+fi
+
+if [ "$COMMITS_AHEAD" -gt 0 ]; then
+  # Check if active iteration goal — silent if mid-bet
+  # Read whereami in_flight_bet field (best-effort)
+  IN_FLIGHT=""
+  if [ "${NO_ACTIVE_BET_OVERRIDE:-0}" != "1" ] && [ -f "docs/whereami.md" ]; then
+    IN_FLIGHT=$(awk '/^in_flight_bet:/{flag=1; next} flag && /^[a-z_]+:/{exit} flag' docs/whereami.md 2>/dev/null | head -5)
+  fi
+  if [ -n "$IN_FLIGHT" ]; then
+    return 0 2>/dev/null || exit 0
+  fi
+  SHA_NOTE=""
+  if [ -n "${LAST_SHA:-}" ]; then
+    SHA_NOTE=" (sha $LAST_SHA)"
+  fi
+  cat <<EOF
+INFO — release pipeline is current but $COMMITS_AHEAD commits ahead of last
+shipped release$SHA_NOTE. No active iteration goal in flight. Consider
+running /release --supersede when ready to ship to adopters.
+EOF
+fi
+
+return 0 2>/dev/null || exit 0

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"