# 2026-05-13 — Onboarding Gate Enforcement (L1 文本 + L3 Hook 三层)

> **Trigger**: 踩了反模式（AI session 10 skip PROJECT_GOAL + AGENTS）+ 学到通用工程经验（L1 vs L3 enforcement layering）
> **Commit**: `812365a8 chore(onboarding-gate): enforce 5-step required read chain (L1 text + L3 hook)`

---

## 1. 反模式触发实证

Session 11 起手, user 一句 "继续整理 TVU 设计规范"。AI 实际 Read 顺序：

| Step | 用户预期 | AI 实际 |
|---|---|---|
| 1 | STATUS.md | ✅ 完整 read |
| 2 | PROJECT_GOAL.md | ❌ **skip** |
| 3a | tracker (排期 SoT) | ✅ read（但 step 3 后） |
| 3b | 最新 pickup | ✅ read（顺序倒置：在 tracker 前）|
| 4 | AGENTS.md §1-10 | ❌ **skip** |
| 5 | 当前 backlog entry | ⚠️ **grep 替代完整 read** |

AI 给出的首轮推荐**方向正确**（v0.3.0 Tier 1-A translation schema 化），但**缺 4 项硬约束**：

1. AGENTS 硬规则 #6 — Figma URL → code 必须用 `src/canonical/*`
2. plan owner 默认不直接改代码，要走 executor prompt 流程
3. `working-principles.md` 7 条原则未读
4. `meta-rules.md` 反模式清单未过

User 反问："上面这个路径是我对你的预期，你是按照这个顺序来读取的吗？" → AI 诚实承认偏离 → 补齐 → 进入修复设计。

---

## 2. 根因 — L1 文本规则不够

L1 现状（CLAUDE.md / AGENTS.md / STATUS.md 都写了"必读链路"）：

- ✅ 链路已文档化
- ❌ 靠 AI 自觉 — shortcut signals 多种：
  - "我已经知道大概了"（其实没有）
  - "状态简单，跳一步"（假设缺乏验证）
  - "grep 替代完整 Read"（信息不完整）
  - "memory 兜底替代 SoT"（缓存可能 stale）

这是 [`meta-rules.md`](../meta-rules.md) trigger K "客观可测规则必须 L3+" 的直接违反 — onboarding 链路是**客观可测**（Read 5 个文件 / 没 Read = 不合格），不应停在 L1。

---

## 3. 修复 — 三层兜底

| 层 | 内容 | 跨工具？ | 强制度 |
|---|---|---|---|
| **L1a** | `docs/STATUS.md §起手必读链路` 加 mandatory gate 措辞 + tracker 显式列为 step 3a + 违反信号 + 历史实证 | ✅ 所有工具 | 文本 |
| **L1b** | `AGENTS.md` 顶部新增 `⛔ Onboarding Gate` 段（5-step checklist + 机械执行说明 + 违反信号）| ✅ 所有工具 | 文本 + mandatory 措辞 |
| **L3** | `.claude/hooks/onboarding-checklist.sh` (新) + `.claude/settings.json` SessionStart hook：注入 5-step checklist via `hookSpecificOutput.additionalContext` | ❌ Claude Code only | 机械 |

**为什么需要三层**：
- L1 单独不够（本 session 实证）
- 仅 L3 也不够（跨工具时失效；hook watcher 偶尔不生效需 `/hooks` 重载）
- 三层叠加成本 ~1h，cost 很低

---

## 4. 验证

| 检查 | 结果 |
|---|---|
| pipe-test JSON 合法 | ✅ 882 chars additionalContext |
| `jq -e` schema 通过 | ✅ SessionStart command 正确注册；UserPromptSubmit `detect-figma-task` 完整保留 |
| `git check-ignore` | ✅ 0 hits — 4 文件全进 git，clone 完整继承 |
| 新 session dogfood | ✅ user 验证 hook 触发，AI 实际执行 5-step onboarding（TodoWrite 5 项 + 5 个 Read） |
| pre-commit gates | ✅ vue-tsc / vitest 105 passed / figma-data check / visual approval 全过 |

---

## 5. 通用工程教训

1. **L1 文本规则 = 提示，L3 hook = 触发** — 关键流程必须升 L3，文本规则不可替代机械触发
2. **跨工具兜底** — hook 仅 Claude Code 生效；跨工具 (Codex / Cursor / Gemini) 靠 L1 + 项目契约文档兜底
3. **dedup-first** — 加 hook 前先 read 现有 settings.json，merge 不覆盖（本次差点覆盖 UserPromptSubmit `detect-figma-task` hook，靠 jq 验证 catch）
4. **pipe-test before commit** — hook 脚本写完先 `echo '{}' | script` 验 JSON 合法 + 字段正确，再 commit
5. **SoT 缺口要查** — STATUS.md `起手必读链路` 段漏 tracker 为显式 step，即使 STATUS.md L7 顶部已提到 tracker SoT — **文本提及 ≠ checklist 显式步骤**

---

## 6. 关联

- **真源**：
  - `docs/STATUS.md §起手必读链路`（5-step checklist）
  - `AGENTS.md §Onboarding Gate`（跨工具适用）
  - `.claude/hooks/onboarding-checklist.sh`（机械触发）
- **触发器**：`docs/meta-rules.md` trigger K（客观可测规则 → L3+）
- **Commit**：`812365a8`
- **Tracker entry**：`design-spec-canonical-alignment-tracker.md` 轨道 A "已完成" 表 INFRA-F31 行