Consider a pre-commit hook (or lint-staged) to enforce Prettier formatting #528

Context

Formatting is currently enforced two ways:

1. Documentation — AGENTS.md and CONTRIBUTING.md instruct contributors to run npm run format:write before committing (recently tightened in docs: require formatting for every contribution #527).
2. CI — npm run format:check runs on every PR and fails if anything is unformatted.

This works, but it relies on contributors (and agentic contributors) reading the docs and remembering to format. When that's missed, the failure shows up late — at CI time — and requires a follow-up commit to fix (e.g. the unformatted plans/ files in #520).

Proposal (for discussion — not a decision)

Add a mechanical backstop that formats/checks staged files locally before a commit lands, so unformatted code never reaches CI in the first place. Common options:

• lint-staged + husky — runs prettier --write on staged files at commit time. Auto-fixes, low friction.
• prettier --check pre-commit hook — blocks the commit instead of auto-fixing. Stricter, more surprising.
• pre-commit framework — language-agnostic, but adds a Python dependency.

Why this is a discussion, not a PR

There has been resistance to pre-commit hooks in the past, so this should be talked through before anything is added. Known trade-offs / objections to weigh:

• Hooks add a dependency and a prepare/install step contributors must opt into; they can be bypassed (--no-verify) and silently skipped if not installed.
• Auto-formatting on commit can surprise contributors by modifying their staged changes.
• CI already catches the problem; a hook is a convenience/shift-left measure, not a correctness gain.
• Adds maintenance surface (husky/lint-staged version bumps, etc.).

Asks

• Do we want a local backstop at all, given CI already enforces formatting?
• If yes, which approach (auto-fix vs. block), and is the added dependency acceptable?
• Surface the prior context/objections so we don't relitigate or repeat a decision already made.