docs: enforce schema-migration + editor-layer rules in review (#376)

Two invariants weren't captured by the wiki or the review-architecture
skill, so a PR could break them and pass review:

- node-schemas.md documented no backward-compat rule, even though
  migrateNodes() runs at load. Add a Schema Evolution section (new
  fields need a Zod default; renames/removals/retypes need a
  migrateNodes entry) plus a Rules bullet.
- review-architecture skill only checked the narrow host-children
  case for migrations and had no editor-layer check at all. Add a
  general schema-migration item (§B) and an editor-overlay-layer
  item (§E, overlay meshes must set EDITOR_LAYER or they leak into
  thumbnails/snapshots and the ink/SSGI buffers).

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

.agents/skills/review-architecture/SKILL.md

@@ -97,6 +97,7 @@ If the PR adds or modifies a node kind, check against `wiki/architecture/node-de
 - **Tag geometry-built children.** `<GeometrySystem>` only disposes children carrying `userData.__fromGeometry = true`. Custom systems that imperatively add children to a registered group must follow the same convention if the group can host React-mounted children (e.g. shelf surfaces hosting items).
 - **One registered mesh per node ID.** If a custom renderer mounts multiple objects, register the parent group (or whichever object the system needs to address via `sceneRegistry.nodes.get(id)`).
 - **Previews must clone cached materials.** If `def.preview` calls the geometry builder and then sets `material.opacity = 0.5`, but the builder caches materials at module scope (most do, keyed on `material` / `materialPreset`), the mutation leaks into every committed instance. Clone, mutate the clone, reassign `mesh.material`, dispose only the clone on unmount. Reference: `nodes/src/shelf/preview.tsx`.
+- **Schema changes must keep old scenes loadable.** Any diff that adds, renames, removes, or retypes a property on a node schema needs a load path for scenes saved before the change (parsed through `AnyNode` in `SceneState.setScene`). A *new* field needs a Zod `.default()` / `.optional()`. A *rename / removal / retype* needs a `migrateNodes` entry in `packages/core/src/store/use-scene.ts` that rewrites the legacy shape before parse — a `.default()` alone silently drops the old value. A schema diff that does neither is a blocker: it breaks every existing scene. See `wiki/architecture/node-schemas.md` § Schema Evolution.
 - **Host kinds need `children` on the schema.** If `def.relations.hosts` is set, the schema must declare `children: z.array(z.string()).default([])` (and `migrateNodes` must patch existing scenes). Otherwise `useScene.createNode(child, parentId)` writes a `parent.children` entry into nothing and the host never sees the new child.
 - **Movable opt-in.** `MoveTool` dispatches to `MoveRegistryNodeTool` only when `def.capabilities.movable` is set. Kinds with bespoke move semantics (wall endpoint drag with linked-wall cascade, slab vertex edit, etc.) deliberately omit `movable` and supply `def.affordanceTools.move` instead. Force-routing a bespoke-move kind through generic dispatch (`nodeRegistry.has(kind)` instead of `def.capabilities.movable`) is a regression — call it out. The bug history is documented in `plans/editor-node-registry.md` ("Capability-driven move dispatch").
 - **Paint dispatch lives on `def.capabilities.paint`.** A paintable kind declares `resolveRole` / `buildPatch` / `applyPreview` (+ optional `getEffectiveMaterial`) on `PaintCapability`; the editor's selection-manager routes hover / click / preview through the generic dispatcher. A PR that adds an `if (node.type === '<kind>')` arm to paint-mode handling, paint-preview application, or material picker resolution is a regression — the behaviour belongs on the kind's `paint` capability. See `packages/core/src/registry/types.ts` (`PaintCapability`).
@@ -127,6 +128,7 @@ If the PR adds or modifies a node kind, check against `wiki/architecture/node-de
 
 - Viewer and core stay unaware of editor-specific concepts (tools, phases, active modes, editor UI state, view-specific helpers).
 - Editor-only overlays and systems are injected as children of `<Viewer>`, not added inside the viewer package.
+- **Editor overlay meshes must carry the editor layer.** Any new `<mesh>` / `<line*>` / `<points>` / `<sprite>` an editor overlay or tool component adds to the 3D scene (gizmos, handles, guides, previews, cursor meshes, marquees) must set `layers={EDITOR_LAYER}` — or `GRID_LAYER` for the ground grid, `ZONE_LAYER` for zone fills. The thumbnail/snapshot camera renders only layer 0, so an untagged overlay leaks into exports (and gets inked / SSGI-darkened in the live view). Flag any overlay-component primitive that omits the layer assignment. See `wiki/architecture/layers.md`.
 - New node types are added by creating one folder under `packages/nodes/src/<kind>/` and registering its definition in `builtinPlugin.nodes`. Adding to a hand-maintained list elsewhere is a sign the registry hasn't absorbed that surface yet — check `plans/editor-node-registry.md` § "Known un-shimmed hardcoded lists" before assuming it's a violation.
 - `AnyNode` is hand-maintained for now (full runtime derivation would lose static typing); `packages/nodes/src/index.test.ts` is the drift gate. If a PR adds a kind to `AnyNode` without adding it to `builtinPlugin.nodes` (or vice versa), the parity test catches it — but flag it in review too.
 

wiki/architecture/node-schemas.md

@@ -78,6 +78,16 @@ const { updateNode } = useScene.getState()
 updateNode(wall.id, { height: 2.8 })   // partial update, merges with existing
 ```
 
+## Schema Evolution & Backward Compatibility
+
+Saved scenes are persisted JSON parsed back through `AnyNode` at load (`SceneState.setScene` → `migrateNodes` → `markDirty`, in `packages/core/src/store/use-scene.ts`). Any change to an existing node's properties must keep older saved scenes loadable — a scene written months ago must still parse and render.
+
+- **Adding a field** → give it a Zod `.default(...)` (or `.optional()`). `AnyNode.parse` then fills it for legacy nodes that lack it. A required field with no default makes every pre-existing scene fail validation.
+- **Renaming, removing, or retyping a field** → a `.default()` is not enough; it silently drops the old value. Add an entry to `migrateNodes` (`use-scene.ts`) that reads the legacy shape and rewrites it to the new one *before* parse. This is also where structural changes go (splitting one material into interior/exterior, deriving `pitch` from a legacy `roofHeight`, seeding `children: []` on a new host kind).
+- **Bumping `schemaVersion`** on the `NodeDefinition` records that a kind's shape changed. The per-kind `def.migrate` map is reserved for future use; today all load-time migration is centralised in `migrateNodes`.
+
+When in doubt, load an old scene (or a fixture) after the change and confirm it still parses and renders.
+
 ## Real Examples
 
 - **Simple geometry node**: `packages/core/src/schema/nodes/wall.ts` — `start`, `end`, `thickness`, `height`
@@ -90,3 +100,4 @@ updateNode(wall.id, { height: 2.8 })   // partial update, merges with existing
 - **Never hardcode IDs.** Let `objectId('type')` generate them.
 - **Add new node types to `AnyNode`** in `types.ts` or they won't be accepted by the store.
 - **Keep schemas in `packages/core`**, not in the viewer or editor — the schema is shared by all packages.
+- **Never break old scenes.** New fields get a `.default()`; renames/removals/retypes get a `migrateNodes` entry. See *Schema Evolution & Backward Compatibility* above.