refactor(work-items): unify typed Todo topology across planning and task graph

[huangruiteng]

Summary

• Share one typed Todo relation catalog across planning inventory, horizon and task graph. Retire Python predecessor indexes, condition splitting and traversal; keep the existing source adapter and public-safe evidence/handoff renderers.
• Correct read semantics: successor lineage is continues, unblocks links point from the waiting parent to the unblocking child, and Monitor generation conditions remain distinct from completion. Preserve parallel semantic edges and diamond joins at the node cap. Report missing targets separately from source/display truncation.
• Update both bilingual RFC execution cards without removing future stages. This closes one T3 interpretation boundary, not T1/T2, whole T3, D1–D3 or promotion qualification.

Issue Or Task

Maintainer-requested next cohesive stage of the TypeScript/shared-authority RFCs. No additional provider, capability, enablement, lifecycle transition or write authority is introduced.

Validation

• Tested revision: 4ffaa63fc1e92d4fe047161bc5bc7c74dd84aba5; rebased on fe18fd386073b973ddcd5b23fffa6c66a2a1124e.
• Run state: finished
• Input classes: synthetic, public_fixture, authorized_private_read_only

Check kind	Result	Public-safe evidence / limitation
static	passed	TypeScript typecheck, focused Ruff and diff checks.
regression_parity	passed	Five public graph counterexamples failed before the fix and passed afterward; horizon's opaque-route counterexample also covered.
integration	passed	45 Python status/CLI/output-budget tests; all 1,241 TS tests passed with concurrency 4, zero skips.
real_backend	passed	Full shared conformance includes an isolated real PostgreSQL 16.15 server. No active Goal promotion or writes.
real_entrypoint	passed	Production status reader and real CLI; legacy/File/SQLite, including missing canonical display, preserve provider revision and display contents.
regression_parity	passed	Authorized read-only snapshot: 468 active and 4,456 archived rows; 80 sampled graph-generation replays plus production-reader replay in disposable legacy/File/SQLite runtimes. Samples may resolve to the same eligible root; this is not a claim of 80 distinct roots or 80 independent backend reads. Private source, scripts and output excluded.
integration	passed	Existing graph, status collection and attention smokes; 16 of 17 final canary checks passed.
regression_parity	failed	The remaining canary is an unchanged main baseline issue: hot-path dashboard payload is 18,930 / 18,500 characters on both clean base fe18fd386 and this head. No budget raised; resolve this gate before merge.

Initial unrestricted-parallel TS run had one NoKV helper-open timeout (2 seconds), not a topology assertion failure. The reduced-concurrency rerun passed all 1,225 tests before rebase, and the final rebased run passed all 1,241 tests. No timeout was increased or ignored in product code.

Coverage limits: the graph still consumes the existing potentially incomplete status source. Its completeness is scoped to the documented bounded expansion policy, not the entire Goal. Existing run-history audit heuristics, gate/claim presentation and legacy status normalization are outside this Todo-topology slice. No live model calls or frontend build: current frontend sources do not consume this projection, and no UI, setting or packaged asset changed. The real status/review-packet contract smoke covers the shipped consumer.

Type / Area / Direction

• Bug fix plus behavior-disclosed refactoring, documentation and regression tests.
• Control plane: work-item read models; target base main.
• Architecture direction: TypeScript migration T3 / shared-authority consumer alignment.

Shared-authority RFC fixture impact

• Reuse loopx_coordination_production_scale_fixture_v0 without reducing its mixed Todo/claim/Monitor/User-gate envelope; add a focused mixed-lineage/condition overlay and no-authority-mutation assertion.
• Additional synthetic dimensions: 4,096 unrelated rows, 512-deep ancestry, cycles, diamond saturation, missing targets, parallel relation kinds and malformed requests.
• Provider arms: legacy/File/SQLite real readback plus shared provider conformance including PostgreSQL. This is not a legacy/file/PostgreSQL promotion rehearsal: no provider routing, cutover or Markdown compatibility-projection writer changed.

Boundary / Review

• Public-safe code, fixtures and aggregate evidence only; no private snapshots, logs, local paths or credentials.
• DCO-signed commits. Local time-gate bypass is authorized for this branch only; no merge requested.
• Existing enum/schema names retained, with additive completeness fields and explicit semantic corrections. A graph edge is diagnostic, never an execution grant.
• Related refactor applied at the existing work_items owner, not a new generic framework. New code volume is primarily typed contracts and regression coverage; no claim of full legacy-writer retirement.

[huangruiteng]

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

Reviewed exact head: 4ffaa63fc1e92d4fe047161bc5bc7c74dd84aba5；对照基线：fe18fd386073b973ddcd5b23fffa6c66a2a1124e。完整评审结论：APPROVE，没有发现新的阻塞问题。本轮没有执行合并。

动机

问题不是“Python 代码应该统一搬到 TypeScript”，而是同一份 Todo 关系被 inventory、horizon 和图分别解释，已经出现可观察的不一致：successor 谱系被画成完成依赖，unblocks 方向反了，Monitor generation 等待没有呈现。操作者据图判断下一步时会得到错误上下文，后续新增关系也容易只修一处。最强的反对方案是仅修 Python 三个分支，避免增加一次跨运行时调用；但这保留了重复的关系知识。PR 在现有 work_items 边界抽出关系目录，再为图保留单独的有界读取视角，范围与实际问题匹配，不需要另建通用图平台。

改动思路

真实调用链是 status --include-task-graph → attention queue → loopx.status.build_task_graph_projection → Python 来源/脱敏适配 → 已注册的 work_item.task_graph.topology → 图节点和证据展示。TS 消费的是已经提供的 status 快照，不自行读取 provider，也不拥有 claim、lease、resume readiness 或生命周期写入权限。inventory/horizon 复用共享关系目录，但 horizon 的连通距离与图的有向前驱展开仍是不同读取语义，不能为了复用而强行合并。新增 completeness 是快照与展开策略的派生信息，没有要求用户同步维护另一份图状态。

正向例子是 root 延续已完成 parent，同时等待 Monitor generation：输出同时出现 continues 和指向 Monitor 的 depends_on，后者说明 generation 等待而不是“完成 Monitor”。负向例子是引用对象缺失、source 被裁剪或节点额度用尽：不创建虚构节点、不补写来源，而是报告对应完整度；节点额度用尽也不应丢掉已展示节点之间的另一条菱形边。

具体改动

全量 diff 为 15 个文件，629 行增加、254 行删除：生产代码 303/245，测试与 smoke 252/8，文档 74/1。没有生成资源或 UI 修改。

关键代码讲解

• planning_relations.ts::candidateRelations / todoRef：抽出既有 relation/enforcement 目录和去重逻辑。条件解析复用 normalizeTodoResumeWhen，不再把 route:todo_x、capacity 或任意未知后缀当成 Todo 关系；inventory/horizon 的调用点已一并改到共享所有者。
• task_graph.ts::graphEdge：区分 lineage 与 condition，明确 successor/superseded/unblocks 的方向，并为 Monitor 等待提供准确的 generation 说明；没有把 edge 变成执行许可。
• task_graph.ts::projectTaskGraphTopology：严格解码请求、拒绝重复 ID 和非法 limit，按稳定顺序做有界 BFS。开放的前驱是展示边界，已完成前驱继续展开；missing、omitted、emitted 分开记录。达到节点上限后仍扫描已接纳顶点的边，保留平行语义和菱形汇合。
• task_graph.py::_task_graph_build_predecessor_chain：删除 Python 前驱索引、条件拆分和遍历知识，保留 public-safe 节点、完成证据和 handoff 展示。传给 TS 的是 ID/关系/done 事实，不是原始 note 或 evidence。运行时 handler 注册使新模块确实被生产入口使用，而不只是测试中的新帮助函数。

图协议和四份中英文 RFC 更新明确披露上述行为修正、完整度的有限范围，以及未完成全部 T3/D1–D3、未授权 promotion；既有 smoke 的 successor 断言也从错误的 depends_on 改为 continues，没有把默认行为变化藏在“纯搬代码”里。

对主干的风险

重点核验了现有测试可能漏掉的入口问题：普通 status 不会自动执行图分支，所以仅运行普通 status 成功不足以证明新拓扑有效。本轮在同一份不可变合成 registry/state 上，分别用基线和 head 执行真实 CLI 的开图/关图路径，并比较完整关图 JSON（只归一化 generated_at）。关图观测哈希均为 6194d8e20bae6ff717a084793726a2f2a6c4d0771f6333b3c8ef450ba62e9cee；开图的独立“谱系 + Monitor generation”断言在基线失败、在 head 通过。两侧命令退出均为 0，来源文件无写入。另经公共 status 图 API 对照了 unblocks、缺失目标、平行关系、未知条件和普通完成条件。

独立运行结果：10 项 Python 拓扑/真实 reader 测试、18 项 TS graph/horizon/inventory 测试通过；其中覆盖真实 legacy/File/SQLite 读取，以及 canonical display 缺失时不修复写回。图 fixture smoke、TypeScript typecheck、变更 Python Ruff 和 diff check 均通过。cli-output-budget-regression-smoke.py 在本轮干净基线与 head 均通过；作者正文中之前的预算失败没有复现，不能据此宣称其历史根因已修复，建议保留原失败条件用于差异排查，而不是直接抬高预算。远端本轮检查也已成功或预期跳过。

未访问或复跑作者的私有快照；未独立复跑其 PostgreSQL conformance 声明。本 PR 改的是 supplied-snapshot 之后的纯拓扑解释，不改存储实现、provider 路由或 promotion；本轮实际验证的是受影响的 managed TS backend 与公开合成 reader 路径，不把这些证据包装成存储迁移资格。

我的整体评价

这次提取有真实消费者，也确实删除了重复解释知识。关系标签、方向、Monitor 条件与节点上限的修正已被独立基线反例验证，不是只看绿色 CI 或作者的“修好了”说明。默认关闭的图不会因 handler 存在而自动激活；horizon 的 opaque-route 修正则是另外明确披露的全局读取修正，不误称为图开关隔离。

未来简化检查的结论是：共享 catalogue 是合适的小型重构，Python 来源与脱敏展示仍有独立职责，不应继续为追求净删行数而搬迁无关模块。残余风险是图来源仍可能不完整，topology_complete 只证明所述有限展开，不能推导整个 Goal 完整、任务已经接受或可以执行。当前证据支持批准这批范围明确的改动；合并仍需当时的 exact-head readiness 检查和独立授权。

English verdict: APPROVE at 4ffaa63fc1e92d4fe047161bc5bc7c74dd84aba5. The shared typed relation owner replaces duplicated Python topology knowledge and validates disclosed lineage, unblocks and Monitor corrections without adding authority. Independent real CLI base/head probes preserve graph-off output and make the historical lineage/Monitor oracle fail before and pass after; source state remains unchanged. Ten Python and eighteen TypeScript tests, graph smoke, typecheck, Ruff, diff check, and budget smoke on both revisions passed. Private replay and PostgreSQL conformance were not independently repeated; no merge was performed.