feat: require writer receipts for docs-only PRs

[miyoungc]

Summary

Extends the documentation-writer receipt pilot from code-changing pull requests to documentation-only pull requests so the writer subagent also verifies writing rules and documentation style. The architecture and contributor guidance now describe the shared workflow, exact-head freshness, and code-versus-docs-only adoption metrics.

Changes

• Require a valid receipt when changed files include code or documentation, while leaving the pilot advisory.
• Count documentation-only pull requests in receipt coverage and report eligiblePrs, eligibleCodePrs, and eligibleDocsOnlyPrs.
• Update the PR template and contributor instructions to require writing-rules and style review for documentation-only changes.
• Preserve the original completed-implementation checkbox wording for historical pilot receipts; the retrospective report is the current consumer, and the focused receipt test protects it.
• Document the receipt workflow, metric meanings, and exact-head refresh behavior in the engineer agentic documentation guide.

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

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Reviewed .github/PULL_REQUEST_TEMPLATE.md, AGENTS.md, CONTRIBUTING.md, docs/CONTRIBUTING.md, and docs/resources/engineer-agentic-documentation.mdx; aligned the writing-rules and documentation-style instructions, metric names, checker messages, and test titles.
• Agent: Codex Desktop
• PR: feat: require writer receipts for docs-only PRs #7400

DGX Station Hardware Evidence

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

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: npx vitest run --project integration test/docs-review-receipt.test.ts passed 14 tests.
• 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 this focused receipt classifier and report change.
• 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)
  • Result: Passed with 0 errors; Fern emitted one existing CLI version-upgrade warning.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Summary by CodeRabbit

• Documentation

  • Added guidance for making documentation reviews observable through structured pull-request receipts.
  • Documented review requirements for documentation-only changes, including terminology, structure, voice, and code samples.
  • Clarified when reviews become stale and must be rerun after new commits.

• Workflow Improvements

  • Documentation review validation now covers both code and documentation changes.
  • Added separate reporting metrics for code-related and documentation-only pull requests.
  • Updated receipt wording and validation guidance for completed changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 08608b7f-39c7-4b57-8b53-621bcce428b8

📥 Commits

Reviewing files that changed from the base of the PR and between 325f82a and 6738512.

📒 Files selected for processing (7)

• .github/PULL_REQUEST_TEMPLATE.md
• AGENTS.md
• CONTRIBUTING.md
• docs/CONTRIBUTING.md
• docs/resources/engineer-agentic-documentation.mdx
• scripts/docs-review-receipt.mts
• test/docs-review-receipt.test.ts

---

📝 Walkthrough

Walkthrough

The PR expands documentation-review receipt requirements for code and documentation changes, updates receipt validation and reporting for documentation-only changes, broadens accepted checkbox wording, and documents workflow operation, adoption metrics, and stale-receipt handling.

Changes

Documentation Review Receipt System

Layer / File(s)	Summary
Receipt validation and reporting scripts/docs-review-receipt.mts, test/docs-review-receipt.test.ts	Receipt evaluation, parsing, eligibility classification, reporting metrics, and tests now cover documentation-only changes, updated wording, and stale receipts.
Review process and receipt requirements .github/PULL_REQUEST_TEMPLATE.md, AGENTS.md, CONTRIBUTING.md, docs/CONTRIBUTING.md	Contributor and agent guidance requires documentation-writer receipts for code or documentation changes, records the reviewed head SHA, and defines reruns after subsequent commits.
Engineer guide integration docs/resources/engineer-agentic-documentation.mdx	Documents receipt fields, CI behavior, refresh rules, adoption metrics, implementation references, and review-readiness requirements.

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

Sequence Diagram(s)

sequenceDiagram
  participant Contributor
  participant DocumentationWriter
  participant PullRequest
  participant DocumentationReviewCI
  participant ReceiptScript
  Contributor->>PullRequest: submit code or documentation changes
  PullRequest->>DocumentationWriter: provide change summary and validation evidence
  DocumentationWriter->>PullRequest: record review receipt and covered head SHA
  DocumentationReviewCI->>ReceiptScript: validate receipt on pull request commits
  ReceiptScript->>DocumentationReviewCI: return receipt status and report metrics

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7343: Introduces the related documentation-writer review workflow and receipt script.

Suggested reviewers: cv, apurvvkumaria

🚥 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: expanding writer receipt requirements to docs-only pull requests.
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.

✨ 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/document-docs-review-receipts

---

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

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7400.docs.buildwithfern.com/nemoclaw

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@docs/resources/engineer-agentic-documentation.mdx`:
- Around line 108-114: Update docs/resources/engineer-agentic-documentation.mdx
lines 108-114 to state that any subsequent commit changing the pull-request head
invalidates the receipt, not only implementation commits; update line 582 to use
the same all-commits scope in the readiness requirement. Ensure both locations
consistently reflect SHA-based staleness for documentation-only and metadata
commits.

🪄 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: 63b2bb93-30bd-4861-9a20-2514ff32cace

📥 Commits

Reviewing files that changed from the base of the PR and between 1bb15a0 and e3b16be.

📒 Files selected for processing (1)

• docs/resources/engineer-agentic-documentation.mdx

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 6738512 in the codex/document-docs-... branch remains at 96%, unchanged from commit 1bb15a0 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 6738512 in the codex/document-docs-... branch remains at 80%, unchanged from commit 1bb15a0 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 1bb15a0	codex/document-docs-... 6738512	+/-
src/lib/onboard...ndbox-create.ts	83%	33%	-50%
src/lib/onboard...-create-plan.ts	88%	75%	-13%
src/lib/onboard...-desktop-gpu.ts	89%	77%	-12%
src/lib/onboard...ndbox-create.ts	91%	83%	-8%
src/lib/state/m...-acquisition.ts	89%	84%	-5%
src/lib/platform.ts	89%	84%	-5%
src/lib/agent/r...ime-manifest.ts	100%	100%	0%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/shields/index.ts	71%	72%	+1%

---

_{Updated July 22, 2026 23:17 UTC}

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

[cv]

Approved on exact head 6738512 against base 1bb15a0. The documentation-only receipt policy remains advisory, preserves historical receipt wording, ties freshness to every head-changing commit, and has focused tests plus passing GitHub checks. Security review found no credential, injection, authorization, dependency, cryptography, configuration, test, or system-security regression.