feat(harness): complete protocol repair stop and archive ISS-016

Add repairable INVALID_PROGRESS_PROTOCOL observations, independent PROGRESS_PROTOCOL_VIOLATED saturation, and controlled release paths. Archive the OpenSpec change after syncing main specs and devflow.
2026-07-27 19:10:07 +08:00
parent 5c369f3b6c
commit 38f781b157
44 changed files with 977 additions and 80 deletions
@@ -189,11 +189,15 @@

 ### Collection State
 - 定义：Diagnosis Harness 对当前 Run 是否允许继续收集证据的控制状态，固定为 `COLLECTING` 或 `SATURATED`。
- 边界：状态由 Harness 维护；`SATURATED` 只表示连续 `NO_GAIN` 达到配置阈值，不包括硬预算耗尽。模型可以请求新的 Tool 调用，但不能绕过 `SATURATED`。
+- 边界：状态由 Harness 维护；`SATURATED` 可因连续 `NO_GAIN` 或连续进展协议错误达到各自配置阈值而进入，不包括硬预算耗尽。模型可以请求新的 Tool 调用，但不能绕过 `SATURATED`。

 ### Diagnosis Stop Reason
- 定义：Harness 停止当前 Run 继续调用 Tool 的内部原因，首版区分 `INFORMATION_SATURATED` 与 `BUDGET_LIMIT_REACHED`。
- 边界：它用于控制、Trace 和 Release 输入，不是用户可见生命周期状态，也不进入模型上下文；真正的不可恢复技术故障走失败通道。
+- 定义：Harness 停止当前 Run 继续调用 Tool 的内部原因，首版区分 `INFORMATION_SATURATED`、`BUDGET_LIMIT_REACHED` 与 `PROGRESS_PROTOCOL_VIOLATED`。
+- 边界：它用于控制、Trace 和 Release 输入，不是用户可见生命周期状态，也不进入模型上下文；真正的不可恢复技术故障走失败通道。协议错误不累计为 `NO_GAIN`，使用独立阈值与 stop reason。
+
+### Progress Protocol Violation
+- 定义：模型未遵守 Tool Call Envelope 进展协议时的安全错误分类，例如缺失/错序/意外 `previous_observation`、缺失 `input` 或非法 Envelope。
+- 边界：返回可修正 observation（`repair_required`、`violation_type`、期望上一轮 Tool Call ID、允许的 `information_gain`）；连续错误达到阈值后交付一次 `STOP_REQUIRED/PROGRESS_PROTOCOL_VIOLATED`。不泄露业务参数、上一轮观察正文、raw response 或内部异常。

 ### Progress Snapshot
 - 定义：Tool Loop 结束时，从当前 Run 的 Canonical Tool Result 一次性投影出的有界发布视图，用于生成已检查范围和客观结果。
@@ -5,12 +5,14 @@
 | Issue | 状态 | 说明 |
 |---|---|---|
 | ISS-014 | archived | 阶段 0-7 的单体 Diagnosis Agent、Harness、ACI、SSE、清理和最终 E2E 已完成并归档；阶段实现对应的 11 个 devflow/OpenSpec 项目均已 archived。 |
-| ISS-015 | active | 承接 ISS-014 E2E 后发现的 Agent 硬停止、Evidence Repair Schema、Reasoning 审计验证/治理和 Fallback 信息质量问题。 |
+| ISS-015 | active | 阶段 1 硬停止已由 ISS-016 收口；剩余 Evidence Repair Schema、Reasoning 审计验证/治理与最终综合验收。 |
+| ISS-016 | archived | Diagnosis 信息增益停止契约、协议修复反馈与统一 Release 已完成并归档。 |

 ## 项目

 | 日期 | slug | 说明 | 领域 | 关键词 | 关联 OpenSpec | 状态 |
 |---|---|---|---|---|---|---|
+| 2026-07-26 | diagnosis-information-gain-stop-contract | Diagnosis 信息增益停止、协议修复反馈、ProgressSnapshot 与统一 Release。 | Harness/Diagnosis stop/Release | ISS-016, GAINED, NO_GAIN, STOP_REQUIRED, ProgressSnapshot, PROGRESS_PROTOCOL_VIOLATED, INSUFFICIENT_EVIDENCE | openspec/changes/archive/2026-07-27-diagnosis-information-gain-stop-contract | archived |
 | 2026-07-27 | rag-chunk-evidence-identity-dedup | chunk 级证据身份、去重、retrieve-k/return-n 与 SearchPort 地基，为 hybrid 铺路。 | RAG/证据身份/去重 | evidenceKey, maxChunksPerDocument, retrieve-k, return-n, KnowledgeSearchPort, document_id chunk-scoped | openspec/changes/archive/2026-07-27-rag-chunk-evidence-identity-dedup | archived |
 | 2026-07-27 | rag-bm25-hybrid-drop-sdk | 真 dense+BM25 hybrid（MilvusClientV2），废弃知识路径旧 SDK 检索/写入。 | RAG/BM25/hybrid | MilvusClientV2, BM25, hybridSearch, RRFRanker, biz_hybrid, drop SDK path | openspec/changes/archive/2026-07-27-rag-bm25-hybrid-drop-sdk | archived |
 | 2026-07-27 | rag-hybrid-search-rrf | Delivery 2：可配置 hybrid 检索与 RRF 多路融合（不绑旧 SDK）。 | RAG/hybrid/RRF | hybrid mode, RRF, KnowledgeSearchPort, filtered+unfiltered fusion, sparse-lite lexical | openspec/changes/archive/2026-07-27-rag-hybrid-search-rrf | archived |
@@ -0,0 +1,68 @@
+# Diagnosis 信息增益停止契约 验收
+
+## 结果
+
+已接受。OpenSpec tasks 37/37 完成；用户确认归档 OpenSpec、提交并推送。
+
+## 验证
+
+### 静态验证
+
+- 命令/检查：`openspec validate diagnosis-information-gain-stop-contract --strict`
+- 结果：passed
+- 备注：Committed OpenSpec 与最终 tasks 一致
+
+- 命令/检查：OpenSpec delta → main specs 同步（6 个 capability）
+- 结果：passed
+- 备注：新建 `openspec/specs/diagnosis-information-gain-stop-contract/`，并更新 5 个既有 main specs
+
+- 命令/检查：对照 OpenSpec 与代码路径（progress tracker、interceptor、release、trace）
+- 结果：passed
+- 备注：Task 8 行为与 design/spec 对齐
+
+### 脚本验证
+
+- 命令：`mvn -q "-Dtest=DiagnosisProgressTrackerTest,HarnessToolInterceptorTest,DiagnosisReleaseUseCaseTest,DiagnosisAgentUseCaseTest,HarnessChatConfigurationTest" test`
+- 结果：passed（exit 0）
+- 备注：覆盖协议 violation_type、可修正 observation、连续协议错误 STOP、Release fail-closed、Agent 受控停止
+
+- 命令：历史全量回归 `mvn -q -Dtest='!MilvusConnectionTest' test`（tasks 6.2/7.5 阶段）
+- 结果：passed（`Tests=292, Failures=0, Errors=0, Skipped=3`）
+- 备注：未设置 `MILVUS_TOKEN` 时 `MilvusConnectionTest` 失败属外部凭据边界，非本变更回归
+
+### 浏览器/人工验证
+
+- 步骤：Maven 启动真实应用；Query `诊断切换企业失败的问题`；named SSE + logs + `scripts/query_mysql.py` 按 exact sessionId/runId 核对
+- 结果：passed
+- 备注：
+  - `sessionId=iss016-final-20260726-a`
+  - `runId=3ab22ed7-d0ed-45d8-b928-dce5790c0542`
+  - SSE：`SAFE_FALLBACK` / `MISSING_REQUIRED_CONTEXT` / `done.outcome=FALLBACK`
+  - DB：`status=SUCCESS`、`intent=DIAGNOSIS`、`release_outcome=FALLBACK`、`tool_call_count=0`、`total_token_count=2890`
+  - Trace：`RUN_STARTED -> ROUTING_* -> AGENT_MODEL_STEP -> EVIDENCE_GUARD_INITIAL -> RELEASE_DECISION/FALLBACK -> RUN_FINISHED/FALLBACK`
+
+### 未验证
+
+- 本轮 Archive 未再重跑全量 `mvn test` 与完整 live SSE E2E；依赖 Apply 阶段记录与本轮 focused tests。
+- 真实 Provider 下连续协议错误的 live E2E 未单独复跑；协议停止由 focused/scripted loop 覆盖。
+- ISS-015 阶段 2（Evidence Repair Schema）与阶段 3（Reasoning 治理）不在本 change 范围。
+
+## 已完成范围
+
+- 信息增益停止、scope 去重、STOP_REQUIRED、ProgressSnapshot、统一 Release
+- Token 审计与 Tool 拒绝 Trace
+- 协议修复反馈 + `PROGRESS_PROTOCOL_VIOLATED` 兜底停止
+- 文档：ISS-015 阶段 1、ISS-016、架构文档、glossary 术语、devflow 档案
+
+## 已知限制
+
+- 重复检测只比较确定性 `tool_name + normalized_scope`，不做自然语言语义去重。
+- 协议错误阈值默认 2，与无增益阈值独立配置。
+- 无安全 ProgressSnapshot 的受控停止继续 fail closed，不伪造用户可见事实。
+- 公开 SSE/前端协议无新增字段；模型侧 Tool Envelope 是已确认 L3 变更。
+
+## 交接
+
+- 下一步：OpenSpec 已用户确认归档；代码提交并推送到当前分支。
+- OpenSpec 归档确认：用户确认归档（“执行，完后提交推送”）
+- 归档位置：`openspec/changes/archive/2026-07-27-diagnosis-information-gain-stop-contract/`
@@ -0,0 +1,45 @@
+# Diagnosis 信息增益停止契约 Brief
+
+## 背景
+
+- 用户目标：未知问题、空证据或缺少查询条件时，Diagnosis 能以正常业务 Fallback 结束，而不是空转到预算耗尽或 `INTERNAL_FAILURE`。
+- 当前问题：停止主要依赖模型自觉结束或硬预算；缺少信息增益回传、确定性饱和停止、协议修复反馈和统一 Release。
+- 关联 OpenSpec：`openspec/changes/diagnosis-information-gain-stop-contract/`（归档后见 `openspec/changes/archive/2026-07-27-diagnosis-information-gain-stop-contract/`）
+- 关联 Issue：ISS-016（承接 ISS-015 阶段 1 硬停止）
+- devflow 分档：complex
+- 接口影响：L3（模型可见 Tool Envelope 有意变更；公开 HTTP/SSE 与业务 Tool backend 不变）
+
+## 范围
+
+### 本次要做
+
+- Run 内二值信息增益 `GAINED / NO_GAIN`、连续无增益阈值与 `COLLECTING / SATURATED`。
+- 服务端注册的 Tool Call Envelope：`previous_observation + input`。
+- 确定性 `NO_GAIN`（`NO_EVIDENCE`、重复 `tool_name + normalized_scope`）。
+- 一次 `STOP_REQUIRED` 收尾机会与受控停止异常。
+- Canonical 控制视图 / 模型白名单观察双视图；RAG 保留 `relevance_level`。
+- Tool loop 结束时一次性投影 `ProgressSnapshot`。
+- `DiagnosisReleaseUseCase` 统一有结论、无结论、信息饱和、预算终止、协议违规停止的发布。
+- 可修正 `INVALID_PROGRESS_PROTOCOL` observation，以及独立 `PROGRESS_PROTOCOL_VIOLATED` 兜底停止。
+- 模型 Token 组件/轮次审计与 `TOOL_REQUEST_REJECTED` 安全 Trace。
+- Prompt、配置、focused/回归测试与真实 named SSE E2E。
+
+### 本次不做
+
+- `new_count`、`next_action`、多级质量分数、独立 Judge。
+- 自然语言语义去重。
+- 第二套诊断生命周期状态。
+- 公开 HTTP/SSE 字段或前端进度协议新增。
+- ISS-015 Reasoning 原文审计治理与 Evidence Repair Schema 注入。
+
+### 影响区域
+
+- `harness.progress`、`HarnessToolInterceptor`、`HarnessEvidenceTools`
+- `DiagnosisAgentUseCase` / Prompt / Release / Application 预算兜底迁移
+- Trace 审计、配置绑定、ISS-015/016 与架构文档
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖
+- specs 覆盖状态：已覆盖（6 个 capability delta，已同步 main specs）
+- tasks 覆盖状态：已覆盖（37/37 完成）
@@ -155,3 +155,34 @@
 - 数据库核对：`status=SUCCESS`、`intent=DIAGNOSIS`、`release_outcome=FALLBACK`、`tool_call_count=0`、`total_token_count=2890`、answer 非空。
 - Trace 核对：`RUN_STARTED -> ROUTING_ATTEMPT -> ROUTING_DECISION -> AGENT_MODEL_STEP -> EVIDENCE_GUARD_INITIAL -> RELEASE_DECISION/FALLBACK -> RUN_FINISHED/FALLBACK`。
 - 兼容性：公开 HTTP/SSE 字段、前端 SafeFallback 消费结构、数据库表和业务 Tool request 均未新增字段；模型侧 Tool Envelope 是本变更已确认的 L3 协议变更。
+
+## Apply Continuation: Task 8 Protocol Repair + Bounded Stop
+
+- Checkpoint：Apply。
+- Capability source：`openspec-apply-change` + sm-flow apply 协议。
+- 背景：tasks 1–7 已完成；真实 E2E 暴露连续 `INVALID_PROGRESS_PROTOCOL` 不会累计 `NO_GAIN`，可能在硬预算前空转。Task 8 补齐协议修复反馈与独立兜底停止。
+- 实现事实（代码已在工作区，本轮补齐测试与收口）：
+  - `ProgressProtocolViolationType` / `ProgressProtocolViolationException` 覆盖 MISSING_PREVIOUS_OBSERVATION、OUT_OF_ORDER、UNEXPECTED、MISSING_INPUT、INVALID_ENVELOPE。
+  - `DiagnosisProgressTracker` 独立累计连续协议错误，默认阈值 2，达到后 `stop_reason=PROGRESS_PROTOCOL_VIOLATED`。
+  - `HarnessToolInterceptor` 返回可修正 observation（repair_required、violation_type、missing_field、expected_previous_tool_call_id、allowed_information_gain）；达阈一次 STOP_REQUIRED，再请求抛 `DiagnosisCollectionStoppedException`。
+  - `DiagnosisReleaseUseCase` 支持 `PROGRESS_PROTOCOL_VIOLATED`：有安全 ProgressSnapshot 发 `INSUFFICIENT_EVIDENCE`，无进展 fail closed。
+  - `TOOL_REQUEST_REJECTED` 记录 violation_type、repair_prompt_delivered、consecutive_protocol_violations、stop_reason，不记录参数/观察正文/异常。
+- 验证：
+  - Focused：`DiagnosisProgressTrackerTest`、`HarnessToolInterceptorTest`、`DiagnosisReleaseUseCaseTest`、`DiagnosisAgentUseCaseTest`、`HarnessChatConfigurationTest` 通过。
+  - OpenSpec strict validate 通过。
+- 文档：ISS-016 剩余协议停止项勾选完成；ISS-015 阶段 1 标记已完成；架构文档同步协议错误独立停止语义。
+- OpenSpec tasks 8.1–8.6 全部完成。剩余 Apply 工作：无。可进入 Archive checkpoint（需用户确认是否归档 OpenSpec）。
+
+## Archive
+
+- Checkpoint：Archive。
+- Capability source：`sm-flow` archive 协议 + `openspec-archive-change`。
+- 用户确认：明确要求“执行（archive），完后提交推送”。
+- devflow 档案：
+  - `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`
+  - 更新 `devflow/index.md`、`devflow/glossary/CONTEXT.md`
+- OpenSpec：
+  - delta specs 已同步到 main specs（含新建 `diagnosis-information-gain-stop-contract`）
+  - change 归档至 `openspec/changes/archive/2026-07-27-diagnosis-information-gain-stop-contract/`
+- 不创建独立 ADR：决策已由 OpenSpec/ISS/架构文档承载，且可通过 OpenSpec 回滚。
+- 状态：archived。
@@ -0,0 +1,38 @@
+# Diagnosis 信息增益停止契约 Evidence
+
+## 证据
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+| --- | --- | --- | --- |
+| `HarnessEvidenceTools` / request records | Agent-facing Tool 直接使用业务 request 生成 Schema | 要增加 `previous_observation + input` 必须显式演进 Tool Schema | 是 |
+| `HarnessToolInterceptor` | 曾把完整 `agentResult` 放入 Tool Response | 必须拆分控制视图与模型观察 | 是 |
+| `RunContext` / `DiagnosisHarnessCore.startRun` | 结构不可变 + 线程安全 handle | 进展 tracker 放 RunContext，不扩 Redis 枚举 | 是 |
+| `CanonicalInvocationStore` | 仅 begin/find/markReady/markError | tracker 只存 identity，结束时投影 | 是 |
+| `RagResultProjector` | 只按 evidence 空否生成状态 | 需兼容 `relevanceLevel/relevance_level` | 是 |
+| `DiagnosisReleaseUseCase` / `EvidenceGuard` | 强制 draft 非空且空 analysis=`ANALYSIS_MISSING` | 与合法无结论冲突，需统一 Release | 是 |
+| `ChatApplicationUseCase.recoverBudgetExhaustion` | 未提交预算 Fallback 绕过 Release | 迁移意图到 Diagnosis Release | 是 |
+| 前端 `app.js` | 已渲染 observed_facts/sources/limitations/next_steps | 不新增公开 SSE 字段 | 是 |
+| 真实 E2E（实施前） | 多轮空转后 `BUDGET_EXHAUSTED`/`INTERNAL_FAILURE` | 需要信息增益停止契约 | 是 |
+| 真实 E2E（实施后） | `iss016-final-20260726-a` → `MISSING_REQUIRED_CONTEXT` FALLBACK | 未知 Query 可正常业务结束 | 是 |
+| Token/拒绝审计 E2E | 9 次 `INVALID_PROGRESS_PROTOCOL` 拒绝不累计 NO_GAIN | 需独立协议错误阈值与 STOP | 是 |
+
+## Evidence-driven 结论
+
+- 结论：Tool Envelope 是 L3 模型侧协议变更，业务 request 在 interceptor 解包后保持不变。
+  - 证据：三个 FunctionToolCallback inputType、adapter bridge 只收业务 JSON。
+  - 风险：框架 Schema/拦截器假设不匹配。
+  - 用户确认：不需要（技术事实）
+
+- 结论：协议错误不得累计为 `NO_GAIN`，必须独立 `PROGRESS_PROTOCOL_VIOLATED`。
+  - 证据：真实审计 9 次协议拒绝 + 13 Agent 轮次；OpenSpec design 6.1。
+  - 风险：只返回通用错误码不足以自修复。
+  - 用户确认：已通过 Task 8 OpenSpec 与实现收口
+
+- 结论：Release 是业务 Fallback 唯一决策入口；Application 不重建业务内容。
+  - 证据：`DiagnosisReleaseUseCase` 统一路径 + Application 窄化预算终态持久化。
+  - 用户确认：已确认
+
+## 实现期补充证据
+
+- Draft 合同失败窄化降级：非法 Draft 丢弃；仅当 ProgressSnapshot 有已验真 facts 时发 `INSUFFICIENT_EVIDENCE`。
+- Task 8 focused tests：tracker / interceptor / release / agent-loop / config 全部通过。