Release Preflight

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）。

--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 分流

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 的空跑修法就靠这条不变量守着，写进判据后它不会被悄悄回退。

诚实边界（沿用 json-claim 自己的声明）：肯读源码的伪造者仍能手工拼一份自洽产物——没有本地工件是不可伪造的。这条杀掉的是廉价伪造（改数字、叙述压过产物），与其余 checker 同档。