fix(runtime): align plan prompt output contract

Author: wynxing

internal/context/source_plan_mode.go

@@ -34,7 +34,7 @@ func (planModeContextSource) Sections(ctx context.Context, input BuildInput) ([]
 		if stage == "plan" {
 			noPlanHint := promptSection{
 				Title:   "Current Plan",
-				Content: "status: none\n\nNo current plan exists. You must create one by outputting a `plan_spec` + `summary_candidate` JSON before this turn ends.",
+				Content: "status: none\n\nNo current plan exists. You must create one before this turn ends by outputting a visible Markdown plan, followed by one compact `plan_spec` + `summary_candidate` JSON object inside an HTML comment.",
 			}
 			sections = append(sections, noPlanHint)
 		}

internal/context/source_plan_mode_test.go

@@ -50,6 +50,37 @@ func TestPlanModeSectionsReturnsWithoutPlanWhenNil(t *testing.T) {
 	}
 }
 
+func TestPlanModeSectionsNoCurrentPlanUsesHTMLCommentContract(t *testing.T) {
+	t.Parallel()
+
+	source := planModeContextSource{}
+	sections, err := source.Sections(context.Background(), BuildInput{
+		AgentMode:   agentsession.AgentModePlan,
+		PlanStage:   "plan",
+		CurrentPlan: nil,
+	})
+	if err != nil {
+		t.Fatalf("Sections() error = %v", err)
+	}
+	var currentPlanContent string
+	for _, section := range sections {
+		if section.Title == "Current Plan" {
+			currentPlanContent = section.Content
+			break
+		}
+	}
+	if currentPlanContent == "" {
+		t.Fatal("expected Current Plan section when plan stage has no current plan")
+	}
+	if !strings.Contains(currentPlanContent, "visible Markdown plan") ||
+		!strings.Contains(currentPlanContent, "inside an HTML comment") {
+		t.Fatalf("Current Plan hint = %q, want Markdown plus HTML comment JSON contract", currentPlanContent)
+	}
+	if strings.Contains(currentPlanContent, "outputting a `plan_spec` + `summary_candidate` JSON") {
+		t.Fatalf("Current Plan hint should not use old JSON-only wording: %q", currentPlanContent)
+	}
+}
+
 func TestPlanModeSectionsContextError(t *testing.T) {
 	t.Parallel()
 

internal/promptasset/assets_test.go

@@ -94,6 +94,12 @@ func TestPlanModePromptTemplates(t *testing.T) {
 		strings.Contains(PlanModePrompt("plan"), "must not be empty") {
 		t.Fatalf("expected plan prompt not to require execution todo ownership")
 	}
+	if strings.Contains(PlanModePrompt("plan"), "Only output a JSON object") {
+		t.Fatalf("expected plan prompt not to require JSON-only output")
+	}
+	if !strings.Contains(PlanModePrompt("plan"), "inside an HTML comment") {
+		t.Fatalf("expected plan prompt to require machine-readable JSON in an HTML comment")
+	}
 	if !strings.Contains(PlanModePrompt("plan"), "Do not create execution todos in plan mode") {
 		t.Fatalf("expected plan prompt to keep todos in build execution")
 	}

internal/promptasset/templates/context/plan_mode_plan.md

@@ -3,9 +3,9 @@ You are currently in the planning stage.
 - You may research, analyze, ask clarifying questions, and produce a plan.
 - Do not perform any write action in this stage.
 - Do not rewrite the current full plan unless the conversation clearly requires creating or replacing the plan itself.
-- **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 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 visible Markdown plan followed by one compact machine-readable JSON object containing `plan_spec` and `summary_candidate` inside an HTML comment. 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.
+- When explicitly creating or rewriting the current full plan, output the visible plan as Markdown first, then append the machine-readable JSON inside an HTML comment, not in a fenced code block.
 - `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`.

internal/runtime/planning.go

@@ -174,8 +174,9 @@ func decodePlanTurnOutput(jsonText string) (planTurnOutput, error) {
 
 // stripPlanningJSONObjectText 从原始回复中移除结构化 JSON，并尽量保留自然段落间距。
 func stripPlanningJSONObjectText(text string, candidate extractedPlanningJSONObject) string {
-	before := strings.TrimSpace(text[:candidate.Start])
-	after := strings.TrimSpace(text[candidate.End:])
+	start, end := planningJSONObjectRemovalRange(text, candidate)
+	before := strings.TrimSpace(text[:start])
+	after := strings.TrimSpace(text[end:])
 	switch {
 	case before == "":
 		return after
@@ -186,6 +187,28 @@ func stripPlanningJSONObjectText(text string, candidate extractedPlanningJSONObj
 	}
 }
 
+// planningJSONObjectRemovalRange 扩展结构化 JSON 的剥离范围，避免 HTML 注释外壳泄漏到可见计划正文。
+func planningJSONObjectRemovalRange(text string, candidate extractedPlanningJSONObject) (int, int) {
+	start := candidate.Start
+	end := candidate.End
+	if start < 0 || end < start || end > len(text) {
+		return candidate.Start, candidate.End
+	}
+
+	prefix := text[:start]
+	open := strings.LastIndex(prefix, "<!--")
+	if open < 0 || strings.TrimSpace(prefix[open+len("<!--"):]) != "" {
+		return start, end
+	}
+
+	suffix := text[end:]
+	closeOffset := strings.Index(suffix, "-->")
+	if closeOffset < 0 || strings.TrimSpace(suffix[:closeOffset]) != "" {
+		return start, end
+	}
+	return open, end + closeOffset + len("-->")
+}
+
 // extractPlanningJSONObjectIfPresent 在文本中提取首个满足指定顶层键契约的 JSON 对象。
 func extractPlanningJSONObjectIfPresent(text string, requiredKey string) (extractedPlanningJSONObject, bool) {
 	start := strings.IndexByte(text, '{')

internal/runtime/planning_test.go

@@ -133,6 +133,29 @@ func TestMaybeParsePlanTurnOutputIgnoresBraceTextAndKeepsExplanation(t *testing.
 	}
 }
 
+func TestMaybeParsePlanTurnOutputStripsHTMLCommentJSON(t *testing.T) {
+	t.Parallel()
+
+	markdown := "### Goal\n\nShip plan display\n\n### Steps\n\n- Align prompts"
+	text := markdown + "\n\n<!-- {\"plan_spec\":{\"goal\":\"Ship plan display\",\"steps\":[\"Align prompts\"],\"constraints\":[\"Keep parser stable\"],\"open_questions\":[]},\"summary_candidate\":{\"goal\":\"Ship plan display\",\"key_steps\":[\"Align prompts\"],\"constraints\":[\"Keep parser stable\"]}} -->"
+	output, ok, err := maybeParsePlanTurnOutput(providertypes.Message{
+		Role:  providertypes.RoleAssistant,
+		Parts: []providertypes.ContentPart{providertypes.NewTextPart(text)},
+	})
+	if err != nil {
+		t.Fatalf("maybeParsePlanTurnOutput() error = %v", err)
+	}
+	if !ok {
+		t.Fatal("expected HTML comment plan JSON to be detected")
+	}
+	if output.PlanSpec.Goal != "Ship plan display" {
+		t.Fatalf("PlanSpec.Goal = %q", output.PlanSpec.Goal)
+	}
+	if output.DisplayText != markdown {
+		t.Fatalf("DisplayText = %q, want %q", output.DisplayText, markdown)
+	}
+}
+
 func TestMaybeParsePlanTurnOutputFallsBackWhenSummaryIsInvalid(t *testing.T) {
 	t.Parallel()