@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/.claude/hooks/file-rename-discipline-check.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# tier: lite
+# install-class: project
+# file-rename-discipline-check — PreToolUse hook that blocks `git commit`
+# Bash invocations when the staged changes delete a file under the
+# rule's scope without a matching entry in standards/file-renames.json.
+#
+# Per .claude/rules/file-rename-discipline.md — every file rename in
+# bassclef registers a map entry AND ships a fixture test. The rule's
+# methodology layer says do it; this hook is the mechanical layer that
+# fires on every commit.
+#
+# Why this exists: the 2026-06-21 rename of canonical-source-config-validate.sh
+# shipped without registering itself anywhere. POA's session on 2026-06-29
+# surfaced the gap eight days later. Bet 29e WU-9 shipped the cure; this
+# hook prevents the next rename from repeating the failure.
+#
+# Exit codes:
+#   0 — allow (non-matching Bash, no scoped deletions, all deletions registered, override)
+#   2 — block (one or more scoped deletions missing from the rename map)
+#
+# Override: SKIP_FILE_RENAME_DISCIPLINE=1 (logged via trace-helper)
+
+set +e
+
+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)
+
+# Only fire on Bash tool calls
+[ "$TOOL_NAME" = "Bash" ] || exit 0
+
+# Only fire on `git commit` invocations (not git status, not git diff, etc)
+case "$COMMAND" in
+  *"git commit"*) : ;;
+  *) exit 0 ;;
+esac
+
+# Skip via override (logged)
+if [ "${SKIP_FILE_RENAME_DISCIPLINE:-0}" = "1" ]; then
+  if [ -x ".claude/hooks/trace-helper.sh" ]; then
+    bash .claude/hooks/trace-helper.sh "file-rename-discipline" "skipped via SKIP_FILE_RENAME_DISCIPLINE=1" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Resolve the rename map (env-var override for tests + curl-pipe scenarios)
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+RENAME_MAP="${BASSCLEF_RENAME_MAP:-$REPO_ROOT/standards/file-renames.json}"
+
+# If the rename map does not exist on this repo, the hook is dormant.
+# (Adopter repos don't ship the map; only bassclef-upstream does.)
+[ -f "$RENAME_MAP" ] || exit 0
+
+# Read staged deletions. `git diff --cached --diff-filter=D --name-only`
+# lists files deleted in the staged change.
+DELETIONS=$(git diff --cached --diff-filter=D --name-only 2>/dev/null)
+[ -n "$DELETIONS" ] || exit 0
+
+# Scope filter — only check deletions under the rule's path list.
+SCOPED_PATHS=(
+  ".claude/hooks/"
+  ".claude/skills/"
+  ".claude/rules/"
+  ".claude/luminaries/"
+  ".claude/agents/"
+  "scripts/"
+  "lib/"
+  "standards/"
+  "presence/"
+  "architecture/decisions/"
+)
+
+# Build the list of registered old_names from the rename map.
+# Both the renames array AND the compat_shims_preserved list are
+# considered "registered" — the rule allows both shapes.
+REGISTERED_NAMES=$(jq -r '
+  ((.renames // [])[]?.old_name),
+  ((.compat_shims_preserved // [])[]?.old_name)
+' "$RENAME_MAP" 2>/dev/null | sort -u)
+
+# Walk the deletions; flag any scoped deletion whose basename is missing
+# from the registered list.
+UNREGISTERED=""
+while IFS= read -r path; do
+  [ -n "$path" ] || continue
+  # Scope filter: skip deletions outside the rule's paths
+  in_scope=0
+  for scope in "${SCOPED_PATHS[@]}"; do
+    case "$path" in
+      "$scope"*) in_scope=1; break ;;
+    esac
+  done
+  [ "$in_scope" = "1" ] || continue
+
+  base=$(basename "$path")
+  if ! echo "$REGISTERED_NAMES" | grep -qFx "$base"; then
+    UNREGISTERED="$UNREGISTERED  - $path (basename: $base)"$'\n'
+  fi
+done <<< "$DELETIONS"
+
+# No unregistered scoped deletions → allow
+[ -z "$UNREGISTERED" ] && exit 0
+
+# Block with a structured remediation message
+cat <<MSG >&2
+============================================
+🛑 FILE-RENAME DISCIPLINE — BLOCKED 🛑
+============================================
+
+The staged commit deletes one or more files under the rule's scope without
+a matching entry in standards/file-renames.json. Per .claude/rules/file-rename-discipline.md
+every file rename registers a map entry plus a fixture test.
+
+Unregistered deletions:
+$UNREGISTERED
+
+Three required moves:
+
+  1. Add an entry under \`.renames\` in standards/file-renames.json:
+
+       {
+         "old_name": "<basename-being-deleted>",
+         "new_name": "<basename-of-the-successor-file>",
+         "renamed_at": "$(date +%Y-%m-%d)",
+         "category": "<hook|skill|rule|agent|luminary|script|lib|standard|adr>"
+       }
+
+  2. Ship a fixture under .claude/hooks/tests/fixtures/adopter-$(date +%Y-%m-%d)-rename/
+     that mirrors the adopter state after the rename ships. The migrate
+     script's test suite reads the fixture; assertions pin the cure.
+
+  3. Cite the rename in the goal doc or chronicle for this commit.
+
+Compat-shim case — when the old name keeps working via a different
+mechanism (e.g., dispatcher's canonical-sync.sh via ADR-032 two-stage rocket):
+add the entry under \`.compat_shims_preserved\` instead, with a reason field.
+
+Override (logged via trace-helper):  SKIP_FILE_RENAME_DISCIPLINE=1 git commit ...
+
+Use only for migrating bulk content or emergency rescue; routine renames
+register the entry.
+
+============================================
+MSG
+
+exit 2

package/dist/lite/.claude/hooks/hook-classifier-canary.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: project
+# hook-classifier-canary.sh — advises author when a new hook lands
+# without any recognized wiring (settings.json / .github/workflows /
+# scripts/release-to-bassclef.sh / launchd header / sourced-lib
+# header). Fires at PreToolUse on Edit|Write against paths under
+# .claude/hooks/*.sh.
+#
+# Layer 4 cure for sunj-labs/bassclef-upstream#1163. Same class as
+# the hook-wire-on-author rule; extends discipline to catch mislabels
+# at author time — not release time.
+#
+# Anchors: @luminary saltzer-schroeder (complete mediation at earliest
+# cheap gate), @luminary david-parnas (canary hides classifier
+# vocabulary from author), @luminary michael-feathers (characterization
+# tests pin behavior at author boundary).
+#
+# Reads stdin JSON per Claude Code hook contract:
+#   { "tool_name": "Edit|Write", "tool_input": { "file_path": "..." } }
+#
+# Exit codes:
+#   0 — pass (V1 ADVISORY only writes to stderr; V2 may flip to BLOCK)
+#   2 — reserved for V2 BLOCK escalation
+#
+# Override:
+#   SKIP_HOOK_CLASSIFIER_CANARY=1  bypass; logged via trace-helper
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Override
+if [ "${SKIP_HOOK_CLASSIFIER_CANARY:-}" = "1" ]; then
+  TRACE_HELPER="$SCRIPT_DIR/trace-helper.sh"
+  if [ -f "$TRACE_HELPER" ]; then
+    # shellcheck disable=SC1090
+    source "$TRACE_HELPER" 2>/dev/null || true
+    trace_record "hook-classifier-canary" "skipped via SKIP_HOOK_CLASSIFIER_CANARY=1" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Read stdin JSON. If jq not available, degrade gracefully.
+INPUT=$(cat)
+if [ -z "$INPUT" ]; then
+  exit 0
+fi
+
+if command -v jq >/dev/null 2>&1; then
+  TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+else
+  # Fallback — crude sed parse
+  TOOL_NAME=$(echo "$INPUT" | sed -n 's/.*"tool_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+  FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+fi
+
+# Pass-through — non-Edit/Write tools
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# Pass-through — no file path
+[ -z "$FILE_PATH" ] && exit 0
+
+# Pass-through — path outside .claude/hooks/*.sh
+case "$FILE_PATH" in
+  */.claude/hooks/*.sh) ;;
+  *) exit 0 ;;
+esac
+
+# Pass-through — path is under .claude/hooks/tests/ or fixtures
+case "$FILE_PATH" in
+  */.claude/hooks/tests/*|*/.claude/hooks/*/tests/*) exit 0 ;;
+esac
+
+# Get bare hook name for classifier lookup
+HOOK_NAME=$(basename "$FILE_PATH")
+
+# Pass-through — this file exists on disk already (edit, not new)
+if [ -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Load classifier
+LIB="$REPO_ROOT/lib/mechanism-fidelity.sh"
+if [ ! -f "$LIB" ]; then
+  # Classifier lib missing — cannot advise; pass silently
+  exit 0
+fi
+# shellcheck disable=SC1090
+source "$LIB"
+
+# Ask classifier what pattern it detects for this hook name
+PATTERN=$(classify_hook_install_pattern "$HOOK_NAME" "$REPO_ROOT" 2>/dev/null)
+
+# Recognized patterns → pass
+case "$PATTERN" in
+  ci|launchd|lib|release)
+    exit 0
+    ;;
+esac
+
+# Standard means classifier could not place it AND file does not exist yet.
+# Check settings.json — hook may be wired for PreToolUse there.
+SETTINGS="$REPO_ROOT/.claude/settings.json"
+if [ -f "$SETTINGS" ] && grep -qF "$HOOK_NAME" "$SETTINGS" 2>/dev/null; then
+  exit 0
+fi
+
+# No recognized wiring signal found. Emit ADVISORY.
+cat >&2 <<EOF
+
+============================================
+🚨 hook-classifier-canary — ADVISORY
+============================================
+
+New hook detected:   $HOOK_NAME
+Author path:         $FILE_PATH
+
+The classifier at lib/mechanism-fidelity.sh does not recognize any
+wiring signal for this hook. If this ships as-is, the cold-adopter
+harness Shape d checks will flag it as DEAD-LETTER.
+
+Five remediation paths (pick one before commit):
+
+  1. settings.json wiring — add hook entry to .claude/settings.json
+     under PreToolUse/PostToolUse/SessionStart/Stop event matcher.
+     For hooks that fire on tool calls.
+
+  2. CI workflow — reference the hook name in a .github/workflows/*.yml
+     file. For hooks that fire on push/PR events.
+
+  3. Release script — reference the hook name in
+     scripts/release-to-bassclef.sh. For hooks that gate on /release
+     dispatch. Classifier returns "release".
+
+  4. launchd header — add "# Runs via launchd" (or "scheduled job" /
+     "cron job") to the hook's top-of-file comment block. For
+     scheduled jobs. Classifier returns "launchd".
+
+  5. Sourced-library header — add "# sourced by <caller>" to the
+     hook's top-of-file comment block. For helper libraries loaded
+     via source. Classifier returns "lib".
+
+If genuinely bypassing (rare): SKIP_HOOK_CLASSIFIER_CANARY=1 <command>
+
+Per rule: .claude/rules/hook-wire-on-author.md
+Per Layer 4 of: bassclef-upstream#1163
+============================================
+
+EOF
+
+# V1 — ADVISORY only. V2 may flip to exit 2 (BLOCK).
+exit 0

package/dist/lite/.claude/hooks/kiss-default-check.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+# tier: lite
+# install-class: project
+# kiss-default-check.sh — pre-push /kiss enforcement check
+# Per bassclef#907 Part 4.
+#
+# Reads a draft body file. Checks for BLOCK-tier bassclef-internal jargon
+# per standards/bassclef-internal-jargon.md. BLOCKs if jargon present and
+# no opt-out signal.
+#
+# Composes with .claude/hooks/pr-body-scrub-check.sh (CI-time enforcement).
+# This hook runs pre-push; the scrub hook runs at CI. Both read the same
+# BLOCK list from the standards source-of-truth.
+#
+# Usage:
+#   bash kiss-default-check.sh <body-file>
+#
+# Optional env:
+#   PR_LABELS=label1,label2,...           — labels on the PR (newline or comma separated)
+#   SKIP_KISS=1                           — operator opt-out for one invocation
+#   KISS_STANDARDS_FILE=<path>            — override standards file location (testing)
+#
+# Exit codes:
+#   0 — pass (no BLOCK terms found, OR opt-out signal present)
+#   1 — block (BLOCK terms found + no opt-out)
+#   2 — usage error
+
+set +e
+
+BODY_FILE="${1:-}"
+if [ -z "$BODY_FILE" ] || [ ! -f "$BODY_FILE" ]; then
+  echo "usage: $0 <body-file>" >&2
+  exit 2
+fi
+
+# Find the repo root + standards file
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+STANDARDS_FILE="${KISS_STANDARDS_FILE:-$REPO_ROOT/standards/bassclef-internal-jargon.md}"
+
+if [ ! -f "$STANDARDS_FILE" ]; then
+  # Try the bassclef-sync'd path (when run from a consumer repo)
+  STANDARDS_FILE="${HOME}/src/sunj-labs/bassclef/standards/bassclef-internal-jargon.md"
+fi
+
+if [ ! -f "$STANDARDS_FILE" ]; then
+  echo "kiss-default-check: standards file not found at $STANDARDS_FILE" >&2
+  echo "  set KISS_STANDARDS_FILE=<path> or skip this check" >&2
+  exit 2
+fi
+
+# Opt-out — env var
+if [ "${SKIP_KISS:-0}" = "1" ]; then
+  echo "kiss-default-check: SKIP_KISS=1 — skipped (logged)" >&2
+  exit 0
+fi
+
+# Opt-out — label
+PR_LABELS="${PR_LABELS:-}"
+LABELS_NORMALIZED=$(echo "$PR_LABELS" | tr ',' '\n' | sed 's/^ *//;s/ *$//' | grep -v '^$' || true)
+if echo "$LABELS_NORMALIZED" | grep -qx "bassclef-internal-prose-ok"; then
+  echo "kiss-default-check: bassclef-internal-prose-ok label — advisory mode" >&2
+  ADVISORY=1
+else
+  ADVISORY=0
+fi
+
+# Extract BLOCK terms from the standards table
+# The standards table has lines like: | term | plain-english | BLOCK |
+# Allows digits in the first column so terms like "12-pattern matcher"
+# (added under bassclef-upstream#101) are picked up.
+BLOCK_TERMS=$(awk -F'|' '
+  /^\| [a-zA-Z0-9-]+ / && /BLOCK *\|$/ {
+    gsub(/^ +| +$/, "", $2)
+    print $2
+  }
+' "$STANDARDS_FILE")
+
+if [ -z "$BLOCK_TERMS" ]; then
+  echo "kiss-default-check: no BLOCK terms found in standards file" >&2
+  exit 0
+fi
+
+# Strip code blocks + inline backtick spans + URLs so they don't trigger false positives
+SCRUBBED=$(awk '
+  BEGIN { in_code = 0 }
+  /^```/ { in_code = !in_code; next }
+  in_code { next }
+  { print }
+' "$BODY_FILE" | sed -E 's/`[^`]*`//g; s|https?://[^ )]+||g')
+
+# Check each BLOCK term
+FINDINGS=""
+FINDING_COUNT=0
+while IFS= read -r term; do
+  [ -z "$term" ] && continue
+  count=$(echo "$SCRUBBED" | grep -ioE "\\b${term}\\b" | wc -l | tr -d ' ')
+  if [ "$count" -gt 0 ]; then
+    FINDINGS="${FINDINGS}- \`${term}\` (${count}x)"$'\n'
+    FINDING_COUNT=$((FINDING_COUNT + count))
+  fi
+done <<< "$BLOCK_TERMS"
+
+if [ "$FINDING_COUNT" -eq 0 ]; then
+  echo "kiss-default-check: pass — no BLOCK terms in draft" >&2
+  exit 0
+fi
+
+# Report findings
+{
+  echo ""
+  echo "kiss-default-check: $FINDING_COUNT BLOCK-tier jargon term(s) found in draft body:"
+  echo ""
+  echo "$FINDINGS"
+  echo "Plain-English alternatives at: $STANDARDS_FILE"
+  echo ""
+  echo "Options:"
+  echo "  1. Run /kiss --grade11 on the draft and re-push"
+  echo "  2. Add label 'bassclef-internal-prose-ok' for advisory-only"
+  echo "  3. Set SKIP_KISS=1 for one-time bypass (logged)"
+  echo ""
+} >&2
+
+if [ "$ADVISORY" = "1" ]; then
+  echo "kiss-default-check: ADVISORY (label) — passing with warnings" >&2
+  exit 0
+fi
+
+exit 1

package/dist/lite/.claude/hooks/multi-tenancy-check.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# tier: lite
+# Multi-Tenancy Check — bassclef template.
+# Fires on Edit/Write of source files.
+# Warns when tenant-scoped patterns are missing.
+#
+# App repos should customize:
+#   TENANT_MODELS — pipe-separated list of tenant-scoped model names
+#   TENANT_CONTEXT_FN — function name that resolves tenant context
+#   TENANT_PARAMS_FN — function name for tenant-specific parameters
+#
+# Override by placing your own multi-tenancy-check.sh in .claude/hooks/
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.file_path // ""')
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""')
+
+# Skip non-source files
+if echo "$FILE_PATH" | grep -qE '\.(sh|json|md)$|/\.claude/|/memory/|/docs/|/scripts/|__tests__'; then
+  exit 0
+fi
+
+# === Customizable per project (override these in your app's copy) ===
+TENANT_CONTEXT_FN="${TENANT_CONTEXT_FN:-getTenantContext}"
+TENANT_PARAMS_FN="${TENANT_PARAMS_FN:-getTenantParams}"
+# Default: no models (app must define its own)
+TENANT_MODELS="${TENANT_MODELS:-}"
+
+# Skip if no tenant models defined (not a multi-tenant project)
+if [ -z "$TENANT_MODELS" ]; then
+  exit 0
+fi
+
+WARNINGS=""
+
+# Check 1: Hardcoded numeric thresholds that should use params facade
+if echo "$CONTENT" | grep -qE '[0-9]{3,}\.?[0-9]*\.?[0-9]*' ; then
+  if echo "$CONTENT" | grep -qE '_FLOOR|_CEILING|_THRESHOLD|_LIMIT|_MIN|_MAX'; then
+    if ! echo "$CONTENT" | grep -q "$TENANT_PARAMS_FN"; then
+      WARNINGS="${WARNINGS}
+MULTI-TENANCY: Possible hardcoded threshold detected.
+    Use ${TENANT_PARAMS_FN}() instead of hardcoded values.
+    Financial and geographic thresholds must flow through
+    the tenant params facade for multi-tenant readiness."
+    fi
+  fi
+fi
+
+# Check 2: Prisma queries on tenant-scoped models without context
+if echo "$CONTENT" | grep -qiE "prisma\.(${TENANT_MODELS})\.(findMany|findFirst|create|update|delete)" ; then
+  if ! echo "$CONTENT" | grep -q "$TENANT_CONTEXT_FN"; then
+    WARNINGS="${WARNINGS}
+MULTI-TENANCY: Query on tenant-scoped model without ${TENANT_CONTEXT_FN}().
+    Tenant-scoped models must be filtered by tenant/user context.
+    Use ${TENANT_CONTEXT_FN}() and filter appropriately."
+  fi
+fi
+
+# Check 3: API routes missing tenant context
+if echo "$FILE_PATH" | grep -qE 'src/app/api/.*route\.ts'; then
+  if echo "$CONTENT" | grep -qE 'export async function (GET|POST|PATCH|DELETE|PUT)'; then
+    if ! echo "$CONTENT" | grep -q "$TENANT_CONTEXT_FN"; then
+      WARNINGS="${WARNINGS}
+MULTI-TENANCY: API route handler without ${TENANT_CONTEXT_FN}().
+    All API routes touching tenant-scoped data must resolve
+    tenant context. Even GET routes need this for data isolation."
+    fi
+  fi
+fi
+
+if [ -n "$WARNINGS" ]; then
+  echo "============================================"
+  echo "MULTI-TENANCY GUARDRAIL"
+  echo "============================================"
+  echo "$WARNINGS"
+  echo ""
+  echo "These are WARNs, not BLOCKs. If this is intentional"
+  echo "(e.g., platform-wide data), proceed."
+  echo "If tenant-scoped, add the missing context/facade."
+  echo "============================================"
+fi
+
+exit 0