osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
190013c901cb4f3bb1790c103261b5a7d3ff287c
SuperBizAgent-java/devflow/projects/2026-07-17-chat-diagnosis-stategraph-cleanup-docs/decisions.md
T

14 KiB
Raw Blame History

Chat Diagnosis StateGraph Cleanup, Final Acceptance And Documentation Decisions

Entry Summary

  • 问题：ISS-011 运行时已切换且测试体系已收敛，但旧 Hook/ThreadLocal/service死代码、当前架构文档和最终 live 证据尚未闭环。
  • 期望：阶段 5完成清理、文档、自动化回归、eval、Maven E2E、日志/DB 验收、Issue 归档和独立提交。
  • 分档：complex；接口影响 L2 内部删除 + 文档/demo 验收增强，外部 API/DB 协议不变。
  • Change：chat-diagnosis-stategraph-cleanup-docs。
  • 授权：用户已明确要求直接实现；本阶段按此前规则执行唯一最终 E2E。

Context Sources

  • ISS-011 阶段 5、测试策略、协议影响、验收标准和冻结决策。
  • 阶段 0–4 OpenSpec archives、devflow acceptance 与提交 581daff、42ba204、1460dd1、99e490f、208a231。
  • 全仓 VerifierInputHook/VerifierContextHolder/ToolTraceSummaryService 定义与引用搜索。
  • mvp/architecture/README.md 列出的 current docs、mvp/eval/README.md、mvp/demo/ scripts/checklist。
  • mvp-demo profile、payment-timeout request、scripts/query_mysql.py 和 logs/ 现有布局。

Question Pool

# 维度 问题 模式 状态
Q1 清理 旧 Hook/ThreadLocal/trace summary service 是否还有生产消费者？ evidence-driven 已解决
Q2 文档 哪些旧引用应更新，哪些历史材料应保留？ evidence-driven 已解决
Q3 E2E 最终 live 场景如何绑定唯一 session/run 并证明 Graph 路径？ evidence-driven 已解决
Q4 日志/DB 如何避免用旧日志/latest DB 记录冒充当前证据？ evidence-driven 已解决
Q5 验收 何时允许启动 Maven、是否需要日志和 DB 查询？ user-interview（用户最新规则） 已确认
Q6 关闭 何时把 ISS-011 从 active 移到 archived？ evidence-driven 已解决

Evidence-driven Findings

  • Q1：旧闭包只有 VerifierInputHook -> VerifierContextHolder + ToolTraceSummaryService，以及 ToolTraceSummaryServiceTest；ChatService/Graph/Trace/Eval 均无引用，可整体删除。
  • 实现前规格校正：ChatVerifierPromptContractTest 和 DiagnosisGraphTestSuiteStructureTest 必须保留旧类型名称的负向字符串断言；这不构成 executable reference。OpenSpec 已收紧为无定义/import/实例化/type-use，允许负向 guard literal。
  • Q2：current architecture index 仍列 agent-orchestration.md 等为当前真理源，因此必须更新；mvp/issues/design-notes、archived issues、历史 eval fixtures 保留时间点/兼容语义，不做大规模重写。
  • Q3：run-interview-demo-check.ps1 已用 Chat response runId 查询 exact Trace/feedback，最适合扩展 run.orchestrationTrace fail-fast 和 summary，不另建重复脚本。
  • Q4：E2E 使用唯一 timestamp sessionId；日志记录启动前 byte/time 边界并按 session/run 搜索；DB 所有核心查询带 exact sessionId/runId，另查询错误 ownership count。
  • Q6：只有实现、回归、eval、live E2E、日志、DB 和 OpenSpec门禁全部通过后，Issue checkbox 才可完成并移动到 archived。

User-interview Confirmation

问题 用户原话 状态 OpenSpec 回写
Q5 最终验收节奏 “端到端只在最后阶段全部完成后才验证……日志在log文件夹，项目库有查询数据库的py工具” 已确认 proposal

Grill-with-docs Result

  • Session/Run/Trace 术语保持不变；新增强调 orchestration_trace 是 Run 路由摘要，不属于 self-evaluation 或日志。
  • StateGraph、Workflow/Node Contract/Chat Integration 属于实现/测试架构术语，不修改业务 glossary。
  • 当前文档必须使用 explicit Gatekeeper Node、verified-only Verifier 和 bounded evidence retry；历史设计笔记仍可描述当时 Hook 架构。
  • 删除旧闭包是阶段 0 已冻结单轨迁移的自然收尾，不形成新的难逆转权衡，无需 ADR。

Discover Status

  • devflow/index.md：命中阶段 0–4 archives。
  • 接口影响：L2 内部类型删除；外部 API/DTO/DB/Prompt/状态语义无变化。
  • E2E 入口/脚本/日志/DB 工具已定位；真实执行留到 Apply 最后。
  • 未解决问题：0。
  • Draft 产物：proposal + decisions；尚未生成 design/spec/tasks，尚未删除代码或启动应用。

Architecture Audit

Module and evidence map

ChatController -> ChatService -> ChatDiagnosisGraphRuntime -> DiagnosisRealGraphActionsFactory -> explicit Nodes -> DiagnosisGraphResultMapper -> DiagnosisRun/Trace 是唯一当前 Chat链。旧 VerifierInputHook -> ToolTraceSummaryService/VerifierContextHolder 已从主链断开，删除不改变输入/输出或持久化。阶段 5新增的 demo script assertion只消费 exact Trace run.orchestrationTrace，DB/log检查是验收消费者，不成为运行时业务依赖。

模块 所有权 阶段 5动作
Graph/Chat runtime 路由、Node、Run 生命周期 不改行为，仅回归
Legacy Hook closure 旧 Sequential Verifier payload 整体删除
Current architecture docs 当前实现真理源 更新 StateGraph/verified-only/trace
Historical docs/fixtures 时间点/兼容记录 保留，不冒充当前实现
Demo check live Chat/Trace/feedback executable contract 增加 exact orchestration trace fail-fast
logs/MySQL live运行证据 只读本次 session/run
ISS/OpenSpec/devflow 生命周期与交接 所有门禁通过后归档

Lifecycle and failure ownership

  • 自动化门禁失败：不启动 live Maven，修复代码/测试/规格后重跑。
  • live startup失败：应用未 ready，不执行 demo/DB成功声明，先读启动输出和新日志诊断。
  • Chat/Trace/feedback失败：保留 exact response/run证据，ISS保持 active。
  • log ERROR：逐条分类；未解释 ERROR阻塞验收。
  • DB不一致：以 exact run为准，不能用 API成功掩盖 persistence偏差。
  • finally：无论成功失败都停止本轮进程并确认端口，不扩大到未知已有进程。

Consumer and compatibility audit

  • 外部 API/DTO/DB consumer无迁移；demo summary仅加字段。
  • Trace UI/eval 对历史 tool_trace_summary 的读取保留，旧 fixture不批量迁移。
  • current docs消费者将看到新 StateGraph架构；历史链接仍可追溯 old Hook设计。
  • Issue move只改变文档位置/index，代码/运行时不依赖该路径。

Cross-artifact alignment

上游 → 下游 检查内容 状态
brief/proposal → proposal cleanup、current docs、demo、regression、live/log/DB、Issue closure 已对齐
proposal → design 删除闭包、current/history边界、顺序、identity、日志/DB、cleanup 已对齐
design → specs/tasks 负向 literal例外、E2E字段、exact evidence、进程清理、Issue gate 已对齐
specs → tasks 每条 requirement有可执行 cleanup/docs/test/live/log/DB/closure slice 已对齐

Audit result

审计确认阶段 5不需要新运行时抽象或 DB migration；主要风险来自外部 live状态和证据归属，已通过 unique session/run、log boundary、exact DB queries和process ownership缓解。规格误把负向名称 literal 当 executable reference 的 gap 已修正。接口影响 L2，cross-artifact gap=0，无新 ADR。

Commit Gate

  • schema：spec-driven；proposal/design/2 delta specs/tasks 全部 done，applyRequires=tasks 已满足。
  • OpenSpec：当前 change strict pass；16 个主 specs strict pass。
  • Cross-artifact：4/4 已对齐，gap=0；负向 guard literal例外已写入 proposal/design/spec/tasks。
  • Question pool：5 个 evidence-driven 已解决，1 个 user-interview 已由用户原话确认，无未决项。
  • Interface impact：L2 internal type removal + demo/docs enhancement；外部协议/DB无变化。
  • Preflight：git diff --check 通过；尚未删除代码、修改 current docs/script或启动应用。
  • 结论：Draft OpenSpec 达到可执行状态，创建 .committed 后进入 Apply。

Apply Progress

Legacy closure removal

  • 已删除 VerifierInputHook、VerifierContextHolder、ToolTraceSummaryService 和 ToolTraceSummaryServiceTest，四个路径均不存在。
  • rg 对 src/main、src/test 的旧类型扫描仅命中 ChatVerifierPromptContractTest 和 DiagnosisGraphTestSuiteStructureTest 中的负向守卫字符串；无定义、import、实例化、继承或类型依赖。
  • 删除后 focused 回归覆盖 Executor parser、Gatekeeper service/node、VerifiedInput、Verifier、Composer、Fallback、Workflow、Node Contract、Chat integration、Trace、result mapper 和结构契约：14 suites / 82 tests，0 failure、0 error、0 skipped。
  • mvn -q -DskipTests test-compile 通过；Graph/shared protocol 真理源保留，Spring 当前链路所需类型可完整编译。

Current docs and demo contract

  • architecture index、编排、session/trace、current MVP、evidence pipeline、quality gates、feedback、retrieval 和 eval 文档已切换为 bounded StateGraph、显式 Gatekeeper/Verified Input、verified-only Verifier、有限重试/Fallback 和 Run-owned orchestration_trace。
  • current-doc scan 对 SequentialAgent、旧 Hook/ThreadLocal/service 及旧测试类名为 0 命中；tool_trace_summary 仅剩 4 处，均明确标注为旧 Run/fixture 只读兼容，不是当前 Verifier 输入。
  • interview demo check 绑定 Chat 返回的 exact runId，校验 Chat/Trace ownership、Run CHAT/SUCCESS、Agent/tool/self-evaluation、Graph trace 六个字段和 feedback success；summary 新增 orchestration version、final node、termination reason、degraded、transition count 和 evidence retry count。
  • PowerShell parser 语法检查通过；InterviewDemoScriptContractTest 2 tests 通过，覆盖 exact runId URL/response、orchestration fail-fast 和 summary 字段。

Final deterministic gates

  • authoritative/focused regression：39 suites / 157 tests，0 failure、0 error、0 skipped；覆盖三层 Graph、全部 Graph Node/router/trace builder、Chat/Trace/Gatekeeper/Composer、Controller、Repository、schema、feedback/tool recorder 和 demo contract。
  • fixed diagnosis eval：12/12 passed，verdict distribution 为 PASS=5、LOW_CONFID=6、REJECT=1；same-baseline diff 无 regression、0 items。
  • mvn -q -DskipTests test-compile 通过；当前 change strict 通过，16 个主 specs strict 全部通过。
  • git diff --check、legacy executable refs、current-doc stale refs 和 unexpected schema change 检查全部通过。
  • focused 回归日志中的 Graph ERROR/exception stack trace 来自 ChatServiceGraphIntegrationTest 对 FAILED/no-answer/unhandled failure 的显式契约用例，Maven exit 0，不是未解释的 live ERROR。

Live failure diagnosis and correction

  • 首次 live identity：sessionId=iss-011-stage5-20260717140450，runId=run-6db680f8-f764-49d1-995f-0e55a4b05a06。demo contract 在 exact Trace run.orchestrationTrace=null 处 fail-fast，未提交 feedback；Run 为 CHAT/FAILED，步骤/工具均为 0。

  • 新日志根因：DiagnosisOrchestrationTraceBuilder 收到类名相同但 classloader identity 不同的 OrchestrationEvent，instanceof 失败并抛出 orchestration events contain unsupported value。这是 Spring Boot DevTools live classloader 才暴露的 Graph state 表示缺陷，单元 JVM 未复现。

  • 冲突分类：代码偏离/运行时兼容 bug，OpenSpec 对 non-empty orchestration trace 和 live Maven startup 的要求正确，不修改验收口径。

  • RED：新增 portable event map builder 回归，修复前 1 test error；GREEN：Graph state 的 production/test actions 改存 classloader-neutral Map，builder兼容 local record/Map，Node/Workflow assertions 改读 Map。

  • 修复后先运行 5-suite Graph/Node/Runtime/Chat integration focused gate，再运行完整 39 suites / 157 tests，全部 0 failure/error/skipped；首次 Maven 进程链已按 ownership 停止，9900 已释放。

  • 第二个 live blocker 为外层 Graph RunnableConfig 的 resume metadata 被原样传给内层 ReactAgent，触发 Resume request without a configured checkpoint saver。回归先证明 nested config 与 outer config 同一且含 HUMAN_FEEDBACK，再改为保留 sessionId/runId、剔除 resume/state-update/checkpoint 控制信息的独立配置；5 suites / 50 tests 和随后完整 39 suites / 157 tests 通过，临时 [DEBUG-ISS011-NODE] 探针已删除且源码扫描为 0。

  • 2026-07-17 的一次长请求在工具执行期间遭遇外部 MySQL 瞬时 Connection is closed，留下精确 RUNNING 失败尝试；仓库查询工具随后证明数据库恢复且 server wait_timeout=28800。该失败未被当作验收通过，失败 Run 保留为真实审计记录。

Accepted live E2E

  • 启动：mvn spring-boot:run "-Dspring-boot.run.profiles=mvp-demo"；启动前 9900 空闲，隐藏进程链为 cmd 25080 -> Maven Java 17860 -> app Java 10732，readiness 后执行固定 payment-timeout demo。
  • identity：sessionId=iss-011-stage5-20260720015557，runId=run-808ac38f-3ad0-4462-a6d0-ed50d8686473；Chat/Trace exact identity 一致，answer 长度 109，feedback request success。
  • Trace：Run=CHAT/SUCCESS，8 AgentSteps、12 ToolInvocations，self-evaluation 非空；stategraph-v1，final node=fallback，termination=fallback_completed，degraded=true，3 transitions，evidence retry count=0。
  • Fallback 原因是 Gatekeeper LOW_CONFID 且本轮模型输出缺少 source_invocation_id；这是按冻结契约执行的安全降级，answer 非空且未绕过 Gatekeeper，日志/DB 均可审计。
  • 最终日志发生跨日 rollover：7 月 20 日 active application.log/chat.log 全部属于本轮；application-error.log 最后写入仍为 7 月 17 日。本轮 rg " ERROR " 对 application/chat 为 0，新增 error-file bytes 为 0；session/run、Graph 75964ms、evaluation、exact Trace 和 useful feedback 均有关联日志。
  • MySQL：V012 orchestration_trace 为 nullable JSON；exact Run answer=109、duration=75964、token=111802、steps=8、tools=12、evaluation len=8822、trace len=438、feedback=useful；JSON 路由与 Trace 完全一致。
  • ownership：AgentStep 8、ToolInvocation 12，各自 distinct session/run=1、wrong owner=0；唯一 session 下 wrong run/step/tool 均为 0。
  • cleanup：只停止 PID 10732/17860/25080，最终 9900 已释放，无剩余 owned process。
Reference in New Issue View Git Blame Copy Permalink