SuperBizAgent-java/devflow/projects/2026-07-21-single-react-evidence-semantic-guards/decisions.md

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？	evidence-driven	已解决
Q4	修复	首次 EvidenceGuard 失败允许如何修复，是否可重跑 Agent 或 Tool？	evidence-driven	已解决
Q5	语义	SemanticGuard 是否拥有 Tool、记忆、ReAct loop 或报告写作能力？	evidence-driven	已解决
Q6	重试	哪些 SemanticGuard 结果允许第二次 attempt？	evidence-driven	已解决
Q7	超时	单轮模型超时和 Run 取消如何终止后台调用？	evidence-driven	已解决
Q8	释放	三种 Fallback 能否包含 Draft、reason 或未验真来源？	evidence-driven	已解决
Q9	接口	阶段 5 是否切换公开入口或修改 SSE/持久化协议？	evidence-driven	已解决
Q10	验收	如何证明不存在隐式 Agent/repair/retry loop？	evidence-driven	已解决

Evidence-driven

结论	证据来源	是否已汇报用户
EvidenceGuard 只验证结构、引用和 canonical invocation 真实性，不判断 Analysis/Conclusion 的语义充分性。	ISS-014 4.3、阶段 5；glossary 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；Spring AI 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；RAG/log 以 agent_result 自带的稳定来源和范围为准。
• SemanticGuard 使用直接 ChatModel.call(Prompt)，不创建第二个 ReactAgent；模型调用由受控 Executor 执行，超时/取消时调用 Future.cancel(true)。
• Evidence repair 与 SemanticGuard 共用同一模型抽象，但各自拥有独立 prompt、严格输出类型和预算；repair 策略固定一次 attempt，不能嵌套 retry executor。
• Release use case 只在 EvidenceGuard 成功后调用 SemanticGuard；SUPPORTED 返回原 Draft 对象，所有其他路径只返回固定 SafeFallback。
• 不创建 ADR：这些是 ISS-014 已冻结架构的阶段实现，不产生新的难逆转跨项目决策。

OpenSpec Backfill

• 需进入 proposal/design/spec/tasks：EvidenceGuard 规则、Tool-specific snapshot、无 raw/ID 泄漏、repair 单次边界、SemanticGuard 隔离/预算/超时/重试、原样发布与三类 Fallback、L2/公开隔离。
• 不进入本阶段：公开 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；Diagnosis Agent 拥有报告语义，repair 只修 ID，SemanticGuard 只审查，release 只做二选一，数据所有权没有重叠。
• 最大运行风险是 provider 忽略 interrupt；design 要求 Future cancel、迟到 Token 记录和 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：SemanticGuard 两次技术 attempt 与 repair 一次 attempt 的装配边界。
• harness/core/RunCancellation.java：取消 callback 注册和 first-cancel 语义。
• service/ExecutorGatekeeperService.java：仅参考报告内部引用检查思想，不复用旧 Map/JPA/session DTO 或规则目录。

Technology Stack

• Jackson strict ObjectReader 解析 frozen Draft/Tool projections；Tool-specific adapter 生成 typed snapshot，不透传 JsonNode/raw response。
• 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；Semantic 总时限由 monotonic elapsed time 控制。
• 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：tasks 2.1-4.2，尚未实现模型边界、SemanticGuard、repair/release 和综合回归。
• 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；SemanticGuard 输入不含 Tool Call ID、Redis key 或 raw response。
• 新增共享 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：SUPPORTED 原样返回 Draft；evidence failed、semantic unsupported/unavailable 均不返回 Draft、完整 snapshot 或审计 reason。
• 公开 Controller、ChatService、AiOpsService、SSE、JPA/Flyway 和旧多 Agent 链路无修改。

Apply Verification

• 编译：mvn -q -DskipTests compile 通过。
• 阶段 5 focused：EvidenceGuardTest 9、SemanticGuardTest 4、DiagnosisReleaseUseCaseTest 6，共 19 tests，0 failure/error。
• 综合回归：阶段 5 + Harness Core/Retry/Tool boundary/store/projections/contracts + Diagnosis Agent，共 18 suites / 70 tests，0 failure/error/skipped。
• 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 已冻结边界，没有新的跨项目难逆转决策。