Skip to content

fix: Build guard 不应将后续阶段计划项视为未完成构建任务 #247

Description

@ipad4

🔎 Existing issue check

  • I have searched the existing issues.

🎯 Affected area

Classic workflow runtime (domains/comet-classic, assets/skills/comet/scripts/)

📦 Comet version

0.4.0-beta.9

💥 Current behavior

Classic full workflow 的 Superpowers Plan 可能描述完整生命周期,包括 Build、Verify 和 Archive。Build 阶段完成时,Verify/Archive 项按语义应保持未勾选,等待后续阶段实际执行。

但当前 Build guard 的 planTasksAllDone() 会扫描整个 plan,并将所有匹配以下格式的行都视为构建任务:

^\s*- \[ \]

它不识别任务所属阶段。因此下面这种计划会阻止 Build → Verify:

## Build

- [x] 完成实现
- [x] 完成构建检查

## Verify

- [ ] 执行完整验证

## Archive

- [ ] 归档 change

执行:

comet guard sample-change build

会将 Verify 和 Archive 项报告为 Unfinished Superpowers plan tasks,即使所有真正的 Build 任务均已完成。

实际 workaround 只能是:

  • 提前错误地勾选尚未执行的后续阶段;或
  • 将 Verify/Archive 项改成普通列表,不再使用可追踪的复选框;或
  • 将完整生命周期拆成多个文档。

第一种会制造虚假完成记录,后两种会削弱计划的可追踪性。

✅ Expected behavior

Build guard 应只验证属于 Build 阶段的任务,不应要求 Verify、Archive 等未来阶段任务提前完成。

建议选择一种明确的阶段协议,例如:

  1. 为任务增加结构化阶段标记:
- [x] [build] 完成实现
- [ ] [verify] 执行完整验证
- [ ] [archive] 归档 change
  1. 或为计划定义稳定的 phase section/frontmatter,由解析器按当前阶段过滤。
  2. 或明确规定 Superpowers Plan 中的复选框只能表示 Build 任务,并让计划生成 Skill/模板自动把未来阶段写为非复选框;guard 报错也应说明该约束。

无论采用哪种方案,都不应迫使 Agent 将尚未执行的后续阶段标记为完成。

🔁 Steps to reproduce

  1. 创建一个 Classic full workflow change,例如 sample-change
  2. 完成 Open、Design,进入 Build,并在 .comet.yaml 中记录一个 Superpowers Plan。
  3. 确保 tasks.md 中的实现任务全部已勾选。
  4. 在 Plan 中加入已经完成的 Build 任务,以及尚未执行的 Verify/Archive 复选框:
## Build
- [x] 完成实现

## Verify
- [ ] 执行验证

## Archive
- [ ] 归档 change
  1. 记录成功的 Build check。
  2. 执行:
comet guard sample-change build
  1. 观察到 Build guard 因 Verify/Archive 复选框未完成而失败。
  2. 将未来阶段条目改为非复选框后再次执行,Build guard 才能通过。

🖥️ Environment

- OS: macOS
- Shell: zsh
- Node: 22.22.1
- Package manager: npm
- Install scope: global CLI with project workflow
- Skill language: zh
- Target AI platform(s): Codex-compatible Skills

📋 Logs or output

$ comet guard sample-change build
...
[FAIL] Superpowers plan all tasks checked
Unfinished Superpowers plan tasks:
<line>:- [ ] 执行验证
<line>:- [ ] 归档 change

🧩 Additional context

Related but not duplicate: #61 discusses that checkbox completion does not prove the corresponding implementation exists. This issue concerns a different problem: future-phase checkboxes are validly incomplete but are still treated as Build blockers.

Relevant current logic:

  • planTasksAllDone() scans every unchecked checkbox in the recorded plan.
  • guardBuildChecks() requires Superpowers plan all tasks checked before Build can transition to Verify.

Suggested regression cases:

  1. All Build tasks checked, Verify/Archive tasks unchecked → Build guard passes.
  2. Any Build task unchecked → Build guard fails and lists only Build blockers.
  3. Verify guard does not require Archive tasks to be completed.
  4. Unknown or missing phase metadata fails with an actionable compatibility message rather than silently assigning every task to Build.
  5. Existing Build-only plans remain backward compatible.

Metadata

Metadata

Assignees

Labels

questionFurther information is requested

Type

No type

Projects

Status
Todo

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions