# TRIG-03 设计 pipeline 编排器工具无关追踪 — 设计 Spec

- **日期**：2026-07-17
- **状态**：**DEFERRED（spec-only，超出 MVP 波3「整理不扩增」范畴，待 owner 排期）**
- **归属**：backlog [[INFRA-F68]] 补测扩展 · L7 治理 · TRIG-03（`docs/internal/backlog.md` line 153）。轨道 B（流程 / 多工具采纳 · 质量与工具解耦）。
- **前置阅读**：`docs/internal/backlog.md`（轨道 B 主线段 line 62-66 + TRIG-03 行）· `skills/tvu-design-pipeline/SKILL.md`（被绑 Claude Code 的编排器本体）· `docs/superpowers/specs/2026-07-09-pillar4-upstream-gate-design.md`（上游 gate 工具无关范式，本 spec 直接复用其架构）。

> **本 spec 只出设计、不实现任何代码 / 不改脚本 / hook / skill 本体。** 存档目的 = 把 TRIG-03 的问题与候选方案写清楚，标 DEFERRED，等 owner 判定值不值得启动。TRIG-03 属"建新机制"，超出当前 MVP 波3 的整理范畴，故不落地。

---

## 0. 一句话问题

设计 pipeline 编排器（`tvu-design-pipeline` skill）把"完整设计全流程的推进"绑死在 Claude Code 上：终点（handoff / mockup 保真）已有工具无关的 git gate，上游阶段内容（discovery / IA / persona / 数据可行性）已被 `upstream-gate` skill 的 artifact+validator 部分覆盖，但**编排流程本身的阶段推进追踪 + 阶段间 handoff 状态，没有任何工具无关落点**——同事在 Codex / claude.ai 里跑同一条流程时，既没有编排指引，也没有"走到哪一步 / 上一步是否交接完整"的可核证据。

---

## 1. 问题：编排绑单一工具的具体表现 + 为何是轨道 B 命门

### 1.1 编排器今天怎么绑死 Claude Code

`tvu-design-pipeline` 是一个 8 阶段编排器（Intake → 用户体验地图 → IA 验证 → 全状态 mockup → UX 交付层 → 设计走查+角色测试 → PRD+Jira 同步 → Handoff Gate），它靠两个 Claude-Code-only 机制存在：

1. **skill 本体只在 Claude Code 里可被 `Skill` 工具唤醒**（唤醒词 `@TVU 设计全流程` / `走全套` / `full design pass`）。skill 定位是"trigger + 编排指路"，把 8 阶段物化成 TodoWrite checklist、串起每阶段对应的子 skill。这套编排知识**只活在 Claude Code 的 skill 加载 + TodoWrite 里**。
2. **触发注入靠 `.claude/hooks/detect-figma-task.sh`**（UserPromptSubmit hook），它探测 Figma URL + 意图分流、注入起手协议。这是纯 Claude Code hook 机制，Codex / claude.ai 完全吃不到。

后果：同事换工具（Codex CLI / claude.ai 网页）做同一条"完整用户流程全状态设计"时——

- **拿不到编排指引**：没有"这条流程该分哪 8 步、每步该调什么、每步产出什么"的可移植说明（编排知识锁在 CC skill 正文里）。
- **拿不到推进追踪**：没有任何工具无关的记录说明"这个 feature 的设计流程现在走到第几阶段 / 哪些阶段已交付 / 阶段之间交接了什么"。跑到一半换 session、换人、换工具，状态全丢。
- **拿不到阶段间 handoff 校验**：阶段 N 的产出是否满足阶段 N+1 的输入前提（如 IA 验证是否 0 🔴 才进 mockup），只在 CC skill 的 checkpoint 提示里存在，无工具无关落点固化。

### 1.2 为何是轨道 B 命门

轨道 B 主线（backlog line 62-66）：**今天几乎所有强制都活在 Claude Code hooks/skills 里 → 同事用 Codex/claude.ai 吃不到任何 gate。轨道 B 的命门 = 把强制从"单一工具 hook"搬到工具无关落点（git hook / CI / 消费仓库 scaffold）。**

编排器是这条命门的一个尚未被覆盖的典型实例：它是"一条多阶段流程该怎么走 + 走到哪了"的权威，却 100% 绑 CC。轨道 B 已有的兄弟项（F61 代码网 / F62 mockup 设计网 / F63 每工具薄适配器 + upstream-gate 支柱④）分别解耦了"代码 gate / mockup 终点 gate / 上游内容 gate"，唯独**编排推进本身**这一层还没被搬到工具无关落点——这正是 TRIG-03 要补的缺口。

---

## 2. 现状盘点：哪些阶段已有工具无关落点，哪些没有

把 8 阶段 pipeline 按"是否已有工具无关追踪/强制"分三段盘点（这是设计 TRIG-03 的事实基础，避免重复造已存在的机制）：

| pipeline 阶段 | 工具无关落点现状 | 覆盖它的机制 |
|---|---|---|
| **上游内容**（阶段 1-2：用户体验地图 / IA / persona / 数据可行性） | **已部分覆盖** | `upstream-gate` skill 产出 `docs/specs/upstream-gate.<feature>.md`（schema 化 artifact）+ `validate-upstream-gate.mjs`（便携 node validator，随 DS 包发）+ PR/CI chokepoint 机校确定层 + owner review 判断层。artifact + validator 是工具无关的；三层适配器（CC skill / Codex file-prompt / claude.ai Project-Instructions）各自把生产者导进同一 artifact。 |
| **中段编排推进**（编排流程本身 + 阶段间 handoff 状态：走到第几阶段 / 上一阶段是否交接完整 / 下一阶段前提是否满足） | **❌ 无工具无关落点** ← **这就是 TRIG-03 缺口** | 只有 CC skill 的 TodoWrite checklist + checkpoint 截图提示（CC-only，session/工具 一换即丢）。 |
| **终点保真**（阶段 3-7：mockup 保真 / handoff gate / delivery 证据） | **已覆盖** | mockup conformance chokepoint（[[INFRA-F62]]）——handoff 进消费仓库 git，chokepoint 挂消费仓库 commit/PR，`audit:mockup-conformance` + handoff-evidence 校 touched-node，工具无关（git teeth）。 |

**关键结论**：TRIG-03 的缺口是**夹在已覆盖的上游（upstream-gate）与已覆盖的终点（mockup git gate）之间的"编排中段"**——即"这条多阶段流程作为一个整体，推进到哪、阶段间交接是否完整"的追踪。上游 gate 管"单阶段内容质量"，终点 gate 管"最终交付物保真"，都不管"流程编排本身的推进状态"。这一层今天只存在于 CC skill 的运行时记忆里。

---

## 3. 建议方案（方向性，不写代码）

核心思路（与 upstream-gate 支柱④ 同构）：**编排状态从"CC skill 的运行时 TodoWrite"外化成一份工具无关的阶段状态制品（stage-state artifact），落进可控 chokepoint，由便携 validator 机校确定层、owner review 判断层。** 编排知识（8 阶段定义 + 阶段间前提）从 CC skill 正文抽成工具无关文档，各工具薄适配器共同引用。

下面给 3 个候选路线，从轻到重，各标 enforcement 层级（参照 `docs/meta-rules.md` 触发器 K 的 L1-L5）。三者可叠加（A 是 B/C 的基座）。

### 路线 A — 编排定义 + 每工具薄适配器（文档层）

把"8 阶段该怎么走 + 阶段间前提"从 `tvu-design-pipeline` CC skill 正文抽成一份**工具无关的编排定义文档**（如 `docs/internal/design-pipeline-orchestration.md`），CC skill / Codex file-prompt / claude.ai Project-Instructions 三个薄适配器都**指向同一份定义**（复用 upstream-gate 支柱③ 已建的三层适配器分发轨道：DS 包 `scripts/` + `templates/consumer-product/` + claude-design-bundle）。

- **解决**：编排知识不再锁死 CC——任何工具的使用者都能拿到同一份"这条流程分哪几步、每步产出什么"的可移植说明。
- **不解决**：推进状态的追踪与强制（仍靠 AI 自觉按文档走）。
- **enforcement 层级**：**L1（文档）+ L2（Codex 结构化 prompt 强制输出阶段字段）**。诚实边界：无机器 teeth，只消除"编排知识工具锁定"。

### 路线 B — 阶段状态 artifact + validator + PR/CI chokepoint（制品层，**推荐主线**）

产出一份工具无关的 **pipeline stage-state artifact**（如 `docs/specs/pipeline-state.<feature>.md`，或直接把阶段推进字段并入既有 `upstream-gate.<feature>.md` 复用其分发+校验链路），front-matter 记录：每阶段 done/skip/pending 状态、阶段产出物的引用（Figma node / handoff 路径 / spec 锚点）、阶段间 handoff 是否满足下一阶段前提（如 `ia_gate: {red_count: 0}` 才允许 `mockup` 阶段置 done）。便携 validator（node 脚本，随 DS 包发，模仿 `validate-upstream-gate.mjs`）机校**确定层**：阶段顺序合法、必填产出引用存在（锚点/路径解析）、handoff 前提条件满足；**判断层**（每阶段产出质量）留 owner PR review。artifact 落进 chokepoint repo（DS Gitea / 采纳了 gate 的消费仓库），PR/CI 跑 validator。

- **解决**：推进状态外化成可核制品，工具无关；换工具/换 session/换人，状态不丢且可机校交接完整性；直接复用 upstream-gate 已验证的"双层（确定层机校 + 判断层 owner review）防假闸"范式，规避"查文本存在性即过"的假闸反模式。
- **enforcement 层级**：**混合 —— 确定层 L3（validator 脚本）+ L5（CI gate 挂 chokepoint）；判断层 L1（owner review，无法机校"阶段产出质量"）**。这是最稳健的路线（与上游 gate 一致的工具无关强度）。

### 路线 C — 消费仓库 scaffold git ledger + git hook（git 层）

在消费仓库 scaffold（[[INFRA-F62]] 已建的消费仓库 chokepoint 分发轨道）里增加一份 git-tracked 的阶段推进 ledger，git hook（pre-commit / pre-push）在每次提交时校验 ledger 的阶段顺序合法性 + handoff 证据存在。骑 F62 已建的"mockup handoff 进消费仓库 git → chokepoint 挂消费仓库 commit/PR"落点。

- **解决**：把编排推进校验直接钉在 git 提交动作上，工具无关强度最高（git teeth）；与 F62 终点 gate 共用同一 chokepoint。
- **enforcement 层级**：**L4（消费仓库 git pre-commit/pre-push hook）**。
- **残余缺口（诚实承认，同 F62）**：若某次设计纯 Figma 全程不碰 git，机械 chokepoint 落空，靠 owner design-walkthrough 兜底。裸 AI 会话（无落点，如 informal claude.ai）无法机械 gate——同 upstream-gate §5 诚实边界。

### 路线取舍建议

- **A 是 B/C 的必要基座**（先把编排定义抽成工具无关文档，B/C 的 artifact/ledger 才有共同的阶段定义可校）。
- **B 为推荐主线**：与 upstream-gate 支柱④ 同构、复用其分发+validator+双层防假闸链路，工具无关强度足够（L3+L5），且不引入新的 git hook 单工具耦合风险。
- **C 为可选增强**：在已有消费仓库 chokepoint（F62 落地后）时，把 B 的 validator 额外挂一道 git-hook（L4）作为提交时的即时兜底；无独立价值时不单独做。

---

## 4. 范围边界

### 4.1 本 spec 不实现

只出设计、存档、标 DEFERRED。不写任何代码、不改脚本/hook/skill 本体、不新建 artifact/validator/ledger。落地需 owner 排期并另出 implementation plan。

### 4.2 与轨道 B 其他工具无关强制项的关系

| 相关 entry | 分工 / 关系 | TRIG-03 是否重做 |
|---|---|---|
| **[[INFRA-F61]]**（支柱② 代码网 + gate 平权 + open-PR 雷达） | 管代码侧 gate 工具无关 + gate 双挂 push:master。TRIG-03 若走路线 B/C，其 CI/PR chokepoint 设计约束（新增 gate 必同挂 push:master）沿用 F61 已拍架构。 | 否，沿用其 chokepoint 架构 |
| **[[INFRA-F62]]**（支柱② 设计网 mockup conformance chokepoint） | 已覆盖 pipeline **终点保真**（mockup handoff git gate）。TRIG-03 的路线 C 骑 F62 已建的消费仓库 chokepoint 落点。 | 否，终点已覆盖；路线 C 复用其落点 |
| **[[INFRA-F63]]**（支柱③ 每工具薄适配器 + 元层） | 最近的归属父项：F63 元层 = 学习闭环 + 可观测埋点。编排推进追踪本质是"元层可观测"的一部分。TRIG-03 的路线 A 复用 F63 已建的三层薄适配器分发轨道（bundle / Codex prompt / Project-Instructions）。 | 否，作为 F63 元层的一个子能力 |
| **upstream-gate（支柱④，[[INFRA-F55]]）** | 已覆盖 pipeline **上游内容**（discovery/IA/persona/数据可行性 的 artifact+validator）。TRIG-03 路线 B 直接复用其 artifact+validator+双层防假闸范式，可考虑把编排推进字段并入同一 artifact 而非另造。 | 否，上游内容已覆盖；路线 B 复用/扩展其制品 |

**一句话定位**：TRIG-03 = 补齐"上游 gate（内容）"与"终点 gate（保真）"之间那段**编排推进追踪**的工具无关落点，不重做已被这两端覆盖的部分。

### 4.3 何时值得启动

- **前提就绪信号**：F61 consumer 冒烟 chokepoint + F62 变体 B produce 侧落地后（届时有稳定的消费仓库 chokepoint 可挂），且 owner 关注点转向"多工具跑完整 pipeline 的采纳一致性"时。
- **暂不启动的理由**：当前 owner 单人主力、主要在 Claude Code 里跑全流程，CC skill 编排 + TodoWrite 对 solo 工作已够用；缺口只在"同事用 Codex/claude.ai 跑完整 pipeline"这一尚未高频发生的场景才真正咬人。属"能力扩增"而非"MVP 硬化整理"，故当前波3 明确 DEFERRED。
- **优先级**：backlog 标 P1（对抗验证后）——是轨道 B 命门的真实缺口，但依赖前置 chokepoint 就绪，非当下可独立启动。

---

## 5. enforcement 层级声明（触发器 K 强制）

> 触发器 K：任何提议的新机制必须声明 enforcement 层级（L1-L5）+ 为什么不能升更高级。

本机制若落地，enforcement 层级 = **混合，以路线 B 为主线**：

- **确定层（阶段顺序合法 / 必填产出引用存在 / 阶段间 handoff 前提满足）→ L3（便携 validator 脚本）+ L5（CI gate 挂 chokepoint）**。理由：这些是客观可机校的（锚点/路径解析、状态机顺序、数值前提如 `red_count==0`），按触发器 K 的判定表"客观可测的规则 → 必须 L3+"，不接受降 L1。落 L5（CI/PR chokepoint）而非仅 L4（git hook）是为满足轨道 B 命门"跨工具/跨人全员强制"的目标——L5 是工具无关强度最高的落点。路线 C 的 L4 git hook 作为**可选即时兜底**叠加，不替代 L5。
- **判断层（每阶段产出的实际质量，如"这个 IA 设计得好不好"）→ L1（owner PR review）**。理由：这是判断题，无可量化机器判据，"假装机校 judgment = 假闸"（upstream-gate §8 + assessment §2 诊断的 `mockup I1=pass 假闸` 反模式）。按触发器 K"AI 自我约束 / 判断题 → L1 可接受"。**明确不假装机校产出质量。**
- **为什么不全部升 L4/L5**：因为编排推进"是否真的走完/走对"含判断成分（阶段产出质量），不能整体机校；但制品的存在性/顺序/证据链可机校，该部分必须 L3+ 才不退回假闸。这正是 upstream-gate 双层设计的直接复用。

---

## 6. 未决项（留给 implementation plan）

1. 阶段状态字段是**并入既有 `upstream-gate.<feature>.md`**（复用分发+校验链路、避免多制品）还是**另造 `pipeline-state.<feature>.md`**（职责单一）——倾向前者，减制品数。
2. 阶段间 handoff 前提的机校判据清单（哪些是确定层可校、哪些必须留 owner review），需逐阶段过一遍 8 阶段的 checkpoint 定义。
3. 路线 A 的编排定义文档抽取后，`tvu-design-pipeline` CC skill 是否收缩为"指向该文档的薄适配器"（与 upstream-gate skill 同构）。
4. 与 [[INFRA-F63]] 元层"可观测埋点"的合并点：编排推进追踪的 artifact 能否同时充当 F63 要的 observability 数据源。