ci(docs): collect documentation writer review data

.github/PULL_REQUEST_TEMPLATE.md

@@ -26,6 +26,16 @@
 - [ ] 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
+<!-- Required for code changes after implementation is complete. Keep one review checkbox and one instance of each visible or hidden field. For Evidence, list changed doc paths or name the reason that no doc change is needed or the review is blocked. For Agent, use a consistent product and surface name, such as Codex Desktop, Codex CLI, Claude Code, or Cursor. Record this PR number. After committing all review changes, put `git rev-parse --short HEAD` and `git rev-parse --short HEAD:AGENTS.md` in the hidden metadata below. Rerun the review and refresh that metadata after new implementation commits. This receipt is advisory during the data-collection pilot. -->
+- [ ] Documentation writer subagent reviewed the completed implementation
+- Result: `docs-updated` | `no-docs-needed` | `blocked`
+- Evidence:
+- Agent:
+- PR: #<number>
+<!-- docs-review-head-sha: -->
+<!-- docs-review-agents-blob-sha: -->
+
 ## DGX Station Hardware Evidence
 <!-- Required only when scripts/prepare-dgx-station-host.sh changes. Maintainers must review the linked evidence before approving or merging. This is human-reviewed evidence, not authenticated hardware provenance. Exceptional bypasses use existing repository governance and must be documented on the PR. -->
 - [ ] Tested on DGX Station

.github/workflows/docs-review-receipt.yaml

@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+name: CI / Documentation Writer Review
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  docs-review-receipt:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: "22"
+
+      - name: Collect receipt inputs
+        id: receipt-inputs
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          changed_files="$RUNNER_TEMP/docs-review-changed-files.txt"
+          git diff --name-only "$BASE_SHA" "$HEAD_SHA" > "$changed_files"
+          agents_blob="$(git rev-parse "${HEAD_SHA}:AGENTS.md")"
+          echo "changed_files=$changed_files" >> "$GITHUB_OUTPUT"
+          echo "agents_blob=$agents_blob" >> "$GITHUB_OUTPUT"
+
+      - name: Check documentation writer review receipt
+        continue-on-error: true
+        env:
+          AGENTS_BLOB: ${{ steps.receipt-inputs.outputs.agents_blob }}
+          CHANGED_FILES: ${{ steps.receipt-inputs.outputs.changed_files }}
+        run: >-
+          node --experimental-strip-types --no-warnings scripts/docs-review-receipt.mts check
+          --event "$GITHUB_EVENT_PATH"
+          --changed-files "$CHANGED_FILES"
+          --agents-blob "$AGENTS_BLOB"
+          --mode advisory

AGENTS.md

@@ -253,6 +253,8 @@ Follow `.agents/skills/_shared/pr-follow-up.md`: after opening or pushing to a P
 
 - Treat `docs/` as the source of truth for user-facing documentation and follow `docs/CONTRIBUTING.md`.
 - After completing development changes, run a documentation writer subagent before final handoff. Give it the changed files, behavior summary, and test evidence so it can update docs or report that no doc changes are needed.
+- After the review, complete the PR template's Documentation Writer Review section. Record the result, evidence, agent surface, and PR number. Put the reviewed head SHA and current `AGENTS.md` blob SHA in the template's hidden metadata comments.
+- If implementation changes after the hidden head SHA, rerun the documentation writer review and refresh the hidden metadata. The receipt check runs again when new commits are pushed.
 - For normal docs changes, include source pages under `docs/`.
 - Update `.agents/skills/nemoclaw-user-guide/SKILL.md` only when the AI-agent docs routing guidance changes.
 - During pre-tag release prep, run `nemoclaw-contributor-update-docs` and include the canonical release entry in the release-note docs PR. Create or update `docs/changelog/YYYY-MM-DD.mdx` for `vX.Y.Z` following `docs/CONTRIBUTING.md`; a PR that updates ordinary pages without the dated changelog entry is incomplete. Merge that PR, or record an explicit maintainer waiver, before generating the release plan.

CONTRIBUTING.md

@@ -400,6 +400,51 @@ If your change affects user-facing behavior (new commands, changed defaults, new
 If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes the `nemoclaw-contributor-update-docs` skill that drafts doc updates. Use it before writing from scratch and follow the style guide in [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).
 During release prep, run that skill first, make any doc version bumps, then open the docs refresh PR.
 
+### Documentation Writer Review Receipt
+
+After you complete a code change, a documentation writer subagent must review the implementation.
+Complete the Documentation Writer Review section in the PR description after that review.
+Keep one review completion checkbox and one instance of each visible or hidden field.
+
+Record one result:
+
+- `docs-updated` when the review changes documentation. List the changed documentation paths as evidence.
+- `no-docs-needed` when the evidence explains why documentation does not change.
+- `blocked` when a named decision, dependency, access problem, or input prevents the review.
+
+Record the product and surface that ran the review, such as `Codex Desktop`, `Codex CLI`, `Claude Code`, or `Cursor`.
+Use the same name for the same surface across PRs so the report groups its data correctly.
+Record the PR number in the visible receipt so the check can detect a receipt copied from another PR.
+
+Commit all changes from the final review.
+Then run these commands and put their values in the receipt's hidden HTML metadata comments:
+
+```bash
+git rev-parse --short HEAD
+git rev-parse --short HEAD:AGENTS.md
+```
+
+The visible PR number ties the receipt to this PR, while the hidden head SHA identifies the implementation revision that the review covered.
+Rerun the review when implementation changes after the hidden head SHA.
+Pushing a new commit runs the receipt check again and reports the review as stale until the hidden metadata is refreshed.
+The Documentation Writer Review check reports an advisory finding when the receipt is missing, incomplete, or stale.
+The check compares the receipt's PR number with the current PR number, the hidden head SHA with the current PR head, and the hidden `AGENTS.md` blob SHA with the current PR's file.
+
+Maintainers can export receipt data from PR descriptions:
+
+```bash
+npm run docs-review:report -- --since 2026-06-12 --format csv > /tmp/nemoclaw-docs-review.csv
+```
+
+The report uses the authenticated GitHub CLI session and returns JSON by default.
+It measures receipt coverage, PR-number integrity, head-revision freshness, review results, and agent-surface counts.
+It records the `AGENTS.md` blob SHA, but only the PR check compares that SHA with the current PR's file.
+It does not prove that an agent loaded `AGENTS.md`; it records observable workflow compliance.
+The retrospective report classifies code changes from the checked Type of Change field.
+It reports a PR as unclassified when that field is incomplete or contradictory.
+Use `--format summary` to print only aggregate metrics.
+Use `--until YYYY-MM-DD` to set the end of the reporting period.
+
 To build and preview docs locally:
 
 ```console

package.json

@@ -74,6 +74,8 @@
     "docs:sync-agent-variants": "npm run docs:prepare",
     "docs:check-agent-variants": "tsx scripts/sync-agent-variant-docs.mts --check",
     "docs:check-routes": "tsx scripts/check-docs-published-routes.mts",
+    "docs-review:check": "node --experimental-strip-types --no-warnings scripts/docs-review-receipt.mts check",
+    "docs-review:report": "node --experimental-strip-types --no-warnings scripts/docs-review-receipt.mts report",
     "docs:validate": "npm run docs:check-starter-prompt && npm run docs:check-agent-variants && npm run docs:check-routes && FERN_VERSION=$(node -p \"require('./fern/fern.config.json').version\") && cd fern && npx --yes \"fern-api@${FERN_VERSION}\" check",
     "docs:strict": "npm run docs:prepare && npm run docs:validate",
     "docs:live": "npm run docs:prepare && FERN_VERSION=$(node -p \"require('./fern/fern.config.json').version\") && cd fern && npx --yes \"fern-api@${FERN_VERSION}\" docs dev",