# .githooks — upstream-gate artifact 确定层机校（零依赖）

本仓 commit `docs/specs/upstream-gate.<feature>.md`（支柱④ 上游理解-分析 gate 的产出物）时，
自动跑 tvu-design-system 的 validator 确定层。人工层（需求复述 / persona / MVP scope）留 owner review。

- `pre-commit` — 纯 POSIX sh。扫 staged `docs/specs/upstream-gate.*.md`（模板 `_upstream-gate.template.md` 不算），
  逐份调 DS 仓的 `scripts/validate-upstream-gate.mjs --no-network`。**唯一硬依赖是 node**，不需要 npm / husky。

## 为什么是 git hook，不是 CI（2026-09-09 owner 拍）

本仓是纯文档仓：无 package.json、无 CI。DS 的 CI 模板要 `pnpm install` + 把 DS 装成依赖 + GitHub Actions 语法。
DS `templates/consumer-product/.githooks/` 那套范式就是为「Design-only、无 npm/husky 基建」的仓设计的，本目录照它的形态。
代价：`core.hooksPath` 是本地配置，**每个 clone 各自跑一次**才生效。

## 启用

```bash
git config core.hooksPath .githooks
```

DS 仓的定位顺序：环境变量 `TVU_DESIGN_SYSTEM_PATH` → 兄弟目录 `../tvu-design-system`。
两个都没有 ⇒ **fail-open**（告警不拦）；设 `TVU_UPSTREAM_GATE_STRICT=1` 改为阻断。node 缺失同理。

## 手工跑（不 commit 也能校）

```bash
node ../tvu-design-system/scripts/validate-upstream-gate.mjs --repo-root=. ; echo EXIT=$?
```

不带 `--no-network` 时会真发 HTTP 请求校竞品 URL 可达性（hook 里刻意不做，pre-commit 不该等网络）。

## 已验（2026-09-09）

合法 artifact ⇒ 放行 · 占位域名 `example.com` ⇒ 拦并点名 · 死锚点 ⇒ 拦并点名 · 非 artifact 文件 / 模板 ⇒ 静默放行 ·
node 缺失 ⇒ fail-open 告警，`STRICT=1` ⇒ 拦。