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

[Ethan-Arrowood]

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.

[dawsontoth]

Eh, I haven't loved it when I've set formatting up as a pre-commit hook. It has surprised me more than not, or been misconfigured at other times and ends up with two commits where it fixes some stuff, writes the original commit, and then I have staged more commits.

We can also target specific agents to automatically format when they stop. Studio does this, albeit in a local settings file for me. I haven't tried putting it in a shared setting for the repo... so lazy, these human fingers...

{
	"hooks": {
		"Stop": [
			{
				"hooks": [
					{
						"type": "command",
						"command": "pnpm run lint:fix && pnpm run format:fix",
						"statusMessage": "Linting and formatting...",
						"async": true
					}
				]
			}
		]
	}
}