motionloom 2.1.0 → 2.2.0

package/scripts/discovery.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""Validate and expose MotionLoom's cross-agent discovery contract.
+
+The command is deliberately offline and read-only. It verifies that every
+Agent-facing surface points back to the canonical root SKILL.md, that install
+recipes name a deterministic verification command, and that the package can be
+discovered from a clean npm/Git/local checkout without inferring approval.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA_VERSION = "1.0"
+EXIT_OK = 0
+EXIT_USAGE = 2
+EXIT_INVALID = 11
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def load_json(path: Path) -> Any:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def relpath(path: Path, root: Path) -> str:
+    return path.relative_to(root).as_posix()
+
+
+def read_package(root: Path) -> dict[str, Any]:
+    package = load_json(root / "package.json")
+    return package if isinstance(package, dict) else {}
+
+
+def git_remote(root: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(root), "config", "--get", "remote.origin.url"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    value = result.stdout.strip()
+    return value or None
+
+
+def source_identity(root: Path) -> dict[str, Any]:
+    package = read_package(root)
+    return {
+        "name": package.get("name"),
+        "version": package.get("version"),
+        "root": str(root.resolve()),
+        "git_remote": git_remote(root),
+        "platform": platform.system().lower(),
+        "node_entrypoint": str((root / "bin" / "motionloom.mjs").resolve()),
+        "canonical_skill": str((root / "SKILL.md").resolve()),
+    }
+
+
+def validate(root: Path) -> dict[str, Any]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    root = root.resolve()
+    manifest_path = root / "agent-surfaces.json"
+
+    if not manifest_path.is_file():
+        return {"status": "fail", "errors": ["missing agent-surfaces.json"], "warnings": [], "root": str(root)}
+
+    try:
+        manifest = load_json(manifest_path)
+    except (OSError, json.JSONDecodeError) as exc:
+        return {"status": "fail", "errors": [f"invalid agent-surfaces.json: {exc}"], "warnings": [], "root": str(root)}
+
+    if manifest.get("schema_version") != SCHEMA_VERSION:
+        errors.append(f"unsupported schema_version: {manifest.get('schema_version')!r}")
+    package = read_package(root)
+    if manifest.get("name") != package.get("name"):
+        errors.append("manifest name does not match package.json")
+    if manifest.get("version") != package.get("version"):
+        errors.append("manifest version does not match package.json")
+    if manifest.get("canonical") != {
+        "skill": "SKILL.md",
+        "agent_card": "agent-card.json",
+        "cli": "bin/motionloom.mjs",
+    }:
+        errors.append("canonical paths do not match the package contract")
+
+    for required in ("SKILL.md", "agent-card.json", "bin/motionloom.mjs", "package.json"):
+        path = root / required
+        if not path.is_file():
+            errors.append(f"missing canonical file: {required}")
+
+    surfaces = manifest.get("surfaces")
+    if not isinstance(surfaces, list) or not surfaces:
+        errors.append("surfaces must be a non-empty array")
+        surfaces = []
+    ids: set[str] = set()
+    paths: set[str] = set()
+    for surface in surfaces:
+        if not isinstance(surface, dict):
+            errors.append("surface entry must be an object")
+            continue
+        surface_id = surface.get("id")
+        surface_path = surface.get("path")
+        if surface_id in ids:
+            errors.append(f"duplicate surface id: {surface_id}")
+        if isinstance(surface_id, str):
+            ids.add(surface_id)
+        if not isinstance(surface_path, str) or surface_path.startswith("/") or ".." in Path(surface_path).parts:
+            errors.append(f"surface path is not safe: {surface_path!r}")
+            continue
+        if surface_path in paths:
+            errors.append(f"duplicate surface path: {surface_path}")
+        paths.add(surface_path)
+        file_path = root / surface_path
+        if not file_path.is_file():
+            errors.append(f"missing surface file: {surface_path}")
+        if file_path.is_symlink():
+            errors.append(f"symlinked surface is not portable: {surface_path}")
+        if surface.get("canonical") != "SKILL.md":
+            errors.append(f"surface {surface_id!r} does not point to SKILL.md")
+        if surface.get("load_mode") not in {"alias", "router"}:
+            errors.append(f"surface {surface_id!r} has invalid load_mode")
+        if not isinstance(surface.get("agents"), list) or not surface.get("agents"):
+            errors.append(f"surface {surface_id!r} has no supported agents")
+
+    installations = manifest.get("installations")
+    if not isinstance(installations, list) or not installations:
+        errors.append("installations must be a non-empty array")
+        installations = []
+    installation_ids: set[str] = set()
+    for item in installations:
+        if not isinstance(item, dict):
+            errors.append("installation entry must be an object")
+            continue
+        item_id = item.get("id")
+        if item_id in installation_ids:
+            errors.append(f"duplicate installation id: {item_id}")
+        if isinstance(item_id, str):
+            installation_ids.add(item_id)
+        for key in ("source_kind", "command", "verification", "provenance"):
+            if not item.get(key):
+                errors.append(f"installation {item_id!r} missing {key}")
+
+    compatibility = manifest.get("compatibility", {})
+    for key in ("operating_systems", "node", "python", "agents"):
+        if not compatibility.get(key):
+            errors.append(f"compatibility missing {key}")
+    rules = manifest.get("rules", {})
+    if rules.get("canonical_instruction_source") != "SKILL.md":
+        errors.append("canonical_instruction_source must be SKILL.md")
+    for key in ("no_surface_copy", "no_network_required_for_check", "approval_is_never_inferred"):
+        if rules.get(key) is not True:
+            errors.append(f"rule {key} must remain true")
+
+    package_files = package.get("files", [])
+    for required_package_path in ("agent-surfaces.json", ".agents", ".claude", ".codex", "AGENTS.md"):
+        if required_package_path not in package_files:
+            warnings.append(f"package.json files does not explicitly include {required_package_path}")
+
+    return {
+        "status": "pass" if not errors else "fail",
+        "schema_version": SCHEMA_VERSION,
+        "root": str(root),
+        "source": source_identity(root),
+        "surface_count": len(surfaces),
+        "installation_count": len(installations),
+        "errors": errors,
+        "warnings": warnings,
+    }
+
+
+def install_matrix(root: Path) -> dict[str, Any]:
+    result = validate(root)
+    manifest = load_json(root / "agent-surfaces.json") if (root / "agent-surfaces.json").is_file() else {}
+    rows = []
+    for item in manifest.get("installations", []):
+        rows.append({
+            "id": item.get("id"),
+            "source_kind": item.get("source_kind"),
+            "command": item.get("command"),
+            "verification": item.get("verification"),
+            "provenance": item.get("provenance"),
+            "status": "available" if result.get("status") == "pass" else "blocked_by_contract",
+        })
+    return {"status": result.get("status"), "matrix": rows, "compatibility": manifest.get("compatibility", {}), "errors": result.get("errors", [])}
+
+
+def parser() -> argparse.ArgumentParser:
+    root_default = str(repo_root())
+    command = argparse.ArgumentParser(prog="motionloom discovery", description=__doc__)
+    sub = command.add_subparsers(dest="action", required=True)
+    for name, help_text in (
+        ("check", "Validate Agent surfaces and installation contract"),
+        ("show", "Print the canonical discovery manifest"),
+        ("source", "Print source identity for this checkout"),
+        ("install-matrix", "Print supported installation sources and verification commands"),
+    ):
+        child = sub.add_parser(name, help=help_text)
+        child.add_argument("--root", default=root_default, help="MotionLoom checkout root")
+        child.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    return command
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    root = Path(args.root).expanduser().resolve()
+    if args.action == "check":
+        result = validate(root)
+    elif args.action == "show":
+        try:
+            result = load_json(root / "agent-surfaces.json")
+        except (OSError, json.JSONDecodeError) as exc:
+            result = {"status": "fail", "errors": [str(exc)]}
+    elif args.action == "source":
+        result = source_identity(root)
+    else:
+        result = install_matrix(root)
+
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True))
+    else:
+        if args.action == "show":
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        elif args.action == "source":
+            print(f"{result.get('name')}@{result.get('version')} — {result.get('platform')} — {result.get('root')}")
+            if result.get("git_remote"):
+                print(f"remote: {result['git_remote']}")
+        elif args.action == "install-matrix":
+            print(f"installation matrix: {result.get('status')}")
+            for row in result.get("matrix", []):
+                print(f"- {row['id']}: {row['command']} -> {row['verification']}")
+        else:
+            print(f"discovery contract: {result.get('status')}")
+            for error in result.get("errors", []):
+                print(f"error: {error}")
+            for warning in result.get("warnings", []):
+                print(f"warning: {warning}")
+    return EXIT_OK if result.get("status") in {None, "pass"} else EXIT_INVALID
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except KeyboardInterrupt:
+        raise SystemExit(EXIT_USAGE)

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/visual-truth.schema.json", "schemas/remediation-history.schema.json", "project-context.example.json", "tests/evals/project-corpus.json"]:
     path = ROOT / relative
     try:
         json.loads(path.read_text(encoding="utf-8"))
@@ -36,6 +36,22 @@ 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}")
+
+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"]:

package/scripts/pr.py

@@ -94,6 +94,7 @@ def main() -> int:
         "--context", args.context or str(repo / "project-context.json"),
         "--task-dir", str(task_dir),
         "--require-browser-review",
+        "--require-visual-truth",
     ]
     print("== running context-bound quality gate ==")
     run(repo, [python, *quality_args])

package/scripts/quality-gate.py

@@ -47,6 +47,14 @@ 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 _json(path: Path):
     try:
         return json.loads(path.read_text(encoding="utf-8"))
@@ -66,7 +74,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) -> list[str]:
     issues = []
     manifest_path = scene_dir / "manifest.json"
     spec_path = scene_dir / "motion-spec.json"
@@ -326,6 +334,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 +381,7 @@ 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("--attestation")
     parser.add_argument("--trust-policy")
     args = parser.parse_args()
@@ -363,14 +402,15 @@ def main() -> int:
         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)
         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")
+            suffix = " + visual-truth contract" if args.require_visual_truth else ""
+            print(f"ACCEPTED {scene_dir.name}: context + spec + runtime snapshots + browser-review candidate + checklist{suffix}")
     return 1 if failed else 0