docs: standardize commit message format

[gregggreg]

Codifies the commit format the repo already mostly follows — Conventional Commits — as a documented, enforced standard.

About 129 of 171 commits on main (~75%) already conform. This makes that explicit for new work.

History is not rewritten

No filter-branch, no rebase of published commits. Merged PRs and released tags keep their SHAs. Enforcement applies to new commits only:

• the commit-msg hook checks what you write locally (opt-in via make install-hooks)
• the commit-lint CI job checks only the commits unique to a PR, computed from git merge-base against the base ref — historical drift on main is left alone

What's here

File	Purpose
docs/guides/commit-messages.md	The canonical convention: format, types table, rules, good/bad examples drawn from real history
.gitmessage.txt	Commit template, so git commit opens with the format inline
scripts/commit-msg.sh	POSIX-sh validator used as the commit-msg hook
scripts/check-commit-range.sh	Same validation over a commit range, for CI and make lint-commits
scripts/commit-msg_test.sh	40 table tests for the validator

Plus: make install-hooks now installs both hooks and sets the template; new make test-scripts and make lint-commits targets; a commit-lint CI job; cross-references from AGENTS.md (and CODEX.md, which symlinks to it) and README.md; a CHANGELOG.md entry.

Format

<type>(<optional scope>): <lowercase imperative subject>

Subject ≤72 chars, no trailing period, imperative mood. Types: feat fix docs refactor test chore build ci perf style revert.

The validator deliberately passes through subjects git authors itself (Merge …, Revert …, fixup!, squash!) and accepts acronym-initial subjects (fix: JSONL parsing …), trailers, and long URLs in the body. --no-verify bypasses the hook locally.

Agent-authored commits

internal/orchestrator/orchestrator.go now states the subject format in both the plan and implement prompts, keeping the existing Nightshift-Task / Nightshift-Ref trailers intact. orchestrator_test.go locks that contract down.

Verification

• gofmt -l . — clean
• go build ./..., go vet ./... — pass
• go test ./... — all packages pass
• make test-scripts — 40/40 pass
• Hook exercised live: it rejected Standardize commit messages, then accepted this PR's own commit
• check-commit-range.sh verified in both directions (flags a known-drifted historical range, passes this branch)

Note on overlap

There is an earlier open PR #186 from a previous run of this task, based on docs-backfill rather than main. It takes a rewrite-in-place approach (scripts/normalize-commit-message.sh); this PR validates and rejects instead, which keeps authorship of the message with the committer. Only one of the two should land — closing #186 in favor of this one is the suggested path.

Nightshift-Task: commit-normalize
Nightshift-Ref: https://github.com/marcus/nightshift

[gregggreg]

Addressed the two review findings in `scripts/commit-msg.sh` (fa7b592):

• Subject length was measured in bytes. wc -c/awk length() counted bytes, so a 71-character subject with accents, an em-dash, smart quotes, or emoji was rejected as over-long. Now measured with wc -m under a UTF-8 locale, probed for one the machine actually has. Note macOS awk reports length() in bytes even in a UTF-8 locale, so awk could not be used here.
• Body-length errors reported the post-strip line number. Since git does not strip the comment block before running commit-msg, and make install-hooks installs an 18-line comment template, "body line 3" pointed at line 21 of the editor buffer. Each line is now tagged with its original number while stripping.

Also documented that limits are character counts and that the body hard limit is 100 (wrap at 72), with trailers and single-token URLs exempt.

Regression tests added — the suite is now 45 checks, all passing. One test uses a body line that is 100 characters but 191 bytes, so it fails if byte counting ever returns. scripts/check-commit-range.sh --base origin/main HEAD passes on both commits, and go build, go vet, go test ./internal/orchestrator/ are green.