@thebassclef/lite 1.0.2 → 1.0.4

package/dist/cli.cjs

@@ -548,8 +548,11 @@ function copySubstrate(targetDir, options = {}) {
   for (const [directory, groupFiles] of groups) {
     let completedInGroup = 0;
     for (const relPath of groupFiles) {
-      const outcome = copyOne(relPath, bundleRoot, targetDir, options, result, scopeMap);
-      if (outcome !== "skipped") completedInGroup += 1;
+      const decisions = decisionsForFile(relPath, scopeMap, targetDir, options);
+      for (const decision of decisions) {
+        const outcome = copyOne(relPath, bundleRoot, options, result, decision);
+        if (outcome !== "skipped") completedInGroup += 1;
+      }
     }
     if (options.onProgress) options.onProgress(directory, completedInGroup);
   }
@@ -656,12 +659,30 @@ function buildScopeMap(bundleRoot, targetDir, options, bundleHookRelPaths) {
 function isHookFile(relPath) {
   return relPath.startsWith(HOOKS_SUBPATH) && relPath.endsWith(".sh");
 }
-function copyOne(relPath, bundleRoot, targetDir, options, result, scopeMap) {
+function decisionsForFile(relPath, scopeMap, targetDir, options) {
+  if (!isHookFile(relPath)) {
+    return [{ scope: "project", targetPath: node_path.join(targetDir, mapAdopterPath(relPath)) }];
+  }
+  const declared = scopeMap.get(relPath);
+  if (declared) {
+    return [declared];
+  }
+  const allowRoot = options.allowRoot ?? false;
+  const userDecision = classify$1(
+    { command: `$HOME/${relPath}` },
+    { targetDir, allowRoot }
+  );
+  const projectDecision = classify$1(
+    { command: `$CLAUDE_PROJECT_DIR/${relPath}` },
+    { targetDir, allowRoot }
+  );
+  return [userDecision, projectDecision];
+}
+function copyOne(relPath, bundleRoot, options, result, scopeDecision) {
   const sourcePath = node_path.join(bundleRoot, relPath);
   const adopterRelPath = mapAdopterPath(relPath);
-  const scopeDecision = isHookFile(relPath) ? scopeMap.get(relPath) : void 0;
-  const targetPath = scopeDecision ? scopeDecision.targetPath : node_path.join(targetDir, adopterRelPath);
-  const scope = scopeDecision ? scopeDecision.scope : "project";
+  const targetPath = scopeDecision.targetPath;
+  const scope = scopeDecision.scope;
   let content;
   try {
     content = node_fs.readFileSync(sourcePath, "utf8");
@@ -919,8 +940,11 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, jso
     `bassclef init: ${grandTotal} files total (1 config + ${result.copied.length} substrate).
 `
   );
+  const declaredCommandLeaves = readDeclaredCommandLeaves(
+    node_path.join(targetDir, ".claude", "settings.json")
+  );
   const copiedHookEntries = result.copiedEntries.filter(
-    (e) => e.path.startsWith(HOOKS_SUBPATH) && e.path.endsWith(".sh")
+    (e) => e.path.startsWith(HOOKS_SUBPATH) && e.path.endsWith(".sh") && declaredCommandLeaves.has(node_path.basename(e.path))
   );
   const copiedCount = copiedHookEntries.length;
   const declaredCount = result.hookCount;
@@ -1148,6 +1172,26 @@ function usage$2() {
     ""
   ].join("\n");
 }
+function readDeclaredCommandLeaves(settingsPath) {
+  try {
+    const parsed = JSON.parse(node_fs.readFileSync(settingsPath, "utf8"));
+    const leaves = /* @__PURE__ */ new Set();
+    for (const matcherBlocks of Object.values(parsed.hooks ?? {})) {
+      for (const block of matcherBlocks) {
+        for (const entry of block.hooks ?? []) {
+          const cmd = entry.command;
+          if (typeof cmd !== "string" || cmd.length === 0) continue;
+          if (!cmd.startsWith("$")) continue;
+          const leaf = cmd.slice(cmd.lastIndexOf("/") + 1);
+          if (leaf.endsWith(".sh")) leaves.add(leaf);
+        }
+      }
+    }
+    return leaves;
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
 const DEFAULTS$1 = {
   force: false,
   replaceEdits: false,

package/dist/cli.js

@@ -525,8 +525,11 @@ function copySubstrate(targetDir, options = {}) {
   for (const [directory, groupFiles] of groups) {
     let completedInGroup = 0;
     for (const relPath of groupFiles) {
-      const outcome = copyOne(relPath, bundleRoot, targetDir, options, result, scopeMap);
-      if (outcome !== "skipped") completedInGroup += 1;
+      const decisions = decisionsForFile(relPath, scopeMap, targetDir, options);
+      for (const decision of decisions) {
+        const outcome = copyOne(relPath, bundleRoot, options, result, decision);
+        if (outcome !== "skipped") completedInGroup += 1;
+      }
     }
     if (options.onProgress) options.onProgress(directory, completedInGroup);
   }
@@ -633,12 +636,30 @@ function buildScopeMap(bundleRoot, targetDir, options, bundleHookRelPaths) {
 function isHookFile(relPath) {
   return relPath.startsWith(HOOKS_SUBPATH) && relPath.endsWith(".sh");
 }
-function copyOne(relPath, bundleRoot, targetDir, options, result, scopeMap) {
+function decisionsForFile(relPath, scopeMap, targetDir, options) {
+  if (!isHookFile(relPath)) {
+    return [{ scope: "project", targetPath: join(targetDir, mapAdopterPath(relPath)) }];
+  }
+  const declared = scopeMap.get(relPath);
+  if (declared) {
+    return [declared];
+  }
+  const allowRoot = options.allowRoot ?? false;
+  const userDecision = classify$1(
+    { command: `$HOME/${relPath}` },
+    { targetDir, allowRoot }
+  );
+  const projectDecision = classify$1(
+    { command: `$CLAUDE_PROJECT_DIR/${relPath}` },
+    { targetDir, allowRoot }
+  );
+  return [userDecision, projectDecision];
+}
+function copyOne(relPath, bundleRoot, options, result, scopeDecision) {
   const sourcePath = join(bundleRoot, relPath);
   const adopterRelPath = mapAdopterPath(relPath);
-  const scopeDecision = isHookFile(relPath) ? scopeMap.get(relPath) : void 0;
-  const targetPath = scopeDecision ? scopeDecision.targetPath : join(targetDir, adopterRelPath);
-  const scope = scopeDecision ? scopeDecision.scope : "project";
+  const targetPath = scopeDecision.targetPath;
+  const scope = scopeDecision.scope;
   let content;
   try {
     content = readFileSync(sourcePath, "utf8");
@@ -896,8 +917,11 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, jso
     `bassclef init: ${grandTotal} files total (1 config + ${result.copied.length} substrate).
 `
   );
+  const declaredCommandLeaves = readDeclaredCommandLeaves(
+    join(targetDir, ".claude", "settings.json")
+  );
   const copiedHookEntries = result.copiedEntries.filter(
-    (e) => e.path.startsWith(HOOKS_SUBPATH) && e.path.endsWith(".sh")
+    (e) => e.path.startsWith(HOOKS_SUBPATH) && e.path.endsWith(".sh") && declaredCommandLeaves.has(basename$1(e.path))
   );
   const copiedCount = copiedHookEntries.length;
   const declaredCount = result.hookCount;
@@ -1125,6 +1149,26 @@ function usage$2() {
     ""
   ].join("\n");
 }
+function readDeclaredCommandLeaves(settingsPath) {
+  try {
+    const parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+    const leaves = /* @__PURE__ */ new Set();
+    for (const matcherBlocks of Object.values(parsed.hooks ?? {})) {
+      for (const block of matcherBlocks) {
+        for (const entry of block.hooks ?? []) {
+          const cmd = entry.command;
+          if (typeof cmd !== "string" || cmd.length === 0) continue;
+          if (!cmd.startsWith("$")) continue;
+          const leaf = cmd.slice(cmd.lastIndexOf("/") + 1);
+          if (leaf.endsWith(".sh")) leaves.add(leaf);
+        }
+      }
+    }
+    return leaves;
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
 const DEFAULTS$1 = {
   force: false,
   replaceEdits: false,

package/dist/index.cjs

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const version = "1.0.2";
+const version = "1.0.4";
 exports.version = version;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.0.2";
+const version = "1.0.4";
 export {
   version
 };

package/dist/lite/.claude/hooks/session-reflection.d/00-bassclef-hook-connect.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# tier: lite
+# 00-bassclef-hook-connect.sh — Auto-connect bassclef hooks to adopter settings.json.
+#
+# Closes sunj-labs/bassclef-upstream#644 — sync-cure peer path fix.
+#
+# Runs at every session-start via the session-reflection dispatcher.
+# Sources presence/install/bassclef-hook-connect.sh (shared function)
+# and calls bassclef_hook_connect_apply. Fires regardless of which sync
+# path (peer, clone, npm, curl) delivered bassclef to the adopter.
+#
+# Sorts BEFORE 08-settings-drift.sh in the dispatcher's lexicographic
+# scan (session-reflection.sh L135), so hooks are merged before drift
+# is reported. First POA session after release shows 0 missing entries.
+#
+# SOURCED (not exec'd) by session-reflection.sh — uses `return 0` NOT
+# `exit 0` so a skip path does not kill sister fragments. The tail
+# `|| true` on `return` is the standard sourced-fragment idiom (from
+# 08-settings-drift.sh) — lets the file also work when bash-invoked
+# directly (in tests) where `return` at top level is an error.
+#
+# Anchor luminaries — @luminary michael-nygard (steady state — merge
+# self-heals per session-start), @luminary alistair-cockburn (walking
+# skeleton — thinnest end-to-end path), @luminary john-ousterhout
+# (signal visibility — every merge run emits stderr line), @luminary
+# michael-feathers (characterization test with fixture parent path
+# OUTSIDE ~/src/sunj-labs/ closes the specific hole).
+#
+# Bootstrap pair — this fragment closes the peer-path gap. Sister:
+# presence/install/bassclef-sync.template.sh:682 retains the clone-path
+# call as belt + suspenders.
+
+# BASSCLEF_DIR is set by the parent dispatcher (session-reflection.sh L33)
+# when this fragment is sourced. CWD is set by the parent dispatcher
+# (session-reflection.sh L14). When executed directly (bash <fragment>),
+# env vars come from the caller.
+
+if [ -z "${BASSCLEF_DIR:-}" ]; then
+  # No bassclef root resolved. Fragment cannot run. Silent skip.
+  return 0 2>/dev/null || exit 0
+fi
+
+# Ousterhout signal-visibility — emit one stderr line per session-start
+# whenever BASSCLEF_DIR is set, before any conditional skip. Silent
+# success is as dangerous as silent failure.
+echo "[bassclef-hook-connect] session-reflection.d: attempting merge for CWD=${CWD:-$PWD}" >&2
+
+__bhc_lib="${BASSCLEF_DIR}/presence/install/bassclef-hook-connect.sh"
+if [ ! -f "$__bhc_lib" ]; then
+  echo "[bassclef-hook-connect] skip — shared function not found at $__bhc_lib" >&2
+  unset __bhc_lib
+  return 0 2>/dev/null || exit 0
+fi
+
+# Source the shared function (defines bassclef_hook_connect_apply).
+# shellcheck disable=SC1090
+source "$__bhc_lib"
+
+# Apply the merge. Never break the dispatcher — return 0 on all paths.
+bassclef_hook_connect_apply "${CWD:-$PWD}" "$BASSCLEF_DIR" || true
+
+unset __bhc_lib
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/05-active-bet.sh

@@ -0,0 +1,113 @@
+# tier: lite
+# install-class: dual
+# 05-active-bet.sh — Surface in_flight_bet from whereami at SessionStart
+#
+# Per architecture/audits/2026-06-30-session-orientation-blind-spot.md cure 1
+# (sister cures: 55-orientation-gate.sh fires on main + /longrun SKILL Step 0.4).
+#
+# The audit's root cause was the agent narrowing scope to "bet 29e wrap" from
+# a stale branch name. Whereami had `in_flight_bet: bet 30a` and the recent
+# commits named bet 30a, but the agent did not read either. This hook puts
+# the in_flight_bet at the TOP of the SessionStart output so the agent sees
+# it before any subsequent reasoning.
+#
+# Behavior:
+#   - Fires at SessionStart in every repo with .claude/ wired
+#   - Reads docs/whereami.md from CWD (the project's whereami, not $HOME)
+#   - When in_flight_bet block present: emits "### ACTIVE BET" header + slug + status + remaining_wus + goal doc pointer + cure source citation
+#   - When in_flight_bet absent: emits "### ACTIVE BET — no in-flight bet" one-line note
+#   - When whereami absent: emits "### ACTIVE BET — no in-flight bet (whereami absent)" one-line note
+#   - Always exit 0 (informational; SessionStart hooks do not block)
+#   - SKIP_ACTIVE_BET=1 silences output entirely
+#
+# Override (logged):
+#   SKIP_ACTIVE_BET=1 <command>
+#
+# Closes 1 of 5 sub-cures under sunj-labs/bassclef-upstream#540.
+
+# Override path — silent, log via trace-helper if present
+if [ "${SKIP_ACTIVE_BET:-0}" = "1" ]; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "active-bet" "skipped via SKIP_ACTIVE_BET=1" 2>/dev/null || true
+  fi
+  return 0 2>/dev/null || exit 0
+fi
+
+# Resolve whereami path. The hook reads from the project's whereami, not
+# from $HOME or the operator-install location. Per criterion 11 (path
+# resolution under both install classes): CWD/docs/whereami.md works under
+# both project install (CLAUDE_PROJECT_DIR=CWD) and operator install
+# (HOME=/some/other; CWD=project root).
+WHEREAMI="docs/whereami.md"
+
+# Silent-but-print one-liner when whereami absent
+if [ ! -f "$WHEREAMI" ]; then
+  echo ""
+  echo "### ACTIVE BET — no in-flight bet (whereami absent)"
+  echo ""
+  return 0 2>/dev/null || exit 0
+fi
+
+# Extract the in_flight_bet block. Whereami uses Shape B markdown YAML
+# frontmatter. The in_flight_bet block looks like:
+#
+#   in_flight_bet:
+#     bet: docs/iteration-bets/<slug>.md
+#     status: <status>
+#     remaining_wus: [<list>]
+#
+# awk extracts lines from `in_flight_bet:` until the next top-level key
+# (a line starting with a non-space character that ends in `:`).
+BLOCK=$(awk '
+  /^in_flight_bet:/ { in_block=1; next }
+  in_block && /^[a-zA-Z][^:]*:/ { in_block=0 }
+  in_block { print }
+' "$WHEREAMI" 2>/dev/null)
+
+# When block is empty, the field is absent
+if [ -z "$BLOCK" ]; then
+  echo ""
+  echo "### ACTIVE BET — no in-flight bet"
+  echo ""
+  echo "Whereami present but no in_flight_bet field. If you expect one, check"
+  echo "  docs/whereami.md for the in_flight_bet: block."
+  echo ""
+  return 0 2>/dev/null || exit 0
+fi
+
+# Extract goal slug: the goal. line under in_flight_bet, then strip path + .md
+BET_PATH=$(echo "$BLOCK" | grep -E "^[[:space:]]+bet:" | head -1 | sed -E 's/^[[:space:]]+bet:[[:space:]]*//')
+BET_SLUG=$(echo "$BET_PATH" | sed -E 's|^.*/||; s|\.md$||')
+
+# Extract status: best-effort, may carry parenthetical suffix
+STATUS=$(echo "$BLOCK" | grep -E "^[[:space:]]+status:" | head -1 | sed -E 's/^[[:space:]]+status:[[:space:]]*//')
+
+# Extract remaining_wus: best-effort, the bracketed list
+REMAINING=$(echo "$BLOCK" | grep -E "^[[:space:]]+remaining_wus:" | head -1 | sed -E 's/^[[:space:]]+remaining_wus:[[:space:]]*//')
+
+# Emit the ACTIVE BET block — header + tagline + fields + cure source
+echo ""
+echo "### ACTIVE BET — read before scoping work"
+echo ""
+if [ -n "$BET_SLUG" ]; then
+  echo "  bet: ${BET_SLUG}"
+fi
+if [ -n "$STATUS" ]; then
+  echo "  status: ${STATUS}"
+fi
+if [ -n "$REMAINING" ]; then
+  echo "  remaining_wus: ${REMAINING}"
+fi
+if [ -n "$BET_PATH" ]; then
+  echo ""
+  echo "  Read the goal doc before picking scope:"
+  echo "    ${BET_PATH}"
+fi
+echo ""
+echo "  Cure source: architecture/audits/2026-06-30-session-orientation-blind-spot.md"
+echo "  Sister cures: 55-orientation-gate.sh fires on main + /longrun SKILL Step 0.4"
+echo "  Closes 1 of 5 sub-cures under sunj-labs/bassclef-upstream#540."
+echo ""
+echo "Override (logged): SKIP_ACTIVE_BET=1"
+echo ""
+return 0 2>/dev/null || exit 0

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

@@ -0,0 +1,62 @@
+# tier: lite
+# Drift detector — fires at every SessionStart via session-reflection.sh.
+# Compares required wirings (per project settings.json) against loaded
+# wirings (per scope-stack-merged settings). Emits BLOCKED banner if drift.
+#
+# Closes the bug class diagnosed 2026-06-24: substrate ships new wiring,
+# operator's user-scope settings.json never picks it up, session-reflection.d/*
+# modules silently never fire.
+#
+# Sourced (not exec'd) by session-reflection.sh. Inherits:
+#   - blocked_banner() function
+#   - trace_log() function (via trace-helper.sh sourced in parent)
+#   - BASSCLEF_DIR environment variable
+#
+# Per .claude/rules/blocked-items.md: BLOCKED items must be resolved
+# or explicitly deferred. Per .claude/rules/defensive-bash.md: trace
+# logging at every exit; quote variables; local in functions.
+# Per docs/decompositions/2026-06-24-adopter-update-distribution.md.
+# WU-2 of bet 2026-06-24a-settings-hardening (#313).
+
+# Override path — operator can bypass per-session.
+if [ "${SKIP_SETTINGS_DRIFT:-0}" = "1" ]; then
+  trace_log "skip" "settings-drift" "SKIP_SETTINGS_DRIFT=1" 2>/dev/null || true
+  return 0 2>/dev/null || true
+fi
+
+# Source the shared wirings accessor (per decomposition § Interface Registry).
+__sd_wirings_lib="${BASSCLEF_DIR:-${PWD}}/.claude/hooks/_lib/wirings.sh"
+if [ ! -f "$__sd_wirings_lib" ]; then
+  # Substrate not fully synced; sister modules surface the larger issue.
+  trace_log "skip" "settings-drift" "wirings lib not yet synced" 2>/dev/null || true
+  unset __sd_wirings_lib
+  return 0 2>/dev/null || true
+fi
+# shellcheck source=/dev/null
+source "$__sd_wirings_lib"
+
+__sd_project_settings="${BASSCLEF_DIR:-${PWD}}/.claude/settings.json"
+
+__sd_required=$(read_required_wirings "$__sd_project_settings")
+__sd_loaded=$(read_loaded_wirings)
+__sd_diff=$(compare_wirings "$__sd_required" "$__sd_loaded")
+__sd_ok=$(echo "$__sd_diff" | jq -r '.ok')
+
+if [ "$__sd_ok" = "true" ]; then
+  trace_log "ok" "settings-drift" "no drift" 2>/dev/null || true
+else
+  __sd_missing_count=$(echo "$__sd_diff" | jq '.missing | length')
+  __sd_missing_list=$(echo "$__sd_diff" | jq -r '.missing[] | "  - " + .event + " → " + .command')
+  blocked_banner "settings-drift — ${__sd_missing_count} required hook wiring(s) missing from harness-loaded settings:
+
+${__sd_missing_list}
+
+Root cause class: substrate ships new wiring; operator's settings.json never picked it up.
+Resolve: bassclef-sync.sh self-heal will additively merge on next session-start once it ships (#313 WU-3). For now, run manually: bash ~/.claude/hooks/bassclef-sync.sh
+Override: SKIP_SETTINGS_DRIFT=1 (one-off bypass; logged to trace)"
+  trace_log "blocked" "settings-drift" "missing=${__sd_missing_count}" 2>/dev/null || true
+  unset __sd_missing_count __sd_missing_list
+fi
+
+unset __sd_wirings_lib __sd_project_settings __sd_required __sd_loaded __sd_diff __sd_ok
+return 0 2>/dev/null || true

package/dist/lite/.claude/hooks/session-reflection.d/10-abrupt-stop-recovery.sh

@@ -0,0 +1,78 @@
+# tier: lite
+# Abrupt-stop detection: dirty working tree indicates the previous
+# session-end protocol was skipped. Surface for recovery.
+#
+# bassclef#888 fix (Phase B WU-B2): filter routine bookkeeping marker
+# writes that happen every session-start. Without this filter, the
+# session-timing marker bumped at every boot surfaces as a false
+# "abrupt stop" gate, training operators + future Claude sessions to
+# disregard the banner as noise.
+#
+# bassclef-web#103 fix: extend allowlist to cover two more false-positive
+# classes surfaced by adopter sessions:
+#   Class A — .playwright-mcp/ transient exhaust from Playwright MCP browser
+#             sessions (visual-review, visual-qa, synthetic-user skills)
+#   Class C — docs/deferred-actions/*-session-rescue.md files that the
+#             session-end hook writes on abrupt stop; the detector then
+#             sees them as untracked and fires the banner about itself
+#
+# Class B (sync-lag on new substrate primitives landing before .gitignore
+# settles) is DEFERRED to a follow-on ticket — that class needs a
+# sync-complete marker sequenced from bassclef-sync, wider scope than
+# this cure.
+#
+# Allowlisted path prefixes (substrate runtime bookkeeping that's
+# expected to be dirty at session-start):
+#   state/markers/session-timing/    — bumped by session-timing hook
+#   state/markers/edit-count/        — budget-tracking, auto-written
+#   state/markers/verify/            — /verify writes
+#   state/markers/temperance/        — /temperance writes
+#   state/markers/diagnose/          — /diagnose writes
+#   state/markers/compliance-history/ — gate-compliance counter writes
+#   .playwright-mcp/                  — Playwright MCP transient (Class A)
+#   docs/deferred-actions/*-session-rescue.md — rescue files (Class C)
+#
+# Real work (src/, docs/ outside the rescue pattern, .claude/, etc.)
+# still surfaces the banner. Non-rescue deferred-action files (e.g.,
+# journal-backfill, wiki-refresh) still fire the banner.
+
+# -uall expands untracked-directory summaries to individual file paths
+# so the per-file allowlist match below can recognize each path.
+# Without -uall, a new file inside a previously empty marker dir would
+# appear as "?? state/" (dir summary), bypassing the allowlist filter.
+DIRTY_TREE_RAW=$(git status --porcelain -uall 2>/dev/null)
+
+# Strip the 3-char porcelain status prefix (XY + space) before matching
+# path prefixes, then re-emit the original line so the user sees the
+# git-status-shaped output if banner fires.
+DIRTY_TREE=$(echo "$DIRTY_TREE_RAW" | awk '
+{
+  path = substr($0, 4)
+  # Class 0 (bassclef#888): substrate runtime bookkeeping markers
+  if (path ~ /^state\/markers\/(session-timing|edit-count|verify|temperance|diagnose|compliance-history)\//) {
+    next
+  }
+  # Class A (bassclef-web#103): Playwright MCP transient exhaust
+  if (path ~ /^\.playwright-mcp\//) {
+    next
+  }
+  # Class C (bassclef-web#103): session-rescue files written by session-end.sh
+  if (path ~ /^docs\/deferred-actions\/.*-session-rescue\.md$/) {
+    next
+  }
+  print
+}' | head -5)
+
+if [ -n "$DIRTY_TREE" ]; then
+  echo "### ABRUPT STOP DETECTED — RECOVERY NEEDED"
+  echo ""
+  echo "Uncommitted changes found:"
+  echo "$DIRTY_TREE"
+  echo ""
+  echo "→ Ask the user: commit these, stash, or discard?"
+  echo ""
+  echo "Session-end protocol was likely skipped. Check:"
+  echo "- Are any issues stuck in 'In Progress' that should be Done?"
+  echo "- Was memory saved from the last session?"
+  echo ""
+fi

package/dist/lite/.claude/hooks/session-reflection.d/12-session-lock.sh

@@ -0,0 +1,63 @@
+# tier: lite
+# SESSION_LOCK presence: surface to operator + future agents that
+# auto-save is suppressed and another session may be active. Without
+# this signal, the next session opens, sees "up-to-date," removes the
+# lock thinking it's stale → auto-save resumes silently → atomic-PR
+# bypass returns. Per bassclef#582 (Phase B WU-B4).
+#
+# Self-recognition (bassclef#1155, WU-1 of bet 2026-06-18a):
+# Back-port the pgid match shipped in save-state.sh L123-130 and
+# session-end.sh Guard 4. When the lock's pid is in the SAME process
+# group as the current shell, the lock is ours — emit an informational
+# "is ours" line instead of the (misleading) "another session" warning.
+
+LOCK_FILE=".claude/SESSION_LOCK"
+
+if [ -f "$LOCK_FILE" ]; then
+  LOCK_CONTENT=$(head -3 "$LOCK_FILE" 2>/dev/null)
+  LOCK_PID=$(grep -E '^pid:' "$LOCK_FILE" 2>/dev/null | head -1 | sed -E 's/^pid:[[:space:]]*//' | tr -d '[:space:]')
+
+  # Try pgid self-recognition first. If our pgid matches the lock pid's
+  # pgid, the lock was written by our session (Claude harness writes the
+  # lock; this hook runs as descendant in the same job/pgid).
+  if [ -n "$LOCK_PID" ] \
+     && LOCK_PGID=$(ps -o pgid= -p "$LOCK_PID" 2>/dev/null | tr -d ' ') \
+     && OUR_PGID=$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ') \
+     && [ -n "$LOCK_PGID" ] && [ -n "$OUR_PGID" ] \
+     && [ "$LOCK_PGID" = "$OUR_PGID" ]; then
+    echo "### SESSION_LOCK is ours (same pgid $OUR_PGID) — proceeding"
+    echo ""
+  else
+    # Foreign pid, dead pid, or malformed lock — surface the warning.
+    # Try to read mtime as the lock-create time.
+    if LOCK_MTIME=$(stat -c %Y "$LOCK_FILE" 2>/dev/null) || \
+       LOCK_MTIME=$(stat -f %m "$LOCK_FILE" 2>/dev/null); then
+      NOW=$(date -u +%s)
+      AGE_SEC=$(( NOW - LOCK_MTIME ))
+      AGE_MIN=$(( AGE_SEC / 60 ))
+      AGE_HOUR=$(( AGE_MIN / 60 ))
+      if [ "$AGE_HOUR" -gt 0 ]; then
+        AGE_LABEL="${AGE_HOUR}h"
+      elif [ "$AGE_MIN" -gt 0 ]; then
+        AGE_LABEL="${AGE_MIN}m"
+      else
+        AGE_LABEL="${AGE_SEC}s"
+      fi
+    else
+      AGE_LABEL="(age unknown)"
+    fi
+
+    echo "### SESSION_LOCK PRESENT — auto-save suppressed"
+    echo ""
+    echo "  Path:  $LOCK_FILE"
+    echo "  Age:   $AGE_LABEL"
+    if [ -n "$LOCK_CONTENT" ]; then
+      echo "  Content:"
+      echo "$LOCK_CONTENT" | sed 's/^/    /'
+    fi
+    echo ""
+    echo "  → Another session may be active. Confirm before removing the"
+    echo "    lock; removing it resumes auto-save in this repo."
+    echo ""
+  fi
+fi

package/dist/lite/.claude/hooks/session-reflection.d/15-substrate-config-validate.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# tier: lite
+# 15-substrate-config-validate.sh
+#
+# bassclef#591 — substrate.config.md presence + basic-coherence check.
+#
+# Today: thin presence check + required-section presence verification.
+# Full JSON Schema validation deferred per bassclef#643 (migration of
+# substrate.config.md to YAML frontmatter; schema already exists at
+# standards/state-spine/schemas/substrate-config.schema.json).
+#
+# Fires at session-start as part of session-reflection.d/* chain.
+# Surfaces BLOCKED if substrate.config.md is missing OR missing key
+# sections that downstream hooks/skills depend on.
+#
+# Override: SKIP_SUBSTRATE_CONFIG_VALIDATE=1
+#
+# Per bassclef#639 — operates ONLY on $CWD; no cross-repo execution.
+
+set -u
+
+if [ "${SKIP_SUBSTRATE_CONFIG_VALIDATE:-0}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Some sessions provide CWD via stdin JSON; fall back to $PWD if not.
+CWD="${CWD:-$PWD}"
+CONFIG_FILE="$CWD/substrate.config.md"
+
+# Not all repos have substrate.config.md (fresh consumer pre-onboarding).
+# Skip silently if absent; bassclef-sync's onboard path prompts when needed.
+if [ ! -f "$CONFIG_FILE" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Required sections (header style: `## SectionName`).
+# Downstream hooks (session-reflection.sh + others) grep for these section
+# fields; absence is observable behavior, not crash.
+REQUIRED_SECTIONS="Configuration"
+MISSING=""
+
+for section in $REQUIRED_SECTIONS; do
+  if ! grep -q "^## $section" "$CONFIG_FILE" 2>/dev/null; then
+    MISSING="$MISSING $section"
+  fi
+done
+
+# Required fields by line-prefix (legacy markdown style — pre-YAML-frontmatter).
+REQUIRED_FIELDS="gating execution_mode"
+for field in $REQUIRED_FIELDS; do
+  if ! grep -q "^$field:" "$CONFIG_FILE" 2>/dev/null; then
+    MISSING="$MISSING $field:"
+  fi
+done
+
+if [ -n "$MISSING" ]; then
+  cat >&2 <<EOF
+
+================================================================
+⚠️  SUBSTRATE.CONFIG DRIFT — INFORM (Class B cure per #1157)
+================================================================
+
+File:    $CONFIG_FILE
+Missing:$MISSING
+
+substrate.config.md is the single source of truth for external
+resource references (per standards/substrate-config-schema.md).
+Missing sections/fields above are expected by downstream hooks.
+Session continues — this WARN does not block SessionStart.
+
+Resolution (do at your convenience):
+  - If field/section was intentionally removed, restore it (set to a
+    placeholder value if not yet decided)
+  - If file is being bootstrapped fresh, see presence/install/
+    for the substrate-config.md template
+
+Override (logged):  SKIP_SUBSTRATE_CONFIG_VALIDATE=1
+
+Full JSON Schema validation (against
+standards/state-spine/schemas/substrate-config.schema.json) is
+deferred — substrate.config.md needs migration to YAML frontmatter
+first; tracked at bassclef#643.
+
+Closes bassclef#1157 (BLOCK→WARN severity ladder).
+Prior contract: bassclef#591 (thin-validator half; full-schema half deferred).
+================================================================
+EOF
+  return 0 2>/dev/null || exit 0
+fi
+
+return 0 2>/dev/null || exit 0