motionloom 2.2.0 → 2.3.0

package/scripts/asset-provenance.py

@@ -0,0 +1,390 @@
+"""Validate and classify asset-level provenance without granting approval.
+
+The contract is intentionally fail-closed. An Agent may declare how an asset
+was produced and may prove runtime readiness, but it cannot manufacture human
+authority or production approval. The script uses pathlib and JSON only so
+the same entrypoint works on Ubuntu, macOS and Windows.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SCHEMA_VERSION = "1.0"
+AUTHORITIES = {
+    "ai_generated",
+    "ai_assisted",
+    "ai_assisted_human_reviewed",
+    "artist_authored",
+    "unknown",
+}
+READINESS = {
+    "blocked",
+    "runtime_ready",
+    "review_required",
+    "production_eligible",
+    "production_approved",
+}
+SAFE_RELATIVE = re.compile(r"^(?!/)(?!.*(?:^|/)\.\.(?:/|$)).+")
+SHA256 = re.compile(r"^[a-f0-9]{64}$")
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"{path}: provenance document must be a JSON object")
+    return value
+
+
+def is_datetime(value: Any) -> bool:
+    if not isinstance(value, str) or not value.strip():
+        return False
+    try:
+        datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return False
+    return True
+
+
+def is_relative_path(value: Any) -> bool:
+    return isinstance(value, str) and bool(SAFE_RELATIVE.fullmatch(value))
+
+
+def is_sha256(value: Any) -> bool:
+    return isinstance(value, str) and bool(SHA256.fullmatch(value))
+
+
+def _required(data: dict[str, Any], keys: tuple[str, ...], prefix: str, errors: list[str]) -> None:
+    for key in keys:
+        if key not in data:
+            errors.append(f"{prefix}.{key} is required")
+
+
+def _check_text(data: dict[str, Any], key: str, prefix: str, errors: list[str]) -> None:
+    if key in data and (not isinstance(data[key], str) or not data[key].strip()):
+        errors.append(f"{prefix}.{key} must be a non-empty string")
+
+
+def _check_human_review(data: dict[str, Any], errors: list[str]) -> None:
+    review = data.get("human_review")
+    if not isinstance(review, dict):
+        errors.append("human_review is required for human-reviewed readiness")
+        return
+    _required(review, ("reviewer", "decision", "scope", "reviewed_at", "user_confirmed"), "human_review", errors)
+    _check_text(review, "reviewer", "human_review", errors)
+    if review.get("decision") not in {"approved", "rejected", "changes_requested"}:
+        errors.append("human_review.decision must be approved, rejected or changes_requested")
+    if not is_datetime(review.get("reviewed_at")):
+        errors.append("human_review.reviewed_at must be an ISO-8601 timestamp")
+    if review.get("user_confirmed") is not True:
+        errors.append("human_review.user_confirmed must be true; Agent-only review is not sufficient")
+
+
+def _check_human_attestation(data: dict[str, Any], errors: list[str]) -> None:
+    attestation = data.get("human_attestation")
+    if not isinstance(attestation, dict):
+        errors.append("artist_authored requires human_attestation")
+        return
+    _required(attestation, ("attestor", "attestor_type", "decision", "attested_at", "user_confirmed"), "human_attestation", errors)
+    _check_text(attestation, "attestor", "human_attestation", errors)
+    if attestation.get("attestor_type") not in {"artist", "user"}:
+        errors.append("human_attestation.attestor_type must be artist or user")
+    if attestation.get("decision") != "artist_authored":
+        errors.append("human_attestation.decision must be artist_authored")
+    if not is_datetime(attestation.get("attested_at")):
+        errors.append("human_attestation.attested_at must be an ISO-8601 timestamp")
+    if attestation.get("user_confirmed") is not True:
+        errors.append("human_attestation.user_confirmed must be true; Agent-only authority is rejected")
+
+
+def _check_generator(data: dict[str, Any], errors: list[str]) -> None:
+    generator = data.get("generator")
+    if not isinstance(generator, dict):
+        errors.append("AI-origin authority requires generator metadata")
+        return
+    _required(generator, ("model", "task_id", "source", "generated_at"), "generator", errors)
+    for key in ("model", "task_id", "source"):
+        _check_text(generator, key, "generator", errors)
+    if not is_datetime(generator.get("generated_at")):
+        errors.append("generator.generated_at must be an ISO-8601 timestamp")
+    if "prompt_hash" in generator and not is_sha256(generator.get("prompt_hash")):
+        errors.append("generator.prompt_hash must be a lowercase SHA-256")
+
+
+def _check_files(data: dict[str, Any], errors: list[str]) -> None:
+    files = data.get("files")
+    if not isinstance(files, list) or not files:
+        errors.append("files must contain at least one asset file")
+        return
+    for index, item in enumerate(files):
+        prefix = f"files[{index}]"
+        if not isinstance(item, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        _required(item, ("path", "role", "sha256"), prefix, errors)
+        if not is_relative_path(item.get("path")):
+            errors.append(f"{prefix}.path must be a safe relative path")
+        _check_text(item, "role", prefix, errors)
+        if not is_sha256(item.get("sha256")):
+            errors.append(f"{prefix}.sha256 must be a lowercase SHA-256")
+        if "bytes" in item and (not isinstance(item["bytes"], int) or item["bytes"] < 0):
+            errors.append(f"{prefix}.bytes must be a non-negative integer")
+
+
+def _check_chain(data: dict[str, Any], errors: list[str]) -> None:
+    chain = data.get("provenance_chain")
+    if not isinstance(chain, list) or not chain:
+        errors.append("provenance_chain must contain at least one step")
+        return
+    for index, item in enumerate(chain):
+        prefix = f"provenance_chain[{index}]"
+        if not isinstance(item, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        _required(item, ("step", "actor", "source", "timestamp"), prefix, errors)
+        for key in ("step", "actor", "source"):
+            _check_text(item, key, prefix, errors)
+        if not is_datetime(item.get("timestamp")):
+            errors.append(f"{prefix}.timestamp must be an ISO-8601 timestamp")
+        if "sha256" in item and not is_sha256(item.get("sha256")):
+            errors.append(f"{prefix}.sha256 must be a lowercase SHA-256")
+
+
+def validate_document(data: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    _required(data, ("schema_version", "provenance_id", "asset", "authority", "readiness", "files", "license", "provenance_chain", "created_at"), "provenance", errors)
+    if data.get("schema_version") != SCHEMA_VERSION:
+        errors.append(f"schema_version must be {SCHEMA_VERSION}")
+    _check_text(data, "provenance_id", "provenance", errors)
+    if not is_datetime(data.get("created_at")):
+        errors.append("created_at must be an ISO-8601 timestamp")
+
+    asset = data.get("asset")
+    if not isinstance(asset, dict):
+        errors.append("asset must be an object")
+    else:
+        _required(asset, ("id", "path", "type", "framework"), "asset", errors)
+        _check_text(asset, "id", "asset", errors)
+        if not is_relative_path(asset.get("path")):
+            errors.append("asset.path must be a safe relative path")
+        for key in ("type", "framework"):
+            _check_text(asset, key, "asset", errors)
+
+    authority = data.get("authority")
+    readiness = data.get("readiness")
+    if authority not in AUTHORITIES:
+        errors.append(f"authority must be one of {sorted(AUTHORITIES)}")
+    if readiness not in READINESS:
+        errors.append(f"readiness must be one of {sorted(READINESS)}")
+
+    license_data = data.get("license")
+    if not isinstance(license_data, dict):
+        errors.append("license must be an object")
+    else:
+        _required(license_data, ("spdx", "source", "attribution"), "license", errors)
+        for key in ("spdx", "source", "attribution"):
+            _check_text(license_data, key, "license", errors)
+
+    _check_files(data, errors)
+    _check_chain(data, errors)
+    if authority in {"ai_generated", "ai_assisted", "ai_assisted_human_reviewed"}:
+        _check_generator(data, errors)
+    if authority == "artist_authored":
+        _check_human_attestation(data, errors)
+
+    if authority == "unknown" and readiness != "blocked":
+        errors.append("unknown authority is always blocked")
+    if authority == "ai_generated" and readiness != "runtime_ready":
+        errors.append("ai_generated assets may be runtime_ready only; they are never production eligible")
+    if authority == "ai_assisted_human_reviewed" and readiness not in {"review_required", "production_eligible"}:
+        errors.append("ai_assisted_human_reviewed assets must remain review_required or pass a later production gate")
+    if authority == "ai_assisted_human_reviewed":
+        _check_human_review(data, errors)
+    if authority == "ai_assisted" and readiness not in {"runtime_ready", "review_required", "production_eligible"}:
+        errors.append("ai_assisted assets must be runtime_ready, review_required or production_eligible")
+    if authority == "ai_assisted" and readiness == "production_eligible":
+        _check_human_review(data, errors)
+    if readiness in {"production_eligible", "production_approved"}:
+        runtime = data.get("runtime_evidence")
+        if not isinstance(runtime, dict) or runtime.get("status") != "pass":
+            errors.append("production eligibility requires runtime_evidence.status=pass")
+        full_gate = data.get("full_gate")
+        if not isinstance(full_gate, dict):
+            errors.append("production eligibility requires full_gate evidence")
+        else:
+            _required(full_gate, ("status", "quality_gate", "visual_truth", "license", "checked_at"), "full_gate", errors)
+            if full_gate.get("status") != "pass" or full_gate.get("quality_gate") != "pass" or full_gate.get("visual_truth") != "pass" or full_gate.get("license") != "pass":
+                errors.append("full_gate must have pass for status, quality_gate, visual_truth and license")
+            if not is_datetime(full_gate.get("checked_at")):
+                errors.append("full_gate.checked_at must be an ISO-8601 timestamp")
+        if authority in {"ai_assisted", "ai_assisted_human_reviewed"}:
+            _check_human_review(data, errors)
+        if authority in {"unknown", "ai_generated"}:
+            errors.append(f"{authority} cannot be production eligible")
+    if readiness == "production_approved":
+        approval = data.get("human_approval")
+        if not isinstance(approval, dict):
+            errors.append("production_approved requires human_approval")
+        else:
+            _required(approval, ("issued_by", "decision", "approved_at", "user_confirmed"), "human_approval", errors)
+            issuer = approval.get("issued_by")
+            if not isinstance(issuer, dict) or issuer.get("type") not in {"user", "artist"} or not str(issuer.get("id") or "").strip():
+                errors.append("human_approval.issued_by must be a non-empty user or artist identity")
+            if approval.get("decision") != "approved":
+                errors.append("human_approval.decision must be approved")
+            if not is_datetime(approval.get("approved_at")):
+                errors.append("human_approval.approved_at must be an ISO-8601 timestamp")
+            if approval.get("user_confirmed") is not True:
+                errors.append("human_approval.user_confirmed must be true")
+        if authority in {"unknown", "ai_generated"}:
+            errors.append("unknown and ai_generated assets can never be production_approved")
+    if "human_approval" in data and readiness != "production_approved":
+        errors.append("human_approval is only valid when readiness is production_approved")
+    return errors
+
+
+def _resolve_inside(base: Path, relative: str) -> Path | None:
+    if not is_relative_path(relative):
+        return None
+    resolved = (base / relative).resolve()
+    try:
+        resolved.relative_to(base.resolve())
+    except ValueError:
+        return None
+    return resolved
+
+
+def validate_files(data: dict[str, Any], base: Path) -> list[str]:
+    errors: list[str] = []
+    for item in data.get("files", []):
+        path = _resolve_inside(base, str(item.get("path", "")))
+        if path is None or not path.is_file():
+            errors.append(f"asset file is missing: {item.get('path', '<unknown>')}")
+            continue
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        if digest != item.get("sha256"):
+            errors.append(f"asset file SHA-256 mismatch: {item.get('path', '<unknown>')}")
+        if "bytes" in item and path.stat().st_size != item.get("bytes"):
+            errors.append(f"asset file byte count mismatch: {item.get('path', '<unknown>')}")
+    asset_path = _resolve_inside(base, str((data.get("asset") or {}).get("path", "")))
+    if asset_path is None or not asset_path.is_file():
+        errors.append(f"asset.path is missing: {(data.get('asset') or {}).get('path', '<unknown>')}")
+    return errors
+
+
+def classify(data: dict[str, Any], errors: list[str] | None = None) -> dict[str, Any]:
+    errors = errors or []
+    authority = data.get("authority", "unknown")
+    readiness = data.get("readiness", "blocked")
+    effective = "blocked" if errors or authority == "unknown" else "runtime_ready"
+    if not errors:
+        if authority == "ai_generated":
+            effective = "runtime_ready"
+        elif authority in {"ai_assisted", "ai_assisted_human_reviewed"}:
+            review = data.get("human_review") or {}
+            if data.get("full_gate", {}).get("status") == "pass" and review.get("decision") == "approved" and review.get("user_confirmed") is True:
+                effective = "production_eligible"
+            elif authority == "ai_assisted_human_reviewed" or readiness == "review_required":
+                effective = "review_required"
+            else:
+                effective = "runtime_ready"
+        elif authority == "artist_authored":
+            effective = "production_eligible" if data.get("full_gate", {}).get("status") == "pass" else "runtime_ready"
+        if readiness == "production_approved" and data.get("human_approval", {}).get("user_confirmed") is True:
+            effective = "production_approved"
+    return {
+        "authority": authority,
+        "declared_readiness": readiness,
+        "effective_readiness": effective,
+        "production_eligible": effective in {"production_eligible", "production_approved"},
+        "production_approved": effective == "production_approved",
+        "errors": errors,
+    }
+
+
+def evaluate(path: Path, *, base: Path | None = None, mode: str = "contract", manifest: dict[str, Any] | None = None) -> dict[str, Any]:
+    try:
+        data = read_json(path)
+    except ValueError as exc:
+        return {"status": "fail", "provenance_path": str(path), "errors": [str(exc)]}
+    errors = validate_document(data)
+    if manifest is not None:
+        manifest_file = manifest.get("file")
+        asset_path = (data.get("asset") or {}).get("path")
+        if manifest_file and asset_path != manifest_file:
+            errors.append("asset.path must match scene manifest.file")
+        provenance_ref = manifest.get("asset_provenance")
+        if provenance_ref and provenance_ref != path.name and provenance_ref != path.as_posix():
+            errors.append("scene manifest asset_provenance does not match the loaded provenance file")
+    if mode in {"runtime", "production"}:
+        if base is None:
+            errors.append(f"{mode} check requires --root for asset file hash verification")
+        else:
+            errors.extend(validate_files(data, base))
+        runtime = data.get("runtime_evidence") or {}
+        if runtime.get("status") != "pass":
+            errors.append("runtime check requires runtime_evidence.status=pass")
+    if mode == "production":
+        summary = classify(data, errors)
+        if summary["effective_readiness"] != "production_eligible":
+            errors.append("production check requires effective_readiness=production_eligible; production_approved remains a human-only state")
+    summary = classify(data, errors)
+    return {
+        "status": "pass" if not errors else "fail",
+        "mode": mode,
+        "provenance_path": str(path),
+        "summary": summary,
+        "errors": errors,
+    }
+
+
+def print_result(result: dict[str, Any], as_json: bool = True) -> None:
+    if as_json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return
+    print(f"Asset provenance: {result.get('status', 'fail').upper()}")
+    summary = result.get("summary") or {}
+    print(f"Authority: {summary.get('authority', 'unknown')}")
+    print(f"Declared readiness: {summary.get('declared_readiness', 'blocked')}")
+    print(f"Effective readiness: {summary.get('effective_readiness', 'blocked')}")
+    for error in result.get("errors", []):
+        print(f"- {error}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate, classify and report MotionLoom asset provenance")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("validate", "classify", "check", "report"):
+        command = sub.add_parser(name)
+        command.add_argument("--input", required=True, help="Asset provenance JSON path")
+        command.add_argument("--root", help="Directory used to resolve and hash asset files")
+        command.add_argument("--mode", choices=("contract", "runtime", "production"), default="contract")
+        command.add_argument("--manifest", help="Optional scene manifest used for binding checks")
+        command.add_argument("--json", action="store_true", help="Emit JSON output")
+    args = parser.parse_args()
+    path = Path(args.input).expanduser().resolve()
+    base = Path(args.root).expanduser().resolve() if args.root else None
+    manifest = read_json(Path(args.manifest).expanduser().resolve()) if args.manifest else None
+    result = evaluate(path, base=base, mode=args.mode, manifest=manifest)
+    if args.command == "classify" and result.get("summary"):
+        result = {"status": result.get("status"), "provenance_path": str(path), "summary": result["summary"], "errors": result.get("errors", [])}
+    if args.command == "validate":
+        result["mode"] = "contract"
+    print_result(result, as_json=args.json or args.command != "report")
+    return 0 if result.get("status") == "pass" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/docs-audit.py

@@ -23,7 +23,7 @@ for markdown in sorted(ROOT.rglob("*.md")):
         if not (markdown.parent / target).resolve().exists():
             errors.append(f"{markdown.relative_to(ROOT)} -> missing {target}")
 
-for relative in ["package.json", "agent-card.json", "agent-surfaces.json", "schemas/agent-surfaces.schema.json", "schemas/visual-truth.schema.json", "schemas/remediation-history.schema.json", "project-context.example.json", "tests/evals/project-corpus.json"]:
+for relative in ["package.json", "agent-card.json", "agent-surfaces.json", "schemas/agent-surfaces.schema.json", "schemas/provenance.schema.json", "schemas/asset-provenance.schema.json", "schemas/scene-manifest.schema.json", "schemas/visual-truth.schema.json", "schemas/remediation-history.schema.json", "project-context.example.json", "examples/agent-consumer/ai-generated-pilot-provenance.json", "tests/evals/project-corpus.json"]:
     path = ROOT / relative
     try:
         json.loads(path.read_text(encoding="utf-8"))
@@ -39,6 +39,12 @@ if package.get("packageManager") != "pnpm@11.20.0":
 for required_surface in [".agents", ".claude", ".codex", "AGENTS.md", "agent-surfaces.json"]:
     if required_surface not in package.get("files", []):
         errors.append(f"package.json: files must include Agent surface {required_surface}")
+for required_path in ["scripts/asset-provenance.py", "schemas/asset-provenance.schema.json", "examples/agent-consumer/ai-generated-pilot-provenance.json"]:
+    if required_path not in package.get("files", []):
+        errors.append(f"package.json: files must include asset provenance contract {required_path}")
+for onboarding_script in ["setup", "setup:dry", "status", "repair"]:
+    if onboarding_script not in package.get("scripts", {}):
+        errors.append(f"package.json: missing onboarding script {onboarding_script}")
 
 sys.path.insert(0, str(ROOT))
 try:
@@ -54,9 +60,13 @@ for required_doc in ["docs/AGENT-INTEGRATION.md", "references/agent-interoperabi
         errors.append(f"missing Agent interoperability document: {required_doc}")
 
 readme = (ROOT / "README.md").read_text(encoding="utf-8")
-for heading in ["Why MotionLoom", "Quick start", "Durable Project Memory", "Evidence, trust and review", "Documentation map"]:
+for heading in ["Why MotionLoom", "Quick start", "Durable Project Memory", "Evidence, trust and review", "Asset provenance tiers", "Documentation map"]:
     if f"## {heading}" not in readme:
         errors.append(f"README.md: missing heading {heading}")
+if "npx --yes motionloom setup" not in readme:
+    errors.append("README.md: missing one-command onboarding recipe")
+if "npx --yes motionloom setup" not in (ROOT / "docs/AGENT-INTEGRATION.md").read_text(encoding="utf-8"):
+    errors.append("docs/AGENT-INTEGRATION.md: missing one-command onboarding recipe")
 
 workflow_dir = ROOT / ".github" / "workflows"
 for workflow in sorted(workflow_dir.glob("*.yml")):
@@ -77,6 +87,8 @@ for workflow in sorted(workflow_dir.glob("*.yml")):
     for required in ["name:", "on:", "jobs:", "permissions:"]:
         if required not in text:
             errors.append(f"{workflow.relative_to(ROOT)}: missing {required}")
+if "--require-asset-provenance" not in (workflow_dir / "quality.yml").read_text(encoding="utf-8"):
+    errors.append("quality.yml: missing fail-closed asset provenance production gate")
     if "pull_request:" in text and "secrets." in text:
         errors.append(f"{workflow.relative_to(ROOT)}: secrets referenced in pull_request workflow")
 

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,14 @@ 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 _json(path: Path):
     try:
         return json.loads(path.read_text(encoding="utf-8"))
@@ -74,7 +82,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) -> list[str]:
     issues = []
     manifest_path = scene_dir / "manifest.json"
     spec_path = scene_dir / "motion-spec.json"
@@ -108,6 +116,28 @@ 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}")
+
     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 +412,8 @@ 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("--attestation")
     parser.add_argument("--trust-policy")
     args = parser.parse_args()
@@ -396,20 +428,26 @@ 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
     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)
         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")
+            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,32 @@ 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_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 memory_summary() -> dict | None:
     path = project_memory_path()
     if not path.is_file():
@@ -433,6 +460,21 @@ 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")
     if state in {"validated", "ready_for_pr", "confirmed"}:
         quality = read_json(task_dir / "quality-report.json")
         if quality.get("status") != "pass":
@@ -529,6 +571,11 @@ 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",
+    )
     lines = [
         f"# Animation Task Report — {task.get('task_id', task_dir.name)}",
         "",
@@ -559,6 +606,9 @@ 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', []))}**",
         "## 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")]),