Collision checking: keep-out shapes, enablement gates, MoveIt-style invalidation

.github/workflows/tests.yml

@@ -24,6 +24,9 @@ jobs:
         shell: bash
         run: |
           python -m pip install --upgrade pip
+          # ruckig 0.17.3 sdist doesn't build under scikit-build-core 1.0;
+          # pre-install the fixed commit until a release lands (pantor/ruckig#262).
+          pip install "ruckig @ git+https://github.com/pantor/ruckig@2249d57ffaa19ecdadeaab62daf97857813629ff"
           pip install -e ".[dev]"
           # Override the pinned waldoctl with the matching feature branch if one
           # exists, AFTER ".[dev]" (and with --force-reinstall) so the pinned tag
@@ -36,31 +39,79 @@ jobs:
           fi
       - name: Run pre-commit
         uses: pre-commit/action@v3.0.1
+
   test:
     name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 30
+    timeout-minutes: 45
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ['3.11', '3.12', '3.13', '3.14']
 
+    defaults:
+      run:
+        shell: bash -l {0}
+
     steps:
       - name: Checkout repository (with submodules)
         uses: actions/checkout@v4
 
-      - name: Setup Python
+      - name: Detect matching pinokin branch
+        id: pinokin
+        shell: bash
+        run: |
+          BRANCH="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
+          if git ls-remote --heads https://github.com/Jepson2k/pinokin.git "$BRANCH" 2>/dev/null | grep -q .; then
+            echo "matching=true" >> "$GITHUB_OUTPUT"
+            echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
+          else
+            echo "matching=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # ----------------------------------------------------------------------
+      # Path A: matching pinokin branch -> conda env (provides libpinocchio +
+      # libcoal headers/libs) so pinokin can be built from source. We install
+      # PAROL6 first (which pulls in the pinned pinokin v0.1.6 wheel) and
+      # then override pinokin with the source-built wheel from the matching
+      # branch. This is the only way to exercise unreleased pinokin features
+      # before a release lands.
+      # ----------------------------------------------------------------------
+      - name: Setup Miniforge (matching pinokin branch)
+        if: steps.pinokin.outputs.matching == 'true'
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          miniforge-version: latest
+          python-version: ${{ matrix.python-version }}
+          conda-remove-defaults: true
+          activate-environment: parol6-test
+
+      - name: Clone matching pinokin branch
+        if: steps.pinokin.outputs.matching == 'true'
+        run: |
+          git clone --depth=1 --branch="${{ steps.pinokin.outputs.branch }}" https://github.com/Jepson2k/pinokin.git pinokin-src
+          conda env update -n parol6-test -f pinokin-src/environment.yml
+
+      # ----------------------------------------------------------------------
+      # Path B: no matching pinokin branch -> plain pip with the pinned
+      # release wheel. Anything in PAROL6 that requires a newer pinokin
+      # feature will fail loudly here (intended).
+      # ----------------------------------------------------------------------
+      - name: Setup Python (pinned pinokin)
+        if: steps.pinokin.outputs.matching != 'true'
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
           cache-dependency-path: pyproject.toml
 
       - name: Install package
-        shell: bash
         run: |
           python -m pip install --upgrade pip
+          # ruckig 0.17.3 sdist doesn't build under scikit-build-core 1.0;
+          # pre-install the fixed commit until a release lands (pantor/ruckig#262).
+          pip install "ruckig @ git+https://github.com/pantor/ruckig@2249d57ffaa19ecdadeaab62daf97857813629ff"
           pip install -e ".[dev]" pytest-timeout
           # Override the pinned waldoctl with the matching feature branch if one
           # exists, AFTER ".[dev]" (and with --force-reinstall) so the pinned tag
@@ -72,6 +123,16 @@ jobs:
             pip install --force-reinstall "waldoctl @ git+https://github.com/Jepson2k/waldoctl.git@${BRANCH}"
           fi
 
+      # Override the pinned pinokin v0.1.6 wheel with the matching-branch
+      # source build. --force-reinstall + --no-deps swaps just pinokin
+      # without disturbing other resolved dependencies.
+      - name: Override pinokin with matching-branch source build
+        if: steps.pinokin.outputs.matching == 'true'
+        run: |
+          cd pinokin-src
+          pip install . --no-build-isolation --force-reinstall --no-deps
+          python -c "from pinokin import CollisionChecker; print('CollisionChecker available')"
+
       - name: Show environment
         run: |
           python -V

CLAUDE.md

@@ -132,6 +132,7 @@ For streamable commands (`streamable = True`), `do_setup()` also runs at high fr
 ## Code Style
 
 - **Comments**: Describe the final code state, not what changed. Avoid "changed X to Y" or "added this because..." comments.
+- **Never ship declared-but-unimplemented API surface.** No "reserved" fields or params, no docstrings saying "not yet applied" — implement it or don't declare it.
 - **Type annotations**: Fix type errors properly instead of using `# type: ignore`. Prefer:
   - `@overload` decorators for functions with different return types based on input
   - `assert` statements to narrow types after None checks
@@ -148,3 +149,13 @@ Prefer fewer, comprehensive integration tests that mimic manual testing over a l
 - **Test results are in `test-results.xml`.** Pytest writes JUnit XML to `test-results.xml` automatically. When diagnosing failures, read this file — it contains test names, durations, failure messages, and captured output. This is more reliable than parsing console output.
 - **NEVER run parol6 and web commander test suites in parallel** — no proper isolation, they share resources and have timing issues when resource-constrained. Always run sequentially.
 - **NEVER allow subagents to run tests.** Many tests are timing-sensitive and the system doesn't have enough resources for agents and tests to run simultaneously. Only the main conversation should run tests, and only after all agents have completed.
+
+### No testing theatre
+
+- Default to real components (fake-serial controller, simulator). A hand-rolled fake is a last resort.
+- Never fake a contract you haven't read — match the real code's raise-vs-return behavior, return types/codes, and signatures.
+- If a fake must mimic protocol behavior (acks, return codes, ordering, lifecycle), the test is at the wrong layer — use the real path. Fakes are for one-line oracles only (e.g. a distance function feeding gate-logic tests).
+- Enter through the real path (command dispatch / client call), not internal helpers fed hand-built inputs.
+- Derive cases from the requirement, not the code under test — "rejects invalid input" means NaN/inf/negative/zero, not the cases the code already handles.
+- Assert outcomes, not interactions — "the fake was called" proves nothing.
+- A regression test must fail against the bug before the fix. Born-green regression tests are theatre.