docs: configuration reference table, contributor docs cleanup, dedupe helpers - #572

What

Three commits: two documentation, one behaviour-neutral refactor, plus three follow-ups (CodeRabbit's review, the adversarial review of this PR, and a red CodSpeed job). No CLI output changes: 123 CLI scenarios and 320 Python API calls compared byte for byte between main and this branch, the only difference being --version reading a stale egg-info in the sandbox.

README: a configuration reference table

Of the 28 keys in get_default_config(), 9 never appeared in the README (message_pattern, allow_revert_commits, allow_empty_commits, allow_fixup_commits, require_body, author_email_pattern, author_name_pattern, require_rebase_target, allow_force_push) and none was shown with its default, CLI flag and CCHK_* environment variable together; the section deferred to the website. A new "Configuration reference" subsection (after "Use CLI Arguments or Environment Variables", in the TOC) lists all 28 keys plus the top-level warn, each with default, flag, env var, meaning and rule ID. The table was generated from get_default_config(), ENV_VAR_MAPPING, CLI_ARG_MAPPING and the argparse help, then committed as static Markdown; a new tests/readme_test.py asserts every section.key is a table row, every CCHK_* variable sits on the row of the key it sets (looked up through ENV_VAR_MAPPING), and the warn row is present, so the table cannot drift from the code. Every row's default, flag, env var and rule ID was re-verified programmatically during review.

One row is honest rather than flattering: push.allow_force_push is a pre-existing dead key. The value is never consulted (CC301 runs only with --no-force-push, which always rejects a force push), so the row says "Reserved; has no effect today" instead of describing behaviour that does not exist. Making the key work is a separate change.

Contributor docs aligned with the code

• CONTRIBUTING.md: the nox -s docs / docs-live sessions were removed in docs: remove the documentation now served from commit-check.com #519 along with docs/; the section now says where the docs live. "~258 imperative verbs" → the set has 526 entries and is not an allow-list. Module and validator trees completed (api, fixes, ai_signatures; Tag/Files/ForcePush/AiAttribution validators); exit codes 0 / 1 / 2.
• .github/copilot-instructions.md: "~564 tests in main_test.py" → 97 (888 total); default commit types no longer list revert (a revert is governed by allow_revert_commits); default branch prefixes no longer list task/; the pip install pyyaml line and two Sphinx build blocks are gone; the noxfile session list and exit-code list match reality; 14 test files listed including readme_test.py, and the CodSpeed benchmarks are no longer attributed to one file (11 of 14 files carry them).
• AGENTS.md: the branch-naming rule listed five types while cchk.toml sets conventional_branch = false, so CI only checks require_rebase_target = "main". The sentence now says exactly that and recommends the Conventional Branch form without pretending it is enforced.
• pyproject.toml: [tool.coverage] omit is not a table coverage.py reads (coverage debug config showed run_omit: -none-); it is now [tool.coverage.run]. No coverage number changes because nox already passes --source.
• .pre-commit-config.yaml: the mypy hook's exclude: ^testing/resources/ pointed at a directory that does not exist; removed.

One deep_merge, one check-group source, module-level imports

• config.py had _deep_merge (returns a new dict) and config_merger.py had deep_merge (in place); api.py deep-copied its input to defend against the in-place one. There is now one deep_merge in config.py (in place; every value taken from the override is deep-copied, dicts and lists alike, so the caller's config is never aliased), re-exported from config_merger; the api.py deepcopy is gone. Tests assert the caller's config is untouched after validate_message and after a list override into an existing section. A 3,000-case property test against a reference implementation found 0 mismatches and 0 aliasing for the new function, against aliasing in about 2,070 of 3,000 cases for each of the two old ones.
• The 13-name message-check list was duplicated between main.py and api.py (in sync today, by luck). rules_catalog.py now defines MESSAGE_CHECKS, BRANCH_CHECKS and FILES_CHECKS next to the catalog; both callers use them, and tests pin each set against the catalog. _get_requested_checks returns a set (only membership was ever used; rule order comes from the catalog).
• 20 function-level import statements (23 names) are hoisted to module level; the import graph is a DAG and none was needed for a cycle. Eight of them were import re on the per-check path, so this is neutral-to-positive for CodSpeed.

A red CodSpeed job, fixed in passing

Run benchmarks has failed on every push since #570, this PR's first run included: test_invalid_default_config_names_the_file_too carries @pytest.mark.benchmark and creates .github with mkdir(), and CodSpeed executes a marked test more than once against the same tmp_path, so the second execution raised FileExistsError. The test measures nothing, so it loses the mark, as two real-git tests in util_test.py already had for the same reason. Reproduced locally by calling the test twice on one tmp_path.

Testing

• 953 tests pass (887 before). One pre-existing chmod 000 test fails locally only because the sandbox runs as root.
• pre-commit run --all-files clean.
• Changed-line coverage 100%; config.py, config_merger.py, rules_catalog.py at 100%.
• coverage debug config now reports run_omit: tests/*.

🤖 Generated with Claude Code

https://claude.ai/code/session_018xYa7m3qup5wyN5MaXFgf6