From b7af2921efbd46b793b081ef649f7a0599b0ec98 Mon Sep 17 00:00:00 2001 From: abacus_fixer Date: Thu, 15 Oct 2026 14:27:40 +0800 Subject: [PATCH 1/2] docs(governance): allow module-level AGENTS.md under source/ Root AGENTS.md, the governance document, and the Copilot/CodeRabbit review configuration now recognize an optional AGENTS.md inside each source/source_xxx/ module directory. Module-level files refine the root baseline and never override it. Add source/source_esolver/AGENTS.md as the first such file: it states the esolver cockpit-dashboard constraint and two checkable rules -- orchestrate the algorithm flow only, and reuse the shared cross-solver naming. .coderabbit.yaml loads nested AGENTS.md through a new "**/AGENTS.md" knowledge-base pattern. --- .coderabbit.yaml | 1 + .github/copilot-instructions.md | 9 ++++++--- AGENTS.md | 5 +++++ docs/developers_guide/agent_governance.md | 9 +++++++++ source/source_esolver/AGENTS.md | 15 +++++++++++++++ 5 files changed, 36 insertions(+), 3 deletions(-) create mode 100644 source/source_esolver/AGENTS.md diff --git a/.coderabbit.yaml b/.coderabbit.yaml index e46e6feb42b..0ebf4abce90 100644 --- a/.coderabbit.yaml +++ b/.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" diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index afe203f9a91..9bdc8a153b1 100644 --- a/.github/copilot-instructions.md +++ b/.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: diff --git a/AGENTS.md b/AGENTS.md index ea0fcd28fc7..a1eab2c7db8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,6 +79,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 docs live in `docs/parameters.yaml` and `docs/advanced/input_files/input-main.md`. diff --git a/docs/developers_guide/agent_governance.md b/docs/developers_guide/agent_governance.md index f708fcc73f5..84e6d655349 100644 --- a/docs/developers_guide/agent_governance.md +++ b/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 diff --git a/source/source_esolver/AGENTS.md b/source/source_esolver/AGENTS.md new file mode 100644 index 00000000000..21938e9ffb7 --- /dev/null +++ b/source/source_esolver/AGENTS.md @@ -0,0 +1,15 @@ +# 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 (e.g., SCF + iteration, relaxation steps). Any computation of a concrete physical + quantity must be implemented in the owning module (e.g., + `module_elecstate`, `module_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. From 8d75259ed4f834c46206bba8e82bbae28ef1d71b Mon Sep 17 00:00:00 2001 From: abacus_fixer Date: Sat, 17 Oct 2026 19:52:29 +0800 Subject: [PATCH 2/2] docs(governance): use current module names in esolver AGENTS.md example Address the review note on PR #8148: the owning-module examples now use the directory names registered in source/CMakeLists.txt (source_estate, source_hamilt) instead of the legacy module_elecstate/module_hamilt names, so the guidance is directly searchable. Co-Authored-By: Claude Sonnet 4.6 --- source/source_esolver/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/source_esolver/AGENTS.md b/source/source_esolver/AGENTS.md index 21938e9ffb7..12d450b34a0 100644 --- a/source/source_esolver/AGENTS.md +++ b/source/source_esolver/AGENTS.md @@ -7,7 +7,7 @@ hood" in their owning modules. 1. `esolver` functions only orchestrate the algorithm flow (e.g., SCF iteration, relaxation steps). Any computation of a concrete physical quantity must be implemented in the owning module (e.g., - `module_elecstate`, `module_hamilt`) and called from `esolver` as a named + `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`