fix(skills): preserve superseded PR attribution

[cv]

Summary

The #6684/#6689 supersession exposed that the maintainer workflow could select a replacement and recommend closing its source without checking whether transferred work retained machine-readable contributor attribution.
This change treats supersession as relationship evidence, requires exact source-commit authorship or co-authorship before selection and closure, and preserves the existing authorization boundaries.

Changes

• Add canonical policy for superseded PR attribution, safe DCO handling, and independent implementations.
• Classify replacement work as independent, transferred, or unclear, and leave the winner unset when attribution evidence is missing.
• Remove supersession as a comparator tiebreaker.
• Sequence transferred work before revalidation, merge, and source-PR closure in the comparator verdict and review finder.
• Add a focused source-contract test for attribution, contributor identity, ranking, and operation order.
• Keep render-verdict.py and validation/backtest.md unchanged because this is a reviewer workflow contract, not a renderer gate.

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 maintainer-agent policy and skill behavior, not a NemoClaw API, CLI, configuration, UI, runtime workflow, or published documentation page.
• 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: Maintainer-directed attribution policy change; canonical write-authorization boundaries remain explicit, the focused contract passes, and the independent review found no issues.
• 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: no-docs-needed
• Evidence: Reviewed the complete seven-file diff, including the active/passive parser direction fix and duplicate-edge regression coverage, after hook formatting. No docs/ change is needed because the change affects only maintainer-agent behavior. The final review found no issues; the focused contract passed 18/18, and repository-managed shfmt and ShellCheck passed.
• 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 validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project integration test/maintainer-skills-policy.test.ts: 18/18 passed; npx vitest run --project integration test/skills-frontmatter.test.ts: 29/29 passed; repository-managed shfmt and ShellCheck: passed; npm run checks:repository: passed.
• 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 to scoped maintainer skill guidance and its source-contract test.
• 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: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• Documentation

  • Added guidance for handling superseded pull requests, including contribution attribution, authorship preservation, DCO verification, and maintainer authorization.
  • Clarified how to distinguish independent, transferred, and unclear work relationships.
  • Updated comparison and verdict guidance to require attribution, commit, and diff verification before selecting a replacement or closing a pull request.

• Bug Fixes

  • Improved recognition and direction of active and passive supersession statements.
  • Prevented duplicate supersession relationships from affecting evaluations.

• Tests

  • Added coverage for attribution requirements, supersession phrase parsing, and comparator reruns.

[coderabbitai]

📝 Walkthrough

Walkthrough

Superseded PR workflows now separate relationship detection from transferred-work verification. Attribution policy checks are required before ranking, merging, or closing a superseded PR. Tests validate authorship, co-authorship, DCO, parser orientation, comparator reruns, and closure requirements.

Changes

Superseded PR attribution

Layer / File(s)	Summary
Canonical attribution policy .agents/skills/nemoclaw-maintainer-policies/references/workflow-policy.md	Defines preserved authorship, verified co-author trailers, DCO and commit checks, unresolved identity handling, related PR links, and authorization requirements.
Comparison and supersession parsing .agents/skills/nemoclaw-maintainer-pr-comparator/SKILL.md, .agents/skills/nemoclaw-maintainer-pr-comparator/scripts/parse-supersession.sh, .agents/skills/nemoclaw-maintainer-pr-comparator/tiebreakers.md	Parses active and passive supersession phrases, normalizes edge direction, classifies transferred work, blocks unverified winner selection, removes supersession from ranking criteria, and requires comparator reruns after transfer.
Closure guidance and validation .agents/skills/nemoclaw-maintainer-find-review-pr/SKILL.md, .agents/skills/nemoclaw-maintainer-pr-comparator/templates/verdict.md, test/maintainer-skills-policy.test.ts	Requires commit and diff comparison, attribution preservation, verification, validation, comparator reruns, target merging, and delayed source closure. Tests cover policy requirements and parser behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested labels: area: skills, bug-fix

Suggested reviewers: jyaunches, ericksoa

Sequence Diagram(s)

sequenceDiagram
  participant PRFinder
  participant SupersessionParser
  participant Comparator
  participant AttributionPolicy
  PRFinder->>SupersessionParser: Parse supersession statements
  SupersessionParser-->>PRFinder: Return normalized PR relationships
  PRFinder->>Comparator: Compare commits, diffs, and scope
  Comparator->>AttributionPolicy: Verify transferred contribution attribution
  AttributionPolicy-->>Comparator: Return verification result
  Comparator-->>PRFinder: Return winner or no clear winner

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 clearly and concisely describes the main change: preserving attribution for superseded pull requests.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/preserve-superseded-pr-attribution

---

_{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 52fdd4a in the codex/preserve-super... branch remains at 96%, unchanged from commit 64d6828 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 52fdd4a in the codex/preserve-super... branch remains at 81%, unchanged from commit 64d6828 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 64d6828	codex/preserve-super... 52fdd4a	+/-
src/lib/onboard/docker-cdi.ts	80%	70%	-10%
src/lib/onboard...host-anchors.ts	94%	90%	-4%
src/lib/onboard/preflight.ts	80%	80%	0%
src/lib/onboard...al-inference.ts	91%	93%	+2%
src/lib/actions...orchestrator.ts	83%	87%	+4%
src/lib/onboard...box-gpu-mode.ts	92%	97%	+5%
src/lib/actions...confirmation.ts	69%	79%	+10%
src/lib/actions...ocker-health.ts	65%	82%	+17%
src/lib/onboard...box-prebuild.ts	74%	92%	+18%
src/lib/onboard...flight-ports.ts	33%	67%	+34%

---

_{Updated July 31, 2026 06:46 UTC}

[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 · 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.

[coderabbitai]

Actionable comments posted: 4

🤖 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 @.agents/skills/nemoclaw-maintainer-find-review-pr/SKILL.md:
- Line 102: Update the closure guidance around the `#1392/`#1416 comparison to
require completed transfer, verification of updated commits and CI, and a rerun
of the comparator before recommending source closure. Preserve the existing
full-scope and contributor-attribution checks, and make closure conditional on
the post-transfer comparison succeeding.

In @.agents/skills/nemoclaw-maintainer-pr-comparator/SKILL.md:
- Around line 62-70: Use one canonical supersession pattern set across the
workflow, matching parse-supersession.sh and consistently including “follow-up
to” and “closes in favor of”. Update the documented patterns in
.agents/skills/nemoclaw-maintainer-pr-comparator/SKILL.md lines 62-70 and apply
the same set in .agents/skills/nemoclaw-maintainer-find-review-pr/SKILL.md lines
71-77 before commit/diff and attribution checks.

In @.agents/skills/nemoclaw-maintainer-pr-comparator/templates/verdict.md:
- Around line 58-68: Update the transfer workflow in the numbered action list to
explicitly verify the source PR’s Signed-off-by declaration, preserve the
replacement author’s DCO declaration when reconstructing commits, and reject
copying another contributor’s DCO sign-off. Also require confirming every
replacement commit is GitHub-verified before rerunning the comparator and
proceeding with closure; keep the existing transfer, attribution, CI, and
comparator steps intact.

In `@test/maintainer-skills-policy.test.ts`:
- Around line 353-361: Strengthen the assertions in the verdict-order test
around the existing transfer, comparator rerun, merge, and source-PR closure
text. Capture each phrase’s index and assert the complete sequence: transfer
first, comparator verification/rerun next, merge only afterward, and closure
after the new verdict; keep the test focused on the public policy output rather
than implementation details.

🪄 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: 5ee7b29a-f0c4-47ed-a31d-facb321e9238

📥 Commits

Reviewing files that changed from the base of the PR and between 64d6828 and 2238ddf.

📒 Files selected for processing (6)

• .agents/skills/nemoclaw-maintainer-find-review-pr/SKILL.md
• .agents/skills/nemoclaw-maintainer-policies/references/workflow-policy.md
• .agents/skills/nemoclaw-maintainer-pr-comparator/SKILL.md
• .agents/skills/nemoclaw-maintainer-pr-comparator/templates/verdict.md
• .agents/skills/nemoclaw-maintainer-pr-comparator/tiebreakers.md
• test/maintainer-skills-policy.test.ts