commit-check · shenxianpeng · Sep 13, 2026 · Sep 13, 2026 · Sep 13, 2026 · coderabbitai
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -8,8 +8,7 @@ in more than one, the first one listed wins:
 3. **A configuration file** — `cchk.toml` or `commit-check.toml`
 4. **Built-in defaults**
 
-That ordering is what makes the layering useful: the file carries the policy
-the project agreed on, the environment overrides it for a single CI job, and a
+The file carries the policy the project agreed on, the environment overrides it for a single CI job, and a
 flag overrides both for a single run.
 
 !!! tip "Defaults are not "nothing""
@@ -169,7 +168,7 @@ the shared one, as any inherited key does.
 ## A worked example
 
 Every line below that differs from the built-in default is marked, so it is
-clear what this file is actually changing:
+clear what this file changes:
 
 ```toml title="cchk.toml"
 # changed: report the branch rule without enforcing it (nothing is warned by default)

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -81,7 +81,7 @@ $ git commit --amend -m "fix(parser): handle empty input"
 $ commit-check --message
 ```
 
-No output and an exit code of `0`. Commit Check is quiet when it is happy.
+It prints nothing and exits with code `0`.
 
 ## 4. Check the branch too
 
@@ -172,8 +172,9 @@ belongs:
 
 ## Verifying the download
 
-Releases are built with [SLSA Level 3](https://slsa.dev) provenance. To verify a
-release artifact came from this repository's build pipeline:
+Every release is published with a signed
+[build provenance attestation](https://docs.github.com/en/actions/concepts/security/artifact-attestations). To verify
+a release artifact came from this repository's build pipeline:
 
 ```console
 $ gh attestation verify commit_check-*.whl --repo commit-check/commit-check

diff --git a/docs/guides/github-actions.md b/docs/guides/github-actions.md
@@ -1,7 +1,7 @@
 # GitHub Action
 
-Local hooks can be skipped. A CI check cannot, which makes GitHub Actions the
-place where your policy is actually a policy.
+Local hooks can be skipped. A CI check cannot, so the Action is where the
+policy is enforced.
-Local hooks can be skipped. A CI check cannot, so the Action is where the
-policy is enforced.
+Local hooks can be skipped. A required Action check enforces the policy before
+merge, while a skipped workflow leaves the required check pending.
-Local hooks can be skipped. A CI check cannot, so the Action is where the
-policy is enforced.
+Local hooks can be skipped. A required Action check enforces the policy before
+merge, while a skipped workflow leaves the required check pending.
 
 ```yaml title=".github/workflows/commit-check.yml"
 name: Commit Check

diff --git a/docs/guides/github-app.md b/docs/guides/github-app.md
@@ -108,7 +108,7 @@ inheritance [fails open](organization.md#other-sources).
 A repository with no config file first looks to its account: a `cchk.toml` in
 the owner's `.github` repository — organizations and personal accounts both
 have one — is applied as if it were the repository's own, and the report says
-so in its last lines. That is enforcement, not advice — the owner chose the
+so in its last lines. Its failures are enforced, because the owner chose those
 rules.
 
 A repository with no config file **and** no shared one has not chosen its
@@ -125,7 +125,8 @@ conventional_commits = true
 conventional_branch = true  # false if branch names are free-form
 ```
 
-Add it, push, and failures are failures. A pass is a pass either way.
+Once the file is pushed, a failure turns the check red instead of neutral. A
+passing result is the same with or without it.
 
 !!! warning "Required means nothing until there is a config"
 
@@ -156,8 +157,8 @@ in the branch's ruleset or branch protection, where the repository's plan
 allows one. With that in place a failing result blocks the merge button and a
 passing one clears it.
 
-The order matters: config file first, then the required check, for the reason
-in the box above.
+Add the config file first and the required check second, for the reason in
+the box above.
 
 ## Across an organization
 

diff --git a/docs/guides/integrations.md b/docs/guides/integrations.md
@@ -1,8 +1,8 @@
 # Where to run it
 
 Commit Check is one rule engine with several places to run it, and every one
-of them reads the same `cchk.toml`. That is the point: the rules cannot drift
-between what a developer sees locally and what is enforced on the pull request.
+of them reads the same `cchk.toml`, so the rules cannot drift between what a
+developer sees locally and what is enforced on the pull request.
 
 | Where | Catches problems | Can be bypassed | Set up |
 |---|---|---|---|

diff --git a/docs/guides/organization.md b/docs/guides/organization.md
@@ -114,7 +114,7 @@ red. A gentler sequence:
    [`dry-run`](github-actions.md#reporting-without-failing) does the same
    for every rule at once, in the Action only.)
 2. Look at what actually fails. Some rules will turn out to be wrong for some
-   teams — that is information, not an obstacle.
+   teams, and those teams can override them in their own config.
 3. Drop a rule from `warn` once the repositories are clean. A repository that
    is already clean can drop it early with a `warn` list of its own, which
    replaces the shared one.

diff --git a/docs/guides/policies.md b/docs/guides/policies.md
@@ -14,8 +14,8 @@ require every commit to carry a `Signed-off-by` trailer. The Linux kernel and
 much of the CNCF work this way.
 
 A DCO bot rejecting a pull request after the fact is a poor experience: the
-contributor has to rewrite history for every commit in the branch. Checking
-locally fixes it before it becomes a problem.
+contributor has to rewrite history for every commit in the branch. A local check
+catches a missing sign-off at commit time, before there is anything to rewrite.
 
 ### Turn it on
 
@@ -157,7 +157,7 @@ Most projects that allow AI assistance ask to be told about it. The
 [Fedora](https://docs.fedoraproject.org/en-US/council/policy/ai-policy/) and
 FluxCD want an `Assisted-by:` trailer; the
 [Apache Software Foundation](https://www.apache.org/legal/generative-tooling.html)
-recommends `Generated-by:`. The kernel adds a second rule: an AI agent must
+recommends `Generated-by:`. The kernel also says an AI agent must
 never add a `Signed-off-by:` line, because only a person can certify the
 [DCO](https://developercertificate.org/).
 
@@ -234,8 +234,8 @@ The Assisted-by value does not match the required pattern: ^\S+/\S+$
 Suggest: Write the Assisted-by value so that it matches ^\S+/\S+$ (set by ai_disclosure_pattern in the [commit] config)
 ```
 
-There is no correction for that one: which model, in which format, is not
-something the tool should guess.
+That failure carries no correction, because the tool should not guess which
+model or format you meant.
 
 ### Disclosure that is appreciated, not required
 

diff --git a/docs/index.md b/docs/index.md
@@ -31,8 +31,7 @@ Suggest: Use "fix: add streaming support"
 Docs: https://commit-check.com/rules/#cc001
 ```
 
-It does not just say no. When the correction is unambiguous, it hands you
-the line.
+When the correction is unambiguous, it hands you the line.
 
 </div>
 </div>
@@ -214,10 +213,11 @@ $ pip install commit-check
 $ commit-check --message --branch
 ```
 
-No configuration file needed to start — sensible defaults apply immediately, and
-you tighten them when you are ready. Releases carry
-[SLSA Level 3](https://slsa.dev) build provenance, so you can verify an artifact
-came from this repository's pipeline before you install it.
+No configuration file needed to start: the defaults check Conventional Commits,
+Conventional Branch and subject length, and you tighten them when you are ready. Every release
+carries a signed [build provenance attestation](https://docs.github.com/en/actions/concepts/security/artifact-attestations),
+so you can verify an artifact came from this repository's pipeline before you
+install it.
 
 ## Pick where it runs
 
@@ -239,7 +239,7 @@ One policy engine, five places to enforce it. Every one of them reads the same
 
     ---
 
-    The fastest feedback there is: the commit is rejected before it exists.
+    It rejects a bad commit before Git records it.
     Opt-in by nature, so pair it with one of the enforced surfaces.
 
     [:octicons-arrow-right-24: Guide](guides/pre-commit.md)
@@ -313,9 +313,9 @@ GitHub can enforce some of the same policies natively, but the commit-metadata
 rules sit behind its Enterprise plan. For a twenty-person team that is the
 difference between $4 and $21 a seat — about $340 a month for a regular
 expression, which reports a bare mismatch where Commit Check reports a rule ID,
-a suggestion and a link. Nineteen dollars is what the same twenty people cost
-here — and the same twenty thousand.
-[The arithmetic and the honest caveats](compare/github-rules.md).
+a suggestion and a link. The Team plan here is $19 a month whatever the team
+size.
+[The arithmetic, and the caveats](compare/github-rules.md).
 
 ## Questions
 
@@ -328,9 +328,8 @@ here — and the same twenty thousand.
 
 ??? question "Can a developer bypass it?"
 
-    The pre-commit hook, yes — `git commit --no-verify` is one flag, and that
-    is by design: a local hook is fast feedback, not a gate. The enforcement
-    boundary is CI. Make the Action or the App a required status check and a
+    The pre-commit hook, yes: `git commit --no-verify` is one flag, and a local
+    hook is there for fast feedback. The enforcement boundary is CI. Make the Action or the App a required status check and a
     violating change cannot merge, however it was committed.
 
 ??? question "Will turning it on block everyone tomorrow?"
@@ -361,9 +360,12 @@ here — and the same twenty thousand.
 
 ??? question "How do I know the package I installed is the one you built?"
 
-    Releases carry [SLSA Level 3](https://slsa.dev) build provenance. The
-    GitHub Action verifies the attestation with `gh attestation verify` before
-    it installs anything, and fails the step if verification does not pass.
+    Every release carries a signed
+    [build provenance attestation](https://docs.github.com/en/actions/concepts/security/artifact-attestations)
+    naming the workflow in this repository that built it. Check a wheel
+    yourself with `gh attestation verify <file> --repo commit-check/commit-check`;
+    the GitHub Action runs the same check before it installs anything, and
+    fails the step if verification does not pass.
 
 ??? question "Who is behind this?"
 

diff --git a/docs/migration.md b/docs/migration.md
@@ -9,7 +9,7 @@ message and suggestion. You wrote the pattern; Commit Check ran it. In v2 the
 patterns are built in and the file selects and tunes them by name. A v1 file
 was mostly regex; a v2 file is mostly booleans.
 
-The practical consequence: you do not translate a v1 file line by line. You
+So you do not translate a v1 file line by line. You
 decide which rules you want and write those down, which is usually far shorter.
 
 ## Converting the file

diff --git a/docs/rules.md b/docs/rules.md
@@ -400,8 +400,8 @@ Rejects commits with an empty message.
 
 **Why is this bad?**
 
-A commit with no subject cannot be searched for, summarised, or reviewed. It is
-a gap in the history that nobody can fill in later.
+A commit with no subject cannot be searched for, summarised, or reviewed, and
+once it is pushed, adding a message means rewriting history.
 
 **Options**