npm - @thebassclef/lite - Versions diffs - 1.9.0 → 1.9.2 - Mend

@thebassclef/lite 1.9.0 → 1.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +37 -2
package/dist/index.cjs +1 -1
package/dist/index.d.ts +1 -1
package/dist/index.js +1 -1
package/dist/lite/.claude/hooks/bassclef-sync.sh +795 -749
package/dist/lite/.claude/hooks/session-reflection.d/tests/01-adopter-message-channel.test.sh +168 -0
package/dist/lite/bassclef-version.json +5 -5
package/dist/lite/presence/install/bassclef-sync.template.sh +34 -19
package/dist/lite/standards/lite-manifest-schema-changes.md +9 -0
package/dist/lite/standards/lite-manifest.json +4 -4
package/package.json +2 -2

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

@@ -1,41 +1,320 @@
 #!/bin/bash
-# tier: upstream
-# install-class: operator
-# Bassclef Substrate Sync — fires on SessionStart.
-# Operator-class hook: lives on bassclef-upstream operators' machines only.
-# Ship 1 (#1828) — install-class: operator retag; adopters use the dispatcher
-# (presence/install/bassclef-sync.dispatcher.template.sh) instead.
-# Adopter consumers receive presence/install/bassclef-sync.template.sh instead
-# (sourced from canonical until the WU-0 absorb gap is closed).
-# Ensures bassclef standards are available regardless of device.
-#
-# 1. Clones/pulls bassclef repo
-# 2. Symlinks bassclef skills into project .claude/skills/ (auto-discovery)
-# 3. Installs general hooks + agents to ~/.claude/
-# 4. Writes ~/.claude/settings.json for user-level hook wiring (cloud)
-# 5. Sets env var for rules/CLAUDE.md inheritance
-# === Section 0a: SELF_MODE detection (#915) ===
-# Sister to Cure 1 in #901 (commit 4b6c258d) which added SELF_MODE
-# detection to the adopter template at presence/install/bassclef-sync.template.sh.
-# This is the operator-class SessionStart hook — it needs the same guard.
-#
-# Detection: git remote origin URL matches sunj-labs/(bassclef|bassclef-upstream)(\.git)?$
-# on both HTTPS and SSH URL shapes. When SELF_MODE=1, hook exits 0 early
-# to prevent the sync flow from re-symlinking tracked hooks in the
-# substrate source repo.
-#
-# Live proof of the class this cures: session 2026-07-26d WU-0 reverted 84
-# T + 1 M hooks caused by this SessionStart re-symlink in bassclef-upstream.
+# tier: lite
+# description: Retagged standard → lite per #1301 concentric rule (ADR-052 D1) —
+# Retagged standard → lite per #1301 concentric rule (ADR-052 D1) —
+# this dispatcher IS the sync entry point every adopter vendors into
+# .claude/hooks/bassclef-sync.sh. Without ship at lite, lite adopters
+# have no sync at all. Closes #1301 sister file.
+# BASSCLEF_SYNC_VERSION=thin-pointer-2026-07-28a
+# ^^ DO NOT REMOVE — used by bassclef's drift check + Layer 3 self-heal
+#    detection (per ADR-032). Version string format: descriptor-YYYY-MM-DD.
+#
+# Thin-pointer bassclef-sync dispatcher.
+#
+# Source of truth for the dispatcher consumers vendor into their
+# .claude/hooks/bassclef-sync.sh. See standards/bassclef-source-config.md
+# for the .bassclef-source.json schema this dispatcher reads.
+#
+# Two paths, tried in order:
+#
+#   1. Sibling fast-path (local dev, desktop, multi-repo workspaces)
+#      — if $CWD/../bassclef/presence/install/bassclef-sync.template.sh
+#        exists, exec it directly. Always-current because the file is
+#        read fresh on every fire.
+#
+#   2. Curl fallback (Cloud Env, mobile, fresh sandboxes, CI)
+#      — read .bassclef-source.json for upstream URL + auth metadata,
+#        fetch the tarball, extract, exec the included template.
+#
+# When neither path works, the dispatcher prints a plain-language
+# explanation with three resolution paths (public adopter / local dev
+# / private fork). Always exits 0 so SessionStart hooks don't crash;
+# consumers that want CI fail-fast behavior should pre-check inside
+# their workflow.
+#
+# Versioning: bump BASSCLEF_SYNC_VERSION when the dispatcher's
+# semantics change. Format: YYYY-MM-DD or descriptor-YYYY-MM-DD.
+#
+#   thin-pointer-2026-07-09: pointer-file rename cure (bet 2026-07-09a).
+#                            Adopters onboarded before 2026-06-20 rename carry
+#                            .canonical-source.json. Dispatcher now reads new
+#                            name first, falls back to old, and self-heals
+#                            (writes new name from old content; removes old on
+#                            second cycle per Hoare two-step atomic). Fires
+#                            before auto_sync check + Path 2 curl fallback.
+#                            Overrides: SKIP_SELF_HEAL_POINTER=1 skips write.
+#                            Prior version: thin-pointer-2026-06-29c.
+#   thin-pointer-2026-06-29c: fallback message names the cure (bet 29e WU-10).
+#                              emit_error() now lists option 4 — the curl
+#                              one-liner that runs migrate-adopter-references.sh
+#                              for adopters whose tree carries leftover
+#                              canonical-* references from the 2026-06-20 rename
+#                              event. Discoverable cure inside the error itself;
+#                              the adopter does not need to read the wiki.
+#                              Prior version: thin-pointer-2026-06-29b.
+#   thin-pointer-2026-06-29b: auto-invocation added (bet 29e WU-4). Detection
+#                              step now runs the migrate script automatically
+#                              via curl-pipe + continues to Path 1/Path 2.
+#                              SKIP_AUTO_INVOKE=1 falls back to WU-2's BLOCKED
+#                              behavior. Passes BASSCLEF_DISPATCHER_TEMPLATE
+#                              to migrate when sibling template available.
+#                              Prior version: thin-pointer-2026-06-29.
+#   thin-pointer-2026-06-29: canonical-* reference detection step added
+#                            (bet 29e WU-2). Scans adopter .claude/settings.json
+#                            + vendored bassclef-sync.sh for refs surviving the
+#                            2026-06-20 rename. Emits BLOCKED + exits 0. WU-4 will
+#                            replace exit with auto-invocation of migrate-adopter-
+#                            references.sh. Override: SKIP_CANONICAL_DETECTION=1.
+#                            Prior version: thin-pointer-2026-06-22.
+#   thin-pointer-2026-06-22: version-detection helper added per ADR-032
+#                            (Layer 2 two-stage rocket). __bassclef_dispatcher_version
+#                            function exposes BASSCLEF_SYNC_VERSION to external
+#                            tooling (Layer 3 self-heal in WU-4). No protocol
+#                            break; purely additive. Prior version: thin-pointer-2026-06-13.
+#   thin-pointer-2026-06-13: auto_sync flag check — dispatcher short-
+#                            circuits when .bassclef-source.json has
+#                            auto_sync:false or the field absent. Per
+#                            bassclef#939. Prior version: 2026-05-15.
+#   thin-pointer-2026-05-15: friendly error messages with three
+#                            resolution paths. Closes bassclef#715
+#                            Layer A. Prior version: 2026-05-02.
+# === Version-detection helper (per ADR-032) ===
+# Layer 3 self-heal (WU-4 of bet 2026-06-22b) calls this to detect
+# bootstrap version drift. External tooling can also grep
+# BASSCLEF_SYNC_VERSION from line 3, but the function gives a stable
+# programmatic interface that survives header-comment reformatting.
+__bassclef_dispatcher_version() {
+  echo "thin-pointer-2026-07-09"
+}
+# === Pointer-file fallback + self-heal (bet 2026-07-09a) ===
+#
+# Every adopter onboarded before the 2026-06-20 canonical → bassclef
+# rename carries .canonical-source.json. The dispatcher previously read
+# .bassclef-source.json only; stale adopters saw substrate refuse to
+# load. These two functions cure the class:
+#
+#   bassclef_sync_resolve_pointer_file(cwd)
+#     Echoes the path of the pointer file to use. Prefers new name;
+#     falls back to old name; echoes empty when neither exists.
+#
+#   bassclef_sync_self_heal_pointer(cwd)
+#     Two-step atomic rename per Tony Hoare. First cycle: writes new
+#     name from old content, keeps old file for safety. Second cycle:
+#     removes old file when new already exists. Never deletes new.
+#     Honors SKIP_SELF_HEAL_POINTER=1 for one-shot recovery scenarios.
+#
+# Composing luminaries:
+#   @luminary linus-torvalds — we-dont-break-adopters (ADR-031)
+#   @luminary jerome-saltzer-and-michael-schroeder — complete mediation
+#   @luminary tony-hoare — pre/post conditions on two-step rename
+#   @luminary michael-feathers — characterization tests using real Quorum
+#
+# Tests: .claude/hooks/tests/bassclef-sync-pointer-fallback.test.sh
+# Refs: bassclef-upstream#679
+bassclef_sync_resolve_pointer_file() {
+  local cwd="${1:-$CWD}"
+  local new="$cwd/.bassclef-source.json"
+  local old="$cwd/.canonical-source.json"
+  if [ -f "$new" ]; then
+    echo "$new"
+  elif [ -f "$old" ]; then
+    echo "$old"
+  else
+    echo ""
+  fi
+}
+# bassclef_sync_bundled_substrate_present <cwd>
+#
+# Returns 0 (yes) when .claude/hooks/, .claude/rules/, .claude/skills/ all
+# exist AND contain at least one file (recursively). Returns 1 (no) when
+# any of those conditions fails.
+#
+# Cures the npm-only cold adopter false-error class per
+# bassclef-upstream#1849. The dispatcher was designed for peer-checkout
+# OR source-config models. Neither works for anonymous adopters against
+# private repos. But the npm bundle already unpacks substrate at install
+# time. The fetch failure is not a real failure; this check catches the
+# steady state and lets the dispatcher exit silently.
+#
+# Composes with:
+#   @luminary alan-cooper — Sam persona; silent-on-success matches user model
+#   @luminary donald-norman — signifier; false-positive banner erodes real signal
+#   @luminary linus-torvalds — adopter contract; npm bundle IS the substrate
+#   @luminary michael-feathers — characterization tests over 3 install shapes
+#
+# Tests: .claude/hooks/tests/bassclef-sync-bundled-substrate-check.test.sh
+# Refs: bassclef-upstream#1849
+bassclef_sync_bundled_substrate_present() {
+  local cwd="${1:-}"
+  if [ -z "$cwd" ] || [ ! -d "$cwd" ]; then
+    return 1
+  fi
+  local _dir
+  for _dir in .claude/hooks .claude/rules .claude/skills; do
+    if [ ! -d "$cwd/$_dir" ]; then
+      return 1
+    fi
+    # Nonempty check: at least one file anywhere under the dir.
+    if [ -z "$(find "$cwd/$_dir" -mindepth 1 -maxdepth 4 -type f -print -quit 2>/dev/null)" ]; then
+      return 1
+    fi
+  done
+  return 0
+}
+bassclef_sync_self_heal_pointer() {
+  local cwd="${1:-$CWD}"
+  if [ "${SKIP_SELF_HEAL_POINTER:-0}" = "1" ]; then
+    return 0
+  fi
+  local new="$cwd/.bassclef-source.json"
+  local old="$cwd/.canonical-source.json"
+  # Second cycle: both exist → remove old, keep new (Hoare postcondition)
+  if [ -f "$new" ] && [ -f "$old" ]; then
+    rm -f "$old"
+    return 0
+  fi
+  # First cycle: only old exists → write new from old content, keep old for safety
+  if [ ! -f "$new" ] && [ -f "$old" ]; then
+    cp "$old" "$new" 2>/dev/null || return 0
+    # Emit a one-line note so operator sees the self-heal firing
+    echo "bassclef-sync: renamed .canonical-source.json → .bassclef-source.json (auto-heal; original kept for one session)" >&2
+    return 0
+  fi
+  # Only new exists OR neither exists → no-op
+  return 0
+}
+# bassclef_sync_self_heal_pointer_content(cwd)
+#   Rewrites drift in .bassclef-source.json content on adopters onboarded
+#   before the 2026-06-20 canonical → bassclef rename.
+#     - source_url: sunj-labs/canonical -> sunj-labs/bassclef
+#     - token_env:  CANONICAL_TOKEN     -> BASSCLEF_TOKEN
+#   Preserves auth_method (Bearer during beta), auto_sync flag, and every
+#   other field. Idempotent — no-op when content already uses new names.
+#   Honors SKIP_SELF_HEAL_POINTER_CONTENT=1 for one-shot recovery cases.
+#   Per bet 2026-07-09c WU-2 (bassclef-upstream#680). Sister to
+#   bassclef_sync_self_heal_pointer (filename cure from bet 09a).
+bassclef_sync_self_heal_pointer_content() {
+  local cwd="${1:-$CWD}"
+  if [ "${SKIP_SELF_HEAL_POINTER_CONTENT:-0}" = "1" ]; then
+    return 0
+  fi
+  local pointer="$cwd/.bassclef-source.json"
+  if [ ! -f "$pointer" ]; then
+    return 0
+  fi
+  # Detect drift — cheap grep before invoking jq
+  local drift=0
+  if grep -q "sunj-labs/canonical" "$pointer" 2>/dev/null; then
+    drift=1
+  fi
+  if grep -q "CANONICAL_TOKEN" "$pointer" 2>/dev/null; then
+    drift=1
+  fi
+  if [ "$drift" = "0" ]; then
+    return 0
+  fi
+  # Rewrite via jq — preserves JSON structure and untouched fields
+  local new_json
+  new_json=$(jq '
+    (if (.source_url // "" | contains("sunj-labs/canonical"))
+      then .source_url = (.source_url | sub("sunj-labs/canonical"; "sunj-labs/bassclef"))
+      else . end)
+    | (if (.token_env // "") == "CANONICAL_TOKEN"
+      then .token_env = "BASSCLEF_TOKEN"
+      else . end)
+    | (if (.comment // "" | contains("sunj-labs/canonical"))
+      then .comment = (.comment | gsub("sunj-labs/canonical"; "sunj-labs/bassclef"))
+      else . end)
+  ' "$pointer" 2>/dev/null)
+  if [ -n "$new_json" ]; then
+    echo "$new_json" > "$pointer.tmp" 2>/dev/null && mv "$pointer.tmp" "$pointer" 2>/dev/null
+    echo "bassclef-sync: cured .bassclef-source.json content drift (source_url + token_env → bassclef names)" >&2
+  fi
+  return 0
+}
+# bassclef_sync_self_heal_claude_md_content(cwd)
+#   Inserts @.claude/bassclef-orientation.md after the first heading in
+#   adopter CLAUDE.md when missing. Rewrites stale sunj-labs/canonical
+#   URL references + ../canonical path references. Preserves adopter-
+#   authored sections. Backs up to CLAUDE.md.bak.<ts> before edit.
+#   Idempotent — no-op on cured content.
+#   Honors SKIP_SELF_HEAL_CLAUDE_MD_CONTENT=1 for adopters who want to
+#   own their CLAUDE.md fully.
+#   Per bet 2026-07-09c WU-3 (bassclef-upstream#687 Path 2). Sister to
+#   bassclef_sync_self_heal_pointer_content (WU-2 pointer content cure).
+bassclef_sync_self_heal_claude_md_content() {
+  local cwd="${1:-$CWD}"
+  if [ "${SKIP_SELF_HEAL_CLAUDE_MD_CONTENT:-0}" = "1" ]; then
+    return 0
+  fi
+  local file="$cwd/CLAUDE.md"
+  if [ ! -f "$file" ]; then
+    return 0
+  fi
+  local drift_import=0
+  local drift_url=0
+  local drift_path=0
+  if ! grep -q "@.claude/bassclef-orientation.md" "$file" 2>/dev/null; then
+    drift_import=1
+  fi
+  if grep -q "sunj-labs/canonical" "$file" 2>/dev/null; then
+    drift_url=1
+  fi
+  if grep -q "\\.\\./canonical" "$file" 2>/dev/null; then
+    drift_path=1
+  fi
+  if [ "$drift_import" = "0" ] && [ "$drift_url" = "0" ] && [ "$drift_path" = "0" ]; then
+    return 0
+  fi
+  local backup_ts
+  backup_ts=$(date +%s)
+  cp "$file" "${file}.bak.${backup_ts}" 2>/dev/null
+  if [ "$drift_import" = "1" ]; then
+    awk 'BEGIN{added=0} /^# / && added==0 {print; print ""; print "@.claude/bassclef-orientation.md"; added=1; next} {print}' \
+      "$file" > "${file}.tmp" 2>/dev/null && mv "${file}.tmp" "$file" 2>/dev/null
+  fi
+  sed 's|sunj-labs/canonical|sunj-labs/bassclef|g; s|\.\./canonical|../bassclef|g' \
+    "$file" > "${file}.tmp" 2>/dev/null && mv "${file}.tmp" "$file" 2>/dev/null
+  echo "bassclef-sync: cured CLAUDE.md content drift (@import + canonical references → bassclef; backup at ${file}.bak.${backup_ts})" >&2
+  return 0
+}
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
+cd "$CWD"
+# Opt-out sentinel (bassclef#119): repos that must NOT inherit substrate.
+if [ -f "$CWD/.no-bassclef-sync" ]; then
+  echo "Bassclef substrate sync: skipped (.no-bassclef-sync sentinel present)."
+  exit 0
+fi
+# === SELF_MODE detection (#929 — closes dispatcher-level bypass of #915) ===
+# Sister to Section 0a in .claude/hooks/bassclef-sync.sh (which shipped in
+# #915 PR #920 and guards the sync flow). This guard sits earlier in the
+# call chain — at the dispatcher — so canonical-* auto-invoke + auto_sync
+# fetch + Path 1 / Path 2 branches ALL skip when the current repo is the
+# substrate source (bassclef or bassclef-upstream).
+#
+# Rationale: session 26g SessionStart re-symlinked ~63 hooks in
+# bassclef-upstream despite #915. The project hook's SELF_MODE fired but
+# only AFTER the dispatcher had already invoked the migrate script + fired
+# other paths that touched the tree. Guard early = complete mediation.
 #
 # Env override SKIP_SELF_MODE_DETECTION=1 forces SELF_MODE=0 regardless
 # of remote — for adopter forks of bassclef-upstream that legitimately
 # want the sync flow.
 #
-# Function is defined ABOVE the main-body INPUT read so tests can source
-# the hook with BASSCLEF_SYNC_TEST_MODE=1 and access the function without
-# triggering the sync flow.
-bassclef_detect_self_mode() {
+# Non-breaking for adopters per ADR-031: SELF_MODE returns 0 for any repo
+# whose git remote is NOT sunj-labs/bassclef or sunj-labs/bassclef-upstream.
+# All 5 existing adopters keep their normal recovery + sync paths.
+__bassclef_dispatcher_detect_self_mode() {
   local cwd="${1:-.}"
   # Env override wins
@@ -67,783 +346,550 @@ bassclef_detect_self_mode() {
   return 0
 }
-# === _sync_install_hooks (goal 14c Step 5) ===
-# Install a hard-coded list of substrate hooks to the operator's
-# ~/.claude/hooks/. For each name: if the source hook declares a
-# # install-class: header, route via lib/hook-installer.sh's
-# install_by_class (which honors operator|project|dual). If no header,
-# fall back to legacy operator-scope copy per ADR-058 c2 grace window
-# (through 2026-10-31).
-#
-# Args:
-#   $1 — BASSCLEF_DIR (source of hooks + lib)
-#   $2 — user-scope target dir (default $HOME/.claude/hooks)
-#
-# Discipline (per ADR-058 constraints 1-4):
-#   c1 — install_by_class wrapped in subshell; lib's strict mode
-#        stays contained; caller's strict-mode state preserved
-#   c2 — unheadered hooks install where they install today +
-#        one trace line `skipped-no-header <hook>` fires
-#   c3 — CLAUDE_PROJECT_DIR resolved (git rev-parse fallback) and
-#        exported before the loop so project/dual class routing works
-#   c4 — settings.json command strings unchanged; wiring self-heal
-#        continues at Section 4 (unrelated to this function)
-_sync_install_hooks() {
-  local bassclef_dir="$1"
-  local user_target_dir="${2:-$HOME/.claude/hooks}"
-  # Full-bundle iteration (goal 14c Step 6). Replaces the pre-Step-6
-  # hardcoded 9-name list. Every hook the old list carried still installs —
-  # either via dispatch (when header present) or via grace-window fallback
-  # (when absent). RFC S-2 HIGH cure per docs/rfcs/
-  # RFC-tier0-tests-install-class-dispatch-review.md.
+__DISPATCHER_SELF_MODE=$(__bassclef_dispatcher_detect_self_mode "$CWD")
+if [ "$__DISPATCHER_SELF_MODE" = "1" ]; then
+  # #895: park user-scope orphans that shadow project scope before exit.
+  # Without this, pre-existing symlinks planted by sibling syncs (POA,
+  # twoDo, utilities) shadow bassclef-upstream's project scope in the
+  # Claude Code menu — 92 skills appear twice. The parking helper leaves
+  # real user-scope dirs (operator-authored content) untouched per its
+  # v3 contract. Adopters never hit this path (SELF_MODE=0 for their
+  # remotes per __bassclef_dispatcher_detect_self_mode).
   #
-  # Architect-review 2026-09-15c folds (L-F2, S-F1, S-F2, M-F1, N-F1) apply
-  # equally to this operator sync path — mirrors the adopter template's
-  # Section 3b shape.
+  # Override: SKIP_SELF_MODE_PARKING=1 for one-shot recovery scenarios.
+  if [ "${SKIP_SELF_MODE_PARKING:-0}" != "1" ]; then
+    __parking_helper="$CWD/scripts/bassclef-orphan-parking.sh"
+    if [ -x "$__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
+          # v4 (bassclef-upstream#1077): pass BOTH user + project settings.json
+          # as variadic 5th+ args. Parking helper unions the $HOME wirings
+          # across both files. Any hook wired at $HOME by either settings
+          # scope is preserved. Missing paths silently skip (helper v4 contract).
+          bash "$__parking_helper" "$__user_surface" "$__project_surface" "$HOME/.claude" "$__surface" "$HOME/.claude/settings.json" "$CWD/.claude/settings.json" 2>/dev/null || true
+        fi
+      done
+    fi
+  fi
+  echo "Bassclef dispatcher SELF_MODE — skipping sync in substrate source repo." >&2
+  echo "  (Override with SKIP_SELF_MODE_DETECTION=1 for adopter forks;" >&2
+  echo "   SKIP_SELF_MODE_PARKING=1 to skip user-scope orphan parking.)" >&2
+  exit 0
+fi
+# === auto_sync flag check (bassclef#939) ===
+#
+# Per bassclef#939, fresh consumers default to OFF — the dispatcher
+# only fetches when the consumer explicitly opts in via auto_sync: true
+# in .bassclef-source.json. Cold adopters get a one-line note + the
+# opt-in path instead of opaque auto-fetch.
+#
+# Default behavior on absence (file or field): OFF.
+#
+# Self-heal first (bet 2026-07-09a): stale adopters carrying
+# .canonical-source.json get the file renamed to .bassclef-source.json
+# so this pre-check sees the correct file. Second cycle drops the old.
+bassclef_sync_self_heal_pointer "$CWD"
+# Content-drift cure runs AFTER filename cure so the file we rewrite exists at the new name.
+bassclef_sync_self_heal_pointer_content "$CWD"
+# CLAUDE.md content cure runs at same lifecycle point — before Path 1 / Path 2 pick.
+bassclef_sync_self_heal_claude_md_content "$CWD"
+SOURCE_FILE_PRECHECK=$(bassclef_sync_resolve_pointer_file "$CWD")
+if [ -n "$SOURCE_FILE_PRECHECK" ] && [ -f "$SOURCE_FILE_PRECHECK" ]; then
+  AUTO_SYNC=$(jq -r '.auto_sync // false' "$SOURCE_FILE_PRECHECK" 2>/dev/null)
+  if [ "$AUTO_SYNC" != "true" ]; then
+    cat <<NOTE
+### bassclef-sync — auto-update is OFF
-  mkdir -p "$user_target_dir" 2>/dev/null || true
+Bassclef can keep your skills, rules, and agents current at every
+session start by pulling its latest substrate. It's off by default
+for fresh repos so nothing fetches without your say-so.
-  local installer_lib="$bassclef_dir/lib/hook-installer.sh"
-  local dispatch_available=0
-  [ -f "$installer_lib" ] && dispatch_available=1
+Turn on anytime by saying "enable auto-sync" or by setting:
-  # ADR-058 c3 — resolve CLAUDE_PROJECT_DIR before loop
-  if [ -z "${CLAUDE_PROJECT_DIR:-}" ]; then
-    if command -v git >/dev/null 2>&1; then
-      CLAUDE_PROJECT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || true)"
-    fi
-    if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
-      export CLAUDE_PROJECT_DIR
-    fi
-  fi
+    "auto_sync": true
-  # Bridge env var — lib uses BASSCLEF_TRACE_LOG.
-  # Default location standardized to $HOME/.claude/state/trace.log per N-F2
-  # (2026-09-15c review). Test-supplied env still wins.
-  : "${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
-  local installed=0
-  local skipped_no_header=0
-  local skipped_invalid=0
-  local skipped_lib_missing=0
-  local failed=0
-  # #1894 — capture missing-hook paths for structured status line
-  local -a missing_paths=()
-  local -a missing_scopes=()
-  # S-F2 LOW — dir-exists guard before loop
-  if [ ! -d "$bassclef_dir/.claude/hooks" ]; then
-    return 0
+in .bassclef-source.json. Run a manual sync once with:
+    bash .claude/hooks/bassclef-sync.sh
+More: https://github.com/sunj-labs/bassclef/blob/main/standards/bassclef-source-config.md
+NOTE
+    exit 0
   fi
+fi
-  local hook_src hook_name target has_header
-  for hook_src in "$bassclef_dir/.claude/hooks/"*.sh; do
-    [ -f "$hook_src" ] || continue                          # T16: glob excludes .sh.bak
+# === Plain-language error printer ===
+#
+# Args: $1 = short heading, $2 = context paragraph (one or more sentences).
+# Always exits 0 to keep SessionStart hooks non-blocking.
+emit_error() {
+  local heading="$1"
+  local context="$2"
+  cat <<HEADER
-    hook_name=$(basename "$hook_src")
-    target="$user_target_dir/$hook_name"
+### bassclef-sync — $heading
-    # M-F1 MED — rm existing symlink at target before cp
-    [ -L "$target" ] && rm -f "$target"
+$context
-    has_header=0
-    if head -10 "$hook_src" 2>/dev/null | grep -qE '^# install-class:[[:space:]]*(operator|project|dual)$'; then
-      has_header=1
-    fi
+Three ways to fix this:
-    if [ "$has_header" = "1" ] && [ "$dispatch_available" = "1" ]; then
-      # ADR-058 c1 — subshell wraps install_by_class so lib strict
-      # mode never leaks into this script. On subshell failure, fall
-      # back to legacy operator-scope copy to preserve adopter
-      # contract per c4 (settings.json command strings byte-identical).
-      # shellcheck disable=SC1090  # dynamic source path
-      if ( source "$installer_lib" 2>/dev/null && install_by_class "$hook_src" ) >/dev/null 2>&1; then
-        installed=$((installed + 1))
-      else
-        cp -p "$hook_src" "$target" 2>/dev/null || true
-        chmod +x "$target" 2>/dev/null || true
-        echo "$(date -u +%FT%TZ) dispatch-fail $hook_name" >> "$BASSCLEF_TRACE_LOG"
-        failed=$((failed + 1))
-        # #1894 — capture path for structured status line
-        missing_paths+=(".claude/hooks/$hook_name")
-        missing_scopes+=("project")
-      fi
-    elif [ "$has_header" = "1" ] && [ "$dispatch_available" = "0" ]; then
-      # S-F1 MED — dispatch lib missing; trace explicitly (not silent)
-      cp -p "$hook_src" "$target" 2>/dev/null || true
-      chmod +x "$target" 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 fallback — grace window through 2026-10-31.
-      # L-F2 MED — additive-only during grace; do NOT rm legacy user-scope copies.
-      cp -p "$hook_src" "$target" 2>/dev/null || true
-      chmod +x "$target" 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))
-        # #1894 — invalid-header is a real defect (not grace-window); capture for status line
-        missing_paths+=(".claude/hooks/$hook_name")
-        missing_scopes+=("project")
-      fi
-    fi
-  done
+  1) PUBLIC adopters (most common)
+     Edit .bassclef-source.json to point at the public release tarball:
-  # N-F1 MED — install summary with reason breakdown when non-zero
-  local skipped_total=$((skipped_no_header + skipped_invalid + skipped_lib_missing))
-  if [ "$skipped_total" = "0" ] && [ "$failed" = "0" ]; then
-    echo "bassclef-sync: $installed hooks ready. Nothing skipped, nothing failed."
-  else
-    local 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#, }"
-    # RFC-0008 F7 — three bare numbers read three ways. Say what they mean
-    # together, and say plainly whether the install is usable.
-    if [ "$failed" = "0" ] && [ "$skipped_invalid" = "0" ]; then
-      echo "bassclef-sync: $installed hooks ready. $skipped_total skipped on purpose ($breakdown). Nothing failed — your install is complete."
-    else
-      echo "bassclef-sync: $installed hooks ready. $skipped_total skipped on purpose ($breakdown)."
-      if [ "$failed" -gt 0 ]; then
-        echo "bassclef-sync: $failed could not be installed. Those hooks will not fire until that is fixed."
-      fi
-    fi
-  fi
+       {
+         "source_url":  "https://github.com/sunj-labs/bassclef/releases/latest/download/substrate.tar.gz",
+         "auth_method": "none",
+         "token_env":   "",
+         "comment":     "Public bassclef substrate. No auth needed."
+       }
-  # #1894 — idempotent-complete-or-fail-loud postcondition
-  # (pre-mortem R2 fold: RESTORED iff failed==0 && skipped_invalid==0;
-  #  grace-window and dispatch-lib-missing count as OK per ADR-058 c2)
-  local total=$((installed + skipped_total + failed))
-  local defect_total=$((failed + skipped_invalid))
-  if [ "$defect_total" = "0" ]; then
-    # RESTORED — human line + minimal JSON status:complete (Beck B1 fold: minimal JSON in V1)
-    echo "bassclef-sync: RESTORED — $installed of $total hooks resolved at their scoped targets."
-    printf 'bassclef-sync: {"status":"complete","installed":%d}\n' "$installed"
-  else
-    # DEGRADED — human line + JSON with missing[] carrying path + scope + cure per entry
-    echo "bassclef-sync: DEGRADED — $defect_total of $total hooks did not resolve after self-heal."
-    local i missing_json="["
-    for i in "${!missing_paths[@]}"; do
-      [ "$i" -gt 0 ] && missing_json="$missing_json,"
-      missing_json="$missing_json{\"path\":\"${missing_paths[$i]}\",\"scope\":\"${missing_scopes[$i]}\",\"cure\":\"bassclef init --force\"}"
-    done
-    missing_json="$missing_json]"
-    printf 'bassclef-sync: {"status":"degraded","installed":%d,"missing":%s}\n' "$installed" "$missing_json"
-  fi
-}
+     Pre-launch note: while bassclef is still private, the public
+     release URL above may not yet exist. Until it does, use option 3.
-# === Test-mode guard (#915) ===
-# Tests source this hook to access helpers without triggering main sync.
-# Early return under BASSCLEF_SYNC_TEST_MODE=1. Helpers defined ABOVE.
-if [ "${BASSCLEF_SYNC_TEST_MODE:-0}" = "1" ]; then
-  return 0 2>/dev/null || exit 0
-fi
+  2) LOCAL DEV — clone bassclef alongside this repo
-# === Hook liveness heartbeat (WU-3 of bet 2026-07-31d; closes #1002) ===
-# Silent-fail — a missing lib never crashes the hook. Discipline: ADR-048 +
-# standards/hook-cadence.json. Session-start reflection module (WU-4.5) checks
-# marker mtime against expected cadence.
-{
-  _hb_sd="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  for _hb_c in "${_hb_sd}/../../lib/hook-heartbeat.sh" "${HOME:-/}/lib/hook-heartbeat.sh"; do
-    [ -f "$_hb_c" ] && source "$_hb_c" && heartbeat_mark "bassclef-sync" && break
-  done
-  unset _hb_sd _hb_c
-} 2>/dev/null || true
+       cd ../ && git clone https://github.com/sunj-labs/bassclef.git
-INPUT=$(cat)
-CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
-cd "$CWD"
+     Re-run your session. The dispatcher uses the local checkout via
+     the sibling fast-path; no auth needed.
+  3) PRIVATE / pre-launch — create a fine-grained GitHub PAT
+       a) GitHub -> Settings -> Developer settings -> Personal access tokens
+          -> Fine-grained -> Generate new token
+       b) Resource owner: sunj-labs
+       c) Repository access: select sunj-labs/bassclef only
+       d) Permissions -> Repository -> Contents -> Read
+       e) Set the token as BASSCLEF_TOKEN in your environment:
+            CI:         gh secret set BASSCLEF_TOKEN -R <your-org/your-repo>
+            Local:      export BASSCLEF_TOKEN=<paste>
+            Cloud Code: set BASSCLEF_TOKEN in your environment config
+  4) STALE REFERENCES — your repo installed bassclef before 2026-06-29
-# === Section 0a fires: exit early if this repo is substrate source ===
-SELF_MODE=$(bassclef_detect_self_mode "$CWD")
-if [ "$SELF_MODE" = "1" ]; then
-  echo "SELF_MODE detected — skipping sync in substrate source repo." >&2
-  echo "  (Override with SKIP_SELF_MODE_DETECTION=1 for adopter forks.)" >&2
+       If your tree carries leftover canonical-* references from the
+       2026-06-20 rename event, refresh them in place by running the
+       migrate script directly:
+         curl -sL https://raw.githubusercontent.com/sunj-labs/bassclef/main/scripts/migrate-adopter-references.sh \\
+           | bash -s -- --apply "\$CWD"
+       Open a fresh Claude Code session afterward. The fresh dispatcher
+       carries detection that runs the cure automatically when needed.
+  More: https://github.com/sunj-labs/bassclef/blob/main/standards/bassclef-source-config.md
+        https://github.com/sunj-labs/bassclef/wiki/Troubleshooting#substrate-fails-to-load-and-you-do-not-see-the-self-heal-banner
+HEADER
   exit 0
-fi
+}
-# Bassclef substrate location — peer clone at ../bassclef (post-rename).
-# Pre-rename ../canonical fallback removed 2026-06-24 per bassclef-upstream#317
-# Phase 0: zero adopters carry the canonical/ path; operator's local
-# ~/src/sunj-labs/canonical was removed before this cleanup.
-#
-# 2026-09-15 (goal 14c Step 6): honor env-supplied BASSCLEF_DIR when set.
-# Real operator machines do not set this env var — L237 default fires as before.
-# Test fixtures set BASSCLEF_DIR to point at a mock bundle; honoring the
-# env unblocks characterization tests for the operator sync path.
-: "${BASSCLEF_DIR:=$CWD/../bassclef}"
-BASSCLEF_REPO="https://github.com/sunj-labs/bassclef.git"
-SYNC_STATUS="up-to-date"
-SYNC_NEW=""
-# === 1. Clone or pull bassclef ===
-# When BASSCLEF_DIR points at a valid bundle with .claude/hooks/ AND is NOT a
-# git repo, skip clone/pull — env-supplied bundle (test fixture) is authoritative.
-if [ -d "$BASSCLEF_DIR/.claude/hooks" ] && [ ! -d "$BASSCLEF_DIR/.git" ]; then
-  # env-override fixture path; skip clone/pull
-  :
-elif [ ! -d "$BASSCLEF_DIR/.claude" ]; then
-  # Capture stderr so classify_clone_failure can name the real cause.
-  # Prior version blamed GitHub auth on every failure — cli#106 body showed
-  # this misleads adopters whose auth is fine but who can't see a private repo.
-  # Classifier emits per-cause hints — for auth failures, the hint reads
-  # "Optional: set up GitHub auth to unlock full-tier sync — run: gh auth login".
-  # (This literal phrase kept here so #1631 Amendment C test greps still match.)
-  __sync_clone_stderr=$(git clone "$BASSCLEF_REPO" "$BASSCLEF_DIR" 2>&1)
-  __sync_clone_exit=$?
-  if [ "$__sync_clone_exit" -eq 0 ]; then
-    SYNC_STATUS="freshly cloned"
-  else
-    # Source the classifier lib; probe bundled path first, then $HOME/lib fallback.
-    {
-      _cf_sd="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
-      for _cf_c in "${_cf_sd}/../../lib/clone-failure-classifier.sh" "${HOME:-/}/lib/clone-failure-classifier.sh"; do
-        [ -f "$_cf_c" ] && source "$_cf_c" && break
-      done
-      unset _cf_sd _cf_c
-    } 2>/dev/null || true
+# === Recovery script resolver + checksum verifier ===
+#
+# Per goal 2026-08-27 step 7 PR #1 — cures external security review HIGH
+# finding on the self-heal curl|bash fallback (source audit tracked in
+# operator-only artifact; not shipped to public bassclef).
+#
+# Two functions cover Adam's Options A (bundle local) + B (checksum on curl).
+#
+# @pattern strategy (RecoveryScriptResolver picks one of three sources)
+# @pattern guard-clause (verify_checksum fails loud on mismatch)
-    if declare -f classify_clone_failure >/dev/null 2>&1; then
-      classify_clone_failure "$__sync_clone_stderr"
-    else
-      # Defensive fallback — preserves prior behavior if lib unavailable.
-      echo "### Bassclef sync — full-tier not synced"
-      echo ""
-      echo "Git said:"
-      echo "$__sync_clone_stderr"
-      echo ""
-      echo "Lite tier works without it — your session is fine."
-    fi
-    exit 0
+# resolve_recovery_script — prints one of:
+#   LOCAL:<path>        env override set + file exists
+#   SIBLING:<path>      sibling checkout has the script
+#   CURL:<url>|<sha>    neither available; use curl with checksum
+#
+# Priority chain per docs/decompositions/2026-08-27-step-7-pr-1-dispatcher-cure-responsibilities.md
+resolve_recovery_script() {
+  # Priority 1 — env override
+  if [ -n "${BASSCLEF_RECOVERY_SCRIPT_PATH:-}" ] && [ -f "$BASSCLEF_RECOVERY_SCRIPT_PATH" ]; then
+    printf 'LOCAL:%s\n' "$BASSCLEF_RECOVERY_SCRIPT_PATH"
+    return 0
   fi
-  unset __sync_clone_stderr __sync_clone_exit
-else
-  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 [ "$BEFORE" != "$AFTER" ]; then
-    SYNC_STATUS="updated"
-    SYNC_NEW=$(git -C "$BASSCLEF_DIR" log --oneline "$BEFORE".."$AFTER" 2>/dev/null)
+  # Priority 2 — sibling checkout (matches SIBLING_TEMPLATE pattern at L594)
+  local sibling_script="${CWD:-$(pwd)}/../bassclef/scripts/migrate-adopter-references.sh"
+  if [ -f "$sibling_script" ]; then
+    printf 'SIBLING:%s\n' "$sibling_script"
+    return 0
   fi
-fi
-# === 2. Symlink bassclef skills into project for auto-discovery ===
-mkdir -p "$CWD/.claude/skills" 2>/dev/null || true
-for SKILL_DIR in "$BASSCLEF_DIR/.claude/skills/"*/; do
-  SKILL_NAME=$(basename "$SKILL_DIR")
-  TARGET="$CWD/.claude/skills/$SKILL_NAME"
-  # Only symlink if not already an app-specific skill (real directory, not symlink)
-  if [ -L "$TARGET" ]; then
-    # Existing symlink — update it
-    rm "$TARGET"
-    ln -s "$SKILL_DIR" "$TARGET"
-  elif [ ! -d "$TARGET" ]; then
-    # Doesn't exist — create symlink
-    ln -s "$SKILL_DIR" "$TARGET"
-  fi
-  # If it's a real directory (app-specific), leave it alone
-done
-# === 2b. Park orphan ~/.claude/skills + agents + hooks symlinks (widened per ADR-033 + bassclef#278) ===
-# Uses the shared orphan-parking helper. Closes the skill / agent / hook
-# duplication-in-available-skills bug. The helper parks user-level
-# symlinks AND cp'd files whose basename appears in project-level —
-# preserves real directories untouched + EXCLUDES hooks wired in
-# settings.json at $HOME paths (per #294); backs up moved entries to
-# dated dirs that survive at least 30 days 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
-      # Pass user settings.json as 5th arg so wired hooks are excluded
-      # from parking. Per #294 — broke the Stop hook on this machine when
-      # parking removed session-end.sh that settings.json wires.
-      PARKED_LINE=$(bash "$PARKING_HELPER" "$USER_SURFACE" "$PROJECT_SURFACE" "$HOME/.claude" "$surface" "$USER_SETTINGS" 2>/dev/null || echo "")
-      if [ -n "$PARKED_LINE" ]; then
-        # Extract the count from "parked N <surface> orphans → <dir>"
-        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
+  # Priority 3 — curl fallback with checksum sidecar
+  local recovery_url="https://raw.githubusercontent.com/sunj-labs/bassclef/main/scripts/migrate-adopter-references.sh"
+  local sha_url="${recovery_url}.sha256"
+  printf 'CURL:%s|%s\n' "$recovery_url" "$sha_url"
+  return 0
+}
-# === 2c. Adopter self-heal — auto-migrate stale canonical references ===
-# Per ADR-031 we-dont-break-adopters + Nygard's Steady State pattern.
-# When this hook runs in an adopter repo (CWD is NOT bassclef-upstream and
-# does NOT have architecture/dual-repo-flow.md), invoke the migration script
-# to repair any stale ../canonical/ references in symlinks + settings.json
-# + dispatcher + statusline. Idempotent — no-op on already-migrated repos.
-#
-# Banner surfaces per-surface info (not just count) so adopters who
-# customized any of the migrated surfaces see exactly what changed.
-# Closes Yellow 2 of the 2026-06-22 release-readiness review.
-MIGRATE_SCRIPT="$BASSCLEF_DIR/scripts/migrate-adopter-references.sh"
-SUMMARY_HELPER="$BASSCLEF_DIR/scripts/bassclef-migrate-summary.sh"
-if [ -f "$MIGRATE_SCRIPT" ] && [ ! -f "$CWD/architecture/dual-repo-flow.md" ]; then
-  MIGRATE_OUT=$(bash "$MIGRATE_SCRIPT" --apply "$CWD" 2>&1)
-  MIGRATE_CHANGES=$(echo "$MIGRATE_OUT" | awk -F: '/^changes:/ {print $2}' | tr -d ' ')
-  if [ -n "$MIGRATE_CHANGES" ] && [ "$MIGRATE_CHANGES" -gt 0 ]; then
-    PER_SURFACE=""
-    # Check -f (file exists), not -x (executable). We invoke via `bash $HELPER`
-    # so the executable bit is irrelevant; the bit may not survive tarball
-    # fetches across adopter clones (per reviewer note on PR #291).
-    if [ -f "$SUMMARY_HELPER" ]; then
-      PER_SURFACE=$(echo "$MIGRATE_OUT" | bash "$SUMMARY_HELPER" 2>/dev/null)
-    fi
-    SYNC_NEW="${SYNC_NEW}
-Adopter self-heal: $MIGRATE_CHANGES surface(s) migrated. Old setup keeps working; new setup matches current bassclef substrate. Per ADR-031."
-    if [ -n "$PER_SURFACE" ]; then
-      SYNC_NEW="${SYNC_NEW}
-${PER_SURFACE}"
-    fi
+# verify_checksum <file> <expected_sha256>
+# Returns 0 on match; non-zero + loud stderr on mismatch or missing tool.
+# @luminary saltzer-schroeder — complete mediation; no silent pass.
+verify_checksum() {
+  local file="$1"
+  local expected="$2"
+  local computed=""
+  if command -v shasum >/dev/null 2>&1; then
+    computed=$(shasum -a 256 "$file" 2>/dev/null | awk '{print $1}')
+  elif command -v sha256sum >/dev/null 2>&1; then
+    computed=$(sha256sum "$file" 2>/dev/null | awk '{print $1}')
+  else
+    echo "verify_checksum: neither shasum nor sha256sum found in PATH" >&2
+    echo "verify_checksum: install one before continuing" >&2
+    return 2
   fi
-fi
-# === 3. Install general hooks to ~/.claude/ ===
-# Delegates to _sync_install_hooks (goal 14c Step 5 per ADR-058).
-# The hard-coded 9-name list that lived here through v0.41.1 moved
-# into the function above. Each hook now routes by its own
-# # install-class: header when declared; unheadered hooks fall back
-# to legacy operator-scope copy per ADR-058 c2 grace window
-# (through 2026-10-31). Section 4 self-heal continues to preserve
-# adopter contract per c4 (settings.json command strings unchanged).
-_sync_install_hooks "$BASSCLEF_DIR" "$HOME/.claude/hooks"
-# === Install agents to ~/.claude/ ===
-mkdir -p ~/.claude/agents 2>/dev/null || true
-cp "$BASSCLEF_DIR/.claude/agents/"*.md ~/.claude/agents/ 2>/dev/null || true
-# === 4. Versioned self-heal of ~/.claude/settings.json ===
-# WU-3 of bet 2026-06-24a-settings-hardening (#313). Replaces the
-# brittle multi-grep + destructive heredoc rewrite with:
-#   1. Version-field comparison (read_settings_version).
-#   2. Additive merge that preserves operator's top-level keys (theme,
-#      statusLine, permissions, alwaysThinkingEnabled, etc.) and
-#      operator-only event types — bassclef wins per-event for events
-#      it ships.
-#   3. Hoare postcondition: after self-heal, drift detector MUST
-#      return clean (compare_wirings .ok == true). Else exit 1 with
-#      structured stderr — failure compounds across every adopter,
-#      so failing loud beats failing silent.
-# Closes the bug class diagnosed 2026-06-24 (operator's settings.json
-# never picked up substrate's new hook wirings).
-WIRINGS_LIB="$BASSCLEF_DIR/.claude/hooks/_lib/wirings.sh"
-PROJECT_SETTINGS="$BASSCLEF_DIR/.claude/settings.json"
-USER_SETTINGS="$HOME/.claude/settings.json"
-sync_self_heal() {
-  if [ ! -f "$WIRINGS_LIB" ] || [ ! -f "$PROJECT_SETTINGS" ]; then
-    # Substrate not fully synced yet OR project settings.json not
-    # checked out on this branch. Fall back silently — drift detector
-    # at next session-start will surface the gap.
-    return 0
+  if [ -z "$computed" ]; then
+    echo "verify_checksum: could not compute SHA-256 of $file" >&2
+    return 3
   fi
-  # shellcheck source=/dev/null
-  source "$WIRINGS_LIB"
-  local required_version user_version
-  required_version=$(read_settings_version "$PROJECT_SETTINGS")
-  user_version=$(read_settings_version "$USER_SETTINGS")
-  if [ ! -f "$USER_SETTINGS" ] || [ "$user_version" -lt "$required_version" ]; then
-    additive_merge_settings "$USER_SETTINGS" "$PROJECT_SETTINGS"
-  fi
-  # Hoare postcondition: required ⊆ loaded after self-heal.
-  local required loaded diff ok missing
-  required=$(read_required_wirings "$PROJECT_SETTINGS")
-  loaded=$(read_loaded_wirings)
-  diff=$(compare_wirings "$required" "$loaded")
-  ok=$(echo "$diff" | jq -r '.ok')
-  if [ "$ok" != "true" ]; then
-    missing=$(echo "$diff" | jq -c '.missing')
-    # cli#1742 cure B — guard banner emit on non-empty missing list.
-    # Prior version printed the header + Fix line even when missing was
-    # empty (extras-only case), leaving adopters with a header pointing at
-    # nothing. Silence when nothing is genuinely missing.
-    __sync_missing_count=$(echo "$missing" | jq 'length' 2>/dev/null || echo 0)
-    if [ "${__sync_missing_count:-0}" -gt 0 ]; then
-      echo "🛑 bassclef-sync — these hooks should fire and are not connected:" >&2
-      echo "$missing" | jq -r '.[] | "  - " + .event + " → " + .command' >&2
-      echo "" >&2
-      echo "Fix: add the lines above to ~/.claude/settings.json, then run bassclef-sync again." >&2
-    fi
-    unset __sync_missing_count
-    if command -v trace_log >/dev/null 2>&1; then
-      trace_log "fail" "bassclef-sync-postcondition" "$missing"
-    fi
-    return 1
-  fi
-  if command -v trace_log >/dev/null 2>&1; then
-    trace_log "ok" "bassclef-sync-postcondition" "version=$required_version"
+  if [ "$computed" = "$expected" ]; then
+    return 0
   fi
-  return 0
+  echo "verify_checksum: SHA-256 mismatch on $file" >&2
+  echo "verify_checksum: expected: $expected" >&2
+  echo "verify_checksum: computed: $computed" >&2
+  return 1
 }
-sync_self_heal || exit 1
-# === 4b. PreToolUse template embedding — operator settings.json self-heal ===
-# Per bassclef-upstream#336 — ensure operator's ~/.claude/settings.json wires
-# the bassclef-managed PreToolUse hooks (substrate-clarity-gate + bet-doc-gate).
-# Mirrors §3c-hooks in presence/install/bassclef-sync.template.sh (consumer-side)
-# but targets ~/.claude/settings.json with $HOME-prefixed commands.
-#
-# Why this lives here even though §4 sync_self_heal runs additive-merge:
-# wirings.sh merges bassclef's project settings.json into operator's user
-# settings.json — but during a sync where wirings.sh itself is being upgraded,
-# OR when the operator's settings.json predates the wirings library entirely,
-# the merge may not fire. This §4b is the literal-text fallback: greppable
-# guards re-emit the PreToolUse template when entries are missing, regardless
-# of wirings.sh state. Bootstrap-pair discipline (per
-# .claude/rules/bootstrap-pair-discipline.md) — wiring ships in the same place
-# as the hook reference.
-#
-# Template (operator settings.json fragment, "PreToolUse": event):
-#   {
-#     "hooks": {
-#       "PreToolUse": [
-#         {
-#           "matcher": "Edit|Write|MultiEdit",
-#           "hooks": [
-#             {"type": "command", "command": "$HOME/.claude/hooks/substrate-clarity-gate.sh"},
-#             {"type": "command", "command": "$HOME/.claude/hooks/bet-doc-gate.sh"}
-#           ]
-#         }
-#       ]
-#     }
-#   }
-#
-# Idempotent via jq additive merge — re-runs detect existing entries and skip.
-# Skip paths:
-#   - SKIP_PRETOOLUSE_EMBED=1 — operator override (logged)
-#   - jq missing — graceful skip with stderr notice
-#   - ~/.claude/settings.json missing — skip (sync_self_heal handles creation)
-if [ "${SKIP_PRETOOLUSE_EMBED:-0}" != "1" ] && \
-   command -v jq >/dev/null 2>&1 && \
-   [ -f "$USER_SETTINGS" ]; then
-  # Guard re-emit when bet-doc-gate missing (existing-adopter self-heal)
-  if ! grep -q 'bet-doc-gate' ~/.claude/settings.json 2>/dev/null; then
-    BET_DOC_GATE_MISSING=1
-  else
-    BET_DOC_GATE_MISSING=0
+# === Canonical-* reference detection (per bet 29e WU-2) ===
+#
+# Self-heal for adopters carrying canonical-* references from the
+# 2026-06-20 rename. Scans the adopter .claude/ tree at session-start
+# BEFORE Path 1 / Path 2. When canonical-* refs are found, emits a
+# BLOCKED block naming the recovery command (curl one-liner shipped
+# in WU-3 of bet 29e) and exits 0 so SessionStart stays non-blocking.
+#
+# WU-2 emits BLOCKED + exits. WU-4 will rewrite this block to auto-
+# invoke the recovery and continue the dispatcher chain.
+#
+# Override: SKIP_CANONICAL_DETECTION=1 bypasses the scan. Reserved for
+# migration scripts; not for routine adopter use.
+#
+# Primary lens: @luminary michael-nygard — self-healing integration
+# point per Release It! Stability Patterns. Composing lenses:
+# @luminary jerome-saltzer-and-michael-schroeder (complete mediation —
+# every session-start sees the scan), @luminary tony-hoare (when no
+# canonical refs found, scan is silent; postcondition holds), @luminary
+# john-ousterhout (deep dispatcher hides migration complexity).
+if [ "${SKIP_CANONICAL_DETECTION:-0}" != "1" ]; then
+  CANONICAL_FINDINGS=()
+  # Surface 2: settings.json additionalDirectories contains "canonical"
+  SETTINGS_PATH="$CWD/.claude/settings.json"
+  if [ -f "$SETTINGS_PATH" ]; then
+    STALE_DIRS=$(jq -r '.permissions.additionalDirectories // [] | .[] | select(test("canonical"))' "$SETTINGS_PATH" 2>/dev/null || true)
+    if [ -n "$STALE_DIRS" ]; then
+      CANONICAL_FINDINGS+=(".claude/settings.json additionalDirectories contains canonical")
+    fi
   fi
-  # Guard re-emit when substrate-clarity-gate missing
-  if ! grep -q 'substrate-clarity-gate' ~/.claude/settings.json 2>/dev/null; then
-    SUBSTRATE_CLARITY_GATE_MISSING=1
-  else
-    SUBSTRATE_CLARITY_GATE_MISSING=0
-  fi
-  if [ "$BET_DOC_GATE_MISSING" = "1" ] || [ "$SUBSTRATE_CLARITY_GATE_MISSING" = "1" ]; then
-    # Operator-class PreToolUse template — note the $HOME prefix (left literal
-    # in JSON; Claude Code expands at hook-fire time per presence/install
-    # consumer-side §4 line 820 precedent).
-    OPERATOR_PRETOOLUSE_JSON='[
-      {"matcher": "Edit|Write|MultiEdit", "command": "$HOME/.claude/hooks/substrate-clarity-gate.sh"},
-      {"matcher": "Edit|Write|MultiEdit", "command": "$HOME/.claude/hooks/bet-doc-gate.sh"}
-    ]'
-    # Additive jq merge — mirrors §3c-hooks logic but writes to USER_SETTINGS:
-    #   1. Ensure .hooks.PreToolUse array exists
-    #   2. For each bassclef hook:
-    #      - If matcher exists, ensure command is in the matcher's hooks array
-    #      - If matcher missing, create new matcher entry with the command
-    # Operator-managed entries (other matchers, other commands) stay untouched.
-    NEW_OPERATOR_SETTINGS=$(jq --argjson bassclef "$OPERATOR_PRETOOLUSE_JSON" '
-      .hooks //= {} |
-      .hooks.PreToolUse //= [] |
-      reduce $bassclef[] as $hook (
-        .;
-        if (.hooks.PreToolUse | map(.matcher) | index($hook.matcher)) != null then
-          .hooks.PreToolUse |= map(
-            if .matcher == $hook.matcher then
-              if (.hooks | map(.command) | index($hook.command)) == null then
-                .hooks += [{"type": "command", "command": $hook.command}]
-              else . end
-            else . end
-          )
-        else
-          .hooks.PreToolUse += [{
-            "matcher": $hook.matcher,
-            "hooks": [{"type": "command", "command": $hook.command}]
-          }]
-        end
-      )
-    ' "$USER_SETTINGS" 2>/dev/null)
-    if [ -n "$NEW_OPERATOR_SETTINGS" ]; then
-      echo "$NEW_OPERATOR_SETTINGS" > "$USER_SETTINGS.tmp" && \
-        mv "$USER_SETTINGS.tmp" "$USER_SETTINGS"
-      if command -v trace_log >/dev/null 2>&1; then
-        trace_log "ok" "bassclef-sync-pretooluse-embed" \
-          "added_bet_doc=$BET_DOC_GATE_MISSING added_substrate_clarity=$SUBSTRATE_CLARITY_GATE_MISSING"
+  # Surface 3: vendored dispatcher BASSCLEF_SYNC_VERSION drift
+  # (per ADR-032 Layer 3 self-heal; mirrors migrate-adopter-references.sh Surface 3)
+  # Read the current version from the helper to avoid drift between the
+  # comment header, the function, and this constant.
+  CURRENT_VERSION=$(__bassclef_dispatcher_version)
+  for CANDIDATE in "$CWD/.claude/hooks/bassclef-sync.sh" "$CWD/.claude/hooks/canonical-sync.sh"; do
+    if [ -f "$CANDIDATE" ] && [ ! -L "$CANDIDATE" ]; then
+      VENDORED_VERSION=$(grep -m1 'BASSCLEF_SYNC_VERSION=' "$CANDIDATE" 2>/dev/null | sed 's/.*BASSCLEF_SYNC_VERSION=\([^ ]*\).*/\1/' | head -1)
+      if [ -z "$VENDORED_VERSION" ] || [[ "$VENDORED_VERSION" < "$CURRENT_VERSION" ]]; then
+        BASENAME=$(basename "$CANDIDATE")
+        DISPLAY_VERSION="${VENDORED_VERSION:-<missing>}"
+        CANONICAL_FINDINGS+=(".claude/hooks/$BASENAME stale (BASSCLEF_SYNC_VERSION=$DISPLAY_VERSION; current=$CURRENT_VERSION)")
       fi
+      break
     fi
-  fi
-fi
+  done
-# === 4c. Stop template embedding — operator settings.json self-heal ===
-# Same pattern as §4b but for the "Stop": event — wires
-# $HOME/.claude/hooks/turn-prose-kiss-check.sh so the per-turn /kiss scan
-# fires at session-stop boundaries. Per bassclef-upstream#336 sister gap
-# (Stop template embedding missing alongside PreToolUse).
-#
-# Template (operator settings.json fragment, "Stop": event):
-#   {
-#     "hooks": {
-#       "Stop": [
-#         {
-#           "matcher": "",
-#           "hooks": [
-#             {"type": "command", "command": "$HOME/.claude/hooks/turn-prose-kiss-check.sh", "timeout": 30}
-#           ]
-#         }
-#       ]
-#     }
-#   }
-#
-# Timeout 30s: turn-prose-kiss-check scans the most-recent assistant message
-# against the BLOCK wordlist; finishes well under 30s on any realistic
-# transcript. ≥5s minimum per session-artifacts rule (Stop hooks need
-# adequate timeout or they get killed mid-write).
-if [ "${SKIP_STOP_EMBED:-0}" != "1" ] && \
-   command -v jq >/dev/null 2>&1 && \
-   [ -f "$USER_SETTINGS" ]; then
-  # Guard re-emit when turn-prose entry missing
-  if ! grep -q 'turn-prose' ~/.claude/settings.json 2>/dev/null; then
-    TURN_PROSE_MISSING=1
-  else
-    TURN_PROSE_MISSING=0
-  fi
-  if [ "$TURN_PROSE_MISSING" = "1" ]; then
-    # Stop-event entry — empty matcher (Stop fires once per session-end;
-    # no per-tool matcher applies). Command uses $HOME-prefixed path
-    # (Claude Code expands at hook-fire time). Timeout 30 per above.
-    OPERATOR_STOP_JSON='[
-      {"matcher": "", "command": "$HOME/.claude/hooks/turn-prose-kiss-check.sh", "timeout": 30}
-    ]'
-    NEW_STOP_SETTINGS=$(jq --argjson bassclef "$OPERATOR_STOP_JSON" '
-      .hooks //= {} |
-      .hooks.Stop //= [] |
-      reduce $bassclef[] as $hook (
-        .;
-        if (.hooks.Stop | map(.matcher) | index($hook.matcher)) != null then
-          .hooks.Stop |= map(
-            if .matcher == $hook.matcher then
-              if (.hooks | map(.command) | index($hook.command)) == null then
-                .hooks += [{"type": "command", "command": $hook.command, "timeout": $hook.timeout}]
-              else . end
-            else . end
-          )
-        else
-          .hooks.Stop += [{
-            "matcher": $hook.matcher,
-            "hooks": [{"type": "command", "command": $hook.command, "timeout": $hook.timeout}]
-          }]
-        end
-      )
-    ' "$USER_SETTINGS" 2>/dev/null)
-    if [ -n "$NEW_STOP_SETTINGS" ]; then
-      echo "$NEW_STOP_SETTINGS" > "$USER_SETTINGS.tmp" && \
-        mv "$USER_SETTINGS.tmp" "$USER_SETTINGS"
-      if command -v trace_log >/dev/null 2>&1; then
-        trace_log "ok" "bassclef-sync-stop-embed" \
-          "added_turn_prose=$TURN_PROSE_MISSING"
+  if [ "${#CANONICAL_FINDINGS[@]}" -gt 0 ]; then
+    RECOVERY_URL="https://raw.githubusercontent.com/sunj-labs/bassclef/main/scripts/migrate-adopter-references.sh"
+    SIBLING_DISPATCHER_TEMPLATE="$CWD/../bassclef/presence/install/bassclef-sync.dispatcher.template.sh"
+    # Per bet 30a WU-5 (F7 cure): the migrate script reads three env vars
+    # for path overrides. Local layout sibling files for each.
+    SIBLING_RENAME_MAP="$CWD/../bassclef/standards/file-renames.json"
+    SIBLING_STATUSLINE_TEMPLATE="$CWD/../bassclef/presence/cli/bassclef-statusline.dispatcher.sh"
+    # Decide auto-invoke vs BLOCKED-only path (per bet 29e WU-4)
+    AUTO_INVOKE_READY=0
+    if [ "${SKIP_AUTO_INVOKE:-0}" != "1" ]; then
+      if [ -n "${BASSCLEF_RECOVERY_SCRIPT_PATH:-}" ] && [ -f "$BASSCLEF_RECOVERY_SCRIPT_PATH" ]; then
+        AUTO_INVOKE_READY=1
+      elif command -v curl >/dev/null 2>&1; then
+        AUTO_INVOKE_READY=1
       fi
     fi
-  fi
-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
+    if [ "$AUTO_INVOKE_READY" = "1" ]; then
+      # === Leg 3 of self-healing — auto-invocation (WU-4) ===
+      # Detection found canonical-* refs; run the migrate script
+      # automatically; continue the dispatcher chain afterward so the
+      # adopter sees one clean session-start (no second paste needed).
+      echo ""
+      echo "🩹 bassclef self-heal — canonical-* references detected; running recovery automatically"
+      for finding in "${CANONICAL_FINDINGS[@]}"; do
+        echo "  - $finding"
+      done
-# === 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 ~/.claude/hooks/*.sh 2>/dev/null | wc -l | tr -d ' ')
-echo ""
-echo "### BASSCLEF SUBSTRATE — SYNCED"
-echo ""
-echo "Status: $SYNC_STATUS"
-echo "Skills: ${SKILL_COUNT} (symlinked to .claude/skills/ for auto-discovery)"
-echo "Rules: ${RULE_COUNT} (loaded via additionalDirectories + env var)"
-echo "Agents: ${AGENT_COUNT} (installed to ~/.claude/agents/)"
-echo "Hooks: ${HOOK_COUNT} user-level (bug-diagnosis, tool-failure, trace-helper)"
-echo ""
-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
+      # Source the migrate script (env-var override for tests, curl in prod).
+      # Per bet 30a WU-5 (F7 cure): pass all three env vars the migrate
+      # script reads — DISPATCHER_TEMPLATE + RENAME_MAP + STATUSLINE_TEMPLATE
+      # — when their sibling files exist. Without these, the script's
+      # fallback expansion `$(cd "$(dirname "$0")/..")` resolves wrong
+      # under curl-pipe ($0 = bash), and Surfaces 5 + 6 silently no-op.
+      # POA was broken for 8+ days because only the dispatcher template
+      # env var was passed.
+      ENV_ARGS=()
+      [ -f "$SIBLING_DISPATCHER_TEMPLATE" ] && ENV_ARGS+=("BASSCLEF_DISPATCHER_TEMPLATE=$SIBLING_DISPATCHER_TEMPLATE")
+      [ -f "$SIBLING_RENAME_MAP" ] && ENV_ARGS+=("BASSCLEF_RENAME_MAP=$SIBLING_RENAME_MAP")
+      [ -f "$SIBLING_STATUSLINE_TEMPLATE" ] && ENV_ARGS+=("BASSCLEF_STATUSLINE_TEMPLATE=$SIBLING_STATUSLINE_TEMPLATE")
+      # Per bet 2026-08-27 step 7 PR #1 — resolver picks source with priority
+      # env override → sibling → curl+checksum. Verifier gates curl path.
+      RESOLVED=$(resolve_recovery_script)
+      RESOLVED_KIND="${RESOLVED%%:*}"
+      RESOLVED_REST="${RESOLVED#*:}"
+      case "$RESOLVED_KIND" in
+        LOCAL|SIBLING)
+          echo "🩹 recovery source: $RESOLVED_KIND ($RESOLVED_REST)" >&2
+          if [ "${#ENV_ARGS[@]}" -gt 0 ]; then
+            cat "$RESOLVED_REST" | env "${ENV_ARGS[@]}" bash -s -- --apply "$CWD" || true
+          else
+            cat "$RESOLVED_REST" | bash -s -- --apply "$CWD" || true
+          fi
+          ;;
+        CURL)
+          RECOVERY_URL_RESOLVED="${RESOLVED_REST%|*}"
+          SHA_URL="${RESOLVED_REST#*|}"
+          echo "🩹 recovery source: CURL ($RECOVERY_URL_RESOLVED)" >&2
+          TMP_SCRIPT=$(mktemp -t bassclef-recovery.XXXXXX.sh) || {
+            echo "⚠ bassclef self-heal: mktemp failed; skipping recovery" >&2
+            true
+          }
+          TMP_SHA=$(mktemp -t bassclef-recovery.XXXXXX.sha) || {
+            rm -f "$TMP_SCRIPT" 2>/dev/null
+            echo "⚠ bassclef self-heal: mktemp failed; skipping recovery" >&2
+            true
+          }
+          # Fetch both files; abort verify path if either fetch fails
+          if curl -sL --fail "$RECOVERY_URL_RESOLVED" -o "$TMP_SCRIPT" 2>/dev/null \
+             && curl -sL --fail "$SHA_URL" -o "$TMP_SHA" 2>/dev/null; then
+            EXPECTED_SHA=$(awk '{print $1}' "$TMP_SHA")
+            if verify_checksum "$TMP_SCRIPT" "$EXPECTED_SHA"; then
+              echo "🩹 recovery: checksum verified; executing" >&2
+              if [ "${#ENV_ARGS[@]}" -gt 0 ]; then
+                cat "$TMP_SCRIPT" | env "${ENV_ARGS[@]}" bash -s -- --apply "$CWD" || true
+              else
+                cat "$TMP_SCRIPT" | bash -s -- --apply "$CWD" || true
+              fi
+            else
+              echo "🛑 recovery: SHA-256 mismatch; refusing to execute" >&2
+              echo "   URL: $RECOVERY_URL_RESOLVED" >&2
+              echo "   To retry manually after investigating:" >&2
+              echo "   SKIP_CANONICAL_DETECTION=1 <re-run session>" >&2
+            fi
+          else
+            echo "⚠ bassclef self-heal: fetch failed for recovery or checksum" >&2
+            echo "   Falls back to manual recovery via BLOCKED path below" >&2
+          fi
+          rm -f "$TMP_SCRIPT" "$TMP_SHA" 2>/dev/null
+          ;;
+        *)
+          echo "⚠ bassclef self-heal: resolver returned unknown kind ($RESOLVED_KIND); skipping" >&2
+          ;;
+      esac
+      echo "🩹 bassclef self-heal: recovery applied; continuing"
+      echo ""
+      # Fall through to Path 1 / Path 2 — substrate now loadable
+    else
+      # === Fall back: BLOCKED + exit (WU-2 behavior) ===
+      # SKIP_AUTO_INVOKE=1 set, OR neither curl nor BASSCLEF_RECOVERY_SCRIPT_PATH
+      # available. Surface the recovery shape and stop here.
+      cat <<DETECT
-if [ "$ORPHAN_COUNT" -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)/"
-  echo "  ~/.claude/agents.orphans.$(date +%Y%m%d)/"
-  echo "  ~/.claude/hooks.orphans.$(date +%Y%m%d)/"
-  echo ""
-  echo "Project-level entries now load without dedupe conflict."
-  echo "Backups survive 30 days minimum; restore if a script you wrote"
-  echo "depends on the user-level location."
-  echo ""
-fi
+🛑 BLOCKED: bassclef substrate — canonical-* references detected
-echo "YOU MUST confirm to the user:"
-echo "  'Bassclef substrate synced: ${SKILL_COUNT} skills, ${RULE_COUNT} rules,"
-echo "   ${AGENT_COUNT} agents, ${HOOK_COUNT} hooks. Status: ${SYNC_STATUS}.'"
-echo ""
+Your adopter tree carries references from before the 2026-06-20
+canonical→bassclef rename. Bassclef cannot load substrate cleanly
+until these are repaired.
-# === 6. Worktree cleanup — prune stale worktrees from crashed parallel sessions ===
-STALE_WORKTREES=$(git -C "$CWD" worktree list --porcelain 2>/dev/null | grep "^worktree " | grep -v "$CWD$" | wc -l | tr -d ' ')
-if [ "$STALE_WORKTREES" -gt 0 ]; then
-  # Prune worktrees whose directories no longer exist
-  git -C "$CWD" worktree prune 2>/dev/null || true
+Found:
+DETECT
+      for finding in "${CANONICAL_FINDINGS[@]}"; do
+        echo "  - $finding"
+      done
+      cat <<RECOVERY
-  # Clean up .claude/worktrees/ directory if it exists
-  if [ -d "$CWD/.claude/worktrees" ]; then
-    rm -rf "$CWD/.claude/worktrees" 2>/dev/null || true
-  fi
+Recovery — one paste, no extra setup:
-  REMAINING=$(git -C "$CWD" worktree list --porcelain 2>/dev/null | grep "^worktree " | grep -v "$CWD$" | wc -l | tr -d ' ')
-  if [ "$REMAINING" -gt 0 ]; then
-    echo "### STALE WORKTREES DETECTED"
-    echo ""
-    echo "$REMAINING worktree(s) from a previous session still exist."
-    echo "These may hold branch locks. Review and remove:"
-    echo ""
-    git -C "$CWD" worktree list 2>/dev/null | grep -v "$CWD "
-    echo ""
-    echo "To remove: git worktree remove <path>"
-    echo ""
+  curl -sL $RECOVERY_URL | bash -s -- --apply "$CWD"
+After it runs, open a fresh Claude Code session in this repo.
+To skip this check once (override):  SKIP_CANONICAL_DETECTION=1
+To skip auto-invocation (manual recovery): SKIP_AUTO_INVOKE=1
+Refs: scripts/migrate-adopter-references.sh, .claude/rules/we-dont-break-adopters.md
+RECOVERY
+      exit 0
+    fi
   fi
 fi
-# === 7. Boot check — only report what's missing ===
-MISSING=""
+# === Path 1. Sibling fast-path ===
+SIBLING_TEMPLATE="$CWD/../bassclef/presence/install/bassclef-sync.template.sh"
+if [ -f "$SIBLING_TEMPLATE" ]; then
+  echo "$INPUT" | bash "$SIBLING_TEMPLATE"
+  exit $?
+fi
-# Google service account (needed for journal → Google Docs)
-# Ship 1 (#1816): env var lookup; operator sets BASSCLEF_GCLOUD_KEY in their shell profile.
-# Unset = feature disabled (no adopter-visible path leak).
-SA_KEY="${BASSCLEF_GCLOUD_KEY:-}"
-if [ -n "$SA_KEY" ] && [ ! -f "$SA_KEY" ]; then
-  MISSING="${MISSING}\n- Google Docs service account key missing at \$BASSCLEF_GCLOUD_KEY (needed for /journal → Google Doc push)"
+# === Path 1.5. Bundled-substrate recognition (per #1849) ===
+# npm-only cold adopters carry substrate in the package bundle. The
+# dispatcher was designed for peer-checkout OR source-config models; both
+# fail for anonymous adopters against private repos. Before firing the
+# fetch-strategies path, check whether the substrate is already loaded at
+# CWD. If yes, exit silently — no news is good news (Cooper).
+#
+# Override: BASSCLEF_DISPATCHER_STRICT=1 forces the Path 2 fetch even when
+# bundled substrate is present (operator debugging).
+if [ "${BASSCLEF_DISPATCHER_STRICT:-0}" != "1" ]; then
+  if bassclef_sync_bundled_substrate_present "$CWD"; then
+    exit 0
+  fi
 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)"
+# === Path 2. Curl fallback ===
+# Uses the same resolver as auto_sync pre-check so old-name adopters
+# still get here (self-heal already fired above, but resolve for safety
+# in case self-heal was skipped via SKIP_SELF_HEAL_POINTER).
+SOURCE_FILE=$(bassclef_sync_resolve_pointer_file "$CWD")
+if [ -z "$SOURCE_FILE" ] || [ ! -f "$SOURCE_FILE" ]; then
+  emit_error "couldn't find bassclef substrate" \
+"This repo doesn't have a sibling bassclef checkout at ../bassclef AND
+doesn't have a .bassclef-source.json file to fetch from a remote source.
+The dispatcher needs ONE of those to load bassclef's substrate (skills,
+rules, hooks, luminaries) into your session."
 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 ""
+SOURCE_URL=$(jq -r '.source_url // empty' "$SOURCE_FILE")
+AUTH_METHOD=$(jq -r '.auth_method // "none"' "$SOURCE_FILE")
+TOKEN_ENV=$(jq -r '.token_env // "BASSCLEF_TOKEN"' "$SOURCE_FILE")
+if [ -z "$SOURCE_URL" ]; then
+  emit_error ".bassclef-source.json is missing source_url" \
+"Your .bassclef-source.json file exists but doesn't specify where to fetch
+bassclef from. The 'source_url' field is required.
+See standards/bassclef-source-config.md for the schema and provider
+examples (GitHub public release, GitHub private repo, Azure DevOps, GitLab)."
 fi
-# === 8. journal draft staleness check ===
-# Check both bassclef and the current repo for stale drafts.
-#
-# Fetch origin first (per bassclef-upstream#403): the staleness check
-# below reads local filesystem state + local git log, which diverges
-# from origin when another session has pushed since the last pull
-# (e.g., a prior session-end's commit). Without the fetch, the banner
-# shows wrong-now data (observed 2026-06-26c — local saw 2026-06-19
-# while origin had 2026-06-26.md from #401).
-#
-# Best-effort: || true keeps the check working when offline / no remote.
-CURRENT_BRANCH_FOR_FETCH=$(git -C "$CWD" symbolic-ref --short HEAD 2>/dev/null)
-if [ -n "$CURRENT_BRANCH_FOR_FETCH" ]; then
-  git -C "$CWD" fetch origin "$CURRENT_BRANCH_FOR_FETCH" --quiet 2>/dev/null || true
+# Resolve auth header from env-stored token.
+TOKEN_VALUE=""
+AUTH_HEADER=""
+if [ "$AUTH_METHOD" != "none" ]; then
+  TOKEN_VALUE=$(printenv "$TOKEN_ENV" 2>/dev/null || true)
+  if [ -z "$TOKEN_VALUE" ]; then
+    emit_error "auth token not set in environment" \
+"Your .bassclef-source.json uses auth_method '$AUTH_METHOD' and expects the
+'$TOKEN_ENV' environment variable to hold the token. That variable isn't set
+in this environment.
+If you're in CI:        the secret needs to be configured on the repo
+                        (gh secret set $TOKEN_ENV -R <repo>).
+If you're on a laptop:  export $TOKEN_ENV=<token> in your shell.
+If you're in Cloud Code: set $TOKEN_ENV in your environment config.
+If you don't have a token yet, follow option 3 below to create one."
+  fi
+  case "$AUTH_METHOD" in
+    Bearer) AUTH_HEADER="Authorization: Bearer $TOKEN_VALUE" ;;
+    Basic)  AUTH_HEADER="Authorization: Basic $(printf ':%s' "$TOKEN_VALUE" | base64)" ;;
+    *)      AUTH_HEADER="Authorization: $AUTH_METHOD $TOKEN_VALUE" ;;
+  esac
 fi
-DRAFT_DIRS=""
-if [ -d "$CWD/docs/operator-private/journals" ]; then
-  DRAFT_DIRS="$CWD/docs/operator-private/journals"
-elif [ -d "$CWD/docs/journals" ]; then
-  # Pre-2026-06-27 path — migrated to operator-private per bassclef-upstream#405
-  DRAFT_DIRS="$CWD/docs/journals"
-elif [ -d "$CWD/docs/linkedin-drafts" ]; then
-  # Legacy path — pre-/linkedin-→-/journal rename
-  DRAFT_DIRS="$CWD/docs/linkedin-drafts"
+# Fetch tarball
+TARBALL="/tmp/bassclef-thin-pointer-$$.tar.gz"
+if [ -n "$AUTH_HEADER" ]; then
+  HTTP_CODE=$(curl -sS -L -H "$AUTH_HEADER" -w "%{http_code}" -o "$TARBALL" "$SOURCE_URL" 2>/dev/null || echo "000")
+else
+  HTTP_CODE=$(curl -sS -L -w "%{http_code}" -o "$TARBALL" "$SOURCE_URL" 2>/dev/null || echo "000")
 fi
-if [ -d "$BASSCLEF_DIR/docs/operator-private/journals" ] && [ "$BASSCLEF_DIR" != "$CWD" ]; then
-  DRAFT_DIRS="$DRAFT_DIRS $BASSCLEF_DIR/docs/operator-private/journals"
-elif [ -d "$BASSCLEF_DIR/docs/journals" ] && [ "$BASSCLEF_DIR" != "$CWD" ]; then
-  DRAFT_DIRS="$DRAFT_DIRS $BASSCLEF_DIR/docs/journals"
+if [ "$HTTP_CODE" != "200" ]; then
+  rm -f "$TARBALL" 2>/dev/null
+  emit_error "fetch returned HTTP $HTTP_CODE" \
+"The dispatcher tried to download bassclef from:
+    $SOURCE_URL
+The server returned HTTP $HTTP_CODE instead of 200. Common causes:
+  HTTP 401: token is invalid or expired. Regenerate it.
+  HTTP 403: token is valid but doesn't have the required permission
+            (needs Contents:read on the bassclef repo).
+  HTTP 404: source_url is wrong, OR the bassclef repo / release
+            doesn't exist at that URL.
+  HTTP 000: network couldn't reach the host. Check DNS / firewall /
+            whether you're offline."
 fi
-if [ -n "$DRAFT_DIRS" ]; then
-  LATEST_DRAFT=""
-  for DIR in $DRAFT_DIRS; do
-    LAST=$(ls -1 "$DIR"/*.md 2>/dev/null | sort | tail -1)
-    if [ -n "$LAST" ]; then
-      DRAFT_DATE=$(basename "$LAST" .md | head -c 10)
-      if [ -z "$LATEST_DRAFT" ] || [ "$DRAFT_DATE" \> "$LATEST_DRAFT" ]; then
-        LATEST_DRAFT="$DRAFT_DATE"
-      fi
-    fi
-  done
+# Extract to a stable per-user location.
+BASSCLEF_FRESH="$HOME/bassclef-fresh"
+rm -rf "$BASSCLEF_FRESH" 2>/dev/null
+mkdir -p "$BASSCLEF_FRESH"
+if ! tar -xzf "$TARBALL" -C "$BASSCLEF_FRESH" --strip-components=1 2>/dev/null; then
+  rm -f "$TARBALL"
+  emit_error "couldn't extract the downloaded tarball" \
+"The dispatcher downloaded the file from $SOURCE_URL but tar -xzf failed.
-  if [ -n "$LATEST_DRAFT" ]; then
-    TODAY=$(date +%Y-%m-%d)
-    # Count commits since last draft
-    COMMITS_SINCE=$(git -C "$CWD" log --oneline --since="$LATEST_DRAFT" 2>/dev/null | wc -l | tr -d ' ')
+This usually means the response wasn't a real tarball. Check:
-    if [ "$LATEST_DRAFT" != "$TODAY" ] && [ "$COMMITS_SINCE" -gt 3 ]; then
-      DAYS_AGO=$(( ( $(date +%s) - $(date -j -f "%Y-%m-%d" "$LATEST_DRAFT" +%s 2>/dev/null || echo 0) ) / 86400 ))
-      echo "### JOURNAL DRAFTS OVERDUE (SHOULD — backfill before other work)"
-      echo ""
-      echo "Last draft: $LATEST_DRAFT ($DAYS_AGO days ago, $COMMITS_SINCE commits since)"
-      echo ""
-      echo "→ BACKFILL NOW — before starting new work."
-      echo "  1. Read chronicles since $LATEST_DRAFT"
-      echo "  2. Write drafts for each session with a notable decision or insight"
-      echo "  3. Push to Google Doc (oldest first)"
-      echo "  4. Then proceed with session work"
-      echo ""
-      echo "This is a SHOULD gate. Do not skip without documented rationale."
-      echo ""
-    fi
-  fi
+  - Is source_url correct? It should return a gzipped tarball, not HTML.
+  - Is a network proxy / SSO portal injecting a login page instead?
+  - To inspect what the server is actually sending, run:
+      curl -sSL -H \"Authorization: ...\" \"$SOURCE_URL\" | file -
+    If the output says 'HTML document' instead of 'gzip compressed data',
+    you're being intercepted."
+fi
+rm -f "$TARBALL"
+# Exec the big template.
+#
+# Export the extracted tarball root so §3c-hooks (dynamic-derive hook connect,
+# per bassclef-upstream#625) can read bassclef's own .claude/settings.json.
+# The template sources presence/install/bassclef-hook-connect.sh and calls
+# bassclef_hook_connect_apply "$CWD" — the function reads
+# $BASSCLEF_SOURCE_ROOT/.claude/settings.json to learn the current hook list
+# across every event type, then merges every entry additively into the
+# adopter's settings.json.
+export BASSCLEF_SOURCE_ROOT="$BASSCLEF_FRESH"
+FALLBACK_TEMPLATE="$BASSCLEF_FRESH/presence/install/bassclef-sync.template.sh"
+if [ ! -f "$FALLBACK_TEMPLATE" ]; then
+  emit_error "tarball is missing bassclef-sync.template.sh" \
+"The dispatcher downloaded and extracted the tarball, but it doesn't
+contain presence/install/bassclef-sync.template.sh — bassclef's
+main sync logic.
+This usually means source_url points at a tarball that isn't bassclef
+(e.g., a different repo, or a branch / tag that's missing the template
+file). Verify the URL in .bassclef-source.json points at bassclef's
+main branch or a release that includes strategy/templates/."
 fi
-exit 0
+echo "$INPUT" | bash "$FALLBACK_TEMPLATE"
+exit $?