motionloom 2.0.0

package/bin/motionloom.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * MotionLoom npm entrypoint.
+ * Style: Timeline Desk — terse command routing, explicit evidence verbs and
+ * no hidden approval side effects. The CLI delegates to the shipped Python
+ * contracts so npm installation and repository execution use one surface.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const PYTHON = process.env.MOTIONLOOM_PYTHON || (process.platform === "win32" ? "python" : "python3");
+
+const PYTHON_COMMANDS = {
+  analyze: "scripts/analyze.sh",
+  attestation: "scripts/attestation.py",
+  "verify-attestation": "scripts/attestation-verifier.py",
+  doctor: "scripts/skill-doctor.py",
+  intelligence: "scripts/intelligence.py",
+  "eval-intelligence": "scripts/eval-intelligence.py",
+  "evidence-verify": "scripts/evidence-verifier.py",
+  "quality-gate": "scripts/quality-gate.py",
+  "report-contract": "scripts/report-contract.py",
+  report: "scripts/report.py",
+  "review-hook": "scripts/review-hook.py",
+  "validate-lottie": "scripts/validate-lottie.py",
+  manifest: "scripts/manifest.py",
+};
+
+function printHelp() {
+  console.log(`MotionLoom 2.0.0 — project-aware animation production and evidence contracts
+
+Usage:
+  motionloom <command> [args...]
+
+Commands:
+  doctor                 Validate the installed Skill package
+  analyze                Run project analysis (delegates to scripts/analyze.sh)
+  intelligence           Build or validate Intelligence Core artifacts
+  attestation            Build/validate canonical signed-attestation artifacts
+  verify-attestation     Verify an attestation against a trust policy
+  evidence-verify        Verify runtime evidence externally
+  quality-gate           Run the strict scene acceptance gate
+  report-contract        Validate task bundle completeness
+  review-hook            Prepare or validate browser review handoff
+  report                 Read or update task review reports
+  validate-lottie        Validate a Lottie animation
+  manifest               Build or validate a production manifest
+  eval-intelligence      Run adversarial Intelligence Core evaluation
+
+The CLI never grants approval or opens a pull request by itself. User review
+and explicit repository side-effect confirmation remain separate gates.
+`);
+}
+
+const [command, ...args] = process.argv.slice(2);
+if (!command || command === "help" || command === "--help" || command === "-h") {
+  printHelp();
+  process.exit(0);
+}
+
+const script = PYTHON_COMMANDS[command];
+if (!script) {
+  console.error(`Unknown MotionLoom command: ${command}`);
+  printHelp();
+  process.exit(2);
+}
+
+const executable = script.endsWith(".sh") ? "bash" : PYTHON;
+const result = spawnSync(executable, [resolve(ROOT, script), ...args], {
+  cwd: ROOT,
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(`MotionLoom could not start ${executable}: ${result.error.message}`);
+  process.exit(2);
+}
+process.exit(result.status ?? 1);

package/docs/BROWSER-REVIEW-E2E.md

@@ -0,0 +1,78 @@
+# MotionLoom Browser Review — End-to-End Runbook
+
+This runbook defines the controlled path from a rendered scene to a user-approved, local-only confirm-to-PR commit. The Dev Lab is a mandatory post-render handoff, not a separate skill or autonomous approval agent.
+
+## Contract
+
+> A scene is not ready for PR until the exact browser-review candidate has been opened, the reviewer has inspected the runtime checkpoints, every checklist item has been explicitly selected, `review.json` has been persisted, and the context-bound quality gate has passed.
+
+The candidate is bound to the task ID, scene ID, source checksum, project-context checksum, reviewer identity and expiry timestamp. The quality gate rejects stale or foreign evidence. `OPEN_PR=0` is the safe default: confirm-to-PR creates a local commit only and never pushes or opens a pull request implicitly.
+
+## Operational sequence
+
+From the repository root, prepare the task lifecycle with the official report CLI, render the scene, and stage the candidate through `review-hook.py prepare`. The resulting URL must include the candidate ID, artifact base and task base; do not replace it with a hand-written URL.
+
+Open the candidate URL in the internal browser Dev Lab. Inspect the runtime at frames **0, 50 and 100**. Then select every checklist input explicitly. A checklist row being visible is not approval; the Dev Lab intentionally starts every input unchecked. Click **Confirm review** only after the user has approved the inspected candidate.
+
+Persist the browser decision and run the gates in this order:
+
+```bash
+TASK_DIR=artifacts/<task-id>
+SCENE=<scene-id>
+CONTEXT=artifacts/<task-id>/project-context.json
+
+python3 scripts/report.py review \
+  --task-dir "$TASK_DIR" \
+  --decision approved \
+  --reviewer user \
+  --candidate-id <candidate-id> \
+  --notes "Approved after inspecting frames 0, 50 and 100." \
+  --feedback "All checklist checks passed."
+
+python3 scripts/review-hook.py validate \
+  --task-dir "$TASK_DIR" \
+  --require-approved
+
+python3 scripts/quality-gate.py \
+  --scene "$SCENE" \
+  --context "$CONTEXT" \
+  --task-dir "$TASK_DIR" \
+  --require-browser-review
+
+python3 scripts/report.py transition --task-dir "$TASK_DIR" --state validated
+python3 scripts/report.py transition --task-dir "$TASK_DIR" --state ready_for_pr
+python3 scripts/report.py check --task-dir "$TASK_DIR"
+
+CONTEXT_PATH="$CONTEXT" TASK_DIR="$TASK_DIR" OPEN_PR=0 \
+  bash scripts/pr.sh "$SCENE" "feat(animation): approved scene in Dev Lab"
+```
+
+After `pr.sh` returns the local commit SHA, record the final task state explicitly:
+
+```bash
+python3 scripts/report.py transition \
+  --task-dir "$TASK_DIR" \
+  --state confirmed \
+  --commit-sha <local-commit-sha>
+```
+
+Do not set `OPEN_PR=1` unless the user separately requests a real push and pull request. A local-only confirmation is the default evidence boundary for this workflow.
+
+## Evidence expected in the task bundle
+
+| Artifact | Purpose |
+| --- | --- |
+| `task.json` | Lifecycle state, scene, project and context identity. |
+| `browser-review.json` | Candidate identity, expiry, source/context hashes and approval status. |
+| `review.json` | User decision, reviewer, timestamp, notes and candidate binding. |
+| `quality-report.json` | Quality gate status and acceptance checks. |
+| `execution-report.json` | Completed, verified, unresolved and next-agent evidence. |
+| `REPORT.md` | Human-readable report generated from the task ledger. |
+| `browser-observation.md` | Durable record of inspected runtime checkpoints and browser safety events. |
+| `artifact-manifest.json` | SHA-256 inventory for task artifacts. |
+
+## Verified reference run
+
+The professional execution fixture is `artifacts/professional-review-e2e/`. It used scene `browser-review-smoke`, candidate `88a2f2f18ba45a07f56e`, and local commit `74a9ea6` on branch `fix/browser-review-smoke`. The candidate was inspected at frames 0, 50 and 100. The first confirm attempt was rejected because the checklist inputs were not selected; after all four checks were explicitly selected and the user confirmed, the browser review was approved.
+
+The acceptance side of this run is covered by `test_approved_browser_review_e2e_contract` in `tests/scripts/run_tests.py`. That test copies the task into a clean temporary root and re-runs candidate validation, the context-bound quality gate and the confirmed-task report contract.

package/docs/CATEGORIES.md

@@ -0,0 +1,16 @@
+# Animation Category Taxonomy
+
+Every request must be classified into exactly one category before generation. The category determines the framework shortlist, the default duration/FPS/loop contract, and the rigging approach.
+
+| Category | Key signals | Contract |
+|---|---|---|
+| ui-micro | button, toggle, toast, hover, focus, feedback | 0.2–0.6 s, 60 fps, no loop, ease-in-out |
+| loading | spinner, skeleton, progress, shimmer | 0.8–1.5 s, loop true, dotLottie |
+| hero-scene | marketing, landing, camera push/pan/tilt | 2–8 s, camera motion, optional state machine |
+| character-body | avatar, mascot, idle/walk/emote | cutout rig, 30 fps, loop true, parent-first bone order |
+| icon-animation | glyph reveal, state change, path draw | ≤0.8 s, path-draw or morph, theme slot bound |
+| scroll-linked | parallax, pin, scroll progress | GSAP ScrollTrigger, scrub |
+| data-viz | charts, counters, transitions | tweened values, accessible reduced-motion alternative |
+| 3d-scene | model turntable, shader, WebGL | threejs/R3F, ≤60 fps, memory budget |
+
+When a request spans categories (e.g., a hero with an animated character), decompose it: the character body becomes a `character-body` scene, the surrounding motion a `hero-scene`, and the Dev Lab composes both.

package/docs/CHECKLIST.md

@@ -0,0 +1,31 @@
+# Dev Lab Quality Checklist
+
+A scene is only ready for the confirm-into-PR step when every item below passes. The Dev Lab UI renders this checklist live against the active scene, and CI re-runs it on every PR.
+
+## Motion correctness
+- [ ] The implemented animation matches `motion-spec.json` exactly: duration, easing, loop, interactivity and reduced-motion policy.
+- [ ] Easing uses a canonical name from the easing canon (no invented bezier constants without comment).
+- [ ] Bone rotations follow parent-first order; no child rotates before its parent (body rigs).
+- [ ] No frame pops at loop seam — first and last frames are visually continuous (looping scenes).
+
+## Brand binding
+- [ ] Primary/accent colors come from `project-context.json` (or an explicit user override recorded in the spec).
+- [ ] Theme slots are used for every user-tunable color, never hardcoded hex inside the animation payload.
+
+## Performance
+- [ ] File size within budget (UI ≤300 KB, hero ≤1500 KB for Lottie).
+- [ ] Layer count ≤80.
+- [ ] Runtime snapshot frames at 0/50/100% render in <3 s each on CI; placeholder frames are rejected.
+
+## Accessibility
+- [ ] `prefers-reduced-motion` honored: looping decorations pause; essential motion reduces to a single crossfade.
+- [ ] Lottie players carry `role="img"` plus a descriptive `aria-label`.
+
+## Source traceability
+- [ ] Every geometric asset references an authoritative source (`assets/library/` or the host project) — flagged if invented.
+- [ ] `manifest.json` records framework, source path, license note, spec hash, and completed checklist entries.
+
+## PR readiness
+- [ ] Snapshot PNGs exist for 0/50/100%.
+- [ ] `motion-spec.json` is bound to the exact `project-context.json` hash (implements == planned).
+- [ ] Dev Lab URL tested on mobile viewport and desktop.

package/docs/DEEP-AUDIT-WORKING-NOTES.md

@@ -0,0 +1,22 @@
+# MotionLoom Deep Audit — Working Notes
+
+## Confirmed findings
+
+- The tracked browser-review smoke bundle is discoverable by `report-contract.py`, but its execution report still says `review_required`, retains the initial pending placeholder, and contains duplicate pending browser-review next-agent entries even though the candidate and review artifact are approved.
+- The tracked smoke task points `context_path` at `/tmp/animation-review-context.json`, so a clean checkout cannot reproduce the report bundle without an external transient file.
+- `review-hook.py` verifies a manifest source is inside `src/output`, but does not yet require it to remain inside the selected scene directory; a scene manifest could therefore bind another scene's source.
+- `review-hook.py validate` computes the expected context hash differently from `prepare` when a spec has no context binding, creating an inconsistent fallback path.
+- `pr.sh` validates the scene and review candidate but does not require `TASK_DIR` to be inside the repository or stage the task/report bundle with the scene, so a PR can omit the evidence that the gate just consumed.
+- Runtime evidence has run identity and framework status, but the report is not yet cryptographically bound to a scene/source/manifest identity; a same-framework evidence file could be copied between scenes if the manifest path is changed.
+- The first runtime-evidence quality-gate path referenced `source_sha` before its later assignment; Python's function-local import semantics made this an `UnboundLocalError` for Rive/GSAP/Framer Motion scenes. The branch now computes shared source and manifest hashes before evidence validation and has regression coverage for fresh and stale evidence.
+
+## Audit direction
+
+Prioritize provenance and PR-handoff hardening before adding more runtime features. The Dev Lab artifact-backed mode is implemented and should remain honest: demo catalog fallback is acceptable only when no `artifact_base` is supplied, while browser-review candidates must use the real artifact bundle.
+
+## Remediation status
+
+- [x] Scene confinement, candidate expiry, task/candidate identity and duplicate review handoff entries are hardened.
+- [x] `pr.sh` requires an in-repository task bundle, matching `task.scene`, semantic report validation and evidence staging.
+- [x] Runtime evidence records `run_id`, scene, source checksum and manifest checksum; quality gate rejects stale or mismatched files.
+- [x] A regression test covers both accepted evidence and stale manifest rejection.

package/docs/FRAMEWORK-SELECTION.md

@@ -0,0 +1,26 @@
+# Framework Selection Matrix
+
+The selection rule is deterministic: bind first to the host project's existing stack (from `project-context.json`), then to the category's optimal runtime, then fall back in the order below. The goal is zero new runtime dependencies per delivered scene unless the category demands it.
+
+| Category | Primary | Secondary | Fallback | Notes |
+|---|---|---|---|---|
+| ui-micro | framer-motion | gsap | css | Use when React present; pure CSS for hover-only states |
+| loading | lottie (dotLottie) | framer-motion | css | Embedded assets + theming slots; loop true |
+| hero-scene | lottie (dotLottie) | gsap | threejs | dotLottie state machines for scroll+hover interactivity |
+| character-body | lottie (dotLottie) | spine | — | Spine runtimes free but require a Spine license policy note |
+| icon-animation | lottie | framer-motion | css | Path-draw reveals; ≤200 KB target |
+| scroll-linked | gsap | framer-motion | — | ScrollTrigger; `toggleActions` over manual listeners |
+| data-viz | gsap | framer-motion | threejs | Numbers: GSAP `to()` with `innerText` plugin pattern |
+| 3d-scene | threejs | — | — | React Three Fiber when React present |
+
+## License discipline
+
+Lottie/dotLottie (MIT) and Anime.js (MIT) are safe defaults for any commercial product. GSAP's core is free but large-scale commercial deployments should verify the license tier; never bundle GSAP Club plugins without a license file in the repo. Spine runtimes integrate free of charge, but end users of your software need their own Spine license — record this in the scene manifest under `license_note`. Rive runtimes are free (Apache-2.0) with the Rive editor subject to its own terms.
+
+## Why dotLottie over raw JSON
+
+The dotLottie container is smaller than raw Lottie JSON, can hold multiple animations, embeds images and fonts, and adds state machines and theme slots (color/scalar/vector/gradient/text/image) — the canonical theming spec that keeps animations aligned with brand tokens extracted by the analyzer. Always generate `.lottie`; keep the JSON only as a debug artifact.
+
+## Performance budget
+
+Every scene must ship under these limits or it fails the Dev Lab checklist: Lottie UI assets ≤300 KB (hero ≤1500 KB), ≤80 layers, 60 fps standard (30 fps acceptable for body rigs), and durations ≤2 s for UI / ≤8 s for scenes. The snapshot renderer enforces these at PR time via CI (see `.github/workflows/quality.yml`).

package/docs/PROJECT-MANIFEST.md

@@ -0,0 +1,37 @@
+# Project Manifest
+
+`project-manifest.json` lives in the root of the host project (or is auto-generated by `scripts/analyze.sh`). It is the authoritative voice of the project that the skill must bind to. When the manifest is missing, the analyzer infers values from `package.json`, Tailwind/CSS tokens, and README — and flags the inferred values as *assumptions* that the user should confirm in the Dev Lab.
+
+```jsonc
+{
+  "name": "my-app",
+  "description": "One-line product pitch the animations must reinforce",
+  "brand": {
+    "primary": "#2563eb",       // required — every generated scene binds its theme slots here
+    "accent": "#f59e0b",
+    "palette": ["#2563eb", "#f59e0b", "#0f172a"],
+    "fonts": ["Inter", "Space Grotesk"]
+  },
+  "motion_language": {
+    "easing": "ease-in-out",    // project-wide default easing
+    "ui_duration_ms": 300,      // project-wide UI motion budget
+    "hero_duration_s": 4,
+    "camera": "push-in"
+  },
+  "stack": {
+    "framework": "lottie",      // preferred runtime: lottie | rive | gsap | framer-motion | threejs
+    "react": true
+  },
+  "rules": {                    // hard constraints the agent must never violate
+    "no_flash": true,
+    "reduced_motion_required": true,
+    "max_file_kb": 300
+  },
+  "asset_sources": {            // where authoritative geometry lives
+    "library": "assets/library/",
+    "project_svgs": ["src/assets/icons/"]
+  }
+}
+```
+
+The analyzer writes `project-context.json` inside the host project by merging this manifest with what it reads from the filesystem; the generator then binds each scene's `motion-spec.json` to the exact context hash, so any drift (for example, someone changed the brand color) is caught at PR time.

package/docs/ROADMAP-INTELLIGENCE.md

@@ -0,0 +1,224 @@
+# MotionLoom Intelligence Roadmap
+
+## Kết luận điều hành
+
+MotionLoom hiện đã vượt qua mức “skill chứa prompt và template”. Repo đã có lifecycle, source binding, runtime evidence, browser review, quality gate, report contract và confirm-to-PR an toàn. Tuy nhiên, phần lớn “trí thông minh” hiện vẫn nằm trong **quy tắc kiểm tra và artifact rời**, chưa nằm trong một mô hình chung để Agent suy luận xuyên suốt dự án.
+
+Định hướng đúng tiếp theo không phải là thêm thật nhiều framework animation. MotionLoom nên trở thành một **evidence-driven animation compiler cho Agent**: đọc dự án, chuyển intent thành motion specification có cấu trúc, chọn capability dựa trên evidence, tạo artifact, kiểm chứng runtime, giải thích sai lệch, đề xuất cách sửa và chỉ cho phép handoff khi toàn bộ chuỗi bằng chứng còn hợp lệ.
+
+> **Mục tiêu:** Agent không chỉ tạo được animation; Agent phải chứng minh animation đó đúng với dự án, đúng nguồn, đúng runtime, đúng accessibility policy và đúng quyết định của reviewer.
+
+## 0. Trạng thái triển khai v0.1
+
+Milestone **Intelligence Core v0.1 đã được triển khai ở lớp trust core**. CLI `scripts/intelligence.py` hiện tạo và validate `project-graph.json`, `provenance.json`, `capability-registry.json`, `motion-ir.json` và `replay-bundle.json`. Quality gate có thể chạy strict với `--require-intelligence`; CI luôn validate capability registry và yêu cầu task bundle đầy đủ cho changed scene. Eval runner `scripts/eval-intelligence.py` hiện chạy bảy case deterministic/adversarial trên clean temporary root.
+
+Phạm vi này chứng minh **artifact relationship, provenance, capability freshness/integrity và replay tamper detection**. Nó chưa phải semantic motion lint, chưa phải recommendation engine và chưa phải MCP server. Những phần đó được giữ ở P1/P2 để không biến heuristic thành acceptance truth trước khi có benchmark đủ mạnh.
+
+### 0.2 Trust-boundary hardening — 1.8.0
+
+Milestone **1.8.0 đã hoàn tất và được merge vào `main`**. Deep audit và regression coverage hiện bảo vệ browser-review lifecycle, report bundle selection, task-root/symlink boundaries, capability evidence paths, provenance attestation paths và deterministic replay binding. Dev Lab artifact intake cũng kiểm tra same-origin, task/scene/candidate identity và browser-review expiry trước khi cho phép staging review.
+
+Audit này không tuyên bố hệ thống đã có cryptographic trust anchor bên ngoài repository. Các guard hiện tại là deterministic repository/runtime checks; approval vẫn chỉ đến từ review artifact hợp lệ và user consent.
+
+### 0.3 Evidence interoperability và runtime observability — 1.9.0
+
+Milestone **1.9.0 đã hoàn tất ở lớp internal evidence interoperability**. Runtime adapter thật ghi `runtime-telemetry.json` tại các scrub point với RAF timing, runtime state hashes và binding tới task, scene, source, manifest và Motion IR. `scripts/evidence-verifier.py` cung cấp verifier read-only với stable JSON result, age/path/symlink guards, cross-task identity checks, tamper detection và invariant `approval: false`.
+
+CI và quality gate đã có capture/verify sequence cùng cờ `--require-telemetry`; report collection và handoff quảng bá verifier report, runtime evidence và telemetry. Dev Lab hiển thị telemetry/verifier/benchmark trong evidence rail và khóa confirm khi integrity hoặc identity binding chưa pass. Đây là integrity contract nội bộ, chưa phải signed DSSE/in-toto trust anchor bên ngoài repository.
+
+### 0.4 Signed attestation và trust anchor — 2.0.0
+
+Milestone **2.0.0 đã hoàn tất ở lớp signed evidence interoperability**. `scripts/attestation.py` tạo statement canonical từ scene/task bytes, đóng gói DSSE-compatible envelope và ký Ed25519; `scripts/attestation-verifier.py` là verifier độc lập với stable exit codes, trust-policy lookup, validity/rotation/revocation checks và fail-closed semantics. `approval` luôn là `false`.
+
+Quality gate và report contract có `--require-attestation`; CI tạo fixture key ephemeral cho verification plumbing, còn production trust anchor/key material phải được quản lý ngoài source repository. Eval corpus và regression harness bao phủ clean path, payload tamper, binding mismatch, revoked signer và unknown signer. Đây là chữ ký xác nhận integrity/identity của evidence, không phải user approval hay quyền mở PR.
+
+## 1. Baseline hiện tại và khoảng trống cần giải quyết
+
+| Lớp | Đã có | Khoảng trống chính | Hậu quả nếu chưa xử lý |
+| --- | --- | --- | --- |
+| Skill discovery | `SKILL.md`, `agent-card.json`, capability registry v0.1 | Chưa có refresh service và compatibility matrix theo từng browser/library release | Registry tốt hơn flat flags nhưng cần CI refresh có policy và diff review |
+| Project awareness | `project-context.json`, context hash, task binding, `project-graph.json` | Graph chưa có semantic constraint nodes và multi-scene supersedes đầy đủ | Agent đã có index quan hệ nhưng chưa suy luận continuity sâu |
+| Motion reasoning | `motion-spec.json`, `motion-ir.json`, analyzer/spec pipeline | Semantic lint và compiler intent → adapter plan chưa hoàn chỉnh | Intent phức tạp vẫn cần policy/profile và human review |
+| Provenance | Source binding, artifact manifest, `provenance.json`, DSSE-compatible signed attestation, Ed25519 trust policy, read-only external verifiers | Chưa có managed key distribution/rotation service và remote transparency log | Chữ ký đã tách khỏi hash-only integrity; vận hành trust anchor vẫn cần secret management và policy distribution phù hợp |
+| Runtime | Adapter thật cho Rive, GSAP, Framer Motion; runtime evidence và scrub-point telemetry | Chưa có adapter interface chung và compatibility matrix theo browser/library/version | Telemetry đã so sánh được integrity/runtime state, nhưng compatibility history vẫn cần chuẩn hóa |
+| Quality | Schema validation, quality gate, browser review | Semantic lint và continuity checks còn mỏng | File hợp lệ về cấu trúc nhưng vẫn sai nhịp, sai intent hoặc phá UX |
+| Review loop | Dev Lab, checklist, `review.json`, expiry/replay protection | Feedback chưa được chuyển thành root-cause/fix-plan có thể chạy lại | Agent thường rerender toàn scene thay vì sửa đúng nguyên nhân |
+| Evaluation | Regression scripts, E2E contract và bảy adversarial eval cases | Chưa có benchmark prompt/context đa dạng và aggregate historical metrics | Chưa đủ dữ liệu để khẳng định capability selection trên nhiều dự án |
+| Agent integration | CLI, `SKILL.md`, stable JSON errors và side-effect metadata | Chưa có typed resources/tools qua MCP | Host Agent vẫn cần gọi CLI trực tiếp thay vì discover protocol |
+
+## 2. Kiến trúc đích: Motion Graph + Evidence Chain
+
+### 2.1 Canonical Project Motion Graph
+
+Tạo một representation duy nhất, ví dụ `project-graph.json`, thay vì để Agent suy luận từ những file không liên kết. Graph nên có các node `project`, `intent`, `constraint`, `asset`, `source`, `scene`, `motion_spec`, `runtime`, `artifact`, `evidence`, `review` và `decision`. Các edge quan trọng gồm `derived_from`, `uses`, `constrained_by`, `rendered_by`, `verified_by`, `reviewed_as`, `supersedes` và `blocked_by`.
+
+Graph không thay thế các artifact hiện có. Nó là **index có hash và quan hệ**, giúp Agent trả lời được những câu hỏi có tính quyết định: scene này phục vụ intent nào, dùng asset nào, source authority là gì, runtime evidence được tạo bởi adapter/version nào, review nào đã phê duyệt và artifact nào đã trở nên stale sau khi context đổi.
+
+### 2.2 Provenance chain theo từng bước
+
+`artifact-manifest.json` hiện đã là inventory checksum tốt, nhưng chưa phải provenance attestation hoàn chỉnh. Nên bổ sung `provenance.json` theo hướng tương thích với các khái niệm `subject`, `materials`, `build definition`, `builder` và `resolved dependencies` của SLSA [1], đồng thời mô hình hóa chuỗi step/actor/material/product theo in-toto [2].
+
+Mỗi step phải ghi tối thiểu:
+
+| Trường | Ý nghĩa |
+| --- | --- |
+| `step_id`, `step_type` | Ví dụ `analyze`, `spec`, `source-bind`, `render`, `runtime-test`, `browser-review`, `quality-gate` |
+| `actor` | Agent, user, CI hoặc runtime adapter đã thực hiện step |
+| `builder` | Toolchain, version, browser và môi trường thực thi |
+| `materials[]` | Input path/URI, resolved version và SHA-256 |
+| `products[]` | Output path, type và SHA-256 |
+| `policy` | Rule set/schema/quality policy được áp dụng |
+| `started_at`, `finished_at` | Khoảng thời gian của step |
+| `result` | `pass`, `fail`, `blocked` hoặc `needs_review` |
+| `parent_attestation` | Liên kết step trước để tạo chain, không chỉ danh sách file |
+
+MotionLoom hiện dùng hash chain nội bộ cùng DSSE-compatible envelope và SLSA/in-toto-inspired statement. Private key không nằm trong artifact bundle; trust policy phải công bố key lifecycle, validity, revocation và fail-closed behavior. Chữ ký không được nâng `approval` hoặc thay thế browser review/user consent.
+
+### 2.3 Capability Registry v2
+
+`agent-card.json` nên chuyển từ danh sách capability sang registry có dữ liệu vận hành. Mỗi capability cần có `id`, `kind`, `status`, `adapter_version`, `supported_inputs`, `supported_outputs`, `browser_matrix`, `evidence`, `last_verified_at`, `limitations`, `fallback` và `risk_level`.
+
+Agent chỉ được chọn capability nếu capability đó thỏa ba điều kiện: input/intent tương thích, evidence chưa quá cũ và runtime/browser hiện tại nằm trong compatibility matrix. `scaffold-only` phải là trạng thái không được dùng cho production trừ khi user chủ động chấp thuận một exception được ghi trong report.
+
+### 2.4 Motion IR và semantic lint
+
+Giữa project intent và framework adapter cần có một **Motion Intermediate Representation** độc lập framework. Motion IR nên mô tả target, property, keyframes hoặc spring, duration, delay, easing, loop, interaction trigger, reduced-motion behavior, performance budget, continuity reference và acceptance assertions.
+
+Semantic lint phải kiểm tra ít nhất bốn lớp:
+
+| Lớp lint | Ví dụ rule |
+| --- | --- |
+| Intent | Motion emphasis phải có target và reason; “subtle” không được map thành scale quá lớn |
+| UX/accessibility | Có reduced-motion fallback; keyboard/assistive action không bị khóa bởi animation |
+| Continuity | ID, state, asset anchor và initial pose không đứt giữa các scene liên quan |
+| Runtime/performance | Không animate layout khi transform/opacity đủ dùng; duration và layer count nằm trong budget |
+
+Lint không được giả vờ hiểu thẩm mỹ tuyệt đối. Mỗi rule phải phân loại `deterministic`, `heuristic` hoặc `human_required`, kèm confidence và evidence. Đây là ranh giới để MotionLoom không biến một phán đoán xác suất thành quality truth.
+
+### 2.5 Unified Runtime Adapter API
+
+Chuẩn hóa adapter interface thành các hook: `capabilities()`, `prepare()`, `render()`, `capture()`, `assert()`, `collect_evidence()` và `cleanup()`. Rive, GSAP và Framer Motion là các adapter đầu tiên; các runtime khác chỉ được gắn nhãn verified sau khi thực hiện cùng contract.
+
+Evidence nên chứa `adapter_id`, `adapter_version`, `browser_version`, `os`, `source_sha256`, `manifest_sha256`, `motion_ir_sha256`, `frames`, `assertions`, `status` và `replay_command`. Khi render fail, output cần trả về failure class và bước self-correction thay vì chỉ exit code.
+
+### 2.6 Structured review feedback loop
+
+Dev Lab nên ghi feedback thành `fix-plan.json`, không chỉ `notes` tự do. Một fix plan tối thiểu gồm `issue_id`, `category`, `severity`, `observed_at`, `evidence`, `root_cause_hypotheses`, `recommended_patch`, `affected_nodes`, `rerun_scope`, `expected_delta` và `requires_user_decision`.
+
+Ví dụ, “nhịp vào quá gấp” cần được chuyển thành `timing/easing`, trỏ tới keyframe hoặc transition cụ thể, đề xuất giảm acceleration, rerun scene + runtime evidence, và không yêu cầu rerender asset nếu source hash không đổi. Đây là điểm biến Dev Lab từ viewer thành **debugging instrument**.
+
+## 3. Roadmap theo thứ tự ưu tiên
+
+### P0 — Trust core, 0–2 tuần — **Đã hoàn thành v0.1**
+
+P0 đã làm cho MotionLoom **khó báo PASS sai** bằng bốn schema mới: `project-graph.schema.json`, `provenance.schema.json`, `capability-registry.schema.json` và `motion-ir.schema.json`. Các command deterministic được gom trong `scripts/intelligence.py` để giữ một entrypoint ổn định cho Agent và CI.
+
+Eval corpus v0.1 nằm ở `tests/evals/intelligence-cases.json` và runner `scripts/eval-intelligence.py`, bao phủ verified selection, scaffold-only block, stale/tampered capability evidence, graph corruption, replay tamper và foreign-task candidate. P1 cần mở rộng corpus lên prompt/context đa dạng, multi-scene và semantic intent.
+
+**Definition of done P0:** Đạt trong suite hiện tại: candidate/task binding bị reject khi sai; scaffold-only không được chọn; capability evidence stale/tampered bị reject; graph edge hỏng bị reject; replay artifact bị sửa bị reject; quality gate strict kiểm tra graph/provenance/Motion IR/replay cùng browser evidence.
+
+### P1 — Reasoning core, 2–6 tuần
+
+P1 xây compiler từ project graph + intent → Motion IR → adapter plan. Agent phải xuất ra `decision-log.jsonl` với lý do chọn runtime, nguồn asset, trade-off, confidence và câu hỏi cần user quyết định. Thêm semantic lint và policy profiles theo loại sản phẩm: `ui`, `character`, `marketing`, `game`, `accessibility-first`.
+
+Tại giai đoạn này nên đưa `fix-plan.json` vào Dev Lab. Khi reviewer request changes, Agent nhận issue có thể định vị và chạy lại một phần pipeline. Không cần thêm runtime mới nếu ba adapter hiện tại chưa đạt replay/compatibility matrix ổn định.
+
+**Definition of done P1:** với cùng một context, Agent chọn capability đúng trong benchmark; mọi quyết định heuristic có confidence và evidence; reviewer feedback có thể chuyển thành patch plan; rerun scope không làm stale artifact ngoài phạm vi.
+
+### P2 — Protocol and ecosystem, 6–10 tuần — **Đã hoàn tất lớp 2.0.0; còn visual/benchmark extensions**
+
+Sau khi core contracts ổn định, expose MotionLoom qua typed CLI trước, sau đó thêm MCP adapter nếu cần interoperability. Theo MCP, resources nên đại diện cho context/task/artifact; prompts hoặc workflow resources đại diện cho playbook; tools đại diện cho prepare, render, inspect, validate và confirm với output schema rõ ràng [4]. Tool execution errors phải actionable để Agent tự sửa, nhưng các side effect như remote push/open PR vẫn phải giữ human-in-the-loop [4].
+
+Mỗi tool cần khai báo `side_effect_level`: `read`, `local_write`, `user_review_required`, `remote_write`. `confirm-to-PR` chỉ được gọi khi có approval authority còn hạn, task identity khớp và quality gate đã pass. Không mở quyền remote write chỉ vì Agent đã nhìn thấy một artifact `approved` cũ.
+
+**Definition of done P2:** host Agent có thể discover capability, lấy resource đúng task, gọi tool typed, nhận lỗi có hướng tự sửa, và không thể gọi remote write khi thiếu approval authority.
+
+Signed attestation 2.0.0 đã hoàn tất trước khi mở rộng protocol: statement canonical, Ed25519 signing, trust policy, external verification, CI/gate/report integration và adversarial coverage đều đã có. Khoảng trống kế tiếp là **visual comparison contract** có dataset fixture được gắn provenance và **benchmark history** append-only; cả hai phải giữ review-first, không biến metric thành approval.
+
+### P3 — Scale and learning, sau 10 tuần
+
+P3 thu thập aggregate metrics từ eval và các task thực tế đã được user cho phép. Feedback phải dùng để cải thiện rule, adapter và prompt contract theo phiên bản; không tự động dùng reviewer feedback làm “training truth” nếu chưa được normalize và kiểm duyệt.
+
+Có thể thêm recommendation engine cho runtime/asset, nhưng recommendation phải trả về alternatives, reason, confidence, evidence age và cost/risk. Không nên biến một score nội bộ thành quyết định tự động không thể giải thích.
+
+## 4. Metrics phải đo từ đầu
+
+| Metric | Cách đo | Mục tiêu ban đầu |
+| --- | --- | --- |
+| Acceptance precision | Tỷ lệ artifact được gate PASS và thực sự không có blocker khi reviewer kiểm tra | ≥ 95% trên eval set có nhãn |
+| False approval rate | Tỷ lệ artifact bị quality/review gate cho PASS dù adversarial case phải fail | 0% cho P0 safety rules |
+| Provenance completeness | Tỷ lệ node/step có materials, products, actor, policy và hash hợp lệ | ≥ 98% |
+| Context retention | Tỷ lệ case Agent giữ đúng project constraints và source authority | ≥ 95% |
+| Capability selection accuracy | Tỷ lệ chọn đúng adapter theo intent/input/browser matrix | ≥ 95% |
+| Replay success | Tỷ lệ clean replay đạt cùng hashes hoặc trong tolerance đã khai báo | ≥ 98% |
+| Fix localization | Tỷ lệ review issue dẫn đến rerun đúng subset thay vì rerender toàn bộ | ≥ 80% ở P1 |
+| Handoff completeness | Agent mới chạy được từ `handoff.json` + artifacts mà không đọc chat cũ | 100% trong CI |
+| Reviewer burden | Số thao tác/checklist và thời gian từ candidate đến quyết định | Giảm dần, không đánh đổi safety |
+| Time-to-fix | Thời gian từ `changes_requested` đến evidence pass tiếp theo | Đo baseline trước, tối ưu sau |
+
+Không dùng một “quality score” tổng hợp làm acceptance truth. Deterministic checks, runtime assertions và human review phải tách riêng; score chỉ dùng để ưu tiên điều tra.
+
+## 5. Cấu trúc repo nên hướng tới
+
+```text
+MotionLoom/
+├── SKILL.md                         # Activation contract ngắn, progressive disclosure
+├── agent-card.json                  # Discovery metadata và capability index
+├── schemas/
+│   ├── project-graph.schema.json
+│   ├── provenance.schema.json
+│   ├── capability-registry.schema.json
+│   ├── motion-ir.schema.json
+│   ├── fix-plan.schema.json
+│   └── ...
+├── scripts/
+│   ├── intelligence.py              # graph/provenance/capability/Motion IR/replay
+│   ├── eval-intelligence.py          # deterministic adversarial eval runner
+│   ├── lint-motion.py                # P1 semantic lint placeholder
+│   └── ...
+├── references/
+│   ├── motion-ir.md
+│   ├── capability-policy.md
+│   ├── provenance-policy.md
+│   └── runtime-adapter-contract.md
+├── tests/evals/
+│   ├── intelligence-cases.json
+│   └── ...
+├── artifacts/
+│   └── <task-id>/
+│       ├── project-graph.json
+│       ├── provenance.json
+│       ├── decision-log.jsonl
+│       ├── fix-plan.json
+│       └── ...
+└── dev-lab/
+    └── ...
+```
+
+## 6. Những việc không nên làm ngay
+
+Không nên thêm Spine, Three.js hoặc nhiều AI generation backend trước khi adapter contract, replay và capability registry đã ổn định. Một danh sách framework dài không tạo ra intelligence nếu Agent không biết runtime nào đã được verify trong môi trường hiện tại.
+
+Không nên dùng LLM judge làm quality gate duy nhất. Judge có thể hỗ trợ triage hoặc gợi ý, nhưng acceptance phải dựa trên schema, hash, runtime assertion, policy và human review có bằng chứng.
+
+Không nên ký provenance vội khi field semantics còn thay đổi. Hãy version schema, chạy migration và xác định trust boundary trước; chữ ký trên metadata không chính xác chỉ tạo cảm giác an toàn giả.
+
+Không nên đưa toàn bộ runbook vào `SKILL.md`. Agent Skills khuyến nghị progressive disclosure và giới hạn phần body chính dưới khoảng 500 dòng [5]. MotionLoom nên giữ activation contract ngắn, còn framework rules và long-form references để trong `references/`.
+
+## 7. Việc nên làm ngay ở milestone kế tiếp
+
+Milestone 2.0.0 đã hoàn tất phần **signed evidence integrity** trên nền 1.9.0. Không nên thêm framework theo số lượng. Ưu tiên tiếp theo là asset/frame-level visual comparison có dataset được gắn nhãn nguồn gốc, benchmark history append-only và aggregate metrics theo project/context/framework; trust anchor vận hành cần secret management/rotation thực tế bên ngoài repository.
+
+Trình tự triển khai cụ thể là: version visual-comparison schema và labeled fixtures; thêm pixel/perceptual hash checks với dataset drift guards; ghi append-only benchmark runs và outlier detection; sau đó tích hợp review rail vào Dev Lab. Mỗi milestone phải giữ nguyên nguyên tắc: evidence có hash và identity, failure có stable exit code, heuristic/metric/chữ ký không tự thành approval, và side effect GitHub luôn cần explicit confirmation.
+
+### References
+
+[1]: <https://slsa.dev/spec/v1.0/provenance> — SLSA Provenance v1.0.
+
+[2]: <https://github.com/in-toto/docs/blob/master/in-toto-spec.md> — in-toto Specification 1.0.0.
+
+[3]: <https://agentskills.io/skill-creation/evaluating-skills> — Agent Skills: Evaluating skill output quality.
+
+[4]: <https://modelcontextprotocol.io/specification/2026-07-28/server/tools> — Model Context Protocol: Tools.
+
+[5]: <https://agentskills.io/specification> — Agent Skills Specification.

package/docs/audits/1.10.0-attestation-research-notes.md

@@ -0,0 +1,19 @@
+# Attestation research notes
+
+## Scope
+
+These notes preserve the external standards findings used to design MotionLoom's signed-attestation phase. They are design inputs, not a claim that MotionLoom is already SLSA- or Sigstore-conformant.
+
+## Verified principles
+
+1. SLSA defines a software attestation as an authenticated statement about a software artifact or collection of artifacts. The metadata is explicit; the signature authenticates the attestation producer rather than silently implying a quality decision. Source: <https://slsa.dev/spec/v1.2/attestation-model>.
+2. DSSE signs the pre-authentication encoding of the payload type and serialized body. The payload type must be unambiguous and the verifier must use the exact serialized body that was verified; it must not re-parse the envelope and verify one body while handing another body to the application. Source: <https://github.com/secure-systems-lab/dsse/blob/master/protocol.md>.
+3. DSSE `keyid` is an unauthenticated hint and must not be used as a security decision by itself. The verifier must establish trust using an independently configured key or trust policy. Source: <https://github.com/secure-systems-lab/dsse/blob/master/protocol.md>.
+
+## MotionLoom design consequences
+
+- The signed predicate will carry artifact identity, task/scene identity, provenance chain hash, policy version and evidence hashes, but never an approval authority.
+- Canonical serialization and domain separation will be explicit in the schema and verifier contract.
+- Trust anchors, signer validity, revocation and key rotation will be evaluated separately from payload integrity.
+- The verifier will return integrity/trust results and keep `approval: false`; only the review lifecycle can produce approval.
+- The first implementation will use a local test trust anchor and deterministic fixtures. Production key custody or Sigstore integration will remain an explicit deployment boundary.

package/docs/audits/1.8.0-trust-boundary-hardening.md

@@ -0,0 +1,56 @@
+# MotionLoom Deep Audit: Trust-Boundary Hardening 1.8.0
+
+## Executive summary
+
+The 1.8.0 hardening pass audited the browser-review lifecycle, Dev Lab artifact intake, report-bundle selection, task-root handling, capability evidence paths, provenance attestation paths and deterministic replay binding. The audit found several places where identity and path contracts needed to be made explicit. Those remediations are now implemented as deterministic guards and adversarial regression tests. The result is stronger protection against cross-task evidence mixing, symlink/path escape, stale or replayed browser candidates and ambiguous report selection. The changes do **not** create a cryptographic trust anchor and do not turn heuristic lint or benchmark results into approval.
+
+## Scope and evidence
+
+| Area | Canonical implementation | Evidence used |
+| --- | --- | --- |
+| Browser review | `scripts/review-hook.py`, `scripts/report.py` | Candidate task/scene identity, reviewer identity, expiry and single-use state checks |
+| Dev Lab intake | `animation-dev-lab/client/src/lib/artifact.ts`, `client/src/pages/Lab.tsx` | Same-origin bases, task/scene/candidate binding, expiry visibility and confirm blocking |
+| Report selection | `scripts/report-contract.py` | Complete passing bundle selection by state, update time and task ID; ambiguous tie rejection |
+| Task-root integrity | `scripts/intelligence.py` | Graph, provenance, capability and replay path/symlink guards |
+| Replay | `scripts/intelligence.py replay` | `task_dir`, `task_id`, scene and recorded file containment checks |
+| Regression | `tests/scripts/run_tests.py` | Foreign candidate, duplicate scene, cross-task replay, symlink artifact and external capability evidence cases |
+
+## Key findings and remediation
+
+| ID | Severity before remediation | Finding | Remediation status |
+| --- | --- | --- | --- |
+| AUD-001 | High | A review artifact must not be reusable after expiry or after approval, and `review.json` must name the exact candidate/task. | Fixed in `report.py` and `review-hook.py`; regression covers expired and foreign candidates. |
+| AUD-002 | High | Multiple passing task bundles for one scene could make evidence selection implicit or filename-dependent. | Fixed in `report-contract.py`; selection is ranked deterministically and equal state/time ties fail. |
+| AUD-003 | High | Symlinked files or resolved paths outside a task bundle could enter graph, provenance or replay inventories. | Fixed in `intelligence.py`; graph/provenance/capability/replay reject symlink traversal and root escapes. |
+| AUD-004 | High | A replay bundle could name a different task directory or record files from another task. | Fixed in replay capture/verify and task Intelligence validation; task directory, task ID, scene and every file are bound. |
+| AUD-005 | Medium | Dev Lab query parameters could point artifact/task intake at a foreign origin or mismatched task/candidate identity. | Fixed in `artifact.ts` and `Lab.tsx`; same-origin and identity checks are surfaced and confirm staging is disabled on failure. |
+| AUD-006 | Medium | Capability evidence supplied from outside the repository weakened the meaning of the registry path reference. | Fixed in `intelligence.py`; capability build and validation require repository-contained, non-symlink evidence. |
+
+## Remediation contract
+
+The following rules are now part of the acceptance boundary:
+
+1. **Identity is explicit.** Candidate, review, task, scene, replay and report selection must agree on stable identifiers; filename order is not an identity mechanism.
+2. **Roots are enforceable.** A resolved path is accepted only when its raw path contains no symlink component and its resolved file remains inside the declared root.
+3. **Review is time-bounded and single-use.** Expired, already-approved or foreign browser candidates cannot be recorded as a new approval.
+4. **Evidence and approval remain separate.** Graphs, provenance, benchmarks, semantic warnings and Dev Lab binding status can block or request review, but none can manufacture user consent.
+5. **Side effects remain explicit.** The Dev Lab only stages a local review decision; `OPEN_PR=0` remains the default and GitHub writes require an explicit action.
+
+## Verification matrix
+
+The following checks passed during the milestone:
+
+| Check | Result |
+| --- | --- |
+| `python3 -m py_compile scripts/report.py scripts/intelligence.py scripts/review-hook.py scripts/report-contract.py tests/scripts/run_tests.py` | Pass |
+| `python3 tests/scripts/run_tests.py` | Pass, including new hardening adversarial cases |
+| Dev Lab `pnpm run build` | Pass; existing CSS parser and bundle-size warnings are non-blocking |
+| Existing P0/P1 Intelligence eval and strict quality contracts | Preserved by the regression suite; full acceptance is required before release commit |
+
+## Residual risk
+
+The Dev Lab is a client-side reviewer. Same-origin and identity checks prevent accidental or query-driven evidence mixing, but a browser user can still modify local client state with developer tools. The authoritative boundary therefore remains the repository-side review hook, report contract and quality gate. Provenance is hash-chain verified inside the repository but is not yet signed with DSSE/in-toto or verified by an external trust anchor. Visual/perceptual lint remains a proxy and must not be described as human visual approval.
+
+## Next audit target
+
+The next roadmap milestone should add external attestation verification, runtime frame telemetry and a labeled visual-comparison benchmark. Each should begin with a threat model and schema contract before any capability is promoted in `agent-card.json`.