@thebassclef/lite 1.7.0 → 1.9.0

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.7.0<!-- version-end -->
+<!-- version-start -->1.9.0<!-- 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.7.0";
+const version = "1.9.0";
 exports.version = version;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.7.0";
+const version = "1.9.0";
 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/80-hook-heartbeat-check.sh

@@ -28,18 +28,57 @@ if [ "${SELF_MODE:-0}" = "1" ]; then
   return 0 2>/dev/null || exit 0
 fi
 
-# Fresh-install gate (#1818 Ship 3): if state/markers/hook-heartbeat/ does
-# not exist, no producer has ever called heartbeat_mark on this machine, so
-# no hook can be "stale" — a fresh install has no heartbeat history to check
-# against. Skip silently. Cold adopters see no false "never fired" banner
-# on their first skill run. The gate activates the moment a producer hook
-# fires and writes its first marker.
+# Fresh-install gate — two layers close the #1895 self-defeat class:
+#
+#   Layer 1: state/markers/hook-heartbeat/ does not exist — no producer has
+#     ever called heartbeat_mark on this machine. Skip silently. Cold
+#     adopters see no false "never fired" banner on their first skill run.
+#
+#   Layer 2: dir exists BUT the oldest marker is younger than the grace
+#     window (default 24h). The install is still bootstrapping — the FIRST
+#     producer fire creates the dir + first marker, but critical hooks that
+#     have not had their trigger event yet would show "never fired." Sam
+#     sees false-positive banner at 4-minute-old install. Cure per #1895:
+#     use oldest marker mtime as the install activation anchor. Add a
+#     wallclock grace window before "never fired" reports get treated as
+#     real defects. New markers written after the first do NOT reset the
+#     anchor (find + sort + head-1 gives the oldest).
+#
+# Override: FRESH_INSTALL_GRACE_SECONDS=0 disables the grace layer for
+# operator debugging.
+#
 # Anchor: @luminary donald-norman — a banner fires only when a real problem
-# exists. @luminary michael-nygard — fresh state is not broken state.
-if [ ! -d "state/markers/hook-heartbeat" ]; then
+# exists. Sam's user model: "I just installed this; give it time."
+# @luminary michael-nygard — fresh state is not broken state.
+# Resolve marker dir — mirror lib/hook-heartbeat.sh::_heartbeat_dir semantics
+# so tests that set HEARTBEAT_MARKER_DIR get consistent behavior.
+_HB_MARKER_DIR="${HEARTBEAT_MARKER_DIR:-state/markers/hook-heartbeat}"
+
+if [ ! -d "$_HB_MARKER_DIR" ]; then
   return 0 2>/dev/null || exit 0
 fi
 
+FRESH_INSTALL_GRACE_SECONDS="${FRESH_INSTALL_GRACE_SECONDS:-86400}"  # 24h default per #1895
+if [ "$FRESH_INSTALL_GRACE_SECONDS" -gt 0 ]; then
+  # Find oldest marker mtime — install activation anchor. Try GNU stat -c
+  # first (Linux; -f on GNU means filesystem info NOT mtime; silently returns
+  # a string that breaks arithmetic below). BSD stat -f second (macOS).
+  # Filter numeric-only output for portability safety.
+  _oldest_mtime=$(find "$_HB_MARKER_DIR" -maxdepth 1 -type f -name '*.marker' -exec stat -c %Y {} + 2>/dev/null | grep -E '^[0-9]+$' | sort -n | head -1)
+  if [ -z "$_oldest_mtime" ]; then
+    _oldest_mtime=$(find "$_HB_MARKER_DIR" -maxdepth 1 -type f -name '*.marker' -exec stat -f %m {} + 2>/dev/null | grep -E '^[0-9]+$' | sort -n | head -1)
+  fi
+  _now=$(date -u +%s)
+  # No markers yet: install has not activated any producer. Skip silently.
+  if [ -z "$_oldest_mtime" ]; then
+    return 0 2>/dev/null || exit 0
+  fi
+  # Grace window active: skip silently.
+  if [ $((_now - _oldest_mtime)) -lt "$FRESH_INSTALL_GRACE_SECONDS" ]; then
+    return 0 2>/dev/null || exit 0
+  fi
+fi
+
 # 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

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: