# 支柱④ 上游理解-分析 Gate — L2 Codex 适配器（file-based prompt）

> **性质**：支柱④「上游理解-分析 gate」的 **L2 = Codex（VS Code Codex 扩展 / 任何跑在 repo 内、能读文件+跑 node 的非 Claude-Code 执行器）** 薄适配器。与 L3（Claude Code skill `skills/upstream-gate/`）、L1（claude.ai bundle `reference/14-upstream-gate.md`）**同契约、同产出物、同 schema**——只是触发与执行入口按 Codex 特性改写。
> **真源**：产出物字段契约 = `scripts/upstream-gate.schema.json`；机校器 = `scripts/validate-upstream-gate.mjs`；模板 = 消费产品里 `docs/specs/_upstream-gate.template.md`（scaffold 时从 DS 包 `templates/consumer-product/docs/specs/_upstream-gate.template.md` 下发；DS 仓库自身无 `docs/specs/`，直接读包内 templates 路径）。本 prompt 不重写契约，只把生产者导进产出 artifact。
> **用法（新 Codex session，起手粘）**：
> `按 docs/internal/_prompts/upstream-gate-codex.prompt.md 执行；feature=<kebab-标识>，需求=<粘贴 PRD / 任务描述>`

---

## 0. 为什么有这份（L2 边界诚实说明）

Codex context 短、每任务 fresh session，且**不吃 Claude Code 的 hooks/skills**——所以支柱④ 在 Claude Code 里的自动前置（skill 触发）在 Codex 端不存在。本 file-based prompt 就是把那套前置**移植成自包含的一次性指令**，让 Codex 用户也走同一道 gate。

Codex 相对 claude.ai（L1）的**关键优势**：Codex 在 repo 内、能跑 shell → **确定层可以真机校**（跑 `validate-upstream-gate.mjs`），不像 L1 只能靠会话内人类确认。所以 L2 = L1 的诚实边界 + L3 的机校能力，唯独缺 Claude Code 的自动触发（靠本 prompt 手动起手补齐）。

---

## 1. 何时走本 gate

任何「做产品设计 / 画 mockup / 写产品页面 / 加新 feature」的任务，**在动手产出 code/mockup 之前**先走。已有 `docs/specs/upstream-gate.<feature>.md` 且需求没变 → 复用，跳到 §4 机校即可。

---

## 2. 产出物（照 schema 填，别自创字段）

写到 `docs/specs/upstream-gate.<feature>.md`（消费产品仓库内）。模板：优先用消费仓库已 scaffold 的 `docs/specs/_upstream-gate.template.md`；若不存在（仓库未 scaffold），从 DS 包 `node_modules/@nancyzeng0210/tvu-design-system/templates/consumer-product/docs/specs/_upstream-gate.template.md` 拷一份。字段（真源 = `scripts/upstream-gate.schema.json`，动手前先 `Read` 它确认最新字段）：

- `feature`：任务 kebab 标识（= 起手粘的 feature）。
- `understanding`：需求复述（front-matter 摘要 + 正文完整复述你理解的问题/约束/成功标准）。
- `sources_read`：读过的真源清单 `["path#anchor"]`（validator 会校锚点真实存在——**别写不存在的锚点**）。
- `competitive`：竞品实时检索 `[{vendor,url,finding}]`——**真实 URL、真实检索**。TVU 域已验证可查：LiveU / Dejero / Grabyo / Teradek / QuickLink / Cingularity。
- `persona_ia`：目标 persona + 信息架构。
- `data_feasibility.fields`：本设计要用的数据字段，对照消费产品 `docs/product-context.md` 的 `available_data_fields` 判是否真实可得。
- `mvp_scope`：首版做什么 / 不做什么。

## 3. 7 步流程

1. **需求复述 + 理解确认** → 填 `understanding`。Codex 一次性执行时无法「当场对话确认」→ **把复述写全，并在报告里显式请 owner 复审确认**（理解层验收在 owner review，不由你自 ack）。
2. **读真源**：Read 消费产品 `docs/product-context.md`（若有）+ 相关 design-record / PRD / roadmap → 填 `sources_read`。
3. **竞品实时检索**：带真实 URL + 引用 → 填 `competitive`。**工具超时 / 拿不到 / 无返回 → STOP，标 `UNVERIFIED`，禁脑补 URL**（[[feedback_no-fabrication-on-uncertain-tool-output]] / [[feedback_verify-resource-availability-before-workaround]]）。若 Codex 环境无联网检索能力，把该字段标 `UNVERIFIED` 并在报告注明「需 owner / 联网工具补检索」，**不要编造**。
4. **persona / IA** → 填 `persona_ia`。
5. **数据可行性** → 填 `data_feasibility.fields`；缺 `product-context.md` 不阻断，降 `SKIP` 并在报告标注降级。
6. **MVP scope** → 填 `mvp_scope`。
7. **产出 artifact + 机校**（见 §4）。

## 4. 机校（Codex 的确定层优势——必跑）

写完 artifact 后，在 repo 根跑：

```bash
# 在 DS 仓库内：
node scripts/validate-upstream-gate.mjs --artifact=docs/specs/upstream-gate.<feature>.md --repo-root=.

# 在消费产品仓库内（DS 作为 npm 依赖）：
node node_modules/@nancyzeng0210/tvu-design-system/scripts/validate-upstream-gate.mjs --repo-root=.

# 无联网 / CI 沙箱内禁网时加 --no-network（competitive URL 不做可达性探测，仍校结构+锚点）：
node scripts/validate-upstream-gate.mjs --artifact=... --repo-root=. --no-network
```

validator 只机校**确定层**：schema 完整性 / `sources_read` 锚点真实存在 / competitive URL 可达（超时→UNVERIFIED，不脑补）/ data_feasibility 字段。输出 `PASS / FAIL / UNVERIFIED / SKIP` + 降级说明。**理解 / persona / MVP 质量绝不由 validator 或你自判通过——留 owner review。**

## 5. STOP —— 产出后停，不 commit

- artifact + 机校 stdout 产出后 **STOP**。**禁止自 commit / push**（[[feedback_executor-no-self-commit]]）。
- 报告里回：① 生成/改动的文件 diff ② `validate-upstream-gate.mjs` 完整 stdout（含 PASS/FAIL/UNVERIFIED/SKIP + 每条降级说明）③ §3.1 需求复述**请 owner 复审确认** ④ 任何标 UNVERIFIED/SKIP 的字段及原因。
- 由 plan owner 复审 + 人类确认理解层后，才把 artifact 与 code/mockup 同 PR 提交（落进采纳了 gate 的 repo → 那里的 `audit:upstream-gate` CI + owner PR review 补上 chokepoint）。

## 6. 护栏（Codex 尤其注意）

- **禁脑补**：竞品 URL / 锚点 / 数据字段拿不到就标 UNVERIFIED/SKIP，别为凑 PASS 编造看似合理的内容（Codex 编造倾向已多次实证）。
- **别改契约凑 pass**：validator FAIL 是让你补 artifact，不是让你改 schema / validator 迁就（tail wagging the dog）。
- **理解层不自 ack**：复述、persona、MVP 的「对不对」是人的判断，你只负责产出 + 机校确定层。
- **自包含**：本 prompt 起手 Read `scripts/upstream-gate.schema.json` + 模板文件（消费仓库 `docs/specs/_upstream-gate.template.md` 或包内 `templates/consumer-product/...`）拿最新字段真源，不凭本文缓存的字段列表想当然（契约可能已演进）。