docs(semantics): reconcile RFC milestones with shipped contracts - #4777
Conversation
Signed-off-by: song <22676124+songoow@users.noreply.github.com>
songoow
left a comment
There was a problem hiding this comment.
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机
exact head 95dad68e45195e831dce07da51041ceb315f7302 修复双语语义 RFC 的事实时态:M0.5 scope checks、M1/Q6 和 M2 Turn generation 已交付,却仍被描述为未来工作。PR 以 bfbb5ac60 为实现读回基线,保留 Draft 状态、历史测量和未完成的 M3/M4、F6 与兼容迁移。
改动思路
直接修订现有双语 RFC,没有创建竞争路线图。源码事实、规范性交付义务和未决批准分开表达;inventory/consumer report 明确是 advisory,drift smoke 才是阻断检查。
具体改动
- 准确记录
check_scope_declarations的四个 bounded-context owner。 - 补齐
generate_semantic_bindings.py --check与generate_turn_contract.py --check的真实入口和消费者。 - Q3/Q6 与 M1 描述与 EffectiveAction owner、根部 decision/frontier union、nested frontier action 和 journal observation 对齐。
- Section 11 明确六个旧字段、F6、#4747 baseline 和交叠风险仍未闭合;历史 SHA 未重写。
正向路径是 owner/registry 修改后生成检查和 drift smoke 保证一致;负向路径是 owner 漂移或生成物过期时非零退出。报告存在、PR 状态或代码已落地都不会自动把 Draft 升为批准。
对主干的风险
运行时风险低,主要风险是规范写错时态或把 advisory 写成机器义务。源码读回、两个 generator、45 个 focused tests、docs governance、inventory/report 入口、diff 和最终 CI 均通过;中英文含义一致。分支落后于 main,任何 head 更新需重新核验,尤其与 #4789 修改同一规范表的集成。
我的整体评价
APPROVE。 PR 完整完成 PR-03 的事实校正,没有偷渡运行时行为、批准状态或第二权威。
English verdict: APPROVE — exact head 95dad68 matches shipped generators and Q3/Q6/M2 behavior, preserves Draft and historical boundaries, and passes focused validation and final CI.
huangruiteng
left a comment
There was a problem hiding this comment.
动机
这次改动解决的是 RFC 与已交付实现之间的事实错位,而不是借文档改动批准新的规范。旧文本仍把 M0.5、M1 与 M2 的若干核心机制写成未来工作;实际在 bfbb5ac60 上,作用域声明、EffectiveAction/frontier 所有权以及 Turn 契约生成与消费路径已经存在。继续保留旧时态会让后续贡献者重复规划已经落地的工作,也容易把历史测量、当前实现和未完成的 F6/M3/M4 混为一谈。
我对照了讨论 #4738 中 PR-03 的边界:本 PR 只做双语事实校正,保留 Draft、历史 SHA、剩余未决问题和独立的后续规范修订,不把“代码已经存在”偷换成“里程碑治理条件已经全部满足”。在这个边界上,目标已完整达成。
改动思路
改动继续以现有两份 RFC 镜像为唯一文档 owner,没有新增第二份状态表:
- 用 delivery maturity 和 Section 11 的
bfbb5ac60readback 明确“已实现”与“已批准/已闭环”是不同维度; - 把 M0.5 scope、M1 action owner、M2 Turn generator 的现实所有权写回 Sections 1、5、11、12;
- 给出可直接运行的 generator/inventory 命令,同时明确 inventory report 只是 advisory,不能证明 producer 或 persistence;
- 显式保留六个 legacy 字段仍在写入、F6 未证明、M3/M4 未完成等负面边界。
最强的反对理由是:这个 head 基于较早的 main,而 #4747 已修改同一 RFC、#4764 也改变相关 quota 行为,因此旧基线上的“事实正确”可能在合并后变成“当前主线语义过时”。我没有只看 GitHub 的 MERGEABLE,而是把最新 origin/main 与本 exact head 生成了 detached 合成树,并在合成树上重跑 generator、semantic drift、docs governance 与 public-boundary 检查;合并后的 F1/F2 producer domain 也正确吸收了 #4747 的 settlement_binding_kind witness,未把它扩大成 F6 或全部 cross-runtime proof。
具体改动
关键内容讲解
- 成熟度与文档地图: 两种语言都把 M0/M0.5、M1、M2 的已实现部分与 M3/M4 的未完成部分分开;Section 12 也从“全部未决”修正为“已实现选择与剩余决策”,但不推断批准。
- 作用域事实:
SOURCE_SURFACES的四个 bounded context 已由scope_declarations枚举,check_scope_declarations核对真实 owner;文本同时保留“原始 fork inventory 仍可见、改名不能证明修复”的约束。 - 生成边界: M1 的 TS action/frontier binding 仍从代码 owner 派生;M2 的 Turn vocabulary、route projection 与 ordered controller rules 从专用 Turn contract 生成。注册表负责核对这些 authority,而不取代它们。
- 交付与验证入口: 新增四条只读命令,区分 blocking drift smoke 与 advisory inventory report;
transaction.py、settlement.ts、loop_controller.py的实际消费路径已读回。 - 未完成边界: 文本没有把 Draft 改成 Accepted,没有改写历史测量 SHA,没有声称六个 legacy 字段已退休,也没有把一个 producer witness 夸大成 persistence compatibility proof。
exact base-to-head 只有两份 RFC,+111/-50;中英文语义对应,没有 runtime、schema、generated artifact 或 test fixture 改动。
对主干的风险
主要风险是“时态正确但治理语义被抬高”。我重点验证了三个反例:
- generator freshness 通过并不等于 prose 仍适配最新
main:因此额外验证了最新主线合成树; - M2 代码存在不等于 Q7、F6、M3/M4 已关闭:文本保留 entry/exit obligations、Draft 状态与明确的 remaining gaps;
- inventory report 成功不等于 producer/persistence proof:新增命令后的说明明确将其标为 advisory。
本地证据:
generate_semantic_bindings.py --check:通过;generate_turn_contract.py --check:通过;- 两个 semantic inventory report:通过;
- 聚焦 semantic/Turn 测试:首次因 checkout 缺少锁定的 Node 依赖出现 16 个环境失败;按文档执行
npm ci --ignore-scripts后原样重跑,304 passed in 61.75s; semantic-vocabulary-drift-smoke.py --report、docs-governance-smoke.py、check-public-boundary-smoke.py:exact head 与最新主线 detached 合成树均通过;git diff --check与三方合成树:通过。
按本次 capability 契约,远端 CI 不作为审阅证据来源,因此未轮询或等待 CI。剩余风险是 RFC 仍为 Draft,Q7、F6、M3/M4 以及其他 cross-runtime producer coverage 仍需后续独立证据;本 PR 已如实保留这些边界。
我的整体评价
批准 exact head 95dad68e45195e831dce07da51041ceb315f7302。这是一个边界清楚、可回滚的双语事实校正:它修复“实现已交付但 RFC 仍写成未来”的误导,同时没有把事实 readback 变成规范批准或扩大证据权威。未来向前看的小步重构不适用——继续拆出另一份状态文档反而会制造重复 authority;下一次实现状态变化应直接同步这两个现有 mirror。
English verdict: APPROVE - exact head 95dad68e45195e831dce07da51041ceb315f7302 accurately reconciles the bilingual RFC with the implemented M0/M0.5, M1 and M2 boundaries, preserves Draft/unproved/retirement limits, and passes exact-head plus latest-main synthetic-integration validation.
The bilingual semantic-convergence RFC still describes shipped scope checks and M2 Turn generation as future work, and its M1 milestone asks for a slot split even though Section 12 already records the root decision/frontier union. Those contradictions can send follow-up work back to completed migrations.
Implements the factual-correction portion of discussion #4738 PR-03. Both language versions now distinguish the M0 historical baseline from implementation readback at
bfbb5ac60, align M1/Q6 and M2 descriptions with active callers, and document the two generation checks plus advisory inventory/consumer report entrypoints. Original measurement SHAs, Draft status, question anchors and approval requirements are preserved.The checkpoint names the remaining work: six legacy fields still written; release/consumer/historical-signature decisions for PR-05; #4747 as an unmerged pilot; F6 unproved; and PR-07/08 parity reconciliation with the overlapping same-Turn selection changes in #4764. This is not the separate normative-revision portion of PR-03 and does not implement PR-07/08.
Validation: both generators pass
--check; the inventory/consumer report command ran successfully; docs-governance smoke passes; semantic binding and Turn contract generation tests 45 passed; diff and added-line public-boundary checks pass. No runtime or frontend surface changes. The related cleanup replaces stale descriptions in place rather than adding a competing roadmap. Maintainer review requested; no self-merge.