motionloom 2.0.0 → 2.2.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/render.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+MotionLoom render entrypoint.
+
+Style contract: evidence-first, explicit runtime mode and no hidden approval
+side effects. This is the cross-platform equivalent of render.sh and delegates
+to the canonical Python snapshot renderer without requiring Bash.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+
+SCENE_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Render MotionLoom runtime snapshots")
+    parser.add_argument("scene")
+    parser.add_argument("--repo", default=None, help="Repository root; defaults to the script parent")
+    parser.add_argument("--progress", default="0,50,100")
+    parser.add_argument("--allow-placeholder", action="store_true")
+    args = parser.parse_args()
+
+    if not SCENE_RE.fullmatch(args.scene):
+        parser.error("scene id contains unsafe path characters")
+
+    repo = Path(args.repo).expanduser().resolve() if args.repo else Path(__file__).resolve().parents[1]
+    scene_dir = repo / "src" / "output" / args.scene
+    if not scene_dir.is_dir():
+        print(f"error: scene directory not found: {scene_dir}", file=sys.stderr)
+        return 1
+
+    try:
+        progress = [int(value) for value in args.progress.split(",") if value.strip()]
+    except ValueError:
+        print("error: progress must be a comma-separated list of integers", file=sys.stderr)
+        return 1
+
+    if not progress or any(value < 0 or value > 100 for value in progress):
+        print("error: progress values must be between 0 and 100", file=sys.stderr)
+        return 1
+
+    # Import by path-independent package layout. The repository root is added
+    # only for this process; no cwd or shell-specific import assumptions.
+    sys.path.insert(0, str(repo))
+    from src.core.snapshot import render_snapshots  # pylint: disable=import-outside-toplevel
+
+    result = render_snapshots(
+        args.scene,
+        scene_dir,
+        progress,
+        allow_placeholder=args.allow_placeholder or os.environ.get("ALLOW_PLACEHOLDER") == "1",
+    )
+    print(__import__("json").dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/report.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import argparse
 import hashlib
 import json
+import shutil
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -49,6 +50,39 @@ def read_json(path: Path, default: dict | list | None = None):
     return json.loads(path.read_text(encoding="utf-8"))
 
 
+def project_memory_path() -> Path:
+    return ROOT / ".motionloom" / "project-memory.json"
+
+
+def memory_summary() -> dict | None:
+    path = project_memory_path()
+    if not path.is_file():
+        return None
+    try:
+        memory = read_json(path)
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+    except (OSError, json.JSONDecodeError):
+        return {"path": ".motionloom/project-memory.json", "status": "invalid"}
+    freshness = memory.get("freshness") if isinstance(memory, dict) else {}
+    return {
+        "path": ".motionloom/project-memory.json",
+        "snapshot_path": "project-memory.json",
+        "memory_id": memory.get("memory_id"),
+        "status": freshness.get("status", "invalid"),
+        "sha256": digest,
+        "updated_at": memory.get("updated_at"),
+    }
+
+
+def sync_memory_snapshot(task_dir: Path) -> dict | None:
+    source = project_memory_path()
+    if not source.is_file():
+        return None
+    destination = task_dir / "project-memory.json"
+    shutil.copy2(source, destination)
+    return memory_summary()
+
+
 def has_symlink_component(path: Path) -> bool:
     current = path
     while True:
@@ -78,6 +112,7 @@ def candidate_is_current(candidate: dict) -> bool:
 def init_task(args: argparse.Namespace) -> int:
     task_dir = Path(args.output or ROOT / "artifacts" / args.task_id).resolve()
     timestamp = now()
+    memory = memory_summary()
     task = {
         "schema_version": "1.0",
         "task_id": args.task_id,
@@ -92,6 +127,8 @@ def init_task(args: argparse.Namespace) -> int:
         "created_at": timestamp,
         "updated_at": timestamp,
     }
+    if memory:
+        task["project_memory"] = memory
     report = {
         "report_version": "1.0",
         "task_id": args.task_id,
@@ -103,7 +140,7 @@ def init_task(args: argparse.Namespace) -> int:
         "problems": [],
         "structure_review": {"missing_files": [], "broken_references": [], "untracked_artifacts": []},
         "browser_review": [],
-        "next_agent": [{"agent": args.agent, "action": "Run project analysis and populate context before generation."}],
+        "next_agent": [{"agent": args.agent, "action": "Recover Project Memory and run project analysis before generation.", "evidence_needed": ["project-memory.json", "project-context.json"]}],
         "generated_at": timestamp,
     }
     handoff = {
@@ -114,7 +151,7 @@ def init_task(args: argparse.Namespace) -> int:
         "state": "created",
         "summary": "New animation task initialized.",
         "next_actions": [{"action": "Analyze host project context", "skill": "motionloom", "evidence_needed": ["project-context.json"]}],
-        "required_artifacts": ["task.json", "execution-report.json", *EVIDENCE_ARTIFACTS],
+        "required_artifacts": ["task.json", "execution-report.json", *EVIDENCE_ARTIFACTS, *( ["project-memory.json"] if memory else [] )],
         "blockers": [],
     }
     write_json(task_dir / "task.json", task)
@@ -122,6 +159,8 @@ def init_task(args: argparse.Namespace) -> int:
     write_json(task_dir / "issue-register.json", {"version": "1.0", "task_id": args.task_id, "issues": []})
     write_json(task_dir / "handoff.json", handoff)
     write_json(task_dir / "artifact-manifest.json", {"manifest_version": "1.0", "task_id": args.task_id, "generated_at": timestamp, "artifacts": []})
+    if memory:
+        sync_memory_snapshot(task_dir)
     (task_dir / "decision-log.jsonl").write_text("", encoding="utf-8")
     print(json.dumps({"status": "created", "task_id": args.task_id, "task_dir": str(task_dir)}, ensure_ascii=False))
     return 0
@@ -130,6 +169,7 @@ def init_task(args: argparse.Namespace) -> int:
 def collect(args: argparse.Namespace) -> int:
     task_dir = Path(args.task_dir).resolve()
     task = read_json(task_dir / "task.json")
+    sync_memory_snapshot(task_dir)
     excluded = {"artifact-manifest.json", "execution-report.json", "decision-log.jsonl"}
     artifacts = []
     for path in sorted(task_dir.rglob("*")):
@@ -146,6 +186,8 @@ def collect(args: argparse.Namespace) -> int:
         handoff = read_json(handoff_path)
         required = set(handoff.get("required_artifacts", []))
         required.update(name for name in EVIDENCE_ARTIFACTS if (task_dir / name).is_file())
+        if (task_dir / "project-memory.json").is_file():
+            required.add("project-memory.json")
         handoff["required_artifacts"] = sorted(required)
         write_json(handoff_path, handoff)
     print(json.dumps({"status": "collected", "task_id": manifest["task_id"], "artifact_count": len(artifacts)}, ensure_ascii=False))
@@ -372,6 +414,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")
@@ -384,6 +428,11 @@ 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")
     if state in {"validated", "ready_for_pr", "confirmed"}:
         quality = read_json(task_dir / "quality-report.json")
         if quality.get("status") != "pass":
@@ -475,6 +524,11 @@ 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 {}
     lines = [
         f"# Animation Task Report — {task.get('task_id', task_dir.name)}",
         "",
@@ -501,6 +555,10 @@ 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', []))}**",
         "## 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/review-hook.py

@@ -7,6 +7,7 @@ import argparse
 import hashlib
 import json
 import re
+import shutil
 import subprocess
 import sys
 from datetime import datetime, timedelta, timezone
@@ -68,6 +69,11 @@ def prepare(args: argparse.Namespace) -> int:
     if not scene:
         raise ValueError("task.json requires scene")
     scene_dir, source_path, render_meta, context_path = paths(task_dir, task)
+    memory_path = ROOT / ".motionloom" / "project-memory.json"
+    memory = read_json(memory_path, {}) if memory_path.is_file() else {}
+    memory_status = (memory.get("freshness") or {}).get("status")
+    if memory_path.is_file() and memory_status not in {"fresh", None}:
+        raise ValueError(f"project memory is {memory_status}; run motionloom memory refresh/analyze before browser review")
     spec = read_json(scene_dir / "motion-spec.json")
     context_hash = (spec.get("context_binding") or {}).get("context_sha256") or sha256(context_path)
     source_hash = sha256(source_path)
@@ -92,6 +98,9 @@ def prepare(args: argparse.Namespace) -> int:
         "prepared_at": now(),
         "expires_at": (datetime.now(timezone.utc) + CANDIDATE_TTL).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
     }
+    if memory_path.is_file():
+        candidate["project_memory_sha256"] = sha256(memory_path)
+        candidate["project_memory_id"] = memory.get("memory_id")
     (scene_dir / "browser-review.json").write_text(json.dumps(candidate, indent=2) + "\n", encoding="utf-8")
     task["state"] = "review_required"
     task["updated_at"] = now()
@@ -109,9 +118,11 @@ def prepare(args: argparse.Namespace) -> int:
     report_path.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     handoff_path = task_dir / "handoff.json"
     handoff = read_json(handoff_path)
-    handoff.update({"state": "review_required", "to_agent": "browser-review-agent", "summary": "Open the exact rendered candidate in the internal Dev Lab and obtain user approval before PR.", "next_actions": [{"action": "Open internal Dev Lab candidate", "kind": "browser_review", "agent": "browser-review-agent", "skill": "browser-review", "url": url, "candidate_id": cid, "requires_user_approval": True, "evidence_needed": ["review.json"], "output_artifacts": ["review.json"]}], "required_artifacts": sorted(set(handoff.get("required_artifacts", []) + ["browser-review.json", "review.json", "semantic-lint-benchmark.json", "evidence-verifier-report.json", "runtime-adapters/runtime-evidence.json"]))})
+    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_path.write_text(json.dumps(handoff, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    subprocess.run(["bash", str(ROOT / "scripts/devlab.sh"), scene, "--prepare-only", str(task_dir)], check=True, capture_output=True, text=True)
+    subprocess.run([sys.executable, str(ROOT / "scripts/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)
     print(json.dumps({"status": "review_required", "task_id": task["task_id"], "candidate_id": cid, "url": url, "agent": "browser-review-agent", "action": "Open this exact URL in the internal browser; ask the user to inspect frames 0/50/100 and approve or request changes.", "requires_user_approval": True, "output_artifacts": ["review.json"]}, ensure_ascii=False))
     return 0

package/scripts/skill-doctor.py

@@ -13,7 +13,16 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[1]
 REQUIRED_FILES = ["SKILL.md", "agent-card.json", "package.json"]
 REQUIRED_DIRS = ["scripts", "templates", "references", "schemas"]
-REQUIRED_SCRIPT_FILES = ["scripts/report-contract.py", "scripts/review-hook.py", "scripts/quality-gate.py", "scripts/runtime-adapters.mjs"]
+REQUIRED_SCRIPT_FILES = [
+    "scripts/report-contract.py",
+    "scripts/review-hook.py",
+    "scripts/quality-gate.py",
+    "scripts/runtime-adapters.mjs",
+    "scripts/project-memory.py",
+    "scripts/project_memory_loader.py",
+    "scripts/analyze.py",
+    "scripts/devlab.py",
+]
 REQUIRED_SCHEMAS = [
     "task.schema.json",
     "execution-report.schema.json",
@@ -26,6 +35,7 @@ REQUIRED_SCHEMAS = [
     "provenance.schema.json",
     "capability-registry.schema.json",
     "motion-ir.schema.json",
+    "project-memory.schema.json",
 ]
 
 
@@ -121,7 +131,7 @@ def run() -> int:
     package_path = ROOT / "package.json"
     try:
         package = json.loads(package_path.read_text(encoding="utf-8"))
-        for script in ("test", "validate", "doctor", "report", "report:check", "review"):
+        for script in ("test", "validate", "doctor", "report", "report:check", "review", "memory:bootstrap", "memory:recover", "memory:validate", "devlab", "pack:dotlottie"):
             if script not in package.get("scripts", {}):
                 warnings.append({"code": "missing_package_script", "message": f"package.json has no {script} script."})
     except (FileNotFoundError, json.JSONDecodeError) as exc: