128 lines
7.6 KiB
Markdown
128 lines
7.6 KiB
Markdown
## Context
|
||
|
||
ISS-011 的运行时和测试迁移已经完成：复杂 Chat 通过真实 Diagnosis StateGraph，Graph Nodes 使用显式 RunnableConfig/verified state，Run 保存 orchestration trace，三层权威 tests 已建立。剩余工作跨越代码清理、current docs、demo script、eval、live process、日志、数据库和 Issue 生命周期，必须按“静态/自动化先完成，live E2E 最后执行”的顺序收口。
|
||
|
||
全仓引用证明旧闭包为 `VerifierInputHook -> VerifierContextHolder + ToolTraceSummaryService`，外加 `ToolTraceSummaryServiceTest`。新 Graph 不依赖该闭包。current architecture docs 仍描述 Sequential/Hook/full trace；历史 issues/design-notes/fixtures 则应保留当时语义或历史兼容数据。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
|
||
- 删除旧闭包且保持 Graph parser/Gatekeeper/projection/evaluation 行为。
|
||
- 把 architecture index 声明的 current docs、active eval/demo docs 与真实 StateGraph/Run trace 对齐。
|
||
- 让 interview demo check 将 exact `run.orchestrationTrace` 作为强制验收字段和 summary 输出。
|
||
- 运行确定性 Graph/test/eval gates，再启动 Maven 完成唯一最终 live E2E。
|
||
- 对本次 E2E 的日志和数据库做 exact session/run 证据核验并清理进程。
|
||
- 全部通过后关闭/归档 ISS-011 和阶段 5 OpenSpec。
|
||
|
||
**Non-Goals:**
|
||
|
||
- 不修改 Graph 路由、Prompt、公开 API、DTO 或 DB schema。
|
||
- 不重写历史 archived/design-note 文档和 legacy eval fixtures。
|
||
- 不删除 UI/eval 对历史 `tool_trace_summary` 的兼容读取。
|
||
- 不治理仓库凭据、外部基础设施或其他 active issues。
|
||
|
||
## Decisions
|
||
|
||
### 1. 删除完整旧闭包，不留下空壳 Hook
|
||
|
||
删除 `VerifierInputHook.java`、`VerifierContextHolder.java`、`ToolTraceSummaryService.java` 和 `ToolTraceSummaryServiceTest.java`。保留空类或 deprecated wrapper 会继续让维护者误认为存在第二条 Verifier 输入路径，也会让 Spring component 扫描注册无消费者 service。
|
||
|
||
删除前后以全仓 definition/import/instantiation/type-use 搜索、test compilation、Graph suite、Gatekeeper/protocol tests 证明闭包；负向契约 test 可保留名称字符串，任何可执行类型依赖都视为 cleanup blocker。
|
||
|
||
### 2. current docs 改为显式 StateGraph，历史 docs 保留
|
||
|
||
必须更新：
|
||
|
||
- `mvp/architecture/README.md`
|
||
- `agent-orchestration.md`
|
||
- `session-trace-lifecycle.md`
|
||
- `current-mvp-architecture.md`
|
||
- `executor-evidence-pipeline-refactor.md`
|
||
- `harness-quality-gates.md`
|
||
- `feedback-architecture.md`
|
||
- `retrieval-observability.md`
|
||
- `mvp/eval/README.md`
|
||
- `mvp/demo/README.md` / trace checklist
|
||
|
||
历史 archived issues/design-notes 和 legacy fixtures不批量替换：它们记录演进阶段或兼容旧 Trace。current docs 若提到 `tool_trace_summary`，只能标注为历史读取兼容，不能描述为新 Verifier 输入/持久化源。
|
||
|
||
### 3. Demo script 是 final E2E executable contract
|
||
|
||
扩展 `run-interview-demo-check.ps1`：
|
||
|
||
1. 从 Chat response 获取 runId。
|
||
2. 查询 exact Trace。
|
||
3. 要求 `trace.data.run.orchestrationTrace` 非空。
|
||
4. 要求 version/final_node/termination_reason 非空，transitions 为数组。
|
||
5. 把 finalNode、terminationReason、degraded、transitionCount、evidenceRetryCount 写入 summary。
|
||
6. 保留 feedback 和 Prompt/Gatekeeper summary。
|
||
|
||
脚本必须 fail fast，不能用 session self-evaluation 或日志合成缺失的 Graph trace。
|
||
|
||
### 4. 自动化门禁先于 live E2E
|
||
|
||
顺序固定：cleanup source check → docs/script tests → Graph/Chat/Trace/Gatekeeper/Composer/Controller/Repository tests → diagnosis eval baseline/diff → test compilation → OpenSpec/static gates → live startup/E2E → logs → DB → process cleanup。
|
||
|
||
在 live 前发现的失败按 OpenSpec/code/test/documentation分类；live 后失败使用 diagnose loop，以 exact run evidence 定位，不通过放宽断言绕过。
|
||
|
||
### 5. Live E2E 使用唯一 identity 和可回收后台 Maven
|
||
|
||
- sessionId：`iss-011-stage5-<timestamp>`。
|
||
- Maven：`spring-boot:run` + `mvp-demo` profile，后台 hidden process，stdout/stderr 写入 `target/` 临时文件。
|
||
- readiness：轮询 9900，最长明确超时，不阻塞超过 60 秒且持续汇报。
|
||
- 执行：复用 interview demo script，输出写入 `target/iss-011-stage5-output/`，避免覆盖已提交 demo sample。
|
||
- 最终：停止应用进程树，确认 9900 无监听，删除临时启动/output文件。
|
||
|
||
如果 9900 启动前已被其他进程占用，先识别而不是杀掉未知进程；只有本轮启动的 PID 可被清理。
|
||
|
||
### 6. 日志与数据库证据只认本次 Run
|
||
|
||
启动前记录 `logs/application.log`、`application-error.log`、`chat.log` 长度和时间；E2E 后只读新增片段，并搜索 sessionId/runId、Graph执行、Flyway/JPA 和 ERROR。测试阶段写入的旧日志不计入 live 证据。
|
||
|
||
数据库通过 `scripts/query_mysql.py` 执行 read-only queries：
|
||
|
||
- `SHOW COLUMNS ... orchestration_trace`。
|
||
- exact `diagnosis_run` status/flow/answer/metrics/self_evaluation/orchestration trace/feedback。
|
||
- JSON_EXTRACT version/final_node/termination_reason/degraded/evidence_retry_count。
|
||
- exact run AgentStep/ToolInvocation count 和 distinct ownership。
|
||
- wrong session ownership count=0。
|
||
|
||
所有查询必须带 E2E sessionId/runId 或 schema column 条件；不接受全局 latest 代替。
|
||
|
||
### 7. Issue 归档是最后一个实现动作
|
||
|
||
E2E/log/DB 任一失败时 ISS-011 保持 active。全部通过后更新验收 checkbox和状态，将文件 move 到 `mvp/issues/archived/`，并把 issues index 从 active 移到 archived。OpenSpec archive 在 Issue move 后执行，Git commit 是阶段 5最后门禁。
|
||
|
||
## Interface Impact
|
||
|
||
- 等级：L2 内部类型删除 + demo/docs 增强。
|
||
- 外部 `/api/chat`、Trace、feedback、DB schema 和 JSON 字段：不变。
|
||
- 内部消费者：旧 Hook/ThreadLocal/service 无消费者，删除无需迁移调用点。
|
||
- Demo script 行为：新增 fail-fast orchestration trace contract和 summary 字段；旧 Chat/Trace/feedback outputs保留。
|
||
- 回滚：revert 阶段 5代码/文档；DB/生产数据无变更。E2E产生的 demo Run 是正常审计数据，不执行破坏性回滚。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- [隐藏反射/配置消费者未被 rg发现] → test compilation + Spring startup 是最终验证；发现即恢复并修正规格。
|
||
- [文档仍有历史术语] → current docs 白名单扫描；history/design-notes允许但索引明确非当前真理源。
|
||
- [live LLM 输出波动] → mock logs/metrics提供稳定工具证据；Graph允许安全 Fallback，但验收仍要求非空真实 orchestration trace和一致 Run生命周期。
|
||
- [外部 DB/Redis/Milvus/LLM不可用] → readiness/log/DB diagnose；不伪造通过，不修改验收口径。
|
||
- [停止进程误伤] → 只记录和终止本轮 Maven/Java PID，结束后用端口复核。
|
||
- [E2E output覆盖仓库样例] → 输出放 target临时目录，证据摘要提炼进 devflow 后删除临时文件。
|
||
|
||
## Migration Plan
|
||
|
||
1. 删除旧闭包，运行 source/test compilation/Graph安全回归。
|
||
2. 更新 current docs 和 demo script/checklist，增加静态脚本契约 test。
|
||
3. 运行完整 focused tests、diagnosis eval baseline/diff、OpenSpec/static gates。
|
||
4. Maven `mvp-demo` startup，运行 unique session E2E。
|
||
5. 检查新增日志片段和 exact DB数据，停止进程、清理临时文件。
|
||
6. 更新/移动 ISS-011，回填 devflow，archive OpenSpec，独立提交。
|
||
|
||
运行时回滚为 Git revert；数据库 V012列和 E2E Run可安全保留。
|
||
|
||
## Open Questions
|
||
|
||
无。清理闭包、current/history docs边界、E2E身份/证据和 Issue关闭门禁均已确定。
|