docs(agents): document Conventional Commits enforcement in AGENTS.md

[Devin-Holland]

Adds an AGENTS.md section documenting that the Verify Commits workflow enforces Conventional Commits (type(scope): subject, @commitlint/config-conventional) on every PR and on pushes to dev/stage/prod — and that nothing warns locally first, so CI is the first thing that objects.

Context: unprefixed commit messages on the #1574 deploy branches failed Verify Commits, which meant rewriting history that had already landed. This makes the convention discoverable for agents and humans working from bare worktrees.

Rebased on stage, replayed onto AGENTS.md

Per @dawsontoth — the original commit edited CLAUDE.md, which #1573 renamed to AGENTS.md (with CLAUDE.md left as a pointer, per @kriszyp). This branch is now a single commit on top of current stage, with the section added to AGENTS.md instead. The stale CLAUDE.md in the branch name is cosmetic — renaming the branch would orphan this PR.

The local-hook claim is now the verified mechanism, not the guess

The first version blamed a missing node_modules for the hook "failing open". Checked it instead of assuming, in a fresh clone that had never run pnpm install:

• git config --get core.hooksPath → unset. .husky/commit-msg is only wired up by the prepare: husky script, which pnpm install runs — skip install and git never looks in .husky at all.
• Committed not a conventional message in that checkout: it landed, no hook output, exit 0.

So the hook doesn't run and pass — it doesn't run. The section says that now, and names core.hooksPath so the fix is obvious to whoever hits it.

Every other fact in the section was re-checked against current stage: the workflow triggers (.github/workflows/verify-commits.yaml), the 11 config-conventional types, and subject-case being disabled in commitlint.config.cjs.

Verification

dprint check AGENTS.md → exit 0. Markdown-only diff, one file, +16 lines; no code, config, or dependency changes.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates CLAUDE.md to document that Conventional Commits are enforced in CI, explaining the required prefix format, the Verify Commits workflow, and a potential issue with the local Husky hook when node_modules is missing. There are no review comments, and I have no feedback to provide.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	54.2%	6181 / 11403
🔵	Statements	54.76%	6626 / 12098
🔵	Functions	45.97%	1484 / 3228
🔵	Branches	47.36%	4190 / 8847

File Coverage

No changed files found.

Generated in workflow #1648 for commit 65deff6 by the Vitest Coverage Report Action

[kriszyp]

I realize you are editing an existing file, but I think it is supposed to be spelled AGENTS.md, not CLAUDE.md (CLAUDE.md should direct claude to read from AGENTS.md). Claude isn't the only agent being used. I suppose it is fine to omit this from this PR, but maybe @dawsontoth could fix this?
_{🤖 Reviewed with GPT 5.6}

[kriszyp]

The configured action lints the commits in each push event, so a bad commit that already landed does not poison every later run: a subsequent push containing only valid commits gets a new passing check. Rewriting and force-pushing dev/stage/prod is therefore not required, and recommending it here is risky. Could we remove this clause, or limit amend/force-push guidance to the PR branch before merge?

[kriszyp]

The fresh-worktree gap happens before pnpm commitlint runs: Husky's generated .husky/_/commit-msg wrapper is created by pnpm install/the prepare script, so a worktree that has not installed dependencies has no hook for Git to invoke. If that wrapper exists but node_modules is later absent, pnpm commitlint exits nonzero rather than failing open. Could we describe the missing generated hook as the root cause, e.g. “until pnpm install has installed Husky's hooks, commits are not linted locally”?

[dawsontoth]

@Devin-Holland can you rebase on the latest stage? In #1573 I renamed the root file per @kriszyp 's request, so you'll need to replay your changes on the new file.

[Devin-Holland]

Done — thanks for the heads-up on the rename, and nice call making AGENTS.md canonical (@kriszyp): the pointer stub meant there was exactly one place this section belonged, no judgment call needed.

Branch is now a single commit on top of current stage with the section replayed into AGENTS.md. Conflict is gone, all three checks green.

While replaying I re-verified the claims rather than carrying them over, and one was wrong. The original text said the local hook "fails open" because node_modules is missing. The real mechanism is a step earlier: .husky/commit-msg is only wired up by the prepare: husky script that pnpm install runs, so in a fresh clone core.hooksPath is simply unset and git never looks in .husky at all. Confirmed both ways in a clean checkout — git config --get core.hooksPath returns nothing, and a commit literally messaged not a conventional message landed with no hook output. The section now names core.hooksPath, which also makes the fix self-evident to whoever hits it.

I left the branch name (docs/claude-md-commit-conventions) alone since renaming it would orphan this PR — it's cosmetically stale, nothing more.

🤖 Written by Claude Opus 5