@@ -0,0 +1,117 @@
# Decisions: single-react-chat-application-usecase
## Discover Status
- Checkpoint: Discover
- Capability source: `sm-flow` + `grill-with-docs` ； `codebase-retrieval` 、LSP 和 GitNexus MCP 当前不可用，使用既有 GitNexus 结论、`rg` 引用核对和源码阅读降级。
- Scale: complex。跨模型路由、三类执行器、Run/session 生命周期、数据库 migration、PreviousTurn 和阶段 6B consumer boundary。
- `devflow/index.md` 命中阶段 0-5、session-run-trace-isolation、RAG contracts 和 release guards；无 ADR 冲突。
## Question Pool
| # | 维度 | 问题 | 模式 | 状态 |
|---|---|---|---|---|
| Q1 | 术语 | Chat Application Use Case 与 Controller、Harness、Agent 的职责边界是什么？ | evidence-driven | 已解决 |
| Q2 | 路由 | Router 输入、输出和可重试失败范围是什么？ | evidence-driven | 已解决 |
| Q3 | 路由 | Router 最终失败是否允许默认进入 Diagnosis？
| Q4 | 执行器 | 三种 intent 分别允许哪些模型和 Tool 行为？ | evidence-driven | 已解决 |
| Q5 | Knowledge | 单次 RAG 调用如何验证模型引用且不公开 Tool Call ID？
| Q6 | PreviousTurn | 上一回合的真理源、筛选条件和截断边界是什么？ | evidence-driven | 已解决 |
| Q7 | 生命周期 | 何时读取上一回合、创建当前 Run、记录 intent 和终态？ | evidence-driven | 已解决 |
| Q8 | 持久化 | diagnosis_run 需要新增哪些字段，哪些内部内容禁止进入 published_result？
| Q9 | 6B 边界 | 如何让 Controller 切换时不重写应用用例？ | evidence-driven | 已解决 |
| Q10 | 接口 | 数据库/内部接口影响等级和回滚要求是什么？ | evidence-driven | 已解决 |
| Q11 | 验收 | 如何证明原始 Query、sessionId/runId 和失败终态一致传播？ | evidence-driven | 已解决 |
## Evidence-driven
| 结论 | 证据来源 | 是否已汇报用户 |
|---|---|---|
| Controller 只负责协议；Application Use Case 拥有 session/run、routing、executor、persistence，
| Router 输入只含 query/last_intent/last_user_query，输出只允许三枚举；无 Tool/记忆/ReAct。 | ISS-014 4.5 | 已汇报 |
| timeout/transport/非法输出可重试一次；第二次失败返回安全入口错误，不进入 Diagnosis。 | ISS-014 重试策略、`HarnessRetryPolicies.intentRouter()` | 已汇报 |
| SYSTEM_CHAT 无 Tool； ；
| PreviousTurn 只来自同 Session 最近 `DIAGNOSIS + SUCCESS + published_result` ，不使用 Redis 历史。 | ISS-014 4.6 | 已汇报 |
| `PublishedResult` /`PreviousTurn` 已冻结为 query/conclusion/scope/limitations/source_documents，不含 Tool ID/raw/Draft/reason。 | 阶段 0 contracts、`PublishedResult` 、`PreviousTurn` | 已汇报 |
| 当前 `DiagnosisRun` /V011 尚无 intent/release_outcome/published_result，需要 V012 和 repository query。 | `DiagnosisRun.java` 、`V011__add_session_run_isolation.sql` | 已汇报 |
| 上一回合必须在保存当前 PENDING Run 前读取，否则 latest query 会命中当前请求。 | repository 当前 latest method + 生命周期顺序推导 | 已汇报 |
| 6B 需要 metadata/status/cancel，
## User-interview
- 无新增 user-interview。三类路由、数据库字段、PreviousTurn、失败语义、阶段边界和自动 Apply/Archive/commit 均由 ISS-014 与用户持续授权冻结。
## Key Decisions
- 在创建当前 Run 前读取 latest safe routing context 和 PreviousTurn，随后 `startRun -> persist RUNNING -> observer metadata -> route` 。
- Application output 使用 typed content union， ；
- Knowledge path 生成一次 direct canonical Tool Call ID（该路径没有框架 Tool Call），只调用 `lookup_knowledge` ，严格验证 `KnowledgeAnswerDraft` 的 exact call ID 和 document subset，再移除 ID 发布。
- 所有普通单轮模型调用复用阶段 5 的受控 `GuardModelCall` ，从而共享 Core 模型/Token/timeout/cancel 边界；不引入新模型路由。
- `PublishedResult` 仅在 Diagnosis SUCCESS 且 conclusion 非空时写入；Fallback/Failed/Cancelled/System/Knowledge 不生成 PreviousTurn 真理源。
- 数据库变更使用 V012 可前向迁移；回滚为先停止新应用用例，再删除新索引/列，不影响 V011 既有字段。
- 不创建 ADR：这些是 ISS-014 已冻结设计的落地，不是新的跨项目不可逆决策。
## OpenSpec Backfill
- 需进入 proposal/design/spec/tasks：路由隔离/重试、三执行器、original query、PreviousTurn filter/bounds、observer/cancel、Run terminal persistence、V012/L3、公开隔离。
- 非目标：Controller/SSE/前端切换、旧链路删除、live E2E。
## Cross-artifact Alignment
| 上游 -> 下游 | 检查内容 | 状态 |
|---|---|---|
| ISS-014/brief -> proposal | 三路由、previous turn、Run lifecycle、内部-only 和阶段 6B handoff | 已对齐 |
| proposal -> design | typed executors、observer、JPA/V012、异常/终态、L3 migration/rollback | 已对齐 |
| design -> specs/tasks | 每项所有权/安全边界均有可观察 requirement 和实现测试切片 | 已对齐 |
| specs -> tasks | 9 组 requirements 覆盖 Router/executors、store/policy、application、verification | 已对齐 |
## Architecture Audit
- 能力来源：`zoom-out` ，使用 Chat Session、Diagnosis Run、RunContext、Diagnosis Agent、EvidenceGuard、SemanticGuard 和 PublishedResult 术语。
- 链路为 `request -> application use case -> run store/router -> fixed executor -> Harness/Agent/Tool -> typed public content -> run finish` ；
- ChatRunStore 拥有 MySQL 映射，Core 拥有运行状态，Application 拥有 dispatch/终态，path executor 拥有单一路径行为；PreviousTurn policy 是唯一安全历史投影。
- 最大风险是 prior/current Run 顺序和 DB/lifecycle 双终态，design/tasks 已固定 prior read before start、single finish path 和 focused failure/cancel tests。
- V012 是 L3 additive schema；
## Interface Impact
- 级别：L3 database/collaboration interface。
- 新增 `diagnosis_run.intent/release_outcome/published_result` 和索引；修改 Entity/Repository，新增 internal application/store/output contract。
- 消费者：阶段 6B Controller/SSE adapter、MySQL/Flyway；旧 ChatService 在本阶段不消费新字段。
- 迁移/回滚：V012 nullable additive；回滚先切旧入口，再删除 index/columns。
## Commit Gate Preflight
- proposal、design、specs、tasks 完整，`openspec status` complete，
- Question pool 全部已解决并汇报，无 user-interview、未判级接口或未接受架构风险。
- Cross-artifact 四段对齐无 gap；
- Apply/Archive/commit 使用用户持续授权；公开协议和前端必须保持零 diff。
- `.committed` 已创建，可进入 Apply。
## Pre-apply Research
- `DiagnosisHarnessCore` /`RunContext` ：
- `GuardModelCall` /`HarnessRetryExecutor` ：单轮模型 timeout/usage 和 Router 两次 attempt。
- `HarnessEvidenceTools` /`RagToolResult` ：
- `DiagnosisAgentUseCase` /`DiagnosisReleaseUseCase` ：
- `DiagnosisRun` /`DiagnosisRunRepository` /`V011` ：现有 Run schema 和写入模式。
- `ChatService.ensureChatSession/startDiagnosisRun` ：只参考 session metadata/JPA 写法，不复用旧 routing、多 Agent 或 ThreadLocal。
- 技术栈：Spring AI direct Prompt、Jackson strict JSON、JPA repository、Flyway additive migration、protocol-neutral observer；无 MQ/新依赖。
## Apply Progress
- Router/System/Knowledge contracts 与 executors 已完成，tasks 1.1-1.4 完成。
- 5 个 `ApplicationExecutorsTest` 通过：同输入 retry、最终 routing failure、System direct call、Knowledge exact references/no ID、NO_EVIDENCE/model skip。
- TODO：
- REVIEW：修正 `JpaChatRunStore` 多构造器 Spring 注入歧义；prior/start/intent/finish 持久化异常统一为稳定 `RUN_PERSISTENCE_FAILED` ，并在安全完成时更新 ChatSession 活跃时间/消息对数。均为代码偏离修复，无需变更 OpenSpec。
- PublishedResult/JPA/V012、Diagnosis executor、protocol-neutral Run control 与总 ChatApplicationUseCase 已完成，tasks 2.1-3.4 完成。
- 13 个 stage 6A focused tests 通过；TODO 仅剩综合回归、static scope 和 OpenSpec verification。
- 综合回归曾在 `SemanticGuardTest.attemptTimeoutCancelsBothPermittedModelCalls` 出现负载相关失败。诊断确认生产代码对每次 timeout 均调用 `Future.cancel(true)` ，但第二个 Future 可能在任务线程启动前已取消，此时不存在可接收 interrupt 的线程。分类为测试假设偏差，不是 OpenSpec 或生产代码偏离；回归断言改为两次 TIMEOUT attempt、两次模型预算预留，以及至少一个已运行调用收到 interrupt。
## Final Review
- Stage 6A focused tests 与阶段 2-5 regression 共 18 suites / 76 tests， ；
- OpenSpec strict validation 通过；V012、Entity、Repository 的三个字段和 previous-turn filter 对齐。
- 公开 Controller、前端和 endpoint 零 diff；
- `PublishedResult` 只包含 `user_query/published_conclusion/scope/limitations/source_documents` ，负向序列化测试通过。
- 本阶段不运行 live E2E，按 ISS-014 门禁留到阶段 7。
zhuyongxin