prepare: file headers, phase declarations in order, an accurate layout note

- Every phase file opens with what it holds (P0 to P13) and the helper files
  with their concern, as the rest of the tree does.
- `:state` declares the phase functions in the order the driver runs them.
- prepare.cppm's layout note lists all sixteen files as they are, states
  that the interface defines nothing beyond its exported inline functions,
  and cites #721 for the GCC 16.1 constraint.
- check_file_lengths.sh no longer points at a document outside this
  repository or counts the units.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: speak-agent

.github/tools/check_file_lengths.sh

@@ -6,11 +6,12 @@
 #
 # 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 primary interface (src/build/prepare.cppm) holding declarations, an
+# implementation partition (src/build/prepare/state.cppm) and 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 mcpp-community/mcpp#721 for the GCC 16.1 constraint that
+# shapes it.
 #
 # 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 —

src/build/prepare.cppm

@@ -2,35 +2,40 @@
 // core (workspace -> toolchain -> dependency resolution -> features ->
 // modgraph -> fingerprint -> plan -> lockfile).
 //
-// LAYOUT. This file is the primary interface: exported types, and
-// prepare_build's own exported declaration (default arguments included —
-// they belong on the declaration, not the definition). Nothing else. The
-// implementation lives under src/build/prepare/:
-//   state.cppm       implementation partition `:state` — PrepareState (the
-//                     working state every phase reads and writes, by
-//                     reference, in place of prepare_build's former ~180
-//                     locals) and the phase functions' declarations.
-//   driver.cpp        prepare_build's definition: construct PrepareState,
-//                     call each phase in order, return the last one's result.
-//   manifest.cpp      P0 — manifest and workspace resolution.
-//   toolchain.cpp     P1, P2, P5 — toolchain spec, the toolchain resolver
-//                     closure (P2 defines it, P5 calls it), the toolchain
-//                     decision once the graph exists.
-//   xlings.cpp        P3 — xlings payload before the graph.
-//   graph_load.cpp    P4a — the git/path/version dependency loader
-//                     (loadVersionDep), called from graph.cpp.
-//   graph.cpp         P4b — the worklist engine and cycle detection that
-//                     call it.
-//   features.cpp      P6-P8 — feature activation, capability/ABI
-//                     accumulation, target side, host-tool provisioning.
-//   target_side.cpp   P9 — the target side, resolved once against the graph.
-//   scan.cpp          P11 — the modgraph scan, validation, fingerprint.
-//   plan.cpp          P13 — BuildContext: plan, assembly, Windows resources,
-//                     the global cache, mcpp.lock, resolution.json.
-//
-// A GCC 16.1 CONSTRAINT SHAPES ALL OF THIS. Verified locally (archived on
-// branch wip/prepare-split; see the mcpp repository's `upstream`-labelled GCC
-// issue for the minimal reproduction): inserting a new INTERFACE unit into
+// LAYOUT. This file is the primary interface: the exported types, the exported
+// inline functions, and the declarations of every other exported function,
+// default arguments included (they belong on the declaration, not the
+// definition). Nothing else is defined here. The implementation lives under
+// src/build/prepare/:
+//   state.cppm         implementation partition `:state`: PrepareState (the
+//                      working state every phase reads and writes, by
+//                      reference, in place of prepare_build's former ~180
+//                      locals), the phase functions' declarations, and the
+//                      declarations of the helpers the phases share.
+//   driver.cpp         prepare_build: construct PrepareState, run the phases
+//                      in order, return what the last one builds.
+//   manifest.cpp       P0 -- the manifest and its workspace.
+//   toolchain.cpp      P1, P2 -- the toolchain specification and target axis;
+//                      the toolchain resolver's definition.
+//   xlings.cpp         P3 -- xlings payloads before the graph.
+//   graph_load.cpp     P4a -- loading one git, path or version dependency.
+//   graph.cpp          P4b -- the worklist, the graph, the cycle check.
+//   toolchain_decision.cpp  P5 -- the toolchain, decided once the graph exists.
+//   features.cpp       P6-P8 -- features, capabilities, host tools, and the
+//                      dependencies' build programs.
+//   target_side.cpp    P9, P10 -- the target side and each dependency's link form.
+//   scan.cpp           P11, P12 -- the module scan, validation, fingerprint.
+//   plan.cpp           P13 -- the BuildContext, mcpp.lock, resolution.json.
+//   config.cpp, options.cpp, toolchain_env.cpp, fetch.cpp
+//                      the helpers the phases share: manifest merges and
+//                      feature requests; invocation options; target rows,
+//                      sysroots and build-program environments; git remotes
+//                      and xlings provisioning.
+// Every file stays at or below 2,500 lines (.github/tools/check_file_lengths.sh).
+//
+// A GCC 16.1 CONSTRAINT SHAPES ALL OF THIS. Measured locally and recorded in
+// mcpp-community/mcpp#721 (the archived attempt is branch wip/prepare-split):
+// inserting a new INTERFACE unit into
 // mcpp.build.prepare's import chain — a separately named module, or an
 // interface partition (`export module mcpp.build.prepare:x;`) — makes GCC
 // 16.1 segfault in add_imported_namespace while reading `import mcpp.cli;`

src/build/prepare/driver.cpp

@@ -1,3 +1,7 @@
+// driver.cpp -- prepare_build itself: construct the PrepareState, run the
+// phases in order, and return what the last one builds. An early error of any
+// phase ends the call with that phase's message.
+
 module mcpp.build.prepare;
 import :state;
 

src/build/prepare/features.cpp

@@ -1,3 +1,6 @@
+// features.cpp -- P6 to P8: feature activation, capability and ABI
+// requirements, host-tool provisioning, and the dependencies' build programs.
+
 module mcpp.build.prepare;
 import :state;
 

src/build/prepare/graph.cpp

@@ -1,3 +1,6 @@
+// graph.cpp -- P4b: the dependency worklist, the resolved graph and the
+// package-cycle check.
+
 module mcpp.build.prepare;
 import :state;
 

src/build/prepare/graph_load.cpp

@@ -1,3 +1,6 @@
+// graph_load.cpp -- P4a: loading one dependency (git, path or index
+// version) into the graph; the worklist in graph.cpp calls it.
+
 module mcpp.build.prepare;
 import :state;
 

src/build/prepare/manifest.cpp

@@ -1,3 +1,6 @@
+// manifest.cpp -- P0: the effective manifest and the workspace it belongs to,
+// from the one loader every command uses.
+
 module mcpp.build.prepare;
 import :state;
 

src/build/prepare/plan.cpp

@@ -1,3 +1,7 @@
+// plan.cpp -- P13: the BuildContext: the plan, prebuilt dependencies,
+// assembly units, Windows resources, the global cache, mcpp.lock and
+// resolution.json.
+
 module mcpp.build.prepare;
 import :state;
 

src/build/prepare/scan.cpp

@@ -1,3 +1,6 @@
+// scan.cpp -- P11 and P12: the module scan and its validation, the
+// standard-module gate, and the fingerprint.
+
 module mcpp.build.prepare;
 import :state;
 

src/build/prepare/state.cppm

@@ -526,17 +526,17 @@ struct PrepareState {
 // prepare_build(). Ordinary (non-static) module-linkage declarations --
 // static would give each definition internal linkage, invisible outside
 // its own file.
-std::expected<void, std::string> phase9_target_side(PrepareState& state);
-std::expected<void, std::string> phase11_scan(PrepareState& state);
-std::expected<BuildContext, std::string> phase13_finish(PrepareState& state);
 std::expected<void, std::string> phase0_manifest_and_workspace(PrepareState& state);
 std::expected<void, std::string> phase1_toolchain_spec_and_axes(PrepareState& state);
 std::expected<void, std::string> phase2_define_toolchain_resolver(PrepareState& state);
-std::expected<void, std::string> phase5_toolchain_after_graph(PrepareState& state);
 std::expected<void, std::string> phase3_xlings_before_graph(PrepareState& state);
 std::expected<void, std::string> phase4a_graph_load(PrepareState& state);
 std::expected<void, std::string> phase4b_graph_worklist(PrepareState& state);
+std::expected<void, std::string> phase5_toolchain_after_graph(PrepareState& state);
 std::expected<void, std::string> phase6_features_and_host_tools(PrepareState& state);
+std::expected<void, std::string> phase9_target_side(PrepareState& state);
+std::expected<void, std::string> phase11_scan(PrepareState& state);
+std::expected<BuildContext, std::string> phase13_finish(PrepareState& state);
 
 // ── Helpers the phases share, defined in the files named below ─────────────