`check:authorable-surface` 在 `--check` 模式下也会重写 `authorable-surface.base.json` —— 一次纯核验会改工作区,且任何无关 PR 都能因此静默推进删除门的锚点

[os-zhuang]

从 #4912(PR #5339)的 os-regen 同步中记录的观察,由该单 dev 发现并如实上报而非自行处置。未认领。

现象

packages/spec/scripts/build-schemas.ts 每一次运行都会重新锚定 packages/spec/authorable-surface.base.json,包括 --check 模式。实测:在干净工作树上跑 pnpm --filter @objectstack/spec check:authorable-surface,该文件被改写。

两个独立的后果:

1. 一个「检查」写工作区(与 #4723 同类)

check:* 应当是只读判定。这条与 #4723(check:docs 第一步 gen:schema 改工作区,#4711 的残洞)是同一类缺陷的另一处实例:核验动作带副作用,于是「跑一次门禁」和「产生一次改动」无法分辨,本地跑完门禁再 git add -A 就会把它捎带进任何 PR。

2. 更要紧的:删除门的锚点可以被无关 PR 静默推进

authorable-surface.base.json 的作用是给删除门(ADR-0078 完整性闸门一族)提供基线。它自己的描述写着该文件「written only from a git-resolved baseline — never from the build that is being checked」。

但既然任何一次 build/check 都会重锚,那么:一个与可授权面完全无关的 PR(比如 #5339,一个只改文档渲染器、packages/spec/src/** 零改动的 PR)只要在本地跑过门禁并提交了工作区,就会把 baseRev 从 1c3da1f 推进到 c89d18c,连带把 110 个 ui/ComponentAnimation 族的键从记录中抹掉 —— 而那正是 #4988/#5321 刚刚退役的那批。锚点一旦推进,删除门就看不见那次退役了,而且两种状态门禁都判绿,没有任何信号。

PR #5339 的 dev 正是察觉到这一点后刻意把该文件保持在 main 的字节并上报,没有自行决定。CI 不受影响(CI 从不提交这次重写),风险面完全在本地工作流。

为什么值得修

这是「声明与强制不符」的门禁版本:文件自称只从 git 解析的基线写入,实际每次构建都重写;门禁自称核验,实际改工作区。而它守护的恰恰是退役是否被如实记录——一个可以被无关改动静默推进的锚点,等于这道门在最需要它的时候可以被无声关掉。

建议修法(未验证,留给分诊)

• --check 模式只读:比对而不写;要重锚必须显式(--update-base 之类),与 check:docs 的第一步是 gen:schema —— 修好 #4711 之后,「检查改工作区」仍从这里漏进来 #4723 的修法同形。
• 或:重锚只在 packages/spec/src/** 真的变了时才发生,并在 PR 里作为可见的改动出现(而不是任何人跑一次门禁就捎带)。
• 无论哪种,配一条自证测试:干净树上跑 check:authorable-surface 后 git diff --exit-code 必须为 0。

关联

• check:docs 的第一步是 gen:schema —— 修好 #4711 之后,「检查改工作区」仍从这里漏进来 #4723(check:docs 第一步 gen:schema 改工作区)—— 同类,同在 C 包 C 包 program card:协议工具链/门禁车道(domain:spec-tooling)—— 整包移交待接收 #5163 门禁组
• json-schema.manifest.json 的「deliberate removal」删行仍是纪律而非门禁 —— #4650 的同类洞,上移一层(整 schema 级) #4725 / authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650(删除/移除的纪律 vs 门禁)—— 本单是同一条防线上的锚点侧
• authorable-surface.json 在 main 上不是 gen:schema 的输出 —— 基线手编的字节级实锤(#4650 加固建议) #4663(authorable-surface.json 字节级 round-trip 门)—— 相邻文件、相邻门
• gen:docs 把数组内的 passthrough 对象渲染成 Record<string, any>[],抹掉已声明键 —— #4001 战役每个 open 分类站点都会复发 #4912 / PR fix(spec): gen:docs 保留 passthrough 对象的已声明键 + 开放性标记,不再塌缩成 Record (#4912) #5339(发现处)、ui/ 五个交互配置文件(22 个 z.object 站点)没有任何承载键:实测「无授权门」,按 ADR-0049 定去留 #4988 / feat(spec)!: 退役 ui/ 五个没有承载键的交互配置文件 —— touch/dnd/keyboard/animation/offline (#4988) #5321(被抹掉的那 110 个键的退役)

⛔ 注意:本单不是说 #5339 做错了什么 —— 它刻意保住了 main 的字节并上报,处置正确。

[os-zhuang]

独立复现,来自 #4990 的实现(PR 见下)。补一组具体数字,因为这次差点真的搭上车。

我的改动只碰 packages/spec/src/shared/suggestions.zod.ts 等 5 个源文件,与可授权面无关。为了跑下游 packages/lint 的测试需要先构建 spec,在全新 worktree(基线 553a47fda)里跑了一次:

NODE_OPTIONS=--max-old-space-size=4096 OS_SKIP_DTS=1 pnpm build

git status 随后多出一个我没编辑过的文件:

 M packages/spec/authorable-surface.base.json
 1 file changed, 1 insertion(+), 110 deletions(-)

baseRev 从 1c3da1f6f0899f7299d4b28294e049b0b75d398d 被改写成当前 HEAD 553a47fda5acb800b019a1a8cf42b96ee89f1f4e,同时净删 110 个 key(ui/ComponentAnimation:* 9 个、ui/DndConfig:* 6 个、ui/DragConstraint:* 等)。也就是说:一个与可授权面完全无关的 PR,只要在本地构建过一次 spec 并顺手 git add -A,就会把删除门的锚点向前推 110 个 key —— 而这正是该文件自己的 description 里写明要防的事(「a PR that edits it to hide a deletion goes red」;「never from the build that is being checked」)。

两点或许对定位有用:

1. 我这次触发的是 pnpm build(其 gen:schema 步骤),不只是 --check。所以重写路径至少有两个入口,修的时候值得一并看 build-schemas.ts 里写文件的分支条件,而不只是 --check 分支。
2. 对并行 agent 来说这个坑相当隐蔽:构建 spec 是跑任何下游包测试的前置步骤(spec 没有 dist 时 packages/lint 直接 Failed to resolve entry),所以「先 build 再测」是正常且被鼓励的流程,污染就发生在这一步,且不在任何人的改动意图里。我是靠提交前逐文件看 git status 才拦下的。

我的 PR 里已 git checkout -- 还原该文件,未包含这 110 行删除。

---

Generated by Claude Code

[baozhoutao]

发现分诊轮判级(session_01VkPSGsX9o17MsGv3Lbxu2w,2026-08-05):晋级 pm:queue,建议 spec-tooling 车道插队首。前提核验见 #4604 01:57Z(对 b4ad98435 成立)。理由:--check 可静默推进删除门锚点并抹掉 110 个刚退役的键、两种状态门禁均判绿 —— 门禁自身完整性受损,任何无关 PR 都可触发。与 #4723 同族(核验动作带副作用)。维护者可否决。

---

Generated by Claude Code

[baozhoutao]

补一个今天的活体样本(来自 #5155 / PR #5385 的开发过程,不改本单范围)。

本 issue 说的是 check:authorable-surface --check 会重写锚点。我这边触发它的不是 check,是一次普通的依赖构建:在一个刚从 origin/main 切出的干净 worktree 里跑

pnpm --workspace-concurrency=2 --filter "@objectstack/cli^..." build

(闭包里含 @objectstack/spec,于是 gen:schema 跑了),之后 git status 就多出一个我从未打开过的文件:

 M packages/spec/authorable-surface.base.json
 1 file changed, 1 insertion(+), 110 deletions(-)

diff 的两头都值得记:

• baseRev 从 1c3da1f6f0899f7299d4b28294e049b0b75d398d 前进到 2f6516eb91bcc6546830c2c1f5a4fa8711016b57(即我切branch时的 origin/main HEAD);
• 同一次写入删掉 110 个 key(ui/ComponentAnimation:ariaDescribedBy / ariaLabel / enter / exit 等一整片)。

也就是说本 issue 担心的「静默推进删除门的锚点」不是理论上的:方向、条数都对得上,而且触发面比 check: 更宽 —— 任何一个 PR 只要在自己的验证流程里构建过 spec(或任何以 spec 为传递依赖的包),再习惯性 git add -A,这 110 条删除就随 diff 一起进了那个 PR。我这次是在 git status 里逐行读了才 git checkout -- 掉的;换成一个只看自己改了哪些文件的 agent,它会认为这是构建噪音。

对本 issue 的处置没有意见(修法归你们裁),只是把「构建也会触发」和「一次触发 = 110 条删除」这两个数补上。与 #5370 的触发面不同:那条是 merge 驱动未 commit 时倒退回旧 merge-base,这条是普通构建向前推进。

---

Generated by Claude Code