fix(runtime): 调整 Plan/Build Todo 语义 (#659)

Author: wynxing

docs/session-todo-design.md

@@ -58,3 +58,10 @@
 - `Todo` 是更细粒度的结构化执行状态
 - `Todo` 不直接拼入模型消息历史
 - 如需让 `TaskState` 汇总 Todo，应在 runtime/context 层显式投影，而不是复用同一个字段
+
+## 与 Plan Mode 的关系
+
+- `CurrentPlan` 是计划上下文，表示 plan 模式产出的草案或已批准计划
+- `Session.Todos` 是 build 模式的执行进度状态，不由 plan 模式自动创建或维护
+- plan 模式只能研究、澄清和产出计划；即使计划正文包含旧版 `plan_spec.todos`，runtime 也不会把它自动灌入 `Session.Todos`
+- build 模式开始复杂执行且没有当前 Todo State 时，应通过 `todo_write action="plan"` 或 `todo_write action="add"` 显式创建本轮执行 todo

internal/promptasset/assets_test.go

@@ -89,8 +89,12 @@ func TestPlanModePromptTemplates(t *testing.T) {
 		})
 	}
 
-	if !strings.Contains(PlanModePrompt("plan"), "summary_candidate.active_todo_ids") {
-		t.Fatalf("expected plan prompt to require active todo ownership")
+	if strings.Contains(PlanModePrompt("plan"), "summary_candidate.active_todo_ids") ||
+		strings.Contains(PlanModePrompt("plan"), "must not be empty") {
+		t.Fatalf("expected plan prompt not to require execution todo ownership")
+	}
+	if !strings.Contains(PlanModePrompt("plan"), "Do not create execution todos in plan mode") {
+		t.Fatalf("expected plan prompt to keep todos in build execution")
 	}
 	if !strings.Contains(PlanModePrompt("build_execute"), "create current-run required todos") {
 		t.Fatalf("expected build prompt to require direct-build todo bootstrap")

internal/promptasset/templates/context/plan_mode_build_execute.md

@@ -4,7 +4,7 @@ You are currently in build execution.
 - If a current plan summary is attached, use it as guidance by default.
 - If the summary is insufficient for the current task, consult the attached full plan view when available.
 - If no current plan is attached, continue using task state, todos, and the conversation context.
-- If no current plan and no Todo State are attached, create current-run required todos with `todo_write` before the first substantive tool call for project analysis, documentation writing, code changes, multi-step debugging, or verification work.
+- If no Todo State is attached, create current-run required todos with `todo_write` before the first substantive tool call for project analysis, documentation writing, code changes, multi-step debugging, or verification work.
 - Do not update or complete todo IDs that are not present in the current Todo State; create new current-run todos instead.
 - Small necessary deviations are allowed, but explain why they are needed.
 - Do not create or rewrite the current full plan in this stage.

internal/promptasset/templates/context/plan_mode_plan.md

@@ -6,9 +6,7 @@ You are currently in the planning stage.
 - **If no Current Plan section is attached, your first priority is to produce a plan.** The user has entered planning mode expecting a structured plan. Research the codebase as needed, then output a complete `plan_spec` + `summary_candidate` JSON. Do not end the turn with only a conversational answer when there is no existing plan.
 - If a Current Plan is already present, you may refine, replace, or discuss it. When the user asks a clarifying question or wants to explore options without committing to a new plan revision, you may answer conversationally without outputting planning JSON.
 - Only output a JSON object containing `plan_spec` and `summary_candidate` when you are explicitly creating or rewriting the current full plan.
-- `plan_spec` must include `goal`, `steps`, `constraints`, `todos`, and `open_questions`.
-- `plan_spec.todos` **must not be empty**. Populate it with the major actionable items that the plan requires. Each todo must have a unique `id`, a descriptive `content`, and `status: "pending"`. Without todos the plan has no executable work items and the build stage cannot proceed.
-- `summary_candidate` must include `goal`, `key_steps`, `constraints`, and `active_todo_ids`.
-- If a Todo State section is attached, decide which non-terminal todos still belong to the current plan.
-- Todos that still belong to the current plan must appear in `plan_spec.todos` and their IDs must appear in `summary_candidate.active_todo_ids`.
-- Todos that do not belong to the current plan must not be copied into the new plan; create replacement plan-owned todos when ongoing work is still needed.
+- `plan_spec` must include `goal`, `steps`, `constraints`, and `open_questions`.
+- `plan_spec.todos` is optional legacy data. Do not create execution todos in plan mode; build mode will create and maintain runtime todos when implementation starts.
+- `summary_candidate` must include `goal`, `key_steps`, and `constraints`.
+- If a Todo State section is attached, treat it as build execution progress only. Do not copy, rewrite, or complete those todos while planning.

internal/promptasset/templates/core/capabilities_plan.md

@@ -3,8 +3,8 @@ You are currently in plan mode. Write and edit tools are disabled. Only read and
 
 - Read and search files within the current workspace.
 - Run non-interactive shell commands for read-only inspection only.
-- Maintain explicit task state and todos via `todo_write`.
 - Ask clarifying questions when requirements are ambiguous or conflicting.
+- Produce or refine a plan, but do not create or update execution todos.
 - **Do not perform any write, edit, delete, or file mutation operations.** Use this stage only for research, analysis, and planning.
 
 ## Limitations

internal/runtime/planning.go

@@ -258,8 +258,6 @@ func buildPlanArtifact(current *agentsession.PlanArtifact, output planTurnOutput
 	return plan, nil
 }
 
-// applyCurrentPlanRevision 用新 revision 替换当前计划，并清理旧 revision 遗留的对齐状态。
-// resolvePlanDisplayText 优先保留模型对计划的额外说明文本，缺失时回退为规范计划正文。
 // resolvePlanDisplayText 优先保留模型对计划的额外说明文本，缺失时回退为规范计划正文。
 func resolvePlanDisplayText(output planTurnOutput, spec agentsession.PlanSpec) string {
 	display := strings.TrimSpace(output.DisplayText)
@@ -269,28 +267,11 @@ func resolvePlanDisplayText(output planTurnOutput, spec agentsession.PlanSpec) s
 	return strings.TrimSpace(agentsession.RenderPlanContent(spec))
 }
 
+// applyCurrentPlanRevision 用新 revision 替换当前计划，并清理计划对齐状态。
 func applyCurrentPlanRevision(session *agentsession.Session, plan *agentsession.PlanArtifact) bool {
 	if session == nil || plan == nil {
 		return false
 	}
-	// 新 revision 覆盖时，仅取消旧 plan 明确引用的非终态 todo
-	if oldPlan := session.CurrentPlan; oldPlan != nil && oldPlan.Revision < plan.Revision {
-		agentsession.CancelTodosByIDs(session.Todos, oldPlan.Summary.ActiveTodoIDs)
-	}
-	// 将 PlanSpec.Todos 中尚不存在于 session.Todos 的条目补入，
-	// 避免 plan 模式下模型后续通过 todo_write 引用这些 ID 时找不到。
-	for _, planTodo := range plan.Spec.Todos {
-		id := strings.TrimSpace(planTodo.ID)
-		if id == "" {
-			continue
-		}
-		if _, exists := session.FindTodo(id); exists {
-			continue
-		}
-		if err := session.AddTodo(planTodo); err != nil {
-			return false
-		}
-	}
 	session.CurrentPlan = plan
 	session.PlanApprovalPendingFullAlign = false
 	session.PlanCompletionPendingFullReview = false

internal/runtime/planning_test.go

@@ -459,6 +459,55 @@ func TestApplyCurrentPlanRevisionNilGuards(t *testing.T) {
 	}
 }
 
+func TestApplyCurrentPlanRevisionDoesNotMutateExecutionTodos(t *testing.T) {
+	t.Parallel()
+
+	session := agentsession.New("plan revision keeps execution todos")
+	session.Todos = []agentsession.TodoItem{
+		{ID: "todo-exec", Content: "current build work", Status: agentsession.TodoStatusInProgress, Revision: 1},
+	}
+	session.CurrentPlan = &agentsession.PlanArtifact{
+		ID:       "plan-1",
+		Revision: 1,
+		Status:   agentsession.PlanStatusDraft,
+		Spec: agentsession.PlanSpec{
+			Goal:  "old plan",
+			Steps: []string{"old step"},
+		},
+		Summary: agentsession.SummaryView{
+			Goal:          "old plan",
+			KeySteps:      []string{"old step"},
+			ActiveTodoIDs: []string{"todo-old-plan"},
+		},
+	}
+
+	next := &agentsession.PlanArtifact{
+		ID:       "plan-1",
+		Revision: 2,
+		Status:   agentsession.PlanStatusDraft,
+		Spec: agentsession.PlanSpec{
+			Goal:  "new plan",
+			Steps: []string{"new step"},
+			Todos: []agentsession.TodoItem{
+				{ID: "todo-plan-only", Content: "legacy plan todo", Status: agentsession.TodoStatusPending},
+			},
+		},
+		Summary: agentsession.SummaryView{
+			Goal:          "new plan",
+			KeySteps:      []string{"new step"},
+			ActiveTodoIDs: []string{"todo-plan-only"},
+		},
+	}
+
+	if !applyCurrentPlanRevision(&session, next) {
+		t.Fatal("expected plan revision to apply")
+	}
+	if len(session.Todos) != 1 || session.Todos[0].ID != "todo-exec" ||
+		session.Todos[0].Status != agentsession.TodoStatusInProgress {
+		t.Fatalf("expected execution todos to remain untouched, got %+v", session.Todos)
+	}
+}
+
 func TestApproveCurrentPlanValidationErrors(t *testing.T) {
 	t.Parallel()
 

internal/runtime/runtime_test.go

@@ -3954,6 +3954,9 @@ func TestServiceRunPlanModePersistsDraftPlan(t *testing.T) {
 	if saved.CurrentPlan.Status != agentsession.PlanStatusDraft {
 		t.Fatalf("Status = %q, want %q", saved.CurrentPlan.Status, agentsession.PlanStatusDraft)
 	}
+	if len(saved.Todos) != 0 {
+		t.Fatalf("expected plan mode not to create execution todos, got %+v", saved.Todos)
+	}
 	if saved.CurrentPlan.Spec.Goal != "为 runtime 引入 plan/build 模式" {
 		t.Fatalf("Goal = %q", saved.CurrentPlan.Spec.Goal)
 	}
@@ -4019,6 +4022,9 @@ func TestServiceRunPlanModeShowsExplanationTextOutsidePlanningJSON(t *testing.T)
 	if saved.CurrentPlan == nil || saved.CurrentPlan.Spec.Goal != "Preserve prose around planning JSON" {
 		t.Fatalf("expected current plan to be updated, got %+v", saved.CurrentPlan)
 	}
+	if len(saved.Todos) != 0 {
+		t.Fatalf("expected plan prose turn not to create execution todos, got %+v", saved.Todos)
+	}
 	if len(saved.Messages) != 3 {
 		t.Fatalf("message count = %d, want 3", len(saved.Messages))
 	}

internal/runtime/todo_bootstrap.go

@@ -10,13 +10,15 @@ const todoBootstrapRequiredReason = "todo_bootstrap_required"
 
 const todoBootstrapRequiredReminder = `[Runtime Control]
 
-todo_bootstrap_required: This build run has no current plan and no active todos.
+todo_bootstrap_required: This build run has no active todos.
 
 Before project analysis, documentation writing, code changes, multi-step debugging, or verification work, call todo_write with action=plan or action=add to create required todos for this run.
 
+If a Current Plan is attached, use it only as planning context. Create current-run execution todos explicitly instead of assuming plan steps already exist as todos.
+
 Do not update or complete old todo IDs that are not present in the current Todo State.`
 
-// maybeAppendTodoBootstrapReminder 在 direct build 缺少 plan/todo 时注入一次结构化提醒。
+// maybeAppendTodoBootstrapReminder 在 build 缺少执行态 todo 时注入一次结构化提醒。
 func (s *Service) maybeAppendTodoBootstrapReminder(ctx context.Context, state *runState) error {
 	if !shouldInjectTodoBootstrapReminder(state) {
 		return nil
@@ -36,25 +38,12 @@ func shouldInjectTodoBootstrapReminder(state *runState) bool {
 	if agentsession.NormalizeAgentMode(session.AgentMode) != agentsession.AgentModeBuild {
 		return false
 	}
-	if hasActivePlanForTodoBootstrap(session.CurrentPlan) || len(session.Todos) > 0 {
+	if len(session.Todos) > 0 {
 		return false
 	}
 	return true
 }
 
-// hasActivePlanForTodoBootstrap 判断当前 plan 是否仍可为 build 继承 todo 所有权。
-func hasActivePlanForTodoBootstrap(plan *agentsession.PlanArtifact) bool {
-	if plan == nil {
-		return false
-	}
-	switch agentsession.NormalizePlanStatus(plan.Status) {
-	case agentsession.PlanStatusDraft, agentsession.PlanStatusApproved:
-		return true
-	default:
-		return false
-	}
-}
-
 const planBootstrapRequiredReason = "plan_bootstrap_required"
 
 const planBootstrapRequiredReminder = `[Runtime Control]
@@ -65,7 +54,7 @@ Before research, analysis, or conversational response, you MUST complete the fol
 
 1. Research the codebase as needed using read-only tools.
 2. Output a JSON object containing "plan_spec" and "summary_candidate" that defines the current plan.
-3. plan_spec.todos must be non-empty — include major actionable items with unique IDs and status "pending".
+3. Focus plan_spec on goal, steps, constraints, and open_questions. Do not create execution todos in plan mode.
 
 Do not end this turn without producing a plan.`
 

internal/runtime/todo_bootstrap_test.go

@@ -38,7 +38,7 @@ func TestShouldInjectTodoBootstrapReminder(t *testing.T) {
 			want: true,
 		},
 		{
-			name: "active plan skips",
+			name: "active plan without execution todos injects",
 			state: runState{
 				session: agentsession.Session{
 					AgentMode: agentsession.AgentModeBuild,
@@ -49,7 +49,7 @@ func TestShouldInjectTodoBootstrapReminder(t *testing.T) {
 				userGoal:        "请分析项目并写文档",
 				planningEnabled: true,
 			},
-			want: false,
+			want: true,
 		},
 		{
 			name: "existing todo skips",