motionloom 2.1.0 → 2.3.0

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", "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"))
@@ -36,11 +36,37 @@ for required in ["author", "repository", "homepage", "bugs", "license", "engines
         errors.append(f"package.json: missing public metadata {required}")
 if package.get("packageManager") != "pnpm@11.20.0":
     errors.append("package.json: packageManager must pin 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:
+    from scripts.discovery import validate as validate_discovery
+    discovery = validate_discovery(ROOT)
+    for discovery_error in discovery.get("errors", []):
+        errors.append(f"agent discovery: {discovery_error}")
+except Exception as exc:
+    errors.append(f"agent discovery: validator could not load: {exc}")
+
+for required_doc in ["docs/AGENT-INTEGRATION.md", "references/agent-interoperability.md"]:
+    if not (ROOT / required_doc).is_file():
+        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")):
@@ -61,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

@@ -94,6 +94,8 @@ def main() -> int:
         "--context", args.context or str(repo / "project-context.json"),
         "--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])
@@ -120,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

@@ -47,6 +47,22 @@ def _load_attestation_verifier():
     return module
 
 
+def _load_visual_truth():
+    path = ROOT / "scripts" / "visual-truth.py"
+    loader = importlib.util.spec_from_file_location("visual_truth", path)
+    module = importlib.util.module_from_spec(loader)
+    loader.loader.exec_module(module)
+    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"))
@@ -66,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) -> 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"
@@ -100,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")
@@ -326,6 +364,36 @@ def validate_scene(scene_dir: Path, context_path: Path, require_review: bool = F
                             issues.append(f"signed attestation required binding source is missing: {field}")
                 except (OSError, ValueError, json.JSONDecodeError) as exc:
                     issues.append(f"signed attestation contract: {exc}")
+    if require_visual_truth:
+        visual_name = manifest.get("visual_truth")
+        if not isinstance(visual_name, str) or not visual_name.strip():
+            issues.append("visual truth gate requires manifest.visual_truth")
+        else:
+            visual_path = (scene_dir / visual_name).resolve()
+            if not visual_path.is_file() or scene_dir.resolve() not in visual_path.parents:
+                issues.append("manifest.visual_truth must point to an existing file inside the scene directory")
+            else:
+                try:
+                    task_id = None
+                    motion_ir_hash = None
+                    if task_dir:
+                        task = _json(task_dir / "task.json")
+                        task_id = task.get("task_id")
+                        motion_ir = task_dir / "motion-ir.json"
+                        motion_ir_hash = _sha256_file(motion_ir) if motion_ir.is_file() else None
+                    visual_truth = _load_visual_truth()
+                    visual_issues = visual_truth.validate_report(
+                        visual_path,
+                        ROOT,
+                        scene_dir.name,
+                        task_id,
+                        source_sha_for_evidence,
+                        manifest_sha_for_evidence,
+                        motion_ir_hash,
+                    )
+                    issues.extend(f"visual truth: {issue}" for issue in visual_issues)
+                except (OSError, ValueError, json.JSONDecodeError) as exc:
+                    issues.append(f"visual truth contract: {exc}")
     return issues
 
 
@@ -343,6 +411,9 @@ def main() -> int:
     parser.add_argument("--require-benchmark", action="store_true")
     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()
@@ -357,20 +428,27 @@ 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)
+        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:
-            print(f"ACCEPTED {scene_dir.name}: context + spec + runtime snapshots + browser-review candidate + checklist")
+            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/remediation-learning.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""Record and summarize user-confirmed remediation and benchmark history.
+
+The history is an append-only JSONL ledger. Each event carries a hash of its
+canonical payload and the hash of the previous event. This makes the ledger
+portable and inspectable without introducing a database or treating metrics as
+approval. Only explicitly user-confirmed remediation outcomes contribute to
+acceptance metrics.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import os
+import sys
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SCHEMA_VERSION = "0.1"
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def canonical(value: Any) -> bytes:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def event_digest(event: dict[str, Any]) -> str:
+    payload = {key: value for key, value in event.items() if key != "event_sha256"}
+    return sha256_bytes(canonical(payload))
+
+
+def history_path(raw: str | None) -> Path:
+    return (Path(raw).expanduser() if raw else ROOT / "artifacts" / "remediation-history.jsonl").resolve()
+
+
+def output_path(raw: str | None, default_name: str) -> Path:
+    return (Path(raw).expanduser() if raw else ROOT / "artifacts" / default_name).resolve()
+
+
+def read_history(path: Path) -> tuple[list[dict[str, Any]], list[str]]:
+    if not path.exists():
+        return [], []
+    if path.is_symlink():
+        return [], ["history path must not be a symlink"]
+    events: list[dict[str, Any]] = []
+    errors: list[str] = []
+    previous: str | None = None
+    seen: set[str] = set()
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError) as error:
+        return [], [f"history read failed: {error}"]
+    for line_number, line in enumerate(lines, start=1):
+        if not line.strip():
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError as error:
+            errors.append(f"line {line_number}: invalid JSON: {error.msg}")
+            continue
+        if not isinstance(event, dict):
+            errors.append(f"line {line_number}: event must be an object")
+            continue
+        event_id = str(event.get("event_id", ""))
+        if not event_id:
+            errors.append(f"line {line_number}: event_id is required")
+        if event_id in seen:
+            errors.append(f"line {line_number}: duplicate event_id {event_id}")
+        seen.add(event_id)
+        if event.get("schema_version") != SCHEMA_VERSION:
+            errors.append(f"line {line_number}: unsupported schema_version")
+        if event.get("previous_event_sha256") != previous:
+            errors.append(f"line {line_number}: previous_event_sha256 does not match ledger head")
+        expected = event_digest(event)
+        if event.get("event_sha256") != expected:
+            errors.append(f"line {line_number}: event_sha256 mismatch")
+        previous = expected
+        events.append(event)
+    return events, errors
+
+
+def append_event(path: Path, event: dict[str, Any]) -> dict[str, Any]:
+    events, errors = read_history(path)
+    if errors:
+        raise ValueError("cannot append to invalid history: " + "; ".join(errors))
+    event = dict(event)
+    event.setdefault("schema_version", SCHEMA_VERSION)
+    event.setdefault("recorded_at", now())
+    event["previous_event_sha256"] = events[-1].get("event_sha256") if events else None
+    event["event_sha256"] = event_digest(event)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists() and path.is_symlink():
+        raise ValueError("history path must not be a symlink")
+    with path.open("a", encoding="utf-8", newline="\n") as handle:
+        handle.write(json.dumps(event, ensure_ascii=False, sort_keys=True) + "\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    return event
+
+
+def file_ref(raw: str | None) -> dict[str, Any] | None:
+    if not raw:
+        return None
+    path = Path(raw).expanduser().resolve()
+    result: dict[str, Any] = {"path": str(path)}
+    if path.is_file():
+        result["sha256"] = sha256_bytes(path.read_bytes())
+        result["bytes"] = path.stat().st_size
+        result["exists"] = True
+    else:
+        result["exists"] = False
+    return result
+
+
+def cmd_record_outcome(args: argparse.Namespace) -> int:
+    if args.correction_count < 0:
+        raise ValueError("correction-count must be >= 0")
+    event = append_event(history_path(args.history), {
+        "event_id": args.event_id,
+        "event_type": "remediation_outcome",
+        "issue_id": args.issue_id,
+        "issue_class": args.issue_class or args.issue_id.split(".", 1)[0],
+        "summary": args.summary,
+        "root_cause": args.root_cause or "",
+        "resolution": args.resolution or "",
+        "result": args.result,
+        "correction_count": args.correction_count,
+        "first_pass_accepted": args.result == "pass" and args.correction_count == 0,
+        "rerun_scope": args.rerun_scope or [],
+        "user_confirmed": True,
+        "source_task_id": args.source_task_id,
+        "evidence": [ref for raw in (args.evidence or []) if (ref := file_ref(raw))],
+    })
+    emit({"status": "recorded", "event": event}, args.json)
+    return 0
+
+
+def cmd_record_benchmark(args: argparse.Namespace) -> int:
+    if args.iterations <= 0 or args.p95_ms < 0 or args.threshold_ms <= 0:
+        raise ValueError("benchmark iterations must be > 0, p95-ms must be >= 0 and threshold-ms must be > 0")
+    event = append_event(history_path(args.history), {
+        "event_id": args.event_id,
+        "event_type": "benchmark_run",
+        "operation": args.operation,
+        "task_id": args.task_id,
+        "scene": args.scene,
+        "iterations": args.iterations,
+        "p95_ms": args.p95_ms,
+        "threshold_ms": args.threshold_ms,
+        "status": args.status or ("pass" if args.p95_ms < args.threshold_ms else "fail"),
+        "provenance": file_ref(args.evidence),
+    })
+    emit({"status": "recorded", "event": event}, args.json)
+    return 0
+
+
+def percentile(values: list[int | float], fraction: float) -> int | float | None:
+    if not values:
+        return None
+    ordered = sorted(values)
+    index = max(0, math.ceil(len(ordered) * fraction) - 1)
+    return ordered[index]
+
+
+def rate(numerator: int, denominator: int) -> float | None:
+    return round(numerator / denominator, 4) if denominator else None
+
+
+def cmd_summary(args: argparse.Namespace) -> int:
+    path = history_path(args.history)
+    events, errors = read_history(path)
+    if errors:
+        emit({"status": "fail", "history": str(path), "errors": errors}, args.json)
+        return 1
+    outcomes = [event for event in events if event.get("event_type") == "remediation_outcome"]
+    confirmed = [event for event in outcomes if event.get("user_confirmed") is True]
+    benchmarks = [event for event in events if event.get("event_type") == "benchmark_run"]
+    passes = [event for event in confirmed if event.get("result") == "pass"]
+    first_passes = [event for event in confirmed if event.get("first_pass_accepted") is True]
+    corrections = [int(event.get("correction_count", 0)) for event in confirmed]
+    p95_corrections = percentile(corrections, 0.95)
+    outlier_threshold = max(3, int(p95_corrections or 0))
+    outliers = [
+        {"event_id": event.get("event_id"), "issue_id": event.get("issue_id"), "correction_count": event.get("correction_count")}
+        for event in confirmed if int(event.get("correction_count", 0)) >= outlier_threshold and int(event.get("correction_count", 0)) > 0
+    ]
+    by_issue_class: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for event in confirmed:
+        by_issue_class[str(event.get("issue_class") or "unknown")].append(event)
+    issue_summary = {}
+    for issue_class, items in sorted(by_issue_class.items()):
+        issue_passes = sum(item.get("result") == "pass" for item in items)
+        issue_first_passes = sum(item.get("first_pass_accepted") is True for item in items)
+        issue_summary[issue_class] = {
+            "outcomes": len(items),
+            "passes": issue_passes,
+            "success_rate": rate(issue_passes, len(items)),
+            "first_pass_acceptance_rate": rate(issue_first_passes, len(items)),
+            "average_correction_count": round(sum(int(item.get("correction_count", 0)) for item in items) / len(items), 4),
+        }
+    benchmark_passes = sum(event.get("status") == "pass" for event in benchmarks)
+    summary = {
+        "schema_version": SCHEMA_VERSION,
+        "summary_id": f"remediation-summary-{path.stem}",
+        "status": "pass",
+        "history_path": str(path),
+        "history_sha256": sha256_bytes(path.read_bytes()) if path.is_file() else None,
+        "generated_at": now(),
+        "ledger": {"event_count": len(events), "outcomes": len(outcomes), "confirmed_outcomes": len(confirmed), "ignored_unconfirmed_outcomes": len(outcomes) - len(confirmed), "benchmarks": len(benchmarks)},
+        "remediation": {
+            "passes": len(passes),
+            "success_rate": rate(len(passes), len(confirmed)),
+            "first_pass_acceptances": len(first_passes),
+            "first_pass_acceptance_rate": rate(len(first_passes), len(confirmed)),
+            "average_correction_count": round(sum(corrections) / len(corrections), 4) if corrections else None,
+            "p95_correction_count": p95_corrections,
+            "outlier_threshold": outlier_threshold,
+            "outliers": outliers,
+            "by_issue_class": issue_summary,
+        },
+        "benchmarks_summary": {
+            "runs": len(benchmarks),
+            "passes": benchmark_passes,
+            "pass_rate": rate(benchmark_passes, len(benchmarks)),
+            "operations": sorted({str(event.get("operation")) for event in benchmarks}),
+        },
+        "approval": False,
+    }
+    if args.output:
+        write_json(output_path(args.output, "remediation-summary.json"), summary)
+    emit(summary, args.json)
+    return 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    path = history_path(args.history)
+    events, errors = read_history(path)
+    result = {"status": "pass" if not errors else "fail", "history": str(path), "event_count": len(events), "errors": errors, "approval": False}
+    emit(result, args.json)
+    return 0 if not errors else 1
+
+
+def write_json(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.tmp-{os.getpid()}")
+    temporary.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def emit(value: dict[str, Any], as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(value, indent=2, ensure_ascii=False))
+    else:
+        print(json.dumps(value, ensure_ascii=False))
+
+
+def add_common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--history", help="Append-only JSONL history path")
+    parser.add_argument("--json", action="store_true")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="MotionLoom remediation and benchmark history")
+    sub = parser.add_subparsers(dest="command", required=True)
+    outcome = sub.add_parser("record-outcome", help="Record an explicitly user-confirmed remediation outcome")
+    add_common(outcome)
+    outcome.add_argument("--event-id", required=True)
+    outcome.add_argument("--issue-id", required=True)
+    outcome.add_argument("--issue-class")
+    outcome.add_argument("--summary", required=True)
+    outcome.add_argument("--root-cause")
+    outcome.add_argument("--resolution")
+    outcome.add_argument("--result", choices=["pass", "fail", "partial", "unknown"], required=True)
+    outcome.add_argument("--correction-count", type=int, default=0)
+    outcome.add_argument("--rerun-scope", action="append")
+    outcome.add_argument("--source-task-id")
+    outcome.add_argument("--evidence", action="append")
+    outcome.add_argument("--user-confirmed", action="store_true", required=True)
+    outcome.set_defaults(func=cmd_record_outcome)
+    benchmark = sub.add_parser("record-benchmark", help="Record a deterministic benchmark run")
+    add_common(benchmark)
+    benchmark.add_argument("--event-id", required=True)
+    benchmark.add_argument("--operation", required=True)
+    benchmark.add_argument("--task-id", required=True)
+    benchmark.add_argument("--scene", required=True)
+    benchmark.add_argument("--iterations", type=int, required=True)
+    benchmark.add_argument("--p95-ms", type=float, required=True)
+    benchmark.add_argument("--threshold-ms", type=float, required=True)
+    benchmark.add_argument("--status", choices=["pass", "fail"])
+    benchmark.add_argument("--evidence")
+    benchmark.set_defaults(func=cmd_record_benchmark)
+    summary = sub.add_parser("summary", help="Aggregate confirmed outcomes and benchmark history")
+    add_common(summary)
+    summary.add_argument("--output")
+    summary.set_defaults(func=cmd_summary)
+    validate = sub.add_parser("validate", help="Verify the append-only hash chain")
+    add_common(validate)
+    validate.set_defaults(func=cmd_validate)
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    try:
+        return int(args.func(args))
+    except (OSError, ValueError) as error:
+        print(f"MotionLoom remediation contract error: {error}", file=sys.stderr)
+        return 11
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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():
@@ -414,6 +441,8 @@ def check_report(args: argparse.Namespace) -> int:
     task = read_json(task_dir / "task.json")
     report = read_json(task_dir / "execution-report.json")
     manifest = read_json(task_dir / "artifact-manifest.json", {"artifacts": []})
+    scene_manifest_path = ROOT / "src" / "output" / str(task.get("scene", "")) / "manifest.json"
+    scene_manifest = read_json(scene_manifest_path, {})
     state = task.get("state")
     if not task.get("task_id") or not task.get("scene"):
         errors.append("task.json requires task_id and scene")
@@ -426,6 +455,26 @@ def check_report(args: argparse.Namespace) -> int:
             errors.append(f"artifact has invalid sha256: {artifact.get('path', '<unknown>')}")
         if not (task_dir / artifact.get("path", "")).is_file():
             errors.append(f"artifact path missing: {artifact.get('path', '<unknown>')}")
+    visual_truth_name = scene_manifest.get("visual_truth")
+    if visual_truth_name:
+        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":
@@ -517,6 +566,16 @@ def render(args: argparse.Namespace) -> int:
     lint = read_json(task_dir / "semantic-lint-report.json", {})
     continuity = read_json(task_dir / "continuity-report.json", {})
     fix_plan = read_json(task_dir / "fix-plan.json", {})
+    scene_manifest = read_json(ROOT / "src" / "output" / str(task.get("scene", "")) / "manifest.json", {})
+    visual_truth = read_json(
+        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)}",
         "",
@@ -543,6 +602,13 @@ def render(args: argparse.Namespace) -> int:
         "",
         "## Browser review",
         md_table(report.get("browser_review", []), [("Candidate", "candidate_id"), ("Decision", "decision"), ("Reviewer", "reviewer"), ("Evidence", "evidence")]),
+        "## Visual Truth",
+        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")]),