motionloom 2.0.0

package/scripts/review-hook.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Prepare and validate the mandatory internal-browser Dev Lab review handoff."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import subprocess
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from urllib.parse import urlencode
+
+ROOT = Path(__file__).resolve().parents[1]
+SAFE_SCENE = re.compile(r"^[A-Za-z0-9._-]+$")
+CANDIDATE_TTL = timedelta(hours=24)
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def read_json(path: Path, default: dict | None = None) -> dict:
+    if not path.is_file():
+        return {} if default is None else default
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def parse_time(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def candidate_id(task_id: str, scene: str, context_hash: str, source_hash: str, render_hash: str) -> str:
+    raw = f"{task_id}:{scene}:{context_hash}:{source_hash}:{render_hash}".encode()
+    return hashlib.sha256(raw).hexdigest()[:20]
+
+
+def paths(task_dir: Path, task: dict) -> tuple[Path, Path, Path, Path]:
+    scene = task.get("scene", "")
+    if not scene or scene in {".", ".."} or not SAFE_SCENE.fullmatch(scene):
+        raise ValueError("task.scene contains unsafe path characters")
+    scene_dir = ROOT / "src" / "output" / scene
+    manifest_path = scene_dir / "manifest.json"
+    manifest = read_json(manifest_path)
+    source_path = (scene_dir / manifest["file"]).resolve()
+    render_meta = scene_dir / "snapshot" / ".render-meta.json"
+    context_path = Path(task.get("context_path") or ROOT / "project-context.json")
+    if not context_path.is_absolute():
+        context_path = ROOT / context_path
+    if not source_path.is_file() or scene_dir.resolve() not in source_path.parents:
+        raise ValueError("manifest.file must point to a source inside the selected scene directory")
+    if not render_meta.is_file():
+        raise ValueError("runtime snapshot metadata is required before browser review")
+    return scene_dir, source_path, render_meta, context_path
+
+
+def prepare(args: argparse.Namespace) -> int:
+    task_dir = Path(args.task_dir).resolve()
+    task_path = task_dir / "task.json"
+    task = read_json(task_path)
+    scene = task.get("scene")
+    if not scene:
+        raise ValueError("task.json requires scene")
+    scene_dir, source_path, render_meta, context_path = paths(task_dir, task)
+    spec = read_json(scene_dir / "motion-spec.json")
+    context_hash = (spec.get("context_binding") or {}).get("context_sha256") or sha256(context_path)
+    source_hash = sha256(source_path)
+    render_hash = sha256(render_meta)
+    cid = candidate_id(task["task_id"], scene, context_hash, source_hash, render_hash)
+    base = args.lab_url.rstrip("/")
+    task_id = task["task_id"]
+    url = f"{base}/?{urlencode({'scene': scene, 'task_id': task_id, 'candidate_id': cid, 'artifact_base': f'{base}/scenes/{scene}', 'task_base': f'{base}/tasks/{task_id}'})}"
+    candidate = {
+        "schema_version": "1.0",
+        "candidate_id": cid,
+        "task_id": task["task_id"],
+        "scene": scene,
+        "url": url,
+        "status": "prepared",
+        "context_sha256": context_hash,
+        "source_sha256": source_hash,
+        "runtime": spec.get("framework", "unknown"),
+        "checkpoints": [0, 50, 100],
+        "review_artifact": "review.json",
+        "requires_user_approval": True,
+        "prepared_at": now(),
+        "expires_at": (datetime.now(timezone.utc) + CANDIDATE_TTL).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+    }
+    (scene_dir / "browser-review.json").write_text(json.dumps(candidate, indent=2) + "\n", encoding="utf-8")
+    task["state"] = "review_required"
+    task["updated_at"] = now()
+    task["browser_review"] = {"required": True, "status": "prepared", "candidate_id": cid, "candidate_path": "browser-review.json", "review_artifact": "review.json"}
+    (task_dir / "browser-review.json").write_text(json.dumps(candidate, indent=2) + "\n", encoding="utf-8")
+    (task_dir / "task.json").write_text(json.dumps(task, indent=2) + "\n", encoding="utf-8")
+    report_path = task_dir / "execution-report.json"
+    report = read_json(report_path)
+    report["status"] = "review_required"
+    report["browser_review"] = [item for item in report.get("browser_review", []) if item.get("candidate_id") != cid]
+    report["browser_review"].append({"candidate_id": cid, "decision": "pending", "evidence": ["browser-review.json"], "next_action": "Open the internal Dev Lab URL and ask the user to review."})
+    report["next_agent"] = [item for item in report.get("next_agent", []) if item.get("id") != "browser-review"]
+    report["next_agent"].append({"id": "browser-review", "summary": "Open the exact candidate in the internal Dev Lab browser.", "status": "pending", "agent": "browser-review-agent", "skill": "browser-review", "evidence_needed": ["review.json"], "next_action": "Ask user to approve or request changes."})
+    report["generated_at"] = now()
+    report_path.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    handoff_path = task_dir / "handoff.json"
+    handoff = read_json(handoff_path)
+    handoff.update({"state": "review_required", "to_agent": "browser-review-agent", "summary": "Open the exact rendered candidate in the internal Dev Lab and obtain user approval before PR.", "next_actions": [{"action": "Open internal Dev Lab candidate", "kind": "browser_review", "agent": "browser-review-agent", "skill": "browser-review", "url": url, "candidate_id": cid, "requires_user_approval": True, "evidence_needed": ["review.json"], "output_artifacts": ["review.json"]}], "required_artifacts": sorted(set(handoff.get("required_artifacts", []) + ["browser-review.json", "review.json", "semantic-lint-benchmark.json", "evidence-verifier-report.json", "runtime-adapters/runtime-evidence.json"]))})
+    handoff_path.write_text(json.dumps(handoff, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    subprocess.run(["bash", str(ROOT / "scripts/devlab.sh"), scene, "--prepare-only", str(task_dir)], check=True, capture_output=True, text=True)
+    subprocess.run([sys.executable, str(ROOT / "scripts/report.py"), "collect", "--task-dir", str(task_dir)], check=True, capture_output=True, text=True)
+    print(json.dumps({"status": "review_required", "task_id": task["task_id"], "candidate_id": cid, "url": url, "agent": "browser-review-agent", "action": "Open this exact URL in the internal browser; ask the user to inspect frames 0/50/100 and approve or request changes.", "requires_user_approval": True, "output_artifacts": ["review.json"]}, ensure_ascii=False))
+    return 0
+
+
+def validate(args: argparse.Namespace) -> int:
+    task_dir = Path(args.task_dir).resolve()
+    task = read_json(task_dir / "task.json")
+    candidate = read_json(task_dir / "browser-review.json")
+    scene_dir, source_path, render_meta, context_path = paths(task_dir, task)
+    spec = read_json(scene_dir / "motion-spec.json")
+    context_hash = (spec.get("context_binding") or {}).get("context_sha256") or sha256(context_path)
+    expected = candidate_id(task["task_id"], task["scene"], context_hash, sha256(source_path), sha256(render_meta))
+    errors = []
+    if not candidate.get("expires_at"):
+        errors.append("browser-review candidate has no expiry")
+    else:
+        try:
+            if datetime.now(timezone.utc) > parse_time(candidate["expires_at"]):
+                errors.append("browser-review candidate has expired")
+        except (TypeError, ValueError):
+            errors.append("browser-review candidate expiry is invalid")
+    if candidate.get("candidate_id") != expected:
+        errors.append("candidate_id does not match task, context, source and runtime metadata")
+    if candidate.get("task_id") != task.get("task_id"):
+        errors.append("candidate task_id does not match task.json")
+    task_review = task.get("browser_review") or {}
+    if task_review.get("candidate_id") != candidate.get("candidate_id"):
+        errors.append("task browser_review candidate_id does not match browser-review.json")
+    if task_review.get("status") == "approved" and candidate.get("status") != "approved":
+        errors.append("task browser_review status claims approved but candidate is not approved")
+    if candidate.get("scene") != task.get("scene"):
+        errors.append("candidate scene does not match task scene")
+    if candidate.get("source_sha256") != sha256(source_path):
+        errors.append("candidate source_sha256 is stale")
+    if candidate.get("context_sha256") != context_hash:
+        errors.append("candidate context_sha256 is stale")
+    if candidate.get("status") not in {"prepared", "opened", "reviewed", "approved", "changes_requested", "expired"}:
+        errors.append(f"browser-review candidate status is invalid: {candidate.get('status')}")
+    review = read_json(task_dir / "review.json", {})
+    if review and review.get("candidate_id") != candidate.get("candidate_id"):
+        errors.append("review.json approves a different candidate")
+    if review:
+        if review.get("task_id") != task.get("task_id"):
+            errors.append("review.json task_id does not match task.json")
+        if not str(review.get("reviewer") or "").strip():
+            errors.append("review.json reviewer is required")
+        reviewed_at = review.get("reviewed_at")
+        if reviewed_at:
+            try:
+                if parse_time(reviewed_at) > parse_time(candidate["expires_at"]):
+                    errors.append("review.json was recorded after candidate expiry")
+            except (TypeError, ValueError, KeyError):
+                errors.append("review.json reviewed_at or candidate expiry is invalid")
+    if args.require_approved:
+        if candidate.get("status") != "approved":
+            errors.append("browser-review candidate is not approved")
+        if not review or review.get("decision") != "approved":
+            errors.append("review.json decision must be approved")
+    status = "pass" if not errors else "fail"
+    print(json.dumps({"status": status, "task_id": task.get("task_id"), "candidate_id": candidate.get("candidate_id"), "candidate_status": candidate.get("status"), "errors": errors}, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("prepare")
+    p.add_argument("--task-dir", required=True)
+    p.add_argument("--lab-url", default="http://127.0.0.1:3300")
+    p.set_defaults(func=prepare)
+    v = sub.add_parser("validate")
+    v.add_argument("--task-dir", required=True)
+    v.add_argument("--require-approved", action="store_true")
+    v.set_defaults(func=validate)
+    args = parser.parse_args()
+    try:
+        return args.func(args)
+    except (KeyError, FileNotFoundError, json.JSONDecodeError, ValueError, subprocess.CalledProcessError) as exc:
+        print(json.dumps({"status": "fail", "error": str(exc)}, ensure_ascii=False))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/runtime-adapters.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawn } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
+import { chromium } from "playwright";
+import crypto from "node:crypto";
+
+const ROOT = path.resolve(new URL("..", import.meta.url).pathname);
+const outputRoot = path.resolve(process.env.RUNTIME_EVIDENCE_DIR || path.join(ROOT, "artifacts/runtime-adapters"));
+const port = Number(process.env.RUNTIME_HARNESS_PORT || 4179);
+const supportedFrameworks = new Set(["rive", "gsap", "framer-motion"]);
+const frameworks = (process.env.RUNTIME_FRAMEWORKS || "rive,gsap,framer-motion")
+  .split(",").map((name) => name.trim()).filter(Boolean);
+const unsupported = frameworks.filter((name) => !supportedFrameworks.has(name));
+if (unsupported.length) {
+  throw new Error(`unsupported runtime framework(s): ${unsupported.join(", ")}`);
+}
+if (outputRoot === ROOT || outputRoot === path.parse(outputRoot).root) {
+  throw new Error("RUNTIME_EVIDENCE_DIR must be a dedicated child output directory");
+}
+const baseUrl = `http://127.0.0.1:${port}`;
+const runId = `${Date.now()}-${process.pid}`;
+const runtimeScene = process.env.RUNTIME_SCENE || null;
+const runtimeTaskId = process.env.RUNTIME_TASK_ID || null;
+const runtimeSourcePath = process.env.RUNTIME_SOURCE_PATH ? path.resolve(process.env.RUNTIME_SOURCE_PATH) : null;
+const runtimeManifestPath = process.env.RUNTIME_MANIFEST_PATH ? path.resolve(process.env.RUNTIME_MANIFEST_PATH) : null;
+const runtimeMotionIrPath = process.env.RUNTIME_MOTION_IR_PATH ? path.resolve(process.env.RUNTIME_MOTION_IR_PATH) : null;
+
+function sha256File(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function sha256Json(value) {
+  return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+fs.rmSync(outputRoot, { recursive: true, force: true });
+fs.mkdirSync(outputRoot, { recursive: true });
+const viteBin = path.join(ROOT, "node_modules/vite/bin/vite.js");
+const server = spawn(process.execPath, [viteBin, "--host", "127.0.0.1", "--port", String(port), "--strictPort"], {
+  cwd: ROOT,
+  stdio: ["ignore", "pipe", "pipe"],
+});
+let serverLog = "";
+server.stdout.on("data", (chunk) => { serverLog += chunk.toString(); });
+server.stderr.on("data", (chunk) => { serverLog += chunk.toString(); });
+
+try {
+  await waitForServer(`${baseUrl}/tests/runtime-harness/index.html`);
+  const browser = await chromium.launch({ headless: true });
+  const summary = [];
+  for (const framework of frameworks) {
+    summary.push(await testFramework(browser, framework));
+  }
+  await browser.close();
+  const report = {
+    schema_version: "1.1",
+    run_id: runId,
+    generated_at: new Date().toISOString(),
+    mode: "runtime",
+    harness: "tests/runtime-harness",
+    status: summary.every((item) => item.status === "pass") ? "pass" : "fail",
+    frameworks: summary,
+  };
+  if (runtimeScene) report.scene = runtimeScene;
+  if (runtimeTaskId) report.task_id = runtimeTaskId;
+  if (runtimeSourcePath) report.source_sha256 = sha256File(runtimeSourcePath);
+  if (runtimeManifestPath) report.manifest_sha256 = sha256File(runtimeManifestPath);
+  if (runtimeMotionIrPath) report.motion_ir_sha256 = sha256File(runtimeMotionIrPath);
+  fs.writeFileSync(path.join(outputRoot, "runtime-evidence.json"), `${JSON.stringify(report, null, 2)}\n`);
+  const failed = summary.filter((item) => item.status !== "pass");
+  if (failed.length) {
+    console.error(JSON.stringify(report, null, 2));
+    process.exitCode = 1;
+  } else {
+    console.log(JSON.stringify(report, null, 2));
+  }
+} finally {
+  server.kill("SIGTERM");
+  await sleep(100);
+  if (!server.killed) server.kill("SIGKILL");
+}
+
+async function waitForServer(url) {
+  for (let attempt = 0; attempt < 80; attempt += 1) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) return;
+    } catch {
+      // Vite is still starting.
+    }
+    await sleep(100);
+  }
+  throw new Error(`runtime harness did not start on ${url}\n${serverLog}`);
+}
+
+async function testFramework(browser, framework) {
+  const sceneDir = path.join(outputRoot, framework);
+  fs.mkdirSync(sceneDir, { recursive: true });
+  const page = await browser.newPage({ viewport: { width: 512, height: 512 }, deviceScaleFactor: 1 });
+  const consoleErrors = [];
+  page.on("pageerror", (error) => consoleErrors.push(error.message));
+  page.on("console", (message) => {
+    if (message.type() === "error") consoleErrors.push(message.text());
+  });
+  const url = `${baseUrl}/tests/runtime-harness/index.html?framework=${encodeURIComponent(framework)}`;
+  const result = { run_id: runId, framework, url, status: "fail", ready: false, runtime: null, frames: [], console_errors: consoleErrors };
+  try {
+    await page.goto(url, { waitUntil: "networkidle" });
+    await page.waitForFunction(() => Boolean(window.__animationAdapter?.ready), null, { timeout: 30000 });
+    result.ready = true;
+    result.runtime = await page.evaluate(() => window.__animationAdapter.runtime);
+    const telemetrySamples = [];
+    for (const [sequence, percent] of [0, 50, 100].entries()) {
+      const timing = await page.evaluate(async (value) => {
+        window.__animationAdapter.setProgress(value / 100);
+        const timestamps = await new Promise((resolve) => {
+          const values = [];
+          const collect = (timestamp) => {
+            values.push(timestamp);
+            if (values.length >= 4) resolve(values);
+            else requestAnimationFrame(collect);
+          };
+          requestAnimationFrame(collect);
+        });
+        return {
+          captured_at_ms: performance.now(),
+          raf_intervals_ms: timestamps.slice(1).map((timestamp, index) => Math.max(0, timestamp - timestamps[index])),
+        };
+      }, percent);
+      const state = await page.evaluate(() => window.__animationAdapter.getState());
+      const file = path.join(sceneDir, `frame-${String(percent).padStart(2, "0")}.png`);
+      await page.screenshot({ path: file });
+      result.frames.push({ percent, file: path.relative(ROOT, file), state });
+      telemetrySamples.push({
+        sequence,
+        percent,
+        captured_at_ms: Number(timing.captured_at_ms),
+        raf_intervals_ms: timing.raf_intervals_ms.map(Number),
+        state_sha256: sha256Json(state),
+        state,
+      });
+    }
+    if (consoleErrors.length) throw new Error(consoleErrors.join("; "));
+    const intervals = telemetrySamples.flatMap((sample) => sample.raf_intervals_ms);
+    const sortedIntervals = [...intervals].sort((a, b) => a - b);
+    const p95Index = Math.min(sortedIntervals.length - 1, Math.max(0, Math.ceil(sortedIntervals.length * 0.95) - 1));
+    const telemetry = {
+      schema_version: "1.0",
+      run_id: runId,
+      generated_at: new Date().toISOString(),
+      mode: "runtime-telemetry",
+      ...(runtimeTaskId ? { task_id: runtimeTaskId } : {}),
+      ...(runtimeScene ? { scene: runtimeScene } : {}),
+      framework,
+      runtime: result.runtime,
+      ...(runtimeSourcePath ? { source_sha256: sha256File(runtimeSourcePath) } : {}),
+      ...(runtimeManifestPath ? { manifest_sha256: sha256File(runtimeManifestPath) } : {}),
+      ...(runtimeMotionIrPath ? { motion_ir_sha256: sha256File(runtimeMotionIrPath) } : {}),
+      samples: telemetrySamples,
+      metrics: {
+        sample_count: telemetrySamples.length,
+        raf_interval_count: intervals.length,
+        max_raf_interval_ms: Math.max(...intervals),
+        p95_raf_interval_ms: sortedIntervals[p95Index],
+      },
+      status: "pass",
+    };
+    const telemetryPath = path.join(sceneDir, "runtime-telemetry.json");
+    fs.writeFileSync(telemetryPath, `${JSON.stringify(telemetry, null, 2)}\n`);
+    result.telemetry = {
+      file: path.relative(outputRoot, telemetryPath),
+      sha256: sha256File(telemetryPath),
+      metrics: telemetry.metrics,
+    };
+    result.status = "pass";
+  } catch (error) {
+    result.error = error instanceof Error ? error.message : String(error);
+  } finally {
+    await page.close();
+  }
+  fs.writeFileSync(path.join(sceneDir, "runtime-evidence.json"), `${JSON.stringify(result, null, 2)}\n`);
+  return result;
+}

package/scripts/skill-doctor.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Check the skill package structure and emit machine-readable diagnostics."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+REQUIRED_FILES = ["SKILL.md", "agent-card.json", "package.json"]
+REQUIRED_DIRS = ["scripts", "templates", "references", "schemas"]
+REQUIRED_SCRIPT_FILES = ["scripts/report-contract.py", "scripts/review-hook.py", "scripts/quality-gate.py", "scripts/runtime-adapters.mjs"]
+REQUIRED_SCHEMAS = [
+    "task.schema.json",
+    "execution-report.schema.json",
+    "artifact-manifest.schema.json",
+    "handoff.schema.json",
+    "browser-review-candidate.schema.json",
+    "scene-manifest.schema.json",
+    "runtime-evidence.schema.json",
+    "project-graph.schema.json",
+    "provenance.schema.json",
+    "capability-registry.schema.json",
+    "motion-ir.schema.json",
+]
+
+
+def check(condition: bool, code: str, message: str, errors: list, warnings: list) -> None:
+    target = errors if not condition else warnings
+    if not condition:
+        errors.append({"code": code, "message": message})
+
+
+def parse_frontmatter(text: str) -> dict[str, str] | None:
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    try:
+        end = lines.index("---", 1)
+    except ValueError:
+        return None
+    values: dict[str, str] = {}
+    for line in lines[1:end]:
+        match = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line)
+        if match and not match.group(1).startswith(" "):
+            values[match.group(1)] = match.group(2).strip().strip('"')
+    return values
+
+
+def run() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args()
+    errors: list[dict] = []
+    warnings: list[dict] = []
+    checks: list[dict] = []
+
+    for relative in REQUIRED_FILES:
+        exists = (ROOT / relative).is_file()
+        checks.append({"id": f"file:{relative}", "status": "pass" if exists else "fail"})
+        if not exists:
+            errors.append({"code": "missing_file", "message": f"Missing required file: {relative}"})
+    for relative in REQUIRED_DIRS:
+        exists = (ROOT / relative).is_dir()
+        checks.append({"id": f"directory:{relative}", "status": "pass" if exists else "fail"})
+        if not exists:
+            errors.append({"code": "missing_directory", "message": f"Missing required directory: {relative}"})
+    for relative in REQUIRED_SCRIPT_FILES:
+        exists = (ROOT / relative).is_file()
+        checks.append({"id": f"file:{relative}", "status": "pass" if exists else "fail"})
+        if not exists:
+            errors.append({"code": "missing_file", "message": f"Missing required runtime/contract script: {relative}"})
+
+    skill_path = ROOT / "SKILL.md"
+    if skill_path.is_file():
+        text = skill_path.read_text(encoding="utf-8")
+        frontmatter = parse_frontmatter(text)
+        valid_meta = bool(frontmatter and frontmatter.get("name") and frontmatter.get("description"))
+        checks.append({"id": "skill:frontmatter", "status": "pass" if valid_meta else "fail"})
+        if not valid_meta:
+            errors.append({"code": "invalid_frontmatter", "message": "SKILL.md needs YAML frontmatter with name and description."})
+        line_count = len(text.splitlines())
+        checks.append({"id": "skill:line_count", "status": "pass" if line_count <= 500 else "fail", "lines": line_count})
+        if line_count > 500:
+            errors.append({"code": "skill_too_long", "message": f"SKILL.md has {line_count} lines; keep the body under 500 lines."})
+
+    for relative in REQUIRED_SCHEMAS:
+        path = ROOT / "schemas" / relative
+        try:
+            json.loads(path.read_text(encoding="utf-8"))
+            checks.append({"id": f"schema:{relative}", "status": "pass"})
+        except (FileNotFoundError, json.JSONDecodeError) as exc:
+            checks.append({"id": f"schema:{relative}", "status": "fail"})
+            errors.append({"code": "invalid_schema", "message": f"{relative}: {exc}"})
+
+    card_path = ROOT / "agent-card.json"
+    try:
+        card = json.loads(card_path.read_text(encoding="utf-8"))
+        for field in ("name", "version", "capabilities", "input_artifacts", "output_artifacts", "runtime_capabilities", "side_effects"):
+            if field not in card:
+                errors.append({"code": "agent_card_field", "message": f"agent-card.json missing field: {field}"})
+        verified = set(card.get("runtime_capabilities", {}).get("verified", []))
+        scaffold = set(card.get("runtime_capabilities", {}).get("scaffold_only", []))
+        overlap = sorted(verified & scaffold)
+        if overlap:
+            errors.append({"code": "capability_overlap", "message": f"Runtime listed as verified and scaffold-only: {overlap}"})
+    except (FileNotFoundError, json.JSONDecodeError) as exc:
+        errors.append({"code": "invalid_agent_card", "message": str(exc)})
+
+    skill_text = skill_path.read_text(encoding="utf-8") if skill_path.is_file() else ""
+    for reference in re.findall(r"`(references/[A-Za-z0-9_./-]+)`", skill_text):
+        exists = (ROOT / reference).is_file()
+        checks.append({"id": f"reference:{reference}", "status": "pass" if exists else "fail"})
+        if not exists:
+            errors.append({"code": "broken_reference", "message": f"SKILL.md references missing file: {reference}"})
+
+    package_path = ROOT / "package.json"
+    try:
+        package = json.loads(package_path.read_text(encoding="utf-8"))
+        for script in ("test", "validate", "doctor", "report", "report:check", "review"):
+            if script not in package.get("scripts", {}):
+                warnings.append({"code": "missing_package_script", "message": f"package.json has no {script} script."})
+    except (FileNotFoundError, json.JSONDecodeError) as exc:
+        errors.append({"code": "invalid_package_json", "message": str(exc)})
+
+    result = {
+        "doctor_version": "1.0",
+        "skill_root": str(ROOT),
+        "status": "pass" if not errors else "fail",
+        "checks": checks,
+        "errors": errors,
+        "warnings": warnings,
+    }
+    if args.as_json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(f"skill-doctor: {result['status'].upper()}")
+        for item in errors:
+            print(f"ERROR {item['code']}: {item['message']}")
+        for item in warnings:
+            print(f"WARN  {item['code']}: {item['message']}")
+    return 0 if not errors else 1
+
+
+if __name__ == "__main__":
+    sys.exit(run())

package/scripts/to-dotlottie.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * Deterministic dotLottie v2 packager.
+ * The scene manifest stays outside the archive; the archive contains the
+ * standard manifest.json plus the Lottie payload under a/.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+function arg(name, fallback = undefined) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? fallback : process.argv[index + 1];
+}
+
+const sceneDir = path.resolve(arg("--scene-dir", ""));
+const output = path.resolve(arg("--output", ""));
+const generator = arg("--generator", "motionloom/to-dotlottie");
+if (!sceneDir || !output) throw new Error("--scene-dir and --output are required");
+
+const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+const sceneManifestPath = path.join(sceneDir, "manifest.json");
+if (!fs.existsSync(sceneManifestPath)) throw new Error("scene manifest.json is required");
+const sceneManifest = readJson(sceneManifestPath);
+const source = sceneManifest.file;
+if (typeof source !== "string" || !source || path.isAbsolute(source) || source.includes("..")) {
+  throw new Error("scene manifest.file must be a relative path without traversal");
+}
+const sourcePath = path.resolve(sceneDir, source);
+if (!sourcePath.startsWith(`${sceneDir}${path.sep}`) || !fs.existsSync(sourcePath)) {
+  throw new Error(`scene source does not exist inside scene directory: ${source}`);
+}
+if (path.extname(sourcePath).toLowerCase() !== ".json") {
+  throw new Error("dotLottie packager currently accepts a Lottie JSON scene source");
+}
+
+const animationId = String(arg("--animation-id", path.basename(sourcePath, ".json")))
+  .trim();
+if (!/^[a-zA-Z0-9._ -]+$/.test(animationId)) {
+  throw new Error(`invalid dotLottie animation id: ${animationId}`);
+}
+readJson(sourcePath);
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "animation-skill-dotlottie-"));
+const archiveRoot = path.join(tmp, "archive");
+fs.mkdirSync(path.join(archiveRoot, "a"), { recursive: true });
+fs.copyFileSync(sourcePath, path.join(archiveRoot, "a", `${animationId}.json`));
+
+const optionalDirectories = ["i", "t", "s", "f"];
+for (const directory of optionalDirectories) {
+  const candidate = path.join(sceneDir, "dotlottie", directory);
+  if (fs.existsSync(candidate)) {
+    fs.cpSync(candidate, path.join(archiveRoot, directory), { recursive: true });
+  }
+}
+
+const dotManifest = {
+  version: "2",
+  generator,
+  initial: { animation: animationId },
+  animations: [{ id: animationId }],
+};
+fs.writeFileSync(
+  path.join(archiveRoot, "manifest.json"),
+  `${JSON.stringify(dotManifest, null, 2)}\n`,
+  "utf8",
+);
+
+fs.mkdirSync(path.dirname(output), { recursive: true });
+if (fs.existsSync(output)) fs.rmSync(output, { force: true });
+execFileSync("zip", ["-X", "-q", "-r", output, "."], { cwd: archiveRoot });
+
+const entries = execFileSync("unzip", ["-Z1", output], { encoding: "utf8" })
+  .trim()
+  .split(/\r?\n/)
+  .filter(Boolean);
+if (!entries.includes("manifest.json")) throw new Error("archive missing manifest.json");
+if (!entries.includes(`a/${animationId}.json`)) {
+  throw new Error("archive missing initial animation payload");
+}
+const packagedManifest = readJsonFromZip(output, "manifest.json");
+if (packagedManifest.version !== "2") throw new Error("dotLottie manifest version must be 2");
+if (packagedManifest.initial?.animation !== animationId) {
+  throw new Error("dotLottie initial.animation does not match packaged animation");
+}
+const hash = crypto.createHash("sha256").update(fs.readFileSync(output)).digest("hex");
+console.log(JSON.stringify({
+  output,
+  bytes: fs.statSync(output).size,
+  sha256: hash,
+  manifest: packagedManifest,
+  entries,
+}, null, 2));
+
+function readJsonFromZip(file, entry) {
+  return JSON.parse(execFileSync("unzip", ["-p", file, entry], { encoding: "utf8" }));
+}

package/scripts/to-dotlottie.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Package a validated scene into a dotLottie v2 archive.
+# Usage: bash scripts/to-dotlottie.sh <scene> [output.lottie]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(dirname "$SCRIPT_DIR")"
+SCENE="${1:?usage: bash scripts/to-dotlottie.sh <scene> [output.lottie]}"
+OUT="${2:-$REPO/src/output/$SCENE/animation.lottie}"
+
+if [[ ! "$SCENE" =~ ^[A-Za-z0-9._-]+$ ]]; then
+  echo "error: scene id contains unsafe path characters: $SCENE" >&2
+  exit 1
+fi
+
+SCENE_DIR="$REPO/src/output/$SCENE"
+if [[ ! -d "$SCENE_DIR" ]]; then
+  echo "error: scene directory not found: $SCENE_DIR" >&2
+  exit 1
+fi
+
+node "$SCRIPT_DIR/to-dotlottie.mjs" \
+  --scene-dir "$SCENE_DIR" \
+  --output "$OUT" \
+  --generator "motionloom/to-dotlottie@1.0.0"