@thebassclef/lite 1.0.2 → 1.0.3

package/dist/lite/.claude/hooks/session-reflection.d/30-metrics-staleness.sh

@@ -0,0 +1,61 @@
+# tier: lite
+# Metrics-staleness check: version tags, iteration closeouts, metrics
+# dashboard, DORA freshness, changelog_doc_id. Surfaces as one BLOCKED
+# with all gaps enumerated.
+
+METRICS_SCRIPT="scripts/metrics.sh"
+if [ -f "$METRICS_SCRIPT" ] || [ -f "$BASSCLEF_DIR/$METRICS_SCRIPT" ]; then
+  METRICS_GAPS=""
+
+  # Version tags
+  TAG_COUNT=$(git tag 2>/dev/null | wc -l | tr -d '[:space:]')
+  if [ "$TAG_COUNT" -eq 0 ]; then
+    TOTAL_COMMITS=$(git log --oneline 2>/dev/null | wc -l | tr -d '[:space:]')
+    if [ "$TOTAL_COMMITS" -gt 20 ]; then
+      METRICS_GAPS="${METRICS_GAPS}  - NO VERSION TAGS: $TOTAL_COMMITS commits but zero tags. Create retroactive tags at major milestones.\n"
+    fi
+  fi
+
+  # Iteration goal closeouts
+  BET_DIR="docs/iteration-bets"
+  if [ -d "$BET_DIR" ]; then
+    TOTAL_BETS=$(ls -1 "$BET_DIR"/*.md 2>/dev/null | wc -l | tr -d '[:space:]')
+    CLOSED_BETS=$(grep -rl "## Closeout" "$BET_DIR"/*.md 2>/dev/null | wc -l | tr -d '[:space:]')
+    MISSING=$((TOTAL_BETS - CLOSED_BETS))
+    if [ "$MISSING" -gt 0 ]; then
+      METRICS_GAPS="${METRICS_GAPS}  - MISSING CLOSEOUTS: $MISSING of $TOTAL_BETS iteration goals have no closeout. Backfill from chronicles + git log.\n"
+    fi
+  fi
+
+  # Metrics dashboard
+  if [ ! -f "docs/metrics/latest.md" ]; then
+    ACTUAL_METRICS="$( [ -f "$METRICS_SCRIPT" ] && echo "$METRICS_SCRIPT" || echo "$BASSCLEF_DIR/$METRICS_SCRIPT" )"
+    METRICS_GAPS="${METRICS_GAPS}  - NO METRICS GENERATED: Run $ACTUAL_METRICS --all > docs/metrics/latest.md\n"
+  fi
+
+  # DORA staleness
+  ACTUAL_METRICS_PATH="$( [ -f "$METRICS_SCRIPT" ] && echo "$METRICS_SCRIPT" || echo "$BASSCLEF_DIR/$METRICS_SCRIPT" )"
+  if [ -f "docs/metrics/latest.md" ]; then
+    METRICS_MTIME=$(stat -f "%m" "docs/metrics/latest.md" 2>/dev/null || stat -c "%Y" "docs/metrics/latest.md" 2>/dev/null || echo "0")
+    COMMITS_SINCE=$(git log --after="@${METRICS_MTIME}" --oneline 2>/dev/null | wc -l | tr -d '[:space:]')
+    if [ "$COMMITS_SINCE" -gt 20 ]; then
+      METRICS_GAPS="${METRICS_GAPS}  - DORA METRICS STALE: ${COMMITS_SINCE} commits since last run. Run $ACTUAL_METRICS_PATH --all to refresh (includes lead time, deploy frequency, MTTR, change failure rate).\n"
+    fi
+  fi
+
+  # changelog_doc_id — bassclef-only check.
+  # The weekly changelog is bassclef's own release-notes push (per
+  # .claude/skills/release-notes/SKILL.md). Adopter repos typically
+  # do not publish a weekly community changelog. Skip the check when
+  # .bassclef-source.json is present (marker of an adopter repo that
+  # syncs from bassclef rather than being bassclef itself).
+  if [ ! -f ".bassclef-source.json" ] && [ -f "substrate.config.md" ]; then
+    if ! grep -q "changelog_doc_id:" substrate.config.md 2>/dev/null; then
+      METRICS_GAPS="${METRICS_GAPS}  - NO CHANGELOG DOC: Add changelog_doc_id to substrate.config.md for weekly changelog push.\n"
+    fi
+  fi
+
+  if [ -n "$METRICS_GAPS" ]; then
+    blocked_banner "$(printf 'metrics — resolve before other work:\n%b' "$METRICS_GAPS")"
+  fi
+fi

package/dist/lite/.claude/hooks/session-reflection.d/35-post-merge-whereami-self-heal.sh

@@ -0,0 +1,180 @@
+# tier: lite
+# Post-merge whereami self-heal (bassclef#505 Option A — LR7 WU-2).
+#
+# /session-end writes whereami BEFORE PR merges happen — correct, because
+# the chronicle + whereami land on the WU-N branch that's about to be
+# merged. After all PRs in the stack merge, whereami still says
+# "SHIPPED-PENDING-MERGE" on the active iteration_bet line. Operator
+# previously hand-edited each session to flip this. This hook closes
+# the gap automatically.
+#
+# Triggers: SessionStart (via session-reflection.d/* discovery).
+# Mutates: docs/whereami.md (Shape B sed-in-place) OR docs/whereami.json
+#         (Shape A via state_whereami_set accessor).
+# Detects: "SHIPPED-PENDING-MERGE" substring on the active iteration_bet
+#         line/field.
+# Verifies: no open PRs match the goal slug AND ≥1 merged PR matches.
+# Resolves: replace "SHIPPED-PENDING-MERGE" → "CLOSED+MERGED YYYY-MM-DD".
+# Skips: gh unavailable, slug unparseable, mixed-state PRs (some open).
+#
+# Override: SKIP_WHEREAMI_SELFHEAL=1 disables the hook for the session.
+# Override: WHEREAMI_SELFHEAL_DRY_RUN=1 emits the suggestion without mutating.
+
+if [ "${SKIP_WHEREAMI_SELFHEAL:-0}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+WHEREAMI_MD="docs/whereami.md"
+WHEREAMI_JSON="docs/whereami.json"
+
+# Resolve goal slug + status line. Two shapes:
+#  - Shape A: docs/whereami.json with .iteration.bet (or top-level iteration_bet) string field
+#  - Shape B: docs/whereami.md with line `iteration_bet: <slug> (STATUS — narrative...)`
+SHAPE=""
+ACTIVE_LINE=""
+ACTIVE_SLUG=""
+
+if [ -f "$WHEREAMI_JSON" ]; then
+  SHAPE="A"
+  if command -v jq >/dev/null 2>&1; then
+    ACTIVE_LINE="$(jq -r '.iteration.bet // .iteration_bet // empty' "$WHEREAMI_JSON" 2>/dev/null || true)"
+  fi
+elif [ -f "$WHEREAMI_MD" ]; then
+  SHAPE="B"
+  # Find the FIRST line starting `iteration_bet:` (active bet, not previous_iteration_bet:).
+  ACTIVE_LINE="$(grep -m1 -E '^iteration_bet:' "$WHEREAMI_MD" 2>/dev/null || true)"
+else
+  # No whereami at all; nothing to self-heal.
+  return 0 2>/dev/null || exit 0
+fi
+
+if [ -z "$ACTIVE_LINE" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Quick exit: no PENDING-MERGE marker = nothing to flip.
+case "$ACTIVE_LINE" in
+  *"SHIPPED-PENDING-MERGE"*) ;;
+  *) return 0 2>/dev/null || exit 0 ;;
+esac
+
+# Extract goal slug. Format: `iteration_bet: <slug> (...)` (Shape B) or
+# the JSON field value directly (Shape A). Slug is the first
+# whitespace-delimited token after `iteration_bet: ` in Shape B, OR the
+# first whitespace-delimited token in Shape A's value.
+if [ "$SHAPE" = "B" ]; then
+  ACTIVE_SLUG="$(echo "$ACTIVE_LINE" | sed -E 's/^iteration_bet:[[:space:]]+//' | awk '{print $1}')"
+else
+  ACTIVE_SLUG="$(echo "$ACTIVE_LINE" | awk '{print $1}')"
+fi
+
+if [ -z "$ACTIVE_SLUG" ]; then
+  echo "post-merge whereami self-heal: skipped — could not parse goal slug from active iteration_bet line" >&2
+  return 0 2>/dev/null || exit 0
+fi
+
+# gh unavailable → soft-skip.
+if ! command -v gh >/dev/null 2>&1; then
+  echo "post-merge whereami self-heal: skipped — gh not available; manual whereami refresh recommended" >&2
+  return 0 2>/dev/null || exit 0
+fi
+
+# Query merged + open PRs that mention the slug in title OR body. Bassclef's
+# PR title convention is `<type>(bassclef#NNN): ...` — the slug appears in
+# bodies (iteration-goal doc paths, chronicle citations) more than titles.
+# Defaulting to title+body search (no `in:title` modifier) catches both
+# conventions; downstream "no merged matches" branch still covers the case
+# where the slug lives nowhere greppable in PR metadata.
+# Caught at LR7 closeout 2026-05-05: `in:title` filter never matched because
+# bassclef PR titles cite bassclef#NNN not the goal slug — defect surfaced
+# only at first live eat-our-own-dogfood run.
+MERGED_COUNT=$(gh pr list --state merged --search "$ACTIVE_SLUG" --json number --limit 30 2>/dev/null \
+               | jq 'length' 2>/dev/null || echo 0)
+OPEN_COUNT=$(gh pr list --state open --search "$ACTIVE_SLUG" --json number --limit 30 2>/dev/null \
+             | jq 'length' 2>/dev/null || echo 0)
+
+# Also check for the bassclef-NNN-stack-N branch shape (PRs may not include
+# the slug verbatim in titles — branch names + WU citations do). Use the
+# slug's date + LR-N prefix as a coarser match for safety. Skip this fallback
+# if jq broke above.
+if [ -z "$MERGED_COUNT" ] || [ "$MERGED_COUNT" = "null" ]; then MERGED_COUNT=0; fi
+if [ -z "$OPEN_COUNT" ] || [ "$OPEN_COUNT" = "null" ]; then OPEN_COUNT=0; fi
+
+# Decision matrix:
+#  - OPEN > 0: bet partially shipped; do not flip; surface informational note
+#  - MERGED ≥ 1 AND OPEN = 0: safe to flip
+#  - MERGED = 0 AND OPEN = 0: title-substring match found nothing; skip with note (slug may be
+#                              non-bassclef or PRs cite by issue number not slug)
+if [ "$OPEN_COUNT" -gt 0 ]; then
+  echo "post-merge whereami self-heal: detected SHIPPED-PENDING-MERGE on $ACTIVE_SLUG, but $OPEN_COUNT PR(s) still open. Skipping flip; resolve PRs first."
+  return 0 2>/dev/null || exit 0
+fi
+
+if [ "$MERGED_COUNT" -lt 1 ]; then
+  echo "post-merge whereami self-heal: skipped for $ACTIVE_SLUG — no merged PRs match by title substring; manual whereami refresh recommended"
+  return 0 2>/dev/null || exit 0
+fi
+
+# Safe to flip. Compute today's date (UTC) for the marker.
+TODAY="$(date -u +%Y-%m-%d)"
+NEW_STATUS="CLOSED+MERGED $TODAY"
+
+# Dry-run mode: emit suggestion without mutating.
+if [ "${WHEREAMI_SELFHEAL_DRY_RUN:-0}" = "1" ]; then
+  echo "post-merge whereami self-heal (DRY-RUN): would flip $ACTIVE_SLUG SHIPPED-PENDING-MERGE → $NEW_STATUS"
+  echo "  shape=$SHAPE; merged=$MERGED_COUNT; open=$OPEN_COUNT"
+  echo "  override: WHEREAMI_SELFHEAL_DRY_RUN=0 to apply, OR SKIP_WHEREAMI_SELFHEAL=1 to disable"
+  return 0 2>/dev/null || exit 0
+fi
+
+# Apply the mutation.
+APPLIED=0
+if [ "$SHAPE" = "A" ] && [ -f "lib/state.sh" ]; then
+  # Use the accessor — it handles atomic write + schema validation.
+  # shellcheck disable=SC1091
+  source lib/state.sh
+  # Replace the substring within the iteration.bet field. We have to read +
+  # mutate + write because state_whereami_set takes a full value.
+  CURRENT_VALUE="$(echo "$ACTIVE_LINE")"
+  # Eat trailing YYYY-MM-DD if present so we don't double up the date.
+  # Pattern: "SHIPPED-PENDING-MERGE 2026-05-05" → "CLOSED+MERGED 2026-05-05"
+  # rather than "CLOSED+MERGED 2026-05-05 2026-05-05".
+  NEW_VALUE="$(echo "$CURRENT_VALUE" | sed -E "s/SHIPPED-PENDING-MERGE[[:space:]]+[0-9]{4}-[0-9]{2}-[0-9]{2}/$NEW_STATUS/" | sed "s/SHIPPED-PENDING-MERGE/$NEW_STATUS/")"
+  # Try .iteration.bet first; fall back to top-level iteration_bet.
+  if state_whereami_set "iteration.bet" "$NEW_VALUE" 2>/dev/null; then
+    APPLIED=1
+  elif state_whereami_set "iteration_bet" "$NEW_VALUE" 2>/dev/null; then
+    APPLIED=1
+  fi
+elif [ "$SHAPE" = "B" ]; then
+  # Shape B: in-place sed on the FIRST iteration_bet: line only. Match
+  # the SHIPPED-PENDING-MERGE substring on that line specifically.
+  # Use awk to limit the change to the first matching line — sed's `0,/pat/`
+  # is GNU-only. BSD-portable awk path:
+  TMP="$(mktemp)"
+  awk -v new="$NEW_STATUS" '
+    /^iteration_bet:/ && !done {
+      # Eat trailing YYYY-MM-DD if present so we do not double up the date.
+      # Pattern: "SHIPPED-PENDING-MERGE 2026-05-05" → "CLOSED+MERGED 2026-05-05"
+      # rather than "CLOSED+MERGED 2026-05-05 2026-05-05".
+      if (sub(/SHIPPED-PENDING-MERGE[ \t]+[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/, new) == 0) {
+        sub(/SHIPPED-PENDING-MERGE/, new)
+      }
+      done = 1
+    }
+    { print }
+  ' "$WHEREAMI_MD" > "$TMP"
+  if [ -s "$TMP" ] && ! cmp -s "$TMP" "$WHEREAMI_MD"; then
+    mv "$TMP" "$WHEREAMI_MD"
+    APPLIED=1
+  else
+    rm -f "$TMP"
+  fi
+fi
+
+if [ "$APPLIED" = "1" ]; then
+  echo "post-merge whereami self-heal: flipped $ACTIVE_SLUG SHIPPED-PENDING-MERGE → $NEW_STATUS (shape=$SHAPE; $MERGED_COUNT PR(s) merged, 0 open)"
+  echo "  Commit when ready: git add docs/whereami.{md,json} && git commit -m 'chore: post-merge whereami self-heal for $ACTIVE_SLUG'"
+else
+  echo "post-merge whereami self-heal: detected $ACTIVE_SLUG ready to flip but mutation did not apply (shape=$SHAPE)"
+fi

package/dist/lite/.claude/hooks/session-reflection.d/36-whereami-size-check.sh

@@ -0,0 +1,117 @@
+# tier: lite
+# Whereami size check + auto-rotate (bassclef-upstream#1284).
+#
+# docs/whereami.md grows past Claude Code's Read tool 256KB ceiling within
+# days on active bassclef sessions (~110 turns per session; 3-5 recap blocks
+# per day). When the file exceeds 256KB, session-start Step 0.4 mandatory
+# read fails per .claude/skills/longrun/SKILL.md. This hook surfaces the
+# risk + auto-rotates via scripts/rotate-whereami.py.
+#
+# Thresholds:
+#   < 200KB (204800 bytes)      — silent (healthy)
+#   200-250KB (up to 256000)    — INFORM approaching (rotation due soon)
+#   > 250KB (256000 bytes)      — auto-rotate via `rotate-whereami.py --days 3`
+#                                 + INFORM before/after size
+#                                 Skips rotation if whereami is uncommitted
+#                                 (operator may be mid-edit).
+#
+# Fires: SessionStart via session-reflection.d/* discovery.
+# Mutates: docs/whereami.md + docs/whereami-archive/YYYY-MM.md (when rotating).
+# Depends: scripts/rotate-whereami.py + python3. Silent skip if either missing.
+#
+# Override:
+#   SKIP_WHEREAMI_SIZE_CHECK=1     disable hook for the session
+#   WHEREAMI_PATH=<path>           override whereami location (test hook)
+#   ROTATE_SCRIPT=<path>           override rotate-whereami.py path (test hook)
+#   ARCHIVE_DIR=<path>             override archive dir (test hook)
+#   WHEREAMI_MODIFIED=1            treat whereami as uncommitted (test hook)
+#
+# Anchor luminaries:
+#   michael-nygard — fail-safe defaults + stability pattern
+#   kent-beck — Tier 0 strict TDD
+#   michael-feathers — characterization of existing rotate-whereami.py
+#   jerome-saltzer-and-michael-schroeder — complete mediation per session
+#   donald-norman — INFORM line surfaces state change
+
+if [ "${SKIP_WHEREAMI_SIZE_CHECK:-0}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+WHEREAMI_PATH="${WHEREAMI_PATH:-docs/whereami.md}"
+ROTATE_SCRIPT="${ROTATE_SCRIPT:-scripts/rotate-whereami.py}"
+ARCHIVE_DIR="${ARCHIVE_DIR:-docs/whereami-archive}"
+
+# Skip silently if whereami doesn't exist (fresh repo case)
+if [ ! -f "$WHEREAMI_PATH" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Size check via wc -c (portable across BSD + GNU; avoids stat -f/-c ambiguity
+# where BSD stat -f=file-format vs GNU stat -f=filesystem-info — Linux CI ran
+# stat -f %z and got filesystem block info, breaking numeric comparison).
+SIZE=$(wc -c <"$WHEREAMI_PATH" | tr -d ' ')
+
+THRESHOLD_APPROACH=204800   # 200KB — approaching ceiling
+THRESHOLD_ROTATE=256000     # 250KB — auto-rotate now
+
+# Below approaching threshold — silent
+if [ "$SIZE" -lt "$THRESHOLD_APPROACH" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Between approaching + rotate — INFORM only
+if [ "$SIZE" -lt "$THRESHOLD_ROTATE" ]; then
+  echo "[whereami-size] approaching Read tool ceiling — file $SIZE bytes; rotation due soon (see bassclef-upstream#1284)" >&2
+  return 0 2>/dev/null || exit 0
+fi
+
+# Above rotate threshold — check for uncommitted changes first
+# Only check `git diff` when file is tracked; untracked paths (test fixtures,
+# fresh repos) return 0/0 exit codes we cannot distinguish, so we default to
+# NOT modified for those cases.
+IS_MODIFIED=0
+if [ "${WHEREAMI_MODIFIED:-0}" = "1" ]; then
+  IS_MODIFIED=1
+elif command -v git >/dev/null 2>&1; then
+  # git ls-files --error-unmatch returns 0 iff path is tracked
+  if git ls-files --error-unmatch "$WHEREAMI_PATH" >/dev/null 2>&1; then
+    if ! git diff --quiet "$WHEREAMI_PATH" 2>/dev/null; then
+      IS_MODIFIED=1
+    fi
+  fi
+fi
+
+if [ "$IS_MODIFIED" = "1" ]; then
+  echo "[whereami-size] file $SIZE bytes past ceiling BUT modified — skipping auto-rotate (commit or stash first)" >&2
+  return 0 2>/dev/null || exit 0
+fi
+
+# Skip if rotate script missing (adopter case)
+if [ ! -f "$ROTATE_SCRIPT" ]; then
+  echo "[whereami-size] file $SIZE bytes past ceiling but $ROTATE_SCRIPT not found — skipping (adopter path)" >&2
+  return 0 2>/dev/null || exit 0
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "[whereami-size] file $SIZE bytes past ceiling but python3 not found — skipping" >&2
+  return 0 2>/dev/null || exit 0
+fi
+
+# Fire rotation with tighter --days 3 default (7-day window overshoots per
+# 2026-08-19 diagnostic in bassclef-upstream#1284).
+SIZE_BEFORE="$SIZE"
+python3 "$ROTATE_SCRIPT" --days 3 --file "$WHEREAMI_PATH" --archive-dir "$ARCHIVE_DIR" >/dev/null 2>&1 || {
+  echo "[whereami-size] auto-rotate FAILED — file $SIZE bytes past ceiling; run manually: python3 $ROTATE_SCRIPT --days 3" >&2
+  return 0 2>/dev/null || exit 0
+}
+
+SIZE_AFTER=$(wc -c <"$WHEREAMI_PATH" | tr -d ' ')
+
+echo "[whereami-size] rotated — before $SIZE_BEFORE bytes; after $SIZE_AFTER bytes; archive at $ARCHIVE_DIR" >&2
+
+# Follow-on inform when rotation left file still past ceiling (dense session week)
+if [ "$SIZE_AFTER" -ge "$THRESHOLD_ROTATE" ]; then
+  echo "[whereami-size] file still past ceiling after 3-day rotation — consider byte-cap strategy per bassclef-upstream#1284" >&2
+fi
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/40-gate-compliance.sh

@@ -0,0 +1,108 @@
+# tier: lite
+# Gate-compliance check: if /verify or /temperance fire below 80% across
+# the last 5 chronicles, flag as BLOCKED. Uses extract-session-telemetry.sh.
+#
+# Spine v0 note (WU-6): this hook reads gate-compliance state INDIRECTLY
+# via scripts/extract-session-telemetry.sh, which is itself accessor-based
+# post-WU-5. So the hook conforms to accessor-library-discipline.md by
+# composition: telemetry script → lib/state.sh accessors → JSON state.
+# Direct lib/state.sh integration here is deferred to spine v1 (would
+# duplicate the rate-calculation logic that lives in the telemetry script).
+#
+# When the signal is STUCK (same rate across ≥3 consecutive sessions),
+# the BLOCKED banner includes mechanism paths so the agent reads the
+# hook + telemetry script rather than trying harder on the surface.
+# See .claude/rules/stuck-signal-diagnostic.md.
+
+TELEMETRY_SCRIPT="scripts/extract-session-telemetry.sh"
+TELEMETRY_PATH=""
+if [ -f "$TELEMETRY_SCRIPT" ]; then
+  TELEMETRY_PATH="$TELEMETRY_SCRIPT"
+elif [ -f "$BASSCLEF_DIR/$TELEMETRY_SCRIPT" ]; then
+  TELEMETRY_PATH="$BASSCLEF_DIR/$TELEMETRY_SCRIPT"
+fi
+
+# History surface used to detect "stuck" — the last 3 rate values for
+# each gate. Lives under state/markers/compliance-history/ so it
+# survives sandbox teardown (per mobile-ephemeral-session.md markers).
+HISTORY_DIR="state/markers/compliance-history"
+mkdir -p "$HISTORY_DIR" 2>/dev/null || true
+
+# Given a gate name and current rate, update the rolling history file
+# and echo "stuck" if the last 3 entries (including current) are identical.
+check_stuck() {
+  local gate="$1"
+  local rate="$2"
+  local hist_file="$HISTORY_DIR/${gate}.history"
+
+  # Append current rate; keep last 3 entries
+  echo "$rate" >> "$hist_file"
+  local tmp
+  tmp=$(tail -3 "$hist_file")
+  echo "$tmp" > "$hist_file"
+
+  # If we have 3 entries and all match, signal is stuck
+  local count
+  count=$(wc -l < "$hist_file" | tr -d ' ')
+  if [ "$count" = "3" ]; then
+    local uniq
+    uniq=$(sort -u "$hist_file" | wc -l | tr -d ' ')
+    if [ "$uniq" = "1" ]; then
+      echo "stuck"
+      return
+    fi
+  fi
+  echo "moving"
+}
+
+# Build the mechanism-paths block appended to BLOCKED banner when stuck.
+mechanism_block() {
+  local telemetry="$1"
+  cat <<MECH
+
+STUCK SIGNAL — rate unchanged across ≥3 sessions. Per
+.claude/rules/stuck-signal-diagnostic.md, stop retrying the surface
+and read the mechanism. The counter's update path lives in:
+
+  - ${telemetry} (rate calculation — how the % is computed)
+  - .claude/hooks/session-reflection.d/40-gate-compliance.sh (banner emitter + history surface)
+  - state/markers/compliance-history/ (rolling rate file this hook reads)
+  - chronicle/ frontmatter gates_fired / gate-evidence block (what the telemetry script consumes)
+
+Read those files. Trace where the gate marker is written → where the
+telemetry script reads it → why the rate isn't moving despite work
+being done. If you find a substrate defect, fire /promote with the
+substrate-defect classifier (see blocked-items.md §"When resolution
+reveals a substrate defect").
+MECH
+}
+
+if [ -n "$TELEMETRY_PATH" ]; then
+  GATE_OUTPUT=$(bash "$TELEMETRY_PATH" --recent 5 --gates 2>/dev/null || true)
+  if [ -n "$GATE_OUTPUT" ]; then
+    VERIFY_LINE=$(echo "$GATE_OUTPUT" | grep -i "Verify" | head -1 || true)
+    if [ -n "$VERIFY_LINE" ]; then
+      VERIFY_RATE=$(echo "$VERIFY_LINE" | grep -oE '[0-9]+%' | tr -d '%' || echo "")
+      if [ -n "$VERIFY_RATE" ] && [ "$VERIFY_RATE" -lt 80 ] 2>/dev/null; then
+        STUCK=$(check_stuck "verify" "$VERIFY_RATE")
+        if [ "$STUCK" = "stuck" ]; then
+          blocked_banner "verify-compliance — verify gate fired ${VERIFY_RATE}% in last 5 sessions (threshold: 80%). $(mechanism_block "$TELEMETRY_PATH")"
+        else
+          blocked_banner "verify-compliance — verify gate fired ${VERIFY_RATE}% in last 5 sessions (threshold: 80%). Run /verify after each task this session."
+        fi
+      fi
+    fi
+    TEMP_LINE=$(echo "$GATE_OUTPUT" | grep -i "Temperance" | head -1 || true)
+    if [ -n "$TEMP_LINE" ]; then
+      TEMP_RATE=$(echo "$TEMP_LINE" | grep -oE '[0-9]+%' | tr -d '%' || echo "")
+      if [ -n "$TEMP_RATE" ] && [ "$TEMP_RATE" -lt 80 ] 2>/dev/null; then
+        STUCK=$(check_stuck "temperance" "$TEMP_RATE")
+        if [ "$STUCK" = "stuck" ]; then
+          blocked_banner "temperance-compliance — temperance gate fired ${TEMP_RATE}% in last 5 sessions (threshold: 80%). $(mechanism_block "$TELEMETRY_PATH")"
+        else
+          blocked_banner "temperance-compliance — temperance gate fired ${TEMP_RATE}% in last 5 sessions (threshold: 80%). Run /temperance before first edit."
+        fi
+      fi
+    fi
+  fi
+fi

package/dist/lite/.claude/hooks/session-reflection.d/45-auto-sync-status.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# tier: lite
+# 45-auto-sync-status.sh — Always-on version status line
+#
+# V3 refactor (bassclef bet 2026-06-15b — Phase B Trust Busters):
+# - Always-on session-start version-status line replacing the earned-banner
+#   Layer 2 surface (per operator decision — always-on subsumes earned)
+# - Critical-fix entries from adopter-notable-releases.json fire warnings
+#   BYPASSING age threshold (no 30-day gate)
+# - Backward-compat: silent when .bassclef-source.json absent (bassclef's
+#   own repo) or when V1 installed_sha/installed_at fields not yet populated
+#
+# Behavior:
+# - When .bassclef-source.json present + has installed_sha + installed_at:
+#     emit "### bassclef-sync — version status" header + one-line status
+#     showing installed SHA + days-behind + auto-sync state
+# - When critical-fix entries published_at > installed_at:
+#     emit additional warning section listing the entries
+#
+# Override: SKIP_AUTO_SYNC_STATUS=1 in env.
+#
+# Per bassclef#939 — adopter sync opt-in default.
+# Per bet 2026-06-15b V3 — Layer 2 collapse to always-on.
+
+[ "${SKIP_AUTO_SYNC_STATUS:-0}" = "1" ] && { return 0 2>/dev/null || exit 0; }
+
+CWD="${CLAUDE_PROJECT_DIR:-$PWD}"
+SOURCE_FILE="$CWD/.bassclef-source.json"
+ADOPTER_NOTABLE_FILE="$CWD/state/adopter-notable-releases.json"
+
+# Silent if no .bassclef-source.json (bassclef's own repo path).
+[ -f "$SOURCE_FILE" ] || { return 0 2>/dev/null || exit 0; }
+
+# Parse V1 fields. Silent if installed_sha + installed_at not yet populated
+# (adopter hasn't migrated to V1 schema).
+INSTALLED_SHA=$(jq -r '.installed_sha // empty' "$SOURCE_FILE" 2>/dev/null)
+INSTALLED_AT=$(jq -r '.installed_at // empty' "$SOURCE_FILE" 2>/dev/null)
+AUTO_SYNC=$(jq -r '.auto_sync // false' "$SOURCE_FILE" 2>/dev/null)
+
+if [ -z "$INSTALLED_SHA" ] || [ -z "$INSTALLED_AT" ]; then
+  # Pre-V1 adopter — silent to avoid noise during gradual schema rollout.
+  return 0 2>/dev/null || exit 0
+fi
+
+# Compute days-behind from installed_at. Cross-platform date parsing.
+NOW_EPOCH=$(date +%s)
+INSTALLED_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$INSTALLED_AT" +%s 2>/dev/null \
+  || date -d "$INSTALLED_AT" +%s 2>/dev/null || echo "$NOW_EPOCH")
+AGE_SECONDS=$((NOW_EPOCH - INSTALLED_EPOCH))
+DAYS_BEHIND=$((AGE_SECONDS / 86400))
+
+# Auto-sync state surfacing.
+if [ "$AUTO_SYNC" = "true" ]; then
+  AUTO_LINE="Auto-update is ON — next session-start fetches latest."
+else
+  AUTO_LINE="Auto-update is OFF — say \"enable auto-sync\" to flip the default."
+fi
+
+# Days-behind phrasing.
+if [ "$DAYS_BEHIND" -eq 0 ]; then
+  AGE_PHRASE="today"
+elif [ "$DAYS_BEHIND" -eq 1 ]; then
+  AGE_PHRASE="1 day ago"
+else
+  AGE_PHRASE="$DAYS_BEHIND days ago"
+fi
+
+# Compose status line + emit. Always fires when reaching this point.
+cat <<HEADER
+
+### bassclef-sync — version status
+
+Installed: $INSTALLED_SHA ($AGE_PHRASE)
+$AUTO_LINE
+HEADER
+
+# Check for critical-fix entries published_at > installed_at.
+# Critical-fixes BYPASS the age threshold (no 30-day gate).
+if [ -f "$ADOPTER_NOTABLE_FILE" ]; then
+  CRITICAL_COUNT=$(jq --arg cutoff "$INSTALLED_AT" \
+    '[.releases[]? | select(.published_at > $cutoff) | select(.kind == "critical_fix")] | length' \
+    "$ADOPTER_NOTABLE_FILE" 2>/dev/null || echo 0)
+  if [ "$CRITICAL_COUNT" -gt 0 ]; then
+    CRITICAL_SUMMARY=$(jq --arg cutoff "$INSTALLED_AT" -r \
+      '[.releases[]? | select(.published_at > $cutoff) | select(.kind == "critical_fix") | "   • " + .summary] | join("\n")' \
+      "$ADOPTER_NOTABLE_FILE" 2>/dev/null || echo "")
+    cat <<CRITICAL
+
+⚠ $CRITICAL_COUNT critical-fix update(s) released since your install:
+$CRITICAL_SUMMARY
+
+Pull now with:
+
+    bash .claude/hooks/bassclef-sync.sh
+CRITICAL
+  fi
+fi
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/50-evolution-issues.sh

@@ -0,0 +1,44 @@
+# tier: lite
+# Bassclef-evolution promotion scan: in bassclef sessions only, list
+# open bassclef-evolution issues in bassclef and known consumer repos.
+#
+# Consumer list is read from substrate.config.md field
+# `bassclef_evolution_child_repos` (comma-separated owner/name list).
+# Falls back to sunj-labs/poa only when the field is absent — safe
+# default for old consumer checkouts predating the config field.
+#
+# Keep the field in sync with .github/workflows/bassclef-template-sync.yml
+# matrix.consumer list.
+
+REPO_NAME_CHECK=$(gh repo view --json name -q '.name' 2>/dev/null || echo "")
+if [ "$REPO_NAME_CHECK" = "platform-docs" ] || [ "$REPO_NAME_CHECK" = "bassclef" ]; then
+  CHILD_REPOS_RAW=$(grep "^bassclef_evolution_child_repos:" substrate.config.md 2>/dev/null | sed 's/^bassclef_evolution_child_repos:[[:space:]]*//' || echo "")
+  if [ -n "$CHILD_REPOS_RAW" ]; then
+    CHILD_REPOS=$(echo "$CHILD_REPOS_RAW" | tr ',' '\n' | tr -d ' ' | grep -v '^$')
+  else
+    CHILD_REPOS="sunj-labs/poa"
+  fi
+
+  ALL_EVOLUTION=""
+
+  BASSCLEF_ISSUES=$(gh issue list -R "sunj-labs/bassclef" --label "bassclef-evolution" --state open --limit 10 2>/dev/null)
+  if [ -n "$BASSCLEF_ISSUES" ]; then
+    ALL_EVOLUTION="${ALL_EVOLUTION}\n  From bassclef:\n${BASSCLEF_ISSUES}\n"
+  fi
+
+  for CHILD in $CHILD_REPOS; do
+    CHILD_ISSUES=$(gh issue list -R "$CHILD" --label "bassclef-evolution" --state open --limit 10 2>/dev/null)
+    if [ -n "$CHILD_ISSUES" ]; then
+      ALL_EVOLUTION="${ALL_EVOLUTION}\n  From ${CHILD}:\n${CHILD_ISSUES}\n"
+    fi
+  done
+
+  if [ -n "$ALL_EVOLUTION" ]; then
+    echo "### BASSCLEF EVOLUTION — PENDING PROMOTIONS"
+    echo ""
+    echo -e "$ALL_EVOLUTION"
+    echo "Review and resolve these. Child repo proposals need ingestion"
+    echo "into bassclef if globally applicable."
+    echo ""
+  fi
+fi