Add ABACUS agent governance checks

[QuantumMisaka]

Linked Issue

No linked issue; this PR bootstraps ABACUS automated development and review governance.

Unit Tests and/or Case Tests for my changes

• python3 -m unittest tools/03_code_analysis/test_agent_governance_check.py — ran 34 tests, OK.
• python3 tools/03_code_analysis/agent_governance_check.py --staged — no findings.
• PRE_COMMIT_HOME=/private/tmp/abacus-pre-commit-cache pre-commit run abacus-agent-governance --all-files — Passed.
• git diff --cached --check before commit — no whitespace errors.

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 configuration that points review guidance 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.

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.

INPUT Parameter Changes

No INPUT parameter behavior changes. No update to docs/parameters.yaml or docs/advanced/input_files/input-main.md is required.

Core Module Impact

No runtime core-module behavior changes are intended. The source/runtime changes outside governance are line-ending normalization and SIAB author-reference documentation cleanup.

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.

[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.