Stated the compiler and coverage requirements directly, and said who the pinned toolchain default serves

.github/workflows/gcc_check.yml

@@ -7,11 +7,11 @@ name: gcc_check
 # link the example builds, both the script-driven ones and those driven by
 # CMake.
 #
-# Why this exists: GCC is the project's declared default compiler (AGENTS.md,
-# "The default compiler for the project is GCC 14 on Linux") and until this
-# workflow landed, nothing in CI compiled a line of any port with it. The only
-# cross-compilation check that ran was clang_check, so the LLVM path was better
-# guarded than the GNU one, on ports whose directory is literally named gnu.
+# Why this exists: GCC 14 on Linux is the project's default compiler, it is
+# what the gnu ports exist for, and until this workflow landed, nothing in CI
+# compiled a line of any port with it. The only cross-compilation check that
+# ran was clang_check, so the LLVM path was better guarded than the GNU one,
+# on ports whose directory is literally named gnu.
 #
 # What it covers: 840 assembly sources across 40 port families, 469 of them
 # again behind feature macros, common/src for nine cores, 302 module manager C
@@ -94,8 +94,8 @@ jobs:
     env:
       # Pinned deliberately, as the runner image is: a toolchain upgrade should
       # be a reviewable commit rather than something that changes underneath the
-      # ports. 14.3.rel1 matches AGENTS.md's GCC 14 default and the version
-      # cortex_m already pins.
+      # ports. 14.3.rel1 is the GCC 14 the project builds against, and the
+      # version cortex_m already pins.
       # Releases: https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
       GCC_VERSION: 14.3.rel1
 

.github/workflows/r52_fvp.yml

@@ -75,7 +75,7 @@ jobs:
       # Pinned deliberately. Matches gcc_check.yml and ci_cortex_m.yml so all
       # three share one cache entry rather than each holding its own copy of
       # the same archive; change them together or the sharing silently stops.
-      # 14.3.rel1 is AGENTS.md's declared GCC 14 default.
+      # 14.3.rel1 is the project's GCC 14 default.
       GCC_VERSION: 14.3.rel1
 
       # Where the Armv8-R AEM FVP comes from.

.github/workflows/regression_template.yml

@@ -54,7 +54,7 @@ on:
       # rate, and not the lower of the two. Probed on the same run: the
       # ThreadX report at 100.00% lines and 77.67% branches passes a floor of
       # 99. Worth knowing, because branch coverage is around 78% in both
-      # suites while AGENTS.md asks for 100%, and a floor set from the
+      # suites while the project asks for 100%, and a floor set from the
       # headline line figure says nothing about it.
       #
       # Each suite sets its own in regression_test.yml, because they do not
@@ -157,9 +157,9 @@ jobs:
     # ! opens a YAML tag, and the expression will not parse without it.
     #
     # fail_below_min turns the summary into a gate. Until now coverage could
-    # fall from any figure to any other and no check went red, against an
-    # AGENTS.md that asks for 100% -- a stated requirement measured with a
-    # gauge that could not fail.
+    # fall from any figure to any other and no check went red, against a
+    # project target of 100% -- a stated requirement measured with a gauge
+    # that could not fail.
     #
     # One thing the floor does not defend, and it is the likeliest way for
     # coverage to break: an empty report reads as 100%. gcovr writes

cmake/cortex_m52.cmake

@@ -29,6 +29,10 @@ include(${CMAKE_CURRENT_LIST_DIR}/arm-none-eabi.cmake)
 # reject the port outright.  Override with -DARM_TOOLCHAIN_PATH=<dir containing
 # arm-none-eabi-gcc> to build with a different compiler.  The check leaves PATH
 # alone when the pinned directory is absent.
+#
+# As in cortex_r52.cmake, the default below serves local builds and nothing
+# else -- no CI job has that directory, so on a runner the EXISTS check falls
+# through and the compiler comes from PATH.  See the longer note there.
 if(NOT DEFINED ARM_TOOLCHAIN_PATH)
     set(ARM_TOOLCHAIN_PATH
         "$ENV{HOME}/toolchains/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-eabi/bin")

cmake/cortex_r52.cmake

@@ -30,10 +30,20 @@ set(SPEC_FLAGS "--specs=nosys.specs")
 
 include(${CMAKE_CURRENT_LIST_DIR}/arm-none-eabi.cmake)
 
-# Pin the reference cross toolchain (see AGENTS.md, "Compiler").  Absolute paths
-# are used deliberately so the build does not depend on PATH ordering.  Override
-# with -DARM_TOOLCHAIN_PATH=<dir containing arm-none-eabi-gcc> to build with a
-# different compiler -- for example the advisory newest-compiler lane.
+# Pin the project's reference cross toolchain, GCC 14 for Arm.  An absolute
+# path is used deliberately, so that a build on a machine which has it does not
+# depend on PATH ordering.  Override with -DARM_TOOLCHAIN_PATH=<dir containing
+# arm-none-eabi-gcc> to build with a different compiler -- for example the
+# advisory newest-compiler lane.
+#
+# The default below serves local builds and nothing else.  It fires only on a
+# machine that already has that directory, and no CI job does: the workflows
+# unpack the toolchain into the workspace and put it on PATH, and
+# scripts/check_gcc.sh passes -DARM_TOOLCHAIN_PATH at every CMake call site.
+# On a runner the EXISTS check therefore falls through and the compiler comes
+# from PATH.  Do not read the default as something CI depends on -- and do not
+# remove it as dead code either, because it is what makes a no-flag build work
+# on a developer machine.
 if(NOT DEFINED ARM_TOOLCHAIN_PATH)
     set(ARM_TOOLCHAIN_PATH
         "$ENV{HOME}/toolchains/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-eabi/bin")

scripts/check_gcc.sh

@@ -37,13 +37,12 @@
 #
 # Exit status is 0 when everything builds and 1 otherwise.
 #
-# Why this exists: GCC is the project's declared default compiler (AGENTS.md,
-# "The default compiler for the project is GCC 14 on Linux"), it is what the
-# gnu ports exist for, and it is what nearly every downstream user builds with
-# -- and until this script landed, nothing in CI compiled a line of any port
-# with it. The only cross-compilation check that ran was the LLVM one, so the
-# ATfE path was better guarded than the GNU one, on ports whose directory is
-# literally named gnu.
+# Why this exists: GCC 14 on Linux is the project's default compiler, it is
+# what the gnu ports exist for, and it is what nearly every downstream user
+# builds with -- and until this script landed, nothing in CI compiled a line
+# of any port with it. The only cross-compilation check that ran was the LLVM
+# one, so the ATfE path was better guarded than the GNU one, on ports whose
+# directory is literally named gnu.
 #
 # This is the companion to scripts/check_clang.sh and deliberately mirrors it
 # stage for stage. They are two scripts rather than one with a --toolchain flag