refactor(harness): freeze single-agent contracts

2026-07-21 17:33:25 +08:00
parent 30d3296043
commit 58c39107c5
47 changed files with 2607 additions and 24 deletions
@@ -0,0 +1,20 @@
+# Decisions: single-react-design-freeze
+
+## 已确认决策
+
+- ISS-014 保留为总 Issue，实施拆成 11 个独立、串行 sm-flow changes。
+- 每个 change 必须完成 Apply、阶段验收、OpenSpec Archive 和 Git commit 后才能进入下一项。
+- Apply、Archive 和阶段 Git commit 已获得用户对整个目标的持续授权；仅方向性决策需要暂停。
+- `tool_call_id` 使用框架协议 ID，Harness 不生成第二套 ID。
+- `status=PROJECTING/READY/ERROR` 表示 invocation lifecycle；`evidence_status=EVIDENCE_FOUND/NO_EVIDENCE/ERROR` 表示结果语义。
+- `NO_EVIDENCE` 只能支持限定范围的 `NEGATIVE_OBSERVATION`。
+- KNOWLEDGE_QUERY 使用 answer items 绑定 `tool_call_id + document_id`，首版不进入 SemanticGuard。
+- `diagnosis_run` 是 previous turn 的持久化真理源；只有最近的 `DIAGNOSIS + SUCCESS` 安全发布结果可用。
+- 取消采用分层、可观测语义；同步模型调用不承诺无法证明的立即硬取消。
+- 底层重试压为一次 attempt，Router/SemanticGuard 的允许重试只由 Harness 执行。
+- 阶段 4 和 6A 不接管公开入口，阶段 6B 才执行原子 SSE 切换。
+
+## 权衡
+
+- contract types 提前落地会增加少量文件，但后续 output type、validator、持久化和 SSE 可以复用，避免多阶段字符串协议漂移。
+- Provider 侧凭据轮换是外部前置，阶段 0 只证明工作树已清理，不伪造外部完成状态。