refactor(todos): unify follow-up capture with atomic canonical authority

[huangruiteng]

Goal And Delivered Outcome

Related to #4574; base: main. Complete the todo capture-followups slice of shared-authority L2 / TS T1: promoted Goals previously reached a fenced Markdown writer; legacy capture also dropped --continuation-policy and used a 500-character display summary as duplicate identity.

The command now uses one typed batch planner, an atomic canonical CAS/receipt transaction, and current-head Markdown delivery. Legacy capture adopts the same plan. Distinct long texts remain distinct and project losslessly; baseline/head regression tests and real CLI/backend runs prove the change.

Scope And Continuation

• Complete within capture scope: whole-request validation, two-item selection, unclaimed native Todo creation, no-op receipts, replay/identity mismatch, missing display and projection recovery. Python no longer owns batch selection, regex checks, cap or per-item add admission.
• Reuse native Todo create, existing provider opening/maintenance guard, source witness, command receipts and projection outbox. The companion projection fix uses source/metadata codecs instead of status summaries; it derives missing display priority/title but rejects explicit contradictions.
• Remaining work stays in shared-authority L2–L9 and TS migration: other public/effect callers, consumer closure, D1/D2/D3, rollback/cohort migration, default creation and legacy writer retirement. This is not L7 shadow-capture continuity or whole-Goal promotion.
• Rollback boundary: keep promoted Goals fenced; withhold capture until its canonical implementation is restored. Do not restore the legacy writer beneath canonical authority.

Validation

• Tested revision: 7de9b7525ba6aa863e2f6f54c671006706a5d42d. Full TS/PG suites ran on the unchanged TS sources before the final Python lossless-projection companion; affected Python consumers, real snapshot rehearsal and packages ran on final sources.
• Run state: finished.
• Input classes: synthetic, public_fixture, authorized_private_read_only.

Check kind	Result	Public-safe evidence / limitation
static	passed	TS typecheck; changed Python Ruff; configured mypy 22 files; capture adapters with silent dependency traversal; diff hygiene and public-boundary scan. Two unrelated existing registry-projection warnings.
unit	passed	uv run --extra test npm run test:control-plane: 2,074 passed, 18 environment-conditional skips; real PostgreSQL separately qualified below.
integration	passed	Capture/shadow/CLI 157 passed before projection companion; final diagnostic suite 98 passed; final capture/projection/recovery 81 and affected consumer/update suites 92 passed. Counts overlap; not a unique-test total.
real_backend	passed	PostgreSQL 16 on a task-owned disposable server: store suite 179 passed and service suite 10 passed, no skips. File/SQLite shared conformance and public CLI passed.
real_entrypoint	passed	Fresh wheel and sdist installs outside the checkout; installed product sources match final files. Legacy and File/SQLite CLI capture, long text, replay and projection passed.
regression_parity	passed	Same continuation/full-text regressions fail on pinned base 42620170d and pass on candidate; retained cap/order characterization passes both. CAS competition, malformed tail/metadata, lost acknowledgement, source changes and no-op replay use shared real-provider fixtures.
real_backend	passed	Read-only Goal snapshot rehearsal: 361 Todos, 9 leases; legacy/File/SQLite/PostgreSQL service semantics agree, existing records and live source unchanged. Private snapshot is not published; durable synthetic conformance is the public reproducer.
manual	passed	Steady batch runtime calls reduce 4 → 1; warm request p95 1.081 ms. Initial cross-directory CLI p95 regressed 6.2%; profiling identified code-file IO sensitivity. Co-located alternating 12-sample base/head run showed no regression, with substantial host noise. No CLI speedup claim or budget increase.
integration	passed	loopx canary premerge --from-git-diff: 19 selected/executed, zero failures, skips or manual holds; exact quality receipt valid.

Initial bare-npm validation selected unsupported system Python and failed; rerunning through the intended checkout environment passed. An early package probe raced the sdist installation and observed the prior package; installed-source parity was then verified and both final probes passed. Unconfigured whole-import-graph mypy exposes pre-existing repository errors; it is not claimed as passing.

Coverage and gaps: PostgreSQL capture is qualified through the existing authenticated service-owned store factory, not a new standalone PostgreSQL CLI configuration. No active Goal was promoted. Long-duration soak, whole-Goal default cutover and CI are not claimed by these local results. Goal review policy disables fetching/waiting for CI.

Quality receipt: cqr_c430a6c0b65f694e082e, verified against all 31 changed files; no blockers/warnings/advisories. One bounded simplification pass applied.

Frontend / Visual Evidence

UI impact: none. No dedicated capture-followups frontend/Lark editor exists; ordinary Todo readers and the existing projection outbox consume the unclaimed records. The affected public interaction is CLI/Python capture. No settings, first viewport or presentation chrome changed; screenshots are not applicable.

Type of Change

• Bug fix
• New feature
• Documentation update
• Test update

LoopX Area / Technical Direction

Control plane; Shared Goal Authority and cross-host coordination; TS-owned Todo decisions. See capture contract and recovery. No capability/provider is added.

Shared-authority RFC fixture impact

• Reuses productionScaleCoordinationFixture with native and legacy records and complete mixed state; adds capture to shared source/receipt conformance rather than creating another fixture family.
• Dimensions: full-text identity, active done/deferred duplicates, unchanged old Todos/leases, atomic competing batches, immutable no-op decisions, request identity, display loss/recovery and no execution claim.
• Arms: File, SQLite, NoKV; real PostgreSQL store/service; read-only legacy/File/SQLite/PostgreSQL rehearsal described above.

Boundary Checklist

• Diff and public artifacts exclude private state, credentials, raw evidence, internal links and local paths.
• No benchmark work or new jobs.
• Scoped to the existing task/RFC boundary; no new default or execution authority.
• UI impact is none.
• All four commits carry DCO sign-off.

Control-plane change: proposed for maintainer merge after exact-head review; no self-merge.

[huangruiteng]

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

评审提交：7de9b7525ba6aa863e2f6f54c671006706a5d42d，基线 42620170d7f1ef5a2a55989853d791ded5bbd21c。没有阻塞性发现。依据当前 review policy 7 完成全量 diff、既有 owner、真实调用路径与反例检查；这条评审不授予合并或 Goal promotion 权限。

动机

按 #4574、shared-authority L2 和 TS T1 判断，本 PR 是合理且完整的命令级增量。原来的 capture-followups 在 promoted Goal 仍进入已被 fence 禁止的 Markdown writer；legacy 路径还丢弃 CLI 的 continuation policy，并把 500 字符显示摘要用于重复身份。现在真实 CLI 能完成批次写入、历史回执恢复和当前 Markdown 回读。

这没有完成全量默认切换。其他 L2/L3 effect caller、L5 consumers、L6/L7 qualification、L8 迁移/回滚、L9 新 Goal 默认仍按既有 RFC 推进。没有为一个完成的子命令虚构新 Todo，也没有把测试数量当作整个计划的完成证据。

改动思路

已对照基线和最终提交中的 capture_followup_todos、native create、command receipt、source witness、provider opening 及 projection outbox。只补 CLI 参数无法让 promoted command 可用；循环调用单条 create 又无法保证整批 CAS 和 capture 特有的重复规则。因此新增的是 cohesive batch planner/transaction，底层记录准入、持久化和恢复都复用现有实现。

legacy 与 canonical 均调用同一 TS selection owner；Python 只适配调用、解析来源和渲染接受的结果。canonical 先查询原回执，再做当前来源准入，读取完整 head，计划所有新增 Todo，最后一次 CAS。capture-operation-id 是调用者不可推导的恢复意图；原回执是不可从后续状态重建的历史事实。priority/title 则可由完整 text 推导，只在投影时补齐，不能重复写入权威状态。

正向路径已经从 CLI 验证到真实 File/SQLite 和安装包：没有 Markdown 时仍能新增两条未认领任务；重试恢复旧回执，同时把后来的任务也投影出来。该命令不 acquire lease、不认领、不执行任务、不 spend quota。

具体改动

全 PR 为 31 个文件、+1062/-158：15 个产品文件，11 个测试/隔离 rehearsal 文件，5 个文档。包含 CLI 参数与诊断、两条 runtime handler、共享 metadata enum、lossless source codecs、四个新 planner/transaction/transport 模块、现有复杂 fixture 的 conformance 接入及双语 RFC checkpoint；没有生成文件或私有快照。

关键代码讲解

1. planFollowupCapture：先验证整个请求和 metadata，再按空文本、unsafe、duplicate、cap 的次序决定结果。复用 Python-compatible whitespace 与已有 work/decision metadata；full text Set 决定身份，最多接受两项，跳过项不占名额。
2. executeCoordinationFollowupCapture：active Agent 中 done/deferred 仍抑制重复；archive/User 不抑制。批次选择后使用已有 operation_lane create admission；所有 Todo 和回执一次提交。即使全部重复，也保存 no-op 回执，避免后续归档后旧请求突然获得新增含义。
3. capture_followup_todos：canonical routing 位于读取 Markdown 之前；legacy 保留原锁和 shadow capture，但删除 Python regex、cap、去重及逐条 add 决策。显式 durable operation id 在 legacy 被拒绝，不假装拥有历史恢复能力。
4. _parsed_active_records：机器投影回读改用完整 source/metadata codec，避免 status summary 截断和不相关 eligibility 求值。active/archive 长原文均可 round-trip；缺失 priority/title 可推导，显式矛盾仍触发 parity error。

对主干的风险

最强反例是“权威写入成功，但长文本 projection 一直 pending”，而普通短文本测试仍全部通过。开发中的真实 File/SQLite 验证复现了它，本 PR 已补齐投影修复；最终测试同时验证无冗余 annotations、完整长文本、原 record 不变及矛盾 metadata 拒绝。

并发竞争在真实 provider 的 validated read 与 CAS 之间发生，断言败者没有第一条残留。共享 receipt/source conformance 覆盖来源变更、提交回应丢失、回执不可读、历史 replay 和 intent mismatch。display failure 不回滚业务；旧 operation replay 渲染最新 head，不用旧回执覆盖新状态。provider outage 和损坏的 promoted fence 连 preview 都不能伪装成功或转写 legacy。

最终验证：TS typecheck；TS 全套 2,074 passed / 18 环境条件 skip；独立真实 PostgreSQL 16 store 179、service 10 passed，均无 skip；最终 Python capture/projection/recovery 81、受影响 consumers/update 92、CLI diagnostics 98 passed。完整 TS/PG 使用最终未再改变的 TS 源码；最后 Python 投影改动另有上述最终测试、安装包与快照 rehearsal。计数有重叠，不相加宣称独立测试总数。

冻结只读 Goal 快照的 361 Todos / 9 leases 在 legacy、File、SQLite、PostgreSQL service 四条路径语义一致，原记录和源文件未改。私有快照不公开，仓库复杂合成 fixture 提供可复现边界。wheel/sdist 安装后从 checkout 外执行真实 CLI；15 个变化产品文件与安装源逐字节一致。Canary 19 项全部执行通过，零失败/skip/manual hold；exact-scope quality receipt 有效。未查询/等待 CI，符合该 Goal 的 wait_for_ci=false。

最初 bare npm 选错系统 Python 的失败、安装未完成时旧 sdist 的失败以及不在配置范围内的全导入图 mypy 错误均保留并披露；最终限定环境和配置的验证通过。没有把失败改成 skip。

语义与 CI 对齐

复用已有 Todo task class、continuation policy、work requirements、create/receipt/outbox 语义。对 legacy 的 policy、full-text、whole-request validation 与 optional metadata 输出变化明确写入命令契约，不宣称 feature-off 路径与旧 bug 完全等价；既有 cap/order、普通 writer 与 bounded status 默认保持。没有新增自动加载 instruction、默认开启 provider、领域专属 obligation 或把强制规则称为 guidance。

unsafe regex 是原 public-safe capture 的有限启发式，可误判包含 credential-like 文本的正常句子，也不能识别所有敏感格式；已明确其不是 DLP/授权分类器。typed skip reason 和 Unicode 边界减少跨语言漂移，不扩张到新的安全承诺。

本 PR 没有调整预算。测得稳定批次 RPC 4→1；最初跨目录 CLI p95 +6.2%，定位到 Python 文件载入敏感性，随后同目录交错 12 次对照未见回归但噪声明显，因此不宣称端到端加速。输出预算和 maintainability canary 均通过。历史失败被保留，未通过删语义或改阈值得到绿色结果。

我的整体评价

APPROVE 此 exact head。最有价值的变化是统一了仍可达的两条路径的业务规则，并把 lossless identity、历史决定和当前展示的边界落实到真实入口。产品净增 252 行对应一个此前缺失的完整事务，而 Python capture owner 从 203 行缩到 145 行；没有另造 provider、重复 create/receipt 或未来框架。相邻未来可维护性检查已应用到 source/metadata codec 和直接 owner imports。

同一份测试在基线准确失败于 policy 丢失和长文本只接受一条，保留规则测试通过；最终 head 三项均通过。剩余限制是既有 heuristic、legacy migration window、whole-Goal/default/soak 验证，以及不在本 PR 范围的 standalone PostgreSQL CLI。它们不被此命令的成功证据消除。按照仓库 control-plane 规则，交由维护者合并。

English verdict: APPROVE - 7de9b75. No blocking finding. The complete capture command shares one TS planner, commits atomic canonical batches with immutable no-op/replay receipts, and projects lossless current state. Baseline counterfactuals, real File/SQLite CLI, isolated PostgreSQL store/service, packaged installs, read-only four-arm rehearsal and 19 risk canaries passed. Whole-Goal/default/soak qualification remains outside this slice; maintainer merge is required.

[huangruiteng]

The product decision has changed after the command-usage audit: todo capture-followups will be retired directly rather than migrated. #4723 removes the command and its dedicated compatibility surface while preserving the separate runtime shadow-capture mechanism. The atomic batch, deduplication, and replay behavior implemented here is therefore no longer a required migration path; independently valuable fixes should be reconsidered only if a retained caller needs them.