@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/lib/hook-heartbeat.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# tier: lite
+# lib/hook-heartbeat.sh — hook liveness marker helper.
+#
+# Deep module per @luminary john-ousterhout. Two-function interface
+# hides the marker path convention, atomic write pattern, format
+# schema, directory creation, and silent-fail behavior.
+#
+# tier: upstream
+# install-class: dual
+#
+# Interface (what callers know):
+#   heartbeat_mark <hook-name>
+#     — call from any critical hook on entry; records fire timestamp
+#     — silent-fails; never crashes the caller
+#
+#   heartbeat_check <hook-name> <max-age-seconds>
+#     — returns 0 when marker exists AND is younger than max-age
+#     — returns 1 when marker exists AND is older than max-age (stale)
+#     — returns 2 when marker file does not exist
+#
+# Hidden (what the module encapsulates):
+#   - Marker path: state/markers/hook-heartbeat/<hook-name>.marker
+#     (overridable via HEARTBEAT_MARKER_DIR env var for test isolation)
+#   - Format: single-line ISO 8601 UTC timestamp (YYYY-MM-DDTHH:MM:SSZ)
+#   - Atomic write: temp file + mv (survives concurrent writes)
+#   - Directory creation: mkdir -p on first mark
+#   - Silent-fail: any I/O failure returns 0 from heartbeat_mark
+#
+# Consumers:
+#   - Critical hooks call heartbeat_mark on entry (WU-3 of bet 2026-07-31d)
+#   - Session-start reflection module calls heartbeat_check per hook
+#     against expected cadence from standards/hook-cadence.json
+#
+# Rules governed by:
+#   - .claude/rules/testing-tier-config.md (Tier 0 strict TDD; lib/*.sh)
+#   - .claude/rules/mechanism-fidelity.md (interface honored end to end)
+#   - .claude/rules/substrate-as-system.md (runtime cadence axis)
+#
+# Anchor luminaries:
+#   - @luminary john-ousterhout (deep module)
+#   - @luminary michael-nygard (heartbeat = steady-state pattern)
+#   - @luminary jerome-saltzer-and-michael-schroeder (complete mediation)
+#   - @luminary michael-feathers (characterization pins observed shape)
+
+# ---------------------------------------------------------------------------
+# Internal helpers (leading underscore per convention)
+# ---------------------------------------------------------------------------
+
+# Resolve the marker directory. Test isolation via HEARTBEAT_MARKER_DIR env.
+_heartbeat_dir() {
+  if [ -n "${HEARTBEAT_MARKER_DIR:-}" ]; then
+    printf '%s' "$HEARTBEAT_MARKER_DIR"
+    return 0
+  fi
+  # Default: <repo-root>/state/markers/hook-heartbeat
+  local repo_root
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+    repo_root="$CLAUDE_PROJECT_DIR"
+  else
+    # Fallback: walk up from this file
+    repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)"
+  fi
+  printf '%s' "$repo_root/state/markers/hook-heartbeat"
+}
+
+# ISO 8601 UTC timestamp. macOS + Linux compatible.
+_heartbeat_iso_now() {
+  date -u +%Y-%m-%dT%H:%M:%SZ
+}
+
+# Marker mtime (epoch seconds). Portable macOS + Linux.
+# GNU stat first (Linux default; `stat -f` on GNU means filesystem info,
+# NOT modification time — silently returns nonsense with exit 0). BSD
+# stat second (macOS). Fallback echoes 0 (treats as ancient).
+_heartbeat_mtime() {
+  local file="$1"
+  stat -c %Y "$file" 2>/dev/null || stat -f %m "$file" 2>/dev/null || echo 0
+}
+
+# ---------------------------------------------------------------------------
+# Public interface
+# ---------------------------------------------------------------------------
+
+# heartbeat_mark <hook-name>
+#
+# Records that <hook-name> fired. Writes an ISO 8601 UTC timestamp to
+# state/markers/hook-heartbeat/<hook-name>.marker via a temp-file-and-mv
+# atomic write. Silent-fails on any error so the caller never crashes.
+heartbeat_mark() {
+  local hook_name="${1:-}"
+  if [ -z "$hook_name" ]; then
+    return 0
+  fi
+
+  local dir marker tmp
+  dir="$(_heartbeat_dir)"
+  marker="$dir/${hook_name}.marker"
+
+  # Ensure directory exists. Silent-fail on any error.
+  mkdir -p "$dir" 2>/dev/null || return 0
+
+  # Atomic write via temp + mv. mktemp under the same dir so mv is atomic
+  # on the same filesystem. Silent-fail if mktemp cannot create the temp.
+  tmp="$(mktemp "${dir}/.${hook_name}.marker.XXXXXX" 2>/dev/null)" || return 0
+
+  # Write timestamp. If any of these fail, clean up + silent-fail.
+  if ! _heartbeat_iso_now > "$tmp" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null
+    return 0
+  fi
+
+  if ! mv "$tmp" "$marker" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null
+    return 0
+  fi
+
+  return 0
+}
+
+# heartbeat_check <hook-name> <max-age-seconds>
+#
+# Returns:
+#   0 — marker exists AND is younger than max-age (fresh)
+#   1 — marker exists AND is older than max-age (stale)
+#   2 — marker file does not exist (never fired, or purged)
+heartbeat_check() {
+  local hook_name="${1:-}"
+  local max_age="${2:-0}"
+  if [ -z "$hook_name" ]; then
+    return 2
+  fi
+
+  local dir marker
+  dir="$(_heartbeat_dir)"
+  marker="$dir/${hook_name}.marker"
+
+  if [ ! -f "$marker" ]; then
+    return 2
+  fi
+
+  local mtime now age
+  mtime="$(_heartbeat_mtime "$marker")"
+  now="$(date -u +%s)"
+  age=$((now - mtime))
+
+  if [ "$age" -le "$max_age" ]; then
+    return 0
+  fi
+
+  return 1
+}

package/dist/lite/lib/hook-inject.sh

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# lib/hook-inject.sh — shared helper for hooks that inject additionalContext
+# per standards/hook-injection-discipline.md and resolve project resources
+# per standards/hook-install-class.md.
+#
+# This library is SOURCED by hooks, not executed. It does not set -e/-u
+# globally (would affect callers); functions enforce their own contracts.
+#
+# Authority: ADR-035 (substrate-as-system + hooks-as-steering-surfaces)
+# Tier 0 strict TDD: lib/tests/hook-inject.test.sh
+# Anchors: @luminary john-ousterhout (deep modules) + @luminary michael-nygard
+# (fail-soft fallback chain) + @luminary tony-hoare (pre/post contracts)
+#
+# Exposed functions:
+#   emit_additional_context <event> <content>       # JSON envelope to stdout
+#   emit_base_pair_reminders                         # plain-English + assert-verify reminder text
+#   resolve_standards_path <filename>                # CLAUDE_PROJECT_DIR → env → HOME → fail
+#   resolve_config_path                              # same chain for bassclef-configs.jsonc
+#   extract_block_terms <jargon-file>                # BLOCK-tier rows from wordlist
+#
+# Env vars consumed:
+#   CLAUDE_PROJECT_DIR    — project root (Claude Code sets this)
+#   KISS_STANDARDS_FILE   — override for standards path resolution
+#   BASSCLEF_CONFIG_FILE  — override for config path resolution
+#   HOME_OVERRIDE         — test-only; replaces $HOME for fixture isolation
+#
+# Per standards/hook-injection-discipline.md:
+#   - additionalContext capped at 10,000 chars (Anthropic limit)
+#   - JSON envelope shape: {"hookSpecificOutput": {"hookEventName": "...", "additionalContext": "..."}}
+#   - Fail-soft: all resolution helpers return non-zero with structured stderr; never silently pass
+
+# === Constants ===
+HOOK_INJECT_MAX_CONTENT=10000
+
+# === Resolve $HOME with test-override support ===
+__hook_inject_home() {
+  echo "${HOME_OVERRIDE:-$HOME}"
+}
+
+# === emit_additional_context ===
+# Args:
+#   $1 — event name (e.g., UserPromptSubmit, Stop)
+#   $2 — content (the additionalContext string)
+# Stdout: JSON envelope per Anthropic's hookSpecificOutput shape
+# Exit: 0 success; 2 missing/invalid args
+emit_additional_context() {
+  local event="${1:-}"
+  local content="${2-}"  # NOT :- so explicit empty string is allowed (test case)
+
+  # Validate event arg
+  if [ -z "$event" ]; then
+    echo "emit_additional_context: missing event arg" >&2
+    echo "  Usage: emit_additional_context <event-name> <content>" >&2
+    return 2
+  fi
+
+  # Reject event names with spaces (Anthropic events are single tokens)
+  if echo "$event" | grep -q ' '; then
+    echo "emit_additional_context: invalid event name '$event' (spaces not allowed)" >&2
+    echo "  Anthropic hook events are single tokens like UserPromptSubmit, Stop, PostToolUse" >&2
+    return 2
+  fi
+
+  # Validate content arg presence (allow empty string but require the arg)
+  if [ $# -lt 2 ]; then
+    echo "emit_additional_context: missing content arg" >&2
+    echo "  Usage: emit_additional_context <event-name> <content>" >&2
+    return 2
+  fi
+
+  # Truncate if exceeds Anthropic 10K cap
+  local truncated=0
+  if [ ${#content} -gt $HOOK_INJECT_MAX_CONTENT ]; then
+    content="${content:0:$HOOK_INJECT_MAX_CONTENT}"
+    truncated=1
+  fi
+
+  # Emit JSON envelope via jq for proper escaping
+  if command -v jq >/dev/null 2>&1; then
+    jq -n \
+      --arg event "$event" \
+      --arg content "$content" \
+      '{hookSpecificOutput: {hookEventName: $event, additionalContext: $content}}'
+  else
+    # jq-missing fallback: emit minimally-escaped JSON
+    # (lib design assumes jq present per standards/bash-hook-safety.md;
+    # this fallback exists so a jq-missing system still produces parseable output)
+    local esc_event="${event//\"/\\\"}"
+    local esc_content="${content//\"/\\\"}"
+    esc_content="${esc_content//$'\n'/\\n}"
+    printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":"%s"}}\n' \
+      "$esc_event" "$esc_content"
+  fi
+
+  if [ $truncated -eq 1 ]; then
+    echo "emit_additional_context: content truncated to $HOOK_INJECT_MAX_CONTENT chars (Anthropic limit)" >&2
+  fi
+
+  return 0
+}
+
+# === emit_base_pair_reminders ===
+# Emits the shared base-pair reminder text for the 5 UserPromptExpansion
+# hooks per bet 2026-07-01e. Content covers both R8 cures:
+#   1. Plain-English discipline (per .claude/rules/operator-facing-prose.md)
+#   2. Assert-verify discipline (per .claude/rules/assert-only-after-verify.md)
+#
+# Callers prepend this to their skill-specific content, then pass the
+# combined string to emit_additional_context.
+#
+# Stdout: reminder text (no envelope; caller wraps)
+# Exit: 0 always
+emit_base_pair_reminders() {
+  cat <<'EOF'
+**Plain check:** Before I make a claim in this turn, I read the source first and cite it. If I cannot cite the source, I do not ship the claim.
+
+**Base-pair reminders — plain-English + assert-verify:**
+
+Plain-English (per .claude/rules/operator-facing-prose.md):
+- Grade-10 reading level. Subject-verb-object. Short sentences.
+- Drop bassclef-internal jargon (composer, primitive, load-bearing, blast radius, tier-preset, operationalize, wirings). See standards/bassclef-internal-jargon.md for the substitution table.
+- Keep standard tech vocab: API, hook, PR, schema, ORM.
+
+Assert-verify (per .claude/rules/assert-only-after-verify.md):
+- Every operator-facing assertion carries three parts: My claim + Evidence + Why the evidence supports the claim.
+- Evidence means the source read inline (file path, ticket #, git SHA).
+- Why the evidence supports the claim means one sentence tying the source to the claim.
+- Optional sharpeners: Qualifier (Toulmin), Rebuttal (Popper), Alternatives (Peirce).
+- If you cannot fill all three, do not ship the assertion. Read the source first.
+- Toulmin's original vocabulary (claim / data / warrant) stays as the research citation in .claude/luminaries/stephen-toulmin.md.
+EOF
+  return 0
+}
+
+# === resolve_standards_path ===
+# Resolves a standards/ file via project → env → user → fail fallback.
+# Args:
+#   $1 — relative filename under standards/ (e.g., "bassclef-internal-jargon.md")
+# Stdout: resolved absolute path
+# Exit: 0 success; 1 all layers fail; 2 missing arg
+resolve_standards_path() {
+  local filename="${1:-}"
+  if [ -z "$filename" ]; then
+    echo "resolve_standards_path: missing filename arg" >&2
+    return 2
+  fi
+
+  local project_dir="${CLAUDE_PROJECT_DIR:-}"
+  local env_override="${KISS_STANDARDS_FILE:-}"
+  local home_dir
+  home_dir="$(__hook_inject_home)"
+
+  # Layer 1: project
+  if [ -n "$project_dir" ] && [ -f "$project_dir/standards/$filename" ]; then
+    echo "$project_dir/standards/$filename"
+    return 0
+  fi
+
+  # Layer 2: env override (only if env file actually exists; otherwise fall through)
+  if [ -n "$env_override" ] && [ -f "$env_override" ]; then
+    echo "$env_override"
+    return 0
+  fi
+
+  # Layer 3: user-level
+  if [ -f "$home_dir/standards/$filename" ]; then
+    echo "$home_dir/standards/$filename"
+    return 0
+  fi
+
+  # All layers failed — structured stderr with the fallback chain attempted
+  cat >&2 <<EOF
+resolve_standards_path: '$filename' not found in any fallback layer
+  Layer 1 (project): ${project_dir:-<CLAUDE_PROJECT_DIR unset>}/standards/$filename
+  Layer 2 (env KISS_STANDARDS_FILE): ${env_override:-<unset>}
+  Layer 3 (user): $home_dir/standards/$filename
+  Per standards/hook-injection-discipline.md fail-soft contract.
+EOF
+  return 1
+}
+
+# === resolve_config_path ===
+# Resolves bassclef-configs.jsonc via project → env → user → fail.
+# Stdout: resolved absolute path
+# Exit: 0 success; 1 all layers fail
+resolve_config_path() {
+  local project_dir="${CLAUDE_PROJECT_DIR:-}"
+  local env_override="${BASSCLEF_CONFIG_FILE:-}"
+  local home_dir
+  home_dir="$(__hook_inject_home)"
+
+  # Layer 1: project
+  if [ -n "$project_dir" ] && [ -f "$project_dir/.claude/bassclef-configs.jsonc" ]; then
+    echo "$project_dir/.claude/bassclef-configs.jsonc"
+    return 0
+  fi
+
+  # Layer 2: env override
+  if [ -n "$env_override" ] && [ -f "$env_override" ]; then
+    echo "$env_override"
+    return 0
+  fi
+
+  # Layer 3: user-level
+  if [ -f "$home_dir/.claude/bassclef-configs.jsonc" ]; then
+    echo "$home_dir/.claude/bassclef-configs.jsonc"
+    return 0
+  fi
+
+  cat >&2 <<EOF
+resolve_config_path: bassclef-configs.jsonc not found in any fallback layer
+  Layer 1 (project): ${project_dir:-<CLAUDE_PROJECT_DIR unset>}/.claude/bassclef-configs.jsonc
+  Layer 2 (env BASSCLEF_CONFIG_FILE): ${env_override:-<unset>}
+  Layer 3 (user): $home_dir/.claude/bassclef-configs.jsonc
+  Per standards/hook-injection-discipline.md fail-soft contract.
+EOF
+  return 1
+}
+
+# === extract_block_terms ===
+# Parses a bassclef-internal-jargon.md style file + returns BLOCK-tier terms.
+# Args:
+#   $1 — path to the jargon file
+# Stdout: one term per line (BLOCK rows only)
+# Exit: 0 success (even if zero terms found); 1 file missing; 2 missing arg
+extract_block_terms() {
+  local file="${1:-}"
+  if [ -z "$file" ]; then
+    echo "extract_block_terms: missing file arg" >&2
+    return 2
+  fi
+  if [ ! -f "$file" ]; then
+    echo "extract_block_terms: file not found: $file" >&2
+    return 1
+  fi
+
+  # Parse markdown table rows: extract column 2 (term) where column 3 (tier) == BLOCK
+  # Format: | term | TIER | replacement |
+  awk -F'|' '
+    /BLOCK *\|/ {
+      # Get tier column (3rd field after split — col 1 is leading empty)
+      tier = $3
+      gsub(/^ +| +$/, "", tier)
+      if (tier == "BLOCK") {
+        term = $2
+        gsub(/^ +| +$/, "", term)
+        # Skip header rows (term column says "term" literally)
+        if (term != "term" && term != "") print term
+      }
+    }
+  ' "$file"
+  return 0
+}

package/dist/lite/lib/hook-installer.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+#
+# lib/hook-installer.sh — installs a hook file at its declared install-class scope
+#
+# @pattern patterns/code/gof/strategy.md
+# Picks route (operator | project | dual) by install-class value.
+#
+# @pattern patterns/code/ousterhout/deep-module.md
+# One function, one argument. Targets resolved inside the module.
+#
+# Contract (Hoare):
+# - Precondition: hook_path exists AND is readable AND declares
+#   one of operator|project|dual in its # install-class: header
+# - Postcondition (success): file present at every target the class names
+#   AND every source-graph dependent resolves AND trace logs the action
+# - Postcondition (failure): non-zero exit AND stderr names the missing target
+# - Silent-fail per ADR-050 R7: permission denied writes trace + exits 0
+#
+# Per docs/canvases/2026-09-15-install-class-dispatch.md
+# Per docs/use-cases/UC-lib-hook-installer.md
+
+set -euo pipefail
+
+# Resolve dependent lib scripts relative to this file
+_HOOK_INSTALLER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=/dev/null
+if [ -f "$_HOOK_INSTALLER_DIR/hook-header-parser.sh" ]; then
+  source "$_HOOK_INSTALLER_DIR/hook-header-parser.sh"
+fi
+# Source the real walker (replaces the stub defined below if present)
+# shellcheck source=/dev/null
+if [ -f "$_HOOK_INSTALLER_DIR/source-graph-walker.sh" ]; then
+  source "$_HOOK_INSTALLER_DIR/source-graph-walker.sh"
+fi
+
+# Trace log location — honors BASSCLEF_TRACE_LOG env override (used by tests)
+_hook_installer_trace_log() {
+  if [ -n "${BASSCLEF_TRACE_LOG:-}" ]; then
+    echo "$BASSCLEF_TRACE_LOG"
+  elif [ -n "${REPO_ROOT:-}" ]; then
+    echo "$REPO_ROOT/state/trace.log"
+  else
+    echo "/tmp/bassclef-hook-installer-trace.log"
+  fi
+}
+
+# Trace helper — best-effort append; falls back to stderr on file error
+_hook_installer_trace() {
+  local line="$*"
+  local log
+  log=$(_hook_installer_trace_log)
+  {
+    mkdir -p "$(dirname "$log")" 2>/dev/null || true
+    echo "$(date -u +'%Y-%m-%dT%H:%M:%SZ') $line" >> "$log"
+  } 2>/dev/null || echo "TRACE: $line" >&2
+}
+
+# Home target — honors HOME_OVERRIDE env (used by tests)
+_hook_installer_home() {
+  if [ -n "${HOME_OVERRIDE:-}" ]; then
+    echo "$HOME_OVERRIDE"
+  else
+    echo "$HOME"
+  fi
+}
+
+# Content-hash compare — sha256sum works on both macOS + Linux via shasum
+_hook_installer_content_hash() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" | awk '{print $1}'
+  else
+    # Fallback — content diff via cmp
+    echo "no-hash-tool"
+  fi
+}
+
+# Copy hook_file to target_dir; idempotent on content-hash match
+# Silent-fail on permission denied per ADR-050 R7
+_hook_installer_copy() {
+  local hook_file="$1"
+  local target_dir="$2"
+  local target_file
+  target_file="$target_dir/$(basename "$hook_file")"
+
+  # Create target dir — silent-fail if permission denied
+  if ! mkdir -p "$target_dir" 2>/dev/null; then
+    _hook_installer_trace "silent-fail permission-denied create $target_dir"
+    return 0
+  fi
+
+  # Check write permission on target dir
+  if [ ! -w "$target_dir" ]; then
+    _hook_installer_trace "silent-fail permission-denied write $target_dir"
+    return 0
+  fi
+
+  # Idempotency — skip when content-hash matches
+  if [ -f "$target_file" ]; then
+    local src_hash tgt_hash
+    src_hash=$(_hook_installer_content_hash "$hook_file")
+    tgt_hash=$(_hook_installer_content_hash "$target_file")
+    if [ "$src_hash" = "$tgt_hash" ] && [ "$src_hash" != "no-hash-tool" ]; then
+      _hook_installer_trace "no-op idempotent $hook_file -> $target_file"
+      return 0
+    fi
+  fi
+
+  # Copy — silent-fail on permission denied; -p preserves mode (executable bit)
+  if cp -p "$hook_file" "$target_file" 2>/dev/null; then
+    _hook_installer_trace "install $hook_file -> $target_file"
+    return 0
+  else
+    _hook_installer_trace "silent-fail permission-denied copy $hook_file -> $target_file"
+    return 0
+  fi
+}
+
+# walk_source_dependents comes from lib/source-graph-walker.sh sourced at
+# L34-37. The naive fallback that lived here through v0.41.1 retired at
+# goal 2026-09-14c Step 5.0 per #1663 + ADR-058 c5 — one walker, one
+# implementation. If source-graph-walker.sh is missing (misconfigured
+# install), install_by_class will exit 1 at the walker check line below
+# with the resolved-to-nothing error path — better than a silent fallback
+# that scans differently from the real walker.
+
+# install_by_class(hook_path) → 0 on success, non-zero on failure
+install_by_class() {
+  local hook_path="$1"
+
+  # Precondition: hook_path exists
+  if [ ! -f "$hook_path" ]; then
+    echo "install_by_class: hook_path not found: $hook_path" >&2
+    _hook_installer_trace "error hook-not-found $hook_path"
+    return 1
+  fi
+
+  # Parse install-class header
+  local install_class
+  install_class=$(parse_install_class "$hook_path" 2>/dev/null || true)
+
+  if [ -z "$install_class" ]; then
+    echo "install_by_class: missing or malformed # install-class: header in $hook_path" >&2
+    _hook_installer_trace "error missing-header $hook_path"
+    return 1
+  fi
+
+  # Walker check — Step 4 will extract real walker
+  local missing_deps
+  missing_deps=$(walk_source_dependents "$hook_path" 2>/dev/null || true)
+  if [ -n "$missing_deps" ]; then
+    echo "install_by_class: missing dependent(s) for $hook_path:" >&2
+    echo "$missing_deps" >&2
+    _hook_installer_trace "error missing-deps $hook_path"
+    return 1
+  fi
+
+  # Resolve targets — install to $HOME and/or $CLAUDE_PROJECT_DIR based on class
+  local home_target project_target
+  home_target="$(_hook_installer_home)/.claude/hooks"
+
+  # Project target — CLAUDE_PROJECT_DIR must be set for project + dual
+  if [ "$install_class" = "project" ] || [ "$install_class" = "dual" ]; then
+    if [ -z "${CLAUDE_PROJECT_DIR:-}" ]; then
+      echo "install_by_class: CLAUDE_PROJECT_DIR unset — cannot install $install_class hook $hook_path" >&2
+      _hook_installer_trace "error CLAUDE_PROJECT_DIR-unset $hook_path"
+      return 1
+    fi
+    project_target="$CLAUDE_PROJECT_DIR/.claude/hooks"
+  fi
+
+  # Dispatch — copy to declared target(s)
+  case "$install_class" in
+    operator)
+      _hook_installer_copy "$hook_path" "$home_target"
+      ;;
+    project)
+      _hook_installer_copy "$hook_path" "$project_target"
+      ;;
+    dual)
+      _hook_installer_copy "$hook_path" "$home_target"
+      _hook_installer_copy "$hook_path" "$project_target"
+      ;;
+  esac
+
+  return 0
+}
+
+# Export for callers that source this file
+export -f install_by_class 2>/dev/null || true
+export -f walk_source_dependents 2>/dev/null || true

package/dist/lite/lib/luminary-pick.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# tier: lite
+# andon-allow: docs/operator-private/[a-z-]+/20[0-9][0-9]-[0-9]{2}
+#
+# lib/luminary-pick.sh — bassclef catalog helper for the in-turn luminary picker.
+#
+# Shape A per docs/decompositions/2026-09-03-picker-harness-llm.md.
+# Consult at docs/operator-private/consultations/2026-09-03-picker-shape.md
+# picked Shape A 5-0 (Cooper, Linus, Ousterhout, Nygard, Feathers).
+#
+# The pick itself lives in each caller SKILL body:
+#   .claude/skills/pick-luminaries/SKILL.md
+#   .claude/skills/launch/SKILL.md
+#   .claude/skills/stage/SKILL.md
+#
+# Claude reads the catalog list from luminary_pick_catalog() below,
+# reasons over the intent inside the current turn, writes the JSON.
+# No shell-out. No separate API key required.
+#
+# This lib provides:
+#   - luminary_pick_catalog() — read catalog dir; emit sorted slug list
+#   - luminary_pick() — grace-window stub preserving signature through
+#                       2026-10-31 per ADR-031 we-dont-break-adopters
+#   - luminary_pick_status() — mode report for adopter debugging
+#
+# Usage from a caller SKILL body:
+#
+#   source "${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}/lib/luminary-pick.sh"
+#   CATALOG=$(luminary_pick_catalog)
+#   # then Claude reasons over $CATALOG + intent, writes JSON in-turn
+#
+# Output JSON shape (produced by SKILL body prose, not by this lib):
+#   {
+#     "matched_luminaries": ["slug1", "slug2", ...],
+#     "rationale": "One short sentence per pick",
+#     "picker_version": "bassclef-harness-pick-2.0",
+#     "provider": "claude-code-harness"
+#   }
+
+set -euo pipefail
+
+# Read catalog dir and emit one line per luminary.
+# Format: "<slug> (<domain>) — <name>"
+# Sort: alphabetical by slug.
+# Return: 0 on success (including empty catalog); non-zero if dir missing.
+luminary_pick_catalog() {
+  local basedir="${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}"
+  local catalog_dir="${basedir}/state/luminary-implementations"
+
+  if [ ! -d "$catalog_dir" ]; then
+    echo "[luminary-pick-catalog] catalog dir missing: $catalog_dir" >&2
+    return 2
+  fi
+
+  (
+    shopt -s nullglob
+    set +e
+    for f in "$catalog_dir"/*.json; do
+      jq -r '"\(.luminary_slug) (\(.primary_domain // "unknown")) — \(.name // .luminary_slug)"' "$f" 2>/dev/null || true
+    done | sort -u
+  )
+  return 0
+}
+
+# Grace-window stub preserving the old function signature.
+# Adopter scripts that source this lib and call luminary_pick continue
+# to run. They see a stderr note pointing at the new home. Exit 0 so
+# scripts checking exit code do not error.
+# Retires 2026-10-31 per ADR-031.
+luminary_pick() {
+  echo "[luminary-pick] moved to caller SKILL body prose per web#193." >&2
+  echo "[luminary-pick] adopters: see .claude/skills/pick-luminaries/SKILL.md" >&2
+  echo "[luminary-pick] grace-window stub retires 2026-10-31 per ADR-031." >&2
+  return 0
+}
+
+# Report picker mode. Kept for adopter debugging.
+luminary_pick_status() {
+  echo "LIVE — in-turn picker per SKILL body prose (Shape A, web#193)"
+  return 0
+}
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  case "${1:-}" in
+    catalog) luminary_pick_catalog ;;
+    status)  luminary_pick_status ;;
+    *)
+      echo "Usage: $0 catalog    # emit luminary catalog list"
+      echo "       $0 status     # report picker mode"
+      echo ""
+      echo "The pick itself moved to caller SKILL body prose per web#193."
+      echo "See .claude/skills/pick-luminaries/SKILL.md."
+      exit 0
+      ;;
+  esac
+fi