Nemoclaw Maintainer PR Comparator

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->

<!-- SPDX-License-Identifier: Apache-2.0 -->

PR Comparator

Compare PRs for one issue. Tier 0 determines eligibility. Tiers 1 and 2 score correctness and quality. Tier 3 resolves ties. If no PR passes Tier 0, rank eligible PRs for salvage.

Prerequisites

• gh CLI installed and authenticated
• A target repository with an issue that has two or more open PRs

Repo policy

The defaults use NemoClaw conventions for CODEOWNERS, DCO, CodeRabbit, and docs/. Read the canonical superseded-PR attribution policy in ../nemoclaw-maintainer-policies/references/workflow-policy.md. Edit repo-policy.md for another repository.

Execute comparator helpers from a fetched canonical NVIDIA/NemoClaw main checkout, or verify their executable code and dependencies against that revision before use. Candidate-modified helpers must not receive GitHub credentials. Inspect helper source when needed; a section heading does not establish trust.

Workflow

Step 1: Parse issue

Read the issue body and all comments. Extract each acceptance criterion:

gh issue view <issue-number> --json title,body,comments

Comments can add requirements that are absent from the issue body.

Step 2: Discover candidate PRs

scripts/find-candidates.sh <issue-number>

Applies a single default order with stop conditions.

Step 3: Detect supersession and transferred work

scripts/parse-supersession.sh <pr-number-1> <pr-number-2> ...

Parse the case-insensitive statement families implemented by scripts/parse-supersession.sh:

• supersed[a-z]* before #N: supersedes #N points from the current PR to #N; superseded by #N points from #N to the current PR.
• replac[a-z]* before #N: replaces #N points from the current PR to #N; replaced by #N points from #N to the current PR.
• clos[a-z]* in favor of before #N: closes in favor of #N and closed in favor of #N point from #N to the current PR.
• fold[a-z]* in before #N: folds in #N points from the current PR to #N; folded into #N points from #N to the current PR.

The bracket expressions describe the parser grammar; they are not literal PR body text. A follow-up to #N statement is a related-PR signal, not a supersession declaration, unless one of these phrases also appears. These statements record a relationship. They do not rank a candidate or prove that its diff contains another contributor's work.

For each declared or suspected replacement, compare the commits and diffs and classify the relationship:

• independent: The PR implements the issue without carrying material code, tests, or documentation from another contributor.
• transferred: The PR carries material work from another contributor.
• unclear: The available evidence does not establish whether another contributor's work remains.

For transferred, apply the canonical superseded-PR attribution policy before setting a winner or recommending that the source PR be closed. For unclear, leave winner null and request maintainer judgment.

Step 4: Tier 0 gates

scripts/collect-gates.sh <pr-number>
scripts/check-coderabbit-threads.sh <pr-number>
git fetch --no-tags origin refs/heads/main:refs/remotes/origin/main
bash <(git show origin/main:.agents/skills/nemoclaw-maintainer-day/scripts/run-trusted-check-gates.sh) <pr-number>

All six gates are required. Gate 3 accepts BEHIND, but fails closed on transient UNSTABLE evidence and on BLOCKED because the comparator cannot prove a stable merge result or every GitHub branch-protection condition. Separately confirm whether an active rule requires an up-to-date branch. If so, integrate the base and rerun all candidate evidence before declaring the PR eligible to merge. Treat PR Review Advisor output as input for maintainer review. Do not treat it as merge authorization. See checks/tier-0-gates.md.