Synthesis Preflight 是一个分支就绪门禁（branch readiness gate），用于在创建 PR 之前判断当前分支是否在机制上准备好成为 PR。它不评估代码是否正确——那是实现完整性自检（synthesis-implementation-integrity）和代码审计（synthesis-code-audit）的职责。Preflight 回答的是另一个问题：分支是否在机制上就绪？
一个分支可能包含完全正确的代码，但仍然无法通过 preflight：测试失败、遗留未提交变更、提交消息含糊、过时的临时变通方案未移除。Preflight 捕捉的是介于“代码能工作”和“分支已就绪”之间的那些事项。
在流程中的位置
Preflight 是整个技能链中的最后一道门禁。典型流程为：实现 → 自验证（implementation-integrity）→ 质量扫描（code-audit）→ 分支门禁（preflight）→ 创建 PR → 同行评审（pr-review）。
Preflight 会消费当前的 implementation-integrity 和 audit 证据，检查这些证据是否覆盖了提议的分支状态和所需消费者；它不会为了生成另一份报告而重复未变更的评审。就绪裁定不授予合并、发布或部署权限。
质量门禁框架
Preflight 评估六个正交维度，每个维度独立评级：
- 通过（Pass）：无问题
- 警告（Warning）：潜在关注点，不阻塞
- 失败（Fail）：阻塞 PR 直至解决
- 未知（Unknown）：所需证据不可用、不完整或过时；阻塞就绪
- 不适用（N/A）：该维度不适用，需给出与项目契约挂钩的具体理由
任一必需维度出现 FAIL 或 UNKNOWN，分支即为 未就绪（NOT READY）。警告仅用于提示，不阻塞。已批准的契约修正可以改变要求，但不能将失败或缺失的观察重新标记为通过。
六个质量维度
1. 分支验证
确认当前位于功能、修复或工作分支上，而非默认分支（main、master 或项目指定的受保护分支）。若在受保护分支上，拒绝继续。统计领先基分支的提交数。若分支落后于基分支，警告可能需要在创建 PR 前同步。
2. 工作区清洁度
检查未提交的变更。若存在，警告它们不会被包含在 PR 中。若有未暂存变更，显式列出，让开发者决定提交或丢弃。目标是告知，而非强制——未提交的工作可能是有意为之（无关实验、本地配置）。
3. 测试与类型验证
运行项目完整测试套件，报告通过/失败摘要。若项目使用类型检查器（TypeScript、mypy、pyright 或等价物），运行并报告类型错误。这些是二进制门禁：测试失败或类型不通过，分支未就绪。
4. 代码审计
对完整分支 diff（基分支到 HEAD）运行 synthesis-code-audit 方法。审计中任何 FAIL 维度 = preflight 此门禁 FAIL。WARNING 维度在报告中呈现但不阻塞。审计裁定为“Clean” = 此门禁 PASS。
5. 临时事项
检查项目是否跟踪临时变通方案、已知问题或有时限的技术债。对每个跟踪条目：运行其解决验证检查（每个临时事项应定义可移除的标准，如标志被删除、迁移完成、依赖升级）；已解决条目从跟踪中移除并在输出中报告；仍活跃条目列出。若项目不跟踪临时事项，此维度评为 N/A。
6. 提交历史
审查从基分支到 HEAD 的提交：提交消息中出现秘密或凭据 → FAIL（即使秘密不在代码中，出现在提交消息中也会持久化在 git 历史中）；消息清晰度是否符合仓库策略——当仓库要求描述性主题时标记不清晰消息，显式披露规则可能要求通用消息，不应为满足通用风格偏好而要求敏感细节或重写历史；约定合规——检查提交消息是否遵循项目文档化格式（约定式提交、祈使语气、字符限制等），标记违规。
裁定输出
输出格式为状态报告，列出六个维度的评级和详情，最终给出 READY / NOT READY 裁定。READY 表示所有必需维度都有当前通过的证据，真正不适用的维度和非阻塞警告已解释。NOT READY 表示一个或多个必需维度为 FAIL 或 UNKNOWN，按优先级列出阻塞项，说明问题或缺失内容以及何种观察能解决它。
规则
- 永不跳过维度。真正不适用的检查可以评为 N/A，但需给出不适用的证据。缺失工具、缺少必需测试套件、环境不可访问或检查失败均为 UNKNOWN 或 FAIL，而非 N/A。
- 裁定是机械的。任何必需的 FAIL 或 UNKNOWN 都导致 NOT READY。
- 警告仅提供信息，不阻塞。
- 若 preflight 由其他工作流（发布或 CI 管道）调用，返回完整报告供该工作流决策。
- 仅当来源/基哈希、相关输入、工具/环境假设和标准仍然有效时复用证据。变更后需重跑受影响检查及仓库明确要求的检查；保留未受影响的证据。仅凭同一会话时间戳不能确立有效性。
临时事项模式
该模式值得说明，因为大多数项目未将其形式化，导致变通方案静默累积。
应跟踪的内容：依赖或基础设施已知缺陷的变通方案、本应临时的功能标志、特定迁移后应来自配置的硬编码值、已弃用 API 的兼容层、任何有隐含过期日期的代码。
条目格式：描述（变通方案做什么及为何存在）、临时原因（什么事件或变更使其不再需要）、解决验证（具体可检查的条件，如文件被删除、配置键存在、依赖版本高于 X、功能标志被移除）、提议的排除项（识别受影响的要求、决策所有者及任何适用授权；记录失败一次但不抑制其阻塞后果；仅列在此处不产生任何排除）。
为何 preflight 检查此项：未跟踪、未检查的变通方案往往变成永久性的。Preflight 自动清理已解决条目防止累积。解决底层问题的开发者可能不记得受影响的每个变通方案——preflight 替他们记住。
适用场景与限制
适用于任何使用 git 分支和 PR 工作流的软件项目，尤其在团队协作中需要统一合并前检查标准时。它需要项目已配置测试套件、类型检查器和代码审计流程；若这些缺失，相关维度将评为 UNKNOWN 而非 N/A，从而阻塞就绪。Preflight 本身不执行代码正确性评估，不授予合并权限，依赖已有的 implementation-integrity 和 code-audit 证据。