chore(task): archive 08-03-material-export-contract

.trellis/tasks/archive/2026-08/08-03-material-export-contract/implement.md

@@ -0,0 +1,114 @@
+# 执行计划：Material export contract
+
+> 对应 `prd.md` / `design.md`。按序执行，避免把视觉调参和契约迁移混在一起。
+
+---
+
+## 前置检查
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+python3 -m unittest discover blender/tests
+git status --porcelain
+```
+
+可选但推荐：若本机 Blender / 输出产物可用，先采集 before parity：
+
+```bash
+node scripts/parity.js capture material-contract-before
+```
+
+## Step 1 — 迁移 catalog 契约
+
+- [x] 在 `blender/osmassets/catalog.py` 中把有效 Cesium 覆盖迁入对应
+      `MATERIALS[*]["cesium"]`
+- [x] 不把 `"Office White Metal Facade"` 迁入新契约源
+- [x] 删除或消解 `catalog.CESIUM_EXPORT` 死代码状态
+- [x] 保持 `MATERIALS` 顺序不变，不在中间插入新材质
+
+检查：
+
+```bash
+grep -n "CESIUM_EXPORT\\|Office White Metal Facade\\|cesium" blender/osmassets/catalog.py
+```
+
+## Step 2 — 材质创建时写自定义属性
+
+- [x] 在 `blender/osmassets/materials.py` 增加 `cesium_export` 写入 helper
+- [x] `from_spec()` 对每个 material 应用 helper
+- [x] 无 `cesium` 的材质清理旧属性，避免复用同名材质时残留
+
+检查点：
+
+```bash
+python3 -m unittest discover blender/tests
+```
+
+## Step 3 — 导出器优先读 contract
+
+- [x] 在 `blender/export_cesium.py` 增加 `cesium_contract(material)` helper
+- [x] `make_export_material()` 使用 contract 优先、旧表回退
+- [x] `cesium_tinted_image()` 改为由调用方传入 tint
+- [x] 旧四张表保留为旧 `.blend` 兼容层，并注释说明
+- [x] alpha-clipped foliage 分支不做行为重构
+
+检查：
+
+```bash
+grep -n "EXPORT_TINTS\\|EXPORT_METALLIC_OVERRIDES\\|EXPORT_BASE_COLOR_OVERRIDES\\|EXPORT_EMISSION_OVERRIDES\\|cesium_contract" blender/export_cesium.py
+```
+
+## Step 4 — 验证新 `.blend` 带 contract
+
+用一个区域跑 `blender` 阶段或 parity capture 后，使用 Blender/Python 摘要确认材质自定义属性存在。
+可接受的验证方式：
+
+- 从 `blender/tools/scene_digest.py` 输出里看材质 custom property
+- 或用 Blender `--background --python-expr` 检查若干材质的 `cesium_export`
+
+目标材质至少覆盖：
+
+- `Grass`
+- `Office White Plaster Facade`
+- `Industrial White Ribbed Facade`
+- `Factory Blue Metal Roof`
+- `Tree Crown`
+
+## Step 5 — Spec 更新
+
+- [x] 更新 `.trellis/spec/blender/module-structure.md`
+- [x] 更新 `.trellis/spec/blender/asset-generation.md`
+- [x] 必要时更新 `.trellis/spec/guides/artifact-parity-guide.md` 的 P3 状态
+
+移除或改写“`catalog.CESIUM_EXPORT` 是死代码 / 改它不会生效 / P3 未做”的当前事实。
+
+## Step 6 — 全量验收
+
+```bash
+python3 -m unittest discover blender/tests
+node scripts/parity.js capture material-contract-after
+node scripts/parity.js compare material-contract-before material-contract-after
+git status --porcelain
+```
+
+若没有可用 before capture，则先在未改动代码上 capture before；如果实现已经完成但 before 缺失，
+不要伪造 parity 结论，明确记录“未运行 before/after parity”的缺口。
+
+## 回滚点
+
+- Step 1 后如果纯测试失败，回滚 `catalog.py` 迁移。
+- Step 3 后如果旧 `.blend` 导出行为不清晰，保留旧表优先，重新收窄 contract 读取范围。
+- Parity 若出现非自定义属性以外的 `.blend` / GLB 结构差异，先修实现，不扩大忽略名单。
+
+## 实施记录
+
+- 2026-08-03：实现完成。`node scripts/parity.js capture material-contract-before`
+  与 `material-contract-after` 均成功。
+- `node scripts/parity.js compare material-contract-before material-contract-after`
+  返回差异 15 项：仅 `.blend` 材质 `props.cesium_export` 新增和 `.blend` bytes 变化；
+  未出现对象、网格、材质 PBR、GLB 结构或 metadata 差异。
+- after snapshot 确认 `Grass`、`Office White Plaster Facade`、
+  `Industrial White Ribbed Facade`、`Factory Blue Metal Roof` 带 `cesium_export`；
+  `hanyang-block` 还确认 `Tree Crown Dark` / `Tree Crown Light`。默认样本不创建
+  `Tree Crown`，另用 Blender `--python-expr` 构造 `catalog.MATERIALS["tree_crown"]`
+  确认该材质也写入 `cesium_export`。