📝 docs(main_loop): enforce plan archive completion gate

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 无遗留差异；如剩余差异属于

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` 但相关差异未归档/提交，停止并完成归档；
+  只能报告“状态已写回，交付未完成”
 - 如验证不足以支持交付，停止并标记风险
 
 ---

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 完成
 - 证据不足以支持“完成”结论时停止并汇报
 
 ---

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)