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

命令	作用	退出码
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}] }