motionloom 2.0.0

package/docs/audits/1.9.0-evidence-interoperability-threat-model.md

@@ -0,0 +1,37 @@
+# Evidence Interoperability and Runtime Observability — Threat Model
+
+## Scope
+
+This phase adds a narrow, evidence-first slice to MotionLoom: runtime frame telemetry emitted by the existing browser harness and an independent verifier that can validate the evidence bundle without granting approval. The telemetry is an observation of a runtime execution, not a visual-quality score. The verifier is a read-only trust check, not a reviewer and not a PR action.
+
+## Trust zones
+
+| Zone | Examples | Trust assumption |
+| --- | --- | --- |
+| Project source | `src/output/<scene>/`, source asset, `manifest.json`, `motion-spec.json` | Untrusted until hashes, source binding and schema contracts agree. |
+| Task evidence | `artifacts/<task-id>/`, browser review, provenance, replay and handoff artifacts | Untrusted input; identity, expiry, path and hash binding must be rechecked. |
+| Runtime observation | Browser harness, runtime evidence and telemetry samples | Measurements are observations from one run; they do not prove human approval or universal performance. |
+| External verifier | `scripts/evidence-verifier.py` and its JSON report | Must be deterministic, read-only, fail closed and independent from builder-side approval state. |
+| Remote side effects | Git push, PR creation, merge and confirm-to-PR | Out of scope for the verifier; remain behind explicit user approval and existing review gates. |
+
+## Threats and controls
+
+| Threat | Risk | Required control |
+| --- | --- | --- |
+| Telemetry copied from another scene or task | A valid-looking runtime observation is attached to the wrong artifact | Bind task ID, scene, source hash, manifest hash and Motion IR hash; recompute all local hashes. |
+| Symlink or `..` path escapes | Verifier reads attacker-controlled files outside the declared evidence root | Reject symlink components and require resolved paths to remain under the declared root. |
+| Stale or replayed telemetry | Old evidence is presented as current after source or manifest changes | Verify generated time format, source/manifest/Motion IR hashes and optional freshness policy. |
+| Tampered measurements | Frame metrics are edited after capture | Verify the telemetry file digest when a manifest/inventory binding exists; validate numeric bounds and sample shape. |
+| Telemetry interpreted as approval | A performance observation silently bypasses review | Verifier reports `pass` or `fail` only for evidence integrity and sets `approval=false`; it never emits an approval decision. |
+| Browser/runtime mismatch | Evidence from an incompatible adapter is treated as current | Require framework/runtime identity and preserve browser/OS/toolchain metadata in the report. |
+| Verifier itself becomes a hidden gate bypass | Builder imports mutable project state or accepts missing evidence | Keep the verifier CLI read-only, use stable exit codes, require explicit paths and fail on missing required fields. |
+
+## Contract decisions
+
+The first telemetry contract records scrub-point observations and frame-loop timing metadata that the current Playwright harness can measure. It does not claim to provide production fleet FPS, visual similarity, dropped-frame truth across all browsers or a perceptual quality score. Thresholds are policy inputs and must be declared by the caller; the verifier validates integrity and policy evaluation but does not invent approval.
+
+The verifier consumes a scene directory and an optional task directory. It may produce a JSON report outside the evidence root, but it must never mutate the input bundle. A successful verification means that the declared evidence is internally consistent under the requested policy. It does not mean that a user approved the animation, that a PR may be opened, or that a remote write is authorized.
+
+## Definition of done for this phase
+
+The phase is complete when the telemetry and verifier schemas are machine-checkable, the runtime harness emits telemetry for all verified adapters, the verifier rejects cross-task, stale, tampered and path-escaped evidence, regression/eval/CI invoke it with stable exit codes, and Dev Lab can display the observation without presenting it as approval.

package/docs/audits/2.0.0-attestation-acceptance.md

@@ -0,0 +1,30 @@
+# MotionLoom 2.0.0 Attestation Acceptance Audit
+
+## Scope
+
+This audit covers the signed-attestation and trust-policy implementation added after the 1.9.0 runtime telemetry milestone. The target is a task-bound, externally verifiable integrity contract that cannot convert cryptographic success into user approval.
+
+## Contract decisions
+
+The statement is canonical JSON and includes the task ID, scene, project-context hash, source hash, manifest hash, Motion IR hash, runtime evidence hashes, telemetry bundle hash, verifier report hash, provenance hash, policy version and builder identity. The envelope follows the DSSE payload separation model and signs the canonical payload with Ed25519. The trust policy declares key ID, algorithm, public key, validity, status, rotation limits and fail-closed revocation behavior.
+
+The independent verifier checks envelope shape, payload SHA-256, canonical UTF-8 JSON, statement bindings, signature validity, key lookup, key lifecycle and expected task/scene identity. Its output is machine-readable and always sets `approval` to `false`. The report contract and quality gate only accept the attestation when the verifier returns success and its bindings match the selected task bundle.
+
+## Adversarial coverage
+
+| Case | Expected behavior | Result |
+| --- | --- | --- |
+| Clean active signer | Verify with exit `0`; preserve `approval: false` | Pass |
+| Payload tamper | Reject with exit `11` | Pass |
+| Expected binding mismatch | Reject with exit `14` | Pass |
+| Revoked signer | Reject with exit `13` | Pass |
+| Unknown signer | Reject with exit `13` | Pass |
+| Symlink/path escape | Reject before evidence is trusted | Pass through existing trust-boundary regression suite |
+
+## Acceptance evidence
+
+The focused attestation contract test, the full regression harness, the 25-case Intelligence eval suite, strict report contract and strict quality gate all pass in the working tree. CI installs the pinned cryptography range from `requirements.txt` before running any attestation command.
+
+## Residual risks
+
+The repository does not operate a remote key registry, secret manager, transparency log or automatic key rotation service. CI uses an ephemeral job-local key only to prove pipeline wiring; production operators must inject and govern real key material and publish the corresponding trust policy through an approved deployment channel. Visual comparison and benchmark history remain future roadmap work, and neither metric nor attestation can waive human review.

package/docs/releases/1.5.0.md

@@ -0,0 +1,25 @@
+# MotionLoom 1.5.0 — Intelligence Core v0.1
+
+## Summary
+
+MotionLoom 1.5.0 introduces the first deterministic intelligence layer for project-aware animation work. The release does not add another rendering framework. It makes the existing pipeline more explainable and harder to accept stale, foreign or tampered evidence.
+
+## Added
+
+The release adds versioned JSON Schemas for project graph, step-level provenance, capability registry and framework-neutral Motion IR. The stdlib-only `scripts/intelligence.py` CLI builds and validates those contracts and captures/verifies a task-bound replay bundle.
+
+Capability selection now checks status, evidence freshness, evidence file hashes, compatibility metadata and side-effect policy. A scaffold-only adapter cannot pass production selection. Strict quality gates can require the Intelligence Core artifacts with `--require-intelligence`.
+
+The release also adds `scripts/eval-intelligence.py` and a seven-case adversarial corpus. CI runs this corpus alongside the existing regression suite, Skill Doctor and quality gate. Reporting and handoff documentation now treats graph, provenance, Motion IR and replay as first-class artifacts.
+
+## Safety correction
+
+Replay capture excludes generated report and manifest files because lifecycle collection legitimately rewrites them. Runtime/source/spec/review and Intelligence Core artifacts remain hash-bound. This prevents a false stale-replay failure while preserving tamper detection for substantive evidence.
+
+## Not included
+
+Semantic motion lint, fix-plan generation, recommendation learning and MCP transport remain future work. They require broader benchmark data and must not be implemented by converting heuristic confidence into an acceptance decision.
+
+## Verification
+
+The release was verified with JSON contract parsing, Python compilation, shell syntax checks, Skill Doctor, the full regression suite, the seven-case adversarial eval, strict quality gates for both tracked smoke and professional browser-review task bundles, and `git diff --check`.

package/docs/releases/1.6.0.md

@@ -0,0 +1,27 @@
+# MotionLoom 1.6.0 — P1 Feedback Intelligence
+
+## Summary
+
+MotionLoom 1.6.0 adds a semantic feedback layer above deterministic runtime and provenance checks. It does not claim to judge aesthetics autonomously. Instead, it identifies explainable risks, binds them to evidence, and gives the next Agent a selective repair plan.
+
+## Added
+
+The release adds versioned schemas and canonical CLI commands for `semantic-lint-report.json`, `continuity-report.json` and `fix-plan.json`. Semantic lint evaluates the available Motion IR for intent specificity, timing/easing semantics, accessibility policy, performance constraints and known anti-patterns. Findings carry severity, confidence, evidence references and a human-review requirement.
+
+Continuity analysis accepts an ordered set of task bundles and checks shared project context, scene identity, Motion IR compatibility and transition assumptions. It reports context drift without treating a single-scene pass as evidence that an entire sequence is coherent.
+
+The fix-plan command converts lint and continuity findings into root cause, affected artifacts, patch scope, selective rerun scope and verification commands. The plan is synchronized into the existing issue register, execution report and handoff; it does not introduce a parallel lifecycle or bypass reviewer consent.
+
+The quality gate and report contract can now require P1 artifacts. The bundled Dev Lab stages and displays semantic status, continuity status, fix-plan status and the first actionable findings in the evidence rail before confirm. GitHub Actions runs the P1 regression contracts and preserves the existing strict v0.1 gates.
+
+## Verified behavior
+
+The fixture suite covers a human-review warning for generic intent, a matching multi-scene continuity pass, context drift detection, fix-plan source binding and selective lint rerun scope. Smoke and professional task bundles pass schema parsing, regression, eval, Skill Doctor, report contract and strict quality gates.
+
+## Trust boundary
+
+Semantic confidence and severity are prioritization signals. They cannot replace source binding, runtime assertions, replay verification, browser review or user approval. A `warn` result must remain visible, become a structured fix plan and be resolved or explicitly reviewed; it must never be rewritten as `pass` by the Agent.
+
+## Remaining scope
+
+P2 remains for richer continuity semantics, asset-level visual comparison, performance budget telemetry and recommendation learning. Those features require a broader benchmark corpus and will be added only with false-positive/false-negative evaluation rather than heuristic scoring alone.

package/docs/releases/1.7.0.md

@@ -0,0 +1,23 @@
+## Summary
+
+MotionLoom 1.7.0 extends the P1 feedback layer with deterministic performance and perceptual-risk contracts. The release makes lint execution measurable, exposes UI animation budget and frame-rate risks, and keeps easing and reduced-motion guidance visible without turning heuristics into approval.
+
+## Added
+
+The semantic linter now emits a non-blocking `perf-animation-budget` warning when a UI-context Motion IR exceeds the default 500 ms interaction budget, a `perf-frame-rate` warning below 30 FPS, and an informational `perf-track-count` finding above ten tracks. It also emits perceptual warnings for linear easing in UI context and an explicit `none` reduced-motion policy. Structural source/spec mismatches remain deterministic errors; heuristic findings remain warnings or information.
+
+The new `semantic-lint benchmark` command writes `semantic-lint-benchmark.json`. It measures in-process semantic-lint execution across configurable iterations, records average and p95 milliseconds, declares the evaluated rule set, and passes only when p95 is below the declared threshold. The default contract is 25 iterations and 500 ms. This is an execution-performance signal, not a human visual score or approval token.
+
+The strict quality gate accepts `--require-benchmark`, and CI generates and validates the benchmark artifact before running the P1 gate. The Agent Card, README, installable Skill instructions, Intelligence Core reference and package scripts now expose the same command surface. The eval corpus and regression harness cover duration, FPS, linear easing, reduced-motion risk and benchmark threshold behavior.
+
+## Verified behavior
+
+The professional task fixture passes Python compilation, the regression harness, the adversarial Intelligence eval corpus and Skill Doctor checks. The benchmark reports a p95 execution time below 500 ms on the canonical fixture. The multi-scene continuity fixtures continue to pass for matching context and report a warning for intentional context drift.
+
+## Trust boundary
+
+Performance and perceptual findings are explainable risk signals. They may create a fix-plan entry and a selective rerun request, but they do not replace runtime evidence, source binding, browser review or user consent. A benchmark pass proves only that the semantic lint operation stayed below its declared execution threshold.
+
+## Remaining scope
+
+Runtime frame telemetry, asset-level visual comparison, richer transition semantics and recommendation learning remain future work. They require runtime evidence and a broader labeled benchmark corpus rather than a single heuristic score.

package/docs/releases/1.8.0.md

@@ -0,0 +1,23 @@
+## Summary
+
+MotionLoom 1.8.0 hardens the evidence and approval trust boundary after the 1.7.0 semantic benchmark milestone. The release makes candidate identity, task roots, replay scope and report selection explicit across the CLI, quality contracts and Dev Lab handoff.
+
+## Added
+
+Browser-review lifecycle checks now reject expired or replayed candidates and require the exact task, scene, candidate and reviewer relationship. Report completeness now selects one deterministic passing task bundle per changed scene and fails when equally ranked bundles are ambiguous.
+
+Intelligence Core path handling now rejects symlink traversal and resolved files outside declared task/repository roots for graph, provenance, capability evidence and replay. Replay verification binds `task_dir`, `task_id`, scene and every recorded file to the selected task bundle, preventing cross-task replay reuse.
+
+Dev Lab artifact intake now requires same-origin `artifact_base` and `task_base` URLs, checks manifest/spec/review/task identity, surfaces candidate expiry and disables review staging when binding is invalid. This is a client-side safety rail backed by repository-side validators; it is not a replacement for cryptographic verification.
+
+## Verified behavior
+
+The regression harness now covers foreign candidate review, duplicate scene bundle selection, cross-task replay, symlink artifacts and capability evidence outside the repository. Python compilation and the Dev Lab production build pass. Existing Intelligence Core P0/P1 contracts remain covered by the same deterministic suite.
+
+## Trust boundary
+
+Hash chains and path guards provide deterministic repository-local integrity. They do not create an external trust anchor, and semantic lint, benchmark, provenance or Dev Lab state cannot manufacture user approval. `OPEN_PR=0` remains the default; GitHub write actions continue to require explicit confirmation.
+
+## Remaining scope
+
+Signed DSSE/in-toto attestation, external verification, runtime frame telemetry, asset-level visual comparison and historical multi-project benchmark aggregation remain future roadmap work.

package/docs/releases/1.9.0.md

@@ -0,0 +1,21 @@
+## Summary
+
+MotionLoom 1.9.0 adds an internal evidence-interoperability layer for runtime observability. The real browser adapter harness now emits deterministic scrub-point telemetry, and a read-only external verifier checks whether that evidence is fresh, task-bound, path-safe and hash-consistent before a strict quality gate can accept it.
+
+## Added
+
+Runtime telemetry records the scene, task identity, source and manifest hashes, Motion IR hash, runtime adapter metadata, scrub points, observed runtime state hashes and RAF timing. The telemetry contract is versioned in `schemas/runtime-telemetry.schema.json`; the existing runtime evidence contract now exposes the binding fields in a backward-compatible extension.
+
+`scripts/evidence-verifier.py` provides a machine-readable verifier result under `schemas/evidence-verifier-report.schema.json`. It is intentionally read-only, has stable exit behavior, rejects stale, tampered, cross-task, symlinked and path-escaped evidence, and always emits `approval: false`. A successful verification proves evidence integrity only; it never replaces runtime assertions, Dev Lab review or user consent.
+
+The `--require-telemetry` quality-gate contract and `scripts/capture-runtime-telemetry.sh` CI helper make the sequence reproducible. Report collection and handoff now include the verifier and telemetry artifacts. The Dev Lab evidence rail displays verifier status, telemetry summary and semantic benchmark status, and prevents confirm-to-PR when identity or integrity checks fail.
+
+The regression harness and Intelligence eval corpus cover telemetry happy path, state tampering, cross-task identity, stale evidence and symlink escape. The Agent Card, SKILL.md, README and Intelligence reference expose the same command and artifact vocabulary.
+
+## Verified behavior
+
+The canonical smoke task passes replay verification after handoff synchronization, runtime telemetry capture, external verification, report completeness, strict quality gate with `--require-telemetry`, regression tests, adversarial Intelligence evals, Skill Doctor and the Dev Lab production build. The phase remains compatible with the existing runtime evidence and review-first approval model.
+
+## Trust boundary and remaining scope
+
+This release is an internal integrity contract, not an independent cryptographic trust anchor. A compromised repository or substituted verifier is outside its assurance boundary. Signed DSSE/in-toto-compatible attestations, key rotation/revocation, an independently deployed verifier, asset-level visual comparison and historical benchmark aggregation remain the next roadmap phase.

package/docs/releases/2.0.0.md

@@ -0,0 +1,21 @@
+# MotionLoom 2.0.0 — Signed Attestation and Trust Anchor Contract
+
+## Summary
+
+MotionLoom 2.0.0 adds a DSSE-compatible signed attestation layer for task-bound animation evidence. The milestone separates **cryptographic integrity and signer identity** from **human approval**: every attestation and verifier report preserves `approval: false`, and the confirm-to-PR flow still requires an approved browser review plus a passing quality gate.
+
+## Added
+
+The release adds versioned schemas for `signed-attestation.json` and `trust-policy.json`, a canonical statement builder, an Ed25519 attestation builder, an independent external verifier, and a fixture-only key generator for local/CI plumbing. The verifier uses stable exit codes: `0` verified, `10` malformed envelope, `11` payload mismatch, `12` signature failure, `13` trust-policy failure, `14` expected binding mismatch, and `2` usage or I/O failure.
+
+The report contract and quality gate now support `--require-attestation`. CI derives a statement from exact scene/task hashes, signs it with a job-local ephemeral key for verification plumbing, copies the matching policy into the task bundle, and runs the independent verifier. Production deployments must use a managed private key and trust policy outside the repository; the CI fixture is not a production trust anchor.
+
+## Verified behavior
+
+Regression and adversarial evaluation cover clean verification, payload tampering, expected task/scene binding mismatch, revoked signer, unknown signer, path safety, and the invariant that a valid signature never becomes approval. The complete suite passes with the 2.0.0 eval corpus, including all previous Intelligence Core, P1 semantic, continuity, runtime telemetry and trust-boundary cases.
+
+## Trust boundary and remaining scope
+
+Attestation proves that a trusted signer signed a canonical statement whose bound bytes and identities verify under the selected policy. It does not prove visual quality, accessibility quality, user intent, or reviewer consent. A user must still inspect the Dev Lab, record `review.json`, and explicitly authorize any commit/push/PR side effect.
+
+The next roadmap slice is visual comparison with provenance-labeled fixtures and append-only benchmark history with aggregate metrics and outlier detection. Managed key distribution, rotation and transparency logging remain deployment responsibilities rather than hidden behavior inside the Skill repository.

package/docs/releases/npm-publish-from-workstation.md

@@ -0,0 +1,88 @@
+# Publish MotionLoom to npm from your workstation
+
+This guide publishes the prepared `motionloom@2.0.0` package from your own computer. The npm password, authenticator code and access token must stay on your computer; never paste them into chat, GitHub issues or repository files.
+
+## 1. Install prerequisites
+
+Use Node.js 18 or newer, npm 10 or newer, Git and Python 3.11 or newer. Verify them before cloning:
+
+```bash
+node --version
+npm --version
+git --version
+python3 --version
+```
+
+## 2. Clone the prepared GitHub release
+
+After the npm packaging commit has been pushed to `main`, clone the repository and enter it:
+
+```bash
+git clone https://github.com/lenhonbp/MotionLoom.git
+cd MotionLoom
+git checkout main
+git pull --ff-only origin main
+git log -1 --oneline
+```
+
+The latest commit must be the npm packaging release announced in the task. Do not publish from an older checkout or from a different fork.
+
+## 3. Authenticate npm locally
+
+Start the official npm login flow on your computer:
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm whoami
+```
+
+Complete the browser login and 2FA challenge if npm requests them. The second command must print your npm username. If the account uses an organization, confirm that the account has publish permission for the unscoped package name `motionloom`.
+
+## 4. Inspect the package before publishing
+
+Run the package checks from the cloned repository:
+
+```bash
+node -e 'JSON.parse(require("fs").readFileSync("package.json", "utf8")); console.log("package.json: valid")'
+npm pack --dry-run --json --ignore-scripts
+npm publish --dry-run --access public
+```
+
+The dry-run should report `motionloom@2.0.0`, public access, approximately 260 kB compressed size and 111 files. The prepack hook removes generated Python bytecode before packaging. Do not publish if the dry-run shows private keys, `.env` files, `artifacts/`, `dev-lab/` or `__pycache__/` entries.
+
+## 5. Publish the package
+
+When the dry-run is correct and `npm whoami` shows the intended account, publish the unscoped package publicly:
+
+```bash
+npm publish --access public
+```
+
+The version `2.0.0` becomes immutable on npm after a successful publish. If npm reports that the version already exists, stop and verify the registry instead of trying to overwrite it.
+
+## 6. Verify the registry publication
+
+Run the following commands and confirm that they return `2.0.0` and a tarball URL:
+
+```bash
+npm view motionloom version --registry=https://registry.npmjs.org/
+npm view motionloom@2.0.0 name version license dist.tarball dist.shasum --json \
+  --registry=https://registry.npmjs.org/
+```
+
+Then test installation in a clean temporary directory:
+
+```bash
+TMP_DIR="$(mktemp -d)"
+cd "$TMP_DIR"
+npm init --yes
+npm install motionloom@2.0.0
+motionloom --help
+motionloom doctor
+```
+
+The CLI should print the MotionLoom command surface. `motionloom doctor` should validate the installed package contract. The Python runtime remains a prerequisite for commands that delegate to Python scripts.
+
+## Troubleshooting
+
+If `npm whoami` returns `ENEEDAUTH`, repeat `npm login` on the same computer and registry. If publishing returns `E403`, check package ownership, organization publish permission and 2FA policy; do not disable security controls. If the package name is already claimed, stop and choose a scoped name such as `@your-npm-user/motionloom`, then update `name` and `publishConfig` before publishing a new package identity. Never place an npm token in `package.json`, `.npmrc` committed to Git, shell history or chat.

package/docs/research/AGENT-PROTOCOL-FINDINGS.md

@@ -0,0 +1,43 @@
+# Agent Protocol Findings
+
+## Model Context Protocol
+
+Source: <https://modelcontextprotocol.io/specification/2026-07-28>
+
+The current MCP specification separates contextual data/resources, prompts/workflows and tools/capabilities. This maps cleanly to MotionLoom's future surface: project context and artifact bundles should be exposed as resources, workflow recipes as prompts or instructions, and side-effecting operations such as prepare-review or confirm-to-PR as tools with explicit input/output schemas.
+
+Source: <https://modelcontextprotocol.io/specification/2026-07-28/server/tools>
+
+The Tools specification distinguishes malformed protocol requests from actionable tool execution errors. Execution errors should carry self-correcting feedback for the model. It also states that tool invocations should preserve a human-in-the-loop ability to deny invocation. MotionLoom should therefore return structured diagnostics for invalid context, stale evidence, missing source binding and failed runtime checks, while keeping review approval and real PR side effects behind an explicit user confirmation boundary.
+
+## Design implication for MotionLoom
+
+MotionLoom should not expose one opaque “make animation” action. It should expose typed stages with discoverable capabilities, machine-readable error classes, resource references to the exact task/artifact bundle, and explicit side-effect levels. The protocol layer must preserve the existing `OPEN_PR=0` default and add an approval token or equivalent short-lived authority for any remote write.
+
+## Provenance and attestations
+
+Source: <https://slsa.dev/spec/v1.0/provenance>
+
+SLSA models provenance as verifiable information about how an artifact was produced. The model separates the artifact `subject`, the parameterized `buildType`/build definition, the builder identity, and resolved dependencies/materials. Verification is based on trusted signer-builder pairs rather than a generic “generated successfully” flag.
+
+Source: <https://github.com/in-toto/docs/blob/master/in-toto-spec.md>
+
+in-toto describes a supply chain as an ordered set of steps with explicit actors, materials, products and inspections. Its core value is detecting a step that was omitted, replaced, added or performed by the wrong actor, not merely checking the final file hash.
+
+## Design implication for MotionLoom
+
+The current `artifact-manifest.json` is a useful checksum inventory but not yet a complete provenance attestation. A deeper design should add a signed or attestable `provenance.json` containing `materials`, `products`, `step`, `actor`, `builder`, `build_type`, `inputs`, `outputs` and verification policy. The chain should cover analyze, spec, source, generate, render, runtime adapter, browser review, quality gate and confirm—not just the final scene.
+
+## Agent Skill packaging and evaluation
+
+Source: <https://agentskills.io/specification>
+
+The Agent Skills specification defines a small `SKILL.md` frontmatter contract and recommends progressive disclosure: short metadata for discovery, an instructions body kept below roughly 500 lines, and on-demand resources in `scripts/`, `references/` or `assets/`. MotionLoom should keep the activation contract concise and move framework-specific rules, schemas and long runbooks into referenced files.
+
+Source: <https://agentskills.io/skill-creation/evaluating-skills>
+
+The evaluation guidance recommends realistic prompts, expected outputs, input files, varied wording and at least one boundary or ambiguous case. It also describes an iterative loop of running evaluations, writing assertions, grading outputs and reviewing patterns with a human.
+
+## Design implication for MotionLoom
+
+The current regression suite validates scripts and artifacts, but it does not yet measure whether an Agent selected the correct capability, preserved project intent or produced a useful fix plan. MotionLoom needs an `evals/` corpus with project contexts, animation intents, ambiguous requests, stale source, unsupported runtime and review rejection cases. Each case should grade both machine contracts and human-facing report quality.

package/examples/report-demo/REPORT.md

@@ -0,0 +1,50 @@
+# Animation Task Report — report-demo
+
+## Status
+- Overall: **created**
+- Confidence: **low**
+- Scene: `onboarding-wave`
+- Project: `example-project`
+- Context hash: ``
+
+## Completed
+| Item | Status | Evidence |
+| --- | --- | --- |
+| Host project context analyzed | pass | ['project-context.json'] |
+
+## Verified
+| Item | Status | Evidence |
+| --- | --- | --- |
+| Motion spec context binding created | pass | ['motion-spec.json'] |
+
+## Not completed
+| Item | Status | Evidence |
+| --- | --- | --- |
+| Runtime render has not been executed in this example | pending |  |
+
+## Problems to fix
+| ID | Severity | Problem | Status | Next action |
+| --- | --- | --- | --- | --- |
+| runtime-evidence | P1 | PR evidence is incomplete until runtime snapshots exist | open | Render frames 0/50/100 and attach .render-meta.json |
+
+## Structure review
+- Missing files: `project-context.json`
+- Broken references: `src/output/onboarding-wave/animation.json`
+- Artifact count: **3**
+- Quality gate: **not-run**
+
+## Recommended next Agent / Skill
+| Agent/Skill | Action | Evidence needed |
+| --- | --- | --- |
+| motionloom | Run project analysis and populate context before generation. |  |
+| motionloom |  | ['snapshot/.render-meta.json', 'review.json'] |
+
+## Evidence files
+| Path | Type | Bytes | SHA-256 |
+| --- | --- | --- | --- |
+| handoff.json | json | 479 | b4b14fce76fa027276ab569c1b74a2de1ebdb3f8f0e3f46d9930a1e3fb5a96ae |
+| issue-register.json | json | 67 | 56667cfd1b718546956e2b0b6a08adb328fe4d7c3df6814dda81b33fb8296504 |
+| task.json | json | 367 | ee315e0c3eee2f12d80d4856623520b894bfdec404f0838973026401b42c2c27 |
+
+
+_Generated at 2026-08-12T13:57:24Z by `scripts/report.py`._

package/examples/report-demo/artifact-manifest.json

@@ -0,0 +1,25 @@
+{
+  "manifest_version": "1.0",
+  "task_id": "report-demo",
+  "generated_at": "2026-08-12T13:57:24Z",
+  "artifacts": [
+    {
+      "path": "handoff.json",
+      "type": "json",
+      "sha256": "b4b14fce76fa027276ab569c1b74a2de1ebdb3f8f0e3f46d9930a1e3fb5a96ae",
+      "bytes": 479
+    },
+    {
+      "path": "issue-register.json",
+      "type": "json",
+      "sha256": "56667cfd1b718546956e2b0b6a08adb328fe4d7c3df6814dda81b33fb8296504",
+      "bytes": 67
+    },
+    {
+      "path": "task.json",
+      "type": "json",
+      "sha256": "ee315e0c3eee2f12d80d4856623520b894bfdec404f0838973026401b42c2c27",
+      "bytes": 367
+    }
+  ]
+}

package/examples/report-demo/execution-report.json

@@ -0,0 +1,70 @@
+{
+  "report_version": "1.0",
+  "task_id": "report-demo",
+  "status": "created",
+  "confidence": "low",
+  "completed": [
+    {
+      "id": "analyze",
+      "summary": "Host project context analyzed",
+      "status": "pass",
+      "evidence": [
+        "project-context.json"
+      ]
+    }
+  ],
+  "verified": [
+    {
+      "id": "spec",
+      "summary": "Motion spec context binding created",
+      "status": "pass",
+      "evidence": [
+        "motion-spec.json"
+      ]
+    }
+  ],
+  "not_completed": [
+    {
+      "id": "runtime",
+      "summary": "Runtime render has not been executed in this example",
+      "status": "pending",
+      "next_action": "Run scripts/render.sh onboarding-wave"
+    }
+  ],
+  "problems": [
+    {
+      "id": "runtime-evidence",
+      "summary": "PR evidence is incomplete until runtime snapshots exist",
+      "status": "open",
+      "severity": "P1",
+      "next_action": "Render frames 0/50/100 and attach .render-meta.json"
+    }
+  ],
+  "structure_review": {
+    "missing_files": [
+      "project-context.json"
+    ],
+    "broken_references": [
+      "src/output/onboarding-wave/animation.json"
+    ],
+    "untracked_artifacts": []
+  },
+  "next_agent": [
+    {
+      "agent": "motionloom",
+      "action": "Run project analysis and populate context before generation."
+    },
+    {
+      "id": "render",
+      "summary": "Continue with runtime render and Dev Lab review",
+      "status": "pending",
+      "agent": "motionloom",
+      "skill": "motionloom",
+      "evidence_needed": [
+        "snapshot/.render-meta.json",
+        "review.json"
+      ]
+    }
+  ],
+  "generated_at": "2026-08-12T13:57:24Z"
+}

package/examples/report-demo/handoff.json

@@ -0,0 +1,22 @@
+{
+  "handoff_version": "1.0",
+  "task_id": "report-demo",
+  "from_agent": "motionloom",
+  "to_agent": "motionloom",
+  "state": "created",
+  "summary": "New animation task initialized.",
+  "next_actions": [
+    {
+      "action": "Analyze host project context",
+      "skill": "motionloom",
+      "evidence_needed": [
+        "project-context.json"
+      ]
+    }
+  ],
+  "required_artifacts": [
+    "task.json",
+    "execution-report.json"
+  ],
+  "blockers": []
+}

package/examples/report-demo/issue-register.json

@@ -0,0 +1,5 @@
+{
+  "version": "1.0",
+  "task_id": "report-demo",
+  "issues": []
+}

package/examples/report-demo/task.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": "1.0",
+  "task_id": "report-demo",
+  "scene": "onboarding-wave",
+  "intent": "Demonstrate transparent execution reporting",
+  "project_name": "example-project",
+  "context_path": "",
+  "context_hash": "",
+  "state": "created",
+    "owner_agent": "motionloom",
+  "created_at": "2026-08-12T13:57:24Z",
+  "updated_at": "2026-08-12T13:57:24Z"
+}