From 6fdc734ffe02a9d87eb725f15ed5fe40487c22e2 Mon Sep 17 00:00:00 2001 From: DJC1412 <108855841+DJC1412@users.noreply.github.com> Date: Sat, 19 Sep 2026 16:58:09 +0800 Subject: [PATCH] docs(rfc): give shared-goal-authority records a ledger directory check_rfc_ledger_entries accepted only the literal heading "Appendix A: Execution ledger", so an RFC already using Appendix A for other evidence could not adopt per-file entries without renumbering its appendices across both language files -- a mechanical diff that itself forces rework on the branches the convention exists to spare. The heading is now matched for any appendix letter, and the READMEs stop hardcoding how many RFCs carry one. shared-goal-authority-state-provider-v0 records each delivery as a dated subsection at the end of one large file, which is why #3820, #4061 and #4672 all collided there per #4677. New records move to ledger/shared-goal-authority-state-provider-v0/ as dated files with Chinese mirrors; existing dated subsections stay as append-only history. Refs #4677 Signed-off-by: DJC1412 <108855841+DJC1412@users.noreply.github.com> --- docs/architecture/rfcs/ledger/README.md | 6 ++- docs/architecture/rfcs/ledger/README.zh-CN.md | 3 +- ...red-goal-authority-entries-get-a-ledger.md | 38 +++++++++++++++++++ ...al-authority-entries-get-a-ledger.zh-CN.md | 28 ++++++++++++++ ...shared-goal-authority-state-provider-v0.md | 18 +++++++++ ...-goal-authority-state-provider-v0.zh-CN.md | 13 +++++++ examples/docs-governance-smoke.py | 16 +++++--- 7 files changed, 114 insertions(+), 8 deletions(-) create mode 100644 docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.md create mode 100644 docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md diff --git a/docs/architecture/rfcs/ledger/README.md b/docs/architecture/rfcs/ledger/README.md index 48ba494f19..d111c614b6 100644 --- a/docs/architecture/rfcs/ledger/README.md +++ b/docs/architecture/rfcs/ledger/README.md @@ -18,8 +18,10 @@ same day touch two different files and merge cleanly with no resolution at all. ## Convention - `/YYYY-MM-DD-slug.md` — one directory per RFC, named exactly like - the RFC file it belongs to. Six RFCs carry an execution-ledger appendix, so - an entry has to say which one it extends. + the RFC file it belongs to. Several RFCs carry an execution-ledger appendix, + so an entry has to say which one it extends. The appendix inside the RFC is + titled `Appendix : Execution ledger` and takes whichever letter the + RFC has free. - The name carries the date the work was measured, not the merge date. - Each entry carries a Chinese mirror at `/YYYY-MM-DD-slug.zh-CN.md`, the same rule the RFCs themselves follow. diff --git a/docs/architecture/rfcs/ledger/README.zh-CN.md b/docs/architecture/rfcs/ledger/README.zh-CN.md index 0f6f33243b..b1f1f1f0a3 100644 --- a/docs/architecture/rfcs/ledger/README.zh-CN.md +++ b/docs/architecture/rfcs/ledger/README.zh-CN.md @@ -16,7 +16,8 @@ ## 约定 - `/YYYY-MM-DD-slug.md` —— 每份 RFC 一个目录，目录名与其所属 RFC - 文件名完全一致。有六份 RFC 带执行账本附录，所以条目必须写明它补的是哪一份。 + 文件名完全一致。多份 RFC 带执行账本附录，所以条目必须写明它补的是哪一份。 + RFC 内那一节的标题是 `附录 <字母>：执行账本`，用该 RFC 还没占用的字母。 - 文件名中的日期是**测量**当天，不是合并当天。 - 每条配一份中文镜像 `/YYYY-MM-DD-slug.zh-CN.md`，与 RFC 自身同一规则。 - 每个 RFC 的目录就是该 RFC 的索引。跨 RFC 不设枚举，因为索引行正是本目录要消除的那种 diff --git a/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.md b/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.md new file mode 100644 index 0000000000..ae4205e630 --- /dev/null +++ b/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.md @@ -0,0 +1,38 @@ +# Shared-goal-authority delivery records get a ledger directory + +Non-normative for the shared Goal authority model: it adds no runtime invariant. +It relaxes one condition the ledger check imposed — a ledger directory had to +name an RFC whose *Appendix A* is the execution ledger — and points this RFC's +future delivery records at files. + +- **The cost was measured by the maintainer, not by this entry.** #4677 surveyed + every open PR against `origin/main = d8e7af141` on 2026-09-17 and found 19 of + 34 heads `mergeStateStatus=DIRTY`, three of them (`#3820`, `#4061`, `#4672`) + colliding on this one file. This entry re-measures no head: GitHub computes + mergeability lazily, so a same-day recount is not available without forcing a + computation per PR. +- **Why records collide in this file.** Delivery records for this RFC are dated + subsections inside Appendix C — `Provider-first terminal lifecycle checkpoint + (2026-09-07)`, `Cross-RFC semantic and presentation conformance checkpoint + (2026-09-12)`, `Next delivery and parallel provider work`. They sit at the end + of a 3,125-line English file and a 2,474-line Chinese one, so two branches + recording a delivery insert at the same position by construction. +- **The convention already existed and could not be adopted here.** + `check_rfc_ledger_entries` in `examples/docs-governance-smoke.py` required a + ledger directory's RFC to contain the literal heading + `Appendix A: Execution ledger`. This RFC's Appendix A is + `What This Evidence Proves`, so per-file entries would have meant renumbering + Appendices A-C across both language files — a large mechanical diff that + itself forces rework on the branches the change exists to help. The check now + accepts `Appendix : Execution ledger` in the English document, and this RFC's + Appendix D is the pointer. +- **Existing records stay put**, for the reason the semantic-vocabulary round + recorded on 2026-09-18: they are append-only history nobody edits, so they + were never the thing a later branch conflicts with — the shared insertion + point ahead of them is. +- **What this does not do.** It resolves no conflict that already exists; each + affected branch still rebases once. It does not make a ledger entry + reviewable evidence — entries remain non-normative records of what a change + measured and what it did not establish. And it adds no navigation entry: the + hosted-docs check requires a file for every nav entry, not a nav entry for + every file. diff --git a/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md b/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md new file mode 100644 index 0000000000..516e204cbf --- /dev/null +++ b/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md @@ -0,0 +1,28 @@ +# shared-goal-authority 的交付记录有了自己的账本目录 + +对共享 Goal authority 模型是非规范性的：它不新增任何 runtime 不变量。它放宽了账本 +检查附加的一个条件——账本目录原本必须指向一份"附录 A 就是执行账本"的 RFC——并把本 RFC +后续的交付记录指向这里的文件。 + +- **这笔成本是 maintainer 量出来的，不是本条目量的。** #4677 在 2026-09-17 以 + `origin/main = d8e7af141` 为基线普查了全部 open PR：34 个 head 里 19 个 + `mergeStateStatus=DIRTY`，其中三个（`#3820`、`#4061`、`#4672`）撞在同一份文件上。 + 本条目不重新度量任何 head：GitHub 是惰性计算可合并性的，不在每个 PR 上强制触发一次 + 计算，就得不到当天的复核数字。 +- **记录为什么在这份文件里相撞。** 本 RFC 的交付记录是附录 C 内部的带日期小节—— + `Provider-first terminal lifecycle checkpoint (2026-09-07)`、 + `Cross-RFC semantic and presentation conformance checkpoint (2026-09-12)`、 + `Next delivery and parallel provider work`。它们位于一份 3,125 行英文文件与一份 + 2,474 行中文文件的末尾，于是两个记录交付的分支按构造就会插在同一位置。 +- **约定早就有，但这份 RFC 用不上。** `examples/docs-governance-smoke.py` 里的 + `check_rfc_ledger_entries` 要求账本目录所指向的 RFC 含字面标题 + `Appendix A: Execution ledger`。而本 RFC 的附录 A 是 `What This Evidence Proves`， + 因此要改成一条一个文件，就得把附录 A–C 在两份语言文件里一起重新编号——那是一次很大的 + 机械 diff，本身就会逼这个改动本想帮的那些在途分支重做一遍。现在检查在英文文档里接受 + `Appendix <字母>: Execution ledger`，本 RFC 的附录 D 就是那个指针。 +- **已有记录原样保留**，理由与 2026-09-18 语义词表那一轮记录的一样：它们是没人再编辑的 + 只追加历史，所以从来不是后来分支相撞的对象——撞的是它们前面那个共享插入点。 +- **这次没有做的事。** 它不解决任何已经存在的冲突，受影响的分支仍各自 rebase 一次； + 它不会让账本条目变成可评审证据——条目仍然是"某次改动测到了什么、没有确立什么"的 + 非规范性记录；它也不新增托管文档导航项——那边的检查要求每个导航项都有对应文件， + 而不是每个文件都要有导航项。 diff --git a/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md b/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md index a9725b7b22..840ca41f4f 100644 --- a/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md +++ b/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md @@ -3125,3 +3125,21 @@ soak, release, merge and live promotion retain their respective authorization. | C. Canonical transaction capture | Qualify the implementation merged in #3870 | Transaction-bound outbox capture targets the one `coordination.runtime_shadow` lineage and retains complete versioned Todo/lease records. Finish sustained mixed-writer parity, explicit-clear/omission coverage, and event-only Todo recovery evidence. | Can run in parallel with P, but both C and the selected provider profile must finish before parity or promotion integration. | | I. Binding and qualification integration | After C and the selected profile's qualification | Bind one exact provider lineage, field manifest, source revision, digest, and cursor; qualify explicit v0 import, ordering/archival/consumer parity, and recovery/capacity without consulting legacy state for missing fields. | Long-goal local integration requires L and does not wait for P. PostgreSQL joins only when its own P holds pass. | | F. Promotion and cleanup | After I and explicit maintainer approval | Complete provider-first CLI routing, the lock-owning promotion orchestrator, compatibility projection outbox, post-promotion fenced export/rollback, then delete duplicate reference aggregates and flip the reviewed stage/hold declarations. | Each profile must pass C, I, and its own provider qualification; long-goal local promotion additionally requires L, and PostgreSQL requires P. | + +## Appendix D: Execution ledger + +Delivery records for this RFC are files under +[`ledger/shared-goal-authority-state-provider-v0/`](ledger/shared-goal-authority-state-provider-v0/), +one dated entry per change, named and paired per +[the ledger convention](ledger/README.md). An entry states what the change +measured, what it changed, and what it did not establish. + +New records go there instead of into the dated sections of Appendix C. Those +sections stay as they are: append-only history that nobody edits, and rewriting +them into files would produce a large mechanical diff that forces rework on the +open branches it is meant to help, while fixing nothing. The reason is measured, +not assumed — see +[`2026-09-19-shared-goal-authority-entries-get-a-ledger.md`](ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.md). + +`examples/docs-governance-smoke.py` checks the entry naming, the Chinese mirror +beside each entry, and that this appendix exists for the directory it names. diff --git a/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md b/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md index e1164ae2d7..30fe774ee4 100644 --- a/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md +++ b/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md @@ -2478,3 +2478,16 @@ adapter，也不依赖 PostgreSQL service 部署。 | C. Canonical transaction capture | 资格化 #3870 已合入实现 | transaction-bound outbox 已指向唯一 `coordination.runtime_shadow` lineage，并保留完整带版本的 Todo/lease record；继续完成 sustained mixed-writer parity、explicit-clear/omission 与 event-only Todo recovery 证据。 | 可与 P 并行；但 C 与选定 provider profile 都完成后，才能进入 parity 或 promotion 集成。 | | I. Binding 与资格集成 | C 与选定 profile 的资格化完成后 | 绑定一个精确 provider lineage、field manifest、source revision、digest 与 cursor；资格化显式 v0 import、排序/归档/consumer parity 与 recovery/capacity；缺字段时不得查询 legacy state 补齐。 | 长程本地集成需要 L，不等待 P；PostgreSQL 仅在自己的 P hold 全通过后汇合。 | | F. Promotion 与清理 | I 完成且 maintainer 显式批准后 | 完成 provider-first CLI routing、持锁 promotion orchestrator、兼容投影 outbox、晋升后 fenced export/rollback；随后删除重复 reference aggregate，并翻转经评审的 stage/hold 声明。 | 每个 profile 必须通过 C、I 与自身 provider 资格化；长程本地晋升还需 L，PostgreSQL 还需 P。 | + +## 附录 D：执行账本 + +本 RFC 的交付记录是 [`ledger/shared-goal-authority-state-provider-v0/`](ledger/shared-goal-authority-state-provider-v0/) 下的文件， +一次改动一条带日期的条目，命名与镜像配对遵循 +[账本约定](ledger/README.zh-CN.md)。一条条目写清这次改动测到了什么、改了什么、以及没有确立什么。 + +新记录写在这里，而不再写进附录 C 的那些带日期小节。附录 C 里已有的内容原样保留：它们是没人再编辑的只追加历史， +把它们改写成文件只会产生一次很大的机械 diff，逼那些在途分支重做一遍合并——而这正是本改动想帮的对象，且什么都没能修好。 +理由是量出来的，不是猜的，见 +[`2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md`](ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md)。 + +`examples/docs-governance-smoke.py` 校验条目的命名、每条旁边的中文镜像，以及账本目录所指向的这份附录确实存在。 diff --git a/examples/docs-governance-smoke.py b/examples/docs-governance-smoke.py index 557e960c57..3402e469d4 100644 --- a/examples/docs-governance-smoke.py +++ b/examples/docs-governance-smoke.py @@ -203,6 +203,10 @@ def check_rfc_language_mirrors() -> None: LEDGER_ENTRY_NAME = re.compile(r"^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$") +# The appendix that points at the ledger directory is whichever one an RFC has +# free: an RFC whose Appendix A carries other content adopts a later letter +# rather than renumbering history and forcing every open branch to re-resolve it. +LEDGER_APPENDIX_HEADING = re.compile(r"^## Appendix [A-Z]: Execution ledger", re.MULTILINE) def check_rfc_ledger_entries() -> None: @@ -219,19 +223,21 @@ def check_rfc_ledger_entries() -> None: return assert (ledger / "README.md").exists(), "ledger README missing" assert (ledger / "README.zh-CN.md").exists(), "ledger README missing its Chinese mirror" - # Six RFCs carry an execution-ledger appendix, so entries are shared and + # Several RFCs carry an execution-ledger appendix, so entries are shared and # must say which one they belong to. The RFC slug is a directory, and the # directory has to name a real RFC: an entry cannot claim an RFC that does # not exist, and the per-RFC listing stays the index. scopes = sorted(path for path in ledger.iterdir() if path.is_dir()) assert scopes, "ledger has no per-RFC directories" for scope in scopes: - appendix_a = DOCS / "architecture" / "rfcs" / f"{scope.name}.md" - assert appendix_a.is_file(), ( + rfc_document = DOCS / "architecture" / "rfcs" / f"{scope.name}.md" + assert rfc_document.is_file(), ( f"ledger directory {scope.name}/ does not name an RFC: " - f"{appendix_a.relative_to(DOCS.parent)} does not exist" + f"{rfc_document.relative_to(DOCS.parent)} does not exist" ) - assert "Appendix A: Execution ledger" in appendix_a.read_text(encoding="utf-8"), ( + assert LEDGER_APPENDIX_HEADING.search( + rfc_document.read_text(encoding="utf-8") + ), ( f"{scope.name} has a ledger directory but no execution-ledger appendix" ) for entry in sorted(scope.glob("*.md")):