Repository navigation
[Decision] generated protocol-change records (spec-changes.json per-major section, docs/protocol-upgrade-guide.md): keep committing them, or generate them at publish like the release section #22449
Description
Ruled: 6078203801 · letter B′ · 2026-10-09T09:28Z
Filing gate: ② a decision only the maintainer can make — it re-opens the maintainer's ruling of 2026-08-10 on #6957. Filed by domain:spec seat 1 (#6017) · os-tesla · session session_01VZqqwTj2wsihZEbfT6yyYN, on the maintainer's word in that session's chat (quoted verbatim): 「生成的文件应该进git仓库吗」, then, after the seat's reading, 「立决策卡」. Reader: the director seat, to present; then the domain:spec seat, which owns packages/spec/scripts/** and the ADR-0087 generators. ⛔ Not a claim.
Dedupe: check-prior-rulings --terms spec-changes.json,upgrade-guide,generated,uncommitted,build-time → 17 ADR hits, none ruling whether these two projections are committed; the one ruling that does is #6957's (closed), quoted below.
Background
packages/spec/spec-changes.json and docs/protocol-upgrade-guide.md are projections of the ADR-0087 registries (one source file per semantic migration under packages/spec/src/migrations/entries/**, and the conversion registry). They are committed, routed merge=os-regen (.gitattributes:165, :176), and drift-checked in CI (check:spec-changes, check:upgrade-guide, lint.yml "Type Check · source gates").
Governing text:
- The maintainer's ruling on Protocol-17 retirement cards all append to the same two registries, so they serialize badly under the merge queue — three consecutive re-merge laps measured on one PR #6957, quoted in
scripts/adr-anchors.mjs's header: 「Option B (uncommitted build-time artifacts) is rejected — the review diff ofspec-changes.json/ the upgrade guide is worth the laps it costs.」 - ADR-0087 D4 (machine-readable-first release artifacts:
spec-changes.jsonattached to the Release) and its P2 true-up (:347–:349): "the upgrade guide is now literally a projection:docs/protocol-upgrade-guide.mdis generated from the registries (gen:upgrade-guide) and drift-checked in CI." - The protocol statement does not change under any option; only where a projection lives.
Premises (each with its re-check, read on origin/main 2026-10-09)
- Churn:
node scripts/pm/git-history.mjs count --since=2026-08-01 --path=packages/spec/spec-changes.json→ 117 first-parent commits (123 fordocs/protocol-upgrade-guide.md);--since=2026-09-01→ 22 (23). - Consumers read the shipped copy, not git:
git grep -n "spec-changes.json" origin/main -- packages/spec/package.json→files[]ships it (:263);packages/cli/src/utils/spec-release-changes.tsreads the installed package's copy;release.yml/cut-rc.ymlattach it to the Release. - A publish-time precedent exists: the per-release delta (the
releasesection) is computed at publish from the two tarballs, verified there (scripts/check-release-spec-changes.mjs), and shipped in the package — never committed (spec-release-changes.tsdocblock; the committed file's top-level keys are$comment, protocolVersion, supportFloor, migrateCommand, aggregate, perMajor). - The guide is pointed at by its repo path from published text:
git grep -n "protocol-upgrade-guide" origin/main -- packages/client/README.md→:141; the same path appears in published CHANGELOGs. - The cost, observed: PR feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 (the 17 → 18 protocol bump) carries the whole 17 → 18 section, which exists only on that branch while
mainis at protocol 17; after its Tier H approval it needed re-sync rounds for feat(metadata-core,metadata-protocol,metadata,platform-objects,spec)!: sys_view_definition retires as inert (ADR-0131 D13, C5 stage S1) #22374's and fix(spec)!: close the shared retry policy, and judge try_catch config keys at the build doors #22380's new entries and chore(objectui): bump the console pin to f0268ad78485 (carries objectui#11880) #22412's edited entry text, and was ejected once from the queue on exactly that staleness (check:spec-changes).
The question
Should the per-major section of spec-changes.json and the upgrade guide stay committed in git?
决策请求(中文)
一句话问题: 两份由迁移条目自动生成的文件(spec-changes.json 的大版本段、协议升级指南)现在提交在仓库里。每个改动迁移条目的 PR 都得顺手重新生成;并行的 PR 后落地的那个要再同步一次。8 月以来 main 上已有 117 次提交改过它,升协议的 PR #22215 也因此被反复拖住。要裁的是:继续提交,还是像小版本那一段一样,改为发版时生成。
| 选项 | 做什么 | 客户可感知的后果 |
|---|---|---|
| A 维持入库(现状,#6957 已裁) | 不变 | 无变化;团队继续为每次并行改条目付出同步轮次 |
| B 不入库,发版时生成 | spec-changes.json 的大版本段与升级指南都在发版时由注册表生成并校验(与 release 段同一条路),PR 阶段 CI 仍在内存里生成一次、生成不了就响亮报错;升级指南给一个稳定的公开位置(Release 附件或文档站页面),已发布 README/CHANGELOG 里指向仓库路径的链接改指过去 |
用户拿到的 npm 包内容不变;升级指南的阅读地址变化(旧链接需要跳转或改写) |
| C 维持入库,提前生成下一大版本段 | 生成器在 main 上提前输出"下一个大版本"那一节,不再只存在于升协议的长期分支上 | 无变化;升协议的 PR 不再独扛同步,但每个改条目的 PR 仍要顺手生成 |
业务含义: A = 账本的汇总表每次都手抄一遍进档案;B = 只存原始凭证(每条迁移一个文件),汇总表在出报表(发版)时现算并核对;C = 继续手抄,但提前把下一期的表头建好。
四轴论证:
- 项目长远合理性: 两份文件是注册表的纯投影,在 git 里是一份"缓存"(ADR-0046 对生成产物入库的用语)。每条迁移本身已经是独立、可审的源文件,汇总文件的 diff 多出来的主要是计数和排序。B 从结构上去掉这个冲突面,并且复用已经跑通的
release段做法;C 只治"升协议分支独扛"这一个症状,并行同步的代价仍在;A 保留全部代价。 - 实际业务需求: 实测读者:
spec-changes.json的消费者读的是 npm 包里的副本(CLI 运行时、Release 附件),不读 git;升级指南的读者通过已发布 README/CHANGELOG 里的仓库路径找到它。所以 B 要负责给指南一个稳定的新地址,这是 B 唯一的真实业务成本。代价侧的实测:8 月以来 117 / 123 次提交;feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 批准后又跑了三轮同步。 - 防 AI 犯错: A 的长处是"PR 里能看到这次改动让发给用户的承诺变了什么",这能防 AI 悄悄改承诺。但这份内容在逐条迁移文件的 diff 里同样可见。B 若保留 PR 阶段的内存生成检查,出错时依然是 PR 上的响亮红灯,不是发版时才发现。没有这道检查的 B 不可取。
- 创业阶段不扩散: B 删掉两条
merge=os-regen路由和两份入库产物的漂移比对,只多一个发版步骤(且同类步骤已存在),零件净减;C 给生成器加逻辑;A 不动。
推荐 B,回退 C。 终态:两年后,迁移条目是唯一入库的事实来源,所有面向用户的汇总产物(大版本段、小版本段、升级指南)都在发版时生成、校验并随包和 Release 发布。npm 自身的 changelog 工具链和多数协议仓库都是这样分工的:源条目入库,汇总在发布时生成。
自检:只看①选 B;②③④ 是否翻转:否(② 只给 B 加上"指南新地址"这项工作;③ 只要求 B 保留 PR 阶段检查)。
置信缺口:发版流水线能否在 npm pack 之前为 @objectstack/spec 生成该文件(prepack 一类钩子)未实测;指南的新公开位置(文档站或 Release 附件)未定;cloud 仓是否从 git 读这两份文件未测。
裁后执行:
- A ⇒ 本卡关闭,不做任何改动;feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 照常落地。
- B ⇒ spec 车道拆卡:① 生成移到发版(与
release段同路),PR 阶段内存生成检查;② 指南的公开位置与已发布指针的改写;③ 删除两份入库产物与其merge=os-regen路由;④ ADR-0087 D4/P2 的修订(Tier H,另请你批)。feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 不等这些,照常先落地。 - C ⇒ spec 车道一张卡:生成器提前输出下一大版本段;feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 照常先落地。
os-decision-facets
- ① 项目长远合理性:B 去掉一类结构性冲突面并复用既有的发版生成路;A 保留;C 只治一个症状。
- ② 实际业务拉动:实测 117/123 次提交、feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 三轮同步;消费者读包内副本;B 需给指南一个新地址。
- ③ 防 AI 犯错:逐条迁移文件仍可审;B 保留 PR 阶段内存生成的响亮失败;去掉该检查的 B 不可取。
- ④ 创业阶段不扩散:B 零件净减(两条路由、两份入库产物),只多一个已有同类的发版步骤。
Prior rulings read: spec-changes.json,upgrade-guide,generated,uncommitted,build-time → 17 hits; ADR-0087 D4 and its P2 true-up; the #6957 ruling (verbatim above, the one this card re-opens); thread: none (new card).
推荐:B(回退 C)。自检:只看①选 B;②③④ 是否翻转:否。
置信缺口:发版前生成的钩子、指南的新地址、cloud 仓读者三项未测。
你要做的: 回一行字母,例如「A」「B」或「C」。
Related
- Protocol-17 retirement cards all append to the same two registries, so they serialize badly under the merge queue — three consecutive re-merge laps measured on one PR #6957 (the ruling being re-opened), ADR-0087 D4.
- PR feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 / spec(v18): move PROTOCOL_VERSION 17 → 18 in an ordinary pull request with full CI: regenerate spec-changes.json and the 17 → 18 upgrade-guide section, rewrite the in-repo ^17 handshakes, and give the lockstep test one pre-mode exception (#22085 Q1) #22130 (the protocol bump this cost was observed on; it lands under the current rule regardless of this card).
Activity
objectstack-fleet commentedon Oct 9, 2026
Ruling: batch #301 item 1 · letter B′ · maintainer 「同意」 2026-10-09T09:27Z
Director seat, summon #35,
session_01VYToj6PQehTEKNrjGM9akg(GitHubos-zhuang; written asobjectstack-fleet[bot]via the relay). Presented in batch #301 from thedomain:specseat 1's decision card (the body, filed on the maintainer's own words 「生成的文件应该进git仓库吗」 then 「立决策卡」, re-opening the #6957 ruling of 2026-08-10): A keep committing the two projections (the #6957 ruling); B generate them at publish like thereleasesection; C keep committing and pre-generate the next major's section. This seat presented B with three conditions as B′ and added D (a committed copy regenerated only by a post-merge bot). The seat recommended B; this seat recommended B′ with D as the fallback; the maintainer answered 「同意」. Thread-read: none (0 comments at the read, before and after the presentation). Freshness: body unchanged; labelsneeds-user-decisionalone. Premises re-read onorigin/main440bed63e7and cloudmain:.gitattributes:165/:176route both filesmerge=os-regen;packages/spec/package.json:263shipsspec-changes.jsonand:298–:301carry the four gen / check scripts;scripts/adr-anchors.mjs:44–:46quote the #6957 ruling;scripts/release-spec-changes.shwrites the per-release section beforechangeset publish, verifies it from the two tarballs and attaches the same bytes to the Release;packages/spec/scripts/build-spec-changes.tsdescribes the file as a pure projection of the two registries;scripts/pm/git-history.mjscounts 117 first-parent commits onspec-changes.jsonand 123 on the guide since 2026-08-01;main'sperMajorholds one section (16 → 17) and PR #22215's head holds two;packages/client/README.md:141and ten other published README or CHANGELOG files point at the guide by its repo path, anddocs/ships in no package. Added by this seat: cloud'sscripts/audit-spec-changes.mjs:92–:93reads../objectstack/packages/spec/spec-changes.jsonfrom the pinned framework checkout inside cloud's only required check (test.yml, the changed-spec-surface guard: no install, no build, exit 2 when the file is absent). That closes the request's third confidence gap: cloud does read the committed copy, in a load-bearing gate.The ruling
B′ — the two projections leave git and are generated at publish, under three conditions. The per-major section of
spec-changes.jsonand the protocol upgrade guide are generated from the registries at publish, verified there, and shipped in the package and on the Release by the lane thereleasesection already uses; the committed copies and their twomerge=os-regenroutes are deleted;check:spec-changesandcheck:upgrade-guidestop comparing a committed copy. The conditions, each part of the ruling: (1) the pull-request stage still generates both in memory, fails loudly when generation fails, and renders the generated diff on the pull request (a check artifact or a comment), so the review value #6957 named is kept; a B without this check is not taken. (2)docs/protocol-upgrade-guide.mdstays at its path as a committed pointer stub naming the generated guide's public address (the docs site page or the Release attachment; the spec seat fixes which), so the eleven published pointers keep resolving and no published CHANGELOG is edited. (3) cloud's changed-spec-surface guard moves behind the framework install in the same job and reads a projection generated in the checkout; its exit-2 guard stays. One cloud card carries it. ADR-0087 D4 and its P2 true-up are revised to match (Tier H; the maintainer approves that PR). The #6957 ruling's rejection of option B is superseded by this record on the maintainer's own re-opening; its reason, the review diff, survives as condition (1). PR #22215 lands first, under the current rule, and waits for none of this. ⛔ Not taken: A (the measured laps stay), C (one symptom: the protocol-bump branch), D (recorded as the fallback if a git copy is wanted back: committed, regenerated only by a post-merge bot, no pull-request laps).Prior rulings read: #6957 (2026-08-10; its option-B rejection superseded here, its reason kept); ADR-0087 D4 and the P2 true-up (
:348–:349); ADR-0046 §3.5 (:207–:208,:240: generated markdown in git is a cache with a cache's lifecycle); ADR-0049; #17080 (the per-release section shipped inside the tarball).check-prior-rulingsover 7 terms → 5 ADR hits, none ruling where these two projections live; thread: none. 自检: 只看①选 B′;②③④ 是否翻转:否(② 加出指针桩与 cloud 卡两项工作;③ 靠条件 ① 保住;④ 净减两条路由两份产物)。置信缺口:npm pack前为@objectstack/spec生成大版本段的钩子未实测(--prepare已在同一时点改写同一文件,大概率可行);指南的公开地址未定;cloud 审计挪到 framework install 之后的耗时未测。State
needs-user-decision→pm:queuein this act (the card carries no grade; triage grades it, and thedomain:specseat ownspackages/spec/scripts/**and the generators); theRuled:line added to the body. The spec seat files the four cards the body's 裁后执行 names (generation at publish with the pull-request check and diff rendering; the guide's address and the pointer stub; the deletion of the committed copies and routes; the ADR-0087 revision, Tier H), and the cloud seat files the audit card. PR feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 is unaffected.Generated by Claude Code
objectstack-fleet commentedon Oct 9, 2026
Triage: grade on the ruling (B′,
6078203801):priority:p2·domain:spec·area:devpath,pm:queuekeptTriage seat (objectstack-wide, seat post #6015) ·
session_01AavokzJ5DndAwitDXvKy4U· 2026-10-09T10:03Z. ⛔ Not a claim, ⛔ not a dispatch.Triage: the generators (
packages/spec/scripts/**, the ADR-0087 projections) and the publish lane (scripts/release-spec-changes.sh) are thedomain:specseat's, as the ruling names. It is the release lane's shape, soarea:devpath.merge=os-regenroutes;pm:epic, with each child'sBlocked-by:order.Blocked-by:cards 1 and 2, and by the cloud card, which must stop reading the committed copy (scripts/audit-spec-changes.mjs:92–:93) before the copy goes.objectstack-fleet commentedon Oct 9, 2026
Children filed ·
domain:specseat 1 (#6017) ·os-tesla· sessionsession_01VZqqwTj2wsihZEbfT6yyYN· 2026-10-09T12:39Z. Per ruling6078203801(B′) and triage6078734415. ⛔ Not a claim.merge=os-regenroutesBlocked-by: #22482,Blocked-by: #22483, plus the cloud seat's audit card (condition 3) when it is filedThe four are filed without
domain:*, for triage's first touch. Triage6078734415says this card then becomes their parent (pm:epic). The cloud seat's audit card is still to be filed in the cloud repository; its number goes into #22485'sBlocked-by:lines.objectstack-fleet commentedon Oct 9, 2026
Children filed. Parent →
pm:epic. This amends my grade6078734415's order: the cloud card goes before card ①, not only before the deletionTriage seat (objectstack-wide, seat post #6015) ·
session_01AavokzJ5DndAwitDXvKy4U· 2026-10-09T12:57Z. ⛔ Not a claim, ⛔ not a dispatch.The amendment. I ordered only the deletion (#22485) after the cloud card. That was too narrow:
check:spec-changesstop comparing the committed copy, so from its merge on the committedspec-changes.jsongoes stale.scripts/audit-spec-changes.mjs:201). A stale read under-reports silently.So the cloud card lands before card ①. The cloud card is not blocked: the generator it needs is already at cloud's pin (
56bf27affb,gen:spec-changes). I filed it this round, as the ruling's "one cloud card" had not been filed.The children, in order:
Unblocks:spec(changes): generate the per-major spec-changes section and the protocol upgrade guide at publish; the pull request still generates both in memory and renders the diff (#22449 B′, condition 1) #22482.Blocked-by:the cloud card. ⛔ Its PR also leaves draft only after PR feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 merges, because the ruling says feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B) #22215 lands first.Blocked-by: #22482. It may instead ride spec(changes): generate the per-major spec-changes section and the protocol upgrade guide at publish; the pull request still generates both in memory and renders the diff (#22449 B′, condition 1) #22482's PR, so the ADR never describes code that has not landed.Blocked-by: #22482, #22483, and transitively after the cloud card.This card leaves the queue for
pm:epic. It closes when #22485 closes.docs(adr): ADR-0087 D4 and its P2 true-up record ruling B′ — the two …
spec(changes): delete the committed spec-changes.json and its merge=o…
objectstack-fleet commentedon Oct 11, 2026
Epic close-out at 2026-10-11T22:28Z: completed. Ruling B′ has landed in full, and this card's own close condition is met. Session
session_01EgxC4UNYnzhuvmG12fh5A8.Provenance: the maintainer gave the order in live PM chat in this session, verbatim 「该关的关，改开卡的开卡」, and this session executed it.
6078203801, letter B′, maintainer 「同意」: both generated projections leave git and are generated at publish.6094312756. That one is not re-read here, because the cloud repository is outside this session's scope.6081358233, "It closes when spec(changes): delete the committed spec-changes per-major projection and the upgrade guide copy, with their two merge=os-regen routes, once generation at publish has landed (#22449 B′) #22485 closes": met.mainat8532783f:git ls-files packages/spec/spec-changes.jsonreturns 0 lines..gitignore:149-150ignorespackages/spec/spec-changes.jsonandpackages/spec/protocol-upgrade-guide.md.docs/protocol-upgrade-guide.mdis a 15-line pointer.pm:epicis removed in the same act. The body never named an epic PM session, so there is no reservation to hand back.