# 实现决策记录（append-only）

> 实现期做出、而规格未覆盖的决策 + 理由。一条一决策，最新在最上。
> 与规格冲突的不要写这里——去改规格（见 CLAUDE.md「Conventions」）。重大架构选择见 `ARCHITECTURE.md §1.2 ADR`。

格式：
```
## [YYYY-MM-DD] <决策标题> — @skill
- 背景：为什么要决策
- 选择：选了什么
- 理由 / 取舍：
- 影响：动到哪些契约/模块/任务
```

---

## [2026-06-18] 网关结构化输出经可注入 `StructuredClient` 缝（instructor）— @llm
- 背景：`OpenAICompatAdapter` 需接 instructor 产结构化输出（C1 类型预留 `output_schema`/`parsed` 但 M1 未接线），但测试绝不可联网/碰真实 LLM。
- 选择：定义 `StructuredClient` Protocol（`create_with_completion(*, messages, response_model, **kw) -> (parsed, raw)`，即 `instructor.AsyncInstructor` 的形）；adapter 构造可选注入 `structured_client`，未注入时懒构建 `instructor.from_openai(self._client)`。`run()` 透传 `result.parsed → LlmResponse.parsed`。
- 理由 / 取舍：保留既有「注入 client 便于测试」风格，结构化路径同样可注 fake。`ProviderResult.text` 对结构化路径置为 `parsed.model_dump_json()`（便于日志/留痕），程序消费走 `parsed`。
- 影响：契约 C1（`run()` 填 `parsed`；见 contracts 变更日志）、`ProviderResult` 加 `parsed` 字段；T2.2 续审节点据此消费。

## [2026-06-18] 审稿页终稿来源：页内可编辑 textarea（无 GET draft 端点）— @frontend (T2.6)
- 背景：审稿/验收都需「终稿」文本，但当前无 `GET .../draft` 端点拉取已存草稿。
- 选择：审稿页用可折叠 textarea 编辑终稿（`initialDraft=''`），重审传它为 `{draft}`（空→后端回退已存草稿），验收 `final_text`=它。
- 理由 / 取舍：对齐不变量#4（摘要从作者裁决/改稿后的终稿提炼）；作者可在审稿页改稿。代价：刷新页不自动回填草稿正文（M2 可接受，后续可加 GET draft）。
- 影响：仅前端；T2.7 E2E 用 `#final-text` 注入终稿。

## [2026-06-18] 验收事务边界：digest 提炼在事务外、单事务三写一次提交 — @backend (T2.4)
- 背景：§5.5 要求验收「单事务」含「从终稿提炼 digest（LLM 调用）」，但不能在持开 DB 事务里跨网络调 LLM（占锁）。
- 选择：digest 提炼 `extract_digest_facts`(tier=light，`ChapterDigestFacts` schema，经网关 `run().parsed`) 在 `run_accept_transaction` **之前**调用（R2），结果作 `digest_facts:dict` 传入；事务内只三次纯 DB 写（`promote_to_accepted`→`digest.append`→`set_decisions`）+ 末尾一次 `session.commit()`，任一步失败整体回滚。
- 理由 / 取舍：兼顾「digest 从终稿（不变量#4）」与「事务不跨网络」；提炼那次网关调用的 usage 随事务提交落 1 条 usage_ledger。digest 用 light、续审用 analyst 档位，统一经新 `build_gateway_for_tier(session, store, tier)`（`build_writer_gateway` 退化为 writer 特例）。§5.5 步骤 3（人物 latest_state/伏笔更新）留 `TODO(M3)` 占位，不引入 M3 表逻辑。
- 影响：契约 C3（accept/review/reviews 三端点）；T2.6 消费 `AcceptResponse`/`CONFLICT_UNRESOLVED`；T2.7 E2E 验证事务原子性+digest 来源+ledger。

## [2026-06-18] 验收-side 写侧 Repository 命名与提交边界 — @backend (T2.3)
- 背景：`chapter_digests` 已有读侧 repo（`memory/` 的 `DigestRepo.recent`，供 assemble）；M2 需写侧 append。同名易混。
- 选择：写侧命名 `DigestAppendRepo`/`SqlDigestAppendRepo`，落 `domain/digest_repo.py`，**共用 `DigestView`**；读侧仍在 `memory/`。新增 `review_repo.py`(`record`/`list_for_chapter` 新→旧/`set_decisions`) 与 `chapter_repo` 扩 `max_version`/`promote_to_accepted`/`latest_accepted`。
- 理由 / 取舍：读写分离避免同名歧义；写侧三 repo 的写方法**只 `flush()` 不 `commit()`**，提交归 T2.4 验收事务单次完成（对齐「写库副作用在编排/事务层」不变量）；`save_draft` 仍自 commit（M1 自动保存语义）。
- 影响：T2.4 在单事务里组合 `promote_to_accepted`→`digest.append`→`review.set_decisions` 后 `commit()`；R2/R3/R4/R5 决策落在这些接口点。
- 背景：ARCH §5.3 伪码里 `assemble` 直接返回 `LlmRequest`，会让 `packages/core/memory` 反向依赖 `packages/llm_gateway` 的类型，且使 M1 的 T1.2 强依赖 T1.1（无法并行）。
- 选择：`assemble(project_id, chapter_no) -> AssembledContext(stable_core: str, volatile: str, selection: SelectionTrace)`。稳定内核/易变各为**已确定性排序、无时间戳/UUID 的字符串**；write 节点(T1.3)再据此构造 `LlmRequest(system=[Block(text=stable_core, cache=True)], input=volatile)`。`SelectionTrace` 记录每个实体的入选理由，供 UX 注入透明面板(T1.6)。
- 理由 / 取舍：记忆服务只经 DB 通信、不应知道网关请求类型（对齐不变量①②）；解耦后 T1.1‖T1.2 可并行。§5.3 伪码视为示意，真正的缝是「确定性选择 → 序列化的 stable/volatile 文本」。
- 影响：契约 C5 输出形 = `AssembledContext`（非 `LlmRequest`）；C1 的 `Block`/`LlmRequest` 仅 gateway+orchestrator 使用。回写 ARCH §5.3 待 M1 落地后由 @docs 注一句。

## [2026-06-18] CLAUDE.md 不复制 spec 的枚举值，只重述跨文档规则 — @all
- 背景：CLAUDE.md 原先内联了 SSE 事件名、LLM 调用日志字段、错误码/envelope 形状等"会变的具体值"，ARCHITECTURE 一改即静默过期，使 CLAUDE.md 自身成为最大漂移源。
- 选择：CLAUDE.md 只保留跨文档、易错的**规则**（含 9 条架构不变量）；所有枚举型/具体值改为指向 ARCHITECTURE/PRODUCT_SPEC 对应 §（唯一真源）。新增"冲突裁决"段：ARCHITECTURE > UX_SPEC/DEV_PLAN > PRODUCT_SPEC，矛盾时回写上游。
- 理由 / 取舍：消除文档间漂移面、降低每 session 上下文成本；代价是查具体值需多跳一层到 ARCHITECTURE（可接受）。
- 影响：编辑 CLAUDE.md 的任何 agent 遵循此纪律——契约/枚举值落在 spec 与 `memory/contracts.md`，不在 CLAUDE.md。