docs(rfc): propose the Stage 2C promotion design and record its owner decisions

[wchwawa]

Summary

• Add questions 8 to 14 to RFC section 12 ("What the Owner Still Needs to Decide"), each with a proposed answer: the promoted head schema and the closed coordination field set the aggregate owns; hard_lease-only promotion in v0; prose persistence through a projection outbox; the registry declaration of a promoted goal and who may write it; the file-profile retention, fast-path, and capacity rules that gate the first real promotion; the fate of the Python reference executor, and which of the two shadow lineages now on main (the feat(authority): add local post-commit observation capture #3818 observation capture and the runtime shadow) is Stage 2C's lineage and what closes their sampling and loss windows.
• Add Appendix C, the Stage 2C promotion design those questions decide. It starts from what main already ships (the runtime shadow, coordination-shadow inspect|qualify|read-candidate|bootstrap|rollback, the cutover kernel, the fence integration) and names only what is still missing before promotion: provider-first CLI routing and the lock-owning orchestrator, a transaction-bound capture, prose persistence after the read flip, the declaration record, retention and capacity, the reference executor's removal, and post-promotion rollback; plus growth as a prerequisite and the PR sequence.
• English and zh-CN in step. Documentation only; nothing in Appendix C is implemented.

@huangruiteng This is the design half of Stage 2C, split out per the agreed scope. Revised after your runtime shadow, cutover kernel, and fence integration merged: the proposal now builds on them rather than beside them, and question 14 asks the one thing those merges left open, which of the two shadow lineages is Stage 2C's and whether the parity half's transaction-bound outbox becomes its durable capture. The promotion half only proposes here and waits for your answers to questions 8 to 14 before any code. Questions 6 and 7 (#3833) stay as recorded.

Issue Or Task

• RFC section 11, Stage 2C: "a separately reviewed promotion" needs its decisions and design written down before the parity half completes.
• Contributor task ID: stage-2c-promotion-design-decisions

Validation

• python examples/docs-governance-smoke.py: ok
• python examples/docs-asset-integrity-smoke.py: ok
• git diff --check: clean; no code, test, or configuration files changed

Type of Change

• Documentation update

LoopX Area

• Public docs or presentation surface (README, protocols, dashboard)

Technical Direction

• Shared Goal Authority and cross-host coordination

• Target base branch: main

• Direction tracker or promotion unit: Stage 2C promotion design (decision record)

Boundary Checklist

• I did not commit .loopx/, .codex/goals/, live ACTIVE_GOAL_STATE.md, credentials, private benchmark traces, verifier output, raw agent sessions, internal document links, or local machine paths.
• I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
• I kept the change scoped to the linked issue/task.
• Every commit includes a DCO Signed-off-by trailer (git commit -s).

[wchwawa]

@huangruiteng Revised on the current head after your runtime shadow, cutover kernel, and fence integration merged: questions 8 to 13 and Appendix C now start from those shipped pieces instead of proposing parallel ones (the runtime-shadow projection as the promoted head with three amendments, the durable fence as the local authority of the cutover, the reference executor's removal tied to routing the kernel's mutation path from the CLI), and question 14 asks the one thing those merges left open: which of the two shadow lineages on main is Stage 2C's, and whether the parity half's transaction-bound outbox (#3870) becomes its durable capture. Documentation only; both language versions are in step.

[huangruiteng]

评审结论：REQUEST_CHANGES。评审 exact head：cc56a0ae155e728f32a2863878e8eae449996b47。

动机

这个 PR 为 Shared Goal Authority RFC 的 Stage 2C promotion 补齐尚未由 owner 决定的设计问题，并把方案更新到 main 已合并的 runtime shadow、cutover kernel 与 durable legacy-writer fence 之上。目标是避免 promotion 实现继续沿两套 shadow lineage 或两种本地 aggregate 形状演进，并在动代码前明确 head 字段、hard-lease 前置、projection outbox、声明记录、retention/capacity、Python reference executor 退场和 rollback 路径。这个设计切片是必要的，因为一旦 provider-first read flip 生效，遗漏的权威字段不能再从 Markdown 静默补回。

改动思路

英文和中文 RFC 都在第 12 节新增问题 8–14，并以附录 C 区分“main 已交付”“promotion 前仍缺”和后续 A–E 顺序。正向路径是：runtime shadow 先达到持续 parity，事务绑定 outbox 关闭 post-commit 采样窗口；orchestrator 持有 legacy Todo/lease 锁并 engage fence；kernel 把同一 projection 晋升到 file_v0 canonical authority；之后 CLI 的 mutation/read 只访问 provider head，Markdown/lease 文件成为投影。失败路径要求 fence 不可读、shadow revision/digest 漂移、provider 缺失等情况 fail closed，且不能回退 Markdown。

总体方向与现有实现一致，但 promoted head 的字段闭包尚未覆盖当前 LoopX 的调度与依赖语义。RFC 一方面说 provider-first 读永不回退，另一方面又把 monitor metadata 留作 Markdown-canonical prose；当前 runtime-shadow projection 恰好会丢掉这些字段。这会使“head 是完整决策权威”的目标在 continuous monitor 和等待/恢复 Todo 上不成立。

具体改动

• 英文文档新增 162 行：记录问题 8–14、已交付的 runtime shadow/qualification/read-candidate/bootstrap/rollback、promotion kernel 与 writer fence，以及仍缺的 orchestrator、transaction-bound capture、prose outbox、retention/capacity 和 post-promotion rollback。
• 中文文档新增 117 行，与英文保持相同的问题编号、目标边界、失败策略和 A–E 实施顺序；本次检查未发现两种语言在关键结论上的漂移。
• 问题 8 选择 loopx_coordination_runtime_shadow_projection_v0 作为 promoted head 的基础，移除 updated_at 比较，并拟补 required_capabilities、decision scopes、completion/evidence、archived 与 todo_revision。
• 问题 14 明确选择 runtime-shadow lineage，并要求 transaction-bound outbox 取代 #3818 的 post-commit observation capture。

关键内容讲解

1. 问题 8 的权威字段闭包决定 provider-first read 能否替代 Markdown。当前 _TODO_PROJECTION_FIELDS 只有 19 个字段；提案列出的增量仍没有 target_key、cadence、next_due_at、expires_at、watch_only、resume_when、resume_monitor_generation、unblocks_todo_id 等会改变选择、到期、等待和恢复行为的字段。
2. 问题 10 的 no-fallback 边界要求 read flip 后不从 Markdown 补决策事实。这与“monitor metadata stays Markdown-canonical”直接冲突：要么 provider read 丢调度语义，要么 CLI 必须重新读取 Markdown，形成第二权威。
3. 问题 11 与 Appendix C 的 fencing/orchestration正确继承了已合并实现：Todo 和 task-lease writer 都在各自锁内检查 TypeScript-owned durable fence；promotion kernel 绑定 exact shadow revision/digest，provider 缺失不回退。
4. 问题 14 的 lineage 收敛是合理修正：runtime shadow 已拥有 parity、bootstrap、quarantine rollback、read candidate 和 promotion kernel，复用 transaction-bound entry schema 能避免保留第二套 observation record format。

对主干的风险

阻塞问题：promoted head 的拟议字段集不足以重建当前 Todo 的可执行性与调度状态。 触发场景不需要边缘输入：任意 continuous_monitor 都依赖 next_due_at/expires_at/watch_only，能力门还依赖 required_capabilities，等待链依赖 resume_when/unblocks_todo_id。build_todo_runtime_shadow_projection() 当前会把这些字段中的大部分全部删除，而 readLocalCoordinationTodo() 只返回 provider head 内的 compact Todo，明确 legacy_fallback_used=false。

我用一个已到期的 watch-only monitor 做了 counterexample：legacy Todo 上 todo_item_is_due_monitor=True、todo_item_is_watch_only_monitor=True；经 RFC 选定的 runtime-shadow projection 后，两者都变为 False，丢失字段包括 cadence、next_due_at、expires_at、target_key、watch_only、required_capabilities。结果是 promotion 后同一 Todo 可以从“应立即运行且保持 watch lane”变成“无调度、非 watch”，或者实现被迫回读 Markdown，违反 no-fallback/单一权威原则。

最小修复是二选一并写入问题 8 与附录 C：

1. 把所有影响 Todo 路由、gate/dependency、resume、monitor due/expiry、capability admission 和 continuation 的规范化字段纳入 canonical projection，并增加 promotion 前后选择结果等价测试；或
2. 在 v0 promotion precondition 中显式拒绝包含这些字段/任务类的 goal，并定义后续 schema 扩展与无 Markdown fallback 的迁移路径。

另有一个非阻塞精度问题：3 个活跃 Todo、每 300 秒续约应约为 864 次 transition/天、25,920 次/月；附录写的约 300/天、9,000/月和 140 MB 对应约一个 Todo，低估了三 Todo 场景约 3 倍。结论“需要 retention/capacity”不变，但建议修正算例。

验证：两项 docs smoke 均通过；相关 Python runtime-shadow/fence/E2E 测试 45/45；TypeScript runtime-shadow/local-authority tests 28/28；control-plane typecheck、git diff --check、两文件 public-boundary scan 均通过；远端 DCO、dependency-review、Pages build、SonarCloud 成功。已通读两份完整 diff（+279/-0）并核对关键实现路径。未验证真实 promotion，因为该 PR 明确只写设计、没有接线实现。

我的整体评价

这份 RFC 对已交付能力的盘点、双 shadow lineage 收敛、transaction-bound capture 和 fail-closed promotion 边界都很扎实，中英文也保持同步；问题不是文档形式，而是目标 head 仍少了会直接改变执行结果的权威字段。Stage 2C 一旦批准就会约束后续实现，若此处把 monitor/dependency metadata 误归为 prose，后续只能丢语义或重新引入 split authority。请先闭合字段集或收紧 v0 promotion 适用范围，再复核批准。

English verdict: REQUEST_CHANGES on exact head cc56a0ae155e728f32a2863878e8eae449996b47 — the proposed promoted head omits monitor and resume/dependency fields that drive runnable selection, so a provider-first no-fallback read changes Todo semantics; 45 Python tests, 28 TypeScript tests, both docs smokes, typecheck, diff check, and the public-boundary scan pass.

[huangruiteng]

No remaining findings on exact head d817a4e33563318ee1340528c5867fbc0598a38c.

The previous blocker is resolved: Stage 2C no longer promotes the old 19-field runtime-shadow subset. The RFC now adopts the versioned complete canonical Todo/lease record as the provider readback contract, keeps updated_at and all legally stored routing, capability, decision, dependency, resume, monitor, completion, note/evidence, and archival state, rejects omission as deletion, and fails qualification closed when a new field has not entered the manifest. Any later reduction—even for a stored field with no known consumer—requires a named field inventory, producer/reader/writer and compatibility research, migration/rollback and semantic-equivalence evidence, plus explicit maintainer approval.

Architecture judgment: the promotion state machine is now provider-neutral. File, NoKV, and PostgreSQL share the authority binding, complete head, CAS/transaction preconditions, receipt, cursor, manifest, readback, and fail-closed semantics; only physical retention differs by profile. This keeps the initial file promotion useful without making file paths, segments, or size constants part of the cross-provider protocol. The retention example is corrected to 864 transitions/day and 25,920/30-day month for three 300-second renewals, with cumulative rewrite volume distinguished from final document size.

The RFC is also easier to maintain: stable specification, normative delivery plan, dated execution ledger, remaining promotion plan, and detailed Stage 2C contract are explicitly separated. docs/architecture/rfcs/TEMPLATE.md generalizes that structure with independent RFC/delivery maturity, decision and evidence logs, migration/rollback, and a rule for splitting oversized execution ledgers without losing history.

Validation:

• change-quality receipt cqr_b731b32b4cb7a56efe97: valid, no blockers or risks;
• premerge: 17/17 selected checks passed, public boundary clean, zero manual holds, self_merge_allowed=true;
• docs governance and asset-integrity smokes passed;
• TypeScript control-plane typecheck passed;
• coordination projection tests passed 10/10, including rejection of replacements that drop stored fields;
• git diff --check passed.

Merge decision: approved for self-merge after required remote checks pass. The change remains documentation-only and does not itself promote an authority provider or alter runtime behavior.

[huangruiteng]

No remaining findings on exact head 1e3b9edbd5c4ebb50786238b5188dab002583fe6.

The previous blocker is resolved: Stage 2C no longer promotes the old 19-field runtime-shadow subset. The RFC now adopts the versioned complete canonical Todo/lease record as the provider readback contract, keeps updated_at and all legally stored routing, capability, decision, dependency, resume, monitor, completion, note/evidence, and archival state, rejects omission as deletion, and fails qualification closed when a new field has not entered the manifest. Any later reduction—even for a stored field with no known consumer—requires a named field inventory, producer/reader/writer and compatibility research, migration/rollback and semantic-equivalence evidence, plus explicit maintainer approval.

Architecture judgment: the promotion state machine is now provider-neutral. File, NoKV, and PostgreSQL share the authority binding, complete head, CAS/transaction preconditions, receipt, cursor, manifest, readback, and fail-closed semantics; only physical retention differs by profile. This keeps the initial file promotion useful without making file paths, segments, or size constants part of the cross-provider protocol. The retention example is corrected to 864 transitions/day and 25,920/30-day month for three 300-second renewals, with cumulative rewrite volume distinguished from final document size.

The RFC is also easier to maintain: stable specification, normative delivery plan, dated execution ledger, remaining promotion plan, and detailed Stage 2C contract are explicitly separated. docs/architecture/rfcs/TEMPLATE.md generalizes that structure with independent RFC/delivery maturity, decision and evidence logs, migration/rollback, and a rule for splitting oversized execution ledgers without losing history.

Validation:

• change-quality receipt cqr_94c32b9fd089ae450276: valid, no blockers or risks;
• premerge: 17/17 selected checks passed, public boundary clean, zero manual holds, self_merge_allowed=true;
• docs governance and asset-integrity smokes passed;
• TypeScript control-plane typecheck passed;
• coordination projection tests passed 10/10, including rejection of replacements that drop stored fields;
• git diff --check passed.

Merge decision: approved for self-merge after required remote checks pass. The change remains documentation-only and does not itself promote an authority provider or alter runtime behavior.

DCO follow-up: the branch was replayed linearly onto current main so all three PR commits carry valid sign-off trailers; the public file diff is unchanged from the reviewed revision.