-```
-
-Forgot it? Fix the last commit in place:
-
-```console
-$ git commit --amend --signoff --no-edit
-```
-
-Fix a whole branch:
-
-```console
-$ git rebase --signoff main
-```
-
-!!! tip "Make it automatic"
-
- Signing off is easy to forget. Combine this rule with the
- [pre-commit hook](pre-commit.md) so a missing trailer is caught at commit
- time, not at review time.
-
-## Identity matters
-
-The DCO is a statement about who wrote the code, so it only means something if
-the identity is real. [CC101](../rules.md#cc101) and
-[CC102](../rules.md#cc102) check the committer name and email, and are enabled
-by default when their check runs:
-
-```console
-$ commit-check --author-name --author-email
-```
-
-To require a company address:
-
-```toml title="cchk.toml"
-[commit]
-author_email_pattern = "^.+@example\\.com$"
-```
-
-## Bots
-
-Automation cannot meaningfully sign the DCO, and forcing it to produces
-meaningless trailers. Exempt bots instead:
-
-```toml title="cchk.toml"
-[commit]
-require_signed_off_by = true
-ignore_authors = ["dependabot[bot]", "renovate[bot]"]
-```
-
-`ignore_authors` matches the commit author and any `Co-authored-by:` trailers.
diff --git a/docs/index.md b/docs/index.md
index 01c36e1..adff20c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -31,7 +31,7 @@ whatever your AI agent is committing on your behalf.
```yaml title=".pre-commit-config.yaml"
repos:
- repo: https://github.com/commit-check/commit-check
- rev: v2.11.0
+ rev: v2.13.0
hooks:
- id: check-message
- id: check-branch
@@ -63,6 +63,59 @@ whatever your AI agent is committing on your behalf.
}
```
+## Why it exists
+
+Git history is a database that every team writes to and almost nobody validates.
+
+The cost shows up later, and indirectly. Release notes get written by hand
+because commit subjects cannot be grouped. `git bisect` walks through merge
+commits that record nothing but a sync. A commit is attributed to `ec2-user`
+because a build box had no `user.name`. A contribution has to be rejected months
+after the fact because it never carried a `Signed-off-by` trailer.
+
+None of these are caught by a linter, a type checker, or a test suite. They are
+all caught by review — which means inconsistently, by whoever happens to be
+looking, and only after the work is done.
+
+Commit Check treats commit metadata the way linters treat code: a policy written
+down once, enforced identically everywhere, with a stable identifier for every
+diagnostic so findings can be discussed, cited, and tracked.
+
+
+
+- :material-file-cog-outline:{ .lg .middle } __One config__
+
+ ---
+
+ A single `cchk.toml` drives the CLI, the pre-commit hook, the GitHub Action
+ and the MCP server. There is no second place where the rules can disagree
+ with themselves.
+
+- :material-lightning-bolt-outline:{ .lg .middle } __Fails where it is cheap__
+
+ ---
+
+ The same check that runs in CI runs in your `commit-msg` hook. A malformed
+ subject costs a second locally, or a full CI cycle plus a force-push
+ remotely.
+
+- :material-tag-outline:{ .lg .middle } __Stable rule IDs__
+
+ ---
+
+ Every rule has an ID like `CC003` that never changes once released. Cite it
+ in a review comment, link to its documentation, suppress it per-rule.
+
+- :material-shield-check:{ .lg .middle } __Built to be trusted__
+
+ ---
+
+ SLSA Level 3 build provenance with artifact attestation you can verify
+ before installing. A failure names the rule, quotes the offending value,
+ and says how to fix it.
+
+
+
## What it checks
@@ -101,7 +154,7 @@ whatever your AI agent is committing on your behalf.
Require the `Signed-off-by` trailer locally, so contributors find out before
CI rejects the pull request.
- [:octicons-arrow-right-24: Signoff guide](guides/signoff.md)
+ [:octicons-arrow-right-24: Policy guides](guides/policies.md#require-signoff-dco)
- :material-robot-outline:{ .lg .middle } __AI attribution__
@@ -110,7 +163,7 @@ whatever your AI agent is committing on your behalf.
Whatever your project has decided about AI-assisted commits, enforce it
mechanically instead of relitigating it in review.
- [:octicons-arrow-right-24: AI attribution guide](guides/ai-attribution.md)
+ [:octicons-arrow-right-24: Policy guides](guides/policies.md#ai-attribution)
- :material-office-building-outline:{ .lg .middle } __Org-wide policy__
@@ -119,34 +172,88 @@ whatever your AI agent is committing on your behalf.
Inherit a base config from a shared repository, then let each project
override only what it needs.
- [:octicons-arrow-right-24: Organization guide](guides/organization.md)
+ [:octicons-arrow-right-24: Integrations](guides/integrations.md#across-an-organization)
-## Built to be trusted
+## What it is not
+
+Commit Check is deliberately narrow: it validates *metadata*, not code.
+
+- **Not a code linter.** It never reads your source files.
+- **Not a replacement for review.** It enforces the mechanical rules so review
+ can spend its attention on the change itself.
+- **Not opinionated by default.** Most rules are off until you turn them on. See
+ the [rules reference](rules.md) for what applies out of the box.
+
+It is a lightweight, open alternative to
+[GitHub Enterprise metadata restrictions](https://docs.github.com/en/enterprise-server@3.11/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions)
+and Bitbucket's paid
+[Yet Another Commit Checker](https://marketplace.atlassian.com/apps/1211854/yet-another-commit-checker),
+without requiring a particular forge or an enterprise plan. If you already run
+`ruff`, `eslint` or `golangci-lint` on your source, Commit Check is the
+equivalent for the commits that carry it.
+
+## Ecosystem
+
+One policy engine, multiple enforcement surfaces. Write your `cchk.toml` once —
+every surface reads the same file.
+
+```mermaid
+graph TB
+ subgraph Policy["📄 cchk.toml"]
+ direction LR
+ Config[One policy file]
+ end
+
+ subgraph Engine["⚙️ commit-check
(Python core)"]
+ direction LR
+ CLI[CLI & pre-commit]
+ API[Python API]
+ end
+
+ subgraph Surfaces["🚀 Enforcement surfaces"]
+ Action[commit-check-action
GitHub Action]
+ MCP[commit-check-mcp
MCP Server]
+ end
+
+ Config --> Engine
+ CLI --> Action
+ API --> MCP
+ Action --> CI[CI Pipeline]
+ MCP --> Agent[AI Coding Agent]
+```
-- :material-shield-check:{ .lg .middle } __SLSA Level 3__
+- :fontawesome-brands-python: __commit-check__
---
- Build provenance with artifact attestation you can verify before
- installing.
+ **Core engine** — Python CLI, library and pre-commit hooks. Runs every
+ validation the other surfaces expose.
-- :material-tag-outline:{ .lg .middle } __Stable rule IDs__
+ [:octicons-arrow-right-24: Getting started](getting-started.md)
+ [:octicons-arrow-right-24: Repo](https://github.com/commit-check/commit-check)
+
+- :material-github: __commit-check-action__
---
- Every diagnostic carries an ID like `CC003` that never changes, so you can
- cite it in review, suppress it, or feed it to tooling.
+ **GitHub Action** — CI integration that posts results as check runs, job
+ summaries and pull request comments.
-- :material-source-commit:{ .lg .middle } __Used in production__
+ [:octicons-arrow-right-24: Guide](guides/integrations.md#in-github-actions)
+ [:octicons-arrow-right-24: Repo](https://github.com/commit-check/commit-check-action)
+
+- :material-robot: __commit-check-mcp__
---
- Running at Apache, Texas Instruments, Mila, and
- [many more](https://github.com/commit-check/commit-check-action/network/dependents).
+ **MCP server** — exposes the validations as structured tools for AI coding
+ agents such as Claude Code, Cursor and Copilot.
+
+ [:octicons-arrow-right-24: Repo](https://github.com/commit-check/commit-check-mcp)
@@ -233,48 +340,7 @@ whatever your AI agent is committing on your behalf.
-## Ecosystem
-
-Commit Check is a family of projects — one engine, multiple surfaces.
-Write your policy **once** in a `cchk.toml`, enforce it **everywhere**.
-
-
-
-- :fontawesome-brands-python: __commit-check__ `v2.11.0`
-
- ---
-
- **Core engine** — Python CLI, library & pre-commit hooks.
-
- :material-star: AI attribution governance, message patterns, JSON output
-
- [:octicons-arrow-right-24: Docs](getting-started/installation.md)
- [:octicons-arrow-right-24: Repo](https://github.com/commit-check/commit-check)
-
-- :material-github: __commit-check-action__ `v2.10.0`
-
- ---
-
- **GitHub Action** — seamless CI integration with PR comments.
-
- :material-star: Windows runner, PR title validation
-
- [:octicons-arrow-right-24: Docs](guides/github-actions.md)
- [:octicons-arrow-right-24: Repo](https://github.com/commit-check/commit-check-action)
-
-- :material-robot: __commit-check-mcp__ `v0.1.7`
-
- ---
-
- **MCP Server** — structured tools for AI coding agents.
-
- :material-star: AI attribution governance, message patterns
-
- [:octicons-arrow-right-24: Repo](https://github.com/commit-check/commit-check-mcp)
-
-
-
-[See all projects →](projects.md){ .md-button }
+And [many more](https://github.com/commit-check/commit-check-action/network/dependents).
## Ready in two minutes
@@ -286,8 +352,8 @@ $ commit-check --message --branch
No configuration file needed to start — sensible defaults apply immediately, and
you tighten them when you are ready.
-[Install :octicons-arrow-right-24:](getting-started/installation.md){ .md-button .md-button--primary }
-[Why Commit Check?](getting-started/why.md){ .md-button }
+[Get started :octicons-arrow-right-24:](getting-started.md){ .md-button .md-button--primary }
+[Rules reference](rules.md){ .md-button }
---
diff --git a/docs/projects.md b/docs/projects.md
deleted file mode 100644
index 8226890..0000000
--- a/docs/projects.md
+++ /dev/null
@@ -1,41 +0,0 @@
----
-hide:
- - toc
----
-
-# Projects
-
-The commit-check ecosystem is built on a simple architecture: **one policy engine,
-multiple enforcement surfaces.** Write your `cchk.toml` once — every surface
-reads the same file.
-
-```mermaid
-graph TB
- subgraph Policy["📄 cchk.toml"]
- direction LR
- Config[One policy file]
- end
-
- subgraph Engine["⚙️ commit-check
(Python core)"]
- direction LR
- CLI[CLI & pre-commit]
- API[Python API]
- end
-
- subgraph Surfaces["🚀 Enforcement surfaces"]
- Action[commit-check-action
GitHub Action]
- MCP[commit-check-mcp
MCP Server]
- end
-
- Config --> Engine
- CLI --> Action
- API --> MCP
- Action --> CI[CI Pipeline]
- MCP --> Agent[AI Coding Agent]
-```
-
-| Surface | What it does | Get started |
-|---------|-------------|-------------|
-| **commit-check** | CLI tool, pre-commit hooks, and Python library. The core engine that runs all validations. | [`commit-check/commit-check`](https://github.com/commit-check/commit-check) |
-| **commit-check-action** | GitHub Action wrapping the core engine. Posts results as check runs, job summaries, and PR comments. | [`commit-check/commit-check-action`](https://github.com/commit-check/commit-check-action) |
-| **commit-check-mcp** | MCP server that exposes validations as structured tools for AI coding agents (Claude Code, Cursor, Copilot, etc.). | [`commit-check/commit-check-mcp`](https://github.com/commit-check/commit-check-mcp) |
diff --git a/docs/what-is-new.md b/docs/what-is-new.md
deleted file mode 100644
index a64fc17..0000000
--- a/docs/what-is-new.md
+++ /dev/null
@@ -1,127 +0,0 @@
-# Release highlights
-
-The changes worth knowing about, newest first, each pointing at the page that
-documents it properly. For the full record of every change, see the
-[changelog](changelog.md).
-
-## 2.13.0 — Stable rule IDs
-
-Every diagnostic now carries an ID that never changes once released, so a
-failure can be cited in review, looked up, or matched by tooling.
-
-```console
-$ commit-check --message
-CC003 subject-imperative check failed ==> docs: revamped the profile
-Commit message should use imperative mood (e.g., 'fix bug' not 'fixed bug')
-Suggest: Change the first verb to imperative form
-Docs: https://commit-check.com/rules/#cc003
-```
-
-The ID also appears in `--format json` as `rule_id`, next to a `docs_url`. In a
-terminal that renders hyperlinks the ID *is* the link, and the `Docs:` line is
-dropped — piped output and CI logs keep it.
-
-`docs/`, `ci/`, `test/`, `refactor/`, `build/`, `perf/` and `style/` also join
-the default branch types.
-
-[:octicons-arrow-right-24: Rules reference](rules.md)
-
-## 2.12.0 — Custom author patterns
-
-`author_name` and `author_email` accept a regex of your own, so a team can
-require its own naming convention or email domain rather than the built-in
-patterns.
-
-```toml title="cchk.toml"
-[commit]
-author_email = "^.+@example\\.com$"
-```
-
-[:octicons-arrow-right-24: CC101](rules.md#cc101) ·
-[CC102](rules.md#cc102)
-
-## 2.11.0 — AI attribution policy
-
-Commits carrying the trailers AI coding tools add — Claude Code, Copilot,
-Codex, Gemini, Cursor, Devin, Aider, Windsurf, Tabby — can now be rejected.
-
-```toml title="cchk.toml"
-[commit]
-ai_attribution = "forbid" # "ignore" is the default
-```
-
-Whether AI-assisted commits are acceptable is a policy question with no single
-right answer, so this stays off until you turn it on.
-
-[:octicons-arrow-right-24: AI attribution guide](guides/ai-attribution.md) ·
-[CC013](rules.md#cc013)
-
-## 2.10.0 — Bot branch prefixes accepted by default
-
-`dependabot/` and `renovate/` branches pass branch validation without
-configuration. Automation was previously failing a check it could not satisfy.
-
-[:octicons-arrow-right-24: CC201](rules.md#cc201)
-
-## 2.9.0 — AI agent branch prefixes accepted by default
-
-`ai/`, `claude/`, `codex/`, `copilot/` and `cursor/` joined the default branch
-types, following
-[Conventional Branch v1.1.0](https://conventional-branch.github.io/).
-
-[:octicons-arrow-right-24: CC201](rules.md#cc201)
-
-## 2.8.0 — Custom message patterns
-
-`message_pattern` replaces the generated Conventional Commits regex with one of
-your own, for teams that already enforce a different format.
-
-```toml title="cchk.toml"
-[commit]
-message_pattern = "^PROJ-\\d+: .+"
-```
-
-This release also dropped Python 3.9. The minimum is now 3.10.
-
-[:octicons-arrow-right-24: CC001](rules.md#cc001) ·
-[Configuration](configuration.md)
-
-## 2.7.0 — Force push blocking
-
-A `pre-push` hook that refuses a force push to a shared branch, plus a
-`--no-force-push` flag for running the same check by hand.
-
-```toml title="cchk.toml"
-[push]
-allow_force_push = false
-```
-
-[:octicons-arrow-right-24: CC301](rules.md#cc301) ·
-[Command-line recipes](example.md#blocking-force-pushes)
-
-## 2.6.0 — Output controls for scripts and CI
-
-`--format json` for machine-readable results, `--compact` for one line per
-failure, and `--no-banner` to drop the ASCII art that only adds noise to a CI
-log.
-
-[:octicons-arrow-right-24: Command-line recipes](example.md#output-for-scripts-and-ci)
-
-## 2.5.0 — Organization-wide configuration
-
-`inherit_from` lets a repository pull a shared base config and override only
-what it needs, so a policy change no longer means editing every repository.
-
-```toml title=".github/cchk.toml"
-inherit_from = "github:my-org/.github:cchk.toml"
-```
-
-[:octicons-arrow-right-24: Organization guide](guides/organization.md)
-
-## 2.0.0 — TOML configuration
-
-The configuration format moved from YAML to TOML, the CLI was simplified, and
-settings became overridable by environment variable and command-line flag.
-This is a breaking change from 1.x.
-
-[:octicons-arrow-right-24: Migrating from v1](migration.md)
diff --git a/mkdocs.yml b/mkdocs.yml
index 23ec40d..5b6975f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -17,6 +17,14 @@ edit_uri: edit/main/docs/
docs_dir: docs
+# The deploy workflow builds with --strict, which turns these into errors. The
+# pages cross-link by section anchor rather than by page alone, and an anchor
+# that no longer exists is invisible in a rendered page — it just scrolls to the
+# top. Failing the build is the only way that gets noticed.
+validation:
+ unrecognized_links: warn
+ anchors: warn
+
theme:
name: material
language: en
@@ -133,16 +141,10 @@ hooks:
nav:
- Home: index.md
- - Getting started:
- - Installation: getting-started/installation.md
- - Quick start: getting-started/quickstart.md
- - Why Commit Check: getting-started/why.md
+ - Getting started: getting-started.md
- Guides:
- - Pre-commit hook: guides/pre-commit.md
- - GitHub Actions: guides/github-actions.md
- - Organization-wide policy: guides/organization.md
- - Signoff and DCO: guides/signoff.md
- - AI attribution policy: guides/ai-attribution.md
+ - Integrations: guides/integrations.md
+ - Policy guides: guides/policies.md
- Command-line recipes: example.md
- Reference:
- Rules: rules.md
@@ -150,8 +152,6 @@ nav:
- About:
- Migrating from v1: migration.md
- Troubleshooting: troubleshoot.md
- - Release highlights: what-is-new.md
- Changelog: changelog.md
- - Projects: projects.md
- Blog:
- blog/index.md
diff --git a/netlify.toml b/netlify.toml
index 0d67e73..8478346 100644
--- a/netlify.toml
+++ b/netlify.toml
@@ -75,7 +75,7 @@
[[redirects]]
from = "/what-is-new.html"
- to = "/what-is-new/"
+ to = "/changelog/"
status = 301
force = true
@@ -101,7 +101,7 @@
[[redirects]]
from = "/README.html"
- to = "/getting-started/installation/"
+ to = "/getting-started/"
status = 301
force = true
@@ -117,10 +117,11 @@
status = 301
force = true
-# "Getting started" is a nav section rather than a page, so the bare directory
-# has nothing to serve. The old landing site published this URL.
-[[redirects]]
- from = "/getting-started/"
- to = "/getting-started/quickstart/"
- status = 301
- force = true
+# "Getting started" used to be a nav section with nothing at its own URL, and
+# this file redirected the bare directory to the quick start page. It is a real
+# page now, so the redirect is gone — a forced redirect here would shadow it.
+#
+# The pages that were merged into it, and the other retired URLs, are covered by
+# the stubs scripts/mkdocs_hooks.py writes into the build. Those are directory
+# URLs with no page behind them, so unlike the .html rules above they cannot
+# collide with anything and need no entry here.
diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py
index c3b30da..bb0f49b 100644
--- a/scripts/mkdocs_hooks.py
+++ b/scripts/mkdocs_hooks.py
@@ -20,15 +20,39 @@
"migration": "migration/",
"troubleshoot": "troubleshoot/",
"changelog": "changelog/",
- "what-is-new": "what-is-new/",
# The CLI reference is no longer a generated page; the flags it listed are
# documented alongside the settings that control them.
"cli_args": "configuration/",
"cli": "configuration/",
- "README": "getting-started/installation/",
+ "README": "getting-started/",
+ "what-is-new": "changelog/",
"genindex": "",
}
+#: Retired page URL -> the page that absorbed it.
+#
+# Unlike LEGACY_URLS these are directory URLs, so the stub is written to
+# ``/index.html``. Nothing is served at the old path any more, so the stub
+# cannot shadow a real page the way a flat ``rules.html`` would, and it is
+# written on every host rather than skipped on Netlify.
+#
+# Two URLs are deliberately absent: ``rules/`` and ``configuration/``. The rule
+# IDs printed by every released version of the package link to
+# ``commit-check.com/rules/#ccNNN`` — the URL is hardcoded in
+# ``commit_check/rules_catalog.py`` — so those two pages do not move.
+MOVED_URLS = {
+ "getting-started/installation": "getting-started/",
+ "getting-started/quickstart": "getting-started/",
+ "getting-started/why": "",
+ "guides/pre-commit": "guides/integrations/",
+ "guides/github-actions": "guides/integrations/",
+ "guides/organization": "guides/integrations/",
+ "guides/signoff": "guides/policies/",
+ "guides/ai-attribution": "guides/policies/",
+ "what-is-new": "changelog/",
+ "projects": "",
+}
+
# Redirect stubs for the URLs the Sphinx site served.
# The script carries the fragment across, because the links most worth keeping
# alive are the per-rule ones (``rules.html#cc003``) and a plain redirect drops
@@ -58,18 +82,27 @@
def on_post_build(config, **kwargs) -> None:
- """Write a redirect stub for each URL the Sphinx site used to serve."""
+ """Write a redirect stub for each URL this site no longer serves."""
site = Path(config["site_dir"])
- # On Netlify the stubs would be served in place of the real pages: Netlify
- # resolves ``/rules/`` to the file ``rules.html``, so the stub that
+ # Deploy previews pass their own URL in, and it may arrive without the
+ # trailing slash the targets below are joined onto.
+ base = (config["site_url"] or "/").rstrip("/") + "/"
+
+ # Retired pages first: these run on every host, Netlify included. The old
+ # path has no page of its own any more, so the stub is the only thing that
+ # can answer for it.
+ for old, target in MOVED_URLS.items():
+ stub = site / old / "index.html"
+ stub.parent.mkdir(parents=True, exist_ok=True)
+ stub.write_text(REDIRECT.format(url=base + target), encoding="utf-8")
+
+ # On Netlify the .html stubs would be served in place of the real pages:
+ # Netlify resolves ``/rules/`` to the file ``rules.html``, so the stub that
# redirects to ``/rules/`` would shadow ``rules/index.html`` and loop. The
# ``[[redirects]]`` table in netlify.toml covers the same URLs with real
- # 301s, so the stubs are only written for hosts without redirects.
+ # 301s, so these are only written for hosts without redirects.
if os.environ.get("NETLIFY") == "true":
return
- # Deploy previews pass their own URL in, and it may arrive without the
- # trailing slash the targets below are joined onto.
- base = (config["site_url"] or "/").rstrip("/") + "/"
for legacy, target in LEGACY_URLS.items():
(site / f"{legacy}.html").write_text(
REDIRECT.format(url=base + target), encoding="utf-8"