# Next Session Pickup（落仓库 2026-05-12）

> 本文件锚在 repo 里，呼应 2026-05-08 行为约束 #19（跨 session 任务必须留 repo 锚点）。
> **新 session 起手第一步：把本文件 + AGENTS.md 必读链路读完，再决定动手顺序。**
> 前任：[`archived/next-session-pickup-2026-05-11.md`](archived/next-session-pickup-2026-05-11.md)（已归档，v0.1 publish 阶段闭环完成）

---

## TL;DR（3 句话）

1. **v0.1.0 已发布 🎉**：`@tvu/design-system@0.1.0` 在 GitHub Packages；CI workflow tag-triggered + 7 strict + 2 warn-only audit gate 全部就位；首次 publish 走完。完整复盘 [`retrospection/2026-05-11-v0-1-publish-flow.md`](../retrospection/2026-05-11-v0-1-publish-flow.md)。
2. **下个 session 起手任务**：**CANONICAL-009**（Tab.vue 硬编码 hex `#1f1f1f`/`#353535` token 化 + Icon.vue/Logo.vue raw SVG binding fix）—— NPM-003 Phase 1 baseline 已抓到具体 violation，可直接写 prompt；修完顺手升 `audit:design-system` warn-only → strict + 累积 0.1.1 第一个 changeset。
3. **4 个 dirty 文件别 session 进行中**（不动）：`.claude/settings.json` / `docs/meta-rules.md` / `docs/multi-session-collaboration-rules.md` / `docs/internal/retrospection/2026-05-11-library-key-confusion.md`

---

## 1. 2026-05-09 → 2026-05-11 已落地清单（v0.1 publish 完整 commit chain）

| commit | 内容 |
|---|---|
| `5125e625` | fix(icons): INFRA-F27 build-icon-dist currentColor 修复（含 3 处主动延展） |
| `7e54d50d` | docs(npm): NPM-001 — CHANGELOG.md + changesets 工具链 |
| `babee0fd` | docs(npm): NPM-002 — README registry install + 29 components 表 + GETTING_STARTED.md |
| `520bb15a` | build(publish): NPM-003 — `.github/workflows/publish.yml` + `package.json` (prepublishOnly + engines + publishConfig) + docs/RELEASING.md |
| `26122ad3` | docs(backlog,plans): NPM-003 ✅ 收尾 — 2 follow-up backlog + pickup 更新 |
| `v0.1.0` tag at `26122ad3` | user 手动 `git tag -d v0.1.0 && git tag v0.1.0 && git push --tags` 触发 CI publish |
| `45ef1aa2` | docs(plans): archive 2026-05-11 pickup — v0.1 published 🎉 |
| `1c23bf28` | fix(backlog): CANONICAL-007 → CANONICAL-009 collision fix |
| `cf1d53d2` | docs(retrospection): 2026-05-11 v0.1 publish flow 完整闭环复盘（259 行）|

**本 session 后 git status 应当是**：
- 本地 = origin/master（0 未推 commit）✅
- 4 个 untracked / dirty 文件保留（别 session 进行中，本任务范围外）：
  - `M .claude/settings.json`
  - `M docs/meta-rules.md`
  - `M docs/multi-session-collaboration-rules.md`
  - `?? docs/internal/retrospection/2026-05-11-library-key-confusion.md`

如新 session 看到 git 状态不是上面这样，先 `git log origin/master..HEAD` 排查。

---

## 2. 新 session 起手 onboarding（按顺序读）

1. **本文件**（你正在读）— 5min
2. **复盘** [`retrospection/2026-05-11-v0-1-publish-flow.md`](../retrospection/2026-05-11-v0-1-publish-flow.md) — 8min（含 anti-pattern + 工程技巧；起新任务前必读，规避前 session 踩过的 4 个反模式）
3. [AGENTS.md](../../../AGENTS.md) 必读链路 §1-8 — 10min
4. [`backlog.md`](../backlog.md) Active 段，重点看 CANONICAL-009 + BRIDGE-MOCKUP-004（两条 NPM-003 派生的 follow-up）— 5min
5. [`docs/RELEASING.md`](../../RELEASING.md) — 3min（理解 0.1.1+ release flow + audit gate 政策）
6. （可选）[`PROJECT_GOAL.md`](../../PROJECT_GOAL.md) — 仅当忘记项目目标 / 桥的 5 个能力时

**总 onboarding ~30min，做完即可动手。**

---

## 3. 任务队列（推荐路径）

**建议把 CANONICAL-009 + BRIDGE-MOCKUP-004 + 0.1.1 release 作为一组**——3 步连贯，1 个完整 0.1.x release cycle 演练 publish flow。

```
🥇 第 1 步 — CANONICAL-009 (Tab.vue token 化 + Icon/Logo raw SVG fix) → 升 audit:design-system strict
🥈 第 2 步 — BRIDGE-MOCKUP-004 baseline (查 2 figma-only 具体哪 2 个) → A/B/C 路线 fix → 升 audit:published-vs-code strict
🥉 第 3 步 — 0.1.1 release cycle 演练（pnpm changeset:version → tag → push → CI auto-publish）
```

### 第 1 步 — CANONICAL-009（~2-3h）

按 [backlog CANONICAL-009 entry](../backlog.md) §修复方向 + §执行链路：

1. **跑 `pnpm audit:design-system`** 看完整 123 行报告，列具体 violation 位置 + raw SVG binding 类型
2. **propose 2 个决策点给 user 拍板**：
   - **D1 — Tab.vue hex 对应 token**：查 [`token-aliases.ts`](../../../src/design-system/translation/token-aliases.ts) 找 `#1f1f1f` / `#353535` 对应 token（候选 `UX/Black/Surface-1` / `UX/Grey/Border` 系列）
   - **D2 — Icon.vue / Logo.vue raw SVG binding fix 路线**：可能 `<g v-html="...">` → component import；具体看 audit violation pattern 决定
3. 拍板后写 `docs/internal/_prompts/canonical-009-design-system-audit-fix.prompt.md`（**一步到位 prompt**，决策 §0 全 baked-in；按本 pickup §6 复盘 anti-pattern #3 教训不分阶段）
4. Fire → executor 跑 → plan owner 复审 → user 拍板
5. **顺手做**：
   - 跑 `pnpm changeset` 写 0.1.1 patch description（"fix(canonical): Tab.vue token化 + Icon/Logo raw SVG binding"）
   - 改 `.github/workflows/publish.yml`：把 `audit:design-system` step 从 `continue-on-error: true` 删，移到 `prepublishOnly` chain 末尾（升 strict gate）
   - 改 `docs/RELEASING.md`：audit gate policy 表把 `audit:design-system` 从 warn-only 改 strict
6. Commit + push

### 第 2 步 — BRIDGE-MOCKUP-004（~1-2h baseline + 后续 fix 视量）

1. **跑 `pnpm audit:published-vs-code`** 看 11 行输出 + `figma-data/normalized/published-vs-code.audit.json` 详情；列具体 2 个 figma-only component 名 + figma 来源
2. **与 user 确认 A/B/C 路线**（backlog 已列）：
   - A：figma 已新增组件需入库 → generator 链路
   - B：figma 已废弃但未删 → 与设计师沟通 figma 删除
   - C：figma 设计实验不入库 → audit 白名单（需查 audit 脚本是否支持）
3. 写 `docs/internal/_prompts/bridge-mockup-004-figma-only-drift-fix.prompt.md`
4. Fire → executor 跑 → plan owner 复审 → user 拍板
5. **顺手做**：第二个 changeset + workflow 升 strict（同第 1 步收尾）

### 第 3 步 — 0.1.1 release cycle 演练（user 操作，~10min）

完成第 1+2 步后 `.changeset/` 应累积 2 个 changeset。按 [`RELEASING.md`](../../RELEASING.md) §Standard release flow：

```bash
pnpm changeset:status                       # 看 2 个 pending
pnpm changeset:version                      # 聚合 → bump 0.1.0 → 0.1.1 + 写入 CHANGELOG [0.1.1] 段
git add -A
git commit -m "release v0.1.1"
git tag v0.1.1
git push origin master --tags               # 推 → CI 自动 publish 0.1.1
```

**验证目标**：
- CI workflow tag-triggered 工作正常
- `prepublishOnly` 7 strict audit 全过（且现在还要加上原 warn 升 strict 的 audit:design-system + audit:published-vs-code，共 9 strict）
- GitHub Packages 显示 `@tvu/design-system@0.1.1`
- 整套 changeset → version → tag → publish flow 闭环

---

## 4. Dirty 文件协议（别 session 进行中）

User 多 session 并行；以下 4 个文件**别 session 在跑**，本 session 不要碰，除非 user 主动说"消化这些文件"：

| 文件 | 状态 | 备注 |
|---|---|---|
| `.claude/settings.json` | M | 工具设置（私有），user 自决 |
| `docs/meta-rules.md` | M | 别 session 在动 |
| `docs/multi-session-collaboration-rules.md` | M | 别 session 在动 |
| `docs/internal/retrospection/2026-05-11-library-key-confusion.md` | ?? | MicroApps mockup session 产物 |

**新 session 起手协议**：onboarding 报告 dirty 状态时 explicit 标"如果别 session 在跑可忽略"；user 不主动说要消化 → **不动**，直接推进 §3 任务。

---

## 5. 已知 bug / 不确定项

| 项 | 状态 | 处理 |
|---|---|---|
| `audit:design-system` FAIL 内容（Tab.vue 硬编码 + Icon/Logo raw SVG）| CANONICAL-009 跟踪 | 本 session §3 第 1 步处理 |
| `audit:published-vs-code` FAIL（2 figma-only）具体哪 2 个 | BRIDGE-MOCKUP-004 跟踪，需先跑 audit | 本 session §3 第 2 步处理 |
| `figma-data/normalized/*.audit.json` 跑 audit 时被改写 | 已知 INFRA-F26 timestamp idempotence 问题；`--no-git-checks` 在 publish workflow 已绕过 | 不阻 publish；INFRA-F26 后续做 |
| backlog hygiene — NPM-001/002/003 / INFRA-F19/F22/F23 entries 仍在 Active 段（实际已 ✅）| 待 plan owner cleanup | 可顺手在 §3 第 1+2 步 commit 时一起改 |
| pickup §3 真正运转后是否还能"一步到位" | 看 user 这次会不会再要分阶段 | 留意复盘 anti-pattern #3 教训 |

---

## 6. Out-of-scope（不在本 session 临界路径，按需做）

按优先级倒排（最不紧急在最下）：

- **CANONICAL-006 Pagination figma alignment refactor** — prompt 已写未 fire；可任意 session fire
- **CANONICAL-007 Pagination page number buttons 改用 design system Button** — backlog Active
- **CANONICAL-008 Table + InputNumber Helvetica drift** — backlog Active
- **CANONICAL-004 Progress dark cell 视觉不可见** — backlog Active
- **CANONICAL-002 PromptMessage 不可交互模式 auto-dismiss** — backlog Active
- **BRIDGE-MOCKUP-001/002/003** 库债 — 设计师 owner，等设计师补 token / variant / promotion
- **BRIDGE-005** figma boolean / instance-swap properties 三层范式 — generator 改动较大
- **EXTRACT-006** figma extract pipeline 不抽 Styles — T1c 复活时一起做
- **INFRA-F20** visual baseline (Playwright) — review §6 建议 NPM 链路后做（=现在可启动）
- **INFRA-F21** pre-commit hooks — 依赖 F20 + audit upgrade
- **INFRA-F24** page theme injection 范式统一 — 双轨当前可生存
- **INFRA-F25** audit suite formalization — 已起步，完整化与 F21 一起
- **INFRA-F26** extract timestamp idempotence — commit cap 噪音问题，不阻 publish
- **6.3** 删 Notification.success/type — 未启动；post-v0.1
- **6.4** 新增运行时能力 — 未启动；post-v0.1
- **A6** package.json 补 `audit:page-t2` 等缺失 npm script alias — 可任意 session 顺手做
- **A7** docs/internal 43+ 历史 report 挪 `_reports/` — 可任意 session 顺手做
- **META-F28** 定期 review 节奏（每 1-2 月触发系统性 review）— 候选，未启动

---

## 7. 文件位置速查

| 我要看 | 路径 |
|---|---|
| 当前 backlog | [`backlog.md`](../backlog.md) |
| v0.1 publish 复盘（本 pickup 前置必读）| [`../retrospection/2026-05-11-v0-1-publish-flow.md`](../retrospection/2026-05-11-v0-1-publish-flow.md) |
| Release 流程指南 | [`../../RELEASING.md`](../../RELEASING.md) |
| Publish workflow | [`../../../.github/workflows/publish.yml`](../../../.github/workflows/publish.yml) |
| CHANGELOG | [`../../../CHANGELOG.md`](../../../CHANGELOG.md) |
| changesets 配置 | [`../../../.changeset/config.json`](../../../.changeset/config.json) |
| NPM-001 prompt（已 fire） | [`../_prompts/npm-001-changelog-spec.prompt.md`](../_prompts/npm-001-changelog-spec.prompt.md) |
| NPM-002 prompt（已 fire） | [`../_prompts/npm-002-install-quickstart.prompt.md`](../_prompts/npm-002-install-quickstart.prompt.md) |
| NPM-003 prompt（已 fire，一步到位）| [`../_prompts/npm-003-publish-workflow.prompt.md`](../_prompts/npm-003-publish-workflow.prompt.md) |
| INFRA-F27 prompt（已 fire） | [`../_prompts/infra-f27-build-icon-dist-currentcolor-fix.prompt.md`](../_prompts/infra-f27-build-icon-dist-currentcolor-fix.prompt.md) |
| AGENTS.md | [`../../../AGENTS.md`](../../../AGENTS.md) |
| Meta-rules | [`../../meta-rules.md`](../../meta-rules.md) |
| Mockup 硬约束 | [`../mockup-conventions.md`](../mockup-conventions.md) |
| 库组件目录 | [`../figma-component-catalog.md`](../figma-component-catalog.md) |

---

## 8. 元说明

- **本文件生命周期**：CANONICAL-009 + BRIDGE-MOCKUP-004 + 0.1.1 release cycle 完成后，本文件挪 `_plans/archived/` 或重写覆盖（保留时间戳后缀）
- **plan owner closing checklist**（基于本次复盘改进，下个 session 起手强制项）：
  - [ ] 起手前过本 pickup §2 复盘文件，规避 4 个 anti-pattern
  - [ ] 加新 backlog entry 前 grep 全部已用 ID（feedback_backlog-id-collision.md）
  - [ ] 写 prompt 一步到位带 recommendation + fallback，不假分阶段（feedback_one-shot-prompts.md）
  - [ ] pickup §4 dirty 文件不主动消化，user 不说就跳过（user_parallel-sessions.md）
  - [ ] 决策点已被 pickup/backlog/review 预分析 → 直接文本 propose，不用 AskUserQuestion 弹窗（feedback_no-popup-for-clear-recommendation.md）
  - [ ] **阶段完成后必须写复盘**（AGENTS.md §共同规则；本次漏写被 user 发现 — 已补 cf1d53d2）
- **如果新 session 决定不按本顺序做**：在新 session 重写一份覆盖本文件（保留时间戳后缀），不要在本文件里改
- **本 handoff 不是 prompt**：是 plan owner 给下个 session 的 plan owner（自己或换人）的 onboarding 文档，不直接喂 executor

---

## 9. Update 2026-05-11 baseline 后修订

> 本段是 pickup 原 §3 第 2/3 步路径前提失效后的修订记录，**新 session 起手按本段读，不按原 §3 第 2/3 步**。
> 复盘 → [`../retrospection/2026-05-11-bridge-mockup-004-baseline-assumption-invalid.md`](../retrospection/2026-05-11-bridge-mockup-004-baseline-assumption-invalid.md)

### 9.1 已完成（vs 原 §3 计划）

| 原 §3 步骤 | 实际状态 |
|---|---|
| §3 第 1 步 — CANONICAL-009（~2-3h）| ✅ 完成 commit `72fc6bec`，audit:design-system 升 8 strict gate |
| §3 第 2 步 — BRIDGE-MOCKUP-004（~1-2h baseline + fix 视量）| ⚠️ **前提失效** — baseline 跑完发现 2 figma-only = PopupBox + Chart `needs-implementation`，~10-15h 实现量超 v0.1.1 sprint |
| §3 第 3 步 — 0.1.1 release cycle 演练 | 🟡 **待用户操作** — CANONICAL-009 已是有意义 patch，无需等 BRIDGE-MOCKUP-004 |

### 9.2 BRIDGE-MOCKUP-004 真相 + D 路线（user 2026-05-11 拍板）

baseline 真相：

| Figma set | variants | 期望代码 | mapping status |
|---|---|---|---|
| `Popup Box` | 2 | `PopupBox` | needs-implementation |
| `Chart` | 6 | `Chart` | needs-implementation |

**不是漂移**（A/B/C 路线适用性都失败）：
- A 路线（实现入库）适用但工作量 ~10-15h，超 v0.1.1 sprint 5x 量
- B 路线（设计师删 figma）不适用（status approved）
- C 路线（audit 白名单）不适用（status `needs-implementation`），且 `audit-figma-published-vs-code.mjs` 脚本不支持白名单

**新 D 路线**：拆独立 canonical entries + audit 保 warn-only 直到两子项完才升 strict（不阻 0.1.1 release）。

### 9.3 派生 backlog（已落 [`../backlog.md`](../backlog.md)）

- **CANONICAL-010** PopupBox 实现（~3-5h，v0.1.x）
- **CANONICAL-011** Chart 实现（~6-10h，v0.2 — 需 dep 选型 + API 设计 propose user 拍板）
- **BRIDGE-MOCKUP-004** 重写为 tracker entry，指针指 010/011 + Resolved 条件 = 两子项完 + audit:published-vs-code 升 strict

### 9.4 修订后的 next-session 推荐顺序

```
🥇 第 1 步 — 0.1.1 release cycle 演练（user 操作，~10min）
   pnpm changeset:status → version → tag v0.1.1 → push --tags → CI auto-publish
   验证目标：CANONICAL-009 升 8 strict gate 后第一次 release flow 通过

🥈 第 2 步（next session 可拆开）— CANONICAL-010 PopupBox 实现
   ~3-5h；BRIDGE-MOCKUP-004 tracker 子项 1/2

🥉 第 3 步（next session）— INFRA-F29 docs grid card hover
   ~1h；UX 微改进，2026-05-11 user 提议

🏅 第 4 步（v0.2 minor）— CANONICAL-011 Chart 实现
   ~6-10h；需 dep 选型 propose user 拍板（chart.js / echarts / @vueuse 等）
```

### 9.5 触发本 pickup 归档的条件

CANONICAL-009 + 0.1.1 release cycle 演练完成后，本文件挪 `_plans/archived/`（原 §8 元说明里的 "BRIDGE-MOCKUP-004 完成"条件**作废**，BRIDGE-MOCKUP-004 跨多个 sprint 由 tracker 跟踪，不阻本 pickup 归档）。