[DevEx] PostToolUse hook: micro-alignment on every edit (cargo check, clippy, shellcheck, shfmt)

Why

Code quality misalignments — compilation errors, lint violations, unsafe shell constructs — are cheap to fix individually but expensive to discover late. When they accumulate across multiple edits, they compound: a broken type cascades into a broken module, a clippy warning multiplies across 10 files, and the developer ends up doing a bulk cleanup pass instead of shipping.

Claude Code edits files frequently and rapidly. Without an inline gate, each Write/Edit is a potential misalignment that silently persists until the developer runs cargo clippy manually or the CI pipeline catches it. In the RTK workflow, that gap can span dozens of tool calls.

The "alignment" principle is simple: the shorter the life of a misalignment, the lower its blast radius. A compilation error caught after one edit costs one fix. The same error caught after twenty edits costs a debugging session.

How

We propose adding a PostToolUse hook that fires on every Write or Edit tool call in Claude Code. It would inspect the modified file, route to the appropriate gates by extension, and either auto-fix or block.

Rust (.rs)

• cargo check — blocks on type/compilation errors
• cargo clippy — blocks on errors, warns on warnings (non-blocking)

Shell (.sh)

• shfmt -w — auto-formats in place (non-blocking)
• shellcheck — blocks on undefined behavior, unsafe constructs

Behavior

Outcome	Hook exit	Effect
All gates pass	0	Emits systemMessage to Claude UI (e.g. cargo check: OK)
Auto-fix applied	0	Emits auto-fixed by shfmt | ...
Gate failure	2	Blocks the edit, surfaces error in Claude UI
Tool not installed	0	Degrades gracefully, records not installed

Setup would require copying .claude/settings.json.example → settings.json. All tool dependencies (cargo, clippy, shfmt, shellcheck) would be declared in .mise/config.toml and auto-installed.

A working implementation is available on branch devex/alignment-claude-hook.