feat(main_loop): harden plan execution state

Validate required Plan Meta before claims, record claim ownership, and persist verification evidence on completion.

Document conditional skill triggers without adding them to automatic main-loop dispatch.
This commit is contained in:
csh
2026-05-29 15:42:03 +08:00
parent 3023aef8a0
commit eaa061fd2b
3 changed files with 528 additions and 34 deletions
+42 -7
View File
@@ -86,6 +86,22 @@
再更新 `progress.md` 上半部分摘要,并按主循环收尾要求归档当前
Plan 变更
### 条件触发 Skills
以下 skill 是额外能力,只在满足触发条件时使用,不改变主流程顺序,
也不由 `main_loop.py` 自动调度:
| Skill | 触发条件 | 负责范围 |
| ------------------ | -------------------------------------- | -------------------------------------- |
| `codebase-recon` | 架构、跨模块、重构、迁移或风险不明任务 | 代码库侦察、热点分析、影响面判断 |
| `brooks-audit` | 方案影响架构边界、模块职责或长期维护性 | 架构审查、结构风险识别 |
| `codebase-migrate` | 大规模迁移、多文件重构、API 替换 | 分批迁移、可审查 refactor、CI 验证节奏 |
| `brooks-review` | 代码类 Plan 完成后,归档前需要审查 | diff / PR 级代码审查 |
| `brooks-test` | 测试改动复杂,或需要确认测试质量 | 测试有效性、覆盖边界、断言质量审查 |
| `gitea-fix-ci` | Gitea Actions 失败 | 拉取 CI 日志、定位失败、形成修复计划 |
| `style-cleanup` | 代码实现后需要格式或 lint 收尾 | 格式化、lint cleanup,不改变语义 |
| `commit-message` | 需要提交或归档当前 Plan 改动 | commit message 生成与 staged diff 检查 |
### Plan 要求
- `Plan Meta` 必填,位于 Plan 头部 `---` 之后、Task 1 之前
@@ -135,16 +151,20 @@
```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \
-plans docs/superpowers/plans \
-progress memory-bank/progress.md
-progress memory-bank/progress.md \
-owner "<当前session或agent标识>"
```
该命令会在锁保护下串行完成三件事:
- 自动识别当前环境:`windows``linux``darwin`
- 校验 Plan 文件包含必需 `Plan Meta`
- 已有 `in-progress` 优先恢复
- 如无 `in-progress`,按 Plan 文件顺序选择第一个可执行 Plan:
`pending``blocked: env:<当前环境>:...`
- 将选中的 Plan 写成 `in-progress`
-`workflow-state` 写入 `claimed_by``claimed_at`,并清理上一轮
`verification`
这里的锁保护的是 `progress.md` 状态块更新,避免多个 session
同时读写时发生覆盖。
@@ -176,7 +196,8 @@ python {{PLAYBOOK_SCRIPTS}}/playbook.py \
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
-plan <plan> \
-status done \
-progress memory-bank/progress.md
-progress memory-bank/progress.md \
-verified "<本轮已通过的验证命令或证据>"
```
```bash
@@ -195,6 +216,17 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
-note "<原因>"
```
只读状态命令:
```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \
-plans docs/superpowers/plans \
-progress memory-bank/progress.md
```
`status` 只汇总 `pending``in-progress``done``blocked`
`skipped` 和当前 `workflow-state`,不得修改 `progress.md`
### Plan 场景下的执行上下文与隔离策略
- 本节仅适用于通过主循环领取并执行 Plan 的场景
@@ -235,11 +267,14 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
- Plan `done` 后必须完成当前 Plan 变更的归档/提交,然后才能继续领取下一个
Plan;归档方式由项目约定决定
- 收尾顺序:
1. 完成 Plan 约定验证
2. 运行 `main_loop.py finish -status done` 写回状态
3. 必要时更新 `progress.md` 上半部分摘要和相关 memory
4. 检查当前变更清单与差异
5. 只归档/提交当前 Plan 相关改动
1. 完成 Plan 约定验证
2. 运行 `main_loop.py finish -status done -verified "<证据>"`
写回状态
3. 必要时更新 `progress.md` 上半部分摘要和相关 memory
4. 检查当前变更清单与差异
5. 只归档/提交当前 Plan 相关改动
- 当前 Plan 相关改动包括但不限于:
- 本轮代码、配置、测试、模板改动
- 当前 Plan 文件(创建、补充、勾选 Task、记录结果等)