gateflow

Gateflow

Gateflow 只定义单个 work unit 的流程和 gate。work unit 可以是 feature、issue、bug fix、migration、refactor、 schema/public contract change 或 architecture-sensitive task。

Core Principles

• 先看代码和事实，再判断 work unit 是否成立。
• 进入 plan 前，先用通俗语言向用户确认目标、非目标、边界和成功信号。
• Goal confirmation 是 binding scope contract。改变目标、公共契约、兼容性承诺、验收标准或未获授权的重大架构边界， 先让用户重新确认；已确认目标内、保持对外承诺的必要实现选择和内部重构由总控继续处理，不重复请示已授权的变化。
• 最小必要设计是减少不必要的机制，不是减少修改行数。基于代码与事实明确目标行为和正确职责 owner，优先复用适用机制； 对已证实的缺陷或结构性问题解决根因，允许范围明确的内部重构或旧机制替换，不靠特例、旁路、重复判断或兜底保留错误模型。 最佳实践须有当前需求、具体风险和收益依据，不为假设未来需求引入框架、抽象或基础设施。
• 保留可追踪的计划、实现/验证、审核/裁决和交付事实；可同文件维护或引用已有记录，不要求每个 gate 独立文件或 commit。 conversation-only 结果不足以通过 gate。
• draft PR gate 自动推进到 draft-PR-pass；merge、approve、mark ready for review、request reviewers、delete branch、 对外 comment、创建/修改外部 issue 仍需用户额外授权。

Invocation

典型调用：

使用 $gateflow 开发 <work-unit>。

可选参数：

使用 $gateflow design_doc=<path> base_ref=<ref> 开发 <work-unit>。

如果传入 design_doc，它是当前 work unit 的设计依据之一。若未传入，则以用户需求和代码事实为准。

Preflight

任何 discussion、plan 或文件修改前，先检查：

git branch --show-current
git status --short

如果当前 branch 是 main、master、develop、release/* 或项目定义的 protected trunk branch，先停下来让用户确认创建 工作分支。若 branch、dirty changes 或 scope ownership 不清，也先停下来问用户。

Gate: goal confirmation

进入 plan 前必须完成 goal confirmation：

• 读取需求、design document（如有）和相关代码；
• 从第一性原理判断 work unit 是否成立；
• 复述目标、动机、成功信号、非目标、scope boundary；
• 说明直接代码证据；
• 说明本轮不会做的过度设计；
• 列出 blocking open questions（如有）。

用户确认后才能进入 plan。如果目标不成立、范围过大、动机不足或关键约束缺失，先 discussion，不进入 implementation。

Gate Order

按以下顺序执行适用步骤；fix/re-review 仅在有实际修复时执行：

goal confirmation
-> plan
   （总控核对；重要决策执行 plan review）
-> [fix -> 受影响面 re-review]
-> implementation / validation（按必要 slices）
-> code review
   （一轮完整审核，含整体目标与多 slice 交互）
-> [fix -> 受影响面 re-review]
-> ready-to-open-draft-PR
-> 必要提交 / push
-> create draft PR
-> 总控交付核对
-> draft-PR-pass
-> final closeout

简单计划由总控核对；重要契约、架构、迁移或状态机决策执行 planreview，用户或项目显式要求的计划审核仍执行。 最终组合版本的 code review 使用 deepreview，包含原 aggregate 职责，不再另设 aggregate 轮次或强制逐 slice 审核。 PR 交付核对由总控完成，相同内容不重复派完整代码审核。