SuperBizAgent-java/openspec/changes/archive/2026-07-07-executor-v2-output-contract/proposal.md

Why

The current Chat Executor evidence contract still mixes diagnostic material with final user-facing prose through diagnosis_summary and user_facing_answer. This keeps the Executor in a "diagnose and narrate" mode, so unsupported details can be smuggled into the final answer before later Gatekeeper, Verifier V2, and Composer phases exist.

This first phase narrows Executor to structured diagnostic material only and adds a temporary safe rendering path so normal Chat responses do not expose raw Executor JSON while later phases are implemented.

What Changes

• BREAKING internal Agent contract: Chat Executor output changes from executor_evidence_v1 to executor_evidence_v2.
• Remove diagnosis_summary and user_facing_answer from the Chat Executor final JSON contract.
• Keep the existing structured arrays: claims, hypotheses, recommended_actions, and missing_info.
• Preserve claims[].evidence_bindings and current-session evidence attribution rules.
• Adjust runtime final-answer handling so a PASS result with V2 Executor output is rendered into readable Chinese from structured fields instead of returning raw JSON.
• Keep Planner, Verifier, Gatekeeper, retry behavior, database schema, and tool signatures unchanged in this phase.

Capabilities

New Capabilities

None.

Modified Capabilities

• chat-verifier-agent: The Executor evidence-attribution contract is tightened so V2 structured output no longer contains final-expression fields. Verifier still receives executor_final_answer as raw text and executor_structured_output when parseable.

Impact

• Affected prompt: src/main/resources/prompts/chat-executor-prompt.md.
• Affected runtime: ChatService PASS answer extraction/rendering for Executor V2.
• Affected parser boundary: VerifierInputHook should continue parsing JSON but must not treat schema validation as its own responsibility in this phase.
• Affected tests: ChatService sequential flow tests and VerifierInputHook parsing tests for V2 output without user_facing_answer.
• Interface impact: L4 for internal Agent output contract because fields are removed from Executor JSON; external HTTP/chat answer behavior must remain readable Chinese and must not expose raw JSON.