motionloom 2.5.1 → 2.6.1

package/AGENTS.md

@@ -12,6 +12,10 @@ motionloom discovery check --root . --json
 
 Then follow the lifecycle in `SKILL.md`. The repository may coordinate Lottie, dotLottie, Rive, GSAP and Framer Motion, but it does not replace those runtimes. Render evidence, provenance, semantic checks and browser review are separate states. **Do not infer user approval from a passing heuristic, signature, screenshot or quality gate.**
 
+For generated multi-frame animation assets, read [`references/multi-frame-asset-generation.md`](references/multi-frame-asset-generation.md) **before generating frame 2**. Apply it automatically without waiting for the user to ask: keep generated source frames isolated, lock canvas/scale/pivot/baseline from the accepted anchor frame, and pack sprite sheets/atlases only after the isolated frames pass. Before generating any later pose, create or load a `schemas/frame-generation-lock.schema.json` contract and run `motionloom frame-generation-lock validate`; compose each provider-facing frame instruction from that same lock with `motionloom frame-generation-lock compose`. After each generated frame, update the bound frame-geometry evidence and run `motionloom frame-set-preflight`. Six-frame-or-longer actions must never use one generated multi-pose sheet as their production source.
+
+For Dev Lab work, also read [`docs/CHECKLIST.md`](docs/CHECKLIST.md) and [`docs/DEV-LAB-RUNTIME.md`](docs/DEV-LAB-RUNTIME.md). A runnable animation candidate should expose the live runtime descriptor/controls defined there; 0/50/100 PNGs remain evidence/fallback and must not be presented as an interactive runtime when live playback is available.
+
 ## Source of truth
 
 Do not duplicate or edit Agent-specific copies of the workflow. If this router conflicts with `SKILL.md`, the canonical root Skill and machine-readable schemas win. Use `references/agent-interoperability.md` for discovery details and `docs/AGENT-INTEGRATION.md` for installation examples.

package/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable MotionLoom changes are documented here. The project follows semantic
 
 ## [Unreleased]
 
+## [2.6.1] - 2026-08-21
+
+### Added
+
+- Add a machine-readable `frame-generation-lock` contract that hash-binds the accepted identity/reference and locks canvas, alpha/color space, apparent size, pivot, footline, safe rectangle, transparent padding, camera/orientation and per-frame output identity before later frames are generated.
+- Add provider-neutral `motionloom frame-generation-lock validate|compose|compose-all` commands and public Agent routing so every pose instruction is deterministically rebuilt from the same lock instead of relying on repeated prose prompts.
+- Expose the strict generated `motionloom frame-set-preflight` command through the public CLI for post-generation alpha-bounds, scale, pivot/footline, guard-band, contamination and source-isolation checks.
+
+### Hardened
+
+- Default generated multi-frame source policy to one isolated PNG per frame; six-frame-or-longer actions must not use one generated pose sheet/contact sheet as production source material.
+- Fail closed on stale reference hashes, duplicate frame outputs, pose-sheet policy violations, path escape, shared/non-isolated sources, post-generation resize and measured apparent-size drift beyond tolerance.
+- Keep atlas packing as a later, separate gate: a clean atlas cannot repair inconsistent or contaminated source frames.
+
+### Verified
+
+- Dedicated Frame Generation Lock CI validates the public CLI, provider instruction composition and strict post-generation preflight.
+- Pull request #18 passed MotionLoom Quality, Security Analysis, Documentation and Package Hygiene, plus the dedicated Frame Generation Lock workflow before merge.
+
+### Boundary
+
+- Frame locks, generated prompts, SHA-256 bindings, preflight passes and atlas checks are deterministic evidence only. They never grant artist authorship, production eligibility, runtime approval, licence authority or user approval.
+
+See the [2.6.1 release note](docs/releases/2.6.1.md) for the generation/preflight contract and migration guidance.
+
+## [2.6.0] - 2026-08-21
+
+### Added
+
+- Upgrade Dev Lab from checkpoint-oriented review to an interactive live-runtime workbench with Play, Pause, Restart, scrub, frame-step, speed and loop controls plus fullscreen, zoom/fit, background, grid, bounds, baseline and pivot inspection tools.
+- Discover arbitrary project-defined actions from `devlab-runtime.json` instead of hard-coding `idle`, `walk`, `run` or `attack`; add groups/categories, tags, search, collapsible sections and review-state filters for large action libraries.
+- Add the hash-bound `devlab-state-machine.json` contract, legal transition controls, transition history and bounded multi-step review sequences for flows such as `Idle -> Run -> Attack -> Hurt -> Idle`.
+- Add strict iframe `runtime-trigger` support through `triggerTransition(request)` and portable `select-animation` transitions for sprite/clip runtimes.
+
+### Hardened
+
+- Bind declared live-runtime and state-machine bytes into the browser-review candidate so runtime drift invalidates stale review links.
+- Fail closed on unsafe/missing runtime paths, duplicate animation ids, mismatched candidate/runtime action sets and unsupported runtime triggers; a failed live runtime remains inspectable only through explicit captured-evidence fallback and cannot be approved.
+- Keep Action Library search/group/filter presentation independent from review coverage so hidden required actions do not disappear from the approval gate.
+- Count runtime-trigger transitions only after the target state is observable; never silently replace a failed runtime state transition with a clip switch.
+- Ship `runtime-bridge.js` with the npm package so installed-package iframe/state-machine review uses the same bridge as the repository harness.
+
+### Verified
+
+- Dev Lab CI covers deterministic snapshots, live sprite and iframe runtimes, a four-action interactive dogfood candidate, a twelve-action Action Library fixture, sprite state transitions, real iframe runtime-trigger transitions and browser-security smoke tests.
+- Pull requests #13, #14 and #15 passed Dev Lab Build, MotionLoom Quality, Security Analysis and Documentation and Package Hygiene before this release candidate was prepared.
+
+### Boundary
+
+- Runtime playback, action/transition/sequence coverage, successful triggers, hashes, snapshots and automated checks are evidence only. `approved` remains an explicit user decision bound to the exact candidate.
+- MotionLoom does not promote AI-generated material to artist-authored or production-approved status, and this release does not change the unsigned source-alpha status of the Apple companion apps.
+
+See the [2.6.0 release note](docs/releases/2.6.0.md) for the Dev Lab runtime contract, verification scope and trust boundaries.
+
 ## [2.5.1] - 2026-08-18
 
 ### Fixed
@@ -148,9 +202,12 @@ See the [2.0.0 release note](docs/releases/2.0.0.md).
 
 The 1.5.0–1.9.0 milestones established runtime evidence, browser review, Intelligence Core, semantic lint, continuity, telemetry and trust-boundary hardening. Their detailed notes are available in [`docs/releases/`](docs/releases/).
 
-[2.2.0]: docs/releases/2.2.0.md
+[2.6.1]: docs/releases/2.6.1.md
+[2.6.0]: docs/releases/2.6.0.md
+[2.5.1]: docs/releases/2.5.1.md
 [2.5.0]: docs/releases/2.5.0.md
 [2.4.0]: docs/releases/2.4.0.md
 [2.3.0]: docs/releases/2.3.0.md
+[2.2.0]: docs/releases/2.2.0.md
 [2.1.0]: docs/releases/2.1.0.md
 [2.0.0]: docs/releases/2.0.0.md

package/README.md

@@ -15,7 +15,7 @@ MotionLoom is an independent open-source Agent Skill for building UI motion, Lot
 
 > **MotionLoom is not an auto-approval layer.** A valid signature, a passing heuristic, or a successful render proves only the contract it checks. Visual quality, intent, accessibility and PR authorization remain reviewable human decisions.
 
-> **Release posture:** MotionLoom 2.5.1 hardens installed-package onboarding, Dev Lab browser review, runtime-output cleanup and consumer-package acceptance. The native macOS/iOS review app remains an unsigned source alpha under `apps/apple/`; the npm package remains the cross-platform Node/Python Skill and documentation surface. Verify npm/GitHub publication metadata separately; passing evidence never implies user approval.
+> **Release posture:** MotionLoom 2.6.1 keeps the interactive Dev Lab from 2.6.0 and adds a proactive Frame Generation Lock for generated multi-frame animation assets. Agents now hash-bind one accepted identity/reference, compose one isolated provider instruction per frame from locked canvas/scale/pivot/footline geometry, and run measured frame-set preflight before atlas packing. The native macOS/iOS review app remains an unsigned source alpha under `apps/apple/`; the npm package remains the cross-platform Node/Python Skill and documentation surface. Generation, runtime and validation evidence never imply artist authorship or user approval. See the [2.6.1 release note](docs/releases/2.6.1.md).
 
 ## Why MotionLoom
 
@@ -33,7 +33,7 @@ MotionLoom turns that fragile sequence into a bounded production system. Its dur
 | **Asset consistency** | Measured multi-frame geometry, pivot/footline stability, atlas boundaries and layered-map contracts | Treat a heuristic warning or deterministic pass as artist approval or production authorization |
 | **Runtime truth** | Lottie/dotLottie, SVG cutout rig, Rive, GSAP and Framer Motion evidence from real runtime paths | Call scaffold, static validation or a heuristic score visual approval |
 | **Agent intelligence** | Project graph, provenance, Motion IR, replay, semantic lint, continuity and fix plan | Convert confidence, benchmark output or warnings into approval |
-| **Human review** | Exact candidate URL, frame checkpoints, checklist, review artifact and handoff report in Dev Lab | Confirm, push or open a PR without explicit user authorization |
+| **Human review** | Exact candidate URL, live playback, Action Library, state/transition testing, deterministic checkpoints, checklist and review artifact in Dev Lab | Confirm, push or open a PR without explicit user authorization |
 
 ## The production contract
 
@@ -55,6 +55,16 @@ flowchart LR
 
 Every handoff is machine-readable. The typical bundle under `artifacts/<task-id>/` includes the task ledger, context hash, motion spec, manifest, runtime snapshots, telemetry, project graph, provenance, lint and continuity reports, fix plan, browser-review candidate, review decision, execution report and next-Agent handoff.
 
+## Interactive Dev Lab
+
+Dev Lab is designed to let the user inspect the same candidate behavior that MotionLoom is claiming as runtime evidence, rather than treating three screenshots as an animation review surface. A live candidate can expose Play, Pause, Restart, scrub, frame-step, speed and loop controls together with fullscreen, zoom/fit, background, grid, bounds, baseline and pivot inspection tools. Deterministic snapshots remain available as captured evidence and compatibility fallback.
+
+Actions are data-driven. `devlab-runtime.json` may declare any project-specific action vocabulary and optional groups/tags, so a character can expose `Idle`, `Walk`, `Run`, `Attack`, `Jump`, skills, reactions, emotes or domain-specific clips without a MotionLoom UI change. Dev Lab turns large sets into a searchable/filterable Action Library while keeping review coverage independent from presentation filters.
+
+When interaction between actions matters, an optional hash-bound `devlab-state-machine.json` can declare states, legal transitions and review sequences such as `Idle -> Run -> Attack -> Hurt -> Idle`. Sprite/clip candidates can use portable `select-animation` transitions; iframe runtimes can implement strict `runtime-trigger` transitions through the runtime bridge. A runtime trigger counts as inspected only after the target state is observable, and unsupported triggers are never silently replaced by clip switches.
+
+Review policy may require selected actions, transitions or sequences to be inspected before approval becomes available. **Completing playback or transition coverage does not approve the candidate.** Request Changes remains available and `approved` is still an explicit user decision. See the [Dev Lab live runtime contract](docs/DEV-LAB-RUNTIME.md) and [2.6.0 release note](docs/releases/2.6.0.md).
+
 ## Quick start
 
 ### Start once. Continue your normal work.
@@ -175,7 +185,7 @@ MotionLoom keeps distinct layers distinct:
 | Provenance | Which source/material/product bytes were used and how they hash | That the source is appropriate beyond the declared authority/license contract |
 | Semantic lint and benchmark | Bounded rule findings, risk signals and performance measurements | Human visual quality or intent acceptance |
 | Signed attestation | A trusted signer signed the same task-bound hashes under the policy | Reviewer consent, accessibility approval or PR authorization |
-| Dev Lab review | The user saw the exact candidate and recorded a decision | A future candidate is automatically approved |
+| Dev Lab review | The user saw and interacted with the exact candidate and recorded a decision | A future candidate is automatically approved |
 
 `approval` remains `false` in attestation and verifier artifacts. The default PR mode is local-only (`OPEN_PR=0`); commit, push and pull-request operations remain explicit side effects.
 
@@ -307,6 +317,7 @@ Read [the Apple workspace guide](apps/apple/README.md), [the contract boundary](
 | Install or understand the full lifecycle | [SKILL.md](SKILL.md) |
 | Choose a runtime | [Framework selection](docs/FRAMEWORK-SELECTION.md) and [runtime capability reference](references/runtime-capability.md) |
 | Run a review-ready scene | [Production checklist](docs/CHECKLIST.md) and [browser review contract](references/browser-review-contract.md) |
+| Configure live actions, playback or state transitions in Dev Lab | [Dev Lab live runtime contract](docs/DEV-LAB-RUNTIME.md) and [2.6.0 release note](docs/releases/2.6.0.md) |
 | Understand Agent intelligence | [Intelligence Core](references/intelligence-core.md) and [roadmap](ROADMAP.md) |
 | Run labeled project evaluation | [Project corpus manifest](tests/evals/project-corpus.json) and `python3 scripts/eval-projects.py --allow-insufficient` |
 | Understand trust boundaries | [Signed attestation](references/signed-attestation.md) and [2.0.0 release note](docs/releases/2.0.0.md) |
@@ -339,17 +350,17 @@ The GitHub Actions workflow is designed to run the Project Memory and CLI contra
 
 ## Automated CI/CD
 
-MotionLoom separates verification from publication. Pull requests and pushes to `main` trigger the quality, documentation, security and relevant Dev Lab workflows when their path filters match. A weekly Dependabot job proposes dependency updates for the root package, Dev Lab and GitHub Actions. The npm release workflow is manual only, protected by the `npm-release` environment, and requires the maintainer to choose the distribution tag; GitHub release creation is an explicit input rather than an automatic side effect.
+MotionLoom separates verification from publication. Pull requests and pushes to `main` trigger the quality, documentation, security and relevant Dev Lab workflows when their path filters match. A weekly Dependabot job proposes dependency updates for the root package, Dev Lab and GitHub Actions. The npm release workflow is manual only, protected by the `npm-release` environment, and requires the maintainer to choose the distribution tag; GitHub release creation is a dispatch input rather than a consequence of ordinary CI.
 
 | Workflow | Trigger | Responsibility |
 |---|---|---|
 | `quality.yml` | Pull request, `main`, manual | Cross-platform memory/CLI matrix and full evidence-aware quality suite |
 | `docs.yml` | Documentation/package changes, `main`, manual | Internal links, metadata, workflow safety, Skill Doctor and npm tarball inspection |
 | `security.yml` | Pull request, `main`, weekly schedule, manual | Dependency review and CodeQL for JavaScript/Python |
-| `devlab.yml` | `dev-lab/**` changes, `main`, manual | Build and retain the browser review workbench artifact |
-| `release.yml` | Manual dispatch only | Regression, npm publish with provenance and optional GitHub release |
+| `devlab.yml` | `dev-lab/**` changes, `main`, manual | Build and retain the interactive browser review workbench artifacts and smoke evidence |
+| `release.yml` | Manual dispatch only | Regression, installed-package smoke, release traceability, npm Trusted Publishing with provenance and optional GitHub Release |
 
-To enable npm publication, configure a protected GitHub environment named `npm-release` and either add the `NPM_TOKEN` environment secret or configure npm trusted publishing for this repository. Each manual run must provide `release_version`; the workflow verifies package/changelog/release-note alignment before publishing. The workflow never runs on a pull request and never changes MotionLoom's user-review or approval contract.
+To enable npm publication, configure the protected GitHub environment named `npm-release` and configure npm Trusted Publishing for this repository/workflow/environment. No long-lived `NPM_TOKEN` is required or expected by the current release workflow. Each manual run provides `release_version`; the workflow verifies package/changelog/release-note alignment before publishing. The workflow never runs on a pull request and never changes MotionLoom's user-review or approval contract.
 
 ## License
 

package/SECURITY.md

@@ -4,10 +4,9 @@
 
 | Version | Security fixes |
 |---|---|
-| `2.2.x` | Release candidate; support begins on publication |
-| `2.1.x` | Current published line; supported until 2.2.0 publication |
-| `2.0.x` | Best effort while upgrading |
-| `<2.0.0` | Not supported |
+| `2.6.x` | Current supported line |
+| `2.5.x` | Previous line; security fixes are best effort while consumers upgrade |
+| `2.4.x` and earlier | Upgrade recommended; no routine support commitment |
 
 ## Reporting a vulnerability
 
@@ -19,10 +18,10 @@ If private reporting is unavailable, open a minimal issue titled **Security cont
 
 MotionLoom can read and write files in the host project, invoke runtimes and prepare Git operations. The npm CLI does not silently push, open a PR or turn evidence into approval. Treat project context, artifact bundles, trust policies, private keys and browser sessions as sensitive. Keep managed signing keys outside the repository and never use CI fixture keys as production trust anchors.
 
-Path guards, task identity, source/manifest hashes, evidence freshness, signer policy and approval invariants are security-relevant contracts. Report any bypass that allows cross-project memory, cross-task evidence, stale runtime output or unreviewed Git side effects.
+Path guards, task identity, source/manifest hashes, runtime bundle hashes, state-machine bindings, evidence freshness, signer policy and approval invariants are security-relevant contracts. Report any bypass that allows cross-project memory, cross-task evidence, stale runtime output, undeclared runtime/state-machine bytes or unreviewed Git side effects.
 
-See the [signed attestation reference](references/signed-attestation.md), [browser review contract](references/browser-review-contract.md) and [2.2.0 release note](docs/releases/2.2.0.md) for the current threat model and limitations.
+See the [signed attestation reference](references/signed-attestation.md), [browser review contract](references/browser-review-contract.md), [Dev Lab runtime contract](docs/DEV-LAB-RUNTIME.md) and [2.6.0 release note](docs/releases/2.6.0.md) for the current trust boundaries and limitations.
 
 ## CI/CD controls
 
-GitHub Actions workflows default to read-only repository permissions. The publication workflow is manual-only, uses the protected `npm-release` environment, requests OIDC only for the release job, and keeps npm credentials in environment secrets. Dependency updates are proposed by Dependabot as pull requests rather than applied directly to `main`.
+GitHub Actions workflows default to read-only repository permissions. The publication workflow is manual-only, uses the protected `npm-release` environment, requests OIDC only for the release job and publishes through npm Trusted Publishing without a long-lived `NPM_TOKEN`. npm provenance is generated by the trusted publication path. Dependency updates are proposed by Dependabot as pull requests rather than applied directly to `main`.

package/SKILL.md

@@ -7,7 +7,7 @@ description: >-
   validate, review, or deliver animation inside an existing project.
 license: MIT
 metadata:
-  version: "2.5.1"
+  version: "2.6.1"
   target_frameworks: "lottie,dotlottie,rive,gsap,framer-motion,spine,threejs"
   verified_runtimes: "lottie-json,dotlottie-package,svg-cutout-rig,rive,gsap,framer-motion"
 ---
@@ -30,18 +30,18 @@ For Agent or CI composition, consume JSON and preserve the exit code. If the pro
 2. **Plan** — classify the animation, select a framework, and generate a context-bound `motion-spec.json` with timing, easing, loop, accessibility, performance and source authority.
 3. **Source** — resolve an authoritative asset from the project or `assets/library/`. Record attribution, license and checksum in the scene manifest's required `source_binding`; the binding's SHA-256 must match the bytes referenced by `manifest.file`. Do not promote an unknown or placeholder asset to production.
 3a. **Classify asset provenance** — create or load `asset-provenance.json` with `motionloom asset-provenance`. Treat Agent-created material as ingestible only when its origin, generator task, license, file hash and derivation chain are explicit. Use `code_authored` for an authored runtime scene such as GSAP or Framer Motion; it may be runtime-tested and marked `review_required`, but never self-promotes to production eligibility or approval. `ai_generated` may be runtime-tested but is never production-eligible; `ai_assisted` requires human sign-off; `artist_authored` and `production_approved` cannot be self-asserted by an Agent or quality gate. Use `check --mode runtime` for candidate ingest and `check --mode production` only for a full production gate.
-3b. **Compile asset consistency** — when a task contains multi-frame character actions, sprite sheets/atlases or layered maps, create the matching identity, action-set, frame-geometry, atlas and layered-map contracts from `schemas/`. Run `motionloom asset-consistency validate --kind <identity|action-set|frame-geometry|atlas|layered-map> --input <contract> --root <asset-root> --json`. The compiler measures actual PNG alpha bounds, pivot/footline/bbox drift, frame and atlas contamination, region overlap, parallax/z-order, tile seams and camera-safe bounds. A pass is deterministic contract evidence only; it never upgrades provenance, artist authority, production eligibility or human approval.
+3b. **Compile asset consistency and lock multi-frame generation** — when a task contains multi-frame character actions, sprite sheets/atlases or layered maps, create the matching identity, action-set, frame-geometry, atlas and layered-map contracts from `schemas/`. For Agent-generated frame sequences, read `references/multi-frame-asset-generation.md` before generating frame 2 and apply it automatically without waiting for the user to request consistency. Lock exact canvas, apparent scale, pivot, footline, safe rectangle, transparent guard band, camera/orientation and identity from the accepted anchor frame. Generate source frames as separate isolated images; actions with six or more frames must never use one generated contact sheet or multi-pose canvas as production source material. Validate every accepted frame incrementally with `python3 scripts/frame-set-preflight.py --input <frame-geometry.json> --root <asset-root> --json`; a shared source image, non-isolated source rect, scale drift beyond `bbox_drift_tolerance_px`, pivot/footline drift, guard-band violation, contamination or hash mismatch blocks continuation. Only after the isolated frames pass may the Agent pack a sprite sheet/atlas and run the normal atlas contract. For general consistency checks run `motionloom asset-consistency validate --kind <identity|action-set|frame-geometry|atlas|layered-map> --input <contract> --root <asset-root> --json`. The compiler measures actual PNG alpha bounds, pivot/footline/bbox drift, frame and atlas contamination, region overlap, parallax/z-order, tile seams and camera-safe bounds. A pass is deterministic contract evidence only; it never upgrades provenance, artist authority, production eligibility or human approval.
 3c. **Ingest generation artifacts** — before using output from an internal skill or external provider, bind it with a `generation-receipt`, `control-track` and `export-manifest`. Run `motionloom artifact-intake intake --root <project-root> --registry artifact-adapter-registry.json --receipt <receipt> --controls <controls> --export-manifest <export> --json`. For a single-character AI frame sequence, first run `motionloom build-ai-pilot`: it rejects painted checkerboards, all-opaque RGBA, insufficient measured padding and canvas-spanning detached residue. Visually inspect the isolated output too: edge-connected alpha removal cannot prove that disconnected opaque artifacts are absent. The core path makes no provider call and stores no secret; adapters are evidence descriptors. Use `--provider chatgpt` for user-provided ChatGPT bytes so the receipt records `openai.chatgpt` and `user-mediated`; never relabel them as `internal-imagegen`. Both adapters are scaffold-only metadata, not proof of runtime readiness, artist authority or approval.
 3d. **Build the runtime candidate and rig proof** — bind the intake bundle to identity/action/frame contracts with `motionloom runtime-candidate validate --root <project-root> --input <runtime-candidate.json> --json`, then validate the declared skeleton, sockets, actions, events, export target and runtime adapter with `motionloom rig-compatibility validate --root <project-root> --registry rig-adapter-registry.json --input <rig-contract.json> --json`. A passing candidate is `runtime_test_ready` and remains review-required; it cannot stand in for a production rig, human review or `production_approved`.
-4. **Generate** — use the matching template or rig implementation. For body animation, preserve named anatomy, pivot and parent-first hierarchy.
+4. **Generate** — use the matching template or rig implementation. For body animation, preserve named anatomy, pivot and parent-first hierarchy. For generated frame sequences, do not batch the whole action blindly: preserve the locked anchor geometry and accept each frame only after the multi-frame preflight passes; regenerate only the failing frame rather than resizing accepted frames to match it.
 5. **Render** — run the platform-neutral Node entrypoint for scene output, or `node scripts/runtime-adapters.mjs` for the verified Rive/GSAP/Framer Motion adapter matrix. Acceptance requires runtime evidence at 0/50/100%, not a static placeholder. Keep the render metadata beside the snapshots.
 6. **Bind Intelligence Core** — build a framework-neutral `motion-ir.json`, `project-graph.json`, `provenance.json`, `replay-bundle.json`, `semantic-lint-report.json` and `semantic-lint-benchmark.json` with `python3 scripts/intelligence.py`. Select only a capability registry entry whose status is `verified`, whose evidence is fresh and whose compatibility matches the target environment. A confidence score or benchmark result can prioritize investigation; neither can replace deterministic or human acceptance.
 6a. **Harden the trust boundary** — keep artifact and task bundles inside the repository/task root, reject symlinked evidence, bind replay to its exact `task_dir`, `task_id` and scene, select one deterministic report bundle per scene, and require browser candidate/review identity and expiry checks before readiness. The Dev Lab must reject cross-origin or identity-mismatched artifact bases. In strict runtime-observability runs, capture `runtime-telemetry.json` and a read-only `evidence-verifier-report.json`; verifier output must preserve `approval: false`. These checks expose risk and prevent evidence mixing, but do not turn heuristics or evidence integrity into approval.
 6b. **Attest** — derive a canonical statement from the exact scene/task hashes, sign it with an Ed25519 key through `scripts/attestation.py`, and verify it with the independent `scripts/attestation-verifier.py` against a fail-closed `trust-policy.json`. DSSE/SLSA-compatible attestation proves signer and binding integrity only; `approval` must remain `false` and never replaces user review.
-7. **Visual truth and browser review handoff** — after runtime rendering, build `visual-truth.json` from real baseline/candidate PNGs with `motionloom visual-truth build`. The contract records frame hashes, dimensions, runtime/source/manifest provenance and region-level review explanations; a changed frame means `review_required`, never automatic failure or approval. Then run `python3 scripts/review-hook.py prepare --task-dir artifacts/<task-id> --lab-url <internal-lab-url>`. The hook prepares the exact candidate and emits a JSON action for a browser-capable Agent. Trigger or suggest that Agent to open the emitted URL, inspect frames 0/50/100, scrub the timeline and ask the user to review. This is not a separate Dev Lab Skill; it is a required post-render handoff.
+7. **Visual truth and browser review handoff** — after runtime rendering, build `visual-truth.json` from real baseline/candidate PNGs with `motionloom visual-truth build`. The contract records frame hashes, dimensions, runtime/source/manifest provenance and region-level review explanations; a changed frame means `review_required`, never automatic failure or approval. Then run `python3 scripts/review-hook.py prepare --task-dir artifacts/<task-id> --lab-url <internal-lab-url>`. The hook prepares the exact candidate and emits a JSON action for a browser-capable Agent. Trigger or suggest that Agent to open the emitted URL. For live candidates, expose the declared Action Library and real playback controls (Play/Pause/Restart/scrub/frame-step/speed/loop); when `devlab-state-machine.json` is hash-bound, expose its legal transitions and required review sequences. Deterministic 0/50/100 snapshots remain evidence/fallback, not a substitute for live interaction. This is not a separate Dev Lab Skill; it is a required post-render handoff.
 
 > **Runtime-first reference:** `examples/agent-consumer/runtime-pilot/` and `src/output/runtime-pilot-framer/` demonstrate a code-authored Framer Motion lane with hash-bound Intake controls, deterministic 0/50/100 Playwright frames, strict runtime candidate validation, verifier and `approval: false` attestation before a prepared Dev Lab review. It is evidence of the pipeline, not a release approval or a substitute for an imported art package.
-8. **Review capture** — the browser Agent calls `window.__lab.getReview()` after the user approves or requests changes, then persists it with `python3 scripts/report.py review --task-dir artifacts/<task-id> --candidate-id <id> --decision approved|changes_requested --reviewer user`. A change request returns to generation; no approval means no PR.
+8. **Review capture** — the browser Agent calls `window.__lab.getReview()` after the user approves or requests changes, then persists it with `python3 scripts/report.py review --task-dir artifacts/<task-id> --candidate-id <id> --decision approved|changes_requested --reviewer user`. A change request returns to generation; no approval means no PR. Playback, action coverage, transition coverage and sequence completion remain evidence only and must never mint the user's decision.
 9. **Validate** — run `motionloom asset-provenance check --input src/output/<scene>/asset-provenance.json --root src/output/<scene> --mode runtime|production --manifest src/output/<scene>/manifest.json`, `motionloom visual-truth validate --root . --input src/output/<scene>/visual-truth.json --scene <scene> --task-id <task-id>`, `motionloom review-hook validate --task-dir artifacts/<task-id>`, `motionloom intelligence semantic-lint benchmark --task-dir artifacts/<task-id> --iterations 25 --threshold-ms 500`, `motionloom runtime-telemetry <scene> artifacts/<task-id>`, the independent attestation verifier, `motionloom report-contract --root . --scenes-file <changed-scenes> --require-attestation`, `motionloom quality-gate --scene <scene> --context <context-path> --task-dir artifacts/<task-id> --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation --require-visual-truth --require-asset-provenance`, and `motionloom doctor --json` when validating the Skill package itself.
 10. **Report** — create or update an artifact bundle with `python3 scripts/report.py`. Record facts with `report.py add`, structural defects with `report.py structure`, collect checksums with `report.py collect`, and run `report.py check` before rendering the final report. The final report must state completed, verified, not completed, blocked/failed, structure problems, browser candidate/review evidence and the recommended next Agent/Skill.
 11. **Learn** — after a user-confirmed fix or a deterministic benchmark, record it with `motionloom remediation-learning record-outcome|record-benchmark`. Run `summary` to expose correction count, first-pass acceptance, success rate, issue-class outliers and benchmark pass rate. Only `--user-confirmed` outcomes contribute to remediation acceptance metrics.
@@ -68,7 +68,9 @@ Only user-confirmed decisions and outcomes may become durable remediation memory
 - Read `references/reporting-contract.md` when creating task, execution, issue or handoff artifacts.
 - Read `references/runtime-capability.md` before claiming a framework is production-verified.
 - Read `docs/FRAMEWORK-SELECTION.md` and `docs/CATEGORIES.md` when selecting a runtime.
+- Read `references/multi-frame-asset-generation.md` before creating the second generated frame of any multi-frame action; this is an automatic source-generation rule, not an optional user preference.
 - Read `docs/CHECKLIST.md` before marking a scene ready for review.
+- Read `docs/DEV-LAB-RUNTIME.md` before declaring live actions, playback controls, Action Library metadata or state/transition review flows.
 - Read `src/rig/README.md` for character body hierarchy and pose rules.
 - Read `references/dotlottie-source-notes.md` when packaging or validating `.lottie` archives.
 - Read `docs/ROADMAP-INTELLIGENCE.md` before extending graph, provenance, capability or replay behavior.
@@ -90,10 +92,12 @@ Only user-confirmed decisions and outcomes may become durable remediation memory
 - Asset provenance is tiered: `code_authored` is runtime-only and may be `review_required`; `ai_generated` is `runtime_ready` but not `production_eligible`; `ai_assisted` becomes eligible only after human sign-off; `ai_assisted_human_reviewed` remains review-bound; `artist_authored` requires a verified human/artist record and full gate; `unknown` is `blocked`.
 - `production_approved` is a human decision only. An Agent, generator metadata, signed attestation or quality gate may preserve or verify a decision but may never mint it; `approval` remains `false` in machine-generated evidence.
 - Asset provenance binds each declared file to a SHA-256, license/source metadata, generator or derivation chain, runtime evidence and, where applicable, human review. Production checks fail closed on unknown origin, self-asserted artist authority, missing evidence or hash drift.
+- Generated multi-frame source assets are isolated-frame-first. Lock canvas/apparent scale/pivot/footline/safe-rect geometry before frame 2, validate every accepted frame incrementally, and pack atlases only after preflight. Six-frame-or-longer generated actions must not use a single multi-pose source sheet. Deterministic source-geometry failures are blockers and must not be weakened into approval-friendly tolerances.
 - Asset consistency is artifact-first and fail-closed: declared frame geometry, hashes, atlas regions and layered-map bounds must agree with measured runtime/source files. Heuristic warnings remain visible and may become blocking under `--strict`; no consistency result is an approval decision.
 - Artifact Intake is provider-neutral and hash-bound: receipt, control track, export manifest, provenance reference and adapter registry evidence must agree with the actual output bytes. Provider metadata, a prompt, a skill name, a model identifier or an adapter status cannot mint artist authority, production eligibility, runtime proof or approval.
 - A runtime candidate may become `runtime_test_ready` only when its intake and referenced consistency contracts pass. Rig compatibility must bind a supported adapter, skeleton/socket/action/event requirements and runtime evidence; `static-validated` and `scaffold` remain non-production states.
 - Browser-review candidates are single-use, time-bounded and bound to the exact task, scene and candidate identity; Dev Lab artifact/task bases must be same-origin and identity-consistent before staging a review decision.
+- Live Dev Lab review is data-driven and hash-bound: declared runtime and state-machine files must stay inside the scene, Action Library filtering must not weaken review coverage, and unsupported `runtime-trigger` transitions must fail visibly rather than silently switching clips.
 - Report completeness must select one deterministic passing task bundle per scene and fail on ambiguous ties; a valid artifact is never sufficient to bypass explicit user approval.
 - Runtime telemetry must bind task, scene, source, manifest, Motion IR and deterministic scrub points; tampered, stale, missing or cross-task telemetry is a verification failure.
 - Visual Truth must bind baseline/candidate PNG hashes, dimensions, source, manifest, runtime evidence and Motion IR where available; it explains changed regions for review but never emits approval.
@@ -122,6 +126,11 @@ node scripts/to-dotlottie.mjs --scene-dir src/output/<scene> --output src/output
 motionloom memory init --project-root <project-path>
 motionloom memory recover --project-root <project-path> --json
 
+# Generated multi-frame source preflight: isolated canvases, scale/pivot/footline and guard-band checks.
+python3 scripts/frame-set-preflight.py \
+  --input src/output/<scene>/hero-walk-frame-geometry.json \
+  --root src/output/<scene> --json
+
 # Measure multi-frame, atlas or layered-map consistency from real artifacts.
 motionloom asset-consistency validate --kind frame-geometry \
   --input src/output/<scene>/hero-walk-frame-geometry.json \

package/agent-card.json

@@ -1,8 +1,8 @@
 {
   "card_version": "1.0",
   "name": "motionloom",
-  "version": "2.5.1",
-  "description": "Project-aware animation production with durable Project Memory, provider-neutral Artifact Intake, hash-bound control-to-runtime candidates, tiered asset provenance, framework-neutral motion IR, rig compatibility, runtime verification and telemetry, Visual Truth, Remediation Learning, DSSE-compatible signed attestation, internal browser review, trust-boundary hardening and deterministic Agent handoff.",
+  "version": "2.6.1",
+  "description": "Project-aware animation production with durable Project Memory, provider-neutral Artifact Intake, hash-bound control-to-runtime candidates, tiered asset provenance, framework-neutral motion IR, rig compatibility, runtime verification and telemetry, Visual Truth, Remediation Learning, DSSE-compatible signed attestation, interactive Dev Lab review, trust-boundary hardening and deterministic Agent handoff.",
   "capabilities": [
     "project.setup",
     "project.status",
@@ -28,6 +28,9 @@
     "asset.provenance.validate",
     "asset.provenance.report",
     "asset.provenance.production-gate",
+    "asset.frame-generation-lock.validate",
+    "asset.frame-generation-lock.compose",
+    "asset.frame-set-preflight",
     "asset.consistency.validate",
     "asset.consistency.frame-geometry",
     "asset.consistency.atlas",
@@ -94,7 +97,8 @@
     "control-track",
     "export-manifest",
     "runtime-candidate",
-    "rig-compatibility-contract"
+    "rig-compatibility-contract",
+    "frame-generation-lock"
   ],
   "output_artifacts": [
     "agent-discovery-report",
@@ -134,11 +138,23 @@
     "project-memory",
     "continuity-report",
     "fix-plan",
-    "pr-patch"
+    "pr-patch",
+    "frame-generation-instruction",
+    "generated-frame-set-preflight-report"
   ],
   "runtime_capabilities": {
-    "verified": ["lottie-json", "dotlottie-package", "svg-cutout-rig", "rive", "gsap", "framer-motion"],
-    "scaffold_only": ["spine", "threejs"]
+    "verified": [
+      "lottie-json",
+      "dotlottie-package",
+      "svg-cutout-rig",
+      "rive",
+      "gsap",
+      "framer-motion"
+    ],
+    "scaffold_only": [
+      "spine",
+      "threejs"
+    ]
   },
   "side_effects": {
     "read_files": "allowed",
@@ -146,8 +162,8 @@
     "network": "optional-and-declared",
     "git_commit": "explicit-confirmation",
     "git_push": "explicit-confirmation",
-    "open_pull_request": "explicit-confirmation"
-    ,"open_internal_browser": "trigger-or-suggest-after-render; user-review-required"
+    "open_pull_request": "explicit-confirmation",
+    "open_internal_browser": "trigger-or-suggest-after-render; user-review-required"
   },
   "recommended_integrations": [
     {
@@ -155,24 +171,46 @@
       "url": "https://github.com/LottieFiles/dotlottie-web/blob/main/SKILL.md",
       "role": "official-runtime-reference",
       "trust": "official",
-      "use_for": ["dotLottie runtime API", "worker rendering", "state machines", "slots"],
-      "not_for": ["project planning", "provenance", "PR acceptance"]
+      "use_for": [
+        "dotLottie runtime API",
+        "worker rendering",
+        "state machines",
+        "slots"
+      ],
+      "not_for": [
+        "project planning",
+        "provenance",
+        "PR acceptance"
+      ]
     },
     {
       "id": "text-to-lottie",
       "url": "https://github.com/diffusionstudio/lottie",
       "role": "optional-scaffold",
       "trust": "community-open-source",
-      "use_for": ["scene setup", "live preview patterns", "prompt conventions"],
-      "not_for": ["runtime truth", "context binding"]
+      "use_for": [
+        "scene setup",
+        "live preview patterns",
+        "prompt conventions"
+      ],
+      "not_for": [
+        "runtime truth",
+        "context binding"
+      ]
     },
     {
       "id": "animation-design",
       "url": "https://github.com/b1rdmania/claude-lottie-skill/blob/main/SKILL.md",
       "role": "optional-asset-discovery",
       "trust": "community-open-source",
-      "use_for": ["brand-aware Lottie/Rive search", "series coherence"],
-      "not_for": ["license authority", "runtime verification"]
+      "use_for": [
+        "brand-aware Lottie/Rive search",
+        "series coherence"
+      ],
+      "not_for": [
+        "license authority",
+        "runtime verification"
+      ]
     }
   ],
   "entrypoints": {
@@ -234,10 +272,21 @@
     "remediation_summary": "motionloom remediation-learning summary --history artifacts/remediation-history.jsonl --output artifacts/remediation-summary.json --json",
     "browser_review_prepare": "python3 scripts/review-hook.py prepare --task-dir artifacts/<task-id> --lab-url <internal-lab-url>",
     "browser_review_validate": "python3 scripts/review-hook.py validate --task-dir artifacts/<task-id>",
-    "pr_prepare": "node scripts/pr.mjs <scene>"
+    "pr_prepare": "node scripts/pr.mjs <scene>",
+    "frame_generation_lock_validate": "motionloom frame-generation-lock validate --input <frame-generation-lock.json> --root <asset-root> --json",
+    "frame_generation_lock_compose": "motionloom frame-generation-lock compose --input <frame-generation-lock.json> --frame-id <frame-id> --root <asset-root> --json",
+    "frame_set_preflight": "motionloom frame-set-preflight --input <frame-geometry.json> --root <asset-root> --json"
   },
   "report_contract": {
-    "required_sections": ["completed", "verified", "not_completed", "problems", "structure_review", "next_agent", "browser_review"],
+    "required_sections": [
+      "completed",
+      "verified",
+      "not_completed",
+      "problems",
+      "structure_review",
+      "next_agent",
+      "browser_review"
+    ],
     "artifact_root": "artifacts/<task-id>/"
   }
 }

package/agent-surfaces.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "1.0",
   "name": "motionloom",
-  "version": "2.5.1",
+  "version": "2.6.1",
   "canonical": {
     "skill": "SKILL.md",
     "agent_card": "agent-card.json",
@@ -14,7 +14,12 @@
       "path": ".agents/skills/motionloom/SKILL.md",
       "canonical": "SKILL.md",
       "load_mode": "alias",
-      "agents": ["codex", "claude-code", "cursor", "opencode"]
+      "agents": [
+        "codex",
+        "claude-code",
+        "cursor",
+        "opencode"
+      ]
     },
     {
       "id": "claude-code",
@@ -22,7 +27,9 @@
       "path": ".claude/skills/motionloom.md",
       "canonical": "SKILL.md",
       "load_mode": "alias",
-      "agents": ["claude-code"]
+      "agents": [
+        "claude-code"
+      ]
     },
     {
       "id": "codex",
@@ -30,7 +37,9 @@
       "path": ".codex/skills/motionloom.md",
       "canonical": "SKILL.md",
       "load_mode": "alias",
-      "agents": ["codex"]
+      "agents": [
+        "codex"
+      ]
     },
     {
       "id": "repository-agent-guide",
@@ -38,7 +47,12 @@
       "path": "AGENTS.md",
       "canonical": "SKILL.md",
       "load_mode": "router",
-      "agents": ["codex", "claude-code", "cursor", "opencode"]
+      "agents": [
+        "codex",
+        "claude-code",
+        "cursor",
+        "opencode"
+      ]
     }
   ],
   "installations": [
@@ -72,10 +86,19 @@
     }
   ],
   "compatibility": {
-    "operating_systems": ["ubuntu", "macos", "windows"],
+    "operating_systems": [
+      "ubuntu",
+      "macos",
+      "windows"
+    ],
     "node": ">=18",
     "python": ">=3.11",
-    "agents": ["codex", "claude-code", "cursor", "opencode"]
+    "agents": [
+      "codex",
+      "claude-code",
+      "cursor",
+      "opencode"
+    ]
   },
   "rules": {
     "canonical_instruction_source": "SKILL.md",

package/bin/motionloom.mjs

@@ -40,6 +40,8 @@ const PYTHON_COMMANDS = {
   "remediation-learning": "scripts/remediation-learning.py",
   "asset-provenance": "scripts/asset-provenance.py",
   "asset-consistency": "scripts/asset-consistency.py",
+  "frame-generation-lock": "scripts/frame-generation-lock.py",
+  "frame-set-preflight": "scripts/frame-set-preflight.py",
   "artifact-intake": "scripts/artifact-intake.py",
   "runtime-candidate": "scripts/runtime-candidate.py",
   "rig-compatibility": "scripts/rig-compatibility.py",
@@ -92,6 +94,8 @@ Use when an animation task needs it:
   remediation-learning   Record or summarize user-confirmed remediation and benchmark history
   asset-provenance       Validate, classify or report asset origin and production readiness
   asset-consistency      Validate frame geometry, atlas contamination and layered-map contracts
+  frame-generation-lock  Validate or compose locked per-frame generation instructions
+  frame-set-preflight    Fail closed on shared canvases, scale drift and frame contamination
   artifact-intake        Bind generation controls, provenance, adapter metadata and exported bytes
   runtime-candidate      Bind intake exports to consistency contracts before runtime testing
   rig-compatibility      Validate rig bones, sockets, actions, events and runtime adapter evidence
@@ -114,6 +118,8 @@ Cross-platform examples:
   motionloom remediation-learning summary --history artifacts/remediation-history.jsonl --json
   motionloom asset-provenance check --input <asset-provenance.json> --root <scene-dir> --mode runtime --json
   motionloom asset-consistency validate --kind frame-geometry --input <frame-geometry.json> --root <scene-dir> --json
+  motionloom frame-generation-lock compose --input <frame-generation-lock.json> --root <asset-root> --frame-id walk.00 --json
+  motionloom frame-set-preflight --input <frame-geometry.json> --root <asset-root> --json
   motionloom artifact-intake intake --root <asset-dir> --registry artifact-adapter-registry.json \\
     --receipt <generation-receipt.json> --controls <control-track.json> --export-manifest <export-manifest.json> --json
   motionloom alpha-isolate <opaque.png> <isolated.png> --report <alpha-report.json>