docs(contributing): share permanent writing guide

[cv]

Summary

This PR moves the permanent NemoClaw writing policy from CONTRIBUTING.md to WRITING.md and removes the pilot terms. It updates contributor and maintainer guidance, and it makes the PR Review Advisor load the guide from its trusted workflow checkout.

Changes

• Add WRITING.md as the source for writing scope, terms, rules, examples, and review policy.
• Point contributor docs, agent guidance, skills, and the PR template to the shared guide.
• Embed the guide in the PR Review Advisor prompt and test that a PR worktree cannot replace it.

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: No product behavior changes. This PR updates contributor and advisor guidance directly.
• 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 advisor resolves WRITING.md from the trusted script checkout. test/pr-review-advisor-writing-guide.test.ts proves that a file in the PR worktree cannot replace it.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable. scripts/prepare-dgx-station-host.sh is unchanged.
• 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 — npx vitest run test/pr-review-advisor.test.ts test/maintainer-skills-policy.test.ts test/skills-frontmatter.test.ts passed 86 tests. After the review fix, npx vitest run test/pr-review-advisor.test.ts test/pr-review-advisor-writing-guide.test.ts passed 46 tests. npm run test-size:check passed.
• Applicable broad gate passed — Not run. The focused tests cover the advisor and skill changes.
• 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). The build passed with 0 errors and 2 existing Fern warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only). WRITING.md is a root repository guide and includes its SPDX header; Fern frontmatter does not apply.

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• New Features

  • Added a centralized NemoClaw Writing Guide with required terminology, writing rules, and examples.
  • Updated contributor, maintainer, documentation, and PR template guidance to reference the new Writing Guide.
  • PR review assistance now incorporates the trusted Writing Guide when generating review guidance.

• Documentation

  • Clarified which language findings block vs remain suggestions, and how to format rewrite suggestions.
  • Updated guidance for PR text, changelog/announcement posts, test titles, and procedural documentation.

• Tests

  • Added/updated coverage to verify the trusted Writing Guide is loaded and used by review assistance.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 8482afc in the codex/shared-writing... branch remains at 96%, unchanged from commit 6b29277 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 8482afc in the codex/shared-writing... branch remains at 80%, unchanged from commit 6b29277 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 6b29277	codex/shared-writing... 8482afc	+/-
src/lib/inferen...lama/process.ts	100%	50%	-50%
src/lib/inferen...er-lifecycle.ts	71%	65%	-6%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/tunnel/services.ts	73%	73%	0%
src/lib/adapter...shell/client.ts	88%	90%	+2%

---

_{Updated July 22, 2026 05:07 UTC}

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds WRITING.md as the central writing guide, updates repository instructions to reference it, and integrates the trusted guide into the PR review advisor with corresponding tests.

Changes

Writing Guide Adoption

Layer / File(s)	Summary
Writing guide and policy contract WRITING.md, AGENTS.md, CONTRIBUTING.md, docs/*	Adds writing rules, terminology, examples, and review policy while replacing the former Technical English guidance.
Contributor and maintainer guidance updates .agents/skills/*, .github/PULL_REQUEST_TEMPLATE.md	Updates PR, review, workflow, release-note, and follow-up instructions to use the new guide and its language-review rules.
Trusted advisor prompt integration tools/pr-review-advisor/analyze.mts, test/pr-review-advisor*.test.ts	Loads the trusted guide into the advisor prompt and tests trusted-path loading, prompt inclusion, and isolation from user-controlled content.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• NVIDIA/NemoClaw#7263: Updates PR Review Advisor language-guidance expectations related to the writing-profile content changed by this PR.

Suggested labels: area: onboarding, area: skills

🚥 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 is concise and accurately reflects the main change: introducing a shared permanent writing guide.

✨ 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/shared-writing-guide

---

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

[github-actions]

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

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