@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/.claude/hooks/pr-body-scrub-check.sh

@@ -0,0 +1,446 @@
+#!/bin/bash
+# tier: lite
+# install-class: project
+# PR-body scrub check — Rule 1 (jargon) + Rule 4 (operator-private +
+# strategic-deliberation) + Rule 5 (ADVISE-PHRASE advisory) + Rule 6
+# (Problem-section opener shape, bassclef#1178, advisory in V1).
+# Per bassclef#739 substrate-coherence CI extension.
+#
+# Rule 1: blocks PR if bassclef-internal jargon found in PR body.
+#   Jargon list: composer, primitive, tier-preset, load-bearing, blast radius,
+#   compose-with, scope-bounded, operationalize.
+#   Allowlist (per bassclef#763): substrate, bassclef, cameo, Studio, Band, bandleader.
+#
+# Rule 4: blocks PR if scrub criteria 1+2 violated per bassclef#787:
+#   Criterion 1 — no docs/operator-private/ path citations
+#   Criterion 2 — no operator-strategic deliberation framing
+#     (heuristics: "leap-of-faith", "LF[0-9]", "F-[A-Z][0-9]", "canvas walk surfaced",
+#      "audit finding F-", "persona divergence", "strategic pivot reasoning")
+#
+# Shared override: PR labeled `bassclef-internal-prose-ok` downgrades to advisory.
+#
+# Usage:
+#   bash pr-body-scrub-check.sh <pr-body-file>
+#
+# Optional env:
+#   PR_LABELS=label1,label2,...  — labels on the PR (newline OR comma separated)
+#   STRICT_MODE=1                — force blocking even with override label (testing)
+#
+# Exit codes:
+#   0 — pass (no findings, OR findings + override label present)
+#   1 — block (findings + no override)
+#   2 — usage error
+
+set +e
+
+BODY_FILE="${1:-}"
+if [ -z "$BODY_FILE" ] || [ ! -f "$BODY_FILE" ]; then
+  echo "usage: $0 <pr-body-file>" >&2
+  exit 2
+fi
+
+PR_LABELS="${PR_LABELS:-}"
+STRICT_MODE="${STRICT_MODE:-0}"
+
+# Normalize labels (newline or comma separated → lines)
+LABELS_NORMALIZED=$(echo "$PR_LABELS" | tr ',' '\n' | sed 's/^ *//;s/ *$//' | grep -v '^$' || true)
+
+# Check override label
+HAS_OVERRIDE=0
+if [ "$STRICT_MODE" != "1" ]; then
+  if echo "$LABELS_NORMALIZED" | grep -qx "bassclef-internal-prose-ok"; then
+    HAS_OVERRIDE=1
+  fi
+fi
+
+# Strip code blocks + inline backtick spans + URLs + bare file paths so they
+# don't trigger false positives (filenames, function names, etc. are technical
+# refs not prose).
+# Bare file path strip added per sunj-labs/bassclef-upstream#1581 — a file
+# path in a bullet list without backticks (e.g., `- standards/composer-foo.md`)
+# used to trip the jargon scan on substrings within the file name.
+# Path pattern matches known bassclef-substrate trees plus common extensions.
+SCRUBBED=$(awk '
+  BEGIN { in_code = 0 }
+  /^```/ { in_code = !in_code; next }
+  in_code { next }
+  { print }
+' "$BODY_FILE" \
+  | sed -E 's/`[^`]*`//g' \
+  | sed -E 's|https?://[^ )]+||g' \
+  | sed -E 's|\.claude/[A-Za-z0-9_./-]+||g' \
+  | sed -E 's|standards/[A-Za-z0-9_./-]+||g' \
+  | sed -E 's|lib/[A-Za-z0-9_./-]+||g' \
+  | sed -E 's|scripts/[A-Za-z0-9_./-]+||g' \
+  | sed -E 's|docs/[A-Za-z0-9_./-]+||g' \
+  | sed -E 's|chronicle/[A-Za-z0-9_./-]+||g' \
+  | sed -E 's|presence/[A-Za-z0-9_./-]+||g' \
+  | sed -E 's|templates/[A-Za-z0-9_./-]+||g' \
+  | sed -E 's|architecture/[A-Za-z0-9_./-]+||g' \
+  | sed -E 's|state/[A-Za-z0-9_./-]+||g')
+
+# === Rule 1 — jargon detection ===
+# Allowlist per bassclef#763: substrate, bassclef, cameo, Studio, Band, bandleader
+# (Excluded from the blocking list even though "substrate" appears in /kiss table.)
+#
+# Per bassclef#907 Part 1: BLOCK terms read from standards/bassclef-internal-jargon.md
+# (single source of truth shared with /kiss skill + pre-push hook). Falls back to
+# hardcoded list if standards file missing (defensive backward compat).
+SCRIPT_DIR_PR_SCRUB="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+STANDARDS_FILE="${KISS_STANDARDS_FILE:-${SCRIPT_DIR_PR_SCRUB}/../../standards/bassclef-internal-jargon.md}"
+
+# Surface-context flag (bassclef#1241 WU-2). When set to "title" or "commit",
+# also read BLOCK-title terms (surface-specific blocking). Unset or "body" =
+# legacy behavior (BLOCK terms only, no BLOCK-title).
+SCRUB_SURFACE="${SCRUB_SURFACE:-body}"
+
+# awk extractor (shared) — strips parenthetical context ` (...)` from term column
+# at parse time so rows like `seed (verb)` extract as `seed`. Robust against
+# terms ending in `:` (e.g., `substrate-defect:`) via the `:?` in the term regex.
+extract_terms() {
+  local tier="$1"
+  local file="$2"
+  awk -F'|' -v tier="$tier" '
+    {
+      # Build a regex that matches the tier exactly at the end of line
+      tier_pat = " " tier " *\\|$"
+      if ($0 ~ "^\\| [a-zA-Z0-9][a-zA-Z0-9 :+./-]* *\\|" && $0 ~ tier_pat) {
+        term = $2
+        sub(/^ +/, "", term)
+        sub(/ +$/, "", term)
+        # Strip parenthetical context: "term (note)" → "term"
+        sub(/ +\(.*\)$/, "", term)
+        print term
+      }
+    }
+  ' "$file"
+}
+
+if [ -f "$STANDARDS_FILE" ]; then
+  # Read BLOCK-tier terms (fire on all surfaces)
+  JARGON_TERMS=()
+  while IFS= read -r line; do
+    [ -n "$line" ] && JARGON_TERMS+=("$line")
+  done < <(extract_terms "BLOCK" "$STANDARDS_FILE")
+
+  # Read BLOCK-title terms only when surface is title or commit
+  if [ "$SCRUB_SURFACE" = "title" ] || [ "$SCRUB_SURFACE" = "commit" ]; then
+    while IFS= read -r line; do
+      [ -n "$line" ] && JARGON_TERMS+=("$line")
+    done < <(extract_terms "BLOCK-title" "$STANDARDS_FILE")
+  fi
+
+  if [ ${#JARGON_TERMS[@]} -eq 0 ]; then
+    # Empty result (malformed standards file) → fall through to backward-compat list
+    JARGON_TERMS=(
+      "composer"
+      "primitive"
+      "tier-preset"
+      "load-bearing"
+      "blast radius"
+      "compose-with"
+      "scope-bounded"
+      "operationalize"
+    )
+  fi
+else
+  # Backward compat fallback
+  JARGON_TERMS=(
+    "composer"
+    "primitive"
+    "tier-preset"
+    "load-bearing"
+    "blast radius"
+    "compose-with"
+    "scope-bounded"
+    "operationalize"
+  )
+fi
+
+JARGON_FINDINGS=""
+JARGON_COUNT=0
+for term in "${JARGON_TERMS[@]}"; do
+  # Soft-boundary matcher (bassclef#1241 WU-2):
+  # - Terms ending in alphanumeric use word-boundary (\b) — backward compat
+  # - Terms ending in non-alphanumeric (e.g., `substrate-defect:`) use a
+  #   character-class boundary that treats hyphen, underscore, and alnum
+  #   as "in-word" — so `substrate-defect:` matches at "start of token"
+  #   contexts (start of line, after whitespace, etc.)
+  last_char="${term: -1}"
+  first_char="${term:0:1}"
+  if [[ "$last_char" =~ [a-zA-Z0-9] ]] && [[ "$first_char" =~ [a-zA-Z0-9] ]]; then
+    pat="\\b${term}\\b"
+  else
+    # At least one boundary is non-alnum — use soft boundary
+    prefix='(^|[^[:alnum:]_-])'
+    suffix='([^[:alnum:]_-]|$)'
+    [[ "$first_char" =~ [a-zA-Z0-9] ]] && prefix='\b'
+    [[ "$last_char" =~ [a-zA-Z0-9] ]] && suffix='\b'
+    pat="${prefix}${term}${suffix}"
+  fi
+  count=$(echo "$SCRUBBED" | grep -ioE "$pat" | wc -l | tr -d ' ')
+  if [ "$count" -gt 0 ]; then
+    JARGON_FINDINGS="${JARGON_FINDINGS}- \`${term}\` (${count}x)"$'\n'
+    JARGON_COUNT=$((JARGON_COUNT + count))
+  fi
+done
+
+# === Rule 4 Criterion 1 — operator-private path citations ===
+# Read from raw body file — SCRUBBED strips bare file paths (bassclef-upstream#1581)
+# which would mask operator-private path citations. Rule 4 checks all citations
+# regardless of code-block or path context — leaks are leaks.
+PATH_FINDINGS=""
+PATH_HITS=$(cat "$BODY_FILE" | grep -oE 'docs/operator-private/[A-Za-z0-9_./-]+' | sort -u || true)
+PATH_COUNT=0
+if [ -n "$PATH_HITS" ]; then
+  while IFS= read -r path; do
+    [ -z "$path" ] && continue
+    PATH_FINDINGS="${PATH_FINDINGS}- \`${path}\`"$'\n'
+    PATH_COUNT=$((PATH_COUNT + 1))
+  done <<< "$PATH_HITS"
+fi
+
+# === Rule 4 Criterion 2 — operator-strategic deliberation framing ===
+# Heuristics that signal strategic deliberation in PR bodies:
+#   - "leap-of-faith" / "leap of faith"
+#   - "LF[0-9]" / "LF-[0-9]"   (e.g., LF1, LF-6)
+#   - "F-[A-Z][0-9]"           (e.g., F-D9.1) — audit finding IDs are fine to cite
+#                              by ID, but ONLY by ID without exposition.
+#                              We don't flag F-X.Y refs themselves; we flag the
+#                              EXPLANATORY framing around them.
+#   - "canvas walk surfaced"   (canvas analysis exposition)
+#   - "audit finding"          (only flagged if appears with multi-sentence framing)
+#   - "persona divergence"     (operator-strategic analysis)
+#   - "strategic pivot"        (strategic reasoning)
+#   - "IP-protection-vs"       (specific pivot vocabulary)
+#   - "riskiest assumption"    (canvas-derived strategic vocabulary)
+DELIB_PATTERNS=(
+  "leap[ -]of[ -]faith"
+  "\bLF-?[0-9]+\b"
+  "canvas walk surfaced"
+  "persona divergence"
+  "strategic pivot"
+  "IP-protection-vs"
+  "riskiest assumption"
+)
+
+DELIB_FINDINGS=""
+DELIB_COUNT=0
+for pattern in "${DELIB_PATTERNS[@]}"; do
+  hits=$(echo "$SCRUBBED" | grep -iEc "$pattern" || true)
+  if [ "$hits" -gt 0 ]; then
+    DELIB_FINDINGS="${DELIB_FINDINGS}- pattern \`${pattern}\` (${hits}x)"$'\n'
+    DELIB_COUNT=$((DELIB_COUNT + hits))
+  fi
+done
+
+# === Rule 5 — phrase-shaped substrate-speak (ADVISORY ONLY per bassclef#915) ===
+# Word-shaped Rule 1 catches individual jargon terms. Compound noun-phrases
+# pass Rule 1 (each individual word is plain) but read as substrate-internal.
+# Phrases are read from standards file ADVISE-PHRASE tier. Advisory only —
+# emits CI annotation, does not block. bassclef#915 V2 considers promoting
+# to blocking after operator-feedback cycle.
+PHRASE_TERMS=()
+if [ -f "$STANDARDS_FILE" ]; then
+  while IFS= read -r line; do
+    PHRASE_TERMS+=("$line")
+  done < <(awk -F'|' '
+    /^\| [a-zA-Z]/ && /ADVISE-PHRASE *\|$/ {
+      gsub(/^ +| +$/, "", $2)
+      print $2
+    }
+  ' "$STANDARDS_FILE")
+fi
+
+PHRASE_FINDINGS=""
+PHRASE_COUNT=0
+for phrase in "${PHRASE_TERMS[@]}"; do
+  [ -z "$phrase" ] && continue
+  # Case-insensitive plain substring match (phrases may include hyphens/spaces)
+  count=$(echo "$SCRUBBED" | grep -io -- "${phrase}" | wc -l | tr -d ' ')
+  if [ "$count" -gt 0 ]; then
+    PHRASE_FINDINGS="${PHRASE_FINDINGS}- \`${phrase}\` (${count}x)"$'\n'
+    PHRASE_COUNT=$((PHRASE_COUNT + count))
+  fi
+done
+
+# === Rule 6 — Problem section opener (bassclef#1178, ADVISORY) ===
+# Per bassclef#1178: PR body should open with **Problem (≤500 chars):**
+# followed by --- and ## Goal. Advisory in V1; may flip to blocking after
+# adopters get used to the new shape.
+PROBLEM_PRESENT=0
+if grep -qE '^\*\*Problem' "$BODY_FILE"; then
+  PROBLEM_PRESENT=1
+fi
+
+# === Rule 7 — Closes-keyword check (bassclef#974, ADVISORY) ===
+# When title carries feat(#NNN): or fix(#NNN): pattern, body should carry
+# Closes / Fixes / Resolves keyword so GitHub auto-closes the ticket on
+# merge. Ticket state and shipped state can otherwise drift silently.
+# Reads $PR_TITLE env var (passed by pre-gh-pr-body-scrub.sh wrapper).
+# Advisory in V1; may flip to blocking after calibration.
+CLOSES_ADVISORY=""
+PR_TITLE="${PR_TITLE:-}"
+if [ -n "$PR_TITLE" ]; then
+  TITLE_TICKET=$(echo "$PR_TITLE" | grep -oE '(feat|fix)\((bassclef)?#[0-9]+\)' | grep -oE '#[0-9]+' | head -1)
+  if [ -n "$TITLE_TICKET" ]; then
+    if ! grep -qiE "(closes|fixes|resolves)[[:space:]]+$TITLE_TICKET" "$BODY_FILE"; then
+      CLOSES_ADVISORY="title carries \`${TITLE_TICKET}\` in feat/fix pattern but body has no \`Closes ${TITLE_TICKET}\` / \`Fixes ${TITLE_TICKET}\` / \`Resolves ${TITLE_TICKET}\` keyword. Without a closing keyword in the body, GitHub will not auto-close the ticket on merge — the ticket stays open even after the PR ships. Add \`Closes ${TITLE_TICKET}\` to the body Refs section, or use \`SKIP_PRE_GH_PR_BODY_SCRUB=1\` if this PR intentionally does not close the ticket."
+    fi
+  fi
+fi
+
+LEGACY_SHAPE=0
+if grep -qE '^\*\*Flash' "$BODY_FILE" && grep -qE '^\*\*Tweet' "$BODY_FILE"; then
+  LEGACY_SHAPE=1
+fi
+
+SHAPE_ADVISORY=""
+if [ "$PROBLEM_PRESENT" = "0" ]; then
+  if [ "$LEGACY_SHAPE" = "1" ]; then
+    SHAPE_ADVISORY="legacy Flash + Tweet opener present; bassclef#1178 retired the pair in favor of a single Problem section. Use /state-a-problem brief to draft the new shape (runs /kiss --grade10 inline by default)."
+  else
+    SHAPE_ADVISORY="no Problem section detected at opener. Per .claude/rules/pr-body-shape.md (bassclef#1178), feature-scope PRs open with **Problem (≤500 chars):** drafted by /state-a-problem brief. Trivial fix PRs (under 3 files, no SKILL.md or rule changes) may skip."
+  fi
+fi
+
+# === Report ===
+TOTAL_FINDINGS=$((JARGON_COUNT + PATH_COUNT + DELIB_COUNT))
+
+if [ "$TOTAL_FINDINGS" -eq 0 ]; then
+  if [ "$PHRASE_COUNT" -eq 0 ] && [ -z "$SHAPE_ADVISORY" ] && [ -z "$CLOSES_ADVISORY" ]; then
+    echo "PASS — PR body clean (Rule 1 + Rule 4 + Rule 5 + Rule 6 + Rule 7 scrub criteria)"
+    exit 0
+  fi
+  # Rule 1 + Rule 4 clean, but Rule 5 phrase hits or Rule 6 shape note or Rule 7 closes advisory — emit + exit 0
+  echo "PASS — PR body clean (Rule 1 + Rule 4). Advisory hits below."
+  echo ""
+  if [ "$PHRASE_COUNT" -gt 0 ]; then
+    echo "## Rule 5 — phrase-shaped substrate-speak (${PHRASE_COUNT} matches, advisory only)"
+    echo ""
+    echo "$PHRASE_FINDINGS"
+    echo ""
+    echo "Compound substrate-speak passes word-shaped Rule 1 but reads as substrate-internal."
+    echo "Plain alternatives per standards/bassclef-internal-jargon.md ADVISE-PHRASE tier:"
+    echo "- \`pipeline altitude\` → \`pipeline\` (drop altitude)"
+    echo "- \`atomic discipline\` → \`one-PR-per-concern\` (or \`one concern per PR\`)"
+    echo "- \`operator-attention\` / \`operator-attended\` → \`operator review\` / \`operator-reviewed\`"
+    echo "- \`honest case\` → \`valid case\` (or omit)"
+    echo "- \`forcing function\` → \`what forces the answer\`"
+    echo ""
+    echo "Advisory only — does not block merge. Per bassclef#915."
+    echo ""
+  fi
+  if [ -n "$SHAPE_ADVISORY" ]; then
+    echo "## Rule 6 — Problem-section opener shape (advisory)"
+    echo ""
+    echo "${SHAPE_ADVISORY}"
+    echo ""
+    echo "Per .claude/rules/pr-body-shape.md (bassclef#1178). Advisory only in V1."
+    echo ""
+  fi
+  if [ -n "$CLOSES_ADVISORY" ]; then
+    echo "## Rule 7 — ticket-close keyword (advisory)"
+    echo ""
+    echo "${CLOSES_ADVISORY}"
+    echo ""
+    echo "Per .claude/rules/pr-body-shape.md (bassclef#974). Advisory only in V1."
+    echo ""
+  fi
+  exit 0
+fi
+
+# Findings exist — report
+echo "==============================================="
+echo "PR-body scrub findings (bassclef#739 Rule 1 + Rule 4)"
+echo "==============================================="
+echo ""
+
+if [ -n "$JARGON_FINDINGS" ]; then
+  echo "## Rule 1 — bassclef-internal jargon (${JARGON_COUNT} matches)"
+  echo ""
+  echo "$JARGON_FINDINGS"
+  echo ""
+  echo "Plain-English alternatives per /kiss substitution table:"
+  echo "- \`composer\` → \`runs\` or \`chains\` or \`combines\`"
+  echo "- \`primitive\` → \`building block\`"
+  echo "- \`tier-preset\` → \`preset\` or \`size\`"
+  echo "- \`load-bearing\` → \`required\` or \`essential\`"
+  echo "- \`blast radius\` → \`impact\` or \`what it can break\`"
+  echo "- \`compose-with\` → \`uses\` or \`builds on\`"
+  echo "- \`scope-bounded\` → \`small\` or \`tight\`"
+  echo "- \`operationalize\` → \`do\` or \`ship\`"
+  if [ "$SCRUB_SURFACE" = "title" ] || [ "$SCRUB_SURFACE" = "commit" ]; then
+    echo "- \`substrate-defect:\` (as title or commit prefix) → \`fix:\` (per commit-conventions.md — use the 8 standard types)"
+  fi
+  echo ""
+fi
+
+if [ -n "$PATH_FINDINGS" ]; then
+  echo "## Rule 4 Criterion 1 — operator-private path citations (${PATH_COUNT} matches)"
+  echo ""
+  echo "$PATH_FINDINGS"
+  echo ""
+  echo "Operator-private paths are gitignored; citations point at files invisible"
+  echo "to public readers. Use stub framing per standards/pr-body-discipline.md:"
+  echo "  Avoid: \`per docs/operator-private/strategy/...md\`"
+  echo "  Use:   \`per internal strategic decision\`"
+  echo ""
+fi
+
+if [ -n "$DELIB_FINDINGS" ]; then
+  echo "## Rule 4 Criterion 2 — operator-strategic deliberation framing (${DELIB_COUNT} matches)"
+  echo ""
+  echo "$DELIB_FINDINGS"
+  echo ""
+  echo "PR bodies frame mechanically: what the PR does + which acceptance criterion"
+  echo "it closes + which downstream work it unblocks. Strategic deliberation belongs"
+  echo "in operator-private canvas/audit, not public PR body."
+  echo "  Avoid: \"LF1 Morgan-as-gatekeeper riskiest assumption analysis\""
+  echo "  Use:   \"Closes audit finding F-D9.1 (README hedges audience).\""
+  echo ""
+fi
+
+if [ -n "$PHRASE_FINDINGS" ]; then
+  echo "## Rule 5 — phrase-shaped substrate-speak (${PHRASE_COUNT} matches, ADVISORY)"
+  echo ""
+  echo "$PHRASE_FINDINGS"
+  echo ""
+  echo "Compound substrate-speak passes word-shaped Rule 1 but reads as substrate-internal."
+  echo "Plain alternatives per standards/bassclef-internal-jargon.md ADVISE-PHRASE tier."
+  echo "Advisory only — does not contribute to block decision (per bassclef#915)."
+  echo ""
+fi
+
+if [ -n "$SHAPE_ADVISORY" ]; then
+  echo "## Rule 6 — Problem-section opener shape (advisory)"
+  echo ""
+  echo "${SHAPE_ADVISORY}"
+  echo ""
+  echo "Per .claude/rules/pr-body-shape.md (bassclef#1178). Advisory only in V1."
+  echo ""
+fi
+
+if [ -n "$CLOSES_ADVISORY" ]; then
+  echo "## Rule 7 — ticket-close keyword (advisory)"
+  echo ""
+  echo "${CLOSES_ADVISORY}"
+  echo ""
+  echo "Per .claude/rules/pr-body-shape.md (bassclef#974). Advisory only in V1."
+  echo ""
+fi
+
+echo "==============================================="
+echo "Override path: add label \`bassclef-internal-prose-ok\` to the PR."
+echo "This downgrades the check to advisory + lets the PR merge."
+echo "Use sparingly; the label indicates conscious operator choice to keep"
+echo "bassclef-internal vocabulary or operator-private framing in this PR."
+echo "==============================================="
+
+if [ "$HAS_OVERRIDE" -eq 1 ]; then
+  echo ""
+  echo "ADVISORY — \`bassclef-internal-prose-ok\` label present; downgraded from blocking."
+  exit 0
+fi
+
+exit 1

package/dist/lite/.claude/hooks/pre-commit-identifier-leak-scrub.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# PreToolUse: Bash
+# andon-allow: [A-Za-z][A-Za-z0-9]*-MacBook-(Air|Pro)
+# andon-allow: /Users/[a-z][a-z0-9._-]+
+# andon-allow: /home/[a-z][a-z0-9._-]+
+#
+# pre-commit-identifier-leak-scrub.sh — Pre-commit hook that BLOCKs commits
+# carrying operator machine identifiers in commit messages or staged content.
+#
+# Pattern classes:
+#   1. Hostname shapes — [A-Za-z]+-MacBook-(Air|Pro), DESKTOP-[A-Z0-9]+,
+#      *-server-*, *-desktop-* (macOS + Windows + Linux common patterns)
+#   2. Absolute paths — /Users/<name>, /home/<name>
+#
+# Fires on PreToolUse Bash matcher when tool_input.command starts with
+# `git commit`. Non-git-commit commands pass through cleanly.
+#
+# Failure modes covered:
+#   - R-N1 (Nygard) grep missing → fail-soft exit 0 with stderr warning
+#   - R-L1 (Linus) legitimate content → SKIP_IDENTIFIER_LEAK_SCRUB=1 bypass
+#   - R-F1 (Feathers) git commit -F file → reads assembled COMMIT_EDITMSG
+#     (deferred: current hook parses -m arg only; -F support in V2)
+#
+# Closes sunj-labs/bassclef#1471 item 5b.
+#
+# Anchors:
+#   @luminary jerome-saltzer-and-michael-schroeder — complete mediation
+#   @luminary linus-torvalds — adopter contract per ADR-031
+#   @luminary michael-feathers — characterization tests pin behavior
+#   @luminary michael-nygard — fail-soft stability
+
+set -u
+
+# Override path — logged via trace-helper per bassclef discipline
+if [ "${SKIP_IDENTIFIER_LEAK_SCRUB:-0}" = "1" ]; then
+  echo "  identifier-leak-scrub: SKIP_IDENTIFIER_LEAK_SCRUB=1 — bypassing scrub" >&2
+  exit 0
+fi
+
+# R-N1 fail-soft: if grep is unavailable, warn to stderr and exit 0
+if ! command -v grep >/dev/null 2>&1; then
+  echo "  identifier-leak-scrub: warn — grep unavailable; skipping scrub" >&2
+  exit 0
+fi
+
+# Read the Claude Code Bash tool JSON from stdin
+INPUT=$(cat 2>/dev/null || echo "")
+if [ -z "$INPUT" ]; then
+  exit 0
+fi
+
+# Extract command (fallback grep if jq unavailable — jq is standard on bassclef machines)
+if command -v jq >/dev/null 2>&1; then
+  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null || echo "")
+else
+  # Bash-native extraction: find "command":"..." in the JSON blob
+  COMMAND=$(echo "$INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/^"command"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
+fi
+
+# Pass through non-git-commit commands
+if ! echo "$COMMAND" | grep -qE '^[[:space:]]*git[[:space:]]+commit'; then
+  exit 0
+fi
+
+# Pattern set — loaded from single source of truth (bassclef-upstream#1461).
+# Same file scripts/release-to-bassclef.sh andon scan reads — both gates share one truth.
+PATTERN_FILE="${PATTERN_FILE_OVERRIDE:-${CLAUDE_PROJECT_DIR:-.}/standards/identifier-leak-patterns.txt}"
+if [ -f "$PATTERN_FILE" ]; then
+  # Join non-comment lines with | into one grep -E pattern
+  IDENTIFIER_PATTERNS=$(grep -v '^#' "$PATTERN_FILE" 2>/dev/null | sed '/^$/d' | tr '\n' '|' | sed 's/|$//')
+  IDENTIFIER_PATTERNS="($IDENTIFIER_PATTERNS)"
+else
+  # Fallback if standards file missing (defensive; fail-soft to prior inline pattern)
+  IDENTIFIER_PATTERNS='([A-Za-z][A-Za-z0-9]*-MacBook-(Air|Pro)|DESKTOP-[A-Z0-9]{4,}|/Users/[a-z][a-z0-9._-]+|/home/[a-z][a-z0-9._-]+)'
+fi
+
+BLOCK_REASON=""
+BLOCK_MATCH=""
+
+# Check 1 — commit message text (parse -m "..." or -m '...' argument)
+MSG=$(echo "$COMMAND" | grep -oE '\-m[[:space:]]*("[^"]*"|'"'"'[^'"'"']*'"'"')' | head -1 | sed -E 's/^-m[[:space:]]*["'"'"']//' | sed -E 's/["'"'"']$//')
+if [ -n "$MSG" ]; then
+  MATCH=$(echo "$MSG" | grep -oE "$IDENTIFIER_PATTERNS" | head -1)
+  if [ -n "$MATCH" ]; then
+    BLOCK_REASON="commit message"
+    BLOCK_MATCH="$MATCH"
+  fi
+fi
+
+# Check 2 — staged content (git diff --cached, ADDED lines only)
+# Filter to '+' lines only so a commit that REMOVES a pre-existing leak
+# does not trip on the removed-content line. `+++` file headers stripped.
+# Per sunj-labs/bassclef-upstream#1575.
+if [ -z "$BLOCK_REASON" ]; then
+  STAGED_DIFF=$(git diff --cached 2>/dev/null | grep '^+' | grep -v '^+++' || echo "")
+  if [ -n "$STAGED_DIFF" ]; then
+    MATCH=$(echo "$STAGED_DIFF" | grep -oE "$IDENTIFIER_PATTERNS" | head -1)
+    if [ -n "$MATCH" ]; then
+      BLOCK_REASON="staged content"
+      BLOCK_MATCH="$MATCH"
+    fi
+  fi
+fi
+
+# BLOCK if any pattern matched
+if [ -n "$BLOCK_REASON" ]; then
+  cat >&2 <<EOF
+============================================
+🛑 IDENTIFIER LEAK — BLOCKED
+============================================
+
+Location: $BLOCK_REASON
+Pattern:  $BLOCK_MATCH
+
+Bassclef discipline (per CCF-3 + sunj-labs/bassclef#1471) forbids
+operator machine identifiers in committed artifacts. Detected patterns:
+
+  - Hostname shapes: X-MacBook-Air, X-MacBook-Pro, DESKTOP-XYZ, etc.
+  - Absolute paths: /Users/<name>, /home/<name>
+
+Resolution paths:
+  1. Rewrite the commit message or staged content to drop the identifier
+     - Replace machine names with placeholders like <machine> or the branch
+     - Replace absolute paths with relative paths or \$HOME references
+  2. Override (rare — for legitimate cases like DON'T-do-this documentation):
+     SKIP_IDENTIFIER_LEAK_SCRUB=1 git commit ...
+
+See .claude/rules/identifier-leak-prevention.md for full discipline.
+============================================
+EOF
+  exit 2
+fi
+
+# All clean — pass through
+exit 0