Add ABACUS agent governance checks (#7505)

* Normalize CRLF line endings to LF

* Normalize whitespace in legacy text files

* Update SIAB author reference

* Add agent governance checks

* Document agent governance review fixes

* fix: tighten agent governance diff scope

* remove useless plan file

* fix: preserve LiRh integration input bytes

* test: normalize LiRh integration input

* test: report integration fatal deviations

* test: disable force stress in LiRh symmetry case

* test: refresh LiRh symmetry reference

* fix: address copilot governance review

* docs: refine agent governance

* docs: strengthen governance PR follow-up

---------

Co-authored-by: QuantumMisaka <QuantumMisaka@users.noreply.github.com>

Author: QuantumMisaka

.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,17 +1,51 @@
 ### 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 listed the exact verification commands run and their results.
+- [ ] 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 #...
 
 ### Unit Tests and/or Case Tests for my changes
 - A unit test is added for each new feature or bug fix.
 
+### Exact Verification Performed
+- Commands run:
+- Result summary:
+- Checks not run, with reason:
+
 ### 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

@@ -27,4 +27,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,104 @@
+# 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.
+
+## Repository Map
+
+- Core C++ implementation lives under `source/`; source additions must be wired
+  through the relevant `CMakeLists.txt`.
+- 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`.
+- Unit tests are colocated under module `test/` directories such as
+  `source/source_md/test/`; integration and workflow tests are selected through
+  CTest labels and patterns.
+- Developer and user build/install references live in `docs/quick_start/`,
+  `docs/advanced/`, `toolchain/`, `Dockerfile.gnu`, `Dockerfile.intel`, and
+  `Dockerfile.cuda`.
+
+## Build And Test Entry Points
+
+- Prefer the repository CMake/CTest flow already used by CI. For focused local
+  checks, use commands such as `ctest --test-dir build -V -R MODULE_MD` after a
+  usable build exists.
+- For INPUT-related changes, verify both documentation and CLI behavior when an
+  executable is available: `./build/abacus -h <parameter>` and
+  `./build/abacus --check-input` from a valid case directory.
+- For executable identity, record `./build/abacus --version` or the equivalent
+  installed `abacus --version` command used during verification.
+- Reuse existing Docker and toolchain assets. Do not add a new container,
+  compiler setup, or calculation-task skill unless the PR explicitly requires
+  and justifies it.
+
+## Local Runtime Testing
+
+- Set `OMP_NUM_THREADS=1` for ABACUS runtime, integration, and MPI tests unless
+  a test explicitly requires another value.
+- Run MPI/runtime tests outside restricted sandboxes when process visibility,
+  sockets, or MPI launch behavior matters.
+- Treat OpenMPI `opal_ifinit: socket() failed errno=1` warnings from sandboxed
+  MPI-linked builds or runs as expected sandbox artifacts; rerun outside the
+  sandbox before treating them as ABACUS failures.
+- Do not relax existing tests or references merely to make a failure pass.
+  Update references only when the intended behavior changed and the PR explains
+  why.
+
+## 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
+python3 tools/03_code_analysis/agent_governance_check.py --base upstream/develop --head HEAD --format text
+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.
+
+## PR Self-Check
+
+- Confirm the PR body states exact commands run, whether they passed or failed,
+  and why any expected check could not be run.
+- Keep warning rationales concrete. For example, a header include warning can be
+  acceptable when the header owns a value member that requires the complete type.
+- Keep historical-debt notes separate from new deterministic errors introduced
+  by the PR.