motionloom 2.2.0 → 2.4.0

package/scripts/isolate-alpha-background.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Deterministically isolate a high-contrast, edge-connected flat background.
+
+This is a narrow recovery utility for generated PNGs where an image provider
+painted a dark background despite a transparency request. It flood-fills only
+edge-connected pixels within a stated RGB-distance of an observed edge color.
+It does not claim the input was provider-native alpha, alter provenance, or
+approve an asset. Review the JSON report before using the result in a bundle.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib.util
+import json
+import struct
+import sys
+import zlib
+from collections import deque
+from pathlib import Path
+from statistics import median
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+
+def digest(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def load_png_reader() -> Any:
+    source = ROOT / "scripts" / "asset-consistency.py"
+    spec = importlib.util.spec_from_file_location("motionloom_alpha_isolation_png", source)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"could not load PNG reader: {source}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module.PNGImage
+
+
+def median_edge_color(pixels: list[tuple[int, int, int, int]], width: int, height: int) -> tuple[int, int, int]:
+    indices = set(range(width)) | {width * (height - 1) + x for x in range(width)}
+    indices.update(y * width for y in range(height))
+    indices.update(y * width + width - 1 for y in range(height))
+    values = [pixels[index] for index in sorted(indices)]
+    return tuple(int(median([pixel[channel] for pixel in values])) for channel in range(3))
+
+
+def distance(pixel: tuple[int, int, int, int], color: tuple[int, int, int]) -> int:
+    return sum(abs(pixel[index] - color[index]) for index in range(3))
+
+
+def isolate(pixels: list[tuple[int, int, int, int]], width: int, height: int, background: tuple[int, int, int], tolerance: int) -> set[int]:
+    def matches(index: int) -> bool:
+        return pixels[index][3] > 0 and distance(pixels[index], background) <= tolerance
+    edges = set(range(width)) | {width * (height - 1) + x for x in range(width)}
+    edges.update(y * width for y in range(height))
+    edges.update(y * width + width - 1 for y in range(height))
+    queue = deque(index for index in edges if matches(index))
+    visited = set(queue)
+    while queue:
+        index = queue.popleft()
+        x, y = index % width, index // width
+        for neighbour in (index - 1 if x else None, index + 1 if x + 1 < width else None, index - width if y else None, index + width if y + 1 < height else None):
+            if neighbour is not None and neighbour not in visited and matches(neighbour):
+                visited.add(neighbour)
+                queue.append(neighbour)
+    return visited
+
+
+def png_rgba(width: int, height: int, pixels: list[tuple[int, int, int, int]]) -> bytes:
+    raw = bytearray()
+    for y in range(height):
+        raw.append(0)
+        for pixel in pixels[y * width : (y + 1) * width]:
+            raw.extend(pixel)
+    def chunk(kind: bytes, content: bytes) -> bytes:
+        return struct.pack(">I", len(content)) + kind + content + struct.pack(">I", zlib.crc32(kind + content) & 0xFFFFFFFF)
+    return PNG_SIGNATURE + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0)) + chunk(b"IDAT", zlib.compress(bytes(raw), level=9)) + chunk(b"IEND", b"")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Flood-fill a flat edge-connected background into alpha=0")
+    parser.add_argument("input", type=Path)
+    parser.add_argument("output", type=Path)
+    parser.add_argument("--report", type=Path, help="Optional JSON evidence report")
+    parser.add_argument("--tolerance", type=int, default=24, help="Manhattan RGB distance from edge background; 0-765")
+    parser.add_argument("--allow-edge-foreground", action="store_true", help="Permit opaque pixels on the canvas edge; only use for intentionally edge-cropped art")
+    args = parser.parse_args(argv)
+    if not 0 <= args.tolerance <= 765:
+        raise SystemExit("--tolerance must be in 0..765")
+    if not args.input.is_file():
+        raise SystemExit(f"input is missing: {args.input}")
+    if args.output.resolve() == args.input.resolve():
+        raise SystemExit("output must differ from input")
+    PNGImage = load_png_reader()
+    image = PNGImage(args.input)
+    pixels = image.rgba()
+    background = median_edge_color(pixels, image.width, image.height)
+    removed = isolate(pixels, image.width, image.height, background, args.tolerance)
+    if not removed:
+        raise SystemExit("no edge-connected background pixels matched; do not use a larger tolerance without visual review")
+    output_pixels = [(r, g, b, 0 if index in removed else a) for index, (r, g, b, a) in enumerate(pixels)]
+    foreground = sum(1 for _, _, _, alpha in output_pixels if alpha > 0)
+    if foreground == 0:
+        raise SystemExit("isolation would remove all pixels; lower tolerance or provide a different source")
+    edge_indices = set(range(image.width)) | {image.width * (image.height - 1) + x for x in range(image.width)}
+    edge_indices.update(y * image.width for y in range(image.height))
+    edge_indices.update(y * image.width + image.width - 1 for y in range(image.height))
+    residual_edge_pixels = sum(1 for index in edge_indices if output_pixels[index][3] > 0)
+    if residual_edge_pixels and not args.allow_edge_foreground:
+        raise SystemExit(
+            f"{residual_edge_pixels} opaque pixel(s) remain at the canvas edge after isolation; "
+            "this is likely residual background contamination. Use a cleaner source, or explicitly review and pass --allow-edge-foreground for intentionally cropped art."
+        )
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_bytes(png_rgba(image.width, image.height, output_pixels))
+    report = {
+        "contract": "alpha-isolation-report",
+        "mode": "edge_connected_flat_background",
+        "input": str(args.input),
+        "input_sha256": digest(args.input),
+        "output": str(args.output),
+        "output_sha256": digest(args.output),
+        "canvas": {"width": image.width, "height": image.height},
+        "observed_edge_background_rgb": list(background),
+        "tolerance": args.tolerance,
+        "removed_pixels": len(removed),
+        "foreground_alpha_pixels": foreground,
+        "residual_edge_foreground_pixels": residual_edge_pixels,
+        "edge_foreground_allowed": args.allow_edge_foreground,
+        "human_review_required": True,
+        "production_approved": False,
+    }
+    if args.report:
+        args.report.parent.mkdir(parents=True, exist_ok=True)
+        args.report.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(json.dumps(report, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/pr.py

@@ -95,6 +95,7 @@ def main() -> int:
         "--task-dir", str(task_dir),
         "--require-browser-review",
         "--require-visual-truth",
+        "--require-asset-provenance",
     ]
     print("== running context-bound quality gate ==")
     run(repo, [python, *quality_args])
@@ -121,6 +122,7 @@ def main() -> int:
         f"- snapshot frames: 0/50/100% in src/output/{args.scene}/snapshot/\n"
         "- context-bound quality gate: passed\n"
         f"- brand tokens bound from {args.context or 'project-context.json'}"
+        "\n- asset provenance: production_eligible (human approval remains separate)"
     )
     run(repo, ["git", "commit", "-m", commit_message])
 

package/scripts/quality-gate.py

@@ -55,6 +55,32 @@ def _load_visual_truth():
     return module
 
 
+def _load_asset_provenance():
+    path = ROOT / "scripts" / "asset-provenance.py"
+    loader = importlib.util.spec_from_file_location("asset_provenance", path)
+    module = importlib.util.module_from_spec(loader)
+    loader.loader.exec_module(module)
+    return module
+
+
+def _load_asset_consistency():
+    path = ROOT / "scripts" / "asset-consistency.py"
+    loader = importlib.util.spec_from_file_location("asset_consistency", path)
+    module = importlib.util.module_from_spec(loader)
+    sys.modules[loader.name] = module
+    loader.loader.exec_module(module)
+    return module
+
+
+def _load_artifact_intake():
+    path = ROOT / "scripts" / "artifact-intake.py"
+    loader = importlib.util.spec_from_file_location("artifact_intake", path)
+    module = importlib.util.module_from_spec(loader)
+    sys.modules[loader.name] = module
+    loader.loader.exec_module(module)
+    return module
+
+
 def _json(path: Path):
     try:
         return json.loads(path.read_text(encoding="utf-8"))
@@ -74,7 +100,7 @@ def _telemetry_bundle_sha256(task_dir: Path) -> str:
     return hashlib.sha256(json.dumps(entries, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest()
 
 
-def validate_scene(scene_dir: Path, context_path: Path, require_review: bool = False, task_dir: Path | None = None, require_intelligence: bool = False, require_p1: bool = False, require_benchmark: bool = False, require_telemetry: bool = False, require_attestation: bool = False, attestation_path: Path | None = None, trust_policy_path: Path | None = None, require_visual_truth: bool = False) -> list[str]:
+def validate_scene(scene_dir: Path, context_path: Path, require_review: bool = False, task_dir: Path | None = None, require_intelligence: bool = False, require_p1: bool = False, require_benchmark: bool = False, require_telemetry: bool = False, require_attestation: bool = False, attestation_path: Path | None = None, trust_policy_path: Path | None = None, require_visual_truth: bool = False, require_asset_provenance: bool = False, asset_provenance_path: Path | None = None, require_asset_consistency: bool = False, asset_consistency_path: Path | None = None, require_artifact_intake: bool = False) -> list[str]:
     issues = []
     manifest_path = scene_dir / "manifest.json"
     spec_path = scene_dir / "motion-spec.json"
@@ -108,6 +134,88 @@ def validate_scene(scene_dir: Path, context_path: Path, require_review: bool = F
     if not (spec.get("accessibility") or {}).get("reduced_motion"):
         issues.append("motion spec has no reduced-motion policy")
 
+    asset_provenance_name = manifest.get("asset_provenance")
+    if require_asset_provenance and not isinstance(asset_provenance_name, str):
+        issues.append("asset provenance gate requires manifest.asset_provenance")
+    if asset_provenance_name or asset_provenance_path:
+        resolved_asset_provenance = asset_provenance_path or (scene_dir / str(asset_provenance_name)).resolve()
+        if scene_dir.resolve() not in resolved_asset_provenance.parents or not resolved_asset_provenance.is_file():
+            issues.append("manifest.asset_provenance must point to an existing file inside the scene directory")
+        else:
+            try:
+                asset_module = _load_asset_provenance()
+                asset_result = asset_module.evaluate(
+                    resolved_asset_provenance,
+                    base=scene_dir,
+                    mode="production" if require_asset_provenance else "runtime",
+                    manifest=manifest,
+                )
+                issues.extend(f"asset provenance: {issue}" for issue in asset_result.get("errors", []))
+                if require_asset_provenance and not asset_result.get("summary", {}).get("production_eligible"):
+                    issues.append("asset provenance is not production_eligible; human approval remains separate")
+            except (OSError, ValueError, AttributeError) as exc:
+                issues.append(f"asset provenance contract: {exc}")
+
+    consistency_name = manifest.get("consistency_ref")
+    if require_asset_consistency and not isinstance(consistency_name, str) and asset_consistency_path is None:
+        issues.append("asset consistency gate requires manifest.consistency_ref")
+    if consistency_name or asset_consistency_path:
+        resolved_consistency = asset_consistency_path or (scene_dir / str(consistency_name)).resolve()
+        if scene_dir.resolve() not in resolved_consistency.parents or not resolved_consistency.is_file():
+            issues.append("manifest.consistency_ref must point to an existing file inside the scene directory")
+        else:
+            try:
+                consistency_kind = manifest.get("consistency_kind", "frame-geometry")
+                consistency_module = _load_asset_consistency()
+                consistency_document = _json(resolved_consistency)
+                consistency_result = consistency_module.run(
+                    consistency_kind,
+                    consistency_document,
+                    scene_dir,
+                    strict=require_asset_consistency,
+                )
+                issues.extend(
+                    f"asset consistency: {item.get('code', 'issue')} — {item.get('message', 'contract violation')}"
+                    for item in consistency_result.get("errors", [])
+                )
+                if require_asset_consistency and not consistency_result.get("ready"):
+                    issues.append("asset consistency contract is not ready")
+            except (OSError, ValueError, AttributeError, KeyError, TypeError) as exc:
+                issues.append(f"asset consistency contract: {exc}")
+
+    intake = manifest.get("artifact_intake")
+    if require_artifact_intake and not isinstance(intake, dict):
+        issues.append("artifact intake gate requires manifest.artifact_intake")
+    if intake is not None:
+        required_intake_keys = ("registry", "receipt", "controls", "export_manifest")
+        if not isinstance(intake, dict) or any(not isinstance(intake.get(key), str) for key in required_intake_keys):
+            issues.append("manifest.artifact_intake requires registry, receipt, controls and export_manifest relative paths")
+        else:
+            resolved_intake = {key: (scene_dir / intake[key]).resolve() for key in required_intake_keys}
+            if any(scene_dir.resolve() not in path.parents or not path.is_file() for path in resolved_intake.values()):
+                issues.append("manifest.artifact_intake paths must point to existing files inside the scene directory")
+            else:
+                try:
+                    intake_module = _load_artifact_intake()
+                    intake_result = intake_module.evaluate_bundle(
+                        argparse.Namespace(
+                            root=scene_dir,
+                            registry=resolved_intake["registry"],
+                            receipt=resolved_intake["receipt"],
+                            controls=resolved_intake["controls"],
+                            export_manifest=resolved_intake["export_manifest"],
+                            strict=require_artifact_intake,
+                        )
+                    )
+                    issues.extend(
+                        f"artifact intake: {item.get('code', 'issue')} — {item.get('message', 'contract violation')}"
+                        for item in intake_result.get("errors", [])
+                    )
+                    if require_artifact_intake and not intake_result.get("ready"):
+                        issues.append("artifact intake contract is not runtime-ready")
+                except (OSError, ValueError, AttributeError, KeyError, TypeError) as exc:
+                    issues.append(f"artifact intake contract: {exc}")
+
     checks = manifest.get("checks")
     if not isinstance(checks, list) or not checks:
         issues.append("manifest.checks must contain the Dev Lab quality checklist")
@@ -382,6 +490,11 @@ def main() -> int:
     parser.add_argument("--require-telemetry", action="store_true")
     parser.add_argument("--require-attestation", action="store_true")
     parser.add_argument("--require-visual-truth", action="store_true")
+    parser.add_argument("--require-asset-provenance", action="store_true")
+    parser.add_argument("--asset-provenance")
+    parser.add_argument("--require-asset-consistency", action="store_true")
+    parser.add_argument("--asset-consistency")
+    parser.add_argument("--require-artifact-intake", action="store_true")
     parser.add_argument("--attestation")
     parser.add_argument("--trust-policy")
     args = parser.parse_args()
@@ -396,20 +509,31 @@ def main() -> int:
     task_dir = Path(args.task_dir).resolve() if args.task_dir else None
     attestation_path = Path(args.attestation).resolve() if args.attestation else None
     trust_policy_path = Path(args.trust_policy).resolve() if args.trust_policy else None
+    asset_provenance_path = Path(args.asset_provenance).resolve() if args.asset_provenance else None
+    asset_consistency_path = Path(args.asset_consistency).resolve() if args.asset_consistency else None
     scenes = [root / "src" / "output" / args.scene] if args.scene else sorted(p for p in output_root.iterdir() if p.is_dir()) if output_root.exists() else []
     if not scenes:
         print("QUALITY GATE: no scene outputs found")
         return 0
     failed = False
     for scene_dir in scenes:
-        issues = validate_scene(scene_dir, context, args.require_browser_review, task_dir, args.require_intelligence, args.require_p1, args.require_benchmark, args.require_telemetry, args.require_attestation, attestation_path, trust_policy_path, args.require_visual_truth)
+        issues = validate_scene(scene_dir, context, args.require_browser_review, task_dir, args.require_intelligence, args.require_p1, args.require_benchmark, args.require_telemetry, args.require_attestation, attestation_path, trust_policy_path, args.require_visual_truth, args.require_asset_provenance, asset_provenance_path, args.require_asset_consistency, asset_consistency_path, args.require_artifact_intake)
         if issues:
             failed = True
             print(f"REJECTED {scene_dir.name}:")
             for issue in issues:
                 print(f"  - {issue}")
         else:
-            suffix = " + visual-truth contract" if args.require_visual_truth else ""
+            suffixes = []
+            if args.require_visual_truth:
+                suffixes.append("visual-truth contract")
+            if args.require_asset_provenance:
+                suffixes.append("asset provenance production eligibility")
+            if args.require_asset_consistency:
+                suffixes.append("asset consistency contract")
+            if args.require_artifact_intake:
+                suffixes.append("runtime-ready artifact intake")
+            suffix = f" + {' + '.join(suffixes)}" if suffixes else ""
             print(f"ACCEPTED {scene_dir.name}: context + spec + runtime snapshots + browser-review candidate + checklist{suffix}")
     return 1 if failed else 0
 

package/scripts/report.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import argparse
 import hashlib
+import importlib.util
 import json
 import shutil
 import sys
@@ -54,6 +55,88 @@ def project_memory_path() -> Path:
     return ROOT / ".motionloom" / "project-memory.json"
 
 
+def asset_provenance_module():
+    path = 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)
+    return module
+
+
+def asset_consistency_module():
+    path = 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
+    loader.loader.exec_module(module)
+    return module
+
+
+def artifact_intake_module():
+    path = 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
+    loader.loader.exec_module(module)
+    return module
+
+
+def asset_provenance_result(scene_manifest_path: Path, scene_manifest: dict, mode: str = "runtime") -> dict:
+    name = scene_manifest.get("asset_provenance")
+    if not name:
+        return {"status": "not-run", "errors": ["scene manifest has no asset_provenance"]}
+    provenance_path = (scene_manifest_path.parent / str(name)).resolve()
+    if scene_manifest_path.parent.resolve() not in provenance_path.parents or not provenance_path.is_file():
+        return {"status": "fail", "errors": ["scene manifest asset_provenance points to a missing or unsafe artifact"]}
+    try:
+        return asset_provenance_module().evaluate(
+            provenance_path,
+            base=scene_manifest_path.parent,
+            mode=mode,
+            manifest=scene_manifest,
+        )
+    except (OSError, ValueError, AttributeError) as exc:
+        return {"status": "fail", "errors": [f"asset provenance contract: {exc}"]}
+
+
+def asset_consistency_result(scene_manifest_path: Path, scene_manifest: dict, strict: bool = False) -> dict:
+    name = scene_manifest.get("consistency_ref")
+    if not name:
+        return {"status": "not-run", "ready": False, "errors": []}
+    scene_dir = scene_manifest_path.parent.resolve()
+    consistency_path = (scene_dir / str(name)).resolve()
+    if scene_dir not in consistency_path.parents or not consistency_path.is_file():
+        return {"status": "fail", "ready": False, "errors": ["scene manifest consistency_ref points to a missing or unsafe artifact"]}
+    try:
+        document = read_json(consistency_path)
+        kind = scene_manifest.get("consistency_kind", "frame-geometry")
+        result = asset_consistency_module().run(kind, document, scene_dir, strict=strict)
+        result["status"] = "pass" if result.get("ready") else "fail"
+        return result
+    except (OSError, ValueError, AttributeError, KeyError, TypeError) as exc:
+        return {"status": "fail", "ready": False, "errors": [f"asset consistency contract: {exc}"]}
+
+
+def artifact_intake_result(scene_manifest_path: Path, scene_manifest: dict, strict: bool = False) -> dict:
+    intake = scene_manifest.get("artifact_intake")
+    if not intake:
+        return {"status": "not-run", "ready": False, "errors": []}
+    required = ("registry", "receipt", "controls", "export_manifest")
+    scene_dir = scene_manifest_path.parent.resolve()
+    if not isinstance(intake, dict) or any(not isinstance(intake.get(key), str) for key in required):
+        return {"status": "fail", "ready": False, "errors": ["scene manifest artifact_intake is incomplete"]}
+    paths = {key: (scene_dir / intake[key]).resolve() for key in required}
+    if any(scene_dir not in path.parents or not path.is_file() for path in paths.values()):
+        return {"status": "fail", "ready": False, "errors": ["scene manifest artifact_intake points to a missing or unsafe artifact"]}
+    try:
+        result = artifact_intake_module().evaluate_bundle(
+            argparse.Namespace(root=scene_dir, registry=paths["registry"], receipt=paths["receipt"], controls=paths["controls"], export_manifest=paths["export_manifest"], strict=strict)
+        )
+        return result
+    except (OSError, ValueError, AttributeError, KeyError, TypeError) as exc:
+        return {"status": "fail", "ready": False, "errors": [f"artifact intake contract: {exc}"]}
+
+
 def memory_summary() -> dict | None:
     path = project_memory_path()
     if not path.is_file():
@@ -433,6 +516,33 @@ def check_report(args: argparse.Namespace) -> int:
         visual_truth_path = scene_manifest_path.parent / str(visual_truth_name)
         if not visual_truth_path.is_file():
             errors.append("scene manifest visual_truth points to a missing artifact")
+    provenance_mode = "production" if state in {"ready_for_pr", "confirmed"} else "runtime"
+    provenance = asset_provenance_result(scene_manifest_path, scene_manifest, provenance_mode)
+    if provenance.get("status") == "fail":
+        errors.extend(f"asset provenance: {error}" for error in provenance.get("errors", []))
+    # Legacy report-contract fixtures may exercise lifecycle/report behavior
+    # without materializing a scene manifest. Do not invent provenance for
+    # those synthetic tasks. Once a real scene manifest exists, readiness is
+    # fail-closed and its asset_provenance reference is mandatory for PR
+    # states; the production quality gate remains independently strict when
+    # --require-asset-provenance is supplied.
+    if state in {"ready_for_pr", "confirmed"} and scene_manifest_path.is_file():
+        if provenance.get("status") != "pass":
+            errors.append("ready-for-PR or confirmed task requires a passing asset provenance production check")
+        elif not provenance.get("summary", {}).get("production_eligible"):
+            errors.append("ready-for-PR or confirmed task requires asset provenance production_eligible")
+    consistency = asset_consistency_result(scene_manifest_path, scene_manifest, strict=state in {"ready_for_pr", "confirmed"})
+    if consistency.get("status") == "fail":
+        errors.extend(f"asset consistency: {error}" for error in consistency.get("errors", []))
+    if state in {"ready_for_pr", "confirmed"} and scene_manifest_path.is_file() and scene_manifest.get("consistency_ref"):
+        if consistency.get("status") != "pass" or not consistency.get("ready"):
+            errors.append("ready-for-PR or confirmed task requires a passing asset consistency contract")
+    intake = artifact_intake_result(scene_manifest_path, scene_manifest, strict=state in {"ready_for_pr", "confirmed"})
+    if intake.get("status") == "fail":
+        errors.extend(f"artifact intake: {error}" for error in intake.get("errors", []))
+    if state in {"ready_for_pr", "confirmed"} and scene_manifest_path.is_file() and scene_manifest.get("artifact_intake"):
+        if intake.get("status") != "pass" or not intake.get("ready"):
+            errors.append("ready-for-PR or confirmed task requires a runtime-ready artifact intake contract")
     if state in {"validated", "ready_for_pr", "confirmed"}:
         quality = read_json(task_dir / "quality-report.json")
         if quality.get("status") != "pass":
@@ -529,6 +639,23 @@ def render(args: argparse.Namespace) -> int:
         ROOT / "src" / "output" / str(task.get("scene", "")) / str(scene_manifest.get("visual_truth", "")),
         {},
     ) if scene_manifest.get("visual_truth") else {}
+    provenance = asset_provenance_result(
+        ROOT / "src" / "output" / str(task.get("scene", "")) / "manifest.json",
+        scene_manifest,
+        "production" if task.get("state") in {"ready_for_pr", "confirmed"} else "runtime",
+    )
+    consistency = asset_consistency_result(
+        ROOT / "src" / "output" / str(task.get("scene", "")) / "manifest.json",
+        scene_manifest,
+        strict=task.get("state") in {"ready_for_pr", "confirmed"},
+    )
+    intake = artifact_intake_result(
+        ROOT / "src" / "output" / str(task.get("scene", "")) / "manifest.json",
+        scene_manifest,
+        strict=task.get("state") in {"ready_for_pr", "confirmed"},
+    )
+    intake_adapter = intake.get("adapter") or {}
+    intake_evidence = intake.get("evidence") or {}
     lines = [
         f"# Animation Task Report — {task.get('task_id', task_dir.name)}",
         "",
@@ -559,6 +686,14 @@ def render(args: argparse.Namespace) -> int:
         f"- Status: **{visual_truth.get('status', 'not-run')}**; scene: `{visual_truth.get('scene', task.get('scene', ''))}`; approval: **{visual_truth.get('review_boundary', {}).get('approval', False)}**",
         f"- Baseline: `{visual_truth.get('frames', {}).get('baseline', {}).get('path', '')}`; candidate: `{visual_truth.get('frames', {}).get('candidate', {}).get('path', '')}`",
         f"- Changed pixels: **{visual_truth.get('comparison', {}).get('changed_pixels', 'not-run')}**; changed regions: **{len(visual_truth.get('comparison', {}).get('regions', []))}**",
+        "## Asset provenance",
+        f"- Status: **{provenance.get('status', 'not-run')}**; authority: **{provenance.get('summary', {}).get('authority', 'unknown')}**; declared readiness: **{provenance.get('summary', {}).get('declared_readiness', 'blocked')}**; effective readiness: **{provenance.get('summary', {}).get('effective_readiness', 'blocked')}**",
+        f"- Production eligible: **{provenance.get('summary', {}).get('production_eligible', False)}**; production approved: **{provenance.get('summary', {}).get('production_approved', False)}**; errors: **{len(provenance.get('errors', []))}**",
+        "## Asset consistency",
+        f"- Status: **{consistency.get('status', 'not-run')}**; contract: **{consistency.get('contract', scene_manifest.get('consistency_kind', 'not-declared'))}**; ready: **{consistency.get('ready', False)}**; errors: **{len(consistency.get('errors', []))}**; warnings: **{len(consistency.get('warnings', []))}**",
+        "## Artifact Intake",
+        f"- Status: **{intake.get('status', 'not-run')}**; adapter: **{intake_adapter.get('adapter_id', 'not-declared')}**; adapter status: **{intake_adapter.get('status', 'not-declared')}**; ready: **{intake.get('ready', False)}**; production eligible: **{intake.get('production_eligible', False)}**; production approved: **{intake.get('production_approved', False)}**",
+        f"- Receipt: `{intake_evidence.get('receipt', '')}`; controls: `{intake_evidence.get('controls', '')}`; export: `{intake_evidence.get('export_manifest', '')}`; errors: **{len(intake.get('errors', []))}**; warnings: **{len(intake.get('warnings', []))}**",
         "## Semantic motion lint",
         f"- Status: **{lint.get('status', 'not-run')}**; errors: **{lint.get('summary', {}).get('errors', 0)}**; warnings: **{lint.get('summary', {}).get('warnings', 0)}**; blocking: **{lint.get('summary', {}).get('blocking', 0)}**",
         md_table(lint.get("findings", []), [("Rule", "rule_id"), ("Severity", "severity"), ("Confidence", "confidence"), ("Message", "message"), ("Basis", "basis")]),

package/scripts/resolve-task-bundle.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Resolve one safe artifact task bundle bound to a scene identity.
+
+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.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+SAFE_SCENE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def read_json(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def has_symlink_component(path: Path, root: Path) -> bool:
+    current = path
+    while True:
+        if current.is_symlink():
+            return True
+        if current == root:
+            return False
+        if current == current.parent:
+            return True
+        current = current.parent
+
+
+def resolve_task_dirs(root: Path, scene: str) -> list[Path]:
+    artifacts = root / "artifacts"
+    if not artifacts.is_dir() or artifacts.is_symlink():
+        return []
+    resolved_artifacts = artifacts.resolve()
+    matches: list[Path] = []
+    for task_path in sorted(artifacts.glob("*/task.json")):
+        if has_symlink_component(task_path, root):
+            continue
+        try:
+            if not task_path.resolve().is_relative_to(resolved_artifacts):
+                continue
+        except (OSError, RuntimeError):
+            continue
+        if read_json(task_path).get("scene") == scene:
+            matches.append(task_path.parent)
+    return matches
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--scene", required=True)
+    parser.add_argument("--root", default=".")
+    args = parser.parse_args()
+    if not SAFE_SCENE.fullmatch(args.scene) or args.scene in {".", ".."}:
+        print("FAIL: unsafe scene identifier", file=sys.stderr)
+        return 2
+
+    root = Path(args.root).resolve()
+    matches = resolve_task_dirs(root, args.scene)
+    if not matches:
+        print(f"FAIL: no safe task bundle bound to scene: {args.scene}", file=sys.stderr)
+        return 3
+    if len(matches) != 1:
+        joined = ", ".join(str(path.relative_to(root)) for path in matches)
+        print(f"FAIL: ambiguous task bundles bound to scene {args.scene}: {joined}", file=sys.stderr)
+        return 4
+    print(matches[0].relative_to(root).as_posix())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/review-hook.py

@@ -12,7 +12,7 @@ import subprocess
 import sys
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from urllib.parse import urlencode
+from urllib.parse import urlencode, urlsplit, urlunsplit
 
 ROOT = Path(__file__).resolve().parents[1]
 SAFE_SCENE = re.compile(r"^[A-Za-z0-9._-]+$")
@@ -42,6 +42,29 @@ def candidate_id(task_id: str, scene: str, context_hash: str, source_hash: str,
     return hashlib.sha256(raw).hexdigest()[:20]
 
 
+def review_urls(lab_url: str, scene: str, task_id: str, candidate: str) -> tuple[str, str, str]:
+    """Build an exact review route while anchoring artifact paths at its origin.
+
+    `--lab-url` is the actual browser route, e.g. `https://host/lab` for the
+    React Dev Lab or `http://127.0.0.1:3300/` for the bundled static lab.
+    Artifact and task paths intentionally remain same-origin root paths.
+    """
+    parsed = urlsplit(lab_url.strip())
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.query or parsed.fragment:
+        raise ValueError("lab-url must be an absolute http(s) Dev Lab route without query or fragment")
+    origin = urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
+    review_path = parsed.path.rstrip("/") or "/"
+    review_base = f"{origin}{review_path}" if review_path != "/" else origin
+    query = urlencode({
+        "scene": scene,
+        "task_id": task_id,
+        "candidate_id": candidate,
+        "artifact_base": f"{origin}/scenes/{scene}",
+        "task_base": f"{origin}/tasks/{task_id}",
+    })
+    return f"{review_base}/?{query}" if review_path != "/" else f"{origin}/?{query}", f"{origin}/scenes/{scene}", f"{origin}/tasks/{task_id}"
+
+
 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):
@@ -79,9 +102,8 @@ def prepare(args: argparse.Namespace) -> int:
     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}'})}"
+    url, artifact_base, task_base = review_urls(args.lab_url, scene, task_id, cid)
     candidate = {
         "schema_version": "1.0",
         "candidate_id": cid,
@@ -120,7 +142,7 @@ def prepare(args: argparse.Namespace) -> int:
     handoff = read_json(handoff_path)
     if memory_path.is_file():
         shutil.copy2(memory_path, task_dir / "project-memory.json")
-    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"] + (["project-memory.json"] if memory_path.is_file() else [])))})
+    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, "artifact_base": artifact_base, "task_base": task_base, "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"] + (["project-memory.json"] if memory_path.is_file() else [])))})
     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)