@thebassclef/lite 1.0.1 → 1.0.3

package/dist/lite/.claude/hooks/session-reflection.d/15-substrate-config-validate.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# tier: lite
+# 15-substrate-config-validate.sh
+#
+# bassclef#591 — substrate.config.md presence + basic-coherence check.
+#
+# Today: thin presence check + required-section presence verification.
+# Full JSON Schema validation deferred per bassclef#643 (migration of
+# substrate.config.md to YAML frontmatter; schema already exists at
+# standards/state-spine/schemas/substrate-config.schema.json).
+#
+# Fires at session-start as part of session-reflection.d/* chain.
+# Surfaces BLOCKED if substrate.config.md is missing OR missing key
+# sections that downstream hooks/skills depend on.
+#
+# Override: SKIP_SUBSTRATE_CONFIG_VALIDATE=1
+#
+# Per bassclef#639 — operates ONLY on $CWD; no cross-repo execution.
+
+set -u
+
+if [ "${SKIP_SUBSTRATE_CONFIG_VALIDATE:-0}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Some sessions provide CWD via stdin JSON; fall back to $PWD if not.
+CWD="${CWD:-$PWD}"
+CONFIG_FILE="$CWD/substrate.config.md"
+
+# Not all repos have substrate.config.md (fresh consumer pre-onboarding).
+# Skip silently if absent; bassclef-sync's onboard path prompts when needed.
+if [ ! -f "$CONFIG_FILE" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Required sections (header style: `## SectionName`).
+# Downstream hooks (session-reflection.sh + others) grep for these section
+# fields; absence is observable behavior, not crash.
+REQUIRED_SECTIONS="Configuration"
+MISSING=""
+
+for section in $REQUIRED_SECTIONS; do
+  if ! grep -q "^## $section" "$CONFIG_FILE" 2>/dev/null; then
+    MISSING="$MISSING $section"
+  fi
+done
+
+# Required fields by line-prefix (legacy markdown style — pre-YAML-frontmatter).
+REQUIRED_FIELDS="gating execution_mode"
+for field in $REQUIRED_FIELDS; do
+  if ! grep -q "^$field:" "$CONFIG_FILE" 2>/dev/null; then
+    MISSING="$MISSING $field:"
+  fi
+done
+
+if [ -n "$MISSING" ]; then
+  cat >&2 <<EOF
+
+================================================================
+⚠️  SUBSTRATE.CONFIG DRIFT — INFORM (Class B cure per #1157)
+================================================================
+
+File:    $CONFIG_FILE
+Missing:$MISSING
+
+substrate.config.md is the single source of truth for external
+resource references (per standards/substrate-config-schema.md).
+Missing sections/fields above are expected by downstream hooks.
+Session continues — this WARN does not block SessionStart.
+
+Resolution (do at your convenience):
+  - If field/section was intentionally removed, restore it (set to a
+    placeholder value if not yet decided)
+  - If file is being bootstrapped fresh, see presence/install/
+    for the substrate-config.md template
+
+Override (logged):  SKIP_SUBSTRATE_CONFIG_VALIDATE=1
+
+Full JSON Schema validation (against
+standards/state-spine/schemas/substrate-config.schema.json) is
+deferred — substrate.config.md needs migration to YAML frontmatter
+first; tracked at bassclef#643.
+
+Closes bassclef#1157 (BLOCK→WARN severity ladder).
+Prior contract: bassclef#591 (thin-validator half; full-schema half deferred).
+================================================================
+EOF
+  return 0 2>/dev/null || exit 0
+fi
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/20-artifact-staleness.sh

@@ -0,0 +1,98 @@
+# tier: lite
+# Artifact-staleness checks: chronicle, danger-mode summary,
+# architect review, release notes. Any that are overdue fire BLOCKED.
+
+# === Chronicle ===
+# Freshness signal reads TWO sources per bassclef-upstream#1438:
+#   1. Chronicle filename date (YYYY-MM-DD from `chronicle/YYYY-MM-DDx-slug.md`)
+#   2. Latest `## Amendment YYYY-MM-DD` header inside chronicle bodies
+# LAST_CHRONICLE = MAX of the two. Cross-day marathon sessions land
+# amendments on prior-day chronicles instead of creating same-day files;
+# reading only the filename produced false-positive blocks. Similarly,
+# TODAY_CHRONICLE counts same-day filename OR any today amendment header.
+for CHRONICLE_DIR in "chronicle" "docs/chronicle"; do
+  if [ -d "$CHRONICLE_DIR" ]; then
+    TODAY=$(date +%Y-%m-%d)
+    LAST_CHRONICLE_FILENAME=$(ls -1 "$CHRONICLE_DIR"/*.md 2>/dev/null | sort | tail -1 | xargs basename 2>/dev/null | cut -c1-10)
+
+    # Path A (bassclef-upstream#1438): scan chronicle bodies for
+    # `^## Amendment YYYY-MM-DD` headers. Take the latest by date-sort.
+    LATEST_AMENDMENT_DATE=$(grep -h -E '^## Amendment [0-9]{4}-[0-9]{2}-[0-9]{2}' "$CHRONICLE_DIR"/*.md 2>/dev/null \
+      | sed -E 's/^## Amendment ([0-9]{4}-[0-9]{2}-[0-9]{2}).*/\1/' \
+      | sort | tail -1)
+
+    # LAST_CHRONICLE = MAX(filename-date, amendment-date). Empty inputs
+    # drop out of grep -v; sort picks max lex which equals max date for
+    # ISO YYYY-MM-DD format.
+    LAST_CHRONICLE=$(printf '%s\n%s\n' "$LAST_CHRONICLE_FILENAME" "$LATEST_AMENDMENT_DATE" \
+      | grep -v '^$' | sort | tail -1)
+
+    if [ -n "$LAST_CHRONICLE" ]; then
+      COMMITS_SINCE_CHRONICLE=$(git log --oneline --since="$LAST_CHRONICLE" 2>/dev/null | wc -l | tr -d ' ')
+
+      # TODAY_CHRONICLE: same-day filename OR any today amendment header
+      TODAY_CHRONICLE_FILENAME=$(ls -1 "$CHRONICLE_DIR"/${TODAY}*.md 2>/dev/null | wc -l | tr -d ' ')
+      TODAY_AMENDMENT=$(grep -h -E "^## Amendment ${TODAY}" "$CHRONICLE_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+      TODAY_CHRONICLE=$((TODAY_CHRONICLE_FILENAME + TODAY_AMENDMENT))
+
+      if [ "$COMMITS_SINCE_CHRONICLE" -ge 3 ] && [ "$TODAY_CHRONICLE" -eq 0 ]; then
+        blocked_banner "chronicle — last entry $LAST_CHRONICLE, $COMMITS_SINCE_CHRONICLE commits since. Write the missing chronicle."
+      fi
+    fi
+    break
+  fi
+done
+
+# === Danger mode summary ===
+DANGER_DIR="docs/danger-mode-summaries"
+if [ -d "$DANGER_DIR" ]; then
+  TODAY=$(date +%Y-%m-%d)
+  COMMITS_TODAY=$(git log --oneline --since="$TODAY" 2>/dev/null | wc -l | tr -d ' ')
+  TODAY_DANGER=$(ls -1 "$DANGER_DIR"/${TODAY}.md 2>/dev/null | wc -l | tr -d ' ')
+
+  if [ "$COMMITS_TODAY" -ge 3 ] && [ "$TODAY_DANGER" -eq 0 ]; then
+    echo "### DANGER MODE SUMMARY MAY BE MISSING"
+    echo ""
+    echo "$COMMITS_TODAY commits today but no danger mode summary."
+    echo "If the previous session used auto-complete, write the summary."
+    echo ""
+  fi
+fi
+
+# === Architect review ===
+# Per #1486: scan all three known review-output paths (audits/ was added
+# via bet 27c; reader was blind to it). Take the LATEST date across paths
+# — the write side may land in any of them.
+LAST_REVIEW=""
+for REVIEW_DIR in "docs/architecture/reviews" "architecture/reviews" "architecture/audits"; do
+  if [ -d "$REVIEW_DIR" ]; then
+    CANDIDATE=$(ls -1 "$REVIEW_DIR"/*.md 2>/dev/null | sort | tail -1 | xargs basename 2>/dev/null | cut -c1-10)
+    if [ -n "$CANDIDATE" ] && [[ "$CANDIDATE" > "$LAST_REVIEW" ]]; then
+      LAST_REVIEW="$CANDIDATE"
+    fi
+  fi
+done
+if [ -n "$LAST_REVIEW" ]; then
+  COMMITS_SINCE=$(git log --oneline --since="$LAST_REVIEW" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$COMMITS_SINCE" -ge 10 ]; then
+    blocked_banner "architect-review — $COMMITS_SINCE commits since last review ($LAST_REVIEW). Run /architect-review."
+  fi
+fi
+
+# === Release notes ===
+NOTES_DIR="docs/release-notes"
+if [ -d "$NOTES_DIR" ]; then
+  LAST_NOTES=$(ls -1 "$NOTES_DIR"/*.md 2>/dev/null | grep -v .gitkeep | sort | tail -1)
+  if [ -n "$LAST_NOTES" ]; then
+    LAST_NOTES_DATE=$(basename "$LAST_NOTES" .md | cut -c1-10)
+    DAYS_SINCE=$(( ( $(date +%s) - $(date -j -f "%Y-%m-%d" "$LAST_NOTES_DATE" +%s 2>/dev/null || echo "0") ) / 86400 ))
+    if [ "$DAYS_SINCE" -gt 7 ]; then
+      blocked_banner "release-notes — last entry $(basename "$LAST_NOTES"), ${DAYS_SINCE} days ago. Run /release-notes."
+    fi
+  else
+    TOTAL_COMMITS=$(git log --oneline 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$TOTAL_COMMITS" -gt 10 ]; then
+      blocked_banner "release-notes — $TOTAL_COMMITS commits, zero changelogs. Run /release-notes to backfill."
+    fi
+  fi
+fi

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