@thebassclef/lite 1.8.0 → 1.9.1

package/README.md

@@ -35,7 +35,7 @@ See [`standards/os-support.md`](standards/os-support.md) for the full policy.
 
 ## Current release
 
-<!-- version-start -->1.8.0<!-- version-end -->
+<!-- version-start -->1.9.1<!-- version-end -->
 
 See [CHANGELOG.md](CHANGELOG.md) for release notes.
 

package/dist/index.cjs

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const version = "1.8.0";
+const version = "1.9.1";
 exports.version = version;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export declare const version: "1.8.0";
+export declare const version: "1.9.1";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.8.0";
+const version = "1.9.1";
 export {
   version
 };

package/dist/lite/.claude/hooks/bassclef-sync.sh

@@ -1,7 +1,10 @@
 #!/bin/bash
-# tier: lite
+# tier: upstream
+# install-class: operator
 # Bassclef Substrate Sync — fires on SessionStart.
 # Operator-class hook: lives on bassclef-upstream operators' machines only.
+# Ship 1 (#1828) — install-class: operator retag; adopters use the dispatcher
+# (presence/install/bassclef-sync.dispatcher.template.sh) instead.
 # Adopter consumers receive presence/install/bassclef-sync.template.sh instead
 # (sourced from canonical until the WU-0 absorb gap is closed).
 # Ensures bassclef standards are available regardless of device.
@@ -127,6 +130,9 @@ _sync_install_hooks() {
   local skipped_invalid=0
   local skipped_lib_missing=0
   local failed=0
+  # #1894 — capture missing-hook paths for structured status line
+  local -a missing_paths=()
+  local -a missing_scopes=()
 
   # S-F2 LOW — dir-exists guard before loop
   if [ ! -d "$bassclef_dir/.claude/hooks" ]; then
@@ -161,6 +167,9 @@ _sync_install_hooks() {
         chmod +x "$target" 2>/dev/null || true
         echo "$(date -u +%FT%TZ) dispatch-fail $hook_name" >> "$BASSCLEF_TRACE_LOG"
         failed=$((failed + 1))
+        # #1894 — capture path for structured status line
+        missing_paths+=(".claude/hooks/$hook_name")
+        missing_scopes+=("project")
       fi
     elif [ "$has_header" = "1" ] && [ "$dispatch_available" = "0" ]; then
       # S-F1 MED — dispatch lib missing; trace explicitly (not silent)
@@ -179,6 +188,9 @@ _sync_install_hooks() {
       else
         echo "$(date -u +%FT%TZ) skipped-invalid-header $hook_name" >> "$BASSCLEF_TRACE_LOG"
         skipped_invalid=$((skipped_invalid + 1))
+        # #1894 — invalid-header is a real defect (not grace-window); capture for status line
+        missing_paths+=(".claude/hooks/$hook_name")
+        missing_scopes+=("project")
       fi
     fi
   done
@@ -195,13 +207,36 @@ _sync_install_hooks() {
     breakdown="${breakdown#, }"
     # RFC-0008 F7 — three bare numbers read three ways. Say what they mean
     # together, and say plainly whether the install is usable.
-    if [ "$failed" = "0" ]; then
+    if [ "$failed" = "0" ] && [ "$skipped_invalid" = "0" ]; then
       echo "bassclef-sync: $installed hooks ready. $skipped_total skipped on purpose ($breakdown). Nothing failed — your install is complete."
     else
       echo "bassclef-sync: $installed hooks ready. $skipped_total skipped on purpose ($breakdown)."
-      echo "bassclef-sync: $failed could not be installed. Those hooks will not fire until that is fixed."
+      if [ "$failed" -gt 0 ]; then
+        echo "bassclef-sync: $failed could not be installed. Those hooks will not fire until that is fixed."
+      fi
     fi
   fi
+
+  # #1894 — idempotent-complete-or-fail-loud postcondition
+  # (pre-mortem R2 fold: RESTORED iff failed==0 && skipped_invalid==0;
+  #  grace-window and dispatch-lib-missing count as OK per ADR-058 c2)
+  local total=$((installed + skipped_total + failed))
+  local defect_total=$((failed + skipped_invalid))
+  if [ "$defect_total" = "0" ]; then
+    # RESTORED — human line + minimal JSON status:complete (Beck B1 fold: minimal JSON in V1)
+    echo "bassclef-sync: RESTORED — $installed of $total hooks resolved at their scoped targets."
+    printf 'bassclef-sync: {"status":"complete","installed":%d}\n' "$installed"
+  else
+    # DEGRADED — human line + JSON with missing[] carrying path + scope + cure per entry
+    echo "bassclef-sync: DEGRADED — $defect_total of $total hooks did not resolve after self-heal."
+    local i missing_json="["
+    for i in "${!missing_paths[@]}"; do
+      [ "$i" -gt 0 ] && missing_json="$missing_json,"
+      missing_json="$missing_json{\"path\":\"${missing_paths[$i]}\",\"scope\":\"${missing_scopes[$i]}\",\"cure\":\"bassclef init --force\"}"
+    done
+    missing_json="$missing_json]"
+    printf 'bassclef-sync: {"status":"degraded","installed":%d,"missing":%s}\n' "$installed" "$missing_json"
+  fi
 }
 
 # === Test-mode guard (#915) ===
@@ -719,9 +754,11 @@ fi
 MISSING=""
 
 # Google service account (needed for journal → Google Docs)
-SA_KEY="$HOME/.config/gcloud/sunjay-google-ops.json"
-if [ ! -f "$SA_KEY" ]; then
-  MISSING="${MISSING}\n- Google Docs service account key missing at $SA_KEY (needed for /journal → Google Doc push)"
+# Ship 1 (#1816): env var lookup; operator sets BASSCLEF_GCLOUD_KEY in their shell profile.
+# Unset = feature disabled (no adopter-visible path leak).
+SA_KEY="${BASSCLEF_GCLOUD_KEY:-}"
+if [ -n "$SA_KEY" ] && [ ! -f "$SA_KEY" ]; then
+  MISSING="${MISSING}\n- Google Docs service account key missing at \$BASSCLEF_GCLOUD_KEY (needed for /journal → Google Doc push)"
 fi
 
 # gh CLI auth (needed for /promote, issue creation)

package/dist/lite/.claude/hooks/git-stash-u-guard.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# PreToolUse: Bash
+#
+# git-stash-u guard (bassclef-upstream#1691 Cure 2)
+#
+# Fires ADVISORY banner when a `git stash -u` or `git stash --include-untracked`
+# command runs in a repo where any bassclef substrate directory is gitignored.
+# Warns the operator (or their agent) that `-u` would stash bassclef's own
+# untracked files, causing subsequent hook calls to fail with "No such file
+# or directory" per .claude/bassclef-orientation.md L120-134.
+#
+# ADVISORY tone (exit 0; never blocks). Silent when trap conditions do not
+# match — bare `git status`, plain `git stash` (no -u), stash subcommands
+# (pop, apply, list), or a repo where substrate is committed.
+#
+# Anchor luminaries — @luminary donald-norman (signifier match: ⚠ tone),
+# @luminary alan-cooper (Sam+Louis plain language), @luminary linus-torvalds
+# (adopter contract; additive-only + skippable + gitignore-conditional).
+#
+# Override: SKIP_GIT_STASH_U_GUARD=1 bypasses for one call (logged via trace).
+
+set -uo pipefail
+
+# --- Read JSON stdin ---
+INPUT=""
+if [ -t 0 ]; then
+  # No stdin (interactive test) — nothing to check
+  exit 0
+fi
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+# --- Extract tool_input.command ---
+if ! command -v jq >/dev/null 2>&1; then
+  # Fail-soft on missing jq (Nygard stability)
+  exit 0
+fi
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$CMD" ] && exit 0
+
+# --- Regex — match ONLY git stash with -u OR --include-untracked (Norman N2 fold) ---
+# Anchor on "git stash" followed by args that include -u or --include-untracked.
+# Excludes: bare `git stash`, `git stash pop`, `git stash apply`, `git stash list`, etc.
+# The -u flag can appear anywhere after the `stash` verb (e.g., `git stash -u`,
+# `git stash push -u`, `git stash -u -m "msg"`).
+if ! echo "$CMD" | grep -qE '(^|[[:space:]])git[[:space:]]+stash([[:space:]]+push)?([[:space:]]+.*)?(-u([[:space:]]|$)|--include-untracked([[:space:]]|$))'; then
+  exit 0
+fi
+
+# --- Override — SKIP_GIT_STASH_U_GUARD=1 bypasses (logged) ---
+if [ "${SKIP_GIT_STASH_U_GUARD:-0}" = "1" ]; then
+  TRACE_LOG="${BASSCLEF_TRACE_LOG:-${BASSCLEF_TRACE_FILE:-$HOME/.claude/state/trace.log}}"
+  mkdir -p "$(dirname "$TRACE_LOG")" 2>/dev/null || true
+  echo "$(date -u +%FT%TZ) SKIP_GIT_STASH_U_GUARD $CMD" >> "$TRACE_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# --- Gitignore state check (Torvalds T2 fold) — fire only if substrate is gitignored ---
+GITIGNORE=""
+if [ -f "./.gitignore" ]; then
+  GITIGNORE=$(cat ./.gitignore 2>/dev/null || true)
+fi
+# Trap conditions: any of the substrate dirs listed in .gitignore
+if ! echo "$GITIGNORE" | grep -qE '^\.claude/(hooks|skills|rules|agents|luminaries)/?[[:space:]]*$'; then
+  exit 0
+fi
+
+# --- Emit ADVISORY banner (operator pick 2026-09-23c mock 2 v2B) ---
+cat <<'ADVISORY'
+
+⚠  Heads up — this would break bassclef.
+
+A stash tucks changes out of sight. `-u`
+also stashes untracked files, and bassclef's
+files aren't committed here — so `-u` would
+tuck them away too.
+
+Use plain `git stash` instead.
+
+ADVISORY
+
+exit 0

package/dist/lite/.claude/hooks/session-reflection.d/01-adopter-message-channel.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# SessionStart fragment — adopter message channel (bassclef-upstream#1926)
+#
+# Prints a welcome message on first-run adopters (no state files present).
+# Serves as a channel — future first-touch messages register by adding
+# check-print blocks that read state and print when a gate matches.
+#
+# V1 registers one message — welcome text pointing at /onboard-repo.
+# Fires only when ALL of these are absent: docs/whereami.md,
+# substrate.config.md, .claude/settings.json (fresh install shape).
+#
+# Anchor luminaries — @luminary alan-cooper (Sam+Louis first-touch persona),
+# @luminary donald-norman (INFO tone; no BLOCK glyph), @luminary linus-torvalds
+# (adopter contract; additive-only + silent on onboarded installs).
+#
+# Override: SKIP_ADOPTER_MESSAGES=1 bypasses for one call.
+
+set -uo pipefail
+
+# --- Override — SKIP_ADOPTER_MESSAGES=1 bypasses ---
+if [ "${SKIP_ADOPTER_MESSAGES:-0}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# --- Message: V1 welcome (only registered message so far) ---
+# Gate: fresh install shape — ALL 3 state files absent.
+_welcome_gate_matches() {
+  [ ! -f "./docs/whereami.md" ] && \
+  [ ! -f "./substrate.config.md" ] && \
+  [ ! -f "./.claude/settings.json" ]
+}
+
+_welcome_print() {
+  echo ""
+  echo "Welcome to bassclef."
+  echo ""
+  echo "First, run /onboard-repo — it wires hooks, writes config,"
+  echo "and creates the state files this repo needs."
+  echo ""
+}
+
+# --- Channel: check each message's gate; print first that matches ---
+if _welcome_gate_matches; then
+  _welcome_print
+fi
+
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/tests/fresh-install-state-gate.test.sh

@@ -0,0 +1,242 @@
+#!/bin/bash
+# tier: standard
+# fixtures: bassclef-upstream-self
+# Tier 0 test for #1818 Ship 3 — fresh-install state gates on
+# 30-metrics-staleness.sh + 80-hook-heartbeat-check.sh.
+#
+# Per @luminary donald-norman — a banner fires only when a real problem
+# exists. Fresh state (state dir absent) is not broken state.
+# Per @luminary michael-feathers — characterization tests via mktemp
+# fixture repos; source fragment inside wrapper that provides the
+# coordinator's helper stubs (blocked_banner, BASSCLEF_DIR).
+#
+# Test list per .claude/rules/test-list-discipline.md:
+# [x] Test 1 — 30-metrics-staleness.sh: no docs/metrics/ dir → silent (no BLOCKED)
+# [x] Test 2 — 30-metrics-staleness.sh: with docs/metrics/ dir + no latest.md → BLOCKED fires (gate does not over-scope)
+# [x] Test 3 — 80-hook-heartbeat-check.sh: no state/markers/hook-heartbeat/ → silent (no BLOCKED)
+# [x] Test 4 — 80-hook-heartbeat-check.sh: with state/markers/hook-heartbeat/ + aged markers past grace → BLOCKED fires
+# [x] Test 5 — 81-hook-manifest-staleness.sh: no state/markers/hook-heartbeat/ → silent (bassclef-upstream#1896 cure)
+# [x] Test 6 — 81-hook-manifest-staleness.sh: SELF_MODE=1 → silent (bassclef-upstream#1804 sister guard)
+# [x] Test 7 — 80-hook-heartbeat-check.sh: dir exists + no markers → silent (#1895 fresh-install cure — was BLOCKED pre-fix)
+# [x] Test 8 — 80-hook-heartbeat-check.sh: dir exists + fresh markers under 24h grace → silent (#1895 grace window)
+# [x] Test 9 — 80-hook-heartbeat-check.sh: FRESH_INSTALL_GRACE_SECONDS=0 override → BLOCKED fires immediately (#1895 override path)
+
+set -u
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
+METRICS_FRAG="$REPO_ROOT/.claude/hooks/session-reflection.d/30-metrics-staleness.sh"
+HB_FRAG="$REPO_ROOT/.claude/hooks/session-reflection.d/80-hook-heartbeat-check.sh"
+MS_FRAG="$REPO_ROOT/.claude/hooks/session-reflection.d/81-hook-manifest-staleness.sh"
+
+PASS=0
+FAIL=0
+FAILED_TESTS=()
+
+check() {
+  local name="$1"
+  local cond="$2"
+  if eval "$cond"; then
+    echo "PASS: $name"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name"
+    FAIL=$((FAIL + 1))
+    FAILED_TESTS+=("$name")
+  fi
+}
+
+TMPBASE=$(mktemp -d)
+# shellcheck disable=SC2064
+trap "rm -rf $TMPBASE" EXIT
+
+# Wrapper that stubs the coordinator's helpers so the fragment runs
+# under conditions matching real session-reflection.sh invocation.
+# blocked_banner writes to a marker file so tests can detect emission.
+run_fragment_with_stubs() {
+  local frag="$1"
+  local fixture_dir="$2"
+  local marker_file="$3"
+  (
+    cd "$fixture_dir" || exit 99
+    # shellcheck disable=SC2317
+    blocked_banner() {
+      echo "$*" >> "$marker_file"
+    }
+    export -f blocked_banner 2>/dev/null || true
+    BASSCLEF_DIR="$REPO_ROOT"
+    export BASSCLEF_DIR
+    # Source the fragment
+    # shellcheck disable=SC1090
+    source "$frag" 2>/dev/null || true
+  )
+}
+
+# === Test 1 — metrics fragment: no docs/metrics/ → silent ===
+FIXTURE1="$TMPBASE/fixture1-no-metrics"
+mkdir -p "$FIXTURE1"
+cd "$FIXTURE1" && git init -q -b main && git config user.email test@bassclef.local && git config user.name test
+mkdir -p "$FIXTURE1/scripts"
+touch "$FIXTURE1/scripts/metrics.sh"
+BANNER1="$TMPBASE/banner1.out"
+run_fragment_with_stubs "$METRICS_FRAG" "$FIXTURE1" "$BANNER1"
+if [ ! -s "$BANNER1" ]; then
+  check "Test 1 — metrics fragment silent when no docs/metrics/ dir" "true"
+else
+  echo "  banner content: $(cat $BANNER1)"
+  check "Test 1 — metrics fragment silent when no docs/metrics/ dir" "false"
+fi
+
+# === Test 2 — metrics fragment: docs/metrics/ present + no latest.md → BLOCKED fires ===
+FIXTURE2="$TMPBASE/fixture2-with-metrics-no-latest"
+mkdir -p "$FIXTURE2/docs/metrics" "$FIXTURE2/scripts"
+cd "$FIXTURE2" && git init -q -b main && git config user.email test@bassclef.local && git config user.name test
+touch "$FIXTURE2/scripts/metrics.sh"
+BANNER2="$TMPBASE/banner2.out"
+run_fragment_with_stubs "$METRICS_FRAG" "$FIXTURE2" "$BANNER2"
+if [ -s "$BANNER2" ] && grep -q "NO METRICS GENERATED" "$BANNER2"; then
+  check "Test 2 — metrics fragment fires BLOCKED when docs/metrics/ exists + no latest.md" "true"
+else
+  echo "  banner content: $(cat $BANNER2 2>/dev/null || echo empty)"
+  check "Test 2 — metrics fragment fires BLOCKED when docs/metrics/ exists + no latest.md" "false"
+fi
+
+# === Test 3 — heartbeat fragment: no state/markers/hook-heartbeat/ → silent ===
+FIXTURE3="$TMPBASE/fixture3-no-heartbeat-dir"
+mkdir -p "$FIXTURE3/standards" "$FIXTURE3/lib"
+cd "$FIXTURE3" && git init -q -b main && git config user.email test@bassclef.local && git config user.name test
+# Copy the manifest + lib so the fragment finds them but state dir absent
+cp "$REPO_ROOT/standards/hook-cadence.json" "$FIXTURE3/standards/" 2>/dev/null
+cp "$REPO_ROOT/lib/hook-heartbeat.sh" "$FIXTURE3/lib/" 2>/dev/null
+BANNER3="$TMPBASE/banner3.out"
+SELF_MODE=0 run_fragment_with_stubs "$HB_FRAG" "$FIXTURE3" "$BANNER3"
+if [ ! -s "$BANNER3" ]; then
+  check "Test 3 — heartbeat fragment silent when no state/markers/hook-heartbeat/ dir" "true"
+else
+  echo "  banner content: $(cat $BANNER3)"
+  check "Test 3 — heartbeat fragment silent when no state/markers/hook-heartbeat/ dir" "false"
+fi
+
+# === Test 4 — heartbeat fragment: dir + aged markers past grace → BLOCKED fires ===
+# Fixture: dir exists AND has an aged marker (48h old) — install is past
+# the 24h grace window AND has real staleness (marker's referenced hook
+# has max_age < 48h so it counts as stale).
+FIXTURE4="$TMPBASE/fixture4-heartbeat-aged-markers"
+mkdir -p "$FIXTURE4/standards" "$FIXTURE4/lib" "$FIXTURE4/state/markers/hook-heartbeat"
+cd "$FIXTURE4" && git init -q -b main && git config user.email test@bassclef.local && git config user.name test
+cp "$REPO_ROOT/standards/hook-cadence.json" "$FIXTURE4/standards/" 2>/dev/null
+cp "$REPO_ROOT/lib/hook-heartbeat.sh" "$FIXTURE4/lib/" 2>/dev/null
+# Write an anchor marker aged 48h old so the grace window has expired.
+# Use bassclef-sync as the aged marker; max_age is 86400s (24h) so it counts as stale.
+echo "2026-09-20T00:00:00Z" > "$FIXTURE4/state/markers/hook-heartbeat/bassclef-sync.marker"
+# Portable mtime setup: BSD `date -u -v-48H` first, fallback to GNU `date -u -d`
+old_stamp=$(date -u -v-48H +%Y%m%d%H%M 2>/dev/null || date -u -d '48 hours ago' +%Y%m%d%H%M)
+touch -t "$old_stamp" "$FIXTURE4/state/markers/hook-heartbeat/bassclef-sync.marker"
+BANNER4="$TMPBASE/banner4.out"
+SELF_MODE=0 run_fragment_with_stubs "$HB_FRAG" "$FIXTURE4" "$BANNER4"
+if [ -s "$BANNER4" ] && grep -q "hook liveness" "$BANNER4"; then
+  check "Test 4 — heartbeat fragment fires BLOCKED when dir + aged markers past grace" "true"
+else
+  echo "  banner content: $(cat $BANNER4 2>/dev/null || echo empty)"
+  check "Test 4 — heartbeat fragment fires BLOCKED when dir + aged markers past grace" "false"
+fi
+
+# === Test 5 — 81 fragment: no state/markers/hook-heartbeat/ → silent (bassclef-upstream#1896 cure) ===
+FIXTURE5="$TMPBASE/fixture5-no-heartbeat-dir-ms"
+mkdir -p "$FIXTURE5/standards" "$FIXTURE5/.claude/hooks"
+cd "$FIXTURE5" && git init -q -b main && git config user.email test@bassclef.local && git config user.name test
+# Copy manifest + a new hook that would flag as "not in manifest" without the gate
+cp "$REPO_ROOT/standards/hook-cadence.json" "$FIXTURE5/standards/" 2>/dev/null
+touch "$FIXTURE5/.claude/hooks/some-uncatalogued-hook.sh"
+BANNER5="$TMPBASE/banner5.out"
+SELF_MODE=0 run_fragment_with_stubs "$MS_FRAG" "$FIXTURE5" "$BANNER5"
+if [ ! -s "$BANNER5" ]; then
+  check "Test 5 — 81 fragment silent when no state/markers/hook-heartbeat/ dir (#1896 cure)" "true"
+else
+  echo "  banner content: $(cat $BANNER5)"
+  check "Test 5 — 81 fragment silent when no state/markers/hook-heartbeat/ dir (#1896 cure)" "false"
+fi
+
+# === Test 6 — 81 fragment: SELF_MODE=1 → silent (bassclef-upstream#1804 sister guard) ===
+FIXTURE6="$TMPBASE/fixture6-selfmode"
+mkdir -p "$FIXTURE6/standards" "$FIXTURE6/.claude/hooks" "$FIXTURE6/state/markers/hook-heartbeat"
+cd "$FIXTURE6" && git init -q -b main && git config user.email test@bassclef.local && git config user.name test
+cp "$REPO_ROOT/standards/hook-cadence.json" "$FIXTURE6/standards/" 2>/dev/null
+touch "$FIXTURE6/.claude/hooks/some-uncatalogued-hook.sh"
+BANNER6="$TMPBASE/banner6.out"
+SELF_MODE=1 run_fragment_with_stubs "$MS_FRAG" "$FIXTURE6" "$BANNER6"
+if [ ! -s "$BANNER6" ]; then
+  check "Test 6 — 81 fragment silent under SELF_MODE=1 (#1804 sister guard)" "true"
+else
+  echo "  banner content: $(cat $BANNER6)"
+  check "Test 6 — 81 fragment silent under SELF_MODE=1 (#1804 sister guard)" "false"
+fi
+
+# === Test 7 — heartbeat fragment: dir exists + no markers → silent (#1895 fresh-install cure) ===
+# Fixture: dir mkdir'd but no producer has ever fired heartbeat_mark. This is
+# the exact self-defeat class from #1895 — dir gets created by first hook fire,
+# but at 4 min old install with only 1 fire, remaining 6 hooks show "never fired."
+# Cure: grace window (24h default) suppresses banner on fresh install.
+FIXTURE7="$TMPBASE/fixture7-heartbeat-dir-no-markers"
+mkdir -p "$FIXTURE7/standards" "$FIXTURE7/lib" "$FIXTURE7/state/markers/hook-heartbeat"
+cd "$FIXTURE7" && git init -q -b main && git config user.email test@bassclef.local && git config user.name test
+cp "$REPO_ROOT/standards/hook-cadence.json" "$FIXTURE7/standards/" 2>/dev/null
+cp "$REPO_ROOT/lib/hook-heartbeat.sh" "$FIXTURE7/lib/" 2>/dev/null
+# dir EXISTS but no markers — pre-cure this triggers BLOCKED; post-cure silent under grace
+BANNER7="$TMPBASE/banner7.out"
+SELF_MODE=0 run_fragment_with_stubs "$HB_FRAG" "$FIXTURE7" "$BANNER7"
+if [ ! -s "$BANNER7" ]; then
+  check "Test 7 — heartbeat fragment silent when dir exists + no markers (#1895 cure)" "true"
+else
+  echo "  banner content: $(cat $BANNER7)"
+  check "Test 7 — heartbeat fragment silent when dir exists + no markers (#1895 cure)" "false"
+fi
+
+# === Test 8 — heartbeat fragment: dir + fresh markers under 24h grace → silent (#1895 grace window) ===
+# Fixture: dir exists AND has 1 fresh marker (just written) — install is
+# actively booting. Grace window should suppress banner even though other
+# critical hooks show "never fired."
+FIXTURE8="$TMPBASE/fixture8-heartbeat-fresh-marker"
+mkdir -p "$FIXTURE8/standards" "$FIXTURE8/lib" "$FIXTURE8/state/markers/hook-heartbeat"
+cd "$FIXTURE8" && git init -q -b main && git config user.email test@bassclef.local && git config user.name test
+cp "$REPO_ROOT/standards/hook-cadence.json" "$FIXTURE8/standards/" 2>/dev/null
+cp "$REPO_ROOT/lib/hook-heartbeat.sh" "$FIXTURE8/lib/" 2>/dev/null
+# Write a fresh marker (now) — grace window should hold.
+date -u +%Y-%m-%dT%H:%M:%SZ > "$FIXTURE8/state/markers/hook-heartbeat/bassclef-sync.marker"
+BANNER8="$TMPBASE/banner8.out"
+SELF_MODE=0 run_fragment_with_stubs "$HB_FRAG" "$FIXTURE8" "$BANNER8"
+if [ ! -s "$BANNER8" ]; then
+  check "Test 8 — heartbeat fragment silent when dir + fresh markers under 24h grace (#1895)" "true"
+else
+  echo "  banner content: $(cat $BANNER8)"
+  check "Test 8 — heartbeat fragment silent when dir + fresh markers under 24h grace (#1895)" "false"
+fi
+
+# === Test 9 — heartbeat fragment: FRESH_INSTALL_GRACE_SECONDS=0 override → BLOCKED fires ===
+# Fixture: same shape as Test 7 (dir + no markers) but grace window disabled.
+# Override path exercised — operator can bypass grace to test the check itself.
+FIXTURE9="$TMPBASE/fixture9-heartbeat-grace-override"
+mkdir -p "$FIXTURE9/standards" "$FIXTURE9/lib" "$FIXTURE9/state/markers/hook-heartbeat"
+cd "$FIXTURE9" && git init -q -b main && git config user.email test@bassclef.local && git config user.name test
+cp "$REPO_ROOT/standards/hook-cadence.json" "$FIXTURE9/standards/" 2>/dev/null
+cp "$REPO_ROOT/lib/hook-heartbeat.sh" "$FIXTURE9/lib/" 2>/dev/null
+BANNER9="$TMPBASE/banner9.out"
+FRESH_INSTALL_GRACE_SECONDS=0 SELF_MODE=0 run_fragment_with_stubs "$HB_FRAG" "$FIXTURE9" "$BANNER9"
+if [ -s "$BANNER9" ] && grep -q "hook liveness" "$BANNER9"; then
+  check "Test 9 — heartbeat fragment fires BLOCKED when FRESH_INSTALL_GRACE_SECONDS=0 (#1895 override)" "true"
+else
+  echo "  banner content: $(cat $BANNER9 2>/dev/null || echo empty)"
+  check "Test 9 — heartbeat fragment fires BLOCKED when FRESH_INSTALL_GRACE_SECONDS=0 (#1895 override)" "false"
+fi
+
+# --- Summary ---
+echo ""
+echo "Tests passed: $PASS"
+echo "Tests failed: $FAIL"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed tests:"
+  for t in "${FAILED_TESTS[@]}"; do
+    echo "  - $t"
+  done
+  exit 1
+fi
+exit 0

package/dist/lite/.claude/settings.json

@@ -47,6 +47,11 @@
             "type": "command",
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-commit-identifier-leak-scrub.sh",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/git-stash-u-guard.sh",
+            "timeout": 5
           }
         ]
       },

package/dist/lite/.claude/skills/build/SKILL.md

@@ -1,13 +1,14 @@
 ---
 tier: lite
 name: build
-description: "Take a buildable plan and ship it. Reads a spec from /launch. Dispatches a builder per user story. Runs /verify. Opens PRs. Gates prod deploy on a human. Refuses auth, schema, security, and tenant work. --explain narrates first."
+description: "Take a plan from /launch and ship it. One builder per user story. Runs /verify. Opens PRs. Gates prod on a human. Refuses auth, schema, security, and tenant work. Two modes — full and degrade-with-note."
 problem: "A buildable plan sits on disk. Nothing ships until someone writes code and PRs and gates prod."
 value: "Reads the plan and ships it. Runs the whole cycle so you can watch instead of type."
 inputs: [A goal slug pointing to a spec on disk]
 outputs: [One PR per user story, Verify report, Reviewer sign-off, Prod deploy gated on a human]
 user_invocable: true
 disable_model_invocation: false
+modes: [full, degrade-with-note]
 requires:
   cli: [git, gh]
   network: true
@@ -104,8 +105,63 @@ Open every /build invocation with:
 
 Walls of structured Phase 0-7 detail come AFTER this block.
 
+### Phase −1a — Capability probe (per bassclef-upstream#1909)
+
+/build gets two modes: **full** and **degrade-with-note**. Per RFC B1 folded (`docs/rfcs/2026-09-23-graceful-degrade-adversarial-review.md`), a third `scratch` mode would collide with the Phase 0 blast-radius floor — /build must never run in a repo it cannot audit for auth, schema, security, or tenant work.
+
+- **full** — git repo + gh auth + Playwright MCP + network. Full chain runs through Phase 7.
+- **degrade-with-note** — one or more capabilities missing. /build emits the spec and a plain-language note ("cd into a git repo with gh auth before /build") and exits. No PR attempt.
+
+The blast-radius floor at Phase 0 is not overridable by mode dispatch (spec Req 10 per `docs/specs/2026-09-23-graceful-degrade-skills.md`). The floor holds forever.
+
+The mode picker short-circuits `probe_network` when other probes already downgrade the mode (RFC C2 folded).
+
+```bash
+source "${BASSCLEF_DIR:-$REPO_ROOT}/lib/capability-probe.sh"
+
+probe_git; GIT=$?
+probe_mcp_playwright; MCP=$?
+probe_gh_auth; GH=$?
+
+if [ $GIT -eq 0 ] && [ $MCP -eq 0 ] && [ $GH -eq 0 ]; then
+  probe_network; NET=$?
+else
+  NET=1
+fi
+
+G=$([ $GIT -eq 0 ] && echo 1 || echo 0)
+M=$([ $MCP -eq 0 ] && echo 1 || echo 0)
+H=$([ $GH  -eq 0 ] && echo 1 || echo 0)
+N=$([ $NET -eq 0 ] && echo 1 || echo 0)
+
+# /build collapses the three-value probe into its two modes:
+# full requires all four; anything else is degrade-with-note.
+LIB_MODE=$(resolve_mode "$G" "$H" "$M" "$N")
+if [ "$LIB_MODE" = "full" ]; then
+  MODE="full"
+else
+  MODE="degrade-with-note"
+fi
+
+announce_mode "$MODE" "/build"
+
+if [ "$MODE" = "degrade-with-note" ]; then
+  echo "" >&2
+  echo "/build: environment does not support the full chain." >&2
+  echo "  - git present? $([ $GIT -eq 0 ] && echo yes || echo no)" >&2
+  echo "  - gh authed? $([ $GH -eq 0 ] && echo yes || echo no)" >&2
+  echo "  - Playwright MCP loaded? $([ $MCP -eq 0 ] && echo yes || echo no)" >&2
+  echo "  - network reachable? $([ $NET -eq 0 ] && echo yes || echo no)" >&2
+  echo "" >&2
+  echo "Emitting the spec at docs/specs/<slug>.md. cd into a git repo with gh auth to run the full chain." >&2
+  exit 0
+fi
+```
+
 ### Phase -1 — Pre-flight (per bassclef#408)
 
+Fires only when Phase −1a picked `full` mode. In `degrade-with-note` mode the skill already exited at Phase −1a.
+
 Before Phase 0 (which is /build's blast-radius floor refusal), source
 the shared pre-flight helper to surface workflow prerequisites:
 

package/dist/lite/.claude/skills/launch/SKILL.md

@@ -1,7 +1,7 @@
 ---
 tier: lite
 name: launch
-description: "Compare variants of an idea. Ships a mock gallery with an Anthropic baseline. You pick a direction from the phone. Get the spec plus user stories. Get the decomposition plus a migration plan. Two sizes: medium and full."
+description: "Compare variants of an idea. Get a mock gallery. Pick a direction. Get a spec, user stories, and a plan to build. Two sizes \u2014 medium and full. Three modes \u2014 full, local, scratch."
 problem: "An idea is a doc. A working feature is code. The gap in between is where projects stall."
 value: "Turns an idea into a buildable plan \u2014 mock gallery and spec and INVEST stories. Ready for /build."
 inputs: [A rough idea or ticket or canvas]
@@ -9,6 +9,7 @@ outputs: [Clickable mock gallery, Buildable spec, INVEST user stories, GRASP res
 user_invocable: true
 disable_model_invocation: false
 sizes: [medium, full]
+modes: [full, local, scratch]
 composes_baseline: anthropic-frontend-design
 ---
 
@@ -97,8 +98,49 @@ Per `.claude/rules/adr-discipline.md`. Mechanism: `adr-discipline-check.sh` fire
 
 ## Procedure
 
+### Phase −1a — Capability probe (per bassclef-upstream#1909)
+
+Source `lib/capability-probe.sh` and pick a mode. Three modes: **full**, **local**, **scratch**. Modes are orthogonal to the existing `--brownfield`, `--reuse-artifact`, and `--local` deploy flags (RFC H3 folded per `docs/rfcs/2026-09-23-graceful-degrade-adversarial-review.md`).
+
+- **full** — git repo + gh auth + Playwright MCP + network. Full chain runs.
+- **local** — git repo present. No PR, no screenshots. Composer-preflight skips the deploy-host check.
+- **scratch** — no git repo. Writes to a tmp dir. Composer-preflight skips entirely; only Phase 1 (interpret-input) and Phase 4 (riff-prototypes) run.
+
+The mode picker short-circuits `probe_network` when other probes already downgrade the mode below `full` (RFC C2 folded).
+
+```bash
+source "${BASSCLEF_DIR:-$REPO_ROOT}/lib/capability-probe.sh"
+
+probe_git; GIT=$?
+probe_mcp_playwright; MCP=$?
+probe_gh_auth; GH=$?
+
+if [ $GIT -eq 0 ] && [ $MCP -eq 0 ] && [ $GH -eq 0 ]; then
+  probe_network; NET=$?
+else
+  NET=1
+fi
+
+G=$([ $GIT -eq 0 ] && echo 1 || echo 0)
+M=$([ $MCP -eq 0 ] && echo 1 || echo 0)
+H=$([ $GH  -eq 0 ] && echo 1 || echo 0)
+N=$([ $NET -eq 0 ] && echo 1 || echo 0)
+
+MODE="${OVERRIDE_MODE:-$(resolve_mode "$G" "$H" "$M" "$N")}"
+validate_mode "$MODE" "$G" "$H" "$M" "$N" || exit 1
+announce_mode "$MODE" "/launch"
+
+if [ "$MODE" = "scratch" ]; then
+  echo "launch: scratch mode — Phase −1 (composer prerequisites) skipped; no git repo, no deploy chain" >&2
+fi
+```
+
+Operator override reads `--mode=<name>` from argv. The parser validates the requested mode against the environment before dispatch. Requested `full` without gh auth exits with a plain-language error.
+
 ### Phase -1 — Pre-flight (per bassclef#408 + bassclef#449/#450)
 
+Runs only when Phase −1a picked `full` or `local`. Skipped entirely in `scratch` mode.
+
 Source the shared pre-flight helper and surface all 6 prerequisites
 upfront. Pass `--no-launch` if the dispatch is variants-only (no
 `/launch-preview` chain expected); the deploy-host check (Check 6)

package/dist/lite/.claude/skills/riff/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: riff
-description: "Produce 2-3 clickable mock alternatives for a UI surface. Includes an Anthropic baseline. Each mock uses a different luminary lens. One picks a marketing variant. Another picks a build direction. Combines /interpret-input + /luminary + /stage + /visual-review."
-problem: "Design directions get one variant and no comparison. Operator picks blind. Rework is huge."
-value: "Two or three clickable mocks per UI surface. Each mock pins a different luminary lens."
+description: "Produce 2 or 3 clickable mock variants. Each pins a luminary lens. Three modes — full, local, scratch. Full uses git, gh, and screenshots. Local writes to disk only. Scratch uses a tmp dir with no git."
+problem: "Design work gets one variant. No comparison. The operator picks blind. Rework is heavy."
+value: "Two or three mocks per surface. Each mock pins a luminary lens. Cold adopters see a result in five minutes."
 inputs: [A UI surface intent or design goal]
 outputs: [2-3 clickable mock variants, Luminary lens per variant]
 tier: lite
 user_invocable: true
 disable_model_invocation: false
+modes: [full, local, scratch]
 composes_with: [interpret-input, luminary, visual-review]
 ---
 
@@ -70,15 +71,55 @@ Standard adopters can bypass `/riff`. They invoke `/stage` directly for the full
 
 Per canvas `docs/canvases/2026-08-02-porcelain-plumbing-reframe.md` — 10 of 10 luminaries agreed on the reframe.
 
+## Modes (per bassclef-upstream#1909)
+
+Three modes let the skill run in any environment:
+
+- **full** — git repo + gh auth + Playwright MCP + network. Ships PR + screenshots.
+- **local** — git repo present. No PR. No screenshots. Artifacts land on disk.
+- **scratch** — no git. Writes to a tmp dir. No PR. No screenshots. Fastest path for cold adopters.
+
+Cold adopters typing `/riff` on a fresh Saturday hit **local** or **scratch** by default. They see a viewable result. No BLOCK on missing MCP.
+
+The mode picker sits at Phase −1. It reads four probes from `lib/capability-probe.sh`. It picks the highest-fidelity mode the environment supports. Operator can override with `--mode=<name>`. The picker validates the requested mode's requirements. If a required capability is missing, the parser exits with a plain-language error.
+
 ## Procedure
 
+0. **Phase −1 — pick the mode.** Source the probe lib. Read four capability probes. Resolve a mode. Announce it. This step short-circuits `probe_network` when the other three probes already downgrade the mode below `full` (RFC C2 folded).
+
+   ```bash
+   source "${BASSCLEF_DIR:-$REPO_ROOT}/lib/capability-probe.sh"
+
+   probe_git; GIT=$?
+   probe_mcp_playwright; MCP=$?
+   probe_gh_auth; GH=$?
+
+   # Short-circuit: only probe network when other capabilities support full mode
+   if [ $GIT -eq 0 ] && [ $MCP -eq 0 ] && [ $GH -eq 0 ]; then
+     probe_network; NET=$?
+   else
+     NET=1
+   fi
+
+   # Convert exit codes to booleans (0 = present)
+   G=$([ $GIT -eq 0 ] && echo 1 || echo 0)
+   M=$([ $MCP -eq 0 ] && echo 1 || echo 0)
+   H=$([ $GH  -eq 0 ] && echo 1 || echo 0)
+   N=$([ $NET -eq 0 ] && echo 1 || echo 0)
+
+   # Operator override reads --mode=<name>; parser validates before dispatch
+   MODE="${OVERRIDE_MODE:-$(resolve_mode "$G" "$H" "$M" "$N")}"
+   validate_mode "$MODE" "$G" "$H" "$M" "$N" || exit 1
+   announce_mode "$MODE" "/riff"
+   ```
+
 1. Parse the operator's input via `/interpret-input`. Output: normalized InputArtifact.
 2. Pick 2-3 luminary lenses. Either operator-named or via `/luminary` picker.
-3. For each lens: author a static HTML mock. Path: `docs/prototypes/YYYY-MM-DD-riff-<slug>-variant-N/index.html`. Stubbed data. Include a `<h2>` naming the lens.
-4. Screenshot each variant via Playwright MCP. Save under `.playwright-mcp/`.
-5. Assemble a gallery page. Link every variant. Show screenshots inline. Show luminary tags.
-6. Run `/visual-review` on each variant. Report findings per variant.
-7. Present the gallery URL to the operator. Operator picks. Picked variant flows into `/build` or `/launch` at standard.
+3. For each lens: author a static HTML mock. Path in `full` and `local` modes: `docs/prototypes/YYYY-MM-DD-riff-<slug>-variant-N/index.html`. Path in `scratch` mode: `${TMPDIR:-/tmp}/riff-<slug>-variant-N/index.html`. Stubbed data. Include a `<h2>` naming the lens.
+4. **Screenshots — mode-gated.** In `full` mode, screenshot each variant via Playwright MCP and save under `.playwright-mcp/`. In `local` and `scratch` modes, skip this step and note in the gallery output that screenshots are absent because the environment did not have Playwright MCP.
+5. Assemble a gallery page. Link every variant. Show screenshots inline when present. Show luminary tags in every mode.
+6. Run `/visual-review` in `full` mode. In `local` and `scratch` modes, run the self-review checklist against each variant instead. Report findings per variant.
+7. Present the gallery URL to the operator. In `full` mode, open a PR. In `local` mode, print the disk path. In `scratch` mode, print the tmp path and a note that the gallery does not survive reboot. Picked variant flows into `/build` or `/launch` at standard.
 
 ## Baseline composition
 
@@ -93,11 +134,12 @@ Per canvas `docs/canvases/2026-08-02-porcelain-plumbing-reframe.md` — 10 of 10
 
 ## Rules
 
-- MUST produce a PR. Push to a feature branch, not main.
-- MUST run on a feature branch.
-- MUST screenshot every variant via Playwright MCP. BLOCK if MCP not enabled.
-- MUST tag each variant with its luminary lens in the HTML.
-- MUST report per-variant `/visual-review` findings with the gallery link.
+- MUST produce a PR when running in `full` mode. Push to a feature branch, not main.
+- MUST run on a feature branch when git is present. Scratch mode has no branch.
+- MUST screenshot every variant via Playwright MCP when running in `full` mode. In `local` and `scratch` modes, skip screenshots and note the reason in the gallery output. (Per bassclef-upstream#1909 — the prior BLOCK broke cold adopters.)
+- MUST tag each variant with its luminary lens in the HTML in every mode.
+- MUST report per-variant `/visual-review` findings in `full` mode. In `local` and `scratch` modes, run the self-review checklist and report findings the same way.
+- MUST print the mode announcement line at Phase −1. STDOUT stays untouched; the line prints to STDERR so parsers stay clean (RFC R1 folded per `docs/risk-ledgers/2026-09-23-graceful-degrade.md`).
 
 ## Refs
 

package/dist/lite/bassclef-version.json

@@ -1,7 +1,7 @@
 {
-  "version": "v1.3.0",
-  "marker_tag": "release-2026-09-23-8f764ed8",
-  "release_date": "2026-09-23T00:10:17Z",
-  "release_sha": "8f764ed8",
-  "release_tag": "release-2026-09-23-8f764ed8"
+  "version": "v1.5.1",
+  "marker_tag": "release-2026-09-24-c4fa9e65",
+  "release_date": "2026-09-24T16:59:30Z",
+  "release_sha": "c4fa9e65",
+  "release_tag": "release-2026-09-24-c4fa9e65"
 }

package/dist/lite/lib/capability-probe.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# tier: lite
+# lib/capability-probe.sh — capability probe deep module.
+#
+# Per @luminary john-ousterhout deep module: hides several probe strategies
+# behind a narrow interface. Downstream SKILLs source this lib and ask what
+# mode fits the environment. Probe strategies can change without touching
+# any SKILL.
+#
+# Exposed functions:
+#   probe_git()             — 0 inside git repo, 1 otherwise
+#   probe_gh_auth()         — 0 when authenticated to GitHub, 1 otherwise
+#   probe_mcp_playwright()  — 0 when Playwright MCP loaded, 1 otherwise
+#   probe_network()         — 0 when network reachable, 1 otherwise (or OFFLINE=1)
+#   resolve_mode g gh m n   — echoes "full" | "local" | "scratch"
+#   validate_mode m g gh m n — 0 if mode requirements met, 1 otherwise
+#   announce_mode m skill   — prints "<skill>: running in <m> mode — <reason>" to stderr
+#
+# Per bassclef-upstream#1909 + spec docs/specs/2026-09-23-graceful-degrade-skills.md.
+# Every probe fail-soft. Never throws.
+
+# --- Individual probes -------------------------------------------------------
+
+probe_git() {
+  # Short-circuit if git binary absent
+  command -v git >/dev/null 2>&1 || return 1
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    return 0
+  fi
+  return 1
+}
+
+probe_gh_auth() {
+  # Fast path: token env vars indicate auth intent + presence.
+  if [ -n "${GH_TOKEN:-}" ] || [ -n "${GITHUB_TOKEN:-}" ]; then
+    return 0
+  fi
+  # Slow path: gh CLI must be present + authenticated.
+  command -v gh >/dev/null 2>&1 || return 1
+  if gh auth status >/dev/null 2>&1; then
+    return 0
+  fi
+  return 1
+}
+
+probe_mcp_playwright() {
+  # V1 heuristic — env var contract. V2 may read tool inventory.
+  [ -n "${CLAUDE_MCP_PLAYWRIGHT:-}" ] && return 0
+  return 1
+}
+
+probe_network() {
+  # Short-circuit: OFFLINE=1 skips the wire call entirely.
+  [ -n "${OFFLINE:-}" ] && return 1
+  command -v curl >/dev/null 2>&1 || return 1
+  if curl -sSf --max-time 2 "${BASSCLEF_NETWORK_PROBE_URL:-https://api.github.com/zen}" >/dev/null 2>&1; then
+    return 0
+  fi
+  return 1
+}
+
+# --- Mode resolution ---------------------------------------------------------
+
+# resolve_mode <git> <gh> <mcp> <network>
+# Each arg is "0" or "1" per the probe result convention (1 = capability present).
+# Prints one of: "full" | "local" | "scratch".
+resolve_mode() {
+  local git="${1:-0}" gh="${2:-0}" mcp="${3:-0}" net="${4:-0}"
+  if [ "$git" = "1" ] && [ "$gh" = "1" ] && [ "$mcp" = "1" ] && [ "$net" = "1" ]; then
+    echo "full"
+  elif [ "$git" = "1" ]; then
+    echo "local"
+  else
+    echo "scratch"
+  fi
+}
+
+# validate_mode <mode> <git> <gh> <mcp> <net>
+# Returns 0 when the mode's requirements are met, 1 otherwise.
+# Stderr names the missing capability on failure.
+validate_mode() {
+  local mode="${1:-}" git="${2:-0}" gh="${3:-0}" mcp="${4:-0}" net="${5:-0}"
+  case "$mode" in
+    full)
+      [ "$git" = "1" ] || { echo "validate_mode: full requires git (not present)" >&2; return 1; }
+      [ "$gh"  = "1" ] || { echo "validate_mode: full requires gh auth (not present)" >&2; return 1; }
+      [ "$mcp" = "1" ] || { echo "validate_mode: full requires MCP (CLAUDE_MCP_PLAYWRIGHT not set)" >&2; return 1; }
+      [ "$net" = "1" ] || { echo "validate_mode: full requires network (probe failed)" >&2; return 1; }
+      return 0
+      ;;
+    local)
+      [ "$git" = "1" ] || { echo "validate_mode: local requires git (not present)" >&2; return 1; }
+      return 0
+      ;;
+    scratch)
+      return 0
+      ;;
+    *)
+      echo "validate_mode: '$mode' is not a valid mode (expected: full | local | scratch)" >&2
+      return 1
+      ;;
+  esac
+}
+
+# --- Announcement ------------------------------------------------------------
+
+# announce_mode <mode> <skill-name>
+# Prints one line to stderr naming the picked mode and the reason.
+# Honors SKIP_MODE_ANNOUNCE=1 to suppress the line (useful for scripted runs).
+# STDOUT is untouched — parsers relying on STDOUT stay clean (R1 folded).
+announce_mode() {
+  [ -n "${SKIP_MODE_ANNOUNCE:-}" ] && return 0
+  local mode="${1:-}" skill="${2:-}"
+  local reason
+  case "$mode" in
+    full)    reason="all capabilities present" ;;
+    local)   reason="one or more of gh, MCP, or network missing; disk-only" ;;
+    scratch) reason="no git repo detected; using scratch dir" ;;
+    *)       reason="unknown mode" ;;
+  esac
+  echo "${skill}: running in \`${mode}\` mode — ${reason}. Say \`--mode=<other>\` to override." >&2
+}
+
+# --- Lib self-check on source ------------------------------------------------
+# Per R13 folded (Nygard stability): a broken lib should not silently return
+# FALSE for everything. Emit a WARN if any required function is missing.
+__bassclef_capability_probe_self_check() {
+  local missing=""
+  local f
+  for f in probe_git probe_gh_auth probe_mcp_playwright probe_network resolve_mode validate_mode announce_mode; do
+    type -t "$f" >/dev/null 2>&1 || missing="$missing $f"
+  done
+  if [ -n "$missing" ]; then
+    echo "WARN: lib/capability-probe.sh is missing functions:$missing" >&2
+    return 1
+  fi
+  return 0
+}
+
+__bassclef_capability_probe_self_check || true

package/dist/lite/presence/install/bassclef-sync.template.sh

@@ -256,6 +256,42 @@ bassclef_sync_parse_whereami_ts() {
   return 0
 }
 
+# === #1929 — postcondition emitter (RESTORED/DEGRADED + JSON) ===
+# Mirrors .claude/hooks/bassclef-sync.sh L215-243 (idempotent-complete-or-fail-loud
+# pattern shipped under #1894 Cure 1 of #1691). Reads globals INSTALLED_COUNT,
+# FAILED_COUNT, SKIPPED_INVALID, SKIPPED_TOTAL, missing_paths[], missing_scopes[]
+# set by the install loop below. Emits exactly one human line + one JSON status
+# line. Defined ABOVE the BASSCLEF_SYNC_TEST_MODE guard so tests can source and
+# invoke directly.
+#
+# Anchor luminaries — @luminary linus-torvalds (adopter contract), @luminary
+# michael-nygard (fail-loud stability), @luminary jerome-saltzer-and-michael-schroeder
+# (complete mediation across both callers).
+_template_emit_install_postcondition() {
+  local installed="${INSTALLED_COUNT:-0}"
+  local failed="${FAILED_COUNT:-0}"
+  local skipped_invalid="${SKIPPED_INVALID:-0}"
+  local skipped_total="${SKIPPED_TOTAL:-0}"
+  local total=$((installed + skipped_total + failed))
+  local defect_total=$((failed + skipped_invalid))
+
+  if [ "$defect_total" = "0" ]; then
+    # RESTORED — human line + minimal JSON status:complete
+    echo "bassclef-sync: RESTORED — $installed of $total hooks resolved at their scoped targets."
+    printf 'bassclef-sync: {"status":"complete","installed":%d}\n' "$installed"
+  else
+    # DEGRADED — human line + JSON with missing[] carrying path + scope + cure per entry
+    echo "bassclef-sync: DEGRADED — $defect_total of $total hooks did not resolve after self-heal."
+    local i missing_json="["
+    for i in "${!missing_paths[@]}"; do
+      [ "$i" -gt 0 ] && missing_json="$missing_json,"
+      missing_json="$missing_json{\"path\":\"${missing_paths[$i]}\",\"scope\":\"${missing_scopes[$i]}\",\"cure\":\"bassclef init --force\"}"
+    done
+    missing_json="$missing_json]"
+    printf 'bassclef-sync: {"status":"degraded","installed":%d,"missing":%s}\n' "$installed" "$missing_json"
+  fi
+}
+
 # === Test-mode early return (#897 Cure A) ===
 # Tests source this template to access helper functions (see
 # .claude/hooks/tests/bassclef-sync-*.test.sh). Early return under
@@ -528,25 +564,40 @@ if [ "$FETCH_DONE" = "0" ]; then
     SYNC_STATUS="freshly cloned"
     FETCH_DONE=1
   else
-    # Banner cure per sunj-labs/bassclef-upstream#1636 — friendly framing paired
-    # with the bassclef-upstream copy at `.claude/hooks/bassclef-sync.sh` L112-117.
-    # Bootstrap pair per `.claude/rules/bootstrap-pair-discipline.md`. Diagnostic
-    # paths list retained (richer than the hook copy because template supports
-    # strategies A/B/D as well as C).
-    echo "### Bassclef sync — full-tier not synced"
-    echo ""
-    echo "Optional: set up GitHub auth to sync the full bassclef substrate."
-    echo "Lite tier works without it — your session is fine."
-    echo "Skills / rules / agents beyond lite become available once sync succeeds."
-    echo ""
-    echo "Paths attempted:"
-    echo "  - peer (\$CWD/../bassclef): not present"
-    if [ "$IS_EPHEMERAL" = "1" ]; then
-      echo "  - HTTP API (.bassclef-source.json): $([ -f "$CWD/.bassclef-source.json" ] && echo "file present but Strategy D fell through (see [bassclef-sync] stderr lines above for reason)" || echo "file missing; run /onboard-repo to write one, or set up .bassclef-url as fallback")"
-      echo "  - S3 (.bassclef-url): $([ -f "$CWD/.bassclef-url" ] && echo "file present but Strategy B fell through" || echo "file missing; run bassclef-s3-publish workflow or merge pending sync PR")"
-    fi
-    echo "  - bash clone: failed (private repo, no credentials)"
-    echo ""
+    # v1.5.1 refactor (bassclef-upstream#1935 epic + peer bassclef-cli-aa diagnostic on
+    # @thebassclef/lite@1.9.0 2026-09-24): the pre-v1.5.1 stdout banner ("### Bassclef sync
+    # — full-tier not synced" + Optional-auth prose + Paths attempted list) was fired on
+    # every cold-adopter SessionStart. Norman lens (adversarial RFC 2026-09-24): a loud
+    # banner on a working state trains adopters to ignore banners.
+    #
+    # New shape per operator direction 2026-09-24:
+    #   stdout — one-line RESTORED acknowledgment + JSON contract (peer #1510 harness reads)
+    #   stderr — [bassclef-sync] diagnostic lines (advanced adopters + operator trace)
+    #
+    # Cures the #1929 tail defect (postcondition emit unreachable on this branch — see
+    # peer's docker-smoke against v1.9.0) in the same edit.
+    {
+      echo "[bassclef-sync] Strategy A (peer $CWD/../bassclef): not present"
+      if [ "$IS_EPHEMERAL" = "1" ]; then
+        if [ -f "$CWD/.bassclef-source.json" ]; then
+          echo "[bassclef-sync] Strategy D (.bassclef-source.json): config present but fetch fell through (see prior [bassclef-sync] stderr lines)"
+        else
+          echo "[bassclef-sync] Strategy D (.bassclef-source.json): config missing"
+        fi
+        if [ -f "$CWD/.bassclef-url" ]; then
+          echo "[bassclef-sync] Strategy B (.bassclef-url): URL file present but fetch fell through"
+        else
+          echo "[bassclef-sync] Strategy B (.bassclef-url): URL file missing"
+        fi
+      fi
+      echo "[bassclef-sync] Strategy C (git clone $BASSCLEF_REPO): failed (no network, no git, or auth required)"
+    } >&2
+
+    _clone_fail_hook_count=$(find "$CWD/.claude/hooks" -maxdepth 1 -name '*.sh' 2>/dev/null | wc -l | tr -d ' ')
+    echo "bassclef-sync: RESTORED — lite bundle in place."
+    printf 'bassclef-sync: {"status":"complete","installed":%d}\n' "$_clone_fail_hook_count"
+    unset _clone_fail_hook_count
+
     exit 0
   fi
 fi
@@ -898,6 +949,9 @@ SKIPPED_NO_HEADER=0
 SKIPPED_INVALID=0
 SKIPPED_LIB_MISSING=0
 FAILED_COUNT=0
+# #1929 — missing[] capture for RESTORED/DEGRADED postcondition
+missing_paths=()
+missing_scopes=()
 
 mkdir -p "$HOME/.claude/hooks" 2>/dev/null || true
 
@@ -933,6 +987,8 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
       if [ -n "$_WALKER_MISS" ]; then
         echo "$(date -u +%FT%TZ) install-fail-missing-dep $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
         FAILED_COUNT=$((FAILED_COUNT + 1))
+        missing_paths+=(".claude/hooks/$HOOK_NAME")
+        missing_scopes+=("operator")
         continue
       fi
 
@@ -947,6 +1003,8 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
         chmod +x "$TARGET_USER" 2>/dev/null || true
         echo "$(date -u +%FT%TZ) dispatch-fail $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
         FAILED_COUNT=$((FAILED_COUNT + 1))
+        missing_paths+=(".claude/hooks/$HOOK_NAME")
+        missing_scopes+=("operator")
       fi
     elif [ "$HAS_HEADER" = "1" ] && [ "$DISPATCH_AVAILABLE" = "0" ]; then
       # S-F1 MED — dispatch lib missing; trace explicitly (not silent)
@@ -965,6 +1023,8 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
       else
         echo "$(date -u +%FT%TZ) skipped-invalid-header $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
         SKIPPED_INVALID=$((SKIPPED_INVALID + 1))
+        missing_paths+=(".claude/hooks/$HOOK_NAME")
+        missing_scopes+=("operator")
       fi
     fi
   done
@@ -1005,6 +1065,12 @@ fi
 
 # N-F1 MED — install summary with reason breakdown when non-zero
 SKIPPED_TOTAL=$((SKIPPED_NO_HEADER + SKIPPED_INVALID + SKIPPED_LIB_MISSING))
+
+# #1929 — RESTORED/DEGRADED + JSON postcondition (mirrors operator hook L215-243).
+# Retains the legacy breakdown line for adopters parsing the old shape.
+_template_emit_install_postcondition
+
+# RFC-0008 F7 legacy — plain-English breakdown line preserved for parser contract.
 if [ "$SKIPPED_TOTAL" = "0" ] && [ "$FAILED_COUNT" = "0" ]; then
   echo "bassclef-sync: installed $INSTALLED_COUNT hooks; skipped 0; failed 0"
 else

package/dist/lite/standards/bassclef-wiring-manifest.json

@@ -165,6 +165,12 @@
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-commit-identifier-leak-scrub.sh",
             "timeout": 10,
             "tier": "lite"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/git-stash-u-guard.sh",
+            "timeout": 5,
+            "tier": "lite"
           }
         ]
       },

package/dist/lite/standards/lite-manifest-schema-changes.md

@@ -34,6 +34,15 @@ Every entry stays in this file for the life of the manifest. Never pruned. When
 
 ## Entries (newest first)
 
+### Track 1 v1.5.1 — bassclef-sync clone-fail postcondition emit + banner-to-stderr (v1.11.0 → v1.11.1, 2026-09-24)
+
+- **Change type:** content-change (1 file: `bassclef-sync-template`)
+- **Fields:** 434 entries (unchanged from v1.11.0). Content hash shifts on the `bassclef-sync-template` slug — `presence/install/bassclef-sync.template.sh` gains a postcondition emit block before the L586 clone-fail exit, plus moves the prior multi-line stdout banner to stderr with `[bassclef-sync]` prefix.
+- **Version bump:** v1.11.0 → v1.11.1 (content_hash change only → patch bump per policy).
+- **Rationale:** #1929 tail cure — postcondition emit was unreachable on the clone-fail branch (peer bassclef-cli-aa docker-smoke evidence 2026-09-24 against `@thebassclef/lite@1.9.0`). See PR #1936 + `docs/theses/2026-09-24-bassclef-sync-class-cure-thesis.md` + `docs/rfcs/RFC-2026-09-24-parallel-sync-adversarial.md`.
+- **Downstream cure:** none required. Adopters see one-line `bassclef-sync: RESTORED — lite bundle in place.` on stdout on cold-adopter runs (was multi-line "### Bassclef sync — full-tier not synced" banner). Paths-attempted debug moves to stderr with `[bassclef-sync]` prefix — accessible via `2>&1`. Peer #1510 harness can now grep `RESTORED` on the cold-adopter path to verify cure landing.
+- **Old shape retired:** immediately. The pre-v1.5.1 banner had a factual error (called the public bassclef repo "private" at L584) — no adopters had a stable contract to break.
+
 ### Q1 /longrun Slice D — session-start banner-tone discipline (v1.9.10 → v1.9.11, 2026-09-22)
 
 - **Change type:** content-add (1 new standard) + content-change (session-reflection.sh + 3 fragments)

package/dist/lite/standards/lite-manifest.json

@@ -1,7 +1,7 @@
 {
   "tier": "lite",
-  "manifest_version": "1.9.14",
-  "generated_at": "2026-09-22T23:10:32Z",
+  "manifest_version": "1.11.1",
+  "generated_at": "2026-09-24T15:21:28Z",
   "entries": [
     {
       "slug": "029-release-pipeline",
@@ -91,6 +91,14 @@
       "content_hash": "sha256:732f8c5a9c2e206f55246aafbdd7fd5c2fa2a154b37b7281b238f0b1175e1ba0",
       "description": "00-bassclef-hook-connect.sh — Auto-connect bassclef hooks to adopter settings.json."
     },
+    {
+      "slug": "01-adopter-message-channel",
+      "type": "hook",
+      "path": ".claude/hooks/session-reflection.d/01-adopter-message-channel.sh",
+      "tier": "lite",
+      "content_hash": "sha256:c2831a9400ef8cacc4d79ed4bb3c8696a1b89826c7a9ece52e373a2c30f36e8c",
+      "description": "SessionStart fragment — adopter message channel (bassclef-upstream#1926)"
+    },
     {
       "slug": "05-active-bet",
       "type": "hook",
@@ -387,6 +395,14 @@
       "content_hash": "sha256:c923c8081ce4055060ac9d3e2f0a6a7f245087b96098a5c610196d74fc5ba97b",
       "description": "file-rename-discipline-check — PreToolUse hook that blocks `git commit`"
     },
+    {
+      "slug": "git-stash-u-guard",
+      "type": "hook",
+      "path": ".claude/hooks/git-stash-u-guard.sh",
+      "tier": "lite",
+      "content_hash": "sha256:23e45017aa058d6110a327e5e74a70233333b64a0d9c09c5f03549fb58c42add",
+      "description": "PreToolUse: Bash"
+    },
     {
       "slug": "hook-classifier-canary",
       "type": "hook",
@@ -723,6 +739,14 @@
       "content_hash": "sha256:10d42c54a64415f7e9b4f2a6701d57ffc89cc9d59ec0fec9ddc2af3c178855a2",
       "description": "bassclef-dir-resolver.sh — resolve BASSCLEF_DIR across install layouts."
     },
+    {
+      "slug": "capability-probe",
+      "type": "lib",
+      "path": "lib/capability-probe.sh",
+      "tier": "lite",
+      "content_hash": "sha256:12d4d7cfa78bd07e1f67a405a88b960ac62ac637297698d8ca43f217b74f4de0",
+      "description": "lib/capability-probe.sh — capability probe deep module."
+    },
     {
       "slug": "clean-artifacts-sweep",
       "type": "lib",
@@ -1295,7 +1319,7 @@
       "type": "presence-template",
       "path": "presence/install/bassclef-sync.template.sh",
       "tier": "lite",
-      "content_hash": "sha256:0a689f73d94bb78d1a3e7fdb3cda760e093db1d7536548cb05cf3a9ea9fb4c6c",
+      "content_hash": "sha256:d79a9a6499c1bcaa368e0472f7a9cd76611f2dbdb8ab2b42533c3f85de2323c4",
       "description": "description: BASSCLEF_SYNC_VERSION=2026-09-06-1496-sessionstart-heal-v1"
     },
     {
@@ -2146,8 +2170,8 @@
       "type": "skill",
       "path": ".claude/skills/build/SKILL.md",
       "tier": "lite",
-      "content_hash": "sha256:be80d5fb771cf7665f7db67f8089229620b14b3e7757c298e516acf488680aaa",
-      "description": "Take a buildable plan and ship it. Reads a spec from /launch. Dispatches a builder per user story. Runs /verify. Opens PRs. Gates prod deploy on a human. Refuses auth, schema, security, and tenant work. --explain narrates first.",
+      "content_hash": "sha256:ef8f6b7872a29f74e8a9c181ab0b7c24f7c93bfc76b05baaf4cee4703318b10c",
+      "description": "Take a plan from /launch and ship it. One builder per user story. Runs /verify. Opens PRs. Gates prod on a human. Refuses auth, schema, security, and tenant work. Two modes — full and degrade-with-note.",
       "inputs": [
         "A goal slug pointing to a spec on disk"
       ],
@@ -2534,8 +2558,8 @@
       "type": "skill",
       "path": ".claude/skills/launch/SKILL.md",
       "tier": "lite",
-      "content_hash": "sha256:a99fd150c677290ef82423318cab4ff8abcda109a2b2c2371847b53e026cd17e",
-      "description": "Compare variants of an idea. Ships a mock gallery with an Anthropic baseline. You pick a direction from the phone. Get the spec plus user stories. Get the decomposition plus a migration plan. Two sizes: medium and full.",
+      "content_hash": "sha256:35763f40fe046500da02f8d37ff4e6984e18ab08b64ed0eaa3c4095d90a22225",
+      "description": "Compare variants of an idea. Get a mock gallery. Pick a direction. Get a spec, user stories, and a plan to build. Two sizes — medium and full. Three modes — full, local, scratch.",
       "inputs": [
         "A rough idea or ticket or canvas"
       ],
@@ -2910,8 +2934,8 @@
       "type": "skill",
       "path": ".claude/skills/riff/SKILL.md",
       "tier": "lite",
-      "content_hash": "sha256:e2a6a45f05df1e7cbc8138fbdcbc9ddf169aaf3b32fd5824b410912412fab0c4",
-      "description": "Produce 2-3 clickable mock alternatives for a UI surface. Includes an Anthropic baseline. Each mock uses a different luminary lens. One picks a marketing variant. Another picks a build direction. Combines /interpret-input + /luminary + /stage + /visual-review.",
+      "content_hash": "sha256:c481ce52be01c6d5e62e8ea07389e7612362b77721228fb59cd1c1c469f327ff",
+      "description": "Produce 2 or 3 clickable mock variants. Each pins a luminary lens. Three modes — full, local, scratch. Full uses git, gh, and screenshots. Local writes to disk only. Scratch uses a tmp dir with no git.",
       "composes_with": [
         "interpret-input",
         "luminary",
@@ -2924,8 +2948,8 @@
         "2-3 clickable mock variants",
         "Luminary lens per variant"
       ],
-      "problem": "Design directions get one variant and no comparison. Operator picks blind. Rework is huge.",
-      "value": "Two or three clickable mocks per UI surface. Each mock pins a different luminary lens."
+      "problem": "Design work gets one variant. No comparison. The operator picks blind. Rework is heavy.",
+      "value": "Two or three mocks per surface. Each mock pins a luminary lens. Cold adopters see a result in five minutes."
     },
     {
       "slug": "riff-prototypes",
@@ -3737,7 +3761,7 @@
       "type": "standard",
       "path": "standards/lite-manifest-schema-changes.md",
       "tier": "lite",
-      "content_hash": "sha256:17f5c69efd97240348b6f74d35b200400c2817f7e303eb288b027fbb2bb38991",
+      "content_hash": "sha256:bccea2ce3acc450f35729690e7c24706391c87186ce99ece91e574a8f4686c58",
       "description": "Chronological ledger of every lite-manifest schema change. Adopters read this before sync to know what shifted."
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebassclef/lite",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Bassclef CLI — install and upgrade bassclef in your project with two commands.",
   "keywords": [
     "bassclef",