SuperBizAgent-java/openspec/changes/archive/2026-07-27-diagnosis-information-gain-stop-contract/tasks.md

1. Tool Envelope 与进展状态契约

• 1.1 新增 InformationGain、collection state、stop reason、上一轮评价和三个强类型 Agent-facing Tool Envelope，并用序列化/Schema 测试固定 snake_case、必填项和非法枚举拒绝行为
• 1.2 在 ChatHarnessProperties 增加 stopAfterConsecutiveNoGain=2、正数校验和配置绑定测试，并在创建 Run 时固定阈值
• 1.3 实现线程安全 DiagnosisProgressTracker，覆盖 GAINED 清零、NO_GAIN 累加、待评价 ID 单次消费、错序拒绝、饱和状态和一次 STOP_REQUIRED 交付
• 1.4 为 RAG、日志和 MySQL 实现确定性 scope projector，覆盖相同参数去重、不同结构化 scope 放行和失败 scope 不进入成功去重集合

2. Canonical 双视图与 Tool 门禁

• 2.1 扩展 canonical RAG result 以兼容读取 relevanceLevel/relevance_level 并输出规范化 relevance_level，补充 REFERENCE 与空 evidence 回归测试
• 2.2 实现按 Tool 类型的 Harness Control View 和白名单 Model Observation projector，证明 returned count、内部指纹、raw score、预算和 raw response 不进入模型观察
• 2.3 将 HarnessEvidenceTools 的模型可见 Schema 切换为三个强类型 Envelope，同时保持 adapter bridge 只接收原业务 request JSON
• 2.4 重构 HarnessToolInterceptor，按“消费上一轮评价 -> 饱和门禁 -> scope 去重 -> ToolBoundary -> 记录结果”顺序执行，并覆盖 NO_EVIDENCE、REFERENCE、重复 scope、协议错误和 Tool ERROR
• 2.5 实现 STOP_REQUIRED 一次收尾机会和 DiagnosisCollectionStoppedException，用真实 scripted framework loop 证明忽略停止指令不会继续执行 Tool 或耗尽 Tool 预算

3. ProgressSnapshot 与 Agent 执行结果

• 3.1 让 tracker 有序索引当前 Run 已完成的 canonical identity，并实现 DiagnosisProgressProjector 逐条验证 READY/Run ownership 后生成有界 snapshot
• 3.2 覆盖 canonical 记录缺失、过期、PROJECTING、ERROR、跨 Run 和投影超限，确保它们只产生 limitation 而不成为 observed fact
• 3.3 将 DiagnosisAgentUseCase 返回值改为可选 Draft、ProgressSnapshot 和 stop reason，更新全部调用方并保留未分类框架异常 fail closed
• 3.4 让预算/取消异常在 cause chain 中保持可分类：预算可进入统一 Release，取消保持 CANCELLED，其他异常不得伪装为正常证据不足

4. 统一 Diagnosis Release

• 4.1 为无结论 Draft 增加确定性引用真实性/负向语义校验路径，证明它不调用 EvidenceRepair 或 SemanticGuard
• 4.2 扩展 SafeFallbackFactory，从 ProgressSnapshot 生成 INSUFFICIENT_EVIDENCE 或从 limitations.missing_info 生成 MISSING_REQUIRED_CONTEXT，复用现有 observed facts、sources、limitations 和 next steps
• 4.3 重构 DiagnosisReleaseUseCase，统一处理有结论 Draft、主动无结论、信息饱和、预算终止，并保留有结论时完整 EvidenceGuard/Repair/SemanticGuard 行为
• 4.4 更新 DiagnosisChatExecutor 与内部 result contract，使已处理的饱和/预算 Fallback 返回 Application 而不创建 PublishedResult
• 4.5 从 ChatApplicationUseCase 移除内容级预算 Fallback 决策，保留窄化的已处理预算终态持久化，并迁移现有预算耗尽测试意图
• 4.6 对最终 Draft 合同失败增加窄化降级：丢弃非法内容，仅在 ProgressSnapshot 含已验真 observed facts 时由 Release 生成 INSUFFICIENT_EVIDENCE，无安全进展仍 fail closed，并记录脱敏失败 Trace

5. Prompt、Trace 与配置装配

• 5.1 按最小中文契约重写 Diagnosis Prompt：合法放弃、零 Tool、missing_info、GAINED/NO_GAIN、禁止等价重试和服从 STOP_REQUIRED，且不写 Tool 名/Schema/阈值/next_action
• 5.2 增加有界 progress/stop Trace 事件，记录信息增益生产者、scope 摘要、collection state 和 stop reason，并用测试证明不记录 Prompt、thought、raw payload、SQL 参数或预算余量
• 5.3 更新 HarnessChatConfiguration 装配 tracker factory、scope/projector、ProgressSnapshot 和统一 Release 依赖，修复全部构造调用与 Spring context 测试

6. 验证与文档收口

• 6.1 运行 Tool contract、tracker、projector、interceptor、Agent loop、Guard、Release 和 Application focused tests，修复所有回归
• 6.2 运行 Harness 综合回归、mvn test 和 openspec validate diagnosis-information-gain-stop-contract --strict，记录命令与结果
• 6.3 用 Maven 启动真实应用，对“诊断切换企业失败的问题”执行 named SSE E2E，并从 logs/ 与 scripts/query_mysql.py 按 exact sessionId/runId 核对过程、停止原因、Tool 次数和 FALLBACK 内容
• 6.4 更新 ISS-016、架构文档、glossary 和 OpenSpec task 状态，核对公开 SSE/前端协议无新增字段且工作区原有无关修改未被覆盖

7. 模型 Token 与 Tool 拒绝审计补充

• 7.1 新增 Run 内模型调用组件/轮次账本和脱敏 Trace contract 测试，覆盖 Usage 可用、不可用、组件轮次和 Token 合计
• 7.2 将 Router、System Chat、Knowledge Answer、Diagnosis Agent、Evidence Repair 和 Semantic Guard 接入统一 Token 审计，并回填对应 AgentStep token_count
• 7.3 为进展协议错误、重复 scope、信息饱和和观察合同拒绝增加安全 TOOL_REQUEST_REJECTED Trace，证明不记录参数或原始响应
• 7.4 在 Run 完成时持久化 step_count 并记录 Token 总账/明细对账结果，补充 Store 和 Trace 回归测试
• 7.5 运行 focused、Harness 全量回归、strict validate 和真实 SSE/数据库 E2E，核对 Tool 执行/拒绝数量、Token 对账和 Trace 连续性

8. 协议修复反馈与兜底停止

• 8.1 为进展协议错误建模安全 violation_type，覆盖缺失 previous_observation、错序 Tool Call ID、意外 previous observation、缺失 input 和非法 Envelope
• 8.2 将 INVALID_PROGRESS_PROTOCOL observation 改为可修正响应，包含安全 repair hint、期望上一轮 Tool Call ID 和允许的 information_gain 值，不泄露业务参数或原始响应
• 8.3 为 Run tracker 增加连续协议错误计数和 PROGRESS_PROTOCOL_VIOLATED stop reason；未达阈值打回修正，达到阈值返回一次 STOP_REQUIRED
• 8.4 Release/Agent 受控停止路径支持 PROGRESS_PROTOCOL_VIOLATED：有安全 ProgressSnapshot 时发布 INSUFFICIENT_EVIDENCE，无进展时继续 fail closed
• 8.5 扩展 TOOL_REQUEST_REJECTED 审计字段，记录安全 violation_type、repair_prompt_delivered、连续协议错误次数和 stop reason，并用测试证明不含 Tool 参数、上一轮观察正文或内部异常
• 8.6 运行 tracker、interceptor、release、agent-loop focused tests 和 strict OpenSpec validate，更新 ISS-015/ISS-016 进度