@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/bassclef-orientation.md

@@ -0,0 +1,120 @@
+---
+tier: lite
+purpose: adopter orientation — auto-imported into adopter CLAUDE.md via @.claude/bassclef-orientation.md per ADR-032 + Anthropic @import convention
+last_updated: 2026-06-22
+bet: 2026-06-22b-dispatcher-hardening-rename-orientation (WU-5)
+---
+
+# Bassclef orientation
+
+You've inherited the bassclef substrate. This file loads into every session via `@import` from your CLAUDE.md.
+
+The substrate is a stable set of skills, rules, hooks, luminaries, agents, and standards that pin discipline at decision boundaries. It evolves upstream in `sunj-labs/bassclef-upstream`; you receive releases from public `sunj-labs/bassclef` via `bassclef-sync` at every session start.
+
+## What you have
+
+| Layer | Where | Discover |
+|---|---|---|
+| Skills (invocable workflows) | `.claude/skills/<name>/SKILL.md` | `/skills` |
+| Rules (auto-loaded context) | `.claude/rules/*.md` | All loaded every session via `additionalDirectories` |
+| Luminaries (design + authoring lenses) | `.claude/luminaries/*.md` | `/luminary` |
+| Agents (specialist roles) | `.claude/agents/*.md` | Used by `/autonomous`, `/build`, `/longrun` |
+| Hooks (mechanical enforcement) | `.claude/hooks/*.sh` | Fire automatically; see `/hooks` |
+| Standards (reference docs) | `standards/*.md` | Cited by rules + skills |
+| ADRs (architectural decisions) | `architecture/decisions/ADR-*.md` | Read before changing what they govern |
+
+## Cross-cutting gates — fire across every phase
+
+| Gate | When to run |
+|---|---|
+| `/temperance` | Before first edit on a branch + at scope-decision boundaries |
+| `/diagnose` | Before writing any fix code |
+| `/quick-fix` | Localized, obvious, ≤10 lines, no blast radius |
+| `/auto-fix` | Narrow non-trivial bugs within Builder's safe zone |
+| `/verify` | After each task before committing |
+| `/whats-the-plan` | Before any ≥3-skill chain |
+| `/kiss` | When scope bloats or prose drifts toward jargon |
+| `/luminary` | Before ADR authoring + at any design-decision boundary |
+
+## SDLC flow
+
+```
+Canvas → Spec → Design → Issue → Branch → PR → CI → Deploy → Observe
+```
+
+For UI work, run the UX translation chain during Design:
+
+```
+JTBD → HTA → Entity Model → State Diagrams → Sequence Diagrams → /decompose
+```
+
+## Conventions
+
+- **Commits**: `type: description` per `.claude/rules/commit-conventions.md`
+- **PR titles**: ≤72 chars per `.claude/rules/pr-title-shape.md`
+- **PR bodies**: open with `**Problem (≤500 chars):**` per `.claude/rules/pr-body-shape.md`
+- **Specs** reference their source canvas or issue
+- **New standards** go in `standards/`, not inline in other docs
+
+## What NOT to do
+
+- **Don't break adopters** (ADR-031). Every change to a downstream-observable surface ships with a compat shim, migration manifest, and changelog entry.
+- **Don't make architectural or design decisions without consulting luminaries.** Design without a named lens drifts toward generic; the lens is what gives you a position to defend in review.
+- **Don't release without checking prior open PRs first.** Cumulative stacks create cascade failures.
+- **Don't write source before tests** on Tier 0 paths (per `.claude/rules/testing-tier-config.md`).
+- **Don't auto-apply discipline changes without `/temperance`** at scope boundaries.
+- **Don't conflate "propose" with "execute".** When operator says "propose," "options," "path forward" — wait for explicit go signal.
+- **Don't use bassclef-internal jargon** in operator-facing prose. Plain English at grade-10 reading level.
+- **Don't push to main without PR review** even on solo workflows.
+
+## Luminaries at design boundaries
+
+The substrate ships ~38 luminaries (Linus, Beck, Brooks, Norman, Cooper, Tufte, Nygard, Vernon, Ousterhout, Hyrum, Myers, Hoare, Saltzer-Schroeder, Parnas, Fowler, and more). They pin specific disciplines — they aren't decoration.
+
+When to consult:
+
+- **Architectural decisions (ADRs)** — pin 1-3 luminaries; the ADR cites their lens
+- **Iteration bets** — declare a luminary map (primary pair + extended pairs per surface in scope) per `.claude/rules/iteration-bet-brief-completeness.md`
+- **UI surfaces** — Norman / Cooper / Tufte / Morville per the surface's job
+- **Cross-cutting design choices** — Bulkhead (Nygard) + Anticorruption Layer (Vernon) + Deep Modules (Ousterhout) converge often
+
+`/luminary <slug>` previews one; `/luminary` browses by discipline. Skills with UI / architecture surfaces pin their luminary map in frontmatter — read the skill before invoking.
+
+## Luminaries at the keyboard — not just the whiteboard
+
+Beyond ADRs and iteration bets, luminaries inform code authoring directly. **Pick ONE dominant lens per scope** (bet / WU / surface) and check your work against it. Background discipline fires automatically — don't manually verify against each.
+
+| Scope | Default dominant authoring luminary |
+|---|---|
+| Most code | @luminary kent-beck (TDD rhythm + test list + simple design) |
+| Bash hooks + scripts | @luminary saltzer-schroeder (7 defensive disciplines) |
+| State-spine writes | @luminary tony-hoare (pre/postconditions; contracts) |
+| UI components | Whichever pair the prototype pinned |
+| Architecture refactoring | @luminary john-ousterhout (deep modules) + @luminary martin-fowler (refactoring patterns) |
+
+**Background discipline** (fires automatically — don't manually verify):
+
+- **Rules cite anchor luminaries** explaining why each rule exists. Read the rule; the anchor tells you when the rule generalizes vs when an edge case applies
+- **Hooks enforce specific luminary-anchored disciplines mechanically** — `testing-tier-enforce.sh` (Beck), `state-validate.sh` (Hoare), `substrate-clarity-gate.sh` (context engineering)
+- **`@pattern <catalog-path>` annotation** in source code when you CONSCIOUSLY instantiate a named pattern (GoF, Fowler, Vernon DDD). Not every class — only the ones that EMBODY a pattern as a design choice. Per `.claude/rules/pattern-annotation.md`
+
+## Luminary matching — tier ladder
+
+`/pick-luminaries` picks luminary fits for an intent paragraph. Adopter capability scales with what keys you provide:
+
+- **lite** — stub / deterministic mode; no keys required; for cold-start adopters + CI + tests
+- **standard** — single LLM call picks from the full catalog; semantic matching; needs `ANTHROPIC_API_KEY` (default in bassclef-core)
+- **ultra** — embedding shortlist (Voyage `voyage-3-lite`) + LLM judge re-rank; faster + per-candidate confidence; needs `ANTHROPIC + VOYAGE` keys; load `bassclef-upstream` via `additionalDirectories` to activate
+
+Pre-computed catalog embeddings (~230KB) ship with bassclef-upstream so ultra-tier Voyage cost is per-query intent embedding only.
+
+Pick the tier that matches your trust + budget. Upgrade path is additive — no migration required to move lite → standard → ultra. See bassclef-upstream#262 for ultra-tier downstream-readiness status; bassclef-upstream#263 for the future "plus" tier (local embedding model, no Voyage key).
+
+## Discovery commands
+
+- `/sprint` — what's in flight + what's next
+- `/whereami` — current project state
+- `/substrate-check` — validate substrate wiring
+- `/skills` — phase-grouped skill catalog
+- `/luminary` — design-lens catalog
+- `/hooks` — mechanical-enforcement layer

package/dist/lite/.claude/hooks/adr-discipline-check.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# tier: lite
+# adr-discipline-check.sh — PreToolUse hook on architectural decision boundaries
+#
+# Detects "load-bearing" architectural decisions via path-shape heuristics and
+# refuses unless an ADR marker at state/markers/adr/<decision-slug>.md exists
+# linking to a real ADR file under docs/adrs/ or architecture/decisions/.
+#
+# Per bassclef#1149 + WU-11 of bet 2026-06-20e.
+# Override: SKIP_ADR_CHECK=1 (logged via trace-helper).
+
+set -euo pipefail
+
+# ============================================================================
+# Read stdin JSON from Claude Code harness
+# ============================================================================
+PAYLOAD=$(cat 2>/dev/null || echo '{}')
+
+TOOL_NAME=$(echo "$PAYLOAD" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE_PATH=$(echo "$PAYLOAD" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+# ============================================================================
+# Filters: only fire on Write/Edit/MultiEdit
+# ============================================================================
+case "$TOOL_NAME" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# ============================================================================
+# Override check
+# ============================================================================
+if [ "${SKIP_ADR_CHECK:-0}" = "1" ]; then
+  TRACE_HELPER="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/trace-helper.sh"
+  if [ -f "$TRACE_HELPER" ]; then
+    bash "$TRACE_HELPER" override "adr-discipline-check" "SKIP_ADR_CHECK=1 on $FILE_PATH" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# ============================================================================
+# Architectural-decision detection via path-shape heuristics
+# ============================================================================
+IS_ARCHITECTURAL=0
+DECISION_SLUG=""
+
+case "$FILE_PATH" in
+  */prisma/schema.prisma|prisma/schema.prisma)
+    IS_ARCHITECTURAL=1
+    DECISION_SLUG="schema-change"
+    ;;
+  */docker-compose*.yml|docker-compose*.yml|*/docker-compose*.yaml|docker-compose*.yaml)
+    IS_ARCHITECTURAL=1
+    DECISION_SLUG="deployment-topology-change"
+    ;;
+  */middleware.ts|src/middleware.ts|*/middleware.py|*/middleware.rb)
+    IS_ARCHITECTURAL=1
+    DECISION_SLUG="middleware-change"
+    ;;
+  */alembic/versions/*.py|*/db/migrate/*.rb|*/migrations/*.go)
+    IS_ARCHITECTURAL=1
+    DECISION_SLUG="schema-migration"
+    ;;
+esac
+
+# package.json / pyproject.toml / Gemfile / go.mod / Cargo.toml — only fire on Write (new file or rewrite)
+# Detecting "dependency-add" inside Edit would require diff parsing; deferred to V2
+if [ "$TOOL_NAME" = "Write" ]; then
+  case "$FILE_PATH" in
+    */package.json|package.json|*/pyproject.toml|pyproject.toml|*/Gemfile|Gemfile|*/go.mod|go.mod|*/Cargo.toml|Cargo.toml)
+      IS_ARCHITECTURAL=1
+      DECISION_SLUG="dependency-manifest-change"
+      ;;
+  esac
+fi
+
+if [ "$IS_ARCHITECTURAL" -eq 0 ]; then
+  exit 0
+fi
+
+# ============================================================================
+# Marker check: state/markers/adr/<decision-slug>.md must exist
+# ============================================================================
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+MARKER_DIR="$REPO_ROOT/state/markers/adr"
+
+# Explicit marker required — generic "recent ADR in dir" is too permissive
+# (other ADRs unrelated to this decision class would silently satisfy)
+if find "$MARKER_DIR" -maxdepth 1 -name "${DECISION_SLUG}*.md" 2>/dev/null | grep -q .; then
+  exit 0
+fi
+
+# ============================================================================
+# Block: no marker + no recent ADR
+# ============================================================================
+cat >&2 <<EOF
+🛑 adr-discipline-check — BLOCK (bassclef#1149)
+
+You're about to make a load-bearing architectural decision: ${DECISION_SLUG}
+
+Path: ${FILE_PATH}
+
+Architectural decisions require an ADR (Architecture Decision Record)
+per Michael Nygard's lifecycle: proposed → accepted → deprecated → superseded.
+
+Write one before proceeding:
+
+1. Copy the template:
+   cp standards/adr-template.md docs/adrs/ADR-NNN-<slug>.md
+   (or architecture/decisions/ADR-NNN-<slug>.md per your project layout)
+
+2. Fill Context + Decision + Status + Consequences sections.
+
+3. Touch the marker:
+   mkdir -p ${MARKER_DIR}
+   touch ${MARKER_DIR}/${DECISION_SLUG}-<your-slug>.md
+
+4. Retry the original change.
+
+Override (logged): SKIP_ADR_CHECK=1 <command>
+
+When to use override:
+- Trivial revert of a previously-decided architectural change
+- Emergency rescue when the hook itself misclassifies
+- One-shot migration script that touches many architectural files
+EOF
+
+exit 2

package/dist/lite/.claude/hooks/atomic-pr-check.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# tier: lite
+# Atomic-PR Check — fires on Bash tool calls matching "git push" patterns.
+# Counts distinct WU-N tags in commit messages on the branch. BLOCKs the
+# push if multiple step tags exist unless an iteration goal declares
+# `bundle: true` in frontmatter.
+#
+# Phase II of 8-phase staircase: Trim the Fat (bassclef#382).
+# The methodology rule at .claude/rules/pr-strategy.md is the reasoning;
+# this hook is the mechanical enforcement.
+#
+# Exit codes:
+#   0 — allow (no WU tags, single WU tag, bundle:true in matching bet,
+#       or override)
+#   2 — block (multi-step branch without bundle:true)
+#
+# Override: SKIP_ATOMIC_PR_CHECK=1 to bypass (logged via trace-helper)
+#
+# Rule:  .claude/rules/pr-strategy.md
+# Issue: bassclef#382
+
+set +e  # never crash the tool call; fall through to allow on any unexpected error
+
+INPUT=$(cat)
+TOOL_NAME=$(jq <<< "$INPUT" -r '.tool_name // ""' 2>/dev/null)
+COMMAND=$(jq <<< "$INPUT" -r '.tool_input.command // ""' 2>/dev/null)
+
+# Only fire on Bash with a git push command
+if [ "$TOOL_NAME" != "Bash" ]; then
+  exit 0
+fi
+
+# Match git push patterns (allow flags like -u, --force, etc.)
+case "$COMMAND" in
+  *"git push"*)
+    : # match — continue
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Override hatch — log and allow
+if [ "${SKIP_ATOMIC_PR_CHECK:-0}" = "1" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+  if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+    source "$SCRIPT_DIR/trace-helper.sh" 2>/dev/null || true
+    trace_log "atomic-pr-check" "OVERRIDE git push" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Find the repo root
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$REPO_ROOT" ]; then
+  exit 0  # not in a git repo — allow
+fi
+cd "$REPO_ROOT" || exit 0
+
+# Get current branch name
+BRANCH=$(git branch --show-current 2>/dev/null)
+if [ -z "$BRANCH" ]; then
+  exit 0  # detached HEAD or no branch — allow
+fi
+
+# Skip the check on main branch and bare branch names
+case "$BRANCH" in
+  main|master|HEAD)
+    exit 0
+    ;;
+esac
+
+# Find commits on this branch not yet on main
+# If main is not available locally, fall back to origin/main, then to all commits
+BASE_REF=""
+if git rev-parse --verify main >/dev/null 2>&1; then
+  BASE_REF="main"
+elif git rev-parse --verify origin/main >/dev/null 2>&1; then
+  BASE_REF="origin/main"
+fi
+
+if [ -n "$BASE_REF" ]; then
+  COMMITS=$(git log --format="%s%n%b" "${BASE_REF}..HEAD" 2>/dev/null)
+else
+  # No base ref available — check the last 10 commits as a heuristic
+  COMMITS=$(git log -10 --format="%s%n%b" HEAD 2>/dev/null)
+fi
+
+# Extract distinct WU-N tags from commit messages
+# Match patterns: "WU-1", "WU-2a", "WU-3", etc. (case-sensitive; expects WU-)
+WU_TAGS=$(echo "$COMMITS" | grep -oE '\bWU-[0-9]+[a-z]?\b' | sort -u)
+
+# Count distinct WU tags. If WU_TAGS is empty, count is 0.
+if [ -z "$WU_TAGS" ]; then
+  WU_COUNT=0
+else
+  WU_COUNT=$(echo "$WU_TAGS" | wc -l | tr -d ' ')
+fi
+
+# 0 or 1 WU tags — allow
+if [ "$WU_COUNT" -le 1 ]; then
+  exit 0
+fi
+
+# Multi-WU branch — check for bundle:true in any matching goal doc
+ALLOWED=0
+ITERATION_BETS_DIR="docs/iteration-bets"
+if [ -d "$ITERATION_BETS_DIR" ]; then
+  # Look for goal docs that mention any of the step tags AND have bundle: true
+  for bet in "$ITERATION_BETS_DIR"/*.md; do
+    [ -f "$bet" ] || continue
+    # Check if bet has bundle: true in frontmatter
+    if awk '/^---$/{c++; next} c==1 && /^bundle:[[:space:]]*true/{print "yes"; exit}' "$bet" | grep -q "yes"; then
+      # Verify this goal covers at least one of the step tags
+      for wu in $WU_TAGS; do
+        if grep -qE "\\b${wu}\\b" "$bet"; then
+          ALLOWED=1
+          break 2
+        fi
+      done
+    fi
+  done
+fi
+
+if [ "$ALLOWED" = "1" ]; then
+  exit 0
+fi
+
+# BLOCK — multi-step branch without bundle:true
+WU_LIST=$(echo "$WU_TAGS" | tr '\n' ' ' | sed 's/ $//')
+
+cat >&2 <<EOF
+
+============================================
+🛑 ATOMIC-PR GATE — BLOCKED 🛑
+============================================
+
+Branch: $BRANCH
+Commits found tagged with multiple steps: $WU_LIST
+
+Per .claude/rules/pr-strategy.md, the default is one step per branch
+per PR (atomic). Multiple WUs in one branch defeats the rollback
+discipline — reverting one step also reverts the others.
+
+Three resolution paths:
+
+1. Split — create a separate branch per step and a PR for each.
+   Operator merges in dependency order.
+
+2. Bundle — if these WUs genuinely belong together (single concern,
+   tight coupling, emergency hotfix), declare it explicitly:
+   add 'bundle: true' to the iteration goal's frontmatter, then push.
+
+3. Override (rare) — SKIP_ATOMIC_PR_CHECK=1 git push ...
+   Logged to trace. Use only for genuine bypass cases.
+
+Per pr-strategy.md the bundle option requires one of:
+- Single logical concern across files (changes don't compile if split)
+- Tight coupling that breaks atomic /verify
+- Emergency hotfix
+- Explicit operator request
+
+Rule:  .claude/rules/pr-strategy.md
+Issue: bassclef#382
+============================================
+
+EOF
+
+exit 2

package/dist/lite/.claude/hooks/auto-save-idle.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# tier: lite
+# Auto-save idle checker — runs via cron on macOS + Linux + WSL (or Task Scheduler on native Windows) every 15 minutes.
+# Checks all watched repos for uncommitted changes and runs save-state.sh.
+#
+# Watched repos are listed below. Add new repos as they're created.
+
+# WATCHED_REPOS_OVERRIDE — colon-separated list for testing.
+# When unset, the production default applies (bassclef + poa).
+# See .claude/hooks/tests/auto-save-idle.test.sh for usage.
+if [ -n "${WATCHED_REPOS_OVERRIDE:-}" ]; then
+  IFS=':' read -ra WATCHED_REPOS <<< "$WATCHED_REPOS_OVERRIDE"
+else
+  WATCHED_REPOS=(
+    "$HOME/src/sunj-labs/bassclef"
+    "$HOME/src/sunj-labs/poa"
+  )
+fi
+
+for REPO in "${WATCHED_REPOS[@]}"; do
+  if [ ! -d "$REPO/.git" ]; then
+    continue
+  fi
+
+  cd "$REPO"
+
+  # Skip if an autonomous session is active — the agent owns commits
+  # during autonomous sessions. Auto-save checkpoints on feature branches
+  # cause merge conflicts when the agent rebases after squash merges.
+  if [ -f "$REPO/.claude/SESSION_LOCK" ]; then
+    echo "$(date): Skipping $REPO — SESSION_LOCK present (autonomous session active)"
+    continue
+  fi
+
+  # Check for uncommitted changes (excluding .DS_Store)
+  DIRTY=$(git status --porcelain 2>/dev/null | grep -v '\.DS_Store' | grep -v 'SESSION_LOCK' | grep -v 'LAST_SAVE' | head -5)
+  if [ -z "$DIRTY" ]; then
+    continue
+  fi
+
+  # Check if a save-state.sh exists in this repo
+  SAVE_SCRIPT="$REPO/.claude/hooks/save-state.sh"
+  if [ ! -x "$SAVE_SCRIPT" ]; then
+    continue
+  fi
+
+  # Run save-state quietly with --auto flag (refuses on feature/fix branches
+  # per bassclef#581 / WU-A4 — atomic-PR rule).
+  echo "$(date): Auto-saving $REPO ($( echo "$DIRTY" | wc -l | tr -d ' ') uncommitted files)"
+  cd "$REPO" && "$SAVE_SCRIPT" --quiet --auto 2>&1 || true
+done

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

@@ -186,14 +186,21 @@ _sync_install_hooks() {
   # 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 $installed hooks; skipped 0; failed 0"
+    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#, }"
-    echo "bassclef-sync: installed $installed hooks; skipped $skipped_total ($breakdown); failed $failed"
+    # RFC-0008 F7 — three bare numbers read three ways. Say what they mean
+    # together, and say plainly whether the install is usable.
+    if [ "$failed" = "0" ]; then
+      echo "bassclef-sync: $installed hooks ready. $skipped_total skipped on purpose ($breakdown). Nothing failed — your install is complete."
+    else
+      echo "bassclef-sync: $installed hooks ready. $skipped_total skipped on purpose ($breakdown)."
+      echo "bassclef-sync: $failed could not be installed. Those hooks will not fire until that is fixed."
+    fi
   fi
 }
 
@@ -249,17 +256,40 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ] && [ ! -d "$BASSCLEF_DIR/.git" ]; then
   # env-override fixture path; skip clone/pull
   :
 elif [ ! -d "$BASSCLEF_DIR/.claude" ]; then
-  if git clone "$BASSCLEF_REPO" "$BASSCLEF_DIR"; 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
-    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 ""
+    # 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
+
+    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
   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
@@ -407,10 +437,18 @@ sync_self_heal() {
   ok=$(echo "$diff" | jq -r '.ok')
   if [ "$ok" != "true" ]; then
     missing=$(echo "$diff" | jq -c '.missing')
-    echo "🛑 bassclef-sync postcondition FAILED — required wirings missing after self-heal:" >&2
-    echo "$missing" | jq -r '.[] | "  - " + .event + " → " + .command' >&2
-    echo "" >&2
-    echo "Resolve: edit ~/.claude/settings.json to include the missing wirings, then re-run bassclef-sync." >&2
+    # 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