motionloom 2.6.0 → 2.7.0

package/docs/ASSET-GENERATION-PLANNER.md

@@ -0,0 +1,101 @@
+# Provider-aware asset generation planner
+
+MotionLoom does not choose animation tools in isolation. It first understands the project and task, evaluates available or requested routes against those requirements, then produces an explainable recommendation and validation workflow. A provider is only an execution route; **MotionLoom remains the project-aware decision and guidance layer**.
+
+MotionLoom also does not treat an image provider's native canvas as the game's runtime canvas. A request such as a `256x448` character frame can be valid for the game while being impossible as a native input to a provider whose animation tools accept only square canvases. The planner makes this mismatch explicit before any provider call.
+
+## Command
+
+```bash
+motionloom asset-generation-plan plan \
+  --request examples/agent-consumer/asset-planning/pixellab-hero-256x448-request.json \
+  --project-root . --json
+```
+
+The command is **plan-only**. It does not invoke a provider, read or transfer a Bearer token, modify image bytes, create a generation job or grant approval. It reads the request, the local `artifact-adapter-registry.json`, and the repository contracts that are present in `--project-root`.
+
+When the plan selects deterministic padding, execute it explicitly with `asset-adapt`; the operation is transparent, hash-bound and still requires downstream geometry/action review:
+
+```bash
+motionloom asset-adapt pad \
+  --input provider-source.png \
+  --output runtime-frame.png \
+  --width 256 --height 448 \
+  --anchor footline \
+  --report asset-adaptation.json --json
+```
+
+`asset-adapt` uses integer nearest-neighbour scaling only when requested, refuses source pixels that do not fit the target, and never crops or non-uniformly stretches. It does not decide whether the source frame belongs to the requested action.
+
+## Why PixelLab needs an adaptation plan
+
+PixelLab's official API documentation exposes image and animation endpoints and documents Bearer-token authentication.[1] The official skeleton animation guide accepts square canvases including `256x256`, `128x128`, `64x64`, `32x32` and `16x16`.[2] The official Animation to animation guide documents square sizes `128x128`, `64x64`, `32x32` and `16x16`, with maximum frame count dependent on canvas size.[3] The official Create animated object/character route creates a new object or character from text and action, supports `32x32`, `64x64`, `128x128` and `256x256`, and emits 16 frames for 32/64px tiers or 4 frames for larger documented tiers.[4] The separate Animate with text route animates an existing reference image and is not the same provider capability as create-from-text.[5]
+
+Therefore, a game target of `256x448` is not a PixelLab-native animation canvas for these documented routes. MotionLoom may still recommend a PixelLab route when it is a good project fit, but represents it as `recommendation_status: recommended` with `execution_status: provisional` under the default policy. The recommendation is explicit transparent padding into the `256x448` target, followed by frame-geometry and action-separation validation. It never silently stretches, crops or treats a provider batch as equivalent to required isolated-frame generation.
+
+PixelLab also documents a Resize tool, but the official page currently states that the feature is available in the Aseprite extension.[6] MotionLoom consequently does not claim provider-native API resize as verified. Deterministic nearest-neighbour scaling or a manual/provider-specific resize route must be declared and evidenced separately.
+
+## Request contract
+
+`schemas/asset-generation-request.schema.json` records the information that a generic prompt usually omits:
+
+| Field | Purpose |
+|---|---|
+| `target.canvas` | The real runtime width and height, not the provider's preferred size. |
+| `target.frame_count` and `fps` | The temporal contract the generated sequence must satisfy. |
+| `target.alpha_mode` and `pixel_art` | Transparency and pixel-grid constraints for downstream geometry checks. |
+| `generation_policy.frame_isolation` | Whether one source image per frame is required. |
+| `allow_crop`, `allow_stretch`, `allow_silent_resize` | Hard safety boundaries; the current contract requires all three to be false. |
+| `actions` | Positive and negative cues that feed the existing action-scoped manifest/verifier pipeline. |
+| `provider_preferences` | Optional preferred or excluded adapter IDs; preference is visible but cannot override hard constraints. |
+| `references` | Identity/style/pose roles without placing secrets or prompt plaintext in the request. |
+
+## Decision model
+
+The planner compares the request with adapter capability metadata, current availability metadata, user preference and the active registry selection policy. It separates **recommendation status** from **execution status** and keeps normal planning useful even when no route is execution-eligible.
+
+| Situation | Planner behavior |
+|---|---|
+| Verified adapter satisfies hard constraints | Set `execution_status: verified`, `execution_eligible: true` and usually `recommendation_status: recommended` or `acceptable`; retain human-review boundaries. |
+| Provisional/scaffold adapter fits project requirements | It may receive `recommendation_status: recommended` in normal planning while `execution_status: provisional` remains visible. It is not authorized under verified-only strict execution. |
+| User explicitly prefers a route | Preserve `user_preference: preferred`, add an explainable ranking signal and provide route guidance; never override hard incompatibility or approval boundaries. |
+| User explicitly excludes a route | Preserve `user_preference: excluded` and do not recommend it, while evaluating other routes normally. |
+| Provider canvas is incompatible but safe adaptation is declared | Recommend a concrete source canvas only when both source dimensions fit the target after the declared integer transform. |
+| Provider emits a batch while per-frame isolation is required | Mark execution provisional or blocked according to policy; require independent envelopes after export and never promote it automatically. |
+| Capability/availability is unknown or no safe route exists | Mark the route blocked or not recommended as appropriate, surface the reason, and suggest a manual/alternate option without fabricating availability. Strict mode returns non-zero when no execution-eligible route exists. |
+
+The current registry includes a manual single-frame import fallback. In normal planning it remains a visible MotionLoom recommendation because it is project-compatible and explains its user-managed availability; under the default `require_verified: true` policy it remains provisional rather than execution-eligible. This is deliberate: MotionLoom gives the Agent useful choices without silently relaxing policy or forcing it to invent a workaround.
+
+## Recommended 256x448 route
+
+For a pixel-art action with eight frames and required isolation, the safe provisional route is:
+
+1. Treat PixelLab as one MotionLoom recommendation, not a default provider. If selected or explicitly preferred, use a square animation route only as a source-generation candidate, with a declared source canvas such as `256x256` and a separate action-specific request.
+2. Keep the provider result provisional because the documented animation routes are batch-oriented and the adapter is not runtime-verified.
+3. Place each accepted source frame on a transparent `256x448` target canvas using the declared footline/pivot anchor. Do not stretch or crop.
+4. Bind source and target geometry in the export manifest and generate one independent frame envelope per output image.
+5. Run `frame-set-preflight` and `action-separation validate` before atlas packing or Dev Lab review. The adaptation report is evidence of geometry transformation, not a substitute for either contract.
+6. If any frame is ambiguous, quarantine that frame and regenerate or independently verify it. Do not move it to another action automatically.
+
+If strict one-frame-per-provider-call isolation is non-negotiable, the planner's recommendation is to use a provider or manual workflow that declares single-frame output and target-canvas compatibility. PixelLab remains a useful provisional source option, not proof that the hard contract has been met.
+
+## MotionLoom Agent guidance
+
+Every recommendation includes `agent_guidance` with `recommended_by: MotionLoom`, a summary, a route-specific sequence of steps and the MotionLoom validation route. The plan also exposes availability as `available`, `known`, `unavailable` or `unknown`; an unavailable/unknown tool may remain a recommendation, but the Agent must resolve connectivity before execution and MotionLoom must not claim it can invoke the tool.
+
+Normal output uses the `MotionLoom Project Assessment`, `MotionLoom Recommendations` and `MotionLoom Agent Guidance` headings. JSON output includes `producer: MotionLoom`, `source`, project assessment, recommendation status, execution status, preference, availability, rationale and validation route.
+
+## Adapter registry policy
+
+The registry is not a provider launcher. It is a capability and evidence ledger. A `scaffold_only` entry may describe official limits and useful routes, but it cannot satisfy a strict selection policy that requires verified adapters. An adapter can become `verified` only after real export bytes, provider receipt metadata where available, target-runtime evidence, deterministic contract results and a human review path are present.
+
+Credentials remain outside all request, receipt, control and manifest files. For an eventual PixelLab integration, the API token should be supplied through the project's secret/connector layer, while the receipt records only non-secret task identity and output hashes.
+
+## References
+
+[1]: https://api.pixellab.ai/v2/docs "PixelLab API — official API documentation"
+[2]: https://www.pixellab.ai/docs/tools/animate-with-skeleton "PixelLab — Animate with skeleton"
+[3]: https://www.pixellab.ai/docs/tools/animation-to-animation "PixelLab — Animation to animation"
+[4]: https://www.pixellab.ai/docs/tools/text2animation "PixelLab — Create animated object/character"
+[5]: https://www.pixellab.ai/docs/tools/animation "PixelLab — Animate with text (existing reference)"
+[6]: https://www.pixellab.ai/docs/tools/resize "PixelLab — Resize"

package/docs/BRANCH-PROTECTION.md

@@ -0,0 +1,44 @@
+# MotionLoom main branch protection recommendation
+
+## Current observed state
+
+As of the repository audit, `main` is not protected and the repository exposes no active rulesets. This document records the exact recommended configuration; it does not mutate GitHub settings automatically.
+
+## Recommended configuration
+
+Open **Settings → Rules → Rulesets → New branch ruleset** in `lenhonbp/MotionLoom` and create a ruleset named `protect-main-motionloom` with enforcement set to **Active** and target branch `main`.
+
+| Setting | Recommended value |
+|---|---|
+| Target branches | Include `main`; do not target feature branches by default. |
+| Restrict deletions | Enabled. |
+| Require linear history | Enabled if the repository policy accepts squash/rebase-only integration; otherwise leave disabled and require the repository's chosen merge strategy consistently. |
+| Require a pull request before merging | Enabled. Require at least 1 approving review; enable dismissal of stale approvals after new commits and require review from Code Owners when a CODEOWNERS file is adopted. |
+| Block force pushes | Enabled. |
+| Required status checks | Require the exact successful checks listed below, with no test-only bypass. |
+| Conversation resolution | Enabled before merge. |
+| Bypass actors | Keep to repository administrators/maintainers only, document emergency use, and do not use bypass as the normal merge path. |
+
+The required status checks should include the following exposed check names:
+
+| Required check | Why it is required |
+|---|---|
+| `MotionLoom Quality / quality` | Full regression, intelligence, runtime, attestation and quality gate. |
+| `Security Analysis / CodeQL (javascript)` | JavaScript security analysis. |
+| `Security Analysis / CodeQL (python)` | Python security analysis. |
+| `Security Analysis / Dependency review` | Dependency change review. |
+| `Documentation and Package Hygiene / Docs, metadata and npm package` | Docs, metadata and package-surface checks. |
+| `Dev Lab Build / Run browser review harness` | Browser review harness integrity. |
+| `Frame Generation Lock / Lock, compose and preflight` | Frame-lock and action-aware preflight contract. |
+| `Published Consumer Frame Dogfood / Published package → 12 frames → Dev Lab` | Installed/published consumer integration proof. |
+| `MotionLoom Apple / Swift packages and iOS Simulator compatibility` | Apple package and simulator compatibility. |
+
+The exact check labels can change when workflow job names change. After creating the ruleset, open a test pull request and select the checks as GitHub exposes them for the current default branch; do not guess a check name that is not present in the branch's status context.
+
+## Maintenance policy
+
+Do not require a check that is intentionally skipped for a given path unless GitHub's ruleset semantics and workflow path filters are verified to keep the branch mergeable. If a required hosted environment is unavailable, fix or replace the check rather than bypassing the protection. The repository owner should review administrator bypass access periodically and record any emergency merge in the PR.
+
+## Manual verification
+
+After saving the ruleset, confirm that a direct push to `main` is rejected, a pull request without all required checks cannot merge, stale approvals are dismissed after a new commit, force-push/delete operations are blocked, and an administrator bypass is an explicit exceptional path rather than an implicit permission.

package/docs/EXTERNAL-CORPUS.md

@@ -0,0 +1,26 @@
+# External analyzer corpus
+
+MotionLoom keeps external project evaluation **opt-in**. The default CI path never clones, installs, builds, tests or executes code from third-party repositories. A checkout is considered evidence only when the caller explicitly fetches it into a workspace and the evaluator records its source and commit.
+
+## Reproduce the corpus evaluation
+
+From the repository root, run:
+
+```bash
+rm -rf /tmp/motionloom-external-corpus
+python3 scripts/fetch-project-corpus.py \
+  --workspace /tmp/motionloom-external-corpus \
+  --all \
+  --depth 1
+python3 scripts/eval-projects.py \
+  --workspace /tmp/motionloom-external-corpus \
+  --output /tmp/motionloom-external-corpus/evaluation.json
+```
+
+The fetch helper reads the allowlisted repository URLs and relative paths from `tests/evals/project-corpus.json`, records the resolved commit in `.motionloom-corpus-fetch.json`, and performs no package installation or external code execution. The evaluator runs MotionLoom's bounded analyzer only; it writes a separate report containing the available project count, expected signals, scan budgets and status.
+
+The current manifest covers Motion One, GSAP and Rive React as external projects, in addition to the first-party repository. On 21 Aug 2026, a depth-one checkout of all three external projects produced `available_external_projects=3` and `status=pass`. This is analyzer compatibility evidence, not a guarantee of runtime correctness, design quality or product value in arbitrary host applications.
+
+## Evidence policy
+
+External evidence must remain labeled with its source URL, resolved commit and fetch timestamp. Missing or unavailable checkouts must produce `insufficient_evidence`; `--allow-insufficient` may make a local report non-blocking, but it must not turn missing evidence into a pass. No external checkout should be added to the npm package or committed into this repository.

package/docs/STATUS.md

@@ -4,7 +4,7 @@
 
 ## Current release posture
 
-MotionLoom's repository source and package manifest carry **2.6.0 release metadata**. The publication state of the npm registry and GitHub Release/tag must be verified against the latest release workflow rather than inferred from this document. The repository has a cross-platform CLI, one-command project onboarding, durable Project Memory, Agent interoperability surfaces, artifact-first handoff, runtime evidence, Visual Truth, Remediation Learning, signed attestation, AI-first asset provenance, a truthful code-authored runtime lane and an interactive browser-based Dev Lab review workbench. Dev Lab now supports hash-bound live playback, arbitrary project-defined action libraries, and optional state/transition review flows in addition to deterministic snapshot evidence. The protected manual release workflow verifies package/changelog/release-note alignment before publication.
+MotionLoom's repository source and package manifest carry **2.6.1 release metadata**. The npm registry now resolves `motionloom@2.6.1`, and the `v2.6.1` Git tag is bound to the release-preparation main commit; future publication state must still be verified against the registry/tag rather than inferred from this document alone. The repository has a cross-platform CLI, one-command project onboarding, durable Project Memory, Agent interoperability surfaces, artifact-first handoff, runtime evidence, Visual Truth, Remediation Learning, signed attestation, AI-first asset provenance, a truthful code-authored runtime lane and an interactive browser-based Dev Lab review workbench. Dev Lab supports hash-bound live playback, arbitrary project-defined action libraries and optional state/transition review flows; generated frame sequences additionally use a machine-readable Frame Generation Lock plus fail-closed measured preflight so isolated source geometry is controlled before and after generation. The protected manual release workflow verifies package/changelog/release-note alignment before publication.
 
 The repository is **engineering-ready for continued integration work**, not a universal production certification for every animation framework or every host project. CI status must be read from the latest GitHub Actions run, not inferred from historical audit prose.
 
@@ -15,6 +15,7 @@ The repository is **engineering-ready for continued integration work**, not a un
 | Lottie JSON and SVG cutout rig | End-to-end contract evidence | Context binding, source binding, runtime snapshots, Dev Lab review, quality gate and PR preflight have deterministic fixtures | Visual quality for every brand, asset or device |
 | Rive, GSAP and Framer Motion | Adapter and fixture evidence | Framework-specific runtime adapters and smoke checks can render representative scenes through browser/runtime paths | Equivalent coverage to the Lottie path across arbitrary projects |
 | Project Memory | Contract and relocation evidence | Stable project identity, atomic persistence, integrity guard, freshness states and path rebinding after relocation | Automatic correctness of an Agent's inferred decision |
+| Generated multi-frame assets | Published-package consumer contract evidence | An isolated consumer installs `motionloom@2.6.1`, composes a 12-frame lock, validates 12 unique isolated PNG sources, blocks a deliberately shared neighboring source, and plays the accepted 12-frame set through live Dev Lab controls | Image-model art quality, identity fidelity on arbitrary generated assets, artist authorship, licence authority, production/runtime approval or user approval |
 | Semantic intelligence | Deterministic evaluation evidence | Project graph, provenance, Motion IR, continuity, fix-plan and adversarial/deep-stress contracts; bounded analyzer reports scan budgets and truncation | Human-level design judgment, external-project product-value evidence or guaranteed first-pass acceptance |
 | Dev Lab | Interactive review infrastructure evidence | Identity-bound candidate loading, live runtime playback controls, arbitrary Action Library discovery, state/transition and review-sequence testing, deterministic snapshots, user checklist and review export | A full visual authoring editor, automatic approval or PR authorization |
 
@@ -30,4 +31,4 @@ Use the following order when sources disagree:
 
 ## Known next work
 
-The bounded analyzer has been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md). The 2.5.x publication chain established npm/GitHub release provenance, and 2.6.0 adds a substantially richer Dev Lab review surface without weakening the human approval boundary. The highest-value next evidence work is consumer-project review of real action sets and transitions, followed by paired product evaluation across more real projects and repeating the same provenance verification for each new release. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert runtime success or heuristic warnings into approval.
+The bounded analyzer has been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md) and the reproducible [external corpus workflow](EXTERNAL-CORPUS.md). The 2.5.x publication chain established npm/GitHub release provenance, 2.6.0 added the richer Dev Lab review surface, and 2.6.1 added proactive machine-readable frame-generation geometry control without weakening the human approval boundary. A published-package isolated consumer dogfood now covers a deterministic 12-frame generation/preflight/runtime/review path, including rejection of shared-source contamination; this deliberately remains synthetic contract evidence rather than a claim about image-generator visual quality. The next evidence work is user review inside a real consumer project with genuinely generated action frames and project-specific transitions, followed by paired product evaluation across more real projects and repeating the same provenance verification for each new release. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert runtime success or heuristic warnings into approval.

package/docs/audits/field-test-after-hardening-2026-08-21.md

@@ -0,0 +1,25 @@
+# Field test after hardening
+
+## Browser pass 1
+
+Candidate `9130000e6b6bc610c8d8` loaded from `http://127.0.0.1:4190` as `LIVE RUNTIME` / `LIVE SPRITE RUNTIME`. It was bound to task `browser-review-smoke-task`, used the sprite bundle hash `d8c2cb98a5cc089637b289580d773108199865b3707a196f54ecd943c71659a7`, and exposed the two required actions `idle` and `reverse`.
+
+Selecting `reverse` reset the runtime to `reverse-00.png`, changed the inspector to `animation=reverse`, and moved review coverage from `1/2` to `2/2`. The inspector showed `playing=false`, `frame=0`, `totalFrames=3`, `fps=6`, `loop=false`, `mode=live-runtime`, and `runtime=sprite-sequence`.
+
+## Browser pass 2
+
+The live controls behaved correctly in browser: `restart` returned to frame 1, `stepFrames(1)` moved to frame 2 at 50%, setting speed `2x` and loop `true` updated the runtime, and play/pause ended at frame 3 with `playing=false`. The image source followed the declared sprite files, no console errors were observed, all four checklist checkboxes remained unchecked, and Approve remained disabled. This confirms the human review gate was not bypassed by live runtime success.
+
+## Browser pass 3
+
+With live coverage already at `2/2`, Approve was initially disabled because all four review checklist items were unchecked. Clicking all four checkboxes changed `Approve` to enabled and all four boxes to `true`, confirming the gate requires explicit checklist confirmation in addition to runtime coverage. A subsequent Reset action triggered a page navigation/reload, so the browser context was reloaded rather than returning a synchronous DOM payload; this is recorded as an observed reset behavior and will be checked again after the page settles.
+
+## Browser pass 4
+
+After the reset reload settled, the candidate remained bound to the same task and hash. Runtime returned to `idle`, frame 1/3, progress 0, `playing=false`, speed 1, loop true; coverage returned to `1/2`, all four checklist items were unchecked, Approve was disabled, and no console errors were observed. Reset therefore clears review progress rather than preserving an accidental approval-ready state.
+
+## Fresh field test after CI fix
+
+A fresh detached worktree from commit `e146164` was prepared through `review-hook prepare --root ...`; the previously observed external-root failure no longer occurred after passing `MOTIONLOOM_PROJECT_ROOT` and `cwd` to the internal Dev Lab/report subprocesses. The resulting candidate was `9130000e6b6bc610c8d8`, bound to `browser-review-smoke-task`, with live sprite bundle hash `d8c2cb98a5cc089637b289580d773108199865b3707a196f54ecd943c71659a7`.
+
+The fresh browser load showed `LIVE RUNTIME` / `LIVE SPRITE RUNTIME`, two required actions, and coverage `1/2`. Selecting `reverse` reset to `reverse-00.png`, changed the inspector to `animation=reverse`, and moved coverage to `2/2`; the candidate/task identity remained consistent.

package/docs/releases/2.6.1.md

@@ -0,0 +1,57 @@
+# MotionLoom 2.6.1
+
+MotionLoom 2.6.1 closes the generated multi-frame consistency gap discovered during real Codex animation work. The release makes frame consistency proactive: the Agent binds one accepted identity/reference into a machine-readable Frame Generation Lock before producing later poses, then validates the real PNG bytes after every generated frame before any atlas is packed.
+
+## What changed
+
+### Frame Generation Lock before generation
+
+Generated frame sequences now have a provider-neutral contract in `schemas/frame-generation-lock.schema.json`. The lock records and verifies:
+
+- accepted identity/reference path and SHA-256;
+- exact canvas dimensions, alpha mode and color space;
+- camera/orientation and apparent character scale;
+- pivot and baseline/footline;
+- safe rectangle, transparent padding and geometry tolerances;
+- ordered frame ids, pose intent and one unique isolated output path per frame.
+
+Agents use `motionloom frame-generation-lock validate` before generation and `motionloom frame-generation-lock compose` (or `compose-all`) to build each provider-facing pose instruction from the same lock. This removes dependence on an Agent remembering or rewriting the geometry prose consistently across frame 2, frame 6 or frame 20.
+
+### Strict preflight after each generated frame
+
+`motionloom frame-set-preflight` is now a public CLI command. It re-measures actual PNG bytes and blocks shared/non-isolated source canvases, stale hashes, contamination, guard-band violations, pivot/footline drift and apparent-size drift beyond the declared tolerance.
+
+The default source policy is deliberately strict: generate one isolated source PNG per frame, validate it, and only then continue. For long actions (including six or more frames), a generated contact sheet or multi-pose sheet must not be cropped into production source frames. Atlas/sprite-sheet packing happens only after all isolated source frames pass.
+
+## Agent behavior
+
+`AGENTS.md` and the canonical Skill route Codex and other compatible Agents through this workflow automatically. The user does not need to remember to ask for equal scale, separate frames, padding, baseline consistency or pose-sheet avoidance.
+
+If one frame fails, the Agent regenerates or repairs that frame under the same lock. It must not silently resize previously accepted frames or weaken tolerances merely to make the set pass.
+
+## Verification
+
+PR #18 passed:
+
+- the dedicated Frame Generation Lock workflow;
+- MotionLoom Quality (including engine tests and cross-platform package checks);
+- Security Analysis / CodeQL;
+- Documentation and Package Hygiene.
+
+The dedicated regression suite covers stale reference hashes, duplicate outputs, pose-sheet policy, path escape, post-generation resize, public CLI composition and strict preflight.
+
+## Trust boundary
+
+This release improves source consistency and evidence quality; it does not change authority. A generator prompt, reference hash, frame lock, preflight pass, atlas pass, runtime render or signed evidence record does **not** create artist authorship, licence authority, production eligibility, production approval or user approval. Human review remains a separate bounded decision.
+
+## Updating a project
+
+After `motionloom@2.6.1` is published, update the project-local development dependency and refresh the managed Agent surface:
+
+```bash
+npm install --save-dev motionloom@2.6.1
+npx --no-install motionloom repair --yes
+npx --no-install motionloom status --json
+```
+
+For a generated multi-frame task, the Agent should then use the Frame Generation Lock before later frames and `frame-set-preflight` after each accepted frame.

package/docs/releases/2.7.0.md

@@ -0,0 +1,98 @@
+# MotionLoom 2.7.0
+
+MotionLoom 2.7.0 makes provider/tool choice explicitly project-aware. Instead of treating a provider as the product or choosing one by a fixed rule, MotionLoom first reads the animation task and project constraints, then produces a ranked **MotionLoom Recommendation** plus **MotionLoom Agent Guidance**. A user's preferred tool remains visible and influences ranking, but it never overrides hard canvas, isolation, provenance or trust constraints.
+
+This release also hardens generated multi-frame review evidence so a generator cannot manufacture an "independent" verifier claim from caller-supplied values.
+
+## What changed
+
+### MotionLoom project-aware asset planning
+
+Use `motionloom asset-generation-plan plan` before an Agent calls an image/animation provider. The planner evaluates the declared target canvas, frame count/isolation, alpha/pixel-art policy, available project contracts, adapter capabilities and optional user preferences.
+
+The plan separates four ideas that were previously easy to conflate:
+
+- **recommendation status** — whether MotionLoom considers the route useful for this project/task;
+- **execution status** — `verified`, `provisional` or `blocked`;
+- **availability** — whether the tool is actually available in the current environment, known but user-managed, unavailable, or unknown;
+- **execution eligibility** — the final guarded decision used by strict mode.
+
+Normal planning may recommend a provisional/manual route when it is the best project fit. `--strict` still fails closed unless a route satisfies the active execution policy. Recommendation never upgrades provider evidence.
+
+### User preference without blind obedience
+
+`asset-generation-request.json` can declare preferred or excluded adapter IDs. A preferred route gets additional ranking weight when it fits the project, but MotionLoom still reports incompatible geometry, missing isolation, unknown availability or evidence gaps. If a requested tool cannot satisfy a hard requirement, MotionLoom explains the mismatch and surfaces safer alternatives instead of silently switching tools or weakening the contract.
+
+No provider is hard-coded as MotionLoom's default. PixelLab entries in the registry are examples of provider-specific capability metadata and remain `scaffold_only` until real provider/runtime evidence exists.
+
+### MotionLoom Agent Guidance
+
+Human and JSON planner output now identify MotionLoom as the producer and include project assessment, rationale and the recommended Agent route. Guidance sends provider output back through MotionLoom validation instead of ending at generation:
+
+1. resolve provider/tool availability if needed;
+2. generate/import at the declared source geometry;
+3. apply only declared MotionLoom adaptation when needed;
+4. bind one accepted frame to the action/identity contracts;
+5. run MotionLoom frame geometry/asset consistency;
+6. run MotionLoom action separation;
+7. review the runtime candidate in MotionLoom Dev Lab;
+8. keep `approval` and `production_approved` false until human review.
+
+The installed `agent-card.json` exposes the planner, action-separation and adaptation capabilities so compatible Agents can discover this workflow directly from the package.
+
+### Safe canvas adaptation
+
+`motionloom asset-adapt pad` provides deterministic transparent padding and integer nearest-neighbour upscaling. It refuses source overflow/cropping and does not stretch content. The adaptation report remains evidence only and preserves `approval: false` and `production_approved: false`.
+
+### Action-scoped verification provenance
+
+Frame/action evidence is now schema `0.2`. Generator-side envelopes are explicitly `declared`, quarantined evidence. An `independently_bound` envelope must point to a separate verifier artifact whose bytes and canonical result are hash-bound to the sequence, action, frame, image, identity lock, generator and verifier identities.
+
+MotionLoom verifies those bindings, but does not overclaim what hashes prove: integrity/provenance claims are not proof that a named producer truly performed an independent semantic review. Human approval remains separate.
+
+## Verification
+
+PR #21 and PR #22 were integrated only after hosted checks passed. Coverage included:
+
+- MotionLoom Quality;
+- Security Analysis / CodeQL and dependency review;
+- Documentation and Package Hygiene;
+- Dev Lab Build;
+- Frame Generation Lock;
+- MotionLoom Apple compatibility;
+- installed-package consumer smoke;
+- planner and asset-adaptation adversarial regressions;
+- action-separation provenance regressions;
+- runtime and quality-attestation validation;
+- Intelligence evaluation;
+- deep audit: 6,900/6,900 passed with 0 false positives and 0 false negatives.
+
+The release workflow re-runs documentation/package metadata validation, Skill Doctor, the full regression suite, installed-package smoke and release traceability before npm publication.
+
+## Trust boundary
+
+MotionLoom 2.7.0 recommends tools; it does not silently authorize them. Provider metadata, a high ranking, user preference, a successful adaptation, verifier hashes, CI success or a passing quality gate cannot mint artist authority, licence authority, production eligibility or user approval.
+
+The planner does not store provider credentials or invoke authenticated provider APIs. Real provider integration should bind availability and execution evidence separately and promote an adapter to `verified` only when fresh independent evidence supports that status.
+
+## Updating a project
+
+After `motionloom@2.7.0` is published:
+
+```bash
+npm install --save-dev motionloom@2.7.0
+npx --no-install motionloom repair --yes
+npx --no-install motionloom status --json
+```
+
+Then ask the Agent to work normally on the animation task. When generated/provider-backed assets are relevant, MotionLoom should understand the project first and produce its recommendation/guidance without requiring the user to preselect a provider.
+
+To inspect the planner directly:
+
+```bash
+npx --no-install motionloom asset-generation-plan plan \
+  --request examples/agent-consumer/asset-planning/pixellab-hero-256x448-request.json \
+  --project-root .
+```
+
+The important behavior to evaluate during dogfood is not whether MotionLoom always selects one specific tool. Evaluate whether it correctly understands the project constraints, explains the available choices, respects an explicit user preference when safe, and routes the Agent back through MotionLoom verification and human review.

package/examples/agent-consumer/asset-consistency/action-sequence/envelopes/walk.00.json

@@ -0,0 +1,32 @@
+{
+  "schema_version": "0.1",
+  "generator_agent_id": "motionloom-generator-v1",
+  "sequence_id": "hero-walk-v1",
+  "action_id": "walk",
+  "frame_id": "walk.00",
+  "frame_index": 0,
+  "image": "assets/hero-frame-00.png",
+  "image_sha256": "75ce90653a01a23bcfab1aef83647d6364d3edbf6e4a44b84c635338c12b9248",
+  "identity_lock_sha256": "59d6b09622b19839b8c9342fb043965ea3f515c8979d769284d413f60a5f7e2d",
+  "verifier": {
+    "verifier_id": "motionloom-separation-verifier-v1",
+    "expected_action": "walk",
+    "top_competitor": "run",
+    "margin": 0.42,
+    "threshold": 0.2,
+    "status": "pass",
+    "method": "independent-action-rubric-v1",
+    "verification_mode": "independently_bound",
+    "evidence": {
+      "artifact": "action-sequence/verifier-evidence/walk.00.json",
+      "artifact_sha256": "cd9adf1eafb82e1a36056934495a012b0caa87eb26e26213fff28cc25d90e8a0",
+      "result_sha256": "c1e08d34fc0fab0c32a6eb1ad2c8e5e4c2c659f91a0d2f8295759c6c8e5fd804",
+      "provenance": {
+        "kind": "separate_verifier_artifact",
+        "producer_id": "motionloom-independent-verifier-v1",
+        "run_id": "fixture-run-2026-08-22"
+      }
+    }
+  },
+  "approval": false
+}

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

@@ -0,0 +1,32 @@
+{
+  "schema_version": "0.1",
+  "generator_agent_id": "motionloom-generator-v1",
+  "sequence_id": "hero-walk-v1",
+  "action_id": "walk",
+  "frame_id": "walk.01",
+  "frame_index": 1,
+  "image": "assets/hero-frame-01.png",
+  "image_sha256": "1eaf21df83ed49e490ceb7db1e1a14c58e5227bcb4f1fd79a70e8ad3ee7d38ad",
+  "identity_lock_sha256": "59d6b09622b19839b8c9342fb043965ea3f515c8979d769284d413f60a5f7e2d",
+  "verifier": {
+    "verifier_id": "motionloom-separation-verifier-v1",
+    "expected_action": "walk",
+    "top_competitor": "jump",
+    "margin": 0.39,
+    "threshold": 0.2,
+    "status": "pass",
+    "method": "independent-action-rubric-v1",
+    "verification_mode": "independently_bound",
+    "evidence": {
+      "artifact": "action-sequence/verifier-evidence/walk.01.json",
+      "artifact_sha256": "9e9ec13a79d2384cb9320ed04204e31262a640104685307ede836dd9f3a0244e",
+      "result_sha256": "0ad134eda50c1d6a161d0395d03f43a51a15767665bc06b203564dd327ce0904",
+      "provenance": {
+        "kind": "separate_verifier_artifact",
+        "producer_id": "motionloom-independent-verifier-v1",
+        "run_id": "fixture-run-2026-08-22"
+      }
+    }
+  },
+  "approval": false
+}

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

@@ -0,0 +1,32 @@
+{
+  "schema_version": "0.1",
+  "generator_agent_id": "motionloom-generator-v1",
+  "sequence_id": "hero-walk-v1",
+  "action_id": "walk",
+  "frame_id": "walk.02",
+  "frame_index": 2,
+  "image": "assets/hero-frame-02.png",
+  "image_sha256": "de88659cb7a57ae9c10b6e3e84e04e54bdc07e9971d5c42160a315d41b38fbc3",
+  "identity_lock_sha256": "59d6b09622b19839b8c9342fb043965ea3f515c8979d769284d413f60a5f7e2d",
+  "verifier": {
+    "verifier_id": "motionloom-separation-verifier-v1",
+    "expected_action": "walk",
+    "top_competitor": "attack",
+    "margin": 0.36,
+    "threshold": 0.2,
+    "status": "pass",
+    "method": "independent-action-rubric-v1",
+    "verification_mode": "independently_bound",
+    "evidence": {
+      "artifact": "action-sequence/verifier-evidence/walk.02.json",
+      "artifact_sha256": "28b0c41b059d91299456877259b48304a93045334f55864b3a90a29ac72535e6",
+      "result_sha256": "529c083ac2959e80524234910750c015377d0d7be59b27ca5b14edf6585cd1cc",
+      "provenance": {
+        "kind": "separate_verifier_artifact",
+        "producer_id": "motionloom-independent-verifier-v1",
+        "run_id": "fixture-run-2026-08-22"
+      }
+    }
+  },
+  "approval": false
+}

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

@@ -0,0 +1,32 @@
+{
+  "schema_version": "0.1",
+  "generator_agent_id": "motionloom-generator-v1",
+  "sequence_id": "hero-walk-v1",
+  "action_id": "walk",
+  "frame_id": "walk.03",
+  "frame_index": 3,
+  "image": "assets/hero-frame-03.png",
+  "image_sha256": "161d906dc850cd3d3ee970b97406fc36bcdf1c34222ac94171a05672bf64d957",
+  "identity_lock_sha256": "59d6b09622b19839b8c9342fb043965ea3f515c8979d769284d413f60a5f7e2d",
+  "verifier": {
+    "verifier_id": "motionloom-separation-verifier-v1",
+    "expected_action": "walk",
+    "top_competitor": "run",
+    "margin": 0.32999999999999996,
+    "threshold": 0.2,
+    "status": "pass",
+    "method": "independent-action-rubric-v1",
+    "verification_mode": "independently_bound",
+    "evidence": {
+      "artifact": "action-sequence/verifier-evidence/walk.03.json",
+      "artifact_sha256": "e1ddede6701ab41f5a5ac2d35d32d85b148e82a1cf53285877195d115166b681",
+      "result_sha256": "259be183f714d57cec7721127c0dfe61b552e8fbcbb189b782b662ed57ac138b",
+      "provenance": {
+        "kind": "separate_verifier_artifact",
+        "producer_id": "motionloom-independent-verifier-v1",
+        "run_id": "fixture-run-2026-08-22"
+      }
+    }
+  },
+  "approval": false
+}

package/examples/agent-consumer/asset-consistency/action-sequence/hero-walk-action-manifest.json

@@ -0,0 +1,81 @@
+{
+  "schema_version": "0.2",
+  "sequence_id": "hero-walk-v1",
+  "asset_identity": "character/hero-male",
+  "action_id": "walk",
+  "identity_lock_sha256": "59d6b09622b19839b8c9342fb043965ea3f515c8979d769284d413f60a5f7e2d",
+  "generator_agent_id": "motionloom-generator-v1",
+  "forbidden_action_ids": [
+    "run",
+    "jump",
+    "attack"
+  ],
+  "actions": [
+    {
+      "action_id": "walk",
+      "positive_cues": [
+        "alternating contact and passing phases",
+        "upright body and natural counter-swing"
+      ],
+      "negative_cues": [
+        "no airborne phase",
+        "no attack or hurt silhouette"
+      ]
+    },
+    {
+      "action_id": "run",
+      "positive_cues": [
+        "longer stride and stronger forward lean"
+      ],
+      "negative_cues": [
+        "not an upright alternating walk"
+      ]
+    },
+    {
+      "action_id": "jump",
+      "positive_cues": [
+        "airborne body and compressed takeoff/landing"
+      ],
+      "negative_cues": [
+        "feet do not remain on shared footline"
+      ]
+    },
+    {
+      "action_id": "attack",
+      "positive_cues": [
+        "directed weapon or strike motion"
+      ],
+      "negative_cues": [
+        "no locomotion cycle"
+      ]
+    }
+  ],
+  "frames": [
+    {
+      "frame_index": 0,
+      "frame_id": "walk.00",
+      "image": "assets/hero-frame-00.png",
+      "envelope": "action-sequence/envelopes/walk.00.json"
+    },
+    {
+      "frame_index": 1,
+      "frame_id": "walk.01",
+      "image": "assets/hero-frame-01.png",
+      "envelope": "action-sequence/envelopes/walk.01.json"
+    },
+    {
+      "frame_index": 2,
+      "frame_id": "walk.02",
+      "image": "assets/hero-frame-02.png",
+      "envelope": "action-sequence/envelopes/walk.02.json"
+    },
+    {
+      "frame_index": 3,
+      "frame_id": "walk.03",
+      "image": "assets/hero-frame-03.png",
+      "envelope": "action-sequence/envelopes/walk.03.json"
+    }
+  ],
+  "status": "review_required",
+  "approval": false
+}

package/examples/agent-consumer/asset-consistency/action-sequence/verifier-evidence/walk.00.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.00",
+  "frame_index": 0,
+  "image_sha256": "75ce90653a01a23bcfab1aef83647d6364d3edbf6e4a44b84c635338c12b9248",
+  "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.42,
+    "threshold": 0.2,
+    "status": "pass",
+    "method": "independent-action-rubric-v1"
+  },
+  "result_sha256": "c1e08d34fc0fab0c32a6eb1ad2c8e5e4c2c659f91a0d2f8295759c6c8e5fd804",
+  "provenance": {
+    "kind": "separate_verifier_artifact",
+    "producer_id": "motionloom-independent-verifier-v1",
+    "run_id": "fixture-run-2026-08-22"
+  }
+}