docs: document global dependency budget

Author: QuantumMisaka

.coderabbit.yaml

@@ -15,6 +15,10 @@ reviews:
         Focus on newly introduced GlobalV/GlobalC/PARAM dependencies, default
         parameters in headers, module placement, CMakeLists.txt linkage, C++11
         compatibility, and focused tests for behavior changes.
+        During the legacy global-state migration period, treat a net increase in
+        GlobalV/GlobalC/PARAM code references as blocking, and treat
+        migration-neutral added usage as reviewer-visible warnings requiring
+        reason, scope, risk, and cleanup rationale.
     - path: "source/source_io/module_parameter/**"
       instructions: |
         Treat INPUT parameter metadata, parsing, defaults, descriptions, and

.github/instructions/abacus-governance.instructions.md

@@ -12,7 +12,9 @@ Apply these instructions when reviewing or changing ABACUS code:
   newly introduced symbols, and changed text files for line-ending checks.
 - Do not treat untouched historical debt as a default blocker. Mention it only
   when it affects the changed area, and label it as advisory.
-- Flag newly introduced `GlobalV`, `GlobalC`, or `PARAM` cross-layer control.
+- Flag PRs that increase `GlobalV`, `GlobalC`, or `PARAM` code references as
+  blocker-level governance issues. Flag migration-neutral added usage as a
+  warning that requires reason, scope, risk, and cleanup/follow-up rationale.
   Prefer explicit dependencies or narrow local interfaces.
 - Flag new default arguments in existing header interfaces. Prefer explicit
   call-site updates, overloads, or a clearer configuration object.

.github/pull_request_template.md

@@ -22,7 +22,7 @@ Fix #...
 - Example: My changes might affect the performance of the application under certain conditions, and I have tested the impact on various scenarios...
 
 ### Governance Checklist
-- Global dependencies: no new `GlobalV`, `GlobalC`, or `PARAM` cross-layer control, or exception requested below.
+- Global dependencies: no net increase in `GlobalV`, `GlobalC`, or `PARAM` code references, or exception requested below with reason, scope, risk, and cleanup plan.
 - Default parameters: no new default arguments added to existing interfaces, or exception requested below.
 - Headers: no unnecessary header dependencies or `.hpp` propagation, or rationale provided below.
 - Line endings: text files use LF; only `.bat` and `.cmd` use CRLF.

AGENTS.md

@@ -9,8 +9,10 @@ rules. Read the complete governance document before making or reviewing changes:
 ## Required Baseline
 
 - Follow the seven ABACUS coding rules summarized from the project governance:
-  1. Do not introduce new cross-layer control through `GlobalV`, `GlobalC`, or
-     `PARAM`; pass dependencies explicitly.
+  1. Do not increase cross-layer control through `GlobalV`, `GlobalC`, or
+     `PARAM`; pass dependencies explicitly where practical. Migration-neutral
+     moves must keep the PR-level global dependency budget non-increasing and
+     explain the remaining global usage.
   2. Do not hide workflow switches in mutable member variables that can be
      changed from multiple places.
   3. Keep header dependencies minimal.

docs/developers_guide/agent_governance.md

@@ -69,7 +69,7 @@ decisions.
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | Basic text format | LF line endings | phase-one mechanical | hook + CI | medium | block | full changed text file | `.bat` and `.cmd` keep CRLF |
 | Language baseline | C++11 compatibility | build/toolchain | CI | high | block | build/static tooling | Actual compiler/toolchain result wins |
-| New global dependency | Added `GlobalV`/`GlobalC`/`PARAM` as cross-layer control | phase-one mechanical + AI review | CI + AI review | high | block | added code lines | Historical untouched usage and documentation mentions are not blocked |
+| Global dependency budget | Net increase of `GlobalV`/`GlobalC`/`PARAM` references in code diff | phase-one mechanical + AI review | CI + AI review | high | block on net increase, warn on non-increasing added usage | added and removed code lines | Historical untouched usage and documentation mentions are not blocked; migration-neutral moves require reviewer rationale |
 | New default parameter | Header declaration adds a default argument | phase-one mechanical + AI review | CI + AI review | high | block | header diff | High misuse risk |
 | `.hpp` propagation | New `.hpp` or header includes `.hpp` | phase-one mechanical warning | CI + AI review | medium | warn | new files and added includes | Exception can be recorded in PR |
 | Header dependency growth | Header diff adds includes | phase-one mechanical warning + AI review | CI + AI review | medium | warn | added header includes | Necessity is semantic and not mechanically decided |
@@ -97,6 +97,13 @@ explicit governance change. For header include warnings, the rationale should
 state whether the header needs a complete type, for example because it owns a
 value member rather than a pointer or reference.
 
+For global dependencies, the mechanical checker uses a PR-level budget during
+the legacy migration period. A PR blocks only when the number of code references
+to `GlobalV`, `GlobalC`, or `PARAM` increases after accounting for deleted
+references. If a PR adds global references while deleting at least as many
+elsewhere, the checker warns instead of blocking; reviewers should confirm the
+change is a migration-neutral move or part of a cleanup path.
+
 ## Automation Responsibilities
 
 Local hooks: