docs(contributing): add contribution intake and decision record

[wscurran]

Summary

Feature requests now collect the planning details maintainers need before implementation starts. CONTRIBUTING.md now defines the matching maintainer decision record while preserving the direct pull request path for small documentation changes and low-risk fixes.

Related Issue

Closes #9659
Supports #8498

Changes

• Require feature requests to state scope and exclusions, proposed ownership, requested placement and support expectations, validation, compatibility, and security or privacy impact.
• Allow explained Not applicable or Unknown answers.
• Document the maintainer decision, reason and placement, accountable maintainer, and validation plan required before accepted substantive work starts.
• Keep the direct pull request path for small documentation changes and low-risk fixes.

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: This change updates a declarative GitHub issue form and contributor guidance. It does not change NemoClaw runtime behavior; YAML and Markdown validation are recorded below.
• 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:

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 — command/result or justification: check-yaml and markdownlint-cli2 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)

Documentation build: npm run docs passed with 0 errors and 2 warnings.

---

Signed-off-by: Will Curran wcurran@nvidia.com

Summary by CodeRabbit

• Documentation
  • Enhanced feature request templates with required details covering scope, ownership, placement, validation, compatibility, and security or privacy impact.
  • Added maintainer triage guidance requiring documented decisions, rationale, accountability, and validation plans before substantive proposals proceed.

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

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: e2e62848-95f3-4183-80f7-84314bdf3b6e

📥 Commits

Reviewing files that changed from the base of the PR and between b7383ca and 4701f64.

📒 Files selected for processing (2)

• .github/ISSUE_TEMPLATE/feature_request.yml
• CONTRIBUTING.md

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Walkthrough

Walkthrough

The contribution request template now requires proposal scope, ownership, placement, support, validation, compatibility, and security details. CONTRIBUTING.md requires a documented maintainer decision before substantive implementation while preserving direct pull requests for documentation and low-risk fixes.

Changes

Contribution process

Layer / File(s)	Summary
Proposal intake requirements .github/ISSUE_TEMPLATE/feature_request.yml	The feature request template adds required fields for scope and exclusions, ongoing ownership, placement and support expectations, validation, compatibility, and security or privacy impact.
Maintainer decision gate CONTRIBUTING.md	The contribution guide requires a documented decision, rationale, accountable maintainer, and validation plan before substantive implementation. Documentation changes and low-risk fixes remain exempt.

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

Merge Risk: ⚪ Minimal · up to 4701f

This change only updates contribution intake and maintainer guidance; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: apurvvkumaria, cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the documentation changes to contribution intake and maintainer decision records.
Linked Issues check	✅ Passed	The changes address the linked issue by expanding intake details, documenting maintainer decisions, and preserving the direct-PR path for low-risk work.
Out of Scope Changes check	✅ Passed	The changes are limited to contribution documentation and the existing feature request template, with no unrelated implementation or automation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/contribution-intake-decision-record

---

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

[prekshivyas]

Draft review for commit 48da715009818ae0d1be76a2ff6fabdcb0f46dfb against base 01e0b92645a68d4ff772dce20ee5758def7211cc.

The feature-request form is scoped to planning evidence, permits explained unknown/not-applicable answers, warns against disclosing sensitive information, and preserves the direct PR path for small documentation changes and low-risk fixes. I found one actionable policy ambiguity in CONTRIBUTING.md: the implementation gate is phrased as applying only when the recorded decision is already Accept, so the other recorded outcomes appear to satisfy the preceding requirement and permit work. The inline rewrite makes Accept itself a prerequisite.

Validation: pre-commit run check-yaml --files .github/ISSUE_TEMPLATE/feature_request.yml passed; npx markdownlint-cli2 CONTRIBUTING.md passed; git diff --check passed. No runtime, credential, dependency, authorization, cryptography, or deployment behavior changes are present. I am leaving a comment rather than approval while the PR remains a draft.

[prekshivyas]

[P2] Make Accept a prerequisite for implementation

As written, this forbids implementation only with an Accept decision until the other fields exist. Combined with line 85, a recorded Request changes, Defer, or Decline can be read as satisfying the decision-before-work gate. State the intended positive gate directly: “Contributors must not start implementing a substantive contribution until a maintainer records Accept, names one accountable maintainer, and states an explicit validation plan.”

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit 7547c48 in the codex/contribution-i... branch remains at 96%, unchanged from commit 40dc272 in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit 7547c48 in the codex/contribution-i... branch remains at 83%, unchanged from commit fed0c45 in the main branch.

Show a line coverage summary of the most impacted files.

File	main fed0c45	codex/contribution-i... 7547c48	+/-
src/lib/onboard...uild-context.ts	86%	86%	0%
src/lib/cli/oclif-metadata.ts	95%	95%	0%
src/commands/sandbox/agent.ts	100%	100%	0%
src/lib/cli/public-dispatch.ts	87%	88%	+1%
src/lib/onboard...on-authority.ts	81%	82%	+1%
src/lib/securit...ate-endpoint.ts	95%	96%	+1%
src/lib/cli/com...and-registry.ts	93%	94%	+1%
src/commands/sandbox/mcp.ts	85%	86%	+1%
src/commands/uninstall.ts	90%	91%	+1%
src/lib/onboard...nflict-guard.ts	88%	93%	+5%

---

_{Updated August 20, 2026 04:05 UTC}

[github-actions]

PR Review Advisor — Blocking findings reported

Advisor assessment: Blockers require maintainer review
Next action: Review the blockers below.
Findings: 1 blocker · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 1 blocker · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections match; Nemotron reported 1 fewer blocker, the same number of warnings, the same number of suggestions.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

2 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• justified — core NemoClaw at .github/ISSUE_TEMPLATE/feature_request.yml:58: Keep the term because the placement contrast changes contribution routing.
• define — substantive contribution at CONTRIBUTING.md:94: Define the boundary or use the enumerated proposal categories consistently so contributors can determine whether the acceptance gate applies.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Blockers

PRA-1 Blocker — Record all product-scope expectations in an Accept decision

• Location: CONTRIBUTING.md:88
• Category: scope
• Problem: The new decision-record process permits an Accept decision without lifecycle, compatibility, or security expectations.
• Impact: A maintainer can accept a new supported surface under the documented process without recording the lifecycle, compatibility, or security contract required by the product-scope gate.
• Fix: Add lifecycle, compatibility, and security expectation fields to the Accept decision record. Require `Not applicable` with a reason when an expectation does not apply. Keep contributor proposal fields distinct from the maintainer decision.
• Verification: Compare the final Accept record in CONTRIBUTING.md with the product-scope gate in AGENTS.md and confirm that each required expectation has a maintainer-recorded outcome.
• Test coverage: Add a repository-policy test that reads AGENTS.md, CONTRIBUTING.md, and .github/ISSUE_TEMPLATE/feature_request.yml and verifies that an accepted supported-surface proposal records ownership, lifecycle, compatibility, security, and validation expectations.
• Evidence: AGENTS.md:14-16 requires an accepted issue or design decision to define ownership, lifecycle, compatibility, security, and validation expectations. CONTRIBUTING.md:88-94 defines the new Accept record and omits lifecycle, compatibility, and security expectations. .github/ISSUE_TEMPLATE/feature_request.yml:69-95 collects contributor compatibility and security input, but states that maintainers make the final placement and support decision.

Workflow run details

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

[apurvvkumaria]

Documentation and contribution-workflow review complete.

• The feature-request form now requires an Accept decision, one accountable maintainer, and an explicit validation plan before substantive implementation starts.
• CONTRIBUTING.md states the same gate and distinguishes intake, decision, implementation, and verification responsibilities without creating a second process vocabulary.
• The wording is direct, uses the repository’s controlled terms, and keeps maintainer authority and contributor responsibility clear.
• This changes contributor guidance and issue intake only; it does not create or approve a product integration.
• The full documentation build passed with 0 errors and the two standard Fern warnings. Generated agent variants are current. CLI build and type checking, hooks, and pre-push checks passed after incorporating current main.
• Security review: PASS across secrets, input validation, authorization, dependencies, error handling, cryptography, deployment, testing, and system safety. The form collects planning text only, changes no repository permission, and executes no contributor-provided value.
• Size: 85 additions and 3 deletions across two files. This is not a large LOC increase.

The remaining gates are the fresh required checks and any new actionable review feedback.

[apurvvkumaria]

Approved after the contribution-workflow, documentation-writing, security, and validation review recorded above. Fresh CI and later actionable feedback remain merge gates.