docs: document extension readiness gates by jyaunches · Pull Request #6499 · NVIDIA/NemoClaw

jyaunches · 2026-07-08T21:45:40Z

Summary

Adds the candidate surface stability and security reference for NemoClaw extension discussions.
Documents stability levels, execution classes, readiness gates, and issue classifications without creating a public NemoClaw plugin SDK commitment.
References docs(architecture): define extensibility terminology and SDK readiness gates #6229.

Validation

npm run docs

Sibling PR

The sibling PR for issue-6229-taxonomy covers the lifecycle contribution, managed agent package, agent-native plugin, and reserved future NemoClaw plugin SDK taxonomy half of docs(architecture): define extensibility terminology and SDK readiness gates #6229.

Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>

copy-pr-bot · 2026-07-08T21:45:44Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

coderabbitai · 2026-07-08T21:45:54Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 5526c37c-9882-4c27-a88a-dc65d7273234

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch agent/issue-6229-readiness

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

github-actions · 2026-07-08T21:46:21Z

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

None. Docs-only change. The new MDX reference content does not affect installer/onboarding behavior, sandbox lifecycle, credentials, security enforcement, network policy implementation, inference routing, deployment, or real assistant user flows.

Optional E2E

None.

New E2E recommendations

None.

github-actions · 2026-07-08T21:46:22Z

E2E Target Recommendation

Required E2E targets: None
Optional E2E targets: None

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

None. Docs-only change outside test/e2e and the e2e.yaml workflow; it cannot affect E2E target behavior.

Optional E2E targets

None.

Relevant changed files

None.

github-actions · 2026-07-08T21:46:29Z

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

github-actions · 2026-07-08T21:47:43Z

PR Review Advisor (Nemotron Ultra) — Changes requested

Merge posture: Do not merge yet
Primary next action: Resolve or justify PRA-1: Source-of-truth review needed: Issue #6201 classification evidence.
Open items: 0 required · 6 warnings · 2 suggestions · 6 test follow-ups
Since last review: 0 prior items resolved · 2 still apply · 3 new items found

Action checklist

Findings index

ID	Severity	Category	Location	Required action
`PRA-1`	Resolve/justify	architecture	—	Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
`PRA-2`	Resolve/justify	architecture	—	Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
`PRA-3`	Resolve/justify	architecture	—	Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
`PRA-4`	Resolve/justify	docs	`docs/reference/candidate-surface-stability-security.mdx:87`	Add a note in the Issue Classification table or Decision Boundary section stating that #6201 and #6207 classifications are provisional pending maintainer verification of actual issue content when those issues land.
`PRA-5`	Resolve/justify	docs	`docs/reference/candidate-surface-stability-security.mdx:13`	Add a 'Related Documents' or 'See Also' section referencing PR #6498 / the taxonomy document it produces, or add a forward-reference note in the Decision Boundary section.
`PRA-6`	Resolve/justify	security	`docs/reference/candidate-surface-stability-security.mdx:55`	Strengthen the language to 'Not allowed as a public surface today. Any future consideration would require sandbox isolation, least privilege, and fail-closed recovery — no implementation exists and no commitment to implement is made.'
`PRA-7`	Improvement	security	`docs/reference/candidate-surface-stability-security.mdx:35`	Add a parenthetical cross-reference: '(see Credential Storage and Security Best Practices for credential isolation mechanisms)' or link to the relevant enterprise-readiness sections.
`PRA-8`	Improvement	acceptance	`docs/reference/candidate-surface-stability-security.mdx:70`	Add a note clarifying gate applicability per execution class, or add a column in the matrix indicating which readiness gates are relevant for each surface.

Review findings by urgency: 0 required fixes, 6 items to resolve/justify, 2 in-scope improvements

⚠️ Resolve or justify before merge

Investigate these in the current review; either fix them, explain why they are not applicable, or document the accepted risk.

`PRA-1` Resolve/justify — Source-of-truth review needed: Issue #6201 classification evidence

Location: not file-specific
Category: architecture
Problem: The advisor marked localized patch analysis as needs_followup.
Impact: A localized workaround can preserve or hide an invalid state when the source boundary is unclear.
Recommended action: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Missing regression test: Maintainers should verify classification against actual issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 when it lands and update documentation if needed
Done when: The risk is fixed or explicitly justified in the PR. Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Evidence: Line 87: 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says it tracks OpenClaw-side requirements only...'

`PRA-2` Resolve/justify — Source-of-truth review needed: Issue #6207 classification evidence

Location: not file-specific
Category: architecture
Problem: The advisor marked localized patch analysis as needs_followup.
Impact: A localized workaround can preserve or hide an invalid state when the source boundary is unclear.
Recommended action: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Missing regression test: Maintainers should verify classification against actual issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 when it lands and update documentation if needed
Done when: The risk is fixed or explicitly justified in the PR. Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Evidence: Line 88: 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says it tracks only the OpenShell boundary...'

`PRA-3` Resolve/justify — Source-of-truth review needed: Sibling PR #6498 cross-reference

Location: not file-specific
Category: architecture
Problem: The advisor marked localized patch analysis as needs_followup.
Impact: A localized workaround can preserve or hide an invalid state when the source boundary is unclear.
Recommended action: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Missing regression test: Documentation cross-reference check during PR docs: define lifecycle and plugin taxonomy #6498 review or after merge
Done when: The risk is fixed or explicitly justified in the PR. Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Evidence: Decision Boundary (line 13): 'Any cross-link from architecture or taxonomy references should wait for the sibling architecture decision to land' — no PR number or document name

`PRA-4` Resolve/justify — Issue #6201 and #6207 classifications cite unverified broker-provided evidence

Location: docs/reference/candidate-surface-stability-security.mdx:87
Category: docs
Problem: The Issue Classification table rows for OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 (OpenClaw voice plugin) and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 (OpenShell networking) cite 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says...' and 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says...' as evidence. These are broker-provided characterizations, not verified against actual issue content. The previous review (SHA 942451b) flagged this as PRA-1 and it remains unaddressed.
Impact: If broker-provided evidence diverges from actual issue scope when those issues land, the classification could mislead future readers about ownership boundaries between NemoClaw and OpenClaw/OpenShell.
Recommended action: Add a note in the Issue Classification table or Decision Boundary section stating that OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 classifications are provisional pending maintainer verification of actual issue content when those issues land.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Read the Issue Classification table rows for OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207; observe the evidence column cites 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says...' and 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says...' without cross-referencing actual issue content.
Missing regression test: No automated test needed; maintainers should verify classifications against actual issues OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 when they are resolved.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Read the Issue Classification table rows for OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207; observe the evidence column cites 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says...' and 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says...' without cross-referencing actual issue content.
Evidence: Lines 87-88: 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says it tracks OpenClaw-side requirements only...' and 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says it tracks only the OpenShell boundary...'

`PRA-5` Resolve/justify — Missing cross-reference to sibling PR #6498 taxonomy document

Location: docs/reference/candidate-surface-stability-security.mdx:13
Category: docs
Problem: The document does not reference sibling PR docs: define lifecycle and plugin taxonomy #6498 (docs: define lifecycle and plugin taxonomy) which covers the complementary taxonomy half of issue docs(architecture): define extensibility terminology and SDK readiness gates #6229. The previous review (SHA 942451b) flagged this as PRA-2 and it remains unaddressed.
Impact: Readers may miss the complementary taxonomy definitions in PR docs: define lifecycle and plugin taxonomy #6498, leading to incomplete understanding of the docs(architecture): define extensibility terminology and SDK readiness gates #6229 deliverables.
Recommended action: Add a 'Related Documents' or 'See Also' section referencing PR docs: define lifecycle and plugin taxonomy #6498 / the taxonomy document it produces, or add a forward-reference note in the Decision Boundary section.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Check if PR docs: define lifecycle and plugin taxonomy #6498 has been merged and what document it produces; verify a cross-reference exists in this file.
Missing regression test: No automated test; documentation cross-reference check during PR docs: define lifecycle and plugin taxonomy #6498 review.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Check if PR docs: define lifecycle and plugin taxonomy #6498 has been merged and what document it produces; verify a cross-reference exists in this file.
Evidence: Decision Boundary section (line 13) says 'Any cross-link from architecture or taxonomy references should wait for the sibling architecture decision to land' but doesn't reference PR docs: define lifecycle and plugin taxonomy #6498 by number or the document it produces.

`PRA-6` Resolve/justify — Arbitrary third-party executable extension row phrasing could imply future implementation plan

Location: docs/reference/candidate-surface-stability-security.mdx:55
Category: security
Problem: The 'Arbitrary third-party NemoClaw executable extension' row correctly marks this as 'Reserved' and 'Blocked until every readiness gate passes.' However, the Isolation and secret posture column says 'Not allowed as a public surface today. It would require sandbox isolation, least privilege, and fail-closed recovery.' This phrasing could be interpreted as a future implementation plan rather than a firm boundary.
Impact: Security-critical boundary language should be unambiguous. Current phrasing leaves room for misinterpretation as a roadmap item rather than a hard 'not allowed, no commitment' stance.
Recommended action: Strengthen the language to 'Not allowed as a public surface today. Any future consideration would require sandbox isolation, least privilege, and fail-closed recovery — no implementation exists and no commitment to implement is made.'
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Read the Arbitrary third-party row, Isolation and secret posture column (lines 55-58); assess whether the phrasing leaves room for misinterpretation as a roadmap item.
Missing regression test: Documentation review; no automated test.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Read the Arbitrary third-party row, Isolation and secret posture column (lines 55-58); assess whether the phrasing leaves room for misinterpretation as a roadmap item.
Evidence: Lines 55-58 in the Candidate Surface Matrix table, Arbitrary third-party row, Isolation and secret posture column.

💡 In-scope improvements

These are lower-risk, not throwaway. Prefer fixing them in this PR when they are local to changed code; defer only with rationale or a linked follow-up.

`PRA-7` Improvement — Built-in agent lifecycle integration row lacks cross-reference to credential isolation mechanisms

Location: docs/reference/candidate-surface-stability-security.mdx:35
Category: security
Problem: The 'Built-in agent lifecycle integration' row states 'Provider credentials stay on the host and route through `inference.local`.' This is accurate but doesn't explicitly reference the credential isolation mechanisms documented in enterprise-readiness.mdx (credential storage, redaction, memory secret scanner).
Impact: Readers of this reference document may not discover the detailed credential isolation controls without knowing to check enterprise-readiness.mdx.
Suggested action: Add a parenthetical cross-reference: '(see Credential Storage and Security Best Practices for credential isolation mechanisms)' or link to the relevant enterprise-readiness sections.
Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
Verification: Compare the Built-in agent lifecycle integration row's isolation posture (line 35-38) with enterprise-readiness.mdx sections on Credential Storage and Security Best Practices.
Missing regression test: Documentation cross-reference check; no automated test.
Done when: The local improvement is applied, or the PR notes why it should be deferred.
Evidence: Lines 35-38: 'Provider credentials stay on the host and route through `inference.local`.' No cross-reference to enterprise-readiness.mdx.

`PRA-8` Improvement — Readiness gates don't explicitly map applicability per execution class

Location: docs/reference/candidate-surface-stability-security.mdx:70
Category: acceptance
Problem: The Public-SDK Readiness Gates table lists 10 categories but the Candidate Surface Matrix has 7 surfaces with different execution classes (Data-only, Managed executable, Arbitrary executable). The document states 'A candidate public seam cannot move beyond candidate status until every category below has concrete evidence' but doesn't explicitly map which gates apply to which surfaces. Some gates (e.g., Provenance, Secrets) may not apply to Data-only surfaces.
Impact: Readers may incorrectly assume all 10 gates apply equally to all surfaces, or may miss that Data-only surfaces have different requirements than executable surfaces.
Suggested action: Add a note clarifying gate applicability per execution class, or add a column in the matrix indicating which readiness gates are relevant for each surface.
Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
Verification: Review the matrix surfaces against the 10 readiness gates; identify which gates are relevant for Data-only vs Managed executable vs Arbitrary executable surfaces.
Missing regression test: Documentation completeness review; no automated test.
Done when: The local improvement is applied, or the PR notes why it should be deferred.
Evidence: Public-SDK Readiness Gates table (lines 70-80) lists 10 gates with no mapping to execution classes. Matrix surfaces (lines 44-52) have 3 execution classes.

Simplification opportunities: 1 possible cut

These are safe simplification checks only. Do not remove validation, security controls, data-loss prevention, or required tests.

PRA-8 yagni (docs/reference/candidate-surface-stability-security.mdx:70): Implicit assumption that all 10 readiness gates apply uniformly to all surfaces
- Replacement: Explicit note or matrix column mapping gate applicability per execution class (Data-only, Managed executable, Arbitrary executable)
- Net: 3 lines
- Safety boundary: Must not weaken any security gate for surfaces where it applies; only clarify scope

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

PRA-T1 Acceptance clause — VoiceClaw integration via existing messaging and provider contracts #5998, refactor(messaging): organize channels into plugin-style modules #6097, Observability plugin support for external telemetry adapters #3915, OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201, OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 classified without overlapping ownership — add test evidence or identify existing coverage. Issue Classification table maps all 5 issues to distinct matrix rows. However, OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 evidence is broker-provided and unverified (see finding PRA-1).
PRA-T2 Acceptance clause — Cross-reference sibling PR docs: define lifecycle and plugin taxonomy #6498 taxonomy document — add test evidence or identify existing coverage. No reference to PR docs: define lifecycle and plugin taxonomy #6498 or its resulting document in the file. Previous review PRA-2 flagged this.
PRA-T3 Acceptance clause — Mark OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 classifications as provisional pending issue verification — add test evidence or identify existing coverage. Issue Classification table cites 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says...' and 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says...' without provisional notation. Previous review PRA-1 flagged this.
PRA-T4 Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 classification evidence — Maintainers should verify classification against actual issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 when it lands and update documentation if needed. Line 87: 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says it tracks OpenClaw-side requirements only...'
PRA-T5 Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 classification evidence — Maintainers should verify classification against actual issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 when it lands and update documentation if needed. Line 88: 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says it tracks only the OpenShell boundary...'
PRA-T6 Sibling PR docs: define lifecycle and plugin taxonomy #6498 cross-reference — Documentation cross-reference check during PR docs: define lifecycle and plugin taxonomy #6498 review or after merge. Decision Boundary (line 13): 'Any cross-link from architecture or taxonomy references should wait for the sibling architecture decision to land' — no PR number or document name

Since last review details

Current findings, using the urgency labels above:

`PRA-1` Resolve/justify — Source-of-truth review needed: Issue #6201 classification evidence

Location: not file-specific
Category: architecture
Problem: The advisor marked localized patch analysis as needs_followup.
Impact: A localized workaround can preserve or hide an invalid state when the source boundary is unclear.
Recommended action: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Missing regression test: Maintainers should verify classification against actual issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 when it lands and update documentation if needed
Done when: The risk is fixed or explicitly justified in the PR. Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Evidence: Line 87: 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says it tracks OpenClaw-side requirements only...'

`PRA-2` Resolve/justify — Source-of-truth review needed: Issue #6207 classification evidence

Location: not file-specific
Category: architecture
Problem: The advisor marked localized patch analysis as needs_followup.
Impact: A localized workaround can preserve or hide an invalid state when the source boundary is unclear.
Recommended action: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Missing regression test: Maintainers should verify classification against actual issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 when it lands and update documentation if needed
Done when: The risk is fixed or explicitly justified in the PR. Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Evidence: Line 88: 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says it tracks only the OpenShell boundary...'

`PRA-3` Resolve/justify — Source-of-truth review needed: Sibling PR #6498 cross-reference

Location: not file-specific
Category: architecture
Problem: The advisor marked localized patch analysis as needs_followup.
Impact: A localized workaround can preserve or hide an invalid state when the source boundary is unclear.
Recommended action: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Missing regression test: Documentation cross-reference check during PR docs: define lifecycle and plugin taxonomy #6498 review or after merge
Done when: The risk is fixed or explicitly justified in the PR. Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Evidence: Decision Boundary (line 13): 'Any cross-link from architecture or taxonomy references should wait for the sibling architecture decision to land' — no PR number or document name

`PRA-4` Resolve/justify — Issue #6201 and #6207 classifications cite unverified broker-provided evidence

Location: docs/reference/candidate-surface-stability-security.mdx:87
Category: docs
Problem: The Issue Classification table rows for OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 (OpenClaw voice plugin) and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 (OpenShell networking) cite 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says...' and 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says...' as evidence. These are broker-provided characterizations, not verified against actual issue content. The previous review (SHA 942451b) flagged this as PRA-1 and it remains unaddressed.
Impact: If broker-provided evidence diverges from actual issue scope when those issues land, the classification could mislead future readers about ownership boundaries between NemoClaw and OpenClaw/OpenShell.
Recommended action: Add a note in the Issue Classification table or Decision Boundary section stating that OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 classifications are provisional pending maintainer verification of actual issue content when those issues land.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Read the Issue Classification table rows for OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207; observe the evidence column cites 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says...' and 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says...' without cross-referencing actual issue content.
Missing regression test: No automated test needed; maintainers should verify classifications against actual issues OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 when they are resolved.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Read the Issue Classification table rows for OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207; observe the evidence column cites 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says...' and 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says...' without cross-referencing actual issue content.
Evidence: Lines 87-88: 'Issue OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201 says it tracks OpenClaw-side requirements only...' and 'Issue OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207 says it tracks only the OpenShell boundary...'

`PRA-5` Resolve/justify — Missing cross-reference to sibling PR #6498 taxonomy document

Location: docs/reference/candidate-surface-stability-security.mdx:13
Category: docs
Problem: The document does not reference sibling PR docs: define lifecycle and plugin taxonomy #6498 (docs: define lifecycle and plugin taxonomy) which covers the complementary taxonomy half of issue docs(architecture): define extensibility terminology and SDK readiness gates #6229. The previous review (SHA 942451b) flagged this as PRA-2 and it remains unaddressed.
Impact: Readers may miss the complementary taxonomy definitions in PR docs: define lifecycle and plugin taxonomy #6498, leading to incomplete understanding of the docs(architecture): define extensibility terminology and SDK readiness gates #6229 deliverables.
Recommended action: Add a 'Related Documents' or 'See Also' section referencing PR docs: define lifecycle and plugin taxonomy #6498 / the taxonomy document it produces, or add a forward-reference note in the Decision Boundary section.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Check if PR docs: define lifecycle and plugin taxonomy #6498 has been merged and what document it produces; verify a cross-reference exists in this file.
Missing regression test: No automated test; documentation cross-reference check during PR docs: define lifecycle and plugin taxonomy #6498 review.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Check if PR docs: define lifecycle and plugin taxonomy #6498 has been merged and what document it produces; verify a cross-reference exists in this file.
Evidence: Decision Boundary section (line 13) says 'Any cross-link from architecture or taxonomy references should wait for the sibling architecture decision to land' but doesn't reference PR docs: define lifecycle and plugin taxonomy #6498 by number or the document it produces.

`PRA-6` Resolve/justify — Arbitrary third-party executable extension row phrasing could imply future implementation plan

Location: docs/reference/candidate-surface-stability-security.mdx:55
Category: security
Problem: The 'Arbitrary third-party NemoClaw executable extension' row correctly marks this as 'Reserved' and 'Blocked until every readiness gate passes.' However, the Isolation and secret posture column says 'Not allowed as a public surface today. It would require sandbox isolation, least privilege, and fail-closed recovery.' This phrasing could be interpreted as a future implementation plan rather than a firm boundary.
Impact: Security-critical boundary language should be unambiguous. Current phrasing leaves room for misinterpretation as a roadmap item rather than a hard 'not allowed, no commitment' stance.
Recommended action: Strengthen the language to 'Not allowed as a public surface today. Any future consideration would require sandbox isolation, least privilege, and fail-closed recovery — no implementation exists and no commitment to implement is made.'
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Read the Arbitrary third-party row, Isolation and secret posture column (lines 55-58); assess whether the phrasing leaves room for misinterpretation as a roadmap item.
Missing regression test: Documentation review; no automated test.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Read the Arbitrary third-party row, Isolation and secret posture column (lines 55-58); assess whether the phrasing leaves room for misinterpretation as a roadmap item.
Evidence: Lines 55-58 in the Candidate Surface Matrix table, Arbitrary third-party row, Isolation and secret posture column.

`PRA-7` Improvement — Built-in agent lifecycle integration row lacks cross-reference to credential isolation mechanisms

Location: docs/reference/candidate-surface-stability-security.mdx:35
Category: security
Problem: The 'Built-in agent lifecycle integration' row states 'Provider credentials stay on the host and route through `inference.local`.' This is accurate but doesn't explicitly reference the credential isolation mechanisms documented in enterprise-readiness.mdx (credential storage, redaction, memory secret scanner).
Impact: Readers of this reference document may not discover the detailed credential isolation controls without knowing to check enterprise-readiness.mdx.
Suggested action: Add a parenthetical cross-reference: '(see Credential Storage and Security Best Practices for credential isolation mechanisms)' or link to the relevant enterprise-readiness sections.
Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
Verification: Compare the Built-in agent lifecycle integration row's isolation posture (line 35-38) with enterprise-readiness.mdx sections on Credential Storage and Security Best Practices.
Missing regression test: Documentation cross-reference check; no automated test.
Done when: The local improvement is applied, or the PR notes why it should be deferred.
Evidence: Lines 35-38: 'Provider credentials stay on the host and route through `inference.local`.' No cross-reference to enterprise-readiness.mdx.

`PRA-8` Improvement — Readiness gates don't explicitly map applicability per execution class

Location: docs/reference/candidate-surface-stability-security.mdx:70
Category: acceptance
Problem: The Public-SDK Readiness Gates table lists 10 categories but the Candidate Surface Matrix has 7 surfaces with different execution classes (Data-only, Managed executable, Arbitrary executable). The document states 'A candidate public seam cannot move beyond candidate status until every category below has concrete evidence' but doesn't explicitly map which gates apply to which surfaces. Some gates (e.g., Provenance, Secrets) may not apply to Data-only surfaces.
Impact: Readers may incorrectly assume all 10 gates apply equally to all surfaces, or may miss that Data-only surfaces have different requirements than executable surfaces.
Suggested action: Add a note clarifying gate applicability per execution class, or add a column in the matrix indicating which readiness gates are relevant for each surface.
Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
Verification: Review the matrix surfaces against the 10 readiness gates; identify which gates are relevant for Data-only vs Managed executable vs Arbitrary executable surfaces.
Missing regression test: Documentation completeness review; no automated test.
Done when: The local improvement is applied, or the PR notes why it should be deferred.
Evidence: Public-SDK Readiness Gates table (lines 70-80) lists 10 gates with no mapping to execution classes. Matrix surfaces (lines 44-52) have 3 execution classes.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

github-actions · 2026-07-08T21:49:01Z

PR Review Advisor — Changes requested

Merge posture: Do not merge yet
Primary next action: Fix PRA-2: New decision reference is not wired into the published docs navigation; then add or justify PRA-T1.
Open items: 1 required · 2 warnings · 0 suggestions · 6 test follow-ups
Since last review: 2 prior items resolved · 1 still applies · 1 new item found

Action checklist

PRA-2 Fix: New decision reference is not wired into the published docs navigation in docs/index.yml:153
PRA-1 Resolve or justify: Source-of-truth review needed: Published decision record for extension terminology and SDK readiness
PRA-3 Resolve or justify: Naming guidance does not use the required `lifecycle contribution` term for NemoClaw seams in docs/reference/candidate-surface-stability-security.mdx:90
PRA-T1 Add or justify test follow-up: Acceptance clause
PRA-T2 Add or justify test follow-up: Acceptance clause
PRA-T3 Add or justify test follow-up: Acceptance clause
PRA-T4 Add or justify test follow-up: Acceptance clause
PRA-T5 Add or justify test follow-up: Acceptance clause
PRA-T6 Add or justify test follow-up: Published decision record for extension terminology and SDK readiness

Findings index

ID	Severity	Category	Location	Required action
`PRA-1`	Resolve/justify	architecture	—	Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
`PRA-2`	Required	acceptance	`docs/index.yml:153`	Add `Candidate Surface Stability and Security` to the intended `docs/index.yml` Reference sections, or add another durable in-repo publishing mechanism/cross-link that proves this page is included in the generated documentation for the intended agent variants.
`PRA-3`	Resolve/justify	acceptance	`docs/reference/candidate-surface-stability-security.mdx:90`	Either add the `lifecycle contribution` term to this page's Naming Guidance and matrix where proposed NemoClaw seams are discussed, or explicitly narrow this page's scope and link to the taxonomy decision once it lands so the required term is resolved in one published source.

🚨 Required before merge

Address these before merging unless a maintainer explicitly overrides the advisor with rationale.

`PRA-2` Required — New decision reference is not wired into the published docs navigation

Location: docs/index.yml:153
Category: acceptance
Problem: Issue docs(architecture): define extensibility terminology and SDK readiness gates #6229's outcome says to "Publish a decision record that removes plugin terminology ambiguity and defines measurable gates for any future public NemoClaw extension SDK." This PR adds `docs/reference/candidate-surface-stability-security.mdx`, but the inspected OpenClaw, Deep Agents, and Hermes `Reference` sections in `docs/index.yml` still list existing reference pages without this new page or slug. `docs/AGENTS.md` also says to update `docs/index.yml` when navigation, slugs, or page placement changes.
Impact: The decision record can exist in the repository while remaining absent from the published docs site, leaving the linked issue outcome unmet and making the security/readiness gates hard for users and maintainers to find or audit.
Required action: Add `Candidate Surface Stability and Security` to the intended `docs/index.yml` Reference sections, or add another durable in-repo publishing mechanism/cross-link that proves this page is included in the generated documentation for the intended agent variants.
Expected follow-up: Fix before merge or get explicit maintainer override.
Verification: Read `docs/index.yml` around each agent variant's `Reference` section and check for `candidate-surface-stability-security`; it is absent while other `docs/reference/*.mdx` pages are listed.
Missing regression test: Extend docs navigation validation to assert `reference/candidate-surface-stability-security.mdx` has a published route in each intended agent variant Reference section, or add this page to the guarded route set in `scripts/check-docs-published-routes.ts` so an unindexed reference page fails deterministically.
Done when: The required change is committed and verification passes: Read `docs/index.yml` around each agent variant's `Reference` section and check for `candidate-surface-stability-security`; it is absent while other `docs/reference/*.mdx` pages are listed.
Evidence: `docs/reference/candidate-surface-stability-security.mdx` is added with `content.type: "reference"`, but inspected `docs/index.yml` Reference contents for OpenClaw, Deep Agents, and Hermes do not include its page path or slug.

Review findings by urgency: 1 required fix, 2 items to resolve/justify, 0 in-scope improvements

⚠️ Resolve or justify before merge

Investigate these in the current review; either fix them, explain why they are not applicable, or document the accepted risk.

`PRA-1` Resolve/justify — Source-of-truth review needed: Published decision record for extension terminology and SDK readiness

Location: not file-specific
Category: architecture
Problem: The advisor marked localized patch analysis as needs_followup.
Impact: A localized workaround can preserve or hide an invalid state when the source boundary is unclear.
Recommended action: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Missing regression test: Add docs navigation validation that proves `reference/candidate-surface-stability-security.mdx` has a published route for the intended agent variants.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Evidence: The new reference file is added, but the inspected `docs/index.yml` Reference sections do not list it; this is covered by the blocker finding.

`PRA-3` Resolve/justify — Naming guidance does not use the required `lifecycle contribution` term for NemoClaw seams

Location: docs/reference/candidate-surface-stability-security.mdx:90
Category: acceptance
Problem: Issue docs(architecture): define extensibility terminology and SDK readiness gates #6229 has a deliverable requiring: "Explicit reservation of "plugin" for agent-native plugins or the scoped internal work already owned by VoiceClaw integration via existing messaging and provider contracts #5998/refactor(messaging): organize channels into plugin-style modules #6097; proposed NemoClaw seams use "lifecycle contribution" until a later decision says otherwise." The new page reserves `NemoClaw plugin SDK` and distinguishes NemoClaw-managed operations from agent-native plugins, but the Naming Guidance uses broader phrases like `NemoClaw-owned lifecycle and managed-package operations` and does not introduce `lifecycle contribution` as the term for proposed NemoClaw seams.
Impact: Readers can still see multiple terms for the same proposed NemoClaw seam, which weakens the issue's goal of removing plugin terminology ambiguity and may conflict with the sibling taxonomy work.
Recommended action: Either add the `lifecycle contribution` term to this page's Naming Guidance and matrix where proposed NemoClaw seams are discussed, or explicitly narrow this page's scope and link to the taxonomy decision once it lands so the required term is resolved in one published source.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Read `docs/reference/candidate-surface-stability-security.mdx` lines 90-95 and search within the file for `lifecycle contribution`; the exact required term is not present.
Missing regression test: Add a lightweight docs/source validation or fixture check for the docs(architecture): define extensibility terminology and SDK readiness gates #6229 decision record that asserts the published terminology includes `lifecycle contribution`, `managed agent package`, and agent-native plugin/package wording without calling NemoClaw seams a plugin SDK.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Read `docs/reference/candidate-surface-stability-security.mdx` lines 90-95 and search within the file for `lifecycle contribution`; the exact required term is not present.
Evidence: The page says to use `NemoClaw terminology for NemoClaw-owned lifecycle and managed-package operations` and `OpenClaw, Hermes, or Deep Agents Code terminology for agent-native plugins and packages`, but it never uses the required `lifecycle contribution` term.

💡 In-scope improvements

These are lower-risk, not throwaway. Prefer fixing them in this PR when they are local to changed code; defer only with rationale or a linked follow-up.

None.

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

PRA-T1 Acceptance clause — Outcome: Publish a decision record that removes plugin terminology ambiguity and defines measurable gates for any future public NemoClaw extension SDK. — add test evidence or identify existing coverage. The PR adds `docs/reference/candidate-surface-stability-security.mdx` with readiness gates and terminology boundaries, but the page is not present in the inspected `docs/index.yml` navigation, so publication is not proven.
PRA-T2 Acceptance clause — Questions to resolve: What terms distinguish NemoClaw lifecycle contributions, managed agent packages, and OpenClaw/Hermes/Deep Agents Code plugins? — add test evidence or identify existing coverage. The page distinguishes managed package operations from OpenClaw/Hermes/Deep Agents Code native plugins or packages, but it does not use the exact `lifecycle contribution` term for proposed NemoClaw seams.
PRA-T3 Acceptance clause — Questions to resolve: What evidence demonstrates that onboarding, rebuild, reconcile, removal, and recovery behave consistently across agents? — add test evidence or identify existing coverage. The page makes this a future readiness gate by requiring install, reconcile, remove, rebuild, backup, restore, and failure recovery tests, but this docs-only PR does not add behavior evidence.
PRA-T4 Acceptance clause — Deliverables: A glossary/ADR using the terminology established by the parent epic. — add test evidence or identify existing coverage. The PR adds a reference page with terminology and decision-boundary content, but it is not an ADR file and is not wired into published navigation.
PRA-T5 Acceptance clause — Deliverables: Explicit reservation of "plugin" for agent-native plugins or the scoped internal work already owned by VoiceClaw integration via existing messaging and provider contracts #5998/refactor(messaging): organize channels into plugin-style modules #6097; proposed NemoClaw seams use "lifecycle contribution" until a later decision says otherwise. — add test evidence or identify existing coverage. The page reserves `NemoClaw plugin SDK` and keeps OpenClaw/Hermes/Deep Agents Code plugin terminology agent-native, but it does not use `lifecycle contribution` for proposed NemoClaw seams.
PRA-T6 Published decision record for extension terminology and SDK readiness — Add docs navigation validation that proves `reference/candidate-surface-stability-security.mdx` has a published route for the intended agent variants.. The new reference file is added, but the inspected `docs/index.yml` Reference sections do not list it; this is covered by the blocker finding.

Since last review details

Current findings, using the urgency labels above:

`PRA-1` Resolve/justify — Source-of-truth review needed: Published decision record for extension terminology and SDK readiness

Location: not file-specific
Category: architecture
Problem: The advisor marked localized patch analysis as needs_followup.
Impact: A localized workaround can preserve or hide an invalid state when the source boundary is unclear.
Recommended action: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Missing regression test: Add docs navigation validation that proves `reference/candidate-surface-stability-security.mdx` has a published route for the intended agent variants.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Inspect the localized patch and source-of-truth review fields for a concrete invalid state, source boundary, source-fix constraint, regression test, and removal condition.
Evidence: The new reference file is added, but the inspected `docs/index.yml` Reference sections do not list it; this is covered by the blocker finding.

`PRA-2` Required — New decision reference is not wired into the published docs navigation

Location: docs/index.yml:153
Category: acceptance
Problem: Issue docs(architecture): define extensibility terminology and SDK readiness gates #6229's outcome says to "Publish a decision record that removes plugin terminology ambiguity and defines measurable gates for any future public NemoClaw extension SDK." This PR adds `docs/reference/candidate-surface-stability-security.mdx`, but the inspected OpenClaw, Deep Agents, and Hermes `Reference` sections in `docs/index.yml` still list existing reference pages without this new page or slug. `docs/AGENTS.md` also says to update `docs/index.yml` when navigation, slugs, or page placement changes.
Impact: The decision record can exist in the repository while remaining absent from the published docs site, leaving the linked issue outcome unmet and making the security/readiness gates hard for users and maintainers to find or audit.
Required action: Add `Candidate Surface Stability and Security` to the intended `docs/index.yml` Reference sections, or add another durable in-repo publishing mechanism/cross-link that proves this page is included in the generated documentation for the intended agent variants.
Expected follow-up: Fix before merge or get explicit maintainer override.
Verification: Read `docs/index.yml` around each agent variant's `Reference` section and check for `candidate-surface-stability-security`; it is absent while other `docs/reference/*.mdx` pages are listed.
Missing regression test: Extend docs navigation validation to assert `reference/candidate-surface-stability-security.mdx` has a published route in each intended agent variant Reference section, or add this page to the guarded route set in `scripts/check-docs-published-routes.ts` so an unindexed reference page fails deterministically.
Done when: The required change is committed and verification passes: Read `docs/index.yml` around each agent variant's `Reference` section and check for `candidate-surface-stability-security`; it is absent while other `docs/reference/*.mdx` pages are listed.
Evidence: `docs/reference/candidate-surface-stability-security.mdx` is added with `content.type: "reference"`, but inspected `docs/index.yml` Reference contents for OpenClaw, Deep Agents, and Hermes do not include its page path or slug.

`PRA-3` Resolve/justify — Naming guidance does not use the required `lifecycle contribution` term for NemoClaw seams

Location: docs/reference/candidate-surface-stability-security.mdx:90
Category: acceptance
Problem: Issue docs(architecture): define extensibility terminology and SDK readiness gates #6229 has a deliverable requiring: "Explicit reservation of "plugin" for agent-native plugins or the scoped internal work already owned by VoiceClaw integration via existing messaging and provider contracts #5998/refactor(messaging): organize channels into plugin-style modules #6097; proposed NemoClaw seams use "lifecycle contribution" until a later decision says otherwise." The new page reserves `NemoClaw plugin SDK` and distinguishes NemoClaw-managed operations from agent-native plugins, but the Naming Guidance uses broader phrases like `NemoClaw-owned lifecycle and managed-package operations` and does not introduce `lifecycle contribution` as the term for proposed NemoClaw seams.
Impact: Readers can still see multiple terms for the same proposed NemoClaw seam, which weakens the issue's goal of removing plugin terminology ambiguity and may conflict with the sibling taxonomy work.
Recommended action: Either add the `lifecycle contribution` term to this page's Naming Guidance and matrix where proposed NemoClaw seams are discussed, or explicitly narrow this page's scope and link to the taxonomy decision once it lands so the required term is resolved in one published source.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Read `docs/reference/candidate-surface-stability-security.mdx` lines 90-95 and search within the file for `lifecycle contribution`; the exact required term is not present.
Missing regression test: Add a lightweight docs/source validation or fixture check for the docs(architecture): define extensibility terminology and SDK readiness gates #6229 decision record that asserts the published terminology includes `lifecycle contribution`, `managed agent package`, and agent-native plugin/package wording without calling NemoClaw seams a plugin SDK.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Read `docs/reference/candidate-surface-stability-security.mdx` lines 90-95 and search within the file for `lifecycle contribution`; the exact required term is not present.
Evidence: The page says to use `NemoClaw terminology for NemoClaw-owned lifecycle and managed-package operations` and `OpenClaw, Hermes, or Deep Agents Code terminology for agent-native plugins and packages`, but it never uses the required `lifecycle contribution` term.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>

apurvvkumaria · 2026-07-08T23:01:05Z

Superseded by #6508, which consolidates this readiness work with the complementary taxonomy draft into one publishable decision record. Julie Yaunches is credited as co-author on the replacement commit. Closing this draft so #6229 has one active review surface.

## Summary This PR consolidates the complementary work from #6498 and #6499 into one published decision record for NemoClaw extension terminology and future SDK readiness. It preserves Julie Yaunches's original authorship, removes conflicting issue classifications, and avoids implying that a public NemoClaw plugin SDK exists today. ## Related Issue Closes #6229. ## Changes - Define lifecycle contribution, managed agent package, agent-native plugin, candidate public seam, and the reserved future `NemoClaw plugin SDK` terminology. - Document execution boundaries, a stability and security matrix, measurable readiness gates, and non-overlapping ownership for #5998, #6097, #3915, #6201, and #6207. - Publish the decision record in the OpenClaw, Hermes, and Deep Agents Code reference navigation. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [x] 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: - [x] Tests not applicable — justification: This is a documentation-only architecture decision with no runtime behavior. - [x] 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: ## Verification  - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Tests are not applicable; `npm run docs` passed with zero errors. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — result: The command passed with zero errors; Fern reported the unauthenticated redirects check and the existing light-theme accent contrast as unrelated warnings. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [x] New doc pages include SPDX header and frontmatter (new pages only) ---  Signed-off-by: Apurv Kumaria <akumaria@nvidia.com>  ## Summary by CodeRabbit * **New Features** * Added a new reference page covering extension and SDK readiness concepts, including terminology, trust boundaries, and readiness criteria. * Expanded the documentation navigation so the new reference article appears across all agent variants. * **Documentation** * Clarified current platform commitments and non-commitments around SDKs, registries, marketplaces, compatibility, and support expectations. * Added guidance for naming and describing future extension-related capabilities.  --------- Signed-off-by: Apurv Kumaria <akumaria@nvidia.com> Co-authored-by: Julie Yaunches <jyaunches@nvidia.com>

## Summary This PR consolidates the complementary work from NVIDIA#6498 and NVIDIA#6499 into one published decision record for NemoClaw extension terminology and future SDK readiness. It preserves Julie Yaunches's original authorship, removes conflicting issue classifications, and avoids implying that a public NemoClaw plugin SDK exists today. ## Related Issue Closes NVIDIA#6229. ## Changes - Define lifecycle contribution, managed agent package, agent-native plugin, candidate public seam, and the reserved future `NemoClaw plugin SDK` terminology. - Document execution boundaries, a stability and security matrix, measurable readiness gates, and non-overlapping ownership for NVIDIA#5998, NVIDIA#6097, NVIDIA#3915, NVIDIA#6201, and NVIDIA#6207. - Publish the decision record in the OpenClaw, Hermes, and Deep Agents Code reference navigation. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [x] 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: - [x] Tests not applicable — justification: This is a documentation-only architecture decision with no runtime behavior. - [x] 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: ## Verification  - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Tests are not applicable; `npm run docs` passed with zero errors. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — result: The command passed with zero errors; Fern reported the unauthenticated redirects check and the existing light-theme accent contrast as unrelated warnings. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [x] New doc pages include SPDX header and frontmatter (new pages only) ---  Signed-off-by: Apurv Kumaria <akumaria@nvidia.com>  ## Summary by CodeRabbit * **New Features** * Added a new reference page covering extension and SDK readiness concepts, including terminology, trust boundaries, and readiness criteria. * Expanded the documentation navigation so the new reference article appears across all agent variants. * **Documentation** * Clarified current platform commitments and non-commitments around SDKs, registries, marketplaces, compatibility, and support expectations. * Added guidance for naming and describing future extension-related capabilities.  --------- Signed-off-by: Apurv Kumaria <akumaria@nvidia.com> Co-authored-by: Julie Yaunches <jyaunches@nvidia.com>

jyaunches added 2 commits July 8, 2026 20:14

docs(reference): add candidate surface readiness matrix

5cc1c19

Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>

docs: document extension readiness gates

942451b

Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>

github-actions Bot mentioned this pull request Jul 8, 2026

docs: define lifecycle and plugin taxonomy #6498

Closed

docs: cite issue evidence for readiness classifications

a6c5683

Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>

apurvvkumaria added the v0.0.79 label Jul 8, 2026

apurvvkumaria self-assigned this Jul 8, 2026

apurvvkumaria mentioned this pull request Jul 8, 2026

docs: define extension taxonomy and SDK readiness #6508

Merged

21 tasks

apurvvkumaria closed this Jul 8, 2026

Uh oh!

Conversation

jyaunches commented Jul 8, 2026

Summary

Validation

Sibling PR

Uh oh!

copy-pr-bot Bot commented Jul 8, 2026

Uh oh!

coderabbitai Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Target Recommendation

E2E Target Advisor

Required E2E targets

Optional E2E targets

Relevant changed files

Uh oh!

github-actions Bot commented Jul 8, 2026

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor (Nemotron Ultra) — Changes requested

Action checklist

Findings index

⚠️ Resolve or justify before merge

PRA-1 Resolve/justify — Source-of-truth review needed: Issue #6201 classification evidence

PRA-2 Resolve/justify — Source-of-truth review needed: Issue #6207 classification evidence

PRA-3 Resolve/justify — Source-of-truth review needed: Sibling PR #6498 cross-reference

PRA-4 Resolve/justify — Issue #6201 and #6207 classifications cite unverified broker-provided evidence

PRA-5 Resolve/justify — Missing cross-reference to sibling PR #6498 taxonomy document

PRA-6 Resolve/justify — Arbitrary third-party executable extension row phrasing could imply future implementation plan

💡 In-scope improvements

PRA-7 Improvement — Built-in agent lifecycle integration row lacks cross-reference to credential isolation mechanisms

PRA-8 Improvement — Readiness gates don't explicitly map applicability per execution class

PRA-1 Resolve/justify — Source-of-truth review needed: Issue #6201 classification evidence

PRA-2 Resolve/justify — Source-of-truth review needed: Issue #6207 classification evidence

PRA-3 Resolve/justify — Source-of-truth review needed: Sibling PR #6498 cross-reference

PRA-4 Resolve/justify — Issue #6201 and #6207 classifications cite unverified broker-provided evidence

PRA-5 Resolve/justify — Missing cross-reference to sibling PR #6498 taxonomy document

PRA-6 Resolve/justify — Arbitrary third-party executable extension row phrasing could imply future implementation plan

PRA-7 Improvement — Built-in agent lifecycle integration row lacks cross-reference to credential isolation mechanisms

PRA-8 Improvement — Readiness gates don't explicitly map applicability per execution class

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor — Changes requested

Action checklist

Findings index

🚨 Required before merge

PRA-2 Required — New decision reference is not wired into the published docs navigation

⚠️ Resolve or justify before merge

PRA-1 Resolve/justify — Source-of-truth review needed: Published decision record for extension terminology and SDK readiness

PRA-3 Resolve/justify — Naming guidance does not use the required `lifecycle contribution` term for NemoClaw seams

💡 In-scope improvements

PRA-1 Resolve/justify — Source-of-truth review needed: Published decision record for extension terminology and SDK readiness

PRA-2 Required — New decision reference is not wired into the published docs navigation

PRA-3 Resolve/justify — Naming guidance does not use the required `lifecycle contribution` term for NemoClaw seams

Uh oh!

apurvvkumaria commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai Bot commented Jul 8, 2026 •

edited

Loading

github-actions Bot commented Jul 8, 2026 •

edited

Loading

github-actions Bot commented Jul 8, 2026 •

edited

Loading

github-actions Bot commented Jul 8, 2026 •

edited

Loading

`PRA-1` Resolve/justify — Source-of-truth review needed: Issue #6201 classification evidence

`PRA-2` Resolve/justify — Source-of-truth review needed: Issue #6207 classification evidence

`PRA-3` Resolve/justify — Source-of-truth review needed: Sibling PR #6498 cross-reference

`PRA-4` Resolve/justify — Issue #6201 and #6207 classifications cite unverified broker-provided evidence

`PRA-5` Resolve/justify — Missing cross-reference to sibling PR #6498 taxonomy document

`PRA-6` Resolve/justify — Arbitrary third-party executable extension row phrasing could imply future implementation plan

`PRA-7` Improvement — Built-in agent lifecycle integration row lacks cross-reference to credential isolation mechanisms

`PRA-8` Improvement — Readiness gates don't explicitly map applicability per execution class

`PRA-1` Resolve/justify — Source-of-truth review needed: Issue #6201 classification evidence

`PRA-2` Resolve/justify — Source-of-truth review needed: Issue #6207 classification evidence

`PRA-3` Resolve/justify — Source-of-truth review needed: Sibling PR #6498 cross-reference

`PRA-4` Resolve/justify — Issue #6201 and #6207 classifications cite unverified broker-provided evidence

`PRA-5` Resolve/justify — Missing cross-reference to sibling PR #6498 taxonomy document

`PRA-6` Resolve/justify — Arbitrary third-party executable extension row phrasing could imply future implementation plan

`PRA-7` Improvement — Built-in agent lifecycle integration row lacks cross-reference to credential isolation mechanisms

`PRA-8` Improvement — Readiness gates don't explicitly map applicability per execution class

github-actions Bot commented Jul 8, 2026 •

edited

Loading

`PRA-2` Required — New decision reference is not wired into the published docs navigation

`PRA-1` Resolve/justify — Source-of-truth review needed: Published decision record for extension terminology and SDK readiness

`PRA-3` Resolve/justify — Naming guidance does not use the required `lifecycle contribution` term for NemoClaw seams

`PRA-1` Resolve/justify — Source-of-truth review needed: Published decision record for extension terminology and SDK readiness

`PRA-2` Required — New decision reference is not wired into the published docs navigation

`PRA-3` Resolve/justify — Naming guidance does not use the required `lifecycle contribution` term for NemoClaw seams