refactor(todos): unify canonical User completion updates and reviewed recovery

docs/architecture/rfcs/ledger/typescript-control-plane-migration-v0/2026-09-18-user-completion-updates.md

@@ -0,0 +1,16 @@
+# User completion updates join canonical transactions
+
+| Field | Evidence and boundary |
+| --- | --- |
+| Goal/source | #4574 R5; TS T1/T2; shared-authority local-default L2. A new local default must support actual callers before D2/D3 qualification or writer retirement. |
+| Demonstrated gap | On fixed main `0d90d6f66`, public User `todo update --status done` executes a declared command and then fails the legacy writer fence on both File and SQLite. The canonical `complete` owner already exists; rebuilding its decisions in Python would duplicate authority. |
+| Delivered operation | The existing update facade routes User completion to the TS terminal owner, sharing edit decoding/materialization and preserving combined metadata, original and candidate authority, completion policy, exact lease release, CAS, business receipt and projection intent. Agent update-done stays rejected. |
+| Semantic corrections | Linked-successor existence/self-cycle admission precedes terminal validation effects. User validation resume binds the issued provider revision, retains the registry witness and refreshes time; expired explicit proof cannot reacquire. Update-only delegation cannot close another owner's Todo by clearing ownership. New annotations preserve completion time and do not rerun validation or require a retired private declaration. |
+| Caller closure | The existing Chat User-completion action uses reviewed canonical basis and operation identity. Validation failure produces no success receipt; projection interruption and lost action response recover the original operation. The shared review plan and packaged frontend retain its retry button. CLI/API names and provider selectors do not change. |
+| Reuse/retirement | Extract the actual edit decoder/materializer from ordinary update, reuse terminal admission/CAS/outbox and the existing public authoring rules. Share Python validation-effect execution and failure projection, deleting the terminal transport's duplicate blocks. Python adapters, private command execution and permanent Markdown rendering still have callers; no unused native-CLI framework is added. |
+| Validation | Fixed-baseline real CLI counterexample; complete legacy/native synthetic graph across File, SQLite, NoKV and isolated PostgreSQL; fresh/expired/unauthorized/malformed/no-write cases, changed revision, immutable replay and delegation counterexamples. Source CLI/Chat, installed wheel/HTTP and packaged browser recovery exercise user entry points. A read-only frozen full-graph rehearsal preserves all pre-existing Todos/leases and compares complete heads across providers and baseline ordinary edits. |
+| Remaining boundary | This closes one L2 operation, not every event/Monitor caller or executor-held external-effect fence. Existing D1 consumer work, SQLite D2 capacity/soak and D3 integrated cutover retain their owners. The already merged #4315 repair is reconciled rather than counted as new implementation. New-Goal defaults and existing-Goal cohort migration remain separate changes; native TS distribution is not a prerequisite. |
+| Compatibility/rollback | Ordinary v0–v2 update requests and existing terminal receipt identity remain unchanged; they reject the new v3 completion envelope. Finish pending new-operation recovery before downgrading. Preserve historical receipts and projection/import/export responsibilities; never restore stale Markdown authority. |
+
+The [operation reference](../../../../reference/canonical-todo-completion-update.md)
+records the public command, typed ownership and bounded retirement contract.

docs/architecture/rfcs/ledger/typescript-control-plane-migration-v0/2026-09-18-user-completion-updates.zh-CN.md

@@ -0,0 +1,16 @@
+# 用户完成更新进入 canonical 事务
+
+| 字段 | 证据与边界 |
+| --- | --- |
+| 目标／来源 | #4574 R5、TS T1/T2、shared-authority local-default L2。新的本地默认必须先覆盖实际 caller，再做 D2/D3 资格化和旧 writer 退出。 |
+| 已复现缺口 | 固定 main `0d90d6f66` 上，用户 `todo update --status done` 在 File／SQLite 都先执行声明的验证命令，再因旧 writer fence 被拒绝。已有 canonical complete owner；在 Python 重建其决策会复制 authority。 |
+| 交付操作 | 既有 update facade 将用户完成交给 TS terminal owner，共用编辑解码／物化，保留合并字段编辑、原始和候选权限、完成策略、精确租约释放、CAS、业务回执及投影意图。Agent update-done 仍拒绝。 |
+| 语义修复 | terminal 的关联 successor 存在性／自环检查提前到验证效果之前。用户验证续提绑定签发时 provider revision，沿用 registry witness 并刷新时钟；过期显式证明不能重新获取租约。仅有 update 委托不能通过清除 owner 关闭他人的 Todo。完成后新备注保留完成时间，不重跑验证，也不依赖已退休的私有声明。 |
+| 调用闭合 | 既有 Chat 用户完成动作使用审阅时 canonical basis 和操作身份。验证失败不产生成功回执；显示投影中断和 action 响应丢失均恢复原操作。共享 review plan 与打包前端保留重试按钮。CLI／API 名称及 provider 选择器不变。 |
+| 复用／退出 | 从普通 update 提取实际编辑 decoder／materializer，复用 terminal 准入／CAS／outbox 和公开 authoring 规则；共用 Python 验证效果执行与失败投影，删除 terminal 传输层中的重复代码块。Python adapter、私有命令执行和永久 Markdown 渲染仍有 caller，不新增未使用的原生 CLI 框架。 |
+| 验证 | 固定基线真实 CLI 反例；File、SQLite、NoKV、隔离 PostgreSQL 上完整 legacy／native 合成图；新鲜／过期／越权／畸形／不写入、revision 改变、不可变回放和委托反例。源码 CLI／Chat、安装后的 wheel／HTTP、打包浏览器恢复覆盖用户入口。只读冻结全图保留全部既有 Todo／lease，并比较 provider 完整 head 及基线普通编辑。 |
+| 剩余边界 | 闭合一个 L2 操作，不代表全部 event／Monitor caller 或 executor-held 外部效果 fence 完成。D1 消费者、SQLite D2 容量／soak、D3 集成切换仍由原有 owner 推进；核对已合入 #4315 修复，不重复计算实现。新 Goal 默认与已有 Goal 分组迁移是独立变化，原生 TS 分发不是前置条件。 |
+| 兼容／回滚 | 普通 v0–v2 update 请求及既有 terminal receipt 身份保持；旧 wire 拒绝 v3 完成 envelope。降级前处理新操作的待恢复投影，保留历史回执与投影／导入导出职责，不恢复陈旧 Markdown authority。 |
+
+[操作参考](../../../../reference/canonical-todo-completion-update.md)记录公开命令、
+类型化所有权及有界退出合同。

docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md

@@ -3071,12 +3071,12 @@ or moving a helper is not by itself a package exit.
 | Wave / package | Reviewable delivery and TS ownership payoff | Dependencies and exit evidence |
 | --- | --- | --- |
 | A / L1: Monitor configuration (this slice) | Existing `todo update` config enters the TS planner/CAS/receipt; delete Python's duplicate intent field catalog. Separate authoring from observed hashes, times and generations. | Ordinary CLI/API, clear/omission, active lease proof, no-op/replay, failed display delivery, complete fixture and real providers. This does not complete delegated Chat or leased polling. |
-| A / L2: Complete public mutation admission | Inventory actual CLI/Turn/Chat callers; close remaining effect-owned user decisions, delegated owner actions and Monitor lifecycle transitions with validated actor/grant facts. | Build on merged T1 owners, not a generic raw patch. Prove permission rejection and exact caller response; remove replaced Python admission and name every remaining unsupported command. |
+| A / L2: Complete public mutation admission | User completion updates now share the TS edit/terminal transaction and reviewed Chat recovery. Continue the actual CLI/Turn/Chat inventory for remaining effect-owned decisions, delegated owner actions and Monitor lifecycle transitions; [caller contract](../../reference/canonical-todo-completion-update.md). | Build on merged T1 owners, not a generic raw patch. Prove permission rejection and exact caller response; remove replaced Python admission and name every remaining unsupported command. |
 | A / L3: Canonical lease lifecycle | Standalone acquire/takeover, atomic claim lease admission and maintenance reuse TS facts/decision/materialization and one provider opening fence. Explicit claimed-work transfer now commits source-authorized Todo ownership and the new lease generation together; canonical request types exclude legacy held-fence fields. Acquire success verifies current execution proof; canonical completion can recover missing display. | Full-head scope conflict, archived/ineffective holders, exact create-CAS retry, stale execution, process loss and real CLI/four-arm rehearsal are covered. [Operation and remaining callers](../../reference/canonical-lease-renew.md). Executor-held external-effect fences remain explicit work; D1–D3/default holds remain. |
 | B / L4: Leased Monitor poll and settlement | Current execution proof now binds CLI intent, observation/generation/independent-successor CAS and historical business receipt. Quota pending admission is frozen before the business write; recovery preserves that decision after lease retirement. | Existing L3 lease lifecycle, real File/SQLite/PostgreSQL, mixed fixtures, process death between business/quota commits, competing renewal and unchanged polling. [Operation and snapshot rehearsal](../../reference/protocols/quota-monitor-observation-receipt-v0.md). No lease lifecycle effects or quota spend; separate authorities stay separate. Event callers, wider L2 admission and D1–D3/default remain open. |
 | B / L5: Consumer and display closure | Reconcile #4316, audit Turn/quota/Dashboard/Chat source reads, and finish D1 freshness/recovery through the existing projection outbox. | CLI, Lark/Chat and packaged frontend read back their affected interactions; absent/stale display, empty canonical state, pending projection and data beyond UI limits. Delete post-promotion legacy fallbacks with each consumer. |
 | A–C / L6: Local durability qualification | Continue contributor-owned #4224/#4328 on the selected SQLite profile; reuse File/NoKV references and complete 7.2's ledger. | Capacity, real process/crash/restore/upgrade, retained receipts/scans, consumer lag, supported runtimes/OS and the separately authorized >=10-day synthetic soak. Missing measurements remain holds. |
-| A–C / L7: Capture continuity | Resolve #4315 with source-correlated archive retirement and identical lease membership at bootstrap and later writers; activate its row/mutant and complete the mixed-writer/event-source matrix. | Real CLI/File capture, history retained, partial drain unqualified, crash/replay and a new lease after archive/rebootstrap. Keep the legacy migration window provable; T4 cannot be used to skip this row. |
+| A–C / L7: Capture continuity | Reconcile the merged #4315 archive/lease-membership repair; qualify its ladder row/mutant and sustained mixed-writer/event-source matrix rather than reimplementing the closed defect. | Real CLI/File capture, history retained, partial drain unqualified, crash/replay and a new lease after archive/rebootstrap. Keep the legacy migration window provable; T4 cannot be used to skip this row. |
 | C / L8: Whole-Goal rehearsal and cohort migration | Integrate one exact revision/profile after L2–L7; drain capture, fence old writers, verify canonical readback and projection, then rehearse fenced export/rollback. | D3 evidence packet binds lineage, cursor, source digest, command coverage and profile. Existing Goal migration requires explicit cohort approval; no per-command split authority or stale Markdown revival. |
 | D / L9: New-Goal default and bounded retirement | A dedicated default-change PR makes new-Goal creation/onboarding choose the qualified local profile, including settings/readback, installer and packaged clients. Retire old business writers only as their final callers and migration window close. | L8's integrated product/rollback qualification; distinguish new Goal default from existing Goal migration. Publish compatibility/disable guidance, keep explicit provider choice, permanent rendering and validated import/export. T4 can continue after the default ships. |
 

docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md

@@ -2434,12 +2434,12 @@ canonical renew 候选，#4328 是 SQLite D2 首批测量／恢复候选；它
 | 波次／PR 包 | 完整交付内容与 TS 归属收益 | 依赖与退出证据 |
 | --- | --- | --- |
 | A／L1：Monitor 配置（本切片） | 现有 `todo update` 配置进入 TS planner／CAS／receipt，删除 Python 重复 intent 字段表；区分配置与观察 hash、时间、代数。 | 普通 CLI/API、清除／省略、active lease proof、no-op／replay、展示失败恢复、完整 fixture 和真实 provider。不宣称完成委托 Chat 或 leased polling。 |
-| A／L2：公共 mutation admission 闭合 | 盘点 CLI／Turn／Chat 实际 caller；以可信 actor／grant 事实闭合剩余 effect-owned 用户决策、委托 owner 动作和 Monitor lifecycle。 | 复用已合并 T1 owner，不开通通用 raw patch；验证权限拒绝和 caller 响应，删除替代的 Python admission，列全未支持命令。 |
+| A／L2：公共 mutation admission 闭合 | 用户 completion update 已共用 TS 编辑／terminal 事务与 Chat 审阅后恢复；继续盘点剩余 effect-owned 决策、委托 owner 动作和 Monitor lifecycle 的 CLI／Turn／Chat caller。见[调用合同](../../reference/canonical-todo-completion-update.md)。 | 复用已合并 T1 owner，不开通通用 raw patch；验证权限拒绝和 caller 响应，删除替代的 Python admission，列全未支持命令。 |
 | A／L3：canonical lease 生命周期 | 独立 acquire/接管、原子 claim 的 lease 准入及维护复用 TS facts/decision/materializer 与同一 provider opening fence。显式联合交接由源持有者授权，一次提交 Todo 归属与新租约 generation；canonical 请求类型不再携带 legacy 持锁字段。Acquire 成功必须校验当前执行 proof；canonical 完成可恢复缺失展示。 | 已覆盖完整 head scope 冲突、归档/失效 holder、创建 CAS 原样重试、旧执行、进程中断、真实 CLI 与四臂演练。[操作及剩余 caller](../../reference/canonical-lease-renew.md)。跨外部 effect 的 executor 持锁 fence 仍为明确工作；保留 D1–D3/default hold。 |
 | B／L4：leased Monitor poll 与 settlement | 当前 execution proof 贯穿 CLI intent、观察／generation／独立 successor CAS 和历史业务回执；业务写入前冻结 quota 准入，租约结束后仍按原决策恢复结算。 | 既有 L3 lease lifecycle、真实 File／SQLite／PostgreSQL、混合 fixture、业务与 quota 间真实进程退出、并发 renewal 和 unchanged poll；见[操作与快照演练](../../reference/protocols/quota-monitor-observation-receipt-v0.md)。不操作 lease lifecycle、不消耗 quota，不把两个 authority 假装成同一事务。Event caller、更广 L2 准入及 D1–D3/default 仍开放。 |
 | B／L5：consumer 与展示闭合 | 核对 #4316，审计 Turn／quota／Dashboard／Chat 的来源，复用 projection outbox 完成 D1 新鲜度和恢复。 | 验证 CLI、Lark／Chat、打包 frontend 的受影响交互；缺失／陈旧展示、权威空状态、pending 投影及超过 UI 上限的数据。逐个删除晋升后的 legacy fallback。 |
 | A–C／L6：本地持久化资格 | 延续 contributor 认领的 #4224／#4328，在选定 SQLite profile 上补齐第 7.2 节 ledger，复用 File／NoKV 对照。 | capacity、真实进程／crash／restore／upgrade、历史 receipt／scan、consumer lag、支持的 runtime／OS，以及另行授权的 >=10 天合成 soak。缺项继续 hold。 |
-| A–C／L7：capture 连续性 | 修复 #4315：归档的源事务明确退休 lease 引用，bootstrap 与后续 writer 使用一致成员范围；执行 row／mutant 和 mixed-writer／event-source 矩阵。 | 真实 CLI／File capture、保留历史、半完成 drain 不合格、crash／replay，以及归档／rebootstrap 后再申请 lease。不能借 T4 跳过迁移窗口证明。 |
+| A–C／L7：capture 连续性 | 核对已合入的 #4315 归档／lease membership 修复，完成对应 ladder row／mutant 与持续 mixed-writer／event-source 矩阵；不重复实现已关闭缺陷。 | 真实 CLI／File capture、保留历史、半完成 drain 不合格、crash／replay，以及归档／rebootstrap 后再申请 lease。不能借 T4 跳过迁移窗口证明。 |
 | C／L8：整 Goal 演练与分组迁移 | L2–L7 后汇合一个精确 revision／profile；drain capture、fence 旧 writer、回读 canonical 与投影、演练 fenced export／rollback。 | D3 包绑定 lineage、cursor、source digest、命令覆盖和 profile；已有 Goal 分组迁移需明确批准，不能按命令拆 authority 或复活旧 Markdown。 |
 | D／L9：新 Goal 默认与有界退役 | 单独 default-change PR 让新建／onboarding 选择合格本地 profile，配齐 settings／readback、installer 和打包客户端；最后 caller 与迁移窗口退出才删除旧业务 writer。 | L8 整体产品／回滚资格；区分新 Goal 默认和已有 Goal 迁移。发布兼容／停用说明，保留显式 provider、永久 renderer 和合法 import/export。T4 可在默认启用后继续收尾。 |
 

docs/architecture/rfcs/typescript-control-plane-migration-v0.md

@@ -571,6 +571,12 @@ the shared plan, not another per-agent checklist database.
 
 **T1 — close the public Todo update transaction.**
 
+User completion updates now compose the canonical edit planner and terminal
+transaction, including original/edited authority, source-bound validation,
+lease release and reviewed Chat recovery. The Python transport shares effect
+execution and failure projection. This closes one remaining public caller,
+not all T1 callers or the legacy writer. See [operation and compatibility](../../reference/canonical-todo-completion-update.md).
+
 The current ownership slice closes promoted claim transfer, claim clearing and
 executor-exclusion edits through this typed update planner. Normalization is
 part of request identity, so replay cannot restore a superseded claim. A
@@ -1644,3 +1650,9 @@ Python semantic owner, the handler boundary becomes chatty, two consecutive PRs
 increase bridge/scaffolding without retiring a facade, or a transaction cannot
 meet its invariant/recovery/performance gates without weakening existing
 behavior.
+
+## Appendix A: Execution ledger
+
+Measured delivery records live in the [per-entry ledger](ledger/typescript-control-plane-migration-v0/).
+Each entry names its delivered boundary and remaining acceptance gaps; the T1–T4
+checkpoints above remain the current migration plan.

docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md

@@ -451,6 +451,12 @@ commit。#4121（SQLite 候选）和 #4101（投影 receipt 保留）是独立
 
 **T1 — 闭合公开 Todo update 事务。**
 
+用户 Todo 的 completion update 现组合 canonical 编辑 planner 与 terminal
+事务，覆盖原始／编辑后权限、绑定来源的验证、租约释放及 Chat 审阅后恢复。
+Python 传输层共用效果执行和失败投影；这闭合一个剩余公共 caller，不代表
+所有 T1 caller 或旧 writer 已退出。见[操作与兼容边界](../../reference/canonical-todo-completion-update.md)。
+
+
 当前 ownership slice 已将 promoted 路径的 claim 转交、清除和执行排除编辑接入
 typed update planner。规范化参与请求身份，因此重放不能恢复已被后续操作取代的
 claim。带 lease 的 ownership 变化仍必须走 lifecycle，不是 metadata 授权；未
@@ -1318,3 +1324,8 @@ Rollback 恢复上一版本 artifact 与 fingerprint。在单独通过 state-sch
 变得 chatty、连续两个 PR 增加 bridge/scaffolding 却没有退出 facade，或一笔
 transaction 只能靠削弱既有行为才能通过 invariant/recovery/performance 门禁，
 就停止或 replan。
+
+## 附录 A：执行记录
+
+实测交付记录存于[逐条 ledger](ledger/typescript-control-plane-migration-v0/)。
+每条记录说明已交付边界及剩余验收缺口；上方 T1–T4 检查点仍是当前迁移计划。