Add ABACUS agent governance checks

[QuantumMisaka]

Linked Issue

#7488

Unit Tests and/or Case Tests for my changes

• python3 tools/03_code_analysis/agent_governance_check.py --staged --format text — no findings.
• python3 tools/03_code_analysis/agent_governance_check.py --base upstream/develop --head HEAD --format text — no errors; one warning remains for source/source_esolver/esolver_fp.h header dependency growth.
• pytest tools/03_code_analysis/test_agent_governance_check.py -q — 36 passed.
• python3 -c "import yaml; d=yaml.safe_load(open('docs/parameters.yaml')); print(len(d['parameters']))" — printed 499.
• rg -n "Local Runtime Testing|OMP_NUM_THREADS|opal_ifinit|page_allocator.o|unitcell_lite.o|md_csvr_tau" AGENTS.md docs/developers_guide/agent_governance.md source/Makefile.Objects docs/parameters.yaml docs/advanced/input_files/input-main.md — confirmed the follow-up guidance, Makefile objects, and INPUT docs are present.
• git diff --check — no whitespace findings.
• Not run locally: ABACUS executable, Makefile link, or ctest verification; this checkout has no top-level build/ directory and no shallow abacus executable.

What's changed?

• Adds AGENTS.md and the full ABACUS agent governance guide for human contributors, AI agents, CodeRabbit, and CI.
• Adds a deterministic governance checker plus regression tests for LF line endings, diff-scoped semantic rules, PR metadata completeness, INPUT documentation linkage, CMake linkage, and review-only warnings.
• Adds a GitHub Actions workflow to run governance checks on pull requests and publish Markdown summaries.
• Adds CodeRabbit and Copilot guidance that points review tools at the new governance rules.
• Normalizes repository text line endings to LF and records the follow-up diff-scope fix so line-ending-only changes do not create semantic false positives.
• Adds local runtime/MPI testing guidance for agent environments, including OMP_NUM_THREADS=1, sandboxed MPI caveats, and reference-update discipline.
• Keeps the legacy Makefile neighbor-search object list aligned with the neighbor-list sources already used by CMake.

Governance Checklist

• Diff-scoped blocking rules are limited to deterministic checks on changed files or added lines.
• Warning-only and human-confirmation rules remain advisory and are not converted into hard blockers.
• New source file additions are covered by CMake linkage checks where mechanically detectable.
• PR metadata completeness is checked only when PR metadata is available.
• GitHub Actions compares PR merge-base to head, matching the PR diff scope.
• Header dependency warning rationale: source/source_esolver/esolver_fp.h directly includes parallel_grid.h because ESolver_FP owns Parallel_Grid Pgrid as a value member and therefore needs the complete type.

INPUT Parameter Changes

• Added and documented md_csvr_tau for the CSVR thermostat.
• docs/parameters.yaml updated: yes.
• docs/advanced/input_files/input-main.md updated: yes.

Core Module Impact

No runtime core-module behavior changes are intended by the governance layer. The source/runtime changes outside governance are limited to line-ending normalization, SIAB author-reference documentation cleanup, CSVR metadata/test follow-up, and Makefile object-list parity for already-present neighbor-list sources.

Governance Exception

No governance exceptions requested.

Notes

• A separate review surfaced existing ASE/Wannier interface issues outside this branch's diff scope. Those are not part of this governance PR and should be handled in a separate focused fix if maintainers want to address them.
• Review feedback about nspin=4 meta-GGA, LCAO hybrid EXX guards, Makov-Payne/PARAM plumbing, and assume_isolated documentation touches files that are not part of this PR's current diff. Those runtime/core behavior issues should be handled in separate focused PRs rather than folded into this governance PR.

[QuantumMisaka]

CI failure follow-up for 01_PW/074_PW_SY_LiRH:

The current Integration Test and Unit Test failure is not an energy-reference drift. The failing detail is:

074_PW_SY_LiRH: key totalforceref not found in output

Root cause: this case's INPUT had cal_force 1 and cal_stress 1, so catch_properties.sh generated force/stress keys in result.out; however result.ref only contains etotref, etotperatomref, and totaltimeref. Since this case README says it tests symmetry analysis, the fix disables force/stress output for this case instead of recalculating and extending the reference file.

This also exposed a broader issue from the fix process: non-normalized line endings / input bytes can affect whether ABACUS input parameters are parsed as intended. The LiRh input normalization made the latent mismatch visible. We should treat line-ending normalization for INPUT-style test files as semantically relevant and keep changed test inputs LF-normalized.

[Growl1234]

I think, it is worth checking and replacing all CRLFs in testing input files.

[QuantumMisaka]

Update for 01_PW/074_PW_SY_LiRH:

This case is intended to test symmetry analysis, so symmetry 1 should remain active. The original input also contained
cal_force 1 and cal_stress 1; after line-ending/input-byte normalization those parameters are parsed as intended, so the test reference must cover the corresponding outputs.

I refreshed the reference using the actual integration-test flow (tests/integrate/Autotest.sh): generate reference first, then rerun the same case against that reference. The updated result.ref now includes totalforceref, totalstressref, pointgroupref, spacegroupref, and nksibzref.

SAI verification:

• Tried abacus/v3.9.0.17-sm70-auto on the GPU path first; the preinstalled GPU binary segfaulted inside cublasZgemm_v2.
• Then used the same ABACUS 3.9.0.17 installation with a temporary device cpu input for the recalculation, 4 MPI ranks, and the same Autotest.sh harness.
• The generated reference passed the harness check for all 7 captured fields.

The final committed test does not add device cpu; it only restores the original force/stress intent and refreshes the expected reference values.

[Copilot]

Pull request overview

This PR introduces an “agent governance” layer for ABACUS development and review by adding a documented rule set, a deterministic diff-scoped checker (hook + CI), and corresponding configuration for GitHub Actions, pre-commit, and CodeRabbit. It also normalizes many repository text files to LF to support low-noise diff-based checks.

Changes:

• Adds the ABACUS agent governance documentation entry points (AGENTS.md and developer guide page) and wires them into existing contributor docs and PR template.
• Adds an automated governance checker with CI workflow + pre-commit hook integration.
• Normalizes LF line endings and performs minor formatting-only touch-ups across assorted source/tests/examples.

Reviewed changes

Copilot reviewed 21 out of 78 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tools/02_postprocessing/rt-tddft-tools/examples/Absorpation-N2/ABACUS-INPUT	LF/format normalization in example input.
tools/01_NAO_generation/SIAB/src_parallel/parallel_global.h	Comment/header formatting updates.
tools/01_NAO_generation/SIAB/src_parallel/parallel_global.cpp	Formatting-only touch-up.
tools/01_NAO_generation/pytorch/unittest_inverse.py	Formatting-only touch-up.
tools/01_NAO_generation/pytorch/torch_complex.py	Formatting-only touch-up.
tools/01_NAO_generation/pytorch/opt_orbital.py_real	Formatting-only touch-up.
tools/01_NAO_generation/pytorch/inverse.py	Formatting-only touch-up.
tools/01_NAO_generation/pytorch_gradient_source/unittest_inverse.py	Formatting-only touch-up.
tools/01_NAO_generation/pytorch_gradient_source/torch_complex.py	Formatting-only touch-up.
tools/01_NAO_generation/pytorch_gradient_source/opt_orbital.py_real	Formatting-only touch-up.
tools/01_NAO_generation/pytorch_gradient_source/inverse.py	Formatting-only touch-up.
tools/01_NAO_generation/pytorch_dpsi/torch_complex_bak.py	Formatting-only touch-up.
tools/01_NAO_generation/pytorch_dpsi/IO/read_istate.py	Formatting-only touch-up.
tools/01_NAO_generation/pytorch_dpsi/IO/change_info.py	Formatting-only touch-up.
tools/01_NAO_generation/pytorch_dpsi/IO/cal_weight.py	Formatting-only touch-up.
tests/integrate/Autotest.sh	Improves fatal error reporting output (adds fatal deviation details).
tests/15_rtTDDFT_GPU/18_NO_hyb_TDDFT_GPU/INPUT	LF/format normalization for test INPUT.
tests/15_rtTDDFT_GPU/17_NO_vel_TDDFT_GPU/INPUT	LF/format normalization for test INPUT.
tests/08_EXX/14_NO_TDDFT_PBE0/INPUT	LF/format normalization for test INPUT.
tests/05_rtTDDFT/18_NO_hyb_TDDFT/INPUT	LF/format normalization for test INPUT.
tests/05_rtTDDFT/17_NO_vel_TDDFT/INPUT	LF/format normalization for test INPUT.
tests/01_PW/074_PW_SY_LiRH/result.ref	Updates/extends integration reference keys (force/stress/symmetry) for this case.
tests/01_PW/074_PW_SY_LiRH/INPUT	LF/format normalization for test INPUT.
source/source_pw/module_stodft/sto_stress_pw.h	Formatting-only touch-up.
source/source_lcao/module_ri/test_code/Inverse_Matrix-test.h	Formatting-only touch-up.
source/source_lcao/module_ri/RI_Util.h	Formatting-only touch-up.
source/source_lcao/module_ri/RI_2D_Comm.h	Formatting-only touch-up.
source/source_lcao/module_ri/Mix_DMk_2D.h	Formatting-only touch-up.
source/source_lcao/module_ri/Mix_DMk_2D.cpp	Formatting-only touch-up.
source/source_lcao/module_ri/Matrix_Orbs22.h	Formatting-only touch-up.
source/source_lcao/module_ri/Matrix_Orbs21.h	Formatting-only touch-up.
source/source_lcao/module_ri/Matrix_Orbs11.hpp	Formatting-only touch-up.
source/source_lcao/module_ri/Matrix_Orbs11.h	Formatting-only touch-up.
source/source_lcao/module_ri/LRI_CV.h	Formatting-only touch-up.
source/source_lcao/module_ri/Inverse_Matrix.h	Formatting-only touch-up.
source/source_lcao/module_ri/Exx_LRI.h	Formatting-only touch-up.
source/source_io/module_chgpot/write_libxc_r.h	Formatting-only touch-up.
source/source_hamilt/test/dnrm2_test.cpp	Formatting-only touch-up.
source/source_hamilt/test/CMakeLists.txt	Formatting-only touch-up.
source/source_hamilt/module_xc/test/test_xc5.cpp	Whitespace cleanup.
source/source_hamilt/module_xc/test/test_xc3.cpp	Whitespace cleanup.
source/source_estate/module_pot/pot_xc_fdm.cpp	Formatting-only touch-up.
source/source_estate/module_pot/pot_cosikr.h	Formatting-only touch-up.
source/source_esolver/esolver_lj.cpp	Whitespace cleanup.
source/source_cell/module_neighlist/unitcell_lite.cpp	Whitespace cleanup.
source/source_cell/module_neighlist/page_allocator.cpp	Whitespace cleanup.
source/source_basis/module_ao/element_basis_index-ORB.h	Formatting-only touch-up.
source/source_basis/module_ao/element_basis_index-ORB.cpp	Formatting-only touch-up.
source/source_base/test/tool_title_test.cpp	Whitespace cleanup.
source/source_base/test/tool_threading_test.cpp	Formatting-only touch-up.
examples/22_rt-tddft/02_H2_velocity_gauge/STRU	LF/format normalization for example structure.
examples/22_rt-tddft/01_H2_length_gauge/STRU	LF/format normalization for example structure.
docs/developers_guide/index.rst	Adds governance doc to developer guide TOC.
docs/developers_guide/agent_governance.md	Adds the full governance specification and rule grading matrix.
docs/CONTRIBUTING.md	Links contributor workflow to governance docs and checklist.
docs/community/contribution_guide.md	Adds governance guidance for community contributors.
docs/advanced/interface/pyatb.md	Formatting-only touch-up.
AGENTS.md	Adds the short governance entry point and required baseline for contributors/agents.
tools/03_code_analysis/agent_governance_check.py	Adds diff-scoped governance checker (line endings, globals, defaults, CMake linkage, PR metadata, etc.).
tools/03_code_analysis/test_agent_governance_check.py	Adds regression tests for the governance checker.
.pre-commit-config.yaml	Adds mixed-line-ending fixer and local governance hook.
.gitignore	Ignores .codex.
.github/workflows/agent_governance.yml	Runs governance checker on PRs and publishes a Markdown summary.
.github/pull_request_template.md	Extends PR template with governance checklist and required sections.
.gitattributes	Enforces LF by default with CRLF exceptions for .bat/.cmd.
.coderabbit.yaml	Configures CodeRabbit review guidance to follow the new governance docs.

Comments suppressed due to low confidence (1)

tools/01_NAO_generation/SIAB/src_parallel/parallel_global.h:28

• The include guard ends with #endif // GMPI, which doesn’t match the actual guard name (PARALLEL_GLOBAL_H). This makes it harder to audit nested guards and can confuse automated tooling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zhubonan]

Thanks for pushing this forward. I think this PR is on the right track: the AGENTS.md entry point plus the fuller governance document covers the core guidance from #7488, and the diff-scoped checker/CI setup is a useful next layer.

I checked a few existing local AGENTS.md files from ABACUS worktrees, and one small operational detail seems worth adding to the new upstream AGENTS.md: ABACUS runtime/MPI tests often need special handling under sandboxed agent environments.

Suggested addition:

## 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.
- OpenMPI `opal_ifinit: socket() failed errno=1` warnings from sandboxed MPI-linked builds/runs are expected sandbox artifacts; rerun the command outside the sandbox before treating it as an ABACUS failure.
- 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.

This is not a blocker from my side, but I think it would make the agent instructions more robust for the actual workflows where agents run ABACUS tests locally.