# 2026-05-11 — Package scope rename + release verify 协议补丁

## TL;DR

- v0.1.0 / v0.1.1 publish **从未真正成功**：GitHub Packages scope `@tvu` 不匹配 repo owner `NancyZeng0210`，`pnpm publish` 静默失败。CI workflow green + tag pushed + commit msg 写 🎉，但 Packages 页全空。错判持续 1-2 周跨多个 session 才暴露。
- 修复：rename package scope `@tvu/design-system` → `@nancyzeng0210/tvu-design-system`，重发 **v0.1.2** patch — **first actual successful publish**。v0.1.0/v0.1.1 tags 保留为 historical artifacts（no consumer impact — no install ever succeeded）。
- 协议补丁：**Release tag pushed + CI green 不等于 publish 成功**。必须 verify GitHub Packages 页实物显示包 + 版本号；CI green 只代表 step exit 0，不代表 registry 接受。落实到 STATUS.md `Release wrap-up 必改项` + `code-conventions.md` R5 §7。
- Memory 固化：[`feedback_release-verify-packages-page.md`](.claude memory)
- **Meta lesson**：信号假象（tag push ≈ ship）是 distributed system 经典坑——单步成功 ≠ 链路成功；release flow 设计必须 thinking in terms of "what's the FINAL artifact check"。

---

## §1 失败诊断

### 现场

| 步骤 | 当时 observed | 当时 interpreted | 真相 |
|---|---|---|---|
| 1 | `git tag v0.1.0 && git push --tags` | "tag pushed → CI 触发" | ✅ 这一步正常 |
| 2 | CI workflow `Publish to GitHub Packages` 触发 | "CI 跑了" | ✅ 这一步正常 |
| 3 | 8 strict audit 全过 + `pnpm publish` step exit 0 | "audit + publish 都过 → published" | ❌ **关键误判** |
| 4 | commit msg 写 "v0.1 published 🎉" | "✅ shipped" | ❌ 错判持续 1-2 周 |

### 隐藏失败

`pnpm publish --no-git-checks` step **exit 0 但 registry 实际 reject**（GitHub Packages 要求 scope 匹配 owner）。这是 GitHub Packages 的 silent failure 模式 — `pnpm publish` CLI 不报 error 但 registry 不接受包。

错判信号链：
- ✅ `git tag` 成功
- ✅ `git push --tags` 成功
- ✅ CI workflow trigger 正常
- ✅ 8 strict audits 全过
- ✅ `pnpm publish` step exit 0（**这是骗局**）
- ❌ Packages 页实物：**全空**（这是真相，但没人去看）

错判**持续 1-2 周跨多个 session**，期间多个 retrospect / pickup 写 "v0.1 published 完整闭环"，基于错判。

### 暴露契机

User 用 browser 看 https://github.com/NancyZeng0210/TVU-Design-System/packages 才发现页全空 — Packages 页空就是真相，所有"CI green + tag pushed" 信号都没有 override 价值。

---

## §2 协议盲点

### 盲点根因

Wrap-up checklist **没强制 verify Packages 页实物**。整个 release flow 的成功判定基于：
- tag pushed ✓
- CI workflow green ✓
- commit msg 写 published 🎉

但 **CI green 不等于 registry 接受**。GitHub Packages（和很多 npm-compatible registry）允许 `pnpm publish` step exit 0 但 silent reject — 这是 distributed system 经典 silent failure。

### 错判传播

错判被多份文档放大：
- `docs/STATUS.md` "已 publish" 行 — 写"2026-05-11 → GitHub Packages"
- `docs/internal/retrospection/2026-05-11-v0-1-publish-flow.md` — 写 "v0.1.0 已发布 🎉"
- `docs/internal/_plans/next-session-pickup-2026-05-12.md` — TL;DR §1 写 "v0.1.0 已发布"
- `CHANGELOG.md [0.1.0]` 段 — 写 "首次正式发布"

每一份都基于"上游 retrospect / pickup 这么写所以是真的"的链式信任，没人主动去 verify。

### 信号假象的本质

`CI green + tag pushed` 是**中间步骤成功**信号，不是**最终 artifact**信号。Release flow 真正的 final artifact = "registry 上有这个包"。

中间信号 vs 最终 artifact 不区分 → 任何 distributed system 都会被坑。

---

## §3 修复（落地清单）

### 包名 rename（17 active files）

`@tvu/design-system` → `@nancyzeng0210/tvu-design-system`：
- `package.json` (name)
- `.github/workflows/publish.yml` (scope: `@nancyzeng0210`)
- `src/components/Badge/Badge.figma.ts` (Figma Code Connect imports)
- `README.md` / `docs/GETTING_STARTED.md` / `docs/RELEASING.md` / `docs/STATUS.md` / `docs/PROJECT_GOAL.md` / `docs/PROJECT_MAP.md` / `docs/internal/backlog.md`
- 6 个 `playground/docs/pages/*Page.vue` usageCode 内嵌 import strings
- `CHANGELOG.md` [0.1.2] 段（auto-generated via `pnpm changeset:version`）

### 决策（拍板写进本复盘避免未来重复纠结）

**CHANGELOG [0.1.0] 历史段保留 `@tvu/design-system` 引用 = by-design**：
- CHANGELOG 是 release-time 快照（描述当时 release 内容），不是 live SoT
- Consumer 当前 install 指引读 `README.md` / `GETTING_STARTED.md`（这些已改新 scope），而非历史 [0.1.0] 段
- 改历史段 = 重写历史叙事 → 违反 "history is history" 原则
- 同理：`docs/internal/_prompts/*.prompt.md`（已 fire prompt artifact）+ `docs/internal/retrospection/*.md`（历史快照）+ `_plans/archived/*.md`（归档 pickup）都不改

### 协议补丁（核心 — 防止再犯）

**STATUS.md `Release wrap-up 必改项` 段（新增）**：

```markdown
### Release wrap-up 必改项（仅 release tag pushed 时强制）

> **协议规则**：Release tag pushed + CI green 不等于 publish 成功。必须 verify
> GitHub Packages 页实物显示包 + 版本号；CI green 只代表 step exit 0，不代表
> registry 接受。

- [ ] CI workflow run 全 green（actions 页 status PASS）
- [ ] Packages 页 actual 显示 `@scope/package@<new-version>` 实物
- [ ] STATUS.md "当前版本" 段 "已 publish" 行加 Packages 页 URL link as evidence
- [ ] 复盘 retrospect 含 Packages 页 actual 状态
```

**`code-conventions.md` R5 §7 ledger entry checklist 加新条目**：

```markdown
- [ ] Release 类任务（含 changeset:version + tag push）wrap-up 必含 Packages 页
      实物 verify link 或 screenshot 作为 evidence
```

### v0.1.0/v0.1.1 tag 处理

- **保留** tag（不删）作 historical artifact
- CHANGELOG [0.1.0]/[0.1.1] 段不改（history is history）
- STATUS.md `Note` 段明示 "v0.1.0/v0.1.1 never successfully published，no consumer impact"

---

## §4 Memory: [`feedback_release-verify-packages-page.md`](.claude memory)

**核心规则**：Release wrap-up 必须 verify package registry 实物状态；tag pushed + CI triggered 不等于 publish 成功。

**实证**：v0.1.0/v0.1.1 scope mismatch fail 持续 1-2 周未被发现，纯靠 Packages 页空才暴露。

详见 memory 文件本身。

---

## §5 Meta lesson（元层学习）

### 经验 1 — 协议盲点是正常的；关键是被发现时显式 patch 而非掩盖

每个协议都有盲点，没人能 design out 所有 silent failure 模式。重要的是：
- 暴露时**显式 patch**（写进 STATUS / R5 / memory，机制化防再犯）
- **不要 retrofit 历史**叙事掩盖错判（CHANGELOG [0.1.0]/[0.1.1] 不改，错判留作 baseline）
- 把 patch 落到机制层（checklist + memory）而非个人记忆层

### 经验 2 — 信号假象是 distributed system 经典坑

任何"中间步骤成功 → 假设整链成功"的 reasoning 都是 distributed system 经典坑：
- DB transaction commit 不等于 row 实际 persist 到 disk（需要 fsync）
- HTTP 200 不等于业务逻辑成功（需要看 response body）
- CI green 不等于 deploy 成功（需要看 production state）
- **`pnpm publish` exit 0 不等于 registry 接受（需要看 Packages 页）**

**单步成功 ≠ 链路成功**。

### 经验 3 — Release flow 设计要 thinking in terms of "what's the FINAL artifact check"

Release 真正的 final artifact = "registry 上有这个包"。中间步骤（tag / CI / publish CLI）都是 means，不是 end。设计 release flow 时：

- 明确写出 "final artifact" 是什么（registry 实物 / production endpoint / 用户可见状态）
- 必须有 verify final artifact 的 step（不是 verify means）
- "tag pushed" / "CI green" / "publish exit 0" 是 means，不能替代 final artifact verify

### 经验 4 — Wrap-up 必改项检查类机制可硬性兜底

人是会忘的（甚至连续 1-2 周）。靠"plan owner 记得 verify Packages 页"不够。机制化兜底：
- STATUS.md `Wrap-up 必改项` 段是机械 checklist
- code-conventions R5 §7 是文档强制
- SessionEnd hook 可机械检测 release tag 是否 followed by Packages verify entry
- memory feedback 给 AI 起手即提醒

---

## §6 关联

- Commit chain: `fda9185a` (rename + v0.1.2)
- Tag: `v0.1.2` (first actual successful publish)
- CI run: #3 (green)
- Packages: https://github.com/NancyZeng0210/TVU-Design-System/packages
- 关联 retrospect: [v0-1-publish-flow.md](2026-05-11-v0-1-publish-flow.md)（保留 v0.1 publish 错判叙事作 baseline 实证，本复盘修正其结论）
- 关联协议补丁落点:
  - [STATUS.md](../../STATUS.md) §Wrap-up 协议 §Release wrap-up 必改项（新增段）
  - [code-conventions.md](../code-conventions.md) §R5 §7（新增 release evidence 条目）
- 关联 memory: `feedback_release-verify-packages-page.md`