Add ABACUS agent governance checks

.coderabbit.yaml

@@ -0,0 +1,47 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: en-US
+
+reviews:
+  auto_review:
+    enabled: true
+    drafts: false
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  path_instructions:
+    - path: "source/**"
+      instructions: |
+        Apply the ABACUS agent governance rules before general style feedback.
+        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.
+    - path: "source/source_io/module_parameter/**"
+      instructions: |
+        Treat INPUT parameter metadata, parsing, defaults, descriptions, and
+        availability changes as user-visible behavior. Require matching updates
+        to docs/parameters.yaml and docs/advanced/input_files/input-main.md, or
+        a clear no-update explanation in the PR.
+    - path: "docs/**"
+      instructions: |
+        Check that documentation changes match the implementation and do not
+        weaken the rule grading matrix without an explicit rationale.
+    - path: ".github/**"
+      instructions: |
+        Check workflow, PR-template, CodeRabbit, and Copilot instruction
+        changes for consistency with AGENTS.md and
+        docs/developers_guide/agent_governance.md.
+    - path: "tools/03_code_analysis/**"
+      instructions: |
+        Review governance checker changes for false positives, missing
+        diff-scoping, test coverage, and consistency with the GitHub Actions
+        summary output. Prefer deterministic checks for low-noise blockers and
+        leave semantic ownership decisions to AI and human review.
+
+knowledge_base:
+  code_guidelines:
+    enabled: true
+    filePatterns:
+      - "AGENTS.md"
+      - "docs/developers_guide/agent_governance.md"
+      - ".github/copilot-instructions.md"
+      - ".github/instructions/*.instructions.md"

.gitattributes

@@ -1,7 +1,8 @@
-# Shell scripts and the bash-parsed integration-test case lists must keep LF
-# endings so they run under bash, including MSYS2/Git-Bash on Windows where
-# core.autocrlf may rewrite them to CRLF (which breaks `#!/bin/bash` and adds
-# stray \r to parsed lines such as the case names in CASES_*.txt).
+# Text files use LF by default. Windows command scripts keep CRLF because
+# cmd.exe and installer tooling may depend on it.
+* text=auto eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
 *.sh text eol=lf
 CASES_*.txt text eol=lf
 

.github/copilot-instructions.md

@@ -0,0 +1,23 @@
+# ABACUS Copilot Instructions
+
+Before generating code or reviewing pull requests in this repository, follow
+the ABACUS development baseline in:
+
+- `AGENTS.md`
+- `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.
+
+Use the ABACUS review finding format for actionable findings:
+
+```markdown
+Rule: <rule name>
+Severity: error | warning | info
+Location: <file:line>
+Reason: <specific trigger>
+Suggested action: <concrete next step>
+Exception: allowed | not allowed | human approval required
+```

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

@@ -0,0 +1,33 @@
+---
+applyTo: "**"
+---
+
+# ABACUS Governance Review Instructions
+
+Apply these instructions when reviewing or changing ABACUS code:
+
+- Use `AGENTS.md` and `docs/developers_guide/agent_governance.md` as the
+  authoritative project baseline.
+- Keep review scope diff-oriented: new files, diff-added lines, new includes,
+  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.
+  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.
+- Review header include growth and `.hpp` propagation carefully. These are
+  usually warnings unless the PR records a narrow reason.
+- Require LF line endings for text files. `.bat` and `.cmd` files are the CRLF
+  exceptions.
+- For INPUT parameter behavior changes, require synchronized updates to
+  `docs/parameters.yaml` and `docs/advanced/input_files/input-main.md`, or a
+  clear no-update explanation in the PR.
+- Check that new source files are linked through the relevant `CMakeLists.txt`
+  unless the PR explains generated or indirect inclusion.
+- Keep default C++ changes compatible with the repository C++11 baseline.
+- Ask for focused tests or explicit test rationale for feature changes, bug
+  fixes, INPUT behavior changes, heterogeneous kernels, and core-module
+  refactors.
+- Treat CI governance findings as deterministic evidence and semantic review
+  findings as advisory until maintainers approve them.

.github/pull_request_template.md

@@ -1,8 +1,10 @@
 ### Reminder
-- [ ] Have you linked an issue with this pull request?
-- [ ] Have you added adequate unit tests and/or case tests for your pull request?
-- [ ] Have you noticed possible changes of behavior below or in the linked issue?
-- [ ] Have you explained the changes of codes in core modules of ESolver, HSolver, ElecState, Hamilt, Operator or Psi? (ignore if not applicable)
+- [ ] I have read `AGENTS.md` and `docs/developers_guide/agent_governance.md`.
+- [ ] I have linked an issue or explained why this PR does not need one.
+- [ ] I have added adequate unit tests and/or case tests, or explained why not.
+- [ ] I have described user-visible behavior changes, including INPUT parameter changes.
+- [ ] I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other `source/` changes.
+- [ ] I have requested any needed governance exception below.
 
 ### Linked Issue
 Fix #...
@@ -13,5 +15,31 @@ Fix #...
 ### What's changed?
 - Example: My changes might affect the performance of the application under certain conditions, and I have tested the impact on various scenarios...
 
-### Any changes of core modules? (ignore if not applicable)
-- Example: I have added a new virtual function in the esolver base class in order to ...
+### Governance Checklist
+- Global dependencies: no new `GlobalV`, `GlobalC`, or `PARAM` cross-layer control, or exception requested below.
+- 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.
+- Build linkage: new source files are listed in the relevant `CMakeLists.txt`, or rationale provided below.
+- Documentation: behavior/interface changes include documentation updates, or no documentation update is required because ...
+- CodeRabbit: if automatic review has not started and the repository has CodeRabbit installed, request `@coderabbitai review`.
+
+### INPUT Parameter Changes
+- Parameters added/removed/changed:
+- `docs/parameters.yaml` updated: yes/no/not applicable
+- `docs/advanced/input_files/input-main.md` updated: yes/no/not applicable
+- If not updated, explain why no INPUT documentation update is required:
+
+### Core Module Impact
+- Affected core modules:
+- Risk summary:
+- Compatibility or performance impact:
+
+### Governance Exception
+- Rule:
+- Reason:
+- Scope:
+- User or maintenance risk:
+- Why the normal rule cannot be followed now:
+- Follow-up cleanup plan:
+- Requested approver:

.github/workflows/agent_governance.yml

@@ -0,0 +1,55 @@
+name: Agent Governance
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  governance:
+    name: Governance checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run ABACUS governance checker
+        id: governance
+        run: |
+          set +e
+          base_sha="${{ github.event.pull_request.base.sha }}"
+          head_sha="${{ github.event.pull_request.head.sha }}"
+          merge_base="$(git merge-base "$base_sha" "$head_sha")"
+          merge_base_status=$?
+          if [ "$merge_base_status" -ne 0 ]; then
+            {
+              echo "## Agent Governance Check"
+              echo
+              echo "Failed to compute the pull request merge base."
+            } > agent_governance_summary.md
+            exit "$merge_base_status"
+          fi
+          python3 tools/03_code_analysis/agent_governance_check.py \
+            --base "$merge_base" \
+            --head "$head_sha" \
+            --event-path "$GITHUB_EVENT_PATH" \
+            --format markdown | tee agent_governance_summary.md
+          status=${PIPESTATUS[0]}
+          if [ ! -s agent_governance_summary.md ]; then
+            {
+              echo "## Agent Governance Check"
+              echo
+              echo "Checker failed before producing a summary."
+            } > agent_governance_summary.md
+          fi
+          exit "$status"
+
+      - name: Publish governance summary
+        if: always()
+        run: |
+          cat agent_governance_summary.md >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -26,4 +26,5 @@ abacus.json
 toolchain/install/
 toolchain/abacus_env.sh
 .trae
+.codex
 compile_commands.json

.pre-commit-config.yaml

@@ -1,5 +1,11 @@
 fail_fast: false
 repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: mixed-line-ending
+        args: [--fix=lf]
+        exclude: '(\.bat|\.cmd)$'
   - repo: https://github.com/pocc/pre-commit-hooks
     rev: v1.3.5
     hooks:
@@ -12,3 +18,10 @@ repos:
       # - id: cppcheck
       # - id: cpplint
       # - id: include-what-you-use
+  - repo: local
+    hooks:
+      - id: abacus-agent-governance
+        name: ABACUS agent governance checks
+        entry: python3 tools/03_code_analysis/agent_governance_check.py --staged
+        language: system
+        pass_filenames: false

AGENTS.md

@@ -0,0 +1,53 @@
+# ABACUS Agent Instructions
+
+This file is the entry point for AI agents, automated review tools, and human
+contributors who want the short operational version of the ABACUS development
+rules. Read the complete governance document before making or reviewing changes:
+
+- `docs/developers_guide/agent_governance.md`
+
+## 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.
+  2. Do not hide workflow switches in mutable member variables that can be
+     changed from multiple places.
+  3. Keep header dependencies minimal.
+  4. Avoid adding `.hpp` implementation headers or propagating them through
+     other headers unless there is a narrow reason.
+  5. Do not add default arguments to existing interfaces; update call sites or
+     design a clearer extension.
+  6. Add focused tests for key features, bug fixes, INPUT behavior changes,
+     heterogeneous kernels, and core-module refactors.
+  7. Keep code compatible with the repository C++11 baseline.
+- Use LF line endings for text files. Only `.bat` and `.cmd` files may use CRLF.
+- Keep source file additions deterministic: update the relevant `CMakeLists.txt`
+  or explain why the file is generated or included indirectly.
+- INPUT parameter behavior changes must update `docs/parameters.yaml` and
+  `docs/advanced/input_files/input-main.md`, or the PR must state why no update
+  is required.
+- Report the exact verification performed. Do not claim completion without
+  fresh test or check output.
+
+## Review And Exception Flow
+
+- Mechanical blockers are enforced by hook and CI only for new files, changed
+  files, or diff-added lines. Historical untouched code is not a default blocker.
+- Warnings from CI or AI review require reviewer attention but do not block by
+  themselves.
+- Semantic questions such as module ownership, member-variable workflow state,
+  test sufficiency, and exception approval require human review.
+- Exceptions must be recorded in the PR with reason, scope, risk, and a follow-up
+  cleanup plan.
+
+## Local Commands
+
+```bash
+python3 tools/03_code_analysis/agent_governance_check.py --staged
+pre-commit run abacus-agent-governance --all-files
+```
+
+The repository text files have been normalized to LF once. Day-to-day line
+ending enforcement should rely on staged/changed-file hooks and CI; rerun the
+full mixed-line-ending hook only for intentional repository-wide normalization.

docs/CONTRIBUTING.md

@@ -9,6 +9,7 @@ For more non-technical aspects, please refer to the [ABACUS Contribution Guide](
 - [Got a question?](#got-a-question)
 - [Structure of the package](#structure-of-the-package)
 - [Submitting an Issue](#submitting-an-issue)
+- [Agent governance and automated review](#agent-governance-and-automated-review)
 - [Comment style for documentation](#comment-style-for-documentation)
 - [Documenting INPUT parameters](#documenting-input-parameters)
 - [Code formatting style](#code-formatting-style)
@@ -91,6 +92,19 @@ For those who are interested in the source code, the following figure shows the
 Before you submit an issue, please search the issue tracker, and maybe your problem has been discussed and fixed. You can [submit new issues](https://github.com/deepmodeling/abacus-develop/issues/new/choose) by filling our issue forms.
 To help us reproduce and confirm a bug, please provide a test case and building environment in your issue.
 
+## Agent governance and automated review
+
+Before coding or requesting review, read the repository governance entry point
+[`AGENTS.md`](../AGENTS.md) and the full
+[ABACUS Agent Governance](./developers_guide/agent_governance.md) guide.
+These rules apply to human contributors, AI agents, GitHub CI, and CodeRabbit.
+
+Pull requests must complete the governance checklist in the PR template,
+including issue linkage, test evidence, behavior-change notes, INPUT parameter
+documentation linkage, core-module impact, and any requested exceptions. Local
+pre-commit checks cover deterministic rules such as LF line endings and staged
+diff checks; CI repeats the governance check against the PR diff and PR body.
+
 ## Comment style for documentation
 
 ABACUS uses Doxygen to generate docs directly from `.h` and `.cpp` code files.
@@ -368,13 +382,13 @@ To add a unit test:
 ## Adding an integrate test
 The integrate test is a test suite for testing the whole ABACUS package. The examples are located in the `tests/integrate` directory. Before adding a new test, please firstly read `README.md` in `tests/integrate` to understand the structure of the integrate test. To add an integrate test:
 1. Add a new directory under `tests/integrate` for the new test.
-2. Prepare the input files for the new test. 
+2. Prepare the input files for the new test.
     - The input files should be placed in the new directory. Pseudopotential files and orbital files should be placed in `tests/PP_ORB`. You should define the correct `pseudo_dir` and `orb_dir`(if need orbital files) in INPUT with the relative path to the `tests/PP_ORB` directory, and be sure the new test can be run successfully.
     - The running time of the new test should not exceed 20 seconds. You can try to reduce the time by below methods (on the premise of ensuring the effectiveness of the test):
         - Reduce the number of atoms in the unit cell (1~2 atoms).
         - Reduce the number of k-points (`1 1 1` or `2 2 2`).
         - Reduce ecutwfc (20~50 Ry).
-        - Reduce the number of steps for relax or md job (2~3 steps). 
+        - Reduce the number of steps for relax or md job (2~3 steps).
         - Reduce the basis set for LCAO calculations (DZP orbital and 6 a.u. cutoff).
     - For PW calculations, should set `pw_seed 1` in INPUT file to ensure the reproducibility of the test.
 3. Generate the reference results for the new test.
@@ -385,7 +399,7 @@ The integrate test is a test suite for testing the whole ABACUS package. The exa
          etotref -3439.007931317310
          etotperatomref -3439.0079313173
          totaltimeref 2.78
-        ``` 
+        ```
     - If you want to test the correctness of some output files, you need to do extra below steps:
         1. add the corresponding comparison method in `catch_properties.sh`. For example, to verify whether the output of the BANDS_1.dat file is correct, you need to add the following code in `catch_properties.sh`:
             ```bash