Skip to content

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.

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.md
new file mode 100644
index 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.yaml
new file mode 100644
index 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.md
new file mode 100644
index 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.yaml
new file mode 100644
index 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.md
index 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's
standard Git workflow: do not artificially leave completed work local, and do
not wait for extra PersonalJarvis permission to commit, branch, push, or open
diff --git a/CLAUDE.md b/CLAUDE.md
index 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's
standard Git workflow: do not artificially leave completed work local, and do
not wait for extra PersonalJarvis permission to commit, branch, push, or open
diff --git a/docs/agent-society/MASTERPLAN.md b/docs/agent-society/MASTERPLAN.md
index 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 product
release stays explicit and separate. Working
codename: `society`; the section keeps the name "Jarvis Agents" (§10).
diff --git a/docs/agent-society/character-pipeline.md b/docs/agent-society/character-pipeline.md
index 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.** Amended
the 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.md
new file mode 100644
index 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.md
index 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 the
master plan requires before environment assets are built. Figures are governed by
diff --git a/docs/agent-society/world-masterplan-v2.md b/docs/agent-society/world-masterplan-v2.md
index 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); this
document succeeds [`world-art-direction.md`](world-art-direction.md) for everything it covers. Subordinate to
diff --git a/scripts/art/export_study.py b/scripts/art/export_study.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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")