motionloom 2.6.1 → 2.7.0

package/AGENTS.md

@@ -12,9 +12,9 @@ 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.
+Before calling an image/animation provider for a generated asset, create an `asset-generation-request.json` and run `motionloom asset-generation-plan plan --request <request.json> --project-root <project-root> --json`. Read the plan as a recommendation: it must expose provider-native canvas limits, batch versus single-frame behavior, safe padding/upscale options, and a manual or alternate-provider fallback. Never hide an incompatible provider behind a generic error, silently crop/stretch to fit, or place a secret in a request/receipt. 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`. For enhanced lock schema 0.2, bind one immutable `sequence_id`, `action_id`, action cues, forbidden competitor actions and `action_manifest`; every image must have a schema 0.2 manifest-bound frame envelope. A generator-created envelope is declared evidence and remains quarantined; only a separate verifier artifact with hash-bound provenance may be classified as `independently_bound`. After each generated frame, update the bound frame-geometry evidence and run `motionloom frame-set-preflight --action-manifest <action-manifest.json>` plus `motionloom action-separation validate`. Low action-separation margins are quarantined, never relabeled or moved automatically. 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.
+For Dev Lab work, also read [`docs/CHECKLIST.md`](docs/CHECKLIST.md), [`docs/DEV-LAB-RUNTIME.md`](docs/DEV-LAB-RUNTIME.md) and [`docs/ACTION-SEPARATION.md`](docs/ACTION-SEPARATION.md). A runnable animation candidate should expose the live runtime descriptor/controls defined there and, when action evidence exists, its action-separation summary; 0/50/100 PNGs remain evidence/fallback and must not be presented as an interactive runtime when live playback is available.
 
 ## Source of truth
 

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable MotionLoom changes are documented here. The project follows semantic
 
 ## [Unreleased]
 
+No unreleased changes.
+
+## [2.7.0] - 2026-08-22
+
+### Added
+
+- Add action-scoped frame separation contracts with schema `0.2`, immutable sequence/action identity, forbidden competitor actions, per-frame envelopes and separate verifier evidence artifacts.
+- Add `motionloom asset-generation-plan plan`, a project-aware recommendation layer that evaluates tool/provider routes against the real project target before an Agent executes them.
+- Separate MotionLoom recommendation status from execution status, evidence status, availability and execution eligibility, so provisional routes can be suggested without being misrepresented as verified.
+- Add explicit `preferred`, `neutral` and `excluded` provider preference handling; user preference influences ranking but cannot override hard project, canvas, isolation or evidence constraints.
+- Add deterministic transparent padding and integer nearest-neighbour scaling through `motionloom asset-adapt`, with hash-bound adaptation reports and no silent crop/stretch.
+- Expose the new MotionLoom planning/action-separation capabilities, inputs, outputs and entrypoints in `agent-card.json` so compatible Agents can discover the workflow from an installed package.
+
+### Hardened
+
+- Treat generator-created verifier envelopes as `declared` and quarantined; only hash-bound separate verifier artifacts may become `independently_bound` evidence, and machine paths preserve `approval: false`.
+- Enforce hash-bound scene/task browser-review candidate consistency in review-hook validation, quality gates and ready-for-PR report checks.
+- Add an opt-in `doctor --runtime` preflight and `doctor:runtime` npm script that verifies the installed Playwright Chromium executable and prints a concrete remediation command.
+- Require capability registry identifiers and adapter evidence versions to align with the package version during release verification.
+- Keep normal asset planning useful when only provisional/manual routes exist while `--strict` stays fail-closed unless an execution-eligible route satisfies the active MotionLoom policy.
+- Model provider availability separately from registry presence so unknown/unavailable tools are explained instead of being silently treated as executable.
+
+### Changed
+
+- MotionLoom is now the explicit project-aware decision and guidance layer in asset-generation plans: it assesses project constraints, ranks routes, explains tradeoffs, produces MotionLoom Agent Guidance and routes generated output back through MotionLoom validation/review.
+- No provider is a hard-coded default. PixelLab routes remain scaffold metadata and are represented as provider choices inside MotionLoom recommendations rather than as a product dependency.
+
+### Verified
+
+- Pull requests #21 and #22 passed hosted MotionLoom Quality, Security Analysis, Documentation and Package Hygiene, Dev Lab Build, Frame Generation Lock and Apple compatibility checks before integration.
+- Planner/adaptation regression tests cover user-preferred provisional tools, incompatible preferred tools, strict-mode failure, availability states, safe canvas adaptation and MotionLoom-branded Agent guidance.
+- Deep audit remains green at 6,900/6,900 with 0 false positives and 0 false negatives, preserving the approval-false invariant.
+- Add adversarial regression coverage proving foreign/divergent browser-review candidates and malformed or self-declared verifier evidence fail closed.
+
+### Boundary
+
+- Recommendation is not execution authority. A provisional/scaffold provider may be useful to suggest but never becomes verified merely because MotionLoom ranks it highly or the user prefers it.
+- MotionLoom planning does not invoke provider APIs, store credentials, publish assets or grant human approval. Provider output must return through MotionLoom provenance, geometry/action-separation, runtime and Dev Lab review gates.
+
+See the [2.7.0 release note](docs/releases/2.7.0.md) for the project-aware recommendation model, trust boundaries and project update steps.
+
 ## [2.6.1] - 2026-08-21
 
 ### Added
@@ -202,6 +243,7 @@ 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.7.0]: docs/releases/2.7.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

package/CONTRIBUTING.md

@@ -16,9 +16,10 @@ cd MotionLoom
 npm install
 python3 -m pip install --requirement requirements.txt
 python3 scripts/skill-doctor.py --json
+python3 scripts/skill-doctor.py --runtime --json
 ```
 
-Node.js 18+ and Python 3.11+ are required. On Windows, use `python` if `python3` is not available or set `MOTIONLOOM_PYTHON` for the npm wrapper. Runtime adapter tests may require the Playwright browser installation described by the CI workflow.
+Node.js 18+ and Python 3.11+ are required. On Windows, use `python` if `python3` is not available or set `MOTIONLOOM_PYTHON` for the npm wrapper. Runtime adapter tests require a Playwright browser executable; run `python3 scripts/skill-doctor.py --runtime --json` before the suite, then `npx playwright install chromium` if the diagnostic reports `missing_browser_executable`.
 
 ## Validation commands
 
@@ -30,6 +31,7 @@ python3 tests/scripts/test_project_memory.py
 python3 tests/scripts/run_tests.py
 python3 scripts/eval-intelligence.py
 python3 scripts/skill-doctor.py --json
+python3 scripts/skill-doctor.py --runtime --json
 npm run runtime:test
 npm publish --dry-run --access public
 ```

package/README.md

@@ -84,10 +84,12 @@ Use these only if you need them:
 ```bash
 npx --yes motionloom init --dry-run --json     # preview; no install or file changes
 npx --no-install motionloom doctor             # check the installed package
+npx --no-install motionloom doctor --runtime --json  # include Playwright Chromium preflight
 npx --no-install motionloom repair --yes       # restore only missing managed pieces
 ```
 
-MotionLoom's onboarding and contract CLI supports **Node.js 18+** and **Python 3.11+** on Ubuntu, macOS and Windows. Browser-runtime capture uses the separately declared optional Playwright/Vite dependencies and follows the capability contract's Node.js 22 requirement. Signed-attestation commands additionally require the Python `cryptography` package declared in the shipped `requirements.txt`; `motionloom doctor` reports missing runtime prerequisites. `npx` is the recommended first-run surface; after setup, use the project-local binary through `npx --no-install motionloom ...`. A global install remains optional, not required.
+MotionLoom's onboarding and contract CLI supports **Node.js 18+** and **Python 3.11+** on Ubuntu, macOS and Windows. Browser-runtime capture uses the separately declared optional Playwright/Vite dependencies and follows the capability contract's Node.js 22 requirement. Signed-attestation commands additionally require the Python `cryptography` package declared in the shipped `requirements.txt`; `motionloom doctor` reports package prerequisites, while `motionloom doctor --runtime` additionally verifies the installed Playwright Chromium executable and prints `npx playwright install chromium` when it is missing.
+ `npx` is the recommended first-run surface; after setup, use the project-local binary through `npx --no-install motionloom ...`. A global install remains optional, not required.
 
 ### When you begin animation work
 
@@ -98,6 +100,19 @@ The detail level follows the job rather than the installation. A simple interfac
 | UI motion, loading state, page transition | `motionloom analyze . --init-memory` | Scene plan, runtime render and Dev Lab review |
 | Imported or AI-generated frames, sprite atlas, layered map | The same project analysis | Provenance and measured asset-consistency/intake steps |
 | Rive, Spine or other packaged runtime asset | The same project analysis | Package, rig and runtime evidence steps |
+| AI-generated or provider-backed game asset | Project analysis plus `asset-generation-plan` | Provider capability, canvas adaptation, isolation and fallback recommendations before generation |
+
+### Provider-aware asset planning
+
+When a provider reports a native size or frame limitation, do not force the provider output into the runtime contract by cropping or stretching. Describe the real game target in an `asset-generation-request.json` and ask MotionLoom for a machine-readable plan:
+
+```bash
+npx --no-install motionloom asset-generation-plan plan \
+  --request examples/agent-consumer/asset-planning/pixellab-hero-256x448-request.json \
+  --project-root . --json
+```
+
+MotionLoom does not choose PixelLab or any other provider by default. It first assesses the project target, then ranks compatible routes. A user preference such as `preferred_adapter_ids` is preserved and can elevate a provisional route, but cannot override a hard canvas/isolation failure. Normal planning may recommend a provisional/manual route while `execution_status` remains `provisional`; `--strict` remains fail-closed and requires execution eligibility. The plan exposes a human-readable `MotionLoom Project Assessment`, `MotionLoom Recommendations` and `MotionLoom Agent Guidance`, including availability, rationale and the MotionLoom validation route. For PixelLab's documented square animation routes, MotionLoom can recommend a provisional square source plus explicit transparent padding into a `256x448` target, or suggest a manual/single-frame fallback when per-frame isolation is mandatory. The plan is advisory and does not call the provider, handle the Bearer token, edit the image, or approve the asset. Read the [provider-aware planner contract](docs/ASSET-GENERATION-PLANNER.md) for the decision model.
 
 ### Advanced: start from a real project
 
@@ -317,9 +332,10 @@ 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) |
+| Configure live actions, playback or state transitions in Dev Lab | [Dev Lab live runtime contract](docs/DEV-LAB-RUNTIME.md), [canonical live sprite fixture](examples/agent-consumer/devlab-live-sprite/), and [2.6.0 release note](docs/releases/2.6.0.md) |
+| Prevent cross-action frame mixing | [Action-scoped isolated frame pipeline](docs/ACTION-SEPARATION.md), `motionloom action-separation`, and manifest-aware `motionloom frame-set-preflight` |
 | 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` |
+| Run labeled project evaluation | [Project corpus manifest](tests/evals/project-corpus.json), [external corpus workflow](docs/EXTERNAL-CORPUS.md), 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) |
 | Classify AI-generated or assisted assets | [Asset provenance tiers](schemas/asset-provenance.schema.json), `motionloom asset-provenance`, and the [production checklist](docs/CHECKLIST.md) |
 | Bind an internal skill or provider output before runtime testing | [Artifact Intake examples](examples/agent-consumer/artifact-intake/), `motionloom artifact-intake`, and [AI/Agent research](docs/research/ai-animation-tools-2026-report.md) |

package/SECURITY.md

@@ -4,9 +4,9 @@
 
 | Version | Security fixes |
 |---|---|
-| `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 |
+| `2.7.x` | Current supported line |
+| `2.6.x` | Previous line; security fixes are best effort while consumers upgrade |
+| `2.5.x` and earlier | Upgrade recommended; no routine support commitment |
 
 ## Reporting a vulnerability
 
@@ -18,9 +18,9 @@ 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, 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.
+Path guards, task identity, source/manifest hashes, runtime bundle hashes, state-machine bindings, action-separation verifier bindings, provider/tool execution status, 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, provisional provider evidence to become verified without proof, or unreviewed Git side effects.
 
-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.
+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.7.0 release note](docs/releases/2.7.0.md) for the current trust boundaries and limitations.
 
 ## CI/CD controls
 

package/SKILL.md

@@ -30,8 +30,10 @@ 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 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.
+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> --action-manifest <action-manifest.json> --json`; a shared source image, non-isolated source rect, scale drift beyond `bbox_drift_tolerance_px`, pivot/footline drift, guard-band violation, contamination, cross-action envelope, low action-separation margin or hash mismatch blocks continuation. The enhanced `frame-generation-lock` schema 0.2 binds `sequence_id`, action cues, forbidden competitors and the manifest path; each frame must have a schema 0.2 envelope. A generator-created envelope is only `declared` evidence and remains quarantined; only a separate verifier artifact with hash-bound provenance may be bound as `independently_bound`. Low-confidence frames are quarantined and regenerated from the accepted anchor, never relabeled or moved automatically. 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`; for action identity run `motionloom action-separation validate --input <action-manifest.json> --root <asset-root> --json` and use `motionloom action-separation envelope` only to create a declared/quarantined generator envelope; bind a separate verifier artifact before treating a frame as independently-bound evidence.
+ 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. **Plan and ingest generation artifacts** — before calling an internal skill or external provider, create an `asset-generation-request.json` and run `motionloom asset-generation-plan plan --request <request.json> --project-root <project-root> --json`. The planner must first assess the real project/task target canvas, frame-isolation policy, available contracts and declared adapter capabilities, then return ranked MotionLoom recommendations with explicit native, padding, integer-upscale, tile or manual-import options. If the user explicitly prefers a provider, preserve that preference and explain the fit/risks without overriding hard constraints. Normal planning may recommend provisional routes; `execution_status` and `--strict` remain guarded by the active execution policy. It never invokes a provider or handles credentials. Do not silently crop, stretch, resize or treat a provider batch as isolated source frames. After selecting a route, bind output 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. 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.
@@ -77,7 +79,7 @@ Only user-confirmed decisions and outcomes may become durable remediation memory
 - Read `references/intelligence-core.md` before building or validating Intelligence Core artifacts.
 - Read `docs/research/AGENT-PROTOCOL-FINDINGS.md` before exposing MotionLoom through Agent tools or MCP resources.
 - Read `references/agent-interoperability.md` when installing MotionLoom into Codex, Claude Code, Cursor, OpenCode or another Agent environment; run `motionloom discovery check --root <motionloom-checkout> --json` before relying on a surface.
-- Read `docs/research/agent-skill-ecosystem-notes.md` and `docs/research/ai-animation-tools-2026-report.md` before selecting a provider or internal capability; use its evidence to distinguish a scaffold adapter from a verified runtime path.
+- Read `docs/research/agent-skill-ecosystem-notes.md`, `docs/research/ai-animation-tools-2026-report.md` and `docs/ASSET-GENERATION-PLANNER.md` before selecting a provider or internal capability; use their evidence to distinguish a scaffold adapter from a verified runtime path.
 
 ## Non-negotiable contracts
 
@@ -94,6 +96,7 @@ Only user-confirmed decisions and outcomes may become durable remediation memory
 - 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.
+- Asset generation planning is provider-neutral and explicit: target canvas, frame isolation, adaptation and fallback decisions must be machine-readable before a provider call; unknown capabilities are warnings/blockers, not permission to guess.
 - 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.

package/agent-card.json

@@ -1,8 +1,8 @@
 {
   "card_version": "1.0",
   "name": "motionloom",
-  "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.",
+  "version": "2.7.0",
+  "description": "Project-aware animation production and Agent guidance with durable Project Memory, provider-neutral tool recommendations, guarded asset-generation planning, action-separated frame evidence, Artifact Intake, provenance, Motion IR, rig compatibility, runtime verification, Visual Truth, signed attestation and Dev Lab review.",
   "capabilities": [
     "project.setup",
     "project.status",
@@ -31,6 +31,11 @@
     "asset.frame-generation-lock.validate",
     "asset.frame-generation-lock.compose",
     "asset.frame-set-preflight",
+    "asset.action-separation.validate",
+    "asset.action-separation.verifier-evidence",
+    "asset.generation-plan",
+    "asset.generation-plan.recommend",
+    "asset.adapt",
     "asset.consistency.validate",
     "asset.consistency.frame-geometry",
     "asset.consistency.atlas",
@@ -98,7 +103,10 @@
     "export-manifest",
     "runtime-candidate",
     "rig-compatibility-contract",
-    "frame-generation-lock"
+    "frame-generation-lock",
+    "action-sequence-manifest",
+    "action-separation-verifier-evidence",
+    "asset-generation-request"
   ],
   "output_artifacts": [
     "agent-discovery-report",
@@ -140,7 +148,10 @@
     "fix-plan",
     "pr-patch",
     "frame-generation-instruction",
-    "generated-frame-set-preflight-report"
+    "generated-frame-set-preflight-report",
+    "action-separation-report",
+    "asset-generation-plan",
+    "asset-adaptation-report"
   ],
   "runtime_capabilities": {
     "verified": [
@@ -256,6 +267,9 @@
     "asset_provenance_report": "motionloom asset-provenance report --input <asset-provenance.json> --json",
     "asset_consistency_validate": "motionloom asset-consistency validate --kind <identity|action-set|frame-geometry|atlas|layered-map> --input <contract.json> --root <asset-root> --json",
     "asset_consistency_report": "motionloom asset-consistency report --kind <identity|action-set|frame-geometry|atlas|layered-map> --input <contract.json> --root <asset-root> --strict --json",
+    "action_separation_validate": "motionloom action-separation validate --input <action-sequence.json> --root <asset-root> --json",
+    "asset_generation_plan": "motionloom asset-generation-plan plan --request <asset-generation-request.json> --project-root <project-root> --json",
+    "asset_adapt": "motionloom asset-adapt pad --input <source.png> --output <target.png> --width <width> --height <height> --anchor <center|footline> --report <adaptation.json> --json",
     "artifact_intake": "motionloom artifact-intake intake --root <project-root> --registry artifact-adapter-registry.json --receipt <generation-receipt.json> --controls <control-track.json> --export-manifest <export-manifest.json> --json",
     "runtime_candidate_validate": "motionloom runtime-candidate validate --root <project-root> --input <runtime-candidate.json> --json",
     "rig_compatibility_validate": "motionloom rig-compatibility validate --root <project-root> --registry rig-adapter-registry.json --input <rig-compatibility.json> --json",

package/agent-surfaces.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "1.0",
   "name": "motionloom",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "canonical": {
     "skill": "SKILL.md",
     "agent_card": "agent-card.json",