@thebassclef/lite 1.9.16 → 1.9.19

package/README.md

@@ -67,7 +67,7 @@ your browser.
 
 ## Current release
 
-<!-- version-start -->1.9.16<!-- version-end -->
+<!-- version-start -->1.9.19<!-- 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/index.cjs

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.9.16";
+const version = "1.9.19";
 export {
   version
 };

package/dist/lite/.claude/agents/builder.md

@@ -3,7 +3,7 @@ tier: lite
 name: Builder
 description: "Executes against spec. Respects ADR constraints. Commits with conventional commits. Doesn't redesign mid-build. Raises blockers immediately."
 tools: Read, Write, Edit, Glob, Grep, Bash
-model: claude-sonnet-4-6
+model: claude-sonnet-5
 model_tier: balanced
 ---
 
@@ -16,15 +16,18 @@ You execute. You don't redesign mid-build. You raise blockers immediately rather
 - Construction (primary)
 
 ## Responsibilities
-- Run /pattern-review BEFORE implementing — check GoF patterns, Fowler
-  refactoring smells, SOLID principles, DDD alignment. This shapes the
-  implementation approach, not just reviews it after the fact.
+- Run /pattern-review BEFORE implementing **when a pattern catalog exists** —
+  check `state/pattern-implementations/` or `patterns/` for a catalog. If
+  present, review GoF patterns, Fowler refactoring smells, SOLID principles,
+  DDD alignment. If absent, skip the ask — do not block on a missing catalog.
+  Per bassclef-upstream#2175 Batch C (F8).
 - Implement against spec acceptance criteria + pattern guidance
 - Respect ADR constraints — flag violations rather than working around them
 - Commit with conventional commits
 - Open PRs with context, not just diffs
 - Run /temperance before non-trivial tasks
 - Run /verify after each task before committing
+- **Friction report before marking a step done (per bassclef-upstream#2175 Batch C — F9).** Before stating a step is complete, read `docs/session-friction-log.md` for new entries from this step. Report friction count in the PR body under a Friction section. Escalate `BLOCK`-tagged entries to Architect.
 
 ## Decision authority
 Implementation approach within ADR constraints. Escalate if a constraint must be broken.

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

@@ -146,6 +146,28 @@ Pick the tier that matches your trust + budget. Upgrade path is additive — no
 - `/luminary` — design-lens catalog
 - `/hooks` — mechanical-enforcement layer
 
+## Concise output style (opt-in)
+
+Anthropic ships four output styles besides Default — Proactive, Concise, Explanatory, Learning. See [Output styles docs](https://code.claude.com/docs/en/output-styles). The Concise style (v2.1.237+) leads replies with the result, skips step-by-step narration, and skips closing recaps. Simple questions answer in one to three sentences. Full-length output stays for error reports, failing tests, security warnings, and destructive-action confirmations.
+
+Concise covers prose dimensions bassclef already steers via `operator-facing-prose.md` + `writing-craft-discipline.md` + visual hierarchy. Enabling it at operator-user scope reduces per-turn hook-injected reminders for those dimensions. The bassclef-specific layers (grade target, jargon wordlist, appositive discipline, claim + evidence + warrant shape, per-turn metric feedback) stay as the written contract. Your project CLAUDE.md and rules stay loaded regardless of the style — Concise shapes response form, not what the model reads about your project. The before-and-after measure for Concise plus bassclef combined lands in bassclef-upstream#2197 Step 1 baseline.
+
+Bassclef does not set the output style at project scope. Project settings would override adopter choice. To enable, add this field to your user-scope `~/.claude/settings.json`:
+
+```json
+{
+  "outputStyle": "Concise"
+}
+```
+
+The value is case-sensitive — `"Concise"` with a capital C. A value that does not match an output-style name exactly falls back to Default silently. The `/output-style concise` command (v2.1.269+) is case-insensitive and offers the same result.
+
+Switching styles mid-session takes effect at the next message and invalidates one prompt-cache slot per the [prompt-caching docs](https://code.claude.com/docs/en/prompt-caching#changing-output-style). After the first message post-switch, cache resumes.
+
+See `docs/audits/2026-10-12-anthropic-builtins-vs-bassclef-steering.md` for the overlap analysis — which bassclef dimensions Concise covers, which bassclef dimensions stay bassclef's own.
+
+Ships bassclef-upstream#2205.
+
 ## Statusline (opt-in)
 
 Bassclef ships a statusline reader at `lib/statusline-version.sh`. When enabled, terminal Claude Code sessions render `bassclef v1.6.2 · up-to-date` at the bottom of every prompt. The reader consults `state/bassclef-sync-status.json` (written by `bassclef-sync.sh` at end-of-run) and `bassclef-version.json` at the repo root.

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

@@ -84,16 +84,24 @@ elif [ "$TOOL_NAME" = "Edit" ]; then
 ${NEW_STRING}"
 fi
 
-# Check for Sources-read block (case-insensitive, tolerant of heading depth).
+# Check for Sources-read block (case-insensitive, tolerant of heading depth,
+# tolerant of leading whitespace per bassclef-upstream#2142).
 # Accepted forms:
-#   ## Sources read
+#   ## Sources read                     (markdown artifact at col 0)
 #   ### Sources read
 #   ## Sources Read
 #   ## SOURCES READ
+#     ## Sources read                   (indented inside HTML comment per #2142)
 # Also accepts an explicit from-scratch rationale:
 #   "No prior artifacts" (per rule)
+#
+# Prior anchor `^#{1,6}` required the hash to sit at column 0. HTML prototype
+# files produced by /launch --local carry sources inside a top-of-file
+# `<!-- ... -->` comment where the hash is naturally indented. The anchor
+# removal keeps match specificity (hash prefix + exact phrase) without
+# false-positive risk on arbitrary prose.
 HAS_SOURCES_READ=0
-if echo "$FUTURE_CONTENT" | grep -qiE '^#{1,6}[[:space:]]+sources[[:space:]]+read'; then
+if echo "$FUTURE_CONTENT" | grep -qiE '#{1,6}[[:space:]]+sources[[:space:]]+read'; then
   HAS_SOURCES_READ=1
 fi
 if echo "$FUTURE_CONTENT" | grep -qi 'no prior artifacts'; then

package/dist/lite/.claude/hooks/assert-verify-steering.sh

@@ -52,25 +52,7 @@ if [ "${SKIP_ASSERT_VERIFY_STEERING:-0}" = "1" ]; then
 fi
 
 # === Steering content ===
-STEERING_CONTENT="**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.
-
-**Check my claims before I write them:**
-
-For any claim to the operator — a finding, a rating, a fix I recommend, why I think X caused Y, how many turns something will take, or a strong-word claim (wrong, broken, should, must, always) — I fill three parts:
-
-1. **My claim** — the assertion in one sentence.
-2. **Evidence** — the source I read, cited inline (file path, ticket number, git SHA, chronicle filename, standard section).
-3. **Why the evidence supports the claim** — one sentence tying the source to the claim.
-
-Add more when it helps:
-
-4. **Confidence plus how many observations back it** — from Toulmin, *The Uses of Argument* (1958).
-5. **What would falsify the claim** — from Popper, *The Logic of Scientific Discovery* (1959). A claim that cannot be falsified is a guess.
-6. **Two or three alternative explanations that fit the same data** — from Peirce, *Deduction, Induction, and Hypothesis* (1878). Name each option before you pick one.
-
-If I cannot fill all three, I do not ship the claim. I read the source first.
-
-Per bassclef#559 and .claude/rules/assert-only-after-verify.md."
+STEERING_CONTENT="**Plain check:** Before I make a claim, I read the source first and cite it. Every operator-facing claim carries three parts — **My claim** (one sentence) + **Evidence** (source cited inline — file path, ticket, SHA) + **Why the evidence supports the claim** (one sentence). Add Toulmin confidence, Popper falsifiability, or Peirce alternatives when they help. If any part is missing, I do not ship — read the source first. Full shape at .claude/rules/assert-only-after-verify.md (bassclef#559)."
 
 # === Emit envelope ===
 emit_additional_context "UserPromptSubmit" "$STEERING_CONTENT"

package/dist/lite/.claude/hooks/plain-english-steering.sh

@@ -33,6 +33,21 @@ for _candidate in \
   fi
 done
 
+# === Source lib/prose-marker.sh (Longrun 2 Step 2d — scorer stack reader) ===
+# Provides read_prose_markers for density + appositive scorer markers.
+# Silent-fail — missing lib = no scorer line injection; existing grade +
+# flags paths unchanged.
+for _candidate in \
+  "${SCRIPT_DIR}/../../lib/prose-marker.sh" \
+  "${HOME_OVERRIDE:-${HOME:-/}}/lib/prose-marker.sh"; do
+  if [ -f "$_candidate" ]; then
+    # shellcheck disable=SC1090
+    source "$_candidate"
+    break
+  fi
+done
+unset _candidate
+
 # Defensive: if lib not loaded, exit silent
 if ! declare -f emit_additional_context >/dev/null 2>&1; then
   exit 0
@@ -119,51 +134,81 @@ if [ -f "$FLAGS_MARKER" ]; then
   fi
 fi
 
-# === Emit steering content ===
-# Extension per ticket #935 — first-person Ogilvy compose tests
-# grounded in standards/ogilvy-writing-rules.md (from #934 PR #938)
-STEERING_CONTENT="**Plain English for anything the operator or an adopter reads:**
-
-For turn output, PR body, issue body, session log, journal entry, and skill output:
-
-- Bassclef aims for grade 8 in most prose. Grade 10 is the top limit for simple technical sentences.
-- Above grade 10, give a clear reason grades 8-10 could not say it. A technical topic on its own is not a reason.
-- Short sentences. Subject-verb-object.
-- If I want to use a hyphen word (X-side, X-as-Y, N-layer X, X gate), I write what it does instead.
-- No more than two nouns in a row without a verb between them.
-- Drop words that only bassclef readers know — see standards/bassclef-internal-jargon.md.
-- Keep standard tech words: API, hook, PR, schema, ORM.
-
-**Vocabulary rename active (per ADR-040 D1; grace window through 2026-10-31):**
-
-When I author NEW prose for the operator or an adopter, I use the new terms:
-
-- Say **goal** not **bet**. (Historical goal IDs like \`bet 08-11a\` stay as-is.)
-- Say **step** not **WU** or **workunit**. (Historical \`WU-2\` refs stay.)
-- Say **in_flight_goal** not **in_flight_bet** for new whereami updates.
-- Say **time budget** not **appetite** for new prose.
-- Say **parent goal** and **thread** not **parent bet** and **arc** for new prose.
-
-**Discrimination cue.** Two situations, two different rules:
-
-1. When I AUTHOR — writing my own sentence about work in flight or scope decisions — I use the new terms (Step-N, goal, time budget). Never introduce \`WU-N\` or \`bet\` or \`appetite\` in new prose.
-2. When I QUOTE a past goal ID or reference (\`bet 27c WU-5\`, \`bet 2026-06-20a WU-1\`) — I preserve the exact historical string verbatim inside backticks. The backticks mark the historical boundary. The reader sees \"quote\" not \"active vocabulary.\"
-
-Rule of thumb: if I am about to type \`WU-\` in a sentence, ask — am I quoting a historical goal ID? If yes, wrap in backticks. If no, use Step-N instead.
+# === Resolve scorer_track opt-in flag (Longrun 2 Step 2f — ADR-049) ===
+# Default false per ADR-049 opt-in. Config at .claude/bassclef-configs.jsonc
+# field prose_discipline.scorer_track. Env PROSE_DISCIPLINE_SCORER_TRACK
+# overrides the config.
+SCORER_TRACK="${PROSE_DISCIPLINE_SCORER_TRACK:-}"
+if [ -z "$SCORER_TRACK" ]; then
+  if declare -f resolve_config_path >/dev/null 2>&1; then
+    CONFIG_FILE_FOR_SCORER=$(resolve_config_path 2>/dev/null) || CONFIG_FILE_FOR_SCORER=""
+  else
+    CONFIG_FILE_FOR_SCORER="${SCRIPT_DIR}/../bassclef-configs.jsonc"
+  fi
+  if [ -n "$CONFIG_FILE_FOR_SCORER" ] && [ -f "$CONFIG_FILE_FOR_SCORER" ]; then
+    SCORER_TRACK=$(sed 's|//.*||g' "$CONFIG_FILE_FOR_SCORER" 2>/dev/null \
+      | jq -r '.prose_discipline.scorer_track // false' 2>/dev/null)
+  fi
+  SCORER_TRACK="${SCORER_TRACK:-false}"
+fi
 
-Historical mentions (past goal IDs, closed PR bodies, archived session logs) keep the old words — read-through via \`standards/vocabulary-migration.json\`.
+# === Read scorer-stack markers (Longrun 2 Step 2d — density + appositive) ===
+# Reads turn-prose-density + turn-prose-appositive markers via lib. Builds
+# a one-line scorer digest with glyph legend per standards/prose-marker-format.md v1.0.
+# Silent-fail — missing lib or markers = empty SCORER_LINE; existing paths unchanged.
+# Gated by SCORER_TRACK opt-in flag (Step 2f).
+SCORER_LINE=""
+if [ "$SCORER_TRACK" = "true" ] && declare -f read_prose_markers >/dev/null 2>&1; then
+  SCORER_JSON=$(read_prose_markers "turn-prose-density" "turn-prose-appositive" 2>/dev/null)
+  if [ -n "$SCORER_JSON" ]; then
+    SCORER_LINE=$(echo "$SCORER_JSON" | python3 -c '
+import json, sys
+try:
+    data = json.loads(sys.stdin.read())
+except Exception:
+    sys.exit(0)
+parts = []
+# density scorer — green=0 amber=3 per standards/prose-marker-format.md
+d = data.get("turn-prose-density")
+if d and isinstance(d, dict) and "value" in d:
+    v = d["value"]
+    glyph = "🟢" if v <= 0 else ("🟡" if v <= 3 else "🔴")
+    parts.append(f"density {v} {glyph}")
+# appositive scorer — green=0 amber=2
+a = data.get("turn-prose-appositive")
+if a and isinstance(a, dict) and "value" in a:
+    v = a["value"]
+    glyph = "🟢" if v <= 0 else ("🟡" if v <= 2 else "🔴")
+    parts.append(f"appositive misses {v} {glyph}")
+if parts:
+    print(" · ".join(parts))
+' 2>/dev/null)
+  fi
+fi
 
-**Compose check this turn (per Ogilvy + Roman-Raphaelson via standards/ogilvy-writing-rules.md).**
-Before I write each sentence, I ask:
+# Format the scorer line as a steering block addition when non-empty
+SCORER_BLOCK=""
+if [ -n "$SCORER_LINE" ]; then
+  SCORER_BLOCK="
 
-- Natural voice — would a real person say this to a peer? If it sounds like corporate throat-clearing, rewrite.
-- Short units — is this sentence past 25 words? If yes, split.
-- Read-aloud — when I read this in my head, does it stumble? If yes, rewrite until it flows.
-- Completeness — is the ONE thing the reader needs to take from this actually written down in plain language?
-- Honesty — am I saying what I mean or hiding behind hedge words and euphemisms? Say it straight.
-- Facts with context — for each number or fact, did I say why it matters?
+**Scorer stack — $SCORER_LINE.**
+- Density counts odd compound words — jargon that stacks.
+- Appositive misses count shortcuts I used without saying what they mean.
+- Thresholds at standards/prose-marker-format.md v1.0."
+fi
 
-Per bassclef#790 + .claude/rules/operator-facing-prose.md + .claude/rules/writing-craft-discipline.md.${GRADE_LINE}${FLAGS_LINE}${FALLBACK_WARNING}"
+# === Emit steering content ===
+# Extension per ticket #935 — first-person Ogilvy compose tests
+# grounded in standards/ogilvy-writing-rules.md (from #934 PR #938)
+# Scorer-stack SCORER_BLOCK added at Longrun 2 Step 2d (#2197).
+STEERING_CONTENT="**Plain English for operator-facing prose.**
+- Target grade 8. Ceiling grade 10 for simple tech sentences.
+- Short sentences. Subject-verb-object.
+- Drop bassclef-internal jargon. Full list at standards/bassclef-internal-jargon.md.
+- Keep standard tech words — API, hook, PR, schema.
+- Vocabulary rename per ADR-040 D1 (grace through 2026-10-31): say goal not bet, step not WU, time budget not appetite, parent goal + thread not parent bet + arc.
+- Historical goal IDs stay verbatim in backticks.
+- Compose check (Ogilvy, six tests): natural voice · short units · read-aloud · completeness · honesty · facts with context. Full guidance at .claude/rules/writing-craft-discipline.md and .claude/rules/operator-facing-prose.md.${GRADE_LINE}${FLAGS_LINE}${SCORER_BLOCK}${FALLBACK_WARNING}"
 
 # Use emit_additional_context to wrap as JSON envelope
 emit_additional_context "UserPromptSubmit" "$STEERING_CONTENT"

package/dist/lite/.claude/hooks/pre-commit-gate.sh

@@ -23,8 +23,16 @@ INPUT=$(cat)
 # stdin (exit 5 from jq).
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null || echo "")
 
-# Only fire on git commit commands
-if ! echo "$COMMAND" | grep -q 'git commit'; then
+# Only fire on git commit commands.
+# Per bassclef-upstream#2139 — the prior matcher `grep -q 'git commit'` had no
+# command-position anchor, so a heredoc body containing the words "git commit"
+# fired the hook on cat/echo writes. The anchored regex below matches `git commit`
+# only when it sits at a shell command position: start-of-line, after a chain
+# operator (`&&`, `||`, `|`, `;`), or after an env-assignment prefix
+# (`VAR=val git commit`). Grep is line-oriented, so each line of a multi-line
+# heredoc is checked independently; body text with "git commit" as prose does
+# not match any anchor and the hook skips.
+if ! echo "$COMMAND" | grep -qE '(^|&&|\|\||[|;])[[:space:]]*([A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*git[[:space:]]+commit([[:space:]]|$)'; then
   exit 0
 fi
 

package/dist/lite/.claude/hooks/pre-push-shellcheck.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# pre-push-shellcheck — PreToolUse Bash hook that scans .sh files going
+# out at `git push` and BLOCKs on un-allowlisted shellcheck findings.
+#
+# Catches shellcheck SC2164 and sister findings at author time so the
+# CI shellcheck gate (.github/workflows/shellcheck.yml) does not fire
+# red on a fresh PR. Closes bassclef-upstream#2108 + #2253 + #2254.
+#
+# Reuses the existing allowlist at .claude/hooks/shellcheck-allowlist.txt
+# (format: SC<code>:<path>). Scans files changed between upstream HEAD
+# and local HEAD; falls back to origin/main when no upstream is set.
+#
+# Install-written-paths consult (#2253) — bassclef-shipped .sh files
+# (recorded in state/install-written-paths.json with matching
+# content_hash) skip the scan. Adopter edits to those files mismatch
+# the hash and still get scanned. Lib fails soft when manifest absent.
+#
+# Exit codes:
+#   0 — pass OR fail-soft (shellcheck missing / jq missing / no .sh changed)
+#   2 — BLOCK (un-allowlisted shellcheck finding above severity=warning)
+#
+# Override — env (shell): SKIP_PRE_PUSH_SHELLCHECK=1 git push ...
+# Override — marker (agent, #2254): touch state/markers/skip/pre-push-shellcheck.marker
+#   (both logged via trace-helper when available)
+#
+# Per @luminary jerome-saltzer-and-michael-schroeder — complete mediation.
+# Per @luminary michael-nygard — fail-soft on missing binaries.
+# Per @luminary michael-feathers — reuses CI's shellcheck JSON + allowlist shape.
+
+set +e  # never crash the tool call
+
+INPUT=$(cat 2>/dev/null)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+
+# Filter: Bash only
+[ "$TOOL_NAME" = "Bash" ] || exit 0
+
+# Filter: git push only
+case "$COMMAND" in
+  *"git push"*) : ;;
+  *) exit 0 ;;
+esac
+
+# Override — env var (compat; may not reach from Claude Code harness per #2254)
+if [ "${SKIP_PRE_PUSH_SHELLCHECK:-}" = "1" ]; then
+  if [ -f "${CLAUDE_PROJECT_DIR:-.}/lib/trace-helper.sh" ]; then
+    # shellcheck disable=SC1091
+    source "${CLAUDE_PROJECT_DIR:-.}/lib/trace-helper.sh" 2>/dev/null || true
+    command -v trace_record >/dev/null 2>&1 \
+      && trace_record "pre-push-shellcheck" "override" "SKIP_PRE_PUSH_SHELLCHECK=1" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Override — state-marker bypass (#2254; agent-reachable from Claude Code
+# harness via Write tool when env prefix does not propagate). File check
+# fires on filesystem each invocation; no env dependency.
+_PROJECT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+if [ -f "$_PROJECT/state/markers/skip/pre-push-shellcheck.marker" ]; then
+  if [ -f "$_PROJECT/lib/trace-helper.sh" ]; then
+    # shellcheck disable=SC1091
+    source "$_PROJECT/lib/trace-helper.sh" 2>/dev/null || true
+    command -v trace_record >/dev/null 2>&1 \
+      && trace_record "pre-push-shellcheck" "override" "state-marker" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Fail-soft on missing binaries
+if ! command -v shellcheck >/dev/null 2>&1; then
+  echo "pre-push-shellcheck: shellcheck not installed; skipping scan" >&2
+  exit 0
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  echo "pre-push-shellcheck: jq not installed; skipping scan" >&2
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+cd "$PROJECT_DIR" || exit 0
+
+# Figure out which .sh files are going out
+UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null)
+if [ -z "$UPSTREAM" ]; then
+  UPSTREAM="origin/main"
+fi
+
+CHANGED_FILES=$(git diff --name-only "$UPSTREAM"..HEAD 2>/dev/null | grep -E '\.sh$' || true)
+
+if [ -z "$CHANGED_FILES" ]; then
+  exit 0
+fi
+
+# Only scan files that still exist (skip renamed / deleted)
+EXISTING_FILES=()
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  [ -f "$f" ] && EXISTING_FILES+=("$f")
+done <<< "$CHANGED_FILES"
+
+if [ "${#EXISTING_FILES[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# #2253 — consult install-written-paths lib. Files bassclef ships to
+# the adopter via `bassclef init` or `bassclef-sync` are not the
+# adopter's work; shellcheck findings in them should not BLOCK the
+# adopter's first push. Lib's `is_install_written_path` returns 0 only
+# when the path is in the manifest AND the current content_hash still
+# matches — adopter edits to install-written files mismatch the hash
+# and still get scanned.
+#
+# Fail-soft per @luminary michael-nygard — missing lib OR missing
+# accessor falls back to pre-cure scan behavior (BLOCK on findings).
+# The pre-cure BLOCK is better than a crash.
+# shellcheck disable=SC1091
+# Lib enables `set -u` on source. Guard the array ops below against
+# unbound-array semantics by scoping the lib under +u then restoring.
+set +u
+source "$PROJECT_DIR/lib/install-written-paths.sh" 2>/dev/null || true
+set +u  # lib may re-enable; keep +u for our own array ops
+if declare -f is_install_written_path >/dev/null 2>&1; then
+  FILTERED_FILES=()
+  for f in "${EXISTING_FILES[@]}"; do
+    if is_install_written_path "$f" 2>/dev/null; then
+      continue
+    fi
+    FILTERED_FILES+=("$f")
+  done
+  if [ "${#FILTERED_FILES[@]}" -eq 0 ]; then
+    exit 0
+  fi
+  EXISTING_FILES=("${FILTERED_FILES[@]}")
+fi
+
+# Run shellcheck on changed .sh files — exit non-zero means findings exist
+# (expected); do NOT fall back to "[]" on non-zero or the hook silently passes.
+FINDINGS_JSON=$(shellcheck --format=json --severity=warning "${EXISTING_FILES[@]}" 2>/dev/null)
+
+# Guard against malformed JSON (empty output or non-array)
+if [ -z "$FINDINGS_JSON" ] || ! echo "$FINDINGS_JSON" | jq -e 'type == "array"' >/dev/null 2>&1; then
+  FINDINGS_JSON="[]"
+fi
+
+COUNT=$(echo "$FINDINGS_JSON" | jq 'length' 2>/dev/null || echo "0")
+[ "$COUNT" = "0" ] && exit 0
+
+# Apply allowlist filter — reuse existing allowlist file
+ALLOWLIST="$PROJECT_DIR/.claude/hooks/shellcheck-allowlist.txt"
+ALLOW_FILTER="[]"
+if [ -f "$ALLOWLIST" ]; then
+  CANDIDATE=$(grep -v '^#' "$ALLOWLIST" | grep -v '^[[:space:]]*$' \
+    | jq -R -s -c 'split("\n") | map(select(length > 0))' 2>/dev/null || echo "[]")
+  if echo "$CANDIDATE" | jq -e 'type == "array"' >/dev/null 2>&1; then
+    ALLOW_FILTER="$CANDIDATE"
+  fi
+fi
+
+UNALLOWLISTED=$(echo "$FINDINGS_JSON" | jq --argjson allow "$ALLOW_FILTER" '
+  map(select(
+    ("SC" + (.code | tostring) + ":" + ((.file // "") | ltrimstr("./"))) as $key |
+    ([$key] | inside($allow)) | not
+  ))
+' 2>/dev/null || echo "[]")
+
+if ! echo "$UNALLOWLISTED" | jq -e 'type == "array"' >/dev/null 2>&1; then
+  UNALLOWLISTED="[]"
+fi
+
+UCOUNT=$(echo "$UNALLOWLISTED" | jq 'length' 2>/dev/null || echo "0")
+[ "$UCOUNT" = "0" ] && exit 0
+
+# BLOCK
+cat >&2 <<EOF
+
+🛑 pre-push-shellcheck — BLOCKED
+
+$UCOUNT un-allowlisted shellcheck finding(s) in files going out:
+
+EOF
+echo "$UNALLOWLISTED" | jq -r '.[] | "  \(.file):\(.line):\(.column) SC\(.code): \(.message)"' >&2
+cat >&2 <<EOF
+
+Resolution paths:
+  1. Fix the finding in each listed file (preferred — e.g. 'cd \"\$dir\" || exit')
+  2. Allowlist the SC<code>:<path> pair in .claude/hooks/shellcheck-allowlist.txt
+  3. Agent bypass — mkdir -p state/markers/skip && touch state/markers/skip/pre-push-shellcheck.marker
+  4. Shell bypass — SKIP_PRE_PUSH_SHELLCHECK=1 git push ...  (logged; may not propagate from agent harness per #2254)
+
+Per .claude/rules/defensive-bash.md + bassclef-upstream#2108.
+
+EOF
+exit 2