Governance: require Autotest cases for integration tests

AGENTS.md

@@ -82,6 +82,10 @@ rules. Read the complete governance document before making or reviewing changes:
   22. Print ionic-step indices one-based (starting from 1) in user-facing
       output files, matching the `g{N}` filename suffix convention; do not
       write zero-based step counters such as `STEP: 0` into output files.
+  23. Use Autotest cases for integration tests. Standalone `add_test()` drivers
+      require a check Autotest cannot express, a PR rationale, and compliance
+      with "Integration Test Drivers" in the governance document. Autotest
+      helpers are unaffected.
 - 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.

docs/developers_guide/agent_governance.md

@@ -97,6 +97,7 @@ decisions.
 | Heterogeneous test evidence | CUDA/ROCM/kernel change has test evidence or reason | phase-one mechanical warning + AI review | CI + AI review | high | warn | changed paths and PR body | Sufficiency is human-reviewed |
 | Test existence | Source change has test evidence or reason | phase-one mechanical warning + AI review | CI + AI review | high | warn | PR body and changed paths | Sufficiency is human-reviewed |
 | Test sufficiency | Tests cover important behavior | AI review + human confirmation | AI + human review | medium | human confirmation | semantic review | Not mechanically blocked |
+| Integration test driver | Integration test uses an Autotest case, not a standalone `add_test()` script | AI review + human confirmation | AI + human review | medium | human confirmation | `tests/**/CMakeLists.txt` and new scripts under `tests/` | Standalone drivers need a stated reason Autotest cannot express the check; see Integration Test Drivers |
 | INPUT behavior linkage | Parameter metadata/default/type/parser behavior updates YAML and docs | phase-one mechanical + AI review | CI + AI review | high | warn | behavior-field diff plus docs/PR body | Comment-only parameter-file changes are not blocked |
 | Documentation sync | Behavior/interface docs updated | phase-one mechanical warning + AI review | CI + AI review | medium | warn | changed paths and PR body | Major behavior changes escalate to reviewers |
 | PR metadata completeness | Issue, tests, behavior, INPUT, core impact, exceptions | phase-one mechanical | CI or GitHub bot | medium | warn | PR template fields | Not run by local hook |
@@ -179,6 +180,24 @@ project regressions. Do not relax existing integration tests or reference files
 just to make a failure pass. Update references only when the intended behavior
 changed and the PR explains why the new reference is correct.
 
+## Integration Test Drivers
+
+Use Autotest cases with `INPUT`, `STRU`, `KPT` (when needed) and `result.ref`,
+listed in `CASES_*.txt` and run by `Autotest.sh` through the suite's CTest entry.
+Autotest helpers are unaffected.
+
+Standalone `add_test()` drivers that launch ABACUS require a check Autotest
+cannot express (e.g., nonzero exits or per-rank stderr) and a PR rationale.
+Keep Autotest-compatible checks in cases. Drivers must:
+
+- Live in `tests/integrate/validation_tools/` with descriptive names
+  (e.g., `check_<feature>.py`); reserve `test_*.py` for tool unit tests.
+- Use dedicated fixtures; never rewrite another case's `INPUT` at run time.
+- Use `find_program` plus `if()` for optional interpreters; never `REQUIRED`.
+- For MPI, forward `MPIEXEC_NUMPROC_FLAG`, `MPIEXEC_PREFLAGS` and
+  `MPIEXEC_POSTFLAGS`; set CTest `PROCESSORS` to the launched rank count.
+- Set `OMP_NUM_THREADS=1`, use temporary scratch space and a CTest `TIMEOUT`.
+
 ## CLI Verification
 
 When a usable ABACUS executable is present, INPUT and command-line changes