@thebassclef/lite 1.9.10 → 1.9.12

package/README.md

@@ -67,7 +67,7 @@ your browser.
 
 ## Current release
 
-<!-- version-start -->1.9.10<!-- version-end -->
+<!-- version-start -->1.9.12<!-- version-end -->
 
 See [CHANGELOG.md](CHANGELOG.md) for the full changelog. Adopter-facing
 release notes live at [docs.bassclef.dev/docs/whats-new/releases](https://docs.bassclef.dev/docs/whats-new/releases).

package/dist/cli.cjs

@@ -272,6 +272,47 @@ function hashContent(content) {
   normalized = normalized.replace(/\r\n/g, "\n");
   return node_crypto.createHash("sha256").update(normalized, "utf8").digest("hex");
 }
+const SCHEMA_VERSION = "1.0.0";
+const WRITER_SLUG = "bassclef-init-npm";
+function registerInstallWrittenPaths(targetDir, paths, now = /* @__PURE__ */ new Date()) {
+  if (paths.length === 0) return;
+  const manifestPath = node_path.join(targetDir, "state", "install-written-paths.json");
+  let manifest = {
+    schema_version: SCHEMA_VERSION,
+    entries: []
+  };
+  if (node_fs.existsSync(manifestPath)) {
+    try {
+      const parsed = JSON.parse(node_fs.readFileSync(manifestPath, "utf8"));
+      if (parsed && typeof parsed === "object" && "entries" in parsed && Array.isArray(parsed.entries)) {
+        manifest = parsed;
+        manifest.schema_version = SCHEMA_VERSION;
+      }
+    } catch {
+    }
+  }
+  const writtenAt = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  const uniqueInputs = /* @__PURE__ */ new Map();
+  for (const p of paths) {
+    uniqueInputs.set(p.relativePath, p);
+  }
+  const incomingPaths = new Set(uniqueInputs.keys());
+  manifest.entries = manifest.entries.filter((e) => !incomingPaths.has(e.path));
+  for (const p of uniqueInputs.values()) {
+    manifest.entries.push({
+      path: p.relativePath,
+      writer: WRITER_SLUG,
+      written_at: writtenAt,
+      content_hash: `sha256:${p.contentHashSha256}`
+    });
+  }
+  node_fs.mkdirSync(node_path.dirname(manifestPath), { recursive: true });
+  node_fs.writeFileSync(
+    manifestPath,
+    JSON.stringify(manifest, null, 2) + "\n",
+    "utf8"
+  );
+}
 const SUBSTRATE_CONFIG_TEMPLATE_VERSION = "0.0.1";
 function substrateConfigMdTemplate(pkgVersion) {
   return [
@@ -549,6 +590,7 @@ function copySubstrate(targetDir, options = {}) {
     copied: [],
     copiedEntries: [],
     refused: [],
+    unchanged: [],
     errored: [],
     erroredMessages: [],
     hookCount: 0,
@@ -736,6 +778,16 @@ function copyOne(relPath, bundleRoot, options, result, scopeDecision) {
   } catch (e) {
     if (e instanceof WriteError) {
       if (e.kind === "AlreadyExists") {
+        if (scope === "user") {
+          try {
+            const existing = node_fs.readFileSync(targetPath, "utf8");
+            if (hashContent(existing) === hashContent(outputContent)) {
+              result.unchanged.push(adopterRelPath);
+              return "unchanged";
+            }
+          } catch {
+          }
+        }
         result.refused.push(adopterRelPath);
         return "refused";
       }
@@ -1079,13 +1131,14 @@ function buildInitReport(input) {
     else project += 1;
   }
   const refused = input.refused.length;
+  const unchanged = input.unchanged?.length ?? 0;
   const errored = input.errored.length;
   const written = input.configs.length + input.entries.length;
   return {
     schema_version: 3,
     tier: input.tier,
     totals: {
-      files: written + refused + errored,
+      files: written + refused + unchanged + errored,
       written,
       project,
       user,
@@ -1098,6 +1151,7 @@ function buildInitReport(input) {
       files: catalog.hooks
     },
     refused,
+    unchanged,
     errored,
     failed: refused + errored
   };
@@ -1203,6 +1257,7 @@ function runInit(argv) {
         entries: outcome.result?.wouldCopyEntries ?? [],
         configs: plans.map((pl) => ({ path: pl.relativePath })),
         refused: outcome.result?.refused ?? [],
+        unchanged: outcome.result?.unchanged ?? [],
         // A dry run still reads every source file, so it can still fail
         // to read one. Hard-coding this empty hid those failures from
         // the JSON (RFC-0005 A-3).
@@ -1301,6 +1356,7 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, say
   }
   const parts = [];
   if (result.copied.length > 0) parts.push(`${result.copied.length} substrate files copied`);
+  if (result.unchanged.length > 0) parts.push(`${result.unchanged.length} already-present`);
   if (result.refused.length > 0) parts.push(`${result.refused.length} refused`);
   if (result.errored.length > 0) parts.push(`${result.errored.length} error(s)`);
   say(`bassclef init: ${parts.join(", ")}.
@@ -1531,12 +1587,25 @@ function runReal$1(plans, force, verbose, targetDir, allowRoot, json, skipStatus
     entries: walker.result?.copiedEntries ?? [],
     configs: results.map((r) => ({ path: r.plan.relativePath })),
     refused: walker.result?.refused ?? [],
+    unchanged: walker.result?.unchanged ?? [],
     errored: walker.result?.errored ?? [],
     hookCount: walker.result?.hookCount ?? 0,
     declaredHooksCopied,
     tier: RESOLVED_TIER
   });
   writeManifest(targetDir, results, walker.result);
+  const createdConfigPaths = results.filter((r) => r.outcome === "created").map((r) => ({
+    relativePath: r.plan.relativePath,
+    contentHashSha256: hashContent(r.plan.content)
+  }));
+  const createdBundlePaths = (walker.result?.copiedEntries ?? []).filter((e) => typeof e.content_hash_sha256 === "string").map((e) => ({
+    relativePath: e.path,
+    contentHashSha256: e.content_hash_sha256
+  }));
+  registerInstallWrittenPaths(targetDir, [
+    ...createdConfigPaths,
+    ...createdBundlePaths
+  ]);
   if (walker.code === 0) {
     say(
       `bassclef init: your substrate lives under .claude/. Add .claude/ to .gitignore if you have not.
@@ -1606,6 +1675,15 @@ function writeManifest(targetDir, results, walkerResult) {
         source: "bundle"
       });
     }
+    for (const path of walkerResult.unchanged) {
+      entries.push({
+        path,
+        template: `bundle:${path}`,
+        template_version: index.version,
+        outcome: "unchanged",
+        source: "bundle"
+      });
+    }
     for (const path of walkerResult.errored) {
       entries.push({
         path,

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { version } from "./index.js";
-import { realpathSync, statSync, constants, lstatSync, mkdirSync, accessSync, unlinkSync, openSync, writeSync, closeSync, readlinkSync, readFileSync, chmodSync, readdirSync, existsSync, writeFileSync, renameSync } from "node:fs";
+import { realpathSync, statSync, constants, lstatSync, mkdirSync, accessSync, unlinkSync, openSync, writeSync, closeSync, readlinkSync, existsSync, readFileSync, writeFileSync, chmodSync, readdirSync, renameSync } from "node:fs";
 import { isAbsolute, resolve, dirname, join, normalize, relative, basename as basename$1 } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
@@ -249,6 +249,47 @@ function hashContent(content) {
   normalized = normalized.replace(/\r\n/g, "\n");
   return createHash("sha256").update(normalized, "utf8").digest("hex");
 }
+const SCHEMA_VERSION = "1.0.0";
+const WRITER_SLUG = "bassclef-init-npm";
+function registerInstallWrittenPaths(targetDir, paths, now = /* @__PURE__ */ new Date()) {
+  if (paths.length === 0) return;
+  const manifestPath = join(targetDir, "state", "install-written-paths.json");
+  let manifest = {
+    schema_version: SCHEMA_VERSION,
+    entries: []
+  };
+  if (existsSync(manifestPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+      if (parsed && typeof parsed === "object" && "entries" in parsed && Array.isArray(parsed.entries)) {
+        manifest = parsed;
+        manifest.schema_version = SCHEMA_VERSION;
+      }
+    } catch {
+    }
+  }
+  const writtenAt = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  const uniqueInputs = /* @__PURE__ */ new Map();
+  for (const p of paths) {
+    uniqueInputs.set(p.relativePath, p);
+  }
+  const incomingPaths = new Set(uniqueInputs.keys());
+  manifest.entries = manifest.entries.filter((e) => !incomingPaths.has(e.path));
+  for (const p of uniqueInputs.values()) {
+    manifest.entries.push({
+      path: p.relativePath,
+      writer: WRITER_SLUG,
+      written_at: writtenAt,
+      content_hash: `sha256:${p.contentHashSha256}`
+    });
+  }
+  mkdirSync(dirname(manifestPath), { recursive: true });
+  writeFileSync(
+    manifestPath,
+    JSON.stringify(manifest, null, 2) + "\n",
+    "utf8"
+  );
+}
 const SUBSTRATE_CONFIG_TEMPLATE_VERSION = "0.0.1";
 function substrateConfigMdTemplate(pkgVersion) {
   return [
@@ -526,6 +567,7 @@ function copySubstrate(targetDir, options = {}) {
     copied: [],
     copiedEntries: [],
     refused: [],
+    unchanged: [],
     errored: [],
     erroredMessages: [],
     hookCount: 0,
@@ -713,6 +755,16 @@ function copyOne(relPath, bundleRoot, options, result, scopeDecision) {
   } catch (e) {
     if (e instanceof WriteError) {
       if (e.kind === "AlreadyExists") {
+        if (scope === "user") {
+          try {
+            const existing = readFileSync(targetPath, "utf8");
+            if (hashContent(existing) === hashContent(outputContent)) {
+              result.unchanged.push(adopterRelPath);
+              return "unchanged";
+            }
+          } catch {
+          }
+        }
         result.refused.push(adopterRelPath);
         return "refused";
       }
@@ -1056,13 +1108,14 @@ function buildInitReport(input) {
     else project += 1;
   }
   const refused = input.refused.length;
+  const unchanged = input.unchanged?.length ?? 0;
   const errored = input.errored.length;
   const written = input.configs.length + input.entries.length;
   return {
     schema_version: 3,
     tier: input.tier,
     totals: {
-      files: written + refused + errored,
+      files: written + refused + unchanged + errored,
       written,
       project,
       user,
@@ -1075,6 +1128,7 @@ function buildInitReport(input) {
       files: catalog.hooks
     },
     refused,
+    unchanged,
     errored,
     failed: refused + errored
   };
@@ -1180,6 +1234,7 @@ function runInit(argv) {
         entries: outcome.result?.wouldCopyEntries ?? [],
         configs: plans.map((pl) => ({ path: pl.relativePath })),
         refused: outcome.result?.refused ?? [],
+        unchanged: outcome.result?.unchanged ?? [],
         // A dry run still reads every source file, so it can still fail
         // to read one. Hard-coding this empty hid those failures from
         // the JSON (RFC-0005 A-3).
@@ -1278,6 +1333,7 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, say
   }
   const parts = [];
   if (result.copied.length > 0) parts.push(`${result.copied.length} substrate files copied`);
+  if (result.unchanged.length > 0) parts.push(`${result.unchanged.length} already-present`);
   if (result.refused.length > 0) parts.push(`${result.refused.length} refused`);
   if (result.errored.length > 0) parts.push(`${result.errored.length} error(s)`);
   say(`bassclef init: ${parts.join(", ")}.
@@ -1508,12 +1564,25 @@ function runReal$1(plans, force, verbose, targetDir, allowRoot, json, skipStatus
     entries: walker.result?.copiedEntries ?? [],
     configs: results.map((r) => ({ path: r.plan.relativePath })),
     refused: walker.result?.refused ?? [],
+    unchanged: walker.result?.unchanged ?? [],
     errored: walker.result?.errored ?? [],
     hookCount: walker.result?.hookCount ?? 0,
     declaredHooksCopied,
     tier: RESOLVED_TIER
   });
   writeManifest(targetDir, results, walker.result);
+  const createdConfigPaths = results.filter((r) => r.outcome === "created").map((r) => ({
+    relativePath: r.plan.relativePath,
+    contentHashSha256: hashContent(r.plan.content)
+  }));
+  const createdBundlePaths = (walker.result?.copiedEntries ?? []).filter((e) => typeof e.content_hash_sha256 === "string").map((e) => ({
+    relativePath: e.path,
+    contentHashSha256: e.content_hash_sha256
+  }));
+  registerInstallWrittenPaths(targetDir, [
+    ...createdConfigPaths,
+    ...createdBundlePaths
+  ]);
   if (walker.code === 0) {
     say(
       `bassclef init: your substrate lives under .claude/. Add .claude/ to .gitignore if you have not.
@@ -1583,6 +1652,15 @@ function writeManifest(targetDir, results, walkerResult) {
         source: "bundle"
       });
     }
+    for (const path of walkerResult.unchanged) {
+      entries.push({
+        path,
+        template: `bundle:${path}`,
+        template_version: version,
+        outcome: "unchanged",
+        source: "bundle"
+      });
+    }
     for (const path of walkerResult.errored) {
       entries.push({
         path,

package/dist/index.cjs

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.9.10";
+const version = "1.9.12";
 export {
   version
 };

package/dist/lite/.claude/hooks/artifact-ingestion-gate.sh

@@ -143,9 +143,15 @@ if [ "$HAS_SOURCES_READ" -eq 1 ]; then
         exit
       }
     ')
-    if [ -z "$PARENT_VALUE" ]; then
-      continue
-    fi
+    # cli#311 cure — treat null / ~ / empty as "no parent declared" (Peirce three-case).
+    # YAML null shorthand is `null`, `~`, or an empty value. Prior code caught empty
+    # only; `parent_bet: null` tripped the gate on root goals that genuinely have no
+    # parent. Mirrors the #70 cure in bet-doc-gate.sh.
+    case "$PARENT_VALUE" in
+      "" | "null" | "Null" | "NULL" | "~" | "None")
+        continue
+        ;;
+    esac
 
     # Check if the parent path (or its basename without extension) appears
     # in the Sources-read section. Accepts either:

package/dist/lite/.claude/hooks/save-state.sh

@@ -209,7 +209,12 @@ DIRTY=$(git status --porcelain 2>/dev/null | grep -v '\.DS_Store' | grep -v 'SES
 if [ -n "$DIRTY" ]; then
   # Stage tracked modified files + any docs/ or chronicle/ or runtime state
   git add -u 2>/dev/null || true
-  git add docs/ chronicle/ specs/ 2>/dev/null || true
+  # docs/ except docs/prototypes/ — prototypes are review-gated mocks per
+  # .claude/rules/prototype-workflow.md; auto-save must not commit them
+  # before the operator confirms the rendered output (cli#323).
+  # Same pathspec pattern used for state/markers below.
+  git add 'docs/' ':!docs/prototypes' ':!docs/prototypes/**' 2>/dev/null || true
+  git add chronicle/ specs/ 2>/dev/null || true
   # state/ except state/markers/ — markers are runtime gate evidence that
   # trigger session-rescue false-positives if committed (bassclef#341 / WU-A2).
   # Negative pathspec syntax requires git >= 2.13 (stable since 2017).

package/dist/lite/.claude/hooks/session-reflection.d/97-last-block-count.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# Session-reflection fragment — surface last-block marker count.
+#
+# Per @luminary don-norman signifier: when BLOCK banners from prior
+# sessions sit in state/markers/last-block/, this fragment tells the
+# adopter they exist and names /last-block as the retrieval path.
+#
+# Fires once at session-start. Reads marker count. Prints one line to
+# stdout when count > 0. Silent on empty.
+#
+# Composition — sourced by session-reflection.sh under set -e. Must use
+# `return`, not `exit`, else the coordinator dies. Per test-sufficiency
+# criterion 12 (invocation-mode variation).
+#
+# Per bassclef-upstream#2036 Finding #10 + UC-skill-last-block.md.
+
+# Resolve directory (same convention as lib/last-block.sh).
+_last_block_count_dir() {
+  if [ -n "${LAST_BLOCK_DIR:-}" ]; then
+    echo "$LAST_BLOCK_DIR"
+  else
+    echo "${CLAUDE_PROJECT_DIR:-.}/state/markers/last-block"
+  fi
+}
+
+LBC_DIR="$(_last_block_count_dir)"
+
+if [ ! -d "$LBC_DIR" ]; then
+  # Fresh install or dir never created. Silent.
+  # shellcheck disable=SC2317  # dual-use sourced-or-standalone exit path
+return 0 2>/dev/null || exit 0
+fi
+
+LBC_COUNT=$(find "$LBC_DIR" -maxdepth 1 -name '*.marker' -type f 2>/dev/null | wc -l | tr -d ' ')
+
+if [ "$LBC_COUNT" -gt 0 ]; then
+  if [ "$LBC_COUNT" = "1" ]; then
+    echo "### LAST BLOCK"
+    echo ""
+    echo "1 BLOCK banner stored. Read it with /last-block."
+    echo ""
+  else
+    echo "### LAST BLOCKS"
+    echo ""
+    echo "${LBC_COUNT} BLOCK banners stored. Read the newest with /last-block, or list all with /last-block --list."
+    echo ""
+  fi
+fi
+
+# shellcheck disable=SC2317  # dual-use sourced-or-standalone exit path
+return 0 2>/dev/null || exit 0

package/dist/lite/.claude/hooks/session-reflection.d/tests/97-last-block-count.test.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# tier: lite
+# fixtures: bassclef-upstream-self
+# shellcheck disable=SC2034
+# Tier 0 test for .claude/hooks/session-reflection.d/97-last-block-count.sh
+#
+# Covers invocation-mode variation (criterion 12 of test-sufficiency rubric):
+# both standalone and sourced-under-set-e paths.
+#
+# Ticket: bassclef-upstream#2036 Finding #10
+#
+# test-list:
+# [x] T01: standalone + no dir -> silent, exit 0, no return error
+# [x] T02: standalone + empty dir -> silent, exit 0
+# [x] T03: standalone + 1 marker -> prints "1 BLOCK banner stored"
+# [x] T04: standalone + 3 markers -> prints "3 BLOCK banners stored"
+# [x] T05: sourced under set -e -> parent survives (no exit)
+# [x] T06: honors LAST_BLOCK_DIR env override
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FRAG_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+FRAG="$FRAG_DIR/97-last-block-count.sh"
+
+if [ ! -f "$FRAG" ]; then
+  echo "RED: $FRAG does not exist yet" >&2
+  exit 1
+fi
+
+FIXTURE_ROOT="$(mktemp -d)"
+RESULTS_FILE="$FIXTURE_ROOT/results.log"
+touch "$RESULTS_FILE"
+trap 'rm -rf "$FIXTURE_ROOT"' EXIT
+
+pass() { echo "PASS" >> "$RESULTS_FILE"; echo "PASS: $1"; }
+fail() { echo "FAIL" >> "$RESULTS_FILE"; echo "FAIL: $1"; }
+
+# T01: standalone + no dir
+( LAST_BLOCK_DIR="$FIXTURE_ROOT/nonexistent"
+  export LAST_BLOCK_DIR
+  OUT=$(bash "$FRAG" 2>&1)
+  RC=$?
+  if [ "$RC" = "0" ] && [ -z "$OUT" ]; then
+    pass "T01: standalone + no dir -> silent"
+  else
+    fail "T01: standalone + no dir -> silent (rc=$RC out=$OUT)"
+  fi
+)
+
+# T02: standalone + empty dir
+( LAST_BLOCK_DIR="$(mktemp -d)"
+  export LAST_BLOCK_DIR
+  OUT=$(bash "$FRAG" 2>&1)
+  RC=$?
+  if [ "$RC" = "0" ] && [ -z "$OUT" ]; then
+    pass "T02: standalone + empty dir -> silent"
+  else
+    fail "T02: standalone + empty dir -> silent (rc=$RC out=$OUT)"
+  fi
+)
+
+# T03: standalone + 1 marker
+( DIR="$(mktemp -d)"
+  LAST_BLOCK_DIR="$DIR"
+  export LAST_BLOCK_DIR
+  echo "hook: a" > "$DIR/a.marker"
+  OUT=$(bash "$FRAG" 2>&1)
+  if echo "$OUT" | grep -qF "1 BLOCK banner stored"; then
+    pass "T03: 1 marker -> prints singular"
+  else
+    fail "T03: 1 marker (got: $OUT)"
+  fi
+)
+
+# T04: standalone + 3 markers
+( DIR="$(mktemp -d)"
+  LAST_BLOCK_DIR="$DIR"
+  export LAST_BLOCK_DIR
+  echo "hook: a" > "$DIR/a.marker"
+  echo "hook: b" > "$DIR/b.marker"
+  echo "hook: c" > "$DIR/c.marker"
+  OUT=$(bash "$FRAG" 2>&1)
+  if echo "$OUT" | grep -qF "3 BLOCK banners stored"; then
+    pass "T04: 3 markers -> prints plural with count"
+  else
+    fail "T04: 3 markers (got: $OUT)"
+  fi
+)
+
+# T05: sourced under set -e -> parent survives (criterion 12)
+( DIR="$(mktemp -d)"
+  LAST_BLOCK_DIR="$DIR"
+  export LAST_BLOCK_DIR
+  echo "hook: a" > "$DIR/a.marker"
+  # Simulate coordinator: set -e wrapper + source
+  CANARY_FILE="$FIXTURE_ROOT/canary-t05"
+  (
+    set -e
+    # shellcheck source=/dev/null
+    source "$FRAG"
+    # If frag used `exit` instead of `return`, this line never runs.
+    touch "$CANARY_FILE"
+  ) >/dev/null 2>&1 || true
+  if [ -f "$CANARY_FILE" ]; then
+    pass "T05: sourced under set -e survives (canary ran)"
+  else
+    fail "T05: sourced under set -e survives (canary missing)"
+  fi
+)
+
+# T06: honors LAST_BLOCK_DIR env override
+( DIR="$(mktemp -d)"
+  LAST_BLOCK_DIR="$DIR"
+  export LAST_BLOCK_DIR
+  echo "hook: a" > "$DIR/a.marker"
+  OUT=$(bash "$FRAG" 2>&1)
+  if echo "$OUT" | grep -qF "1 BLOCK banner stored"; then
+    pass "T06: honors LAST_BLOCK_DIR override"
+  else
+    fail "T06: honors LAST_BLOCK_DIR override (got: $OUT)"
+  fi
+)
+
+echo
+echo "=== Results ==="
+PASS=$(awk '/^PASS$/ {c++} END {print c+0}' "$RESULTS_FILE")
+FAIL=$(awk '/^FAIL$/ {c++} END {print c+0}' "$RESULTS_FILE")
+echo "PASS: $PASS"
+echo "FAIL: $FAIL"
+if [ "$FAIL" -gt 0 ]; then exit 1; fi

package/dist/lite/.claude/hooks/session-reflection.sh

@@ -74,6 +74,14 @@ else
 fi
 export BASSCLEF_DIR
 
+# Source lib/last-block.sh so banner calls persist markers. Per Finding
+# #10 — adopters need a first-class way to retrieve BLOCK text they saw.
+# The lib fails soft; missing lib leaves the banners untouched.
+# shellcheck source=/dev/null
+if [ -f "${BASSCLEF_DIR}/lib/last-block.sh" ]; then
+  source "${BASSCLEF_DIR}/lib/last-block.sh"
+fi
+
 # High-contrast BLOCKED banner; used by every module that raises a gap.
 # RFC-0008 F3 — "Silence is not deferral" is a commitment device. It works
 # because it forecloses the easy out, and it is consumable: spend it on a
@@ -81,9 +89,13 @@ export BASSCLEF_DIR
 # Callers that can prove their own state is benign pass a second argument
 # and get a softer close. Callers that pass one argument behave exactly as
 # before, so the other 27 sites are untouched.
+#
+# Per Finding #10 — each call now also writes a marker so the adopter can
+# retrieve the exact banner text later via /last-block.
 blocked_banner() {
   local msg="$1"
   local severity="${2:-blocking}"
+  local hook_name="${BASSCLEF_CALLING_HOOK:-session-reflection}"
   echo ""
   case "$severity" in
     info)
@@ -106,9 +118,14 @@ blocked_banner() {
       echo "────────────────────────────────────────────"
       echo "ACTION: resolve OR explicitly defer (per .claude/rules/blocked-items.md)."
       echo "Silence is not deferral. Propose this as item #1 in your session plan."
+      echo "(Retrieve this banner later with: /last-block ${hook_name})"
       ;;
   esac
   echo ""
+  # Persist marker for /last-block retrieval. Fail-soft.
+  if type -t record_last_block >/dev/null 2>&1; then
+    record_last_block "$hook_name" "$severity" "$msg" 2>/dev/null || true
+  fi
 }
 
 # Vendor-swap constant — the AI in the harness running bassclef. Adopter
@@ -131,7 +148,12 @@ guardrail_banner() {
   echo "────────────────────────────────────────────"
   echo "bassclef is steering $AI_NAME to $step — $retry"
   echo "────────────────────────────────────────────"
+  echo "(Retrieve this banner later with: /last-block ${hook_name})"
   echo ""
+  # Persist marker for /last-block retrieval. Fail-soft.
+  if type -t record_last_block >/dev/null 2>&1; then
+    record_last_block "$hook_name" "guardrail" "$step — $retry" 2>/dev/null || true
+  fi
 }
 
 # RFC-0008 F6 — this block is steering aimed at the agent, but the adopter