Skip to content

Refine agent governance global dependency downgrade#7591

Open
QuantumMisaka wants to merge 3 commits into
deepmodeling:developfrom
QuantumMisaka:feat/agent
Open

Refine agent governance global dependency downgrade#7591
QuantumMisaka wants to merge 3 commits into
deepmodeling:developfrom
QuantumMisaka:feat/agent

Conversation

@QuantumMisaka

Copy link
Copy Markdown
Collaborator

Linked Issue

Follow-up to #7586.

Unit Tests and/or Case Tests for my changes

  • Added governance checker unit coverage for the global dependency budget behavior:
    • net increase in GlobalV / GlobalC / PARAM references blocks;
    • add/remove-neutral migration exits successfully with a warning;
    • removal-only cleanup exits successfully without a global-dependency finding;
    • staged-mode net increase also blocks.

Exact Verification Performed

  • python3 -m unittest tools/03_code_analysis/test_agent_governance_check.py -q - passed: 38 tests, OK.
  • python3 tools/03_code_analysis/agent_governance_check.py --base upstream/develop --head HEAD --format text - passed: Agent governance check: no findings.
  • git diff --check upstream/develop...HEAD - passed with no output.

What's changed?

This PR is a follow-up to #7586. PR #7586 intentionally relaxed the initial agent governance gate because the previous "any added global dependency blocks" behavior was too strict for the current legacy migration stage and was blocking normal development PRs.

During the review discussion on #7586, we identified two risks with a blanket downgrade from error to warning:

  1. It could silently allow the total amount of GlobalV, GlobalC, or PARAM dependency debt to grow.
  2. It also downgraded PR metadata completeness, which is unrelated to global-state migration and should remain a deterministic blocker.

This PR keeps #7586 as the merged baseline, but refines the policy into a PR-level global dependency budget:

  • Count GlobalV / GlobalC / PARAM references in added code lines.
  • Count the same references in removed code lines.
  • If the PR has a positive net increase, emit an error and fail the governance check.
  • If the PR adds global references but removes at least as many elsewhere, emit a warning and let CI pass.
  • If the PR only removes global references, emit no global-dependency finding.

This should avoid over-strict CI behavior for normal development and migration work while still preventing new global dependency debt from increasing unnoticed.

The PR also:

  • restores PR metadata completeness to blocker severity;
  • updates governance docs, AGENTS.md, the PR template, Copilot instructions, and CodeRabbit instructions to describe the budget rule consistently;
  • makes successful-check warnings visible through a single updatable PR comment for same-repository PRs.

Governance Checklist

  • Global dependencies: no runtime source global dependency increase; this PR changes only the governance checker and policy text. The checker itself remains excluded from global dependency source checks.
  • Default parameters: no default argument changes.
  • Headers: no C++ header dependency changes.
  • Line endings: checked with git diff --check upstream/develop...HEAD.
  • Build linkage: no source files added.
  • Documentation: governance documentation, agent instructions, PR template, and automated review instructions updated.
  • CodeRabbit: instructions updated to match the budget-based policy.

INPUT Parameter Changes

  • Parameters added/removed/changed: none.
  • docs/parameters.yaml updated: not applicable.
  • docs/advanced/input_files/input-main.md updated: not applicable.
  • If not updated, explain why no INPUT documentation update is required: this PR changes only governance tooling and governance documentation.

Core Module Impact

  • Affected core modules: none.
  • Risk summary: no ABACUS runtime behavior changes.
  • Compatibility or performance impact: none expected.

Governance Exception

  • Rule: Global dependency governance during legacy migration.
  • Reason: Modify AI agent #7586 established that a strict added-line blocker is too rigid while legacy global-state migration is ongoing.
  • Scope: governance checker severity for GlobalV / GlobalC / PARAM references, related documentation, and warning visibility.
  • User or maintenance risk: without this follow-up, a warning-only policy could allow global dependency debt to grow silently.
  • Why the normal rule cannot be followed now: existing ABACUS code still has broad historical global-state usage, so migration-neutral moves must remain possible without failing CI.
  • Follow-up cleanup plan: keep warnings review-visible during migration, require rationale for neutral moves, and block only net increases until maintainers are ready to tighten module-specific rules again.
  • Requested approver: ABACUS maintainers.

@QuantumMisaka QuantumMisaka marked this pull request as ready for review July 4, 2026 08:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant