@thebassclef/lite 1.1.1 → 1.2.0-alpha.1

package/dist/cli.cjs

@@ -318,6 +318,12 @@ const GENERATED_BY = "@thebassclef/lite";
 function manifestTemplate(input) {
   const value = {
     schema_version: MANIFEST_SHAPE_VERSION,
+    // Top-level `version` — read by the v0.45.0 npm-version-drift hook
+    // (fragment 91 under session-reflection) via lib/npm-version-check.sh
+    // `jq -r '.version // ""' "$manifest"`. Duplicates
+    // $bassclef.generated_by_version on purpose — the hook does not walk
+    // into $bassclef. Per bassclef-upstream#1749.
+    version: input.pkgVersion,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: MANIFEST_SCHEMA_VERSION,
@@ -1076,13 +1082,13 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, say
   );
   const copiedCount = copiedHookEntries.length;
   const declaredCount = result.hookCount;
-  const failedCount = result.refused.length + result.errored.length;
+  const erroredCount = result.errored.length;
   const userScope = copiedHookEntries.filter((e) => e.scope === "user").length;
   const projectScope = copiedHookEntries.filter((e) => e.scope === "project").length;
   const scopeSuffix = userScope + projectScope > 0 ? ` ${projectScope} in <repo>/${HOOKS_SUBPATH.replace(/\/$/, "")}, ${userScope} in ~/${HOOKS_SUBPATH.replace(/\/$/, "")}.` : "";
-  if (failedCount > 0) {
+  if (erroredCount > 0) {
     say(
-      `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix} ${failedCount} failed — see errors above. Rerun bassclef init to retry.
+      `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix} ${erroredCount} failed — see errors above. Rerun bassclef init to retry.
 `
     );
   } else {
@@ -1151,10 +1157,12 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, say
 `
     );
   }
-  say(
-    `bassclef init: ${result.refused.length} files refused (path collision).` + (result.refused.length > 0 ? ` Use --force to overwrite existing files.` : ``) + `
+  if (result.refused.length > 0) {
+    say(
+      `bassclef init: ${result.refused.length} files refused (path collision). Use --force to overwrite existing files.
 `
-  );
+    );
+  }
   if (verbose && result.erroredMessages) {
     for (const msg of result.erroredMessages) {
       process.stderr.write(`  substrate: ${msg}
@@ -2011,6 +2019,12 @@ Proceed?`,
   const errored = copyResult.errored;
   const newManifest = {
     schema_version: MANIFEST_SHAPE_VERSION,
+    // Top-level `.version` — read by the v0.45.0 npm-version-drift hook
+    // (fragment 91 under session-reflection) via lib/npm-version-check.sh
+    // `jq -r '.version // ""' "$manifest"`. Duplicates
+    // $bassclef.generated_by_version on purpose — the hook does not walk
+    // into $bassclef. Per bassclef-upstream#1749; bassclef-cli#129.
+    version: index.version,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: "0.1.0",
@@ -2178,6 +2192,9 @@ Run \`bassclef migrate --help\` for migrate options + the upgrade paths.
 Version: ${index.version}
 Docs:    https://github.com/sunj-labs/bassclef-cli
 `;
+for (const stream of [process.stdout, process.stderr]) {
+  stream._handle?.setBlocking?.(true);
+}
 async function main(argv) {
   const first = argv[0];
   if (first === void 0 || first === "--help" || first === "-h" || first === "help") {

package/dist/cli.js

@@ -295,6 +295,12 @@ const GENERATED_BY = "@thebassclef/lite";
 function manifestTemplate(input) {
   const value = {
     schema_version: MANIFEST_SHAPE_VERSION,
+    // Top-level `version` — read by the v0.45.0 npm-version-drift hook
+    // (fragment 91 under session-reflection) via lib/npm-version-check.sh
+    // `jq -r '.version // ""' "$manifest"`. Duplicates
+    // $bassclef.generated_by_version on purpose — the hook does not walk
+    // into $bassclef. Per bassclef-upstream#1749.
+    version: input.pkgVersion,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: MANIFEST_SCHEMA_VERSION,
@@ -1053,13 +1059,13 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, say
   );
   const copiedCount = copiedHookEntries.length;
   const declaredCount = result.hookCount;
-  const failedCount = result.refused.length + result.errored.length;
+  const erroredCount = result.errored.length;
   const userScope = copiedHookEntries.filter((e) => e.scope === "user").length;
   const projectScope = copiedHookEntries.filter((e) => e.scope === "project").length;
   const scopeSuffix = userScope + projectScope > 0 ? ` ${projectScope} in <repo>/${HOOKS_SUBPATH.replace(/\/$/, "")}, ${userScope} in ~/${HOOKS_SUBPATH.replace(/\/$/, "")}.` : "";
-  if (failedCount > 0) {
+  if (erroredCount > 0) {
     say(
-      `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix} ${failedCount} failed — see errors above. Rerun bassclef init to retry.
+      `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix} ${erroredCount} failed — see errors above. Rerun bassclef init to retry.
 `
     );
   } else {
@@ -1128,10 +1134,12 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, say
 `
     );
   }
-  say(
-    `bassclef init: ${result.refused.length} files refused (path collision).` + (result.refused.length > 0 ? ` Use --force to overwrite existing files.` : ``) + `
+  if (result.refused.length > 0) {
+    say(
+      `bassclef init: ${result.refused.length} files refused (path collision). Use --force to overwrite existing files.
 `
-  );
+    );
+  }
   if (verbose && result.erroredMessages) {
     for (const msg of result.erroredMessages) {
       process.stderr.write(`  substrate: ${msg}
@@ -1988,6 +1996,12 @@ Proceed?`,
   const errored = copyResult.errored;
   const newManifest = {
     schema_version: MANIFEST_SHAPE_VERSION,
+    // Top-level `.version` — read by the v0.45.0 npm-version-drift hook
+    // (fragment 91 under session-reflection) via lib/npm-version-check.sh
+    // `jq -r '.version // ""' "$manifest"`. Duplicates
+    // $bassclef.generated_by_version on purpose — the hook does not walk
+    // into $bassclef. Per bassclef-upstream#1749; bassclef-cli#129.
+    version,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: "0.1.0",
@@ -2155,6 +2169,9 @@ Run \`bassclef migrate --help\` for migrate options + the upgrade paths.
 Version: ${version}
 Docs:    https://github.com/sunj-labs/bassclef-cli
 `;
+for (const stream of [process.stdout, process.stderr]) {
+  stream._handle?.setBlocking?.(true);
+}
 async function main(argv) {
   const first = argv[0];
   if (first === void 0 || first === "--help" || first === "-h" || first === "help") {

package/dist/index.cjs

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.1.1";
+const version = "1.2.0-alpha.1";
 export {
   version
 };

package/dist/lite/.claude/bassclef-configs.jsonc

@@ -0,0 +1,56 @@
+// tier: lite
+// bassclef adopter config — tune substrate rules from one file.
+// Reference schema: standards/bassclef-configs-schema.md
+// Every block below matches what a substrate rule reads. Values shown
+// are the defaults; delete a block and the default kicks in.
+{
+  // What your project runs. Frontend framework the /shadcn-first and
+  // /new-dependency-check rules key off. Common values: "vite-react",
+  // "nextjs", "remix", "vue", "svelte", "none".
+  "tech_stack": {
+    "frontend": "none"
+  },
+
+  // Prose discipline. The kiss-check Stop hook watches your writing
+  // for jargon. Value "true" = advisory (findings to stderr, no block).
+  // Value "strict" = BLOCK the stop, forcing a rewrite turn.
+  // Value false = disabled.
+  "prose_discipline": {
+    "kiss_words_turn_prose": true
+  },
+
+  // Where /promote sends proposals. Two shapes:
+  //   "<owner>/<repo>" — gh issue create --repo <value>
+  //   "email:<address>" — mailto: URL printed for adopter to send
+  // Absent → /promote files in the current repo (backward-compat).
+  // "promote_target": "your-org/your-repo",
+
+  // Testing tiers per .claude/rules/testing-tier-config.md. Global
+  // floor sets the baseline for every path that no matcher covers.
+  // Tier 0 = strict TDD (test-first, BLOCK on missing). Tier 1 =
+  // test-with (WARN on missing). Tier 2 = smoke test only. Tier 3 =
+  // manual verify (no test discipline).
+  "testing": {
+    "global_floor": 1,
+    "path_matchers": [
+      { "match": ".claude/rules/*.md", "tier": 3 },
+      { "match": "state/markers/*/*", "tier": 3 },
+      { "match": "chronicle/*.md", "tier": 3 },
+      { "match": "docs/iteration-bets/*.md", "tier": 3 },
+      { "match": "docs/decompositions/*.md", "tier": 3 }
+    ]
+  },
+
+  // /longrun preset picker per .claude/skills/longrun/SKILL.md. Values:
+  //   "converged" — plan doc drives; lean prep output
+  //   "exploratory" — scan-table with no cards until asked
+  //   "reversible-small" — three-chunk compact for small scope
+  //   "auto" — picker decides per session signals (default)
+  "longrun": {
+    "preset": "auto"
+  },
+
+  // Adopter defaults surface. Reserved for future rules. Absent =
+  // downstream rules keep their own defaults.
+  "adopter_defaults": {}
+}

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

@@ -0,0 +1,120 @@
+---
+tier: lite
+purpose: adopter orientation — auto-imported into adopter CLAUDE.md via @.claude/bassclef-orientation.md per ADR-032 + Anthropic @import convention
+last_updated: 2026-06-22
+bet: 2026-06-22b-dispatcher-hardening-rename-orientation (WU-5)
+---
+
+# Bassclef orientation
+
+You've inherited the bassclef substrate. This file loads into every session via `@import` from your CLAUDE.md.
+
+The substrate is a stable set of skills, rules, hooks, luminaries, agents, and standards that pin discipline at decision boundaries. It evolves upstream in `sunj-labs/bassclef-upstream`; you receive releases from public `sunj-labs/bassclef` via `bassclef-sync` at every session start.
+
+## What you have
+
+| Layer | Where | Discover |
+|---|---|---|
+| Skills (invocable workflows) | `.claude/skills/<name>/SKILL.md` | `/skills` |
+| Rules (auto-loaded context) | `.claude/rules/*.md` | All loaded every session via `additionalDirectories` |
+| Luminaries (design + authoring lenses) | `.claude/luminaries/*.md` | `/luminary` |
+| Agents (specialist roles) | `.claude/agents/*.md` | Used by `/autonomous`, `/build`, `/longrun` |
+| Hooks (mechanical enforcement) | `.claude/hooks/*.sh` | Fire automatically; see `/hooks` |
+| Standards (reference docs) | `standards/*.md` | Cited by rules + skills |
+| ADRs (architectural decisions) | `architecture/decisions/ADR-*.md` | Read before changing what they govern |
+
+## Cross-cutting gates — fire across every phase
+
+| Gate | When to run |
+|---|---|
+| `/temperance` | Before first edit on a branch + at scope-decision boundaries |
+| `/diagnose` | Before writing any fix code |
+| `/quick-fix` | Localized, obvious, ≤10 lines, no blast radius |
+| `/auto-fix` | Narrow non-trivial bugs within Builder's safe zone |
+| `/verify` | After each task before committing |
+| `/whats-the-plan` | Before any ≥3-skill chain |
+| `/kiss` | When scope bloats or prose drifts toward jargon |
+| `/luminary` | Before ADR authoring + at any design-decision boundary |
+
+## SDLC flow
+
+```
+Canvas → Spec → Design → Issue → Branch → PR → CI → Deploy → Observe
+```
+
+For UI work, run the UX translation chain during Design:
+
+```
+JTBD → HTA → Entity Model → State Diagrams → Sequence Diagrams → /decompose
+```
+
+## Conventions
+
+- **Commits**: `type: description` per `.claude/rules/commit-conventions.md`
+- **PR titles**: ≤72 chars per `.claude/rules/pr-title-shape.md`
+- **PR bodies**: open with `**Problem (≤500 chars):**` per `.claude/rules/pr-body-shape.md`
+- **Specs** reference their source canvas or issue
+- **New standards** go in `standards/`, not inline in other docs
+
+## What NOT to do
+
+- **Don't break adopters** (ADR-031). Every change to a downstream-observable surface ships with a compat shim, migration manifest, and changelog entry.
+- **Don't make architectural or design decisions without consulting luminaries.** Design without a named lens drifts toward generic; the lens is what gives you a position to defend in review.
+- **Don't release without checking prior open PRs first.** Cumulative stacks create cascade failures.
+- **Don't write source before tests** on Tier 0 paths (per `.claude/rules/testing-tier-config.md`).
+- **Don't auto-apply discipline changes without `/temperance`** at scope boundaries.
+- **Don't conflate "propose" with "execute".** When operator says "propose," "options," "path forward" — wait for explicit go signal.
+- **Don't use bassclef-internal jargon** in operator-facing prose. Plain English at grade-10 reading level.
+- **Don't push to main without PR review** even on solo workflows.
+
+## Luminaries at design boundaries
+
+The substrate ships ~38 luminaries (Linus, Beck, Brooks, Norman, Cooper, Tufte, Nygard, Vernon, Ousterhout, Hyrum, Myers, Hoare, Saltzer-Schroeder, Parnas, Fowler, and more). They pin specific disciplines — they aren't decoration.
+
+When to consult:
+
+- **Architectural decisions (ADRs)** — pin 1-3 luminaries; the ADR cites their lens
+- **Iteration bets** — declare a luminary map (primary pair + extended pairs per surface in scope) per `.claude/rules/iteration-bet-brief-completeness.md`
+- **UI surfaces** — Norman / Cooper / Tufte / Morville per the surface's job
+- **Cross-cutting design choices** — Bulkhead (Nygard) + Anticorruption Layer (Vernon) + Deep Modules (Ousterhout) converge often
+
+`/luminary <slug>` previews one; `/luminary` browses by discipline. Skills with UI / architecture surfaces pin their luminary map in frontmatter — read the skill before invoking.
+
+## Luminaries at the keyboard — not just the whiteboard
+
+Beyond ADRs and iteration bets, luminaries inform code authoring directly. **Pick ONE dominant lens per scope** (bet / WU / surface) and check your work against it. Background discipline fires automatically — don't manually verify against each.
+
+| Scope | Default dominant authoring luminary |
+|---|---|
+| Most code | @luminary kent-beck (TDD rhythm + test list + simple design) |
+| Bash hooks + scripts | @luminary saltzer-schroeder (7 defensive disciplines) |
+| State-spine writes | @luminary tony-hoare (pre/postconditions; contracts) |
+| UI components | Whichever pair the prototype pinned |
+| Architecture refactoring | @luminary john-ousterhout (deep modules) + @luminary martin-fowler (refactoring patterns) |
+
+**Background discipline** (fires automatically — don't manually verify):
+
+- **Rules cite anchor luminaries** explaining why each rule exists. Read the rule; the anchor tells you when the rule generalizes vs when an edge case applies
+- **Hooks enforce specific luminary-anchored disciplines mechanically** — `testing-tier-enforce.sh` (Beck), `state-validate.sh` (Hoare), `substrate-clarity-gate.sh` (context engineering)
+- **`@pattern <catalog-path>` annotation** in source code when you CONSCIOUSLY instantiate a named pattern (GoF, Fowler, Vernon DDD). Not every class — only the ones that EMBODY a pattern as a design choice. Per `.claude/rules/pattern-annotation.md`
+
+## Luminary matching — tier ladder
+
+`/pick-luminaries` picks luminary fits for an intent paragraph. Adopter capability scales with what keys you provide:
+
+- **lite** — stub / deterministic mode; no keys required; for cold-start adopters + CI + tests
+- **standard** — single LLM call picks from the full catalog; semantic matching; needs `ANTHROPIC_API_KEY` (default in bassclef-core)
+- **ultra** — embedding shortlist (Voyage `voyage-3-lite`) + LLM judge re-rank; faster + per-candidate confidence; needs `ANTHROPIC + VOYAGE` keys; load `bassclef-upstream` via `additionalDirectories` to activate
+
+Pre-computed catalog embeddings (~230KB) ship with bassclef-upstream so ultra-tier Voyage cost is per-query intent embedding only.
+
+Pick the tier that matches your trust + budget. Upgrade path is additive — no migration required to move lite → standard → ultra. See bassclef-upstream#262 for ultra-tier downstream-readiness status; bassclef-upstream#263 for the future "plus" tier (local embedding model, no Voyage key).
+
+## Discovery commands
+
+- `/sprint` — what's in flight + what's next
+- `/whereami` — current project state
+- `/substrate-check` — validate substrate wiring
+- `/skills` — phase-grouped skill catalog
+- `/luminary` — design-lens catalog
+- `/hooks` — mechanical-enforcement layer

package/dist/lite/.claude/hooks/adr-discipline-check.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# tier: lite
+# adr-discipline-check.sh — PreToolUse hook on architectural decision boundaries
+#
+# Detects "load-bearing" architectural decisions via path-shape heuristics and
+# refuses unless an ADR marker at state/markers/adr/<decision-slug>.md exists
+# linking to a real ADR file under docs/adrs/ or architecture/decisions/.
+#
+# Per bassclef#1149 + WU-11 of bet 2026-06-20e.
+# Override: SKIP_ADR_CHECK=1 (logged via trace-helper).
+
+set -euo pipefail
+
+# ============================================================================
+# Read stdin JSON from Claude Code harness
+# ============================================================================
+PAYLOAD=$(cat 2>/dev/null || echo '{}')
+
+TOOL_NAME=$(echo "$PAYLOAD" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE_PATH=$(echo "$PAYLOAD" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+# ============================================================================
+# Filters: only fire on Write/Edit/MultiEdit
+# ============================================================================
+case "$TOOL_NAME" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# ============================================================================
+# Override check
+# ============================================================================
+if [ "${SKIP_ADR_CHECK:-0}" = "1" ]; then
+  TRACE_HELPER="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/trace-helper.sh"
+  if [ -f "$TRACE_HELPER" ]; then
+    bash "$TRACE_HELPER" override "adr-discipline-check" "SKIP_ADR_CHECK=1 on $FILE_PATH" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# ============================================================================
+# Architectural-decision detection via path-shape heuristics
+# ============================================================================
+IS_ARCHITECTURAL=0
+DECISION_SLUG=""
+
+case "$FILE_PATH" in
+  */prisma/schema.prisma|prisma/schema.prisma)
+    IS_ARCHITECTURAL=1
+    DECISION_SLUG="schema-change"
+    ;;
+  */docker-compose*.yml|docker-compose*.yml|*/docker-compose*.yaml|docker-compose*.yaml)
+    IS_ARCHITECTURAL=1
+    DECISION_SLUG="deployment-topology-change"
+    ;;
+  */middleware.ts|src/middleware.ts|*/middleware.py|*/middleware.rb)
+    IS_ARCHITECTURAL=1
+    DECISION_SLUG="middleware-change"
+    ;;
+  */alembic/versions/*.py|*/db/migrate/*.rb|*/migrations/*.go)
+    IS_ARCHITECTURAL=1
+    DECISION_SLUG="schema-migration"
+    ;;
+esac
+
+# package.json / pyproject.toml / Gemfile / go.mod / Cargo.toml — only fire on Write (new file or rewrite)
+# Detecting "dependency-add" inside Edit would require diff parsing; deferred to V2
+if [ "$TOOL_NAME" = "Write" ]; then
+  case "$FILE_PATH" in
+    */package.json|package.json|*/pyproject.toml|pyproject.toml|*/Gemfile|Gemfile|*/go.mod|go.mod|*/Cargo.toml|Cargo.toml)
+      IS_ARCHITECTURAL=1
+      DECISION_SLUG="dependency-manifest-change"
+      ;;
+  esac
+fi
+
+if [ "$IS_ARCHITECTURAL" -eq 0 ]; then
+  exit 0
+fi
+
+# ============================================================================
+# Marker check: state/markers/adr/<decision-slug>.md must exist
+# ============================================================================
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+MARKER_DIR="$REPO_ROOT/state/markers/adr"
+
+# Explicit marker required — generic "recent ADR in dir" is too permissive
+# (other ADRs unrelated to this decision class would silently satisfy)
+if find "$MARKER_DIR" -maxdepth 1 -name "${DECISION_SLUG}*.md" 2>/dev/null | grep -q .; then
+  exit 0
+fi
+
+# ============================================================================
+# Block: no marker + no recent ADR
+# ============================================================================
+cat >&2 <<EOF
+🛑 adr-discipline-check — BLOCK (bassclef#1149)
+
+You're about to make a load-bearing architectural decision: ${DECISION_SLUG}
+
+Path: ${FILE_PATH}
+
+Architectural decisions require an ADR (Architecture Decision Record)
+per Michael Nygard's lifecycle: proposed → accepted → deprecated → superseded.
+
+Write one before proceeding:
+
+1. Copy the template:
+   cp standards/adr-template.md docs/adrs/ADR-NNN-<slug>.md
+   (or architecture/decisions/ADR-NNN-<slug>.md per your project layout)
+
+2. Fill Context + Decision + Status + Consequences sections.
+
+3. Touch the marker:
+   mkdir -p ${MARKER_DIR}
+   touch ${MARKER_DIR}/${DECISION_SLUG}-<your-slug>.md
+
+4. Retry the original change.
+
+Override (logged): SKIP_ADR_CHECK=1 <command>
+
+When to use override:
+- Trivial revert of a previously-decided architectural change
+- Emergency rescue when the hook itself misclassifies
+- One-shot migration script that touches many architectural files
+EOF
+
+exit 2

package/dist/lite/.claude/hooks/atomic-pr-check.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# tier: lite
+# Atomic-PR Check — fires on Bash tool calls matching "git push" patterns.
+# Counts distinct WU-N tags in commit messages on the branch. BLOCKs the
+# push if multiple step tags exist unless an iteration goal declares
+# `bundle: true` in frontmatter.
+#
+# Phase II of 8-phase staircase: Trim the Fat (bassclef#382).
+# The methodology rule at .claude/rules/pr-strategy.md is the reasoning;
+# this hook is the mechanical enforcement.
+#
+# Exit codes:
+#   0 — allow (no WU tags, single WU tag, bundle:true in matching bet,
+#       or override)
+#   2 — block (multi-step branch without bundle:true)
+#
+# Override: SKIP_ATOMIC_PR_CHECK=1 to bypass (logged via trace-helper)
+#
+# Rule:  .claude/rules/pr-strategy.md
+# Issue: bassclef#382
+
+set +e  # never crash the tool call; fall through to allow on any unexpected error
+
+INPUT=$(cat)
+TOOL_NAME=$(jq <<< "$INPUT" -r '.tool_name // ""' 2>/dev/null)
+COMMAND=$(jq <<< "$INPUT" -r '.tool_input.command // ""' 2>/dev/null)
+
+# Only fire on Bash with a git push command
+if [ "$TOOL_NAME" != "Bash" ]; then
+  exit 0
+fi
+
+# Match git push patterns (allow flags like -u, --force, etc.)
+case "$COMMAND" in
+  *"git push"*)
+    : # match — continue
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Override hatch — log and allow
+if [ "${SKIP_ATOMIC_PR_CHECK:-0}" = "1" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+  if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+    source "$SCRIPT_DIR/trace-helper.sh" 2>/dev/null || true
+    trace_log "atomic-pr-check" "OVERRIDE git push" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Find the repo root
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$REPO_ROOT" ]; then
+  exit 0  # not in a git repo — allow
+fi
+cd "$REPO_ROOT" || exit 0
+
+# Get current branch name
+BRANCH=$(git branch --show-current 2>/dev/null)
+if [ -z "$BRANCH" ]; then
+  exit 0  # detached HEAD or no branch — allow
+fi
+
+# Skip the check on main branch and bare branch names
+case "$BRANCH" in
+  main|master|HEAD)
+    exit 0
+    ;;
+esac
+
+# Find commits on this branch not yet on main
+# If main is not available locally, fall back to origin/main, then to all commits
+BASE_REF=""
+if git rev-parse --verify main >/dev/null 2>&1; then
+  BASE_REF="main"
+elif git rev-parse --verify origin/main >/dev/null 2>&1; then
+  BASE_REF="origin/main"
+fi
+
+if [ -n "$BASE_REF" ]; then
+  COMMITS=$(git log --format="%s%n%b" "${BASE_REF}..HEAD" 2>/dev/null)
+else
+  # No base ref available — check the last 10 commits as a heuristic
+  COMMITS=$(git log -10 --format="%s%n%b" HEAD 2>/dev/null)
+fi
+
+# Extract distinct WU-N tags from commit messages
+# Match patterns: "WU-1", "WU-2a", "WU-3", etc. (case-sensitive; expects WU-)
+WU_TAGS=$(echo "$COMMITS" | grep -oE '\bWU-[0-9]+[a-z]?\b' | sort -u)
+
+# Count distinct WU tags. If WU_TAGS is empty, count is 0.
+if [ -z "$WU_TAGS" ]; then
+  WU_COUNT=0
+else
+  WU_COUNT=$(echo "$WU_TAGS" | wc -l | tr -d ' ')
+fi
+
+# 0 or 1 WU tags — allow
+if [ "$WU_COUNT" -le 1 ]; then
+  exit 0
+fi
+
+# Multi-WU branch — check for bundle:true in any matching goal doc
+ALLOWED=0
+ITERATION_BETS_DIR="docs/iteration-bets"
+if [ -d "$ITERATION_BETS_DIR" ]; then
+  # Look for goal docs that mention any of the step tags AND have bundle: true
+  for bet in "$ITERATION_BETS_DIR"/*.md; do
+    [ -f "$bet" ] || continue
+    # Check if bet has bundle: true in frontmatter
+    if awk '/^---$/{c++; next} c==1 && /^bundle:[[:space:]]*true/{print "yes"; exit}' "$bet" | grep -q "yes"; then
+      # Verify this goal covers at least one of the step tags
+      for wu in $WU_TAGS; do
+        if grep -qE "\\b${wu}\\b" "$bet"; then
+          ALLOWED=1
+          break 2
+        fi
+      done
+    fi
+  done
+fi
+
+if [ "$ALLOWED" = "1" ]; then
+  exit 0
+fi
+
+# BLOCK — multi-step branch without bundle:true
+WU_LIST=$(echo "$WU_TAGS" | tr '\n' ' ' | sed 's/ $//')
+
+cat >&2 <<EOF
+
+============================================
+🛑 ATOMIC-PR GATE — BLOCKED 🛑
+============================================
+
+Branch: $BRANCH
+Commits found tagged with multiple steps: $WU_LIST
+
+Per .claude/rules/pr-strategy.md, the default is one step per branch
+per PR (atomic). Multiple WUs in one branch defeats the rollback
+discipline — reverting one step also reverts the others.
+
+Three resolution paths:
+
+1. Split — create a separate branch per step and a PR for each.
+   Operator merges in dependency order.
+
+2. Bundle — if these WUs genuinely belong together (single concern,
+   tight coupling, emergency hotfix), declare it explicitly:
+   add 'bundle: true' to the iteration goal's frontmatter, then push.
+
+3. Override (rare) — SKIP_ATOMIC_PR_CHECK=1 git push ...
+   Logged to trace. Use only for genuine bypass cases.
+
+Per pr-strategy.md the bundle option requires one of:
+- Single logical concern across files (changes don't compile if split)
+- Tight coupling that breaks atomic /verify
+- Emergency hotfix
+- Explicit operator request
+
+Rule:  .claude/rules/pr-strategy.md
+Issue: bassclef#382
+============================================
+
+EOF
+
+exit 2