/release-preflight

name: release-preflight
description: Run the release hard-precondition gate before any tag/OTA — apc release preflight runs the real tier gate (run.ts), version alignment, and prisma regen check, all read-only. green(0) releasable · staged(3) fixable preconditions · blocked(1) tier red/env_blocked. No push, no write.
license: MIT
scope: coding
compatibility:
  - claude-code
allowed-tools:
  - Bash
metadata:
  category: release

release-preflight

发版最前面的**只读硬前置门**（`apc/01` §2 release-preflight，收口步 1/2/5）。它跑三道检查——**tier 门**（真跑 `run.ts`，读真退出码）、**版本对齐**（`/VERSION` ⇄ 承载文件）、**prisma regen**（源 schema ⇄ generated client 逐字节）——收敛成一个 `decision`。**全程只读 / 本地，不 push、不写库、不发版。**

**什么时候用**：任何 `release-tag` / `ota-promote` 之前的第一步。没跑过 preflight 拿到 green 就去 tag，是在拿没验过的栈发版。

承重纪律（发版 skill 的命根子，先记死）

• **`--tier` 必须显式传，没有默认值**。`TD`（桌面冒烟）在 `apps/desktop/e2e/smoke/` 无真跑 spec（`RUN_ELECTRON_SMOKE!=1` 时自动 `exit 77` skip）时会占位 `passed:0/failed:0`——单独拿它当发版硬前置是一道**不可能红**的空门（`apc/12` §0.12：之前 SKILL 范例全不带 `--tier` 让 agent 照抄默认值正是这么踩的坑）。**选一个会真执行断言的层**，例如 `--tier=T0,T1`。
• **tier 绿是发版的硬前置，"绿"必须是真跑过用例**。tier 红 / `env_blocked` / **空跑**（该轮所有 tier 的 `passed+failed` 合计为 0，一个用例都没真执行，即便 `exitCode` 是 0）⇒ `blocked`——发版根本不该起步，preflight 直接拦在这里。**别把 tier 红当成"发版流程的问题"绕过去**：那是被测栈的红，先修栈；也别挑一个恰好全 skip 的层去骗过门。
• **preflight 只诊断，不修**。版本失配 / prisma 待重生是 `staged`（可修前置），它给你 fix-hint（`sdk/build/version.sh` / `npm run prisma:generate:all`），**由你或人去修**，preflight 不代跑。
• **这是只读门**：它不碰 prod、不碰远端、不 push。prod 红线由 `release-tag` / `ota-promote` 的人闸把守，preflight 不涉及。

Anti-pattern（这些做法直接判红）

• ❌ **preflight `staged` 就当 green 往下发版**。`staged`（exit 3）不是 green（exit 0）——有未对齐的版本 / 未重生的 client，带病发版。
• ❌ **preflight `blocked`（tier 红）时放松 tier 或改 `--tier` 挑一个能绿的层**去骗过门。tier 门跑的是真 `run.ts`，红就是栈红。
• ❌ **不看退出码只看输出文本**。`decision` + exit code 是承重信息；"看起来没问题"不是证据。

工具契约（签名以此为准）

> `apc` **不在 PATH**——在仓库根一律用 `npx tsx sdk/apc/bin/apc.ts <sub>` 跑（stdout 是纯 JSON）。

| 命令 | 作用 | 退出码 | | --- | --- | --- | | `npx tsx sdk/apc/bin/apc.ts release preflight --tier=<tiers> [--json]` | tier 门 + 版本对齐 + prisma regen 三道只读检查 | `0` green · `3` staged · `1` blocked（tier 红 / 空跑 / env_blocked）· `2` 用法错（缺 `--tier`） |

`--tier` **没有默认值**，不传直接 usage 错 exit 2。选一个会真执行断言的层，例如 `--tier=T0,T1`——**别用 `--tier=TD`** 当唯一层：无桌面冒烟 spec 时它是空门。

`--json` 出结构化回执（审批人证据包）。字段（**名以此为准**）：

• 顶层：`{ verb:'preflight', decision:'green'|'staged'|'blocked', tier, version, prisma, blockers:[], staged:[] }`
• `tier`：`{ tier, exitCode, envBlocked, regressions:[], emptyRun }`（`exitCode` 是 run.ts 真退出码：0 绿 / 1 SUT 红 / 78 env_blocked；`emptyRun:true` = 该轮所有 tier 的 `passed+failed` 合计为 0，一个用例都没真跑，即便 `exitCode:0` 也判 `blocked`）
• `version`：`{ aligned, rootVersion, mismatches:[{file,found}] }`
• `prisma`：`{ ok, stale:[{schema,reason}] }`

Workflow

1. 跑门（`--tier` 必须显式传，选会真执行断言的层）

npx tsx sdk/apc/bin/apc.ts release preflight --tier=T0,T1 --json > /tmp/preflight.json; P=$?
echo "preflight exit=$P"

从 `/tmp/preflight.json` 读 `decision`，并把退出码 `$P` 对照下表。

2. 按 decision 分流

| decision | exit | 含义 | 你要做的 | | --- | --- | --- | --- | | `green` | `0` | 三项全绿 | 放行——可进入 `release-tag` | | `staged` | `3` | 有可修前置（版本失配 / prisma 待重生） | 读 `staged[]` 的 fix-hint，修完（`sdk/build/version.sh` / `npm run prisma:generate:all`）**重跑 preflight** 直到 green；不得带病往下发 | | `blocked` | `1` | tier 红 / 空跑 / env_blocked | 读 `tier` + `blockers[]`。`env_blocked` → 先 env-doctor 修环境；`exitCode:1`（SUT 红）→ 停手，栈有回归，回 bugfix 入口；`emptyRun:true`（0 用例真实执行）→ 换一个会真跑的层，不是"再跑一次同一个空层". **绝不绕过** |

Failure / 边界

• `env_blocked`（`tier.envBlocked:true` / run.ts exit 78）是**环境故障域**，不是发版失败也不是 SUT 红——先 env-doctor，别当成"发版门坏了"。
• 本机 `prisma/schema.mysql.prisma` 与 generated client 若 drift，preflight 会**如实**落 `staged` 提示 regen——这是真信号非误报（`apc/11` §0.21 已记账）。
• preflight 无远端替身缺口：它全程真路径（只读），不存在"本机替身没接线"的 ⬜。

输出契约（机器判据按这个复验，别自由发挥格式）

本 skill 的验收判据不再是「报告里出现了 `green` / `prisma` 这些词」——旧判据里一句「看起来 version 都 aligned」就能让「版本/prisma 已核」变绿。现在判据找的是**三道硬前置 + decision 各自那一行**，并把该行的引用**读回磁盘复核**（`structured-criteria.ts` 的 `dimension-coverage`）。

**四行逐条作答**（每条**独占一行 + 固定 key**，值给：JSON 里的**真值** → 明细 → 该判据在源码里的定义处）：

- [1] tier-gate: exit=0 envBlocked=false emptyRun=false regressions=0 | sdk/apc/cli/release-common.ts:179
- [2] version-alignment: aligned=true /VERSION=2.2.4 mismatches=0 | sdk/apc/cli/release-common.ts:110
- [3] prisma-regen: ok=false stale=1（prisma/schema.mysql.prisma schema-drift）| sdk/apc/cli/release-common.ts:144
- [4] decision-exit: decision=staged → exit=3（green→0 / staged→3 / blocked→1）| sdk/apc/cli/release-preflight.ts:83

判据强制三条：

1. 四个 key **各自必须有自己那一行**——「正文里提过 tier」不算作答（漏一条判红）。 2. 每行的值**必须带至少一条能在磁盘上复核的 `path:line`**（文件存在、行号在范围内、该行非空）——`rg -n 'export function runTierGate' sdk/apc/cli/release-common.ts` 出来的行号，**别猜**。引用指向**该检查在源码里的定义处**（tier 门 / 版本对齐 / prisma regen / decision 收敛），这是"对码"：你报的是哪道门给的结论，就指出那道门。 3. 真跑一轮，这四条**没有一条是 N/A**；行首别以 `无` / `N/A` 开头（会被当成"不适用"并要求 ≥20 字符理由）。

引用写法：**必须 repo-root-relative**（`sdk/apc/cli/release-common.ts:179`，不要简写、不要绝对路径）；`rg -c` 出的 `path:12` 是**命中计数不是行号**，要写就写 `count=12`。

**诚实边界（`dimension-coverage` 这条判据管到哪）**：它复核的是「四条前置都作答了 + 引用真实存在」，**不复核 `exit=0` 这类数值本身**。~~把 `staged` 写成 `green` 骗不过重跑的人，但骗得过这条判据。~~ ← **这个洞已由下面的 ⑤ 补上**（2026-07-26）。

**⑤ 原始产物 + decision 声明行**（`json-claim` 复核；**这条是本 skill 的承重判据**）

把 `apc release preflight --json` 的 stdout **原样贴进一个 fenced JSON 块**（别摘录、别改写），并给出一行：

PREFLIGHT-DECISION: blocked

checker 重新解析产物并核对：

• **`PREFLIGHT-DECISION` 必须逐字等于产物的 `decision`。** 把 `blocked`/`staged` 叙述成 `green` 即红——这正是上一段原本承认骗得过的那件事。
• `verb` 必须是 `preflight`；`decision ∈ {green, staged, blocked}`；`blockers`/`staged` 必须是数组。
• **三条 decision 收敛不变量**（把判定逻辑本身钉死，防回退）：
• `decision=green` ⇒ `blockers` 必须为空
• `decision=blocked` ⇒ `blockers` 必须非空（不许无理由地红）
• `tier.emptyRun=true` **或** `tier.envBlocked=true` ⇒ `decision` 必须是 `blocked`

> **为什么第三条是承重的**：TD 层空跑时 `tier.exitCode` **是 0**——一个只看退出码的判据会把它读成绿。真产物长这样：`tier={tier:'TD', exitCode:0, envBlocked:false, emptyRun:true}` 而 `decision='blocked'`。apc/12 §0.12 的空跑修法就