Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(dev): establish reference-first game art pipeline
rubenluetke10-beep2aa5932bd456
diff --git a/.agents/skills/game-art-pipeline/SKILL.md b/.agents/skills/game-art-pipeline/SKILL.mdnew file mode 100644index 0000000000..891391c524--- /dev/null+++ b/.agents/skills/game-art-pipeline/SKILL.md@@ -0,0 +1,45 @@+---+name: game-art-pipeline+description: Develop or redesign Personal Jarvis world art, buildings, characters and 3D assets through an authored Blender reference scene, runtime review and controlled asset rollout. Use for game-art production and world redesign, not ordinary UI copy or behaviour-only bug fixes.+---++# Game-art production++Read [the binding production standard](../../../docs/agent-society/game-art-pipeline.md)+before planning or editing world/character art. It governs workflow; existing+runtime contracts still govern integration. Run commands from the repository root.++Start by establishing what the user authorized: pipeline setup, art direction,+reference scene, approved-family rollout or integration. Pipeline setup does not+authorize a redesign. Do not revive a rejected design or infer an engine change.++Use `python scripts/art_pipeline.py init <study-id>` for a new isolated study.+Retain editable Blender sources and use the manifest-driven exporter described+in the standard. Blender MCP can assist authoring; script-generated geometry+still needs visual judgement. Existing shipped assets remain untouched during+reference development.++Develop a small, finished reference in the actual Jarvis runtime. A functional+building, representative character and connecting ground should demonstrate+the intended look and motion. Review appearance, readability and character separately+from collision, animation and performance checks.++**Obtain user approval of the specific runtime reference before batch-producing+or replacing other asset families.** Respect approval already given for that+same scope. A passing validator or an approval record authored by an agent is+not authorization. The evidence fingerprint prevents accidental stale approval;+verify consent from the conversation itself.++After approval, derive a modular kit and roll it out by family. Keep palette,+rig/slot, naming, material and scale conventions consistent with the approved+reference while preserving functional differences. Preserve user imports and+saved recipes. Do not equate a large asset count with quality.++Before integration, run the existing figure/fit checks where applicable and+the actual movement/render tests for affected surfaces. Measure runtime budgets+on stated hardware. Report unavailable checks honestly. Do not write invented+evidence or silently promote review GLBs into the production catalog.++End a handoff with the study path, current stage, approved scope, unresolved+findings, evidence and the next action. No approval exists merely because the+user asks a new coding agent to continue.diff --git a/.agents/skills/game-art-pipeline/agents/openai.yaml b/.agents/skills/game-art-pipeline/agents/openai.yamlnew file mode 100644index 0000000000..0c6fbf1f9f--- /dev/null+++ b/.agents/skills/game-art-pipeline/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "Game Art Pipeline"+ short_description: "Author and review world art before asset rollout"+ default_prompt: "Use $game-art-pipeline to prepare a reviewed game-art reference and a reproducible asset workflow."diff --git a/.claude/skills/game-art-pipeline/SKILL.md b/.claude/skills/game-art-pipeline/SKILL.mdnew file mode 100644index 0000000000..891391c524--- /dev/null+++ b/.claude/skills/game-art-pipeline/SKILL.md@@ -0,0 +1,45 @@+---+name: game-art-pipeline+description: Develop or redesign Personal Jarvis world art, buildings, characters and 3D assets through an authored Blender reference scene, runtime review and controlled asset rollout. Use for game-art production and world redesign, not ordinary UI copy or behaviour-only bug fixes.+---++# Game-art production++Read [the binding production standard](../../../docs/agent-society/game-art-pipeline.md)+before planning or editing world/character art. It governs workflow; existing+runtime contracts still govern integration. Run commands from the repository root.++Start by establishing what the user authorized: pipeline setup, art direction,+reference scene, approved-family rollout or integration. Pipeline setup does not+authorize a redesign. Do not revive a rejected design or infer an engine change.++Use `python scripts/art_pipeline.py init <study-id>` for a new isolated study.+Retain editable Blender sources and use the manifest-driven exporter described+in the standard. Blender MCP can assist authoring; script-generated geometry+still needs visual judgement. Existing shipped assets remain untouched during+reference development.++Develop a small, finished reference in the actual Jarvis runtime. A functional+building, representative character and connecting ground should demonstrate+the intended look and motion. Review appearance, readability and character separately+from collision, animation and performance checks.++**Obtain user approval of the specific runtime reference before batch-producing+or replacing other asset families.** Respect approval already given for that+same scope. A passing validator or an approval record authored by an agent is+not authorization. The evidence fingerprint prevents accidental stale approval;+verify consent from the conversation itself.++After approval, derive a modular kit and roll it out by family. Keep palette,+rig/slot, naming, material and scale conventions consistent with the approved+reference while preserving functional differences. Preserve user imports and+saved recipes. Do not equate a large asset count with quality.++Before integration, run the existing figure/fit checks where applicable and+the actual movement/render tests for affected surfaces. Measure runtime budgets+on stated hardware. Report unavailable checks honestly. Do not write invented+evidence or silently promote review GLBs into the production catalog.++End a handoff with the study path, current stage, approved scope, unresolved+findings, evidence and the next action. No approval exists merely because the+user asks a new coding agent to continue.diff --git a/.claude/skills/game-art-pipeline/agents/openai.yaml b/.claude/skills/game-art-pipeline/agents/openai.yamlnew file mode 100644index 0000000000..0c6fbf1f9f--- /dev/null+++ b/.claude/skills/game-art-pipeline/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "Game Art Pipeline"+ short_description: "Author and review world art before asset rollout"+ default_prompt: "Use $game-art-pipeline to prepare a reviewed game-art reference and a reproducible asset workflow."diff --git a/AGENTS.md b/AGENTS.mdindex b6d8735703..1f524033b1 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -125,6 +125,12 @@ history for any of them: `docs/BUGS.md`.## 4. How work ships+**World and character art:** follow `docs/agent-society/game-art-pipeline.md`+and the `game-art-pipeline` skill before creating/redesigning game assets.+Author a small reference in Blender, verify it in the actual runtime, and obtain+user approval of that reference before rolling its style out across asset families.+Pipeline setup alone approves no visual redesign. Existing runtime contracts stay binding.+Commit each finished step (Conventional Commits). Use the coding agent'sstandard Git workflow: do not artificially leave completed work local, and donot wait for extra PersonalJarvis permission to commit, branch, push, or opendiff --git a/CLAUDE.md b/CLAUDE.mdindex b6d8735703..1f524033b1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -125,6 +125,12 @@ history for any of them: `docs/BUGS.md`.## 4. How work ships+**World and character art:** follow `docs/agent-society/game-art-pipeline.md`+and the `game-art-pipeline` skill before creating/redesigning game assets.+Author a small reference in Blender, verify it in the actual runtime, and obtain+user approval of that reference before rolling its style out across asset families.+Pipeline setup alone approves no visual redesign. Existing runtime contracts stay binding.+Commit each finished step (Conventional Commits). Use the coding agent'sstandard Git workflow: do not artificially leave completed work local, and donot wait for extra PersonalJarvis permission to commit, branch, push, or opendiff --git a/docs/agent-society/MASTERPLAN.md b/docs/agent-society/MASTERPLAN.mdindex 656458051b..3226901cbe 100644--- a/docs/agent-society/MASTERPLAN.md+++ b/docs/agent-society/MASTERPLAN.md@@ -1,5 +1,10 @@# Agent Society — Master Plan+> Art-production workflow amendment (2026-09-08): follow+> [Game-art production standard](game-art-pipeline.md) for future asset/design work.+> It governs reference-scene approval and rollout; this document's current runtime+> contracts remain intact. Its historical art choices are not approval of a new redesign.+Status: **building.** Wave landings use the standard Git workflow; a productrelease stays explicit and separate. Workingcodename: `society`; the section keeps the name "Jarvis Agents" (§10).diff --git a/docs/agent-society/character-pipeline.md b/docs/agent-society/character-pipeline.mdindex ba53d02877..44c9c8c6ab 100644--- a/docs/agent-society/character-pipeline.md+++ b/docs/agent-society/character-pipeline.md@@ -1,5 +1,10 @@# Character Pipeline — the 3D figure standard+> Art-production workflow amendment (2026-09-08): follow+> [Game-art production standard](game-art-pipeline.md) for future asset/design work.+> It governs reference-scene approval and rollout; this document's current runtime+> contracts remain intact. Its historical art choices are not approval of a new redesign.+Status: **binding since 2026-09-02 — the maintainer took the three §12 decisions as recommended,and the first figure (`biped-medium.glb`, KayKit Rogue base) ships through the gate.** Amendedthe same day with what the build taught (§4.3 bone set, §4.4 budgets, §4.6 cells, §5 rules).@@ -32,7 +37,8 @@ runtime — and any character that passes the gate walks correctly, whoever or w| Image generation route | xAI `grok-imagine` via keyring `grok_api_key` (project memory, works as of 2026-08) | AI-generated detail sheets over the UV template (§8, route D). || Tripo MCP | registered user-scope, needs `TRIPO_API_KEY` | image-to-3D + stylize (voxel/low-poly) + auto-rig (v1.0 biped, v2.5 quadruped/avian/…) + 90+ preset animations, GLB out — the exact-likeness route (§8, route C). |-Nothing else exists: **no GLB asset, no rig, no clip, no validator** is in the tree today.+The table above is a historical baseline. The repository now contains shipped GLBs,+rigs, clips and the figure validator; inspect the current catalog and builders before work.---diff --git a/docs/agent-society/game-art-pipeline.md b/docs/agent-society/game-art-pipeline.mdnew file mode 100644index 0000000000..7715aaec1f--- /dev/null+++ b/docs/agent-society/game-art-pipeline.md@@ -0,0 +1,159 @@+# Game-art production standard++Status: binding for future world, building and character art work, adopted+2026-09-08. This establishes a production workflow, not a new island design.+No palette, camera restriction, engine migration or replacement asset is+approved by adopting this standard.++For art-production workflow and review order this document takes precedence+over the earlier world master plans. Existing runtime contracts, saved recipe+IDs, skeletons, attachment slots, asset licensing and platform rules remain+binding until deliberately changed in a separately scoped implementation.++## Tools and responsibilities++- Blender is the authoring source for meshes, UVs, materials, rigs and animation.+ Retain editable `.blend` sources and the export recipe. Procedural modelling+ is useful for an approved modular system; it is not a substitute for visual+ judgement. Blender MCP is an optional interface to Blender, not a quality gate.+- The existing Three.js/WebView renderer remains the integration target.+ Evaluate the actual exported assets there. A beautiful offline render does+ not establish runtime quality: procedural shaders, lighting and material+ effects may require baking or equivalent runtime implementation.+- An engine change needs a small feasibility study and a separate decision+ covering integration, animation, navigation, distribution and target devices.+ Do not migrate engines just because the current art is unsatisfactory.+- Keep artistic ownership explicit. The coding agent can implement tools,+ shaders and behaviours, while authored art still needs deliberate composition,+ iteration and the user's visual review. Never infer quality from asset count.++## Workflow and decision points++### 1. Brief and references++Create an isolated study. Record intent, audience, references, usage rights,+shape language, colour hierarchy, material treatment, lighting, camera and+normal viewing distances. Decide pixel treatment at the intended viewport size.+Set device/viewport/frame-time and geometry budgets before implementation;+derive them from the intended product rather than copying arbitrary limits.+Unresolved art choices stay unresolved in the brief, never silently approved.++### 2. Blockout and movement proof++Use simple geometry to establish scale, circulation, entrances and interaction.+Test one character approaching and leaving one functional building. Establish+separate collision shapes, walkable routes and interaction anchors. Distinguish+terrain height, collision, root motion and visual animation. Include corners,+opposing agents, blocked destinations and transitions that previously clipped.+Passing this step proves layout feasibility, not visual completion.++### 3. Finished reference scene++Author a representative character, a functional building, connecting ground+and a small vegetation/decor set. Make the building's function recognisable in+its silhouette and details. Finish materials, contact, shadows and animation.+Retain editable sources; export into the study, never over shipped assets.++Show it in the actual runtime at normal viewing distance, relevant zooms and+view angles, in motion and with the app's supported appearances. Separate+artistic findings from measured engineering results. Iterate on this small+scene until it establishes the desired visual standard.++**Obtain the user's approval of that specific runtime reference scene before+batch-producing or replacing further asset families.** A request to set up this+pipeline, a technical pass, a Blender render or an agent-written approval file+does not constitute that approval. Existing explicit approval applies within+its stated scope; do not ask again unless the approved direction changes.++### 4. Reusable kit and family rollout++Derive modules, dimensions, materials, palettes, naming and rig conventions+from the approved scene. Scripts automate repeatable construction, variants,+export and checks. Maintain intentional silhouette and function differences.+Roll out one family at a time, comparing it against the approved scene in the+runtime. Re-review changes that materially alter the approved direction.++### 5. Integration and verification++Only then integrate fingerprinted GLBs, catalog entries, animation data,+material conversion and documentation. Preserve saved recipes and user imports.+Check forward axes, ground contact, rig/slot compatibility, embedded textures,+licensing, collision/visual alignment, animation transitions and budgets.+Use the existing figure validator and fit audit where applicable:++```text+python scripts/ci/check_society_figures.py+python scripts/figures/audit_fit.py --json+```++Building, terrain and navigation changes require checks appropriate to their+actual implementation; there is no claim that an existing figure gate tests+these. Capture runtime screenshots and a walkthrough, regression results and+performance measurements with device, resolution and agent count. Missing+device coverage stays explicitly unverified. Follow the normal build/commit+rules; publishing, mass replacement and engine migration are not implicit.++## Isolated study tools++```text+python scripts/art_pipeline.py init reference-study+python scripts/art_pipeline.py check art/studies/reference-study/study.json+```++The initializer creates a pending brief/review and empty `source/`, `exports/`+and `evidence/` directories. It creates no model and approves no design. Never+overwrite an existing study; choose a new ID for a separate direction.++Add an asset entry after choosing the reference scope:++```json+{+ "id": "workshop-reference",+ "kind": "building",+ "source": "source/workshop.blend",+ "collection": "Export",+ "export": "exports/workshop.glb"+}+```++The review exporter reads paths from this manifest and requires a study inside+`art/studies/`. Run Blender separately, without loading embedded scripts:++```text+blender --background --factory-startup --disable-autoexec --python scripts/art/export_study.py -- --manifest art/studies/reference-study/study.json --asset workshop-reference+```++It exports only the named collection in the active scene, embeds textures and+replaces its study GLB only after a structural check. It does not promote assets+to production or replace the existing character build's contract checks.++Record runtime screenshots/video in `runtime_evidence` and a written check+result in `technical_report`, using study-relative file paths. Then run:++```text+python scripts/art_pipeline.py check art/studies/reference-study/study.json --stage reference+```++This returns an evidence fingerprint and still reports rollout as unapproved.+After actual user approval, write an English approval summary and scope in+`review.md` with `Decision: approved`. Keep private conversation content and+personal identifiers outside the public repository. Set `approval.status` to+`approved` and `approval.evidence_sha256` to the reviewed fingerprint:++```text+python scripts/art_pipeline.py check art/studies/reference-study/study.json --stage ready+```++Any changed source, export, brief or evidence invalidates that fingerprint.+The tool checks artifact consistency and approval-record completeness. It+cannot authenticate user consent, judge aesthetics, prove that a screenshot+is genuine or certify collision/performance claims. The agent must verify those+against the conversation and actual runtime tests. No command auto-approves,+copies a study into production or redesigns the island.++## Handoff to another coding agent++Provide the study path, approved reference and its scope, open art decisions,+editable sources, export command, integration map, test evidence and known+limitations. State the current stage and one concrete next action. An unfinished+reference is handed off as unfinished, even when its export and tests pass.diff --git a/docs/agent-society/world-art-direction.md b/docs/agent-society/world-art-direction.mdindex 2fcbe70189..a8d2272796 100644--- a/docs/agent-society/world-art-direction.md+++ b/docs/agent-society/world-art-direction.md@@ -1,5 +1,10 @@# World Art Direction — the island+> Art-production workflow amendment (2026-09-08): follow+> [Game-art production standard](game-art-pipeline.md) for future asset/design work.+> It governs reference-scene approval and rollout; this document's current runtime+> contracts remain intact. Its historical art choices are not approval of a new redesign.+Status: **binding for M3 (world), decided with the maintainer on 2026-09-01/02.**Subordinate to [`MASTERPLAN.md`](MASTERPLAN.md) §4.1/§4.3; this is the art-direction pass themaster plan requires before environment assets are built. Figures are governed bydiff --git a/docs/agent-society/world-masterplan-v2.md b/docs/agent-society/world-masterplan-v2.mdindex 0ef689fd03..dc5b323cfb 100644--- a/docs/agent-society/world-masterplan-v2.md+++ b/docs/agent-society/world-masterplan-v2.md@@ -1,5 +1,10 @@# World Master Plan v2 — from the first island to a professional game world+> Art-production workflow amendment (2026-09-08): follow+> [Game-art production standard](game-art-pipeline.md) for future asset/design work.+> It governs reference-scene approval and rollout; this document's current runtime+> contracts remain intact. Its historical art choices are not approval of a new redesign.+Status: **binding since 2026-09-02** — the maintainer took the four recommended decisions of §9(grain off by default, one house per agent, the 15 hubs, the scripted Blender World Kit); thisdocument succeeds [`world-art-direction.md`](world-art-direction.md) for everything it covers. Subordinate todiff --git a/scripts/art/export_study.py b/scripts/art/export_study.pynew file mode 100644index 0000000000..244445cf6f--- /dev/null+++ b/scripts/art/export_study.py@@ -0,0 +1,72 @@+"""Export one named collection from a .blend source into its isolated study.++blender --background --factory-startup --disable-autoexec --python+scripts/art/export_study.py -- --manifest art/studies/example/study.json --asset example+"""++from __future__ import annotations++import argparse+import os+import sys+import uuid+from pathlib import Path++import bpy++sys.path.insert(0, str(Path(__file__).resolve().parents[1]))+from art_pipeline import glb_report, local_file, read_manifest # noqa: E402+++def main() -> None:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--manifest", type=Path, required=True)+ parser.add_argument("--asset", required=True)+ args = parser.parse_args(sys.argv[sys.argv.index("--") + 1 :])+ manifest = args.manifest.resolve()+ studies = Path(__file__).resolve().parents[2] / "art/studies"+ if not manifest.is_relative_to(studies.resolve()):+ raise SystemExit("review exports must stay in this project's art/studies directory")+ data = read_manifest(manifest)+ asset = next((a for a in data["assets"] if a["id"] == args.asset), None)+ if asset is None:+ raise SystemExit(f"unknown study asset: {args.asset}")+ source = local_file(manifest.parent, asset["source"])+ target = local_file(manifest.parent, asset["export"])+ if not source.is_file():+ raise SystemExit("create and save the authored Blender source first")+ bpy.ops.wm.open_mainfile(filepath=str(source), load_ui=False, use_scripts=False)+ collection = bpy.data.collections.get(asset["collection"])+ if collection is None:+ raise SystemExit(f"missing export collection: {asset['collection']}")+ selected = [o for o in collection.all_objects if o.name in bpy.context.view_layer.objects]+ if not any(o.type == "MESH" for o in selected):+ raise SystemExit("export collection has no mesh in the active scene")+ bpy.ops.object.select_all(action="DESELECT")+ for obj in selected:+ obj.select_set(True)+ bpy.context.view_layer.objects.active = selected[0]+ target.parent.mkdir(parents=True, exist_ok=True)+ temporary = target.with_name(f".{target.stem}-{uuid.uuid4().hex}.glb")+ try:+ bpy.ops.export_scene.gltf(+ filepath=str(temporary),+ export_format="GLB",+ use_selection=True,+ use_active_scene=True,+ export_yup=True,+ export_extras=True,+ export_animations=True,+ export_skins=True,+ export_materials="EXPORT",+ )+ report = glb_report(temporary)+ os.replace(temporary, target)+ finally:+ temporary.unlink(missing_ok=True)+ print(f"Exported review asset {asset['id']}: {report}")+ print("Review export only; existing production asset gates still apply before integration.")+++if __name__ == "__main__":+ main()diff --git a/scripts/art_pipeline.py b/scripts/art_pipeline.pynew file mode 100644index 0000000000..b6f282ebf9--- /dev/null+++ b/scripts/art_pipeline.py@@ -0,0 +1,203 @@+"""Scaffold and check an isolated game-art study; never publish production assets."""++from __future__ import annotations++import argparse+import hashlib+import json+import re+import struct+from pathlib import Path++ROOT = Path(__file__).resolve().parents[1]+KINDS = {"character", "building", "prop", "terrain"}+++def local_file(root: Path, value: str) -> Path:+ """Study paths are portable and cannot escape through traversal or symlinks."""+ if not value or "\\" in value or ":" in value or Path(value).is_absolute():+ raise ValueError(f"expected a study-relative path: {value!r}")+ path = (root / value).resolve()+ if not path.is_relative_to(root.resolve()) or path == root.resolve():+ raise ValueError(f"path escapes the study: {value!r}")+ return path+++def read_manifest(path: Path) -> dict:+ data = json.loads(path.read_text(encoding="utf-8"))+ if data.get("schema") != 1 or not isinstance(data.get("assets"), list):+ raise ValueError("expected art study schema 1 with an assets list")+ seen = set()+ exports = set()+ for asset in data["assets"]:+ if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", asset.get("id", "")):+ raise ValueError("asset IDs must be lowercase slugs")+ if asset["id"] in seen or asset.get("kind") not in KINDS:+ raise ValueError("asset IDs must be unique and kinds must be known")+ seen.add(asset["id"])+ for key, suffix in (("source", ".blend"), ("export", ".glb")):+ target = local_file(path.parent, asset.get(key, ""))+ if target.suffix.lower() != suffix:+ raise ValueError(f"{asset['id']}: {key} must be {suffix}")+ export = local_file(path.parent, asset["export"])+ if export in exports:+ raise ValueError("each asset needs its own review export path")+ exports.add(export)+ if not isinstance(asset.get("collection"), str) or not asset["collection"].strip():+ raise ValueError(f"{asset['id']}: name the export collection")+ return data+++def init_study(slug: str, studies: Path | None = None) -> Path:+ if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", slug):+ raise ValueError("study ID must be a lowercase slug")+ parent = (studies or ROOT / "art/studies").resolve()+ folder = parent / slug+ # Refuse to overwrite an existing study, including an existing empty directory.+ folder.mkdir(parents=True, exist_ok=False)+ for name in ("source", "exports", "evidence"):+ (folder / name).mkdir()+ manifest = {+ "schema": 1,+ "study": slug,+ "brief": "brief.md",+ "assets": [],+ "runtime_evidence": [],+ "technical_report": "",+ "approval": {"status": "pending", "record": "review.md", "evidence_sha256": ""},+ }+ (folder / "study.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")+ (folder / "brief.md").write_text(+ "# Art study brief\n\n"+ "Record the user intent, visual references and their usage rights.\n\n"+ "## Decisions to establish\n\n"+ "- Audience, mood, shape language, palette and materials.\n"+ "- Camera, pixel treatment and normal viewing distance.\n"+ "- Reference scope: one character, one functional building and connecting ground.\n"+ "- Target devices, viewport and measurable runtime budgets.\n"+ "- Readability, animation, collision and accessibility acceptance criteria.\n\n"+ "No visual direction or engine migration has been approved by this scaffold.\n",+ encoding="utf-8",+ )+ (folder / "review.md").write_text(+ "# Reference review\n\nDecision: pending.\n\n"+ "Separate visual judgement from technical results. Record defects and revisions.\n"+ "After actual user approval, record its date, scope and an English summary here;\n"+ "keep private conversation content and personal identifiers outside the repository.\n"+ "A passing check or an agent's own opinion is not user approval.\n",+ encoding="utf-8",+ )+ return folder / "study.json"+++def glb_report(path: Path) -> dict:+ raw = path.read_bytes()+ if len(raw) < 20:+ raise ValueError("truncated GLB")+ magic, version, length, size, kind = struct.unpack_from("<IIIII", raw)+ if magic != 0x46546C67 or version != 2 or length != len(raw) or kind != 0x4E4F534A:+ raise ValueError("invalid GLB 2 container")+ if size > len(raw) - 20:+ raise ValueError("truncated GLB JSON")+ doc = json.loads(raw[20 : 20 + size])+ if not doc.get("meshes"):+ raise ValueError("reference asset contains no mesh")+ accessors = doc.get("accessors", [])+ for mesh in doc["meshes"]:+ if not mesh.get("primitives"):+ raise ValueError("mesh contains no primitives")+ for primitive in mesh["primitives"]:+ position = primitive.get("attributes", {}).get("POSITION")+ if not isinstance(position, int) or not 0 <= position < len(accessors):+ raise ValueError("mesh is missing a position accessor")+ if accessors[position].get("type") != "VEC3" or accessors[position].get("count", 0) < 3:+ raise ValueError("mesh has no usable position data")+ for entry in doc.get("buffers", []) + doc.get("images", []):+ if "uri" in entry:+ raise ValueError("embed buffers and textures in the review GLB")+ return {+ "bytes": len(raw),+ "meshes": len(doc["meshes"]),+ "materials": len(doc.get("materials", [])),+ "animations": [a.get("name", "") for a in doc.get("animations", [])],+ }+++def reference_files(path: Path, data: dict) -> list[str]:+ names = [data.get("brief", "")]+ for asset in data["assets"]:+ names.extend([asset["source"], asset["export"]])+ evidence = data.get("runtime_evidence", [])+ if not isinstance(evidence, list) or not all(isinstance(n, str) for n in evidence):+ raise ValueError("runtime_evidence must list study-relative files")+ names.extend(evidence)+ names.append(data.get("technical_report", ""))+ for name in names:+ if not local_file(path.parent, name).is_file():+ raise ValueError(f"missing review artifact: {name}")+ return sorted(set(names))+++def reference_hash(path: Path, data: dict) -> str:+ # Approval itself is excluded; all reviewed inputs and evidence are included.+ manifest = {k: v for k, v in data.items() if k != "approval"}+ digest = hashlib.sha256(json.dumps(manifest, sort_keys=True).encode())+ for name in reference_files(path, data):+ digest.update(name.encode())+ digest.update(hashlib.sha256(local_file(path.parent, name).read_bytes()).digest())+ return digest.hexdigest()+++def check(path: Path, stage: str = "draft") -> dict:+ path = path.resolve()+ data = read_manifest(path)+ if stage == "draft":+ return {"stage": stage, "assets": len(data["assets"]), "ready_to_roll_out": False}+ if not data["assets"] or not data.get("runtime_evidence"):+ raise ValueError("a reference needs real assets and evidence from the target runtime")+ reference_files(path, data)+ reports = {a["id"]: glb_report(local_file(path.parent, a["export"])) for a in data["assets"]}+ fingerprint = reference_hash(path, data)+ if stage == "ready":+ approval = data.get("approval", {})+ record = local_file(path.parent, approval.get("record", ""))+ if approval.get("status") != "approved" or not record.is_file():+ raise ValueError("record the user's reference-scene approval before rollout")+ if not re.search(+ r"^Decision: approved\.?$", record.read_text(encoding="utf-8"), re.M | re.I+ ):+ raise ValueError("approval record must state 'Decision: approved'")+ if approval.get("evidence_sha256") != fingerprint:+ raise ValueError("approval is stale: the reviewed assets or evidence changed")+ return {+ "stage": stage,+ "assets": reports,+ "evidence_sha256": fingerprint,+ "ready_to_roll_out": stage == "ready",+ }+++def main() -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ commands = parser.add_subparsers(dest="command", required=True)+ init = commands.add_parser("init")+ init.add_argument("slug")+ validate = commands.add_parser("check")+ validate.add_argument("manifest", type=Path)+ validate.add_argument("--stage", choices=["draft", "reference", "ready"], default="draft")+ args = parser.parse_args()+ try:+ result = (+ str(init_study(args.slug))+ if args.command == "init"+ else check(args.manifest, args.stage)+ )+ print(json.dumps(result, indent=2))+ return 0+ except (OSError, ValueError, KeyError, TypeError) as exc:+ print(f"art pipeline: {exc}")+ return 1+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/tests/unit/test_art_pipeline.py b/tests/unit/test_art_pipeline.pynew file mode 100644index 0000000000..cda3a9afe0--- /dev/null+++ b/tests/unit/test_art_pipeline.py@@ -0,0 +1,119 @@+"""Behavioural tests for the future art workflow, not for a proposed visual style."""++from __future__ import annotations++import importlib.util+import json+import struct+from pathlib import Path++import pytest++ROOT = Path(__file__).resolve().parents[2]+SPEC = importlib.util.spec_from_file_location("art_pipeline", ROOT / "scripts/art_pipeline.py")+assert SPEC and SPEC.loader+pipeline = importlib.util.module_from_spec(SPEC)+SPEC.loader.exec_module(pipeline)+++def save(path: Path, data: dict) -> None:+ path.write_text(json.dumps(data), encoding="utf-8")+++def triangle() -> bytes:+ doc = {+ "asset": {"version": "2.0"},+ "buffers": [{"byteLength": 36}],+ "bufferViews": [{"buffer": 0, "byteLength": 36}],+ "accessors": [{"bufferView": 0, "componentType": 5126, "count": 3, "type": "VEC3"}],+ "meshes": [{"primitives": [{"attributes": {"POSITION": 0}}]}],+ }+ text = json.dumps(doc).encode()+ text += b" " * (-len(text) % 4)+ binary = struct.pack("<9f", 0, 0, 0, 1, 0, 0, 0, 1, 0)+ return (+ struct.pack("<III", 0x46546C67, 2, 12 + 8 + len(text) + 8 + len(binary))+ + struct.pack("<II", len(text), 0x4E4F534A)+ + text+ + struct.pack("<II", len(binary), 0x004E4942)+ + binary+ )+++def reference(tmp_path: Path) -> tuple[Path, dict]:+ path = pipeline.init_study("reference", tmp_path)+ data = json.loads(path.read_text())+ data["assets"] = [+ {+ "id": "sample",+ "kind": "prop",+ "source": "source/reference.blend",+ "collection": "Reference",+ "export": "exports/sample.glb",+ }+ ]+ data["runtime_evidence"] = ["evidence/runtime.png"]+ data["technical_report"] = "evidence/checks.md"+ (path.parent / "source/reference.blend").write_bytes(b"test source fixture")+ (path.parent / "exports/sample.glb").write_bytes(triangle())+ (path.parent / "evidence/runtime.png").write_bytes(b"test evidence fixture")+ (path.parent / "evidence/checks.md").write_text("Fixture review results", encoding="utf-8")+ save(path, data)+ return path, data+++def test_new_study_is_pending_and_cannot_roll_out(tmp_path: Path) -> None:+ path = pipeline.init_study("world-study", tmp_path)+ assert pipeline.check(path)["ready_to_roll_out"] is False+ with pytest.raises(ValueError, match="real assets"):+ pipeline.check(path, "ready")+ with pytest.raises(FileExistsError):+ pipeline.init_study("world-study", tmp_path)++[email protected]("value", ["../escape", "/absolute", "C:/absolute", "nested\\path"])+def test_paths_cannot_escape_a_study(tmp_path: Path, value: str) -> None:+ with pytest.raises(ValueError):+ pipeline.local_file(tmp_path, value)+++def test_reference_check_does_not_grant_approval(tmp_path: Path) -> None:+ path, _ = reference(tmp_path)+ assert pipeline.check(path, "reference")["ready_to_roll_out"] is False+ with pytest.raises(ValueError, match="approval"):+ pipeline.check(path, "ready")+++def test_approval_expires_when_reviewed_content_changes(tmp_path: Path) -> None:+ path, data = reference(tmp_path)+ data["approval"].update(status="approved", evidence_sha256=pipeline.reference_hash(path, data))+ (path.parent / "review.md").write_text(+ "Decision: approved\nTest fixture decision.", encoding="utf-8"+ )+ save(path, data)+ assert pipeline.check(path, "ready")["ready_to_roll_out"] is True+ (path.parent / "source/reference.blend").write_bytes(b"a different test source")+ with pytest.raises(ValueError, match="stale"):+ pipeline.check(path, "ready")+++def test_missing_runtime_evidence_is_not_a_reference(tmp_path: Path) -> None:+ path, _ = reference(tmp_path)+ (path.parent / "evidence/runtime.png").unlink()+ with pytest.raises(ValueError, match="missing review artifact"):+ pipeline.check(path, "reference")+++def test_export_destinations_are_unique(tmp_path: Path) -> None:+ path, data = reference(tmp_path)+ data["assets"].append({**data["assets"][0], "id": "another"})+ save(path, data)+ with pytest.raises(ValueError, match="own review export"):+ pipeline.read_manifest(path)+++def test_truncated_export_is_rejected(tmp_path: Path) -> None:+ path, _ = reference(tmp_path)+ (path.parent / "exports/sample.glb").write_bytes(triangle()[:-4])+ with pytest.raises(ValueError, match="invalid GLB"):+ pipeline.check(path, "reference")