IT1 (#210): tool-descriptor axis on the kernel ActionCatalog + failing completeness gate test

[George-RD]

What & why

IT1 for spec #209 (capability-derived tool catalogs; Immune-system lane; promises Immune system + Permissions; users Bell, Lyra). This lands the kernel-owned tool-descriptor axis the later projection (IT2) and wire seam (IT3) will consume — nothing shell-spoofable, nothing carried on the TaskGrant.

• ToolDescriptor (crates/openspine-schemas/src/action): LLM-facing name, one-line description, parameter JSON Schema (serde_json::Value), and presentation flags approval_required / selection_token_required. Derives PartialEq/Serialize/Deserialize with #[serde(deny_unknown_fields)] and a manual impl Eq so ActionCatalog keeps its derived Eq.
• ActionCatalog axis: tool_descriptors map + with_tool_descriptors builder + tool_descriptor_for accessor (+ tool_descriptor_count), mirroring egress_declarations exactly.
• Curated data: one descriptor per currently-dispatchable action id (the 15 ActionHandlerRegistry::default_registrations() ids) in a new kernel sibling action_catalog_tool_descriptors.rs, wired into canonical_catalog(). The intentionally-unwired PRD ids get none.
• Fail-closed completeness gate test: iterates the handler registry and panics naming any dispatchable action lacking a descriptor (a capability gap a human must consciously accept, spec owner note A — a failing test, not a log line). Also pins the descriptor cardinality to 15 and asserts each selection_token_required mirrors requires_selection_token(id).is_some(). Demonstrated: removing a descriptor makes the test fail with dispatchable action <id> lacks a tool descriptor.

approval_required is a curated presentation flag by reviewed judgment (spec #209 design choice 3): true only for worker.commission (mints a delegated grant) and openspine.overlay.restore (mutates the live governed set); all others false.

No change to compose(), gate() decision logic, TaskViewBody, or the shell.

Deviation

ActionEgressDeclaration was moved into a new sibling action/catalog_metadata.rs alongside ToolDescriptor: action.rs was at 499/500 lines and the cap left no room. Preferred a split over the allow-large-module hatch (per AGENTS.md); both are per-action catalog-metadata value types, so they group naturally. All public paths (openspine_schemas::action::ActionEgressDeclaration) preserved via pub use — no caller changes.

Verification

• cargo test -p openspine-schemas -p openspine-kernel green.
• scripts/check.sh green (fmt, clippy -D warnings, workspace tests + shell E2E, file-size cap, claims, omp ceremony, openspec validate --all --strict: 45/45).

Implementation-notes summary

• Added kernel-owned ToolDescriptor type + tool_descriptors axis on ActionCatalog (builder + accessor + count), mirroring egress_declarations.
• Split catalog-metadata value types into action/catalog_metadata.rs to stay under the 500-line cap; all public paths preserved via pub use.
• Populated one curated descriptor per dispatchable id (15) in a new kernel sibling action_catalog_tool_descriptors.rs, wired into canonical_catalog().
• Added a fail-closed gate completeness test (panics on a missing descriptor; pins cardinality 15; asserts selection-token flag mirrors the catalog).
• cargo test -p openspine-schemas -p openspine-kernel and scripts/check.sh both green; no change to compose(), gate(), TaskViewBody, or the shell.

Closes #210

---

Summary by cubic

Adds a kernel-owned ToolDescriptor axis to the ActionCatalog and wires curated descriptors for all 15 dispatchable actions. This enables the capability‑derived tool catalog from spec #209 and fail‑closes missing or inconsistent descriptors without changing runtime behavior.

• Schema and API: new ToolDescriptor in openspine-schemas::action::catalog_metadata (name, description, parameters_schema, approval_required, selection_token_required, #[serde(deny_unknown_fields)]), plus ActionCatalog support (tool_descriptors map, with_tool_descriptors, tool_descriptor_for, tool_descriptor_count).
• Data and wiring: curated descriptors in openspine-kernel/src/action_catalog_tool_descriptors.rs for the 15 currently dispatchable IDs, integrated via canonical_catalog(); approval_required = true only for worker.commission and openspine.overlay.restore.
• Guardrails: a completeness test fails if any dispatchable action lacks a descriptor, if selection_token_required drifts from requires_selection_token, or if the descriptor count differs from 15.
• Organization: moved ActionEgressDeclaration into openspine-schemas::action::catalog_metadata; re‑export preserves openspine_schemas::action::ActionEgressDeclaration for callers.
• Migration: when adding a dispatchable action, add its descriptor to action_catalog_tool_descriptors.rs and update the pinned count in the test. No changes to compose(), gate decisions, TaskViewBody, or the shell.

^{Written for commit 0233a70. Summary will update on new commits.}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

@George-RD, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 21 minutes

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d574c416-7b10-4a77-9edd-dcb7cbd1973a

📥 Commits

Reviewing files that changed from the base of the PR and between b5d0f68 and 0233a70.

📒 Files selected for processing (6)

• crates/openspine-kernel/src/action_catalog.rs
• crates/openspine-kernel/src/action_catalog_tests.rs
• crates/openspine-kernel/src/action_catalog_tool_descriptors.rs
• crates/openspine-schemas/src/action.rs
• crates/openspine-schemas/src/action/catalog_metadata.rs
• crates/openspine-schemas/src/action/tests.rs

---

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