motionloom 2.6.0 → 2.7.0

package/scripts/frame-set-preflight.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""Fail-closed preflight for Agent-generated multi-frame source assets.
+
+This wrapper reuses MotionLoom's deterministic frame-geometry measurements, then
+adds generation-time rules that are intentionally stricter than a generic asset
+inspection: source frames must be isolated canvases, scale drift is blocking,
+and the measured alpha bounds must preserve the declared transparent guard band.
+
+It never grants provenance authority, artistic approval or production approval.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+ASSET_CONSISTENCY = ROOT / "scripts" / "asset-consistency.py"
+ACTION_SEPARATION = ROOT / "scripts" / "action-separation.py"
+
+
+def load_action_separation():
+    spec = importlib.util.spec_from_file_location("motionloom_action_separation", ACTION_SEPARATION)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("cannot load action-separation.py")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def load_asset_consistency():
+    spec = importlib.util.spec_from_file_location("motionloom_asset_consistency", ASSET_CONSISTENCY)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("cannot load asset-consistency.py")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+AC = load_asset_consistency()
+AS = load_action_separation()
+
+
+def _error(code: str, message: str, path: str = "") -> dict[str, str]:
+    return {"severity": "error", "code": code, "message": message, "path": path}
+
+
+def _normalise_rect(value: dict[str, Any]) -> dict[str, int]:
+    return {key: int(value[key]) for key in ("x", "y", "width", "height")}
+
+
+def _contains(outer: dict[str, int], inner: dict[str, int]) -> bool:
+    return (
+        inner["x"] >= outer["x"]
+        and inner["y"] >= outer["y"]
+        and inner["x"] + inner["width"] <= outer["x"] + outer["width"]
+        and inner["y"] + inner["height"] <= outer["y"] + outer["height"]
+    )
+
+
+def _shrink(rect: dict[str, int], margin: int) -> dict[str, int] | None:
+    width = rect["width"] - 2 * margin
+    height = rect["height"] - 2 * margin
+    if width <= 0 or height <= 0:
+        return None
+    return {
+        "x": rect["x"] + margin,
+        "y": rect["y"] + margin,
+        "width": width,
+        "height": height,
+    }
+
+
+def validate(
+    document: dict[str, Any],
+    root: Path,
+    allow_shared_source: bool = False,
+    action_manifest: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    base = AC.validate_frame_geometry(document, root)
+    errors = list(base.get("errors", []))
+    warnings = list(base.get("warnings", []))
+    frames = document.get("frames") if isinstance(document.get("frames"), list) else []
+    canvas = document.get("canvas") if isinstance(document.get("canvas"), dict) else {}
+    canvas_width = int(canvas.get("width", 0) or 0)
+    canvas_height = int(canvas.get("height", 0) or 0)
+
+    measurements_by_id = {
+        str(item.get("frame_id")): item
+        for item in base.get("metrics", {}).get("measurements", [])
+        if isinstance(item, dict)
+    }
+
+    seen_images: dict[str, int] = {}
+    for index, frame in enumerate(frames):
+        if not isinstance(frame, dict):
+            continue
+        prefix = f"frames[{index}]"
+        image_value = str(frame.get("image", ""))
+        if image_value:
+            if image_value in seen_images and not allow_shared_source:
+                errors.append(
+                    _error(
+                        "shared_source_image",
+                        f"generated source frame reuses image {image_value!r}; use one isolated image per source frame",
+                        f"{prefix}.image",
+                    )
+                )
+            seen_images[image_value] = index
+
+        rect = frame.get("rect") if isinstance(frame.get("rect"), dict) else None
+        if rect and canvas_width > 0 and canvas_height > 0 and not allow_shared_source:
+            expected = {"x": 0, "y": 0, "width": canvas_width, "height": canvas_height}
+            try:
+                actual = _normalise_rect(rect)
+            except (KeyError, TypeError, ValueError):
+                actual = {}
+            if actual != expected:
+                errors.append(
+                    _error(
+                        "non_isolated_source",
+                        f"generated source frame rect must own the full {canvas_width}x{canvas_height} canvas before atlas packing",
+                        f"{prefix}.rect",
+                    )
+                )
+
+        frame_id = str(frame.get("frame_id", ""))
+        measurement = measurements_by_id.get(frame_id)
+        safe_rect_value = frame.get("safe_rect") if isinstance(frame.get("safe_rect"), dict) else None
+        if measurement and safe_rect_value:
+            try:
+                safe_rect = _normalise_rect(safe_rect_value)
+                bbox = _normalise_rect(measurement["alpha_bbox"])
+                margin = int(frame.get("bleed_margin_px", 0) or 0)
+                guarded = _shrink(safe_rect, margin)
+            except (KeyError, TypeError, ValueError):
+                guarded = None
+                bbox = None
+            if guarded is None:
+                errors.append(
+                    _error(
+                        "invalid_guard_band",
+                        "safe_rect is too small for the declared bleed_margin_px",
+                        f"{prefix}.bleed_margin_px",
+                    )
+                )
+            elif bbox is not None and not _contains(guarded, bbox):
+                errors.append(
+                    _error(
+                        "guard_band_violation",
+                        f"measured alpha bbox {bbox} leaves less than {frame.get('bleed_margin_px', 0)}px inside safe_rect {safe_rect}",
+                        f"{prefix}.safe_rect",
+                    )
+                )
+
+    action_result = None
+    if action_manifest is not None:
+        action_result = AS.validate_manifest(action_manifest, root)
+        errors.extend(action_result.get("errors", []))
+        warnings.extend(action_result.get("warnings", []))
+
+    remaining_warnings: list[dict[str, Any]] = []
+    for item in warnings:
+        if isinstance(item, dict) and item.get("code") == "bbox_drift":
+            promoted = dict(item)
+            promoted["severity"] = "error"
+            promoted["message"] = f"{promoted.get('message', 'bbox drift exceeds tolerance')}; generated frame scale drift blocks preflight"
+            errors.append(promoted)
+        else:
+            remaining_warnings.append(item)
+
+    return {
+        "contract": "generated_frame_set_preflight",
+        "ready": not errors,
+        "errors": errors,
+        "warnings": remaining_warnings,
+        "metrics": {
+            **base.get("metrics", {}),
+            "isolated_source_required": not allow_shared_source,
+            "unique_source_images": len(seen_images),
+            "action_manifest": action_result.get("metrics") if action_result else None,
+        },
+        "approval": False,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--input", required=True, help="frame-geometry contract JSON")
+    parser.add_argument("--root", default=".", help="root used to resolve frame paths")
+    parser.add_argument("--allow-shared-source", action="store_true", help="for imported/shared canvases only; not recommended for generated source frames")
+    parser.add_argument("--action-manifest", help="action-sequence manifest; validates frame envelopes and action separation")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    try:
+        document = json.loads(Path(args.input).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        result = {
+            "contract": "generated_frame_set_preflight",
+            "ready": False,
+            "errors": [_error("invalid_input", str(exc), args.input)],
+            "warnings": [],
+            "metrics": {},
+            "approval": False,
+        }
+    else:
+        if not isinstance(document, dict):
+            result = {
+                "contract": "generated_frame_set_preflight",
+                "ready": False,
+                "errors": [_error("invalid_input", "contract root must be an object", args.input)],
+                "warnings": [],
+                "metrics": {},
+                "approval": False,
+            }
+        else:
+            action_manifest = None
+            if args.action_manifest:
+                try:
+                    action_manifest = json.loads(Path(args.action_manifest).read_text(encoding="utf-8"))
+                except (OSError, json.JSONDecodeError) as exc:
+                    result = {
+                        "contract": "generated_frame_set_preflight",
+                        "ready": False,
+                        "errors": [_error("invalid_action_manifest", str(exc), args.action_manifest)],
+                        "warnings": [],
+                        "metrics": {},
+                        "approval": False,
+                    }
+                    action_manifest = None
+                if action_manifest is not None and not isinstance(action_manifest, dict):
+                    result = {
+                        "contract": "generated_frame_set_preflight",
+                        "ready": False,
+                        "errors": [_error("invalid_action_manifest", "action manifest root must be an object", args.action_manifest)],
+                        "warnings": [],
+                        "metrics": {},
+                        "approval": False,
+                    }
+                    action_manifest = None
+            if action_manifest is not None or not args.action_manifest:
+                result = validate(document, Path(args.root).resolve(), args.allow_shared_source, action_manifest)
+
+    if args.as_json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(f"generated frame-set preflight: {'PASS' if result['ready'] else 'FAIL'}")
+        for item in result.get("errors", []):
+            print(f"ERROR {item.get('code')}: {item.get('message')}")
+        for item in result.get("warnings", []):
+            print(f"WARN  {item.get('code')}: {item.get('message')}")
+    return 0 if result["ready"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/package-consumer-smoke.mjs

@@ -69,6 +69,26 @@ try {
   if (!fs.existsSync(path.join(installedRoot, "dev-lab", "public", "scenes", scene, "browser-review.json"))) {
     throw new Error("installed Dev Lab did not prepare the consumer scene");
   }
+  const requestSource = path.join(installedRoot, "examples", "agent-consumer", "asset-planning", "pixellab-hero-256x448-request.json");
+  const requestCopy = path.join(consumer, "asset-generation-request.json");
+  const registryCopy = path.join(consumer, "artifact-adapter-registry.json");
+  fs.copyFileSync(requestSource, requestCopy);
+  fs.copyFileSync(path.join(installedRoot, "artifact-adapter-registry.json"), registryCopy);
+  const plan = JSON.parse(run(bin, ["asset-generation-plan", "plan", "--request", requestCopy, "--registry", registryCopy, "--project-root", consumer.toString(), "--json"], { cwd: consumer }));
+  if (plan.contract !== "motionloom-asset-generation-plan" || plan.schema_version !== "0.2" || plan.producer !== "MotionLoom" || plan.approval !== false) throw new Error("installed planner contract failed");
+  if (!Array.isArray(plan.recommendations) || plan.recommendations.length === 0) throw new Error("installed planner returned no normal-planning recommendations");
+  if (!plan.recommendations.some((item) => item.recommendation_status === "recommended" && item.execution_status === "provisional")) throw new Error("installed planner lost provisional recommendation/execution separation");
+  if (!plan.agent_guidance || plan.agent_guidance.recommended_by !== "MotionLoom") throw new Error("installed planner omitted MotionLoom agent guidance");
+  const humanPlan = run(bin, ["asset-generation-plan", "plan", "--request", requestCopy, "--registry", registryCopy, "--project-root", consumer.toString()], { cwd: consumer });
+  if (!humanPlan.includes("MotionLoom Project Assessment") || !humanPlan.includes("MotionLoom Recommendations")) throw new Error("installed planner human output lost MotionLoom identity");
+
+  const sourceImage = path.join(installedRoot, "examples", "agent-consumer", "asset-consistency", "assets", "hero-frame-00.png");
+  const adaptedImage = path.join(consumer, "adapted-frame.png");
+  const adaptationReport = path.join(consumer, "adaptation-report.json");
+  const adaptation = JSON.parse(run(bin, ["asset-adapt", "pad", "--input", sourceImage, "--output", adaptedImage, "--width", "256", "--height", "448", "--anchor", "footline", "--report", adaptationReport, "--json"], { cwd: consumer }));
+  if (adaptation.contract !== "motionloom-asset-adaptation" || adaptation.approval !== false || adaptation.output.canvas[0] !== 256 || adaptation.output.canvas[1] !== 448) throw new Error("installed Node asset-adapt contract failed");
+  if (!fs.existsSync(adaptedImage) || !fs.existsSync(adaptationReport)) throw new Error("installed asset-adapt omitted output/report");
+
   run(process.execPath, ["--input-type=module", "-e", "await import('playwright'); await import('vite');"], { cwd: consumer });
   console.log(JSON.stringify({ status: "pass", project_root: init.project_root, installed_root: installedRoot }, null, 2));
 } finally {

package/scripts/quality-gate.py

@@ -19,6 +19,7 @@ ROOT = Path(__file__).resolve().parents[1]
 SAFE_SCENE = re.compile(r"^[A-Za-z0-9._-]+$")
 sys.path.insert(0, str(ROOT / "scripts"))
 from intelligence import validate_task_benchmark, validate_task_intelligence, validate_task_p1  # noqa: E402
+from browser_review_consistency import candidate_consistency_errors  # noqa: E402
 sys.path.insert(0, str(ROOT / "src"))
 from core.spec import validate_spec  # noqa: E402
 
@@ -321,6 +322,12 @@ def validate_scene(scene_dir: Path, context_path: Path, require_review: bool = F
                     issues.append("browser review candidate scene mismatch")
                 if task_dir:
                     task = _json(task_dir / "task.json")
+                    issues.extend(candidate_consistency_errors(
+                        scene_dir / "browser-review.json",
+                        task_dir / "browser-review.json",
+                        expected_task_id=task.get("task_id"),
+                        expected_scene=scene_dir.name,
+                    ))
                     if candidate.get("task_id") != task.get("task_id"):
                         issues.append("browser review candidate task_id mismatch")
                 if candidate.get("source_sha256") != source_sha:

package/scripts/release-verify.py

@@ -20,6 +20,7 @@ def main() -> int:
     parser.add_argument("--changelog", default=str(ROOT / "CHANGELOG.md"))
     parser.add_argument("--release-note", default="")
     parser.add_argument("--tag", default="", help="Optional Git tag; accepts v<version> or <version>")
+    parser.add_argument("--capability-registry", default=str(ROOT / "capability-registry.json"))
     args = parser.parse_args()
 
     errors: list[str] = []
@@ -43,6 +44,30 @@ def main() -> int:
     if args.tag and args.tag.removeprefix("v") != expected:
         errors.append(f"tag {args.tag!r} does not match version {expected!r}")
 
+    registry_path = Path(args.capability_registry).resolve()
+    try:
+        registry = json.loads(registry_path.read_text(encoding="utf-8"))
+        expected_registry_id = f"registry-{package.get('name', 'motionloom')}-{expected}"
+        if registry.get("registry_id") != expected_registry_id:
+            errors.append(
+                f"capability registry id {registry.get('registry_id')!r} does not match {expected_registry_id!r}"
+            )
+        capabilities = registry.get("capabilities")
+        if not isinstance(capabilities, list) or not capabilities:
+            errors.append("capability registry must contain a non-empty capabilities array")
+        else:
+            mismatched = [
+                str(item.get("id", "<unknown>"))
+                for item in capabilities
+                if item.get("adapter_version") != expected
+            ]
+            if mismatched:
+                errors.append(
+                    "capability registry adapter_version mismatch: " + ", ".join(mismatched)
+                )
+    except (OSError, json.JSONDecodeError, AttributeError) as exc:
+        errors.append(f"capability registry is invalid: {exc}")
+
     report = {"status": "fail" if errors else "pass", "version": actual, "expected_version": expected, "errors": errors}
     print(json.dumps(report, indent=2))
     return 1 if errors else 0

package/scripts/report-contract.py

@@ -91,7 +91,7 @@ def main() -> int:
         passing: list[Path] = []
         for task_dir in complete:
             result = subprocess.run(
-                [sys.executable, str(report_script), "check", "--task-dir", str(task_dir)],
+                [sys.executable, str(report_script), "check", "--task-dir", str(task_dir), "--root", str(root)],
                 cwd=root,
                 capture_output=True,
                 text=True,

package/scripts/report.py

@@ -12,8 +12,11 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+from browser_review_consistency import candidate_consistency_errors
 
-ROOT = Path(__file__).resolve().parents[1]
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+ROOT = PACKAGE_ROOT
 EVIDENCE_ARTIFACTS = (
     "semantic-lint-benchmark.json",
     "evidence-verifier-report.json",
@@ -56,7 +59,7 @@ def project_memory_path() -> Path:
 
 
 def asset_provenance_module():
-    path = ROOT / "scripts" / "asset-provenance.py"
+    path = PACKAGE_ROOT / "scripts" / "asset-provenance.py"
     loader = importlib.util.spec_from_file_location("motionloom_asset_provenance", path)
     module = importlib.util.module_from_spec(loader)
     loader.loader.exec_module(module)
@@ -64,7 +67,7 @@ def asset_provenance_module():
 
 
 def asset_consistency_module():
-    path = ROOT / "scripts" / "asset-consistency.py"
+    path = PACKAGE_ROOT / "scripts" / "asset-consistency.py"
     loader = importlib.util.spec_from_file_location("motionloom_asset_consistency", path)
     module = importlib.util.module_from_spec(loader)
     sys.modules[loader.name] = module
@@ -73,7 +76,7 @@ def asset_consistency_module():
 
 
 def artifact_intake_module():
-    path = ROOT / "scripts" / "artifact-intake.py"
+    path = PACKAGE_ROOT / "scripts" / "artifact-intake.py"
     loader = importlib.util.spec_from_file_location("motionloom_artifact_intake", path)
     module = importlib.util.module_from_spec(loader)
     sys.modules[loader.name] = module
@@ -450,6 +453,14 @@ def approval_contract_errors(task_dir: Path, task: dict, require_current: bool)
         return ["ready-for-PR task requires review.json"]
     if candidate.get("task_id") != task.get("task_id"):
         errors.append("browser-review candidate task_id does not match task.json")
+    scene_candidate_path = ROOT / "src" / "output" / str(task.get("scene", "")) / "browser-review.json"
+    if scene_candidate_path.is_file():
+        errors.extend(candidate_consistency_errors(
+            scene_candidate_path,
+            candidate_path,
+            expected_task_id=task.get("task_id"),
+            expected_scene=task.get("scene"),
+        ))
     if candidate.get("scene") != task.get("scene"):
         errors.append("browser-review candidate scene does not match task.json")
     task_review = task.get("browser_review") or {}
@@ -717,6 +728,7 @@ def render(args: argparse.Namespace) -> int:
 
 
 def main() -> int:
+    global ROOT
     parser = argparse.ArgumentParser(description=__doc__)
     sub = parser.add_subparsers(dest="command", required=True)
     init = sub.add_parser("init")
@@ -772,8 +784,11 @@ def main() -> int:
     structure_parser.set_defaults(func=record_structure)
     check_parser = sub.add_parser("check", help="Validate semantic completeness of a task bundle")
     check_parser.add_argument("--task-dir", required=True)
+    check_parser.add_argument("--root", default=str(ROOT), help="Repository root containing the canonical scene artifacts")
     check_parser.set_defaults(func=check_report)
     args = parser.parse_args()
+    if hasattr(args, "root"):
+        ROOT = Path(args.root).expanduser().resolve()
     return args.func(args)
 
 

package/scripts/resolve-task-bundle.py

@@ -4,7 +4,7 @@
 The resolver intentionally does not infer a task path from a scene slug. A
 bundle is eligible only when its direct ``artifacts/<task-id>/task.json``
 declares the requested scene and remains inside the repository artifacts root.
-Multiple matching bundles are rejected rather than ranked implicitly.
+Multiple matching bundles are rejected rather than ranked implicitly. A task bundle with a browser-review candidate that conflicts with the canonical scene candidate is not eligible; the later quality/review gates still report that divergence when the bundle is checked directly.
 """
 
 from __future__ import annotations
@@ -44,6 +44,7 @@ def resolve_task_dirs(root: Path, scene: str) -> list[Path]:
     if not artifacts.is_dir() or artifacts.is_symlink():
         return []
     resolved_artifacts = artifacts.resolve()
+    scene_candidate = read_json(root / "src" / "output" / scene / "browser-review.json")
     matches: list[Path] = []
     for task_path in sorted(artifacts.glob("*/task.json")):
         if has_symlink_component(task_path, root):
@@ -53,8 +54,15 @@ def resolve_task_dirs(root: Path, scene: str) -> list[Path]:
                 continue
         except (OSError, RuntimeError):
             continue
-        if read_json(task_path).get("scene") == scene:
-            matches.append(task_path.parent)
+        task = read_json(task_path)
+        if task.get("scene") != scene:
+            continue
+        task_candidate = read_json(task_path.parent / "browser-review.json")
+        if scene_candidate and task_candidate:
+            identity_fields = ("candidate_id", "task_id", "scene", "source_sha256", "context_sha256", "expires_at")
+            if any(scene_candidate.get(field) != task_candidate.get(field) for field in identity_fields):
+                continue
+        matches.append(task_path.parent)
     return matches
 
 

package/scripts/review-hook.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import argparse
 import hashlib
+import os
 import json
 import re
 import shutil
@@ -14,6 +15,12 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from urllib.parse import urlencode, urlsplit, urlunsplit
 
+try:
+    from browser_review_consistency import candidate_consistency_errors
+except ModuleNotFoundError:  # Support importlib-based contract tests.
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from browser_review_consistency import candidate_consistency_errors
+
 ROOT = Path(__file__).resolve().parents[1]
 SAFE_SCENE = re.compile(r"^[A-Za-z0-9._-]+$")
 SAFE_ANIMATION = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
@@ -182,6 +189,20 @@ def runtime_bundle(scene_dir: Path) -> dict | None:
     review_policy = descriptor.get("review_policy")
     if not isinstance(review_policy, dict) or not isinstance(review_policy.get("require_all_animations"), bool):
         raise ValueError("devlab-runtime.json review_policy.require_all_animations must be boolean")
+    action_separation = descriptor.get("action_separation")
+    if action_separation is not None:
+        if not isinstance(action_separation, dict):
+            raise ValueError("devlab-runtime.json action_separation must be an object")
+        if action_separation.get("status") not in {"pass", "quarantined"}:
+            raise ValueError("devlab-runtime.json action_separation.status must be pass or quarantined")
+        if not isinstance(action_separation.get("action_id"), str) or not SAFE_ANIMATION.fullmatch(action_separation["action_id"]):
+            raise ValueError("devlab-runtime.json action_separation.action_id is invalid")
+        frame_count = action_separation.get("frame_count")
+        passing_count = action_separation.get("passing_frame_count")
+        if not isinstance(frame_count, int) or frame_count < 1 or not isinstance(passing_count, int) or passing_count < 0 or passing_count > frame_count:
+            raise ValueError("devlab-runtime.json action_separation frame counts are invalid")
+        if not isinstance(action_separation.get("forbidden_action_ids"), list):
+            raise ValueError("devlab-runtime.json action_separation.forbidden_action_ids must be an array")
 
     digest = hashlib.sha256()
     digest.update(b"motionloom-devlab-runtime-v1\0")
@@ -198,6 +219,7 @@ def runtime_bundle(scene_dir: Path) -> dict | None:
         "mode": mode,
         "files": sorted(resolved_files),
         "review_policy": {"require_all_animations": review_policy["require_all_animations"]},
+        "action_separation": action_separation,
     }
 
 
@@ -215,6 +237,7 @@ def runtime_review_payload(bundle: dict | None) -> dict:
         "bundle_sha256": bundle["bundle_sha256"],
         "animations": bundle["animations"],
         "review_policy": bundle["review_policy"],
+        "action_separation": bundle.get("action_separation"),
     }
 
 
@@ -334,8 +357,24 @@ def prepare(args: argparse.Namespace) -> int:
         )),
     })
     handoff_path.write_text(json.dumps(handoff, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    subprocess.run([sys.executable, str(ROOT / "scripts/devlab.py"), scene, "--prepare-only", "--task-dir", 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)
+    project_env = os.environ.copy()
+    project_env["MOTIONLOOM_PROJECT_ROOT"] = str(ROOT)
+    subprocess.run(
+        [sys.executable, str(ROOT / "scripts/devlab.py"), scene, "--prepare-only", "--task-dir", str(task_dir)],
+        check=True,
+        capture_output=True,
+        text=True,
+        cwd=ROOT,
+        env=project_env,
+    )
+    subprocess.run(
+        [sys.executable, str(ROOT / "scripts/report.py"), "collect", "--task-dir", str(task_dir)],
+        check=True,
+        capture_output=True,
+        text=True,
+        cwd=ROOT,
+        env=project_env,
+    )
     print(json.dumps({
         "status": "review_required",
         "task_id": task["task_id"],
@@ -363,6 +402,12 @@ def validate(args: argparse.Namespace) -> int:
         bundle["bundle_sha256"] if bundle else None,
     )
     errors = []
+    errors.extend(candidate_consistency_errors(
+        scene_dir / "browser-review.json",
+        task_dir / "browser-review.json",
+        expected_task_id=task.get("task_id"),
+        expected_scene=task.get("scene"),
+    ))
     if not candidate.get("expires_at"):
         errors.append("browser-review candidate has no expiry")
     else:
@@ -446,17 +491,21 @@ def validate(args: argparse.Namespace) -> int:
 
 
 def main() -> int:
+    global ROOT
     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("--root", default=str(ROOT), help="Repository root containing the canonical scene artifacts")
     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("--root", default=str(ROOT), help="Repository root containing the canonical scene artifacts")
     v.add_argument("--require-approved", action="store_true")
     v.set_defaults(func=validate)
     args = parser.parse_args()
+    ROOT = Path(args.root).expanduser().resolve()
     try:
         return args.func(args)
     except (KeyError, FileNotFoundError, json.JSONDecodeError, ValueError, subprocess.CalledProcessError) as exc:

package/scripts/skill-doctor.py

@@ -7,6 +7,7 @@ import argparse
 import importlib.util
 import json
 import re
+import subprocess
 import sys
 from pathlib import Path
 
@@ -71,9 +72,35 @@ def parse_frontmatter(text: str) -> dict[str, str] | None:
     return values
 
 
+def chromium_executable() -> tuple[Path | None, str | None]:
+    probe = (
+        "import { chromium } from 'playwright'; "
+        "process.stdout.write(chromium.executablePath());"
+    )
+    try:
+        result = subprocess.run(
+            ["node", "--input-type=module", "--eval", probe],
+            cwd=ROOT,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return None, str(exc)
+    if result.returncode != 0:
+        return None, (result.stderr or result.stdout).strip() or "Playwright import failed"
+    path = Path(result.stdout.strip())
+    return (path if path else None), None
+
+
 def run() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--json", action="store_true", dest="as_json")
+    parser.add_argument(
+        "--runtime",
+        action="store_true",
+        help="also verify that the Playwright Chromium executable is installed",
+    )
     args = parser.parse_args()
     errors: list[dict] = []
     warnings: list[dict] = []
@@ -156,6 +183,21 @@ def run() -> int:
     except (FileNotFoundError, json.JSONDecodeError) as exc:
         errors.append({"code": "invalid_package_json", "message": str(exc)})
 
+    if args.runtime:
+        chromium_path, chromium_error = chromium_executable()
+        chromium_ready = chromium_path is not None and chromium_path.is_file()
+        checks.append({
+            "id": "runtime:chromium",
+            "status": "pass" if chromium_ready else "fail",
+            "path": str(chromium_path) if chromium_path else None,
+        })
+        if not chromium_ready:
+            detail = chromium_error or f"Chromium executable is missing: {chromium_path}"
+            errors.append({
+                "code": "missing_browser_executable",
+                "message": f"Playwright Chromium is unavailable ({detail}); run `npx playwright install chromium`.",
+            })
+
     cryptography_available = importlib.util.find_spec("cryptography") is not None
     checks.append({"id": "python-dependency:cryptography", "status": "pass" if cryptography_available else "fail"})
     if not cryptography_available: