@@ -0,0 +1,144 @@
# Decisions: single-react-evidence-semantic-guards
## Discover Status
- Checkpoint: Discover
- Capability source: `sm-flow` ，使用 `grill-with-docs` 做 evidence-driven 澄清；`codebase-retrieval` 、LSP 和 GitNexus MCP 在当前会话不可用，降级为既有 GitNexus 研究结论、`rg` 调用点核对和逐文件源码阅读。
- Scale: complex。变更跨 canonical store、三类 Tool projection、模型预算、超时/取消、结构修复、语义审查和释放边界，但不切换公开协议。
- `devflow/index.md` 命中阶段 0-4 的设计冻结、RunContext、canonical store、Tool projection 和 Diagnosis Agent；没有与当前 OpenSpec 冲突的 ADR。
## Question Pool
| # | 维度 | 问题 | 模式 | 状态 |
|---|---|---|---|---|
| Q1 | 术语 | EvidenceGuard 是否判断证据足以推出结论？ | evidence-driven | 已解决 |
| Q2 | 边界 | verified snapshot 能读取哪些 canonical 字段，并向 SemanticGuard 暴露哪些内容？ | evidence-driven | 已解决 |
| Q3 | 边界 | `NO_EVIDENCE` 能支持哪类 Analysis？
| Q4 | 修复 | 首次 EvidenceGuard 失败允许如何修复，是否可重跑 Agent 或 Tool？
| Q5 | 语义 | SemanticGuard 是否拥有 Tool、记忆、ReAct loop 或报告写作能力？ | evidence-driven | 已解决 |
| Q6 | 重试 | 哪些 SemanticGuard 结果允许第二次 attempt？
| Q7 | 超时 | 单轮模型超时和 Run 取消如何终止后台调用？ | evidence-driven | 已解决 |
| Q8 | 释放 | 三种 Fallback 能否包含 Draft、reason 或未验真来源？ | evidence-driven | 已解决 |
| Q9 | 接口 | 阶段 5 是否切换公开入口或修改 SSE/持久化协议？ | evidence-driven | 已解决 |
| Q10 | 验收 | 如何证明不存在隐式 Agent/repair/retry loop？
## Evidence-driven
| 结论 | 证据来源 | 是否已汇报用户 |
|---|---|---|
| EvidenceGuard 只验证结构、引用和 canonical invocation 真实性，不判断 Analysis/Conclusion 的语义充分性。 | ISS-014 4.3、阶段 5； `EvidenceGuard` | 已汇报 |
| Store 只能按 `ToolCallKeyFactory.create(runId, toolCallId)` 查找；可引用记录必须是当前 Run、`READY` 、含 `agent_result` 且状态为 `EVIDENCE_FOUND|NO_EVIDENCE` 。 | `CanonicalInvocationStore` 、`CanonicalToolInvocation.isReferencableBy` | 已汇报 |
| Snapshot 解析 `agent_result` 和必要的有界 request 字段，不读取 `raw_response` ；输出按 `analysis_id` 分组且不包含 Tool Call ID。 | ISS-014 4.4、10.2、已冻结 Tool contracts | 已汇报 |
| `NORMAL` 只绑定 `EVIDENCE_FOUND` ； `NEGATIVE_OBSERVATION` 只绑定 `NO_EVIDENCE` ，且零结果范围来自投影/请求。 | ISS-014 4.3、10.2； `EvidenceStatus` glossary | 已汇报 |
| Evidence repair 只在首次物理验真失败后执行一次无 Tool单轮模型调用，不重跑 Diagnosis Agent 或 Tool loop。 | ISS-014 10.3、阶段 5、重试边界决策 | 已汇报 |
| SemanticGuard 复用同一 `ChatModel` ，使用全新 `Prompt` 单轮调用，无 Tool/记忆/ReAct；只返回二元 verdict 和审计 reason。 | ISS-014 4.4、阶段 5； `ChatModel.call(Prompt)` | 已汇报 |
| 仅超时、传输、解析或 Schema 技术失败可重试一次；`UNSUPPORTED` 是有效业务结果，不重试。 | `HarnessRetryPolicies.strict().semanticGuard()` 、ISS-014 重试策略 | 已汇报 |
| `ChatResponseMetadata.Usage` 可复用 Core 的 model/Token 预算；受控 `Future.get(timeout)` 可在超时或 Run 取消时取消任务。 | `HarnessModelInterceptor` 、`DiagnosisHarnessCore` 、`RunCancellation` | 已汇报 |
| `EVIDENCE_VALIDATION_FAILED` 的来源必须为空；其余 Fallback 只能包含已验真来源，不包含 Draft 或 SemanticGuard reason。 | ISS-014 10.3、阶段 5； `SafeFallback` /`FallbackType` | 已汇报 |
| 阶段 5 只新增内部用例，公开入口切换留到阶段 6B。 | ISS-014 阶段顺序和 6B 门禁 | 已汇报 |
## User-interview
- 本阶段没有新增 user-interview 问题。上述方向、范围、修复次数、模型复用、超时/重试、Fallback 和阶段串行规则均已在 ISS-014 评审及前序对话中由用户确认。
## Key Decisions
- Snapshot 使用 Tool-specific adapter 严格解析冻结 projection；未知 Tool、ID 不一致、projection 反序列化失败或 projection 的 EvidenceStatus 与 canonical record 不一致均 fail closed。
- MySQL 的逻辑数据源和查询范围来自 canonical `request` ，行/列和值来自 `agent_result` ； `agent_result` 自带的稳定来源和范围为准。
- SemanticGuard 使用直接 `ChatModel.call(Prompt)` ，不创建第二个 `ReactAgent` ；模型调用由受控 Executor 执行，超时/取消时调用 `Future.cancel(true)` 。
- Evidence repair 与 SemanticGuard 共用同一模型抽象，但各自拥有独立 prompt、严格输出类型和预算；repair 策略固定一次 attempt，不能嵌套 retry executor。
- Release use case 只在 EvidenceGuard 成功后调用 SemanticGuard； `SafeFallback` 。
- 不创建 ADR：这些是 ISS-014 已冻结架构的阶段实现，不产生新的难逆转跨项目决策。
## OpenSpec Backfill
- 需进入 proposal/design/spec/tasks：
- 不进入本阶段：公开 Chat/SSE 装配、Run 持久化、旧多 Agent 删除和 live E2E。
## Cross-artifact Alignment
| 上游 -> 下游 | 检查内容 | 状态 |
|---|---|---|
| ISS-014/brief -> proposal | 物理验真、结构修复、隔离语义审查、固定 Fallback、阶段边界 | 已对齐 |
| proposal -> design | Store ownership、Tool-specific snapshot、timeout/cancel/retry、唯一报告作者和 L2 影响 | 已对齐 |
| design -> specs/tasks | 每个关键决策均有可观察 requirement 和对应实现/测试切片 | 已对齐 |
| specs -> tasks | 9 组 requirements 覆盖为 Evidence、model boundary、repair/release 和回归验证任务 | 已对齐 |
## Architecture Audit
- 能力来源：`zoom-out` ，使用 glossary 的 Diagnosis Harness、EvidenceGuard、SemanticGuard、RunContext、Invocation Status 和 Evidence Status 术语。
- 链路为 `query + Draft + RunContext -> EvidenceGuard/store -> optional repair/shared model boundary -> SemanticGuard/shared model boundary -> original Draft or fixed Fallback` ，没有外层 Graph 或第二个 Tool loop。
- Store 拥有物理调用记录，EvidenceGuard 只读并生成 snapshot； ，
- 最大运行风险是 provider 忽略 interrupt； `core.checkActive` 丢弃迟到结果，阶段 6A 再负责 Run 终态。
- 架构审计未发现与阶段 0-4 或 ADR 冲突；所有风险缓解已回写 design/spec/tasks。
## Interface Impact
- 级别：L2 内部接口。
- 变更对象：新增 guard/release records、interfaces、use cases、prompts 和 tests；现有方法签名不变。
- 消费者：本阶段只有 focused tests，阶段 6A 才接入 production application use case。
- 兼容性：公开 HTTP/SSE、Controller DTO、数据库、Redis key schema 和旧 Chat/AiOps 路径不变。
## Commit Gate Preflight
- proposal、design、specs、tasks 完整，`openspec status` 为 complete， `openspec validate single-react-evidence-semantic-guards --strict` 通过。
- Question pool 全部为已汇报的 evidence-driven 结论；无未确认 user-interview、接口等级或风险接受问题。
- Cross-artifact 四段对齐无 gap；架构审计的数据所有权、模型取消和唯一报告作者约束已进入 design/spec/tasks。
- 接口影响为 L2，仅新增内部 Java API；公开 Controller/SSE/JPA/Redis schema/旧 ChatService 保持不变。
- Apply、Archive 和阶段 Git commit 使用用户对 ISS-014 各阶段的持续授权；实现必须严格限制为 Committed OpenSpec。
- `.committed` 已创建，Committed OpenSpec 可进入 Apply。
## Pre-apply Research
### Reference Implementations
- `harness/tool/store/CanonicalInvocationStore.java` 、`CanonicalToolInvocation.java` 、`ToolCallKeyFactory.java` ：当前 Run 物理验真和 lifecycle 真理源。
- `harness/tool/projection/RagResultProjector.java` 、`QueryLogsResultProjector.java` 、`harness/tool/mysql/MysqlResultProjector.java` ：三类 `agent_result` 的唯一生产者和有界字段来源。
- `harness/agent/HarnessModelInterceptor.java` ：模型调用前预算、响应 Usage 记账和 late-result active check 模式。
- `harness/retry/HarnessRetryExecutor.java` 、`HarnessRetryPolicies.java` ：
- `harness/core/RunCancellation.java` ：取消 callback 注册和 first-cancel 语义。
- `service/ExecutorGatekeeperService.java` ：仅参考报告内部引用检查思想，不复用旧 Map/JPA/session DTO 或规则目录。
### Technology Stack
- Jackson strict `ObjectReader` 解析 frozen Draft/Tool projections；
- Spring AI `ChatModel.call(Prompt)` 执行无 Tool 单轮 guard； `ChatResponseMetadata.Usage` 接入现有 Core Token 预算。
- Java 17 `ExecutorService/Future.get(timeout)` 提供 per-attempt timeout， `Future.cancel(true)` 接入 Run cancellation；
- JUnit 5 scripted `ChatModel` 和 in-memory canonical store 作为外部边界 fake；测试只通过 EvidenceGuard/SemanticGuard/Release use case 公共接口断言行为。
- 无 Controller、MQ、JPA、Flyway 或新 Maven dependency；不需要新共享基础设施。
## Apply Progress
- 首模块对齐：EvidenceGuard typed contracts、Draft/reference checks、current-Run canonical validation 和 RAG/log/MySQL snapshot adapters 已完成，tasks 1.1-1.4 完成。
- 8 个 `EvidenceGuardTest` 行为测试通过；快照序列化不含 Tool Call ID 或 `raw_response` ， `NO_EVIDENCE` 仅在 `NEGATIVE_OBSERVATION` 下进入带 scope/zero-match 的快照。
- TODO：
- REVIEW 发现 corrupted Store key 下 record ID 可能与 Draft reference 不同；分类为代码偏离，已增加 exact canonical ID 校验和回归测试，无需改变规格方向。
- REVIEW 发现 fallback `DiagnosisReleaseResult` 携带完整 snapshot 会通过 `analysis_text` 间接泄漏 Draft；分类为规格安全边界细化，已回写 design/spec，并让 fallback result 强制使用空 snapshot，安全来源只保留在 `SafeFallback.verified_sources` 。
## Apply Result
- 新增确定性 EvidenceGuard：校验 typed Draft、唯一 Analysis ID、报告引用、exact current-Run Tool ID、READY lifecycle、agent result、Evidence Status 与 Analysis Kind，并严格展开 RAG/log/MySQL projection。
- verified snapshot 按 Analysis ID 分组，只含稳定 source/scope/timestamp/excerpt/values；
- 新增共享 `GuardModelCall` ：复用系统 ChatModel，执行 Core model/Token/Run byte budget、per-attempt timeout、total timeout、Future cancellation 和 late-result active check。
- 新增无 Tool/无记忆/无 ReAct 的单轮 SemanticGuard，严格解析 `SUPPORTED|UNSUPPORTED + reason` ；仅技术失败使用既有两次 attempt，业务 UNSUPPORTED 不重试。
- 新增一次 EvidenceRepair，只允许 ID/reference 修复；任何可见文本、kind、顺序、human-confirmation 或 limitations 变化都直接 Evidence fallback。
- 新增 DiagnosisReleaseUseCase 和固定 SafeFallbackFactory： ；
- 公开 Controller、ChatService、AiOpsService、SSE、JPA/Flyway 和旧多 Agent 链路无修改。
## Apply Verification
- 编译：`mvn -q -DskipTests compile` 通过。
- 阶段 5 focused： `EvidenceGuardTest` 9、`SemanticGuardTest` 4、`DiagnosisReleaseUseCaseTest` 6，共 19 tests，
- 综合回归：阶段 5 + Harness Core/Retry/Tool boundary/store/projections/contracts + Diagnosis Agent，共 18 suites / 70 tests，
- OpenSpec： `openspec validate single-react-evidence-semantic-guards --strict` 通过。
- 静态范围：公开 Controller/ChatService/AiOpsService diff 为空；SemanticGuard 无 Tool ID/raw response/ReactAgent/StateGraph/ThreadLocal/手写 while；新 guard/release 包无业务 Agent loop。
- 仓库级 `openspec validate --specs --strict` 为 16 passed / 2 failed；失败仍是前序 `mysql-readonly-tool` 、`rag-log-projections` 的 scenario 标题格式，按计划阶段 7 统一修复。
- 未执行 live E2E：按 ISS-014 阶段门禁统一留到阶段 7。
## Archive Result
- 14/14 OpenSpec tasks 完成，`.archive-ready` 已创建。
- 主规格已同步至 `openspec/specs/single-react-evidence-semantic-guards/spec.md` ，新增 9 个 requirements。
- Change 已归档至 `openspec/changes/archive/2026-07-21-single-react-evidence-semantic-guards` 。
- `devflow/index.md` 和 ISS-014 阶段表已更新为阶段 0-5 archived，下一阶段为 6A。
- 未创建 ADR/compound knowledge：本阶段落实 ISS-014 已冻结边界，没有新的跨项目难逆转决策。
zhuyongxin