test(graph): establish diagnosis stategraph suite

2026-07-17 18:53:29 +08:00
parent 99e490f227
commit 208a231113
19 changed files with 868 additions and 395 deletions
@@ -0,0 +1,121 @@
+# Chat Diagnosis StateGraph Test Suite Decisions
+
+## Entry Summary
+
+- 问题：阶段 1–3 的安全覆盖已充足，但测试命名/组织仍是逐步实现产物，尚未形成 ISS-011 指定的 Workflow、Node Contract、Chat Integration 三层权威体系。
+- 期望：阶段 4只重构测试结构并补齐矩阵，不改变生产行为；归档并提交后才进入阶段 5。
+- 分档：complex（路径矩阵广、涉及旧安全测试退役，但接口影响为 L1 test-only）。
+- Change：`chat-diagnosis-stategraph-test-suite`。
+- 授权：用户已要求直接实现，阶段门禁与阶段 5 才 live E2E 的约束不变。
+
+## Context Sources
+
+- ISS-011 阶段 4、测试策略和验收标准。
+- `chat-diagnosis-stategraph-design-freeze` 的 test migration requirement。
+- 阶段 1–3 archive/acceptance 和当前 119-test focused baseline。
+- `DiagnosisGraphRoutingTest`、各 Node tests、`DiagnosisRealGraphIntegrationTest`、`ChatDiagnosisGraphRuntimeTest`、`ChatServiceGraphIntegrationTest`。
+- `VerifierInputHookTest`、protocol parser tests、`ExecutorGatekeeperServiceTest` 与 Trace/Controller/Repository/Eval tests。
+
+## Question Pool
+
+| # | 维度 | 问题 | 模式 | 状态 |
+|---|---|---|---|---|
+| Q1 | 术语 | Workflow、Node Contract、Chat Integration 的职责边界是什么？ | evidence-driven | 已解决 |
+| Q2 | 边界 | 是否把所有现有 Graph unit tests 合并成三个巨型类？ | evidence-driven | 已解决 |
+| Q3 | 旧测试 | `VerifierInputHookTest` 在显式 Graph Gatekeeper 后应保留、改写还是删除？ | evidence-driven | 已解决 |
+| Q4 | 验收 | 如何证明阶段 4矩阵完整且没有恢复固定 Sequential 顺序？ | evidence-driven | 已解决 |
+| Q5 | 阶段 | 是否允许为测试可测性改生产代码或执行 live E2E？ | user-interview（既有冻结规则） | 已确认 |
+
+## Evidence-driven Findings
+
+- Q1：Issue 已明确三类测试；现有 `DiagnosisGraphRoutingTest` 对应 Workflow，分散 Node/Protocol tests 对应 Node Contract，`ChatServiceGraphIntegrationTest` 对应外部生命周期。
+- Q2：现有细粒度测试失败定位清晰，全部合并会制造大文件；应保留专用 unit tests，同时新增/重命名三层权威入口并共享夹具。
+- Q3：生产 Graph Verifier 已不注册 Hook，Hook test 仍验证 raw/full-trace/ThreadLocal payload，与 verified-only 生产协议冲突；parser/Gatekeeper/投影行为已有独立 tests，故阶段 4删除 Hook test，生产类型留到阶段 5。
+- Q4：以 Issue 必需路径清单建立 requirement-to-test matrix；source check 禁止 `SequentialAgent`/`VerifierInputHookTest` 成为新 suite 依赖，并运行保留安全回归。
+
+## User-interview Confirmation
+
+| 问题 | 用户原话/既有确认 | 状态 | OpenSpec 回写 |
+|---|---|---|---|
+| Q5 阶段边界 | “端到端只在最后阶段全部完成后才验证；每个阶段如果有必要添加单元测试验收的话，就加” | 已确认 | proposal |
+
+## Grill-with-docs Result
+
+- 术语不进入业务 glossary：Workflow/Node Contract/Integration 是测试架构术语，不改变 Session、Run、Trace、Gatekeeper 或 evidence gap 领域定义。
+- 具体场景压力测试：同 session 多 run 属于 Chat Integration；Gatekeeper REJECT/LOW_CONFID 与 retry exhaustion 属于 Workflow；failed binding 过滤与 verified-only payload 属于 Node Contract。
+- 旧 Hook test 的有效行为已分别迁移到 `ExecutorEvidenceParserTest`、`ExecutorGatekeeperServiceTest`、`GatekeeperNodeTest` 和 `VerifiedInputNodeTest`；删除不会丢失安全真理源。
+- 没有难以逆转的新架构取舍，不创建 ADR；测试组织可以在保持行为矩阵的前提下继续演进。
+
+## Discover Status
+
+- `devflow/index.md`：命中阶段 0–3 archive。
+- 生产调用链：阶段 3 已冻结且测试阶段默认不修改。
+- 接口影响：L1 test-only；无 API/DTO/DB/Prompt/运行时消费者变化。
+- 未解决问题：0。
+- Draft 产物：proposal + decisions；尚未生成 design/spec/tasks，尚未修改测试代码。
+
+## Architecture Audit
+
+### Test ownership map
+
+`ISS-011 path matrix -> DiagnosisGraphWorkflowTest -> ScriptedDiagnosisGraphActions -> real DiagnosisGraphFactory` 负责控制流；`Node/protocol contracts -> DiagnosisGraphNodeContractTest + focused component tests -> real Node actions/parsers/Gatekeeper` 负责安全投影；`public lifecycle -> ChatServiceGraphIntegrationTest -> Run repositories/Eval/Trace mapping` 负责外部行为。Controller、Repository、Trace、Eval 和 protocol tests 是三层体系的下游安全消费者，不应被重写成 Graph 内部顺序断言。
+
+### Data and lifecycle ownership
+
+- Workflow fixtures 只拥有脚本状态、调用计数和 events，不创建 Session/Run。
+- Node Contract fixtures 只拥有 invoker input/output 和 mock Gatekeeper current-run result，不持久化生产实体。
+- Chat Integration fixtures 只观察 ChatService public result 和 current Run persistence，不推断内部 Node 次序。
+- `VerifierInputHookTest` 删除后不产生数据契约缺口：Executor parser、Gatekeeper、passed-binding projection 各自已有单一测试所有者。
+
+### Coupling risks
+
+- 最大风险是 Workflow 与 Node Contract 都断言完整路径而重复；设计将 Fake route matrix 与 real-node input/security matrix分开。
+- `ScriptedDiagnosisGraphActions` 是唯一 Fake topology fixture；不新增第二套 Graph builder。
+- 测试-only阶段禁止 `src/main` diff，避免为测试便利扩大 production API。
+- 类重命名使用 Git rename，旧名称仅允许出现在 OpenSpec/devflow迁移说明中。
+
+### Cross-artifact alignment
+
+| 上游 → 下游 | 检查内容 | 状态 |
+|---|---|---|
+| brief/proposal → proposal | 三层体系、旧 Hook test退役、保留安全回归、阶段 5 E2E 延期 | 已对齐 |
+| proposal → design | rename-not-copy、职责归属、production diff=0、rollback | 已对齐 |
+| design → specs/tasks | Workflow/Node/Integration矩阵、Hook test删除、source inventory和验证门禁 | 已对齐 |
+| specs → tasks | 每类 scenario 均有 rename、补缺、回归或静态验收任务 | 已对齐 |
+
+### Audit result
+
+架构审计未发现业务 glossary、阶段 0–3 specs 或生产行为冲突。新 capability 只描述测试验证系统，modified design-freeze requirement 完整保留并细化旧测试替换边界。接口影响保持 L1，cross-artifact gap=0，无需回写生产 spec 或创建 ADR。
+
+## Commit Gate
+
+- schema：spec-driven；proposal/design/2 delta specs/tasks 全部 done，applyRequires=`tasks` 已满足。
+- OpenSpec：当前 change strict pass；15 个主 specs strict pass。
+- Cross-artifact：4/4 已对齐，gap=0。
+- Question pool：4 个 evidence-driven 已查证，1 个 user-interview 由用户既有原话确认，无未决项。
+- Interface impact：L1 test-only；design 有独立影响/回滚章节，默认 `src/main` diff=0。
+- Preflight：`git diff --check` 通过，当前仅 Draft OpenSpec/devflow 与根目录计划文件，无测试/生产代码修改。
+- 结论：Draft OpenSpec 达到可执行状态，创建 `.committed` 后进入 Apply。
+
+## Apply Completion
+
+- `DiagnosisGraphRoutingTest` 已以 Git rename 演进为 `DiagnosisGraphWorkflowTest`；所有 scripted run 统一断言 events 与真实 sequence 完全一致。
+- `DiagnosisRealGraphIntegrationTest` 已演进为 `DiagnosisGraphNodeContractTest`；补齐合法工具失败限制、partial-pass REJECT 和 Verifier invalid 无伪 verdict。
+- Workflow 显式断言 Gatekeeper ceiling 将模型 PASS 限制为 LOW_CONFID 且不触发 evidence retry，以及第二次 LOW_CONFID 不再补证据。
+- `ChatServiceGraphIntegrationTest` 增加 SessionContextHolder finally cleanup 断言；public Run/Trace/Eval/multi-run 覆盖保持。
+- `VerifierInputHookTest` 已删除；生产 Hook/ThreadLocal 类型未修改，留待阶段 5清理。
+- 新增 `DiagnosisGraphTestSuiteStructureTest`，保证三个权威类存在、Sequential/Hook实现测试不存在且权威测试不引用旧实现。
+
+## Verification Summary
+
+- 新权威层：4 suites / 43 tests，0 failures/errors/skipped。
+- 完整保留安全回归：31 suites / 126 tests，0 failures/errors/skipped。
+- Maven test compilation：通过。
+- OpenSpec：当前 change strict pass；主 specs 15/15 strict pass。
+- 静态门禁：`git diff --check` 通过；required authoritative classes=3；legacy tests=0；scripted fixture definitions=1；`src/main` diff=0。
+- 按阶段门禁未运行 Maven live E2E、未检查 `logs/`、未执行 `scripts/query_mysql.py`；统一保留到阶段 5。
+
+## Archive Result
+
+- 2 份 delta specs 已同步：新增 test-suite capability 6 条 requirements，修改 design-freeze test migration requirement 1 条。
+- OpenSpec 已归档到 `openspec/changes/archive/2026-07-17-chat-diagnosis-stategraph-test-suite/`。