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
Activity
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
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.- Why p2, not p1: the ruling says 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 lands first under the current rule and waits for none of this. So it is not on the v18 release path.
- The cost it removes (re-sync laps on every parallel migration-entry edit) is real.
- Each of its four children, plus cloud's, is ordinary work.
- Execution, as the ruling sets it:
- The spec seat files the four cards its 裁后执行 names:
- generation at publish, with the pull-request in-memory check and the diff rendering (condition 1);
- the guide's public address and the committed pointer stub (condition 2);
- deleting the committed copies and their two
merge=os-regenroutes; - the ADR-0087 D4 / P2 revision (Tier H).
- The cloud seat files the audit card (condition 3).
- When the four exist, this card becomes their parent:
pm:epic, with each child'sBlocked-by:order. - ⛔ Card 3 (the deletion) goes last. It is
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. - Deleting a committed projection that a load-bearing gate reads is the migration-shape case. It is ordered here, not re-asked: the maintainer ruled it.
- The spec seat files the four cards its 裁后执行 names:
- ⛔ 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 not touched by any of this.
- Why p2, not p1: the ruling says 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 lands first under the current rule and waits for none of this. So it is not on the v18 release path.
Children filed ·
domain:specseat 1 (#6017) ·os-tesla· sessionsession_01VZqqwTj2wsihZEbfT6yyYN· 2026-10-09T12:39Z. Per ruling6078203801(B′) and triage6078734415. ⛔ Not a claim.card what order ① #22482 generation at publish, plus the in-memory pull-request check and diff rendering (condition 1) first ② #22483 the guide's public address, plus the committed pointer stub (condition 2) beside ① ③ #22485 deleting the committed copies and their two merge=os-regenrouteslast: Blocked-by: #22482,Blocked-by: #22483, plus the cloud seat's audit card (condition 3) when it is filed④ #22484 the ADR-0087 D4 / P2 revision, Tier H no earlier than ① The 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.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:
- Card ① (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) makes
check:spec-changesstop comparing the committed copy, so from its merge on the committedspec-changes.jsongoes stale. - cloud's changed-spec-surface guard reads that committed copy from its pinned checkout (
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:
- objectstack-ai/cloud#2750, condition 3: filed this round, unblocked. It has
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. - 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, generation at publish plus the in-memory check and diff, condition 1:
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. - docs(spec): the protocol upgrade guide gets a public address, and docs/protocol-upgrade-guide.md stays as a committed pointer stub so the published pointers keep resolving (#22449 B′, condition 2) #22483, the guide's public address and the pointer stub, condition 2: unblocked, and may land beside 2.
- docs(adr): revise ADR-0087 D4 and its P2 true-up for B′, so the per-major projections are generated at publish rather than committed (#22449, Tier H) #22484, the ADR-0087 D4 / P2 revision (Tier H):
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. - 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, the deletion:
Blocked-by: #22482, #22483, and transitively after the cloud card.
This card leaves the queue for
pm:epic. It closes when #22485 closes.- Card ① (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) makes
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:specseat 1 (#6017) ·os-tesla· sessionsession_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 thedomain:specseat, which ownspackages/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.jsonanddocs/protocol-upgrade-guide.mdare projections of the ADR-0087 registries (one source file per semantic migration underpackages/spec/src/migrations/entries/**, and the conversion registry). They are committed, routedmerge=os-regen(.gitattributes:165,:176), and drift-checked in CI (check:spec-changes,check:upgrade-guide,lint.yml"Type Check · source gates").Governing text:
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.」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."Premises (each with its re-check, read on
origin/main2026-10-09)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).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.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).git grep -n "protocol-upgrade-guide" origin/main -- packages/client/README.md→:141; the same path appears in published CHANGELOGs.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.jsonand the upgrade guide stay committed in git?决策请求(中文)
一句话问题: 两份由迁移条目自动生成的文件(
spec-changes.json的大版本段、协议升级指南)现在提交在仓库里。每个改动迁移条目的 PR 都得顺手重新生成;并行的 PR 后落地的那个要再同步一次。8 月以来 main 上已有 117 次提交改过它,升协议的 PR #22215 也因此被反复拖住。要裁的是:继续提交,还是像小版本那一段一样,改为发版时生成。spec-changes.json的大版本段与升级指南都在发版时由注册表生成并校验(与release段同一条路),PR 阶段 CI 仍在内存里生成一次、生成不了就响亮报错;升级指南给一个稳定的公开位置(Release 附件或文档站页面),已发布 README/CHANGELOG 里指向仓库路径的链接改指过去业务含义: A = 账本的汇总表每次都手抄一遍进档案;B = 只存原始凭证(每条迁移一个文件),汇总表在出报表(发版)时现算并核对;C = 继续手抄,但提前把下一期的表头建好。
四轴论证:
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 批准后又跑了三轮同步。merge=os-regen路由和两份入库产物的漂移比对,只多一个发版步骤(且同类步骤已存在),零件净减;C 给生成器加逻辑;A 不动。推荐 B,回退 C。 终态:两年后,迁移条目是唯一入库的事实来源,所有面向用户的汇总产物(大版本段、小版本段、升级指南)都在发版时生成、校验并随包和 Release 发布。npm 自身的 changelog 工具链和多数协议仓库都是这样分工的:源条目入库,汇总在发布时生成。
自检:只看①选 B;②③④ 是否翻转:否(② 只给 B 加上"指南新地址"这项工作;③ 只要求 B 保留 PR 阶段检查)。
置信缺口:发版流水线能否在
npm pack之前为@objectstack/spec生成该文件(prepack一类钩子)未实测;指南的新公开位置(文档站或 Release 附件)未定;cloud 仓是否从 git 读这两份文件未测。裁后执行:
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 不等这些,照常先落地。os-decision-facets
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