motionloom 2.2.0 → 2.3.0

package/examples/agent-consumer/ai-generated-pilot-provenance.json

@@ -0,0 +1,55 @@
+{
+  "schema_version": "1.0",
+  "provenance_id": "hero-male-ai-pilot-provenance",
+  "task_id": "mission-1.17.5-ai-pilot",
+  "scene": "hero-male-ai-pilot",
+  "created_at": "2026-08-14T00:00:00Z",
+  "asset": {
+    "id": "hero-male-ai-pilot",
+    "path": "hero-male.json",
+    "type": "runtime-pilot",
+    "framework": "body-rig",
+    "version": "0.1.0"
+  },
+  "authority": "ai_generated",
+  "readiness": "runtime_ready",
+  "generator": {
+    "model": "declared-by-agent-at-generation-time",
+    "task_id": "mission-1.17.5-ai-pilot",
+    "source": "agent-created-pilot",
+    "generated_at": "2026-08-14T00:00:00Z",
+    "agent": "codex"
+  },
+  "license": {
+    "spdx": "UNLICENSED",
+    "source": "internal-generation",
+    "attribution": "Generated pilot retained for runtime testing; production distribution requires a separate rights decision."
+  },
+  "files": [
+    {
+      "path": "hero-male.json",
+      "role": "runtime-pilot",
+      "sha256": "fc723dce3005fb2d16fe6df2e20a116f361b2b2b82b4aff7045c186c55190c27"
+    }
+  ],
+  "provenance_chain": [
+    {
+      "step": "generate",
+      "actor": "agent:codex",
+      "source": "agent-created-pilot",
+      "timestamp": "2026-08-14T00:00:00Z"
+    },
+    {
+      "step": "runtime-test",
+      "actor": "runtime:motionloom",
+      "source": "internal-runtime-evidence",
+      "timestamp": "2026-08-14T00:00:00Z"
+    }
+  ],
+  "runtime_evidence": {
+    "status": "pass",
+    "runtime": "motionloom-body-rig-runtime",
+    "tested_at": "2026-08-14T00:00:00Z",
+    "evidence_path": "runtime-evidence.json"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motionloom",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "type": "module",
   "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.",
@@ -28,6 +28,9 @@
     "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",
@@ -80,6 +83,10 @@
     "test": "node bin/motionloom.mjs test",
     "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",
@@ -116,7 +123,9 @@
     "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"
+    "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

@@ -16,6 +16,17 @@ Do not put divergent workflow rules into an Agent-specific file. Add reusable do
 
 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`.

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. |
@@ -26,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.
 
@@ -72,7 +73,11 @@ 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
@@ -98,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

@@ -43,7 +43,7 @@
         "required": ["id", "source_kind", "command", "verification", "provenance"],
         "properties": {
           "id": {"type": "string"},
-          "source_kind": {"type": "string", "enum": ["npm", "git", "local"]},
+          "source_kind": {"type": "string", "enum": ["npm", "npx", "git", "local"]},
           "command": {"type": "string"},
           "verification": {"type": "string"},
           "provenance": {"type": "string"}

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/scene-manifest.schema.json

@@ -12,6 +12,7 @@
     "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"],