motionloom 2.3.0 → 2.5.0

package/bin/motionloom.mjs

@@ -38,25 +38,42 @@ const PYTHON_COMMANDS = {
   "visual-truth": "scripts/visual-truth.py",
   "remediation-learning": "scripts/remediation-learning.py",
   "asset-provenance": "scripts/asset-provenance.py",
+  "asset-consistency": "scripts/asset-consistency.py",
+  "artifact-intake": "scripts/artifact-intake.py",
+  "runtime-candidate": "scripts/runtime-candidate.py",
+  "rig-compatibility": "scripts/rig-compatibility.py",
+  "rive-package-gate": "scripts/rive-package-gate.py",
+  "pilot-build": "scripts/build-ai-pilot.py",
+  "alpha-isolate": "scripts/isolate-alpha-background.py",
 };
 
 const NODE_COMMANDS = {
+  init: "scripts/setup.mjs",
   setup: "scripts/setup.mjs",
   status: "scripts/setup.mjs",
   repair: "scripts/setup.mjs",
 };
 
+const COMMAND_ALIASES = {
+  capability: { script: "scripts/intelligence.py", args: ["capabilities"] },
+};
+
 function printHelp() {
-  console.log(`MotionLoom 2.2.0 — project-aware animation production and evidence contracts
+  console.log(`MotionLoom 2.4.0 — project-aware animation production and evidence contracts
 
 Usage:
   motionloom <command> [args...]
 
-Commands:
+Start here:
+  init                   One safe project setup; no animation gate runs
+  status                 Short read-only readiness report
   doctor                 Validate the installed Skill package
+
+Use when an animation task needs it:
   analyze                Run project analysis and refresh Project Memory
   memory                 Initialize, inspect, refresh, recover or validate memory
   intelligence           Build or validate Intelligence Core artifacts
+  capability             Export or select evidence-bound runtime capabilities
   attestation            Build/validate canonical signed-attestation artifacts
   verify-attestation     Verify an attestation against a trust policy
   evidence-verify        Verify runtime evidence externally
@@ -73,8 +90,14 @@ Commands:
   visual-truth           Build or validate provenance-bound visual comparisons
   remediation-learning   Record or summarize user-confirmed remediation and benchmark history
   asset-provenance       Validate, classify or report asset origin and production readiness
-  setup                  Install and bootstrap MotionLoom in the current project
-  status                 Read-only project readiness report
+  asset-consistency      Validate frame geometry, atlas contamination and layered-map contracts
+  artifact-intake        Bind generation controls, provenance, adapter metadata and exported bytes
+  runtime-candidate      Bind intake exports to consistency contracts before runtime testing
+  rig-compatibility      Validate rig bones, sockets, actions, events and runtime adapter evidence
+  rive-package-gate      Verify a real .riv package, runtime proof and provenance before testing
+  pilot-build            Build a review-only hash-bound AI scout pilot from true-alpha PNG sources
+  alpha-isolate          Isolate an edge-connected flat background; block residual edge contamination
+  setup                  Alias for init (kept for compatibility)
   repair                 Re-apply safe missing setup pieces
 
 Cross-platform examples:
@@ -85,9 +108,16 @@ Cross-platform examples:
     --status accepted --summary "Use ease-out for UI entry" --user-confirmed
   motionloom discovery check --root . --json
   motionloom discovery install-matrix --root . --json
+  motionloom capability card --format json
   motionloom visual-truth validate --root . --input src/output/<scene>/visual-truth.json
   motionloom remediation-learning summary --history artifacts/remediation-history.jsonl --json
   motionloom asset-provenance check --input <asset-provenance.json> --root <scene-dir> --mode runtime --json
+  motionloom asset-consistency validate --kind frame-geometry --input <frame-geometry.json> --root <scene-dir> --json
+  motionloom artifact-intake intake --root <asset-dir> --registry artifact-adapter-registry.json \\
+    --receipt <generation-receipt.json> --controls <control-track.json> --export-manifest <export-manifest.json> --json
+  motionloom alpha-isolate <opaque.png> <isolated.png> --report <alpha-report.json>
+  motionloom rive-package-gate validate --root <package-dir> --registry rig-adapter-registry.json \\
+    --input <rive-package-manifest.json> --strict --json
 
 The CLI never grants approval or opens a pull request by itself. User review
 and explicit repository side-effect confirmation remain separate gates.
@@ -100,7 +130,8 @@ if (!command || command === "help" || command === "--help" || command === "-h")
   process.exit(0);
 }
 
-const script = NODE_COMMANDS[command] || PYTHON_COMMANDS[command];
+const alias = COMMAND_ALIASES[command];
+const script = alias?.script || NODE_COMMANDS[command] || PYTHON_COMMANDS[command];
 if (!script) {
   console.error(`Unknown MotionLoom command: ${command}`);
   printHelp();
@@ -108,7 +139,13 @@ if (!script) {
 }
 
 const executable = script.endsWith(".mjs") ? process.execPath : PYTHON;
-const delegatedArgs = NODE_COMMANDS[command] && command !== "setup" ? [command, ...args] : args;
+const delegatedArgs = alias
+  ? [...alias.args, ...args]
+  : NODE_COMMANDS[command] && !["setup", "init"].includes(command)
+    ? [command, ...args]
+    : command === "init"
+      ? ["init", ...args]
+      : args;
 const result = spawnSync(executable, [resolve(ROOT, script), ...delegatedArgs], {
   cwd: ROOT,
   stdio: "inherit",

package/capability-registry.json

@@ -0,0 +1,308 @@
+{
+  "schema_version": "0.1",
+  "registry_id": "registry-motionloom-2.5.0",
+  "generated_at": "2026-08-17T05:39:24Z",
+  "selection_policy": {
+    "require_verified": true,
+    "allow_scaffold_only": false,
+    "max_evidence_age_seconds": 604800
+  },
+  "capabilities": [
+    {
+      "id": "runtime.lottie-json",
+      "kind": "renderer",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.dotlottie-package",
+      "kind": "packager",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.svg-cutout-rig",
+      "kind": "renderer",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.rive",
+      "kind": "runtime-adapter",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.gsap",
+      "kind": "runtime-adapter",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.framer-motion",
+      "kind": "runtime-adapter",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.spine",
+      "kind": "renderer",
+      "status": "scaffold_only",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Scaffold only; do not use for production acceptance."
+      ],
+      "fallback": "runtime.lottie-json",
+      "risk_level": "high",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.threejs",
+      "kind": "renderer",
+      "status": "scaffold_only",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Scaffold only; do not use for production acceptance."
+      ],
+      "fallback": "runtime.lottie-json",
+      "risk_level": "high",
+      "side_effect_level": "local_write"
+    }
+  ]
+}

package/docs/CHECKLIST.md

@@ -28,10 +28,26 @@ A scene is only ready for the confirm-into-PR step when every item below passes.
 - [ ] `ai_generated` assets may be runtime-ready but are not production-eligible; `unknown` assets are blocked.
 - [ ] `artist_authored` is backed by a verifiable human/artist record and is not merely an Agent-authored field.
 
+## Asset consistency
+- [ ] Multi-frame actions declare an `identity` and `action-set` contract when the asset has shared character/style identity or loop/event requirements.
+- [ ] `frame-geometry` measures the real PNG bytes: canvas size, alpha bounds, frame SHA-256, pivot/footline drift and opaque pixels outside each frame rect.
+- [ ] Sprite atlases declare non-overlapping regions, explicit rotation policy and transparent pixels outside regions; contamination is blocking in strict runs.
+- [ ] Layered maps declare unique layer IDs/z-order, intentional parallax order, tile seam policy, layer/world bounds and camera-safe bounds.
+- [ ] Consistency output is stored with the task evidence and remains separate from provenance authority, production eligibility and user approval.
+
+## Provider-neutral intake and runtime candidate
+- [ ] Every Agent/internal-skill/provider output used by the scene has a hash-bound generation receipt, control track and export manifest; no receipt stores secrets or self-asserts approval.
+- [ ] The selected artifact adapter is declared in `artifact-adapter-registry.json`; `scaffold` or `static-validated` status is not presented as runtime verification or production eligibility.
+- [ ] `runtime-candidate.json` binds the intake bundle to the matching asset identity, action-set and frame geometry/atlas/map contracts; mismatched refs or hashes block the candidate.
+- [ ] A rigmed or motion-capture candidate declares skeleton, sockets, action/event coverage, export target and adapter evidence in `rig-compatibility.json`.
+- [ ] Artifact Intake, runtime candidate and rig findings are present in the task handoff/Dev Lab rail and visibly retain `review_required` until the user records a decision.
+
 ## PR readiness
 - [ ] Snapshot PNGs exist for 0/50/100%.
 - [ ] `visual-truth.json` binds real baseline/candidate frames to source, manifest and available runtime/Motion IR hashes; `approval` remains `false`.
 - [ ] `motion-spec.json` is bound to the exact `project-context.json` hash (implements == planned).
 - [ ] Dev Lab URL tested on mobile viewport and desktop.
 - [ ] The production provenance check passes with `--mode production` and reports `production_eligible: true`.
+- [ ] If `manifest.json` declares `consistency_ref`, `quality-gate.py --require-asset-consistency` passes for its declared `consistency_kind`.
+- [ ] If `manifest.json` declares an Artifact Intake bundle, `quality-gate.py --require-artifact-intake` passes and the selected adapter/runtime evidence meets the requested mode.
 - [ ] `production_approved` and browser-review approval are recorded only from the user's explicit review; attestation approval remains `false`.

package/docs/STATUS.md

@@ -4,7 +4,7 @@
 
 ## Current release posture
 
-MotionLoom's repository source and package manifest are prepared for **2.3.0 release metadata**. The publication state of the npm registry and GitHub Release/tag must be verified against the latest release workflow rather than inferred from this document. The repository has a cross-platform CLI, one-command project onboarding, durable Project Memory, Agent interoperability surfaces, artifact-first handoff, runtime evidence, Visual Truth, Remediation Learning, signed attestation, AI-first asset provenance and a browser-based Dev Lab review contract. The protected manual release workflow verifies package/changelog/release-note alignment before publication.
+MotionLoom's repository source and package manifest are prepared for **2.4.0 release metadata**. The publication state of the npm registry and GitHub Release/tag must be verified against the latest release workflow rather than inferred from this document. The repository has a cross-platform CLI, one-command project onboarding, durable Project Memory, Agent interoperability surfaces, artifact-first handoff, runtime evidence, Visual Truth, Remediation Learning, signed attestation, AI-first asset provenance, a truthful code-authored runtime lane and a browser-based Dev Lab review contract. The protected manual release workflow verifies package/changelog/release-note alignment before publication.
 
 The repository is **engineering-ready for continued integration work**, not a universal production certification for every animation framework or every host project. CI status must be read from the latest GitHub Actions run, not inferred from historical audit prose.
 
@@ -30,4 +30,4 @@ Use the following order when sources disagree:
 
 ## Known next work
 
-The bounded analyzer has now been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md). The highest-value remaining evidence work is paired product evaluation across more real projects and verification of the 2.3.0 version–tag–GitHub Release–npm provenance chain. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert heuristic warnings into approval.
+The bounded analyzer has now been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md). The highest-value remaining evidence work is paired product evaluation across more real projects and verification of the 2.4.0 version–tag–GitHub Release–npm provenance chain. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert heuristic warnings into approval.

package/docs/apple-distribution.md

@@ -0,0 +1,24 @@
+# Apple distribution boundary
+
+The current `MotionLoomStudio` build is an unsigned local alpha. GitHub CI builds packages and checks iOS Simulator compatibility; it does not sign, upload, submit or distribute an application.
+
+| Channel | Required external inputs | Current state |
+| --- | --- | --- |
+| Local macOS alpha | Xcode and a user-selected project folder | Implemented and manually launchable. |
+| iOS Simulator review UI | Xcode simulator runtime and an Xcode app target that embeds `MotionLoomReviewUI` | Library cross-compilation is verified; the signed target remains intentionally uncreated. |
+| TestFlight | Apple Developer Program membership, bundle identifier, signing, App Store Connect app record and a user approval to upload | Not initiated. |
+| Mac App Store / iOS App Store | The TestFlight requirements plus app metadata, privacy details and an explicit human submission decision | Not initiated. |
+
+TestFlight distribution is handled through App Store Connect and requires the app owner to control signing and submission; MotionLoom’s CI must stay read-only until an owner explicitly decides to introduce that workflow.[1]
+
+## Before a TestFlight decision
+
+1. Create a final bundle identifier and an Apple-owned iCloud container; do not reuse development identifiers accidentally.
+2. Create the iOS/macOS Xcode app targets and add `MotionLoomContracts`, `MotionLoomReview`, `MotionLoomReviewUI` and, on macOS, `MotionLoomMacBridge` as local packages.
+3. Complete privacy labels and explain that CloudKit is limited to review metadata if sync is enabled.
+4. Test review JSON handoff with a real candidate on a physical iPhone/iPad and macOS.
+5. Make a separate explicit decision before uploading any build, inviting testers or submitting for review.
+
+## References
+
+[1]: https://developer.apple.com/testflight/ "Apple Developer — TestFlight"

package/docs/architecture/apple/cloudkit.md

@@ -0,0 +1,18 @@
+# CloudKit review metadata boundary
+
+`MotionLoomReviewSync` is intentionally **local-first**. A review is written to a local outbox before it can be uploaded. The CloudKit adapter uploads only a metadata projection after `MotionLoomContractDecoder.verify` confirms that task ID, candidate ID and both evidence digests match the review launch descriptor.
+
+| Data class | Local outbox | Private CloudKit database | Explicitly excluded |
+| --- | --- | --- | --- |
+| Human review decision and annotations | Yes | Metadata projection only | No production approval field exists. |
+| Task/candidate IDs and evidence hashes | Yes | Yes | No raw runtime artifact bytes. |
+| Source asset, texture, `.riv`, `.lottie`, project repository or secrets | No | No | Never synchronized by this adapter. |
+| GitHub/PR/npm/App Store operations | No | No | Must remain an explicit human-controlled workflow outside CloudKit. |
+
+The default database is the user’s private CloudKit database. Before enabling a production container, the app project needs a user-owned container identifier, the iCloud capability entitlement, an App ID and an explicit privacy review. The source package does **not** supply a container identifier, entitlement, Apple team ID, signing profile or server token.
+
+Apple describes CloudKit as a framework for storing and syncing app data through the user’s iCloud account; this design deliberately narrows that scope to review metadata and does not treat CloudKit as the source of truth for source assets or repository state.[1]
+
+## References
+
+[1]: https://developer.apple.com/icloud/cloudkit/ "Apple Developer — CloudKit"

package/docs/architecture/apple/contracts.md

@@ -0,0 +1,9 @@
+# Apple contract boundary
+
+The Apple application is an inspection and human-review surface. It reads canonical MotionLoom artifacts and writes only a human review decision bound to the selected task, candidate and evidence digests. It does not duplicate Python validator policy, create provenance, grant `production_approved`, set `OPEN_PR=1`, open a pull request or publish a package.
+
+`contracts/apple/review-launch-descriptor.schema.json` defines the minimum identity-bound information a macOS or iOS review surface may accept. A descriptor is rejected when its schema version is unsupported, it has unknown fields, identifiers are invalid, an artifact root is missing, or runtime/candidate evidence digests are absent.
+
+`contracts/apple/review-decision.schema.json` defines a record made only after explicit human action. The only allowed decisions are `request_changes`, `reviewed_no_decision` and `approve_for_next_human_step`. None is production approval. A later policy-controlled workflow may consume a record only after independently verifying the same task, candidate and evidence identity.
+
+The initial fixtures bind to `runtime-pilot-001`. They are decoder and identity fixtures, not an approval fixture and not a claim that the candidate is production eligible.

package/docs/architecture/apple/implementation-status-2026-08-16.md

@@ -0,0 +1,55 @@
+# MotionLoom Apple alpha — implementation status
+
+**Ngày kiểm tra:** 16-08-2026  
+**Phạm vi:** macOS Studio alpha, iOS/iPadOS Review companion, review contracts, local-first sync foundation và native CI.  
+**Trạng thái source:** hoàn thành và đã kiểm thử local; chưa commit, push, ký hoặc phát hành.
+
+## Kết luận
+
+MotionLoom hiện có một lớp app Apple native-first bám đúng mô hình **artifact-first, runtime-evidence và human-governed** của repository. Lớp mới không thay thế CLI Node/Python, runtime adapters hoặc Dev Lab; nó biến evidence đã có thành Project Inspector, Timeline Desk và review surface native cho macOS/iOS.
+
+> App không có khả năng cấp `production_approved`, tự chạy shell tùy ý, tự tạo PR, push Git, publish npm hay submit App Store. Các hành động này tiếp tục nằm ngoài native surface và phải qua cơ chế review/quyền hiện hữu.
+
+| Thành phần | Đầu ra đã tạo | Trạng thái |
+| --- | --- | --- |
+| Canonical contracts | `contracts/apple/review-launch-descriptor.schema.json`, `review-decision.schema.json` và fixture hash-bound runtime-pilot | Đã hoàn thành; reject unknown fields và không biểu diễn production approval. |
+| Contract runtime | `apps/apple/Packages/MotionLoomContracts` | Đã hoàn thành; Swift decoder fail-closed, migration version và identity binding. |
+| Review core | `apps/apple/Packages/MotionLoomReview` | Đã hoàn thành; timeline, annotation, ba human review decisions và export review JSON deterministic. |
+| Project bridge | `apps/apple/Packages/MotionLoomMacBridge` | Đã hoàn thành; security-scoped folder access, allow-list inspection commands, chặn path/URL không tin cậy. |
+| macOS Studio | `apps/apple/MotionLoomStudio` và target `MotionLoomStudio` | Đã build và launch unsigned; có Project Inspector, Timeline Desk và native web surface mở Dev Lab review URL. |
+| iOS/iPadOS companion | `apps/apple/MotionLoomReviewApp`, `MotionLoomReviewUI` và target `MotionLoomReview` | Đã build unsigned cho iPhone Simulator SDK; chỉ đọc evidence, scrub timeline, annotate và tạo review decision. |
+| Đồng bộ review | `apps/apple/Packages/MotionLoomReviewSync` | Đã hoàn thành local-first outbox; chỉ đưa metadata review identity-bound vào sync adapter. |
+| CI và hướng dẫn | `.github/workflows/apple.yml`, `apps/apple/scripts/emit-ios-simulator-destination.sh`, các tài liệu Apple | Đã hoàn thành; CI không ký, không publish và dùng dynamic simulator SDK destination. |
+
+## Trust boundary giữ nguyên
+
+Các package Swift dùng canonical contract và fixture từ repository thay vì sao chép policy validator sang Swift. `MotionLoomContracts` giới hạn review decision ở các trạng thái review của con người; `MotionLoomReview` chỉ export review record; `MotionLoomMacBridge` chỉ có lệnh inspection trong allow-list. CloudKit adapter cũng chỉ nhận review metadata đã identity-bound, không nhận source asset, repository, secret, production authority hoặc capability nâng quyền.
+
+Mac app có thể mở project folder và xuất handoff review; iOS app có thể đọc candidate/evidence và ghi note theo timeline. Cả hai app không làm thay nhiệm vụ của Agent: Agent tiếp tục tạo/sửa artifact, chạy validator và render runtime thật; người dùng review trên native app rồi tạo data để Agent tiếp tục xử lý.
+
+## Kiểm thử đã chạy trên Mac
+
+| Kiểm tra | Kết quả |
+| --- | --- |
+| `pnpm test` từ repository root | **PASS** — toàn bộ regression suite, gồm Apple contract và signed attestation. |
+| `pnpm run docs:check` | **PASS**. |
+| `swift test` cho Contracts, Review, MacBridge, ReviewUI và ReviewSync | **PASS**. |
+| `xcodebuild` unsigned target `MotionLoomStudio` với SDK macOS | **PASS**; Studio đã launch local. |
+| `xcodebuild` unsigned target `MotionLoomReview` với SDK iPhone Simulator | **PASS**. |
+| `git diff --check` | **PASS**. |
+
+Trong quá trình acceptance trên macOS, regression cũ phát hiện giả định path không phù hợp với alias hệ thống `/var -> /private/var`. Các chỉnh sửa giới hạn trong `scripts/evidence-verifier.py`, `scripts/intelligence.py` và `scripts/attestation.py`: chỉ parent alias hệ thống này được xử lý đúng trên macOS; symlink tại hoặc bên trong scene, task, evidence, repository và replay roots vẫn bị reject. Toàn bộ regression suite đã pass sau thay đổi này.
+
+## Blocker còn lại ngoài source code
+
+| Hạng mục | Lý do chưa thực hiện | Điều kiện để hoàn thành |
+| --- | --- | --- |
+| iOS UI smoke trên simulator | Xcode đang có iPhone Simulator SDK để compile nhưng chưa có device runtime khả dụng để boot. | Cài một iOS Simulator runtime trong Xcode Settings, sau đó boot device và chạy UI smoke. |
+| CloudKit sync live | Cần container thuộc Apple Developer account và entitlement có quyền của chủ sở hữu. | Chủ sở hữu tạo/chọn CloudKit container, quyết định retention/privacy và bật entitlement trong Xcode. |
+| Ký/TestFlight/App Store | Cần Apple Developer Team, App IDs, bundle identifiers, signing và quyết định submit của chủ sở hữu. | Cấu hình signing, tạo archive, rồi chủ sở hữu duyệt upload TestFlight. |
+
+Các blocker trên không làm source alpha bị lỗi; chúng là quyền tài khoản và hạ tầng bên ngoài mà MotionLoom không tự tạo hoặc tự chấp nhận thay người dùng.
+
+## Bước tiếp theo sau khi commit/push được duyệt
+
+Sau khi source được commit và push riêng, công việc hợp lý tiếp theo là cài iOS Simulator runtime, chạy UI smoke của Review companion, thiết kế CloudKit container review-only và chỉ sau đó mới cân nhắc beta TestFlight. Không nên thêm production approval, Git push hay asset upload capability vào app trước khi vòng review iOS đã được kiểm chứng trên device/simulator.

package/docs/architecture/apple/studio.md

@@ -0,0 +1,35 @@
+# MotionLoom Studio alpha
+
+MotionLoom Studio is a **native macOS inspection and review surface**, not a replacement for the cross-platform MotionLoom CLI, its Python validators, runtime adapters or Dev Lab. The Studio presents verified task/candidate/evidence identity and helps a human create a review handoff.
+
+| Surface | Responsibility | Prohibited actions |
+| --- | --- | --- |
+| Project Inspector | User selects a scoped project folder, then launches a small allow-list of local inspections. | Arbitrary shell, `git push`, `OPEN_PR=1`, npm publish and PR creation. |
+| Timeline Desk | Scrub review timecodes, open the existing Dev Lab candidate and collect annotations. | Treating a preview or heuristic as approval. |
+| Evidence | Shows task/candidate identity and SHA-256 digests before review. | Loading a candidate whose identity binding is not valid. |
+| Export Human Review | Writes a deterministic review JSON for an Agent or maintainer to act on later. | Writing `production_approved` or modifying a repository. |
+
+The app uses `ProjectAccessScope` to confine read/write operations to an explicitly selected project root. It invokes the CLI through an argument vector and a closed command enum, never a shell string. macOS security-scoped bookmarks are supported for a later sandboxed/notarized build, but the alpha remains unsigned and local.
+
+## Local verification
+
+```bash
+cd apps/apple/Packages/MotionLoomContracts && swift test
+cd ../MotionLoomReview && swift test
+cd ../MotionLoomMacBridge && swift test
+cd ../MotionLoomReviewUI && swift test
+cd ../MotionLoomReviewSync && swift test
+cd ../../MotionLoomStudio && swift build
+swift run MotionLoomStudio
+```
+
+To verify the companion library against the installed iOS Simulator SDK without signing an app bundle:
+
+```bash
+destination="$(mktemp)"
+apps/apple/scripts/emit-ios-simulator-destination.sh "$destination"
+(cd apps/apple/Packages/MotionLoomReviewUI && swift build --destination "$destination")
+rm -f "$destination"
+```
+
+> A successful native build, attestation or quality gate is **not** human approval. The only review records emitted by the app are `request_changes`, `reviewed_no_decision`, and `approve_for_next_human_step`.