docs(issue): add iss-014 handoff

mvp/issues/active/ISS-014-handoff-20260723.md

@@ -0,0 +1,54 @@
+# SuperBizAgent ISS-014 交接文档
+
+## 当前上下文
+
+- 分支：`refactor/chat-single-react-harness`
+- 任务：停止端到端验证，提交当前代码，更新 ISS-014，并交接后续开发。
+- 本轮没有继续启动服务或发送真实请求；9900 端口确认没有监听进程。
+- 工作区仍包含用户已有的文档、技能和演示输出改动；提交时只纳入 ISS-014 实现相关文件。
+
+## 本次已完成
+
+1. 新增独立追加式 `diagnosis_trace_event` 审计表和记录器，覆盖 Run、Routing、Agent、Tool、Evidence、Semantic、Release 生命周期事件。
+2. Knowledge Query 使用 `BeanOutputConverter<KnowledgeAnswerDraft>` 注入实际 JSON Schema，修复缺少 Schema 导致的 `Knowledge answer is invalid`。
+3. Fallback 增加 `failure_stage`、`observed_facts`、`validation_issues`，为失败提供可操作的阶段、事实和校验信息，同时不暴露 Prompt、原始 Draft 或 Tool 载荷。
+4. 新增 `agent_reasoning_audit` 表、Repository、Hook 持久化和专用查询接口。只保存模型供应商实际返回的 reasoning 元数据，长度上限 32000 字符；普通 Trace 只展示是否存在及字节数，不返回原文。
+5. ISS-014 已更新，记录上述实现、成功用例、协议边界变化和后续工作。
+
+## 已知验证结果
+
+- Diagnosis 成功：`mvp-demo-success-e2e-20260722-2032` / `e72d9c7b-2f78-44c8-9086-f2e9d6987f24`，SUCCESS，8455 tokens，1 次 Tool 调用。
+- Knowledge Query 成功：`mvp-demo-order-timeout-fixed-20260723` / `2b704d1b-8f11-40ee-a4c6-5e5e04d3847c`，SUCCESS，1998 tokens。
+- 已通过的重点测试：`HarnessAgentAuditHookTest`、`DiagnosisReleaseUseCaseTest`、`DiagnosisTraceServiceTest`、`HarnessContractTest`、`HarnessChatConfigurationTest`、`ApplicationExecutorsTest`、`ChatApplicationUseCaseTest`、`JpaToolInvocationAuditSinkTest`、`JpaDiagnosisTraceRecorderTest`，以及编译和 `git diff --check`。
+- V015 真实数据库迁移、reasoning endpoint 的真实数据库/E2E 尚未验证。
+
+## 后续实现顺序
+
+1. 为 Diagnosis Agent 增加硬停止策略：限制证据轮次、阻止重复 `lookup_knowledge`，在预算耗尽前强制输出最终 Draft。
+2. 给 Evidence Repair 注入真实 `DiagnosisDraft` Schema，消除运行时 `PARSE_ERROR`。
+3. 使用真实 Provider 验证 reasoning metadata；无 reasoning 时也要写入 `reasoning_available=false` 的审计记录。
+4. 在受控环境验证 V015 迁移和 reasoning 查询接口，并用精确 `sessionId + runId` 对齐数据。
+5. 评估 reasoning 审计表的访问控制、保留期限和加密策略。
+6. 继续细化工具成功但无法构造 verified snapshot 时的 fallback 事实和校验问题。
+
+## 重要约束
+
+- 不恢复完整端到端验证，除非用户明确要求。
+- 不把 reasoning 审计内容当作事实证据，也不加入普通 SSE、Trace 或业务结果。
+- 不提交无关用户文件、演示输出、环境配置和凭据。
+- ISS-014 的后续阶段仍按独立 sm-flow/OpenSpec、归档、提交后再进入下一阶段。
+
+## 建议技能
+
+- `diagnose`：继续处理 Agent 重复工具调用、预算耗尽和 Evidence Repair 解析失败。
+- `sm-flow`：开始下一阶段实现时按 OpenSpec-first 流程执行和归档。
+- `gitnexus-debugging`：定位 Agent 停止条件和跨 Harness 调用链问题。
+- `gitnexus-impact-analysis`：编辑共享 Harness/Agent 方法前评估调用影响。
+
+## 关键文件
+
+- Issue：`mvp/issues/active/ISS-014-single-react-agent-harness-aci-ptk-refactor.md`
+- Trace：`src/main/java/com/superbiz/agent/harness/audit/`、`src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java`
+- Reasoning：`src/main/java/com/superbiz/agent/domain/entity/AgentReasoningAudit.java`、`src/main/java/com/superbiz/agent/harness/audit/HarnessAgentAuditHook.java`、`src/main/resources/db/migration/V015__create_agent_reasoning_audit.sql`
+- Fallback：`src/main/java/com/superbiz/agent/harness/release/SafeFallbackFactory.java`
+- Knowledge：`src/main/java/com/superbiz/agent/harness/application/executor/KnowledgeQueryExecutor.java`