docs: add contributor and agent guides

[sugat009]

Two commits on one branch: test: add upstream parity tests and lint guardrails and docs: add contributor and agent guides. They are separable, but the docs name clippy.toml and tests/upstream_parity.rs directly, so they only read correctly together.

Merging with rebase rather than squash keeps both messages on main, which is what release-please reads to build the changelog. A squash collapses them into one entry.

Tests and guardrails (c05ab0b)

• tests/upstream_parity.rs: ports all 31 rows of LINTER_FIXTURE_PARAMS from commitlint 2.0.0, in upstream order, with the same three columns. Only the pass/fail column is asserted, because cocox has no per-field validator yet; the error strings are listed verbatim so the second assertion is a small diff once it lands. fixture_table_has_all_upstream_rows pins the count at 31, so a dropped row fails instead of quietly shrinking coverage.
• tests/crlf_parity.rs: pins today's CRLF behavior on all three input paths that read from git or disk (crlf_commit_is_rejected_via_hash, crlf_commit_is_rejected_via_from_hash, crlf_message_file_is_rejected). The module header records why this is a divergence and not a contract: Python text mode rewrites \r\n before linting, so upstream accepts these. Normalization belongs in the readers only, since upstream does not normalize a message passed as an argument.
• tests/message_coverage.rs: a ratchet, not a snapshot. src/messages.rs holds only the two verdict lines today and both are exempt, so the test passes with nothing to check. It fails, and names the message, the first time a per-field error is added without an assertion in tests/cli.rs.
• clippy.toml: denies str::len and String::len via disallowed_methods, because Python len() counts code points and Rust len() counts UTF-8 bytes. [lints.clippy] disallowed_methods = "deny" in Cargo.toml makes a plain cargo clippy fail on its own, without -D warnings on the command line. str::lines is listed as a commented-out entry with the reason, since src/utils.rs:10 still calls it and fixing that changes behavior.
• Cargo.toml: declares rust-version = "1.85", with a comment recording that it comes from edition 2024 rather than any language feature.
• .gitignore: ignores .claude/settings.local.json, which until now was only covered by a personal global git config.

Guides (f9ba909)

• CONTRIBUTING.md and .github/CODE_OF_CONDUCT.md follow the structure of the commitlint guides, so both projects in the organization read the same way, with the Rust toolchain in place of the Python one.
• AGENTS.md is the single source of truth for agent guidance: the parity contract, ten Python-to-Rust porting traps that have each produced a real defect here, the testing rules, and the divergences from upstream measured so far. The two upstream behaviors that are defects rather than contracts are called out so nobody ports them.
• CLAUDE.md only imports AGENTS.md and holds the two facts specific to Claude Code, so the guidance does not fork per tool.

The divergence list is what has been measured, not a complete audit. Each entry was reproduced against commitlint 2.0.0, and each is a separate follow-up pull request.

Verification

Run on f9ba909:

cargo fmt --all --check                                        clean
cargo clippy --all-targets --all-features -- -D warnings       clean
cargo test                                                     98 passed, 0 failed

98 = 38 lib, 43 cli, 11 git_helpers, 3 crlf_parity, 1 message_coverage, 2 upstream_parity. The branch also passes its own linter: cocox --from-hash c05ab0b --to-hash f9ba909 exits 0.

No behavior change to the binary. tests/cli.rs is touched only to reorder a use.

🤖 Generated with Claude Code