📝 docs(main_loop): make plan archive contract tool-neutral

templates/AGENT_RULES.template.md

@@ -83,7 +83,8 @@
 - `$subagent-driven-development` 仅在 Plan 或平台明确要求时使用，
   不是默认执行器
 - 执行完成后，必须先运行 `main_loop.py finish` 写回状态，
-  再更新 `progress.md` 上半部分摘要，并按主循环收尾要求提交
+  再更新 `progress.md` 上半部分摘要，并按主循环收尾要求归档当前
+  Plan 变更
 
 ### Plan 要求
 
@@ -194,11 +195,11 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
   -note "<原因>"
 ```
 
-### Plan 场景下的分支与隔离策略
+### Plan 场景下的执行上下文与隔离策略
 
 - 本节仅适用于通过主循环领取并执行 Plan 的场景
-- 默认允许在当前分支直接执行 Plan，包括 `main` / `master`
+- 默认允许在当前项目上下文直接执行 Plan
-- 不强制为 Plan 执行创建隔离工作区、临时分支或 `git worktree`
+- 不强制为 Plan 执行创建隔离上下文
 - 仅在以下场景使用隔离工作区：
   - 用户明确要求隔离执行
   - Plan 文本自身明确要求隔离执行
@@ -220,32 +221,39 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
 8. 触碰安全红线时立即停止，不继续后续 Plan
 9. 常规模式下可对高风险事项向用户确认；无交互模式按本文件
    的“需要确认的场景”自动处理
-10. 每次 `claim` 只领取一个 Plan；写回并完成必要提交后再领取下一个
+10. 每次 `claim` 只领取一个 Plan；写回并归档当前 Plan 变更后
+    再领取下一个
 11. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、
     环境需求与待确认事项
 
-### Plan 完成提交契约
+### Plan 完成归档契约
 
-- Plan `done` 后必须完成一次 commit，然后才能继续领取下一个 Plan
+- Plan `done` 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个
-- 提交顺序：
+  Plan；归档方式由项目约定决定
+- 收尾顺序：
   1. 完成 Plan 约定验证
   2. 运行 `main_loop.py finish -status done` 写回状态
   3. 必要时更新 `progress.md` 上半部分摘要和相关 memory
-  4. 检查 `git status --short` 与 diff
+  4. 检查当前变更清单与差异
-  5. 只提交当前 Plan 相关改动
+  5. 只归档/提交当前 Plan 相关改动
 - 当前 Plan 相关改动包括但不限于：
   - 本轮代码、配置、测试、模板改动
   - 当前 Plan 文件（创建、补充、勾选 Task、记录结果等）
   - `memory-bank/progress.md` 中本轮 `workflow-state`、`plan-status`
     与摘要更新
   - 必要 memory 更新，例如 `active-context.md`、`decisions.md`
-- 不得由 `main_loop.py finish` 自动执行 `git commit`
+- Plan 范围是归档/提交边界，不以整个工作区是否干净作为唯一判断
-- 不得把用户已有改动或其他 Plan 的改动混入当前 Plan commit
+- 允许存在其他 session 的未归档改动，只要它们不属于当前 Plan、
-- 如 Plan `done` 后没有 diff，必须在回复中说明无提交原因
+  不与当前 Plan 范围冲突、且不会被混入本轮归档/提交
-- `blocked` / `skipped` 不默认提交代码改动；只有状态留痕或已验证的
+- 不得由 `main_loop.py finish` 自动执行提交或变更归档
-  局部成果需要保留时才提交
+- 不得把用户已有改动或其他 Plan 的改动混入当前 Plan 交付单元
-- 工作区保持干净后再领取下一个 Plan；如存在不属于当前 Plan 的脏改动，
+- 如 Plan `done` 后没有当前 Plan 相关差异，必须在回复中说明无归档原因
-  常规模式先向用户确认，无交互模式写入风险并停止继续领取
+- `blocked` / `skipped` 不默认归档/提交代码改动；只有状态留痕或已验证的
+  局部成果需要保留时才归档/提交
+- 继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异属于
+  其他 session 或其他 Plan，保留在原处并在报告中说明
+- 如剩余差异与当前 Plan 或下一个 Plan 的预期范围冲突，常规模式先向用户
+  确认；无交互模式写入风险并停止继续领取
 
 ## 通用执行约束
 
@@ -255,7 +263,7 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
 - 遵循 `.agents/`、项目代码风格和现有命名约定
 - 只改必要部分，不顺手重构无关内容
 - 执行与改动相称的验证；如有相关测试且未被豁免，必须通过
-- 遵循 `.gitattributes` 等换行与文件格式规则
+- 遵循项目声明的换行与文件格式规则
 
 ### 决策与留痕
 
@@ -271,11 +279,12 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
   `AGENT_RULES.local.md` 或 `memory-bank/decisions.md`
 - 发现项目特有规律时，沉淀到 `AGENT_RULES.local.md`
 
-### Git 操作
+### 归档操作
 
-- 不使用 `--amend`，除非用户明确要求
+- 不改写既有归档历史，除非用户明确要求
-- 不使用 `--force`；如用户坚持，必须先说明风险
+- 不覆盖他人或其他 session 的归档成果；如用户坚持，必须先说明风险
-- 不使用 `--no-verify` 跳过 hooks
+- 不跳过项目约定的归档前检查
+- 如项目没有归档机制，在回复中列出本轮交付的文件清单与验证证据
 
 ### 工具使用
 
@@ -325,7 +334,8 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
 - [ ] 换行符与文件格式正确
 - [ ] 无语法错误或明显运行时错误
 - [ ] 已通过 `main_loop.py finish` 写回 Plan 状态
-- [ ] Plan `done` 后已完成对应 commit，或已说明无 diff 无需提交
+- [ ] Plan `done` 后已完成当前 Plan 变更归档/提交，或已说明无当前 Plan
+      差异无需归档
 
 ---
 

templates/prompts/coding/update-memory.template.md

@@ -63,7 +63,7 @@
 - 流程规则或项目私有约束变更写入 `AGENT_RULES.local.md`
 - `progress.md` 的状态块只由 `main_loop.py` 维护
 - 摘要应与 `workflow-state` / `plan-status` 保持一致
-- 摘要区保持短期状态快照；长期历史依赖 commit、Plan 文件和
+- 摘要区保持短期状态快照；长期历史依赖项目归档记录、Plan 文件和
   `decisions.md`
 
 ## 禁止事项

tests/test_sync_templates_placeholders.py

@@ -173,14 +173,23 @@ 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("Plan `done` 后必须完成一次 commit", rules_template)
         self.assertIn(
-            "不得由 `main_loop.py finish` 自动执行 `git commit`", rules_template
+            "Plan `done` 后必须完成当前 Plan 变更的归档/提交", rules_template
+        )
+        self.assertIn("Plan 范围是归档/提交边界", rules_template)
+        self.assertIn(
+            "不得由 `main_loop.py finish` 自动执行提交或变更归档",
+            rules_template,
         )
         self.assertIn("当前 Plan 文件", rules_template)
         self.assertIn("`memory-bank/progress.md`", rules_template)
         self.assertIn("必要 memory 更新", rules_template)
-        self.assertIn("工作区保持干净后再领取下一个 Plan", rules_template)
+        self.assertIn("允许存在其他 session 的未归档改动", rules_template)
+        self.assertIn("当前 Plan 无遗留差异", rules_template)
+        self.assertNotIn("git status", rules_template)
+        self.assertNotIn("git commit", rules_template)
+        self.assertNotIn("git worktree", rules_template)
+        self.assertNotIn(".gitattributes", rules_template)
         self.assertIn("`progress.md` 上半部分是短期状态快照", rules_template)
         self.assertIn("`active-context.md` 是短期上下文快照", rules_template)