chore: publish rSkill OpenRAL/rskill-playbook-stage_for_manipulation v0.1.0

PLAYBOOK.md

@@ -0,0 +1,54 @@
+# stage-for-manipulation
+
+> **Hand-authored decision procedure (SOP).** Unlike the generated `SKILL.md`
+> discovery view, this file is the *content the S2 Reasoner reads and follows*.
+> It is injected into the reasoner's system prompt when this playbook is
+> installed. The `rskill.yaml` `playbook.body_uri` points here.
+
+## Trigger
+A chosen manipulation rSkill declares a `starting_pose` (pre-grasp) that the
+robot has **not** yet reached (e.g. a pick policy expects the gripper hovering
+above the black bowl, but the arm is parked at home). Dispatching the
+manipulation from a bad initial pose is a common, avoidable grasp failure.
+
+## Preconditions
+- The target manipulation skill and its `starting_pose` are known (read from the
+  skill's manifest / contract).
+- An arm-motion **approach** skill is installed — the collision-aware MoveGroup
+  plan-arm rSkill (`openral-moveit-plan-arm`) — and/or a navigate skill
+  for mobile bases.
+
+## Steps
+1. **Read the pre-grasp.** Read the target manipulation skill's `starting_pose`
+   (the declared pre-grasp the policy expects to begin from).
+2. **Base staging (mobile only).** If the robot has a mobile base, `resolve_place`
+   a stand pose that puts the target inside the arm's workspace, then
+   `execute_rskill(NAVIGATE, goal=place)`. Skip on a fixed-base arm.
+3. **Approach to pre-grasp.** `execute_rskill` the collision-aware **approach**
+   skill (the MoveGroup plan-arm rSkill) retargeted at `starting_pose`,
+   so the arm moves to the pre-grasp under MoveIt. **Never** a hand-rolled IK.
+4. **Verify.** `query_scene` to confirm the pre-grasp ("is the gripper positioned
+   above the black bowl?"). Treat an unconfirmed pose as not staged.
+5. **Hand back.** Only once verified, return control so the manipulation policy
+   runs from a good initial pose.
+
+## Verify (done predicate)
+The gripper (and base, for mobile embodiments) are at the declared `starting_pose`
+pre-grasp, **confirmed by `query_scene`**. An unverified pose is a failure, not a
+success — do not hand control to the manipulation policy.
+
+## Fallbacks
+- The approach skill cannot plan a collision-free path to `starting_pose`
+  (obstructed / unreachable pre-grasp) → `emit_prompt` that staging failed, so the
+  reasoner replans or hands off rather than dispatching a manipulation from a bad
+  pose. This is the terminal human-handoff rung of the replanning ladder.
+- Pairs with the **preflight-reach** playbook (which checks reachability before a
+  skill is even chosen); this one stages and verifies the chosen skill's pose.
+- **Never** loop past `max_steps`. Every approach attempt and its outcome are on
+  the OTel trace, so staging is replayable.
+
+## Safety
+This playbook only *decides* and *sequences*. Every motion it triggers is an
+`execute_rskill` → Action chunk that still crosses the C++ safety kernel; a bad
+`starting_pose` yields a plan the kernel still vetoes, never a relaxed check
+(CLAUDE.md §1.1).

SKILL.md

@@ -0,0 +1,64 @@
+---
+name: stage-for-manipulation
+description: >-
+  S2 decision-procedure playbook (weightless). Capabilities: plan on manipulation target. S2 decision procedure: move the robot into a manipulation skill's declared pre-grasp / starting pose (and verify it) before the manipulation policy runs, reducing grasp failures from bad initial poses. Composes resolve_place, execute_rskill, query_scene and memory_write over a collision-aware approach skill. Discovery view of an OpenRAL rSkill — NOT directly runnable by an agent harness; it runs via rSkill.from_pretrained + the robot HAL.
+metadata:
+  openral_rskill: true            # generated discovery view of an rSkill
+  schema_version: 0.1
+  rskill_id: OpenRAL/rskill-playbook-stage_for_manipulation
+  manifest: ./rskill.yaml
+  role: s2
+  kind: playbook
+  embodiment_tags: [any]
+  actions: [plan]
+  objects: [manipulation target]
+  scenes: [kitchen, indoor]
+  chunk_size: 1
+  latency_budget: {per_chunk_ms: 5000.0}
+  license_code: Apache-2.0
+  license_weights: apache-2.0
+  paper_url: https://github.com/OpenRAL/openral/blob/master/docs/decisions.md
+---
+
+# stage-for-manipulation — rSkill discovery view
+
+> **Generated view, not a hand-written skill.** This `SKILL.md` is a discovery-only
+> mirror of [`rskill.yaml`](./rskill.yaml), produced by `tools/generate_rskill_skillmd.py`.
+> It lets tools that read the standard agent-skill format find and reason about this
+> OpenRAL rSkill. The `rskill.yaml` manifest is the single source of truth
+> (CLAUDE.md §1.3). Do not edit by hand — edit the manifest and regenerate.
+
+## What it is
+
+An OpenRAL **decision-procedure playbook (weightless)** (`role: s2`, `kind: playbook`). S2 decision procedure: move the robot into a manipulation skill's declared pre-grasp / starting pose (and verify it) before the manipulation policy runs, reducing grasp failures from bad initial poses. Composes resolve_place, execute_rskill, query_scene and memory_write over a collision-aware approach skill.
+
+## Capabilities
+
+- **Verbs:** plan
+- **Objects:** manipulation target
+- **Scenes:** kitchen · indoor
+- **Embodiments:** any
+
+## Why this is discovery-only
+
+An agent skill is natural-language instructions loaded into an LLM's context. An rSkill
+is an executable artifact: it carries a typed capability/embodiment contract
+a runtime, and a license/provenance gate — none of which fit in freeform markdown. So an
+agent can use this view to *select* the right skill, but cannot *execute* it by loading
+this file. Execution always goes through the OpenRAL loader and the robot HAL.
+
+## License
+
+- **Code:** Apache-2.0. This is a weightless rSkill (the manifest *is* the artifact).
+
+## How to actually run it (not via an agent harness)
+
+```python
+from openral_rskill import rSkill
+
+skill = rSkill.from_pretrained("OpenRAL/rskill-playbook-stage_for_manipulation")
+# the loader validates embodiment / sensors / runtime / quantization against the target
+# RobotDescription and enforces the weight-license gate before any weights load.
+```
+
+See [`rskill.yaml`](./rskill.yaml) for the authoritative, validated manifest.

rskill.yaml

@@ -0,0 +1,74 @@
+# rSkill manifest — stage-for-manipulation (kind: playbook)
+#
+# A symbolic S2 *decision procedure* the Reasoner reads (not a neural policy):
+# move the robot into a manipulation skill's declared pre-grasp / starting pose
+# and verify it before the manipulation policy runs. Composes existing read-only +
+# actuating reasoner tools; carries no weights and never actuates directly (every
+# motion it triggers is an ExecuteRskill → Action chunk → C++ safety kernel).
+
+schema_version: "0.1"
+name: "OpenRAL/rskill-playbook-stage_for_manipulation"
+version: "0.1.0"
+license: "apache-2.0"
+role: "s2"
+kind: "playbook"
+
+# Embodiment-agnostic — a playbook is gated by capabilities_required, not by a
+# specific embodiment. Declared explicitly with the "any" wildcard (never an
+# empty list, which the manifest validator rejects).
+embodiment_tags: ["any"]
+
+# Real RobotCapabilities flag: verifying the pre-grasp pose requires a camera. The
+# loader's capability gate (openral_rskill.loader.check_capability_flags) raises
+# ROSCapabilityMismatch on any robot that does not declare `has_vision: true`,
+# or on an unknown flag name — so only real capability fields belong here. The
+# arm-motion / navigation the SOP performs is gated at runtime by the composed
+# tools' own requirements, not by this playbook's flags.
+capabilities_required:
+  has_vision: true
+
+# A playbook actuates nothing itself.
+actuators_required: []
+
+# Required field; pinned to 1 like the perception kinds (no Action rows).
+chunk_size: 1
+
+# S2 planning budget (~0.2 Hz tick). CI enforces on the reference host.
+latency_budget:
+  per_chunk_ms: 5000.0
+
+description: >
+  S2 decision procedure: move the robot into a manipulation skill's declared
+  pre-grasp / starting pose (and verify it) before the manipulation policy runs,
+  reducing grasp failures from bad initial poses. Composes resolve_place,
+  execute_rskill, query_scene and memory_write over a collision-aware approach
+  skill.
+
+# RSkillAction.PLAN — registry/discovery metadata only (a playbook is role s2,
+# never an ExecuteSkill dispatch verb).
+actions:
+  - "plan"
+
+objects:
+  - "manipulation target"
+scenes:
+  - "kitchen"
+  - "indoor"
+
+# Provenance citation (a playbook has no weights / upstream model repo, so a
+# citation is still required for publish-readiness — CLAUDE.md §6.4). The
+# The authoring decision record is private (OpenRAL/management); this points at
+# the public stub that explains where it lives.
+paper_url: "https://github.com/OpenRAL/openral/blob/master/docs/decisions.md"
+
+# The playbook decision-procedure contract.
+playbook:
+  trigger: "a manipulation skill declares a starting_pose or pre-grasp that the robot is not currently in"
+  body_uri: "./PLAYBOOK.md"
+  composes_tools:
+    - "resolve_place"
+    - "execute_rskill"
+    - "query_scene"
+    - "memory_write"
+  done_predicate: "the robot is in the skill's declared pre-grasp / starting pose, verified, and ready to dispatch the manipulation"
+  max_steps: 8