docs: release notes and install pins for commit-check 2.17.0 (#34)

Author: shenxianpeng

docs/changelog.md

@@ -11,6 +11,7 @@ below and to the page that documents the feature properly.
 
 | Version | What changed | Documented in |
 |---|---|---|
+| [2.17.0](#v2170) | Concrete corrections for mechanical slips; a `warn` level per rule | [Reading the JSON](example.md#reading-the-json) · [Report without enforcing](configuration.md#report-a-rule-without-enforcing-it) |
 | [2.16.0](#v2160) | Tag name validation, and file size, path and pattern policies | [CC401](rules.md#cc401) · [CC302–CC304](rules.md#push-rules) |
 | [2.15.1](#v2151) | Color and rule-ID links appear only where they render; `NO_COLOR` honoured | [Color and links](example.md#color-and-links) |
 | [2.15.0](#v2150) | `--rev` names the commit under test; skipped checks are named on stderr | [Command-line recipes](example.md#checking-a-range-of-commits) |
@@ -27,6 +28,49 @@ below and to the page that documents the feature properly.
 | [2.5.0](#v250) | Organization-wide config with `inherit_from` | [Across an organization](guides/organization.md) |
 | [2.0.0](#v200) | Configuration moved from YAML to TOML — breaking | [Migrating from v1](migration.md) |
 
+## v2.17.0 (2026-09-06) { #v2170 }
+
+### Added
+
+* **A failed check names its correction when there is exactly one** — a type
+  written `Fix` where `fix` is allowed, a letter out of place (`feta`), a
+  missing colon after a recognised type, a `WIP:` marker, a missing
+  `Signed-off-by` trailer, a branch typed `Feature/x`, an AI attribution line
+  under `ai_attribution = "forbid"`: the suggestion now says what to use
+  (`Use "fix: add x"`) instead of restating the rule, and `--format json` and
+  the Python API carry the corrected value in a new `fix` field. `fix` stays
+  empty whenever the correction takes a judgment — a subject with no type, one
+  over the length limit, a verb that is not imperative — so a tool can apply a
+  non-empty `fix` as it stands. The pre-commit hook, the Action and the App
+  show the better suggestion with no change on their side; the MCP server
+  passes `fix` through to agents.
+  See PR [#564](https://github.com/commit-check/commit-check/pull/564) and
+  [Reading the JSON](example.md#reading-the-json).
+
+* **A rule can be reported without being enforced** — a top-level
+  `warn = ["branch", "CC003"]` runs the named rules, prints their findings in
+  full, and never fails the run. A warned rule prints `warning` in place of
+  `failed`, no rejection banner, and one closing line saying the run is not
+  failed by it; `--compact` prints one `[WARN]` line. The exit code counts
+  only enforced rules. In `--format json` the check's `status` is `warn`, the
+  top-level `status` stays `pass`, and a `warnings` count is added. A name
+  that matches no rule is a configuration error, so a typo cannot leave a rule
+  silently enforced. This is how a team adopts a rule gradually: turn it on
+  as a warning, watch what it catches, drop it from `warn` when the history
+  is clean.
+  See PR [#565](https://github.com/commit-check/commit-check/pull/565) and
+  [Report a rule without enforcing it](configuration.md#report-a-rule-without-enforcing-it).
+
+### Fixed
+
+* **CC002 reads a plain subject from its first word** — the capitalisation
+  check treated any first word as a Conventional Commits type, so
+  `Add feature` failed on the `f` of `feature`, `Update` alone failed, and
+  `add Feature` passed. Only a prefix that ends in a colon is a type now:
+  the first two pass, the third fails. See PR
+  [#564](https://github.com/commit-check/commit-check/pull/564) and
+  [CC002](rules.md#cc002).
+
 ## v2.16.0 (2026-08-31) { #v2160 }
 
 ### Added

docs/configuration.md

@@ -130,12 +130,51 @@ the head branch.
 pre-commit hook and the Action, which have no pull request to read. The
 setting is read by the App only.
 
+## Report a rule without enforcing it
+
+A rule is normally on or off. `warn` gives it a third setting: run, report the
+finding in full, and never fail the run. It is a top-level key, so it goes
+before the first section, and it names a check or its rule ID in any case:
+
+```toml title="cchk.toml"
+warn = ["branch", "CC003"]
+
+[commit]
+subject_imperative = true
+
+[branch]
+conventional_branch = true
+```
+
+A warned rule prints the same block as a failure with `warning` in place of
+`failed`, no rejection banner, and one closing line saying the run is not
+failed by it; with `--compact` it is one `[WARN]` line. A one-line notice on
+stderr names the warned rules, so a hook that exits `0` after red-looking
+output is not mistaken for a broken hook. The exit code counts only enforced
+rules. In `--format json` the check's `status` is `warn`, the top-level
+`status` stays `pass` unless an enforced rule failed, and `warnings` counts
+them — see [Reading the JSON](example.md#reading-the-json).
+
+A name that matches no rule is a configuration error that lists the known
+rules, so a typo cannot leave a rule silently enforced. Rules not listed
+behave as before.
+
+This is how a team adopts a rule gradually: turn it on as a warning, watch
+what it catches for a week, then drop it from `warn` once the history is
+clean. It is also how a [shared config](guides/organization.md) carries both
+kinds of rule at once — the ones every repository must satisfy, and the ones
+it is asking teams to move towards. A repository's own `warn` list replaces
+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:
 
 ```toml title="cchk.toml"
+# changed: report the branch rule without enforcing it (nothing is warned by default)
+warn = ["branch"]
+
 [commit]
 # https://www.conventionalcommits.org
 conventional_commits = true
@@ -201,7 +240,7 @@ Used from a hook definition, with no config file anywhere in the repository:
 ```yaml title=".pre-commit-config.yaml"
 repos:
   - repo: https://github.com/commit-check/commit-check
-    rev: v2.16.0
+    rev: v2.17.0
     hooks:
       - id: check-message
         args:

docs/example.md

@@ -131,7 +131,7 @@ pushed:
 ```yaml title=".pre-commit-config.yaml"
 repos:
   - repo: https://github.com/commit-check/commit-check
-    rev: v2.16.0
+    rev: v2.17.0
     hooks:
       - id: check-no-force-push
         stages: [pre-push]
@@ -303,3 +303,17 @@ $ echo "Fix: add streaming support" | commit-check -m --format json | jq '.check
 type at all, one over the length limit, a verb that is not imperative — and
 `suggest` then keeps the rule's general advice. A tool can apply a non-empty
 `fix` as it stands; a person only ever needs `suggest`.
+
+A rule listed under [`warn`](configuration.md#report-a-rule-without-enforcing-it)
+reports with `"status": "warn"` instead of `"fail"`. The top-level `status` is
+`fail` only when an enforced rule failed, and a top-level `warnings` counts
+the warned checks, so a tool that tests `status == "fail"` is unaffected and
+one that wants the warnings knows where to look:
+
+```console
+$ commit-check -m -b --format json | jq '{status, warnings}'
+{
+  "status": "pass",
+  "warnings": 1
+}
+```

docs/guides/organization.md

@@ -107,9 +107,15 @@ inherit_from = "github:my-org/.github@v1:cchk.toml"
 Turning on a strict policy across an organization at once produces a wall of
 red. A gentler sequence:
 
-1. Ship the org config with [`dry-run`](github-actions.md#reporting-without-failing) enabled in
-   CI, so violations are reported but nothing blocks.
+1. Ship the org config with the new rules listed under
+   [`warn`](../configuration.md#report-a-rule-without-enforcing-it), so
+   violations are reported in every hook, Action run and App check, and
+   nothing blocks. (The Action's
+   [`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.
-3. Turn off `dry-run` for repositories whose history is already clean.
+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.
 4. Tighten the shared config over time.

docs/guides/pre-commit.md

@@ -8,7 +8,7 @@ Add Commit Check to `.pre-commit-config.yaml`:
 ```yaml title=".pre-commit-config.yaml"
 repos:
   - repo: https://github.com/commit-check/commit-check
-    rev: v2.16.0
+    rev: v2.17.0
     hooks:
       - id: check-message
       - id: check-branch
@@ -55,7 +55,7 @@ Options can be passed as hook arguments, which keeps everything in one file:
 ```yaml title=".pre-commit-config.yaml"
 repos:
   - repo: https://github.com/commit-check/commit-check
-    rev: v2.16.0
+    rev: v2.17.0
     hooks:
       - id: check-message
         args:

docs/index.md

@@ -36,7 +36,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.16.0
+        rev: v2.17.0
         hooks:
           - id: check-message
           - id: check-branch