[bbingz]

Summary

• Adds a one-line semantics map for every static runtime capability flag (RUNTIME_CAPABILITY_DOCS).
• orca status --json now includes runtime.capabilityDocs for the advertised flags (client-side enrichment; no wire change).
• orca status --help notes describe how to use capabilities + capabilityDocs.
• Tests lock full catalog coverage and JSON enrichment.

Why

Closes #13202 — status advertised ~31 bare flag names with no agent-readable semantics.

Test plan

• Unit: every RUNTIME_CAPABILITIES entry has a doc line
• Unit: status --json attaches capabilityDocs for known flags only
• Manual: orca status --json | jq '.result.runtime.capabilityDocs'

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds a runtime capability documentation map and lookup utilities. Tests verify documentation completeness, conditional capabilities, and filtering of unknown flags. JSON status output now includes runtime.capabilityDocs while preserving capability identifiers. The status specification documents capability fields and unsupported flags. Non-JSON status output remains unchanged.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: 🔵 Low · up to b6c0e

A future runtime capability could be added without agent-readable documentation, weakening the advertised JSON contract. Add the completeness assertion before merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the main change, motivation, linked issue, and test coverage. It does not follow the required template and omits the ELI5, Visual Proof, AI Disclosure, Review, Agent skill ups…	Add all required template sections. Include an ELI5 summary, explicit What Changed and Why sections, the linked issue in the required format, Visual Proof with N/A and a reason if applicable, AI Disclosure, Review, Agent skill upstream boun…

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: documenting runtime capability flags in the CLI status JSON output.
Linked Issues check	✅ Passed	The changes satisfy #13202. RUNTIME_CAPABILITY_DOCS provides one-line semantics for the static capability catalog. describeRuntimeCapabilities adds documentation only for advertised known flags. `…
Out of Scope Changes check	✅ Passed	The changed files stay within #13202. The shared catalog and lookup functions implement the capability reference. The status handler, help notes, and tests expose and verify that reference. No unrelat…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 4…

Full details: Description check

Explanation

The description explains the main change, motivation, linked issue, and test coverage. It does not follow the required template and omits the ELI5, Visual Proof, AI Disclosure, Review, Agent skill upstream boundary, Notes, and Checklist sections. It also does not include the required manual-testing checklist details.

Resolution

Add all required template sections. Include an ELI5 summary, explicit What Changed and Why sections, the linked issue in the required format, Visual Proof with N/A and a reason if applicable, AI Disclosure, Review, Agent skill upstream boundary, Notes, and the complete Checklist. Document manual testing and platform coverage.

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (1)

src/shared/runtime-capability-docs.ts (1)

33-36: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reduce these implementation comments to one concise line each.

Both comments explain nearby code across several lines. Keep only the non-obvious rationale.

• src/shared/runtime-capability-docs.ts#L33-L36: State that known advertised capabilities have descriptions and unknown flags are omitted.
• src/cli/handlers/core.ts#L143-L145: State that JSON status receives local enrichment without a wire change.

As per coding guidelines, “Comments must be concise, limited to non-obvious information, and preferably one line.”

Source: Coding guidelines

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3ba4893a-26ff-40e4-a58d-f38cef097ccb

📥 Commits

Reviewing files that changed from the base of the PR and between 6da7b8e and 7b1f9eb60550f78e214fd3562915d8c379745f58.

📒 Files selected for processing (5)

• src/cli/handlers/core.test.ts
• src/cli/handlers/core.ts
• src/cli/specs/core.ts
• src/shared/runtime-capability-docs.test.ts
• src/shared/runtime-capability-docs.ts

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 8f4cb4da-9585-43f2-8edf-de59b0fd154b

📥 Commits

Reviewing files that changed from the base of the PR and between 7b1f9eb60550f78e214fd3562915d8c379745f58 and b6c0e82.

📒 Files selected for processing (4)

• src/cli/handlers/core.test.ts
• src/cli/handlers/core.ts
• src/cli/specs/core.ts
• src/shared/runtime-capability-docs.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/cli/specs/core.ts

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

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Require complete catalog coverage.

The current assertions pass when one or more runtime capabilities lack documentation. Assert that undocumented is empty. This makes a missing RUNTIME_CAPABILITY_DOCS entry fail the test.

Proposed fix

     const undocumented = listUndocumentedRuntimeCapabilities()
+    expect(undocumented).toEqual([])
     expect(Array.isArray(undocumented)).toBe(true)

Based on learnings: fixed registries must have complete coverage.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const undocumented = listUndocumentedRuntimeCapabilities()
	expect(Array.isArray(undocumented)).toBe(true)
	const undocumented = listUndocumentedRuntimeCapabilities()
	expect(undocumented).toEqual([])
	expect(Array.isArray(undocumented)).toBe(true)

Source: Learnings

[bbingz]

Closing: #30641 split the capability constants into per-area files, so this catalog would need a re-port into those files. #13202 stays open for anyone picking up the semantics docs.