docs(mvp): clarify executor v2 implementation issue

mvp/issues/executor-structured-output-v2.md

@@ -1,6 +1,6 @@
 # Executor Structured Output V2 可执行设计与实施 Issue
 
-**状态**：阶段三实施中  
+**状态**：阶段四待启动，前三阶段已归档并提交
 **严重程度**：高  
 **创建日期**：2026-07-07  
 **最后更新**：2026-07-08  
@@ -15,61 +15,147 @@
 
 ---
 
-## 0. 给后续实现 Agent 的执行入口
+## 0. 执行摘要
 
-这份文档是 `Executor Structured Output V2` 的可执行设计 issue，不是单纯的数据结构草案。后续 agent 接手时，先按本节确认背景、当前阶段、执行纪律和验收边界，再进入后面的字段契约。
+这份文档是 `Executor Structured Output V2` 的可执行设计 issue，用来指导后续 agent 按阶段实施，不是单纯的数据结构草案。
 
-### 0.0 当前接手快照
+后续 agent 接手时，应先读完本节，确认“为什么做、做到哪、下一步做什么、如何验收”，再进入后面的字段契约和 prompt 细节。
 
-截至 2026-07-08，阶段状态如下：
+### 0.0 这次改造要解决什么
+
+当前 Chat 复杂诊断链路中，Executor 已经会调用 `lookup_knowledge`、`query_metrics`、`query_logs` 等证据工具，但它在最终输出时容易把三类内容混在一起：
+
+1. 本轮工具真实返回的事实。
+2. runbook、skill、知识库里的通用模式。
+3. 模型基于经验补全的推断。
+
+这会导致 Executor 把“可能方向”写成“确认结论”，甚至在 `user_facing_answer` 中夹带未被 Verifier 校验过的根因、错误码、指标值或修复建议。Verifier 虽然会拦截一部分，但它被迫同时处理“事实抽取”和“事实校验”，职责边界不稳定。
+
+本 issue 的核心目标是切断这条风险链路：
+
+```text
+Executor 只负责收集证据并输出结构化材料；
+Gatekeeper 先用代码拦截物理级幻觉；
+Verifier 只判断 claim 是否能由证据合理推出；
+Composer 只根据 Verifier 允许的材料生成最终用户答案。
+```
+
+### 0.1 当前实现与目标链路
+
+当前复杂 Chat 链路：
+
+```text
+chat_planner -> chat_executor -> chat_verifier -> final answer
+```
+
+目标链路：
+
+```text
+chat_planner
+  -> chat_executor
+  -> VerifierInputHook 内 Gatekeeper
+  -> chat_verifier
+  -> chat_composer
+  -> final answer
+```
+
+本次不改 Planner，不新增 Controller，不改现有 retry 机制。改造重点只放在 Executor 输出契约、Gatekeeper 确定性校验、Verifier claim 可推导性校验、Composer 最终表达。
+
+### 0.2 当前接手快照
+
+截至 2026-07-08，仓库状态应以 `git status --short`、`openspec/changes` 和最近提交为准。当前已知阶段状态如下：
 
 | 阶段 | 状态 | 记录 |
 |---|---|---|
 | 阶段一：Executor V2 输出契约 | 已完成、已归档、已提交 | `050cbc8 feat(agent): add executor evidence v2 contract` |
 | 阶段二：Gatekeeper 接入 VerifierInputHook | 已完成、已归档、已提交 | `c5e496e feat(agent): add executor gatekeeper hook` |
-| 阶段三：Verifier V2 可推导性校验 | 实施中 | active change：`openspec/changes/executor-verifier-claim-checks` |
+| 阶段三：Verifier V2 可推导性校验 | 已完成、已归档、已提交 | `1b31e78 feat(agent): add verifier claim checks` |
-| 阶段四：Composer 输出最终答案 | 未开始 | 等阶段三归档并提交后再启动 |
+| 阶段四：Composer 输出最终答案 | 下一阶段，待启动 | 建议 change id：`executor-composer-final-answer` |
 | 阶段五：回归评测与审计闭环 | 未开始 | 等 Composer 链路稳定后补齐 |
 
 接手时的第一动作：
 
-1. 先运行 `git status --short`，确认是否已有阶段三未提交改动。
+1. 运行 `git status --short`，确认工作区是否干净。
-2. 如果 `openspec/changes/executor-verifier-claim-checks` 仍存在，继续阶段三，不要跳到 Composer。
+2. 运行 `Get-ChildItem openspec\changes`，确认是否存在未完成 active change。
-3. 阶段三完成后，必须先验证、归档 OpenSpec、回填 devflow、单独 commit，再进入阶段四。
+3. 如果没有 active change，下一步应创建阶段四 OpenSpec change：`executor-composer-final-answer`。
+4. 阶段四完成后，必须先验证、归档 OpenSpec、回填 devflow、单独 commit，再进入阶段五。
 
-推荐阅读顺序：
+### 0.3 推荐阅读顺序
 
-1. 先读 `0.1 - 0.10`：理解为什么要改、当前问题在哪里、目标链路是什么、哪些事情明确不做，以及如何按 OpenSpec/devflow 分阶段落地。
+1. 先读 `0A - 0I`：理解背景、问题、目标、范围、阶段和执行纪律。
-2. 再读 `20 - 25`：理解代码影响面、阶段拆分、每阶段验收、回滚策略和最终完成标准。
+2. 再读 `0.5 当前下一阶段执行卡片`、`19. Composer 设计`、`20. 当前代码影响面`、`21. 实施阶段`：理解当前下一阶段如何落地。
-3. 最后按需查阅 `2 - 19`：这些是实现时使用的详细数据契约、Gatekeeper 规则、Verifier/Composer 输入输出。
+3. 最后按需查阅 `2 - 18`：这些是已经讨论过的数据契约、Gatekeeper 规则和 Verifier 输入输出。
 
-一句话目标：
+### 0.4 阶段实施纪律
+
+后续实施必须按阶段串行推进：
 
 ```text
-把 Executor 从“诊断 + 表达”收敛为“证据收集 + 结构化事实输出”，
+阶段一 archive + commit
-在 Verifier 前加 Gatekeeper 做确定性拦截，
+  -> 阶段二 archive + commit
-让 Verifier 只判断 claim 是否能由证据合理推出，
+  -> 阶段三 archive + commit
-最终用户答案交给 Composer 生成。
+  -> 阶段四 archive + commit
+  -> 阶段五 archive + commit
 ```
 
 执行约束：
 
-- 必须按阶段实施，不允许把五个阶段揉成一个大改动。
 - 每个阶段都要先有 OpenSpec change，再实现、验证、归档到 devflow，并单独提交。
 - 阶段未归档、未提交前，不进入下一阶段。
-- 验收失败如果是代码问题，agent 自行修复；如果是设计决策不明确，停下来问用户。
-- 本 issue 不要求一次性完成所有阶段；后续 agent 应从当前 git/OpenSpec/devflow 状态继续推进。
-
-交付纪律：
-
 - 每个阶段只解决该阶段的问题，不顺手做下一阶段。
 - 每个阶段至少要有主成功路径和新增失败路径测试。
 - 提交前必须确认 diff 只包含当前阶段内容。
-- 不提交、不推送，除非用户明确要求；本 issue 默认只指导阶段实现和本地提交。
+- 验收失败如果是代码问题，agent 自行修复；如果是设计决策不明确，停下来问用户。
+- 不推送，除非用户明确要求。
+
+### 0.5 当前下一阶段执行卡片
+
+当前下一阶段是：
+
+```text
+阶段四：Composer 输出最终答案
+```
+
+建议 OpenSpec change id：
+
+```text
+executor-composer-final-answer
+```
+
+阶段四要做的事情：
+
+- 新增 `chat_composer` Agent 或等价 Composer 调用。
+- 新增 `chat-composer-prompt.md`。
+- 在 `ChatService` 中，Verifier 完成后组装 Composer 输入。
+- Composer 输入只能包含 Verifier 允许材料：`allowed_claims`、`allowed_hypotheses`、`missing_info`、`recommended_actions`、`rationale`。
+- PASS、LOW_CONFID、REJECT 的最终用户答案都不能再读取 Executor 的 `user_facing_answer`。
+- Composer 输出必须是严格 JSON，包含 `answer_summary`、`recommended_actions`、`user_facing_answer`。
+- Composer malformed 时必须走安全降级，不得向用户泄露 raw JSON 或 Executor 原文。
+
+阶段四明确不做：
+
+- 不改 Planner。
+- 不改 Gatekeeper 规则集。
+- 不扩展 Verifier 判定枚举。
+- 不新增数据库表。
+- 不让 Composer 调用工具。
+- 不让 Composer 重新判断根因。
+- 不提前做阶段五 eval fixture 大扩展。
+
+阶段四最小验收：
+
+- Composer 输入不包含 raw tool output。
+- 未通过 Verifier 的 claim 不进入最终答案。
+- `REJECT` 最终答案不出现根因结论，`allowed_hypotheses=[]`。
+- `LOW_CONFID` 最终答案区分已确认信息、可能方向和证据缺口。
+- `PASS` 只有在存在允许输出的 root cause claim 时，才表达根因已确认。
+- `ChatService` 不再依赖阶段一临时 V2 renderer 生成 PASS 用户答案。
 
 ---
 
-## 0.1 背景
+## 0A. 背景与问题定义
+
+### 0A.1 背景
 
 近期 Chat 复杂诊断链路中，多条诊断会话被 Verifier 判为 `LOW_CONFID`。这些会话并不是没有调用工具；Executor 通常已经调用了 `lookup_knowledge`、`query_metrics`、`query_logs` 等 evidence tools。
 
@@ -100,7 +186,7 @@ user_facing_answer
 
 ---
 
-## 0.2 当前问题定义
+### 0A.2 当前问题定义
 
 本 issue 要解决的是：
 
@@ -127,7 +213,7 @@ Executor 证据归因幻觉
 
 ---
 
-## 0.3 当前实现
+### 0A.3 当前实现
 
 当前代码中的复杂 Chat 链路是三 Agent 顺序执行：
 
@@ -163,7 +249,7 @@ Verifier 既要校验 structured output，又要扫描自然语言答案
 
 ---
 
-## 0.4 目标设计
+## 0B. 目标设计
 
 目标链路仍保持单条顺序链路，不新增 Controller，不改 Planner：
 
@@ -207,14 +293,14 @@ Executor raw JSON
 
 ---
 
-## 0.5 分阶段实施总览
+## 0C. 分阶段实施总览
 
 | 阶段 | 名称 | 目标 | 状态 | 退出条件 |
 |---|---|---|---|---|
 | 1 | Executor V2 输出契约 | 移除 Executor 最终表达字段，只输出结构化诊断材料 | 已完成并归档 | `executor_evidence_v2` 可运行，最终用户不再看到 raw JSON |
 | 2 | Gatekeeper 接入 VerifierInputHook | 在 Verifier 前加入确定性拦截与审计 | 已完成并归档 | `gatekeeper_result` 进入 Verifier payload 和 `self_evaluation` |
-| 3 | Verifier V2 可推导性校验 | 从 `facts_checked` 转向 `claim_checks`，判断 claims 是否可由证据推出 | 实施中 | Verifier 不再从自然语言答案抽取额外事实 |
+| 3 | Verifier V2 可推导性校验 | 从 `facts_checked` 转向 `claim_checks`，判断 claims 是否可由证据推出 | 已完成并归档 | Verifier 不再从自然语言答案抽取额外事实 |
-| 4 | Composer 最终表达 | 由 Composer 根据 Verifier 允许材料生成最终用户答案 | 未开始 | PASS/LOW_CONFID/REJECT 都不读取 Executor `user_facing_answer` |
+| 4 | Composer 最终表达 | 由 Composer 根据 Verifier 允许材料生成最终用户答案 | 下一阶段 | PASS/LOW_CONFID/REJECT 都不读取 Executor `user_facing_answer` |
 | 5 | 回归评测与审计闭环 | 用测试和 eval fixtures 证明幻觉拦截链路有效 | 未开始 | 伪造 ID、张冠李戴、hypothesis 写成事实等场景都有回归覆盖 |
 
 更详细的实施拆解见 `21. 实施阶段`。
@@ -229,11 +315,11 @@ Executor raw JSON
   -> 阶段五 archive + commit
 ```
 
-不能在阶段三未归档提交时启动 Composer，也不能在 Composer 未稳定时把回归评测阶段提前做成大杂烩。
+不能在 Composer 未稳定时把回归评测阶段提前做成大杂烩。
 
 ---
 
-## 0.6 范围与非目标
+## 0D. 范围与非目标
 
 ### In scope
 
@@ -258,7 +344,7 @@ Executor raw JSON
 
 ---
 
-## 0.7 关键设计决策
+## 0E. 关键设计决策
 
 | 决策 | 结论 | 原因 |
 |---|---|---|
@@ -272,7 +358,7 @@ Executor raw JSON
 
 ---
 
-## 0.8 实现约束
+## 0F. 实现约束
 
 实现时必须遵守：
 
@@ -285,7 +371,7 @@ Executor raw JSON
 
 ---
 
-## 0.9 OpenSpec / devflow 落地要求
+## 0G. OpenSpec / devflow 落地要求
 
 这个 issue 后续按 OpenSpec-first 的方式实施。每个阶段都必须留下可审计痕迹：
 
@@ -334,7 +420,7 @@ cmd /c openspec validate --specs
 
 ---
 
-## 0.10 推荐实现切片
+## 0H. 推荐实现切片
 
 建议不要把所有改动塞进一个大 PR。推荐拆成以下可独立验收的切片：
 
@@ -350,7 +436,7 @@ cmd /c openspec validate --specs
 
 ---
 
-## 0.11 为什么这样拆阶段
+## 0I. 为什么这样拆阶段
 
 本 issue 的改造目标不是一次性重写 Chat 诊断链路，而是逐步切断“证据不足但自然语言先下结论”的通道。阶段拆分按风险来源分层：
 
@@ -1452,9 +1538,9 @@ Composer 输出严格 JSON。
 
 ---
 
-## 20. 当前代码影响面
+## 20. 代码影响面
 
-本 issue 按当前三 Agent 实现增量落地，不改 Planner，不引入 Controller。
+本 issue 按当前三 Agent 实现增量落地，不改 Planner，不引入 Controller。本节描述整体改造影响面；已完成阶段见 `21. 实施阶段`，当前下一步以阶段四 Composer 为准。
 
 | 模块 | 当前职责 | 本次改动 |
 |---|---|---|
@@ -1510,7 +1596,7 @@ Composer 输出严格 JSON。
 已知阶段性债务：
 
 - `ChatService` 仍有临时 V2 renderer，用于 Composer 上线前避免 raw JSON 外泄。
-- Verifier 仍以 `facts_checked` 为主，`claim_checks` 等待阶段三。
+- Composer 上线后需要移除或降级阶段一临时 V2 renderer，避免 PASS 答案继续绕过 Composer。
 
 ### 阶段二：Gatekeeper 接入 VerifierInputHook
 
@@ -1572,19 +1658,13 @@ cmd /c openspec validate --specs
 
 ### 阶段三：Verifier V2 可推导性校验
 
-状态：实施中。
+状态：已完成并归档。
 
-当前 OpenSpec change：
+已完成记录：
 
-```text
+- OpenSpec archive：`openspec/changes/archive/2026-07-07-executor-verifier-claim-checks`
-openspec/changes/executor-verifier-claim-checks
+- devflow：`devflow/projects/2026-07-07-executor-verifier-claim-checks`
-```
+- commit：`1b31e78 feat(agent): add verifier claim checks`
-
-接手说明：
-
-- 如果该 active change 仍存在，继续完成阶段三，不要启动阶段四。
-- 阶段三已有 OpenSpec proposal/design/spec/tasks，后续实现应先对照 `tasks.md` 逐项完成。
-- 阶段三完成后必须 archive、回填 devflow、单独 commit，推荐提交信息：`feat(agent): add verifier claim checks`。
 
 目标：Verifier 不再逐字扫描自然语言，而是校验 claim 是否能由证据合理推出。
 
@@ -1621,7 +1701,6 @@ openspec/changes/executor-verifier-claim-checks
 
 ```powershell
 mvn "-Dtest=ExecutorGatekeeperServiceTest,VerifierInputHookTest,ChatServiceSequentialAgentTest" test
-cmd /c openspec validate executor-verifier-claim-checks
 cmd /c openspec validate --specs
 ```
 
@@ -1636,7 +1715,13 @@ cmd /c openspec validate --specs
 
 ### 阶段四：Composer 输出最终答案
 
-状态：未开始。
+状态：下一阶段，待启动。
+
+建议 OpenSpec change：
+
+```text
+openspec/changes/executor-composer-final-answer
+```
 
 目标：把最终用户表达从 Executor 中移出，由 Composer 基于 Verifier 允许的材料生成。
 
@@ -1655,6 +1740,21 @@ cmd /c openspec validate --specs
 - ChatService 负责根据 `claim_checks` 过滤出 `allowed_claims`。
 - `overstated` claim 不得作为确认事实输出，可降级为 hypothesis 或 missing_info。
 
+建议 OpenSpec 内容：
+
+- `proposal.md`：说明为什么需要 Composer，重点写清“最终表达不能再读 Executor 输出”。
+- `design.md`：说明 Composer 输入过滤、输出解析、malformed fallback、审计落点。
+- `specs/.../spec.md`：补充 Composer 最终答案的行为场景，能力归属可沿用现有 `chat-verifier-agent` 或新增更合适的 capability，但必须保持命名清晰。
+- `tasks.md`：按 prompt、ChatService 组装、输出解析、审计、测试、归档拆任务。
+- `decisions.md`：记录 PASS/LOW_CONFID/REJECT 的降级策略和 Composer 失败 fallback。
+
+建议代码入口：
+
+- `src/main/resources/prompts/chat-composer-prompt.md`
+- `src/main/java/com/superbiz/agent/service/ChatService.java`
+- `src/test/java/com/superbiz/agent/service/ChatServiceSequentialAgentTest.java`
+- 如需要新增专门测试，可新增 Composer 输入过滤或输出解析的 focused test。
+
 验收标准：
 
 - Composer 输出严格 JSON，包含 `answer_summary`、`recommended_actions`、`user_facing_answer`。
@@ -1672,11 +1772,22 @@ cmd /c openspec validate --specs
 - `REJECT` 不输出 root cause 结论。
 - Composer malformed 输出时有降级策略，不向用户泄露 raw JSON。
 
+建议验证命令：
+
+```powershell
+mvn "-Dtest=ChatServiceSequentialAgentTest" test
+cmd /c openspec validate executor-composer-final-answer
+cmd /c openspec validate --specs
+```
+
 阶段退出条件：
 
 - 最终用户答案唯一来源是 Composer 或固定降级模板。
 - Executor 的 `user_facing_answer` 不再参与任何最终答案路径。
 - Stage 1 的临时 renderer 被移除或明确只作为关闭 Composer 时的安全降级，不恢复 Executor 表达。
+- OpenSpec change 已 archive。
+- devflow 已回填 brief、evidence、decisions、acceptance。
+- 本阶段代码和文档已单独 commit。
 
 ### 阶段五：回归评测与审计闭环