prepare.cppm: add the file-length CI gate and the CHANGELOG entry

check_file_lengths.sh fails the build if src/build/prepare.cppm or any
file directly under src/build/prepare/ exceeds 2,500 lines, wired into
ci-linux.yml next to the other pure-text, no-toolchain check_*.sh
steps (check_version_pins.sh, check_modules_wiring.sh). Currently
passes: 13 files, all at or under the cap (the largest, plan.cpp, is
2,392).

CHANGELOG.md: one entry under 2026.9.27.1 describing the internal
decomposition -- no behavior change, so it sits in the existing
'其他' (other) section alongside the ELF-read-once note, not as its
own dated change.

Author: speak-agent

.github/tools/check_file_lengths.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+#
+# Guard: no file under the prepare.cppm decomposition grows past 2,500 lines.
+#
+# WHY
+#
+# prepare.cppm was 16,105 lines: one exported function, prepare_build, ~85%
+# of the file, ~180 top-level locals sharing a stack frame. It was split into
+# a primary interface (src/build/prepare.cppm), an implementation partition
+# (src/build/prepare/state.cppm) and twelve implementation units, each phase
+# a function taking PrepareState& instead of closing over the old locals
+# directly — see the layout comment at the top of prepare.cppm and
+# .agents/docs/2026-09-27-mcpp-2026.9.27.1-ecosystem-plan.md §4.
+#
+# A size cap with no gate is a target nobody re-checks. The decomposition's
+# whole point was to keep any one file's compile from blocking on the rest —
+# a phase file that quietly grows back to several thousand lines is the same
+# defect it fixed, arrived at one small commit at a time. This fails the
+# build the day that happens, at the commit that did it, rather than leaving
+# it for the next person who tries to read the file.
+#
+# THE RULE
+#
+# Every file directly under src/build/prepare/, plus src/build/prepare.cppm
+# itself, stays at or under 2,500 lines. There is no per-file waiver: a file
+# that needs one is a file that needs splitting the way graph.cpp/graph_load.cpp
+# and toolchain.cpp/toolchain_decision.cpp already were.
+#
+# Usage: bash .github/tools/check_file_lengths.sh [repo_dir]
+
+set -uo pipefail
+
+REPO_DIR="${1:-$(pwd)}"
+cd "$REPO_DIR" || { echo "FAIL: cannot cd to $REPO_DIR" >&2; exit 1; }
+
+LIMIT=2500
+PRIMARY="src/build/prepare.cppm"
+DIR="src/build/prepare"
+
+[ -f "$PRIMARY" ] || { echo "FAIL: $PRIMARY does not exist — this guard has gone stale" >&2; exit 1; }
+[ -d "$DIR" ] || { echo "FAIL: $DIR does not exist — this guard has gone stale" >&2; exit 1; }
+
+fail=0
+checked=0
+
+check_one() {
+    file="$1"
+    n=$(wc -l < "$file")
+    checked=$((checked + 1))
+    if [ "$n" -gt "$LIMIT" ]; then
+        echo "FAIL: $file is $n lines (limit $LIMIT)" >&2
+        fail=1
+    fi
+}
+
+check_one "$PRIMARY"
+while IFS= read -r f; do
+    check_one "$f"
+done < <(find "$DIR" -maxdepth 1 -type f \( -name '*.cppm' -o -name '*.cpp' \) | sort)
+
+if [ "$fail" = 1 ]; then
+    cat >&2 <<EOF
+
+  A file over the limit needs splitting, not a raised limit: cut it at a
+  phase boundary (see the layout comment at the top of $PRIMARY) the way
+  P4 (graph_load.cpp/graph.cpp) and P1+P2+P5 (toolchain.cpp/
+  toolchain_decision.cpp) already were. A phase whose closures escape into a
+  later phase needs its captures promoted to PrepareState members first —
+  see state.cppm's own comments for the pattern.
+EOF
+    exit 1
+fi
+
+echo "ok: $checked file(s) under $PRIMARY / $DIR/, all at or under $LIMIT lines"
+exit 0

.github/workflows/ci-linux.yml

@@ -62,6 +62,12 @@ jobs:
       - name: Check modules/ wiring
         run: bash .github/tools/check_modules_wiring.sh
 
+      # Same placement, same reason: pure text, no toolchain, under a second.
+      # Catches the prepare.cppm decomposition growing back into one huge
+      # file one commit at a time — see the script's header.
+      - name: Check src/build/prepare* file lengths
+        run: bash .github/tools/check_file_lengths.sh
+
       # Same placement, same reason: pure text, no toolchain, under a second.
       #
       # This one is a HARD gate (unlike lint-ci-assertions.sh below) because it

CHANGELOG.md

@@ -68,6 +68,12 @@
   工具链,使其断言不依赖机器的默认工具链。
 - ELF 检查以一次读取载入文件。此前逐字节读入,`mcpp test` 的链接后检查在测试程序较多时耗时
   数十分钟。
+- **`src/build/prepare.cppm` 的内部分解。** 原文件 16,105 行,其中一个函数 `prepare_build`
+  占 85%。按 §4.1 划出的十三个阶段拆分为 `PrepareState`(跨阶段状态,取代原来约 180 个共用
+  一个栈帧的局部变量)加十三个阶段函数,后者移入 `src/build/prepare/` 下十二个实现单元与一个
+  实现分区 `:state`;主接口 `prepare.cppm` 只保留导出声明。行为逐条移动,未重排、未改写。公开
+  接口、导出符号与默认参数不变,现有导入方无需改动。分解本身不改变任何行为,详见
+  `src/build/prepare.cppm` 开头的布局说明与 GCC 16.1 约束记录。
 - 规范:SPEC-001 v1.5、SPEC-004 v1.8、SPEC-005 v1.4、SPEC-007 v0.3。
 
 ## [2026.9.26.2] - 2026-09-26