refactor(todo): converge canonical semantic kernel across control plane

[huangruiteng]

Problem

The Todo migration had two related kinds of semantic duplication: Python read paths independently classified and ordered Todo records, while TypeScript mutation callers and the Python provider independently encoded projection delivery and archive acknowledgement states. The closed PRs #4274, #4276, #4277, and #4278 were successive slices of the same RFC stage, but each stopped before the full cross-language boundary was validated.

Change

This PR absorbs the functional content of #4274–#4278 into the existing TypeScript Control-Plane Migration RFC stage and the shared-authority compatibility boundary. It does not create a new RFC.

• Centralize Python Todo task class, title-aware actionability, dependency readiness, agent eligibility, priority ordering, and canonical read records in todo_semantics.py.
• Keep projection.py as an import-only compatibility facade and migrate production consumers to the semantic owner.
• Define one typed TypeScript projection-delivery contract for pending, not_required, delivered, and current.
• Migrate claim, create, monitor-poll, terminal lifecycle, compatibility edit, quota monitor, and provider acknowledgement callers to the shared contract.
• Reject unknown provider delivery states before mutation or acknowledgement decisions; only delivered and current permit archive acknowledgement.
• Add composition and causal-chain fixtures covering mutation, no-op, delivery retry, idempotent replay, terminal no-op, and failed-display paths.
• Update the existing bilingual TypeScript migration RFC to record the completed stage and its compatibility boundary; restore the pre-existing RFC index entries.

The process-only AGENTS/book guidance and the earlier draft standalone semantic-kernel RFC were intentionally excluded. They are not part of the shipped control-plane contract.

Semantic result

The same Todo no longer receives different classification, eligibility, ordering, or delivery acknowledgement semantics depending on whether it is read through summary, status, quota, TypeScript coordination, or the Python provider path. Markdown remains a compatibility projection, and this PR does not promote a provider or change authority ownership.

Validation

• npm run typecheck:control-plane — passed.
• npm run test:control-plane with the project Python runtime — 1218 passed, 1 skipped.
• uv run pytest -q tests/control_plane/test_todo_semantic_kernel.py tests/control_plane/test_todo_provider_projection.py — 9 passed.
• uv run mypy — no issues in 22 source files.
• Focused projection-delivery and production-scale fixture tests — 5 passed.
• loopx-meta read-only status — ok=true, 0 contract errors; agent Todo readback succeeded with 42 records. One existing historical index warning remains.
• loopx change-quality verify — valid receipt cqr_fe9d104e6aac14c689f2 for the exact final diff.
• loopx canary premerge --from-git-diff --goal-id loopx-meta — 17/18 selected checks passed. The only failure is the existing hot-path-interface-budget-smoke dashboard payload budget; the same 18,930-character baseline failure reproduces on origin/main, so it is unrelated to this PR.

[huangruiteng]

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

动机

本次评审针对 exact head ffb1efc3377b70dcfba5a246cb60af75e64f399d，基线为 main 的 787e8dd830887df0114793c59e88bd01d6b6d73d。PR 的目标是把 Todo 语义判断、projection delivery 和 task-graph 关系收敛到更清晰的拥有者，消除 Python/TypeScript 两套近似规则长期漂移的风险。这个动机是成立的：旧的 projection.py 同时承担语义实现和兼容出口，调用方还需要自己理解 pending/delivered/current 等状态，后续每个边界修复都容易漏掉另一条路径。

改动思路

实现把 Python 语义函数集中到 todo_semantics.py，把 projection.py 缩成兼容性 re-export；TypeScript 侧用显式的 projection-delivery 联合类型区分 pending、delivered、current 和 not_required，再把 task graph/planning relations 接到这些 typed 结果上。这样，真正的决策仍在既有 control-plane capability 边界内，Python 只负责适配，未新增 authority writer、lease 权限或默认外部副作用。正向路径是：turn/adapter 产生 typed Todo intent，语义 kernel 计算结果，delivery consumer 依据明确状态投影；负向路径应拒绝未知关系、截断输入和不完整 projection，而不是把任意 opaque 字符串当作图边。

我特别复核了兼容出口与 public facade 的反事实：仅让 projection.py 继续能 import 并不能证明 canonical owner 已经迁移完成，因为 status.py 还有一份用于架构审计的来源 allowlist。这个 allowlist 也是 shipped guard 的一部分，必须和新的真实 import owner 同步。

具体改动

这次 exact head 共 77 个文件，新增 2417 行、删除 1126 行，包含语义 kernel、projection delivery、task graph/planning relations、Python/TypeScript 调用方、RFC 双语文档和回归 fixture。整体范围和目标一致，但仍属于一次较大的边界迁移，必须让所有架构审计和平台检查同时闭合。

关键代码讲解

1. loopx/control_plane/todos/todo_semantics.py 现在承载原先散落在 projection 层的语义函数；这是运行时真正的 Python 决策入口。
2. loopx/control_plane/todos/projection.py 只做兼容 re-export，能保护现有 import，但不应继续被审计记录为 canonical owner。
3. TypeScript projection_delivery.ts 使用 tagged union 表达 delivery 状态，消费方可按状态穷举处理，避免用字段是否存在来猜测结果。
4. loopx/status.py 的 _PUBLIC_COMPAT_REEXPORTS["todo_item_is_expired_monitor"] 仍写成 loopx.control_plane.todos.projection；而同文件顶层实际从 loopx.control_plane.todos.todo_semantics 导入。这个差异就是本次 blocker。

对主干的风险

我在 exact head 上运行了 9 个 Python semantic/projection 测试和 14 个 TypeScript projection/fixture/task-graph 测试，均通过；这些结果说明 kernel 的主要正向、未知关系、截断输入和 delivery 因果链有覆盖。但架构边界测试 test_public_facade_import_only_reexports_match_the_audited_allowlist 实际失败，报出的唯一差异正是上述 todo_item_is_expired_monitor 来源路径。也就是说，兼容 facade 虽然让 import 表面可用，公共 status facade 的 ownership audit 仍然会失败，test-shard (1) 随之失败，pytest wrapper 和 merge-gate 也不能通过。

此外，exact head 的 windows-powershell 仍以 installer/quota status 路径的 skip + exit 1 失败。这个失败是否是 main 基线问题需要继续确认，但“main 也失败”不能替代当前 PR 的 required check 证据。负向场景的最小修复是：把 status allowlist 更新为 todo_semantics（或提供有明确理由且由审计测试接受的兼容 owner），保留该架构回归测试；同时修复或按仓库规则解决 Windows 检查并在同一 head 重跑所有 required checks。未修复前，合入会把一个可见的 canonical-owner 漂移留在主干，并使后续贡献者误判语义实现位置。

我的整体评价

收敛 semantic kernel 的方向正确，typed delivery、task graph 约束和正负路径 fixture 也让后续演进更容易；但当前 exact head 还没有满足“公共 facade 来源一致且 required checks 全绿”的完成条件。由于存在可复现的 P1 架构回归和未闭合的平台门禁，我给出 REQUEST_CHANGES。请先修正 _PUBLIC_COMPAT_REEXPORTS 与新的 canonical owner 对齐，处理 Windows/merge-gate，再用新的 exact head 复审；修复后我会重点复查兼容出口、status import audit 与 disabled/default 路径是否保持原行为。

English verdict: REQUEST_CHANGES on exact head ffb1efc; status.py still audits todo_item_is_expired_monitor against the removed projection owner, and required shard/Windows/merge-gate checks are red.

[huangruiteng]

Superseded by the re-review for the corrected exact head 03b6469: #4279 (review). The earlier assessment targeted the pre-fix head ffb1efc and should not be used for the current merge decision.

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-review)

动机

该 PR 将 Todo 的任务分类、标题感知 actionability、依赖就绪、agent eligibility、priority ordering、canonical read records，以及 projection-delivery acknowledgement 从多个 Python/TypeScript 位置收敛到明确的语义 owner。此前同一条 Todo 可能在 status、quota、provider 和 coordination 路径得到不同的分类或 delivery 结论；这类细微差异会让 work 被错误排序、重复确认或永远留在 pending。PR 还吸收了 #4274–#4278 的 RFC 阶段切片，因此目标是完成一个可验证的 ownership boundary，而不是再建一套平行框架。审阅范围是 base f88aae3a63c9a88fb2ddd3477f5b8dc3a05c2e0f 到 exact head 03b646932af652761b0b0a5d4c7965be66f2a9fa，58 个文件、+1193/-871。

改动思路

Python 侧把可复用的读取和状态规则集中到 todo_semantics.py，原 projection.py 缩成仅用于真实兼容导入的 facade；生产调用者迁移到 canonical owner，但旧 import 仍可解析。TypeScript 侧定义 typed ProjectionDeliveryStatus（pending、not_required、delivered、current），让 claim/create/monitor/terminal/provider callers 在 mutation 或 archive acknowledgement 前共享同一套判定。unknown delivery state 先被拒绝，只有 delivered/ current 才能确认归档；fixture 则覆盖 mutation、no-op、retry、replay、terminal no-op 和 failed-display 的因果链。最后一个 exact-head 提交把 loopx/status.py 的公开兼容 allowlist 从已移除的 projection owner 对齐到 todo_semantics，修复了架构边界 guard，而没有另造兼容层。

具体改动

关键代码讲解

• todo_semantics.py（loopx/control_plane/todos/todo_semantics.py）承载 task class、actionability、依赖/agent eligibility、priority 与 canonical read record；输入是 typed Todo 与 lifecycle/lease facts，输出被 status、quota、provider 和 coordination 读取。
• projection.py（loopx/control_plane/todos/projection.py）现在是 import-only compatibility facade，避免外部真实 import 断裂，同时不再保留第二份语义实现；provider_projection.py 将 provider rows 映射到 canonical projection。
• projection_delivery.ts（loopx/control_plane/todos/projection_delivery.ts）定义并解析 delivery 状态 union，未知值 fail-closed；todo_claim.ts、todo_update.ts、todo_monitor_poll.ts 和 terminal lifecycle 复用同一 parser。
• authority_store_transactions.ts 与 task_lease_*.ts 保持 provider envelope、generation、identity 和 lease 生命周期在各自 owner 内，只让 projection/delivery 语义共享，不扩大 authority。
• loopx/status.py:_PUBLIC_COMPAT_REEXPORTS（exact-head 最后提交）将 todo_item_is_expired_monitor 的 audited owner 指向 todo_semantics；tests/architecture/test_control_plane_import_boundaries.py 对该关系有回归保护。

对主干的风险

我复核了完整 exact-head diff，并特别走了正向与负向路径：有效 Todo 经过 canonical classification/ordering 后被 status/quota/coordination 消费；unknown delivery state、invalid lifecycle/lease transition、duplicate archive acknowledgement、replayed receipt、failed display 和 no-op delivery 都在 typed boundary 失败或保持 retryable，不会静默成功。兼容 facade 只保留真实导入需要的符号，allowlist 与实现 owner 已一致；没有把 projection 名称误当成新的 authority/actor lifecycle。默认行为仍是原有 status/quota/provider 语义，RFC 只记录已完成阶段，未引入产品或 benchmark 专用 obligation，也未授权 lease、host、delegation 或外部发送。

本地 exact-head 运行了 24 个 Python semantic/projection/architecture tests 与 14 个 TypeScript projection/fixture/task-graph tests，全部通过；远端 required checks（Sign-off、dependency review、build、dashboard acceptance、kernel/static、Node minimum/forward、Windows PowerShell、Python 四 shard、Stage2C、pytest、merge-gate）均通过，release/deploy/presentation 按配置跳过，Sonar 为 non-blocking。变更量较大，主要是此前同一 RFC stage 的闭环切片和 fixtures；生成的 chat asset 清理了增加了 diff 噪声，但没有新的运行时 owner。代码量判断为 proportionate：若只修一个调用者，旧的跨语言/跨 provider 语义分叉仍会回来；保留 facade、typed union 和边界回归是可逆且局部的最小完整方案。

我的整体评价

这是对 exact head 03b646932af652761b0b0a5d4c7965be66f2a9fa 的复审；此前较早 head 的 allowlist blocker 已由最后提交修复，并已用 architecture guard 与 hosted checks 验证。APPROVE。语义 owner、兼容导入、delivery union、replay/no-op 负向路径和 required checks 均闭合；后续只需继续保持 import-boundary 与 unknown-state 回归，不需要再扩展框架或改变 authority。

English verdict: APPROVE — exact head 03b6469; Todo semantic classification and projection-delivery acknowledgement now have explicit typed owners with a narrow compatibility facade. Focused Python/TypeScript/architecture tests and all required hosted checks pass; no blocking finding.

[huangruiteng]

Post-merge refinement / validation

• Merged commit: bb0ba5bf9c4677faed4d5ea3774b703663b8c133; merged PR head: 3916d923c5aef509252e8a64cb2e804ebdc14143.
• Rebased onto the then-current main before merge.
• Fixed the deterministic hot-path canary baseline drift: dashboard_status_json was 18,930 chars while the stale contract was 18,500. The established smoke and contract table now use a bounded 19,500-char budget; nested/top-level budgets were unchanged.
• Final local validation: 24 focused Python tests passed; control-plane TypeScript typecheck passed; 1,241 control-plane tests passed with 1 skip; Ruff passed; public/private boundary scan passed; LoopX standard premerge passed (9 catalog canaries, 8 risk-profile smokes, direct checks, and boundary scan).
• Hosted post-merge checks are still settling; the checks already completed are green, with remaining shards/mutants continuing asynchronously.
• Change-quality receipt before the final base moved: cqr_8395888cb403e3093c61; the merged PR itself is the authoritative final artifact.