From a4d7f5d350ffa6ad1f031283db8f9e26fd5e7df0 Mon Sep 17 00:00:00 2001
From: fy59 <fy59@proton.me>
Date: Fri, 18 Sep 2026 16:18:40 +0200
Subject: [PATCH] docs(style): enforce changed-file readability gate

---
 AGENTS.md                       |  5 +++++
 docs/coding_style.md            | 25 +++++++++++--------------
 tools/check_changed_c_format.sh | 25 +++++++++++++++++++++++++
 3 files changed, 41 insertions(+), 14 deletions(-)
 create mode 100755 tools/check_changed_c_format.sh

diff --git a/AGENTS.md b/AGENTS.md
index 3c299d3..32af629 100644
--- a/AGENTS.md
+++ b/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`;
diff --git a/docs/coding_style.md b/docs/coding_style.md
index 61874fa..3cf3088 100644
--- a/docs/coding_style.md
+++ b/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
-normalizes the files it owns and checks that explicit scope. The reproducible,
-non-mutating check for the currently normalized C readability scope is:
+Readable source is a blocking acceptance criterion. Do not compress source to
+save lines or model tokens. Tests and fixtures follow the same standard.
+
+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 \
-  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
+tools/check_changed_c_format.sh main
 ```
 
+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.
diff --git a/tools/check_changed_c_format.sh b/tools/check_changed_c_format.sh
new file mode 100755
index 0000000..6b66b49
--- /dev/null
+++ b/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"