Architecture
Hooks catalog
The full list of lite-tier hooks bassclef installs. Bash scripts that fire on Claude Code events. Adopters see them only when they block.
What hooks are
Hooks are bash scripts bassclef installs into .claude/hooks/. Claude
Code fires them on specific events — before an Edit or Write, after a
tool call, on session start, on session end. You do not call them.
You do not see them unless one blocks something you were doing OR you
override with SKIP_<HOOK_NAME>=1.
Why this is a single catalog page
The hook file IS the docs. Each hook starts with a header comment
explaining what it enforces, when it fires, and what override paths
exist. Rendering per-hook pages here would just copy that comment
block. INSTEAD we list every lite hook plus the path where
bassclef-sync installs it in your repo — open the file with your
editor to read the header.
The catalog
| Hook | What it does | Tier | Installed at |
|---|---|---|---|
00-bassclef-hook-connect | 00-bassclef-hook-connect.sh — Auto-connect bassclef hooks to adopter settings.json. | lite | .claude/hooks/session-reflection.d/00-bassclef-hook-connect.sh |
05-active-bet | 05-active-bet.sh — Surface in_flight_bet from whereami at SessionStart | lite | .claude/hooks/session-reflection.d/05-active-bet.sh |
08-settings-drift | Drift detector — fires at every SessionStart via session-reflection.sh. | lite | .claude/hooks/session-reflection.d/08-settings-drift.sh |
10-abrupt-stop-recovery | Abrupt-stop detection: dirty working tree indicates the previous | lite | .claude/hooks/session-reflection.d/10-abrupt-stop-recovery.sh |
12-session-lock | SESSION_LOCK presence: surface to operator + future agents that | lite | .claude/hooks/session-reflection.d/12-session-lock.sh |
15-substrate-config-validate | 15-substrate-config-validate.sh | lite | .claude/hooks/session-reflection.d/15-substrate-config-validate.sh |
20-artifact-staleness | Artifact-staleness checks: chronicle, danger-mode summary, | lite | .claude/hooks/session-reflection.d/20-artifact-staleness.sh |
30-metrics-staleness | Metrics-staleness check: version tags, iteration closeouts, metrics | lite | .claude/hooks/session-reflection.d/30-metrics-staleness.sh |
35-post-merge-whereami-self-heal | Post-merge whereami self-heal (bassclef#505 Option A — LR7 WU-2). | lite | .claude/hooks/session-reflection.d/35-post-merge-whereami-self-heal.sh |
36-whereami-size-check | Whereami size check + auto-rotate (bassclef-upstream#1284). | lite | .claude/hooks/session-reflection.d/36-whereami-size-check.sh |
40-gate-compliance | Gate-compliance check: if /verify or /temperance fire below 80% across | lite | .claude/hooks/session-reflection.d/40-gate-compliance.sh |
45-auto-sync-status | 45-auto-sync-status.sh — Always-on version status line | lite | .claude/hooks/session-reflection.d/45-auto-sync-status.sh |
50-evolution-issues | Bassclef-evolution promotion scan: in bassclef sessions only, list | lite | .claude/hooks/session-reflection.d/50-evolution-issues.sh |
55-orientation-gate | 55-orientation-gate.sh | lite | .claude/hooks/session-reflection.d/55-orientation-gate.sh |
56-roadmap-reconcile-gate | 56-roadmap-reconcile-gate.sh | lite | .claude/hooks/session-reflection.d/56-roadmap-reconcile-gate.sh |
60-deferred-actions | Deferred-actions scan: enumerate docs/deferred-actions/*.md, detect current | lite | .claude/hooks/session-reflection.d/60-deferred-actions.sh |
70-recent-strategic-artifacts | Recent Strategic Artifacts — session-start branch of artifact-ingestion gate. | lite | .claude/hooks/session-reflection.d/70-recent-strategic-artifacts.sh |
75-prior-r8-findings | 75-prior-r8-findings.sh — SessionStart fragment that surfaces prior R8 | lite | .claude/hooks/session-reflection.d/75-prior-r8-findings.sh |
80-hook-heartbeat-check | Hook heartbeat check — reads standards/hook-cadence.json, calls | lite | .claude/hooks/session-reflection.d/80-hook-heartbeat-check.sh |
80-workflow-staleness | Workflow-staleness — surfaces silent bassclef workflow failures at | lite | .claude/hooks/session-reflection.d/80-workflow-staleness.sh |
81-hook-manifest-staleness | Hook manifest staleness — flags standards/hook-cadence.json when it | lite | .claude/hooks/session-reflection.d/81-hook-manifest-staleness.sh |
90-release-backlog | 90-release-backlog.sh | lite | .claude/hooks/session-reflection.d/90-release-backlog.sh |
90-secrets-expiry | Secrets-expiry scan: parse substrate.secrets.md, surface BLOCKED | lite | .claude/hooks/session-reflection.d/90-secrets-expiry.sh |
91-npm-version-drift | shellcheck shell=bash disable=SC1090 | lite | .claude/hooks/session-reflection.d/91-npm-version-drift.sh |
95-settings-hook-verify | Settings hook path verifier — fires at every SessionStart via | lite | .claude/hooks/session-reflection.d/95-settings-hook-verify.sh |
95-telemetry-emit | .claude/hooks/session-reflection.d/95-telemetry-emit.sh | lite | .claude/hooks/session-reflection.d/95-telemetry-emit.sh |
97-install-class-dispatch | 97-install-class-dispatch.sh — fragment that sources the install-class | lite | .claude/hooks/session-reflection.d/97-install-class-dispatch.sh |
artifact-ingestion-gate | Artifact Ingestion Gate — fires on Write/Edit to generative artifact paths. | lite | .claude/hooks/artifact-ingestion-gate.sh |
assert-verify-steering | assert-verify-steering.sh — UserPromptSubmit hook that injects | lite | .claude/hooks/assert-verify-steering.sh |
atomic-pr-check | Atomic-PR Check — fires on Bash tool calls matching "git push" patterns. | lite | .claude/hooks/atomic-pr-check.sh |
auto-save-idle | Auto-save idle checker — runs via cron on macOS + Linux + WSL (or Task Scheduler on native Windows) every 15 minutes. | lite | .claude/hooks/auto-save-idle.sh |
bassclef-source-config-validate | bassclef-source-config-validate.sh — PreToolUse hook validating | lite | .claude/hooks/bassclef-source-config-validate.sh |
bassclef-sync | Bassclef Substrate Sync — fires on SessionStart. | lite | .claude/hooks/bassclef-sync.sh |
bet-doc-gate | bet-doc-gate.sh — PreToolUse Edit|Write|MultiEdit on docs/iteration-bets/*.md | lite | .claude/hooks/bet-doc-gate.sh |
bug-diagnosis | Bug Diagnosis hook — fires on UserPromptSubmit. | lite | .claude/hooks/bug-diagnosis.sh |
compound-noun-scrub | compound-noun-scrub.sh — PreToolUse Edit|Write gate on | lite | .claude/hooks/compound-noun-scrub.sh |
destructive-command-guard | Destructive Command Guard — fires on Bash PreToolUse. | lite | .claude/hooks/destructive-command-guard.sh |
discipline-check | adr-discipline-check.sh — PreToolUse hook on architectural decision boundaries | lite | .claude/hooks/adr-discipline-check.sh |
file-rename-discipline-check | file-rename-discipline-check — PreToolUse hook that blocks `git commit` | lite | .claude/hooks/file-rename-discipline-check.sh |
hook-classifier-canary | hook-classifier-canary.sh — advises author when a new hook lands | lite | .claude/hooks/hook-classifier-canary.sh |
kiss-default-check | kiss-default-check.sh — pre-push /kiss enforcement check | lite | .claude/hooks/kiss-default-check.sh |
kiss-expansion-inject | kiss-expansion-inject.sh — UserPromptExpansion hook that injects | lite | .claude/hooks/kiss-expansion-inject.sh |
longrun-prep-compounding-axis-check | longrun-prep-compounding-sequence-check.sh — Stop hook that fires when | lite | .claude/hooks/longrun-prep-compounding-axis-check.sh |
longrun-prep-compounding-sequence-check | longrun-prep-compounding-sequence-check.sh — Stop hook that fires when | lite | .claude/hooks/longrun-prep-compounding-sequence-check.sh |
longrun-prep-render-check | PostToolUse: Stop | lite | .claude/hooks/longrun-prep-render-check.sh |
multi-tenancy-check | Multi-Tenancy Check — bassclef template. | lite | .claude/hooks/multi-tenancy-check.sh |
oo-ad-entry-point-check | oo-ad-entry-point-check.sh — PreToolUse Edit/Write hook mechanizing .claude/rules/oo-ad-entry-point.md. | lite | .claude/hooks/oo-ad-entry-point-check.sh |
operator-private-path-check | Operator-private path enforcement — Rule 3 of bassclef#739 | lite | .claude/hooks/operator-private-path-check.sh |
pattern-annotation-validate | pattern-annotation-validate.sh — Layer 3 of bassclef#478 traceability. | lite | .claude/hooks/pattern-annotation-validate.sh |
persona-name-scrub-check | persona-name-scrub-check — PreToolUse hook that scans SKILL descriptions, | lite | .claude/hooks/persona-name-scrub-check.sh |
plain-english-steering | plain-english-steering.sh — UserPromptSubmit hook that injects | lite | .claude/hooks/plain-english-steering.sh |
post-skill-friction-check | Post-Skill Friction Check — fires on PostToolUse for Skill tool. | lite | .claude/hooks/post-skill-friction-check.sh |
post-skill-telemetry | .claude/hooks/post-skill-telemetry.sh | lite | .claude/hooks/post-skill-telemetry.sh |
post-write-trace | Post-Write Traceability — fires on PostToolUse for Write/Edit. | lite | .claude/hooks/post-write-trace.sh |
pr-body-scrub-check | PR-body scrub check — Rule 1 (jargon) + Rule 4 (operator-private + | lite | .claude/hooks/pr-body-scrub-check.sh |
pre-build-gate | Pre-Build Gate — fires on first Edit/Write per session. | lite | .claude/hooks/pre-build-gate.sh |
pre-commit-gate | Observable failure trap — closes bassclef-upstream#1075 (silent-stderr class). | lite | .claude/hooks/pre-commit-gate.sh |
pre-commit-identifier-leak-scrub | PreToolUse: Bash | lite | .claude/hooks/pre-commit-identifier-leak-scrub.sh |
pre-gh-pr-body-scrub | pre-gh-pr-body-scrub — PreToolUse hook that runs the body scrub logic | lite | .claude/hooks/pre-gh-pr-body-scrub.sh |
pre-gh-pr-title-scrub | pre-gh-pr-title-scrub — PreToolUse hook that runs the body scrub logic | lite | .claude/hooks/pre-gh-pr-title-scrub.sh |
role-entry-gate | role-entry-gate.sh — mode-agnostic role-entry discipline (bassclef#1145 T13) | lite | .claude/hooks/role-entry-gate.sh |
save-state | Save State — graceful checkpoint of all work in progress. | lite | .claude/hooks/save-state.sh |
session-end | Session End hook — fires on Stop event. | lite | .claude/hooks/session-end.sh |
session-reflection | Session Start hook coordinator. Injects reflection prompt and iterates | lite | .claude/hooks/session-reflection.sh |
skill-body-grade-gate | skill-body-grade-gate.sh — PreToolUse Edit|Write gate on | lite | .claude/hooks/skill-body-grade-gate.sh |
skill-body-intent-drift | skill-body-intent-drift.sh — PostToolUse Edit|Write hook on | lite | .claude/hooks/skill-body-intent-drift.sh |
skill-step-list-check | Skill-step-list check — Stop hook that scans the transcript for a Skill tool | lite | .claude/hooks/skill-step-list-check.sh |
state-validate | state-validate.sh — PreToolUse hook that validates state-spine entity | lite | .claude/hooks/state-validate.sh |
substrate-clarity-gate | Substrate Clarity Gate — fires on Write/Edit to substrate paths | lite | .claude/hooks/substrate-clarity-gate.sh |
temperance-gate | temperance-gate.sh — mechanical /temperance firing at decision boundaries | lite | .claude/hooks/temperance-gate.sh |
testing-tier-enforce | testing-tier-enforce.sh — per-path testing-tier enforcement (bassclef#1037) | lite | .claude/hooks/testing-tier-enforce.sh |
tool-failure-diagnosis | Tool Failure Diagnosis — fires on PostToolUse. | lite | .claude/hooks/tool-failure-diagnosis.sh |
trace-helper | SDLC Trace Log helper — sourced by all hooks. | lite | .claude/hooks/trace-helper.sh |
turn-prose-grade-measure | Turn-prose grade measure — Stop hook that reads the last assistant message | lite | .claude/hooks/turn-prose-grade-measure.sh |
turn-prose-kiss-check | Turn-prose /kiss check — Stop hook that scans the most recent assistant | lite | .claude/hooks/turn-prose-kiss-check.sh |
vocabulary-migration-check | vocabulary-migration-check.sh — PreToolUse Edit|Write gate on | lite | .claude/hooks/vocabulary-migration-check.sh |
whereami-utc-gate | whereami-utc-gate.sh — PreToolUse hook that BLOCKs Edit|Write|MultiEdit | lite | .claude/hooks/whereami-utc-gate.sh |
Related
- Rules catalog — markdown rules the hooks enforce
- Skills catalog — commands you type
- Failure mode — how bassclef fails safely when a hook blocks
Rules catalog
The full list of lite-tier rules bassclef loads into every session. One row per rule with the path where bassclef-sync installs it in your repo.
When bassclef does something unexpected
Six named failure classes. Each carries a symptom, a diagnose command, an expected output, and the recovery step.