# Design Spec — 规则注册表 + 任务路由 + 分批补闸（确定性规则触发机制）

> **日期**：2026-06-12 · **状态**：⚠️ **owner reframe 待重审（2026-06-12）——可能本末倒置，下个 session 先决断要不要建**
> **量级**：单 owner + AI 代理 · **风险约束**：仓库高度交叉引用 + 多 audit 闸 + onboarding 链 + memory 锚点，**本方案纯增量、不搬任何规则文件**。

> 🛑 **owner reframe（2026-06-12，最高优先级）**：「重要的是**如何做**，不是**如何约定**。」建注册表本身是「关于约定的约定」，可能本末倒置。**执行优先的正解** = 把检查**内嵌进执行器**（design-review 的 agent/skill 自带完整 checklist 一跑全跑；能机检的上 gate），而非"建注册表把规则路由给 AI、寄望它去查"——"查文档式约定"正是会漏的那种。**下个 session 必须先决断**：注册表到底要不要建？还是直接做"comprehensive review 执行器 + 机器 gate"。本 spec 下文（块 1-5 / P1）在此 reframe 下需重审，registry 若留最多是"喂执行器的共享定义"非主角。

---

## 1. 问题（owner 实证确认的三根源）

全仓治理规则散在 `AGENTS.md` / `meta-rules.md` / `design-process.md` / `mockup-conventions.md` / `code-conventions.md`，但「给定一个任务，能否精准/快捷地按规则完成」不可靠。owner 选定三个并存根源：

1. **AI 没加载/没想起该规则** —— 该任务该跑哪几条靠 AI 自己记/判，就漏。
2. **规则本身模糊** —— "应保持一致"这类不可执行，AI/人都不知道具体怎么算过。
3. **没机器闸拦不住** —— 规则停在 L1 自律层，AI 忘了/犯了也没脚本/CI 拦。

→ 同任务不同 session/AI 出不同结果。

**对标锚点**：成熟 DS（Polaris/Ant/Carbon）共同答案 = **机器执行是骨架**（ESLint plugin + CI gate + codemod，不靠人记）。TVU 特殊点：**AI 是主要执行者**，所以除机器闸外，还需一个纯人类 DS 不需要的「**任务→规则集**确定性路由」。

## 2. 目标 / 非目标

**目标**
- 给定任务类型 → 确定性吐出**该任务适用的精确规则集 + 流程 + 闸**（治根源 1）。
- 每条规则的 `enforcement 层级 + 由哪个闸管` 显式、可 audit（可见性）。
- 用可见的 gap 列**驱动按价值把高价值 L1 规则升 L3+ 机器闸**（治根源 3）。
- 建表时**强制每条写成可测判定句**，写不出的标记待重写（治根源 2）。
- **零破坏**现有规则文档 / onboarding / memory / audit（纯增量索引层）。

**非目标（YAGNI / 明确不做）**
- ❌ 不搬动/重排规则文件（wholesale reorg 已否——错杠杆、高风险）。
- ❌ 不给每条规则都建闸（天生靠判断的留 L1，但**显式标注**为有意选择）。
- ❌ 不替换规则正文（注册表只索引；正文留在各自 `.md` 原处）。

## 3. 设计（5 块，复用 component-affordances 已验证范式：JSON SoT + 生成视图 + audit）

### 块 1 — `docs/internal/rule-registry.json`（SoT）
每条治理规则（M / R / 触发器 / 硬规则）一条索引项，**不复制正文**：
```jsonc
{
  "id": "M35",
  "category": "M",                          // M | R | trigger | hard-rule
  "source": "docs/internal/mockup-conventions.md#m35",  // 正文原处，不动
  "title": "Affordance-Category Search Discipline",
  "fires_on": ["mockup", "code"],           // 任务类型枚举（见块 2）
  "statement": "新增/借用基础语义元素前必须按 affordance 分类 + 同义词扫描 + 3 行 trace",  // 可测判定句
  "enforcement": "L1",                       // L1-L5（meta-rules 触发器 K）
  "gate": "none",                            // none | audit:xxx | pre-commit | prepublishOnly | CI
  "gap": "L1 自律,无机器闸"                   // 诚实标执行缺口（none 时必填理由）
}
```

### 块 2 — 任务路由（从注册表派生，治根源 1）
**任务类型枚举**（对齐现有三套分类，不另造）：
`mockup-US1/2` · `mockup-US3` · `mockup-US5` · `mockup-US5.S` · `mockup-US6` · `mockup-US7` · `code-S1` · `code-S2` · `code-S3` · `code-S4` · `sync` · `migration` · `audit` · `infra` · `release`
- `generate:rule-registry` 按 `fires_on` 分组 → 产 `docs/internal/task-routing.md`（每任务类型："起手加载这几条规则 + 走哪条流程 + 哪些闸"）。
- 可选 CLI `pnpm rules-for <task-type>`（P1 末或 P2）。
- AI 起手判完档（design-process 起手自判决策树）→ 加载对应路由输出 = **确定性就那几条**。

### 块 3 — 补闸（按价值分批，治根源 3）
注册表 `gate` 列把**所有 L1-无闸规则一次性暴露**。高价值升 L3+（种子 = 本 session D-findings：D3 prepublishOnly / D4 交互态 linter / icon guard，+ Q3-Q6）；天生判断类留 L1 但 `gap` 写明理由。

### 块 4 — 可执行性 pass（治根源 2）
建表时每条 `statement` 必须是可测判定句；写不出可测句 → 该规则进"待重写"清单（Phase 3）。

### 块 5 — 防破坏 + 防注册表自漂
- 注册表全新增、规则原地不动 → 零 cross-ref/onboarding/memory 破坏。
- onboarding 链（STATUS L-ref / AGENTS）加一指针："判完任务类型 → 加载 task-routing 对应段"。
- 新 `audit:rule-registry`（挂 prepublishOnly + pre-commit 条件）核：① 每条 M/R/触发器/硬规则都有注册项 ② 每个 `gate` 名真实存在（防编造闸）③ `statement` 非空 ④ `enforcement:L1` 必带 `gap` 理由。防注册表 stale（同 `audit:component-affordances` 法）。

## 4. 分批落（每 Phase 独立交付价值）

| Phase | 内容 | 交付 |
|---|---|---|
| **P1 框架** | schema + 从现有规则填充 + `generate:rule-registry`（+ task-routing.md）+ `audit:rule-registry` + onboarding 指针 | 立刻拿到**确定性路由 + 全量执行 gap 可见性** |
| **P2 补闸** | 按 `gap` 列 + D-findings + Q3-Q6 排序，把高价值 L1→L3+ | 关键规则机器兜底 |
| **P3 重写** | 把 P1 标记的模糊规则改成可测句 | 消除歧义 |

P1 是 P2/P3 的前置依赖（没注册表无法排闸优先级）。**填充量大但机械 → P1 可 subagent 辅助批量填**。

## 5. 风险 / 缓解
- 注册表漂 → `audit:rule-registry` 闸。
- 注册表变新"热文档" → 机器可读 JSON + 生成视图（非手写散文）+ audit 兜底（component-affordances 同款，已证可行）。
- 编造"有闸" → audit 核 `gate` 名真实存在。
- 填充工作量 → 机械、可 subagent 并行；P1 可先填高频任务规则再补全。

## 6. 成功标准
- `pnpm rules-for mockup-US5.S` 返回精确规则集。
- `audit:rule-registry` 绿 = 每条规则有索引、每个闸真实、L1 都有理由。
- 执行 gap 成为**单一可查清单**（取代 ad-hoc 撞）。
- 未来 review 对**注册表**比对，不靠记忆。

## 7. 关联
- 执行层级真源：`meta-rules.md` 触发器 K（L1-L5）。
- 范式范本：`component-affordances.json` + `audit:component-affordances`。
- 种子 gap：`consistency-dimensions-audit-2026-06-12.md`（D1-D15）+ 6 条 Q quick-fix。
- 任务分类真源：`design-process.md` US-* 起手自判 + `code-conventions.md` 场景 1-4 + `AGENTS.md` task-type 矩阵。