# v0.4.0 Release Retrospect — 2026-05-14

> **One-liner**：API 形态统一 minor —— Phase 6.6a/6.6b dual-form + Phase 6.7 Badge SoT 一致性 reconciliation + Tier 2-D backlog ID generator。**实际全 non-breaking**（pickup §1 "破坏性=是" 是 SoT drift），实跑 ~4h vs 估 12-18h（4× under-estimate，沿用 v0.3.0 趋势）。
>
> **Ship evidence**（2026-05-14 publish session）：
> - Tag: `v0.4.0` → release commit `77f338fd`
> - CI run: [25856655323](https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/25856655323) ✅ green 1m24s
> - Packages registry: [`@nancyzeng0210/tvu-design-system@0.4.0`](https://github.com/users/NancyZeng0210/packages/npm/package/tvu-design-system) created `2026-05-14T11:07:11Z`
> - Wrap-up协议 Release checklist 全 ✅（CI green / Packages 实物 verified / STATUS evidence 回填 / 本 retrospect 含 actual 状态）

## Scope shipped

| Sprint | Commit | 内容 | 实际 / 估 |
|---|---|---|---|
| Audit fix | `cca1a043` | audit-translation-completeness.mjs h2 boundary fix（防 `### v1.0.0` section 吞掉后续 `## 轨道 A` timeline 表 → 2 个 Phase 6.3 false-positive active-stale 清除） | 30min / TBD |
| A — Phase 6.6a | `529bb366` | base + canonical FormItem.vue 加 `#label` 命名 slot（slot 优先 over prop；default slot 保持 content/control 区） + 3 vitest case + FormItemPage Custom Label Slot demo + divergences/decision/prop-aliases 同步 | 1h / 3-4h |
| B — Phase 6.6b | `0db2bfd0` | base + canonical Tooltip.vue 加 `#content` 命名 slot（slot 优先 over prop；default slot 保持 trigger） + 3 vitest case + TooltipPage Custom Content Slot demo + FormItemPage 顺路 fix demo 用公开 Icon export 路径满足 FigmaFirstContract test | 1h / 3-4h |
| C — Phase 6.7 | `5546ae0b` | Badge SoT drift reconciliation B path — 发现 canonical Badge 自 checkpoint `9e3ca1ae` 起即为 color/tag/type=Circle\|Rectangle API；plan owner 直改 divergences.md/decision JSON 措辞 ack Phase 6.7 实质已 implemented，不改代码 | 30min / 4-6h |
| Catch-up | `92ffb937` | tracker.md 4 timeline entries 追加 + 2 plan owner prompt 文件 catch-up commit | 15min |
| D — Tier 2-D | `50ff23d0` | `scripts/new-backlog.mjs` 单文件 ESM ID generator（~89 行 zero-dep）+ npm script alias — plan owner 直接实现（path B 用户授权） | 20min / 2h |

总 **~4h shipped**；4 项主线 + 1 audit fix + 1 catch-up commit。

## 关键决策点

### Phase 6.6 命名 slot vs default slot

**Spec ambiguity**：[`divergences-decisions.json`](../../src/design-system/translation/divergences-decisions.json) 原 codeSide 写 `"string prop or default slot"`，但 FormItem default slot 已用于 content 区，Tooltip default slot 已用于 trigger 元素——default slot 不能既做 label/content 又做 control/trigger。

**解决**：用 **命名 slot**（`#label` / `#content`）—— Element Plus 范式，[`src/canonical/PopupBox.vue`](../../src/canonical/PopupBox.vue) + [`src/components/Tooltip/Tooltip.vue`](../../src/components/Tooltip/Tooltip.vue) 已用 useSlots idiom，模式成熟。

**Decision JSON / divergences.md narrative 同步更新** 在 Sprint A + B 里完成。

### Phase 6.7 path A vs B

**关键发现**：pickup §3.2 写 "canonical Badge.type 是 Black/Blue/Green/Orange/Red 颜色枚举"——**实际 canonical Badge 自 checkpoint 9e3ca1ae 起就是 color/tag/type=Circle\|Rectangle**，跟 Figma Type axis 命名一致。Pickup 视角 = SoT drift artifact。

**两条路**：
- **A**：把 canonical `type` 重命名为 `shape` + 加 `@deprecated type` alias（破坏性，让 consumer microapp 改 import）
- **B**：接受现状（`type` 本身已对齐 Figma Type axis 名字），只 ack decision + 文档化（0 破坏性）

**plan owner 推荐 B**，用户拍板 B。理由：
1. canonical.type 跟 Figma Type axis 命名一致——翻译层最小化原则
2. 同名异义只在内部（legacy.type=颜色 vs canonical.type=形状）——[`badge-canonical-legacy-dual-source`](../../src/design-system/translation/divergences-decisions.json) decision 早把 legacy 隔离不导出 npm
3. 改 shape 让 consumer 改 import 是真破坏性，收益（命名 self-doc）增量
4. pickup spec 是 SoT drift，应该修 pickup/decision，**不是改代码追上错误 spec**（tail wagging the dog）

### Tier 2-D plan owner direct-implement vs executor

用户选 **path B (plan owner 直接实现)**，绕过 executor 流程：
- Sprint D scope 极简（单文件 ~89 行 zero-dep）
- 用户已审过 Sprint D prompt（285 行 spec），等于 spec 已 ack
- 走 executor 多 1 道 prompt 反 review 反 commit 流程对简单 dev 工具是 overkill

**结果**：~20min ship vs ~30min Codex flow，节省 1 道流程开销。

## 反模式 + 学到的教训

### 反模式 1：Plan owner 引入 prompt 模板回归

**症状**：H2 audit fix prompt + Phase 6.6a prompt v1 都含 `## 5. Commit message` section 给完整 commit message 模板 → Codex 跟着 verify-then-commit。

**Root cause**：我新 session 起手写 prompt 时脑里默认的 "executor prompt 标准结构" 是泛 SWE 模板含 commit section——没去读 `phase-6.4-runtime-additions.prompt.md` / `tier1a-sprint*` 项目既有 pattern 作 reference。

**教训**：写 prompt 前 grep 最近 3-5 个 prompt 的结尾段（`## 严格不做` + `## 完成后 STOP`），机械复用模板；不要脑补。落实到 [`feedback_executor-no-self-commit`](../../../-Users-nancy-claude-projects-tvu-design-system/memory/feedback_executor-no-self-commit.md) memory。

### 反模式 2：Plan owner 把 "我没找到" 等同 "不存在"

**症状**：6.6a 时 Codex 报告 "docs contract 禁止 component page import src/components/*"，我 grep `docs/` + `AGENTS.md` + `playground/` 没找到 → 错误结论 "Codex 编造"，并指示 6.6b prompt 让 Codex 用 `from '@/src/components/Icon/Icon.vue'` 修 demo。

**Sprint B Codex 救回来**：识别 prompt 这条指令会破 [`tests/FigmaFirstContract.test.ts:29-36`](../../tests/FigmaFirstContract.test.ts) 真实存在的 contract，改用公开 export 路径 `from '@/src/index'` 修正。

**Root cause**：plan owner grep 范围太窄（漏 `tests/`），下结论"不存在"前没覆盖全仓库。

**教训**：rationale 实证必须 grep 全仓库（`tests/` + `scripts/` + `.husky/` + config 文件，不仅 markdown）。落实到 [`feedback_review-result-vs-rationale`](../../../-Users-nancy-claude-projects-tvu-design-system/memory/feedback_review-result-vs-rationale.md) memory（双向 — Codex 也可能"措辞不精确" ≠ "编造"）。

### 反模式 3：Pickup spec 可以跟 canonical 现状 desync

**症状**：pickup §3.2 写 canonical.type 是颜色枚举——实际不是。Phase 6.3 也曾有类似 SoT drift（2026-05-11 STATUS stale active）。

**Root cause**：pickup 是手写文档，跟 canonical 代码 / divergences-decisions.json 不自动同步；写时基于过时认知 → desync。

**教训**：开始 sprint 实施前 **plan owner baseline 实跑**：读 canonical 现状代码 + grep decisions JSON 现状，再对照 pickup spec。如发现 desync → propose path B（修 pickup/spec）或 path A（实施补齐），不擅自按 pickup 跑。

### 反模式 4：MCP server churn 触发 UI render bug

**症状**：本 session 内 `[object Object]` UI render 错误两次出现，trigger pattern 一致——`claude.ai Figma` 同轮被报告为 "still connecting" + "disconnected"（race condition）。

**影响**：agent loop 没坏（agent 继续工作），但 UI panel 显示报错 banner 干扰用户体验。

**Not a project bug**——Claude Code 扩展前端 issue。未做处理（agent 工作不受影响）。

## 实跑趋势

- v0.2.0：~2h 实跑（CANONICAL-011 + 多项 in）
- v0.3.0：~8h 实跑 vs 估 1-2 周（4-8× under）
- **v0.4.0：~4h 实跑 vs 估 12-18h（3-4× under）**

模式一致：仓库基础设施成熟后（audit gate / canonical SoT / translation schema），每个组件级 sprint 大概 30min-1h 实跑（prompt + Codex executor + plan owner review + commit），远低于 backlog 估值。

**建议**：tracker 估时往后可以 ÷ 4 作 baseline。

## v0.4.0 Wrap-up Process 流程化

| 步骤 | 谁做 | 自动 / 半自动 / 手动 |
|---|---|---|
| 1. STATUS.md "当前版本" 段更新 | plan owner | 半自动（按模板） |
| 2. STATUS.md Roadmap header archive (~~vX.Y.Z~~ ✅ shipped) | plan owner | 半自动 |
| 3. STATUS.md Active 余量段更新 | plan owner | 半自动 |
| 4. tracker.md Release 排期 header archive | plan owner | 半自动 |
| 5. tracker.md Active 待完成 段清空 | plan owner | 半自动 |
| 6. tracker.md 已完成 段追加 sprint entries | plan owner | 半自动（用 commit log） |
| 7. tracker.md 大图 summary 段 archive 该版本 | plan owner | 半自动 |
| 8. Flip decisions resolved in divergences-decisions.json | plan owner | 半自动 |
| 9. Write retrospect file | plan owner | 手动 |
| 10. Verify audit + prepublishOnly + test | plan owner | 自动 (`pnpm` cmd) |
| 11. Commit wrap-up docs | plan owner + user ack | 手动 |
| 12. Write `.changeset/*.md` + `pnpm changeset version` | plan owner | 半自动 |
| 13. Commit `release: vX.Y.Z` | plan owner + user ack | 半自动 |
| 14. **Tag push** | **user / plan owner with explicit ack** | **手动（不可逆）** |
| 15. CI run → green wait | 自动 | 自动监控 |
| 16. Packages 页 verify | plan owner | 半自动（GitHub API） |
| 17. STATUS.md "已 publish" 行回填 evidence | plan owner | 半自动 |
| 18. Push final wrap-up commit | plan owner | 半自动 |

**未来 release wrap-up 可参考此 18 步 checklist**。Tier 2-G STATUS.md 一致性 lint 可以机械验证 STATUS.md / tracker.md 是否 sync 后状态（v0.6.0 顺路）。

## v0.5.0 准备

**主线 2 项 + 顺路 2 项**：
- **Phase 6.8** — Button canonical 完成迁移（21 sets，DS 最大单组件）— 估 ~20-30h，**真破坏性**
- **Tier 1-B** — `audit:mockup-conformance.mjs`（library key / 颜色 token bound / 字体 token / M1-M5 命名）— 估 ~6-10h —— **能力 4 第一个 L3+ gate（项目最大缺口）**
- 顺路 Tier 2-E — `scripts/figma-url-to-canonical.mjs` CLI
- 顺路 Tier 2-F — `scripts/lint-skills.mjs`

**并行可行**：Phase 6.8 改 `src/canonical/Button` vs Tier 1-B 加 `figma-sync/audit-*` — 0 文件冲突。

**估时**：~3-4 周 vs 实跑预测 ~6-10h（同 v0.3.0 / v0.4.0 趋势）。

下个 session pickup 应写：`docs/internal/_plans/next-session-pickup-2026-05-15-v0-5-0.md`，含 Sprint A (Phase 6.8) + Sprint B (Tier 1-B) 并行 / 串行决策建议。

## 总结

**v0.4.0 ship 完成 4 项主线 + 2 个 plan owner deliverable（catch-up prompts + Tier 2-D）**：
- ✅ Phase 6.6a `#label` named slot dual-form (commit 529bb366)
- ✅ Phase 6.6b `#content` named slot dual-form (commit 0db2bfd0)
- ✅ Phase 6.7 Badge SoT reconciliation B path (commit 5546ae0b)
- ✅ Tier 2-D `scripts/new-backlog.mjs` (commit 50ff23d0)
- ✅ Audit script h2 boundary fix (commit cca1a043)
- ✅ Tracker catch-up (commit 92ffb937)

**能力对齐**：能力 1（dev API 一致）+ 能力 2（AI 从 Figma URL 不撞双 API）+ engineering infra（dev 工具 + audit gate）。

**Next**：tag v0.4.0 push → CI green → Packages 页 verify → STATUS.md 回填 evidence → 进 v0.5.0 主线。