@thebassclef/lite 1.0.4 → 1.1.0

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

@@ -0,0 +1,2278 @@
+#!/bin/bash
+# tier: lite
+# description: BASSCLEF_SYNC_VERSION=2026-09-06-1496-sessionstart-heal-v1
+# BASSCLEF_SYNC_VERSION=2026-09-06-1496-sessionstart-heal-v1
+# ^^ DO NOT REMOVE — used by drift check to detect out-of-date consumer copies.
+# Bump when changing this template's semantics. Format: YYYY-MM-DD-vN.
+#
+# 2026-08-29-v1: #1417 Branch B (Option F full build) — swap ln -s → cp for
+#                Sections 2 (skills project-level), 3a (hooks), 3a-postcheck
+#                (self-heal), 3a-fragments, 3b-skills (user-level), 3d (rules).
+#                Adopter owns copies; symlinks migrate on next sync per
+#                ADR-031 grace window. Skills use .bassclef-managed sentinel
+#                to distinguish bassclef-cp'd dirs from app-specific overrides.
+#                Rules use per-file cp inside a real dir (adopter-added files
+#                preserved). Hooks use per-file cp + chmod +x per spike
+#                prototype pattern (PR #1293). Luminaries + agents + orientation
+#                + lib (Sections 3c + 3e + 3d-bis + 3f) deferred to follow-on.
+#
+# 2026-07-26-v1: #897 Cure A — whereami parser accepts +HHMM/+HH:MM offsets
+#                AND YAML frontmatter last_updated.at fallback. Extracted to
+#                bassclef_sync_parse_whereami_ts() helper. Test-mode source
+#                guard added via BASSCLEF_SYNC_TEST_MODE=1. Fixes "unparseable
+#                — schema non-conformance" warning that fired every session
+#                start since 2026-07-19 f2929de6 when whereami switched from
+#                Z to local BST timestamps.
+#
+# 2026-07-04-v1: bet 2026-07-03b WU-0 (bassclef-upstream#625) — §3c-hooks
+#                dynamic-derive. Reads bassclef's own .claude/settings.json
+#                via presence/install/bassclef-hook-connect.sh (sourceable lib)
+#                and merges every hook entry across all 6 event types into the
+#                adopter settings.json. Prior 5-entry hardcoded list retired.
+#                Dispatcher exports BASSCLEF_SOURCE_ROOT before exec.
+#                Closes the 10 %-coverage class POA hit 2026-07-02.
+#
+# 2026-05-07-v1: Phase II Trim the Fat WU-10 — auto-wire bassclef-managed
+#                PreToolUse hooks into consumer settings.json (bassclef#569).
+#                Surfaced at sibling validation 2026-05-07: POA + TwoDo + Ops
+#                all confirmed Phase II hooks ship dead-letter — scripts on
+#                disk, no settings.json registration, real tool calls bypass
+#                them. Section 3c-hooks added: jq-based merge of bassclef-
+#                managed PreToolUse entries into <consumer>/.claude/settings.json.
+#                Idempotent. Skips bassclef itself (detected via remote URL).
+#                Operator override: SKIP_BASSCLEF_HOOK_WIRE=1.
+#
+# 2026-05-05-v3: drift-block remediation message updated to match thin-pointer
+#                reality (bassclef#418 LR8.5 WU-3). Pre-2026-05-03 vendored-
+#                consumer drift was fixed by `gh workflow run bassclef-template-
+#                sync.yml`; that workflow retired in PR #445. New remediation:
+#                migrate to thin-pointer via /onboard-repo (one-shot — eliminates
+#                the drift class entirely since thin-pointer fetches bassclef's
+#                current template every session-start).
+# 2026-05-05-v2: whereami staleness uses commit-delta (bassclef#514). Idle
+#                consumers (zero commits since whereami was last committed)
+#                downgrade from BLOCKED to INFO at the >=7d tier — calendar
+#                staleness alone stops being a gate when nothing changed in
+#                the repo. Commits-since computed via git log -1 -- docs/
+#                whereami.md + git rev-list --count. SKIP_WHEREAMI_COMMIT_DELTA=1
+#                forces idle (commits=0) for migration. This is sequenced
+#                with v1 (Strategy D HTTP API fetch) — both ship in LR8.5.
+# 2026-05-05-v1: Strategy D — HTTP API fetch via .bassclef-source.json.
+#                Reads consumer's .bassclef-source.json (per
+#                standards/bassclef-source-config.md), dispatches authenticated
+#                tarball curl to the configured source_url, extracts via
+#                --strip-components=1 (GitHub repo-API tarball pattern). Soft-
+#                falls to Strategy B (S3) if config missing, malformed, token
+#                unset, fetch fails, or extraction fails. Banner emits
+#                "Status: fetched from bassclef (HTTP API)" so the new path
+#                is observable. Closes bassclef#419. Sets up bassclef#446
+#                (retire S3 publish) and bassclef#418 (default thin-pointer
+#                onboarding writes .bassclef-source.json instead of
+#                .bassclef-url).
+# 2026-05-02-v1: drift check is thin-pointer-aware. Consumer hooks with
+#                version string matching `thin-pointer-*` opt out of the
+#                drift comparison — they are intentionally a different file
+#                from this template (130-line dispatcher vs 800+ line
+#                template). Different role, different version namespace.
+#                The dispatcher's job is to delegate to bassclef's current
+#                template on every fire, not mirror its version string.
+#                Per bassclef#418. Closes the false-positive drift-block
+#                that fired every session on thin-pointer consumers between
+#                2026-05-02 (TwoDo migration) and this fix.
+# 2026-04-26-v1: #267/#268/#269 fire-and-forget hardening.
+#                #267 — auto-heal drift when working tree is clean AND on main
+#                  AND no unpushed commits AND remote-main matches bassclef.
+#                  Self-pulls + re-execs hook silently (no operator BLOCKED on
+#                  the common case). Preconditions guard against destructive
+#                  pulls into uncommitted/diverged state.
+#                #268 — when both local AND remote main lag template AND no
+#                  open sync PR exists, surface "orphaned closure" diagnosis
+#                  instead of "try git pull" (which would be a no-op).
+#                #269 — paired with #268, offer one-line workflow_dispatch
+#                  remediation: `gh workflow run bassclef-template-sync.yml`
+#                  fires a fresh sync. Operator decides merge vs override.
+# 2026-04-20-v2: #225 follow-up — surface URL-age tier in the mandatory
+#                "YOU MUST confirm" line so agents reinforce warn/expired
+#                state to operators, not just emit it in verbose hook output.
+#                OK tier stays silent on the confirm line (no clutter); warn
+#                and expired tiers are guaranteed-surfaced.
+# 2026-04-20-v1: #224 tiered URL-age banner at session-start — observability
+#                into presigned URL freshness so operators can distinguish
+#                benign rotation-race from stale-URL/reclone-needed without
+#                diving into Actions logs. Thresholds: <18h OK, 18-24h WARN,
+#                fetched-when-expired is unreachable here (curl 403s earlier).
+# 2026-04-19-v3: #173 drift block first checks remote main hook version via
+#                gh API; if remote matches template, emit STALE message
+#                (recommend git pull) instead of BLOCKED. Generalizes #189's
+#                merged-PR detection to any cause of local-behind-main drift.
+#                Falls through to existing BLOCKED on gh unavailable / network
+#                down / remote-main also lags template (genuine drift).
+# 2026-04-19-v2: #192 session-start health check for missing onboarding
+#                artifacts (CLAUDE.md + substrate.config.md — whereami
+#                already covered by its own block)
+# 2026-04-19-v1: #189 drift block detects merged-but-unpulled PR (branches
+#                remediation text: open PR → merge; merged → git pull)
+# 2026-04-17-v1: #162 tarball integrity check + ephemeral-gated settings.json
+#                #161 fail-loud on empty bassclef tree
+#                #160 bootstrap bassclef-evolution labels
+#
+# Bassclef Substrate Sync — fires on SessionStart.
+# Ensures bassclef standards are available regardless of device.
+#
+# Fetch strategies (first match wins; D and B both ephemeral, D preferred):
+#   A. Peer directory     — $CWD/../bassclef already present (desktop / web
+#                           with multi-repo / CI with pre-clone)
+#   D. HTTP API           — .bassclef-source.json in CWD + ephemeral env
+#                           detected; reads source_url + auth_method +
+#                           token_env, curls authenticated tarball, extracts
+#                           with --strip-components=1 (GitHub repo-API pattern).
+#                           Soft-falls to B on any failure (malformed, token
+#                           unset, HTTP non-200, extract fails).
+#   B. S3 tarball         — .bassclef-url in CWD + ephemeral env detected.
+#                           Fires when D unavailable or fails. Retires once
+#                           every consumer is migrated to .bassclef-source.json
+#                           (bassclef#446).
+#   C. Bash clone         — original path; desktop without peer and with
+#                           GitHub credentials
+#
+# Post-fetch (same for all strategies):
+#   1. Symlinks bassclef skills into project .claude/skills/
+#   2. Installs general hooks + agents to ~/.claude/
+#   3. Writes ~/.claude/settings.json for user-level hook wiring
+#   4. Maintains .gitignore managed block for symlinks
+#   5. Sets env var for rules/CLAUDE.md inheritance
+#
+# See ADR-014 in bassclef for the distribution model rationale.
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
+cd "$CWD"
+
+# Opt-out sentinel (#119): repos that must NOT inherit bassclef substrate
+# (public OSS repos curated from bassclef, ephemeral dirs, test fixtures)
+# can place a .no-bassclef-sync file in the repo root to suppress sync.
+if [ -f "$CWD/.no-bassclef-sync" ]; then
+  echo "Bassclef substrate sync: skipped (.no-bassclef-sync sentinel present)."
+  exit 0
+fi
+
+BASSCLEF_REPO="https://github.com/sunj-labs/bassclef.git"
+SYNC_STATUS="up-to-date"
+SYNC_SOURCE="unknown"
+SYNC_NEW=""
+FETCH_DONE=0
+
+# === V1 helper: installed-metadata writeback (bassclef#1037 Phase B WU-V1) ===
+# After a successful fetch, write installed_sha + installed_at into the
+# adopter's .bassclef-source.json so 45-auto-sync-status.sh and /whereami
+# can display the install version + delta-to-current. Best-effort: silent
+# failure when jq missing, config absent, config malformed, or SHA empty.
+# Adopter still gets the substrate even if the metadata write fails.
+bassclef_sync_write_installed_metadata() {
+  local config="$1"
+  local sha="$2"
+  local at="$3"
+  # Silent skip if any required input missing
+  [ -z "$config" ] && return 0
+  [ -z "$sha" ] && return 0
+  [ -z "$at" ] && return 0
+  [ ! -f "$config" ] && return 0
+  command -v jq >/dev/null 2>&1 || return 0
+  # Validate existing JSON before mutating
+  jq empty "$config" >/dev/null 2>&1 || return 0
+  local tmp="$config.installed-writeback.tmp"
+  if jq --arg sha "$sha" --arg at "$at" \
+       '.installed_sha = $sha | .installed_at = $at' \
+       "$config" > "$tmp" 2>/dev/null; then
+    mv "$tmp" "$config"
+  else
+    rm -f "$tmp" 2>/dev/null || true
+  fi
+  return 0
+}
+
+# === #897 Cure A: whereami timestamp parser ===
+# Extracts the whereami last_updated timestamp and normalizes it to
+# UTC Z form for downstream date math. Reads YAML frontmatter
+# `last_updated.at: <TS>` — the canonical shape since #1481 diagnose.
+# Legacy `## Last updated` markdown-section reader retired per goal
+# 2026-09-06d Cure 3. Adopters mid-migration write frontmatter via
+# session-end.sh; sync inherits new shape on next SessionStart.
+# Regex accepts Z, +HHMM, -HHMM, +HH:MM, -HH:MM offsets per RFC 3339.
+# Output is normalized to Z form so downstream date -j -f "%Y-%m-%dT%H:%M:%SZ"
+# reads one canonical shape. Returns empty on missing file, missing
+# timestamp, or malformed timestamp — caller treats empty as unparseable.
+#
+# Portable across Darwin (BSD date) + Linux (GNU date).
+#
+# Per #897 Cure A. Sister #897 Cure B (write-time PreToolUse gate on
+# docs/whereami.md edits) deferred to sister ticket.
+bassclef_sync_parse_whereami_ts() {
+  local whereami_path="$1"
+  local ts=""
+  local ts_regex='[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(Z|[+-][0-9]{2}:?[0-9]{2})?'
+
+  [ -z "$whereami_path" ] && return 0
+  [ ! -f "$whereami_path" ] && return 0
+
+  # YAML frontmatter last_updated.at (canonical shape)
+  ts=$(awk '/^last_updated:/{flag=1;next}
+            /^[a-zA-Z]/{flag=0}
+            flag && /^  at:/{
+              sub(/^  at:[ ]*/, "");
+              sub(/[ ]*$/, "");
+              print;
+              exit
+            }' "$whereami_path" 2>/dev/null | \
+    grep -oE "$ts_regex" | head -1)
+
+  [ -z "$ts" ] && return 0
+
+  # Normalize to Z form. Already-Z passes through.
+  case "$ts" in
+    *Z)
+      echo "$ts"
+      return 0
+      ;;
+  esac
+
+  # Strip colon from offset for BSD date's %z (which expects +HHMM not +HH:MM)
+  local ts_no_colon
+  ts_no_colon=$(echo "$ts" | sed -E 's/([+-][0-9]{2}):([0-9]{2})$/\1\2/')
+
+  local epoch=""
+  # Darwin: date -j -f "%Y-%m-%dT%H:%M:%S%z"
+  if epoch=$(date -j -f "%Y-%m-%dT%H:%M:%S%z" "$ts_no_colon" "+%s" 2>/dev/null); then
+    date -u -r "$epoch" "+%Y-%m-%dT%H:%M:%SZ"
+    return 0
+  fi
+  # GNU: date -d handles ISO 8601 with offset natively
+  if epoch=$(date -d "$ts" "+%s" 2>/dev/null); then
+    date -u -d "@$epoch" "+%Y-%m-%dT%H:%M:%SZ"
+    return 0
+  fi
+
+  # Fallback: pass through unnormalized (downstream will call it unparseable)
+  return 0
+}
+
+# === 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
+# BASSCLEF_SYNC_TEST_MODE=1 skips the main body's stdin read + sync
+# flow. Helpers are defined ABOVE this guard; test access preserved.
+if [ "${BASSCLEF_SYNC_TEST_MODE:-0}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# === 0. Environment detection ===
+# Primary signal: operator-set CLAUDE_EPHEMERAL=1.
+# Fallback heuristic: cwd not under /Users/ (operator Mac) AND no ../bassclef peer dir.
+# See ADR-014 and .claude/rules/mobile-ephemeral-session.md.
+IS_EPHEMERAL=0
+if [ "${CLAUDE_EPHEMERAL:-}" = "1" ]; then
+  IS_EPHEMERAL=1
+elif [[ "$CWD" != /Users/* ]] && [ ! -d "$CWD/../bassclef/.claude" ]; then
+  # Likely ephemeral: non-operator filesystem AND no peer bassclef
+  IS_EPHEMERAL=1
+fi
+
+# === 1. Fetch bassclef (strategy order: peer > HTTP API > S3 > bash clone) ===
+#
+# Strategies are now independent guarded blocks rather than if/elif/else, so
+# Strategy D can soft-fall to Strategy B without restructuring control flow.
+# Each block sets FETCH_DONE=1 on success; subsequent blocks skip when that
+# flag is set. Strategy B's existing failure paths still call exit 0 (its
+# behavior is unchanged when it runs); D's failures are non-fatal — they
+# log to stderr and let B/C try.
+
+# === 0a. SELF_MODE substrate-repo detection (per #901 Cure 1) ===
+# Extends #293 SELF_MODE detection with a second condition: CWD is a
+# bassclef substrate SOURCE repo (bassclef or bassclef-upstream). The
+# #293 check only matched bassclef-on-bassclef (CWD == BASSCLEF_DIR).
+# bassclef-upstream running against the public bassclef sibling
+# ($CWD/../bassclef) has DIFFERENT paths, so #293 missed it — Section
+# 3a then ran and converted 84 tracked hook files to cross-repo
+# symlinks (root cause of #893/#894/#896/#898/#899/#900/#902 CI failures
+# per session log chronicle/2026-07-26b-tree-corruption-5-lens-
+# diagnosis.md).
+#
+# Cure: detect substrate-repo status via git remote pattern.
+# If CWD's origin URL matches sunj-labs/(bassclef|bassclef-upstream),
+# set SELF_MODE=1 regardless of Strategy A's peer-resolve check.
+#
+# Override: SKIP_SELF_MODE_DETECTION=1 for one-shot recovery scenarios.
+#
+# Anchor: @luminary linus-torvalds (we-dont-break-adopters per
+# ADR-031 — a fresh checkout of bassclef-upstream must not inherit
+# broken tree state) + @luminary jerome-saltzer-and-michael-schroeder
+# (complete mediation — every install path guarded).
+SELF_MODE=${SELF_MODE:-0}
+if [ "${SKIP_SELF_MODE_DETECTION:-0}" != "1" ]; then
+  CWD_REMOTE=$(git -C "$CWD" config --get remote.origin.url 2>/dev/null || echo "")
+  if echo "$CWD_REMOTE" | grep -qE 'sunj-labs/(bassclef|bassclef-upstream)(\.git)?$'; then
+    SYNC_SOURCE="self (bassclef substrate source repo)"
+    SELF_MODE=1
+  fi
+fi
+
+# === 0b. Strategy 0 — env-supplied BASSCLEF_DIR (added 2026-09-15 for goal 14c Step 6) ===
+# Real adopters do not set BASSCLEF_DIR in the environment. Test fixtures set
+# it to point at a mock bundle to exercise the sync template in isolation.
+# Honor the env value when set + valid; short-circuit Strategy A-D fetches.
+#
+# Anchor: @luminary michael-feathers (characterization tests need env-supplied
+# fixture paths to exercise real behavior).
+if [ -n "${BASSCLEF_DIR:-}" ] && [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
+  SYNC_SOURCE="env-override"
+  SYNC_STATUS="using BASSCLEF_DIR override"
+  FETCH_DONE=1
+fi
+
+# Strategy A: peer directory (desktop / web with multi-repo / any env with bassclef pre-present)
+if [ "$FETCH_DONE" = "0" ] && [ -d "$CWD/../bassclef/.claude" ]; then
+  BASSCLEF_DIR="$CWD/../bassclef"
+  # Self-detection (#293): if peer resolves back to ourselves (bassclef-on-bassclef),
+  # mark SELF_MODE=1 so Section 3a (the only installer that replaces real files
+  # rather than leaving them alone) is skipped. Without this guard, Section 3a's
+  # "replace stale real files with symlinks" policy turns bassclef's own real
+  # hook files into symlinks pointing back to themselves via .. → ELOOP at hook
+  # execution time. Sections 2, 3b-skills, and 3c are already self-safe via
+  # their existing "leave real dirs alone" or "different filesystem location"
+  # patterns and need no gating.
+  #
+  # Note: 0a above catches the bassclef-upstream case where CWD ≠ BASSCLEF_DIR
+  # but CWD still IS a substrate source repo. Both checks compose.
+  if [ "$(cd "$BASSCLEF_DIR" 2>/dev/null && pwd -P)" = "$(cd "$CWD" 2>/dev/null && pwd -P)" ]; then
+    SYNC_SOURCE="self (bassclef on bassclef)"
+    SELF_MODE=1
+  elif [ "$SELF_MODE" != "1" ]; then
+    SYNC_SOURCE="peer"
+  fi
+  # Best-effort pull (may fail in ephemeral / no creds — non-fatal)
+  BEFORE=$(git -C "$BASSCLEF_DIR" rev-parse HEAD 2>/dev/null)
+  git -C "$BASSCLEF_DIR" pull --quiet 2>/dev/null || true
+  AFTER=$(git -C "$BASSCLEF_DIR" rev-parse HEAD 2>/dev/null)
+  if [ -n "$BEFORE" ] && [ "$BEFORE" != "$AFTER" ]; then
+    SYNC_STATUS="updated"
+    SYNC_NEW=$(git -C "$BASSCLEF_DIR" log --oneline "$BEFORE".."$AFTER" 2>/dev/null)
+  fi
+  FETCH_DONE=1
+fi
+
+# Strategy D: HTTP API via .bassclef-source.json (ephemeral; primary)
+# Per standards/bassclef-source-config.md schema:
+#   { source_url, auth_method (Bearer|Basic|none), token_env, comment? }
+# Soft-fall to Strategy B if config is malformed, the named env var is unset,
+# the curl fetch returns non-200, or extraction fails. None of those are fatal
+# at this layer — they let B/C try. Genuinely-fatal cases (no fallback files
+# present) are handled in Strategy C's failure branch below.
+if [ "$FETCH_DONE" = "0" ] && [ "$IS_EPHEMERAL" = "1" ] && [ -f "$CWD/.bassclef-source.json" ]; then
+  D_CONFIG="$CWD/.bassclef-source.json"
+  D_SOURCE_URL=$(jq -r '.source_url // empty' "$D_CONFIG" 2>/dev/null)
+  D_AUTH_METHOD=$(jq -r '.auth_method // empty' "$D_CONFIG" 2>/dev/null)
+  D_TOKEN_ENV=$(jq -r '.token_env // empty' "$D_CONFIG" 2>/dev/null)
+
+  # Validate config minimally — schema-level validation lives in
+  # bassclef-source-config-validate.sh PreToolUse hook; this is the runtime
+  # defensive check for the case the file was hand-edited or the validator
+  # was bypassed.
+  if [ -z "$D_SOURCE_URL" ] || [ -z "$D_AUTH_METHOD" ]; then
+    echo "[bassclef-sync] Strategy D: .bassclef-source.json malformed (source_url or auth_method missing); falling through" >&2
+  else
+    # Resolve token via bash indirect expansion (safer than eval).
+    # ${!VAR:-} returns empty when VAR is unset.
+    D_TOKEN_VALUE=""
+    if [ "$D_AUTH_METHOD" != "none" ] && [ -n "$D_TOKEN_ENV" ]; then
+      D_TOKEN_VALUE="${!D_TOKEN_ENV:-}"
+    fi
+
+    if [ "$D_AUTH_METHOD" != "none" ] && [ -z "$D_TOKEN_VALUE" ]; then
+      echo "[bassclef-sync] Strategy D: env var '$D_TOKEN_ENV' is unset; falling through to S3" >&2
+    else
+      D_DIR="$HOME/bassclef"
+      mkdir -p "$D_DIR" 2>/dev/null || true
+      rm -rf "$D_DIR"/* "$D_DIR"/.[!.]* 2>/dev/null || true
+
+      D_TARBALL="/tmp/bassclef-sync-d-$$.tar.gz"
+
+      # GitHub repo tarball API redirects (302) to a codeload URL — -L follows.
+      # No retry loop here (unlike B's two-shot); the soft-fall to S3 IS the
+      # retry. Future hardening: per-strategy retry with backoff if real-world
+      # flakiness shows up.
+      if [ "$D_AUTH_METHOD" = "none" ]; then
+        D_HTTP=$(curl -sSL -w "%{http_code}" -o "$D_TARBALL" "$D_SOURCE_URL" 2>/dev/null || echo "000")
+      else
+        D_HTTP=$(curl -sSL -w "%{http_code}" -o "$D_TARBALL" \
+          -H "Authorization: $D_AUTH_METHOD $D_TOKEN_VALUE" \
+          "$D_SOURCE_URL" 2>/dev/null || echo "000")
+      fi
+
+      if [ "$D_HTTP" != "200" ]; then
+        rm -f "$D_TARBALL" 2>/dev/null
+        echo "[bassclef-sync] Strategy D: HTTP $D_HTTP from $D_SOURCE_URL; falling through to S3" >&2
+      elif ! tar -xzf "$D_TARBALL" --strip-components=1 -C "$D_DIR" 2>/dev/null; then
+        # GitHub repo-API tarballs wrap content under <repo>-<sha>/; --strip-
+        # components=1 normalizes. If a future provider returns a non-wrapped
+        # tarball, this fails and we fall to B — the schema does not yet
+        # parameterize strip-components. Schema extension is a future-when-
+        # needed concern, not a today concern (sunj-labs all use the wrapped
+        # GitHub repo-API form per the bassclef#419 acceptance).
+        rm -f "$D_TARBALL" 2>/dev/null
+        rm -rf "$D_DIR"/* "$D_DIR"/.[!.]* 2>/dev/null || true
+        echo "[bassclef-sync] Strategy D: tar extraction failed; falling through to S3" >&2
+      else
+        # V1 (bassclef#1037 WU-V1): capture installed SHA from the tarball's
+        # wrapping directory before normalization. GitHub repo-API tarballs
+        # wrap content under <repo>-<sha>/ where <sha> is the full commit SHA.
+        D_INSTALLED_SHA=$(tar -tzf "$D_TARBALL" 2>/dev/null | head -1 | sed 's|/$||' | sed 's|^.*-||')
+        rm -f "$D_TARBALL"
+        BASSCLEF_DIR="$D_DIR"
+        SYNC_STATUS="fetched from bassclef (HTTP API)"
+        SYNC_SOURCE="bassclef-http-api"
+        FETCH_DONE=1
+        # Best-effort writeback; silent failure does not block sync
+        bassclef_sync_write_installed_metadata \
+          "$CWD/.bassclef-source.json" \
+          "$D_INSTALLED_SHA" \
+          "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+      fi
+    fi
+  fi
+fi
+
+# Strategy B: S3 tarball via .bassclef-url (mobile / ephemeral)
+if [ "$FETCH_DONE" = "0" ] && [ "$IS_EPHEMERAL" = "1" ] && [ -f "$CWD/.bassclef-url" ]; then
+  BASSCLEF_DIR="$HOME/bassclef"
+  SYNC_SOURCE="s3"
+  URL=$(jq -r '.url' "$CWD/.bassclef-url" 2>/dev/null)
+  URL_AGE_GENERATED_AT=$(jq -r '.generated_at' "$CWD/.bassclef-url" 2>/dev/null)
+  URL_EXPIRES_AT=$(jq -r '.expires_at' "$CWD/.bassclef-url" 2>/dev/null)
+  if [ -z "$URL" ] || [ "$URL" = "null" ]; then
+    echo "### BASSCLEF SYNC FAILED"
+    echo ""
+    echo ".bassclef-url is present but malformed (missing .url field)."
+    echo ""
+    exit 0
+  fi
+
+  mkdir -p "$BASSCLEF_DIR" 2>/dev/null || true
+  rm -rf "$BASSCLEF_DIR"/* "$BASSCLEF_DIR"/.[!.]* 2>/dev/null || true
+
+  # Fetch tarball; retry once on transient failure
+  TARBALL="/tmp/bassclef-sync-$$.tar.gz"
+  HTTP_CODE=$(curl -sS -w "%{http_code}" -o "$TARBALL" "$URL" 2>/dev/null || echo "000")
+
+  if [ "$HTTP_CODE" != "200" ]; then
+    sleep 5
+    HTTP_CODE=$(curl -sS -w "%{http_code}" -o "$TARBALL" "$URL" 2>/dev/null || echo "000")
+  fi
+
+  if [ "$HTTP_CODE" != "200" ]; then
+    rm -f "$TARBALL" 2>/dev/null
+    echo "### BASSCLEF SYNC FAILED"
+    echo ""
+    echo "S3 fetch returned HTTP $HTTP_CODE. Presigned URL may be expired."
+    echo "Generated: $URL_AGE_GENERATED_AT"
+    echo "Expires:   $URL_EXPIRES_AT"
+    echo "Wait for bassclef main merge or run bassclef-s3-publish workflow_dispatch."
+    echo ""
+    exit 0
+  fi
+
+  # === 1a. Tarball integrity check (#162) ===
+  # Fail closed if downloaded tarball's sha256 doesn't match what the workflow
+  # recorded in .bassclef-url. Defends against S3 content tampering and
+  # corrupted downloads. Emergency override: SKIP_INTEGRITY_CHECK=1.
+  EXPECTED_SHA=$(jq -r '.tarball_sha256 // empty' "$CWD/.bassclef-url" 2>/dev/null)
+  if [ "${SKIP_INTEGRITY_CHECK:-}" != "1" ] && [ -n "$EXPECTED_SHA" ]; then
+    if command -v sha256sum >/dev/null 2>&1; then
+      ACTUAL_SHA=$(sha256sum "$TARBALL" | awk '{print $1}')
+    else
+      ACTUAL_SHA=$(shasum -a 256 "$TARBALL" | awk '{print $1}')
+    fi
+    if [ "$ACTUAL_SHA" != "$EXPECTED_SHA" ]; then
+      rm -f "$TARBALL" 2>/dev/null
+      echo "### BASSCLEF SYNC FAILED — INTEGRITY CHECK"
+      echo ""
+      echo "Tarball sha256 mismatch:"
+      echo "  Expected: $EXPECTED_SHA"
+      echo "  Actual:   $ACTUAL_SHA"
+      echo ""
+      echo "Possible causes: S3 content tampering, corrupted download, stale URL."
+      echo "Emergency override (review first): SKIP_INTEGRITY_CHECK=1"
+      echo ""
+      exit 0
+    fi
+  fi
+
+  if ! tar -xzf "$TARBALL" -C "$BASSCLEF_DIR" 2>/dev/null; then
+    rm -f "$TARBALL" 2>/dev/null
+    rm -rf "$BASSCLEF_DIR"/* "$BASSCLEF_DIR"/.[!.]* 2>/dev/null || true
+    echo "### BASSCLEF SYNC FAILED"
+    echo ""
+    echo "Tarball extraction failed. Partial extract removed."
+    echo ""
+    exit 0
+  fi
+  rm -f "$TARBALL"
+  SYNC_STATUS="fetched from S3"
+  FETCH_DONE=1
+fi
+
+# Strategy C: bash clone (original path, desktop without peer)
+if [ "$FETCH_DONE" = "0" ]; then
+  BASSCLEF_DIR="$CWD/../bassclef"
+  SYNC_SOURCE="bash-clone"
+  if git clone "$BASSCLEF_REPO" "$BASSCLEF_DIR" 2>/dev/null; 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 ""
+    exit 0
+  fi
+fi
+
+# === 1b. Assert bassclef tree is non-empty (#161) ===
+# Defense against silent failure: fetch + extract can succeed (HTTP 200, tar
+# exits 0) while leaving an empty or partial tree. Without this check, the
+# sync banner reports success and SessionStart proceeds with no substrate.
+#
+# 2026-09-15 (goal 14c Step 6): env-override skips this check. Test fixtures
+# use env-supplied BASSCLEF_DIR and populate only the dirs each test needs.
+# Real fetch paths (peer/http/s3/bash-clone) still enforce the full-tree gate.
+if [ "$SYNC_SOURCE" != "env-override" ]; then
+  for REQUIRED in ".claude/skills" ".claude/hooks" ".claude/luminaries" ".claude/rules" ".claude/agents" "lib"; do
+    if [ ! -d "$BASSCLEF_DIR/$REQUIRED" ] || [ -z "$(ls -A "$BASSCLEF_DIR/$REQUIRED" 2>/dev/null)" ]; then
+      echo "### BASSCLEF SYNC FAILED — EMPTY OR PARTIAL TREE"
+      echo ""
+      echo "Bassclef tree is missing or empty at: $BASSCLEF_DIR/$REQUIRED"
+      echo "Source: $SYNC_SOURCE"
+      echo ""
+      echo "Recovery:"
+      echo "  - Peer source: re-pull \$CWD/../bassclef"
+      echo "  - S3 source: rm -rf \$HOME/bassclef and re-trigger; or re-run bassclef-s3-publish"
+      echo "  - Bash clone: check credentials; try again"
+      echo ""
+      exit 0
+    fi
+  done
+fi
+
+# === 2. Copy bassclef skills into project for auto-discovery ===
+# Per goal 2026-08-29c #1417 Branch B (Option F full build) — swap ln -s → cp
+# so adopter owns the files. Symlinks break under operator mv/rename of
+# bassclef source; owned copies survive. Spike-proven per PR #1293.
+#
+# Migration cutover per ADR-031 grace window: existing symlinks land as
+# copies on the next sync. App-specific skills marked by absence of the
+# .bassclef-managed sentinel stay untouched.
+mkdir -p "$CWD/.claude/skills" 2>/dev/null || true
+SKILL_INSTALL_COUNT=0
+for SKILL_DIR in "$BASSCLEF_DIR/.claude/skills/"*/; do
+  SKILL_NAME=$(basename "$SKILL_DIR")
+  TARGET="$CWD/.claude/skills/$SKILL_NAME"
+  if [ -L "$TARGET" ]; then
+    # Existing symlink from prior sync — migrate to owned copy
+    rm "$TARGET"
+    cp -R "$SKILL_DIR" "$TARGET"
+    touch "$TARGET/.bassclef-managed" 2>/dev/null || true
+    SKILL_INSTALL_COUNT=$((SKILL_INSTALL_COUNT + 1))
+  elif [ ! -d "$TARGET" ]; then
+    # Doesn't exist — cp fresh
+    cp -R "$SKILL_DIR" "$TARGET"
+    touch "$TARGET/.bassclef-managed" 2>/dev/null || true
+    SKILL_INSTALL_COUNT=$((SKILL_INSTALL_COUNT + 1))
+  elif [ -f "$TARGET/.bassclef-managed" ]; then
+    # Prior cp'd bassclef skill — refresh in place (adopter files inside skill dir preserved)
+    cp -Rf "$SKILL_DIR"* "$TARGET/" 2>/dev/null || true
+    touch "$TARGET/.bassclef-managed" 2>/dev/null || true
+    SKILL_INSTALL_COUNT=$((SKILL_INSTALL_COUNT + 1))
+  fi
+  # Else: real dir without .bassclef-managed → app-specific override; leave alone
+done
+[ "$SKILL_INSTALL_COUNT" -gt 0 ] && echo "  bassclef-sync: installed/refreshed $SKILL_INSTALL_COUNT skill(s) via cp" >&2 || true
+
+# === 2b. Park user-level orphans (widened per ADR-033 + bassclef#278; settings-aware per #294) ===
+# Closes the skill / agent / hook duplication-in-available-skills bug.
+# Calls the shared orphan-parking helper for each surface where user-level
+# entries can duplicate project-level entries. Helper:
+#   - Parks symlinks AND cp'd files whose basename matches project-level
+#   - Leaves real directories untouched (operator-authored content)
+#   - EXCLUDES hooks wired in ~/.claude/settings.json at $HOME paths
+#     (per #294 — settings.json wiring is observable behavior; parking
+#     must not break it)
+#   - Idempotent — re-running on already-parked state is a no-op
+#   - Backup dirs (~/.claude/<prefix>.orphans.<date>/) survive 30 days
+#     minimum per Hyrum + Linus discipline
+PARKING_HELPER="$BASSCLEF_DIR/scripts/bassclef-orphan-parking.sh"
+USER_SETTINGS="$HOME/.claude/settings.json"
+ORPHAN_COUNT=0
+if [ -f "$PARKING_HELPER" ]; then
+  for surface in skills agents hooks; do
+    USER_SURFACE="$HOME/.claude/$surface"
+    PROJECT_SURFACE="$CWD/.claude/$surface"
+    if [ -d "$USER_SURFACE" ] && [ -d "$PROJECT_SURFACE" ]; then
+      mkdir -p "$HOME/.claude" 2>/dev/null
+      # Settings-aware: passing user settings.json as 5th arg so wired
+      # hooks are excluded from parking (#294).
+      PARKED_LINE=$(bash "$PARKING_HELPER" "$USER_SURFACE" "$PROJECT_SURFACE" "$HOME/.claude" "$surface" "$USER_SETTINGS" 2>/dev/null || echo "")
+      if [ -n "$PARKED_LINE" ]; then
+        COUNT_N=$(echo "$PARKED_LINE" | grep -oE 'parked [0-9]+' | grep -oE '[0-9]+' | head -1)
+        [ -n "$COUNT_N" ] && ORPHAN_COUNT=$((ORPHAN_COUNT + COUNT_N))
+      fi
+    fi
+  done
+fi
+
+# === 3a. Copy bassclef hooks into repo (same pattern as skills) ===
+# Per goal 2026-08-29c #1417 Branch B (Option F full build) — swap ln -s → cp
+# so adopter owns the hook files. Symlinks break under operator mv/rename;
+# owned copies survive. Spike-proven per PR #1293 (6/6 assertions).
+#
+# Shared hooks come from bassclef. bassclef-sync.sh itself is always
+# app-specific (it IS the sync mechanism) — skipped.
+# In SELF_MODE (bassclef-on-bassclef, #293), skip entirely.
+# Migration cutover per ADR-031: existing symlinks land as copies on next sync.
+if [ "${SELF_MODE:-}" != "1" ]; then
+  mkdir -p "$CWD/.claude/hooks" 2>/dev/null || true
+  HOOK_INSTALL_COUNT=0
+  for HOOK_FILE in "$BASSCLEF_DIR/.claude/hooks/"*.sh; do
+    [ -f "$HOOK_FILE" ] || continue
+    HOOK_NAME=$(basename "$HOOK_FILE")
+    TARGET="$CWD/.claude/hooks/$HOOK_NAME"
+    # Skip self — bassclef-sync.sh is app-specific
+    [ "$HOOK_NAME" = "bassclef-sync.sh" ] && continue
+
+    # 2026-09-15 goal 14c Step 6 — install-class filter.
+    # Section 3b's dispatch loop routes headered hooks per their declared
+    # class. Section 3a stays as the grace-path bulk-copy for UNHEADERED
+    # hooks only (through 2026-10-31 per ADR-058 C2). Any hook with a
+    # valid `# install-class:` header is handled by Section 3b — skip
+    # here to avoid a double-cp per finding L-F3 (2026-09-15c review).
+    # Also skip hooks whose source-graph walker fails — those would
+    # break at load time regardless of scope.
+    _INSTALL_CLASS=$(head -10 "$HOOK_FILE" 2>/dev/null | grep -E \
+                     '^# install-class:[[:space:]]*(operator|project|dual)$' \
+                     | head -1 | sed -E \
+                     's/^# install-class:[[:space:]]*//;s/[[:space:]]*$//')
+    if [ -n "$_INSTALL_CLASS" ]; then
+      continue
+    fi
+
+    # Walker check — skip project-scope copy if source-graph resolution fails.
+    # Section 3b's dispatch will also skip via install_by_class's own walker.
+    if [ -f "$BASSCLEF_DIR/lib/source-graph-walker.sh" ]; then
+      _WALKER_MISSING=$(
+        source "$BASSCLEF_DIR/lib/source-graph-walker.sh" 2>/dev/null
+        walk_source_dependents "$HOOK_FILE" 2>/dev/null || true
+      )
+      if [ -n "$_WALKER_MISSING" ]; then
+        # Trace + skip both scopes for this hook
+        : "${BASSCLEF_TRACE_LOG:=${BASSCLEF_TRACE_FILE:-$HOME/.claude/state/trace.log}}"
+        mkdir -p "$(dirname "$BASSCLEF_TRACE_LOG")" 2>/dev/null || true
+        echo "$(date -u +%FT%TZ) install-fail-missing-dep $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
+        continue
+      fi
+    fi
+
+    if [ -L "$TARGET" ]; then
+      # Existing symlink from prior sync — migrate to owned copy
+      rm "$TARGET"
+      cp "$HOOK_FILE" "$TARGET"
+    elif [ ! -f "$TARGET" ]; then
+      # Doesn't exist — cp fresh
+      cp "$HOOK_FILE" "$TARGET"
+    else
+      # Real file exists — overwrite with fresh cp (stale copy → bassclef source)
+      cp -f "$HOOK_FILE" "$TARGET"
+    fi
+    # Preserve execute bit on hook file (per prototype pattern)
+    chmod +x "$TARGET" 2>/dev/null || true
+    HOOK_INSTALL_COUNT=$((HOOK_INSTALL_COUNT + 1))
+  done
+  [ "$HOOK_INSTALL_COUNT" -gt 0 ] && echo "  bassclef-sync: installed/refreshed $HOOK_INSTALL_COUNT hook(s) via cp" >&2 || true
+fi
+
+# === 3a-postcheck. Verify every hook wired in settings.json has a resolvable target ===
+# Per bassclef-web#167 Cure Path 1 — the section 3a loop above enumerates
+# upstream files and symlinks them. It does NOT verify that every hook
+# referenced in project OR operator settings.json ended up with a resolvable
+# target on-disk. When the initial loop fails (stale $BASSCLEF_DIR, upstream
+# file added after sync ran, or SELF_MODE), no postcondition check catches it.
+# The failure surfaces as SessionStart file-not-found errors — worse when the
+# missing hook IS the reflection layer that would surface the drift as BLOCKED.
+#
+# This block iterates every hook command in project + operator settings.json
+# that references $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh. For each name:
+#   1. If symlink or file exists at $CWD/.claude/hooks/<name> → OK (silent)
+#   2. Else if upstream $BASSCLEF_DIR/.claude/hooks/<name> exists → create symlink
+#      + log INFO (self-heal path)
+#   3. Else → collect for structured BLOCKED emission at end
+#
+# Per @luminary saltzer-schroeder (complete mediation — every wired hook mediated)
+# + @luminary michael-nygard (fail-fast on drift — no silent gaps)
+# + @luminary hyrum-wright (settings.json wiring is observed adopter behavior).
+if [ "${SELF_MODE:-}" != "1" ] && command -v jq >/dev/null 2>&1; then
+  BASSCLEF_SYNC_POSTCHECK_MISSING=()
+  BASSCLEF_SYNC_POSTCHECK_CURED=()
+
+  extract_wired_hook_names() {
+    local settings="$1"
+    [ ! -f "$settings" ] && return 0
+    jq empty "$settings" >/dev/null 2>&1 || return 0
+    # Walk any object with a .command field; extract hook basenames from
+    # $CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh references (bash + direct).
+    jq -r '..
+      | objects
+      | select(.command? != null)
+      | .command' "$settings" 2>/dev/null \
+      | grep -oE '\$CLAUDE_PROJECT_DIR/\.claude/hooks/[a-zA-Z0-9_.-]+\.sh' \
+      | sed 's|.*/hooks/||' \
+      | sort -u \
+      || true
+  }
+
+  # Union hook names from project + operator settings.json
+  BASSCLEF_SYNC_WIRED_NAMES=$(
+    {
+      extract_wired_hook_names "$CWD/.claude/settings.json"
+      extract_wired_hook_names "$HOME/.claude/settings.json"
+    } | sort -u
+  )
+
+  for HOOK_NAME in $BASSCLEF_SYNC_WIRED_NAMES; do
+    [ -z "$HOOK_NAME" ] && continue
+    TARGET="$CWD/.claude/hooks/$HOOK_NAME"
+    # Present already — either symlink or real file — OK
+    if [ -L "$TARGET" ] || [ -f "$TARGET" ]; then
+      continue
+    fi
+    # Missing — try to cure via upstream symlink
+    SOURCE="$BASSCLEF_DIR/.claude/hooks/$HOOK_NAME"
+    if [ -f "$SOURCE" ]; then
+      mkdir -p "$CWD/.claude/hooks" 2>/dev/null || true
+      # Option F cp swap per #1417 Branch B — self-heal path uses cp not ln -s
+      if cp "$SOURCE" "$TARGET" 2>/dev/null; then
+        chmod +x "$TARGET" 2>/dev/null || true
+        BASSCLEF_SYNC_POSTCHECK_CURED+=("$HOOK_NAME")
+      else
+        BASSCLEF_SYNC_POSTCHECK_MISSING+=("$HOOK_NAME (upstream present at $SOURCE; cp failed)")
+      fi
+    else
+      BASSCLEF_SYNC_POSTCHECK_MISSING+=("$HOOK_NAME (upstream missing at $SOURCE)")
+    fi
+  done
+
+  # Report cured (informational — self-heal succeeded via cp per #1417 Branch B)
+  if [ "${#BASSCLEF_SYNC_POSTCHECK_CURED[@]}" -gt 0 ]; then
+    echo "  bassclef-sync: cured ${#BASSCLEF_SYNC_POSTCHECK_CURED[@]} missing hook file(s): ${BASSCLEF_SYNC_POSTCHECK_CURED[*]}"
+  fi
+
+  # Report unresolvable — structured BLOCKED with cure command inline
+  if [ "${#BASSCLEF_SYNC_POSTCHECK_MISSING[@]}" -gt 0 ]; then
+    {
+      echo ""
+      echo "🛑 BLOCKED: settings-drift — ${#BASSCLEF_SYNC_POSTCHECK_MISSING[@]} wired hook(s) missing target on-disk"
+      for M in "${BASSCLEF_SYNC_POSTCHECK_MISSING[@]}"; do
+        echo "  - $M"
+      done
+      echo ""
+      echo "Root cause class: settings.json wires a hook that has no matching file on-disk."
+      echo "Resolve: verify upstream bassclef has the hook file, then re-run:"
+      echo "  bash ~/.claude/hooks/bassclef-sync.sh"
+      echo "Per bassclef-web#167 Cure Path 1."
+      echo ""
+    } >&2
+  fi
+fi
+
+# === 3a-fragments. Symlink hook subdirectory fragments ===
+# Per bet 2026-07-04c WU-2 — the section 3a loop above uses a shallow glob
+# (.claude/hooks/*.sh). It does not recurse into subdirectories like
+# session-reflection.d/. For adopters that copy files rather than symlink
+# (R2 tarball, npm install, curl script), the fragment never lands on
+# adopter disk without this block.
+#
+# Allow-list — only named subdirectories propagate. Unknown subdirs
+# (tests/, _lib/) do NOT propagate. Extend HOOK_FRAGMENT_DIRS as bassclef
+# adds new event-fragment directories. Per @luminary michael-nygard
+# (steady state via allow-list) + @luminary john-ousterhout (per-scan log
+# line — silent success is as dangerous as silent failure).
+if [ "${SELF_MODE:-}" != "1" ]; then
+  HOOK_FRAGMENT_DIRS=(session-reflection.d)
+  for FRAG_DIR in "${HOOK_FRAGMENT_DIRS[@]}"; do
+    SRC_FRAG_DIR="$BASSCLEF_DIR/.claude/hooks/$FRAG_DIR"
+    if [ ! -d "$SRC_FRAG_DIR" ]; then
+      continue
+    fi
+    # Count fragments before scanning; empty subdir stays silent.
+    FRAG_COUNT=$(find "$SRC_FRAG_DIR" -maxdepth 1 -name "*.sh" -type f 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$FRAG_COUNT" = "0" ]; then
+      continue
+    fi
+    DST_FRAG_DIR="$CWD/.claude/hooks/$FRAG_DIR"
+    mkdir -p "$DST_FRAG_DIR" 2>/dev/null || true
+    echo "[bassclef-sync] recursing into .claude/hooks/$FRAG_DIR/ ($FRAG_COUNT fragments)" >&2
+    for FRAG_FILE in "$SRC_FRAG_DIR"/*.sh; do
+      [ -f "$FRAG_FILE" ] || continue
+      FRAG_NAME=$(basename "$FRAG_FILE")
+      TARGET="$DST_FRAG_DIR/$FRAG_NAME"
+      # Option F cp swap per #1417 Branch B — adopter owns fragment file
+      if [ -L "$TARGET" ]; then
+        # Existing symlink from prior sync — migrate to owned copy
+        rm "$TARGET"
+        cp "$FRAG_FILE" "$TARGET"
+      elif [ ! -f "$TARGET" ]; then
+        # Doesn't exist — cp fresh
+        cp "$FRAG_FILE" "$TARGET"
+      else
+        # Real file exists — overwrite with fresh cp (stale copy → bassclef)
+        cp -f "$FRAG_FILE" "$TARGET"
+      fi
+      chmod +x "$TARGET" 2>/dev/null || true
+    done
+  done
+fi
+
+# === 3b. Install-class dispatch — per-hook routing via header (goal 14c Step 6) ===
+#
+# Iterates every substrate hook. For each hook, reads the `# install-class:`
+# header and routes the copy per the declared value (operator, project, dual).
+# Hooks without a header fall through to the legacy path per ADR-058 D2
+# grace window (through 2026-10-31). session-reflection.d fragments run the
+# same dispatch shape, preserving their subdirectory at each target.
+#
+# Historical note — the pre-Step-6 shape here installed a hardcoded 10-name
+# list of user-level hooks. The new full-bundle iteration replaces it. Every
+# hook the 10-name list carried still installs — either via dispatch (when
+# header present) or via grace-window fallback (when absent).
+#
+# Discipline per ADR-058:
+#   C1 — install_by_class wrapped in subshell; lib strict mode contained
+#   C2 — unheadered hooks install where they installed today + one trace line
+#   C3 — CLAUDE_PROJECT_DIR exported before the loop (uses $CWD)
+#   C4 — settings.json command strings unchanged (see migration manifest at
+#        docs/operator-private/forward-port-registry/migrations/
+#        2026-09-15-install-class-dispatch.md)
+#   R7 — fail-soft with trace on permission denied
+#
+# Test coverage per presence/install/tests/bassclef-sync-install-by-class.test.sh
+# T1-T21 (21 tests × 45 sub-assertions).
+#
+# Architect-review 2026-09-15c findings folded inline — L-F2, S-F1, S-F2, M-F1, N-F1.
+
+# ADR-058 C3 — export CLAUDE_PROJECT_DIR before the loop
+export CLAUDE_PROJECT_DIR="$CWD"
+
+# Bridge env var — lib uses BASSCLEF_TRACE_LOG; adopters may already set it
+: "${BASSCLEF_TRACE_LOG:=${BASSCLEF_TRACE_FILE:-$HOME/.claude/state/trace.log}}"
+export BASSCLEF_TRACE_LOG
+mkdir -p "$(dirname "$BASSCLEF_TRACE_LOG")" 2>/dev/null || true
+
+# Resolve dispatch lib + init counters
+DISPATCH_LIB="$BASSCLEF_DIR/lib/hook-installer.sh"
+DISPATCH_AVAILABLE=0
+[ -f "$DISPATCH_LIB" ] && DISPATCH_AVAILABLE=1
+
+INSTALLED_COUNT=0
+SKIPPED_NO_HEADER=0
+SKIPPED_INVALID=0
+SKIPPED_LIB_MISSING=0
+FAILED_COUNT=0
+
+mkdir -p "$HOME/.claude/hooks" 2>/dev/null || true
+
+# Loop 1 — top-level hooks (S-F2 LOW: dir-exists guard)
+if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
+  for HOOK_SRC in "$BASSCLEF_DIR/.claude/hooks/"*.sh; do
+    [ -f "$HOOK_SRC" ] || continue                          # T16: glob excludes .sh.bak
+
+    HOOK_NAME=$(basename "$HOOK_SRC")
+    TARGET_USER="$HOME/.claude/hooks/$HOOK_NAME"
+
+    # M-F1 MED — rm existing symlink at target before cp (T14 assertion)
+    [ -L "$TARGET_USER" ] && rm -f "$TARGET_USER"
+
+    # Header check — strict regex mirrors operator sync L127
+    if head -10 "$HOOK_SRC" 2>/dev/null | grep -qE \
+         '^# install-class:[[:space:]]*(operator|project|dual)$'; then
+      HAS_HEADER=1
+    else
+      HAS_HEADER=0
+    fi
+
+    if [ "$HAS_HEADER" = "1" ] && [ "$DISPATCH_AVAILABLE" = "1" ]; then
+      # Walker check — if source-graph dependent(s) missing, do NOT install.
+      # Trace install-fail-missing-dep + skip both scopes.
+      _WALKER_MISS=""
+      if [ -f "$BASSCLEF_DIR/lib/source-graph-walker.sh" ]; then
+        _WALKER_MISS=$(
+          source "$BASSCLEF_DIR/lib/source-graph-walker.sh" 2>/dev/null
+          walk_source_dependents "$HOOK_SRC" 2>/dev/null || true
+        )
+      fi
+      if [ -n "$_WALKER_MISS" ]; then
+        echo "$(date -u +%FT%TZ) install-fail-missing-dep $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
+        FAILED_COUNT=$((FAILED_COUNT + 1))
+        continue
+      fi
+
+      # ADR-058 C1 — subshell wraps install_by_class; lib strict mode contained
+      # shellcheck disable=SC1090
+      if ( source "$DISPATCH_LIB" 2>/dev/null && install_by_class "$HOOK_SRC" ) \
+           >/dev/null 2>&1; then
+        INSTALLED_COUNT=$((INSTALLED_COUNT + 1))
+      else
+        # T12 — fallback copy on subshell failure (non-walker cause)
+        cp -p "$HOOK_SRC" "$TARGET_USER" 2>/dev/null || true
+        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))
+      fi
+    elif [ "$HAS_HEADER" = "1" ] && [ "$DISPATCH_AVAILABLE" = "0" ]; then
+      # S-F1 MED — dispatch lib missing; trace explicitly (not silent)
+      cp -p "$HOOK_SRC" "$TARGET_USER" 2>/dev/null || true
+      chmod +x "$TARGET_USER" 2>/dev/null || true
+      echo "$(date -u +%FT%TZ) dispatch-lib-missing $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
+      SKIPPED_LIB_MISSING=$((SKIPPED_LIB_MISSING + 1))
+    else
+      # ADR-058 C2 — grace window fallback; unheadered OR invalid-header hook.
+      # L-F2 MED — additive-only during grace; do NOT rm legacy operator-scope copies.
+      cp -p "$HOOK_SRC" "$TARGET_USER" 2>/dev/null || true
+      chmod +x "$TARGET_USER" 2>/dev/null || true
+      if [ "$HAS_HEADER" = "0" ]; then
+        echo "$(date -u +%FT%TZ) skipped-no-header $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
+        SKIPPED_NO_HEADER=$((SKIPPED_NO_HEADER + 1))
+      else
+        echo "$(date -u +%FT%TZ) skipped-invalid-header $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
+        SKIPPED_INVALID=$((SKIPPED_INVALID + 1))
+      fi
+    fi
+  done
+fi
+
+# Loop 2 — session-reflection.d fragments (same shape; preserves subdir at target)
+# install_by_class flattens to $HOME/.claude/hooks/; fragments need the subdir
+# preserved so hook loaders find them. Inline the header-based dispatch here.
+if [ -d "$BASSCLEF_DIR/.claude/hooks/session-reflection.d" ]; then
+  mkdir -p "$HOME/.claude/hooks/session-reflection.d" 2>/dev/null || true
+  for FRAG_SRC in "$BASSCLEF_DIR/.claude/hooks/session-reflection.d/"*.sh; do
+    [ -f "$FRAG_SRC" ] || continue                          # T16: glob excludes .sh.bak
+
+    FRAG_NAME=$(basename "$FRAG_SRC")
+
+    # Read header value (strict regex)
+    FRAG_CLASS=""
+    HEADER_LINE=$(head -10 "$FRAG_SRC" 2>/dev/null | grep -E \
+                  '^# install-class:[[:space:]]*(operator|project|dual)$' \
+                  | head -1)
+    if [ -n "$HEADER_LINE" ]; then
+      FRAG_CLASS=$(echo "$HEADER_LINE" | sed -E \
+                   's/^# install-class:[[:space:]]*//;s/[[:space:]]*$//')
+    fi
+
+    case "$FRAG_CLASS" in
+      operator|dual)
+        TARGET_USER_FRAG="$HOME/.claude/hooks/session-reflection.d/$FRAG_NAME"
+        [ -L "$TARGET_USER_FRAG" ] && rm -f "$TARGET_USER_FRAG"
+        cp -p "$FRAG_SRC" "$TARGET_USER_FRAG" 2>/dev/null || true
+        chmod +x "$TARGET_USER_FRAG" 2>/dev/null || true
+        ;;
+    esac
+    # project scope handled by Section 3a-fragments above (L768-802).
+    # dual class lands at both — 3a-fragments does project, this loop does user.
+  done
+fi
+
+# N-F1 MED — install summary with reason breakdown when non-zero
+SKIPPED_TOTAL=$((SKIPPED_NO_HEADER + SKIPPED_INVALID + SKIPPED_LIB_MISSING))
+if [ "$SKIPPED_TOTAL" = "0" ] && [ "$FAILED_COUNT" = "0" ]; then
+  echo "bassclef-sync: installed $INSTALLED_COUNT hooks; skipped 0; failed 0"
+else
+  BREAKDOWN=""
+  [ "$SKIPPED_NO_HEADER" -gt 0 ] && BREAKDOWN="$BREAKDOWN, $SKIPPED_NO_HEADER grace-window"
+  [ "$SKIPPED_INVALID" -gt 0 ] && BREAKDOWN="$BREAKDOWN, $SKIPPED_INVALID invalid-header"
+  [ "$SKIPPED_LIB_MISSING" -gt 0 ] && BREAKDOWN="$BREAKDOWN, $SKIPPED_LIB_MISSING dispatch-lib-missing"
+  BREAKDOWN="${BREAKDOWN#, }"
+  echo "bassclef-sync: installed $INSTALLED_COUNT hooks; skipped $SKIPPED_TOTAL ($BREAKDOWN); failed $FAILED_COUNT"
+fi
+
+# === 3b-cleanup. Lane 3 / hook-scope-move: remove legacy project-scope copies ===
+# Existing adopters have project-scope copies of the 3 SessionStart hooks
+# from prior bassclef installs. Post-Lane-3 the user-scope copies (installed
+# above) are the source of truth. Remove the project-scope files ONLY AFTER
+# the user-scope install succeeded — order matters per Linus adopter-compat.
+# Per docs/designs/2026-08-06-lane-3-canonical-wiring-race-cure.md § "Adopter
+# contract" — cure for R11 (existing adopters carry legacy project-scope
+# hooks that fire twice per session).
+#
+# Lane 3 extension (#1282, 2026-08-18): when we remove a project-scope hook
+# file, ALSO strip stale entries from adopter's .claude/settings.json that
+# still point at the removed path. R11 mitigation shipped file-only; the
+# wiring layer stayed broken (POA + siblings emit "No such file or directory"
+# every session because settings.json still references the removed files).
+# Full cure — files AND wiring migrate together per ADR-031.
+#
+# Pre-mortem full 8-lens ledger at docs/risk-ledgers/2026-08-18e-1282-lane-3-settings-cure.md;
+# top 12 risks folded into design (backup + atomic mv + jq empty validation
+# + preconditions + idempotent + fast-path + log line).
+
+amend_adopter_settings_for_removed_hook() {
+  local adopter_cwd="$1"
+  local hook_basename="$2"
+  local settings_file="$adopter_cwd/.claude/settings.json"
+
+  # H1: precondition — settings.json exists
+  [ -f "$settings_file" ] || return 0
+
+  # H2: precondition — valid JSON (else INFORM + no-op)
+  if ! jq empty "$settings_file" 2>/dev/null; then
+    echo "  bassclef-sync: settings.json at $settings_file is invalid JSON; skipping Lane 3 amend for $hook_basename (INFORM)" >&2
+    return 0
+  fi
+
+  # H3: precondition — has .hooks key
+  jq -e '.hooks' "$settings_file" >/dev/null 2>&1 || return 0
+
+  # F5: fast-path — count entries matching hook basename; skip if zero (no diff, no backup)
+  local stale_count
+  stale_count=$(jq --arg h "$hook_basename" \
+    '[.hooks | .. | objects | select((.command? // "") | endswith($h))] | length' \
+    "$settings_file" 2>/dev/null || echo 0)
+  if [ "${stale_count:-0}" = "0" ]; then
+    return 0
+  fi
+
+  # N1: backup with timestamped name (keep every backup; rotation deferred to follow-on)
+  local ts backup tmp
+  ts=$(date -u +%Y-%m-%dT%H-%M-%SZ)
+  backup="${settings_file}.bak.${ts}"
+  cp "$settings_file" "$backup" 2>/dev/null || return 0
+
+  # N2 atomic write via tempfile in same directory (same inode namespace → mv is atomic)
+  tmp="${settings_file}.tmp.$$"
+
+  # Strip inner hooks[] entries whose .command endswith hook_basename;
+  # also cull matcher-groups whose inner .hooks array became empty.
+  if ! jq --arg h "$hook_basename" \
+       '.hooks |= with_entries(
+          .value |= (
+            map(.hooks |= map(select(((.command // "") | endswith($h)) | not)))
+            | map(select(.hooks | length > 0))
+          )
+        )' \
+       "$settings_file" > "$tmp" 2>/dev/null; then
+    rm -f "$tmp"
+    echo "  bassclef-sync: jq amend failed for $hook_basename; original preserved; backup at $backup" >&2
+    return 0
+  fi
+
+  # L1 + H4: validate tmp is valid JSON before mv (guard against jq writing null)
+  if ! jq empty "$tmp" 2>/dev/null; then
+    rm -f "$tmp"
+    echo "  bassclef-sync: amended settings.json failed jq empty; original preserved; backup at $backup" >&2
+    return 0
+  fi
+
+  # N2 atomic mv
+  mv "$tmp" "$settings_file"
+
+  # NR1 + NR2 + NR4: log removed entry + backup path
+  echo "  bassclef-sync: removed $hook_basename entry from adopter settings.json; backup at $backup (Lane 3 / #1282)"
+}
+
+# --------------------------------------------------------------
+# verify + heal SessionStart auto-sync wiring — bassclef-upstream#1496
+#
+# Postcondition-check pattern per Nygard (stability patterns) + Saltzer-Schroeder
+# (complete mediation). Ships with backup + jq validate discipline mirrored from
+# amend_adopter_settings_for_removed_hook above (Lane 3 L846 pattern). Traces
+# every pre-mortem risk R3+R5+R11+R16+R19 to preventative code per plan
+# docs/plans/2026-09-06-auto-sync-strip-loop-plan.md.
+#
+# Exit codes for verify_sessionstart_wiring:
+#   0 — wiring intact OR opt-out sentinel present
+#   1 — wiring missing / entry absent
+#   2 — malformed JSON (caller should skip, not heal)
+# --------------------------------------------------------------
+
+verify_sessionstart_wiring() {
+  local settings_file="$1"
+
+  # Absent settings.json: nothing to verify against; return 1 (heal will create)
+  [ -f "$settings_file" ] || return 1
+
+  # R8 preventative — opt-out sentinel in _comment: skip
+  if grep -q 'BASSCLEF_AUTOSYNC_OFF=1' "$settings_file" 2>/dev/null; then
+    return 0
+  fi
+
+  # H2 preventative — malformed JSON: return 2 (caller skips heal to avoid corrupt)
+  if ! jq empty "$settings_file" 2>/dev/null; then
+    return 2
+  fi
+
+  # Check that at least one SessionStart entry points at bassclef-sync.sh
+  local hit
+  hit=$(jq -r '[.hooks.SessionStart // [] | .[] | .hooks // [] | .[] | .command // ""] | map(select(endswith("bassclef-sync.sh"))) | length' "$settings_file" 2>/dev/null || echo 0)
+  if [ "${hit:-0}" -ge 1 ]; then
+    return 0
+  fi
+
+  return 1
+}
+
+heal_sessionstart_wiring() {
+  local settings_file="$1"
+  local target_cmd="\$HOME/.claude/hooks/bassclef-sync.sh"
+
+  # H2 preventative — never touch malformed JSON: backup then skip
+  if [ -f "$settings_file" ] && ! jq empty "$settings_file" 2>/dev/null; then
+    local ts backup
+    ts=$(date -u +%Y-%m-%dT%H-%M-%SZ)
+    backup="${settings_file}.bak.${ts}"
+    cp "$settings_file" "$backup" 2>/dev/null || true
+    echo "  bassclef-sync: settings.json at $settings_file is invalid JSON; skipping heal; backup at $backup (INFORM)" >&2
+    return 0
+  fi
+
+  # R3 preventative — verify target path exists as executable before writing
+  # (checked at $HOME expansion; adopter machine)
+  local expanded_target="$HOME/.claude/hooks/bassclef-sync.sh"
+  if [ ! -x "$expanded_target" ]; then
+    echo "  bassclef-sync: target hook missing at $expanded_target; cannot heal (INFORM)" >&2
+    return 1
+  fi
+
+  # Create settings.json if absent — minimum valid shape
+  if [ ! -f "$settings_file" ]; then
+    mkdir -p "$(dirname "$settings_file")" 2>/dev/null || true
+    echo '{"hooks":{}}' > "$settings_file" 2>/dev/null || return 1
+  fi
+
+  # R5 preventative — backup with timestamped name before write
+  local ts backup tmp
+  ts=$(date -u +%Y-%m-%dT%H-%M-%SZ)
+  backup="${settings_file}.bak.${ts}"
+  cp "$settings_file" "$backup" 2>/dev/null || return 1
+
+  # R19 preventative — atomic write via tempfile + mv in same directory
+  tmp="${settings_file}.tmp.$$"
+
+  # Add bassclef-sync SessionStart entry — preserves other hooks
+  if ! jq --arg cmd "$target_cmd" '
+        .hooks //= {}
+        | .hooks.SessionStart //= []
+        | .hooks.SessionStart += [
+            { "matcher": "", "hooks": [
+                { "type": "command", "command": $cmd, "timeout": 30 }
+              ] }
+          ]
+      ' "$settings_file" > "$tmp" 2>/dev/null; then
+    rm -f "$tmp"
+    echo "  bassclef-sync: jq heal failed; original preserved; backup at $backup" >&2
+    return 1
+  fi
+
+  # H4+L1 preventative — validate tmp is valid JSON before mv
+  if ! jq empty "$tmp" 2>/dev/null; then
+    rm -f "$tmp"
+    echo "  bassclef-sync: healed settings.json failed jq empty; original preserved; backup at $backup" >&2
+    return 1
+  fi
+
+  mv "$tmp" "$settings_file"
+  echo "  bassclef-sync: healed SessionStart wiring in $settings_file; backup at $backup (bassclef-upstream#1496)"
+  return 0
+}
+
+# === LANE 3 LOOP BEGIN === (sentinel — used by test extractor per PR #1288 review A2)
+LEGACY_HOOKS_REMOVED=0
+for HOOK in vendored-dispatcher-refresh.sh session-reflection.sh session-start-recap-inject.sh; do
+  # Guard: only proceed when user-scope hook exists (proves Lane 3 migration succeeded — either now or earlier).
+  # Without this guard, we could amend adopter settings.json for hooks that have no user-scope home.
+  #
+  # Choice of `[ -f ]` over `[ -e ]` (per PR #1288 review A3):
+  # Section 3b installs user-scope hooks via `cp` (not symlink) — so broken symlinks in ~/.claude/hooks/
+  # are not a normal state we produce. `[ -f ]` returns true for regular files + symlinks that resolve
+  # to regular files, false for broken symlinks + missing files. If a prior 3b `cp` failed and left a
+  # broken symlink, we would silently skip amend on that hook. Trade-off accepted: false-negative on
+  # a broken symlink beats false-positive on a partial-install state.
+  if [ -f "$HOME/.claude/hooks/$HOOK" ]; then
+    # Remove project-scope file when still present (fresh Lane 3 case).
+    if [ -f "$CWD/.claude/hooks/$HOOK" ]; then
+      if rm "$CWD/.claude/hooks/$HOOK" 2>/dev/null; then
+        LEGACY_HOOKS_REMOVED=$((LEGACY_HOOKS_REMOVED + 1))
+      fi
+    fi
+    # Amend adopter settings.json unconditionally per hook (per #1282 follow-up).
+    # Handles both fresh-removal (project-scope just deleted) AND already-removed cases
+    # (project-scope deleted in prior sync; settings.json entry left dangling — POA state per smoke 2026-08-18e).
+    # Function is idempotent + fast-path when no matching entries — no diff, no backup.
+    # Bulkhead per Nygard N7: settings.json amend failure must not halt the loop.
+    { amend_adopter_settings_for_removed_hook "$CWD" "$HOOK"; } || true
+  fi
+done
+if [ "$LEGACY_HOOKS_REMOVED" -gt 0 ]; then
+  echo "  bassclef-sync: removed $LEGACY_HOOKS_REMOVED legacy project-scope SessionStart hook(s); user-scope copies now source of truth (Lane 3 / #1146)"
+fi
+# === LANE 3 LOOP END === (sentinel — used by test extractor per PR #1288 review A2)
+
+# === 3b-skills. Symlink bassclef skills into ~/.claude/skills/ (dir-level) ===
+# Per goal 2026-09-01 #1444 — revert PR #1428 + PR #1446 cp swap for skills only.
+# The Skill tool registry double-registered cp'd skills at project + user-global
+# scope, producing every skill twice in the type-ahead menu. Dir-level symlink
+# collapses the two registrations back to one entry.
+#
+# Hooks + lib + agents + luminaries stay on cp per #1428 + #1446 rationale —
+# adopters may edit those. Skills are read-mostly; adopters do not edit skill
+# bodies. Sister ADR-031; sister risk ledger docs/risk-ledgers/2026-09-01c-1444-*
+#
+# Three branches encode migration state (Peirce lens per RFC-0002):
+#   Branch A — fresh install (target absent): create symlink
+#   Branch B — existing symlink: leave if right target, refresh if stale
+#   Branch C — cp'd dir with .bassclef-managed marker: rm-and-symlink to
+#             migrate adopters from #1428 era on next sync
+#   Skip     — real dir without .bassclef-managed marker: adopter override,
+#             leave alone (R-L1 fold per Linus)
+#
+# Nygard N7 bulkhead per R-N1 — a single skill's symlink failure logs to
+# stderr and the loop continues. No one skill halts the sync.
+mkdir -p ~/.claude/skills 2>/dev/null || true
+USER_SKILL_INSTALL_COUNT=0
+USER_SKILL_MIGRATE_COUNT=0
+USER_SKILL_REFRESH_COUNT=0
+for SKILL_DIR in "$BASSCLEF_DIR/.claude/skills/"*/; do
+  SKILL_NAME=$(basename "$SKILL_DIR")
+  TARGET="$HOME/.claude/skills/$SKILL_NAME"
+  SKILL_SRC="${SKILL_DIR%/}"  # strip trailing slash for readlink comparison
+  ACTION=""
+  if [ -L "$TARGET" ]; then
+    # Branch B — existing symlink
+    CURRENT_TARGET=$(readlink "$TARGET" 2>/dev/null || echo "")
+    if [ "$CURRENT_TARGET" = "$SKILL_SRC" ]; then
+      continue  # already correct — no-op
+    fi
+    rm "$TARGET"
+    ACTION="refresh"
+  elif [ ! -e "$TARGET" ]; then
+    # Branch A — fresh install
+    ACTION="fresh"
+  elif [ -d "$TARGET" ] && [ -f "$TARGET/.bassclef-managed" ]; then
+    # Branch C — migrate cp'd dir from #1428 era back to symlink
+    rm -rf "$TARGET"
+    ACTION="migrate"
+  else
+    continue  # adopter override — leave alone (R-L1)
+  fi
+  if ln -s "$SKILL_SRC" "$TARGET" 2>/dev/null; then
+    USER_SKILL_INSTALL_COUNT=$((USER_SKILL_INSTALL_COUNT + 1))
+    case "$ACTION" in
+      migrate) USER_SKILL_MIGRATE_COUNT=$((USER_SKILL_MIGRATE_COUNT + 1)) ;;
+      refresh) USER_SKILL_REFRESH_COUNT=$((USER_SKILL_REFRESH_COUNT + 1)) ;;
+    esac
+  else
+    echo "  bassclef-sync: warn — symlink $ACTION failed for $SKILL_NAME; skill not installed at user scope" >&2
+  fi
+done
+if [ "$USER_SKILL_INSTALL_COUNT" -gt 0 ]; then
+  echo "  bassclef-sync: installed $USER_SKILL_INSTALL_COUNT user-level skill(s) via symlink (migrated: $USER_SKILL_MIGRATE_COUNT, refreshed: $USER_SKILL_REFRESH_COUNT)" >&2
+fi
+# === 3b-skills-end. ===
+
+# === Install agents to ~/.claude/ ===
+mkdir -p ~/.claude/agents 2>/dev/null || true
+cp "$BASSCLEF_DIR/.claude/agents/"*.md ~/.claude/agents/ 2>/dev/null || true
+
+# === 3c. Copy luminaries into project (per-file cp inside real dir) ===
+# Per goal 2026-08-29c #1417 Branch B (Option F full build) + goal 2026-08-31
+# #1429 (remaining paths) — swap ln -s whole-dir → cp per file. Symlinks break
+# under operator mv/rename of bassclef source; owned copies survive. Adopter-
+# added luminary files inside the dir preserved (cp -f overwrites matching
+# names only). See standards/pluggable-luminaries.md for file architecture.
+#
+# Migration cutover per ADR-031: existing whole-dir symlink → real dir with
+# bassclef files cp'd in.
+if [ "${SELF_MODE:-}" != "1" ] && [ -d "$BASSCLEF_DIR/.claude/luminaries" ]; then
+  TARGET="$CWD/.claude/luminaries"
+  # Migrate prior whole-dir symlink OR create fresh dir
+  if [ -L "$TARGET" ]; then
+    rm "$TARGET"
+    mkdir -p "$TARGET"
+  elif [ ! -e "$TARGET" ]; then
+    mkdir -p "$TARGET"
+  fi
+  # Refresh bassclef luminary files inside the dir (per-file cp; adopter files preserved)
+  if [ -d "$TARGET" ]; then
+    LUMINARIES_INSTALL_COUNT=0
+    for LUMINARY_FILE in "$BASSCLEF_DIR/.claude/luminaries/"*.md; do
+      [ -f "$LUMINARY_FILE" ] || continue
+      LUMINARY_NAME=$(basename "$LUMINARY_FILE")
+      cp -f "$LUMINARY_FILE" "$TARGET/$LUMINARY_NAME"
+      LUMINARIES_INSTALL_COUNT=$((LUMINARIES_INSTALL_COUNT + 1))
+    done
+    [ "$LUMINARIES_INSTALL_COUNT" -gt 0 ] && echo "  bassclef-sync: installed/refreshed $LUMINARIES_INSTALL_COUNT luminary/luminaries via cp" >&2 || true
+  fi
+fi
+
+# === 3d. Copy rules directory (per-file cp inside a real dir) ===
+# Per goal 2026-08-29c #1417 Branch B — swap ln -s whole-dir → cp per file.
+# Bassclef's rules are loaded via additionalDirectories in settings.json,
+# but tools that grep .claude/rules/<name>.md directly (skill SKILL.md
+# bodies, hook scripts, agent definitions) need them at the standard path.
+#
+# Migration cutover per ADR-031: existing whole-dir symlink → real dir with
+# bassclef files cp'd in. Adopter-added rule files inside the dir preserved
+# (cp -f overwrites matching names only).
+if [ "${SELF_MODE:-}" != "1" ] && [ -d "$BASSCLEF_DIR/.claude/rules" ]; then
+  TARGET="$CWD/.claude/rules"
+  # Migrate prior whole-dir symlink OR create fresh dir
+  if [ -L "$TARGET" ]; then
+    rm "$TARGET"
+    mkdir -p "$TARGET"
+  elif [ ! -e "$TARGET" ]; then
+    mkdir -p "$TARGET"
+  fi
+  # Refresh bassclef rule files inside the dir (per-file cp; adopter files preserved)
+  if [ -d "$TARGET" ]; then
+    RULES_INSTALL_COUNT=0
+    for RULE_FILE in "$BASSCLEF_DIR/.claude/rules/"*.md; do
+      [ -f "$RULE_FILE" ] || continue
+      RULE_NAME=$(basename "$RULE_FILE")
+      cp -f "$RULE_FILE" "$TARGET/$RULE_NAME"
+      RULES_INSTALL_COUNT=$((RULES_INSTALL_COUNT + 1))
+    done
+    [ "$RULES_INSTALL_COUNT" -gt 0 ] && echo "  bassclef-sync: installed/refreshed $RULES_INSTALL_COUNT rule(s) via cp" >&2 || true
+  fi
+fi
+
+# === 3d-bis. Copy .claude/bassclef-orientation.md (bassclef-upstream#925 + #1429) ===
+# CLAUDE.md carries `@.claude/bassclef-orientation.md` at line 2 (per ADR-032).
+# Without this symlink, the @import resolves only if bassclef sibling loads via
+# additionalDirectories. When the sibling path breaks (rename, delete, corp
+# laptop with no sibling), the import silently no-ops. Substrate discipline
+# vanishes from every session with zero visible signal.
+#
+# Cure: symlink the orientation file into the adopter's .claude/ so the @import
+# resolves without depending on additionalDirectories. Follows the same pattern
+# as 3c (luminaries), 3d (rules), 3e (agents) — but for a single file.
+#
+# Per @luminary linus-torvalds — we do not break adopters. The failure surface
+# for this class is silent-and-critical; a symlink closes it structurally.
+if [ "${SELF_MODE:-}" != "1" ] && [ -f "$BASSCLEF_DIR/.claude/bassclef-orientation.md" ]; then
+  mkdir -p "$CWD/.claude" 2>/dev/null
+  TARGET="$CWD/.claude/bassclef-orientation.md"
+  # Per goal 2026-08-31 #1429 — swap ln -s → cp so adopter owns the file.
+  # Symlinks break under bassclef source mv/rename; owned copies survive.
+  if [ -L "$TARGET" ]; then
+    rm "$TARGET"
+    cp -f "$BASSCLEF_DIR/.claude/bassclef-orientation.md" "$TARGET"
+  elif [ ! -e "$TARGET" ]; then
+    cp -f "$BASSCLEF_DIR/.claude/bassclef-orientation.md" "$TARGET"
+  elif [ -f "$TARGET" ]; then
+    # Refresh bassclef copy in place (rare — file evolves with each release)
+    cp -f "$BASSCLEF_DIR/.claude/bassclef-orientation.md" "$TARGET"
+  fi
+  # Else: a real dir or other non-file target — leave alone
+fi
+
+# === 3e. Copy agents into project (per-file cp inside real dir) ===
+# Per goal 2026-08-31 #1429 — swap ln -s → cp so adopter owns files.
+# Project-level cp complements the ~/.claude/agents/ user-global cp at
+# L970-971 (which serves the Agent-tool registry, similar to ~/.claude/skills/).
+#
+# Migration cutover per ADR-031: existing whole-dir symlink → real dir with
+# bassclef agent files cp'd in. Adopter-added agent files preserved.
+if [ "${SELF_MODE:-}" != "1" ] && [ -d "$BASSCLEF_DIR/.claude/agents" ]; then
+  TARGET="$CWD/.claude/agents"
+  # Migrate prior whole-dir symlink OR create fresh dir
+  if [ -L "$TARGET" ]; then
+    rm "$TARGET"
+    mkdir -p "$TARGET"
+  elif [ ! -e "$TARGET" ]; then
+    mkdir -p "$TARGET"
+  fi
+  # Refresh bassclef agent files inside the dir (per-file cp; adopter files preserved)
+  if [ -d "$TARGET" ]; then
+    AGENTS_INSTALL_COUNT=0
+    for AGENT_FILE in "$BASSCLEF_DIR/.claude/agents/"*.md; do
+      [ -f "$AGENT_FILE" ] || continue
+      AGENT_NAME=$(basename "$AGENT_FILE")
+      cp -f "$AGENT_FILE" "$TARGET/$AGENT_NAME"
+      AGENTS_INSTALL_COUNT=$((AGENTS_INSTALL_COUNT + 1))
+    done
+    [ "$AGENTS_INSTALL_COUNT" -gt 0 ] && echo "  bassclef-sync: installed/refreshed $AGENTS_INSTALL_COUNT agent(s) via cp" >&2 || true
+  fi
+fi
+
+# === 3f. Copy lib into consumer root (per-file cp inside real dir) ===
+# Per goal 2026-08-31 #1429 — swap ln -s → cp so adopter owns files.
+# lib/state.sh, lib/composer-preflight.sh, lib/release-version.sh, etc. are
+# state-spine accessors and shared helpers. They live at bassclef's repo
+# root (NOT under .claude/) so consumers own them at their root too. Skills
+# (e.g. /preview-build pre-flight per bassclef#408, release-to-bassclef.sh
+# per #1435 helper extract) source these by relative path.
+#
+# Migration cutover per ADR-031: existing whole-dir symlink → real dir with
+# bassclef lib files cp'd in. Adopter-added lib files preserved.
+if [ "${SELF_MODE:-}" != "1" ] && [ -d "$BASSCLEF_DIR/lib" ]; then
+  TARGET="$CWD/lib"
+  # Migrate prior whole-dir symlink OR create fresh dir
+  if [ -L "$TARGET" ]; then
+    rm "$TARGET"
+    mkdir -p "$TARGET"
+  elif [ ! -e "$TARGET" ]; then
+    mkdir -p "$TARGET"
+  fi
+  # Refresh bassclef lib files inside the dir (per-file cp; adopter files preserved)
+  # Note: recursive cp -R for subdirs (e.g. lib/adapters/, lib/tests/)
+  if [ -d "$TARGET" ]; then
+    LIB_INSTALL_COUNT=0
+    for LIB_ENTRY in "$BASSCLEF_DIR/lib/"*; do
+      [ -e "$LIB_ENTRY" ] || continue
+      LIB_NAME=$(basename "$LIB_ENTRY")
+      if [ -d "$LIB_ENTRY" ]; then
+        cp -Rf "$LIB_ENTRY" "$TARGET/"
+      else
+        cp -f "$LIB_ENTRY" "$TARGET/$LIB_NAME"
+      fi
+      LIB_INSTALL_COUNT=$((LIB_INSTALL_COUNT + 1))
+    done
+    [ "$LIB_INSTALL_COUNT" -gt 0 ] && echo "  bassclef-sync: installed/refreshed $LIB_INSTALL_COUNT lib entr(y|ies) via cp" >&2 || true
+  fi
+fi
+
+# === 3c-ignore. Maintain .gitignore block for bassclef symlinks ===
+# Symlinks into ../bassclef are per-machine artifacts, not content. Enumerate
+# them explicitly so real app-specific dirs (e.g. deploy-prod/) stay tracked.
+# Managed block — rewritten each sync between sentinels.
+#
+# bassclef#589 (Phase IIIb WU-3): block ownership extends to the
+# missing-file case. If consumer wholesale-deletes .gitignore (or never
+# had one), bassclef creates it with the managed block on next sync.
+# This covers the symmetric case to consumer-wholesale-rewrite (already
+# handled — the BEGIN/END awk loop survives rewrites since bassclef
+# re-appends the block).
+GITIGNORE="$CWD/.gitignore"
+BEGIN="# >>> bassclef-sync managed symlinks (do not edit) >>>"
+END="# <<< bassclef-sync managed symlinks <<<"
+
+# Build IGNORE_LINES — same in both file-exists and file-missing branches
+# Per bassclef-cli#37: prepend "/" to anchor every pattern to repo root.
+# Bare "lib" (before fix) matched every folder depth per gitignore semantics —
+# adopter files under src/lib/, harness/lib/, .claude/lib/ all silently ignored.
+# Leading "/" anchors to repo root only. Multi-segment paths like ".claude/skills/foo"
+# already anchor via embedded slash; the leading "/" is harmless there.
+IGNORE_LINES=""
+for T in "$CWD/.claude/skills/"* "$CWD/.claude/luminaries" "$CWD/.claude/rules" "$CWD/.claude/agents" "$CWD/.claude/hooks/"*.sh "$CWD/.claude/bassclef-orientation.md" "$CWD/lib"; do
+  if [ -L "$T" ]; then
+    REL="${T#$CWD/}"
+    IGNORE_LINES="${IGNORE_LINES}/${REL}"$'\n'
+  fi
+done
+
+# Also ignore CLAUDE.md.bak.<ts> backup files that the dispatcher writes when
+# curing content drift (per bassclef-upstream#889). The backup itself stays
+# on disk for adopter inspection; only the tracking noise goes away.
+IGNORE_LINES="${IGNORE_LINES}CLAUDE.md.bak.*"$'\n'
+
+# Only bother writing if there are actually bassclef symlinks to ignore
+if [ -n "$IGNORE_LINES" ]; then
+  if [ -f "$GITIGNORE" ]; then
+    # Existing file: rewrite the managed block (preserves consumer content)
+    awk -v b="$BEGIN" -v e="$END" '
+      $0==b {skip=1; next}
+      $0==e {skip=0; next}
+      !skip {print}
+    ' "$GITIGNORE" > "$GITIGNORE.tmp"
+    {
+      cat "$GITIGNORE.tmp"
+      echo "$BEGIN"
+      printf '%s' "$IGNORE_LINES"
+      echo "$END"
+    } > "$GITIGNORE"
+    rm -f "$GITIGNORE.tmp"
+  else
+    # Missing file: create with just the managed block (bassclef#589)
+    {
+      echo "$BEGIN"
+      printf '%s' "$IGNORE_LINES"
+      echo "$END"
+    } > "$GITIGNORE"
+  fi
+fi
+
+# === 3c-hooks. Auto-connect bassclef-managed hooks into consumer settings.json ===
+# bassclef#569 (V1) + bassclef-upstream#625 (V2 dynamic-derive).
+#
+# V1 shipped a hardcoded 5-entry list under PreToolUse. Every other event type
+# (PostToolUse, SessionStart, Stop, UserPromptSubmit, UserPromptExpansion) went
+# dead-letter — scripts on disk, never fired. Bassclef itself connects 49 hooks
+# across 6 event types; V1 coverage was 5/49 = 10%.
+#
+# V2 reads bassclef's own .claude/settings.json (the source of truth) via a
+# sourceable lib and merges every entry into the consumer file. Adopters stop
+# hitting BLOCKED on every hook add.
+#
+# Anchor luminaries — @luminary michael-nygard (Steady State — self-healing on
+# every session-start), @luminary linus-torvalds (adopter contract — ADR-031
+# commits bassclef to auto-migration), @luminary john-ousterhout (deep module
+# — one clean interface hides the jq merge bookkeeping).
+#
+# Skip paths (all return 0 so bassclef-sync's other sections still run):
+#   - SKIP_BASSCLEF_HOOK_WIRE=1 — operator override (logged to stderr)
+#   - bassclef itself — detected via remote URL; bassclef manages its own file
+#   - jq missing — graceful skip with stderr notice
+#   - BASSCLEF_SOURCE_ROOT unset or bassclef settings.json missing/malformed
+#
+# Source discovery — BASSCLEF_SOURCE_ROOT is exported by the dispatcher
+# (bassclef-sync.dispatcher.template.sh) before it execs this template. When
+# the template is run directly (developer / test harness), BASSCLEF_SOURCE_ROOT
+# stays unset and the section skips cleanly.
+HOOK_CONNECT_LIB="$(dirname "$0")/bassclef-hook-connect.sh"
+if [ -f "$HOOK_CONNECT_LIB" ]; then
+  # shellcheck disable=SC1090
+  source "$HOOK_CONNECT_LIB"
+  bassclef_hook_connect_apply "$CWD" || true
+fi
+
+# === 3g-workflows. Auto-wire bassclef-managed GitHub Actions workflows ===
+# bassclef#611 — clarity-check propagation. Writes a tiny consumer-side
+# workflow that calls bassclef's reusable clarity-check workflow.
+#
+# Vendor binding tier: GitHub-Actions-Locked (per bassclef vendor-bindings standard; see operator substrate for full spec).
+# ADO/GitLab/Bitbucket migration tracked at bassclef#629.
+#
+# Skip paths:
+#   - SKIP_BASSCLEF_WORKFLOWS=1 — operator-controlled override
+#   - bassclef itself (IS_BASSCLEF_ITSELF=1; bassclef manages its own .github/workflows/ directly)
+#   - Consumer not on GitHub (detected via remote URL — no github.com → skip silently)
+#
+# Idempotency: file is bassclef-managed (header marker). If file exists
+# without the marker, treat as operator-customized + leave alone. If file
+# exists WITH the marker, refresh content (operator can detect bassclef
+# updates via git diff).
+if [ "${SKIP_BASSCLEF_WORKFLOWS:-0}" != "1" ] && \
+   [ "$IS_BASSCLEF_ITSELF" = "0" ]; then
+
+  # Only proceed on GitHub-hosted consumers (extracted from remote URL)
+  case "$CONSUMER_REMOTE_URL" in
+    *github.com*|*github*) IS_GITHUB_CONSUMER=1 ;;
+    *) IS_GITHUB_CONSUMER=0 ;;
+  esac
+
+  if [ "$IS_GITHUB_CONSUMER" = "1" ]; then
+    WORKFLOWS_DIR="$CWD/.github/workflows"
+    CLARITY_WORKFLOW="$WORKFLOWS_DIR/clarity-check.yml"
+    BASSCLEF_MANAGED_MARKER="# bassclef-managed: clarity-check (bassclef#611)"
+
+    mkdir -p "$WORKFLOWS_DIR" 2>/dev/null || true
+
+    # If file exists without our marker, leave it alone (operator-customized)
+    WRITE_WORKFLOW=1
+    if [ -f "$CLARITY_WORKFLOW" ] && ! grep -q "bassclef-managed: clarity-check" "$CLARITY_WORKFLOW" 2>/dev/null; then
+      WRITE_WORKFLOW=0
+    fi
+
+    if [ "$WRITE_WORKFLOW" = "1" ]; then
+      cat > "$CLARITY_WORKFLOW" <<'CLARITY_EOF'
+# bassclef-managed: clarity-check (bassclef#611)
+# Distributed via bassclef-sync. To customize, remove the bassclef-managed
+# marker above + bassclef-sync will leave this file alone on next run.
+
+name: clarity-check
+
+on:
+  pull_request:
+    paths-ignore:
+      - 'docs/chronicle/**'
+      - 'chronicle/**'
+      - 'docs/operator-private/journals/**'
+      - 'docs/release-notes/**'
+
+jobs:
+  clarity:
+    name: PR body clarity (advisory)
+    uses: sunj-labs/bassclef/.github/workflows/clarity-check.reusable.yml@main
+    permissions:
+      contents: read
+      pull-requests: write
+CLARITY_EOF
+    fi
+  fi
+fi
+
+# === 3d. Ensure state/markers/ directory exists (per-repo, not shared) ===
+# /verify, /temperance, /diagnose, etc. write markers here. Per-repo because
+# each repo has its own branches + gate state. Per bassclef#342: markers
+# are runtime workflow events, live under state/ (runtime drawer), not
+# .claude/ (rulebook drawer). See standards/mobile-ephemeral-session.md.
+mkdir -p "$CWD/state/markers/verify" 2>/dev/null || true
+mkdir -p "$CWD/state/markers/temperance" 2>/dev/null || true
+mkdir -p "$CWD/state/markers/diagnose" 2>/dev/null || true
+[ ! -f "$CWD/state/markers/.gitkeep" ] && \
+  echo "# gate markers — per-repo runtime workflow events (bassclef#342)" > \
+  "$CWD/state/markers/.gitkeep"
+
+# === 4. Write ~/.claude/settings.json for user-level hook wiring (cloud) ===
+# Ephemeral-gated (#162): desktop operators own their ~/.claude/settings.json
+# and a repo-local hook should not rewrite it. Skill/agent/hook symlinks
+# above are tool-resolution infrastructure (needed on every platform) and
+# remain unconditional. Only the personal-config settings.json write is
+# gated.
+if [ "$IS_EPHEMERAL" = "1" ] && \
+   { [ ! -f ~/.claude/settings.json ] || ! grep -q 'bug-diagnosis' ~/.claude/settings.json 2>/dev/null; }; then
+  cat > ~/.claude/settings.json <<'SETTINGS'
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.claude/hooks/bug-diagnosis.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.claude/hooks/tool-failure-diagnosis.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+SETTINGS
+fi
+
+# === 5. Set env var for rules/CLAUDE.md inheritance ===
+if [ -n "$CLAUDE_ENV_FILE" ]; then
+  echo "CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1" >> "$CLAUDE_ENV_FILE"
+fi
+
+# === 5b. Bootstrap bassclef-evolution labels (#160) ===
+# /promote creates issues with these labels; consumer repos need them created
+# once so the issues are scannable via gh issue list --label bassclef-evolution.
+# Idempotent: --force updates metadata if label exists, creates if not.
+# Skip silently if gh missing or not authenticated (ephemeral mobile).
+if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+  CONSUMER_OWNER_REPO=$(git -C "$CWD" remote get-url origin 2>/dev/null | \
+    sed -E 's#(git@github.com:|https://github.com/)##; s#\.git$##')
+  if [ -n "$CONSUMER_OWNER_REPO" ]; then
+    gh label create bassclef-evolution --repo "$CONSUMER_OWNER_REPO" --force \
+      --color "0E8A16" --description "Promote this pattern to bassclef substrate" \
+      >/dev/null 2>&1 || true
+    gh label create agent-user-proposed --repo "$CONSUMER_OWNER_REPO" --force \
+      --color "D876E3" --description "Pattern surfaced by agent-user collaboration" \
+      >/dev/null 2>&1 || true
+  fi
+fi
+
+# === 6. Whereami freshness check ===
+# docs/whereami.md is the authoritative project-state snapshot
+# (standards/whereami-schema.md). Session-start reads it; session-end
+# updates it. Staleness fires BLOCKED per .claude/rules/whereami-load-bearing.md.
+#
+# Two-signal staleness (v2, bassclef#514): age threshold AND commits-since-
+# last-whereami-update. Idle consumers (zero commits since whereami was last
+# committed) get INFO instead of BLOCKED at the >=7d tier — calendar staleness
+# alone is not a gate when nothing changed. Consumer override:
+# substrate.config.md field `whereami_freshness_days: N`.
+#
+# Thresholds:
+#   <3d                                      → green (no banner)
+#   3-7d (any commits)                       → stale-warn (visible warning)
+#   >=7d AND commits_since == 0              → stale-info (idle; non-blocking)
+#   >=7d AND commits_since > 0               → stale-block (BLOCKED)
+#   missing                                  → BLOCKED
+WHEREAMI="$CWD/docs/whereami.md"
+WHEREAMI_STATUS=""
+WHEREAMI_AGE_DAYS=""
+WHEREAMI_COMMITS_SINCE=""
+if [ ! -f "$WHEREAMI" ]; then
+  WHEREAMI_STATUS="missing"
+else
+  # Extract ISO timestamp via helper (#897 Cure A). Helper reads either
+  # the "## Last updated" markdown section OR YAML frontmatter
+  # `last_updated.at` fallback, and normalizes offset forms (+HHMM,
+  # -HHMM, +HH:MM) to UTC Z form so downstream date -j -f "%Y-%m-%dT%H:%M:%SZ"
+  # reads one canonical shape. Returns empty on missing / malformed.
+  WHEREAMI_TS=$(bassclef_sync_parse_whereami_ts "$WHEREAMI")
+
+  # Commits since whereami was last committed (idle detection).
+  # On non-git repos, a missing whereami commit, or git unavailable: treat as
+  # "active" (commits_since=1) so existing block behavior is preserved — idle
+  # detection requires affirmative evidence of zero commits, not absence of
+  # signal. Override SKIP_WHEREAMI_COMMIT_DELTA=1 forces commits_since=0
+  # (treat as idle) for migration / testing.
+  if [ "${SKIP_WHEREAMI_COMMIT_DELTA:-}" = "1" ]; then
+    WHEREAMI_COMMITS_SINCE=0
+  elif command -v git >/dev/null 2>&1 && git -C "$CWD" rev-parse --git-dir >/dev/null 2>&1; then
+    LAST_WHEREAMI_COMMIT=$(git -C "$CWD" log -1 --format=%H -- docs/whereami.md 2>/dev/null)
+    if [ -n "$LAST_WHEREAMI_COMMIT" ]; then
+      WHEREAMI_COMMITS_SINCE=$(git -C "$CWD" rev-list --count "$LAST_WHEREAMI_COMMIT"..HEAD 2>/dev/null || echo "1")
+    else
+      # Whereami file is uncommitted (fresh add) — treat as active so the file
+      # gets committed before BLOCKED downgrades to INFO. Caller can also use
+      # the override above for migration.
+      WHEREAMI_COMMITS_SINCE=1
+    fi
+  else
+    WHEREAMI_COMMITS_SINCE=1
+  fi
+
+  if [ -n "$WHEREAMI_TS" ]; then
+    # Portable date math: compute age in days (Darwin + GNU)
+    if date -j -f "%Y-%m-%dT%H:%M:%SZ" "$WHEREAMI_TS" "+%s" >/dev/null 2>&1; then
+      WHEREAMI_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$WHEREAMI_TS" "+%s")
+    else
+      WHEREAMI_EPOCH=$(date -d "$WHEREAMI_TS" "+%s" 2>/dev/null || echo "0")
+    fi
+    NOW_EPOCH=$(date "+%s")
+    if [ "$WHEREAMI_EPOCH" != "0" ] && [ "$NOW_EPOCH" -gt "$WHEREAMI_EPOCH" ]; then
+      WHEREAMI_AGE_SECS=$((NOW_EPOCH - WHEREAMI_EPOCH))
+      WHEREAMI_AGE_DAYS=$((WHEREAMI_AGE_SECS / 86400))
+      if [ "$WHEREAMI_AGE_DAYS" -ge 7 ]; then
+        if [ "$WHEREAMI_COMMITS_SINCE" -gt 0 ]; then
+          WHEREAMI_STATUS="stale-block"
+        else
+          WHEREAMI_STATUS="stale-info"
+        fi
+      elif [ "$WHEREAMI_AGE_DAYS" -ge 3 ]; then
+        WHEREAMI_STATUS="stale-warn"
+      fi
+    else
+      WHEREAMI_STATUS="unparseable"
+    fi
+  else
+    WHEREAMI_STATUS="unparseable"
+  fi
+fi
+
+# === Summary ===
+SKILL_COUNT=$(ls "$BASSCLEF_DIR/.claude/skills/" 2>/dev/null | wc -l | tr -d ' ')
+RULE_COUNT=$(ls "$BASSCLEF_DIR/.claude/rules/" 2>/dev/null | wc -l | tr -d ' ')
+AGENT_COUNT=$(ls ~/.claude/agents/ 2>/dev/null | wc -l | tr -d ' ')
+HOOK_COUNT=$(ls "$CWD/.claude/hooks/"*.sh 2>/dev/null | wc -l | tr -d ' ')
+
+# === Bassclef version readout (per WU-2 of bet 2026-06-22c; closes #3) ===
+# Read bassclef-version.json from the synced bassclef. Surfaces "what version
+# do I have + when was it released" in the SessionStart confirm banner.
+# Best-effort releases-behind count if bassclef is a git checkout (Path 1).
+BASSCLEF_VERSION=""
+BASSCLEF_RELEASE_DATE_SHORT=""
+BASSCLEF_RELEASES_BEHIND=""
+VERSION_FILE="$BASSCLEF_DIR/bassclef-version.json"
+if [ -f "$VERSION_FILE" ]; then
+  BASSCLEF_VERSION=$(jq -r '.version // empty' "$VERSION_FILE" 2>/dev/null)
+  RELEASE_DATE_FULL=$(jq -r '.release_date // empty' "$VERSION_FILE" 2>/dev/null)
+  # Trim to YYYY-MM-DD
+  BASSCLEF_RELEASE_DATE_SHORT="${RELEASE_DATE_FULL%%T*}"
+  # Best-effort: count release-* tags created after this version (git checkout only)
+  if [ -d "$BASSCLEF_DIR/.git" ] && [ -n "$BASSCLEF_VERSION" ]; then
+    BEHIND=$(git -C "$BASSCLEF_DIR" tag --list "release-*" --sort=creatordate 2>/dev/null \
+      | awk -v cur="$BASSCLEF_VERSION" 'found {count++} $0==cur {found=1} END {print count+0}')
+    if [ "${BEHIND:-0}" -gt 0 ] 2>/dev/null; then
+      BASSCLEF_RELEASES_BEHIND=" · $BEHIND releases behind"
+    fi
+  fi
+fi
+
+# === URL age computation (#224) ===
+# When fetched from S3, compute presigned URL age + remaining TTL so the
+# session-start banner can distinguish "fresh / benign" from "stale / near
+# refresh boundary". Expired tier is unreachable here (curl would have 403'd
+# and the hook exited at line ~121 before we got this far), but the WARN
+# tier gives the operator a heads-up on the next-refresh expectation.
+# Portable date math mirrors the whereami block below.
+URL_TIER=""
+URL_AGE_HOURS=""
+URL_REMAINING_HOURS=""
+if [ "$SYNC_SOURCE" = "s3" ] && [ -n "$URL_AGE_GENERATED_AT" ] && [ "$URL_AGE_GENERATED_AT" != "null" ]; then
+  if date -j -f "%Y-%m-%dT%H:%M:%SZ" "$URL_AGE_GENERATED_AT" "+%s" >/dev/null 2>&1; then
+    URL_GEN_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$URL_AGE_GENERATED_AT" "+%s")
+  else
+    URL_GEN_EPOCH=$(date -d "$URL_AGE_GENERATED_AT" "+%s" 2>/dev/null || echo "0")
+  fi
+  NOW_EPOCH_URL=$(date "+%s")
+  if [ "$URL_GEN_EPOCH" != "0" ] && [ "$NOW_EPOCH_URL" -ge "$URL_GEN_EPOCH" ]; then
+    URL_AGE_SECS=$((NOW_EPOCH_URL - URL_GEN_EPOCH))
+    URL_AGE_HOURS=$((URL_AGE_SECS / 3600))
+    URL_REMAINING_SECS=$((86400 - URL_AGE_SECS))
+    if [ "$URL_REMAINING_SECS" -lt 0 ]; then
+      URL_REMAINING_HOURS=0
+      URL_TIER="expired"
+    elif [ "$URL_AGE_SECS" -ge 64800 ]; then  # 18h threshold
+      URL_REMAINING_HOURS=$((URL_REMAINING_SECS / 3600))
+      URL_TIER="warn"
+    else
+      URL_REMAINING_HOURS=$((URL_REMAINING_SECS / 3600))
+      URL_TIER="ok"
+    fi
+  fi
+fi
+
+# === Hook drift check ===
+# Compare this hook's version header against the bassclef template.
+# If consumer hook is out of date, surface a warning (non-blocking).
+#
+# Thin-pointer architecture: consumer hooks with version `thin-pointer-*`
+# are intentionally a different file from this template (different role,
+# different version namespace). They opt out of drift comparison entirely
+# because their job is to delegate to bassclef's current template on
+# every fire — not mirror its version string. Per bassclef#418.
+HOOK_SELF="$CWD/.claude/hooks/bassclef-sync.sh"
+HOOK_BASSCLEF="$BASSCLEF_DIR/presence/install/bassclef-sync.template.sh"
+HOOK_DRIFT=""
+HOOK_ARCH="vendored-snapshot"  # default architecture
+if [ -f "$HOOK_SELF" ] && [ -f "$HOOK_BASSCLEF" ]; then
+  SELF_VER=$(grep -m1 '^# BASSCLEF_SYNC_VERSION=' "$HOOK_SELF" 2>/dev/null | sed 's/^# BASSCLEF_SYNC_VERSION=//' | tr -d '[:space:]')
+  BASSCLEF_VER=$(grep -m1 '^# BASSCLEF_SYNC_VERSION=' "$HOOK_BASSCLEF" 2>/dev/null | sed 's/^# BASSCLEF_SYNC_VERSION=//' | tr -d '[:space:]')
+  case "$SELF_VER" in
+    thin-pointer-*)
+      # Thin-pointer architecture: skip drift comparison.
+      # Consumer hook is a dispatcher, not a snapshot.
+      HOOK_ARCH="thin-pointer"
+      ;;
+    *)
+      if [ -n "$SELF_VER" ] && [ -n "$BASSCLEF_VER" ] && [ "$SELF_VER" != "$BASSCLEF_VER" ]; then
+        HOOK_DRIFT="yes"
+      fi
+      ;;
+  esac
+fi
+
+echo ""
+echo "### BASSCLEF SUBSTRATE — SYNCED"
+echo ""
+echo "Status: $SYNC_STATUS"
+echo "Source: $SYNC_SOURCE"
+echo "Architecture: $HOOK_ARCH"
+if [ "$SYNC_SOURCE" = "s3" ] && [ -n "$URL_AGE_GENERATED_AT" ] && [ "$URL_AGE_GENERATED_AT" != "null" ]; then
+  case "$URL_TIER" in
+    ok)
+      echo "Presigned URL: generated ${URL_AGE_HOURS}h ago, expires in ${URL_REMAINING_HOURS}h ✓"
+      ;;
+    warn)
+      echo "⚠️  Presigned URL: generated ${URL_AGE_HOURS}h ago, expires in ${URL_REMAINING_HOURS}h"
+      echo "    Next bassclef merge or daily 06:00 UTC cron will refresh."
+      ;;
+    expired)
+      EXPIRED_HOURS=$((URL_AGE_HOURS - 24))
+      echo "🛑 Presigned URL expired ${EXPIRED_HOURS}h ago (generated ${URL_AGE_HOURS}h ago)."
+      echo "    Fix: end session + restart (fresh clone), or workflow_dispatch bassclef-s3-publish."
+      ;;
+    *)
+      # Fallback when date math couldn't parse generated_at — preserves prior line format.
+      echo "Tarball URL generated: $URL_AGE_GENERATED_AT (expires: $URL_EXPIRES_AT)"
+      ;;
+  esac
+fi
+echo "Skills: ${SKILL_COUNT} (symlinked to ~/.claude/skills/ for Skill-tool registry + .claude/skills/ for Read/Grep)"
+echo "Rules: ${RULE_COUNT} (loaded via additionalDirectories + env var)"
+echo "Agents: ${AGENT_COUNT} (installed to ~/.claude/agents/)"
+echo "Hooks: ${HOOK_COUNT} (symlinked from bassclef + app-specific)"
+echo ""
+
+if [ "${ORPHAN_COUNT:-0}" -gt 0 ]; then
+  echo "### USER-LEVEL SUBSTRATE CLEANUP (per ADR-033 + bassclef#278)"
+  echo ""
+  echo "Parked $ORPHAN_COUNT user-level entries (skills + agents + hooks; symlinks AND cp'd files)"
+  echo "whose basenames duplicated project-level entries. Backup dirs:"
+  echo "  ~/.claude/skills.orphans.$(date +%Y%m%d)/  (if skills parked)"
+  echo "  ~/.claude/agents.orphans.$(date +%Y%m%d)/  (if agents parked)"
+  echo "  ~/.claude/hooks.orphans.$(date +%Y%m%d)/   (if hooks parked)"
+  echo ""
+  echo "Project-level entries now load without dedupe conflict. Backups"
+  echo "survive 30 days minimum; restore if a script you wrote depends"
+  echo "on the user-level location."
+  echo ""
+fi
+
+# === Whereami status block ===
+if [ "$WHEREAMI_STATUS" = "missing" ]; then
+  echo "🛑🛑🛑 BLOCKED 🛑🛑🛑"
+  echo "────────────────────────────────────────────"
+  echo "whereami-missing — docs/whereami.md not found; project-state snapshot required."
+  echo ""
+  echo "  Create from template:"
+  echo "    cp $BASSCLEF_DIR/strategy/templates/whereami-template.md docs/whereami.md"
+  echo "    # then fill phase, iteration, subsystems, last_updated"
+  echo ""
+  echo "  Or defer explicitly:"
+  echo "    tell the agent: 'skip whereami this session'"
+  echo "────────────────────────────────────────────"
+  echo ""
+elif [ "$WHEREAMI_STATUS" = "stale-block" ]; then
+  echo "🛑🛑🛑 BLOCKED 🛑🛑🛑"
+  echo "────────────────────────────────────────────"
+  echo "whereami-stale — docs/whereami.md last updated ${WHEREAMI_AGE_DAYS} days ago (threshold: 7); ${WHEREAMI_COMMITS_SINCE} commits since the last whereami update."
+  echo ""
+  echo "  Resolve by running session-end-style whereami update as first action,"
+  echo "  OR defer: tell the agent 'skip whereami this session'."
+  echo "────────────────────────────────────────────"
+  echo ""
+elif [ "$WHEREAMI_STATUS" = "stale-info" ]; then
+  echo "ℹ️  whereami ${WHEREAMI_AGE_DAYS} days old, but no commits have touched the repo since the last whereami update — repo is idle, no refresh needed."
+  echo ""
+elif [ "$WHEREAMI_STATUS" = "stale-warn" ]; then
+  echo "⚠️  whereami ${WHEREAMI_AGE_DAYS} days old (warn threshold: 3) — refresh at session-end."
+  echo ""
+elif [ "$WHEREAMI_STATUS" = "unparseable" ]; then
+  echo "⚠️  whereami exists but last_updated field unparseable — schema non-conformance."
+  echo "    See standards/whereami-schema.md §Last updated."
+  echo ""
+fi
+
+# === Onboarding-artifact health check ===
+# If the consumer has bassclef substrate installed (.bassclef-url exists),
+# verify the other required onboarding artifacts are present. Whereami is
+# already handled by the block above; check the remaining two here.
+# Catches consumers onboarded before /onboard-repo was codified (observed
+# 2026-04-18: TwoDo, pruneguice, ops missing whereami; TwoDo also missing
+# CLAUDE.md). Prevents mid-skill blocks by surfacing the gap at session-start.
+if [ -f "$CWD/.bassclef-url" ]; then
+  ONBOARD_MISSING=""
+  [ -f "$CWD/CLAUDE.md" ] || ONBOARD_MISSING="${ONBOARD_MISSING}\n  - CLAUDE.md"
+  [ -f "$CWD/substrate.config.md" ] || ONBOARD_MISSING="${ONBOARD_MISSING}\n  - substrate.config.md"
+
+  if [ -n "$ONBOARD_MISSING" ]; then
+    echo "🛑🛑🛑 BLOCKED 🛑🛑🛑"
+    echo "────────────────────────────────────────────"
+    echo "onboarding-artifacts-missing — bassclef substrate installed but required files absent:"
+    echo -e "$ONBOARD_MISSING"
+    echo ""
+    echo "  → Resolve by re-running /onboard-repo (idempotent — only scaffolds missing):"
+    echo "    In a Claude Code session in this repo, invoke /onboard-repo"
+    echo ""
+    echo "  Or defer explicitly:"
+    echo "    tell the agent: 'skip onboarding check this session'"
+    echo "────────────────────────────────────────────"
+    echo ""
+  fi
+fi
+
+if [ -n "$HOOK_DRIFT" ]; then
+  # Resolve consumer repo owner/name from git remote (for PR link + remote check)
+  CONSUMER_REMOTE=$(git -C "$CWD" remote get-url origin 2>/dev/null | sed -E 's#(git@github.com:|https://github.com/)##; s#\.git$##' || echo "your-org/your-repo")
+
+  # === #173: Remote-main version check (preempts BLOCKED on stale-local) ===
+  # Before declaring drift, check if remote main already has the bassclef
+  # template version. If yes → local is just behind main (e.g., haven't pulled
+  # since the sync PR merged); recommend git pull, do NOT block. This generalizes
+  # the merged-PR detection below to any cause of local-behind-main divergence.
+  # Graceful fallback: if gh unavailable / unauthenticated / network down /
+  # parse fails, leave REMOTE_MAIN_VER empty and fall through to existing
+  # BLOCKED behavior — never worse than current.
+  REMOTE_MAIN_VER=""
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    REMOTE_MAIN_VER=$(gh api "repos/$CONSUMER_REMOTE/contents/.claude/hooks/bassclef-sync.sh?ref=main" \
+      --jq '.content' 2>/dev/null | base64 --decode 2>/dev/null | \
+      grep -m1 '^# BASSCLEF_SYNC_VERSION=' | sed 's/^# BASSCLEF_SYNC_VERSION=//' | tr -d '[:space:]')
+  fi
+
+  if [ -n "$REMOTE_MAIN_VER" ] && [ "$REMOTE_MAIN_VER" = "$BASSCLEF_VER" ]; then
+    # Local is behind, but remote main matches bassclef template → stale-local,
+    # not bassclef drift. Surface the diagnosis + recommend pull. Do NOT block.
+    #
+    # #267 fire-and-forget self-heal: if working tree is clean AND on main AND
+    # no unpushed commits, do the pull silently and re-exec the hook. Operator
+    # in autonomous-overnight mode isn't there to manually clear the BLOCKED;
+    # the common case is safe to auto-resolve.
+    SELF_HEAL_OK=0
+    if [ -z "$(cd "$CWD" && git status --porcelain 2>/dev/null)" ]; then
+      CURRENT_BRANCH="$(cd "$CWD" && git symbolic-ref --short HEAD 2>/dev/null || echo "")"
+      if [ "$CURRENT_BRANCH" = "main" ]; then
+        UNPUSHED="$(cd "$CWD" && git rev-list --count '@{u}..HEAD' 2>/dev/null || echo "0")"
+        if [ "$UNPUSHED" = "0" ]; then
+          SELF_HEAL_OK=1
+        fi
+      fi
+    fi
+
+    if [ "$SELF_HEAL_OK" = "1" ]; then
+      echo "ℹ️  Auto-healing bassclef drift: clean tree on main, no unpushed commits, remote-main matches template."
+      echo "   Pulling latest and re-executing sync (#267)."
+      echo ""
+      if (cd "$CWD" && git pull origin main --quiet 2>&1); then
+        # Re-exec the hook against the freshly-pulled version.
+        # exec replaces the current process so the new hook output supersedes
+        # this stale one — operator sees the fresh summary, not "drift then
+        # something else."
+        exec bash "$CWD/.claude/hooks/bassclef-sync.sh" <<< "{\"cwd\":\"$CWD\"}"
+      else
+        echo "⚠️  Auto-heal pull failed — falling through to manual remediation block."
+        echo ""
+        # Fall through to the manual stale-local block below
+      fi
+    fi
+
+    echo "### LOCAL CLONE STALE — NOT BASSCLEF DRIFT"
+    echo ""
+    echo "Remote main on $CONSUMER_REMOTE matches bassclef template ($BASSCLEF_VER)."
+    echo "Your local hook ($SELF_VER) is behind. Pull to bring it in:"
+    echo ""
+    echo "  cd \"$CWD\" && git pull origin main && \\"
+    echo "    echo '{\"cwd\":\"$CWD\"}' | bash .claude/hooks/bassclef-sync.sh"
+    if [ "$SELF_HEAL_OK" = "1" ]; then
+      echo ""
+      echo "  (Auto-heal attempted but pull failed; resolve the pull error above and re-run.)"
+    else
+      echo ""
+      echo "  (Auto-heal skipped: working tree dirty, off main, or unpushed commits exist."
+      echo "   Resolve those first so the pull is non-destructive.)"
+    fi
+    echo ""
+  else
+    # Remote main also lags template OR remote check unavailable → genuine drift.
+    # Determine the remediation: open sync PR (merge it), merged sync PR (pull),
+    # or fallback (try both).
+    OPEN_SYNC_PR=""
+    MERGED_SYNC_PR_URL=""
+    if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+      OPEN_SYNC_PR=$(gh pr list -R "$CONSUMER_REMOTE" --search "head:bassclef-sync/hook-template is:open" --limit 1 --json number,url --jq '.[0].url' 2>/dev/null)
+      if [ -z "$OPEN_SYNC_PR" ]; then
+        MERGED_SYNC_PR_URL=$(gh pr list -R "$CONSUMER_REMOTE" --state merged --search "head:bassclef-sync/hook-template" --limit 1 --json url --jq '.[0].url' 2>/dev/null)
+      fi
+    fi
+
+    echo "🛑🛑🛑 BLOCKED 🛑🛑🛑"
+    echo "────────────────────────────────────────────"
+    echo "bassclef hook drift — consumer hook version lags bassclef template."
+    echo ""
+    echo "  Consumer hook version:  $SELF_VER"
+    echo "  Bassclef template:     $BASSCLEF_VER"
+    if [ -n "$REMOTE_MAIN_VER" ]; then
+      echo "  Remote main version:    $REMOTE_MAIN_VER (also lags template)"
+    fi
+    echo ""
+    if [ -n "$OPEN_SYNC_PR" ]; then
+      # Open sync PR exists — merge path
+      echo "  → Review + merge the open template-sync PR:"
+      echo "    $OPEN_SYNC_PR"
+      echo ""
+      echo "  After merging, resume with:"
+      echo "    cd \"$CWD\" && git pull origin main && \\"
+      echo "    echo '{\"cwd\":\"$CWD\"}' | bash .claude/hooks/bassclef-sync.sh"
+    elif [ -n "$MERGED_SYNC_PR_URL" ]; then
+      # No open PR but a merged one exists — local is behind main
+      echo "  → Sync PR already merged ($MERGED_SYNC_PR_URL) but your local working"
+      echo "    tree is behind main. Pull to bring the updated hook in:"
+      echo ""
+      echo "    cd \"$CWD\" && git pull origin main && \\"
+      echo "    echo '{\"cwd\":\"$CWD\"}' | bash .claude/hooks/bassclef-sync.sh"
+    else
+      # No open sync PR AND no merged sync PR found.
+      #
+      # Pre-2026-05-03 path (bassclef#268, #269): bassclef-template-sync.yml
+      # auto-generated drift-fix PRs in consumer repos; remediation was
+      # `gh workflow run bassclef-template-sync.yml`. Workflow retired
+      # 2026-05-03 (PR #445); thin-pointer architecture replaces it.
+      #
+      # Current remediation: vendored consumer migrates to thin-pointer by
+      # running /onboard-repo (which writes .bassclef-source.json + a
+      # 130-line dispatcher hook that fetches bassclef's current template
+      # at every session-start — no vendoring, no drift class). Or, if
+      # local clone is stale, pull main.
+      echo "  → No open sync PR + no recent merged sync PR. bassclef-template-sync"
+      echo "    workflow retired 2026-05-03; thin-pointer architecture supersedes it."
+      echo ""
+      echo "    Recommended path — migrate this consumer to thin-pointer (one-shot):"
+      echo ""
+      echo "      In a Claude Code session in this repo, invoke /onboard-repo"
+      echo ""
+      echo "      # /onboard-repo writes .bassclef-source.json + the thin-pointer"
+      echo "      # dispatcher hook. Drift class disappears (the dispatcher fetches"
+      echo "      # bassclef's current template every session)."
+      echo ""
+      echo "    Or, if local clone is stale (rare for vendored consumers):"
+      echo ""
+      echo "      cd \"$CWD\" && git pull origin main && \\"
+      echo "      echo '{\"cwd\":\"$CWD\"}' | bash .claude/hooks/bassclef-sync.sh"
+    fi
+    echo ""
+    echo "  Override (accept stale hook, proceed at own risk):"
+    echo "    tell the agent: 'proceed anyway, will merge later'"
+    echo "────────────────────────────────────────────"
+    echo ""
+  fi
+fi
+
+if [ -n "$SYNC_NEW" ]; then
+  echo "### NEW SINCE LAST SYNC — REVIEW BEFORE PROCEEDING"
+  echo ""
+  echo "$SYNC_NEW"
+  echo ""
+  echo "→ New bassclef standards detected. Ask the user to confirm"
+  echo "  before proceeding. These may change how this session operates."
+  echo ""
+fi
+
+echo "YOU MUST confirm to the user:"
+echo "  'Bassclef substrate synced: ${SKILL_COUNT} skills, ${RULE_COUNT} rules,"
+echo -n "   ${AGENT_COUNT} agents, ${HOOK_COUNT} hooks. Status: ${SYNC_STATUS}."
+# Version readout (per WU-2 of bet 2026-06-22c; closes #3)
+if [ -n "$BASSCLEF_VERSION" ]; then
+  echo ""
+  echo -n "   Version: ${BASSCLEF_VERSION} (released ${BASSCLEF_RELEASE_DATE_SHORT}${BASSCLEF_RELEASES_BEHIND})."
+fi
+# Surface non-OK URL tiers on the mandatory confirm line (#225 follow-up).
+# OK tier stays silent — no clutter on the hot path. Warn/expired tiers
+# are guaranteed-visible to the operator, not buried in verbose output.
+if [ "$URL_TIER" = "warn" ]; then
+  echo ""
+  echo "   ⚠️  Presigned URL: ${URL_AGE_HOURS}h old, expires in ${URL_REMAINING_HOURS}h (refreshes on next merge or 06:00 UTC cron).'"
+elif [ "$URL_TIER" = "expired" ]; then
+  echo ""
+  echo "   🛑 Presigned URL expired — end session and restart for fresh clone.'"
+else
+  echo "'"
+fi
+echo ""
+
+# === 5b. Substrate vs bassclef-content access-model note (bassclef#1290) ===
+# Per bassclef#1290 — the "Status: up-to-date" line above refers to substrate
+# primitives (skills + rules + agents + hooks) which sync into this repo. Bassclef
+# also ships non-substrate content (standards/, architecture/, design/, docs/) that
+# is NOT vendored into this repo — instead it's accessed via the agent's
+# additionalDirectories pointing at bassclef's checkout. This note prevents the
+# adopter from interpreting "Status: up-to-date" as "all bassclef content is
+# mirrored here" — they hit a "file not found" if they try to dispatch a
+# bassclef-only standard from an adopter-rooted relative path.
+echo "  Note: bassclef also ships standards/, architecture/, design/, docs/ that"
+echo "  are NOT vendored into this repo. The agent reads them via additionalDirectories"
+echo "  pointing at bassclef's checkout. To dispatch a bassclef-only standard from"
+echo "  your shell, use the full path (e.g. $HOME/src/sunj-labs/bassclef/standards/..."
+echo "  or wherever your bassclef checkout lives) — not the adopter-rooted relative path."
+echo "  Per bassclef#1290."
+echo ""
+
+# === 6. Boot check — only report what's missing ===
+MISSING=""
+
+# Google service account (needed for LinkedIn → 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)"
+fi
+
+# gh CLI auth (needed for /promote, issue creation)
+if ! command -v gh &>/dev/null; then
+  MISSING="${MISSING}\n- gh CLI not installed (needed for /promote, issue creation)"
+elif ! gh auth status &>/dev/null 2>&1; then
+  MISSING="${MISSING}\n- gh CLI not authenticated (run: gh auth login)"
+fi
+
+if [ -n "$MISSING" ]; then
+  echo "### SUBSTRATE DEPENDENCIES — OPTIONAL SETUP NEEDED"
+  echo ""
+  echo "The following are not blocking but limit some skills:"
+  echo -e "$MISSING"
+  echo ""
+  echo "Run: bassclef/scripts/boot-bassclef.sh for full setup guide."
+  echo "These are informational — proceed with your work."
+  echo ""
+fi
+
+# === 7. Auto self-heal — refresh stale adopter wiring (per ADR-032 Layer 3) ===
+#
+# Anti-brittle pattern (Nygard Steady State): every adopter session-start
+# auto-runs migrate-adopter-references.sh against the adopter repo. Catches:
+#   - Stale `canonical/` symlinks under .claude/hooks/ (Surface 1)
+#   - Stale `canonical` references in .claude/settings.json (Surface 2)
+#   - Vendored dispatcher version drift (Surface 3)
+#
+# Without this auto-trigger, adopters stay on stale state forever unless
+# operator manually invokes the migrate script. Operator framing (2026-06-22b
+# closeout): "no other adopter is going to do (2). How do we solve for that —
+# make this anti-brittle."
+#
+# Defense-in-depth:
+#   - SKIP_BASSCLEF_SELF_HEAL=1 — opt out per session
+#   - Substrate-self guard — silently skip when CWD is bassclef itself
+#   - Dry-run first; only apply when findings > 0 (no churn on clean state)
+#   - migrate-script-not-found → silent no-op (old bassclef snapshots without it)
+#   - Failures fail-soft; never exit non-zero
+
+if [ "${SKIP_BASSCLEF_SELF_HEAL:-0}" = "1" ]; then
+  echo "### bassclef self-heal: SKIPPED (SKIP_BASSCLEF_SELF_HEAL=1)"
+elif [ -f "$CWD/architecture/dual-repo-flow.md" ]; then
+  # We're in bassclef-upstream itself; migrate-script's bulkhead would refuse
+  # anyway. Skip silently for cleaner session-start output.
+  :
+else
+  # Override hatch for tests + non-standard layouts; defaults to sibling lookup
+  MIGRATE_SCRIPT="${BASSCLEF_MIGRATE_SCRIPT:-$(dirname "${BASH_SOURCE[0]}")/migrate-adopter-references.sh}"
+  if [ -x "$MIGRATE_SCRIPT" ]; then
+    # Dry-run first: count findings without mutating anything
+    DRY_OUTPUT=$(bash "$MIGRATE_SCRIPT" --dry-run "$CWD" 2>&1) || true
+    FINDINGS=$(echo "$DRY_OUTPUT" | sed -n 's/^findings: *\([0-9][0-9]*\).*/\1/p' | head -1)
+    FINDINGS=${FINDINGS:-0}
+    if [ "$FINDINGS" -gt 0 ] 2>/dev/null; then
+      echo ""
+      echo "### bassclef self-heal: $FINDINGS finding(s) — applying refresh"
+      bash "$MIGRATE_SCRIPT" --apply "$CWD" 2>&1 | sed 's/^/  /' || true
+      echo ""
+    fi
+  fi
+fi
+
+# --------------------------------------------------------------
+# Tail check — SessionStart wiring postcondition (bassclef-upstream#1496)
+#
+# Fires after every sync. Verifies adopter's project-scope settings.json
+# has bassclef-sync wired at SessionStart. Self-heals when stale.
+# Per Nygard bulkhead (R2): heal failure logs INFORM but does not kill
+# session. BASSCLEF_SYNC_STRICT=1 promotes postcondition fail to exit 3
+# (opt-in for CI validation per R16).
+# --------------------------------------------------------------
+ADOPTER_SETTINGS="$CWD/.claude/settings.json"
+verify_sessionstart_wiring "$ADOPTER_SETTINGS"
+VERIFY_RC=$?
+if [ "$VERIFY_RC" -eq 1 ]; then
+  # Missing entry — attempt heal
+  if heal_sessionstart_wiring "$ADOPTER_SETTINGS"; then
+    :  # heal succeeded; log line already emitted
+  else
+    echo "  bassclef-sync: SessionStart wiring heal did not succeed for $ADOPTER_SETTINGS (INFORM); see stderr above" >&2
+    if [ "${BASSCLEF_SYNC_STRICT:-0}" = "1" ]; then
+      exit 3
+    fi
+  fi
+elif [ "$VERIFY_RC" -eq 2 ]; then
+  # Malformed JSON — R5 backup already handled by heal path; do not attempt jq write
+  echo "  bassclef-sync: adopter settings.json malformed; skipping SessionStart wiring heal (INFORM)" >&2
+  if [ "${BASSCLEF_SYNC_STRICT:-0}" = "1" ]; then
+    exit 3
+  fi
+fi
+
+exit 0