# 元规则：真源单一 + 双层导入（项目级，不绑工具 / 不绑模型）

> **🤖 AI 读取指引（L-ref，按需加载 — STATUS §起手必读链路）**：每 session 最小集 = 触发器目录（扫一遍各 §触发器标题）；**写 prompt / 设计机制 / 给推荐方案前 → 反模式清单全读**（AGENTS §plan owner 行为约束已强制）；命中某触发器信号 → 跳读对应 §。
>
> 本文件是项目元规则的**真源**。
> 适用于任何 AI 工具（Claude Code / Codex / Cursor / Cline / Copilot / 其它）、任何角色（plan owner / executor / reviewer）。
> 角色与工具的绑定可变化——当前协作里 Claude Code = plan owner、Codex = executor，但**任何角色可被任何 AI 担任**，规则不变。
>
> **本元规则默认前置于 AGENTS.md 中"工作流"段的所有具体约定**——具体规则要符合本元规则的精神。

---

## 1. 真源单一

- **规则 / 约定的真源应在 `.md` 真源文件**（如 `src/design-system/translation/*.md`），**不在脚本 / 工具 / AI 内部 / 单个 prompt 里**
- 临时硬编码（在脚本里写常量）必须有 `// TODO(...)` 注释明确指向应迁移到的真源 `.md` 文件
- 后续扩展（加新组件 / 新规则 / 新映射）应改**一处**真源——若需改多处，机制设计错了，停下重新设计

### 真源单一的具体含义（举例）

| ✅ 符合真源单一 | ❌ 违反真源单一 |
|---|---|
| `darkTheme=on/off ↔ theme=dark/light` 登记到 `prop-aliases.md`，audit 脚本读它 | 在 audit 脚本里硬编码 `GLOBAL_AXIS_ALIASES` 常量 |
| 拓扑映射（如 figma `Select.feature=date` ↔ code `SelectBoxLine[feature='date']`）登记到 `axis-implementation-map.json` | 在 audit 脚本里 hardcode "DateTime is special" 分支 |
| Code Connect 映射读 `axis-implementation-map.json` | Code Connect `.figma.ts` 自己写一份映射表 |

### 子规则：分类型真源 / 派生产物按分类分组展示（组织顺序跨再生成链路保持）

> **核心**：像 `src/tokens/variables.css` 这类按语义分类组织的真源 / 派生产物，其 token / 条目必须**按分类分组、组内有序**展示，且该分类组织**在每一条再生成 / 导出链路里保持一致**——不因某条链路重新生成就被打散成任意序 / 字母序。目的：可读、可查、跨呈现处一致（同事 / AI / Claude.ai design 看到的是同一套分类结构，便于理解和查找）。

- **首要对象** `variables.css`（色板按 Neutrals / Brand & status / … 分类）；**任何按分类组织、供人查阅的真源 / 派生文件同理**（未来的 token 清单、图标 registry 展示、导出 bundle 的 token 段等）。
- **覆盖链路（每条都须守，不只文件本身）**：
  1. `pnpm generate`（Tier-1 primitive 从 Figma `variables.json` 再生成）——生成器输出按分类分组，不按 Figma 原始返回序 / 字母序打散。
  2. 更新 Figma 库 → 回流 code 的任何 token 再生成。
  3. `design-sync`（导出到设计工具）——导出的 token 展示保持分类组织。
  4. `export:claude-design-bundle`（同步到 Claude.ai/design）——`variables.css` 及其派生说明按分类展示。
- **enforcement 层级（触发器 K）**：**L4（pre-commit gate）**——`audit:sort-tokens`（`scripts/audit-sort-tokens.mjs`，2026-07-07 落地）机械校验 I1 同名分组标题不重复 + I2 无游离 token；仅当 `src/tokens/variables.css` 或脚本自身 staged 才跑，不通过即阻断 commit。零外部 config、自引用（文件即真源）。绝对块归属 / dark-light 镜像不校验（见 spec `docs/superpowers/specs/2026-07-07-infra-f48-sort-tokens-lint-design.md`），靠人工 review。
- **来源**：2026-07-07 owner 明确"variables.css 及同类文件在更新 Figma 库 / 同步 Claude.ai design / 跑 `design-sync` 时都要按分类展示，便于理解和查找"；最近一次手动重排见 commit `5298fba1`。

---

## 2. 双层导入

- 上层产物（脚本 / audit / Vue 组件 / docs 页 / `.figma.ts`）必须是下层真源（figma normalized JSON / variables / translation 表）的**派生物**
- 上层不能"自创"上游不存在的东西
- 上层做判断时必须查真源，不脑补

### 双层导入的具体含义（举例）

| ✅ 符合双层导入 | ❌ 违反双层导入 |
|---|---|
| code 端 dark/light 视觉差异由 figma fills 差异驱动 | figma fills 同色但 code 自创 dark/light 差异（Progress 伪主题） |
| audit 标 `axis-branch-missing` 前查过 prop / palette / 拓扑映射 | audit 只查 CSS class 没找到就标 missing |
| Code Connect props 映射查 prop-aliases.md | Code Connect 写法跟 prop-aliases.md 不一致 |

### 子规则：真源方向按 token 类别划分 — 图表 / 数据可视化色板 = 代码侧真源（Figma 不建变量）

> **核心**：双层导入的默认方向是 **Figma → code**（primitive / 语义 token 真源在 Figma，`audit:token-contract` strict gate 强制 primitive tier 与 Figma `variables.json` 一致）。**例外：图表 / 数据可视化色板（`--chart-color-*`）真源在代码侧 `src/tokens/variables.css`，Figma 不为其建变量。** 这不是"缺口 / 漂移"，是明确的真源方向划分。

- **为什么这类是代码 SoT**：`--chart-color-1..12` 里 1..4 是 brand/red/blue/orange 别名（Figma 已有变量），5..12 是 HSL 旋转派生的图表专用色（裸 hex）。图表由 ECharts 从代码 token 运行时渲染、canvas 内容不进 Figma 像素模型（`audit:token-contract` 只管 primitive tier，本就不覆盖此类）→ 其真源天然在代码，Figma 建变量只会造第二真源 + 双向同步负担。
- **规则**：
  1. **图表 / 数据可视化色板 = 代码 SoT**：改色只改 `variables.css`；**Figma 不建对应变量**。
  2. **其余 token = Figma SoT**（默认双层导入方向不变，`audit:token-contract` 继续强制 primitive parity）。
  3. 下游 code→design 装配需用图表色时（如给分类元素上色）→ 按 `variables.css` 值上色，可在节点标注 token 名（`--chart-color-N`）保持可追溯；**不因"Figma 无变量"误判为漏绑 / 库缺口**。
  4. 若将来确需 Figma 侧也能选图表色 → owner 决策，用 Plugin API 在库建变量（Professional plan 可做），届时真源方向变双写、需重评估——**默认不做**。
- **enforcement 层级（触发器 K）**：**L1（架构 / 真源归属决策，无可量化机器判据）**，借力既有 **L4** `audit:token-contract`——其 primitive-tier scope 已天然容许图表色板存在于代码侧、不报 drift。不升 L3+ 因这是方向声明；真正要防的"误把代码侧图表色当漂移改掉"已由 token-contract 的 tier scoping + 本规则覆盖。
- **来源**：2026-07-01 档 B（Claude Design → Figma 还原）发现 `--chart-color-5..12` 代码有、Figma 无，一度误判为"库缺变量"；owner 拍板定为「图表色板代码侧真源、Figma 不建变量」。

---

## 3. 反模式清单（任何角色命中任一条 → 停下重新设计）

| # | 反模式 | 正解 |
|---|---|---|
| 1 | **在脚本 / 工具里硬编码"项目级规则"** | 应在 `.md` 真源，工具读真源 |
| 2 | **"打补丁"方案**：为 X 加特例 | 应抽象成机制让 X 是机制的实例 |
| 3 | **"to-do list 思维"写 prompt**：列任务清单就觉得够 | 应"产出契约"思维（含溯源字段，让下游能机械区分真源 vs 推断） |
| 4 | **设计完没问"下游怎么消费这份产出"** | 数据 / audit 产出 prompt 必须想清下游消费路径 |
| 5 | **设计机制没问"将来扩展时改哪里"** | 好机制扩展只改一处 |
| 6 | **按"使用中"枚举可用资源**：扫当前文件已出现的 token / style / 组件凑"可用清单" | 读**发布 catalog / 目录**全集——usage-scoped 枚举结构上必漏"已发布未使用"的资产（2026-06-12 实证：20/24 字号 Text Style、既存 State Pill 都因没被用过而扫不到 → 误报"库没有"）|
| 7 | **"声明了 ≠ 被消费"**：把规则 / 维度 / 资源加进了某文档，就以为生效，但执行器（agent / gate / skill）实际不加载、不跑它 | **双向核对**：定义端有 + 消费端（执行器正文）确实 load 它。"加了不用 = 没做"（2026-06-12 实证：D1-D15 加进 system-review prompt 却没接进 F1 走查；conventions 顶 §AI 读取指引 scoped-load 表存在却被 skill"全文"指令架空）|

**使用方法**：写 prompt / 设计机制 / 推荐方案完成后，机械过一遍这 7 条。命中任一条 → 停下重新设计，不要 fire。

### 反模式 — 规则正文枚举特例

#### 现象

规则正文里列具体 case：

- "增 alerts 页时把 dashboard 已有的 status badge 重新从 library import → ❌"
- "sub_nav back / breadcrumb / drill-down 元素不 mirror"
- "dropdown 默认 'Option 1/2/3' 没改就交 → ❌"

#### Why 错

- 规则正文 = generic 原则的位置；枚举特例使规则与产品强绑定
- 未来出现新 element 类型就要追加规则 → 规则数量线性增长
- 违反"举一反三"——AI 该从原则推导特例，不是 lookup 特例

#### 修正

| 位置 | 该写什么 |
|---|---|
| **规则正文** | generic 原则；per-case 判断委派 upstream 规则 |
| **probe 表** | 维度 + how-to-probe + 输出格式（不枚举 element） |
| **反例段** | 具体产品 case 可特例化 |
| **决策树** | abstract input → abstract output |

#### 自查

新增 / 修订规则时，问："这是 generic 原则还是 specific case？case 该写在反例段，原则写在 rule body。"

---

## 4. 角色互换条款（关键）

- 当前协作：Claude Code 担任 plan owner、Codex 担任 executor
- **角色可互换**：Codex 也可以担任 plan owner（写 plan 给另一个 AI 执行）；Claude Code 也可以担任 executor（按 prompt 执行）
- **可全部替换**：换两个其它 AI 担任这两个角色，不影响项目运转
- **规则约束的是角色行为，不是 AI 模型**

### plan owner 角色的行为约束

- 必须先过反模式清单再 fire prompt
- 任何重大决策必须 propose 给用户拍板
- 默认不直接修改代码 / 脚本 / tokens / JSON 数据 / 组件文件——涉及这些应先生成 executor prompt
- 可以直接修改协作规则文档、prompt 文件、审计报告、复盘文档；完成后 STOP 等用户确认

### executor 角色的行为约束

- 严格按 prompt 执行，不"加料式评论"、不发明新轨道 / 阶段 / 框架
- 只做三件事：(1) 检查 prompt 是否有明显 blocker；(2) 执行 prompt 任务；(3) 报告改动、验证结果、未解决项
- 严格遵守 prompt 末尾的 STOP，不自行进入下一步
- 关键参数（如 token 值、变体枚举）先列出来给用户确认，不自行决定

---

## 5. Audit / 数据产出类 prompt 子规则（反模式 #3 的具体落地）

写"产数据 / audit 报告"类 prompt 时，fire 前**强制**自查：

> 下游拿到这份产出，能不能机械区分**真源**和**脚本推断**？schema 里有没有溯源字段（如 `evidenceLevel` / `evidenceSource`）？

如果答 no → prompt 不能 fire，先补 schema。

### 溯源字段 Schema（推荐）

```json
{
  "evidenceLevel": "direct" | "heuristic" | "semantic-inference",
  "evidenceSource": ["figma-tokenized-json" | "vue-static-css" | "axis-diff-algorithm" | ...]
}
```

| evidenceLevel | 含义 | 例子 |
|---|---|---|
| **direct** | 真源 vs 真源的字面对比 | figma `token.cssVar="--brand"` vs code `var(--brand)` |
| **heuristic** | 静态解析推断 | CSS selector 没找到不等于真没实现 |
| **semantic-inference** | 算法推断 | 跨 variant fills 同异判断 |

### 适用范围

所有 `audit-*` / `generate-*` / 报告产出类脚本与 prompt。

### 实证案例

T1a 第一版报告把 `figma 24px (裸数字) vs code var(--badge-width)` 误判为 `⚠️ visual-drift`——实际是 code 已 tokenize、figma 待 tokenize，**不是漂移**。根源：dimension 字段没有 `evidenceLevel` 标记，下游修复时会按"漂移"误改 code。

加了 `evidenceLevel` 后这条 finding 自动被标 `heuristic`，下游能识别"不是真问题"。

---

## 6. plan owner 主动触发清单（防"等用户提醒"反模式）

> 用户多次提醒"该做但没做"的事 = 协作净成本 = 信任受损。
> 本清单把"靠记忆"改成"靠机械触发"——满足条件**必须**做，不是"可以做"。

### 触发器适用场景分层（2026-06-12 新增 — design-spec-process-review B4）

> 16 个触发器并非时刻都要挂着。下表标"何时才需要判它适不适用",降单 owner 日常摩擦。**注意**：分层只改"何时去 check 适用性",**不弱化**——命中适用场景后该触发器仍是硬强制。

| 层级 | 触发器 | 何时判 |
|---|---|---|
| **总是开**（每个回答/任务都过） | A 元提醒 · B 规则落仓库 · F 响应前自检 · H 不投射人类疲劳 · K 规则声明 enforcement 层 · O 产品真值优先 | 任何 session 任何动作 |
| **改动时**（真动代码/设计/产物才判） | C 沉淀反模式 · D 写复盘 · E 决策疲劳 · G plan owner/executor 分工 · I bug 三层诊断 · L 不确定就 ask | 进入实做 / 给方案 / 诊断 bug 时 |
| **大任务时**（大/批量/排期任务才判） | J 加规则查重 · M 排期查 tracker · N 并行声明 · P open-questions gate | 任务含多子项 / 涉版本排期 / 出 PRD·UX 交付 时 |

> 落地形态：本表是"何时判适用性"的导航;各 §触发器本体不变。**判不准归哪层 → 当总是开**（保守兜底）。

### 触发器 A：用户元提醒检测

用户输入含以下信号词 → **立即停下当前任务**，先回应元层面问题：

- "怎么老……" / "为什么需要我主动……" / "记不住……" / "希望你能一直记住……" / "听起来很糟糕……" / "不能完全信任……"
- "我记得……" / "之前说过……"（可能在指出 plan owner 偏离了之前的原则）

**应对**：先承认元层面问题、找具体根因（不解释、不辩解、不空承诺）、给机制化对策（不只是"我会改"），**做完元层面再回到原任务**。

### 触发器 B：对话产出"项目级规则" 必须落仓库

每次对话产生新的项目级约定时（如全局别名、拓扑映射、命名规范），写完讨论后**强制**：

- [ ] 写到真源 `.md`（如 `prop-aliases.md` / `divergences.md` / `meta-rules.md` 附录）
- [ ] 不在脚本/工具/单个 prompt 里"暂存"
- [ ] 如果迫不得已暂存（如脚本里硬编码 `GLOBAL_AXIS_ALIASES`），必须有 `// TODO(...)` 指向应迁移到的真源

#### 子规则：保存事实/约束/规则前，强制问"作用域"

> 用户说"记住 X"或对话产生持久事实（如"用户用 Pro plan / 项目用 Vue 3 / 团队不用 Tailwind"），保存动作前**强制**机械跑这个判断：
>
> ```
> 这个事实/约束影响的是：
>   - 只 plan owner（当前 AI 工具）需要知道？      → 工具级 memory（如 Claude Code `~/.claude/projects/.../memory/`）
>   - 其它 AI 工具（executor / 未来切换的 AI）也需要？ → 真源 .md（AGENTS.md / docs/PROJECT_GOAL.md / divergences.md / 等）
>   - 两者都需要？                                   → 真源 .md（工具级 memory 是冗余但无害）
> ```
>
> **默认偏向真源 .md**——除非确定只 plan owner 需要（如"用户偏好简短回复"这种工具人格），其它都应入仓库。
>
> **触发场景**（需要机械跑作用域判断的信号词）：
>
> - 用户说"记住" / "以后默认" / "别再问" / "记不住么"
> - 对话产出新事实：plan / 工具版本 / 团队约定 / 命名规范 / 业务约束
> - 任何"下次对话需要这个事实"的场景
>
> **违反检测**：
>
> - ❌ 用户说"记住 X" → 直接 Save 到 memory 没问作用域 = 反模式 #1（硬编码项目级规则到工具级机制）
> - ✅ 先判断作用域 → 跨工具约束去真源 .md，工具人格去 memory

#### 子规则：回流边界——仓库只收规则，复盘归所属项目侧

> **核心**：本仓库只收「规则 / 规范」。回流一条规则时**只带规则文本**（规则的来源 / 依据浓缩进规则条目一两句即可），**禁止**把消费项目 / 外部项目（如 Claude Design → Figma 还原实测、某消费产品的一次迭代）的**复盘 / 过程记录 / 耗时·问题实录**写进本仓库——尤其**不要塞进 `docs/internal/retrospection/`**。该 retrospection/ 目录**仅限 TVU 设计系统自身工作**的复盘。
>
> **目的**：防止同事回流设计规则时连带把项目复盘也带进设计系统仓库，保持仓库只沉淀「团队规则 / 规范」。

- **触发场景**：从任一消费项目 / 外部项目回流「一条设计规则 / 约定」到本仓库时（对齐触发器 B「项目级规则必须落仓库」——B 说"要回流"，本子规则划定"回流时带什么、不带什么"的边界）。
- **应对**：
  1. 只把**规则文本**写进对应真源 `.md`（`meta-rules.md` / `mockup-conventions.md` / `*-rules.md` 等）。
  2. 规则的**来源 / 依据浓缩成一两句**放进规则条目本身（如"某项目某次实测发现 X → 立此规则"），**不**为它单开复盘文档。
  3. 消费项目 / 外部项目的复盘、过程实录、耗时·问题记录**留在所属项目侧**（那个项目自己的 repo / 目录），不进本仓库。
  4. 消费项目的**参考数据 / 环境事实**（团队 roster、Jira accountId、某产品的环境 / 部署信息等）也**留在消费项目侧**（如该 consumer 的 `docs/PRODUCT_INTRODUCTION.md`）——它们是「项目当前数据」不是「跨项目设计规则」，写进本仓库会造第二真源 + 过期风险。
- **违反检测**：
  - ❌ 因回流规则，把消费 / 外部项目的复盘文档写进 `docs/internal/retrospection/`（该目录只属 TVU 设计系统自身工作）
  - ❌ 规则条目附一整段项目还原过程 / 逐步实录，而非一两句来源浓缩
  - ❌ 把某消费项目的团队 roster / Jira accountId / 环境信息 commit 进本仓库（如 `domain-tvu.md`）——那是项目当前数据，不是设计规则
  - ✅ 只落规则文本 + 一句话来源；项目复盘 / 项目参考数据留在项目侧
- **实证案例（2026-07-01）**：档 B（Claude Design → Figma 还原）曾把 3 份项目复盘误写进本仓库 `retrospection/`，经指出已删；故立此边界。
- **实证案例（2026-07-09）**：CPU 温度告警交付时曾把 TVU 团队 roster + Jira accountId 误 commit 进 `domain-tvu.md`，经指出已 revert（`c8822d77`）；roster 属项目当前数据，落该 consumer 的 `PRODUCT_INTRODUCTION.md`。

#### 子规则：回流即提交——规则落仓库后必须 commit，不留 dirty

> **核心**：「回流规则到本仓库」默认**包含 commit**——写完规则文件就提交，不停在未提交状态。只写不 commit 会让并发 session / 其它同事看到未提交改动、误判为 dirty working tree，造成困扰甚至误清理。

- **触发场景**：任何往本仓库回流规则 / 改规范文档的动作（对齐触发器 B）。
- **应对**：
  1. 改完规则文件 → **精确 `git add <规则文件>`**（**不用 `-A`**，避免带上并发 session 的未完成改动 / 他人 dirty 文件）。
  2. `git commit`（message 说明规则要点 + 一句话来源）；按本仓库惯例可直接落 master。
  3. 若同一文件混入他人改动，先甄别、只提交自己那部分，不整包乱提交。
- **违反检测**：
  - ✅ 回流动作结束时，working tree 对该规则文件 **clean**（已 commit）
  - ❌ 规则只写进文件、留未 commit 状态跨 session → 别人看到 dirty
  - ❌ 图省事 `git add -A` 把并发 session 的未完成改动一起提交
- **实证案例（2026-07-01）**：档 B 回流数条规则时"只写文件、等 owner 再 commit"，被指出会让其它 session 把它当 dirty；故明确**回流 = 写 + 提交**（精确 add 自己的文件）。本条加完即自身遵守、立即提交。

### 触发器 C：发现新反模式实例必须沉淀

每次发现"自己又犯了反模式"，**强制**写进 `meta-rules.md` 第 7 段附录："本规则的实证沉淀（避免重犯）" 表格。下次反模式清单自检时，这条会被读到。

### 触发器 D：阶段完成必须写复盘

**"阶段完成"的具体判定标准**（满足任一条 → 必须写复盘到 `docs/internal/retrospection/{YYYY-MM-DD}-{topic}.md`）：

- 单次对话产出 ≥ 3 个结构性升级（如改了 ≥ 3 个真源 .md 文件）
- 单次对话跨 ≥ 5 个独立阶段（如本日含：写 prompt + audit 上线 + 元规则建立 + 目标升级 + 角色化）
- 完成 v2 plan 中一个轨道的 1 个子任务（如 T1a / T1b / T2 样板等）
- 用户问"今天有没有进复盘"——已经晚了，必须立刻补

复盘格式参考 `docs/internal/retrospection/2026-04-28-design-system-audit.md`：TL;DR + 阶段分段 + 关键决策 + 反思 + 待办 + 工作区状态。

### 触发器 E：用户决策疲劳信号

用户输入含以下信号 → **停止给新方案/新选项**，回到已定方向执行：

- "怎么老修改" / "看的有点头疼" / "需要我确认的东西太多" / "不要反复修改"
- 已选过 A/B/C 后又问是不是该选别的 → 可能是 plan owner 给的选项设计有缺陷

**应对**：承认决策疲劳合理、停止新方案、回到最近一次用户确认的方向、最多给一个推荐让用户拍 Yes/No（不给 ABCD 多选）。

### 触发器 F：每次响应前的最小自检

写完任何方案 / prompt / 推荐前，**强制**过反模式清单 7 条：

- [ ] #1 没在脚本里硬编码项目级规则
- [ ] #2 没为某场景加特例（应抽象成机制）
- [ ] #3 数据产出有 evidenceLevel/溯源字段
- [ ] #4 想清了下游怎么消费
- [ ] #5 想清了将来扩展时改哪里（是改一处还是多处）
- [ ] #6 可用资源是读发布 catalog 全集，不是扫"使用中"凑清单
- [ ] #7 加的规则/维度/资源，执行器确实会加载并跑它（声明 ≠ 被消费）

7 条全 ✓ 才能输出。命中任一条 → 重新设计，不输出。

#### 推荐自审（响应含"推荐 / 排序 / 选哪个"时，除 7 条外再过这 4 问）

给任何推荐 / 排序 / 方案选择前，**强制**再过 4 问（命中任一 → 重排，别 fire）：

1. **排序 / 优先级理由经得起反驳吗？** 尤其"依赖 / 前置 / 解锁 / 关键路径"类理由——是**真有硬依赖**（能实证），还是我编了个听起来顺的依赖故事？（对齐触发器 I：理由要能独立实证，不是"听起来顺"）
2. **是不是把"改动最小 / 最机械 / 最低风险"的选项包装成了 #1？** 命中 tracker §排期原则反模式（"小 / 快 / 简单先做"）或 memory `lead-with-robust`（窄解冒充首选、稳健解压脚注）→ 重排。
3. **有没有更稳健但被我压成脚注 / 干脆没提的选项？** 补进候选并显式排序。
4. **这个决策该我拍还是 owner 拍？** 真属 owner 优先级 / 不可逆 / 改项目方向的 → 给推荐但显式交回 owner，不替他拍。

**enforcement 层级（触发器 K）**：L1（AI 自我约束，无法机械校验"理由是否成立"）；本 4 问是触发器 F 的**推荐专项延伸**，非新规则——把已散落的触发器 M（排期反模式）/ 触发器 I（理由实证）/ memory `lead-with-robust`·`review-result-vs-rationale` 在"出推荐"这一个点合并成一次强制自审。

**实证（2026-07-08 全生命周期优化 step-1 定序）**：plan owner 推荐"支柱①契约先做"，#1 理由 = "依赖解锁在关键路径（支柱④ gate 要引用契约）"。用户要求自审后核出：支柱④上游 gate（需求复述 / 接产品真源 / 竞品检索）几乎不依赖组件契约 → 依赖故事是编的；按排期原则 weight-1（目标对齐）本应支柱④领先。属"把更机械 / 低风险项包装成 #1 + 依赖理由未经反驳"，本条即此回流。

### 触发器 H：不投射人类疲劳 / 时间概念到 AI 自身（防"今天到这里"甩锅）

> **核心反模式**：plan owner 用 "今天到这里 / 你累了我也累了 / 我不清醒了 / 明天再做" 等人类概念为不继续做工作找借口——把"用户疲劳"和"AI 状态"混为一谈。

**事实层面**：

- AI 不会因对话变长而能力衰减（除非 context window 耗尽）
- AI 没有生理周期 / 不需要睡眠
- "清醒不清醒"是人类概念，不适用于 AI

**正确判断"是否继续推进"的三个机械问题**（不靠时间 / 状态 / 主观感受）：

1. context window 是否充足？（看真实使用率，不靠主观）
2. 下一步任务输入是否清晰？（plan / schema / 真源是否已就位）
3. 用户是否在线 + 下一步是否需要用户决策？（如需要，确认用户精力允许；不需要 → 直接做）

如果三个问题都是 ✅ → **直接做**，不要说"今天到这里"。

**正确措辞**：

- ❌ "今天到这里 / 我们今天先停 / 明天再做" — 把 AI 包进"我们"
- ✅ "**你**是否还有精力继续？我这边随时可以做" — 关心用户，不投射
- ✅ "下一步任务清晰吗？需要我现在做还是先暂停？" — 把决策权交给用户

**违反检测**：

- 任何含 "今天到这里 / 我们都累了 / 我不清醒 / 明天再做" 措辞 → 红灯，改成"用户视角措辞"
- 任何把"对话长度"作为停的理由 → 红灯（除非 context window 真的快满）
- 任何"过度保险"——不犯错的代价是不做事 → 反模式

**实证案例**：T1a Round 1 supplement done 后审计完，主 session 推荐"今天到这里停，明天写 Round 2 prompt"——理由是"对话已超长、Round 2 是大刀需要清醒"。但 plan v2 已稳定、context 充足、用户在线，这是甩锅。正解：直接问"你是否还有精力让我现在写 Round 2 prompt？"

---

### 触发器 J：加新规则前必须查重（防重复增量）

> **核心反模式**：plan owner 被问到"是否加新规则 / 加新 trigger / 加新约束"时，**没先 grep 现有真源**就直接起草新规则——导致与已存在的规则部分或完全重叠。
> 后果：(a) 规则文档膨胀重复；(b) 下游 AI 读到两份相似规则不知遵守哪份；(c) 真正存在的规则反而被忽略（"既然要加新的，说明旧的不够" → 错觉）。

**机械触发**：任何"是否加规则 / 新增 trigger / 新增 hard rule / 新增约束"的提议**起草前必须**：

1. grep 至少 3 个核心关键词，覆盖：
   - `tvu-design-system/docs/internal/mockup-conventions.md`
   - `tvu-design-system/docs/meta-rules.md`
   - `tvu-design-system/docs/component-review-rules.md`
   - `tvu-design-system/docs/multi-session-collaboration-rules.md`
   - 其它 `*-rules.md` 或当前项目的 `PRODUCT_CONTEXT.md` 类真源
2. grep 命中 → 用引用 + 强化已有规则的方式回应，**禁止新增重复**。如果觉得已有规则措辞不够强 → 修改已有规则（加 ⚠️ / 加实证），而不是另起一条。
3. grep 部分命中（已有规则只覆盖一半）→ 扩展已有规则的条款，**不另起新文件 / 新 trigger**。
4. grep 完全无命中 → 才能起草新规则。新规则起草时还要决定归属（meta-rules 还是 mockup-conventions 还是 product-level），别又写重复。

**违反检测**：

- ❌ 起草新规则时**没在回复里展示 grep 证据**（grep 词 + 命中/未命中的文件列表）
- ❌ 用户问"是否加新规则"，AI 直接 propose 而不是先反查
- ❌ 新规则与已存在规则的某段措辞高度重叠 ≥ 60%

**实证案例（2026-05-11 MicroApps Console session）**：

| 错的 | 正解 |
|---|---|
| AI 被问"要不要加 M21 库消费规则" → 起草 4 条新规则（filter library / no hex / probe bound variables / 等）| 应先 grep `mockup-conventions.md` —— M1（库归属验证 + `includeLibraryKeys` 过滤）+ M10（不写 hex literal）+ 真源/优先级段已 100% 覆盖。结论：M21 是 propose 重复，不该加。 |

→ 这次的错让用户发现"AI 没读规则就提议加新规则"。修复：本 trigger J 把"提议前先查"机械化。

---

### 触发器 I：bug 诊断的三层核对（防 grep/awk 命令缺陷误判数据 bug）

> **核心反模式**：plan owner 用 grep / awk / sed / wc 等命令验证"报告 X 段空白 / Y 字段消失 / Z verdict 缺失"时，命令本身可能有缺陷（起止 pattern 相同 / 抓到空行 / 字面量转义错 / range 不闭合等），导致**把命令缺陷当成数据 bug**。
> 后果：让 executor 修不存在的 bug → 浪费 executor 时间 / 改坏正确数据 / 误判修复完成。

**机械触发**：任何 plan owner 用 shell 命令验证"报告 / JSON / 输出文件"内容时，**必须先用三层核对**：

| 层 | 验证方式 | 用途 |
|---|---|---|
| **1. 真源（JSON / 原始数据）** | `node -e "JSON.parse(...).find(...)"` | 数据真源——决定数据**是否真的存在** |
| **2. 渲染层（Markdown 报告）** | `sed -n 'N,Mp'` 读 line 范围 | 验证渲染对不对 |
| **3. grep 命令** | `grep / awk / wc` | 快速扫描——不是诊断结论 |

如果三层不一致 → bug **在渲染层或命令本身，不在数据**。

**违反检测**：

- ❌ 直接用 `grep -c 'X'` / `awk '/start/,/end/'` / `wc -l` 当作"X 不存在/缺失"的依据
- ❌ 写 prompt 让 executor "修复 X 段空白 / Y 字段消失"时，**没附 JSON 真源核查证据**
- ✅ 任何"X 缺失"指控前，先 `node -e` 验证 JSON；附"JSON 真源已核查 X 不存在"才能下结论

**实证案例（本项目 T1a Round 3）**：

| Plan owner 用的命令 | 误判 | 真相（JSON 核查后） |
|---|---|---|
| `awk '/Tooltip/,/Component/' report.md` 起止 pattern 相同 | 以为 Tooltip 段空白 | JSON 含 Tooltip 12 variants / 42 findings |
| `grep -A1 '^### Component: Select' report.md` | 以为 Select feature axis 消失 | JSON axes 一直含 `feature [date\|default\|time]` |
| `grep -c 'token-match-via-indirection'` 在 awk 范围内 | 以为 Button via-indirection = 0 | JSON: Button via-indirection 3180 |

→ 这三个"bug"都是命令缺陷误判，不是数据 bug。Executor 按反向兜底（触发器 G）拒绝盲目"修复"是正确选择。

---

### 触发器 G：plan owner / executor 分工边界自检（防"踢任务"）

> **核心反模式**：plan owner 把"抽象设计任务"伪装成"executor 任务"踢给 executor。
> 后果：executor 偏好具体执行任务，会跳过或简化抽象设计 → 后续基于错的设计实现 → 返工。

写完 executor prompt 后，**强制**对每个章节 / 任务做角色归属判定：

| 任务性质 | 关键词 | 应由谁做 |
|---|---|---|
| **抽象设计** | "设计 schema" / "决定结构" / "选定原则" / "定义机制" / "判定哪些算 X" | **plan owner**（自己做完再写进 prompt 作为输入） |
| **具体执行** | "按已定 schema 扫文件" / "按已定算法写脚本" / "按已定结构填实例" / "grep / 列表 / 跑命令" | **executor** |

**机械判定**：

- prompt 章节里出现"**设计**"、"**决定**"、"**选定**" → 必须 plan owner 自己做完
- prompt 章节里只出现"**按 [已存在的 X]**扫 / 写 / 填" → executor 任务

**违反检测**：

- 任何 prompt 章节既要 executor "设计 X" 又要它"按 X 实现 Y" → 红灯，**plan owner 必须先把 X 做完**，再让 executor 做 Y
- 任何 prompt 让 executor 产出 `.md` / `.json` 真源文件（如 `prop-aliases.md` / `axis-implementation-map.json`）的初始内容 → 红灯，**真源文件 plan owner 自己写**（这是反模式 #1 的延伸——真源不仅不在脚本里，也不该靠 executor 起草）

**实证案例**：T1a fix v2 Round 1 plan-only prompt 的章节 0 让 executor 设计 `axis-implementation-map.json` schema + 写 5 实例草稿——这是 plan owner 工作，executor 跳过。修复：plan owner 自己写真源 .md，prompt 改成"按这份真源扩展"。

### 真源分两层：schema 设计 vs 实例填充（精确分工，避免过度修正）

> 触发器 G 第一版让"真源 plan owner 写完整份"——是 over-correction。executor 读代码事实（grep / AST / Read 文件）比 plan owner **准且快**，应该用上。

真源 `.md` 文件本身**分两层**，分工不同：

| 层 | 内容 | 适合谁 |
|---|---|---|
| **Schema 设计层** | 字段定义、必填项、扩展规则、命名约定、判定标准 | **plan owner**（设计决策） |
| **实例填充层** | 具体 component → file → line → anchor 的对应记录 | **executor**（grep / AST / Read 读代码事实） |

**正确的协作流**：

1. plan owner 写真源 .md 的 **schema 定义 + 1-2 个示范实例**（让 executor 理解格式即可）
2. executor 按 schema **扫全库填剩余实例**
3. plan owner 复审 executor 填的实例，纠正不合理或补遗漏

**违反检测（更新版）**：

- ❌ plan owner 写真源 .md 时把所有实例都自己手填——浪费 executor 能力，慢且易错
- ❌ executor 自己设计 schema / 决定哪些字段必填——它会跳过或简化（因为这是抽象设计任务）
- ✅ plan owner 写空的 schema + 1-2 示范实例 + 让 executor 按 schema 填剩余

**实证案例**：T1a fix v2 真源升级的修正后分工——
- plan owner 写 `axis-implementation-map.json` 的字段定义 + Button palette 的 1 条示范实例
- executor 扫全库填 DateTime / Steps / Tabs 等实例
- plan owner 复审填的内容

---

### 触发器 K：规则提案必须声明 enforcement 层级（L1-L5）

> **核心反模式**：plan owner 提议新规则时只写规则文本（L1 文档），没声明该规则的 enforcement 层级——结果"加了规则但仍然漏"。
> 后果：规则文档累积膨胀，AI 看了规则仍按 best effort 执行，遗漏问题反复出现；用户失去对规则有效性的信任。

**Enforcement 层级**（从弱到强）：

| 层级 | 机制 | 例子 | 可靠性 |
|---|---|---|---|
| **L1** 规则文档 | AI 读 + 自觉遵守 | R7 / R9 现状 | ⭐ 看 AI 是否记得 + 不偷懒 |
| **L2** 结构化输出 | prompt 模板强制输出字段（如"列已扫元素表"） | audit prompt 强制 evidenceLevel | ⭐⭐ 结构化降漏项 |
| **L3** 脚本辅助 | AI 必须调用脚本拿客观信号 | [`scripts/visual-diff.py`](../scripts/visual-diff.py)（R8 v2） | ⭐⭐⭐ 客观 measurement |
| **L4** Pre-commit hook | hook 强制运行，不通过不能 commit | INFRA-F21 hex literal hook | ⭐⭐⭐⭐ 强制执行 |
| **L5** CI gate | CI 跑测试，不通过不能 merge | INFRA-F20 视觉 baseline（v0.2 roadmap） | ⭐⭐⭐⭐⭐ 全员强制 |

**机械触发**：任何"提议新规则 / 升级规则 / 加 trigger"时，**强制**回答 3 个问题：

1. **这条规则的 enforcement 层级是几？**（L1-L5 选一个，标注在规则正文）
2. **为什么不能升级到 L3+？**（如果选 L1）
   - "工程成本明显高于价值" → 可接受 L1
   - "客观可测但没人写工具" → **不接受 L1**，必须同时写工具或标 "vN 待升 L3"
3. **L3+ 工具是什么？放哪？**（如 `scripts/X.py` / pre-commit hook / CI job）

**类别强制**：

| 规则类别 | 最低 enforcement 层级 |
|---|---|
| **视觉 / 客观可测的规则**（视觉对比、数值阈值、文件存在性） | **L3+** |
| **用户行为 / 协作 / commit format** | **L4+** |
| **跨人协作 / 防错代码 merge** | **L5** |
| **AI 自我约束 / 元规则**（如本规则） | L1 可接受（无法机械约束 AI 思考过程） |

**违反检测**：

- ❌ 起草新规则时没声明 enforcement 层级 → 红灯，回 step 1
- ❌ 选 L1 但没回答"为什么不能升 L3+"理由 → 红灯
- ❌ 视觉 / 客观可测规则选 L1 → 红灯，必须 L3+

**实证案例（2026-05-13 R7 测试 close-loop）**：

| 规则 | 初版层级 | 实测问题 | 升级路径 |
|---|---|---|---|
| **R8 v1**（视觉自检 5 步 protocol） | L1（主观对比） | AI"跑了 5 步"但漏 caret 实心 / back arrow 背景 — 主观对比不可靠；AI 主观估"≥95% match"实际客观工具测出 35% diff | **R8 v2 → L3**：强制调用 `scripts/visual-diff.py` 拿客观 diff%；threshold 不通过强制修 |

→ 这次发现让用户洞察："不停加规则、加描述还是会有遗漏"——根因是 L1 文档无法约束 AI 执行。修正：本 trigger K 把"提议时必须想 enforcement 层级"机械化，stop 凭"写下来就放心"的反模式。

---

### 触发器 L：AI 不确定时必须 ask + 列举疑问点（不自作主张）

> **核心反模式**：AI 遇到 ambiguous case 时默认"我来想办法 / 我来决定"，而不是 stop + 列举 + ask user。后果：(a) AI 自己拍的板用户可能不同意 → 用户 push back → 反复绕弯；(b) "用户没说所以我就做" 等于 AI 越权 — 用户不该当 reviewer 兜底 AI 的默认决策。

**机械触发**：任务执行中任何"不确定的 case"必须 stop + 列举疑问点 + ask user：

- 多种实现路径之间不知道选哪个
- 边界 case 不在已定规则覆盖范围内
- upstream signal 模糊（如 R10 case C/D — unnamed Group / 散乱 layers）
- 用户原 brief 没明说但需要决策的细节（如 hover state 颜色 / loading 时长 / 等）
- 视觉 / 设计决策（尺寸 / 间距 / 字体 weight / 颜色变体）
- 实现路径决策（哪个 library / 哪个 pattern / 单 SVG vs 多 SVG）
- 业务逻辑决策（error handling / loading state / edge case）

**正确措辞**：

- ✅ "下面 N 个 case 不确定，列出来等你拍板：
  1. case A: option X 还是 option Y？
  2. case B: ...
  3. ..."
- ❌ "我先按 X 做，你看效果不对再说" — 这是甩锅给用户当 reviewer

**违反检测**：

- ❌ 任何"我先按 X 做"（自作主张默认值）无 user 拍板
- ❌ AI 写完代码后才发现要 ask — 应该写之前 ask
- ❌ 提议"recommend 方案 A，OK 吗？" 不算 ask — 应该列出 A/B/C 让用户选（除非已被规则覆盖）
- ✅ AI 提出问题清单 + 推荐方案 + 等用户拍板

**例外**（可不 ask）：

- 用户明确说"你看着办" / "随便"
- 决策完全可逆（如临时 PoC）+ 用户已表态接受 iteration
- 已被 meta-rules / conventions 规则覆盖的 case（不重复 ask）

**实证案例（2026-05-13 R7 测试 close-loop）**：

- v6: AI 没 ask 选 approximate inline SVG vs Figma 真 vector，自作主张 approximate → 用户 push back "还是不对"
- v7: AI 没 ask 选 composite 4-layer 还是 single SVG export，自作主张 composite → 用户 push back "应该是一个完整的 svg 图"
- **纠偏**：开始 R7 logo 任务时应该先 ask: "logo 是 Figma Component（按单元导出）还是散乱 layers（各自处理）？你 Figma 那边看到的 node name 是什么？"

跟 R10 D case "AI 不能替设计师决定" 同根，提升为元规则覆盖所有 ambiguity。

---

### 触发器 M：排期决策必须读 tracker §排期原则（防"按耗时 / 复杂度 / 成本最低排"反模式）

> **核心反模式**：plan owner 提排期 / 推荐先做哪个 / 决定 v0.X 含哪些时，默认按"这项小先做 / 那项大推后 / 成本最低先做"——结果主线工作被推后、自动化前置被忽略、项目目标进度滞后。
> **后果**：(a) 项目目标关键能力 ship 节点反复后移；(b) AI / dev / 设计师协作链路缺口（如 mockup-side 全 L1）长期不补；(c) 用户反复纠正"为什么先做小的"。

**机械触发**：任何含以下信号词的回应**必须**先读 [`docs/internal/retrospection/design-spec-canonical-alignment-tracker.md`](internal/retrospection/design-spec-canonical-alignment-tracker.md) §排期原则段：

- "先做哪个 / 排个顺序 / 该 v0.X 还是 v0.Y / 这项放哪"
- "next sprint / next 2 周做什么 / 这周做什么"
- "v0.X 里包含哪些 / v1.0 触发条件 / 该不该升 minor"
- "并行 / 串行 / 先 A 还是先 B"

**排期权重（按优先级，照搬 tracker §排期原则）**：

1. **项目目标对齐** — 直接落地 [`PROJECT_GOAL.md`](./PROJECT_GOAL.md) 5 能力之一 → 最高
2. **依赖解锁** — 后续多项工作的前置 → 高（哪怕单项工作量大）
3. **自动化 / 标准化** — L1 文本规则升 L3+ → 高（呼应 trigger K）
4. **快速可交付独立项** — 0 阻塞 + 短 cycle → 顺路填空，**不挤主线**

**违反检测**：

- ❌ 任何"这项小，先做 / 这项 20-30h 太大推后 / 成本最低先做"措辞（除非已确认在主线依赖路径外）
- ❌ 排期表里把项目目标能力相关项排在"顺路"位置
- ❌ 没读 tracker §排期原则就提排期
- ✅ 排期表每项必须能答上"对齐 PROJECT_GOAL 哪个能力 / unblock 哪些后续项"
- ✅ 命名遵 0.x semver：破坏性走 0.x.0 minor，patch 只 non-breaking，1.0 = 稳定承诺

**实证案例（2026-05-13 session 9）**：

| 错的 | 正解 |
|---|---|
| 把 Phase 6.3/6.4/6.6/6.7/6.8 + BRIDGE-005 + EXTRACT-006 (~50-75h) 整块叫 "v1.0 major"、与 0.x 语义脱节 → 用户纠正"应该叫 0.2.x 或 0.3" | 按 0.x semver 重排：破坏性分散到 v0.3/v0.4/v0.5 minor，1.0 留给稳定承诺；同时按项目目标 5 能力把 Tier 1-A schema 化前置到 v0.3.0、Tier 1-B mockup audit 落进 v0.5.0（能力 4 第一个 L3+ gate） |
| Tier 1-A translation schema 化（"基础设施"）一开始没排进 release 主线，只列在"评估"段 | tracker §排期原则权重 1+2+3 三票通过 → 必须主线，落 v0.3.0 |

→ 这次发现让用户明确："以项目目标为首、不能按复杂度耗时排"。本 trigger M 把这条原则机械化。

### 触发器 N：默认并行 Agent 执行独立任务（防"承诺并行实际串行"反模式）

> 用户多次提醒"能并行就用并行 Agent"，AI 每次 acknowledge 但下次又默认 sequential = 承诺没进 muscle memory = trigger A 的现象，N 是机制化对策。

#### 触发条件（机械判断，命中即跳到 §应对）

任务包含 **≥ 2 个可独立完成的子任务**（输出物互不依赖、输入参数独立）。典型场景：

- 写 ≥ 2 个独立文件（不同目录 / 不同主题 / 互不引用）
- 跑 ≥ 2 个独立 audit / probe / search
- 对 ≥ 2 个独立 frame / page / section 做相同操作
- 编辑 ≥ 2 个互不依赖的文档段落

**不适用**（必须串行）：

- 后一步依赖前一步的产物（如先 grep 找 ID，再用 ID 改文件）
- 涉及同一文件的多处编辑（容易冲突）
- 需要用户中途决策的步骤之间

#### 应对（产物外化为强制 trace）

任务起手前必须输出**并行决策声明**（一句话或简表）：

```
Parallelism plan:
- Track 1 (independent): <task A>  → Agent / Tool call X
- Track 2 (independent): <task B>  → Agent / Tool call Y
- Track 3 (sequential, depends on Track 1): <task C>
```

然后**真的**在单一 message 中并发触发多个 Agent / Tool call（Claude Code 支持 "multiple tool uses in a single message"——参考 Agent tool description "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently"）。

#### 反例（mandatory STOP 信号）

| ❌ AI 行为 | 触发的失败模式 |
|---|---|
| 任务有 2 个独立产物，AI 用 2 个 sequential message 各起 1 个 Agent | "默认串行" reflex 没被机制化对策拦下 |
| AI 写"我接下来跑 X，然后跑 Y"——本来 X / Y 互独立 | 没做 parallelism plan |
| 用户提醒"能并行吗" → AI 答"可以"但下一轮又串行 | 承诺没产物化（trigger A + N 双重命中）|
| AI 主动 acknowledge "下次会并行" 但没把规则落进 meta-rules | trigger B 联动失败 |

#### Acceptance

- 任何任务有 ≥2 个可独立子任务 → response 顶部必含 `Parallelism plan:` 段
- 该段必须列出每个 track 的输入 / 输出 / 是否 independent
- Independent tracks **必须**在单条 message 内并发触发，**不允许**串行 message
- 违例后用户提醒一次 → 立即写到本规则的实证段（如下方）作为新行

#### 与既有 trigger 关系

- 与 **trigger A** 联动（用户元提醒触发器）：N 是 A 的具体落地之一——把"能并行吗"这类元提醒变成机械化决策步骤
- 与 **trigger F** 联动（每次响应前最小自检）：F 是 checklist，N 是 checklist 中的一项"是否 ≥2 独立子任务？是 → parallelism plan"
- 与 **M35** 联动（mockup-conventions affordance trace）：两者同源——把隐性思考外化为可 audit 的产物

#### 实证

- **2026-05-18** Touch-Screen v8 session：用户提醒"为什么默认单 Agent，不能并行"——AI acknowledge 并临时切换并行（2 个 audit script agents 并发），但**之前 4 个独立任务**（M27/M28/M34 stub 化 + R1 stub + 2 SKILL refresh + meta-rules 更新）都是 sequential 单 message 跑的。用户元提醒触发本 trigger 立规则。**根因**：AI 默认 reflex 是"一个一个 tool call 跑"，没有把 parallelism 作为起手必做的产物化步骤。

### 触发器 O：Onboarding 知识 ≠ 实际产品状态（实测优先 / 产品真值优先）

> **核心规则**：**凡是 onboarding 知识（DS 文档 / 规范 / 历史 mockup / 团队约定 / memory / 上一 session context）与实际产品状态可能 diverge 的，永远 trust 后者 + 实测获取**。
>
> Onboarding 读文档构造心智模型，但模型可能 **意外正确 / 巧合一致 / 已 stale / intentional diverge**。Default trust 模型 → 命中错误概率几十%。

#### 触发条件（命中任一）

- 任务 = US-3（existing product iteration）
- 任务涉及 "迭代 / 修改 / 扩展" 已存在 component / page / feature
- 任务输出必须与产品实际 shipped 状态视觉/行为一致
- AI 写产出前要拍板任何"产品真值"（hex / API endpoint / prop value / config / schema / 命名 / 依赖版本）
- AI 起手准备引用 onboarding 中读过的"事实"作为决策依据（任何 "DS 规定是 X" / "上次 session 我们决定 X" / "memory 里说 X"）

#### 应对（mandatory 实测路径）

1. **凡涉及产品真值** → mandatory 实测：sibling probe / grep 实际代码 / `git show HEAD:<path>` 实际 commit / curl 实际 API / read 实际 config
2. 实测结果作为产出第一段固化（如 M21.2 的 Color Contract 范式 — 写代码前先写 contract）
3. 若实测 ≠ onboarding context，**产品真值优先**；onboarding 是 hint 不是 truth
4. divergence 显著时 → 同时记到 divergence log（DS 真源 vs 产品真值），让设计师 / 团队知情

#### 反模式

- ❌ "我刚读了 DS 文档，accent green = #2FB54E" → 直接用（没 sibling probe）
- ❌ "memory 里说 sync:full 已弃用" → 写 prompt 推荐用 sync:figma-library（没 grep 当前 repo 是否真删了 sync:full）
- ❌ "上 session 我们立了规则 X" → 直接套用（没核当前文件是否还有该规则）
- ❌ "spec 写了 cleanup --apply 默认 ON" → 实现时跳过各 mode 边界实测

#### 实例落地（本元规则的具体子条）

- **M21.2** Feature Iteration Color Contract（[`design-process.md`](./internal/design-process.md) 2026-05-27） — 颜色专项；US-3 任务写代码前先 Color Contract
- **触发器 I**（bug 诊断三层核对） — JSON / 数据真源核查不靠 grep/awk 命令输出
- **触发器 J**（加规则前 grep 查重） — 规则立项前实测真源是否已存在
- **触发器 G**（plan owner / executor 分工） — 真源 schema 写完作为 prompt 输入，不踢给 executor 现编
- **AGENTS.md §Sprint 收尾 Self-Audit 协议** — sprint shipped 后 mandatory 跑 spec gap / 实现 bug / doc lag 实测扫描，主动暴露给 user

#### 实证案例

- **2026-05-27 PMPP-955** Recording Control mockup (US-3 任务): onboarding 读 TVU DS 文档 → 用 `#30B54E` (DS 绿) 作 accent → 产品实际 `#5DC045` → user review 抓出返工。根因：跳过 M21 Sibling Visual Contract Color palette probe，把 DS onboarding context 默认推产品真值。立 M21.2 + 本触发器 O。
- **2026-05-27 INFRA-F35** sprint shipped 后：spec 写"cleanup --apply 默认 ON" → 实现没考虑无 `--with-extract` 时 published manifest stale 风险 → user audit 抓出。根因：sprint spec 没实测各 mode 边界，"按 spec ship 完" 默认认为 done。立 Sprint 收尾 Self-Audit 协议。
- **2026-05-26** Calender → Calendar typo: onboarding 读 manifest 找 `icon/Time/Calendar` 没命中 → 默认 "不存在"。根因：name-search absent fallacy，没实测 raw 文件是否有别名 (`Calender` typo)。立 memory `feedback_name-search-absent-fallacy`。
- **2026-05-26** Figma description "空" 误判：grep description="" 字段 → 默认 "设计师未填"。实际 description 在 Component Set 根而非单 variant。同 name-search fallacy 形态。

#### 子面：提取/派生产物 ≠ 上游真源（2026-06-03 INFRA-F36 实证）

> **核心**：`figma-data/raw|normalized/*` 等**提取/归一化产物是有损变换 + 可能自带 extract bug**，不是 Figma 真实结构的镜像。把它当真源反推上游 = 触发器 O 的一种（trust 派生表征而非源真值）。

- **触发条件**（补充）：AI 推断 **Figma 真实结构 / 组件 set 关系 / 节点属性（文本/颜色/层级）** 或 **pipeline 真实行为** 时，读提取产物 / 中间产物 / 自己对机制的假设模型当依据。
- **应对**：
  1. 推断**上游结构** → 查 **live Figma**（MCP `get_metadata` / `get_design_context` / `get_variable_defs`，FIGMA_AS_SOURCE_OF_TRUTH 第 0 步），**或**读**生成该产物的 extract/normalize 源码**搞清变换逻辑。禁止把产物长相直接当 Figma 真相。
  2. 修 **pipeline / 机制 bug** → dry-run / 自写校验脚本验证的是**你的假设模型**（可能错），必须跑**真实 pipeline 看 observable effect**（count / render 真变了吗）才算坐实根因。
  3. **纯结构操作（dedup / 清理）用离线 surgical**（删文件 + 按 key 过滤 index/manifest 数组，零内容 churn），不要拿 `sync:figma-library --with-extract` 当锤子（会顺带拉 fresh 内容 drift 与结构改动纠缠）。
- **反模式**：
  - ❌ 读 raw `componentSetId:null` 文件 → 推 "Figma 没 combine 成 set"（实际 extract 把 set 变体拍平成 standalone 的 artifact）
  - ❌ 看 extractedAt 时间戳猜 "stale 遗留" → 写错根因 commit（实际每次 extract 重复生成）
  - ❌ dry-run 命中预期 → 当根因坐实（dry-run 只复现了你的错误假设模型）
- **实证（一个 session 连犯 3 次，用户两次挑战才纠正）**：
  - 误判 1：raw 610 散装 → "Select 没 combine 成 set"；live Figma 实证是 COMPONENT_SET（144×2 变体）。
  - 误判 2：4044 = "stale + orphan-purge 熔断卡住"；读 extract 源码才知是 `collectComponents` 每次重复收集。
  - 误判 3：commit `7b930683` dry-run "命中 4044" 假性通过；full sync `extracted 4729`（没清）才戳破。
  - 复盘 [`retrospection/2026-06-03-infra-f36-misdiagnosis-and-derived-data-lesson.md`](./internal/retrospection/2026-06-03-infra-f36-misdiagnosis-and-derived-data-lesson.md)。

---

### 触发器 P：产品设计 / PRD / UX 交付起手 → 一次性扫齐 open questions（前置 ask gate，交付物零未决项）

> **核心规则**：任何 **产品设计 / PRD / UX 交付** 任务起手，AI 必须在写任何交付草稿（PRD / UX 卡 / mockup frame / spec / handoff）之前，**把所有 open questions 一次性扫齐，批量发问 + gate 等用户拍板**。交付物里**禁止**残留 open questions / TBD / 待 confirm / "待 PM 拍板" 等未决项——这些只能去 Jira 评论 / Slack / 1:1 邮件等讨论区，不准贴上 Figma 或进任何交付卡。
>
> 这是 [触发器 L](#触发器-lai-不确定时必须-ask--列举疑问点不自作主张) 的**前置式特化**：L 是反应式（流程中途遇到不确定 case 才 ask），P 是前置式（起手就扫齐 + gate，不让未决项漏进契约产物）。

#### 触发条件（命中任一）

- 任务 = 产品设计 / PRD / feature 设计 / UX 交付说明 / mockup（含 Path A 与产品端 claude.ai Figma MCP 路径）
- 任务要产出 PRD card / PRD frame / M23 UX 交付卡 / spec card / handoff doc
- brief 含「设计 X feature」「画个 mockup」「写 PRD」「补 UX 说明」等信号
- 任务经由产品端路径进来（SaaS dashboard / MicroApps / claude.ai 通用 figma-use skill）——**此路径常跳过 mockup/design-process 链路加载，触发器层是唯一兜底**

#### 应对（mandatory 前置 gate）

1. 起手即扫齐所有 open questions，用 [`design-process.md` §No Open Questions in Deliverables](./internal/design-process.md#no-open-questions-in-deliverables2026-06-02-新增) 的批量发问措辞：

   ```
   开画前还要 confirm 这 N 个问题（一句话答即可）：
   1. [Q1]?
   2. [Q2]?
   ...
   等你 ack 完所有问题，再起草稿。
   ```

2. ⏸ **Gate**：用户拍板每个问题后，AI 才能进入草稿。**禁止**用户没拍板就写 "TBD" 绕过。
3. 交付前自查交付物（含 Figma frame 内文字）无 wording 黑名单：`TBD` / `待 confirm` / `待 PM 拍板` / `TODO` / 单字 `?` / `(?)` / "Open questions" / "可能要 X" / "需进一步讨论"。
4. 真有 dev/PM 待办追踪需求 → 只能放 handoff doc 末尾独立 `## Open scope items` 段或 Jira/Slack，与契约段语义隔离。

#### 反模式

- ❌ 把「待 confirm 的 N 个问题」section 或注释直接贴到 Figma frame / PRD card 上（用户原话：「PRD 里不要包含开放性问题，分析需求时让用户回答」）
- ❌ 草稿写到一半才发现要 ask → 应在起手 Step A 一次性扫齐
- ❌ 产品端任务起手只加载通用 figma-use skill 就开画，没走 open-questions gate（路径漏加载 ≠ 规则不适用）

#### 实证案例

- **2026-06-01 V4-1865**：v4 Hotspot UX 卡 §7 含 4 条 unresolved（bonding 行为 / SSID 冲突 / USB 兼容 list / toast 文案）+ v6 §Mode transitions 末尾藏 "Toast wording TBD with PM"；用户 walkthrough v7 抓「PRD 里不要包含开放性问题」。当时只回流成 design-process.md prose（§No Open Questions），**未建触发器** → 2026-06-08 用户再次指出「我记得写过类似规则，不知道为什么没生效」。根因：规则只活在 design-process.md，无触发器层点火 + 产品端路径常跳过加载。本触发器 P 即此回流，把前置 gate 提升到任务 START 的机械触发层。

---

### 触发器 Q：规则优先于范本（照抄范本前先用规则真源校验，防继承 pre-规则范本债务）

> **核心规则**：任何"找最近同类范本对齐现状"的起手动作（开建 PRD / UX 卡 / mockup / spec / 任何有规则真源管辖的契约产物），**范本 ≠ 规则真源**。当范本建于某规则回流**之前**，照抄它的可量化属性会把违规债务一并继承。必须**先用规则真源校验范本**：有规则管的属性以规则值为准，范本仅用于对齐规则未管的项。
>
> 这是 §1 [真源单一](#1-真源单一) 在 authoring 层的应用——范本是派生实例、规则才是真源；拿派生实例当模板会造成"加了规则却没生效"（新产物继承的是旧范本的 pre-规则状态）。

#### 触发条件（命中任一）

- 起手"参考最近同类 X 范本"/"dump 上一个同类当模板"/"inspect the file, match what's there"（含 figma-use 的对齐现状要求）
- 要产出受规则真源管辖的契约产物（PRD / UX 交付卡 / mockup / spec / 注释卡）
- 范本建于相关规则回流之前（无法确认时一律按 pre-规则处理）

#### 应对（mandatory）

1. **先 jump-read 规则真源**建立"该长什么样"的标准；范本仅用于对齐规则未管的项（视觉 token / 结构 / 组件 / 命名），**不照抄有规则管的可量化属性**（间距 / 行距 / 层级 / 字号 / opacity）。
2. **有规则管的属性用规则值**；范本实测值与规则冲突时**以规则为准**。
3. **建完即跑该域机器闸**（不等用户指出）。

#### 反模式

- ❌ 开建前 dump 最近同类范本的可量化属性当"范式"直接照抄，未先用规则真源校验
- ❌ 以"范本就是这么做的"为由跳过规则真源 jump-read
- ❌ 范本建于规则回流前却假设它已合规

#### 实证案例（落地：mockup 域）

- **2026-06-23 V4-1827**：催生本规则的 V4-1864 PRD 卡建于 0608（pre-M23.14 双语行距规则），自身从未按规则修正、仍是统一行距。画 V4-1827 NDI PRD 卡时 AI 照抄该范本 → 继承拥挤间距 + meta 行混入 + 段名无层级，用户连续纠正。mockup 域具体落地见 [`mockup-conventions.md` §M23 卡族 + §M23.14](./internal/mockup-conventions.md) + bilingual-spacing 机器闸（`audit:mockup-bilingual-spacing`）。原 mockup 域 §M23.16（2026-06-25 B-P6 升格至此）。

---

## 7. 元说明

- 本文件是元规则真源——具体规则（如 prop-aliases、divergences、axis-implementation-map）是本元规则的**实例落地**
- 修改本文件需谨慎——所有项目规则的最高约束都在这
- 任何 AI 工具的入口（CLAUDE.md / 未来的 GEMINI.md / CURSOR.md 等）应仅登记**该工具自己特有的工程细节**，元规则与角色行为约束统一指向本文件

---

## 附录：本规则的实证沉淀（避免重犯）

| 实例 | 违反的反模式 / 触发器 | 正解 |
|---|---|---|
| 推荐"硬编码 darkTheme 全局别名 + TODO" | #1 (硬编码项目级规则) | 先登记到 prop-aliases.md，工具读它 |
| audit prompt 列 8 类 verdict 没加溯源字段 | #3 (to-do list 思维) | 先设计 evidenceLevel schema |
| 把 DateTime 作为特例处理 | #2 (打补丁不抽象) | 抽象成 axis-implementation-map 拓扑映射机制 |
| audit 只查 CSS class 没考虑 prop / palette | #5 (没问扩展时改哪里) | 4 层级查找框架（CSS class / prop / palette / 拓扑映射） |
| 单日产出 5 个结构性升级，没主动写复盘 | 触发器 D (阶段完成判定模糊) | 满足任一硬条件（≥ 3 个真源 .md 改 / ≥ 5 阶段 / 完成 v2 子任务）→ 必须写复盘 |
| 用户连续 5 次主动提醒"该做但漏做的事" | 触发器 A (没识别元提醒信号) | 信号词列表机械检测；信号出现 → 停下当前任务，先回应元层面 |
| 写"M1 后再加规则"用"避免越界"做防御借口 | 触发器 E (用户决策疲劳后还推方案) | 真越界=反复改同一文件；加新真源文件=机制化落地，不算越界 |
| Round 1 plan-only prompt 让 executor 设计 axis-implementation-map.json schema + 写实例草稿 | 触发器 G (踢任务) + 反模式 #3 (to-do list 思维) | 真源文件 plan owner 自己写完作为 prompt 输入；executor 只做"按已定 schema 扩展执行" |
| 多次推荐"今天到这里停"作为对话节点，把 AI 包进"我们都累了" | 触发器 H (投射人类疲劳) | AI 不累；判断标准是 context window + 任务输入清晰度 + 用户精力，不是时间 |
| Round 3 prompt 把 grep/awk 命令缺陷误判为数据 bug，让 executor 修 Tooltip / Select 不存在的"消失" | 触发器 I (没做 JSON 真源核查) | 用 `node -e "JSON.parse(...)"` 核查 JSON 真源；命令缺陷不等于数据 bug |
| 用户说"记住 Figma plan = Pro" → 直接 Save 到 Claude Code 工具级 memory，没问"其它 AI 工具是否也需要这条约束" → Codex / Gemini / Cursor 等其它工具看不到 → 用户主动指出 | 反模式 #1 (硬编码项目级规则到工具级机制) + 触发器 B 子规则缺失 | 保存事实前机械跑"作用域"判断：跨工具约束 → 真源 .md（AGENTS.md "项目约束" 段）；工具人格 → memory。详见触发器 B 子规则"保存事实前问作用域" |
| 状态汇总把"plan 决策落地"和"代码执行落地"挤进同一表格 cell（如 "T3 先 → T2 样板换 Badge/Tooltip/Select \| ✅ 完成 \| commit 0fb0d29"），让用户误以为 T3 已执行——实际只改了 v2 plan 文字 | 反模式 #3 (to-do list 思维 / 没产出契约) | 状态汇总**强制分两 section**：(1) Plan-level（文档/决策落地，commit X）；(2) Execution-level（代码/脚本/工件落地，commit Y / diff Z 行）。两层不能混。每条状态必须用动词区分——"修了 plan / 改了文档" vs "执行了 / 跑了 / 改了代码" |
| MicroApps Console mockup session 中 AI 被问"是否加 M21 库消费规则" → 直接 propose 4 条新规则，没先 grep `mockup-conventions.md` —— 实际 M1（库 key 过滤 + 同名旧库陷阱警告）+ M10（不写 hex literal）+ 真源/优先级段已 100% 覆盖 | 触发器 J (加规则前没查重) | 任何新规则提议前必须 grep 至少 3 个关键词、列出查的文件 + 命中情况，证据放在回复里。无命中才能起草。 |
| MicroApps Console Health Indicator 选了 TVU UX Design System `icon/Message/warning 2`（fill 风格），与 Success 1 + Error 3 的 line 风格不一致 —— 凭"颜色对"选 variant，没核对图标轮廓 | 反模式 #2 (打补丁不抽象) + M2 acceptance criteria (convenience over discipline) | 选库 component variant 时必须**渲染对比**——一次 import 全部候选放一行 32px 实例截图，看清 line vs fill / 几何形状一致性后再确定。颜色绑色变量是必要条件不是充分条件。 |
| 把 Phase 6.3/6.4/6.6/6.7/6.8 + BRIDGE-005 + EXTRACT-006（~50-75h）整块叫 "v1.0 major"，与 0.x semver 脱节；Tier 1-A schema 化只列"评估"段，没排进 release 主线 | 触发器 M (排期决策反模式 — "按 1.0 大变更" 思维 + "基础设施不算主线" 思维) | 0.x semver：破坏性走 0.x.0 minor，1.0 = 稳定承诺；Tier 1-A 因为对齐能力 5 + unblock 多项 → 必须主线（v0.3.0）；按 tracker §排期原则的权重 1+2+3 排，不按耗时大小 |
| PMPP-955 Recording Control mockup (US-3) onboarding 读 TVU DS 文档 → 直接用 `#30B54E` (DS 绿) 作 accent → 产品实际 `#5DC045` → user review 抓出返工 | 触发器 O (Onboarding 知识 ≠ 实际产品状态) + M21 (Sibling Visual Contract probe 缺位) | US-3 任务写代码前先做 sibling probe + 固化 Color Contract（M21.2 范式）；产品真值优先于 DS onboarding context |
| INFRA-F35 sprint shipped 后 AI 自报 "complete"，user 追问 audit 才暴露 5 个真问题（cleanup --apply 无 extract 不安全 / AGENTS.md stale / Step 10/11 silent failure / sample 5 太小 / backlog 缺 shipped 标识） | 触发器 O (按 spec ship 完即 done 默认 trust spec 心智模型，没实测 spec 边界) | sprint 收尾 mandatory 跑 3 类 audit (spec gap / 实现 bug / doc lag)；AGENTS.md §Sprint 收尾 Self-Audit 协议机制化 |
| INFRA-F36 一个 session 连犯 3 次：读 raw `componentSetId:null` 文件 → 推 "Select 没 combine 成 set"（实际是 COMPONENT_SET，extract 拍平 artifact）；看 extractedAt 猜 "stale 遗留" 写错根因 commit（实际每次 extract 重复收集）；dry-run "命中 4044" 假性通过（只复现了错误假设模型，full sync `extracted 4729` 才戳破没清） | 触发器 O §派生产物子面 (提取产物当上游真源反推 + dry-run 当真实行为) | 推断上游结构查 live Figma 或读 extract 源码；机制 bug 看真实 pipeline observable effect 非 dry-run；纯结构清理用离线 surgical 不用 full sync。复盘 2026-06-03-infra-f36-misdiagnosis |