ci(e2e): unify maintainer approval

[jyaunches]

Summary

Use one trusted approve-e2e operation for internal and fork PR authorization. Any account with current maintain or admin permission can authorize the exact PR SHA, base SHA, and risk plan. The controller still requires passing evidence before it completes the gate.

Changes

• Require current maintain or admin repository permission for every approve-e2e request.
• Use the same authorization and dispatch path for internal and fork PRs.
• Remove the fork protected-environment job, approval outputs, approval-history parsing, and separate fork command mode.
• Preserve exact PR, head SHA, base SHA, risk plan, workflow revision, pending-check, and live-state validation.
• Update maintainer guidance, E2E operational documentation, and workflow contract tests for the unified flow.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: This changes repository-maintainer CI operation, not a user-facing NemoClaw API, CLI, configuration, UI, or supported product behavior. Maintainer and E2E operational guidance changed with the workflow.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: The nine-category NemoClaw security review passed on PR SHA 426b12b16 with no findings. The controller checks current maintain or admin permission and rejects write permission before any credential-bearing dispatch.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: .agents/skills/nemoclaw-maintainer-day/MERGE-GATE.md and test/e2e/README.md document the maintainer prerequisite, exact-revision review, credential risk, failure behavior, and passing-evidence criterion. The review found no actionable findings and confirmed that no docs/ source page is needed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npm exec -- vitest run --project integration test/pr-e2e-gate*.test.ts test/pr-e2e-required.test.ts test/maintainer-skills-policy.test.ts passed 16 files and 276 tests on 426b12b16.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable. This change does not modify the repository-wide test harness or validation configuration. npm run check:diff passed, and required CI supplies the broad Linux result.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

npm run docs passed with zero errors and two existing Fern warnings.

---

Signed-off-by: Julie Yaunches jyaunches@nvidia.com

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR E2E gate now uses a unified maintainer-only approve-e2e workflow for internal and fork credentialed E2E approval. Legacy modes, approval outputs, protected-environment validation, and the separate fork job are removed, with documentation and tests updated.

Changes

Unified PR E2E approval

Layer / File(s)	Summary
Controller command and authorization flow tools/e2e/pr-e2e-gate.mts	Adds approve-e2e, consolidates authorization handling, removes legacy approval outputs and fork approval validation, and updates recovery instructions.
Workflow dispatch and job topology .github/workflows/pr-e2e-gate.yaml	Restricts dispatch to approve-e2e, updates coordinator invocation, removes approval outputs, and deletes the separate fork approval job.
Merge-gate and E2E approval guidance .agents/skills/nemoclaw-maintainer-day/MERGE-GATE.md, test/e2e/README.md	Documents maintainer approval inputs, revision checks, fork handling, and the requirement that approval alone cannot pass the gate.
Command and workflow contract tests test/pr-e2e-gate-command.test.ts, test/pr-e2e-gate-workflow.test.ts	Updates command parsing, rejected legacy modes, workflow inputs, coordinator behavior, hardening, and reason-forwarding coverage.
Approval lifecycle and safety regression tests test/pr-e2e-gate-fork-approval.test.ts, test/pr-e2e-gate-*.test.ts, test/maintainer-skills-policy.test.ts	Updates approval, fork, cancellation, retry, required-check, recovery, and policy assertions for the unified flow.
Architecture budget adjustment ci/source-architecture-budget.json	Reduces the shell-quote.ts fan-in budget from 27 to 26.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Maintainer
  participant PRGateWorkflow
  participant PrE2EGateController
  participant CoordinationCheck
  Maintainer->>PRGateWorkflow: Dispatch approve-e2e with PR and SHA inputs
  PRGateWorkflow->>PrE2EGateController: Invoke controller in approve-e2e mode
  PrE2EGateController->>CoordinationCheck: Validate approval and revision identity
  PrE2EGateController->>PRGateWorkflow: Start authorized E2E evaluation

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7678 — Directly overlaps the unified approve-e2e controller, workflow, tests, and merge-gate documentation changes.
• NVIDIA/NemoClaw#7505 — Relates to fork E2E authorization and exact-revision checkout handling.
• NVIDIA/NemoClaw#7826 — Modifies the same protected-environment and control-plane authorization machinery.

Suggested labels: area: ci, area: e2e, area: security, refactor, v0.0.98

Suggested reviewers: prekshivyas, cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: unifying E2E authorization under maintainer approval.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/unify-pr-e2e-approval

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 426b12b in the codex/unify-pr-e2e-a... branch remains at 96%, unchanged from commit a6ba7c8 in the main branch.

---

_{Updated July 29, 2026 18:34 UTC}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

tools/e2e/pr-e2e-gate.mts (1)

3108-3127: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Fork authorization instructions omit the "gate passes only if evidence verifies" clarification.

The control-plane authorization message (Line 3156) explicitly states: "This gate passes only if the dispatched evidence references both SHAs and verifies successfully." The fork authorization message doesn't carry the equivalent clarification, only stating that no job ran and no credential was exposed. Given the path instructions explicitly require that "Approval is authorization only: it must not make the gate pass by itself," maintainers approving fork PRs should get the same clarification as maintainers approving control-plane PRs to avoid assuming approve-e2e alone completes the gate.

As per path instructions (test/e2e/README.md): "Approval is authorization only: it must not make the gate pass by itself—coordination succeeds only when the selected E2E run succeeds and every selected job shard/typed target uploads complete passing evidence."

📝 Proposed fix to align fork instructions with control-plane instructions

         [
           `Review scope: PR #${pull.number}; head repository \`${command.headRepository}\`; head SHA \`${command.headSha}\`; base SHA \`${ciIdentity.baseSha}\`; ${selectionSummary}; deterministic plan \`${plan.planHash}\`.`,
           "No selected E2E job or target ran. No repository credential was exposed to fork code.",
           `A repository maintainer must review the exact fork code and risk plan in ${gateRunLink}, then launch a first-attempt \`approve-e2e\` operation from the [${WORKFLOW_NAME}](${workflowUrl}) workflow.`,
           `Use \`pr_number=${pull.number}\`, \`expected_head_sha=${command.headSha}\`, \`expected_base_sha=${ciIdentity.baseSha}\`, and a specific \`review_reason\`. The trusted controller verifies the maintainer role and exact reviewed inputs before it dispatches this plan.`,
+          "This gate passes only if the dispatched evidence references both SHAs and verifies successfully.",
         ].join("\n\n"),

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tools/e2e/pr-e2e-gate.mts` around lines 3108 - 3127, Update the fork
authorization message assembled in the markCheckInProgress call to explicitly
state that approval only authorizes execution and does not make the gate pass.
Add the clarification that the gate passes only after the dispatched evidence
references both SHAs and verifies successfully, while preserving the existing
fork credential and review instructions.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/e2e/README.md`:
- Around line 772-774: Update the shared resolver description in the README to
replace “matching fork approval state” with unified coordination-state
terminology, such as matching pending coordination or maintainer approval state.
Do not imply a separate fork-specific authorization mechanism.

---

Outside diff comments:
In `@tools/e2e/pr-e2e-gate.mts`:
- Around line 3108-3127: Update the fork authorization message assembled in the
markCheckInProgress call to explicitly state that approval only authorizes
execution and does not make the gate pass. Add the clarification that the gate
passes only after the dispatched evidence references both SHAs and verifies
successfully, while preserving the existing fork credential and review
instructions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e647d18b-fbaa-40e0-aca9-c43cf7091f54

📥 Commits

Reviewing files that changed from the base of the PR and between 3aea38c and 697b52e.

📒 Files selected for processing (12)

• .agents/skills/nemoclaw-maintainer-day/MERGE-GATE.md
• .github/workflows/pr-e2e-gate.yaml
• test/e2e/README.md
• test/maintainer-skills-policy.test.ts
• test/pr-e2e-gate-command.test.ts
• test/pr-e2e-gate-dispatch-recovery.test.ts
• test/pr-e2e-gate-fork-approval.test.ts
• test/pr-e2e-gate-lifecycle.test.ts
• test/pr-e2e-gate-retry-history.test.ts
• test/pr-e2e-gate-workflow.test.ts
• test/pr-e2e-required.test.ts
• tools/e2e/pr-e2e-gate.mts

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 2 warnings · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 2 more warnings, 1 more suggestion.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-inference, cloud-onboard, security-posture

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.