# 支柱④ 上游理解-分析 gate — 设计 Spec

> **日期**：2026-07-09
> **归属**：[[INFRA-F55]] 支柱④（上游理解-分析 gate）。真源背景 = `docs/internal/full-lifecycle-assessment-2026-07-08.md` §3/§4 支柱④ + §7 fork。
> **状态**：设计已 owner 批准（brainstorm 三决策）→ 待出 implementation plan。

---

## 0. 目标 & 护栏

**目标**：在任何人 × 任何工具用 TVU DS 产出**产品设计（code / mockup）之前**，强制走上游理解-分析（需求复述+理解确认 → 读真源 → 竞品(实时检索)/persona/IA → 数据可行性 → MVP scope → user 校验），且**质量与工具解耦、系统自触发、不可静默跳过**。

**owner 护栏（不可违背）**：
1. 工具无关 gate 制品 + 每工具薄适配器。
2. claude.ai 降级 L1。
3. 支柱②（PR/CI）兜底。
4. **禁止 Claude-Code-hook-first**（权威不能绑 CC hook）。

**根因对齐**：assessment §2 诊断的 `mockup I1=pass 假闸`（查文本存在性即过 → 可粘贴伪造）是本设计要正面规避的反模式。

---

## 1. 三个已批准的基础决策

| # | 决策 | 选中 |
|---|---|---|
| D1 gate 制品形态 | **产出物 + schema，支柱② PR 校验** | 生产者动手前产出结构化 `upstream-gate.<feature>.md`，PR/CI 校验其存在 + 机器可核部分。真闸（有确定性验收）、工具无关、PR 强制、降级友好。 |
| D2 位置 + 依赖 | **从 DS 发便携 artifact+schema+validator，消费真源可选、优雅降级** | 不强制 owner fork #4（每消费产品维护 roadmap/product-context）；有则确定性检激活、无则该检降 L1+警告。 |
| D3 防假闸 | **双层：确定层机校 + 理解/质量层走 owner PR review** | 不假装机校 judgment；理解确认关卡 = merge gate 本身，无可伪造 self-ack。 |

---

## 2. 架构（四层 + 降级阶梯）

```
[薄适配器: 每工具触发]  →  产出 upstream-gate.<feature>.md (schema)
   CC=skill · Codex=file-prompt · claude.ai=Project-Instructions(L1 手填)
                                      ↓
[validator (DS 便携 node 脚本)]  ← 确定层机校 (可本地跑; 缺则 PR 兜)
                                      ↓
[支柱② PR/CI = 权威闸]  确定层机校 + owner review 人工核理解/质量层
                          PR review = owner 统一验收关卡
```

- **机械权威 = 受控落点(chokepoint)的 PR/CI**，不是"某个普适 PR"（修正：PR 只存在于有 git 的工程 repo；裸 AI 会话没有 PR）。chokepoint = ① DS 自己 repo（Gitea `.gitea/pr-checks.yml`）② 采纳了 gate 的消费 repo（经 scaffold 下发，见 §6）③ [future] Figma 库提交 / npm 消费。
- hooks 只是 L3 适配器的便利触发 → 满足护栏 4（非 hook-first）。
- 产出落进任一 chokepoint repo → 该 repo 的 PR/CI 跑 validator + owner review，否则不 merge。
- **裸 AI 会话（无落点，如 informal claude.ai）无法机械 gate** —— 见 §5 诚实边界 + §6 落点自举。

### 单元边界（isolation）

| 单元 | 职责 | 依赖 | 接口 |
|---|---|---|---|
| `upstream-gate.schema.json` | 定义 artifact 字段 + 哪些是确定层/人工层 | 无 | 被 validator + 适配器读 |
| `validate-upstream-gate.mjs` | 只机校确定层，输出 PASS/FAIL + per-field verdict | schema · (可选)消费 product-context | CLI + PR/CI 调 |
| 薄适配器 ×N | 各工具把生产者导进产出 artifact 的流程 | schema | 产出 artifact |
| 支柱② PR job | 跑 validator + 呈现给 owner review | validator | merge gate |

---

## 3. Gate artifact — `upstream-gate.<feature>.md`（front-matter + 正文）

| 字段 | 层 | 校验方 |
|---|---|---|
| `understanding`（需求复述） | 人 | owner PR review 确认复述是否正确 |
| `sources_read: [路径#锚]` | **机** | validator：锚点存在（复用 stale-anchors 机制） |
| `competitive: [{vendor,url,finding}]`（实时检索） | **机 + 人** | validator：URL 解析 200 + 域名合理性；owner 核相关性 |
| `persona_ia` | 人 | owner review |
| `data_feasibility: {fields:[...]}` | **机**（有 context 时） | validator：字段 ∈ 消费 product-context（缺则降 L1 + 警告） |
| `mvp_scope` | 人 | owner review |
| `degradation_note`（哪些检因缺 context/工具降级） | 机写 | validator 生成，PR 呈现 |

- `<feature>` = 本次产品设计任务标识；artifact 随该 PR 提交，与 code/mockup 同 diff。

---

## 4. Validator — `validate-upstream-gate.mjs`（随 DS 包/bundle 发）

只机校**确定层**：
- schema 完整（所有必填字段存在、格式合法）。
- `sources_read` 锚点存在。
- `competitive[].url` 解析（HTTP 200，带 timeout + 失败不脑补——超时标 UNVERIFIED 而非 PASS）。
- `data_feasibility.fields` 对得上消费 product-context（存在时）；缺 context → 该检 SKIP + `degradation_note` 记录，**不 FAIL**。

**明确不做**：不机校 understanding/persona/mvp 质量（判断题，假装机校 = 假闸）。这些留 owner PR review。

侧效应护栏（复用既有教训）：URL 检查必 timeout + 失败不阻塞进程本身（只标记）；无真实返回时禁脑补（[[feedback_no-fabrication-on-uncertain-tool-output]]）。

---

## 5. 降级阶梯（同一 artifact + validator，触发强度递减）

| 层 | 工具 | 会话内触发 | 机械兜底（仅当产出落进 chokepoint repo） |
|---|---|---|---|
| L3 | Claude Code | 适配器 skill 引导全流程 + 本地跑 validator + 竞品实时检索 | 落点 repo PR/CI |
| L2 | Codex | file-based prompt 自带全流程 + 产出 artifact | 落点 repo PR/CI |
| L1 | claude.ai / 其它 | Project-Instructions（来自 bundle）引导产出 artifact + **会话内人类实时理解确认**（human 在场，AI 复述→人当场确认——D3 人工层在此天然成立，不需机器） | 落点 repo PR/CI（**若**产出被 commit 进采纳了 gate 的 repo） |

**关键修正**：L1 的兜底**不是**"PR 是唯一强制"（claude.ai 根本没 PR）。L1 靠两条：
1. **会话内人类实时理解确认**（真的、L1 有效，因为 human 在场）；
2. **产出被采纳进任一 chokepoint repo 时**，那里的 validator + owner review 才补上确定层机校。

### 诚实边界（不留假承诺）

设计系统只能在**自己控得住的 chokepoint** 上机械 gate。**产出永不落任何 repo 的纯 informal 使用（有人在 claude.ai 里画完直接用）→ 无法机械 gate，也不假装能**。缩小这个边界的唯一杠杆 = 让消费产品尽量都成为 chokepoint（§6 scaffold 自举）。

---

## 6. 落点采纳 = adoption lever（靠现有消费 scaffold，闭合 chokepoint 缺口）

gate 的机械 reach = 有多少消费产品是 chokepoint。**最大化 reach 靠现有消费安装模块下发**，不指望每团队手动接。

### 6.1 骑现有 bundle + scaffold（不新造分发轨道）

- DS npm 包已 `files:["dist","eslint-plugin","scripts","templates",...]` **版本锁定**下发 audit 工具 + `templates/consumer-product/` 片段；`setup-tvu-consumer` skill 按场景接线。
- **upstream-gate 增量落这里**：`validate-upstream-gate.mjs` 进 bundled `scripts/`；CI 片段进 `templates/consumer-product/`（今已有 `audit-workflow.yml` 可扩）；`upstream-gate` artifact 模板 + `_product-context.template.md` 进 `templates/consumer-product/docs/`（与已有 `_feature-design-record.template.md` 同簇）；`setup-tvu-consumer` 按场景接 gate CI。
- **不依赖 Gitea**：消费方 CI = 消费产品自己的 CI（现模板是 **GitHub Actions** `.github/workflows/audit.yml`；可加 Gitea 变体）。**Gitea 只是 DS 自己团队仓的 CI**（`.gitea/pr-checks.yml`），与消费产品 CI 无关。

### 6.2 chokepoint 自举：git-remote 探测（greenfield 从第一天有落点）

当前 scaffold 只 symlink skills + 装 audit 接线，**不做 git-init/remote**。新增探测逻辑（消费者自己的永远优先，只在缺失时建议默认 Gitea）：

| 探测 | 动作 |
|---|---|
| 已有 remote | **直接用它**，只把 gate CI 接到该 repo（场景2 存量产品几乎都属此） |
| 有 repo 无 remote | 建议设 `<Gitea host>/ux-team/<项目名>.git`，**用户确认/可覆盖** |
| 无 git repo（真 greenfield） | `git init` → 再走上面建议逻辑 |

- **只建议、绝不强制** Gitea 默认；消费者指定的 git 地址永远优先。项目名默认 = 目录名。
- 实现细节（plan 定）：默认 Gitea repo = **只 set remote URL + 提示用户去建库**（轻，默认）vs **Gitea API 自动建库**（需 write token，关联 [[INFRA-F56]]，作可选增强）。倾向轻方案默认。

### 6.3 消费真源依赖（优雅降级，不强制 fork #4）

- product-context / roadmap **可选**（`_product-context.template.md` 由 scaffold 提供但不强制填）。
- 存在 → `data_feasibility` / `sources_read` 确定性检激活（强 gate）。
- 缺失 → 该检降 L1 + `degradation_note` 警告，不硬阻。
- **激励非 mandate**：维护 context 的团队得更强 gate（fork #4 = 不强制）。

---

## 7. 与现有骨架的关系（不重复造）

- `skills/design-discovery`（6 deliverable：竞品/persona/IA/data-feasibility 等）+ `skills/design-walkthrough` **不废** → 它们是 **CC 的 L3 适配器内容**，产出喂进 artifact 字段。
- 本 gate 的增量 = 把这些从"AI 自判可跳过的 CC-only skill"**提升为 artifact + 工具无关 PR 强制**。
- `design-process.md` 的上游相关规则 → 由 gate artifact 字段承接（关联 F55 支柱① 规则三层化：契约层）。

---

## 8. 不做（YAGNI）

- ❌ issue-tracker 集成的 out-of-band ack（重、claude.ai 流过重）——理解层靠 owner review 足够。
- ❌ 机校 persona/MVP 质量（判断题，假装机校 = 假闸）。
- ❌ 强制消费产品维护 roadmap/product-context（避开组织 mandate）。
- ❌ 把 gate 做成 CC hook 作为权威（违护栏 4；hook 只作 L3 适配器的便利触发）。

---

## 9. 验收标准（DoD）

1. `upstream-gate.schema.json` + `validate-upstream-gate.mjs` 随 DS 包/bundle 可分发，`pnpm` 脚本入口 + 挂 chokepoint CI（DS repo Gitea PR + 消费 scaffold 下发的消费 repo CI）。
1b. scaffold git-remote 探测：已有 remote→用它；无 remote→建议默认 Gitea 且用户可覆盖；无 repo→git-init（§6.2）。绝不强制覆盖消费者已有 remote。
2. 一份样例 `upstream-gate.<feature>.md` 通过 validator（确定层 PASS）+ 缺 product-context 时正确降级（SKIP + degradation_note，不 FAIL）。
3. 三层适配器至少 L3（CC skill）落地 + L1（bundle Project-Instructions 段）落地；L2（Codex file-prompt）可随后。
4. 伪造测试：故意写不存在的 source 锚点 / 死 URL → validator FAIL；故意留空必填字段 → FAIL。
5. owner PR review 关卡文档化（PR 模板加"理解/persona/MVP 人工核"checklist 项）。

---

## 10. 后续（写 plan 时展开）

- DS repo 支柱② PR job 跑 validator（Gitea runner 无 root → 纯 node 校验不需 chromium，可跑）。
- 消费 bundle/scaffold 落地（§6.1）：validator 进 `scripts/`、CI 片段进 `templates/consumer-product/`、artifact + `_product-context.template.md` 进模板、`setup-tvu-consumer` 按场景接线。
- git-remote 探测逻辑（§6.2）+ 默认 Gitea repo 是 set-remote-only vs API-自动建库（关联 [[INFRA-F56]] token）。
- claude-design-bundle 带 schema + Project-Instructions 段（关联支柱③ 适配器补全）。
- 竞品实时检索缓存策略（每产品 `competitive-intel.md` 定期刷新，避免每需求全网重跑——assessment §6）。