motionloom 2.1.0 → 2.3.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "motionloom",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "type": "module",
   "packageManager": "pnpm@11.20.0",
-  "description": "MotionLoom: project-aware animation Skill with graph, provenance, Motion IR, runtime telemetry, DSSE-compatible signed attestation, external evidence verification and Dev Lab review.",
+  "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"
@@ -28,11 +28,19 @@
     "references",
     "docs",
     "examples",
+    "scripts/asset-provenance.py",
+    "schemas/asset-provenance.schema.json",
+    "examples/agent-consumer/ai-generated-pilot-provenance.json",
     "project-context.example.json",
     "tests/evals",
     "tests/scripts/run_tests.py",
     "tests/scripts/test_attestation.py",
-    "tests/scripts/test_project_memory.py"
+    "tests/scripts/test_project_memory.py",
+    ".agents",
+    ".claude",
+    ".codex",
+    "AGENTS.md",
+    "agent-surfaces.json"
   ],
   "keywords": [
     "animation",
@@ -50,7 +58,10 @@
     "provenance",
     "attestation",
     "browser-review",
-    "dev-lab"
+    "dev-lab",
+    "visual-truth",
+    "remediation-learning",
+    "agent-interoperability"
   ],
   "repository": {
     "type": "git",
@@ -70,8 +81,12 @@
   "scripts": {
     "prepack": "node scripts/prepack-clean.mjs",
     "test": "node bin/motionloom.mjs test",
-    "validate": "node bin/motionloom.mjs quality-gate --all",
+    "validate": "npm run quality:attestation",
     "doctor": "node bin/motionloom.mjs doctor --json",
+    "setup": "node bin/motionloom.mjs setup",
+    "setup:dry": "node bin/motionloom.mjs setup --dry-run",
+    "status": "node bin/motionloom.mjs status",
+    "repair": "node bin/motionloom.mjs repair",
     "docs:check": "python3 scripts/docs-audit.py",
     "eval:projects": "python3 scripts/eval-projects.py --allow-insufficient",
     "release:verify": "python3 scripts/release-verify.py",
@@ -99,9 +114,18 @@
     "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",
+    "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"
+    "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",
+    "asset-provenance:validate": "node bin/motionloom.mjs asset-provenance validate --input examples/agent-consumer/ai-generated-pilot-provenance.json --json",
+    "asset-provenance:check": "node bin/motionloom.mjs asset-provenance check --input examples/agent-consumer/ai-generated-pilot-provenance.json --root examples/agent-consumer --mode runtime --json"
   },
   "dependencies": {
     "@lottiefiles/dotlottie-web": "^0.79.0",

package/references/agent-interoperability.md

@@ -0,0 +1,40 @@
+# 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.
+
+## One-command onboarding
+
+For a host project that has not installed MotionLoom, prefer:
+
+```bash
+npx --yes motionloom setup --project-root <project-path>
+npx --no-install motionloom status --project-root <project-path> --json
+```
+
+`setup` is idempotent. It detects the project root and package manager, installs a local development dependency when needed, merges only the managed router block in `AGENTS.md`, runs discovery and bootstraps project context plus `.motionloom/project-memory.json`. Use `--dry-run --json` to preview and `repair --yes --json` to restore missing managed pieces. A setup result of `blocked` is actionable failure, not permission to continue with guessed context. Setup never commits, pushes, opens a PR or infers approval.
+
+## 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

@@ -8,6 +8,7 @@ Use this reference when an Agent needs to understand or extend MotionLoom's task
 | --- | --- | --- |
 | `project-graph.json` | `python3 scripts/intelligence.py graph build --task-dir <task>` | Links project, intent, scene, context, artifacts and review with task identity and hashes. |
 | `provenance.json` | `python3 scripts/intelligence.py provenance build --task-dir <task>` | Records step actor, builder, materials, products, policy, result and parent chain hash. |
+| `asset-provenance.json` | `motionloom asset-provenance check --input <path> --root <scene-dir> --mode runtime|production` | Classifies asset origin/authority and effective readiness, binds file hashes and license/source metadata, and fails closed before production eligibility. It never grants `production_approved`. |
 | `capability-registry.json` | `python3 scripts/intelligence.py capabilities build --output <path>` | Describes verified/scaffold-only adapters, evidence freshness, compatibility, fallback and side effects. |
 | `motion-ir.json` | `python3 scripts/intelligence.py motion-ir build --task-dir <task>` | Binds framework-neutral tracks and accessibility policy to task, scene, context and source. |
 | `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. |
@@ -15,6 +16,8 @@ Use this reference when an Agent needs to understand or extend MotionLoom's task
 | `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` | `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. |
@@ -24,7 +27,7 @@ Use this reference when an Agent needs to understand or extend MotionLoom's task
 
 ## Agent operating rules
 
-The Agent must build the graph, Motion IR, provenance, replay bundle, P1 feedback reports and semantic-lint benchmark after render and before the strict quality gate. For a strict observability run it must also capture runtime telemetry and run the external verifier before `--require-telemetry`. For a production trust run it must derive/sign `attestation.json`, copy or resolve a managed `trust-policy.json`, run the independent attestation verifier and use `--require-attestation`. It must run the report completeness contract for changed scenes; that contract selects one deterministic passing task bundle and fails on ambiguous ties. It may use a verified capability only when the registry evidence is fresh, its hash matches the referenced file and the target environment is compatible. `scaffold_only` is a planning option, never a production acceptance result.
+The Agent must build the graph, Motion IR, step-level provenance, asset provenance, replay bundle, P1 feedback reports and semantic-lint benchmark after render and before the strict quality gate. For a strict observability run it must also capture runtime telemetry and run the external verifier before `--require-telemetry`. For a production trust run it must derive/sign `attestation.json`, copy or resolve a managed `trust-policy.json`, run the independent attestation verifier and use `--require-attestation` plus `--require-asset-provenance`. It must run the report completeness contract for changed scenes; that contract selects one deterministic passing task bundle and fails on ambiguous ties. It may use a verified capability only when the registry evidence is fresh, its hash matches the referenced file and the target environment is compatible. `scaffold_only` is a planning option, never a production acceptance result.
 
 The graph and provenance are evidence indexes, not approval tokens. A valid graph cannot bypass source binding, runtime assertions, browser review, reviewer consent or the `OPEN_PR=0` default. A confidence or risk value can prioritize investigation but cannot replace a deterministic rule or human decision.
 
@@ -70,7 +73,13 @@ python3 scripts/quality-gate.py \
   --scene <scene> \
   --context <project-context.json> \
   --task-dir artifacts/<task-id> \
-  --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation
+  --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation --require-asset-provenance
+motionloom asset-provenance check \
+  --input src/output/<scene>/asset-provenance.json \
+  --root src/output/<scene> --mode production \
+  --manifest src/output/<scene>/manifest.json --json
+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
 ```
 
@@ -94,5 +103,6 @@ The replay policy excludes generated reports and manifests because `report.py co
 | `artifact_base must share the Dev Lab origin` or identity binding failure | Dev Lab query parameters would mix an external or foreign task/candidate bundle | Reject the handoff and regenerate the review URL from the canonical task bundle. |
 | `runtime telemetry verification failed` | Scrub-point evidence is stale, tampered, missing, cross-task, path-escaped or bound to different source/manifest/Motion IR bytes | Re-run the real runtime capture from the canonical scene/task bundle, then verify again; never treat the verifier as approval. |
 | `attestation verification failed` | Payload hash, DSSE signature, signer validity/revocation, policy lookup, path binding or expected task/scene binding failed | Regenerate the statement from current artifacts, re-run the external verifier against a managed policy and investigate signer lifecycle; never flip `approval` or bypass user review. |
+| `asset provenance is blocked` or `production_eligible: false` | Origin is unknown/AI-generated without the required review, a file hash/license/runtime/full-gate record is missing, or an Agent self-asserted artist authority/approval | Keep the candidate runtime-only, fix the provenance record or obtain the required human review; never rewrite the authority tier or set `production_approved` automatically. |
 
 The public eval corpus is `tests/evals/intelligence-cases.json`. It covers positive verified selection plus scaffold-only, stale evidence, tampering, graph corruption, replay tamper and foreign-task candidate failures. P1 extends the acceptance surface with semantic warning preservation, generic-intent detection, multi-scene context drift, selective rerun binding, performance budget/frame-rate warnings, perceptual easing/reduced-motion warnings and benchmark execution time. The 1.9.0 slice adds runtime telemetry happy-path, state tamper, cross-task identity, stale evidence and symlink escape cases. The 2.0.0 slice adds clean attestation, payload tamper, binding mismatch, revoked signer and unknown signer cases without weakening the approval=false and human-review invariants.

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", "npx", "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/asset-provenance.schema.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/lenhonbp/MotionLoom/blob/main/schemas/asset-provenance.schema.json",
+  "title": "MotionLoom asset provenance contract",
+  "description": "Asset-level origin, authority, readiness and human-governance contract. This schema never treats an Agent assertion as human approval.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "provenance_id", "asset", "authority", "readiness", "files", "license", "provenance_chain", "created_at"],
+  "properties": {
+    "schema_version": {"const": "1.0"},
+    "provenance_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$"},
+    "task_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$"},
+    "scene": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{1,63}$"},
+    "created_at": {"type": "string", "format": "date-time"},
+    "asset": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "path", "type", "framework"],
+      "properties": {
+        "id": {"type": "string", "minLength": 1},
+        "path": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"},
+        "type": {"type": "string", "minLength": 1},
+        "framework": {"type": "string", "minLength": 1},
+        "version": {"type": "string", "minLength": 1}
+      }
+    },
+    "authority": {
+      "type": "string",
+      "enum": ["ai_generated", "ai_assisted", "ai_assisted_human_reviewed", "artist_authored", "unknown"]
+    },
+    "readiness": {
+      "type": "string",
+      "enum": ["blocked", "runtime_ready", "review_required", "production_eligible", "production_approved"]
+    },
+    "generator": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["model", "task_id", "source", "generated_at"],
+      "properties": {
+        "model": {"type": "string", "minLength": 1},
+        "task_id": {"type": "string", "minLength": 1},
+        "source": {"type": "string", "minLength": 1},
+        "generated_at": {"type": "string", "format": "date-time"},
+        "prompt_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "agent": {"type": "string", "minLength": 1}
+      }
+    },
+    "human_attestation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["attestor", "attestor_type", "decision", "attested_at", "user_confirmed"],
+      "properties": {
+        "attestor": {"type": "string", "minLength": 1},
+        "attestor_type": {"type": "string", "enum": ["artist", "user"]},
+        "decision": {"type": "string", "enum": ["artist_authored", "accepted", "rejected"]},
+        "attested_at": {"type": "string", "format": "date-time"},
+        "user_confirmed": {"const": true},
+        "signature": {"type": "string", "minLength": 1}
+      }
+    },
+    "human_review": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reviewer", "decision", "scope", "reviewed_at", "user_confirmed"],
+      "properties": {
+        "reviewer": {"type": "string", "minLength": 1},
+        "decision": {"type": "string", "enum": ["approved", "rejected", "changes_requested"]},
+        "scope": {"type": "string", "minLength": 1},
+        "reviewed_at": {"type": "string", "format": "date-time"},
+        "user_confirmed": {"const": true},
+        "notes": {"type": "string"}
+      }
+    },
+    "human_approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["issued_by", "decision", "approved_at", "user_confirmed"],
+      "properties": {
+        "issued_by": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "type"],
+          "properties": {
+            "id": {"type": "string", "minLength": 1},
+            "type": {"type": "string", "enum": ["user", "artist"]}
+          }
+        },
+        "decision": {"const": "approved"},
+        "approved_at": {"type": "string", "format": "date-time"},
+        "user_confirmed": {"const": true},
+        "notes": {"type": "string"}
+      }
+    },
+    "license": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["spdx", "source", "attribution"],
+      "properties": {
+        "spdx": {"type": "string", "minLength": 1},
+        "source": {"type": "string", "minLength": 1},
+        "attribution": {"type": "string", "minLength": 1}
+      }
+    },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "role", "sha256"],
+        "properties": {
+          "path": {"type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+"},
+          "role": {"type": "string", "minLength": 1},
+          "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+          "bytes": {"type": "integer", "minimum": 0}
+        }
+      }
+    },
+    "provenance_chain": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["step", "actor", "source", "timestamp"],
+        "properties": {
+          "step": {"type": "string", "minLength": 1},
+          "actor": {"type": "string", "minLength": 1},
+          "source": {"type": "string", "minLength": 1},
+          "timestamp": {"type": "string", "format": "date-time"},
+          "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}
+        }
+      }
+    },
+    "runtime_evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "runtime", "tested_at"],
+      "properties": {
+        "status": {"type": "string", "enum": ["pass", "fail", "not_run"]},
+        "runtime": {"type": "string", "minLength": 1},
+        "tested_at": {"type": "string", "format": "date-time"},
+        "evidence_path": {"type": "string", "minLength": 1},
+        "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}
+      }
+    },
+    "full_gate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "quality_gate", "visual_truth", "license", "checked_at"],
+      "properties": {
+        "status": {"type": "string", "enum": ["pass", "fail", "not_run"]},
+        "quality_gate": {"const": "pass"},
+        "visual_truth": {"const": "pass"},
+        "license": {"const": "pass"},
+        "checked_at": {"type": "string", "format": "date-time"},
+        "report_path": {"type": "string", "minLength": 1}
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {"required": ["authority"], "properties": {"authority": {"enum": ["ai_generated", "ai_assisted", "ai_assisted_human_reviewed"]}}},
+      "then": {"required": ["generator"]}
+    },
+    {
+      "if": {"required": ["authority"], "properties": {"authority": {"const": "artist_authored"}}},
+      "then": {"required": ["human_attestation"]}
+    },
+    {
+      "if": {"required": ["authority"], "properties": {"authority": {"const": "unknown"}}},
+      "then": {"properties": {"readiness": {"const": "blocked"}}}
+    },
+    {
+      "if": {"required": ["readiness"], "properties": {"readiness": {"const": "production_approved"}}},
+      "then": {"required": ["human_approval", "full_gate"]}
+    },
+    {
+      "if": {"required": ["readiness"], "properties": {"readiness": {"const": "production_eligible"}}},
+      "then": {"required": ["full_gate"]}
+    }
+  ]
+}

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,8 @@
     "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": "^(?!/)(?!.*\\.\\.).+$"},
+    "asset_provenance": {"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
+}