From e87be183bc2522994e8c042070ca5508b082499b Mon Sep 17 00:00:00 2001 From: csh Date: Thu, 28 May 2026 08:57:01 +0800 Subject: [PATCH] :memo: docs(main_loop): enforce plan archive completion gate --- templates/AGENT_RULES.template.md | 6 ++++++ .../prompts/coding/close-task.template.md | 11 +++++++++- .../prompts/coding/verify-change.template.md | 10 +++++++++- tests/test_sync_templates_placeholders.py | 20 +++++++++++++++++++ 4 files changed, 45 insertions(+), 2 deletions(-) diff --git a/templates/AGENT_RULES.template.md b/templates/AGENT_RULES.template.md index aca661a5..9060e73f 100644 --- a/templates/AGENT_RULES.template.md +++ b/templates/AGENT_RULES.template.md @@ -228,6 +228,10 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ ### Plan 完成归档契约 +- 归档指按当前项目约定创建可回溯的交付记录；如项目使用 Git， + 归档必须是一次 Git 提交（commit），不是仅更新 memory 或回复摘要 +- `main_loop.py finish -status done` 只负责写回机器状态，不代表 Plan + 已完成交付 - Plan `done` 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个 Plan；归档方式由项目约定决定 - 收尾顺序： @@ -248,6 +252,8 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ - 不得由 `main_loop.py finish` 自动执行提交或变更归档 - 不得把用户已有改动或其他 Plan 的改动混入当前 Plan 交付单元 - 如 Plan `done` 后没有当前 Plan 相关差异，必须在回复中说明无归档原因 +- 如当前 Plan 相关差异仍未归档，只能声明“状态已写回，交付未完成”， + 不得声明 Plan 完成 - `blocked` / `skipped` 不默认归档/提交代码改动；只有状态留痕或已验证的 局部成果需要保留时才归档/提交 - 继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异属于 diff --git a/templates/prompts/coding/close-task.template.md b/templates/prompts/coding/close-task.template.md index 84aac65e..06a2054c 100644 --- a/templates/prompts/coding/close-task.template.md +++ b/templates/prompts/coding/close-task.template.md @@ -19,6 +19,8 @@ - 如本轮来自 `main_loop.py claim` 且任务状态变更，优先通过 `main_loop.py finish` 留痕 +- 如本轮来自 `main_loop.py claim` 且结果为 `done`，`finish` 之后还必须 + 完成当前 Plan 变更归档/提交；未归档不得声明 Plan 完成 - 未验证内容必须显式说明 - 只写对下一轮仍重要的信息 - 不手工改写 `workflow-state` 或 `plan-status` 状态块 @@ -32,13 +34,18 @@ 4. 如本轮来自 `main_loop.py claim`，核对 `workflow-state.phase` 是否与当前结果一致 5. 如需回写上下文，更新 `active-context`、`progress` 上半部分和 `decisions` -6. 输出本轮摘要与下一步 +6. 如本轮来自 `main_loop.py claim` 且结果为 `done`，按项目归档机制只归档 + 当前 Plan 相关差异 +7. 复核剩余差异是否属于其他 session / 其他 Plan，且未混入本轮交付单元 +8. 输出本轮摘要与下一步 ## 状态留痕复核 - 如本轮来自 `main_loop.py claim`，`main_loop.py finish` 是否已经写回 `plan-status` - 如本轮来自 `main_loop.py claim`，`workflow-state.phase` 是否与当前结果一致 +- 如本轮来自 `main_loop.py claim` 且结果为 `done`，当前 Plan 相关差异 + 是否已经归档/提交，或是否已说明无当前 Plan 差异 - 如为代码类执行，`workflow-state` 中是否保留了 `executor=executing-plans` 与既定 `constraints` @@ -64,6 +71,8 @@ ## 停止条件 - 如已领取 Plan 但状态未写回，先完成留痕再收尾 +- 如当前 Plan 结果为 `done` 但相关差异未归档/提交，停止并完成归档； + 只能报告“状态已写回，交付未完成” - 如验证不足以支持交付，停止并标记风险 --- diff --git a/templates/prompts/coding/verify-change.template.md b/templates/prompts/coding/verify-change.template.md index 2c8806cf..af83e067 100644 --- a/templates/prompts/coding/verify-change.template.md +++ b/templates/prompts/coding/verify-change.template.md @@ -24,6 +24,8 @@ - 局部修改优先局部验证 - 不能运行的验证必须写明原因 - 不手工改写 `workflow-state` 或 `plan-status` 状态块 +- 如本轮来自 `main_loop.py claim`，验证通过不等于 Plan 完成；Plan + `done` 还必须完成当前 Plan 变更归档/提交 ## 验证步骤 @@ -33,7 +35,10 @@ 4. 复核 diff 是否只包含预期修改 5. 如本轮来自 `main_loop.py claim`，复核 `workflow-state.phase`、 `plan-status` 与当前声明一致 -6. 汇总未覆盖项和剩余风险 +6. 如本轮来自 `main_loop.py claim` 且结果为 `done`，复核当前 Plan + 相关差异是否已经归档/提交；未归档时只能声明“验证完成”， + 不能声明“Plan 完成” +7. 汇总未覆盖项和剩余风险 ## 输出协议 @@ -56,6 +61,8 @@ - 如本轮来自 `main_loop.py claim`，`workflow-state.phase` 是否与当前声明一致 - 如本轮来自 `main_loop.py claim`，`plan-status` 是否已经通过 `main_loop.py finish` 写回 +- 如本轮来自 `main_loop.py claim` 且结果为 `done`，当前 Plan 相关差异 + 是否已经归档/提交，或是否已说明无当前 Plan 差异 - 如为代码类任务，`workflow-state` 中是否保留： `executor=executing-plans` `constraints=karpathy-guidelines,.agents,AGENT_RULES` @@ -63,6 +70,7 @@ ## 停止条件 - 关键验证失败时停止并汇报 +- 当前 Plan 相关差异未归档/提交时，不得声明 Plan 完成 - 证据不足以支持“完成”结论时停止并汇报 --- diff --git a/tests/test_sync_templates_placeholders.py b/tests/test_sync_templates_placeholders.py index a6b04867..81897934 100644 --- a/tests/test_sync_templates_placeholders.py +++ b/tests/test_sync_templates_placeholders.py @@ -105,6 +105,9 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): self.assertIn("main_loop.py finish", close_task_template) self.assertIn("如本轮来自 `main_loop.py claim`", close_task_template) self.assertIn("workflow-state.phase", close_task_template) + self.assertIn("未归档不得声明 Plan 完成", close_task_template) + self.assertIn("按项目归档机制只归档", close_task_template) + self.assertIn("状态已写回，交付未完成", close_task_template) self.assertIn("## Completed", close_task_template) self.assertIn("## Not Completed", close_task_template) self.assertIn("## Verification", close_task_template) @@ -117,6 +120,11 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): self.assertIn("如本轮来自 `main_loop.py claim`", verify_change_template) self.assertIn("workflow-state.phase", verify_change_template) self.assertIn("plan-status", verify_change_template) + self.assertIn("验证通过不等于 Plan 完成", verify_change_template) + self.assertIn( + "当前 Plan 相关差异未归档/提交时，不得声明 Plan 完成", + verify_change_template, + ) self.assertIn("## Validated", verify_change_template) self.assertIn("## Evidence", verify_change_template) self.assertIn("## Not Validated", verify_change_template) @@ -173,6 +181,17 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): self.assertIn("memory-bank/progress.md", rules_template) self.assertIn("已有 `in-progress` 优先恢复", rules_template) self.assertIn("按 Plan 文件顺序选择第一个可执行 Plan", rules_template) + self.assertIn( + "归档指按当前项目约定创建可回溯的交付记录", + rules_template, + ) + self.assertIn("如项目使用 Git", rules_template) + self.assertIn("Git 提交（commit）", rules_template) + self.assertIn("不是仅更新 memory 或回复摘要", rules_template) + self.assertIn( + "`main_loop.py finish -status done` 只负责写回机器状态", + rules_template, + ) self.assertIn( "Plan `done` 后必须完成当前 Plan 变更的归档/提交", rules_template ) @@ -186,6 +205,7 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): self.assertIn("必要 memory 更新", rules_template) self.assertIn("允许存在其他 session 的未归档改动", rules_template) self.assertIn("当前 Plan 无遗留差异", rules_template) + self.assertIn("状态已写回，交付未完成", rules_template) self.assertNotIn("git status", rules_template) self.assertNotIn("git commit", rules_template) self.assertNotIn("git worktree", rules_template)