motionloom 2.6.0 → 2.7.0

package/examples/agent-consumer/asset-consistency/action-sequence/verifier-evidence/walk.01.json

@@ -0,0 +1,26 @@
+{
+  "schema_version": "0.1",
+  "contract": "action-separation-verifier-evidence",
+  "sequence_id": "hero-walk-v1",
+  "action_id": "walk",
+  "frame_id": "walk.01",
+  "frame_index": 1,
+  "image_sha256": "1eaf21df83ed49e490ceb7db1e1a14c58e5227bcb4f1fd79a70e8ad3ee7d38ad",
+  "identity_lock_sha256": "59d6b09622b19839b8c9342fb043965ea3f515c8979d769284d413f60a5f7e2d",
+  "generator_agent_id": "motionloom-generator-v1",
+  "verifier_id": "motionloom-separation-verifier-v1",
+  "result": {
+    "expected_action": "walk",
+    "top_competitor": "jump",
+    "margin": 0.39,
+    "threshold": 0.2,
+    "status": "pass",
+    "method": "independent-action-rubric-v1"
+  },
+  "result_sha256": "0ad134eda50c1d6a161d0395d03f43a51a15767665bc06b203564dd327ce0904",
+  "provenance": {
+    "kind": "separate_verifier_artifact",
+    "producer_id": "motionloom-independent-verifier-v1",
+    "run_id": "fixture-run-2026-08-22"
+  }
+}

package/examples/agent-consumer/asset-consistency/action-sequence/verifier-evidence/walk.02.json

@@ -0,0 +1,26 @@
+{
+  "schema_version": "0.1",
+  "contract": "action-separation-verifier-evidence",
+  "sequence_id": "hero-walk-v1",
+  "action_id": "walk",
+  "frame_id": "walk.02",
+  "frame_index": 2,
+  "image_sha256": "de88659cb7a57ae9c10b6e3e84e04e54bdc07e9971d5c42160a315d41b38fbc3",
+  "identity_lock_sha256": "59d6b09622b19839b8c9342fb043965ea3f515c8979d769284d413f60a5f7e2d",
+  "generator_agent_id": "motionloom-generator-v1",
+  "verifier_id": "motionloom-separation-verifier-v1",
+  "result": {
+    "expected_action": "walk",
+    "top_competitor": "attack",
+    "margin": 0.36,
+    "threshold": 0.2,
+    "status": "pass",
+    "method": "independent-action-rubric-v1"
+  },
+  "result_sha256": "529c083ac2959e80524234910750c015377d0d7be59b27ca5b14edf6585cd1cc",
+  "provenance": {
+    "kind": "separate_verifier_artifact",
+    "producer_id": "motionloom-independent-verifier-v1",
+    "run_id": "fixture-run-2026-08-22"
+  }
+}

package/examples/agent-consumer/asset-consistency/action-sequence/verifier-evidence/walk.03.json

@@ -0,0 +1,26 @@
+{
+  "schema_version": "0.1",
+  "contract": "action-separation-verifier-evidence",
+  "sequence_id": "hero-walk-v1",
+  "action_id": "walk",
+  "frame_id": "walk.03",
+  "frame_index": 3,
+  "image_sha256": "161d906dc850cd3d3ee970b97406fc36bcdf1c34222ac94171a05672bf64d957",
+  "identity_lock_sha256": "59d6b09622b19839b8c9342fb043965ea3f515c8979d769284d413f60a5f7e2d",
+  "generator_agent_id": "motionloom-generator-v1",
+  "verifier_id": "motionloom-separation-verifier-v1",
+  "result": {
+    "expected_action": "walk",
+    "top_competitor": "run",
+    "margin": 0.32999999999999996,
+    "threshold": 0.2,
+    "status": "pass",
+    "method": "independent-action-rubric-v1"
+  },
+  "result_sha256": "259be183f714d57cec7721127c0dfe61b552e8fbcbb189b782b662ed57ac138b",
+  "provenance": {
+    "kind": "separate_verifier_artifact",
+    "producer_id": "motionloom-independent-verifier-v1",
+    "run_id": "fixture-run-2026-08-22"
+  }
+}

package/examples/agent-consumer/asset-planning/pixellab-hero-256x448-request.json

@@ -0,0 +1,43 @@
+{
+  "schema_version": "0.1",
+  "request_id": "hero-attack-pixellab-256x448",
+  "asset_id": "hero.character.attack",
+  "asset_kind": "frame_sequence",
+  "target": {
+    "canvas": {"width": 256, "height": 448},
+    "frame_count": 8,
+    "fps": 8,
+    "alpha_mode": "straight",
+    "pixel_art": true,
+    "anchor": "footline"
+  },
+  "generation_policy": {
+    "frame_isolation": "required",
+    "allow_crop": false,
+    "allow_stretch": false,
+    "allow_silent_resize": false,
+    "allow_provider_batch_as_provisional": true,
+    "integer_scale_only": true
+  },
+  "project_context": {
+    "runtime": "custom-2d-game-runtime",
+    "framework": "canvas-sprite-runtime",
+    "existing_assets": ["examples/agent-consumer/asset-consistency/assets/hero-frame-00.png"],
+    "rig_requirements": ["preserve footline and pivot across frames", "keep action-specific frame identity"],
+    "provenance_requirements": ["generation receipt", "hash-bound export manifest", "human review"],
+    "validation_requirements": ["MotionLoom frame geometry", "MotionLoom action separation", "MotionLoom Dev Lab review"]
+  },
+  "actions": [
+    {
+      "action_id": "attack",
+      "positive_cues": ["forward sword swing", "weight shifts into strike", "weapon leads the silhouette"],
+      "negative_cues": ["walking cycle", "running cycle", "jumping", "idle stance"],
+      "frame_count": 8
+    }
+  ],
+  "references": [
+    {"id": "hero-identity", "role": "identity"},
+    {"id": "hero-style", "role": "style"},
+    {"id": "attack-pose-reference", "role": "pose"}
+  ]
+}

package/examples/agent-consumer/devlab-live-sprite/README.md

@@ -0,0 +1,30 @@
+# Canonical live Dev Lab sprite fixture
+
+This fixture is a small, hash-bindable sprite-sequence runtime for exercising the Dev Lab live path from a clean checkout. It deliberately contains two review-required actions, `idle` and `reverse`, so the Action Library coverage gate can be observed moving from `1/2` to `2/2`.
+
+The PNG files are deterministic repository fixtures. They are suitable for runtime-control and provenance-contract testing; they are **not** a claim about production art quality, identity fidelity, licensing, authorship or user approval.
+
+## Run the live binding check
+
+From the repository root:
+
+```bash
+python3 - <<'PY'
+import importlib.util
+import sys
+from pathlib import Path
+
+root = Path(".").resolve()
+sys.path.insert(0, str(root / "scripts"))
+path = root / "scripts/review-hook.py"
+spec = importlib.util.spec_from_file_location("motionloom_review_hook", path)
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+bundle = module.runtime_bundle(root / "examples/agent-consumer/devlab-live-sprite")
+assert bundle and bundle["mode"] == "sprite-sequence"
+assert bundle["animations"] == ["idle", "reverse"]
+print(bundle["bundle_sha256"])
+PY
+```
+
+To use the fixture in an actual review task, copy it into a rendered scene directory as `devlab-runtime.json` and run `motionloom review-hook prepare --task-dir <task-dir> --lab-url <dev-lab-url>`. Open the exact emitted candidate URL, inspect both actions, exercise play/pause/restart/seek/step/speed/loop, and obtain explicit user approval before any PR workflow.

package/examples/agent-consumer/devlab-live-sprite/devlab-runtime.json

@@ -0,0 +1,61 @@
+{
+  "schema_version": "1.0",
+  "mode": "sprite-sequence",
+  "files": [
+    "frames/idle-00.png",
+    "frames/idle-01.png",
+    "frames/idle-02.png",
+    "frames/reverse-00.png",
+    "frames/reverse-01.png",
+    "frames/reverse-02.png"
+  ],
+  "default_animation": "idle",
+  "animations": [
+    {
+      "id": "idle",
+      "fps": 6,
+      "frames": [
+        "frames/idle-00.png",
+        "frames/idle-01.png",
+        "frames/idle-02.png"
+      ],
+      "loop": true,
+      "review_required": true
+    },
+    {
+      "id": "reverse",
+      "fps": 6,
+      "frames": [
+        "frames/reverse-00.png",
+        "frames/reverse-01.png",
+        "frames/reverse-02.png"
+      ],
+      "loop": false,
+      "review_required": true
+    }
+  ],
+  "controls": {
+    "play": true,
+    "pause": true,
+    "restart": true,
+    "seek": true,
+    "step": true,
+    "speed": true,
+    "loop": true
+  },
+  "viewport": {
+    "canvas_width": 1920,
+    "canvas_height": 1920,
+    "pixel_art": false
+  },
+  "review_policy": {
+    "require_all_animations": true
+  },
+  "action_separation": {
+    "status": "pass",
+    "action_id": "sprite-sequence",
+    "frame_count": 6,
+    "passing_frame_count": 6,
+    "forbidden_action_ids": ["cross-action-mix"]
+  }
+}

package/examples/agent-consumer/frame-generation-lock/hero-walk-lock.json

@@ -0,0 +1,97 @@
+{
+  "schema_version": "0.2",
+  "lock_id": "hero-walk-v1",
+  "asset_identity": "character/hero-male",
+  "action_id": "walk",
+  "sequence_id": "hero-walk-v1",
+  "forbidden_action_ids": ["run", "jump", "attack"],
+  "action_manifest": "asset-consistency/action-sequence/hero-walk-action-manifest.json",
+  "action_contract": {
+    "positive_cues": [
+      "alternating contact and passing phases with an upright body",
+      "weight transfers along the shared footline with a natural counter-swing"
+    ],
+    "negative_cues": [
+      "no airborne jump, attack wind-up, or running stride",
+      "no casting, hurt, dodge, or second character silhouette"
+    ]
+  },
+  "reference": {
+    "image": "asset-consistency/assets/hero-frame-00.png",
+    "sha256": "75ce90653a01a23bcfab1aef83647d6364d3edbf6e4a44b84c635338c12b9248",
+    "role": "accepted_frame_anchor"
+  },
+  "canvas": {
+    "width": 8,
+    "height": 8,
+    "color_space": "srgb",
+    "alpha_mode": "straight"
+  },
+  "geometry": {
+    "center_x": 4,
+    "pivot": { "x": 4, "y": 7, "space": "pixels" },
+    "footline_px": 6,
+    "safe_rect": { "x": 1, "y": 0, "width": 6, "height": 7 },
+    "min_padding_px": 1,
+    "target_alpha_bbox": { "width": 4, "height": 5 },
+    "tolerances": {
+      "pivot_px": 0.01,
+      "footline_px": 0.01,
+      "bbox_width_px": 0,
+      "bbox_height_px": 0
+    }
+  },
+  "appearance": {
+    "preserve": [
+      "same character identity and silhouette",
+      "same camera and left-to-right orientation",
+      "same palette, outline weight and apparent scale"
+    ],
+    "forbid": [
+      "second character or neighboring pose",
+      "background, shadow, text, prop or crop",
+      "camera change, mirror, recolor or post-generation resize"
+    ],
+    "pixel_art": {
+      "enabled": true,
+      "nearest_neighbor_only": true
+    }
+  },
+  "source_policy": {
+    "isolated_frames": true,
+    "max_frames_per_image": 1,
+    "allow_pose_sheet": false,
+    "allow_post_resize": false,
+    "reuse_reference": true
+  },
+  "frames": [
+    {
+      "frame_id": "walk.00",
+      "pose": "Contact-right: right foot forward on the shared footline, left leg trailing, natural counter-swing.",
+      "output": "frame-generation-lock/generated/hero-walk-00.png"
+    },
+    {
+      "frame_id": "walk.01",
+      "pose": "Passing: one leg passes beneath the upright body with compact stride and natural counter-swing.",
+      "output": "frame-generation-lock/generated/hero-walk-01.png"
+    },
+    {
+      "frame_id": "walk.02",
+      "pose": "Contact-left: left foot forward on the shared footline, right leg trailing, natural counter-swing.",
+      "output": "frame-generation-lock/generated/hero-walk-02.png"
+    },
+    {
+      "frame_id": "walk.03",
+      "pose": "Passing complement: opposite leg passes beneath the upright body; preserve the same body scale and baseline.",
+      "output": "frame-generation-lock/generated/hero-walk-03.png"
+    }
+  ],
+  "postflight": {
+    "frame_geometry": "asset-consistency/hero-walk-frame-geometry.json"
+  },
+  "trust": {
+    "authority": "ai_generated",
+    "review_only": true,
+    "approval": false
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motionloom",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "type": "module",
   "packageManager": "pnpm@11.20.0",
   "description": "MotionLoom: project-aware animation Skill with Agent interoperability, graph, provenance, Motion IR, runtime telemetry, Visual Truth, Remediation Learning, DSSE-compatible signed attestation, external evidence verification and Dev Lab review.",
@@ -60,9 +60,18 @@
     "schemas/control-track.schema.json",
     "schemas/export-manifest.schema.json",
     "schemas/artifact-adapter-registry.schema.json",
+    "schemas/action-separation-verifier-evidence.schema.json",
+    "schemas/asset-generation-request.schema.json",
+    "schemas/asset-generation-plan.schema.json",
+    "schemas/asset-adaptation.schema.json",
+    "scripts/asset-adapt.mjs",
     "artifact-adapter-registry.json",
     "examples/agent-consumer/artifact-intake",
     "tests/scripts/test_artifact_intake.py",
+    "scripts/asset-generation-plan.py",
+    "examples/agent-consumer/asset-planning",
+    "tests/scripts/test_asset_generation_plan.py",
+    "tests/scripts/test_asset_adapt.py",
     "scripts/runtime-candidate.py",
     "schemas/runtime-candidate.schema.json",
     "examples/agent-consumer/runtime-candidate",
@@ -76,11 +85,11 @@
     "scripts/rive-package-gate.py",
     "schemas/rive-package-manifest.schema.json",
     "examples/agent-consumer/rive-package-gate",
-    "tests/scripts/test_rive_package_gate.py"
-    ,"scripts/build-ai-pilot.py"
-    ,"scripts/isolate-alpha-background.py"
-    ,"tests/scripts/test_ai_pilot_builder.py"
-    ,"tests/scripts/test_alpha_isolation.py"
+    "tests/scripts/test_rive_package_gate.py",
+    "scripts/build-ai-pilot.py",
+    "scripts/isolate-alpha-background.py",
+    "tests/scripts/test_ai_pilot_builder.py",
+    "tests/scripts/test_alpha_isolation.py"
   ],
   "keywords": [
     "animation",
@@ -133,6 +142,7 @@
     "test": "python3 tests/scripts/run_tests.py",
     "validate": "npm run quality:attestation",
     "doctor": "node bin/motionloom.mjs doctor --json",
+    "doctor:runtime": "node bin/motionloom.mjs doctor --runtime --json",
     "init": "node bin/motionloom.mjs init",
     "setup": "node bin/motionloom.mjs setup",
     "setup:dry": "node bin/motionloom.mjs setup --dry-run",
@@ -181,12 +191,16 @@
     "asset-provenance:check": "node bin/motionloom.mjs asset-provenance check --input examples/agent-consumer/ai-generated-pilot-provenance.json --root examples/agent-consumer --mode runtime --json",
     "asset:consistency": "node bin/motionloom.mjs asset-consistency validate --kind frame-geometry --input examples/agent-consumer/asset-consistency/hero-walk-frame-geometry.json --root examples/agent-consumer/asset-consistency --json",
     "asset:audit": "node bin/motionloom.mjs asset-consistency report --kind frame-geometry --input examples/agent-consumer/asset-consistency/hero-walk-frame-geometry.json --root examples/agent-consumer/asset-consistency --json",
+    "action:separation": "node bin/motionloom.mjs action-separation validate --input examples/agent-consumer/asset-consistency/action-sequence/hero-walk-action-manifest.json --root examples/agent-consumer/asset-consistency --json",
+    "asset:plan": "node bin/motionloom.mjs asset-generation-plan plan --request examples/agent-consumer/asset-planning/pixellab-hero-256x448-request.json --project-root . --json",
+    "asset:adapt:smoke": "node bin/motionloom.mjs asset-adapt pad --input examples/agent-consumer/asset-consistency/assets/hero-frame-00.png --output /tmp/motionloom-adapt-smoke.png --width 16 --height 16 --anchor center --report /tmp/motionloom-adapt-smoke.json --json",
+    "frame:preflight": "node bin/motionloom.mjs frame-set-preflight --input examples/agent-consumer/asset-consistency/hero-walk-frame-geometry.json --root examples/agent-consumer/asset-consistency --action-manifest examples/agent-consumer/asset-consistency/action-sequence/hero-walk-action-manifest.json --json",
     "artifact:intake": "node bin/motionloom.mjs artifact-intake intake --root . --registry artifact-adapter-registry.json --receipt examples/agent-consumer/artifact-intake/hero-motion-receipt.json --controls examples/agent-consumer/artifact-intake/hero-motion-controls.json --export-manifest examples/agent-consumer/artifact-intake/hero-motion-export.json --json",
     "runtime:candidate": "node bin/motionloom.mjs runtime-candidate validate --root . --input examples/agent-consumer/runtime-candidate/hero-walk-candidate.json --json",
     "rig:compatibility": "node bin/motionloom.mjs rig-compatibility validate --root . --registry rig-adapter-registry.json --input examples/agent-consumer/rig-compatibility/hero-walk-fixture-rig.json --json",
-    "rive:gate": "node bin/motionloom.mjs rive-package-gate --help"
-    ,"pilot:build": "node bin/motionloom.mjs pilot-build --help"
-    ,"alpha:isolate": "node bin/motionloom.mjs alpha-isolate --help"
+    "rive:gate": "node bin/motionloom.mjs rive-package-gate --help",
+    "pilot:build": "node bin/motionloom.mjs pilot-build --help",
+    "alpha:isolate": "node bin/motionloom.mjs alpha-isolate --help"
   },
   "dependencies": {
     "@lottiefiles/dotlottie-web": "^0.79.0",

package/references/multi-frame-asset-generation.md

@@ -0,0 +1,144 @@
+# Multi-frame asset generation discipline
+
+This contract applies whenever MotionLoom or an Agent creates two or more source frames for the same character, object, effect or other frame-based animation. It is automatic: the user should not have to ask for consistent frame geometry, isolated source frames or atlas hygiene.
+
+## Plan the provider before generating
+
+Before calling PixelLab, ImageGen, ChatGPT or another provider, create a provider-neutral request that describes the real runtime target. The request must include the target canvas, frame count, alpha mode, pixel-art policy, action cues and whether one source frame per request is required:
+
+```bash
+motionloom asset-generation-plan plan \
+  --request examples/agent-consumer/asset-planning/pixellab-hero-256x448-request.json \
+  --project-root . --json
+```
+
+Treat the result as a MotionLoom recommendation, not an approval. The planner first assesses the project/task, then separates `recommendation_status` from `execution_status`. A provisional or scaffold route may remain a useful normal-planning recommendation when its project fit is strong; strict execution still requires the active execution policy. User preference is visible and may influence ranking, but cannot override a hard incompatibility. For example, PixelLab animation tools documented with square canvases can be used as a provisional source for a `256x448` target only through an explicit transparent-padding plan and post-export action/frame validation; the planner must not silently crop, stretch, or claim that batch output satisfies per-frame isolation. If no route is execution-eligible, normal planning should still expose safe provisional/manual options while strict mode fails closed.
+
+The registry is provider-neutral and metadata-driven. A provider adapter remains `scaffold_only` until real export bytes, generation receipt, target-runtime evidence and human review have been recorded. Availability is separate from registry existence: an unknown or unavailable route may be shown as a MotionLoom option, but the Agent must resolve connectivity before execution. Bearer tokens belong in the connector/secret layer and never in requests, prompts, receipts or project manifests.
+
+## Default source policy
+
+Generated source frames are **isolated-frame assets**, not a pose sheet.
+
+- Generate exactly one animation source frame per image/canvas by default.
+- For long actions (including actions with six or more frames), never ask an image generator for one contact sheet, sprite sheet or multi-pose canvas and then crop the poses out as production source frames.
+- Do not pack an atlas or sprite sheet until every isolated source frame has passed identity and frame-geometry validation.
+- Imported third-party atlases may still use the atlas contract; this rule is about Agent-generated source material.
+
+If a generator cannot preserve isolated source canvases reliably, regenerate in smaller isolated calls or use provider outputs that are already separate files. Do not convert one contaminated multi-pose canvas into accepted source frames merely because crops can be extracted from it.
+
+This avoids neighboring poses leaking into a crop, shared-canvas bleed, accidental partial limbs from adjacent frames and ambiguous ownership of opaque pixels.
+
+## Lock geometry before the second frame
+
+Before generating frame 2, establish one canonical geometry lock from the accepted identity/reference frame and keep it unchanged for the rest of the action:
+
+- exact canvas width and height;
+- transparent alpha mode and color space;
+- camera and left/right orientation;
+- target apparent character scale;
+- pivot point;
+- baseline / footline;
+- safe rectangle and transparent guard band;
+- palette/style/identity reference;
+- frame naming and action order.
+
+Create or update the matching `action-set` and `frame-geometry` contracts before continuing the sequence. The first accepted frame is the geometry anchor; later poses may move limbs, but they must not silently change canvas size, camera, character scale, pivot or baseline.
+
+For AI-generated frames, every subsequent generation request should carry the same locked identity reference and geometry requirements. When the image tool can accept an image reference, reuse the accepted identity/anchor frame rather than relying on prose alone.
+
+## Frame Generation Lock
+
+Do not rely on the Agent remembering the same geometry prose across many provider calls. Persist the generation-side constraints in `frame-generation-lock.json` using `schemas/frame-generation-lock.schema.json`.
+
+The lock binds:
+
+- the exact identity/accepted-frame reference path and SHA-256;
+- canvas dimensions, color space and alpha mode;
+- center, pivot, footline, safe rectangle and minimum transparent padding;
+- target measured alpha-bounds plus permitted width/height drift;
+- appearance features that must be preserved and changes that are forbidden;
+- a hard source policy of one isolated frame per image, no pose sheet and no silent post-generation resize;
+- every `frame_id`, its pose intent and its unique PNG output path;
+- the post-generation `frame-geometry` contract used by deterministic preflight;
+- a review-only trust boundary with `approval: false`.
+
+Before a provider call, validate the lock and compose the exact frame instruction from it:
+
+```bash
+motionloom frame-generation-lock validate \
+  --input src/output/<scene>/<action>-frame-generation-lock.json \
+  --root src/output/<scene> --json
+
+motionloom frame-generation-lock compose \
+  --input src/output/<scene>/<action>-frame-generation-lock.json \
+  --root src/output/<scene> --frame-id <action.frame-id> --json
+```
+
+For batch planning, `compose-all` emits one independent instruction per frame while preserving the same lock hash and reference hash. It does **not** authorize asking a provider for one multi-frame canvas; each returned instruction still represents one isolated source image. If the selected provider only emits a batch animation, record it as provisional and create independent envelopes after export; do not promote it to an isolated-source pass automatically.
+
+If the reference bytes change, an output path escapes the asset root, two frames target the same PNG, the lock permits a pose sheet/post-resize, or the trust boundary is weakened, validation fails closed before generation.
+
+## Keep action identity across isolated frames
+
+Isolated canvases prevent neighboring pixels from leaking into a crop, but they do not prove that a frame belongs to the intended action. For every multi-frame action, use an action-scoped manifest with one immutable `sequence_id`, `action_id`, `identity_lock_sha256`, ordered `frame_index` values and explicit `forbidden_action_ids`. Each image must have a frame envelope binding those fields to the image SHA-256.
+
+The action verifier must record `expected_action`, `top_competitor`, `margin`, `threshold` and `status`. A generator-created envelope is only declared evidence; independent verification requires a separate hash-bound verifier artifact. A low margin, competitor mismatch or missing verifier provenance is **quarantined**, not silently relabeled or moved to another action. Validate the manifest before packing:
+
+```bash
+motionloom action-separation validate \\
+  --input src/output/<scene>/<action>-action-manifest.json \\
+  --root src/output/<scene> --json
+
+motionloom frame-set-preflight \\
+  --input src/output/<scene>/<action>-frame-geometry.json \\
+  --root src/output/<scene> \\
+  --action-manifest src/output/<scene>/<action>-action-manifest.json --json
+```
+
+A contact sheet may be generated after isolated frames pass as a review projection, but it is never the production source. When one frame is ambiguous, regenerate that frame from the accepted anchor and the same action lock; do not auto-move it, use a neighboring action as a reference, or let the agent infer its action from the filename.
+
+See [`docs/ACTION-SEPARATION.md`](../docs/ACTION-SEPARATION.md) for the manifest/envelope contract and quarantine policy.
+
+## Validate incrementally
+
+Do not generate the complete action and only inspect it at the end. After each candidate frame:
+
+1. verify the image is an isolated source canvas rather than a shared pose sheet;
+2. verify exact canvas dimensions and alpha transparency;
+3. measure the real alpha bounding box from pixels;
+4. compare apparent size against the anchor within the declared `bbox_drift_tolerance_px`;
+5. verify pivot and footline tolerance;
+6. verify the alpha bounding box remains inside `safe_rect` with the declared `bleed_margin_px` guard band;
+7. reject unexpected opaque contamination;
+8. only then accept the frame and continue.
+
+Use:
+
+```bash
+motionloom frame-set-preflight \
+  --input src/output/<scene>/<action>-frame-geometry.json \
+  --root src/output/<scene> --json
+```
+
+The preflight is intentionally stricter than a visual warning: shared source images, non-isolated frame rectangles, scale drift beyond the declared tolerance, guard-band violations, pivot/footline drift, hash mismatch or other deterministic frame-geometry failures block the sequence.
+
+If one frame fails, regenerate or repair **that frame only** using the same generation lock. Do not silently rescale every previously accepted frame to match a bad frame, and do not weaken tolerances merely to make the set pass.
+
+## Apparent-size consistency
+
+Equal canvas dimensions are not enough. A 1920 × 1920 PNG can still contain a character that is 20% smaller than the previous frame. MotionLoom therefore treats measured alpha-bounds drift as a real source defect when it exceeds the declared tolerance.
+
+Pose motion can legitimately change the bounding box, so choose a tolerance that allows expected limb extension while preventing whole-character zoom drift. For actions with large reaches, jumps or weapons, lock the body pivot/footline and define a safe rectangle large enough for those poses instead of changing the character scale between frames.
+
+For pixel art, any intentional normalization step must preserve nearest-neighbor pixel density and the locked pivot/baseline. Large scale corrections should trigger regeneration rather than interpolation.
+
+## Packing happens last
+
+Only after every source frame passes preflight may the Agent build a sprite sheet or atlas. The packed result must then pass the atlas contract: no region overlap, no opaque pixels outside declared regions when required, explicit padding/extrusion, and no ambiguous neighboring-frame bleed.
+
+Source-frame acceptance and atlas acceptance are separate gates. A clean atlas cannot repair inconsistent source-frame scale, and consistent source frames do not prove the packed atlas is clean.
+
+## Agent decision rule
+
+When the user asks for an animation such as idle, walk, run, attack, hurt, jump or any project-defined multi-frame action, the Agent should apply this contract automatically. Do not ask the user whether they want frame consistency checks or a generation lock; they are part of the default MotionLoom workflow. Only ask the user when a genuine artistic decision is required, such as choosing between materially different silhouettes or motion intent.

package/schemas/action-separation-verifier-evidence.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/action-separation-verifier-evidence.schema.json",
+  "title": "MotionLoom Action Separation Verifier Evidence",
+  "description": "Separate verifier artifact bound to one frame result. Hashes verify binding integrity, not the truthfulness of an asserted producer identity.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "contract", "sequence_id", "action_id", "frame_id", "frame_index", "image_sha256", "identity_lock_sha256", "generator_agent_id", "verifier_id", "result", "result_sha256", "provenance"],
+  "properties": {
+    "schema_version": {"const": "0.1"},
+    "contract": {"const": "action-separation-verifier-evidence"},
+    "sequence_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,95}$"},
+    "action_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+    "frame_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+    "frame_index": {"type": "integer", "minimum": 0},
+    "image_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+    "identity_lock_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+    "generator_agent_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+    "verifier_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+    "result": {
+      "type": "object", "additionalProperties": false,
+      "required": ["expected_action", "top_competitor", "margin", "threshold", "status", "method"],
+      "properties": {
+        "expected_action": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+        "top_competitor": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+        "margin": {"type": "number", "minimum": 0},
+        "threshold": {"type": "number", "minimum": 0},
+        "status": {"enum": ["pass", "quarantined"]},
+        "method": {"type": "string", "minLength": 1}
+      }
+    },
+    "result_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+    "provenance": {
+      "type": "object", "additionalProperties": false,
+      "required": ["kind", "producer_id", "run_id"],
+      "properties": {
+        "kind": {"const": "separate_verifier_artifact"},
+        "producer_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+        "run_id": {"type": "string", "minLength": 1}
+      }
+    }
+  }
+}

package/schemas/action-sequence-manifest.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/action-sequence-manifest.schema.json",
+  "title": "MotionLoom Action Sequence Manifest",
+  "description": "Manifest binding for isolated frame sequences and explicitly classified action-separation evidence.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "sequence_id", "asset_identity", "action_id", "identity_lock_sha256", "generator_agent_id", "forbidden_action_ids", "actions", "frames", "status", "approval"],
+  "properties": {
+    "schema_version": {"const": "0.2"},
+    "sequence_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,95}$"},
+    "asset_identity": {"type": "string", "minLength": 1},
+    "action_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+    "identity_lock_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+    "generator_agent_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+    "forbidden_action_ids": {
+      "type": "array", "minItems": 1, "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"}
+    },
+    "actions": {
+      "type": "array", "minItems": 2,
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["action_id", "positive_cues", "negative_cues"],
+        "properties": {
+          "action_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+          "positive_cues": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+          "negative_cues": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}
+        }
+      }
+    },
+    "frames": {
+      "type": "array", "minItems": 2,
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["frame_index", "frame_id", "image", "envelope"],
+        "properties": {
+          "frame_index": {"type": "integer", "minimum": 0},
+          "frame_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"},
+          "image": {"type": "string", "pattern": "^.+\\.png$"},
+          "envelope": {"type": "string", "pattern": "^.+\\.json$"}
+        }
+      }
+    },
+    "status": {"enum": ["review_required", "quarantined"]},
+    "approval": {"const": false}
+  }
+}