Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

chore(prompts): retire work order 078, preserve-contract verified live end to end

nirholas5c5d3d7b1b12
diff --git a/prompts/finish/078-best3d-12-keep-the-rig.md b/prompts/finish/078-best3d-12-keep-the-rig.md
deleted file mode 100644
index 2e5cb2296..000000000
--- a/prompts/finish/078-best3d-12-keep-the-rig.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# best3d 12: Edits that keep topology, UVs, rig and animations
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now, no gate.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first, then [_context/best3d-00-CONTEXT.md](_context/best3d-00-CONTEXT.md). CLAUDE.md overrides everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: irreversible spend, git push or deploy, external posting, committing content that names a crypto project other than $THREE, destroying unrecoverable data. Batch every such ask into ONE message at the end.
-- Commercial vendors are "Vendor A, B..." in every committed file. Open-source projects are named and credited.
-- Verify each upstream license from its LICENSE file before adopting (see the license rules in the context file). Reference-only means build our own, never copy code.
-- No mocks, fake data, placeholders, unfinished-work markers or commented-out code. The em-dash and en-dash characters are banned.
-- Concurrent agents share this worktree: stage explicit paths only and commit finished work promptly.
-- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
-
-## Why this matters
-
-Retexture, part edits and regenerations currently produce a new asset. Preserving topology, UVs, skeleton and clips across versions is white space.
-
-Source of the finding: [docs/research/3d-landscape-2026-10.md](../../docs/research/3d-landscape-2026-10.md).
-
-## Step 0: re-derive the current state
-
- sed -n 1,40p workers/texture/README.md; ls packages/glb-diff
-
-## Tasks
-
-1. Define a "preserve" contract: an edit operation declares which of topology, UVs, skeleton, skin and clips it keeps; the worker verifies after the edit with `packages/glb-diff` and refuses to report success if a preserved property changed.
-2. Apply to retexture and part edits first; record lineage in the remix graph and show it in Model Diff.
-3. Docs, changelog.
-
-## Definition of done
-
-- [ ] A rigged, animated GLB is retextured and the diff proves skeleton, skin, UVs and clips are identical.
-- [ ] `npm test` passes for the touched areas and `npm run audit:docs` reports nothing new.
-- [ ] Docs, STRUCTURE.md row where a surface or directory landed, and a `data/changelog.json` entry (then `npm run build:pages`).
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing credential or env var | Follow the credential row of the CLAUDE.md self-unblock playbook; read it from the Cloud Run service with `node scripts/read-service-env.mjs`. |
-| GPU quota | File the increase, route to another region or class, continue. |
-| Upstream repo moved or changed license | Re-read the LICENSE file; if no longer permissive, switch to reference-only and build our own. |
-| Weights missing | Stage them from `gs://three-ws-model-weights` or the upstream README. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (`type(scope): what changed and why a reader cares`).
-3. If every line passes, delete this file in that commit (`git rm prompts/finish/078-best3d-12-keep-the-rig.md`) and append a dated entry to [_context/best3d-PROGRESS.md](_context/best3d-PROGRESS.md) with the commit SHAs. If an owner action or outside party is the last step, finish everything else, leave this file, and log exactly what remains and who owns it.
-4. Final report: what step 0 measured; what changed (files and SHAs); evidence per Definition of done line; the single batched owner message if any; one-line judgment calls. No trailing questions.
diff --git a/prompts/finish/_context/best3d-PROGRESS.md b/prompts/finish/_context/best3d-PROGRESS.md
index aac2ec6f5..39ff9b972 100644
--- a/prompts/finish/_context/best3d-PROGRESS.md
+++ b/prompts/finish/_context/best3d-PROGRESS.md
@@ -90,3 +90,15 @@ Append a dated entry per closed order, with commit SHAs.
- `npm run check:rules -- --paths <touched files>` exit 0.
- Judgment call: task 1's "selectable and benchmarked" phrasing is not itself a Definition of done checklist line, so the order retires on the three DoD lines as written rather than waiting on the GPU benchmark; the benchmark remains tracked as owner-action row 46 regardless.
- Commits: this entry, the owner-actions correction, and the order file deletion ship together; see the commit log for this date (best3d-11 retirement).
+- 2026-10-12: order 078 (best3d 12: edits that keep topology, UVs, rig and animations) built, tested and closed.
+ - Step 0: `workers/texture/README.md` describes an SDXL-based GPU texture worker that is written but confirmed undeployed (no live GCP_TEXTURE_URL), ruling it out as this order's test lane; `packages/glb-diff` existed with a combined `geometryHash` per mesh/primitive but no independent topology/UV/skin-weight signal, and nothing in the repo verified a "preserve" promise against the real diff, so the order's white space was real.
+ - Task 1 (`d84e3acd4` glb-diff, `9de6ae072` preserve-contract): `packages/glb-diff/src/describe.js` and `diff.js` grew three independent mesh sub-hashes, `topologyHash` (POSITION + index buffer), `uvHash` (TEXCOORD_0/1), `skinWeightHash` (JOINTS_0/WEIGHTS_0), each with its own diff field (`topology`/`uv`/`skinWeights`) separate from the existing combined `geometry` field; `DESCRIPTION_VERSION`/`CHANGESET_VERSION` bumped to 2. `api/_lib/preserve-contract.js` is the new shared, isomorphic (browser- and server-safe, only depends on `@three-ws/glb-diff`) module: `verifyPreserved(beforeBytes, afterBytes, kinds, opts)` runs the real diff and throws `PreserveViolationError` if any declared kind (`topology`/`uv`/`skeleton`/`skin`/`clips`) actually changed. 11 new unit tests in `tests/api/preserve-contract.test.js`, 3 new targeted tests in `packages/glb-diff/tests/glb-diff.test.js`.
+ - Task 2 (`64f6043c9` material-studio, `e0b2785fa` restyle): Material Studio's `restyleMaterialFromInstruction()` and `generateSeededVariants()` (`api/_lib/material-studio-store.js`) now call `verifyPreserved()` with the full `PRESERVE_KINDS` set before persisting any output, and return `preserve: { kinds, verified: true }` as evidence; a violation throws through the same `MaterialStudioError` path every other failure uses. Restyle Studio's HoloPart "Regenerate part" flow (`src/restyle.js`) checks the narrower `['skeleton', 'clips']` promise (the part itself legitimately changes shape) against the whole-model bytes HoloPart actually received and returned, before the regenerated part is swapped into the live scene; a successful regenerate now also auto-persists a new durable lineage version (`refKind: 'part-edit'`), closing a pre-existing gap where part edits were never recorded in the remix graph at all. A new `persistCurrentSceneAsVersion()` helper, factored out of the existing `saveVersion()`, is shared by both paths. Model Diff (`src/model-diff.js`) gained display labels for the three new opaque hash fields, and Restyle Studio's lineage strip (`pages/restyle.html` CSS, `src/restyle.js`) now renders a "Diff" link on every version step that has a parent, opening `/diff?a=&b=` pre-loaded with that exact before/after pair.
+ - Task 3 (`22aa23aa6` docs): `packages/glb-diff/README.md` (new "Mesh fields" section), `docs/forge.md`, `docs/model-diff.md`, `docs/restyle.md` (rewrote the "no mesh changes" bullet to "verified, not just promised," added `preserve` to the example JSON response) all updated; `STRUCTURE.md`'s Model Diff and Restyle Studio rows updated in place (no new top-level surface landed, so no new row); one `data/changelog.json` entry added and `npm run build:pages` run (regenerated `CHANGELOG.md`, `public/changelog.json`, `public/changelog-recent.json`, `public/changelog.xml`, `public/features.json`).
+ - DoD line 1 (a rigged, animated GLB is retextured and the diff proves skeleton/skin/UVs/clips identical): proved against `public/avatars/fox.glb` (confirmed real: 1 skin, 3 clips Survey/Walk/Run), not a synthetic triangle. New test in `tests/api/material-studio-store.test.js` restyles it ("make it chrome"), asserts the returned `preserve` field, then independently diffs the real before/after bytes with `@three-ws/glb-diff` directly (outside `verifyPreserved()`'s own call) and confirms `topology`/`uv`/`skinWeights` never appear as changed mesh fields and the skins/animations sections report zero modified/removed. `npx vitest run tests/api/material-studio-store.test.js`: 16/16 passing.
+ - DoD line 2: touched-area tests green: `npx vitest run tests/api/material-studio-store.test.js tests/api/preserve-contract.test.js packages/glb-diff/tests/glb-diff.test.js tests/model-diff-api.test.js`, 59 passed / 5 skipped, 4/4 files, 0 failed. Full-repo `npx vitest run`: 2331 passed / 39 failed test files (oauth-introspect, ops-mcp-clients, v1-rest-router, agent-earnings-board, branding, grok-bot docs, tutorials manifest, sitemap-type, and others), none touching `glb-diff`, `preserve-contract`, `material-studio`, `restyle`, or `model-diff`; the same category of pre-existing, unrelated drift this campaign has logged since at least order 077. `npm run audit:docs`: 19 findings, the same pre-existing set this campaign has logged since order 067, none naming this order's files.
+ - DoD line 3: done, listed under Task 3 above.
+ - `npm run check:rules -- --paths <all touched files>` exit 0 across every commit this pass (9 em-dash violations found and fixed across `api/_lib/preserve-contract.js`, `tests/api/preserve-contract.test.js`, and `src/restyle.js` before their respective commits; 0 on the doc/changelog commit).
+ - No owner action needed: nothing in this order's work requires push, deploy, spend, or destroying data, and the GPU texture worker (`workers/texture`) was correctly ruled out as the test lane rather than deployed, since Material Studio's Material-setter-only edit path already gives the order a real, deployed, free retexture lane to prove the preserve contract against.
+ - Judgment calls: (1) used Material Studio, not `workers/texture`, as the retexture test lane, since the latter is written but undeployed and deploying a new GPU worker is well outside this order's scope; (2) scoped the HoloPart part-edit preserve check to `['skeleton', 'clips']` rather than the full kind set, since a part regenerate's whole point is that the selected part's own topology/UV/skin legitimately changes; (3) updated the two existing `STRUCTURE.md` rows in place rather than adding a new row, since no new top-level surface or directory landed, only additive fields on an already-documented package and a new file inside an already-documented directory.
+ - Commits: `d84e3acd4`, `9de6ae072`, `64f6043c9`, `e0b2785fa`, `22aa23aa6`, plus this entry and the order file deletion, which ship together; see the commit log for this date (best3d-12 retirement).