🐛 fix(templates): enforce main loop progress tracking

replace the old select/record progress flow with a single main_loop claim/finish CLI.

route template execution through main_loop only, remove the legacy plan_progress entry points, and update tests to enforce the new behavior.

templates/AGENT_RULES.template.md

@@ -62,13 +62,13 @@
 
 ## 规划与执行分工
 
-| 阶段         | 工具                   | 产出              | 留痕                 |
-| ------------ | ---------------------- | ----------------- | -------------------- |
-| 头脑风暴     | `$brainstorming` skill | 设计思路          | 无                   |
-| 生成计划     | `$writing-plans` skill | `docs/plans/*.md` | 无                   |
-| **执行计划** | **主循环**             | 代码/配置变更     | **plan_progress.py** |
+| 阶段         | 工具                   | 产出              | 留痕                       |
+| ------------ | ---------------------- | ----------------- | -------------------------- |
+| 头脑风暴     | `$brainstorming` skill | 设计思路          | 无                         |
+| 生成计划     | `$writing-plans` skill | `docs/plans/*.md` | 无                         |
+| **执行计划** | **`main_loop.py` 主循环** | 代码/配置变更     | **`memory-bank/progress.md`** |
 
-> **重要**：第三方 skills 不记录操作状态，执行必须通过主循环完成。
+> **重要**：第三方 skills 只用于规划，不负责执行留痕。收到执行触发词后，不得直接使用 `$executing-plans`，也不得直接使用 `$subagent-driven-development`；必须先运行 `main_loop.py claim` 领取 Plan，再通过 `main_loop.py finish` 写回结果。
 
 ## 主循环
 
@@ -99,21 +99,21 @@
 
 **流程**：
 
-1. 检测环境：
-   - 由 `plan_progress.py` 自动识别当前环境（`windows` / `linux` / `darwin`）
-2. 选择 Plan：
-   - 运行 `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py select -plans docs/plans -progress memory-bank/progress.md`
-   - 返回第一个可执行的 Plan：
-     - `pending` 或 `in-progress` 的 Plan
-     - `blocked: env:<当前环境>:...` 的 Plan（环境匹配时恢复执行）
-   - 如无可执行 Plan，跳到步骤 7
-   - **注意**：每次 select 会重新扫描 `docs/plans/` 目录，支持动态添加 Plan
-3. 标记开始：
-   - 运行 `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status in-progress -progress memory-bank/progress.md`
-4. 阅读 Plan：
+1. 领取 Plan：
+   - 运行 `python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim -plans docs/plans -progress memory-bank/progress.md`
+   - 该命令会**原子化**完成三件事：
+     - 自动识别当前环境（`windows` / `linux` / `darwin`）
+     - 选择第一个可执行的 Plan（优先恢复 `in-progress`，其次 `pending`，最后 `blocked: env:<当前环境>:...`）
+     - 将选中的 Plan 写成 `in-progress`
+   - stdout 必须包含 `PLAN=<path>`；如果是从环境阻塞恢复，还会附带 `NOTE=env:<环境>:<Task列表>`
+   - 如无可执行 Plan，跳到步骤 6
+2. 阅读领取结果：
+   - 记录 `PLAN=` 返回的路径
+   - 如果 stdout 含 `NOTE=env:...`，本轮只执行列出的 Task
+3. 阅读 Plan：
    - 理解目标、子任务与验证标准
-   - 如果是从 `blocked: env:...` 恢复，只执行列出的 Task
-5. 逐步执行：
+   - **注意**：Plan 文档中的 execution handoff / REQUIRED SUB-SKILL 仅作参考；如与本文件冲突，一律以主循环为准
+4. 逐步执行：
    - 按顺序执行 Task
    - 每个 Task 完成后进行必要验证（测试/日志/diff）
    - **Task 失败处理**：
@@ -123,19 +123,23 @@
    - 遇到歧义/风险/决策点：
      - 常规模式：记录到回复中，可询问用户
      - 无交互模式：按「需要确认的场景」规则自动处理
-6. 记录结果：
-   - 全部完成：`... -status done ...`
-   - 有 Task 因环境跳过：`... -status blocked ... -note "env:<所需环境>:<Task列表>"`
-   - 其他阻塞：`... -status blocked ... -note "<原因>"`
-   - 跳过整个 Plan：`... -status skipped ... -note "<原因>"`
-   - 回到步骤 2 继续下一个 Plan
-7. 汇总报告（所有 Plan 处理完毕后）：
+5. 写回结果：
+   - 全部完成：
+     - `python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish -plan <plan> -status done -progress memory-bank/progress.md`
+   - 有 Task 因环境跳过：
+     - `python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish -plan <plan> -status blocked -progress memory-bank/progress.md -note "env:<所需环境>:<Task列表>"`
+   - 其他阻塞：
+     - `python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish -plan <plan> -status blocked -progress memory-bank/progress.md -note "<原因>"`
+   - 跳过整个 Plan：
+     - `python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish -plan <plan> -status skipped -progress memory-bank/progress.md -note "<原因>"`
+   - 写回后回到步骤 1 继续下一个 Plan
+6. 汇总报告（所有 Plan 处理完毕后）：
    - 已完成的 Plan
    - 阻塞/跳过的 Plan 及原因
    - 需要在其他环境执行的 Plan（`blocked: env:...`）
    - 待确认的歧义/风险/决策点
    - 如需记录重要决策，写入 `memory-bank/decisions.md`
-8. **结束**：主循环终止
+7. **结束**：主循环终止
 
 ## Plan 规则
 
@@ -146,6 +150,7 @@
   - `Verification Gate`（must-pass）
 - **不允许中断任务**：Plan 中不应包含必然失败或依赖未确认的信息；未确认项必须在 `$brainstorming` 阶段解决后再产出 Plan
 - **验证必须可通过**：Plan 内验证应为当前阶段可通过的局部验证；需要集成验证的内容放入上层/集成 Plan
+- **执行入口唯一**：Plan 生成完成后，后续执行只能由主循环驱动；不得按 Plan 头部说明直接切换到 `$executing-plans` 或 `$subagent-driven-development`
 - 不因等待确认而中断可执行步骤；待确认事项在回复中列出
 - 每轮只处理一个 Plan
 - **小步快跑**：每个 Plan 应该可快速完成
@@ -174,7 +179,7 @@
 
 - **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式）
 - **待确认事项**：在回复中列出并等待确认
-- **进度留痕**：通过 `{{PLAYBOOK_SCRIPTS}}/plan_progress.py` 维护 `memory-bank/progress.md` 的 Plan 状态块（唯一权威）
+- **进度留痕**：通过 `{{PLAYBOOK_SCRIPTS}}/main_loop.py` 维护 `memory-bank/progress.md` 的 Plan 状态块（唯一权威）
 
 ### Git 操作
 
@@ -233,7 +238,7 @@
 - [ ] 相关测试通过（如有测试且未被豁免）
 - [ ] 换行符正确
 - [ ] 无语法错误
-- [ ] 已通过 `plan_progress.py` 记录 Plan 状态
+- [ ] 已通过 `main_loop.py finish` 写回 Plan 状态
 
 ---
 

templates/README.md

@@ -224,7 +224,7 @@ project/
 如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`，
 且不会被 `playbook.py` 覆盖。
 主循环会根据 `memory-bank/progress.md` 的 Plan 状态清单，
-自动选择第一个 pending 的 Plan，并要求通过 `scripts/plan_progress.py` 写入状态。
+通过 `scripts/main_loop.py claim/finish` 原子化领取 Plan 并写回状态。
 
 ### 示例：不跑测试的计划提示词
 
@@ -246,7 +246,7 @@ project/
 1) 先完成 brainstorming，并输出设计文档 `docs/plans/YYYY-MM-DD-<topic>-design.md`。
 2) 询问我“是否进入 `docs/plans/` 实施计划编写阶段”，确认后使用 writing-plans 生成实现计划。
 3) 实现计划内明确标注每步要改的文件与命令；验证步骤只包含可通过的局部验证，不包含测试。
-4) 执行计划并更新 `memory-bank/progress.md`。
+4) 执行计划时只走主循环，并通过 `docs/standards/playbook/scripts/main_loop.py claim/finish` 更新 `memory-bank/progress.md`。
 ```
 
 ### AGENTS.template.md
@@ -304,7 +304,7 @@ playbook/
 ├── templates/       # 本目录：项目架构模板 → 部署到 memory-bank/ 等
 └── scripts/
     ├── playbook.py        # 统一入口：vendor/sync_rules/sync_memory_bank/sync_prompts/sync_standards/...
-    └── plan_progress.py   # Plan 选择与进度记录
+    └── main_loop.py       # 主循环领取与状态写回
 ```
 
 ## 完整部署流程

templates/prompts/README.md

@@ -36,7 +36,7 @@ prompts/
     ↓
 生成计划 → $writing-plans skill → docs/plans/*.md
     ↓
-执行计划 → AGENT_RULES 主循环（留痕）
+执行计划 → AGENT_RULES 主循环（`main_loop.py claim/finish` 留痕）
     ↓
 代码评审（有 MR/PR 时）→ code-review.md
     ↓
@@ -45,7 +45,7 @@ prompts/
 沉淀提示词 → prompt-generator.md（可选）
 ```
 
-> **核心规则在 `AGENT_RULES.md`**，第三方 skills 负责规划，主循环负责执行和留痕。
+> **核心规则在 `AGENT_RULES.md`**，第三方 skills 只负责规划；执行与留痕必须走 `main_loop.py claim/finish`。
 
 ---