@thebassclef/lite 1.4.0 → 1.5.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.4.0<!-- version-end -->
+<!-- version-start -->1.5.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.4.0";
+const version = "1.5.1";
 exports.version = version;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.4.0";
+const version = "1.5.1";
 export {
   version
 };

package/dist/lite/.bassclef-source.json

@@ -3,8 +3,8 @@
   "source_repo": "sunj-labs/bassclef",
   "source_ref": "main",
   "tier": "[TIER]",
-  "auto_sync": true,
+  "auto_sync": false,
   "installed_at": "[ISO_TIMESTAMP]",
   "installed_via": "bassclef-cli",
-  "notes": "Adopter-owned config. Change `auto_sync` to `false` to pause session-start substrate refresh. Change `tier` to opt into standard or ultra (requires re-run of `bassclef init --tier <T>`). Rename docs at https://github.com/sunj-labs/bassclef."
+  "notes": "Adopter-owned config. Default `auto_sync: false` per #1820 — cli ships self-contained; live substrate fetch is opt-in. Change `auto_sync` to `true` to enable session-start substrate refresh (or say 'enable auto-sync' per .claude/rules/auto-sync-conversational-listener.md). Change `tier` to opt into standard or ultra (requires re-run of `bassclef init --tier <T>`). Docs at https://github.com/sunj-labs/bassclef."
 }

package/dist/lite/.claude/hooks/_lib/wirings.sh

@@ -0,0 +1,237 @@
+#!/bin/bash
+# tier: lite
+# Shared accessor library for hook-wiring inspection.
+# Retagged standard → lite 2026-09-21 per bassclef-upstream#1861 F1b.
+# `session-reflection.d/08-settings-drift.sh` (tier: lite) sources this
+# file. A lite-tier caller must not depend on a standard-tier lib. Cure
+# aligns tiers so `_lib/wirings.sh` ships in the lite bundle to adopters.
+#
+# Used by:
+#  - .claude/hooks/session-reflection.d/08-settings-drift.sh (WU-2 of #313)
+#  - .claude/hooks/bassclef-sync.sh self-heal block (WU-3 of #313)
+#
+# Lives in _lib/ (underscore-prefixed) so the harness does not interpret
+# this file as a hook. Per docs/decompositions/2026-06-24-adopter-update-distribution.md.
+#
+# All functions are pure: take args, emit output. No env reads beyond
+# the optional HOME / CWD_OVERRIDE knobs in read_loaded_wirings. Tier 0
+# strict TDD per .claude/rules/testing-tier-config.md.
+
+# read_required_wirings <settings_path>
+# Reads the canonical wirings list from a project-level settings.json.
+# Output: JSON array of {event, command} pairs.
+# Defaults to "[]" on missing file, invalid JSON, or empty .hooks.
+# WHY: hides the jq filter shape from callers; single place to update
+# when settings.json schema evolves.
+read_required_wirings() {
+  local settings_path="${1:-}"
+  if [ -z "$settings_path" ] || [ ! -f "$settings_path" ]; then
+    echo "[]"
+    return 0
+  fi
+  local result
+  result=$(jq -c '[
+    (.hooks // {}) | to_entries[] as $event |
+    ($event.value // []) | .[] | (.hooks // [])[]? |
+    {event: $event.key, command: (.command // "")}
+  ] | map(select(.command != ""))' "$settings_path" 2>/dev/null) || result=""
+  if [ -z "$result" ]; then
+    echo "[]"
+  else
+    echo "$result"
+  fi
+}
+
+# read_loaded_wirings
+# Reads ~/.claude/settings.json (user-scope) + <repo>/.claude/settings.json
+# (project-scope) and merges per Claude Code scope precedence: project
+# overrides user per event. Output: JSON array of {event, command} pairs
+# the harness would see.
+#
+# Env knobs (for testability):
+#   HOME (standard)             — base for user settings
+#   CWD_OVERRIDE (test-only)    — base for project settings (defaults to $PWD)
+#
+# Contract (RFC-0007 F2 + F6 — write it down so the next reader does not
+# re-derive it wrong):
+#
+#   Precondition  — none. Missing or unreadable files are handled.
+#   Postcondition — stdout is a JSON array of {event, command} pairs, one
+#                   per hook the harness will run, from BOTH scopes.
+#                   The array is a SET: a command wired at both scopes
+#                   appears once. Order follows user scope then project
+#                   scope, first occurrence wins.
+#   Return        — 0 on success. Non-zero when a settings file could not
+#                   be parsed. Callers must tell "could not read" apart
+#                   from "nothing is wired"; both print [].
+#
+# WHY additive, not replace (RFC-0007 F1): the harness loads hooks from
+# user scope and project scope together. Measured 2026-09-17 — this repo
+# declares 1 SessionStart hook in project scope and 4 in user scope, and
+# session-reflection.sh, which is user-scope only, fires every session.
+# The old code used jq's `*`, which replaces arrays, so any event named
+# in both scopes lost every user-scope entry. bassclef-sync then reported
+# those entries missing and the postcondition could never pass in a normal
+# adopter repo. See bassclef-cli#97.
+#
+# WHY: hides scope-stack resolution from the comparator. Testable via
+# env overrides.
+read_loaded_wirings() {
+  local user_settings="${HOME:-/nonexistent}/.claude/settings.json"
+  local project_base="${CWD_OVERRIDE:-${PWD}}"
+  local project_settings="${project_base}/.claude/settings.json"
+
+  local user_json="{}"
+  local project_json="{}"
+  [ -f "$user_settings" ] && user_json=$(cat "$user_settings" 2>/dev/null || echo "{}")
+  [ -f "$project_settings" ] && project_json=$(cat "$project_settings" 2>/dev/null || echo "{}")
+
+  # Per Claude Code docs (https://code.claude.com/docs/en/settings):
+  # scope precedence — project overrides user. For event entries:
+  #   * Events in BOTH: project wins (replace).
+  #   * Events only in user: keep user's.
+  #   * Events only in project: project's.
+  local result jq_rc
+  result=$(echo "$user_json $project_json" | jq -sc '
+    (.[0].hooks // {}) as $user_hooks |
+    (.[1].hooks // {}) as $project_hooks |
+    (($user_hooks | keys) + ($project_hooks | keys) | unique) as $events |
+    [
+      $events[] as $event |
+      (($user_hooks[$event] // []) + ($project_hooks[$event] // []))[] |
+      (.hooks // [])[]? |
+      {event: $event, command: (.command // "")}
+    ]
+    | map(select(.command != ""))
+    | reduce .[] as $x ([];
+        if any(.[]; .event == $x.event and .command == $x.command)
+        then . else . + [$x] end)
+  ' 2>/dev/null)
+  jq_rc=$?
+  if [ "$jq_rc" -ne 0 ] || [ -z "$result" ]; then
+    echo "[]"
+    return 1
+  fi
+  echo "$result"
+  return 0
+}
+
+# compare_wirings <required_json> <loaded_json>
+# Pure function. Diffs two JSON arrays of {event, command} pairs.
+# Output: JSON {missing: [...], extra: [...], ok: bool}
+#   missing — items in required but not in loaded (drift)
+#   extra   — items in loaded but not in required (informational)
+#   ok      — true iff missing is empty
+#
+# Command normalization — sunj-labs/bassclef-upstream#1742 cure.
+# Adopter settings.json wraps hook commands with a defensive guard shape
+# so partial-substrate consumers do not error on missing files. bassclef
+# ships plain form. The two forms are semantically equivalent — same
+# underlying command, one wrapped in an existence check. Prior version
+# did exact-string diff and reported the guarded form as missing. Now we
+# normalize before diff by stripping the guard shape plus quotes around
+# the path.
+compare_wirings() {
+  local required_json="${1:-[]}"
+  local loaded_json="${2:-[]}"
+  echo "$required_json" "$loaded_json" | jq -sc '
+    # normalize_cmd strips the guard wrapper — supports quoted and
+    # unquoted paths — so "[ -f X ] && bash X || true" becomes "bash X".
+    # Also strips the double quotes that the guard shape wraps the path in,
+    # since the plain-form required side does not quote.
+    def normalize_cmd:
+      sub("^\\[ -f (\"[^\"]+\"|[^ ]+) \\] && "; "")
+      | sub(" \\|\\| true$"; "")
+      | gsub("\""; "")
+      | sub("^bash "; "");
+
+    def normalize_entry:
+      .command |= normalize_cmd;
+
+    (.[0] | map(normalize_entry)) as $required |
+    (.[1] | map(normalize_entry)) as $loaded |
+    ([$required[] | select(. as $r | ($loaded | any(. == $r)) | not)]) as $missing |
+    ([$loaded[]   | select(. as $l | ($required | any(. == $l)) | not)]) as $extra |
+    {
+      missing: $missing,
+      extra: $extra,
+      ok: (($missing | length) == 0)
+    }
+  '
+}
+
+# read_settings_version <settings_path>
+# Output: integer (defaults to 0 when field missing, file missing, or
+# non-integer value).
+# WHY: hides the "default-to-0" + "validate-as-integer" logic; single
+# place to update when version field name evolves.
+read_settings_version() {
+  local settings_path="${1:-}"
+  if [ -z "$settings_path" ] || [ ! -f "$settings_path" ]; then
+    echo "0"
+    return 0
+  fi
+  local version
+  version=$(jq -r '.bassclef_settings_version // 0' "$settings_path" 2>/dev/null || echo "0")
+  if [[ "$version" =~ ^[0-9]+$ ]]; then
+    echo "$version"
+  else
+    echo "0"
+  fi
+}
+
+# additive_merge_settings <user_path> <project_path>
+# Merges bassclef-shipped project settings into operator's user settings.
+# Contract:
+#   - Top-level operator keys (theme, statusLine, permissions,
+#     alwaysThinkingEnabled, skipDangerousModePermissionPrompt, etc.) — PRESERVED.
+#   - .hooks — bassclef wins PER EVENT. Events present in user but not
+#     in project survive untouched. Events present in project replace
+#     the user's entries for those events.
+#   - .bassclef_settings_version — set to project's value.
+# Idempotent: running twice produces the same result.
+# Bootstrap: when user file missing, copies project file as starting point.
+# WHY: encapsulates the entire merge contract in one function callable
+# from bassclef-sync.sh AND testable in isolation. The event-level
+# merge granularity is Linus + ADR-031: bassclef governs the events it
+# ships; operator owns everything else.
+additive_merge_settings() {
+  local user_path="$1"
+  local project_path="$2"
+  if [ ! -f "$project_path" ]; then
+    return 1
+  fi
+  mkdir -p "$(dirname "$user_path")" 2>/dev/null || true
+  if [ ! -f "$user_path" ]; then
+    cp "$project_path" "$user_path"
+    # Per bassclef-upstream#340: project settings.json deliberately omits
+    # statusLine (it's user-scope). After cp, re-inject the bassclef
+    # statusLine reference when the operator's statusline script exists
+    # on disk + is executable. Without this re-injection, the cp clones
+    # the empty-statusLine state and silently drops Surface 4 aging
+    # signal. Defensive: skip injection when script missing or not
+    # executable (avoids broken reference).
+    # Env override BASSCLEF_STATUSLINE_PATH supports test fixtures.
+    local statusline_script="${BASSCLEF_STATUSLINE_PATH:-$HOME/.claude/bassclef-statusline.sh}"
+    if [ -x "$statusline_script" ] && command -v jq >/dev/null 2>&1; then
+      local tmp_status
+      tmp_status=$(mktemp)
+      if jq '.statusLine = {"type":"command", "command":"bash ~/.claude/bassclef-statusline.sh"}' \
+         "$user_path" > "$tmp_status" 2>/dev/null; then
+        mv "$tmp_status" "$user_path"
+      else
+        rm -f "$tmp_status"
+      fi
+    fi
+    return 0
+  fi
+  local tmp
+  tmp=$(mktemp)
+  jq -s '
+    (.[0]) as $user |
+    (.[1]) as $project |
+    $user
+    | .hooks = (($user.hooks // {}) + ($project.hooks // {}))
+    | .bassclef_settings_version = ($project.bassclef_settings_version // 0)
+  ' "$user_path" "$project_path" > "$tmp" && mv "$tmp" "$user_path"
+}

package/dist/lite/.claude/hooks/pre-commit-manifest-autoregen.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+# tier: lite
+# install-class: project
+# PreToolUse: Bash
+#
+# Cure 1 — pre-commit auto-regen manifest hook.
+#
+# Fires on `git commit`. Detects lite-tier file edits in the staged diff.
+# When drift is present, runs scripts/generate-lite-manifest.sh + bumps
+# the manifest_version + regenerates docs/lite-manifest.md + stages the
+# resulting diff. The commit then proceeds with a fresh manifest.
+#
+# Closes sunj-labs/bassclef-upstream#1752 (parent epic #1750).
+# Module A1 per docs/decompositions/2026-09-18-ci-cd-subsystem.md.
+# Anchor luminaries:
+#   @luminary michael-nygard — stability pattern (auto-cure at write pipeline)
+#   @luminary john-ousterhout — deep module (hides drift detection + bump)
+#   @luminary linus-torvalds — adopter contract (fail-soft when script absent)
+#
+# Adopter safety: when scripts/generate-lite-manifest.sh is missing (an
+# adopter repo without the substrate generator), the hook falls through
+# with exit 0 rather than blocking the commit. Adopters keep working.
+#
+# Override: SKIP_MANIFEST_AUTOREGEN=1 (logged via trace-helper)
+
+set -e
+
+# Observable failure trap
+# shellcheck disable=SC2154  # _ec assigned in trap context via $?
+trap '_ec=$?; if [ "$_ec" -ne 0 ]; then echo "pre-commit-manifest-autoregen.sh: FAIL at line $LINENO: exit $_ec (command: $BASH_COMMAND)" >&2; fi' ERR
+
+# Read stdin JSON, extract command; fail-soft on malformed JSON
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null || echo "")
+
+# Only fire on git commit
+if ! echo "$COMMAND" | grep -q 'git commit'; then
+  exit 0
+fi
+
+# Override path
+if [ "${SKIP_MANIFEST_AUTOREGEN:-0}" = "1" ]; then
+  # Best-effort trace log; ignore failure so hook stays exit 0
+  if command -v bash >/dev/null 2>&1 && [ -f ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "skip" "manifest-autoregen" "SKIP_MANIFEST_AUTOREGEN=1" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Find repo root; fail-soft if not in a git repo
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+if [ -z "$REPO_ROOT" ]; then
+  exit 0
+fi
+
+GENERATE_SCRIPT="$REPO_ROOT/scripts/generate-lite-manifest.sh"
+RENDER_SCRIPT="$REPO_ROOT/scripts/render-lite-manifest-doc.sh"
+MANIFEST="$REPO_ROOT/lite-manifest.json"
+
+# Adopter safety — fail-soft when script absent
+if [ ! -f "$GENERATE_SCRIPT" ]; then
+  exit 0
+fi
+
+# Get staged files; fail-soft on any git error
+STAGED=$(git diff --cached --name-only 2>/dev/null || echo "")
+if [ -z "$STAGED" ]; then
+  exit 0
+fi
+
+# Lite-tier substrate surfaces per generate-lite-manifest.sh docs:
+#   skills, rules, hooks, luminaries, agents, standards, ADRs
+# Check if any staged file lives in one of these path classes AND has
+# `tier: lite` frontmatter. Fast fail-soft — if grep unavailable, skip.
+if ! command -v grep >/dev/null 2>&1; then
+  exit 0
+fi
+
+LITE_STAGED=0
+while IFS= read -r file; do
+  [ -z "$file" ] && continue
+
+  # Quick path-class filter (avoids frontmatter reads for obviously non-lite files).
+  # Covers all 11 manifest types per bassclef-upstream#1872 widen (2026-09-21):
+  #   skills, rules, hooks, luminaries, agents, standards, ADRs,
+  #   lib, scripts, templates, presence-templates, root-docs.
+  # Note: bash case-pattern `*` matches slashes, so `.claude/hooks/*.sh` already
+  # covers subdirs like `.claude/hooks/session-reflection.d/foo.sh`. Same for
+  # `standards/*.md`. No separate subdir patterns needed.
+  # Sister refactor to path-agnostic marker check tracked at #1873.
+  case "$file" in
+    .claude/skills/*/SKILL.md \
+    | .claude/rules/*.md \
+    | .claude/hooks/*.sh \
+    | .claude/luminaries/*.md \
+    | .claude/agents/*.md \
+    | standards/*.md \
+    | architecture/decisions/ADR-*.md \
+    | lib/*.sh \
+    | scripts/*.sh \
+    | templates/*.md \
+    | presence/install/*.sh \
+    | presence/install/*.md \
+    | presence/install/*.jsonc \
+    | AGENTS.md \
+    | README.md \
+    | CLAUDE-lite.md \
+    | CODE_OF_CONDUCT.md \
+    | CONTRIBUTING.md \
+    | SECURITY.md \
+    | .claude/bassclef-orientation.md)
+      # Path class matches; check frontmatter for tier: lite (markdown YAML)
+      if [ -f "$REPO_ROOT/$file" ] && head -20 "$REPO_ROOT/$file" 2>/dev/null | grep -q '^tier: lite'; then
+        LITE_STAGED=1
+        break
+      fi
+      # Header comment shape for .sh files: `# tier: lite`
+      if [ -f "$REPO_ROOT/$file" ] && head -5 "$REPO_ROOT/$file" 2>/dev/null | grep -q '^# tier: lite'; then
+        LITE_STAGED=1
+        break
+      fi
+      # JSON root-key shape for .jsonc / .json files: `"tier": "lite"` — #1872 addition
+      if [ -f "$REPO_ROOT/$file" ] && head -3 "$REPO_ROOT/$file" 2>/dev/null | grep -q '"tier": "lite"'; then
+        LITE_STAGED=1
+        break
+      fi
+      ;;
+  esac
+done <<< "$STAGED"
+
+# No lite-tier files staged → fast exit
+if [ "$LITE_STAGED" -eq 0 ]; then
+  exit 0
+fi
+
+# Compare current manifest against fresh generation
+TMPFILE=$(mktemp)
+# shellcheck disable=SC2064  # TMPFILE expansion NOW is intended for cleanup
+trap "rm -f $TMPFILE" EXIT INT TERM
+
+if ! bash "$GENERATE_SCRIPT" --dry-run > "$TMPFILE" 2>/dev/null; then
+  # Generate failed — fail-soft; author sees CI red if drift real
+  exit 0
+fi
+
+# Diff manifests. Fail-soft on any error.
+if [ ! -f "$MANIFEST" ]; then
+  # No manifest on disk yet — regen writes it
+  DRIFT=1
+elif ! diff -q "$MANIFEST" "$TMPFILE" >/dev/null 2>&1; then
+  DRIFT=1
+else
+  DRIFT=0
+fi
+
+if [ "$DRIFT" -eq 0 ]; then
+  # No drift — clean exit
+  exit 0
+fi
+
+# Drift detected — count added/removed/modified entries for version bump
+CURRENT_VERSION=$(jq -r '.manifest_version // "0.0.0"' "$MANIFEST" 2>/dev/null || echo "0.0.0")
+
+# Extract entry keys per manifest (type + slug pair)
+OLD_KEYS=$(jq -r '.entries[] | .type + "/" + .slug' "$MANIFEST" 2>/dev/null | sort || echo "")
+NEW_KEYS=$(jq -r '.entries[] | .type + "/" + .slug' "$TMPFILE" 2>/dev/null | sort || echo "")
+
+# Bug 1 fix (#1829): counting lines via wc always exits 0 and emits a
+# single integer. Prior shape used a fallback that appended a second
+# zero on empty input, tripping the integer comparison at L153.
+ADDED=$(comm -13 <(echo "$OLD_KEYS") <(echo "$NEW_KEYS") | wc -l | tr -d ' ')
+REMOVED=$(comm -23 <(echo "$OLD_KEYS") <(echo "$NEW_KEYS") | wc -l | tr -d ' ')
+
+# Compute new version per bump policy
+MAJOR=$(echo "$CURRENT_VERSION" | cut -d. -f1)
+MINOR=$(echo "$CURRENT_VERSION" | cut -d. -f2)
+PATCH=$(echo "$CURRENT_VERSION" | cut -d. -f3)
+
+if [ "$REMOVED" -gt 0 ]; then
+  NEW_VERSION="$((MAJOR + 1)).0.0"
+elif [ "$ADDED" -gt 0 ]; then
+  NEW_VERSION="${MAJOR}.$((MINOR + 1)).0"
+else
+  NEW_VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"
+fi
+
+# Regenerate manifest for real (writes to $MANIFEST)
+if ! bash "$GENERATE_SCRIPT" >/dev/null 2>&1; then
+  # Regen failed after dry-run passed — fail-soft; author cures manually
+  echo "pre-commit-manifest-autoregen: regen failed; commit proceeds; CI will catch drift" >&2
+  exit 0
+fi
+
+# Set new version
+if command -v jq >/dev/null 2>&1; then
+  jq --arg v "$NEW_VERSION" '.manifest_version = $v' "$MANIFEST" > "$MANIFEST.tmp" && \
+    mv "$MANIFEST.tmp" "$MANIFEST"
+fi
+
+# Render the doc — fail-soft if script missing
+if [ -f "$RENDER_SCRIPT" ]; then
+  bash "$RENDER_SCRIPT" >/dev/null 2>&1 || true
+fi
+
+# Stage the regenerated files
+git add "$MANIFEST" 2>/dev/null || true
+git add "$REPO_ROOT/docs/lite-manifest.md" 2>/dev/null || true
+
+# Emit a friendly note to stderr — author sees the auto-cure fire
+echo "pre-commit-manifest-autoregen: manifest regen ${CURRENT_VERSION} → ${NEW_VERSION} (staged)" >&2
+
+exit 0

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

@@ -24,6 +24,16 @@ if [ "${SKIP_SETTINGS_DRIFT:-0}" = "1" ]; then
   return 0 2>/dev/null || true
 fi
 
+# SELF_MODE guard per bassclef-upstream#1804 — settings-drift only makes sense
+# in adopter (downstream) repos where user/project settings.json can diverge
+# from the shipped set. bassclef-upstream IS the source; self-drift is not a
+# real signal. Detect via env var (bassclef-sync exports) OR file existence
+# (presence/install/bassclef-sync.template.sh only exists in the source repo).
+if [ "${SELF_MODE:-0}" = "1" ]; then
+  trace_log "skip" "settings-drift" "SELF_MODE — bassclef-upstream is the source" 2>/dev/null || true
+  return 0 2>/dev/null || true
+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
@@ -53,16 +63,66 @@ if [ "$__sd_ok" = "true" ]; then
   trace_log "ok" "settings-drift" "no drift" 2>/dev/null || true
 else
   __sd_missing_count=$(echo "$__sd_diff" | jq '.missing | length')
-  __sd_missing_list=$(echo "$__sd_diff" | jq -r '.missing[] | "  - " + .event + " → " + .command')
-  blocked_banner "settings-drift — ${__sd_missing_count} required hook wiring(s) missing from harness-loaded settings:
 
-${__sd_missing_list}
+  # Helper — extract first descriptive comment from a hook file. Skips
+  # shebang, metadata lines (# tier:, # install-class:, # PreToolUse:,
+  # # Stop, # SessionStart, # UserPromptSubmit, # PostToolUse:), and
+  # empty lines. Returns the first substantive one-line description or
+  # empty string. Caps scan at 15 lines for speed (per bassclef-upstream#1794).
+  __sd_hook_purpose() {
+    local cmd="$1"
+    # Extract path from command string: strip "bash " prefix + resolve $CLAUDE_PROJECT_DIR
+    local path="${cmd#bash }"
+    path="${path%% *}"
+    path="${path//\$CLAUDE_PROJECT_DIR/${BASSCLEF_DIR:-${PWD}}}"
+    path="${path//\$HOME/${HOME}}"
+    [ -f "$path" ] || { echo ""; return 0; }
+    awk '
+      NR > 15 { exit }
+      /^#!/ { next }
+      /^# tier:/ || /^# install-class:/ { next }
+      /^# PreToolUse:/ || /^# PostToolUse:/ || /^# Stop/ || /^# SessionStart/ || /^# UserPromptSubmit/ { next }
+      /^# *$/ { next }
+      /^#/ { sub(/^# ?/, ""); print; exit }
+    ' "$path" 2>/dev/null | cut -c1-80
+  }
+
+  # Detect SELF_MODE — bassclef-upstream repo carries presence/install/bassclef-sync.template.sh.
+  # Adopter repos never carry this specific file.
+  __sd_self_mode=0
+  if [ -f "${BASSCLEF_DIR:-${PWD}}/presence/install/bassclef-sync.template.sh" ]; then
+    __sd_self_mode=1
+  fi
+
+  # Build per-hook explain block. jq emits event + command per line;
+  # bash loop looks up purpose per hook.
+  __sd_missing_block=""
+  while IFS=$'\t' read -r __sd_event __sd_cmd; do
+    __sd_purpose=$(__sd_hook_purpose "$__sd_cmd")
+    __sd_missing_block+="  - ${__sd_event} → ${__sd_cmd}"$'\n'
+    if [ -n "$__sd_purpose" ]; then
+      __sd_missing_block+="    purpose: ${__sd_purpose}"$'\n'
+    fi
+  done < <(echo "$__sd_diff" | jq -r '.missing[] | .event + "\t" + .command')
+
+  # Cure text branches on SELF_MODE. Both paths land runnable commands.
+  if [ "$__sd_self_mode" = "1" ]; then
+    __sd_cure="Cure (SELF_MODE — this repo IS the source):
+  Edit .claude/settings.json directly, or refresh from the hand-maintained template at
+  presence/install/public-bassclef-settings.template.json (source-of-truth for the shipped set)."
+  else
+    __sd_cure="Cure (adopter mode): bash ~/.claude/hooks/bassclef-sync.sh (additive merge on next session-start)"
+  fi
+
+  blocked_banner "settings-drift — ${__sd_missing_count} required hook wiring(s) missing from harness-loaded settings:
 
+${__sd_missing_block}
 Root cause class: substrate ships new wiring; operator's settings.json never picked it up.
-Resolve: bassclef-sync.sh self-heal will additively merge on next session-start once it ships (#313 WU-3). For now, run manually: bash ~/.claude/hooks/bassclef-sync.sh
+${__sd_cure}
 Override: SKIP_SETTINGS_DRIFT=1 (one-off bypass; logged to trace)"
-  trace_log "blocked" "settings-drift" "missing=${__sd_missing_count}" 2>/dev/null || true
-  unset __sd_missing_count __sd_missing_list
+  trace_log "blocked" "settings-drift" "missing=${__sd_missing_count} self_mode=${__sd_self_mode}" 2>/dev/null || true
+  unset __sd_missing_count __sd_missing_block __sd_event __sd_cmd __sd_purpose __sd_self_mode __sd_cure
+  unset -f __sd_hook_purpose 2>/dev/null || true
 fi
 
 unset __sd_wirings_lib __sd_project_settings __sd_required __sd_loaded __sd_diff __sd_ok

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

@@ -80,14 +80,34 @@ if [ -n "$LAST_REVIEW" ]; then
 fi
 
 # === Release notes ===
+# Freshness signal reads file mtime, not filename per bassclef-upstream#1802.
+# Prior shape parsed `basename | cut -c1-10` as YYYY-MM-DD; release notes
+# ship as v<SEMVER>.md, so the parse failed silently, fell back to epoch 0,
+# and produced "20715 days ago" banner every session. Cure: pick newest file
+# by mtime (`ls -1t | head -1`) and compare mtime to now.
+#
+# SELF_MODE guard per bassclef-upstream#1804 — release-notes freshness only
+# meaningful for adopters watching for shipped releases; bassclef-upstream IS
+# the release source. Detect via env var (bassclef-sync sets); file-based
+# fallback got dropped in a follow-up commit after CI-fixture false positives.
+if [ "${SELF_MODE:-0}" = "1" ]; then
+  return 0 2>/dev/null || true
+fi
 NOTES_DIR="docs/release-notes"
 if [ -d "$NOTES_DIR" ]; then
-  LAST_NOTES=$(ls -1 "$NOTES_DIR"/*.md 2>/dev/null | grep -v .gitkeep | sort | tail -1)
+  LAST_NOTES=$(ls -1t "$NOTES_DIR"/*.md 2>/dev/null | grep -v .gitkeep | head -1)
   if [ -n "$LAST_NOTES" ]; then
-    LAST_NOTES_DATE=$(basename "$LAST_NOTES" .md | cut -c1-10)
-    DAYS_SINCE=$(( ( $(date +%s) - $(date -j -f "%Y-%m-%d" "$LAST_NOTES_DATE" +%s 2>/dev/null || echo "0") ) / 86400 ))
-    if [ "$DAYS_SINCE" -gt 7 ]; then
-      blocked_banner "release-notes — last entry $(basename "$LAST_NOTES"), ${DAYS_SINCE} days ago. Run /release-notes."
+    # Portable stat mtime: GNU `stat -c %Y` (Linux/CI) then BSD `stat -f %m` (macOS).
+    # GNU-first order is load-bearing: on Linux, BSD's `-f` triggers filesystem-status
+    # mode with a different specifier grammar, returning multi-line filesystem info
+    # that breaks the [ -gt 0 ] check. GNU `-c` is unknown on BSD and fails cleanly
+    # to the fallback. Per bassclef-upstream#1819 CI shard 2 diagnosis.
+    LAST_NOTES_MTIME=$(stat -c %Y "$LAST_NOTES" 2>/dev/null || stat -f %m "$LAST_NOTES" 2>/dev/null || echo 0)
+    if [ "$LAST_NOTES_MTIME" -gt 0 ]; then
+      DAYS_SINCE=$(( ( $(date +%s) - LAST_NOTES_MTIME ) / 86400 ))
+      if [ "$DAYS_SINCE" -gt 7 ]; then
+        blocked_banner "release-notes — last entry $(basename "$LAST_NOTES"), ${DAYS_SINCE} days ago. Run /release-notes."
+      fi
     fi
   else
     TOTAL_COMMITS=$(git log --oneline 2>/dev/null | wc -l | tr -d ' ')

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

@@ -2,6 +2,17 @@
 # Metrics-staleness check: version tags, iteration closeouts, metrics
 # dashboard, DORA freshness, changelog_doc_id. Surfaces as one BLOCKED
 # with all gaps enumerated.
+#
+# Fresh-install gate (#1818 Ship 3): if docs/metrics/ does not exist,
+# this repo does not own a metrics dashboard yet. Skip silently. Cold
+# adopters see no false BLOCKED banner on their first skill run. The
+# gate activates the moment docs/metrics/ appears (after the operator
+# runs scripts/metrics.sh --all for real).
+# Anchor: @luminary donald-norman — a banner fires only when a real
+# problem exists.
+if [ ! -d "docs/metrics" ]; then
+  return 0 2>/dev/null || exit 0
+fi
 
 METRICS_SCRIPT="scripts/metrics.sh"
 if [ -f "$METRICS_SCRIPT" ] || [ -f "$BASSCLEF_DIR/$METRICS_SCRIPT" ]; then

package/dist/lite/.claude/hooks/session-reflection.d/60-deferred-actions.sh

@@ -66,7 +66,8 @@ CAP_NPM_INSTALL=0
 CAP_PLAYWRIGHT_MCP=0
 
 # gcloud-auth + google-docs-write: presence of SA key
-if [ -f "$HOME/.config/gcloud/sunjay-google-ops.json" ]; then
+# Ship 1 (#1816): env var lookup; unset = capability disabled.
+if [ -n "${BASSCLEF_GCLOUD_KEY:-}" ] && [ -f "$BASSCLEF_GCLOUD_KEY" ]; then
   CAP_GCLOUD=1
 fi