[Docs] (.github/workflows, CMakeLists.txt, MG_Backend, MG_Backend/DirectGLES, MG_Backend/DirectVulkan, MG_Backend/MGPipe, MG_Backend/Record, MG_Impl/Pipe, MG_IntegrationTest, MG_IntegrationTest/Harness, MG_IntegrationTest/Scenarios, MG_Pipe, MG_Remote, MG_Remote/Client, MG_Remote/Server, MG_Remote/Transport, MG_Remote/Wire, MG_State/GLState, MG_Test, MG_Test/Buffer, MG_Test/Purity, MG_Test/Util, MG_Test/Wire, MG_Util/Metrics, MobileGL, scripts, tools/trace_replay): replace stale line-number citations with sections and symbols

scripts/check_doc_citations.py

@@ -10,8 +10,8 @@
 
 A design document that cites the code is only as good as its line numbers, and a wrong one
 is worse than none: it sends the next reader to a function that does something else. The
-disaggregation plan's first draft cited SamplerObject.h:468-492 for a struct that lives at
-:72-96 in a 160-line file, and nothing caught it.
+disaggregation plan's first draft cited lines 468-492 of SamplerObject.h for a struct that then
+lived at lines 72-96 of a 160-line file, and nothing caught it.
 
 So every `File.h:123` and `File.cpp:123-456` in the given documents is resolved against a
 git revision - the file must exist there and must have at least that many lines. Bare file

scripts/check_include_closure.py

@@ -10,7 +10,7 @@
 
 ROADMAP.md P0.5 asks for a CI assertion on the include CLOSURE of the two headers the
 phase extracts, and for a negative control that goes red when an `MG_State` include is
-added back (ROADMAP.md:7 - every gate must be able to fail for the reason it exists).
+added back (ARCHITECTURE.md §13.2 - every gate must be able to fail for the reason it exists).
 `nm --undefined-only` cannot do that job: a header that is included but whose types are
 never named leaves no symbol behind, and "included at all" is exactly the coupling P1
 and P7 have to be able to sever. So the arbiter here is the preprocessor's own
@@ -91,7 +91,7 @@ PROBES = [
         ],
         "Allow": [],
         "TextLimits": {},
-        "Why": "MG_Pipe is below MG_State (ARCHITECTURE.md:550-561): the value types P1 hands "
+        "Why": "MG_Pipe is below MG_State (ARCHITECTURE.md §16): the value types P1 hands "
                "the backend must not drag the frontend state tree back in.",
     },
     {
@@ -634,7 +634,7 @@ def main():
     # it. `--mode text` is the default and never reaches pick_compiler, so a gate line that
     # spelled a compiler this image does not have (clang++-20, say) used to run the text half,
     # print nothing about it and exit 0 - a green nobody earned, which is exactly what
-    # ROADMAP.md:7 forbids. Asking for a compiler that is not there is an operator error
+    # ARCHITECTURE.md §13.2 forbids. Asking for a compiler that is not there is an operator error
     # whatever the mode, and it stops the run here rather than half-running it.
     resolved_compiler = pick_compiler(args.compiler) if args.compiler else None
     if args.compiler and "clang" not in modes:

scripts/p3a_untouched_regions.sh

@@ -2,8 +2,8 @@
 # G5's gate: "pool 与延迟释放原样搬" is LITERAL - ELEVEN functions in
 # MobileGL/MG_Backend/DirectGLES/Managers.cpp are byte-identical after P3a.
 #
-# WHAT G5 CLAIMS, and why a diff of the file cannot say it. ARCHITECTURE.md:316 puts the three
-# persistently mapped rings and the buffer pool in the do-not-touch list, and :515 says what
+# WHAT G5 CLAIMS, and why a diff of the file cannot say it. ARCHITECTURE.md §9.1 puts the three
+# persistently mapped rings and the buffer pool in the do-not-touch list, and §14 says what
 # protects them: `present` and eglSwapBuffers are strictly 1:1, so the rings' and the pool's retire
 # only ever happens inside Present, and a batching change would starve them. P3a rewrites the file
 # those functions live in - Ops_* becomes handle-shaped, the twin's gate is re-keyed - so the
@@ -69,8 +69,8 @@
 # "a G5-protected function" and E's risk row at :1708 makes this gate the WHOLE mitigation for
 # "the three-tier drain silently changes tier because its caller now supplies bytes differently":
 # dropping the hot path from tier 1 into tier 3 costs the Mali WAR stall back, which is
-# MEASUREMENTS.md:87's p99 163 -> 21 ms and ROADMAP.md:19's headline number, and under ID-6
-# performance is RECORDED rather than gated, so no other gate stops it. A risk row whose named
+# MEASUREMENTS.md §1.4's p99 163 -> 21 ms and the phase gate's headline number (MC 26.3 p99 on Adreno unchanged),
+# and under ID-6 performance is RECORDED rather than gated, so no other gate stops it. A risk row whose named
 # mitigation does not exist is worse than an unmitigated one. It is appended LAST rather than
 # inserted, so the first nine lines of the D.0 baseline capture keep their positions.
 #
@@ -449,7 +449,7 @@ compare_lists() {
           say "  SHIPS has moved away from the text that was reviewed. Either re-pin deliberately,"
           say "  replacing the sha AND the commit AND the decision beside it, or revert the body."
         fi
-        say "  G5 (ARCHITECTURE.md:316, :515) says the buffer pool, the deferred-release drain, the"
+        say "  G5 (ARCHITECTURE.md §9.1, §14) says the buffer pool, the deferred-release drain, the"
         say "  three rings and BOTH arms of the three-tier flush drain - FlushPendingRangesNow in"
         say "  the pull build, FlushPendingRangesFrom in the push build (BRIEF-P3A.md:420, :1708,"
         say "  ID-11, ID-15) - move VERBATIM. If this change is intended, it is not a P3a change"

scripts/p4a_untouched_regions.sh

@@ -2,8 +2,8 @@
 # G5's gate for P4a: the Espryt do-not-touch list is LITERAL - SEVENTEEN regions across THREE
 # files stay byte-identical after P4a.
 #
-# WHAT G5 CLAIMS, and why a diff of the files cannot say it. ARCHITECTURE.md:318 is the Espryt
-# do-not-touch list and :321 names the ONE item moved out of it (the sub-rect upload decision and
+# WHAT G5 CLAIMS, and why a diff of the files cannot say it. ARCHITECTURE.md §9.1 is the Espryt
+# do-not-touch list and §6 names the ONE item moved out of it (the sub-rect upload decision and
 # the stride computation, which is P4a's D-D3/D-D6 subject). P3a made the buffer half of that list
 # literal with a sha gate over eleven functions in Managers.cpp (scripts/p3a_untouched_regions.sh);
 # P4a rewrites the rest of Managers.cpp, DirectGLES.cpp and Utils.cpp by design - the twins become
@@ -85,7 +85,7 @@
 # expected shape of a #if/#else pair that re-spells one of these bodies beside an untouched copy -
 # a finding, not a limitation, because two ladders drift (ID-11, ID-15).
 #
-# A SHARED TEMPLATE OVER AN ACCESSOR INTERFACE IS REJECTED (ID-13, MEASUREMENTS.md:521): it resizes
+# A SHARED TEMPLATE OVER AN ACCESSOR INTERFACE IS REJECTED (ID-13 in notes/p3a/INTEGRATOR-DECISIONS.md): it resizes
 # pull symbols and breaks G1. If a P4a arm needs a variant of one of the seventeen it gets its own
 # `#if MOBILEGL_PIPE_PUSH` function with its own name and its own pinned sha - the
 # FlushPendingRangesFrom shape.
@@ -636,7 +636,7 @@ compare_lists() {
           say "  replacing the sha AND the commit AND the decision beside it in BOTH this script"
           say "  and its parent scripts/p3a_untouched_regions.sh, or revert the body."
         fi
-        say "  G5 (ARCHITECTURE.md:318, :321, :515) says the Espryt do-not-touch list is literal:"
+        say "  G5 (ARCHITECTURE.md §9.1, §6, §14) says the Espryt do-not-touch list is literal:"
         say "  P3a's buffer pool, deferred-release drain, three rings and BOTH arms of the three-tier"
         say "  flush drain, plus P4a's unpack-PBO staging repack and its two ring helpers, the"
         say "  attachment permutation, the D24S8 sampling-emulation core and the format-caveat"

scripts/symbol_report.py

@@ -9,7 +9,7 @@
 """Per-symbol nm/.text attribution between two libMobileGL.so builds.
 
 P0.5's acceptance gate says every `nm --defined-only -S` delta has to be explainable per
-symbol (ROADMAP.md:16). The awkward part is that de-nesting a type renames every mangled
+symbol. The awkward part is that de-nesting a type renames every mangled
 name that mentions it - `ProgramObject::LinkArtifacts` -> `LinkArtifacts` shows up inside
 every `std::vector<...>` instantiation too - so a raw nm diff of a pure move looks
 catastrophic. `--strip-scope` folds those into a "renamed-only" bucket: same normalised
@@ -30,8 +30,8 @@ GUARD RAILS - the comparison is meaningless unless both .so files were built wit
 The header of every report prints both paths and their byte sizes so a mismatched pair is
 visible in the output rather than only in the reader's assumptions.
 
-This tool is informational by default (ARCHITECTURE.md:507, job name `monolith-symbol-report`
-ARCHITECTURE.md:568): with no gate flag it prints its report and exits 0, whatever it found.
+This tool is informational by default (ARCHITECTURE.md §13.2, job name `monolith-symbol-report`
+ARCHITECTURE.md §16): with no gate flag it prints its report and exits 0, whatever it found.
 Three flags turn it into a hard gate, and P1's G1 uses the first two - the strangler's pull build
 has to stay byte-identical, and G1 spells that out as `added == removed == resized == renamed == 0`
 with a `.text` delta of zero: