Review PR

Review PR

Purpose and Modes

Judge the latest reviewed scope from root cause, behavior, contracts, tests, and public or user-authorized repository evidence. Select one output mode:

• Formal Review Mode: return one formal result for a public PR review, authorized local-candidate review, code-readiness judgment, mergeability decision, or CI review.
• PR Discussion Reply Mode: return a copy-ready committer reply only when the user explicitly requests a review-thread response, author or maintainer objection reply, or challenged-finding reply. Do not add a formal verdict unless requested.

Use Formal Review Mode for every complete code review result or recommendation, including pre-handoff review of a local candidate. Identify a local candidate and its local-only delta in ### Coverage; do not create a separate local-preflight result format or describe local-only work as the public PR state.

Review Focus

Review focus is independent from output mode.

Explicit user scope wins. Formal Review of a local candidate uses Code Correctness Review unless the user explicitly requests CI.

In Code Correctness Review, unreviewed CI is not an evidence gap. Runtime facts may still be required from code, official specifications, public reproductions, or local verification. If such a decisive fact is unavailable, identify that fact—not CI—as the incomplete reason.

Canonical Assessment

Resolve one review basis before discovery: the effective candidate, applicable requirements, accepted behavior and project commitments, selected review focus, and admissible evidence. Run the Review Workflow against that basis and produce one mode-independent assessment: confirmed findings consolidated by fix boundary, needs-discussion conditions, incomplete-evidence gaps, and Completion Gate state.

Output mode must not affect candidate discovery, proof, classification, coverage, or convergence. Never use a previous Formal Review result as evidence or as a conclusion to match. Treat previous public findings only as hypotheses whose cited facts must be reverified.

Two reviews with the same effective candidate, requirements, focus, and evidence must produce the same canonical assessment. Public-PR and local-candidate reviews may resolve different candidates, but they must apply the same code-correctness judgment and Formal Review result mapping. A changed focus, requirement, or external fact changes the review basis and may legitimately change the assessment. Mergeability or CI evidence may add external-state findings or gaps, but it must not change code-correctness findings derived from an otherwise unchanged basis.

Core Contracts

1. Review only. Do not modify PR code, post comments, submit reviews, resolve threads, rerun workflows, or change remote state without explicit authority.
2. Public-PR Formal Review scope is the latest target PR head and the complete GitHub changed-file list; use local triple-dot semantics when reproducing it. Local-candidate Formal Review scope follows Local Candidate Scope below. A discussion reply starts from the latest head, thread context, and affected behavior; expand to complete scope only when the claim depends on it.
3. Public community conclusions use only public evidence and sanitized verification summaries. Private-repository conclusions may use authorized repository evidence but must remain within the user-authorized task and target repository.
4. Reconstruct trigger -> failing path -> observed result -> expected behavior before judging the patch. A fallback, default, null check, try-catch, or swallowed error is not a root-cause repair unless it fixes the owning contract.
5. Treat every concern as a candidate until it passes the Finding Proof Gate.
6. Do not turn uncertainty, inaccessible evidence, tool failure, skipped verification, or uninspected counter-evidence into a blocker.
7. In Formal Review, do not select a verdict, stop at the first blocker, or publish findings before the Completion Gate. Consolidate findings by independent fix boundary and return the complete current-head set once. Only an explicit request for status, narrow review, or early high-risk blockers authorizes a partial result.
8. Follow AGENTS.md for repository authority, evidence, scope, safety, and sensitive data, and follow the applicable canonical references below for implementation, testing, contract, non-regression, and verification criteria.

Repository Code Policy References

Standalone review is read-only and does not activate code-implementation or acquire write authority. Before judging the effective candidate, read implementation rules, non-regression rules, and verification rules through EOF. Also read testing rules when tests or coverage matter, and artifact removal and contract impact rules when their trigger matches. Reuse an exact reference already read by the outer implementation workflow. Before judging reviewed code or Maven POM changes, read coding standards through EOF and use its Implementation Guidance Mode.

Problem and Project Commitment Gate

Complete this gate before implementation-detail discovery; it establishes the review basis but does not waive the Finding Proof, Mandatory Style Verification, Completion, or convergence gates.

1. Reconstruct the problem and expected behavior from the PR, linked issue when present, official documentation, maintained contracts, current code, and tests.
2. Classify the requested outcome as preserving an accepted contract or adding a project commitment such as new semantics, configuration, API or SPI, compatibility, topology, database, dialect, or cross-module support.
3. For Apache ShardingSphere, establish that ShardingSphere owns the behavior and that official project positioning, maintained contracts, or an explicit public maintainer decision accepts every new commitment; for an authorized downstream repository, apply equivalent target-project evidence available within the user-authorized repository boundary.
4. Identify the narrowest accepted user-visible behavior and compare it with the patch's public contract, shared abstractions, compatibility surface, documentation, and tests.
5. Check whether the change creates precedent or consistency pressure beyond the accepted behavior; an exact existing behavior or special case does not authorize broader generalization.

An open or labeled issue, popularity, contributor effort, available code, passing tests, or a small diff do not establish project acceptance. When evidence disproves the problem, expected behavior, applicable project ownership, or an asserted accepted commitment, or when a new commitment still requires a maintainer decision, record a Needs Discussion condition. When the behavior is accepted but the patch adds unsupported generalization, public surface, parallel models, or abstractions without a real stable boundary, treat the excess as a finding candidate under the implementation rules; patch size or novelty alone is not evidence of overdesign. When a decisive acceptance or ownership fact is unavailable after every admissible route, apply the Review Incomplete Proof Gate instead of converting uncertainty into Needs Discussion.

Scope and Evidence

Read evidence-access.md and complete its GitHub Access Preflight before any GitHub request. It owns public-read selection, current-head identity, authoritative file scope, local-style evidence, failure attribution, CI, external behavior, and evidence hygiene. Apply its Local Style Verification Evidence to every public-PR or PR-backed local-candidate Formal Review.

For formal reviews, establish the latest head and base, authoritative files and requirements, relevant public discussion, and any authorized local delta. For discussion replies, establish the complete current thread and affected paths; obtain the full file list when scope or readiness is disputed. Earlier findings do not prove current-head readiness.

Treat AI-assistance disclosure only as an explicit mergeability or policy-compliance concern. Apply AI_POLICY.md only when public evidence establishes material AI assistance; never infer it from code, prose, metadata, or a classifier.

Mandatory Style Verification Gate

Apply this gate to every Formal Review of a public PR and every PR-backed local candidate. This gate is local candidate verification rather than a GitHub CI query, so every Review Focus must complete it even when Code Correctness Review does not read GitHub Actions, checks, workflow runs, or Actions logs.

1. Derive the applicable PR-impact files and their owning Maven modules from the authoritative changed-file list for the effective candidate.
2. Treat production and test Java files as applicable to both Checkstyle and Spotless unless repository configuration proves that a check does not govern a file.
3. Run both checks against the latest public PR head or an accurate PR-backed local candidate that contains the latest public head and only its authorized local delta.
4. Invalidate all prior Checkstyle and Spotless evidence immediately when the public PR head or authorized local delta changes.
5. Use a whole-repository check, complete affected-module checks, or an exact-file check only when the command output and file inventory prove that the selected scope covers every applicable PR-impact file.
6. Expand verification to the complete rule impact, normally the whole repository, when the PR changes global Checkstyle or Spotless configuration, a parent POM, or another cross-module style rule.
7. Treat an exit code of zero as passing evidence only when the output also proves that every applicable PR-impact file was selected; a successful command that matched no intended file is not evidence.
8. Do not use passing CI, required checks, commit statuses, a PR comment summary, or evidence from an older candidate to satisfy or waive this gate.
9. Do not run spotless:apply or another file-modifying formatter during review.

Map the gate result before applying the remaining Formal Decision Contract.

• If Checkstyle or Spotless fails on an applicable PR-impact file, return Not Mergeable with Feedback Mode: Change Request.
• A style-check failure result must include Feedback Mode: Change Request and the blocking-issue count in ### Result, then identify each failed check and affected PR-impact file in ### Blocking Issues.
• A style-check failure result must also include ### Coverage with the effective candidate SHA, authoritative files accounted for, failed command, exit code, and affected PR-impact file.
• If environment, dependency, candidate-materialization, tool, or coverage-proof failure leaves any applicable PR-impact file unverified, return Review Incomplete.
• If a module-scoped command fails only on unchanged files, narrow the check reliably or compare the base and effective candidate before attribution; do not classify the PR from that module failure alone.
• If a check has no applicable PR-impact file, record Not Applicable and the repository-configuration basis in ### Coverage.
• Only successful current-candidate evidence for both checks, or an explicit not-applicable determination for either check, permits the remaining Formal Decision Contract to select Mergeable.

Finding Proof Gate

A candidate may become a blocking issue only when all five conditions hold:

1. Evidence: current code, diff, contract, test, log, CI, public reproduction, official documentation, or generated artifact directly supports the claim.
2. Full path: trace the relevant production or test entry path end to end; inspect setup, wrappers, earlier calls, generators, and consuming runtime.
3. Counter-evidence: check the strongest evidence that could disprove the finding, especially author or maintainer replies and version-specific facts.
4. Necessity: the requested change is required for safety, correctness, or an applicable repository design or contract rule in the selected focus, not merely cleaner or preferable.
5. Scope: this PR causes the problem, exposes it through behavior it owns, or must address it to satisfy the linked issue.

Classify failed candidates as an incomplete-evidence gap, non-blocking observation, clarification question, pre-existing issue, or no issue. Do not publish non-blocking observations unless they materially help the user.

Review Incomplete Proof Gate

Review Incomplete is a terminal evidence classification, not a fallback for unfinished analysis. Classify a gap as incomplete only when a specific outcome-sensitive decisive fact remains unavailable after every admissible evidence route has been attempted; if relevant local or public evidence exists or another allowed route remains, continue the review and classify the candidate. After authoritative scope is established, record each incomplete gap in the ledger with the missing fact, unavailable-evidence proof, affected full path, strongest alternatives checked, outcome impact, scope proof, and affected files, then run scripts/review_ledger.py validate-incomplete --ledger <ledger> before selecting the result. If authoritative scope cannot be established, state the exact unavailable scope fact and attempted routes in ### Required Evidence; do not fabricate ledger scope.

Behavior Clusters and Risk Triage

Map every substantive file to the smallest meaningful behavior cluster and identify each cluster's root cause, owner, entry paths, consumers, contracts, project-commitment delta, changed decisions, and validation points. Account explicitly for churn-only files.

Triage functional boundaries, ownership and shared contracts, compatibility and rollback, test validity, concurrency and performance, security and operations, dependencies, packaging, and generated artifacts. Read only the triggered sections of high-risk-review.md. Also read sql-parser-review.md for SQL grammar, visitors, parser tests, syntax documentation, dialect behavior, or parser baselines.