@volter/game-editor 0.5.65

package/template/.github/skills/vgai-threejs-authoring/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: vgai-threejs-authoring
+description: Build, rig, animate, diagnose, and visually refine polished native Three.js scenes and procedural assets with direct Object3D code, reusable construction helpers, geometry libraries, and an inspect-render-critique loop. Use for procedural models, rigid mechanical armatures, environments, static props, stylized materials, lighting, cameras, scene composition, or an agent-focused Blender-like workflow. Use vgai-3d-assets alongside this skill when the result should become a source document and a baked GLB. Do not use for Blender bpy work or imported skeletal retargeting.
+---
+
+# VGAI Three.js Authoring
+
+Author ordinary project source against Three.js. Treat the source module and
+live `Object3D` graph as truth. Use helpers for leverage, not as a replacement
+scene language.
+
+## Establish the authoring surface
+
+1. Read the project instructions and architecture.
+2. Locate the Three root or modeling build entry, existing helpers,
+   renderer setup, and verification commands.
+3. Start or reuse the VGAI editor immediately and keep it open.
+4. Capture a fixed-camera visual baseline.
+5. Inspect the live hierarchy, selected-object facts, renderer state, and
+   console before changing code.
+
+Never introduce a parallel entity tree, semantic operation log, generated
+scene JSON, or wrapper around ordinary Three.js access for agent control. Give
+important objects stable `Object3D.name` values or project metadata.
+
+Also use `vgai-3d-assets` for reusable source-backed assets,
+`vgai-animation-assets` for imported skeletons or clips, and
+`vgai-environment-art` for whole-scene art direction.
+
+## Choose the lowest sufficient layer
+
+Use these layers in order:
+
+1. Use Three.js directly for transforms, parenting, materials, lights,
+   cameras, curves, standard geometries, loaders, and animation.
+2. Use an existing project helper for repeated high-value construction.
+3. Use official Three.js addons before adding dependencies.
+4. Use a proven specialist library for booleans, BVHs, topology repair, or
+   asset optimization.
+5. Add a helper only after the same construction or failure-prone calculation
+   appears more than once.
+
+Keep alternate library representations temporary. Return a normal
+`BufferGeometry`, `Mesh`, `Group`, or other native `Object3D`.
+
+Read [references/helper-catalog.md](references/helper-catalog.md) before adding
+modeling capabilities or dependencies. That catalog answers *which op* — for
+*which surfacing mode* (palette, shader look, tiling projection, card, decal,
+provider retexture, procedural mask) and whether the asset needs UVs at all,
+walk the eight modes cheapest-first in the `vgai-3d-assets` skill's
+`references/surfacing.md`.
+
+## Author raw code
+
+Write named functions that return real objects:
+
+```ts
+function createObservatory(materials: Materials): THREE.Group {
+  const root = new THREE.Group();
+  root.name = 'observatory';
+  root.add(createTowerShell(materials.ivory), createTelescope(materials));
+  return root;
+}
+```
+
+Prefer hierarchy and local coordinates. Give each substantial assembly a
+meaningful origin. Share materials intentionally. Seed authored randomness.
+Use raw Three.js whenever a helper becomes awkward.
+
+## Author shader looks as native GLSL
+
+Keep shader source in ordinary `.vert`, `.frag`, or `.glsl` files and bind it
+with `THREE.ShaderMaterial` directly. A sibling `name.vert.glsl` +
+`name.frag.glsl` pair is the portable convention Asset Lab recognizes; it is
+not a VGAI format. Keep authored uniform defaults, defines, textures, and
+material composition beside the owning material in TS/TSX, where the runtime
+actually reads them. Never add a `.shader.json`, uniform sidecar, or generated
+shader graph to duplicate those facts.
+
+Open either GLSL file from Content to inspect the pair against a real WebGL
+preview. Asset Lab is visual-only: it does not duplicate the project's coding
+surface or write shader source. Edit the ordinary GLSL files with your normal
+coding tools; the open preview reloads them, and compiler diagnostics name the
+native file, stage, and source line. Use the reflected Inspector uniforms to
+explore values, geometry, and time/resolution inputs, then move accepted
+defaults into the owning TS/TSX—the controls are session-only by design.
+Resolve every compiler diagnostic before judging the look in its real scene,
+because neutral preview geometry cannot prove lighting, depth, transparency,
+postprocessing, or the game's actual texture bindings.
+
+## Compose postprocessing directly
+
+When a game needs postprocessing, add `@react-three/postprocessing` to that
+project and import its components directly. Do not create a VGAI chain file,
+effect registry, wrapper component, or JSON descriptor. The owning scene's JSX
+is already the ordered chain; conditionally render one effect to bypass it and
+move its JSX child to reorder it. Keep the finishing order restrained: render,
+limited AO, bloom, color grade, anti-aliasing, then output color/tone conversion.
+
+A 3D `.cube` color grade is an ordinary portable LUT. Open it from Content for
+Asset Lab's visual before/after comparison; intensity and interpolation there
+are session-only exploration. Load the accepted LUT with Three's
+`LUTCubeLoader`, hand its `texture3D` directly to the library's `LUT` effect,
+and author the accepted strength in TSX. Judge each bypass at the same camera,
+pose, exposure, and simulation time. Asset Lab deliberately has no chain source
+view: edit the ordinary TSX with the project's coding surface and watch the
+running viewport reload it.
+
+## Register reusable R3F prefabs
+
+An R3F component becomes a Content prefab only when the project declares a
+portable CSF story for it. Colocate `<Name>.stories.tsx`, set
+`meta.component` to the component itself, and author at least one standalone
+representative state. Update the story whenever the prefab's required props or
+display contract changes.
+
+The editor mounts the composed story off-screen and photographs that exact
+state. It never infers prefab intent or appearance from export status, scene
+placement, or a GLB path referenced by the component. A storyless component is
+valid scene implementation, but it does not belong in Content. Keep model
+files in Models; the component story may render a model, but does not turn the
+model into the component or the component into an inferred prefab.
+
+Use ordinary Storybook `args`, decorators, and loaders for required context.
+For a suspending R3F loader, do not put `<Suspense>` around the story content:
+the preview captures the first commit, so a committed fallback would be the
+photographed subject.
+
+## Build for visual quality
+
+Establish these before micro-detail:
+
+- a readable primary silhouette;
+- asymmetry and at least three depth layers;
+- a clear focal object and subordinate forms;
+- intentional key, fill, and rim light;
+- a restrained material palette with readable value and surface contrast;
+- camera framing chosen for the composition, not merely fitting bounds.
+
+Work through three frequency bands:
+
+1. Primary forms carry silhouette, proportion, and composition.
+2. Secondary forms explain construction: profiles, frames, ribs, supports,
+   openings, joints, and material transitions.
+3. Tertiary accents appear only where the intended camera can read them.
+
+A primitive remains blocking geometry until it has deliberate proportions,
+edge treatment, a believable relationship with adjacent forms, and suitable
+surface response. Object count is not a quality metric; count visible authored
+decisions.
+
+Treat emissive materials, ambient occlusion, and bloom as accents. If an effect
+erases ribs, frames, texture, or material boundaries, reduce the effect before
+adding geometry.
+
+## Author stylized rendering honestly
+
+For cel shading, use a nearest-filter gradient ramp with `MeshToonMaterial`.
+For hard linework, combine inverted back-face hulls for silhouettes with
+`EdgesGeometry` for intentional internal creases.
+
+Treat style as a runtime-wide contract, not a promise made by one builder.
+Inventory the live material classes after every async GLB and modeled object
+has loaded. A helper that exists but is never imported by the mounted root has
+implemented nothing. Apply the policy to the real runtime graph and expose a
+small debug report so playtests can prove which materials were converted,
+preserved, or excluded.
+
+Author the policy per material family and per material slot. Use harder ramps
+for focal props, characters, and readable detail; use a softer, higher-floor
+ramp for broad architectural planes so point lights do not create concentric
+band stains or crush the whole foreground. Preserve intentional Basic,
+transparent/glass, emissive, and special-effect materials. When replacing a
+material, carry forward its maps, vertex colors, alpha test, AO/normal/emissive
+inputs, side, depth, and blend settings. A mixed material array must preserve
+and convert each slot independently.
+
+Attach derived ink beneath source meshes so animation and transforms remain
+automatic. Exclude transparent smoke, glass, skies, and soft background forms
+unless the art direction explicitly requires outlines.
+
+An ordinary inverted-hull `ShaderMaterial` that expands `position` and
+`normal` is not skinning-safe. Reject `SkinnedMesh` at the outline helper
+boundary unless the shader explicitly includes and proves skinning/morph
+chunks; a caller-side entity whitelist is not sufficient. For character ink,
+use a deformation-aware path and inspect it in bent shoulder, hip, elbow,
+knee, wrist, and ankle poses. Expose and assert that a rigid-only path outlined
+zero skinned meshes.
+
+Specify silhouette width in pixels when framing can change. Derive view-space
+offset from depth, projection scale, and drawing-buffer height; refresh the
+height after resize. Keep creases thinner and fade them sooner than
+silhouettes. Prefer dark hues related to each material family over uniform
+black.
+
+Author stylized profiles per material family. Control lit/shadow color, band
+threshold and softness, graphic highlight, rim, and thresholded specular
+response. Preserve native Three.js lighting and shadows. `onBeforeCompile` is
+version-sensitive; compile it in real WebGL after Three.js upgrades.
+
+Run an ink-off diagnostic. The same fixed-camera frame must remain readable
+through value grouping, shadow hue, highlights, and rims. Contours clarify
+forms; they do not rescue confused materials.
+
+Use only visual-inspection boundaries as workflow steps. One style iteration
+produces and inspects, at the same camera and pose: the prior runtime frame,
+toon with ink disabled, toon with ink enabled, and the full game composite.
+Keep typecheck, shader compilation, material census, and scene validation
+inside that same step; they are supporting checks, not separate milestones.
+Reject broad-plane band stains, shadow crush, lost texture identity, mixed PBR/
+toon assets, bind-pose outlines, or HUD/camera mismatch before continuing.
+
+Use postprocessing as a finishing layer. A restrained order is render, limited
+AO, restrained bloom, subtle color composite, SMAA, then output color/tone
+conversion. Keep project-owned presentation separate from exported model
+content.
+
+## Rig at the correct deformation layer
+
+- Use `Object3D` or `Bone` hierarchies for rigid articulated machinery.
+- Use `SkinnedMesh` only for continuous deformation across a joint.
+- Attach rigid accessories directly to their owning joint.
+- Use morph targets for localized shape changes not naturally expressed by a
+  joint.
+
+Put pivots at physical joint centers and author child geometry in local
+coordinates. A `THREE.Bone` does not require a `SkinnedMesh`; use bones when
+armature semantics and `SkeletonHelper` aid inspection.
+
+Keep pose policy separate from construction. Use a deterministic pose function
+for procedural locomotion and exact comparisons. Use native `AnimationClip`
+and `AnimationMixer` when motion must be blended, serialized, edited, or baked.
+Apply contact or IK correction after the base pose.
+
+Validate a full cycle. Sample every driven joint and end effector at exact
+times; reject non-finite transforms, duplicate names, insufficient joint
+range, and negligible contact travel. Inspect support and passing poses. Hide
+rig helpers outside diagnostics.
+
+Animation cadence is separate from render cadence. For stepped motion,
+quantize pose time while rendering and responding at display refresh rate.
+Derive transforms from stored base values; do not accumulate with `+=` unless
+drift is intentional.
+
+## Render self-review is MANDATORY — the look protocol
+
+After EVERY modeling milestone — a new mesh, a kit op applied, a material/
+shading change, a fit or weld — render your work and LOOK at the pixels
+before proceeding. Self-reports ("the topology is correct", "tests pass")
+are not visual evidence; only a render is.
+
+**Everything below happens inside YOUR project directory.** The one command
+is `npx volter-game-editor screenshot`, and the module lane is the asset loop:
+
+1. Look at a builder: `npx volter-game-editor screenshot src/models/<thing>.ts` runs that
+   module's default export headlessly in Node, exports the `Object3D` it
+   returns to an in-memory GLB, and photographs it in your live editor
+   session. `--export <fn>` picks a non-default export. Nothing is written
+   under `public/` and no provenance record is created — a look is not an
+   export. (It needs a live session for this project: `npx volter-game-editor edit .`.)
+2. Look at a baked file: `npx volter-game-editor screenshot <path.glb>` — front/right/top/
+   3-quarter plus a contact sheet, through the Asset Lab.
+3. Ask for canonical angles rather than ad-hoc ones: `--shots <set>`
+   resolves the registered `project.<set>.previewShots` tool, and a lib that
+   registers a set gets it by default. `--size`/`--width`/`--height` frame
+   it; `--compare <ref.glb>` scores silhouette IoU against a reference.
+4. READ every printed PNG before the next edit: silhouette, shading, nothing
+   clipped or inside-out, vert/tri budget. A defect you can see is a defect —
+   fix it before building more on top of it.
+5. Framing is automatic from your mesh's bounding box — if a render looks
+   empty or mis-framed, your geometry (scale/position/origin) is wrong, not
+   the camera. The corollary is a real blind spot: an asset lane auto-frames
+   its subject, so it can NEVER show you a wrong origin, a floating contact
+   plane, or a scale that disagrees with the world. Only a scene shot can —
+   `npx volter-game-editor screenshot` with no target (play mode, whole stack) or `vgai
+   screenshot <entityId>` (one entity where it stands, under the scene's own
+   lighting).
+
+> Engine-repo aside — not for game projects. When you are working inside the
+> vgai engine checkout itself (no game project, no editor session), the
+> equivalent is `node packages/engine/e2e/turntable/capture.mjs <subject>`,
+> run from the checkout root; it boots and tears down its own server. Point
+> it at your own builder with `capture.mjs file --module
+> /<repo-relative-path>.ts --export <fn>`, add `--zooms full,top,detail`
+> (detail takes `--focus x,y,z`) for close-ups, and `npx biome check --write
+> <your-file>.ts` before finishing, since unformatted engine files block the
+> repo's lint for everyone.
+
+## Run the refinement loop
+
+For every meaningful iteration:
+
+1. Build or typecheck.
+2. Reload or rebuild the raw source graph.
+3. Inspect names, bounds, hierarchy, camera, renderer statistics, warnings,
+   and failed requests.
+4. Freeze procedural motion at a known time.
+5. Capture the same viewport and camera as the baseline.
+6. Identify the largest visible defect.
+7. Make the smallest source change that tests the diagnosis.
+8. Repeat until the pixels are visibly better.
+
+When the project has `@volter/editor-live`, make the shared editor view the evidence
+boundary instead of taking an unrelated page screenshot:
+
+```ts
+const shown = await editor.present({
+  version: 1,
+  document: { kind: 'workspace', id: 'workspace:scene' },
+  viewport: { camera: 'isometric', frame: 'document' },
+});
+const actual = await editor.currentView();
+const capture = await editor.captureActiveDocument();
+```
+
+Treat `actual` as the postcondition and `capture.document` as provenance for
+the pixels. `present()` is an intent, not proof: the active document may have
+degraded, failed to mount, or been changed by the human. Keep the returned
+share link with critique notes so the same subject, camera, diagnostic, and
+utility can be reopened for the next cycle.
+
+Do not declare success because code is shorter, more reusable, or produces
+fewer commands.
+
+## Validate the deliverable
+
+Before finishing:
+
+- run project production/type validation;
+- verify no runtime or WebGL shader errors;
+- verify stable names and direct graph inspection;
+- verify derived ink is non-interactive and follows source transforms;
+- verify outline width at default and materially different framing;
+- verify material design with ink disabled;
+- verify every loaded asset participates in the intended runtime material-family policy;
+- verify broad planes have no band stains or crushed readable shadow detail;
+- verify rigid-only outline paths report zero outlined `SkinnedMesh` objects;
+- compare finishing effects at one exact pose;
+- verify deterministic rebuild and bounded animation;
+- verify a full-cycle report has finite, meaningful ranges and travel;
+- verify cleanup and disposal;
+- compare final browser-rendered evidence against the baseline;
+- record generally useful helpers in the catalog while keeping one-off
+  assemblies project-owned.
+
+When a helper improves one scene but harms another, keep it local until its
+contract is understood.

package/template/.github/skills/vgai-threejs-authoring/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "VGAI Three.js Authoring"
+  short_description: "Build polished native Three.js scenes and assets"
+  default_prompt: "Use $vgai-threejs-authoring to build and visually refine native Three.js source without introducing a parallel scene model."

package/template/.github/skills/vgai-threejs-authoring/references/helper-catalog.md

@@ -0,0 +1,65 @@
+# Native Three.js helper and dependency catalog
+
+Use this reference to decide whether a task needs Blender, direct Three.js, a
+small project helper, or a specialist geometry library.
+
+**MODELING IS BLENDER'S.** A model is a `.blend`, authored in the real Blender
+running headless in the editor tab, and a game loads the GLB it exports. Reach
+for `vgai-3d-models` (bpy through the Blender MCP).
+
+**Add a capability before you look for its source.** Everything under
+`src/lib/` below is a CAPABILITY, not scaffold contents — a fresh project has
+no `src/lib/` directory at all. Run `npx volter-game-editor add <id>` to copy the source in as
+ordinary project files you own and edit; bare `npx volter-game-editor add` lists every
+capability and marks what is already present.
+
+
+## Direct Three.js
+
+Use directly for `Object3D` hierarchy and transforms; standard geometries,
+`Shape`, extrusion, lathing, tubes, and curves; materials, textures, lights,
+shadows, cameras, loaders, raycasting, and animation; and official addons such
+as `RoundedBoxGeometry` and `BufferGeometryUtils`. Do not wrap ordinary
+property access.
+
+## Rigging and validation helpers
+
+Keep helpers thin: create named native joints; sample exact-time poses and
+end-effector bounds; report unique names, finite transforms, angular range,
+and contact travel; expose `SkeletonHelper` only as a diagnostic; and convert
+accepted reusable motion into ordinary `AnimationClip`s.
+
+Do not wrap `AnimationMixer`, `AnimationClip`, `KeyframeTrack`, or normal bone
+transforms. Rigid machinery attaches parts directly to joints; deforming
+meshes require real normalized skin attributes — weight them in Blender and
+let the glTF exporter write `JOINTS_0`/`WEIGHTS_0`. Blender's automatic
+weighting can report FINISHED having weighted nothing: check the weights.
+
+## Geometry libraries
+
+- `three-mesh-bvh` for accelerated raycasting, closest-point queries, surface
+  placement and large-mesh spatial tests; `three-bvh-csg` for booleans on
+  watertight meshes when raw `BufferGeometry` interop matters — validate
+  structurally and visually. Both are ordinary libraries you call directly.
+- Evaluate Manifold for robust solids, converting results back to
+  `BufferGeometry`.
+- Use Replicad or OpenCascade only when CAD workplanes, precise fillets,
+  shells, or face selection justify their cost.
+- Use glTF Transform outside the runtime bundle for welding, pruning,
+  simplification, instancing, compression, and texture processing.
+
+Learn functional composition from JSCAD, workplanes/selectors from CadQuery,
+and presentation helpers from Drei. Modifier coverage is Blender's own. Do not
+adopt an alternate persistent scene model to imitate them.
+
+## Proven prototype surface
+
+Proven craft techniques: profile lathing, beveled extrusion, arched frames,
+deterministic canvas textures, CSG, curve pipes, per-material anime profiles,
+pixel-width silhouette ink, distance-faded creases, rigid bone chains,
+exact-time gait validation, stepped pose timing, hard shadows, environment
+lighting, limited AO/bloom, a subtle color composite, and SMAA. Treat them as
+techniques to write in project source, not runtime APIs. Portable GLB ink
+emits ordinary expanded meshes and `LineSegments`; the source-quality
+ink uses project shader hooks and should remain source-only unless an explicit
+import recipe recreates it.

package/template/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "vgai": {
+      "command": "npm",
+      "args": ["run", "--silent", "vgai", "--", "mcp", "."]
+    },
+    "blender": {
+      "command": "npm",
+      "args": ["run", "--silent", "vgai", "--", "blender-mcp"]
+    }
+  }
+}

package/template/.vgai/assets.json

@@ -0,0 +1 @@
+{}

package/template/.vgai/provenance.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "operations": {}
+}

package/template/.volter/tracker/validation/.preset.base.mts

@@ -0,0 +1,178 @@
+// A minimal preset that follows the rules. Domain: a simple spec issue whose
+// acceptance criteria are GFM task-list items, each carrying commit-backed
+// evidence as a nested list. The whole thing is ONE strict Zod schema; mdast
+// fills it; rules validate it with injected context.
+//
+// Hard schema = the core fields (id/title/summary/status, id/status/evidence,
+// id) PLUS preset-specific strict fields (a status enum, AC `text`, evidence
+// `commit`). No passthrough, no unknown.
+
+// A STANDALONE preset: imports ONLY the public mechanism from `ztrack/preset-kit`.
+import {
+  z, toMdast, nodeText, type MdNode,
+  check as runCheck, rule, gitWorld,
+  type Context, type IssueColumns, type IssueRecord, type Preset, type VisualizerSpec,
+} from 'ztrack/preset-kit';
+
+// ── the hard schema (core + preset-specific, all strict) ────────────────────
+export const SpecEvidenceSchema = z.object({
+  id: z.string().min(1),                              // core
+  commit: z.string().regex(/^[0-9a-f]{7,40}$/),       // preset: evidence is commit-backed
+}).strict();
+
+export const SpecAcStatusSchema = z.enum(['pending', 'passed', 'failed']); // preset's status vocabulary
+export const SpecAcSchema = z.object({
+  id: z.string().min(1),                              // core
+  status: SpecAcStatusSchema,                          // core (preset narrows the type)
+  evidence: z.array(SpecEvidenceSchema),              // core
+  text: z.string().min(1),                            // preset
+}).strict();
+
+export const SpecIssueStatusSchema = z.enum(['draft', 'in-review', 'done']);
+export const SpecIssueSchema = z.object({
+  id: z.string().min(1),                              // core
+  title: z.string().min(1),                           // core
+  summary: z.string(),                                // core
+  status: SpecIssueStatusSchema,                       // core (narrowed)
+  acceptanceCriteria: z.array(SpecAcSchema),          // core
+}).strict();
+
+export const SpecRootSchema = z.object({ issues: z.array(SpecIssueSchema) }).strict();
+export type SpecRoot = z.infer<typeof SpecRootSchema>;
+
+// ── mdast parse: markdown -> the schema shape (structured, no prose mining) ──
+// MdNode / toMdast / nodeText are rented from the kit (shared mdast mechanism).
+function firstParagraphText(item: MdNode): string {
+  const p = (item.children ?? []).find((c) => c.type === 'paragraph');
+  return p ? nodeText(p).split('\n')[0]!.trim() : '';
+}
+
+// designated-position parses (the AC line, the evidence line) — not free-prose mining.
+function splitAcIdText(line: string): { id: string; text: string } {
+  const m = /^(\S+)\s+(.+)$/.exec(line);
+  return m ? { id: m[1]!, text: m[2]!.trim() } : { id: line, text: line };
+}
+
+function parseSpecIssue(record: IssueRecord): Record<string, unknown> {
+  // id/title/status come STRUCTURED from the record's columns; only summary + ACs are
+  // parsed from the body.
+  const issue: Record<string, unknown> = { id: record.id, title: record.title, status: record.status || 'draft', summary: '', acceptanceCriteria: [] };
+  const tree = toMdast(record.body);
+  let inAc = false;
+
+  for (const node of tree.children ?? []) {
+    if (node.type === 'heading') {
+      inAc = /acceptance criteria/i.test(nodeText(node));
+      continue;
+    }
+    if (node.type === 'paragraph') {
+      const summary = /^Summary:\s*(.+)$/im.exec(nodeText(node))?.[1]?.trim();
+      if (summary) issue.summary = summary;
+      continue;
+    }
+    if (node.type === 'list' && inAc) {
+      const acs: unknown[] = [];
+      for (const item of node.children ?? []) {
+        if (item.type !== 'listItem') continue;
+        const { id, text } = splitAcIdText(firstParagraphText(item));
+        const status = item.checked === true ? 'passed' : 'pending';
+        const evidence: unknown[] = [];
+        const nested = (item.children ?? []).find((c) => c.type === 'list');
+        for (const evItem of nested?.children ?? []) {
+          const commit = /commit:\s*([0-9a-fA-F]+)/.exec(firstParagraphText(evItem))?.[1]?.toLowerCase();
+          if (commit) evidence.push({ id: `${id}/ev${evidence.length + 1}`, commit });
+        }
+        acs.push({ id, status, text, evidence });
+      }
+      issue.acceptanceCriteria = acs;
+    }
+  }
+  return issue;
+}
+
+// The root: each issue's metadata is structured (its record's columns); content from body.
+export function parseSpec(records: IssueRecord[]): unknown {
+  return { issues: records.map(parseSpecIssue) };
+}
+
+// ── serialize: the validated issue -> its STORED form (content body + metadata columns) ──
+// The evidence id is positional (`<acId>/ev<n>`), so it isn't emitted — re-parsing
+// regenerates it. A passed AC is the checked box; pending/failed are unchecked.
+export function serializeSpecIssue(issue: SpecRoot['issues'][number]): { body: string; columns: IssueColumns } {
+  const out: string[] = [];
+  if (issue.summary) out.push(`Summary: ${issue.summary}`, '');
+  out.push('## Acceptance Criteria', '');
+  for (const ac of issue.acceptanceCriteria) {
+    out.push(`- [${ac.status === 'passed' ? 'x' : ' '}] ${ac.id} ${ac.text}`);
+    for (const ev of ac.evidence) out.push(`  - commit: ${ev.commit}`);
+  }
+  return { body: out.join('\n') + '\n', columns: { title: issue.title, status: issue.status } };
+}
+
+// ── rules: declarative records over the engine's derived model ──────────────
+// Duplicate-id detection is universal, so it arrives on the core model (m.duplicateAcIds
+// / m.duplicateIssueIds) — this preset writes no derive and uses no blocking graph.
+type SpecAC = SpecRoot['issues'][number]['acceptanceCriteria'][number];
+type SpecEvidence = SpecAC['evidence'][number];
+
+const shaMatches = (a: string, b: string) => a.startsWith(b) || b.startsWith(a);
+
+const SPEC_RULES = [
+  rule<SpecRoot, { issueId: string; acId: string; ac: SpecAC }>({
+    code: 'passed_ac_missing_evidence', select: (m) => m.acs,
+    when: ({ ac }) => ac.status === 'passed' && ac.evidence.length === 0,
+    message: ({ ac }) => `AC ${ac.id} is passed but cites no commit-backed evidence.`,
+  }),
+  rule<SpecRoot, { issueId: string; acId: string; evidenceId: string; ev: SpecEvidence }>({
+    code: 'evidence_commit_not_found', select: (m) => m.evidence,
+    when: ({ ev }, m) => { const c = m.context.git?.existingCommits; return !!c && !c.some((x) => shaMatches(x, ev.commit)); },
+    message: ({ ev }) => `Evidence ${ev.id} cites commit ${ev.commit}, which does not exist.`,
+    subject: ({ ev }) => ev.commit,  // the missing sha — a `ref:` waiver pins to exactly this occurrence
+  }),
+  rule<SpecRoot, { issueId: string; acId: string }>({
+    code: 'duplicate_ac_id', select: (m) => m.duplicateAcIds,
+    message: ({ acId }) => `Duplicate AC id ${acId}.`,
+  }),
+  rule<SpecRoot, { issueId: string }>({
+    code: 'duplicate_issue_id', select: (m) => m.duplicateIssueIds,
+    message: ({ issueId }) => `Duplicate issue id ${issueId}.`,
+  }),
+];
+
+// ── the dashboard's vocabulary (VIZ-2), as plain data ────────────────────────────────────────
+// spec's OWN vocabulary — NOT simple-sdlc's default.tsx vocabulary, which this preset's schema
+// doesn't share: a 3-state lifecycle (no ready/in-progress split), no assignee, no PR, and an AC
+// with just id/text (no version, no proof, no image/acVersion-bearing evidence — see
+// SpecAcSchema/SpecEvidenceSchema above). Only map fields this schema actually has; a mapping
+// this preset can't back with a real field (pr, acProof, acEvidence) is simply omitted. Field
+// references and literal labels ONLY (see `VisualizerSpec`, `ztrack/preset-kit`) — no functions,
+// no markup. Installed into your repo verbatim: edit freely, keeping statusOrder in sync with
+// SpecIssueStatusSchema above (`boilerplates/presets/visualizerVocabulary.test.ts` checks that).
+const SPEC_VISUALIZER: VisualizerSpec = {
+  statusOrder: ['draft', 'in-review', 'done'], // must equal SpecIssueStatusSchema above
+  acUnitLabel: 'Acceptance Criteria',
+  acText: { id: 'id', text: 'text' },          // SpecAcSchema.{id,text} — no `version` field to map
+  // no assignee/pr: SpecIssueSchema has neither. No acProof: SpecAcSchema has no proof field.
+  // No acEvidence: SpecEvidenceSchema is only {id, commit} — no image/acVersion fields to map.
+};
+
+export const SpecPreset: Preset<SpecRoot> = {
+  name: 'spec',
+  schema: SpecRootSchema,
+  visualizer: SPEC_VISUALIZER,
+  // observed facts: commit existence (no PR model in this preset).
+  loadContext: (input) => gitWorld(input.projectRoot, [], { verifyCommits: input.verifyCommits }),
+  parse: parseSpec,
+  serialize: serializeSpecIssue, // issue -> { body, columns }; the inverse of parse
+  rules: SPEC_RULES,
+  // `ztrack issue scaffold` starter: a pending AC (green to begin). Mark it [x] + cite a
+  // `- commit: <sha>` once the behavior is implemented.
+  scaffold: (_title) => `Summary: A short spec of the behavior.\n\n## Acceptance Criteria\n\n- [ ] AC-1 Describe one observable acceptance criterion.\n`,
+};
+
+export function checkSpec(records: IssueRecord[], ctx?: Context) {
+  return runCheck(SpecPreset, records, ctx);
+}
+
+// The installed entrypoint: the resolver reads the preset off `default`.
+export default SpecPreset;