# Next Session Pickup — v0.4.0 Tag Push + Verify + Evidence Backfill

> **用途**：新 session 起手直接读本文件，完成 v0.4.0 publish 收尾（tag push → CI green → Packages 页 verify → STATUS/retrospect 回填 evidence），然后开启 v0.5.0 主线。
> **前任**：[`next-session-pickup-2026-05-15-v0-4-0.md`](next-session-pickup-2026-05-15-v0-4-0.md) → 已完成（v0.4.0 主线 4 项 + audit fix + tracker catch-up 全 ship；retrospect [`2026-05-14-v040-release.md`](../retrospection/2026-05-14-v040-release.md)）
> **当前版本**：v0.3.0 ✅ published；v0.4.0 🟡 master 含 release commit，**tag 未 push**

---

## TL;DR

1. v0.4.0 主线 4 sprint + wrap-up 5 commits 已落 master：`cca1a043` → `529bb366` → `0db2bfd0` → `5546ae0b` → `92ffb937` → `50ff23d0` → **`<wrap-up SHA>` + `<release SHA>`**（最后两个是本 session wrap-up 收尾时落的）
2. **下一步 = tag v0.4.0 push 触发 CI → 等 CI green → 验 Packages 页 → STATUS/retrospect 回填 evidence**
3. 完成后立刻进 **v0.5.0 主线** prep（Phase 6.8 Button 完成迁移 + Tier 1-B mockup audit 并行）

---

## 1. 当前状态确认（起手必做）

按 SessionStart hook + STATUS.md §起手必读链路，**机械跑 5-step onboarding**：

```bash
# Step 0 — git baseline
git status --short              # 应只有别 session 持续动的 .claude/settings.json + 几个 docs
git log --oneline -8            # 顶部应是 release: v0.4.0 + docs(wrap-up) + ...
git tag --list 'v0.4.*'         # 当前应**无** v0.4.0 tag（本 session 任务就是 push 它）

# Full baseline green
pnpm test                       # 114 passed | 1 skipped
pnpm exec vue-tsc --noEmit      # 0 错
pnpm run audit:translation-completeness  # 9 findings / 0 active / 9 allowlisted
pnpm run prepublishOnly         # 10 strict gates 全通过
```

任一不绿 → STOP 排查。

5-step onboarding 文档：
1. [`docs/STATUS.md`](../../STATUS.md) — v0.4.0 🟡 ready to publish
2. [`docs/PROJECT_GOAL.md`](../../PROJECT_GOAL.md) — 5 能力 + Quick Reference
3a. [`docs/internal/retrospection/design-spec-canonical-alignment-tracker.md`](../retrospection/design-spec-canonical-alignment-tracker.md) §排期原则 + v0.5.0 段
3b. **本文件**
4. [`AGENTS.md`](../../../AGENTS.md) 必读链路 §1-10
5. v0.4.0 release retrospect [`2026-05-14-v040-release.md`](../retrospection/2026-05-14-v040-release.md)

---

## 2. v0.4.0 已 master 内容（无需再做）

| Sprint | Commit | 内容 |
|---|---|---|
| Audit fix | `cca1a043` | audit-translation-completeness.mjs h2 boundary fix |
| A | `529bb366` | Phase 6.6a FormItem.label `#label` named slot dual-form |
| B | `0db2bfd0` | Phase 6.6b Tooltip.content `#content` named slot dual-form + FormItemPage Icon demo fix |
| C | `5546ae0b` | Phase 6.7 Badge SoT reconciliation B path (0 code change) |
| Catch-up | `92ffb937` | tracker.md timeline + 2 plan owner prompt deliverables |
| D | `50ff23d0` | Tier 2-D `scripts/new-backlog.mjs` ID generator |
| Wrap-up | `<本 session SHA>` | STATUS + tracker + 3 decisions resolved flip + retrospect + 本 pickup |
| Release | `<本 session SHA>` | `release: v0.4.0` (package.json bump + CHANGELOG.md) |

**详细分析见** [`2026-05-14-v040-release.md`](../retrospection/2026-05-14-v040-release.md)。

---

## 3. 本 session 必做（v0.4.0 publish 收尾）

### 3.1 Tag push 触发 CI

```bash
# 当前 master HEAD = release: v0.4.0 commit (package.json + CHANGELOG)
# 该 commit 应已含 version: "0.4.0" in package.json
git tag v0.4.0
git push origin v0.4.0
```

**这是不可逆操作**——tag 一旦 push，CI workflow 立刻跑 + publish 到 GitHub Packages。**用户必须明确 ack tag push 这一步**，plan owner 不擅自做。

### 3.2 CI workflow 监控

```bash
# 监控 CI run（typically ~1m13s for v0.3.0）
gh run watch <run-id>            # 或 gh run list --workflow=publish.yml
```

**期望**：10 strict gates 全 pass + npm publish 成功 → exit 0。

任一 gate fail：
- STOP，不要 retry
- 看 CI logs 定位 fail
- 如果 transient (CI infra 问题) → re-run workflow（不需重打 tag）
- 如果 spec drift → 回 master 修，删 v0.4.0 tag（`git tag -d v0.4.0 && git push --delete origin v0.4.0`），重新进流程

### 3.3 Packages 页 verify

```bash
# 关键 verify — v0.1.0/v0.1.1 silent fail 实证驱动的强制 check
# (per STATUS.md §Release wrap-up 必改项)
gh api 'orgs/<scope>/packages/npm/tvu-design-system/versions' | jq '.[].name'
# 或 GitHub 网页 Packages 页直接看 0.4.0 是否显示 "Latest"
```

**必须看到 actual `@nancyzeng0210/tvu-design-system@0.4.0` 在 Packages 页 + `latest` tag**。CI green ≠ publish 成功 — registry 接受才算。

### 3.4 STATUS.md / retrospect evidence 回填

```bash
# 编辑 STATUS.md "当前版本" 段:
# - "状态" 行从 "🟡 ready to publish" → "✅ published & verified"  
# - 加 CI run URL: https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/<run-id>
# - 加 Packages URL: https://github.com/NancyZeng0210/TVU-Design-System/packages
# - 加 Packages API verified timestamp

# 编辑 retrospect 2026-05-14-v040-release.md:
# - 在 Scope shipped 段加 "Tag push + CI green + Packages verified" 行
# - "Evidence" 字段从 "(Pending)" 改实际 URLs

# 编辑 tracker.md v0.4.0 段:
# - "Evidence" 字段同步更新

# Commit:
git add docs/STATUS.md docs/internal/retrospection/2026-05-14-v040-release.md \
        docs/internal/retrospection/design-spec-canonical-alignment-tracker.md
git commit -m "docs(wrap-up): v0.4.0 ✅ shipped — CI green + Packages verified evidence backfill"
git push origin master
```

---

## 4. v0.4.0 publish 完成后立即进 v0.5.0 prep

### 4.1 v0.5.0 主线内容（tracker SoT）

| 项 | 估时 | 破坏性？ | 备注 |
|---|---|---|---|
| **Phase 6.8** Button canonical 完成迁移（21 sets）| ~20-30h | 是 | DS 最大单组件；canonicalColor/Style/Radius/FixedWidth/Status/Icon/Size 旧 API @deprecated |
| **Tier 1-B** `audit:mockup-conformance.mjs` | ~6-10h | 否（新 audit gate） | **能力 4 第一个 L3+ gate（项目最大缺口）**；library key / 颜色 token bound / 字体 token / M1-M5 命名 |
| 顺路 **Tier 2-E** `scripts/figma-url-to-canonical.mjs` CLI | ~4-6h | 否 | 替代 AI 读 catalog |
| 顺路 **Tier 2-F** `scripts/lint-skills.mjs` | ~3-5h | 否 | 验各 skill md 起手依赖文档存在 |

**并行可行**：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 趋势）。

### 4.2 推荐路径

按 tracker §排期原则 + 文件冲突分析：

| Sprint | 内容 | 估时 |
|---|---|---|
| A — Phase 6.8 Button canonical 迁移 | 加 canonicalTheme + 文档主推 canonical + 旧 variant/size/disabled/loading 标 @deprecated | ~3-4h Codex executor |
| B — Tier 1-B `audit:mockup-conformance.mjs` | 新 audit gate 检查 library key / 颜色 token / 字体 token / M1-M5 命名；升 11th strict | ~2-3h Codex executor |
| (并行) Tier 2-E 顺路 | `scripts/figma-url-to-canonical.mjs` | ~1h plan owner 直接 |
| (并行) Tier 2-F 顺路 | `scripts/lint-skills.mjs` | ~1h plan owner 直接 |
| E — v0.5.0 release wrap-up | flip Phase 6.8 / Tier 1-B decisions resolved + changeset + tag → 18 步 checklist（retrospect §Wrap-up Process 流程化）| ~30min |

**plan owner 推荐 Sprint A + B 并行**（0 文件冲突）；顺路 Tier 2-E/F 在 plan owner 直接实现路径 B 范式。

### 4.3 起手 v0.5.0 Sprint A spec 真源

- [`docs/internal/runtime-additions.md`](../../runtime-additions.md) — Button canonicalTheme / 21 sets axis spec
- [`docs/internal/component-mapping-scan.md`](../../component-mapping-scan.md) — Button mapping 现状
- [`src/canonical/Button.vue`](../../../src/canonical/Button.vue) — current canonical state
- [`divergences-decisions.json`](../../../src/design-system/translation/divergences-decisions.json) `id: button-canonical-api-migration`

### 4.4 写 Sprint A prompt 前的 baseline 自检

per `feedback_baseline-before-plan` + v0.4.0 Phase 6.7 SoT drift 教训：

```bash
# Read current canonical Button state
sed -n '1,80p' src/canonical/Button.vue
# Read button-canonical-api-migration decision
jq '.decisions[] | select(.id == "button-canonical-api-migration")' src/design-system/translation/divergences-decisions.json
# Check if any decision drift (pickup spec vs reality)
grep -n "Button" src/design-system/translation/prop-aliases.json | head -10
```

**如果 canonical Button 状态跟 decision spec 一致** → 写 Sprint A prompt 按 phase-6.4 / phase-6.6 严格模板。
**如果 desync** → propose 给用户拍板 A/B path (跟 Phase 6.7 范式同理)。

---

## 5. 历史决策 + memory 索引（必读）

| Topic | Memory file |
|---|---|
| Executor 不准自 commit | [feedback_executor-no-self-commit](../../../../../.claude/projects/-Users-nancy-Documents-AICoding-VS-Code-tvu-design-system/memory/feedback_executor-no-self-commit.md) |
| Review result vs rationale | [feedback_review-result-vs-rationale](../../../../../.claude/projects/-Users-nancy-Documents-AICoding-VS-Code-tvu-design-system/memory/feedback_review-result-vs-rationale.md) |
| Commit 含 push（项目默认） | [feedback_commit-includes-push](../../../../../.claude/projects/-Users-nancy-Documents-AICoding-VS-Code-tvu-design-system/memory/feedback_commit-includes-push.md) |
| Baseline 实跑前不信 backlog 估值 | [feedback_baseline-before-plan](../../../../../.claude/projects/-Users-nancy-Documents-AICoding-VS-Code-tvu-design-system/memory/feedback_baseline-before-plan.md) |
| Release wrap-up 必 verify Packages 页 | [feedback_release-verify-packages-page](../../../../../.claude/projects/-Users-nancy-Documents-AICoding-VS-Code-tvu-design-system/memory/feedback_release-verify-packages-page.md) |
| No popup for clear recommendation | [feedback_no-popup-for-clear-recommendation](../../../../../.claude/projects/-Users-nancy-Documents-AICoding-VS-Code-tvu-design-system/memory/feedback_no-popup-for-clear-recommendation.md) |
| One-shot prompts | [feedback_one-shot-prompts](../../../../../.claude/projects/-Users-nancy-Documents-AICoding-VS-Code-tvu-design-system/memory/feedback_one-shot-prompts.md) |

---

## 6. v0.4.0 关键复盘点（不重复，refer to retrospect）

详见 [`2026-05-14-v040-release.md`](../retrospection/2026-05-14-v040-release.md) §反模式 + 学到的教训：

- 反模式 1：Plan owner 引入 prompt 模板回归（commit message section 不该写）
- 反模式 2：Plan owner 把"我没找到"等同"不存在"（grep 范围太窄漏 tests/）
- 反模式 3：Pickup spec 可以跟 canonical 现状 desync（Phase 6.3 + 6.7 二次实证）
- 反模式 4：MCP server churn 触发 UI render bug（`[object Object]`）

---

## 7. 起手第一句话（用户对新 session 说）

```
按 docs/internal/_plans/next-session-pickup-2026-05-15-v0-4-0-publish.md 接手
```

或更短：

```
继续 v0.4.0 publish + v0.5.0
```

新 session 起手会自动跑 SessionStart hook → 5-step onboarding → read 本文件 → 推荐 §3.1 tag push 起步。

**用户必须 ack tag push 这步**（不可逆），plan owner 不擅自做。