writer-work-flow/memory/decisions.md

实现决策记录（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] 并行审记账并发安全选 add-only（去网关 ledger flush）— @llm (T3.8)

• 背景：三审同 superstep 并行共用请求 session，SqlAlchemyLedgerSink.record 的 await flush() 是唯一让步点→第二/三审 flush 重入「Session is already flushing」→被 run_review 吞成 incomplete、foreshadow/pace 静默丢失（T3.7 暴露）。
• 选择：record 改 add-only（去 await flush()，只 session.add(row)）。session.add() 同步不让步→并行协程不交错；持久化仍靠端点/事务末尾 commit()（自动 flush 待决行）。
• 理由 / 取舍：最小改动、单 owner（只动 ledger.py），不牵动 apps/（@backend）。前提已校验：①并行审区间无 DB 查询触发 autoflush（review_context 取自 state、适配器不碰 session）；②draft/review/accept/outline 端点末尾均已 commit。缓冲/独立 session 方案跨 owner、更重，不取。
• 影响：C1 边界语义不变（commit 责任方未变）；凡新增「并行用网关产 usage」路径，sink 必须保持 add-only、不得在并行段 await flush。新增并发回归测试 test_ledger_concurrency.py。

[2026-06-18] 节拍图用定高 CSS 柱 + 文本 sparkline，不引图表库 — @frontend (T3.6)

• 选择：beat_map(int 序列) 按本序列 min..max 线性归一到 7 档 ▁..▇（全相等→居中档，最低柱给 12% 可见高度），渲染定高 CSS 柱 + aria-label="爽点节拍图 ▁▃▅…"。静态无动画→天然满足 prefers-reduced-motion。
• 理由：KISS，避免图表库依赖。影响：T3.7 节拍图 role="img" selector。

[2026-06-18] 大纲 beats 存储形 + 写侧 repo 命名 — @backend (T3.5)

• 背景：outline.beats DB 列是 JSONB dict，但 outliner 产 list[str]；读侧 OutlineRepo(C5/memory)已占名。
• 选择：写侧 SqlOutlineWriteRepo 把 list 包成 {"beats":[...]} 落库（读侧同形 round-trip 一致），API 出参 OutlineChapterView.beats 解包成裸 list[str]。写侧命名加 Write 前缀避撞 C5 读侧（同 DigestAppendRepo/ForeshadowLedgerRepo 先例）。volume 由端点提供（schema 无逐章卷号，M3 默认全卷 1）。get_outline_gateway 复用 build_gateway_for_tier(...,"analyst")、独立缝便于测试 override。
• 影响：C3 扩(outline 端点)；T3.6 渲染 beats 裸 list + 窗口徽标；T3.7 断言 outline 行 beats 列形。

[2026-06-18] 验收后伏笔到期扫描挂 BackgroundTask + 重复code/非法转移映射 VALIDATION(422) — @backend (T3.2)

• 背景：§5.5 步骤3 TODO(M3) 要验收后置 OVERDUE；登记/状态端点需映射 DB 唯一冲突与非法状态机转移到错误信封。
• 选择：(1) accept 端点 commit 成功后经 FastAPI BackgroundTasks 登记 run_overdue_scan（自建独立 session，因请求 session 已关闭）；扫描抽纯 async 函数 + 可注入 repo_factory/session_factory 缝，单测直接 await 注 fake、不起后台线程。(2) 重复 code(IntegrityError)/InvalidTransition 都映射 ErrorCode.VALIDATION(422) 非 409——现有 409 码 CONFLICT_UNRESOLVED 语义=未决冲突，复用不符；未新增 shared 错误码。
• 影响：C3 扩(foreshadow 登记/状态端点)；§7.4 持久性局限(进程内/重启丢任务)原型接受、不引 jobs 表；T3.5 看板/outline 续接本 router；T3.7 真 pg 断言 OVERDUE。

[2026-06-18] 伏笔写侧 Repository 加 Ledger 前缀避免与读侧同名 — @backend (T3.1)

• 背景：读侧 ForeshadowRepo/ForeshadowView/SqlForeshadowRepo（domain/repositories.py+memory/）已被 assemble(C5 稳定)占用且 View 最小（无 importance/links/progress）。M3 写侧账本需更全 View + 写方法。
• 选择：写侧命名 ForeshadowLedgerRepo/SqlForeshadowLedgerRepo/ForeshadowLedgerView，落 domain/foreshadow_repo.py；读侧不动。状态机纯函数落 domain/foreshadow_state.py（ForeshadowStatus StrEnum + transition/is_overdue/apply_overdue_scan/InvalidTransition）。
• 理由：同 T2.3 DigestAppendRepo vs 读侧 DigestRepo 先例，读写分离免歧义、不破坏 C5。写方法只 flush 不 commit（commit 归 T3.2 扫描任务 / T3.5 端点）。
• 影响：T3.2 验收后扫描 / T3.5 看板端点消费 ForeshadowLedger*。

[2026-06-18] 大纲节点不接进 review 图、不做失败隔离 — @llm (T3.4)

• 背景：续审在 run_review 内把网关失败隔离为 incomplete（§5.2 任一审不阻塞其余）。
• 选择：大纲是独立生成（不在写章/审稿流水线），run_outline 裸函数、网关失败直接上抛由 T3.5 端点处理；带 output_schema 时 parsed 非 OutlineResult 抛 ValueError（C1 违约即显错，不返回空大纲）。
• 影响：C6 扩（outliner spec + OutlineResult + run_outline 缝）；T3.5 端点调 run_outline 持久化 outline 表。

[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。