motionloom 2.0.0 → 2.2.0

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "motionloom",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "type": "module",
-  "description": "MotionLoom: project-aware animation Skill with graph, provenance, Motion IR, runtime telemetry, DSSE-compatible signed attestation, external evidence verification and Dev Lab review.",
+  "packageManager": "pnpm@11.20.0",
+  "description": "MotionLoom: project-aware animation Skill with Agent interoperability, graph, provenance, Motion IR, runtime telemetry, Visual Truth, Remediation Learning, DSSE-compatible signed attestation, external evidence verification and Dev Lab review.",
+  "author": "lenhonbp",
   "bin": {
     "motionloom": "bin/motionloom.mjs"
   },
   "files": [
     "README.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md",
+    "SUPPORT.md",
     "SKILL.md",
     "LICENSE",
     "agent-card.json",
@@ -23,7 +31,13 @@
     "project-context.example.json",
     "tests/evals",
     "tests/scripts/run_tests.py",
-    "tests/scripts/test_attestation.py"
+    "tests/scripts/test_attestation.py",
+    "tests/scripts/test_project_memory.py",
+    ".agents",
+    ".claude",
+    ".codex",
+    "AGENTS.md",
+    "agent-surfaces.json"
   ],
   "keywords": [
     "animation",
@@ -35,7 +49,16 @@
     "gsap",
     "framer-motion",
     "runtime-evidence",
-    "developer-tools"
+    "developer-tools",
+    "project-memory",
+    "motion-ir",
+    "provenance",
+    "attestation",
+    "browser-review",
+    "dev-lab",
+    "visual-truth",
+    "remediation-learning",
+    "agent-interoperability"
   ],
   "repository": {
     "type": "git",
@@ -53,35 +76,53 @@
     "python": ">=3.11"
   },
   "scripts": {
-    "prepack": "find . -type d -name __pycache__ -prune -exec rm -rf {} + && find . -type f \\( -name '*.pyc' -o -name '*.pyo' \\) -delete",
-    "test": "python3 tests/scripts/run_tests.py",
-    "validate": "python3 scripts/quality-gate.py --all",
-    "doctor": "python3 scripts/skill-doctor.py --json",
-    "report": "python3 scripts/report.py",
-    "report:check": "python3 scripts/report-contract.py",
-    "review": "python3 scripts/review-hook.py",
-    "manifest": "python3 scripts/manifest.py",
-    "intelligence": "python3 scripts/intelligence.py",
-    "intelligence:registry": "python3 scripts/intelligence.py capabilities build --output capability-registry.json",
-    "intelligence:registry:check": "python3 scripts/intelligence.py capabilities validate --path capability-registry.json",
-    "intelligence:p1": "python3 scripts/intelligence.py",
-    "quality:p1": "python3 scripts/quality-gate.py --require-intelligence --require-p1 --require-benchmark",
-    "eval:intelligence": "python3 scripts/eval-intelligence.py",
-    "benchmark:semantic": "python3 scripts/intelligence.py semantic-lint benchmark --task-dir artifacts/professional-review-e2e --iterations 25 --threshold-ms 500",
-    "evidence:verify": "python3 scripts/evidence-verifier.py --scene-dir src/output/browser-review-smoke --task-dir artifacts/browser-review-smoke-task --runtime-evidence runtime-adapters/runtime-evidence.json --max-age-days 1 --output artifacts/browser-review-smoke-task/evidence-verifier-report.json",
-    "attestation:build": "python3 scripts/attestation.py build",
-    "attestation:verify": "python3 scripts/attestation-verifier.py",
-    "attestation:policy": "python3 scripts/attestation.py validate-policy",
-    "attestation:keygen": "python3 scripts/attestation-keygen.py",
-    "quality:telemetry": "python3 scripts/quality-gate.py --scene browser-review-smoke --context artifacts/browser-review-smoke-task/project-context.json --task-dir artifacts/browser-review-smoke-task --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry",
-    "quality:attestation": "python3 scripts/quality-gate.py --scene browser-review-smoke --context artifacts/browser-review-smoke-task/project-context.json --task-dir artifacts/browser-review-smoke-task --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation",
-    "pack:dotlottie": "bash scripts/to-dotlottie.sh",
-    "runtime:test": "node scripts/runtime-adapters.mjs"
+    "prepack": "node scripts/prepack-clean.mjs",
+    "test": "node bin/motionloom.mjs test",
+    "validate": "npm run quality:attestation",
+    "doctor": "node bin/motionloom.mjs doctor --json",
+    "docs:check": "python3 scripts/docs-audit.py",
+    "eval:projects": "python3 scripts/eval-projects.py --allow-insufficient",
+    "release:verify": "python3 scripts/release-verify.py",
+    "report": "node bin/motionloom.mjs report",
+    "report:check": "node bin/motionloom.mjs report-contract",
+    "review": "node bin/motionloom.mjs review-hook",
+    "devlab": "node bin/motionloom.mjs devlab",
+    "manifest": "node bin/motionloom.mjs manifest",
+    "intelligence": "node bin/motionloom.mjs intelligence",
+    "intelligence:registry": "node bin/motionloom.mjs intelligence capabilities build --output capability-registry.json",
+    "intelligence:registry:check": "node bin/motionloom.mjs intelligence capabilities validate --path capability-registry.json",
+    "intelligence:p1": "node bin/motionloom.mjs intelligence",
+    "quality:p1": "node bin/motionloom.mjs quality-gate --require-intelligence --require-p1 --require-benchmark",
+    "eval:intelligence": "node bin/motionloom.mjs eval-intelligence",
+    "audit:deep": "node bin/motionloom.mjs deep-audit --iterations 5000 --seed 20260813 --report docs/audits/data/deep-stress-latest.json",
+    "memory:init": "node bin/motionloom.mjs memory init --project-root .",
+    "memory:bootstrap": "node bin/motionloom.mjs analyze . --init-memory",
+    "memory:recover": "node bin/motionloom.mjs memory recover --project-root .",
+    "memory:validate": "node bin/motionloom.mjs memory validate --project-root . --json",
+    "memory:refresh": "node bin/motionloom.mjs memory refresh --project-root . --json",
+    "benchmark:semantic": "node bin/motionloom.mjs intelligence semantic-lint benchmark --task-dir artifacts/professional-review-e2e --iterations 25 --threshold-ms 500",
+    "evidence:verify": "node bin/motionloom.mjs evidence-verify --scene-dir src/output/browser-review-smoke --task-dir artifacts/browser-review-smoke-task --runtime-evidence runtime-adapters/runtime-evidence.json --max-age-days 1 --output artifacts/browser-review-smoke-task/evidence-verifier-report.json",
+    "attestation:build": "node bin/motionloom.mjs attestation build",
+    "attestation:verify": "node bin/motionloom.mjs verify-attestation",
+    "attestation:policy": "node bin/motionloom.mjs attestation validate-policy",
+    "attestation:keygen": "node bin/motionloom.mjs attestation-keygen",
+    "quality:telemetry": "node bin/motionloom.mjs quality-gate --scene browser-review-smoke --context artifacts/browser-review-smoke-task/project-context.json --task-dir artifacts/browser-review-smoke-task --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry",
+    "quality:attestation": "node bin/motionloom.mjs quality-gate --scene browser-review-smoke --context artifacts/browser-review-smoke-task/project-context.json --task-dir artifacts/browser-review-smoke-task --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation --require-visual-truth",
+    "pack:dotlottie": "node scripts/to-dotlottie.mjs",
+    "runtime:test": "node scripts/runtime-adapters.mjs",
+    "visual-truth:build": "node bin/motionloom.mjs visual-truth build",
+    "visual-truth:check": "node bin/motionloom.mjs visual-truth validate --root . --input src/output/browser-review-smoke/visual-truth.json",
+    "remediation:validate": "node bin/motionloom.mjs remediation-learning validate --history artifacts/remediation-history.jsonl --json",
+    "remediation:summary": "node bin/motionloom.mjs remediation-learning summary --history artifacts/remediation-history.jsonl --output artifacts/remediation-summary.json --json",
+    "discovery:check": "node bin/motionloom.mjs discovery check --root . --json",
+    "discovery:show": "node bin/motionloom.mjs discovery show --root . --json",
+    "install:matrix": "node bin/motionloom.mjs discovery install-matrix --root . --json"
   },
   "dependencies": {
     "@lottiefiles/dotlottie-web": "^0.79.0",
     "@napi-rs/canvas": "^1.0.5",
     "@rive-app/canvas": "^2.39.2",
+    "fflate": "^0.8.3",
     "framer-motion": "^13.1.0",
     "gsap": "^3.15.0",
     "react": "^19.2.8",

package/references/agent-interoperability.md

@@ -0,0 +1,29 @@
+# Agent interoperability reference
+
+Read this reference when installing MotionLoom into a new Agent environment or when adding a new discovery surface.
+
+## Contract hierarchy
+
+1. `SKILL.md` is the canonical workflow and must stay below the skill context budget.
+2. `agent-card.json` is the machine-readable capability and side-effect contract.
+3. `agent-surfaces.json` is the discovery/install/compatibility contract.
+4. `.agents/skills`, `.claude`, `.codex` and `AGENTS.md` are short routers that point to the canonical sources.
+5. `docs/AGENT-INTEGRATION.md` is user-facing installation and troubleshooting documentation.
+
+Do not put divergent workflow rules into an Agent-specific file. Add reusable domain detail to `references/` or `docs/`, then update the canonical Skill navigation.
+
+## Discovery check output
+
+The JSON result contains `status`, `source`, `surface_count`, `installation_count`, `errors` and `warnings`. `status=pass` means the local package has the expected files and contract values. It does not assert that the host project has been analyzed, that runtime dependencies are installed, that a candidate rendered correctly or that a user approved a change.
+
+## Adding a new Agent surface
+
+Add one manifest entry with a safe relative path, a supported agent identifier, `canonical: SKILL.md` and either `load_mode: alias` or `load_mode: router`. Create a short file at that path. Add or update the installation/discovery test and run `motionloom discovery check --root . --json`, `python3 scripts/docs-audit.py` and the full test suite. Never silently overwrite an existing surface with a copied version of `SKILL.md`.
+
+## Source and version binding
+
+When a user reports a discovery issue, capture the package version, source kind, resolved path, Git remote/commit where available and the discovery JSON. Treat a version mismatch as a structural problem, not as a runtime animation failure. Do not use network access in the check command; registry/Git availability belongs to the installation step.
+
+## Approval boundary
+
+Discovery is deliberately orthogonal to approval. The discovery command can only tell an Agent how to load MotionLoom. It cannot transition an animation task to `ready_for_pr` or `confirmed`, and it cannot change `approval` from `false` to `true`.

package/references/intelligence-core.md

@@ -13,8 +13,10 @@ Use this reference when an Agent needs to understand or extend MotionLoom's task
 | `replay-bundle.json` | `python3 scripts/intelligence.py replay capture --root <root> --task-dir <task>` | Captures clean-root artifact hashes and environment metadata; verification fails on mutation or omission. |
 | `semantic-lint-report.json` | `python3 scripts/intelligence.py semantic-lint build --task-dir <task>` | Reports intent, timing, easing, accessibility, performance and anti-pattern findings with severity, confidence and evidence. |
 | `semantic-lint-benchmark.json` | `python3 scripts/intelligence.py semantic-lint benchmark --task-dir <task>` | Measures in-process semantic-lint execution, rule coverage and p95 against a deterministic threshold; it is a performance contract, not visual approval. |
-| `runtime-telemetry.json` | `bash scripts/capture-runtime-telemetry.sh <scene> artifacts/<task-id>` | Records deterministic scrub-point observations, RAF timing, runtime state hashes and source/manifest/Motion IR bindings from the real adapter harness. |
+| `runtime-telemetry.json` | `motionloom runtime-telemetry <scene> artifacts/<task-id>` | Records deterministic scrub-point observations, RAF timing, runtime state hashes and source/manifest/Motion IR bindings from the real adapter harness. The npm CLI is the cross-platform entrypoint; the legacy `.sh` wrapper remains for Unix compatibility. |
 | `evidence-verifier-report.json` | `python3 scripts/evidence-verifier.py --scene-dir <scene-dir> --task-dir <task> --runtime-evidence <path>` | Read-only external verification result for task/scene/path/hash/age integrity; `approval` is always `false`. |
+| `visual-truth.json` | `motionloom visual-truth build|validate` | Baseline/candidate PNG hashes, dimensions, deterministic comparison signal, region-level review explanation and source/runtime/Motion IR provenance; `approval` is always `false`. |
+| `remediation-history.jsonl` | `motionloom remediation-learning record-outcome|record-benchmark|summary` | Append-only, hash-chained user-confirmed corrections and deterministic benchmark runs; first-pass metrics guide future work but `approval` is always `false`. |
 | `attestation-statement.json` | `python3 scripts/attestation.py statement --scene-dir <scene-dir> --task-dir <task> --context <context>` | Derives canonical task/scene/source/manifest/Motion IR/evidence hash bindings before signing. |
 | `attestation.json` | `python3 scripts/attestation.py build --statement <statement> --private-key <key> --key-id <id>` | DSSE-compatible Ed25519 envelope over the versioned statement; `approval` is always `false`. |
 | `trust-policy.json` | `python3 scripts/attestation.py validate-policy --path <policy>` | Declares trusted keys, validity, rotation and fail-closed revocation behavior. |
@@ -71,6 +73,8 @@ python3 scripts/quality-gate.py \
   --context <project-context.json> \
   --task-dir artifacts/<task-id> \
   --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation
+python3 scripts/remediation-learning.py validate --history artifacts/remediation-history.jsonl --json
+python3 scripts/remediation-learning.py summary --history artifacts/remediation-history.jsonl --output artifacts/remediation-summary.json --json
 python3 scripts/eval-intelligence.py
 ```
 

package/schemas/agent-surfaces.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/agent-surfaces.schema.json",
+  "title": "MotionLoom Agent Surfaces",
+  "type": "object",
+  "required": ["schema_version", "name", "version", "canonical", "surfaces", "installations", "compatibility", "rules"],
+  "properties": {
+    "schema_version": {"const": "1.0"},
+    "name": {"const": "motionloom"},
+    "version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"},
+    "canonical": {
+      "type": "object",
+      "required": ["skill", "agent_card", "cli"],
+      "properties": {
+        "skill": {"const": "SKILL.md"},
+        "agent_card": {"const": "agent-card.json"},
+        "cli": {"const": "bin/motionloom.mjs"}
+      },
+      "additionalProperties": false
+    },
+    "surfaces": {
+      "type": "array",
+      "minItems": 4,
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "path", "canonical", "load_mode", "agents"],
+        "properties": {
+          "id": {"type": "string", "pattern": "^[a-z0-9-]+$"},
+          "kind": {"type": "string", "enum": ["agent-skill", "agent-instructions", "repository-guide"]},
+          "path": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"},
+          "canonical": {"const": "SKILL.md"},
+          "load_mode": {"type": "string", "enum": ["alias", "router"]},
+          "agents": {"type": "array", "minItems": 1, "items": {"type": "string"}}
+        },
+        "additionalProperties": false
+      }
+    },
+    "installations": {
+      "type": "array",
+      "minItems": 3,
+      "items": {
+        "type": "object",
+        "required": ["id", "source_kind", "command", "verification", "provenance"],
+        "properties": {
+          "id": {"type": "string"},
+          "source_kind": {"type": "string", "enum": ["npm", "git", "local"]},
+          "command": {"type": "string"},
+          "verification": {"type": "string"},
+          "provenance": {"type": "string"}
+        },
+        "additionalProperties": false
+      }
+    },
+    "compatibility": {
+      "type": "object",
+      "required": ["operating_systems", "node", "python", "agents"],
+      "properties": {
+        "operating_systems": {"type": "array", "items": {"type": "string"}},
+        "node": {"type": "string"},
+        "python": {"type": "string"},
+        "agents": {"type": "array", "items": {"type": "string"}}
+      },
+      "additionalProperties": false
+    },
+    "rules": {
+      "type": "object",
+      "required": ["canonical_instruction_source", "no_surface_copy", "no_network_required_for_check", "approval_is_never_inferred"],
+      "properties": {
+        "canonical_instruction_source": {"const": "SKILL.md"},
+        "no_surface_copy": {"const": true},
+        "no_network_required_for_check": {"const": true},
+        "approval_is_never_inferred": {"const": true}
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/project-memory.schema.json

@@ -0,0 +1,180 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/project-memory.schema.json",
+  "title": "MotionLoom Project Memory",
+  "description": "Durable, relocatable project memory for recovering animation decisions and context across Agent sessions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "memory_id",
+    "created_at",
+    "updated_at",
+    "project",
+    "context",
+    "motion_principles",
+    "policies",
+    "decisions",
+    "rejected_patterns",
+    "remediation",
+    "freshness",
+    "recovery"
+  ],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "memory_id": { "type": "string", "pattern": "^pm-[a-z0-9][a-z0-9._-]*$" },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["project_id", "name", "root_path", "repository"],
+      "properties": {
+        "project_id": { "type": "string", "minLength": 3 },
+        "name": { "type": "string", "minLength": 1 },
+        "root_path": { "type": "string", "minLength": 1 },
+        "repository": { "type": ["string", "null"] },
+        "package_name": { "type": ["string", "null"] }
+      }
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256", "schema_version"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "sha256": { "type": ["string", "null"], "pattern": "^$|^[a-f0-9]{64}$" },
+        "schema_version": { "type": ["string", "null"] },
+        "generated_at": { "type": ["string", "null"] }
+      }
+    },
+    "motion_principles": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["duration_ms", "easing", "rhythm", "reduced_motion", "notes"],
+      "properties": {
+        "duration_ms": { "type": ["number", "null"], "minimum": 0 },
+        "easing": { "type": ["string", "null"] },
+        "rhythm": { "type": ["string", "null"] },
+        "reduced_motion": { "type": ["string", "null"] },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "policies": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["asset", "runtime"],
+      "properties": {
+        "asset": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["authoritative_sources", "license_required", "unknown_asset_policy"],
+          "properties": {
+            "authoritative_sources": { "type": "array", "items": { "type": "string" } },
+            "license_required": { "type": "boolean" },
+            "unknown_asset_policy": { "type": "string", "enum": ["block", "review", "allow"] }
+          }
+        },
+        "runtime": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["preferred_frameworks", "verified_runtimes", "browser_matrix"],
+          "properties": {
+            "preferred_frameworks": { "type": "array", "items": { "type": "string" } },
+            "verified_runtimes": { "type": "array", "items": { "type": "string" } },
+            "browser_matrix": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/decision" }
+    },
+    "rejected_patterns": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/rejectedPattern" }
+    },
+    "remediation": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/remediation" }
+    },
+    "freshness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "checked_at", "context_hash", "project_fingerprint", "reason"],
+      "properties": {
+        "status": { "type": "string", "enum": ["fresh", "stale", "needs_context", "invalid"] },
+        "checked_at": { "type": "string", "format": "date-time" },
+        "context_hash": { "type": ["string", "null"], "pattern": "^$|^[a-f0-9]{64}$" },
+        "project_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "recovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["last_task_id", "next_actions"],
+      "properties": {
+        "last_task_id": { "type": ["string", "null"] },
+        "next_actions": { "type": "array", "items": { "type": "string" } },
+        "last_review_state": { "type": ["string", "null"] }
+      }
+    },
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["canonical_sha256"],
+      "properties": {
+        "canonical_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    }
+  },
+  "$defs": {
+    "decision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "recorded_at", "status", "summary", "rationale", "user_confirmed", "source_task_id", "evidence"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+        "recorded_at": { "type": "string", "format": "date-time" },
+        "status": { "type": "string", "enum": ["accepted", "rejected", "superseded"] },
+        "summary": { "type": "string", "minLength": 1 },
+        "rationale": { "type": "string" },
+        "user_confirmed": { "type": "boolean" },
+        "source_task_id": { "type": ["string", "null"] },
+        "evidence": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "rejectedPattern": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "recorded_at", "pattern", "reason", "source_task_id"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+        "recorded_at": { "type": "string", "format": "date-time" },
+        "pattern": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string" },
+        "source_task_id": { "type": ["string", "null"] }
+      }
+    },
+    "remediation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "recorded_at", "issue_id", "summary", "root_cause", "resolution", "result", "correction_count", "rerun_scope", "user_confirmed", "source_task_id"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+        "recorded_at": { "type": "string", "format": "date-time" },
+        "issue_id": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 },
+        "root_cause": { "type": "string" },
+        "resolution": { "type": "string" },
+        "result": { "type": "string", "enum": ["pass", "fail", "partial", "unknown"] },
+        "correction_count": { "type": "integer", "minimum": 0 },
+        "rerun_scope": { "type": "array", "items": { "type": "string" } },
+        "user_confirmed": { "type": "boolean" },
+        "source_task_id": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/schemas/remediation-history.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/lenhonbp/MotionLoom/blob/main/schemas/remediation-history.schema.json",
+  "title": "MotionLoom remediation and benchmark history event",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version", "event_id", "event_type", "recorded_at", "previous_event_sha256", "event_sha256"],
+  "properties": {
+    "schema_version": {"const": "0.1"},
+    "event_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$"},
+    "event_type": {"type": "string", "enum": ["remediation_outcome", "benchmark_run"]},
+    "recorded_at": {"type": "string", "format": "date-time"},
+    "previous_event_sha256": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"},
+    "event_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+    "user_confirmed": {"type": "boolean"},
+    "first_pass_accepted": {"type": "boolean"},
+    "correction_count": {"type": "integer", "minimum": 0},
+    "result": {"type": "string", "enum": ["pass", "fail", "partial", "unknown"]},
+    "status": {"type": "string", "enum": ["pass", "fail"]},
+    "p95_ms": {"type": "number", "minimum": 0},
+    "threshold_ms": {"type": "number", "exclusiveMinimum": 0}
+  }
+}

package/schemas/scene-manifest.schema.json

@@ -11,6 +11,7 @@
     "category": {"type": "string", "minLength": 1},
     "file": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\.\\.).+$"},
     "runtime_evidence": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\.\\.).+$"},
+    "visual_truth": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\.\\.).+$"},
     "source_binding": {
       "type": "object",
       "required": ["kind", "source_path", "authority", "license", "sha256"],

package/schemas/visual-truth.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/lenhonbp/MotionLoom/blob/main/schemas/visual-truth.schema.json",
+  "title": "MotionLoom Visual Truth Contract",
+  "type": "object",
+  "required": ["schema_version", "contract", "status", "scene", "frames", "comparison", "provenance", "review_boundary"],
+  "properties": {
+    "schema_version": {"const": "1.0"},
+    "contract": {"const": "motionloom-visual-truth"},
+    "status": {"enum": ["pass", "review_required"]},
+    "scene": {"type": "string", "minLength": 1},
+    "task_id": {"type": ["string", "null"]},
+    "frames": {
+      "type": "object",
+      "required": ["baseline", "candidate"],
+      "properties": {
+        "baseline": {"$ref": "#/$defs/frame"},
+        "candidate": {"$ref": "#/$defs/frame"}
+      },
+      "additionalProperties": false
+    },
+    "comparison": {
+      "type": "object",
+      "required": ["metric", "same_dimensions", "byte_identical", "changed", "interpretation"],
+      "properties": {
+        "metric": {"type": "string"},
+        "same_dimensions": {"type": "boolean"},
+        "byte_identical": {"type": "boolean"},
+        "changed": {"type": "boolean"},
+        "distance": {"type": "number", "minimum": 0},
+        "threshold": {"type": "number", "minimum": 0},
+        "interpretation": {"enum": ["equal", "review_required"]}
+      },
+      "additionalProperties": true
+    },
+    "regions": {"type": "array"},
+    "provenance": {
+      "type": "object",
+      "required": ["source_path", "source_sha256", "manifest_path", "manifest_sha256"],
+      "properties": {
+        "source_path": {"type": "string", "pattern": "^(?!/)(?!.*\\.\\.).+$"},
+        "source_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "manifest_path": {"type": "string", "pattern": "^(?!/)(?!.*\\.\\.).+$"},
+        "manifest_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "runtime_evidence_path": {"type": ["string", "null"]},
+        "runtime_evidence_sha256": {"type": ["string", "null"]},
+        "motion_ir_path": {"type": ["string", "null"]},
+        "motion_ir_sha256": {"type": ["string", "null"]}
+      },
+      "additionalProperties": true
+    },
+    "review_boundary": {
+      "type": "object",
+      "required": ["approval", "user_review_required", "decision"],
+      "properties": {
+        "approval": {"const": false},
+        "user_review_required": {"const": true},
+        "decision": {"const": "pending"}
+      },
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "frame": {
+      "type": "object",
+      "required": ["role", "percent", "path", "sha256", "bytes", "width", "height"],
+      "properties": {
+        "role": {"enum": ["baseline", "candidate"]},
+        "percent": {"type": "integer", "minimum": 0, "maximum": 100},
+        "path": {"type": "string", "pattern": "^(?!/)(?!.*\\.\\.).+$"},
+        "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "bytes": {"type": "integer", "minimum": 1},
+        "width": {"type": "integer", "minimum": 1},
+        "height": {"type": "integer", "minimum": 1}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/scripts/analyze.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Cross-platform project analyzer entrypoint.
+
+This replaces the npm CLI's Bash-only analyzer path while preserving the
+existing analyzer implementation and refreshing Project Memory when present.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from src.core.analyzer import analyze  # noqa: E402
+from project_memory_loader import refresh_if_present  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Analyze a host project and refresh MotionLoom Project Memory.")
+    parser.add_argument("project_root", nargs="?", default=".")
+    parser.add_argument("--output")
+    parser.add_argument("--init-memory", action="store_true", help="Create .motionloom/project-memory.json if it does not exist")
+    parser.add_argument("--max-files", type=int, default=2500, help="Maximum files to inspect")
+    parser.add_argument("--max-bytes", type=int, default=25_000_000, help="Maximum file bytes to inspect")
+    parser.add_argument("--max-seconds", type=float, default=10.0, help="Maximum traversal time")
+    parser.add_argument("--ignore-dir", action="append", default=[], help="Directory name to skip; repeatable")
+    parser.add_argument("--ignore-glob", action="append", default=[], help="Relative path glob to skip; repeatable")
+    args = parser.parse_args()
+    root = Path(args.project_root).expanduser().resolve()
+    if not root.is_dir():
+        parser.error(f"project root is not a directory: {root}")
+    context_path = Path(args.output).expanduser().resolve() if args.output else root / "project-context.json"
+    context = analyze(
+        str(root),
+        max_files=args.max_files,
+        max_bytes=args.max_bytes,
+        max_seconds=args.max_seconds,
+        ignore_dirs=args.ignore_dir or None,
+        ignore_globs=args.ignore_glob or None,
+    )
+    context_path.parent.mkdir(parents=True, exist_ok=True)
+    context_path.write_text(json.dumps(context, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(f"{context_path} written ({len(json.dumps(context, ensure_ascii=False))} bytes)")
+    memory_result = refresh_if_present(root, context_path, initialize=args.init_memory)
+    if memory_result:
+        print(json.dumps({"project_memory": memory_result}, ensure_ascii=False))
+    print("== MotionLoom analysis complete: review assumptions before generating ==")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())