证据门禁:什么算真正「做完了」
在 AI 辅助编程中,最常见的问题是:模型在聊天框里信誓旦旦地说“我已经改好并测试通过了”,但你打开仓库一看,要么漏改了文件,要么测试根本没跑,要么在跨仓迁移时只改了 A 漏了 B。
因此,jj-flow 的第一条核心原则就是:聊天口头承诺不算数,只有落盘的文件、测试输出、审查报告与 Git 提交才算数。
一、什么算数 vs 什么不算数?
| 验证维度 | 算作有效凭据(可放行过门禁) | 不算有效凭据(会被拦截或保持 PENDING) |
|---|---|---|
| 需求与步骤完成度 | .workflow/ralph/<task>/task_plan.md 中明确列出的目标、验收项与已完成步骤 | 聊天记录里口头说“所有需求都满足了” |
| 代码改动真实性 | 工作区真实的 git diff 或已产生的 Git commit SHA | 对话里贴了一段代码片段,但未实际写入仓库文件 |
| 测试与验证结果 | progress.md 中记录的真实测试命令输出与验证结论 | 口头声称“单测应该都能过”或跳过验证却未说明原因 |
| 代码审查结论 | 只读审查员写入的 findings.md 与 .state/reviews/REV-*.json(结论为 [OK] 或 [WARN]) | 审查结论仍为 [BLOCK](NEEDS_CHANGES),或存在未解决的高优缺陷 |
| 多仓调度完成度 | 调度账本中记录的真实会话绑定、各仓 commit、审查记录与运行时沙箱证明(sandbox attestation) | 仅在聊天框里列了一张状态表格,但控制面账本无对应记录 |
证据不足时的默认行为:宁可停下问,绝不假装通过
当任何一项证据缺失、或者需求中的必做项(MUST)与边界无法确认时,jj-flow 会将状态保持在当前阶段(或标记为 PENDING / BLOCKED),并主动向你说明卡点,绝不会为了“看起来顺利”而帮你蒙混过关。
二、单仓、跨仓与收工的「完成标准」对照
不同工作流入口负责不同的交付阶段,它们的“完成标准”有着严格的边界:
| 工作流入口 | 什么状态下算该阶段完成? | 此时还没做什么?(下一步动作) |
|---|---|---|
| ralph(单仓闭环) | 代码已修改、测试与审查已通过、你在对话中确认验收,且任务目录已移入 .workflow/ralph/completed/ | 尚未 git commit / push → 如需提交合入 dev,请调用 $jj-end;如需迁往其他仓库,请先提交再调用 $jj-same |
| same(跨仓迁移) | 每个目标仓库都按各自规范改好、跑过验证,并输出了独立小结(若项目B 完成、项目C 阻塞,则只算项目B 完成) | 尚未推送远端 → 请在验证通过的目标仓库调用 $jj-end |
| dispatch(多仓调度) | 统筹账本中所有目标项目均集齐“提交 + 审查 + 会话绑定 + 沙箱证明”并标为 VERIFIED | VERIFIED 不等于已推送远端或已合入 dev → 需在各目标仓执行 $jj-end 完成远端合入 |
| end(Git 收工) | 本任务代码已提交,且工作分支与集成分支(如 dev)均已成功推送至远端,本地已切回工作分支 | Git 交付已全部闭环 |
三、三层状态架构:各层分别管什么?
为了既能跨项目统筹、又不污染各个业务仓库,jj-flow 将状态清晰地分为三层(日常使用无需手动维护,了解即可):
text
┌───────────────────────────────────────────────────────────────────┐
│ 第 1 层:本机全局配置层 (~/.jj-flow/naming.json & map.md) │
│ 职责:记录本机有哪些业务仓库、路径在哪、属于哪个项目族 │
└─────────────────────────────────┬─────────────────────────────────┘
│ 按路径定位仓库
▼
┌───────────────────────────────────────────────────────────────────┐
│ 第 2 层:多仓统筹控制层 (~/.jj-flow/ 下的 DEL-* 调度账本) │
│ 职责:对应 $jj-dispatch —— 管“派给谁、批没批、各仓是否 VERIFIED” │
│ (只存指向各仓任务与 commit 的引用指针,绝不复制业务代码正文) │
└─────────────────────────────────┬─────────────────────────────────┘
│ 下发任务并回收证据
▼
┌───────────────────────────────────────────────────────────────────┐
│ 第 3 层:业务仓库执行层 (<项目根>/.workflow/ralph/task-…/) │
│ 职责:对应 $jj-ralph / $jj-same —— 管真实的代码修改、测试与审查 │
└───────────────────────────────────────────────────────────────────┘