@thebassclef/lite 1.1.1 → 1.2.0-alpha.1

package/dist/lite/.claude/hooks/save-state.sh

@@ -0,0 +1,268 @@
+#!/bin/bash
+# tier: lite
+set -e
+
+# Save State — graceful checkpoint of all work in progress.
+# Called by: session-end hook, idle auto-save loop, or manually.
+#
+# What it does:
+#   1. Commits any uncommitted changes with a checkpoint message
+#   2. Pushes to remote
+#   3. Writes LAST_SAVE with timestamp + machine info
+#   4. Removes SESSION_LOCK
+#
+# Usage:
+#   .claude/hooks/save-state.sh                   # from repo root, interactive
+#   .claude/hooks/save-state.sh --quiet           # suppress output (session-end)
+#   .claude/hooks/save-state.sh --quiet --auto    # launchd auto-save; refuses
+#                                                 # on feature/fix branches per
+#                                                 # bassclef#581 atomic-PR rule
+
+QUIET=""
+AUTO=""
+for arg in "$@"; do
+  case "$arg" in
+    --quiet) QUIET="true" ;;
+    --auto)  AUTO="true" ;;
+  esac
+done
+
+log() {
+  # Note: must always return 0 so `set -e` does not terminate the script
+  # when --quiet is set ($QUIET="true" means the test fails and && skips
+  # echo, which would otherwise return 1). Closes bassclef#1054.
+  if [ -z "$QUIET" ]; then
+    echo "$1"
+  fi
+  return 0
+}
+
+# Trace log
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+  source "$SCRIPT_DIR/trace-helper.sh"
+  trace_log "save-state" "checkpoint"
+fi
+
+# Check AUTO_SAVE_DEFER marker — respect agent-declared commit-sequence
+# intent (bassclef#1026 / WU-A1).
+#
+# When the agent (or operator) is mid-sequence on commits with per-file
+# intent (rationale per commit, semantic grouping), it writes a marker
+# at state/auto-save-defer.marker. save-state.sh sees the marker and
+# skips the auto-save checkpoint until the marker is cleared OR the
+# marker is older than DEFER_MARKER_TTL_SECONDS (default 3600 = 1h).
+#
+# Only --auto invocations check the marker. Operator-triggered or
+# session-end saves proceed normally regardless (those are intentional).
+#
+# Marker format: ISO timestamp on the first line; optional reason on
+# subsequent lines. Example:
+#   $ cat state/auto-save-defer.marker
+#   2026-06-17T06:35:00Z
+#   reason: wiki layer-consistency pass — per-file commits with rationale
+DEFER_MARKER="state/auto-save-defer.marker"
+DEFER_MARKER_TTL_SECONDS=${DEFER_MARKER_TTL_SECONDS:-3600}
+if [ "$AUTO" = "true" ] && [ -f "$DEFER_MARKER" ]; then
+  DEFER_TS=$(head -1 "$DEFER_MARKER" 2>/dev/null | tr -d ' ')
+  if [ -n "$DEFER_TS" ]; then
+    DEFER_EPOCH=""
+    # macOS date doesn't interpret 'Z' as a UTC suffix; force TZ=UTC so
+    # the suffix-literal parse computes the correct epoch.
+    if DEFER_EPOCH=$(TZ=UTC date -j -f "%Y-%m-%dT%H:%M:%SZ" "$DEFER_TS" +%s 2>/dev/null); then
+      :
+    elif DEFER_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%S%z" "$DEFER_TS" +%s 2>/dev/null); then
+      :
+    elif DEFER_EPOCH=$(date -d "$DEFER_TS" +%s 2>/dev/null); then
+      :
+    fi
+    if [ -n "$DEFER_EPOCH" ]; then
+      NOW_DEFER=$(date +%s)
+      DEFER_AGE=$((NOW_DEFER - DEFER_EPOCH))
+      if [ "$DEFER_AGE" -lt "$DEFER_MARKER_TTL_SECONDS" ]; then
+        log "AUTO_SAVE_DEFER marker present (age ${DEFER_AGE}s) — skipping auto-save per bassclef#1026"
+        exit 0
+      else
+        log "AUTO_SAVE_DEFER marker is stale (age ${DEFER_AGE}s > ttl ${DEFER_MARKER_TTL_SECONDS}s) — clearing and proceeding"
+        rm -f "$DEFER_MARKER"
+      fi
+    fi
+  fi
+fi
+
+# Check SESSION_LOCK — respect locks held by other sessions (bassclef#736 / WU-A3)
+# Behavior:
+#   - SAVE_STATE_FORCE=1: bypass entire lock check (logged via trace); per bassclef-upstream#402
+#   - No lock: proceed normally
+#   - Malformed lock or unparseable timestamp: proceed defensively (fail open)
+#   - Lock held by our pid ($$): proceed (it's our own lock)
+#   - Lock held by same pgid as $$: proceed (subshell inheritance — Claude harness writes lock; descendant runs save-state)
+#   - Lock held by an ancestor pid of $$: proceed (per bassclef-upstream#402; Bash-tool self-close case where pgid differs but harness pid is our ancestor)
+#   - Lock held by other pid + fresh (≤ LOCK_TTL_SECONDS): refuse, preserve lock, exit 0
+#   - Lock held by other pid + stale (> LOCK_TTL_SECONDS): clear lock with notice, proceed
+LOCK_FILE=".claude/SESSION_LOCK"
+LOCK_TTL_SECONDS=${LOCK_TTL_SECONDS:-1800}  # 30 min default per mobile-ephemeral-session.md
+LOCK_ANCESTOR_WALK_MAX_DEPTH=${LOCK_ANCESTOR_WALK_MAX_DEPTH:-20}  # caps ancestor walk; mirrors thread-walk pattern
+
+# Walk $$'s ancestor pid chain via repeated ps -o ppid=.
+# Returns 0 if target_pid found in chain; 1 otherwise.
+# Caps at LOCK_ANCESTOR_WALK_MAX_DEPTH and breaks at pid 1 (init) or cycle.
+is_pid_ancestor_of_self() {
+  local target_pid="$1"
+  [ -z "$target_pid" ] && return 1
+  local current_pid=$$
+  local depth=0
+  while [ "$depth" -lt "$LOCK_ANCESTOR_WALK_MAX_DEPTH" ] \
+        && [ -n "$current_pid" ] \
+        && [ "$current_pid" -gt 1 ]; do
+    [ "$current_pid" = "$target_pid" ] && return 0
+    local next_pid
+    next_pid=$(ps -o ppid= -p "$current_pid" 2>/dev/null | tr -d ' ')
+    [ -z "$next_pid" ] && break
+    [ "$next_pid" = "$current_pid" ] && break  # cycle guard
+    current_pid="$next_pid"
+    depth=$((depth + 1))
+  done
+  return 1
+}
+# Refuse --auto saves on every named branch in branching.md (bassclef#581 / WU-A4).
+# Why: launchd auto-save fires every 15 min regardless of operator activity.
+# - On main/master: violates 'no direct commit to main' (guardrails.md + branching.md).
+#   The push protection is separate; the commit still pollutes local main.
+# - On feature/*, fix/*, spike/*: pollutes the atomic-PR rule with unrelated commits.
+# Session-end and operator-triggered saves don't pass --auto; they proceed normally.
+if [ "$AUTO" = "true" ]; then
+  CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+  case "$CURRENT_BRANCH" in
+    main|master|feature/*|fix/*|spike/*)
+      log "Refusing --auto save on $CURRENT_BRANCH — operator-owned branch (bassclef#581). Direct commits violate branching.md + guardrails.md. Save when intentional."
+      exit 0
+      ;;
+  esac
+fi
+
+if [ -f "$LOCK_FILE" ]; then
+  LOCK_PID=$(grep -E '^pid:' "$LOCK_FILE" 2>/dev/null | head -1 | sed -E 's/^pid:[[:space:]]*//' | tr -d '[:space:]')
+  LOCK_TS=$(grep -E '^timestamp:' "$LOCK_FILE" 2>/dev/null | head -1 | sed -E 's/^timestamp:[[:space:]]*//')
+
+  if [ "${SAVE_STATE_FORCE:-0}" = "1" ]; then
+    # Explicit operator/skill override. Used when the agent has verified
+    # the lock is theirs but the pgid/ancestor checks below mis-classify
+    # (e.g., Bash-tool spawn that detaches from harness process tree).
+    # Logged to trace per defensive-bash.md.
+    log "SAVE_STATE_FORCE=1 — bypassing SESSION_LOCK check (LOCK_PID=$LOCK_PID)"
+    if command -v trace_log >/dev/null 2>&1; then
+      trace_log "save-state.sh SAVE_STATE_FORCE override (LOCK_PID=$LOCK_PID)"
+    fi
+    rm -f "$LOCK_FILE"
+  elif [ -z "$LOCK_PID" ] || [ -z "$LOCK_TS" ]; then
+    log "Note: malformed SESSION_LOCK — proceeding defensively"
+  elif LOCK_PGID=$(ps -o pgid= -p "$LOCK_PID" 2>/dev/null | tr -d ' ') \
+       && OUR_PGID=$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ') \
+       && [ -n "$LOCK_PGID" ] && [ -n "$OUR_PGID" ] \
+       && [ "$LOCK_PGID" = "$OUR_PGID" ]; then
+    # Same process group — the lock was written by our session
+    # (Claude harness writes the lock; save-state.sh runs as descendant
+    # in the same job/pgid). Proceed and clear at end.
+    log "SESSION_LOCK is ours (same pgid $OUR_PGID) — proceeding"
+  elif is_pid_ancestor_of_self "$LOCK_PID"; then
+    # Different pgid but LOCK_PID IS in our process-ancestor chain —
+    # the lock is legitimately ours. This catches the Bash-tool
+    # self-close case where the tool spawns a shell in a fresh pgid
+    # but the harness pid is still our process-tree ancestor.
+    # Per bassclef-upstream#402.
+    log "SESSION_LOCK is ours (LOCK_PID $LOCK_PID is ancestor of $$) — proceeding"
+  else
+    # Different pid — determine if stale
+    LOCK_EPOCH=""
+    if LOCK_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%S%z" "$LOCK_TS" +%s 2>/dev/null); then
+      :
+    elif LOCK_EPOCH=$(date -d "$LOCK_TS" +%s 2>/dev/null); then
+      :
+    else
+      LOCK_EPOCH=""
+    fi
+
+    if [ -z "$LOCK_EPOCH" ]; then
+      log "Note: SESSION_LOCK timestamp unparseable ($LOCK_TS) — proceeding defensively"
+    else
+      NOW_EPOCH=$(date +%s)
+      AGE_SECONDS=$((NOW_EPOCH - LOCK_EPOCH))
+      if [ "$AGE_SECONDS" -gt "$LOCK_TTL_SECONDS" ]; then
+        log "Stale SESSION_LOCK (age ${AGE_SECONDS}s, pid $LOCK_PID) — clearing and proceeding"
+        rm -f "$LOCK_FILE"
+      else
+        log "SESSION_LOCK held by other session (pid $LOCK_PID, age ${AGE_SECONDS}s) — refusing to commit; lock preserved"
+        exit 0
+      fi
+    fi
+  fi
+fi
+
+# 1. Commit uncommitted changes
+# Skip if agent has files staged — avoid racing over the same files
+ALREADY_STAGED=$(git diff --cached --name-only 2>/dev/null)
+if [ -n "$ALREADY_STAGED" ]; then
+  log "Skipping auto-save — agent has staged files (avoiding race condition)"
+else
+DIRTY=$(git status --porcelain 2>/dev/null | grep -v '\.DS_Store' | grep -v 'SESSION_LOCK' | head -20)
+if [ -n "$DIRTY" ]; then
+  # Stage tracked modified files + any docs/ or chronicle/ or runtime state
+  git add -u 2>/dev/null || true
+  git add docs/ chronicle/ specs/ 2>/dev/null || true
+  # state/ except state/markers/ — markers are runtime gate evidence that
+  # trigger session-rescue false-positives if committed (bassclef#341 / WU-A2).
+  # Negative pathspec syntax requires git >= 2.13 (stable since 2017).
+  git add 'state/' ':!state/markers' ':!state/markers/**' 2>/dev/null || true
+  git add .claude/projects/*/memory/ 2>/dev/null || true
+
+  STAGED=$(git diff --cached --name-only 2>/dev/null)
+  if [ -n "$STAGED" ]; then
+    TIMESTAMP=$(date +%Y-%m-%dT%H:%M:%S)
+    FILE_COUNT=$(echo "$STAGED" | wc -l | tr -d ' ')
+
+    # No hostname in commit message per sunj-labs/bassclef#1471 + CCF-3.
+    # Branch name + file count + timestamp cover debug needs without leaking
+    # operator machine identifier.
+    BRANCH_NAME=$(git branch --show-current 2>/dev/null || echo "detached")
+    git commit -m "chore: auto-save checkpoint ($FILE_COUNT files on $BRANCH_NAME at $TIMESTAMP)" 2>/dev/null
+    log "Committed $FILE_COUNT files"
+  fi
+fi
+fi  # end ALREADY_STAGED guard
+
+# 2. Push to remote (NEVER push to protected branches)
+BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+PROTECTED_BRANCHES="main master"
+REMOTE_EXISTS=$(git remote 2>/dev/null | head -1)
+
+if [ -z "$BRANCH" ]; then
+  log "Skipping push — detached HEAD or unknown branch"
+elif echo "$PROTECTED_BRANCHES" | grep -qw "$BRANCH"; then
+  log "WARNING: on protected branch '$BRANCH' — skipping push. Commit saved locally."
+elif [ -n "$REMOTE_EXISTS" ]; then
+  git push origin "$BRANCH" 2>/dev/null && log "Pushed to origin/$BRANCH" || log "Push failed (offline?)"
+fi
+
+# 3. Write LAST_SAVE (local-only per .gitignore — never git-tracked;
+# per sunj-labs/bassclef#1471 + CCF-3 + .claude/rules/identifier-leak-prevention.md).
+# machine field kept locally for operator debug; file itself gitignored.
+LAST_SAVE_FILE=".claude/LAST_SAVE"
+TIMESTAMP=$(date +%Y-%m-%dT%H:%M:%S%z)
+MACHINE=$(hostname -s 2>/dev/null || echo "unknown")
+BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+LAST_COMMIT=$(git log --oneline -1 2>/dev/null || echo "none")
+
+cat > "$LAST_SAVE_FILE" <<SAVE
+timestamp: $TIMESTAMP
+machine: $MACHINE
+branch: $BRANCH
+last_commit: $LAST_COMMIT
+SAVE
+
+log "State saved locally at $TIMESTAMP"
+
+# 4. Remove session lock
+rm -f .claude/SESSION_LOCK 2>/dev/null
+
+exit 0

package/dist/lite/.claude/hooks/session-reflection.d/08-settings-drift.sh

@@ -27,7 +27,14 @@ fi
 # Source the shared wirings accessor (per decomposition § Interface Registry).
 __sd_wirings_lib="${BASSCLEF_DIR:-${PWD}}/.claude/hooks/_lib/wirings.sh"
 if [ ! -f "$__sd_wirings_lib" ]; then
-  # Substrate not fully synced; sister modules surface the larger issue.
+  # Audible-fail cure per sunj-labs/bassclef-cli#105 — prior version dropped
+  # only a trace line nobody read. Fragment now names itself + the expected
+  # path on stderr so the adopter can act.
+  if declare -f emit_missing_dep_notice >/dev/null 2>&1; then
+    emit_missing_dep_notice "settings-drift" "$__sd_wirings_lib"
+  else
+    printf 'settings-drift: skip — wirings lib not at %s\n' "$__sd_wirings_lib" >&2
+  fi
   trace_log "skip" "settings-drift" "wirings lib not yet synced" 2>/dev/null || true
   unset __sd_wirings_lib
   return 0 2>/dev/null || true

package/dist/lite/.claude/hooks/session-reflection.d/10-abrupt-stop-recovery.sh

@@ -40,6 +40,25 @@
 # so the per-file allowlist match below can recognize each path.
 # Without -uall, a new file inside a previously empty marker dir would
 # appear as "?? state/" (dir summary), bypassing the allowlist filter.
+# Fresh-install guard — cures sunj-labs/bassclef-cli#108.
+# On the first session after `bassclef init` in an empty repo, `git status
+# --porcelain` sees hundreds of untracked files from init and the banner
+# fires with "ABRUPT STOP" advice against a session that never existed.
+# Skip when the repo has no commits AND no session lock — no prior session
+# to stop abruptly.
+{
+  _fi_sd="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+  for _fi_c in "${_fi_sd}/../../../lib/fresh-install-check.sh" "${BASSCLEF_DIR:-.}/lib/fresh-install-check.sh"; do
+    # shellcheck source=/dev/null
+    [ -f "$_fi_c" ] && source "$_fi_c" && break
+  done
+  unset _fi_sd _fi_c
+} 2>/dev/null || true
+
+if declare -f is_fresh_install >/dev/null 2>&1 && is_fresh_install; then
+  return 0 2>/dev/null || exit 0
+fi
+
 DIRTY_TREE_RAW=$(git status --porcelain -uall 2>/dev/null)
 
 # Strip the 3-char porcelain status prefix (XY + space) before matching
@@ -63,6 +82,39 @@ DIRTY_TREE=$(echo "$DIRTY_TREE_RAW" | awk '
   print
 }' | head -5)
 
+# Class D (bassclef-upstream#1719): no session has ever ended here.
+#
+# A dirty tree is a proxy for "the last session ended without saving". That
+# holds for a repo with history. It is wrong for a repo whose only prior
+# event was an install: `bassclef init` copies 400+ files and commits none
+# of them, so an adopter's very first session start reported an abrupt stop
+# and told them recovery was needed. Nothing had stopped.
+#
+# Same reasoning as Class 0 above, which bassclef#888 added because a banner
+# that fires when nothing is wrong trains the reader to skip the one that
+# matters.
+#
+# Three signals that a session ran here before. Any one is enough.
+PRIOR_SESSION=""
+[ -f ".claude/LAST_SAVE" ] && PRIOR_SESSION="last-save"
+if [ -z "$PRIOR_SESSION" ]; then
+  for d in chronicle docs/chronicle; do
+    if [ -d "$d" ] && [ -n "$(ls -A "$d" 2>/dev/null)" ]; then
+      PRIOR_SESSION="session-log"; break
+    fi
+  done
+fi
+if [ -z "$PRIOR_SESSION" ]; then
+  COMMIT_COUNT=$(git rev-list --count HEAD 2>/dev/null || echo 0)
+  [ "${COMMIT_COUNT:-0}" -gt 1 ] && PRIOR_SESSION="commit-history"
+fi
+
+if [ -n "$DIRTY_TREE" ] && [ -z "$PRIOR_SESSION" ]; then
+  # Fresh install. Uncommitted files are what the installer left, not what a
+  # crash left. Say nothing rather than raise a false alarm.
+  DIRTY_TREE=""
+fi
+
 if [ -n "$DIRTY_TREE" ]; then
   echo "### ABRUPT STOP DETECTED — RECOVERY NEEDED"
   echo ""

package/dist/lite/.claude/hooks/session-reflection.d/55-orientation-gate.sh

@@ -51,6 +51,28 @@ if [ "${SKIP_ORIENTATION_GATE:-0}" = "1" ]; then
   return 0 2>/dev/null || exit 0
 fi
 
+# Fresh-install guard — cures sunj-labs/bassclef-cli#102.
+# Silence when the repo is fresh-install AND no goal docs on disk. The gate
+# needs an orientation target; a cold repo has none. Firing a red BLOCKED
+# in that state reads as a broken install. Established repos and repos with
+# staged goal docs still fire the gate as before.
+{
+  _fi_sd="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+  for _fi_c in "${_fi_sd}/../../../lib/fresh-install-check.sh" "${BASSCLEF_DIR:-.}/lib/fresh-install-check.sh"; do
+    # shellcheck source=/dev/null
+    [ -f "$_fi_c" ] && source "$_fi_c" && break
+  done
+  unset _fi_sd _fi_c
+} 2>/dev/null || true
+
+if declare -f is_fresh_install >/dev/null 2>&1 && is_fresh_install; then
+  # Also require no goal docs AND no whereami.md on disk. An operator who
+  # staged either before their first commit is oriented enough for the gate.
+  if ! ls docs/iteration-bets/*.md >/dev/null 2>&1 && [ ! -f "docs/whereami.md" ]; then
+    return 0 2>/dev/null || exit 0
+  fi
+fi
+
 # Branch detection. Silent only when git is missing.
 BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
 if [ -z "$BRANCH" ]; then
@@ -133,13 +155,27 @@ if [ -f "substrate.config.md" ]; then
   fi
 fi
 
-# Emit BLOCKED block
+# RFC-0008 F3 — this gate already knows its own state. Line 118 branches on
+# whether a goal exists. With a goal, not walking it is a real gap. With no
+# goal there is nothing to walk, and a first-run adopter who has done nothing
+# wrong should not open their first session to a stop sign. Same content,
+# severity that matches what happened.
+if [ -n "$ACTIVE_BET" ] && [ "$ACTIVE_BET" != "(none in whereami)" ]; then
+  GATE_HEAD="🛑 BLOCKED: orientation-gate"
+  GATE_LEAD="Before /sprint or /longrun prep proposes work, read the bigger picture first."
+  GATE_CLOSE="Silence is not deferral. Default is read first."
+else
+  GATE_HEAD="NOTE: orientation-gate"
+  GATE_LEAD="No goal is in flight, so there is nothing to read first. This is how the gate will look once one is."
+  GATE_CLOSE="Nothing to do yet. This becomes a gate once a goal is in flight."
+fi
+
 echo ""
 echo "============================================"
-echo "🛑 BLOCKED: orientation-gate"
+echo "${GATE_HEAD}"
 echo "============================================"
 echo ""
-echo "Before /sprint or /longrun prep proposes work, read the bigger picture first."
+echo "${GATE_LEAD}"
 echo ""
 echo "Active iteration_bet: ${ACTIVE_BET}"
 echo ""
@@ -178,7 +214,7 @@ echo ""
 echo "OR explicitly defer per .claude/rules/blocked-items.md:"
 echo "  \"skip orientation-gate this session\""
 echo ""
-echo "Silence is not deferral. Default is read first."
+echo "${GATE_CLOSE}"
 echo ""
 echo "Override (logged): SKIP_ORIENTATION_GATE=1"
 echo "Per bassclef#1183 + bassclef#1266 + bassclef#1275 + bassclef#1347."

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

@@ -1,5 +1,6 @@
 #!/bin/bash
 # tier: lite
+# install-class: dual
 # 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.
@@ -19,12 +20,18 @@
 # 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.
+# Probe bundled path first (dist/lite/ ship path per ADR-056 D3), then
+# $BASSCLEF_DIR fallback for synced adopters. Pattern matches
+# session-reflection.sh:11-17. Cures #1732 Phase A silent-fail at operator
+# scope where $BASSCLEF_DIR resolves to $HOME with no standards/ or lib/.
 _sd="$(dirname "${BASH_SOURCE[0]:-$0}")"
+
+MANIFEST=""
+for _m in "${_sd}/../../../standards/hook-cadence.json" \
+          "${BASSCLEF_DIR:-.}/standards/hook-cadence.json"; do
+  [ -f "$_m" ] && MANIFEST="$_m" && break
+done
+
 HB_LIB=""
 for _c in "${_sd}/../../../lib/hook-heartbeat.sh" \
           "${BASSCLEF_DIR:-.}/lib/hook-heartbeat.sh"; do

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

@@ -1,5 +1,6 @@
 #!/bin/bash
 # tier: lite
+# install-class: dual
 # 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
@@ -10,8 +11,23 @@
 # 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"
+# Probe bundled path first (dist/lite/ ship path per ADR-056 D3), then
+# $BASSCLEF_DIR fallback for synced adopters. Pattern matches
+# session-reflection.sh:11-17. Cures #1732 Phase A silent-fail at operator
+# scope where $BASSCLEF_DIR resolves to $HOME with no standards/ or .claude/hooks/.
+_sd="$(dirname "${BASH_SOURCE[0]:-$0}")"
+
+MANIFEST=""
+for _m in "${_sd}/../../../standards/hook-cadence.json" \
+          "${BASSCLEF_DIR:-.}/standards/hook-cadence.json"; do
+  [ -f "$_m" ] && MANIFEST="$_m" && break
+done
+
+HOOKS_DIR=""
+for _h in "${_sd}/.." \
+          "${BASSCLEF_DIR:-.}/.claude/hooks"; do
+  [ -d "$_h" ] && HOOKS_DIR="$_h" && break
+done
 
 if [ ! -f "$MANIFEST" ]; then
   return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/91-npm-version-drift.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# shellcheck shell=bash disable=SC1090
+# tier: lite
+# install-class: dual
+# 91-npm-version-drift.sh — SessionStart fragment that surfaces npm-version
+# drift for @thebassclef/lite. Sources lib/npm-version-check.sh + calls
+# check_lite_version_drift. Silent-return on every failure class per
+# ADR-056 D3 fail-soft discipline.
+#
+# Guarded by is_fresh_install — no drift banner on the first session of
+# a brand-new repo (cli#102 + cli#108 companion pattern).
+#
+# @luminary alan-cooper — adopter hears drift banner; acts on `bassclef sync`
+# @luminary michael-nygard — silent-pass on every failure class
+
+# Source lib probe — bundled path first (ADR-056 D3), then $HOME/lib fallback.
+{
+  _nd_sd="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+  for _nd_c in "${_nd_sd}/../../../lib/npm-version-check.sh" \
+               "${BASSCLEF_DIR:-.}/lib/npm-version-check.sh" \
+               "${HOME:-/}/lib/npm-version-check.sh"; do
+    [ -f "$_nd_c" ] && source "$_nd_c" && break
+  done
+  unset _nd_sd _nd_c
+} 2>/dev/null || true
+
+# Source fresh-install helper (from Sub-feature 2).
+{
+  _fi_sd="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+  for _fi_c in "${_fi_sd}/../../../lib/fresh-install-check.sh" \
+               "${BASSCLEF_DIR:-.}/lib/fresh-install-check.sh" \
+               "${HOME:-/}/lib/fresh-install-check.sh"; do
+    [ -f "$_fi_c" ] && source "$_fi_c" && break
+  done
+  unset _fi_sd _fi_c
+} 2>/dev/null || true
+
+# Silence on fresh install per Nygard N5 cure — the adopter has bigger
+# things to look at on turn 1 than a drift notice.
+if declare -f is_fresh_install >/dev/null 2>&1 && is_fresh_install; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Silent-pass if the lib is not present (defensive).
+if ! declare -f check_lite_version_drift >/dev/null 2>&1; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Fire the check. Banner (if any) goes to stdout, then normal fragment flow
+# continues. Wrap in a subshell so the function's return code cannot break
+# the parent session-reflection chain under set -e.
+( check_lite_version_drift ) 2>/dev/null || true
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/tests/10-abrupt-stop-recovery.test.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# tier: standard
+# fixtures: live-substrate
+# Tier 0 test for .claude/hooks/session-reflection.d/10-abrupt-stop-recovery.sh
+#
+# Closes sunj-labs/bassclef-upstream#1719 — a fresh install leaves 400+
+# uncommitted files, so the fragment's dirty-tree condition fires on an
+# adopter's very first session and tells them an abrupt stop was detected.
+# Nothing stopped. They installed thirty seconds ago.
+#
+# Test list (per .claude/rules/test-list-discipline.md):
+#   [x] 1. dirty tree WITH prior-session evidence  -> banner fires (unchanged)
+#   [x] 2. dirty tree with NO prior session        -> silent (#1719)
+#   [x] 3. clean tree                              -> silent (unchanged)
+#   [x] 4. sourced under set -e: parent survives   (criterion 12)
+#   [x] 5. standalone: no "return: can only" error (criterion 12)
+
+set -uo pipefail
+REPO_ROOT=$(git rev-parse --show-toplevel)
+FRAG="$REPO_ROOT/.claude/hooks/session-reflection.d/10-abrupt-stop-recovery.sh"
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "  PASS: $1"; }
+fail() { FAIL=$((FAIL+1)); echo "  FAIL: $1"; }
+
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+
+# Build a repo in one of two shapes: with or without a prior session.
+make_repo() {
+  local dir="$1" prior="$2"
+  rm -rf "$dir"; mkdir -p "$dir"; cd "$dir" || return 1
+  git init -q .; git config user.email t@t.test; git config user.name t
+  echo x > README.md; git add -A; git commit -qm "initial"
+  if [ "$prior" = "with-prior" ]; then
+    mkdir -p .claude; printf 'timestamp: 2026-09-01T00:00:00Z\n' > .claude/LAST_SAVE
+    git add -A; git commit -qm "a real session ended here"
+  fi
+  # the install: many uncommitted files, as bassclef init leaves them
+  mkdir -p .claude/skills/temperance
+  echo "---" > .claude/skills/temperance/SKILL.md
+  echo "untracked" > some-file.md
+  cd - >/dev/null || return 1
+}
+
+run_frag() {  # $1 = repo dir
+  ( cd "$1" && bash "$FRAG" 2>&1 )
+}
+
+# --- Test 1: dirty tree, prior session existed -> banner still fires ---
+make_repo "$TMP/with" with-prior
+OUT=$(run_frag "$TMP/with")
+if echo "$OUT" | grep -q "ABRUPT STOP DETECTED"; then
+  pass "Test 1: dirty tree with a prior session still reports an abrupt stop"
+else
+  fail "Test 1: banner went silent where it should still fire"
+fi
+
+# --- Test 2: dirty tree, no prior session -> silent (#1719) ---
+make_repo "$TMP/fresh" no-prior
+OUT=$(run_frag "$TMP/fresh")
+if echo "$OUT" | grep -q "ABRUPT STOP DETECTED"; then
+  fail "Test 2: fresh install reports an abrupt stop that never happened"
+else
+  pass "Test 2: fresh install stays silent"
+fi
+
+# --- Test 3: clean tree -> silent ---
+rm -rf "$TMP/clean"; mkdir -p "$TMP/clean"
+( cd "$TMP/clean" && git init -q . && git config user.email t@t.test && git config user.name t \
+  && echo x > README.md && git add -A && git commit -qm init ) >/dev/null 2>&1
+OUT=$(run_frag "$TMP/clean")
+if echo "$OUT" | grep -q "ABRUPT STOP DETECTED"; then
+  fail "Test 3: clean tree reported an abrupt stop"
+else
+  pass "Test 3: clean tree stays silent"
+fi
+
+# --- Test 4 + 5: invocation-mode variation (test-sufficiency criterion 12) ---
+# shellcheck source=/dev/null  # $FRAG is the fragment under test; path is a fixture
+OUT=$( set -e; . "$FRAG" >/dev/null 2>&1; echo "parent-survived" )
+if echo "$OUT" | grep -q "parent-survived"; then
+  pass "Test 4: sourced under set -e, the parent survives"
+else
+  fail "Test 4: sourcing killed the parent"
+fi
+
+ERR=$(bash "$FRAG" 2>&1 >/dev/null)
+if echo "$ERR" | grep -q "return: can only"; then
+  fail "Test 5: standalone run emits a return-outside-function error"
+else
+  pass "Test 5: standalone run is clean"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1