motionloom 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Len Hon BP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# MotionLoom
+
+A coding-agent skill for professional animation development: motion, character body rigs and assets. It does not guess — it **understands the host project, plans from a signed motion spec, generates from vetted source assets, renders everything in the Dev Lab for live testing, and only then confirms into a pull request**.
+
+## Install from npm
+
+MotionLoom is distributed as the `motionloom` npm package. The package ships the installable Skill contract, framework adapters, Intelligence Core schemas, evidence verifiers and a small CLI wrapper around the canonical Python scripts.
+
+```bash
+npm install --global motionloom
+motionloom doctor
+motionloom --help
+```
+
+The CLI requires **Node.js 18+** and **Python 3.11+**. Installation does not grant approval, commit changes or open a pull request; browser review and explicit repository-side-effect confirmation remain mandatory.
+
+## Quick start
+
+```bash
+# 1. Understand the project
+bash scripts/analyze.sh /path/to/your/project
+
+# 1b. Start a transparent task ledger for Agent/human handoff
+python3 scripts/report.py init --task-id onboarding-wave \
+  --scene my-scene --intent "Character wave in onboarding" \
+  --project-name your-project
+
+# 2. Plan & sign a spec (example: a loading animation)
+python3 src/core/spec.py generate loading --context /path/to/your/project/project-context.json \
+  --output motion-spec.json --loop
+
+# 3. Generate a body rig, then pose it
+python3 src/rig/cutout_rig.py build \
+  --input assets/library/avatar-base.svg --output rigged.svg
+python3 src/rig/cutout_rig.py pose rigged.svg --pose walk \
+  --duration 1.2 --fps 30 --out walk.json
+
+# 3b. Bind the scene source to an authoritative provenance record
+python3 scripts/manifest.py bind-source --scene my-scene \
+  --source animation.json --kind project \
+  --authority "host project manifest" --license MIT
+
+# 4. Render runtime verification snapshots (0/50/100%; placeholders fail)
+bash scripts/render.sh my-scene
+
+# 4b. Package the Lottie source as a dotLottie v2 archive when required
+bash scripts/to-dotlottie.sh my-scene
+
+# 4c. Verify Rive, GSAP and Framer Motion through the real browser harness
+node scripts/runtime-adapters.mjs
+
+# 4d. Capture runtime telemetry and verify evidence bindings externally
+bash scripts/capture-runtime-telemetry.sh my-scene artifacts/onboarding-wave
+
+# 4e. Derive and verify a signed task-bound statement against a managed trust policy
+python3 scripts/attestation.py statement --scene-dir src/output/my-scene \
+  --task-dir artifacts/onboarding-wave --context /path/to/your/project/project-context.json \
+  --output artifacts/onboarding-wave/attestation-statement.json
+python3 scripts/attestation.py build --statement artifacts/onboarding-wave/attestation-statement.json \
+  --private-key <managed-ed25519-key> --key-id <key-id> \
+  --output artifacts/onboarding-wave/attestation.json
+python3 scripts/attestation-verifier.py --attestation artifacts/onboarding-wave/attestation.json \
+  --trust-policy artifacts/onboarding-wave/trust-policy.json \
+  --expected-task-id onboarding-wave --expected-scene my-scene
+
+# 5. Boot the Dev Lab to test & fix interactively
+bash scripts/devlab.sh my-scene
+
+# 6. Run the acceptance gate, then confirm and ship
+python3 scripts/quality-gate.py --scene my-scene \
+  --context /path/to/your/project/project-context.json \
+  --task-dir artifacts/onboarding-wave --require-telemetry --require-attestation
+
+# 6. Collect evidence and render the user-facing report
+python3 scripts/report.py collect --task-dir artifacts/onboarding-wave
+python3 scripts/report.py render --task-dir artifacts/onboarding-wave
+
+# 7. Confirm and ship only after review
+bash scripts/pr.sh my-scene
+```
+
+The kit is intended to run from a Git clone. Copy `project-context.example.json` only as a schema reference; always generate the real context with `scripts/analyze.sh` against the host project. Do not commit a context containing a temporary path or another project's brand tokens.
+
+For a reproducible review fixture, keep `project-context.json`, `quality-report.json`, `review.json`, `execution-report.json`, `handoff.json` and `artifact-manifest.json` under the repository's `artifacts/<task-id>/` directory. `scripts/pr.sh` rejects task bundles outside the repository, requires the task scene to match the requested scene, runs the semantic report check, and stages the evidence bundle together with the scene. This prevents a gate from consuming evidence that is omitted from the resulting commit.
+
+Runtime adapter evidence can be bound to a scene and its exact source/manifest bytes:
+
+```bash
+RUNTIME_SCENE=my-scene \
+RUNTIME_SOURCE_PATH=src/output/my-scene/animation.json \
+RUNTIME_MANIFEST_PATH=src/output/my-scene/manifest.json \
+node scripts/runtime-adapters.mjs
+```
+
+When these variables are supplied, `runtime-evidence.json` records `scene`, `source_sha256` and `manifest_sha256`; the quality gate rejects evidence copied from another scene or generated against an older manifest.
+
+### Intelligence Core v0.1 + P1 feedback intelligence + trust-boundary hardening + evidence interoperability + signed attestation
+
+After render and before strict acceptance, build the task-bound Intelligence Core artifacts. They give an Agent a single relationship graph, step-level provenance, framework-neutral Motion IR, capability selection policy and deterministic replay inventory instead of requiring it to infer relationships from prose and unrelated files:
+
+```bash
+python3 scripts/intelligence.py motion-ir build --task-dir artifacts/onboarding-wave
+python3 scripts/intelligence.py graph build --task-dir artifacts/onboarding-wave
+python3 scripts/intelligence.py provenance build --task-dir artifacts/onboarding-wave
+python3 scripts/intelligence.py replay capture --root . --task-dir artifacts/onboarding-wave
+python3 scripts/intelligence.py semantic-lint build --task-dir artifacts/onboarding-wave
+python3 scripts/intelligence.py semantic-lint benchmark --task-dir artifacts/onboarding-wave \
+  --iterations 25 --threshold-ms 500
+bash scripts/capture-runtime-telemetry.sh my-scene artifacts/onboarding-wave
+python3 scripts/intelligence.py continuity build --task-dirs artifacts/onboarding-wave
+python3 scripts/intelligence.py fix-plan build --task-dir artifacts/onboarding-wave \
+  --reports semantic-lint-report.json continuity-report.json
+python3 scripts/quality-gate.py --scene my-scene \
+  --context /path/to/your/project/project-context.json \
+  --task-dir artifacts/onboarding-wave \
+  --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation
+python3 scripts/eval-intelligence.py
+```
+
+Semantic lint reports intent, timing, easing, accessibility and performance findings with severity, confidence and evidence. The benchmark records rule coverage and p95 execution time against a 500 ms default threshold; it does not claim to measure human visual quality. Continuity analysis checks context and transition drift across an ordered scene set. `fix-plan.json` converts findings into root cause, affected artifacts, selective rerun scope and verification commands; it does not auto-approve a scene. The 1.8.0 hardening layer rejects symlinked or cross-task Intelligence artifacts, binds replay to task identity, chooses one deterministic passing report bundle per scene, and makes the Dev Lab reject cross-origin or mismatched task/candidate evidence. The 1.9.0 evidence layer captures scrub-point, RAF timing, runtime-state and source/manifest/Motion IR hash bindings, then lets a read-only external verifier reject stale, tampered, cross-task or path-escaped evidence. The 2.0.0 attestation layer signs canonical task-bound hashes with a DSSE-compatible Ed25519 envelope and checks signer lifecycle through fail-closed trust policy. A verifier pass still means integrity only: runtime assertions, Dev Lab review and user consent remain mandatory; `approval` is always `false`. See [Intelligence Core](references/intelligence-core.md), [signed attestation reference](references/signed-attestation.md), the [1.9.0 threat model](docs/audits/1.9.0-evidence-interoperability-threat-model.md) and the [2.0.0 release note](docs/releases/2.0.0.md).
+
+## Pipeline
+
+| Step | Module | What it does |
+|------|--------|--------------|
+| 01 · Understand | `src/core/analyzer.py` | Reads package.json, design tokens and existing motion language; emits `project-context.json` inside the target project |
+| 02 · Plan | `src/core/spec.py` | Generates & validates the motion spec against the framework matrix, easing canon and performance budget |
+| 03 · Source | `assets/library/` | Vetted, traceable source assets with an attribution table — the authoritative geometry |
+| 04 · Generate | `src/rig/cutout_rig.py`, `templates/` | Canonical templates per framework; 20-bone cutout body rigs with parent-first order |
+| 05 · Dev Lab | `dev-lab/` | Self-contained static workbench: preview rendered evidence, scrub, quality checklist, fix notes, review export |
+| 06 · Confirm → PR | `scripts/pr.sh` | Commits scene + spec + snapshots, opens the PR with an evidence body |
+
+## Repository layout
+
+| Path | Purpose |
+|------|---------|
+| `SKILL.md` | The agent-skill definition (installable into any coding agent) |
+| `src/core/` | Analyzer, spec validator, snapshot renderer |
+| `src/rig/` | Cutout character body rig engine |
+| `templates/` | Canonical Lottie / Rive / GSAP / Framer Motion templates |
+| `assets/library/` | Vetted source assets + attribution, including the MIT Rive adapter fixture |
+| `scripts/` | Pipeline CLI plus Intelligence Core (`analyze`, `render`, `devlab`, `pr`, `quality-gate`, `validate-lottie`, `to-dotlottie`, `runtime-adapters`, `capture-runtime-telemetry`, `evidence-verifier`, `attestation`, `attestation-verifier`, `attestation-keygen`, `skill-doctor`, `report`, `report-contract`, `intelligence`, `eval-intelligence`) |
+| `dev-lab/` | Self-contained static Dev Lab + Playwright snapshot harness |
+| `agent-card.json` | Capability discovery, runtime levels and side-effect policy for other Agents |
+| `schemas/` | Task, report, artifact-manifest, scene-manifest, handoff, Intelligence Core, signed-attestation and trust-policy JSON Schemas |
+| `references/` | Progressive-disclosure contracts for reporting, runtime capability, dotLottie packaging and Intelligence Core |
+| `artifacts/<task-id>/` | Per-task ledger, evidence, review, issue register and handoff bundle |
+| `tests/` | Deterministic engine tests |
+| `.github/workflows/quality.yml` | CI that re-runs the quality gate on every PR |
+
+## The quality gate
+
+A scene is only "ready" when, together, the Dev Lab checklist passes, runtime snapshot frames exist at 0/50/100%, the context-bound JSON spec matches the implementation, brand tokens come from the target project's `project-context.json`, the required `source_binding` traces `manifest.file` to an authoritative source with a matching checksum, the P1 reports have been validated and the semantic-lint benchmark is below threshold. For strict observability runs, runtime telemetry and the external verifier report must also pass their identity, freshness and hash checks; for production trust runs, the signed attestation must verify against an active trust-policy key and bind the same task/scene/material hashes. A warning or valid signature may require human review and a selective fix; neither is silently converted into approval. CI reproduces these checks on every PR — see [CHECKLIST.md](docs/CHECKLIST.md).
+
+## Transparent task reporting
+
+The Skill does not end with a prose claim that an animation is complete. Each task can be represented by `artifacts/<task-id>/`, which records the lifecycle state, decisions, changed artifacts, checksums, quality result, review decision, open problems and the next Agent handoff. Generate the report with `python3 scripts/report.py render --task-dir artifacts/<task-id>`.
+
+The report must distinguish **completed**, **verified**, **not completed**, **blocked/failed**, **structure problems** and **recommended next Agent/Skill**. A scaffold-only runtime must be reported as `scaffold`; it cannot be described as `runtime-verified` until its adapter test has produced evidence.
+
+Run `python3 scripts/skill-doctor.py --json` when changing the Skill package. It checks the frontmatter, required directories, schemas, Agent Card and references. CI also requires a task report/handoff bundle for changed scenes, so a future Agent cannot silently modify a scene without leaving a reviewable trail.
+
+## Agent interoperability and public skills
+
+`agent-card.json` is the discovery surface. It declares inputs, outputs, verified versus scaffold-only runtimes and Git side effects. Use official or public skills as focused references and adapters rather than copying their prompts into this repository: [LottieFiles dotLottie Web](https://github.com/LottieFiles/dotlottie-web/blob/main/SKILL.md) for runtime APIs, [Diffusion Studio text-to-lottie](https://github.com/diffusionstudio/lottie) for optional scene scaffolding, [Claude Lottie Skill](https://github.com/b1rdmania/claude-lottie-skill/blob/main/SKILL.md) for optional brand-aware asset discovery, and the [Agent Skills specification](https://agentskills.io/specification) plus [GitHub Agent Skills documentation](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) for packaging and portability.
+
+The project-specific value remains in context binding, Motion Spec, asset provenance, runtime evidence, quality policy, review memory and handoff artifacts. The runtime adapter harness delegates rendering to the official packages; it does not reimplement Lottie/Rive runtimes, MCP transport or GitHub authentication inside this Skill.
+
+### Important trust boundary
+
+`ALLOW_PLACEHOLDER=1 bash scripts/render.sh <scene>` is diagnostic only. It creates visibly marked placeholder frames and the quality gate rejects them. A PR cannot be confirmed until the official runtime or the Dev Lab browser renderer has produced `snapshot/.render-meta.json` with `mode: runtime`.
+
+## Standards basis
+
+The audit and templates are grounded in first-party references: [LottieFiles runtimes](https://docs.lottiefiles.com/en/runtimes), the [dotLottie v2 specification](https://dotlottie.io/spec/2.0/), [Rive Web runtime](https://rive.app/docs/runtimes/web/web-js), [Rive state machines](https://rive.app/docs/runtimes/state-machines), and [GSAP accessibility guidance](https://gsap.com/resources/a11y/). End-to-end adapter evidence currently covers **Lottie JSON, dotLottie packaging, SVG cutout rigs, Rive, GSAP and Framer Motion**. Spine and Three.js remain scaffold-only until framework-specific runtime adapters are implemented.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: motionloom
+description: >-
+  Project-aware animation production and verification for UI motion, Lottie/dotLottie,
+  Rive, GSAP, Framer Motion, character body rigs, scene assets, runtime rendering,
+  Dev Lab browser review, and confirm-to-PR workflows. Use when an Agent must create, fix,
+  validate, review, or deliver animation inside an existing project.
+license: MIT
+metadata:
+  version: "2.0.0"
+  target_frameworks: "lottie,dotlottie,rive,gsap,framer-motion,spine,threejs"
+  verified_runtimes: "lottie-json,dotlottie-package,svg-cutout-rig,rive,gsap,framer-motion"
+---
+
+# MotionLoom Skill
+
+Treat every animation request as a production task, not as an isolated asset-generation prompt. Always bind the work to the host project's context, emit machine-readable artifacts, render through the target runtime, expose review evidence in Dev Lab, and stop before commit when a required gate or user confirmation is missing.
+
+## Required workflow
+
+1. **Understand** — read the host project manifest and run `bash scripts/analyze.sh <project-path>`. Load `project-context.json` from the audited project. If context is missing or ambiguous, stop at `needs_context`.
+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.
+4. **Generate** — use the matching template or rig implementation. For body animation, preserve named anatomy, pivot and parent-first hierarchy.
+5. **Render** — run `bash scripts/render.sh <scene>` 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. **Browser review handoff** — 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.
+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.
+9. **Validate** — run `python3 scripts/review-hook.py validate --task-dir artifacts/<task-id>`, `python3 scripts/intelligence.py semantic-lint benchmark --task-dir artifacts/<task-id> --iterations 25 --threshold-ms 500`, `bash scripts/capture-runtime-telemetry.sh <scene> artifacts/<task-id>`, the independent attestation verifier, `python3 scripts/report-contract.py --root . --scenes-file <changed-scenes> --require-attestation`, `python3 scripts/quality-gate.py --scene <scene> --context <context-path> --task-dir artifacts/<task-id> --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation`, and `python3 scripts/skill-doctor.py --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. **Confirm** — only after approved browser review and a passing quality gate run `TASK_DIR=artifacts/<task-id> bash scripts/pr.sh <scene>`. Commit, push and open PR are explicit side effects.
+
+## Progressive disclosure
+
+- 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 `docs/CHECKLIST.md` before marking a scene ready for review.
+- 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.
+- 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.
+
+## Non-negotiable contracts
+
+- Every task has a lifecycle state: `created`, `needs_context`, `planning`, `sourcing`, `generating`, `rendering`, `review_required`, `blocked`, `failed`, `validated`, `ready_for_pr`, or `confirmed`.
+- Every production scene has context, motion spec, manifest, source binding, runtime metadata, 0/50/100 snapshots, browser-review candidate, checklist result and review artifact.
+- `scaffold` and `static-validated` are not equivalent to `runtime-verified` or `project-integrated`.
+- Never hide a missing dependency, failed render, missing license, context drift, incomplete review or unimplemented framework behind a successful prose response.
+- Use JSON output and stable exit codes for Agent-to-Agent composition; do not require another Agent to parse chat text. The external evidence verifier is read-only and must never emit an approval decision.
+- Destructive Git actions require explicit confirmation. Use `OPEN_PR=0` for local review-only runs.
+- Intelligence Core artifacts are task-bound: graph, provenance, Motion IR and replay evidence must not be reused across tasks without revalidation.
+- Provenance hashes materials and products; replay must fail on tampered or missing files; stale capability evidence must not be selected for production acceptance.
+- 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.
+- 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.
+- Signed attestation must bind the same task, scene, context, source, manifest, Motion IR and evidence hashes; unknown, expired or revoked signers fail closed. Attestation verification is an integrity result only and must preserve `approval: false`.
+
+## Framework boundary
+
+The audited production paths are **Lottie JSON runtime rendering, dotLottie v2 packaging, SVG cutout rigging, Rive Canvas, GSAP and Framer Motion**. Their evidence is generated by `node scripts/runtime-adapters.mjs` and includes deterministic scrub points, runtime state and PNG snapshots. Spine and Three.js remain scaffold/selection paths until their adapter-specific runtime tests pass and their capability level is upgraded in `agent-card.json`.
+
+## Provenance and runtime commands
+
+Every production `src/output/<scene>/manifest.json` must include a `source_binding` object matching `schemas/scene-manifest.schema.json`. The acceptance gate rejects a missing binding, a mismatched source path, an unknown license/authority or a stale SHA-256.
+
+The Intelligence Core contracts are defined in `schemas/project-graph.schema.json`, `schemas/provenance.schema.json`, `schemas/capability-registry.schema.json`, `schemas/motion-ir.schema.json`, `schemas/signed-attestation.schema.json` and `schemas/trust-policy.schema.json`. They make project relationships, supply-chain steps, runtime selection, framework-neutral intent and signer trust inspectable without relying on prose.
+
+```bash
+# Package a Lottie JSON scene as a dotLottie v2 archive.
+bash scripts/to-dotlottie.sh <scene> [output.lottie]
+
+# Run the official runtime adapters in a real browser harness.
+node scripts/runtime-adapters.mjs
+
+# Build the task-bound Intelligence Core artifacts.
+python3 scripts/intelligence.py motion-ir build --task-dir artifacts/<task-id>
+python3 scripts/intelligence.py graph build --task-dir artifacts/<task-id>
+python3 scripts/intelligence.py provenance build --task-dir artifacts/<task-id>
+python3 scripts/intelligence.py replay capture --task-dir artifacts/<task-id>
+
+# Derive, sign and independently verify the exact task-bound attestation.
+python3 scripts/attestation.py statement --scene-dir src/output/<scene> \
+  --task-dir artifacts/<task-id> --context <project-context.json> \
+  --output artifacts/<task-id>/attestation-statement.json
+python3 scripts/attestation.py build --statement artifacts/<task-id>/attestation-statement.json \
+  --private-key <managed-key-file> --key-id <key-id> \
+  --output artifacts/<task-id>/attestation.json
+python3 scripts/attestation-verifier.py --attestation artifacts/<task-id>/attestation.json \
+  --trust-policy artifacts/<task-id>/trust-policy.json \
+  --expected-task-id <task-id> --expected-scene <scene>
+```
+
+`runtime-evidence.json` records the runtime package, three scrub points, observed state and generated snapshots. A template alone is never enough to upgrade a framework from `scaffold_only` to `verified`.
+
+For an observability-enabled run, `bash scripts/capture-runtime-telemetry.sh <scene> artifacts/<task-id>` regenerates the real-browser evidence and writes telemetry under the task bundle. `scripts/evidence-verifier.py` then checks task/scene/hash/path/age bindings with stable machine-readable output. A verifier pass means the evidence is internally consistent; it does not mean the animation is approved.
+
+## Output contract
+
+Create `artifacts/<task-id>/` for cross-Agent handoff. A minimal invocation is:
+
+```bash
+python3 scripts/report.py init --task-id <task-id> --scene <scene> \
+  --intent "<intent>" --output artifacts/<task-id>
+python3 scripts/report.py add --task-dir artifacts/<task-id> \
+  --section completed --id context --summary "Project analyzed" \
+  --status pass --evidence project-context.json
+python3 scripts/report.py structure --task-dir artifacts/<task-id> \
+  --missing-file <path> --broken-reference <path>
+python3 scripts/report.py collect --task-dir artifacts/<task-id>
+python3 scripts/review-hook.py prepare --task-dir artifacts/<task-id> --lab-url http://127.0.0.1:3300
+# Browser Agent opens the emitted URL; user reviews; then persist the browser payload:
+python3 scripts/report.py review --task-dir artifacts/<task-id> \
+  --candidate-id <candidate-id> --decision approved --reviewer user
+python3 scripts/report.py check --task-dir artifacts/<task-id>
+python3 scripts/report.py render --task-dir artifacts/<task-id>
+```
+
+The bundle should contain `task.json`, `execution-report.json`, `decision-log.jsonl`, `artifact-manifest.json`, `quality-report.json`, `issue-register.json`, `review.json` and `handoff.json` as applicable. Telemetry-enabled bundles additionally expose `runtime-adapters/runtime-evidence.json`, `runtime-adapters/runtime-telemetry.json` and `evidence-verifier-report.json`; strict trust bundles also expose `attestation.json`, `trust-policy.json` and `attestation-verifier-report.json`. Reports must never convert “not run” into “passed”: an absent runtime or attestation artifact is a `not_completed` item or a blocker, while an invalid path belongs in `structure_review`. A valid signature remains distinct from user approval.

package/agent-card.json

@@ -0,0 +1,161 @@
+{
+  "card_version": "1.0",
+  "name": "motionloom",
+  "version": "2.0.0",
+  "description": "Project-aware animation production with graph, provenance, framework-neutral motion IR, runtime verification and telemetry, DSSE-compatible signed attestation, external evidence verification, semantic feedback, continuity checks, internal browser review, trust-boundary hardening and deterministic Agent handoff.",
+  "capabilities": [
+    "project.analyze",
+    "project.graph.build",
+    "project.graph.validate",
+    "motion.plan",
+    "motion.ir.build",
+    "motion.ir.validate",
+    "asset.provenance",
+    "provenance.emit",
+    "provenance.verify",
+    "capability.discover",
+    "capability.select",
+    "replay.capture",
+    "replay.verify",
+    "semantic-lint.build",
+    "semantic-lint.validate",
+    "semantic-lint.benchmark",
+    "trust-boundary.audit",
+    "continuity.build",
+    "continuity.validate",
+    "fix-plan.build",
+    "fix-plan.validate",
+    "feedback.sync",
+    "source-binding.validate",
+    "rig.cutout",
+    "runtime.render.lottie",
+    "runtime.package.dotlottie",
+    "runtime.verify.rive",
+    "runtime.verify.gsap",
+    "runtime.verify.framer-motion",
+    "runtime.telemetry.capture",
+    "runtime.telemetry.validate",
+    "evidence.verify.external",
+    "attestation.statement.build",
+    "attestation.sign.ed25519",
+    "attestation.verify.external",
+    "trust-policy.validate",
+    "devlab.review",
+    "browser.review.prepare",
+    "browser.review.trigger",
+    "browser.review.capture",
+    "quality.gate",
+    "report.generate",
+    "handoff.prepare",
+    "pr.prepare"
+  ],
+  "input_artifacts": [
+    "host-project",
+    "project-manifest",
+    "animation-request",
+    "source-asset"
+  ],
+  "output_artifacts": [
+    "project-context",
+    "motion-spec",
+    "runtime-scene",
+    "source-binding",
+    "dotlottie-package",
+    "runtime-evidence",
+    "runtime-telemetry",
+    "evidence-verifier-report",
+    "signed-attestation",
+    "trust-policy",
+    "attestation-verifier-report",
+    "evidence-bundle",
+    "execution-report",
+    "handoff",
+    "browser-review-candidate",
+    "browser-review",
+    "project-graph",
+    "provenance-attestation",
+    "capability-registry",
+    "motion-ir",
+    "replay-bundle",
+    "semantic-lint-report",
+    "semantic-lint-benchmark",
+    "hardening-audit-report",
+    "continuity-report",
+    "fix-plan",
+    "pr-patch"
+  ],
+  "runtime_capabilities": {
+    "verified": ["lottie-json", "dotlottie-package", "svg-cutout-rig", "rive", "gsap", "framer-motion"],
+    "scaffold_only": ["spine", "threejs"]
+  },
+  "side_effects": {
+    "read_files": "allowed",
+    "write_files": "allowed",
+    "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"
+  },
+  "recommended_integrations": [
+    {
+      "id": "dotlottie-web-skill",
+      "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"]
+    },
+    {
+      "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"]
+    },
+    {
+      "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"]
+    }
+  ],
+  "entrypoints": {
+    "analyze": "bash scripts/analyze.sh <project-path>",
+    "report_init": "python3 scripts/report.py init --task-id <id>",
+    "report_collect": "python3 scripts/report.py collect --task-dir <dir>",
+    "report_render": "python3 scripts/report.py render --task-dir <dir>",
+    "skill_doctor": "python3 scripts/skill-doctor.py --json",
+    "quality_gate": "python3 scripts/quality-gate.py --scene <scene> --context <path>",
+    "manifest_bind_source": "python3 scripts/manifest.py bind-source --scene <scene> --source <file> --kind <kind> --authority <authority> --license <license>",
+    "dotlottie_package": "bash scripts/to-dotlottie.sh <scene> [output.lottie]",
+    "runtime_adapter_test": "node scripts/runtime-adapters.mjs",
+    "runtime_telemetry": "bash scripts/capture-runtime-telemetry.sh <scene> artifacts/<task-id>",
+    "evidence_verify": "python3 scripts/evidence-verifier.py --scene-dir src/output/<scene> --task-dir artifacts/<task-id> --runtime-evidence runtime-adapters/runtime-evidence.json --max-age-days 1 --output artifacts/<task-id>/evidence-verifier-report.json",
+    "intelligence_graph": "python3 scripts/intelligence.py graph build --task-dir artifacts/<task-id>",
+    "intelligence_provenance": "python3 scripts/intelligence.py provenance build --task-dir artifacts/<task-id>",
+    "intelligence_capabilities": "python3 scripts/intelligence.py capabilities build --output capability-registry.json",
+    "intelligence_motion_ir": "python3 scripts/intelligence.py motion-ir build --task-dir artifacts/<task-id>",
+    "intelligence_replay": "python3 scripts/intelligence.py replay capture --task-dir artifacts/<task-id>",
+    "semantic_lint": "python3 scripts/intelligence.py semantic-lint build --task-dir artifacts/<task-id>",
+    "semantic_lint_benchmark": "python3 scripts/intelligence.py semantic-lint benchmark --task-dir artifacts/<task-id> --iterations 25 --threshold-ms 500",
+    "continuity": "python3 scripts/intelligence.py continuity build --task-dirs artifacts/<task-id>...",
+    "fix_plan": "python3 scripts/intelligence.py fix-plan build --task-dir artifacts/<task-id> --reports semantic-lint-report.json continuity-report.json",
+    "quality_gate_p1": "python3 scripts/quality-gate.py --scene <scene> --context <path> --task-dir artifacts/<task-id> --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry",
+    "attestation_statement": "python3 scripts/attestation.py statement --scene-dir src/output/<scene> --task-dir artifacts/<task-id> --context <project-context.json> --output artifacts/<task-id>/attestation-statement.json",
+    "attestation_build": "python3 scripts/attestation.py build --statement artifacts/<task-id>/attestation-statement.json --private-key <key> --key-id <key-id> --output artifacts/<task-id>/attestation.json",
+    "attestation_verify": "python3 scripts/attestation-verifier.py --attestation artifacts/<task-id>/attestation.json --trust-policy artifacts/<task-id>/trust-policy.json --expected-task-id <task-id> --expected-scene <scene>",
+    "attestation_report": "python3 scripts/attestation-verifier.py --attestation artifacts/<task-id>/attestation.json --trust-policy artifacts/<task-id>/trust-policy.json --expected-task-id <task-id> --expected-scene <scene> --output artifacts/<task-id>/attestation-verifier-report.json",
+    "quality_gate_attestation": "python3 scripts/quality-gate.py --scene <scene> --context <path> --task-dir artifacts/<task-id> --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation",
+    "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": "bash scripts/pr.sh <scene>"
+  },
+  "report_contract": {
+    "required_sections": ["completed", "verified", "not_completed", "problems", "structure_review", "next_agent", "browser_review"],
+    "artifact_root": "artifacts/<task-id>/"
+  }
+}

package/assets/library/ATTRIBUTION.md

@@ -0,0 +1,6 @@
+# Asset Library Attribution
+
+| Asset | Source | License | Downloaded |
+|---|---|---|---|
+| `success-check.json` | https://lottiefiles.com/free-animation/success-check | LottieFiles Free (check per-asset license page) | v=4.8.0 fr=60 op=240 layers=95 |
+| `error-alert.json` | https://lottiefiles.com/free-animation/error-alert | LottieFiles Free (check per-asset license page) | v=5.5.6 fr=60 op=300 layers=3 |

package/assets/library/README.md

@@ -0,0 +1,20 @@
+# Asset Library — Authoritative Sources
+
+This directory holds the **vetted, traceable source assets** the generator must bind to. The golden rule: when an authoritative source exists here (or in the host project), never invent geometry from memory. Placeholders created by the rig engine or templates are clearly marked and must be replaced before a scene ships.
+
+## Contents
+
+| Item | Purpose |
+|---|---|
+| `success-check.json` | Reference Lottie success state — 60 fps, 240 frames, 95 layers (use as a complexity benchmark) |
+| `error-alert.json` | Reference Lottie error state — 60 fps, 300 frames, minimal layer count |
+| `avatar-base.svg` | Authoritative cutout avatar base for body rigging (`src/rig/cutout_rig.py --input`) |
+| `ATTRIBUTION.md` | Auto-generated provenance table: every fetched asset with source URL + license |
+
+## Adding assets
+
+Use `scripts/fetch-library.sh` — it downloads from official public sources, validates the Bodymovin header (version, fps, frame count, layer count), and appends a row to `ATTRIBUTION.md`. Always open the license page of each asset before shipping it in a commercial product; LottieFiles free assets carry individual license terms.
+
+## Naming convention
+
+`<category>-<variant>.<ext>` — e.g. `loading-dots.json`, `character-walk.svg`. Category must match a taxonomy entry in `docs/CATEGORIES.md`.

package/assets/library/avatar-base.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 500 450">
+  <!-- Authoritative cutout avatar base. Part names map 1:1 to bones in
+       src/rig/cutout_rig.py (head, chest, arms, legs, feet). Replace with
+       owned/licensed character art before shipping. -->
+  <g id="parts">
+    <circle data-part="head" cx="250" cy="90" r="42" fill="#2d2d3a"/>
+    <rect data-part="chest" x="208" y="140" width="84" height="96" rx="22" fill="#2d2d3a"/>
+    <rect data-part="l_upper_arm" x="178" y="148" width="26" height="78" rx="13" fill="#45455a"/>
+    <rect data-part="r_upper_arm" x="296" y="148" width="26" height="78" rx="13" fill="#45455a"/>
+    <rect data-part="l_forearm" x="176" y="228" width="22" height="70" rx="11" fill="#45455a"/>
+    <rect data-part="r_forearm" x="302" y="228" width="22" height="70" rx="11" fill="#45455a"/>
+    <rect data-part="l_thigh" x="216" y="238" width="30" height="84" rx="15" fill="#37374a"/>
+    <rect data-part="r_thigh" x="254" y="238" width="30" height="84" rx="15" fill="#37374a"/>
+    <rect data-part="l_shin" x="218" y="324" width="26" height="80" rx="13" fill="#37374a"/>
+    <rect data-part="r_shin" x="256" y="324" width="26" height="80" rx="13" fill="#37374a"/>
+    <ellipse data-part="l_foot" cx="231" cy="408" rx="24" ry="10" fill="#1f1f2e"/>
+    <ellipse data-part="r_foot" cx="269" cy="408" rx="24" ry="10" fill="#1f1f2e"/>
+  </g>
+</svg>