docs(governance): allow module-level AGENTS.md under source/

.coderabbit.yaml

@@ -46,6 +46,7 @@ knowledge_base:
     enabled: true
     filePatterns:
       - "AGENTS.md"
+      - "**/AGENTS.md"
       - "docs/developers_guide/agent_governance.md"
       - ".github/copilot-instructions.md"
       - ".github/instructions/*.instructions.md"

.github/copilot-instructions.md

@@ -7,9 +7,12 @@ the ABACUS development baseline in:
 - `docs/developers_guide/agent_governance.md`
 
 Treat `AGENTS.md` as the short entry point and
-`docs/developers_guide/agent_governance.md` as the complete rule source. Review
-the pull request diff before general style feedback, and separate blocking
-diff-scoped issues from historical or advisory observations.
+`docs/developers_guide/agent_governance.md` as the complete rule source. A
+module directory under `source/` (e.g., `source/source_esolver/`) may carry its
+own `AGENTS.md` with module-specific constraints; read it when working in or
+reviewing that directory, and note that it refines the root baseline without
+overriding it. Review the pull request diff before general style feedback, and
+separate blocking diff-scoped issues from historical or advisory observations.
 
 Use the ABACUS review finding format for actionable findings:
 

AGENTS.md

@@ -97,6 +97,11 @@ rules. Read the complete governance document before making or reviewing changes:
 
 - Core C++ implementation lives under `source/`; source additions must be wired
   through the relevant `CMakeLists.txt`.
+- Each module directory under `source/` (e.g., `source/source_esolver/`,
+  `source/source_io/`) may carry its own `AGENTS.md` describing module-specific
+  design constraints and conventions. When working inside such a directory,
+  read and follow its `AGENTS.md` in addition to this file; the module-level
+  rules refine, but never override, this root file.
 - INPUT parsing and help metadata live under `source/source_io/`; user-facing
   INPUT reference is generated from that metadata during the documentation
   build.

docs/developers_guide/agent_governance.md

@@ -5,6 +5,15 @@ contributors, general AI agents, CodeRabbit, and GitHub CI. `AGENTS.md` is the
 short entry point; this file is the complete rule source for implementation and
 review.
 
+## Entry Points
+
+The repository-root `AGENTS.md` is the short entry point. A module directory
+under `source/` (e.g., `source/source_esolver/`, `source/source_io/`) may carry
+its own `AGENTS.md` describing module-specific design constraints and
+conventions. When working in, or reviewing, such a directory, read the module
+file together with the root file; module-level rules refine the root baseline
+and never override it.
+
 ## Source Materials
 
 The governance rules consolidate project guidance from @mohanchen's coding

source/source_esolver/AGENTS.md

@@ -0,0 +1,16 @@
+# ESolver Module Rules
+
+`source_esolver` is the cockpit dashboard of ABACUS: it presents the high-level
+algorithm workflow, while the low-level implementation details stay "under the
+hood" in their owning modules.
+
+1. `esolver` functions only orchestrate the algorithm flow within one ionic
+   step (e.g., the SCF iteration); the outer ionic loop lives in the calling
+   driver (`source_relax`, `source_md`). Any computation of a concrete
+   physical quantity must be implemented in the owning module (e.g.,
+   `source_estate`, `source_hamilt`) and called from `esolver` as a named
+   step.
+2. Do not add ad-hoc function names to `esolver`. New steps must reuse the
+   naming conventions already shared across solvers, so that all `esolver`
+   implementations read uniformly. If no suitable name exists, propose the
+   convention change first.