docs(openspec): archive strengthen-plan-artifact and sync specs

- archive change 2026-08-31-strengthen-plan-artifact (key_files required + verification todos)
- sync new capabilities to main specs: plan-key-files, plan-verification-todos

Author: MrWangJustToDo

openspec/changes/archive/2026-08-31-strengthen-plan-artifact/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-31

openspec/changes/archive/2026-08-31-strengthen-plan-artifact/design.md

@@ -0,0 +1,69 @@
+## Context
+
+plan 产物机制目前有两个短板（对比 Claude Plan Agent / Grok workflows）：
+
+1. **`key_files` 可选**（`create-plan-tool.ts:24` `z.array(z.string()).optional()`）——plan 常常不带文件定位，executing 阶段 agent 需重新探索才知道动哪些文件。Claude Plan Agent 强制以 "Critical Files" 收尾，这正是 plan 能直接驱动 execute 的核心。
+2. **Verification 只在执行后一次性提交**——`complete_plan` 要求 `verificationResults[]`，但执行中途没有任何逐项跟踪；验证与执行脱节。
+
+现状代码：plan 域集中在 `packages/core/src/agent/plan/`，已有 `parseVerificationItemsFromText`（`plan-verification.ts:31`）可把 verification 文本解析为条目；TodoManager 提供 `update()`/`getItems()`/`getTitle()`，TodoItem 仅含 content/status/priority（无 evidence 字段）。`applyPlanArtifact`（`plan-mode-controller.ts:313`）统一 seed steps 为 plan todos。
+
+## Goals / Non-Goals
+
+**Goals:**
+- `create_plan`/`update_plan` 强制携带 `key_files`（非空），planning prompt 引导 3-5 个，executing prompt 强调先读
+- plan 应用时把 Verification checklist 项 seed 为 plan todos（与 steps 并列），执行中逐项勾选
+- `complete_plan` 门控保持现状（evidence-based），verification todos 仅作跟踪/提醒
+- 全部改动局限在 `packages/core/src/agent/plan/`，不碰 app/UI
+
+**Non-Goals:**
+- 不扩展 TodoItem 结构（不加 evidence 字段）
+- 不改变 `complete_plan` 门控语义（方案 A）
+- 不改 `## Plan` 文本 fallback 的硬校验（无法验证 key_files，靠 prompt 引导）
+- 不做 allowedPrompts 预批准、planWasEdited、版本化文件名（属后续 change）
+
+## Decisions
+
+### 1. `key_files` 必填：schema 校验 + prompt 引导双层
+
+**做法**：`create-plan-tool.ts` 把 `key_files` 从 `z.array(z.string()).optional()` 改为 `z.array(z.string()).min(1)`（字段仍用 `keyFiles` 传给 `applyStructuredPlan`）。planning prompt 明确要求"输出 3-5 个关键文件"。executing prompt 增加"先读 Key files 再动手"。
+
+**备选**：加运行时校验（类似 `isUsableVerification`）。→ 未采用：zod `.min(1)` 已足够，schema 层校验比手写运行时校验更简洁且自动带错误消息。`applyStructuredPlan` 内部无需再校验（schema 已挡），但可保留防御性判断。
+
+**fallback 路径**：`extract-plan.ts` 不解析 Key files 段，所以 `## Plan` 文本路径无法硬校验——由 planning prompt 引导，不报错（对应 spec 的 "Free-form plan text is guided, not hard-gated"）。
+
+### 2. Verification seed 成 todos：复用 seed 路径 + 来源标记
+
+**做法**：在 `seedTodosFromSteps` 中，除了 steps 之外，用 `parseVerificationItemsFromText(input.verification)`（或从 planMarkdown 解析）得到 verification 条目，追加为 plan todos。为了区分来源（步骤 vs 验证），给验证 todo 的 content 加统一前缀（如 `[verify] `），这样：
+- agent 在执行中能识别"这是验证项，跑完勾掉"
+- `maybeEnterRetro` 无需改逻辑（所有 plan todo 完成才进 retro，正好要求验证项也完成）
+- `applyDoneMarkers`（`[DONE:n]` 按序号）不受影响——验证 todo 追加在 steps 之后，序号映射保持 steps 优先
+
+**具体落点**：`seedTodosFromSteps` 目前 `todoManager.update(steps.map(...), PLAN_TODO_TITLE)`。改为 `update([...stepsTodoInputs, ...verificationTodoInputs], PLAN_TODO_TITLE)`。
+
+**verification 数据来源**：`applyPlanArtifact` 接收的 `planMarkdown` 已含 `**Verification:**` 段，用 `parseVerificationItemsFromPlanMarkdown`（`plan-verification.ts:54`）解析——它同时兼容工具输入和文本 fallback 路径。
+
+**备选**：Verification 用独立的 todo 标题/独立列表。→ 未采用：TodoManager 同一时间只有一个活动列表（`getTitle()`），独立列表需要额外的并行列表机制，改动面大且与 `maybeEnterRetro` 冲突。追加到同一 plan todos 列表并用前缀区分，是最小侵入方案。
+
+### 3. `complete_plan` 门控保持现状
+
+**做法**：不改 `gateCompletePlanVerification`。verification todos 勾选只反映"跑过并标记过"，`complete_plan` 仍要求结构化 `verificationResults`（item/passed/evidence）。prompt 在 executing 阶段引导"标记 Verification todo，并在 retro 提交完整 results"。
+
+**理由**：方案 A 明确不扩展 TodoItem（无 evidence 字段），若让门控读 todo 状态则丢失 evidence 维度，验证可信度反而下降。
+
+## Risks / Trade-offs
+
+- **验证 todo 与 steps todo 混在一个列表** → 用 `[verify]` 前缀区分 + executing prompt 说明；`maybeEnterRetro` 要求全完成正好把"验证项完成"纳入 retro 触发，符合目标。
+- **`[DONE:n]` 序号与验证 todo 的交互** → 验证 todo 追加在 steps 之后，`extractDoneSteps` 按 steps 数量解析，验证项靠 todo 工具标记而非 `[DONE]`；需在 executing prompt 说明。
+- **key_files 必填可能让模型在 fallback 场景困惑** → schema 错误消息 + planning prompt 明确"3-5 个关键文件"；update_plan 也走同一 schema，保持一致。
+- **旧 plan 无 Verification 段** → `parseVerificationItemsFromPlanMarkdown` 返回空数组，不追加验证 todo，行为与现状一致（`maybeEnterRetro` 正常）。
+- **验证 todo 被 agent 误当步骤** → 前缀 + prompt 措辞缓解；即便误标，`complete_plan` 门控仍是最终防线。
+
+## Migration Plan
+
+- 纯增量：`key_files` 必填只影响新写 plan；旧 plan 文件加载（`/plan load`）不校验 key_files，兼容。
+- 无数据迁移、无外部依赖、无配置变更。
+- 回滚：单个 commit 内 revert 即可（改动集中 plan 域）。
+
+## Open Questions
+
+- 验证 todo 前缀文案（`[verify]`）是否合适，或改用其他区分方式（如优先级/分组）——默认 `[verify]`，可后续调整。

openspec/changes/archive/2026-08-31-strengthen-plan-artifact/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+plan 产物的价值取决于它能否直接驱动执行、并在执行中逐项可证。当前 plan 有两个机制短板：(1) `key_files` 是可选的，plan 往往缺少文件定位，execute 阶段需重新探索；(2) Verification checklist 只在整个执行结束后由 `complete_plan` 一次性提交，验证与执行过程脱节，无法中途逐项证明进度。
+
+## What Changes
+
+- **关键文件强制（`key_files`）**：`create_plan` / `update_plan` 的 `key_files` 从可选改为必填（至少 1 个），planning prompt 要求输出 3-5 个关键文件，executing prompt 强调先读 Key files 再动手。`## Plan` 文本 fallback 无法硬校验，由 planning prompt 引导（不报错）。
+- **Verification seed 成 todos（方案 A）**：plan 应用时把 Verification checklist 项追加为 plan 的 todo（与 Steps 并列，标记来源），执行中 agent 逐项完成并勾选；`complete_plan` 门控保持不变（仍要求 `verificationResults[]` 逐项 + evidence），todo 勾选作为进度跟踪与强制提醒，不替代门控。
+- 无 breaking change：现有 plan 文件/会话兼容，`key_files` 缺省的旧文件加载仍可用（仅新写 plan 强制）。
+
+## Capabilities
+
+### New Capabilities
+
+- `plan-key-files`: plan 产物强制携带关键文件定位，planning/executing prompt 据此引导，使 plan 可直接驱动 execute 而无需重新探索。
+- `plan-verification-todos`: plan 的 Verification checklist 逐项 seed 为 todo，执行中逐项勾选跟踪，与 `complete_plan` 门控并存。
+
+### Modified Capabilities
+
+<!-- 无：现有 openspec/specs/ 下无 plan 相关 spec；本 change 新增以上两个 capability。 -->
+
+## Impact
+
+- `packages/core/src/agent/plan/create-plan-tool.ts` — `key_files` schema 必填 + 校验
+- `packages/core/src/agent/plan/plan-mode-controller.ts` — seed todos 时追加 verification 项；状态字段记录 verification 来源
+- `packages/core/src/agent/plan/plan-prompts.ts` — planning/executing prompt 措辞更新
+- `packages/core/src/agent/plan/plan-verification.ts` — 复用 `parseVerificationItemsFromText`（已有）
+- `packages/core/src/agent/todo-manager/` — 无需改动（复用 update 接口）
+- 影响范围：core 内 plan 域，不改 app/UI；无 API 破坏

openspec/changes/archive/2026-08-31-strengthen-plan-artifact/specs/plan-key-files/spec.md

@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: Plan authoring requires key files
+
+The system MUST require at least one key file when creating or updating a plan via `create_plan` or `update_plan`. The `key_files` input MUST be a non-empty array of file paths the plan will touch or rely on. Tool execute MUST reject empty or missing `key_files` without transitioning to ready.
+
+#### Scenario: create_plan rejects missing key files
+
+- **WHEN** the agent calls `create_plan` without any `key_files`
+- **THEN** the tool MUST fail validation or return an error without saving the plan or transitioning to ready
+
+#### Scenario: create_plan accepts key files
+
+- **WHEN** the agent calls `create_plan` with goal, steps, a non-empty `key_files` list, and a usable verification checklist
+- **THEN** the plan is saved with the Key files section present in the plan markdown and plan mode MAY enter ready
+
+### Requirement: Plan prompts enforce key-file-driven work
+
+While plan mode is active, dynamic prompts MUST instruct the agent to: (1) in planning, list 3-5 key files the plan will touch or rely on before calling `create_plan`; (2) in executing, read the plan's Key files first before editing, using them as file anchors for the work.
+
+#### Scenario: planning prompt requires key files
+
+- **WHEN** plan mode phase is `planning`
+- **THEN** the turn-context plan prompt MUST instruct the agent to output 3-5 key files as part of the plan
+
+#### Scenario: executing prompt mentions key files
+
+- **WHEN** plan mode phase is `executing`
+- **THEN** the turn-context plan prompt MUST instruct the agent to read the plan's Key files first before making changes
+
+### Requirement: Free-form plan text is guided, not hard-gated
+
+The `## Plan` markdown fallback path (no `create_plan` call) MUST NOT hard-fail when no Key files section is present, because only `create_plan`/`update_plan` can validate `key_files`. Planning guidance SHOULD still direct the agent to include a Key files list in free-form plan text.
+
+#### Scenario: free-form plan without key files still applies
+
+- **WHEN** the agent writes a `## Plan` section without a Key files list during planning
+- **THEN** the plan still applies and plan mode MAY enter ready, without a hard validation error

openspec/changes/archive/2026-08-31-strengthen-plan-artifact/specs/plan-verification-todos/spec.md

@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: Verification checklist items seed as plan todos
+
+When a plan is applied with a Verification section, the system MUST parse the Verification checklist items (via `parseVerificationItemsFromText`) and seed them as plan todos alongside the step todos. The todos MUST be distinguished as verification items (not steps) so execution can track each checklist item individually.
+
+#### Scenario: plan with verification seeds verification todos
+
+- **WHEN** a plan containing a Verification checklist is applied and the plan has todos seeded
+- **THEN** each parsed verification item MUST be present as a plan todo alongside the step todos
+
+#### Scenario: plan without verification seeds only steps
+
+- **WHEN** a plan with no Verification section is applied
+- **THEN** only step todos are seeded and no verification todos are added
+
+### Requirement: Executing prompt tracks verification todos per item
+
+While plan mode phase is `executing`, the turn-context plan prompt MUST instruct the agent to mark each Verification todo when its check is performed and passed, so verification progress is tracked incrementally during execution.
+
+#### Scenario: executing prompt mentions verification todos
+
+- **WHEN** plan mode phase is `executing` and the plan has verification todos
+- **THEN** the turn-context plan prompt MUST instruct the agent to run and mark each Verification todo with evidence before finishing
+
+### Requirement: complete_plan gating remains evidence-based
+
+The `complete_plan` gate MUST keep requiring structured `verificationResults` (item, passed, evidence) covering the plan Verification items, regardless of verification todo check state. Verification todos are a progress-tracking aid and MUST NOT replace the evidence-based gate.
+
+#### Scenario: complete_plan still needs evidence
+
+- **WHEN** all verification todos are checked but the agent calls `complete_plan` without covering `verificationResults` with evidence
+- **THEN** the tool MUST still reject completion as today
+
+#### Scenario: retro entered after verification todos complete
+
+- **WHEN** execution finishes and both step todos and verification todos are completed
+- **THEN** plan mode MAY enter retro as today (all todos completed triggers retro)

openspec/changes/archive/2026-08-31-strengthen-plan-artifact/tasks.md

@@ -0,0 +1,20 @@
+## 1. 关键文件强制（key_files required）
+
+- [x] 1.1 将 `create-plan-tool.ts` 中 `structuredPlanInputSchema` 的 `key_files` 从 `z.array(z.string()).optional()` 改为 `z.array(z.string()).min(1)`，并更新 describe 措辞（非空、计划将触及/依赖的文件）
+- [x] 1.2 在 `applyStructuredPlan`（`plan-mode-controller.ts`）中增加防御性检查：`keyFiles` 缺失/为空时返回错误 `Plan must include at least one key file`（schema 之外的兜底）
+- [x] 1.3 更新 `buildPlanModePlanningPrompt`：在 `create_plan` 工具参数说明中明确 `key_files` 必填，并引导输出 3-5 个关键文件
+- [x] 1.4 更新 `buildPlanModeExecutingPrompt`：增加"先读 plan 的 Key files（关键文件）再动手"的指示，使 key_files 成为执行的文件锚点
+
+## 2. Verification checklist seed 为 plan todos（方案 A）
+
+- [x] 2.1 在 `seedTodosFromSteps`（`plan-mode-controller.ts`）中解析 plan 的 Verification 段（复用 `parseVerificationItemsFromPlanMarkdown`），将各条目追加为 plan todos，与 steps 并列，并用统一前缀（如 `[verify] `）区分来源
+- [x] 2.2 保持 `maybeEnterRetro` 逻辑不变（所有 plan todos 含验证项完成才进 retro），确认 `applyDoneMarkers`（`[DONE:n]` 按 steps 序号）不受追加验证 todos 影响
+- [x] 2.3 更新 `buildPlanModeExecutingPrompt` 与 `buildPlanExecuteSteerMessage`：告知 agent 验证项已作为 todo 逐项标记，跑完勾选；retro 时仍提交 `verificationResults`（item/passed/evidence）
+- [x] 2.4 确认 `complete_plan` 门控（`gateCompletePlanVerification`）不变：verification todos 仅作跟踪/提醒，不替代 evidence-based 门控
+
+## 3. 验证
+
+- [x] 3.1 `pnpm build:core`（或受影响包构建）通过
+- [x] 3.2 `pnpm typecheck` 通过
+- [x] 3.3 `pnpm lint` 通过（含 ESLint import/order，Prettier 查不到的部分）
+- [x] 3.4 手动/脚本验证：`create_plan` 缺 `key_files` 被拒；带 verification 的 plan 应用后 todos 含验证项；旧 plan（无 Verification 段）不追加验证 todos

openspec/specs/plan-key-files/spec.md

@@ -0,0 +1,42 @@
+# plan-key-files
+
+Plan artifacts MUST carry key file anchors so execution can start from concrete file locations instead of re-exploring.
+
+## Requirements
+
+### Requirement: Plan authoring requires key files
+
+The system MUST require at least one key file when creating or updating a plan via `create_plan` or `update_plan`. The `key_files` input MUST be a non-empty array of file paths the plan will touch or rely on. Tool execute MUST reject empty or missing `key_files` without transitioning to ready.
+
+#### Scenario: create_plan rejects missing key files
+
+- **WHEN** the agent calls `create_plan` without any `key_files`
+- **THEN** the tool MUST fail validation or return an error without saving the plan or transitioning to ready
+
+#### Scenario: create_plan accepts key files
+
+- **WHEN** the agent calls `create_plan` with goal, steps, a non-empty `key_files` list, and a usable verification checklist
+- **THEN** the plan is saved with the Key files section present in the plan markdown and plan mode MAY enter ready
+
+### Requirement: Plan prompts enforce key-file-driven work
+
+While plan mode is active, dynamic prompts MUST instruct the agent to: (1) in planning, list 3-5 key files the plan will touch or rely on before calling `create_plan`; (2) in executing, read the plan's Key files first before editing, using them as file anchors for the work.
+
+#### Scenario: planning prompt requires key files
+
+- **WHEN** plan mode phase is `planning`
+- **THEN** the turn-context plan prompt MUST instruct the agent to output 3-5 key files as part of the plan
+
+#### Scenario: executing prompt mentions key files
+
+- **WHEN** plan mode phase is `executing`
+- **THEN** the turn-context plan prompt MUST instruct the agent to read the plan's Key files first before making changes
+
+### Requirement: Free-form plan text is guided, not hard-gated
+
+The `## Plan` markdown fallback path (no `create_plan` call) MUST NOT hard-fail when no Key files section is present, because only `create_plan`/`update_plan` can validate `key_files`. Planning guidance SHOULD still direct the agent to include a Key files list in free-form plan text.
+
+#### Scenario: free-form plan without key files still applies
+
+- **WHEN** the agent writes a `## Plan` section without a Key files list during planning
+- **THEN** the plan still applies and plan mode MAY enter ready, without a hard validation error

openspec/specs/plan-verification-todos/spec.md

@@ -0,0 +1,42 @@
+# plan-verification-todos
+
+Plan Verification checklist items MUST seed as plan todos so verification progress is tracked incrementally during execution, while the `complete_plan` gate stays evidence-based.
+
+## Requirements
+
+### Requirement: Verification checklist items seed as plan todos
+
+When a plan is applied with a Verification section, the system MUST parse the Verification checklist items (via `parseVerificationItemsFromText`) and seed them as plan todos alongside the step todos. The todos MUST be distinguished as verification items (not steps) so execution can track each checklist item individually.
+
+#### Scenario: plan with verification seeds verification todos
+
+- **WHEN** a plan containing a Verification checklist is applied and the plan has todos seeded
+- **THEN** each parsed verification item MUST be present as a plan todo alongside the step todos
+
+#### Scenario: plan without verification seeds only steps
+
+- **WHEN** a plan with no Verification section is applied
+- **THEN** only step todos are seeded and no verification todos are added
+
+### Requirement: Executing prompt tracks verification todos per item
+
+While plan mode phase is `executing`, the turn-context plan prompt MUST instruct the agent to mark each Verification todo when its check is performed and passed, so verification progress is tracked incrementally during execution.
+
+#### Scenario: executing prompt mentions verification todos
+
+- **WHEN** plan mode phase is `executing` and the plan has verification todos
+- **THEN** the turn-context plan prompt MUST instruct the agent to run and mark each Verification todo with evidence before finishing
+
+### Requirement: complete_plan gating remains evidence-based
+
+The `complete_plan` gate MUST keep requiring structured `verificationResults` (item, passed, evidence) covering the plan Verification items, regardless of verification todo check state. Verification todos are a progress-tracking aid and MUST NOT replace the evidence-based gate.
+
+#### Scenario: complete_plan still needs evidence
+
+- **WHEN** all verification todos are checked but the agent calls `complete_plan` without covering `verificationResults` with evidence
+- **THEN** the tool MUST still reject completion as today
+
+#### Scenario: retro entered after verification todos complete
+
+- **WHEN** execution finishes and both step todos and verification todos are completed
+- **THEN** plan mode MAY enter retro as today (all todos completed triggers retro)