SuperBizAgent-java/devflow/projects/2026-07-17-chat-diagnosis-stategraph-design-freeze/decisions.md

# Chat Diagnosis StateGraph Design Freeze Decisions

## Question Pool

| # | 维度 | 问题 | 模式 | 状态 |
|---|---|---|---|---|
| Q1 | 术语 | Diagnosis Orchestration Trace 与 Diagnosis Trace、self evaluation、Graph checkpoint 的边界是什么？ | evidence-driven | 已解决 |
| Q2 | 边界 | ISS-011 是一个总 sm-flow，还是阶段 0–5 各自独立 sm-flow？ | user-interview | 已解决 |
| Q3 | 验收 | Maven E2E 在每阶段执行还是只在最终阶段执行？ | user-interview | 已解决 |
| Q4 | 验收 | 每阶段是否强制新增并运行单元测试？ | user-interview | 已解决 |
| Q5 | 技术 | 锁定的 StateGraph 版本是否提供条件边、config-aware Node/Edge、recursion limit 和 threadId？ | evidence-driven | 已解决 |
| Q6 | 架构 | Gatekeeper、Verifier 输入与 Composer 的可信材料边界应复用什么现有契约？ | evidence-driven | 已解决 |
| Q7 | 接口 | 阶段 0 本身和最终设计分别属于什么接口影响等级？ | evidence-driven | 已解决 |
| Q8 | 归档 | 每阶段是否应在进入下一阶段前独立 archive 和 Git commit？ | user-interview | 已解决 |

## Evidence-driven

| 结论 | 证据来源 | 是否已汇报用户 |
|---|---|---|
| Orchestration Trace 是 run 级紧凑编排摘要，不是事件日志、自评估或 Graph checkpoint | `devflow/glossary/CONTEXT.md`、ISS-011 §7.5、session-run-trace-isolation decisions | 已汇报 |
| Gatekeeper 从 Hook 迁为显式 Node 是有意替换旧内部架构，不允许双入口 | executor-gatekeeper-hook decisions、ISS-011 §2.3/§7.2/§14 | 已汇报 |
| Verifier verified evidence 必须来自 Gatekeeper 通过的 checked bindings；Composer 不得读取 raw Executor/tool output | verifier-evidence-reference-fidelity、executor-composer-final-answer 历史档案、ISS-011 §7.4 | 已汇报 |
| 本地 1.1.2.0 API 支持条件边、config-aware Node/Edge、recursion limit、RunnableConfig.threadId 和 ReactAgent.call(input, config) | Maven dependency tree 与本地 JAR `javap` 研究记录 | 已汇报 |
| 阶段 0 是文档/规格交付，无运行时接口变化；其冻结的最终目标涉及状态机、DB 和 Trace API，属于 L4 | sm-flow operating-rules、ISS-011 §10/§14 | 已汇报 |
| 主 OpenSpec 的外层 groundedness round、Hook Gatekeeper 和完整 tool_trace_summary 输入与冻结设计冲突 | `openspec/specs/chat-verifier-agent/spec.md` 等主规格 | 已汇报 |

## User-interview

| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
|---|---|---|---|
| ISS-011 的阶段关系如何映射 sm-flow？ | “iss-011里每个阶段，都是一个sm-flow，而不是将一整个iss-011打包进一个sm-flow中” | 已确认 | 已回写 proposal 范围与非目标 |
| Maven E2E 何时执行？ | “端到端只在最后阶段全部完成后才验证” | 已确认 | 已回写 acceptance 与 out of scope |
| 阶段单元测试是否强制？ | “每个阶段如果有必要添加单元测试验收的话，就加，没有必要的话就跳过单元测试” | 已确认 | 已回写 acceptance |
| 每阶段如何进入下一阶段？ | “每个阶段需要归档完并提交才能进入下一个阶段” | 已确认 | 已回写阶段门禁 |

## OpenSpec Input Context

### devflow index

已命中并读取：

- `session-run-trace-isolation`
- `executor-gatekeeper-hook`
- `verifier-evidence-reference-fidelity`
- `executor-evidence-output-contract`
- `executor-v2-output-contract`
- `executor-verifier-claim-checks`
- `executor-composer-final-answer`
- `mvp-demo-trace-acceptance`

### Historical constraints entering OpenSpec

- `runId` 是运行态和 Trace 的所有权边界。
- AgentStep、ToolInvocation 与 self evaluation 的既有 run 绑定必须保留。
- checked binding 是 verified evidence 的复用来源。
- Composer 的 allowed-material 安全边界不得削弱。
- 旧 Gatekeeper-in-Hook 决策在本设计中被显式废止，不能保留并行入口。
- 主 OpenSpec 的旧运行时要求只能在对应实现阶段修改，阶段 0 不提前宣称代码已切换。

## Key Decisions

### 六个独立交付单元

阶段 0–5 分别使用独立 slug、OpenSpec change、devflow 项目、Archive 和 Git commit。前一 change 归档并提交后才创建下一 change。

### 阶段 0 不承载后续实现

阶段 0 只冻结设计并归档长期上下文。阶段 1–5 的代码、数据库、测试和清理任务不进入本 change 的 tasks。

### 验收分层

阶段 0 没有运行时行为变化，不新增或运行单元测试，也不运行 Maven E2E。验收使用 OpenSpec strict validation、结构检查和文档一致性检查。Maven E2E、`logs/` 与数据库只在阶段 5 统一执行。

### 接口影响

- 当前 change：L1 文档/设计交付，不改变调用方可观察行为。
- 冻结目标：L4，涉及内部状态机语义、Trace API 加字段、数据库契约、迁移和回滚。
- 兼容：保持 `/api/chat` 和 Agent 输出协议；Trace API 为加法式 run 字段。
- 回滚：后续运行时代码可按阶段 Git revert；nullable DB 列可保留，不引入双轨配置。
- 消费者：ChatController/ChatService、Trace DTO/Service/UI/demo、数据库迁移、评测与运维审计。

## Risks Accepted

- 阶段 0 archive 后，冻结设计已完成但运行时仍为旧 Sequential；这是有意的阶段性状态。
- 六个 changes 的一致性由后续每次 context/commit gate 读取并审计本档案保证。
- 不为阶段 0 的纯设计变更新增无行为价值的单元测试。

## Cross-Artifact 对齐检查

| 上游 → 下游 | 检查内容 | 状态 |
|---|---|---|
| brief/prd → proposal | Issue 的阶段 0 目标、范围、非目标和验收已进入 proposal | 已对齐 |
| proposal → 设计产物 | 状态、路由、重试、Fallback、审计、测试迁移和六阶段边界均进入 design | 已对齐 |
| 设计产物 → specs/tasks | L4 影响、安全边界、终止规则和阶段 0 文档工作均进入 spec 或 tasks | 已对齐 |
| specs → tasks | 设计基线、源文档、ADR、严格验证和无运行时变更检查均有可执行任务 | 已对齐 |

Gap：无。

## Architecture Audit

输入链为 `ChatController -> ChatService`，目标处理链为 Run 生命周期 → Graph orchestrator → 白名单 Agent/Java Nodes，输出仍为 `ChatResult + DiagnosisRun + exact RunTrace`。Graph State 只属于当前 run，verified evidence 只来自当前 run 的 passed checked bindings，编排摘要只写当前 Diagnosis Run。旧“Gatekeeper stays in VerifierInputHook”决策被 ISS-011 的显式 Node 有意替代，但旧 Gatekeeper 规则本身继续复用；旧“不新增 trace 主表”和 run ownership 决策保持成立。主要耦合风险是 Hook/Node 双执行、阶段性主 spec 漂移和 Trace 投影重复，design 已分别通过单入口迁移、按阶段修改运行时 specs、唯一 `run.orchestrationTrace` 投影缓解。架构风险已由用户确认的 ISS-011 冻结决策和六阶段交付口径接受，无需返回 grill。

## Commit Preflight

- proposal、design、specs、tasks 完整：通过。
- 所有 user-interview 已确认：通过。
- 未汇报 evidence-driven 结论：无。
- L4 接口影响、消费者、兼容、迁移和回滚：已在 design 独立章节记录。
- OpenSpec strict validation：change 1/1 通过，主 specs 11/11 通过。
- Apply 授权：用户启动目标时要求分阶段完整执行、archive 和 Git commit，后续又确认六个独立 sm-flow；视为当前阶段连续执行授权。

## Apply Evidence

- Task 1.1：ISS-011 §3–14 与 committed design 的 State 字段、条件边、四类计数、Fallback、安全审计和测试迁移语义一致；未发现需回写 OpenSpec 的 drift，未修改运行时代码。
- Task 1.2：将 glossary 中新 Orchestration Trace 的具体 StateGraph/Graph State 表述收敛为“诊断编排/编排上下文快照”；Verifier 的 verified-output/evidence 名称作为跨节点协议保留。
- Task 2.1：创建 ADR-001，记录 StateGraph 控制边界、显式 Gatekeeper、run-scoped trace、替代方案、兼容、迁移和回滚。
- Task 2.2：六个独立 change 的唯一边界已写入 design、design-baseline spec、ADR 和根计划；阶段 1–5 必须引用阶段 0 archive。
- Task 3.1：最终 strict validation 为 change 1/1、主 specs 11/11；proposal/design/spec/tasks 对状态、Fallback、审计、运行时非目标和测试迁移均形成闭环，cross-artifact gap 为 0。
- Task 3.2：Git 枚举 12 个 changed/untracked 路径，运行时拒绝列表命中 0；无 `src/`、Maven、运行配置、脚本或数据库迁移变更。
- Task 3.3：单元测试未运行，因为阶段 0 无代码行为；Maven E2E、`logs/` 和数据库核验未运行，因为用户明确要求只在阶段 5 全部实现后统一执行。改造前 research baseline 不计入阶段验收。