docs(style): enforce changed-file readability gate

AGENTS.md

@@ -294,6 +294,11 @@ flow, declarations, assertions, or cleanup onto one line to reduce line or
 token count. Grouped missions may and should use small comprehensible commits.
 Perform an explicit readability review before the final commit.
 
+Readable source is a blocking acceptance criterion. Every new or modified C/H
+file must pass the changed-file `clang-format` check; tests and fixtures follow
+the same rule. Run `tools/check_changed_c_format.sh <base-revision>` without
+formatting unrelated historical files.
+
 Canonical documents:
 
 - `README.md`;

docs/coding_style.md

@@ -102,24 +102,21 @@ explicit control-flow braces, vertical long parameter lists, and no short
 function or control body on one line. Contract literals may exceed the target
 when splitting them would make the protocol less reviewable.
 
-Do not apply the formatter blindly to the entire historical tree. A change
+Readable source is a blocking acceptance criterion. Do not compress source to
-normalizes the files it owns and checks that explicit scope. The reproducible,
+save lines or model tokens. Tests and fixtures follow the same standard.
-non-mutating check for the currently normalized C readability scope is:
+
+Do not apply the formatter blindly to the entire historical tree. Format the
+new or modified regions, then use the reproducible, non-mutating changed-file
+gate with the branch base revision:
 
 ```bash
-clang-format --dry-run --Werror \
+tools/check_changed_c_format.sh main
-  tui/src/dashboard_layout.c \
-  tui/src/generation_mtp.c \
-  tui/src/json_writer.c \
-  tui/src/web_dashboard.c \
-  tui/src/web_dashboard_json.c \
-  tui/include/trainlog/generation_mtp.h \
-  tui/tools/generation_mtp_adapter.c \
-  tui/tests/generation_mtp_adapter_double.c \
-  tui/tests/test_generation_mtp.c \
-  tui/tests/test_web_server.c
 ```
 
+The helper derives the merge-base, includes changed and untracked C/H files,
+and invokes `clang-format --dry-run --Werror` without modifying them. A
+different base revision may be supplied for stacked work.
+
 Formatting changes should not be mixed with unrelated semantic changes when
 avoidable. Review readability explicitly before the final commit, including
 tests and cleanup/error paths.

tools/check_changed_c_format.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+# Check only C and header files changed from a caller-selected Git base.
+
+set -eu
+
+base_ref=${1:-main}
+base_commit=$(git merge-base HEAD "$base_ref")
+temporary_list=$(mktemp)
+trap 'rm -f "$temporary_list"' EXIT HUP INT TERM
+
+{
+    git diff --name-only --diff-filter=ACMR "$base_commit" -- '*.c' '*.h'
+    git ls-files --others --exclude-standard -- '*.c' '*.h'
+} | sort -u >"$temporary_list"
+
+if [ ! -s "$temporary_list" ]; then
+    echo "CHANGED_C_FORMAT=PASS (no changed C/H files)"
+    exit 0
+fi
+
+while IFS= read -r source_file; do
+    clang-format --dry-run --Werror "$source_file"
+done <"$temporary_list"
+
+echo "CHANGED_C_FORMAT=PASS"