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

> 本文件锚在 repo 里，呼应 2026-05-08 行为约束 #19（跨 session 任务必须留 repo 锚点，对话里的计划新 session 看不到）。
> **新 session 起手第一步：把本文件 + AGENTS.md 必读链路读完，再决定动手顺序。**

---

## TL;DR（3 句话）

1. **META-F27 系统性 review 已执行完毕**（commit `ee999c0e`），报告 [`_reports/systematic-review-2026-05-09.md`](../_reports/systematic-review-2026-05-09.md)；INFRA-F21 已升级两层 gate（commit `6ecdd9e7`）
2. **下个 session 起手任务**：先建 NPM-001/002/003 三条 backlog entry（v0.1 物理阻塞），然后写 NPM-001 (CHANGELOG) executor prompt
3. **F20 visual baseline 之前还有一步必做**：A1-A3 dead code cleanup（删 src/legacy/index.ts + 3 个仓库根 untracked .mjs + 2 个真死 audit 脚本），避免基线锁进噪音

---

## 1. 2026-05-09 session 已落地清单

| commit | 内容 | 文件 |
|---|---|---|
| `ee999c0e` | onboarding 链路修复 + META-F27 失实修正 + review 报告本体 | AGENTS.md / backlog.md / `_reports/systematic-review-2026-05-09.md` (新) |
| `6ecdd9e7` | INFRA-F21 加 L0 PostToolUse hook 层（session-level 早检测）| backlog.md |

**本 session 后 git status 应当是**：
- 本地 = origin/master（0 未推 commit）✅
- 3 个 untracked .mjs（`.f19-cell-labels.mjs` / `.f19-visual-audit.mjs` / `.light-theme-audit.mjs`）—— 故意保留，将与 F20 前 cleanup 一起删

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

---

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

1. **本文件**（你正在读）—— 5min
2. [AGENTS.md](../../../AGENTS.md) 必读链路 §1-8（含 Mockup 任务额外必读 §7-8 是 2026-05-09 新加）—— 10min
3. [`_reports/systematic-review-2026-05-09.md`](../_reports/systematic-review-2026-05-09.md) §1 + §7 后续行动建议 + §8 META-F27 善后 —— 5min
4. [`backlog.md`](../backlog.md) Active 段，跳到 META-F27 entry 顶部 callout 看 review 修正 + 跳到 INFRA-F21 看新加的 L0 层 —— 5min

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

---

## 3. 任务队列（按 v0.1 临界路径排序）

### 第 1 批 — backlog entry 立即建（**~30min，单 commit**）

#### NPM-001：CHANGELOG.md 生成规范
- **优先级**：High（v0.1 物理阻塞——npm publish 前必须）
- **scope**：
  - 列 0.1.0 highlights（19 canonical 组件 / 18 toggle-aware page / 翻译层 / Phase X.4.2 / F19 / F22 / F23 / F25）
  - 选 changelog 格式：Keep a Changelog 标准 vs 简化版
  - 决定后续 version bump 流程：手动 vs `changesets` / `release-please`
- **决策点（plan owner 在 prompt 里列给用户拍板）**：
  - 0.1.0 highlights 选哪几条（user 决策）
  - 后续 changelog 维护流程（plan owner 提议）
- **触发**：本 backlog entry 落仓库后即可 fire prompt
- **阻塞关系**：阻塞 v0.1 publish；不阻塞 INFRA-F20

#### NPM-002：INSTALL.md + docs/GETTING_STARTED.md
- **优先级**：High（v0.1 物理阻塞）
- **scope**：
  - `INSTALL.md`：npm install 命令 + Vue 3 setup + 全局/按需 import + tree-shaking 注意
  - `docs/GETTING_STARTED.md`：5min quickstart（创建项目 → 装包 → 引入 token CSS → 第一个组件 → theme toggle）
- **决策点**：
  - install 路径示例用 npm/pnpm/yarn 哪几个（user 决策；建议 pnpm 优先，与项目自身一致）
  - "第一个组件"用哪个（建议 Button，最直观；或 Notification 因 toggle 演示效果好）
- **依赖**：NPM-001（changelog 写完才知道 highlights 怎么对外讲）
- **阻塞关系**：阻塞 v0.1 publish

#### NPM-003：.github/workflows/publish.yml + npm publish 工作流
- **优先级**：High（v0.1 物理阻塞）
- **scope**：
  - tag-triggered npm publish（`v*.*.*` push tag → CI 自动 build + publish）
  - npm token 配置（user 操作 GitHub secrets）
  - prepare 脚本验证（已有 build / typecheck，需补 audit gates 通过的强约束）
- **决策点**：
  - 是否用 `np` / `release-it` / `changesets` 自动化 vs 手 tag
  - 是否在 CI 跑 INFRA-F25 audit suite 作为 publish gate
- **依赖**：NPM-001 + NPM-002（README/INSTALL 完整后再发包）
- **阻塞关系**：阻塞 v0.1 publish

**这 3 条 entry 落 backlog 后**，commit message 建议：
```
docs(backlog): 加 NPM-001/002/003 — v0.1 publish 阻塞物 (CHANGELOG / INSTALL / publish CI)
```

### 第 2 批 — 写 executor prompt + fire（**估时 2-4h，根据 user 节奏**）

按依赖顺序串行：
1. NPM-001 prompt → fire → review → commit
2. NPM-002 prompt → fire → review → commit
3. NPM-003 prompt → fire → review → commit

每步 STOP 等 user 拍板，不连跑。

### 第 3 批 — F20 前 cleanup（**~30min，单 commit**）

预 F20 必删（review §6.1）：
```bash
rm src/legacy/index.ts                                   # 0 consumer 实证
rm .f19-cell-labels.mjs                                   # F19 transient
rm .f19-visual-audit.mjs                                  # F19 transient
rm .light-theme-audit.mjs                                 # X.4.2 transient
rm figma-sync/audit-canonical-figma-alignment.mjs        # 1071 行真死
rm figma-sync/audit-component-token-fidelity.mjs         # 1809 行真死
rm docs/internal/canonical-figma-alignment-report.md     # 上面脚本的输出
rm docs/internal/component-token-fidelity-report.md      # 上面脚本的输出
```

commit message 建议：
```
chore(cleanup): 删 dead code (review §6.1) — src/legacy + 3 transient .mjs + 2 真死 audit 脚本
```

**做完后**：META-F27 entry 整体移到 backlog Resolved 段。

### 第 4 批 — INFRA-F20 visual baseline（**~4h**）

- 写 [`_prompts/f20-snapshot-framework.prompt.md`](../_prompts/f20-snapshot-framework.prompt.md)
- 关键决策点已在 backlog INFRA-F20 entry 列好（threshold / 双 theme baseline / Phase 1 本地 only）
- executor 跑 `pnpm exec playwright test --update-snapshots` 生成 36 张 baseline
- STOP 等 plan owner + user 视觉验收

### 第 5 批 — INFRA-F21 hooks（**~3h**）

- 现在是 L0 + L1 两层（2026-05-09 升级，详见 backlog INFRA-F21 entry）
- 前置依赖：F20 done + INFRA-F25 audit upgrade landed
- 写 [`_prompts/f21-pre-commit-hook.prompt.md`](../_prompts/f21-pre-commit-hook.prompt.md)

### 第 6 批 — v0.1 publish（**user 操作**）

- 需 GitHub secrets 配 `NPM_TOKEN`
- `git tag v0.1.0 && git push --tags`
- CI 自动 build + publish

### Out-of-scope（不在 v0.1 路径）

不要在新 session 起手做这些（除非 user 主动指定）：

- **CANONICAL-006** Pagination figma alignment refactor — prompt 已写，等 fire；可 v0.1 后做
- **INFRA-F24** page theme injection 范式统一 — 双轨当前可生存，等 user 拍板路线 A/B/C
- **INFRA-F25** audit suite formalization — 已有基础（audit:icon-fill-currentcolor / audit:no-hardcoded-design-tokens），完整化与 F21 hook 一起推
- **INFRA-F26** extract timestamp idempotence — commit cap 噪音问题，非阻塞
- **6.3** 删 Notification.success/type — 未启动；可 post-v0.1
- **6.4** 新增运行时能力 — 未启动；可 post-v0.1
- **BRIDGE-MOCKUP-001/002/003** 库债 — 设计师 owner 接手
- **EXTRACT-006 + T1c-revival** figma Styles pipeline 升级 — 长期项
- **A6** package.json 补缺失 npm script alias（`audit:page-t2` 等）— 不阻塞，可任意 session 顺手做
- **A7** docs/internal 43+ 历史 report 挪 _reports/ — 整理收益，可任意 session 顺手做

---

## 4. 已知 Bug / 不确定项（可能新 session 撞到）

| 项 | 状态 | 处理 |
|---|---|---|
| `audit-page-t2-sample.mjs` 没 npm script alias | 实证是手动 gate 工具（review §3.1 修正 Agent C 误判）| 建议 A6 顺手补 alias `audit:page-t2`，但不阻塞 |
| `figma-data/normalized/figma-mcp-cache/` 不在 PROJECT_MAP.md 数据来源表中 | 是手动 MCP 回填，非自动 pipeline 输出 | review §4 已建议补 PROJECT_MAP，新 session 写 NPM-001 时如果碰到顺手补 |
| 60 unpublished cleanup 范围未定义 | Phase X.4.2 复盘提及但未展开 | review §7.1 标 META-F27-v2 候选；新 session 如果做 NPM 链路时碰到 figma-data/raw/ 噪音再决定 |

---

## 5. 文件位置速查

| 我要看 | 路径 |
|---|---|
| 系统性 review 报告 | [`_reports/systematic-review-2026-05-09.md`](../_reports/systematic-review-2026-05-09.md) |
| 当前 backlog | [`backlog.md`](../backlog.md) |
| AGENTS.md | [`../../../AGENTS.md`](../../../AGENTS.md) |
| 最近 retrospection | [`../retrospection/2026-05-09-f23-formitem-page-rewrite.md`](../retrospection/2026-05-09-f23-formitem-page-rewrite.md) |
| Mockup 硬约束（新加必读）| [`../mockup-conventions.md`](../mockup-conventions.md) |
| 库组件目录（新加必读）| [`../figma-component-catalog.md`](../figma-component-catalog.md) |

---

## 6. 元说明

- **本文件生命周期**：next session 第 1 批任务做完后，本文件可移到 `_plans/archived/` 或直接删
- **如果新 session 决定不按本顺序做**：在新 session 重写一份覆盖本文件（保留时间戳后缀），不要在本文件里改
- **本 handoff 不是 prompt**：是 plan owner 给下个 session 的 plan owner（自己或换人）的 onboarding 文档，不直接喂 executor