Skip to content

Official Codebase of 3DCodeVerse

Python

skills: cv3d-repeats-and-mirrors, cv3d-urdf-joints, cv3d-threejs-shader-traps

gaoypeng81eb7d509bf0
diff --git a/harness/codeverse/skills/_claims/cv3d-repeats-and-mirrors.toml b/harness/codeverse/skills/_claims/cv3d-repeats-and-mirrors.toml
new file mode 100644
index 00000000..b56f20d1
--- /dev/null
+++ b/harness/codeverse/skills/_claims/cv3d-repeats-and-mirrors.toml
@@ -0,0 +1,19 @@
+# Every number this bundle quotes, pinned to the constant it came from.
+# `key` is shared across the library: two skills that can attach to one session
+# must render the same text for the same key.
+
+[[claim]]
+key = "bbox_tolerance_m"
+text = "0.01"
+python = "codeverse.conventions:BBOX_TOLERANCE_M"
+
+[[claim]]
+key = "rel_tol"
+text = "0.10"
+python = "codeverse.spatial.contract:REL_TOL"
+format = "{:.2f}"
+
+[[claim]]
+key = "error_factor"
+text = "3.0"
+python = "codeverse.spatial.contract:ERROR_FACTOR"
diff --git a/harness/codeverse/skills/_claims/cv3d-urdf-joints.toml b/harness/codeverse/skills/_claims/cv3d-urdf-joints.toml
new file mode 100644
index 00000000..98c661d8
--- /dev/null
+++ b/harness/codeverse/skills/_claims/cv3d-urdf-joints.toml
@@ -0,0 +1,18 @@
+# Pinned to the live constants. The sweep's `tol_m` (0.002) and `hinge_clearance_m`
+# (0.010) are keyword defaults of joints_sweep.sweep_collisions, not module constants,
+# so they cannot be pinned here; references/sweep-and-motion.md names their call site.
+
+[[claim]]
+key = "contact_gap_m"
+text = "0.002"
+python = "codeverse.conventions:CONTACT_GAP_M"
+
+[[claim]]
+key = "fk_tol_m"
+text = "0.001"
+python = "codeverse.languages.urdf.runtime:FK_TOL_M"
+
+[[claim]]
+key = "rest_penetration_max_m"
+text = "0.005"
+python = "codeverse.languages.urdf.runtime:REST_PENETRATION_MAX_M"
diff --git a/harness/codeverse/skills/cv3d-repeats-and-mirrors/SKILL.md b/harness/codeverse/skills/cv3d-repeats-and-mirrors/SKILL.md
new file mode 100644
index 00000000..9022fb58
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-repeats-and-mirrors/SKILL.md
@@ -0,0 +1,123 @@
+---
+name: cv3d-repeats-and-mirrors
+description: Build repeated, mirrored and radially arrayed parts so the contract gate passes on the first build. Use whenever a plan part has instances greater than 1 or symmetry other than none, when a part is a left/right pair or a ring of N, or on any repair round that reported contract/instance_bbox or contract/instance_count. Covers instance naming (Name_0..Name_N), which box the gate compares for an instanced part, mirroring without a negative object scale, and radial angles derived from the count.
+license: Apache-2.0
+compatibility: static_object and articulated_object tracks; blender, urdf_blender, cadquery and threejs. Numbers are from codeverse/spatial/contract.py and conventions.py.
+metadata:
+ evidence: measured
+ verified: "2026-08-25"
+ corpus: "217 run records / 2,121 gate reports under bench/out, mined 2026-08-25"
+ owns: "contract/instance_bbox, contract/instance_count"
+---
+
+# Repeats, mirrors and arrays
+
+**When:** a plan row says `instances > 1`, or `symmetry` is `mirror_x` / `mirror_y` / `radial`,
+or the brief asks for a ring / row / pair of the same thing. Skip if every part is unique.
+
+**The one move:** build the shape ONCE, then place N copies from a loop whose numbers come out
+of the plan row. A hand-typed second copy is how the pair stops matching.
+
+## What the gate actually measures
+
+`check_contract` (`spatial/contract.py`) treats an instanced part differently from a single part.
+
+* **Naming.** The gate first claims the node named exactly like the plan part, then claims
+ `Name_0`, `Name_1`, ... (regex `^name([_.-]?\d{1,3})?$`, so `Leg1` and `Leg.2` also match).
+ A node whose name is exactly *another* plan part's name is never stolen. Use
+ `Name_0 .. Name_{N-1}` — that is the string the gate's own fix hint asks for.
+* **Count.** `instances = N` but a different number of nodes found is a WARN:
+ `'ApexFinial': found 1 instance(s), plan asks for 2`.
+* **Box.** For `instances > 1` the **centre is not checked at all**. The gate computes two
+ readings and reports whichever fits better:
+ * `(each instance)` — the *worst single copy's* extents against the plan extents;
+ * `(all instances)` — the *union* bbox of all copies against the plan extents.
+ Satisfying either one clears the finding. The plan's bbox for an instanced row describes
+ **one copy** at a representative location (see `tracks/plan_examples.py`: `Leg`,
+ `instances: 2`, extents `0.035 x 0.035 x 0.41`), so build each copy at those extents and the
+ `(each instance)` reading goes to zero.
+* **Tolerance.** Per axis `tol = max(0.01 m, 0.10 x plan extent)`; beyond `3.0 x tol` the WARN
+ becomes an ERROR. Same constants as `cv3d-bbox-contract` (`BBOX_TOLERANCE_M`, `REL_TOL`,
+ `ERROR_FACTOR`).
+
+Because the centre is ignored here, a mis-*placed* copy never shows up as `instance_bbox`. It
+surfaces later as interpenetration, a floating part, or an overall-bbox deviation — one loop
+bug, N findings in a different gate.
+
+## Measured (bench/out, 2026-08-25)
+
+* `contract/instance_bbox` fired in **38 of 217 runs**; 12 of those reached ERROR.
+* Of its 191 findings, **144 were `(each instance)`** and 47 `(all instances)` — the copies were
+ the wrong *size*, far more often than the group was the wrong *span*.
+* Median worst deviation **2.0 x tolerance**, max 27.7 x.
+* The judge's phrasing of the same bug is plural and total: *"All four stool legs float above the
+ ground plane"*, *"All four feet interpenetrate the BasePlinth by 3.0 mm"*, *"All four wheels
+ interpenetrate the chassis"*. When a loop is wrong it is wrong N times.
+
+## Placement: derive from the plan, not from the keyboard
+
+```python
+# plan row: Leg - extents (0.035, 0.035, 0.410) m, centre (0.170, -0.160, 0.205), instances 4
+EX = (0.035, 0.035, 0.410)
+X, Y, Z = 0.170, 0.160, 0.205 # |x|, |y| and z read off the plan centre
+leg0 = make_box("Leg_0", EX, (X, -Y, Z)) # ONE build call ...
+for i, (sx, sy) in enumerate(((-1, -1), (-1, 1), (1, 1)), start=1):
+ linked_copy(leg0, f"Leg_{i}", (sx * X, sy * Y, Z)) # ... N placements
+```
+
+Every copy inherits the extents, so `(each instance)` cannot drift. If a copy must differ,
+that is a different plan part, not an instance.
+
+## Radial arrays: the angle comes from the count
+
+```python
+n = 6 # never a typed list of angles
+for i in range(n):
+ a = 2.0 * math.pi * i / n
+ make_box(f"Spoke_{i}", EXT, (R * math.cos(a), R * math.sin(a), Z))
+```
+
+A typed list silently drops or duplicates a step when the count changes, and the gate then
+reports a count mismatch it took you a round to see. For repeated *detail inside one part*
+(flutes, dentils, cage wires) use the cookbook's `radial_array` ARRAY modifier instead: that
+stays ONE export node, which is what the plan asked for.
+
+## Mirrors
+
+Two different things share the word:
+
+* **Symmetry inside one part** (a bracket that is symmetric about x=0): MIRROR modifier over the
+ object origin — put the origin ON the symmetry plane, then apply. One node, one plan part.
+* **A mirrored pair the plan names** (`instances: 2`, `symmetry: mirror_x`): two nodes,
+ `Name_0` and `Name_1`, at `+X` and `-X`. Both must exist; a missing twin is a count WARN and
+ usually a lopsided silhouette in every render.
+
+**On mirroring by negative object scale, the usual warning is wrong here.** It is widely
+repeated that a negative scale reaches the export and inverts normals. Checked on 2026-08-25:
+`spatial/measure.py` loads the GLB with trimesh and calls `apply_transform` per node, and
+trimesh repairs the face winding of a negatively-scaled mesh on load; `measure` then records
+`abs(volume)`. The gates read identical numbers either way. That cuts the other way too —
+**no geometry gate here can tell a correctly mirrored twin from a botched one.** Mirror the
+mesh data (MIRROR modifier, or a bmesh transform), apply it, and look at the render: the judge
+is the only check you have.
+
+## Same, or deliberately different
+
+The judge penalises both ends, so read the brief before looping:
+
+* Too different: *"The two handle loops are identical in size and shape, failing to provide a
+ distinct smaller thumb loop and larger multi-finger loop"* — 3 findings, `major`, urdf. When
+ the brief distinguishes the members, they are **separate plan parts**, not instances.
+* Too same: *"Cliff walls are composed of identical, rigidly stacked blocks arranged in perfectly
+ straight lines, lacking any organic shape"* — `critical`. For natural repeats, seed a small
+ per-copy jitter (the cookbook's `varied_copies`: 1-2 % scale, sub-millimetre offset, under a
+ degree of tilt). Keep the jitter well inside `0.10 x extent` so it cannot cost you a
+ contract finding.
+
+## Finish
+
+Run `build`, then `check_contract` (count + both box readings) and `check_connectivity` (the
+loop's placement). Read the numbers; do not eyeball the montage.
+
+Depth, the full failing-message catalogue and the per-language array/mirror idioms:
+`references/instances.md`.
diff --git a/harness/codeverse/skills/cv3d-repeats-and-mirrors/references/instances.md b/harness/codeverse/skills/cv3d-repeats-and-mirrors/references/instances.md
new file mode 100644
index 00000000..4d9f7e23
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-repeats-and-mirrors/references/instances.md
@@ -0,0 +1,160 @@
+# Instances, mirrors and arrays — depth
+
+Everything here was read out of the live harness on 2026-08-25:
+`codeverse/spatial/contract.py`, `codeverse/contracts/plan.py`,
+`codeverse/conventions.py`, `codeverse/tracks/plan_examples.py`,
+`codeverse/prompts/blender/cookbook.md`, and 2,121 gate reports under `bench/out`.
+
+## 1. Exactly how the gate matches a name to a plan part
+
+`contract.match_parts` runs two passes over the measured GLB nodes.
+
+1. **Exact pass.** For each plan part, claim every node whose `to_snake(name)` equals the plan
+ part's `to_snake(name)`.
+2. **Instance pass.** For each plan part, claim the remaining nodes matching
+ `^{snake}(?:[_.-]?\d{1,3})?$` — but never a node whose snake name is *reserved*, i.e. is the
+ exact snake name of some other plan part.
+
+Pass 2's reservation exists because of a real regression: a plan with `Shelf` and `Shelf2` had
+`Shelf` swallow the `Shelf2` node, producing a false `plan part 'Shelf2' is missing from the
+GLB` ERROR on geometry that matched the plan exactly.
+
+Consequences you can act on:
+
+* `Leg_0`, `Leg.1`, `Leg-2`, `Leg3` all count as instances of plan part `Leg`. Only up to three
+ digits.
+* Blender's auto-suffix `Leg.001` also matches (3 digits) — but do not rely on it; auto-suffixes
+ mean you created a name collision and the numbering is not yours.
+* `LegFront` does **not** match `Leg` (the regex allows digits only after the stem).
+* If the plan has both `Leg` and `Leg2` as separate rows, name your nodes exactly `Leg` and
+ `Leg2` and do not add `Leg_0`.
+
+## 2. The two box readings, in full
+
+For a plan row with `instances > 1` and `k` matched nodes:
+
+```
+per[i] = extents(node_i) - plan.extents # each copy on its own
+union = extents(bbox of all k) - plan.extents # the group's span
+worst_each = the per[i] with the largest |delta| / tol
+report = whichever of (union, worst_each) has the smaller |delta| / tol
+```
+
+`tol` is per axis: `max(BBOX_TOLERANCE_M, REL_TOL * plan_extent)` = `max(0.01 m, 0.10 * extent)`.
+`ERROR_FACTOR = 3.0`, so `ratio > 3.0` is an ERROR and anything above 1.0 is a WARN.
+`check_center=False` for this branch — the centre delta is computed but never reported.
+
+The message tells you which reading lost:
+
+```
+'Leg' (each instance) bbox deviates from the plan (worst 3.4x tolerance) [error]
+'BaseFootPlates' (all instances) bbox deviates from the plan (worst 1.1x tolerance) [warn]
+```
+
+`(each instance)` means at least one copy is the wrong size. `(all instances)` means the copies
+are individually plausible but their union does not span the planned box — usually the spacing,
+not the shape.
+
+The `fix_hint` gives you the numbers in **your authoring frame**, already converted back from the
+GLB frame, e.g. `size 21.0x3.5x41.0 vs planned 3.5x3.5x41.0 cm (delta x+17.5cm, y+0.0cm,
+z+0.0cm)`. Paste those numbers; do not re-derive them.
+
+## 3. Count mismatch
+
+```
+'ApexFinial': found 1 instance(s), plan asks for 2 [warn]
+'ShoulderFinial': found 2 instance(s), plan asks for 4 [warn]
+```
+
+Fix hint: `name the copies ApexFinial_0 .. ApexFinial_1`. Two causes in the corpus, in order:
+
+1. the loop was written but every copy landed on the same object name, so Blender collapsed them
+ (or the exporter emitted one node);
+2. the copies were parented under an Empty. **Never parent parts or instances under an Empty** —
+ the harness measures top-level GLB nodes, so an Empty merges its whole subtree into one part
+ and the other copies are reported missing.
+
+If a plan part is entirely absent the severity jumps: `plan part 'X' is missing from the GLB` is
+an ERROR, with hint `create a part named exactly 'X' (x4 as X_0..X_3)`.
+
+## 4. Corpus detail (bench/out, mined 2026-08-25)
+
+Denominator: all 217 run records under `bench/out` that carry gate artefacts; 2,121 gate reports.
+
+| observation | value |
+|---|---|
+| runs where `contract/instance_bbox` fired | 38 |
+| of those, runs that reached ERROR | 12 |
+| findings, `(each instance)` | 144 |
+| findings, `(all instances)` | 47 |
+| median worst deviation | 2.0 x tolerance |
+| max worst deviation | 27.7 x tolerance |
+| runs where `contract/instance_count` fired | 1 (6 findings) |
+
+Judge issues that are the same defect seen from the render side (all corpus-verbatim):
+
+* `major / assembly` — "All four stool legs float above the ground plane, not providing support."
+* `major / assembly` — "All four wheels interpenetrate the chassis significantly."
+* `minor / assembly` — "All four feet interpenetrate the BasePlinth by 3.0 mm."
+* `major / fidelity` (x3) — "The two handle loops are identical in size and shape, failing to
+ provide a distinct smaller thumb loop and larger multi-finger loop."
+* `critical / geometry` — "Cliff walls are composed of identical, rigidly stacked blocks arranged
+ in perfectly straight lines, lacking any organic shape."
+
+## 5. Per-language idioms
+
+### blender / urdf_blender (bpy)
+
+```python
+def linked_copy(src, name, location):
+ o = bpy.data.objects.new(name, src.data) # shares mesh data: identical by construction
+ o.location = location
+ o.rotation_euler = src.rotation_euler
+ o.scale = src.scale
+ return link(o)
+```
+
+* Mirror inside one part: `add_mirror(obj, 'X')` then `apply_modifiers(obj)`. Move the **mesh**
+ off the plane (`obj.data.transform(Matrix.Translation((-dx, 0, 0)))`) so the object origin
+ stays on x = 0 — the modifier mirrors across the origin plane, not across the world.
+* Repeated detail inside one part: ARRAY modifier (`add_array`) for rows,
+ `radial_array(obj, count)` for rings. Both produce ONE object, which is what a single plan
+ part must export as.
+* `bpy.ops.mesh.primitive_cube_add(scale=...)` without `size=1` builds a 2 m cube times the
+ scale — every extent doubles. `lint:blender` flags it. Prefer the cookbook's bmesh
+ `make_box`.
+* For a URDF pair, each copy is its **own link** with its own joint and pivot. Instancing is a
+ Blender convenience; the URDF still needs `left_wheel` and `right_wheel` as separate links.
+
+### cadquery
+
+Polar and rectangular arrays place points, then one feature call consumes them:
+
+```python
+(cq.Workplane("XY").faces(">Z").workplane()
+ .polarArray(0.04, 0, 360, 6) # radius, startAngle, total angle, count
+ .hole(0.005)) # ONE feature call consumes all 6 points
+```
+
+`polarArray` takes the count and sweeps the total angle itself, which is exactly the
+"angle from the count" rule the loop version spells out. `.rarray(xSpacing, ySpacing,
+xCount, yCount)` for grids; `.pushPoints([...])` only when the positions are genuinely
+irregular. One array plus one cut is far cheaper than a loop of cuts and never leaves
+slivers behind.
+
+### three.js
+
+`InstancedMesh` is one draw call but also **one node** — good for scenery, wrong for a plan row
+that must be measured per copy. When the plan names `instances: N` and the gate must see N
+nodes, emit N `THREE.Mesh` objects sharing one geometry, named `Name_0..Name_{N-1}`, added at
+the top level of the exported group.
+
+## 6. Jitter that is safe
+
+Per-copy variation reads as real, but it competes with the contract tolerance. The tolerance on
+a 4 cm part is `max(0.01, 0.10 * 0.04) = 0.01 m` — an absolute 10 mm floor, generous. On a
+1 m part it is 0.10 m. Scale jitter of 1-2 % is therefore always safe; position jitter is free
+because the centre is not checked for instanced parts. Rotation jitter can enlarge a copy's
+axis-aligned bbox: a 0.6 degree tilt on a 0.41 m leg adds about 4 mm to the x extent, which is
+inside the 10 mm floor but not inside a 1 % budget on a 5 cm part. Keep tilt under 1 degree on
+parts smaller than 10 cm.
diff --git a/harness/codeverse/skills/cv3d-threejs-shader-traps/SKILL.md b/harness/codeverse/skills/cv3d-threejs-shader-traps/SKILL.md
new file mode 100644
index 00000000..84e84eb0
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-threejs-shader-traps/SKILL.md
@@ -0,0 +1,123 @@
+---
+name: cv3d-threejs-shader-traps
+description: Write a ShaderMaterial or an onBeforeCompile patch that survives this harness's shader gate on the first build. Use on any scene_threejs or threejs session that authors custom GLSL, and on every round where shader_preflight reported an error or a warning. Says which mistakes the harness detects statically, which it detects at runtime, which it cannot see at all, and corrects three widely repeated three.js warnings that do not apply to this renderer.
+license: Apache-2.0
+compatibility: [email protected], headless WebGL via puppeteer. Rules read from runtime_js/lib/glsl_audit.mjs, runtime_js/lib/host_compile.mjs, runtime_js/lib/shader_report.mjs and runtime_js/lib/browser/renderer.js.
+metadata:
+ evidence: mixed
+ evidence_note: "Every rule is read from the live runtime_js source and cross-checked against the shader_report merge path. Incidence is NOT measured: bench/out holds 4 scene_threejs runs, and all 4 shader_preflight reports are clean INFO (10, 9, 14 and 11 programs compiled; 1-12 custom materials). The corpus therefore supports the detection map, not a defect rate."
+ verified: "2026-08-25"
+ owns: "shader/compile_or_binding"
+---
+
+# three.js shader traps that this harness actually detects
+
+**When:** your scene builds a `THREE.ShaderMaterial` / `RawShaderMaterial`, or patches a built-in
+material through `onBeforeCompile`, or `shader_preflight` said something.
+
+The GLSL recipes are in `codeverse/prompts/scene_threejs/glsl_cookbook.md` — start from its
+`makeShaderMaterial` and its 16 pitfalls. What follows is the part the cookbook does not say:
+**which of those pitfalls a gate will catch, at what severity, and which ones nothing catches.**
+
+## The detection map
+
+Everything below lands in the single `shader_preflight` gate report, merged by
+`runtime_js/lib/shader_report.mjs`.
+
+**Static pass** — `glsl_audit.mjs`, over the GLSL string literals in your source, no GPU needed:
+
+| kind | severity | fires when |
+|---|---|---|
+| `include_not_alone` | ERROR | an `#include` shares its line with anything else |
+| `version_directive` | ERROR | a `#version` line in a `ShaderMaterial` (three prepends its own); WARN in a `RawShaderMaterial` if it is not first |
+| `fragment_out_and_gl_fragcolor` | ERROR | the fragment declares `out vec4` **and** writes `gl_FragColor` |
+| `glsl3_gl_fragcolor` | ERROR | `glslVersion: THREE.GLSL3` plus `gl_FragColor` |
+| `undeclared_uniform` | ERROR | GLSL reads `uTime` but no string declares `uniform float uTime;` |
+| `unbound_uniform` | ERROR | GLSL uses `uTime` but no JS outside a template literal writes `uTime:` or `uTime =` |
+| `precision_directive` | WARN | your own `precision ... float;` in a `ShaderMaterial` |
+| `chunk_dropped` | WARN | an `onBeforeCompile` `.replace()` of `#include` that does not keep the include |
+| `no_fog` | WARN | the scene uses fog and a full ShaderMaterial fragment has no fog chunk |
+
+**Runtime pass** — `host_compile.mjs::materialAudit`, walking the booted scene graph:
+
+* `unbound_uniform` **ERROR** — the material's fragment or vertex source contains `uTime` but
+ `material.uniforms.uTime` is missing.
+* `no_fog` **WARN** — `scene.fog` is set and this `ShaderMaterial` neither has
+ `material.fog && material.uniforms.fogColor` nor mentions `fog_fragment` / `fogColor`.
+ Exempt: materials whose object or material name matches `sky|dome|stars|cloud|sun|moon`, or
+ that are `side: THREE.BackSide` with `depthWrite: false`.
+
+Plus GPU compile: every program is force-compiled, and a compiler error is mapped back to
+`file:line` in *your* source. A scene that will not boot produces one ERROR of kind `boot`.
+
+## Name the time uniform exactly `uTime`
+
+Both audits are hard-coded to the identifier `uTime` (`/\buTime\b/`). Call it `time`, `u_time`
+or `iTime` and you get **no** protection from either check — the shader compiles, the uniform
+never updates, and the scene is silently frozen. `animation_life` is **0.431, the lowest
+criterion in the whole corpus** (8 rounds over 4 scene runs), and the judge's words for it are
+*"No animation is visible; the scene is completely static"* and *"MONTAGE 2/3 (t=0s) and
+MONTAGE 3/3 (t=1.5s) shows identical frames"*. Naming the uniform `uTime` is the cheapest
+insurance in this file.
+
+The rule has two halves and they are checked separately:
+
+```js
+// GLSL side: a JS uniforms entry is NOT a GLSL declaration.
+const fs = `uniform float uTime; // <- or 'undeclared_uniform', ERROR
+ void main() { gl_FragColor = vec4(vec3(sin(uTime)), 1.0); }`;
+// JS side: bind it, and mutate .value - never replace the uniforms object.
+const mat = new THREE.ShaderMaterial({ uniforms: { uTime: { value: 0 } }, fragmentShader: fs });
+mat.userData.update = (t) => { mat.uniforms.uTime.value = t; }; // driven from update(t, dt)
+```
+
+## Fog is real here, and doubly detected
+
+`scene.fog` reaches a material only through three's own chunks. A custom shader without them
+keeps full contrast while everything around it recedes — the classic "cardboard cut-out in the
+haze". Both the static pass and the runtime pass flag it, so it costs you two warnings.
+
+Three things are required together and the cookbook's `makeShaderMaterial` does all three:
+`fog: true` on the material, `THREE.UniformsLib.fog` merged into `uniforms`, and
+`#include <fog_pars_fragment>` plus `#include <fog_fragment>` (fog **last** in `main`, after
+tone mapping and colour space, matching three's own materials). For an additive glow, fade
+through alpha instead — `gl_FragColor.a *= 1.0 - smoothstep(fogNear, fogFar, vFogDepth);` — or
+the light gets brighter with distance.
+
+Deliberate exception: a sky dome, or any material that genuinely must not fog. The static audit
+opts out on the whole file if it contains `fog: false`, the comment marker `3dcv: no-fog`, or
+the word `sky`; the runtime audit exempts sky-named and backside-no-depth-write materials.
+Use the marker, do not fight the warning.
+
+## Three warnings from the wider three.js world that do NOT apply here
+
+Verified against this runtime on 2026-08-25 — believing them costs a repair round:
+
+1. **"Always add the `logdepthbuf_*` chunks or your effect vanishes behind geometry."**
+ `runtime_js/lib/browser/renderer.js` takes `logDepth` and it **defaults to false**; the only
+ switch is `render_scene.mjs --log-depth`, and nothing in `codeverse/` ever passes it. So the
+ logarithmic depth buffer is **off in every harness render**. Keep the cookbook's chunks —
+ they compile to nothing without `USE_LOGDEPTHBUF` and would be needed if it were ever turned
+ on — but they can never be the cause of what you are looking at. Do not spend a round there.
+2. **"Guard against the GTAO / post-processing pass overriding your material."**
+ There is no `EffectComposer`, no GTAO and no post-processing anywhere in `runtime_js`; the
+ default pipeline renders straight to the canvas. The failure mode (instanced quads collapsing
+ to the origin in the override-material pass) **cannot occur here**.
+3. **"Patch chaining is safe."** It is not, and this one is real: `chunk_dropped` (WARN) fires
+ when a `.replace('#include <x>', ...)` does not put `#include <x>` back. Always prepend the
+ original include. Two differently patched `MeshStandardMaterial`s also share one compiled
+ program unless each sets its own `customProgramCacheKey` — nothing detects that; you just get
+ two identical-looking materials.
+
+## What nothing detects
+
+The gate proves your shader **compiles and is bound**. It says nothing about whether it is
+*visible* or *right*: colours crushed by the ACES plus sRGB output chain, transparent water
+z-fighting the shore, a patched material whose clone lost its `onBeforeCompile`, a shared
+program cache key, an effect placed outside every camera's frustum. There is no agent tool for
+the counterfactual "strip the shader and diff the pixels" probe, so look at the frames:
+`scene_views` (or `render_views`) at two different times, and check that the thing you wrote
+changed something.
+
+Full audit source lines, the fix-hint texts, and a minimal citizen shader:
+`references/shader-gate.md`.
diff --git a/harness/codeverse/skills/cv3d-threejs-shader-traps/references/shader-gate.md b/harness/codeverse/skills/cv3d-threejs-shader-traps/references/shader-gate.md
new file mode 100644
index 00000000..c0ca58d6
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-threejs-shader-traps/references/shader-gate.md
@@ -0,0 +1,150 @@
+# The shader gate, in full
+
+Read out of the live runtime on 2026-08-25: `runtime_js/lib/glsl_audit.mjs`,
+`runtime_js/lib/host_compile.mjs`, `runtime_js/lib/shader_report.mjs`,
+`runtime_js/lib/scene_host.mjs`, `runtime_js/lib/browser/renderer.js`,
+`runtime_js/check_shaders.mjs`, `runtime_js/package.json`, and
+`codeverse/spatial/probes.py`. Renderer: `[email protected]`, headless WebGL through
+`puppeteer@^24.43.1`.
+
+## 1. How a finding reaches you
+
+```
+src/**.js --(regex-extracted GLSL strings)--> glsl_audit.auditFile -> errors[] / warnings[]
+booted page -> window.__c3v.compileAll() -> shader_errors[] -> errors[] (mapped to file:line)
+ -> materialAudit(scene) -> errors[] / warnings[]
+ -> console noise -> warnings[]
+ all merged by shader_report.compileIntoReport
+ -> codeverse/spatial/probes.py::shader_report
+ -> GateReport(gate="shader_preflight")
+```
+
+`passed` is `report.ok and no ERROR finding`. The agent-facing tool is `shader_probe`
+(`Compile every GLSL/ShaderMaterial in the scene headlessly and report shader errors with line
+numbers`); the same report is produced automatically on every `scene_threejs` build.
+
+A compile error carries `stage`, `material`, the offending `source_line`, surrounding
+`context`, and a `fix_hint` derived from the driver message. When the same GLSL line appears in
+several files the message says `(N identical lines; first shown)` — rename or de-duplicate
+rather than guessing.
+
+## 2. The static audit, rule by rule
+
+Source: `glsl_audit.mjs::auditFile(file, source, { sceneUsesFog })`. Default severity is
+`error`; only the rules marked WARN below pass `'warn'`.
+
+| kind | severity | trigger (as coded) | message / fix |
+|---|---|---|---|
+| `include_not_alone` | ERROR | a line matching `#include` that is not the bare include form and has no `${` in it | "'#include chunk' must be ALONE on its line" |
+| `version_directive` | ERROR / WARN | `^\s*#version` — ERROR in a `ShaderMaterial`, WARN in a `RawShaderMaterial` | three prepends its own `#version`; a second one is a compile error |
+| `precision_directive` | WARN | `^\s*precision (lowp|mediump|highp) float;` and not Raw | three prepends precision for `ShaderMaterial`; delete yours |
+| `fragment_out_and_gl_fragcolor` | ERROR | the string has an `out vec4` declaration and writes `gl_FragColor` | keep one: `gl_FragColor` with no `out`, or GLSL3 with your own out variable |
+| `glsl3_gl_fragcolor` | ERROR | `glslVersion: THREE.GLSL3` in the file and `gl_FragColor` in a fragment-looking string | GLSL3 removes `gl_FragColor`; declare `out vec4 fragColor;` |
+| `undeclared_uniform` | ERROR | any string contains `uTime` and none contains `uniform float uTime;` | "a JS uniforms entry is not a GLSL declaration" |
+| `unbound_uniform` | ERROR | any string contains `uTime` and the source **outside every template literal** has no `uTime:` or `uTime =` | `uniforms: { uTime: { value: 0 } }` and update `.value` in `update(t)` |
+| `chunk_dropped` | WARN | a `.replace('#include <X>', repl)` whose `repl` does not itself contain `#include <X>` | prepend the original include so fog / logdepth / shadow code still runs |
+| `no_fog` | WARN | the scene uses fog, the file has `ShaderMaterial`, is not Raw, has no opt-out, and a `void main` string writes a colour without `fog_fragment` / `USE_FOG` / `fogColor` | add the fog chunks, `fog: true` and `UniformsLib.fog` |
+
+A "fragment-looking" string is one containing any of `gl_FragColor`, `gl_FragCoord`,
+`csm_FragColor`, `pc_fragColor`, `fragColor`, `output_fragment`, `discard` **and** no
+`gl_Position`.
+
+The `no_fog` opt-out is file-wide: `fog: false`, the comment marker `3dcv: no-fog`, or the word
+`sky` anywhere in the file suppresses it. Prefer the explicit marker — the accidental `sky`
+match will also silence a shader you did want fogged.
+
+## 3. The runtime audit, exactly
+
+`host_compile.mjs::materialAudit(scene, THREE)` traverses the booted scene, visits each distinct
+`isShaderMaterial` once, and emits:
+
+```js
+skyLike = /sky|dome|stars|cloud|sun|moon/i.test(`${object.name} ${material.name}`)
+ || (material.side === THREE.BackSide && material.depthWrite === false);
+
+if (scene.fog && !skyLike
+ && !(material.fog && material.uniforms && material.uniforms.fogColor)
+ && !/fog_fragment|fogColor/.test(fragmentShader))
+ -> { kind: 'no_fog', severity: 'warn' }
+
+if (/\buTime\b/.test(fragmentShader + vertexShader) && !material.uniforms?.uTime)
+ -> { kind: 'unbound_uniform', severity: 'error' }
+```
+
+Note what this means in practice: the runtime pass sees the material you actually built, so it
+catches the case the static pass cannot — a `uniforms` object assembled at runtime that ends up
+without `uTime`, or a material cloned from a patched one. Conversely it only inspects
+`isShaderMaterial`, so an `onBeforeCompile` patch on a `MeshStandardMaterial` is invisible to it
+and only the static `chunk_dropped` rule protects you.
+
+## 4. A minimal citizen shader
+
+Full boilerplate: `codeverse/prompts/scene_threejs/glsl_cookbook.md`, section "The boilerplate:
+makeShaderMaterial". The smallest thing that passes every rule above:
+
+```js
+const VS = `
+#include <common>
+#include <fog_pars_vertex>
+varying vec2 vUv;
+void main() {
+ vUv = uv;
+ vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
+ gl_Position = projectionMatrix * mvPosition;
+ #include <fog_vertex>
+}`;
+
+const FS = `
+#include <common>
+#include <fog_pars_fragment>
+uniform float uTime;
+uniform vec3 uTint;
+varying vec2 vUv;
+void main() {
+ float w = 0.5 + 0.5 * sin(vUv.x * 12.0 + uTime * 1.3);
+ gl_FragColor = vec4(uTint * (0.6 + 0.4 * w), 1.0);
+ #include <tonemapping_fragment>
+ #include <colorspace_fragment>
+ #include <fog_fragment>
+}`;
+
+export function makeRipple(THREE, tint = 0x3a6ea5) {
+ const mat = new THREE.ShaderMaterial({
+ uniforms: THREE.UniformsUtils.merge([
+ THREE.UniformsLib.fog, { uTime: { value: 0 }, uTint: { value: new THREE.Color(tint) } }]),
+ vertexShader: VS, fragmentShader: FS, fog: true,
+ });
+ mat.name = 'Ripple';
+ mat.userData.update = (t) => { mat.uniforms.uTime.value = t; };
+ return mat;
+}
+```
+
+Every include is alone on its line; no `#version`, no `precision`; `uTime` is both declared in
+GLSL and bound in JS; the fog chunks are present and `fog_fragment` is last. Collect the
+materials once at build time and call `m.userData.update(t)` from `update(t, dt)` — never
+traverse the scene inside `update`, and never read the clock from `Date.now()`.
+
+## 5. Corpus, and why this bundle is `mixed` rather than `measured`
+
+`bench/out` holds **4** `scene_threejs` runs (8 judged rounds). Their `shader_preflight`
+reports are the only ones in the corpus and **all four are clean**:
+
+```
+scn_easy_rooftop_garden info compiled 10 programs (1 custom) in 107 ms
+scn_easy_desert_canyon info compiled 9 programs (12 custom) in 38 ms
+scn_easy_japanese_garden info compiled 14 programs (2 custom) in 16 ms
+scn_easy_greenhouse info compiled 11 programs (2 custom) in 825 ms
+```
+
+Zero errors, zero warnings, 1-12 custom materials each. So the detection map above is measured
+from the harness source, but the *frequency* of these defects here is unknown, and this bundle
+must not claim otherwise. What the same four runs do show is the failure the shader work is
+supposed to prevent: `animation_life` 0.431 and `technical_cleanliness` 0.475, the two lowest
+criteria of any language in the corpus, with judge issues reading "No animation is visible; the
+scene is completely static" and "No visible movement in plants or string lights between time
+samples". A shader that compiles cleanly and never moves scores exactly like no shader at all.
+
+Revisit this file when `scene_threejs` reaches 20 graded runs; if `shader_preflight` is still
+silent, the honest conclusion is that the *static* rules are doing their job before the corpus
+ever sees them, and the bundle's weight should shift further towards section 4.
diff --git a/harness/codeverse/skills/cv3d-urdf-joints/SKILL.md b/harness/codeverse/skills/cv3d-urdf-joints/SKILL.md
new file mode 100644
index 00000000..0255fa3b
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-urdf-joints/SKILL.md
@@ -0,0 +1,151 @@
+---
+name: cv3d-urdf-joints
+description: Get links, joints, axes, limits and clearances right in one pass on an articulated_object session. Use when authoring or repairing src/robot.urdf and the rest pose in src/model.py, and always on a repair round that reported joint_sweep or motion_direction. Explains which pose set the sweep gate tests, why a moved-pose overlap is always an ERROR, and the arithmetic that predicts which way positive q pushes a child before you write the axis.
+license: Apache-2.0
+compatibility: track articulated_object, language urdf_blender. Constants read from codeverse/languages/urdf/runtime.py, codeverse/spatial/joints_sweep.py, joints_poses.py and codeverse/tracks/motion.py.
+metadata:
+ evidence: measured
+ verified: "2026-08-25"
+ corpus: "26 urdf_blender runs / 50 judged rounds under bench/out, mined 2026-08-25"
+ owns: "joint_sweep, motion_direction"
+ scope: "URDF physical structure only; SRDF semantics are out of scope and must not be invented"
+---
+
+# URDF joints: axes, limits and clearance across the sweep
+
+**When:** any `articulated_object` round that writes or fixes `src/robot.urdf` (and the rest pose
+in `src/model.py`), or that received a `joint_sweep` / `motion_direction` finding.
+
+The frame recipe, the pivot rule and the visual/collision `origin = -pivot` line are in
+`codeverse/prompts/urdf/contract.md` and its cookbook — follow them literally. This skill is the
+part the contract does not tell you: **what the gates measure, and how to satisfy them before the
+first build.**
+
+## Two things fail the BUILD, not just a gate
+
+* **FK check**, tolerance **1 mm** (`FK_TOL_M = 0.001` m). If FK at q=0 does not put every mesh back where
+ `model.py` authored it, the build stops with `FkInconsistent` and prints the corrected
+ `origin`. Cause is almost always a link's visual/collision `origin` left at `0 0 0` instead of
+ `-pivot`, or a joint with `rpy` other than `0 0 0`.
+* **Rest penetration** over **5 mm** (`REST_PENETRATION_MAX_M = 0.005` m): the build stops with
+ `RestPenetration`.
+
+Everything else comes back as findings you still have to read.
+
+## The sweep is not a rest-pose check
+
+`joint_sweep` poses the robot at: **rest**, then **every movable joint alone at its lower, mid
+and upper limit** (others at 0), then **8 seeded random full-body combinations** (seed 0) when
+more than one joint moves. Continuous joints sample 0, +/-pi/2 and pi.
+
+Severity, from `sweep_findings`:
+
+| where the pair overlaps | depth | verdict |
+|---|---|---|
+| any pose | up to 2.0 mm | not reported (`tol_m = 0.002`) |
+| rest, or a pair joined only by `fixed` joints | 2.0-5.0 mm | WARN |
+| rest, or a `fixed`-joined pair | over 5.0 mm | ERROR (and fails the build) |
+| **any moved pose** | over 2.0 mm | **ERROR, whatever the depth** |
+
+So a 2.1 mm graze that only happens at one limit is scored exactly as badly as a 20 mm gouge.
+
+**Measured** (26 urdf runs, 691 sweep findings, 2026-08-25): only **34 findings (4.9 %) were at
+rest**, and every one of those was a WARN. **653 were in a moved pose** — 358 at a single joint's
+limit, **295 in a random multi-joint combination**. Of 48 distinct link pairs that collided,
+**29 never touch at rest** and **7 appear only in a combination**, so posing your joints one at a
+time in your head is not enough: two arms that each clear the body can still meet each other.
+Median depth 4.0 mm, max 20.0 mm; 510 of 687 were 5 mm or less.
+
+Design rule: **1-3 mm of clearance all round, held over the whole envelope**, and think about the
+worst *combination*, not the worst single joint. Fixed hardware is different and cheap — a
+handle welded to a door may sink up to 2 mm with no finding at all, because pairs joined only by
+`fixed` joints are measured once with the rest policy and never re-judged as they move.
+
+**Attachment** is checked at rest only: a `fixed` child must be within `CONTACT_GAP_M = 0.002` of
+its parent (ERROR otherwise, always); a revolute / continuous / prismatic child must be within
+**10 mm** of its parent (WARN, ERROR beyond 30 mm) — `link 'moving_jaw' slides in
+'fixed_jaw_body' (prismatic joint) but the meshes are 42.5 mm apart at rest`. A prismatic child
+already inside the parent's bounding box (a drawer in its cavity) is exempt.
+
+**159 of 687 findings carried `[approx: non-watertight mesh]`.** Depth is then an estimate. Make
+each link one closed solid so the number you are given is the number you can trust.
+
+## Predict the direction before you write the axis
+
+`motion_direction` does **not** read your axis. It moves the joint positively from rest and
+measures where the **child link's centroid** went, then asks whether that displacement is within
+60 degrees of the direction the plan's `motion` sentence names. Probe: the limit of larger
+magnitude, clamped to 0.35 rad for a rotation; the full limit for a slide.
+
+For a revolute joint that is pure geometry:
+
+```python
+import numpy as np
+def child_moves(axis, pivot, centroid): # revolute: d ~ axis x (centroid - pivot)
+ d = np.cross(axis, np.subtract(centroid, pivot))
+ return d / np.linalg.norm(d) # prismatic: the direction IS the axis
+# pedal-bin lid: pivot on the back top edge, lid centroid just above the rim
+print(child_moves((-1, 0, 0), (0, 0.125, 0.351), (0, 0, 0.356)))
+# [0. 0.03996804 0.99920096] -> almost pure +Z: the lid lifts UP
+```
+
+Verified against `motion_direction_check` on 2026-08-25: it reported `up` for axis `-1 0 0` and
+`down` for `+1 0 0` on that geometry, matching the cross product's sign both times.
+
+Two independent ways to get this wrong, and the corpus has both:
+
+1. **Axis sign.** Fix it by negating `axis`. The contract is explicit — *never* compensate by
+ swapping `lower` and `upper`; q=0 must stay the plan's rest pose. (The gate's own fix hint
+ offers both; take only the first half.)
+2. **Pivot off the axis line.** *"The hasp rotates about its center rather than its top edge,
+ causing it to clip into the lid."* Put the pivot at the part's centre and `centroid - pivot`
+ goes to zero: the centroid barely translates, the measured direction is noise, and the part
+ sweeps *through* its neighbour instead of swinging clear of it. The pivot must be a point ON
+ the hinge line.
+
+`_DIRS` in `joints_sweep.py` maps the words onto the authoring frame `conventions.py` owns:
+`up` = +Z, `down` = -Z, `front` = -Y, `back` = +Y, `right` = +X, `left` = -X. Signed-axis keys
+(`+y`, `-x`, ...) name the same vectors.
+
+## How the plan's sentence becomes the expected direction
+
+`tracks/motion.py::expected_direction` parses the plan's `motion` text with a fixed precedence,
+and the gate is unforgiving about it:
+
+* an explicit signed axis token anywhere in the text (`+y`, `-x`, ...) **wins immediately**;
+* otherwise the first matching phrase wins ("pulls out" and "outward" mean `front`, "inward" and
+ "slides in" mean `back`);
+* text containing `around`, `rotates about`, `spins`, a negation, `either` or `both` is skipped —
+ no finding either way;
+* two different axes in one sentence with no dominant one is skipped.
+
+So make **positive q move the child the way the plan's first direction word says**, even when the
+prose is loose. Verified corpus consequences worth knowing before you argue with a finding:
+
+* `"tray slides sideways from left side to right side"` yields `left` (first word wins), and the
+ build that slid it rightward was flagged. The judge agreed the motion "fulfils the brief's
+ intent" and scored it `minor` — but it is still an ERROR-severity gate finding.
+* `"rear-right leg hinges..."` yields `right`, from the part name.
+* `"rotates clockwise (+Y axis)"` yields `+y` as a **translation** direction. A revolute joint
+ about +Y can never move its child along +Y, so no axis satisfies it. Confirm with the
+ `joint_sweep` pose renders that the part moves the way the prose describes, then leave it.
+ **Do not flip a correct axis to chase an unsatisfiable finding.**
+
+## Scope
+
+URDF here owns physical structure only: links, joints, origins, axes, limits, visual and
+collision geometry. Planning groups, end effectors, group states and disabled collision pairs
+are SRDF concepts; this harness has no SRDF, so do not invent them. The URDF contract also
+forbids `gazebo`, `transmission`, `sensor`, xacro, `package://` and inline primitives. Two of
+these the linter measures directly: a `mesh scale` attribute is a WARN ("model in meters in
+model.py instead"), and a `mimic` joint is a WARN because **the harness ignores it — the sweep
+moves the mimicking joint independently**, so a mechanism that depends on mimic will be posed
+in states you never intended.
+
+## Finish
+
+`build` (runs the FK check and the sweep) then `joint_sweep` and look at the lower/mid/upper
+renders for every joint, then `check_connectivity`, then `check_contract`.
+
+Worked repairs, the full finding catalogue with real messages, and clearance numbers per
+mechanism: `references/sweep-and-motion.md`.
diff --git a/harness/codeverse/skills/cv3d-urdf-joints/references/sweep-and-motion.md b/harness/codeverse/skills/cv3d-urdf-joints/references/sweep-and-motion.md
new file mode 100644
index 00000000..0204c63e
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-urdf-joints/references/sweep-and-motion.md
@@ -0,0 +1,168 @@
+# joint_sweep and motion_direction — depth
+
+Read out of the live harness on 2026-08-25: `codeverse/spatial/joints_sweep.py`,
+`joints_poses.py`, `joints_model.py`, `codeverse/languages/urdf/runtime.py`,
+`codeverse/tracks/motion.py`, `codeverse/tracks/articulated_object.py`,
+`codeverse/conventions.py`; plus every `joint_sweep` and `motion_direction` report under
+`bench/out` (26 `urdf_blender` runs, 50 judged rounds).
+
+## 1. Constants, with the module each comes from
+
+| constant | value | module | what it decides |
+|---|---|---|---|
+| `FK_TOL_M` | 0.001 m | `languages/urdf/runtime.py` | build fails `FkInconsistent` above this |
+| `REST_PENETRATION_MAX_M` | 0.005 m | `languages/urdf/runtime.py` | build fails `RestPenetration` above this |
+| `tol_m` | 0.002 m | `joints_sweep.sweep_collisions` | overlaps shallower than this are not reported |
+| `rest_max_m` | 0.005 m | `joints_sweep.sweep_findings` | rest / rigid overlap: WARN below, ERROR above |
+| `contact_gap_m` | 0.002 m (`CONTACT_GAP_M`) | `conventions.py` | a `fixed` child must be this close to its parent |
+| `hinge_clearance_m` | 0.010 m | `joints_sweep` | a moving child must be this close to its parent |
+| ERROR on attachment | gap over 0.030 m | `joints_sweep.sweep_findings` | `hinge_clearance_m * 3` |
+| depth rounding | 0.1 mm | `joints_sweep` | float32 mesh coordinates carry no finer meaning |
+| random poses | 8, seed 0 | `languages/urdf/runtime.py` | only when more than one joint moves |
+| motion probe | limit of larger magnitude, capped at 0.35 rad | `joints_sweep.motion_direction_check` | prismatic uses the full limit |
+| motion pass test | `cos(observed, expected) > 0.5` | same | a 60 degree cone |
+
+## 2. The pose set, exactly
+
+`joints_poses.pose_samples(robot, n_random=8, seed=0)` returns:
+
+1. `{}` — the rest pose, labelled `rest`.
+2. For each movable joint, each distinct non-zero value of `lower`, `(lower+upper)/2`, `upper`,
+ **with every other joint at 0**. Labels: `hinge@lower`, `hinge@mid`, `hinge@upper`.
+ `continuous` joints use `-pi/2`, `+pi/2`, `pi` instead.
+3. Eight seeded uniform draws over every joint at once (only if more than one joint is movable).
+ Labels list every active joint: `door_hinge=1,handle_turn=0.188,latch_retract=0.000615`.
+
+Two structural facts follow:
+
+* **Attachment (`floating`) is only evaluated in the `rest` pose.** A hinge that flies apart at
+ the upper limit is not reported as unattached; it is reported as an overlap somewhere else, or
+ not at all. Look at the pose renders.
+* **Links joined only by `fixed` joints form a rigid group.** Their mutual overlap is measured
+ once (at `rest` if there is one) and judged with the rest policy in every pose. This is why a
+ welded handle costs nothing while a hinged one is expensive.
+
+## 3. Real messages, and what each one means
+
+```
+links 'table_top' and 'left_leg_frame' overlap by 20.0 mm at pose left_leg_joint@upper [error]
+links 'turret' and 'lower_arm' overlap by 2.9 mm at pose shoulder_joint@lower [error]
+links 'window_frame' and 'window_sash' overlap by 11.9 mm at pose crank_rotation=-1.45,
+ latch_pivot=1.43,operator_base_pivot=0.0574,... [approx: non-watertight mesh] [error]
+links 'door_leaf' and 'lever_handle' overlap by 3.0 mm at pose rest [warn]
+link 'moving_jaw' slides in 'fixed_jaw_body' (prismatic joint) but the meshes are
+ 42.5 mm apart at rest - nothing physically connects them [error]
+link 'seat' hinges on 'main_frame' (revolute joint) but the meshes are 11.0 mm apart
+ at rest - nothing physically connects them [warn]
+```
+
+The fix hints differ by pose and are worth reading rather than guessing:
+
+* at rest — "shrink/move one of 'a', 'b' so they touch (2 mm) instead of overlapping";
+* in a moved pose — "Moving joint(s) [...] drives 'a' into 'b'. Either move the pivot/axis in
+ robot.urdf so the part swings/slides clear, shrink the limits, or carve the clearance in
+ model.py." Three genuinely different repairs; pick the one the mechanism justifies. Shrinking
+ a limit is legitimate when the plan's range was optimistic (a drawer at 0.8 x depth), and wrong
+ when the range is the point of the object.
+
+## 4. Corpus (bench/out, mined 2026-08-25)
+
+Denominator: 26 `urdf_blender` run records; 50 judged rounds.
+
+| observation | value |
+|---|---|
+| runs where `joint_sweep` fired | 10 of 26 (38 %) |
+| of those, runs with an ERROR | 9 |
+| runs where `motion_direction` fired | 9 of 26 (35 %) |
+| of those, runs with an ERROR | 8 |
+| total sweep WARN/ERROR findings | 691 (687 penetration, 4 unattached) |
+| findings at the `rest` pose | 34 (4.9 %), **all WARN** |
+| findings at a single-joint limit or mid pose | 358 |
+| findings in a random multi-joint combination | 295 |
+| distinct (run, link-pair) collisions | 48 |
+| pairs that never collide at rest | 29 of 48 |
+| pairs seen **only** in a random combination | 7 of 48 |
+| median overlap depth | 4.0 mm |
+| max overlap depth | 20.0 mm |
+| findings with depth 5 mm or less | 510 of 687 |
+| findings marked `[approx: non-watertight mesh]` | 159 of 687 |
+
+Judge `articulation` issues in `urdf_blender`: **34** — 11 critical, 19 major, 4 minor.
+`articulation_plausibility` (0.732) and `joint_placement_and_range` (0.736) are the 2nd and 3rd
+lowest of the eight urdf criteria over 50 rounds; only `geometry_detail` (0.699) is lower.
+
+Corpus-verbatim, grouped by root cause:
+
+**Direction (about 13 of 34).**
+"Leg frames fold outward and upward into the air instead of inward under the table." (critical)
+"The door swings in the wrong direction (inward instead of outward), causing massive clipping
+with the frame." (critical)
+"The inner tray slides forward out of the chest body instead of sideways." (critical)
+"The joint axis is flipped; the lower limit points the arm up instead of folding it down." (major)
+"The steering joint rotates the fork assembly around the Z-axis (roll) instead of the Y-axis
+(yaw), causing the wheel to tilt sideways." (critical)
+
+**Pivot placement.**
+"The hasp rotates about its center rather than its top edge, causing it to clip into the lid."
+"Because the front leg frame is detached, it pivots around a point in empty space rather than a
+physical crossbar."
+
+**Sweep clearance.**
+"The right rear spreader collides with the front frame during the folding sweep."
+"The moving jaw heavily interpenetrates the fixed jaw body at its upper travel limit."
+"Seat overlaps with the main frame by 6.0 mm when fully raised."
+
+## 5. The motion phrase table, verbatim from the code
+
+`_DIRS` in `joints_sweep.py` (URDF frame: Z up, -Y front, +X right):
+
+```
++x / right (1, 0, 0) -x / left (-1, 0, 0)
++y / back / in (0, 1, 0) -y / front / out / open_front (0, -1, 0)
++z / up / open_up (0, 0, 1) -z / down / open_down (0, 0, -1)
+```
+
+`tracks/motion.py::expected_direction` maps the plan's prose onto those keys. Precedence:
+
+1. Any of `-y +y -z +z -x +x` found as a whole token returns immediately.
+2. Otherwise the longest matching phrase, in the module's fixed order. Phrases that mean
+ `front`: "pulls out", "slides out", "swings out", "outward", "forward", "towards the viewer",
+ "opens out", "opens to the front". Phrases that mean `back`: "pushes in", "slides in",
+ "inward", "backward", "rearward", "towards the back". Then `up` / `down` / `left` / `right`.
+ Bare "out" is `front`; bare "in" is not in the phrase list, only "slides in" / "pushes in".
+3. Skipped entirely (`None`, no finding) if the text contains `not `, `n't`, `either`, `both`,
+ `around`, `rotates about` or `spins`, or if it names two different axes with no dominant one.
+
+Checked against real plan strings on 2026-08-25:
+
+| plan `motion` text | expected |
+|---|---|
+| "lower arm pitches up and down from 20 to 80 degrees elevation" | `up` |
+| "drawer pulls out 0.4 m" | `front` |
+| "door leaf swings 90 degrees outward toward the front (-Y)" | `-y` |
+| "tray slides sideways from left side to right side along internal ledges" | `left` |
+| "rear-right leg hinges from vertical (-25 deg) to deployed splay (0 deg)" | `right` |
+| "Left leg frame rotates clockwise (+Y axis) folding inward toward table center" | `+y` |
+| "wheel spins around its axle" | skipped |
+| "lid rotates about the back edge" | skipped |
+
+The last three rows are the ones to recognise on a repair round. `"rotates clockwise (+Y axis)"`
+asks for a *translation* along +Y from a joint that rotates about +Y — unsatisfiable. The
+`"sideways from left to right"` and `"rear-right"` rows are satisfiable but only by making +q go
+the way the first word says, which may read backwards in prose; the judge scored one of these
+`minor` and noted "the visual sideways motion fulfills the brief's intent".
+
+## 6. Clearance numbers that pass the sweep
+
+| pair | rest gap | why |
+|---|---|---|
+| moving part vs its housing (drawer in cabinet, door in frame) | 1-3 mm all round | must stay positive over the whole range, including combinations |
+| a closed door / lid against the carcass face | 0-1 mm, flush | must not sink in; 2-5 mm is a rest WARN, over 5 mm fails the build |
+| `fixed` hardware (handle, knob, foot) on its parent | touching, or sunk up to 2 mm | rigid pairs are judged once with the rest policy, so this never becomes a moved-pose ERROR |
+| hinge barrel / drawer runner to its partner | touching (2 mm) | otherwise the attachment check calls the child unattached |
+| revolute or prismatic child to its parent at rest | 10 mm or less | over 10 mm is a WARN, over 30 mm an ERROR |
+
+Sanity procedure that costs nothing: for every moving link, take its bounding box at `lower`,
+`mid` and `upper`, plus the corners of the combinations you expect, and check the swept envelope
+against each neighbour. If two joints can move a pair towards each other, test them together —
+7 of 48 collisions in the corpus were visible in no other pose.