ci(station): require hardware evidence for host preparation

[senthilr-nv]

Summary

Requires human-reviewed DGX Station test evidence before maintainers approve or merge a PR that changes scripts/prepare-dgx-station-host.sh. The requirement uses the repository's existing review and administrative-bypass controls; it does not add a custom workflow or claim authenticated hardware provenance.

Related Issue

Fixes #7191

Product-scope decision: #7191 (comment)

Changes

• add PR-template fields for the tested commit, Station profile or scenario, result, and supporting evidence
• give contributor and reviewer agents the same approval requirement and trust semantics
• keep enforcement in existing maintainer review controls, with exceptional bypasses handled by existing repository governance

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: the final diff is contributor-governance prose only and adds no executable behavior
• Docs updated for user-facing behavior changes
• Docs not applicable — contributor review governance does not change supported product behavior or user workflows
• 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:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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 — tests are not applicable; npx --no-install markdownlint-cli2 .github/PULL_REQUEST_TEMPLATE.md AGENTS.md passed
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/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)

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a trusted pull_request_target gate for changes to scripts/prepare-dgx-station-host.sh. The gate validates current hardware evidence or an authorized deferral, updates contributor guidance, and adds tests for validation and workflow security contracts.

Changes

Station hardware evidence enforcement

Layer / File(s)	Summary
Validation contract and selection parsing .github/PULL_REQUEST_TEMPLATE.md, AGENTS.md, tools/station-hardware-evidence/gate.mts	Defines hardware and deferral markers, parses PR selections, and documents required evidence fields.
Evidence and deferral validation tools/station-hardware-evidence/gate.mts	Validates linked comments, script hashes, tested commits, permissions, follow-up issues, and exclusive outcomes.
Trusted workflow and GitHub API runtime .github/workflows/station-hardware-evidence.yaml, tools/station-hardware-evidence/gate.mts	Runs the gate from a trusted revision, loads GitHub data, and publishes results.
Gate and workflow contract tests test/station-hardware-evidence-gate.test.ts, ci/source-shape-test-budget.json	Covers applicability, evidence, deferrals, stale hashes, removed scripts, workflow security, and template alignment.

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

Sequence Diagram(s)

sequenceDiagram
  participant PullRequest as Pull request
  participant Workflow as Station / Hardware Evidence
  participant Gate as evaluateStationHardwareGate
  participant GitHub as GitHub API
  PullRequest->>Workflow: Trigger on pull request or comment event
  Workflow->>Gate: Pass token and PR number
  Gate->>GitHub: Fetch PR, files, comments, issues, and script blobs
  Gate-->>Workflow: Return validation summary and status

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7126: Changes preparation-script content covered by the evidence hash contract.
• NVIDIA/NemoClaw#7132: Modifies preparation-script behavior covered by the evidence and deferral requirements.
• NVIDIA/NemoClaw#7155: Changes preparation-script logic whose content is validated by the gate.

Suggested labels: feature

Suggested reviewers: apurvvkumaria, ericksoa

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR implements the required path-sensitive Station gate, evidence/deferral handling, trusted workflow boundaries, and focused tests described in #7191.
Out of Scope Changes check	✅ Passed	The workflow, gate, template, tests, and budget updates all support the Station evidence requirement; no unrelated changes are apparent.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: requiring hardware evidence for Station host-preparation changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

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 · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections match; severity counts match.

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: None

Workflow run details

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

[senthilr-nv]

Addressed PRA-1 and PRA-2 in signed commit 533f34d6b:

• the changed-file loader now records completeness and fails closed when GitHub's 3,000-file limit prevents proving the Station preparation script is unchanged
• focused negative coverage now rejects duplicate fields and malformed commit, script-hash, and profile values

Verification: npx vitest run --project integration test/station-hardware-evidence-gate.test.ts (17 passed) and npm run check:diff passed.

[senthilr-nv]

Addressed the current PR Review Advisor warning in signed commit 45775c776: added focused coverage proving that a maintainer deferral whose prepare_script_sha256 targets older bytes is rejected as stale. Verification: npx vitest run --project integration test/station-hardware-evidence-gate.test.ts (18 passed); normal commit and pre-push hooks passed.

[coderabbitai]

🧹 Nitpick comments (1)

tools/station-hardware-evidence/gate.mts (1)

304-315: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Bound GitHub API requests with a timeout. The job only has a 5-minute timeout, so a stalled fetch can still consume the entire run; signal: AbortSignal.timeout(30_000) would fail fast with a clearer error.

🤖 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/station-hardware-evidence/gate.mts` around lines 304 - 315, Update
requestJson to pass AbortSignal.timeout(30_000) as the fetch signal, ensuring
stalled GitHub API requests fail within 30 seconds while preserving the existing
response validation and JSON handling.

🤖 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.

Nitpick comments:
In `@tools/station-hardware-evidence/gate.mts`:
- Around line 304-315: Update requestJson to pass AbortSignal.timeout(30_000) as
the fetch signal, ensuring stalled GitHub API requests fail within 30 seconds
while preserving the existing response validation and JSON handling.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ae9cffc3-453d-4142-a27a-0ba2b515a48d

📥 Commits

Reviewing files that changed from the base of the PR and between 78e0e4e and 45775c7.

📒 Files selected for processing (6)

• .github/PULL_REQUEST_TEMPLATE.md
• .github/workflows/station-hardware-evidence.yaml
• AGENTS.md
• ci/source-shape-test-budget.json
• test/station-hardware-evidence-gate.test.ts
• tools/station-hardware-evidence/gate.mts

[cv]

Maintainer review is complete on the current revision: the trusted workflow never executes PR code, permissions remain least-privilege, first-posted evidence now revalidates, Node is pinned, 25 focused contract tests pass, the canonical advisor has no findings, and all named CI checks are green. Deferring approval only because GitHub returns an empty pull_requests association for this fork’s Actions runs, so the deterministic merge gate cannot authenticate the successful contexts. No code changes are requested.

[cjagwani]

Reviewed exact head d34026e against current main (5b547cdf). Please address these blockers before approval:

1. The evidence hash is computed from the PR-head script blob, while the active main ruleset does not require strict up-to-date status checks. A conflict-free base change can therefore alter the eventual merge-result bytes after this check passes. Validate the synthetic merge result or require an up-to-date/strict Station gate, and add a concurrent non-conflicting base-change regression.
2. A green maintainer deferral can become invalid without rerunning this workflow. Closing its required follow-up issue, or losing the required authority, leaves the old success context reusable because the workflow does not receive those state changes. Add merge-time revalidation or an explicit invalidation mechanism, with a follow-up-closure regression.
3. The linked product decision is not accepted: #7191 remains needs: triage, has no Issue Type/project decision, and the repository ruleset does not require Station / Hardware Evidence. Please establish ownership, lifecycle, trust semantics, strictness, and rollout before presenting this as a merge gate.

The current PASS result is also self-attested metadata rather than authenticated DGX Station provenance. Either add trusted run/artifact provenance or rename and document the result so human qualification review remains explicit. The branch can be mechanically merged with current main (no changed-path overlap), but that refresh will not resolve these findings.

[cv]

The product-scope decision is recorded in #7191: accept the hard evidence requirement, but simplify the mechanism.

Please revise this PR around the following contract:

• a PR changing scripts/prepare-dgx-station-host.sh must link reviewable DGX Station test evidence
• the evidence identifies the tested commit, Station profile/scenario, result, and supporting link
• any maintainer may review the evidence; there will be no designated Station owner
• without acceptable evidence, the PR is not ready to approve or merge
• the evidence is human-reviewed, not authenticated hardware provenance
• exceptional bypasses use existing repository governance rather than a Station-specific deferral protocol

The hard gate should be required maintainer approval through existing review controls. Please remove the custom comment grammar, script-hash protocol, permission and follow-up-issue validation, deferral state machine, comment-triggered workflow, custom status check, and their supporting implementation/tests. Retain only the smallest PR-template and contributor/agent guidance needed to make the requirement visible.