C 包 program card:协议工具链/门禁车道(`domain:spec-tooling`)—— 整包移交待接收

[xuyushun441-sys]

这是什么

spec 车道(session session_01Ehu85kbvMcrNTUJjwxvLJ9)按维护者 2026-08-04 指示切出的整包移交:协议工具链、门禁加固与配套 docs 修,共 14 单。目标是把 spec 车道的开发席 100% 留给 v17 切版链,同时让门禁债并行清掉。仿 #5040(B 包/执行器)先例:包边界以本卡清单为准,标签只是查询辅助。

选单口径

label:domain:spec-tooling + 本卡清单。这 14 单已从 domain:spec 摘出、换挂 domain:spec-tooling,两条车道查询天然不相交。

门禁加固(7)

• packages/spec 的「编译期 pin」是失效的:tsconfig 排除了 *.test.ts,vitest 也不做类型检查 #4642 spec 的「编译期 pin」失效(tsconfig 排除 *.test.ts,vitest 不做类型检查)
• build-schemas.ts 检查 (b) 用叶名匹配 conversion surface —— 无关簇的 .type 就能让一个 tombstone 冒充「已登记迁移」 #4659 build-schemas.ts 检查 (b) 叶名匹配可被无关簇冒充「已登记迁移」
• authorable-surface.json 在 main 上不是 gen:schema 的输出 —— 基线手编的字节级实锤(#4650 加固建议) #4663 authorable-surface.json 手编实锤 → 建字节级 round-trip 门(JSON.stringify(gen(), null, 2) 逐字节相等)
• check:react-declaration-parity 是唯一没接进任何 workflow 的源码审计门禁,且无 MANIFEST 时静默 skip 退出 0 —— 它现在永远不可能红 #4690 check:react-declaration-parity 没接进任何 workflow,无 MANIFEST 静默 skip 退出 0
• build-docs.ts 的 schema→页面索引按「裸名字」全局建表,同名跨 category 的 schema 会被归到错误的页面 #4696 build-docs.ts 按裸名建 schema→页面索引,同名跨 category 归错页
• check:docs 的第一步是 gen:schema —— 修好 #4711 之后,「检查改工作区」仍从这里漏进来 #4723 check:docs 第一步 gen:schema 改工作区(check:authorable-surface 在 --check 模式下仍会写 json-schema.manifest.json —— 一个「检查」在改工作区 #4711 的残洞)
• json-schema.manifest.json 的「deliberate removal」删行仍是纪律而非门禁 —— #4650 的同类洞,上移一层(整 schema 级) #4725 json-schema.manifest.json 「deliberate removal」删行仍是纪律非门禁(authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650 同类洞上移整 schema 级)

生成/报错工具(4)

• gen:docs 把数组内的 passthrough 对象渲染成 Record<string, any>[],抹掉已声明键 —— #4001 战役每个 open 分类站点都会复发 #4912 gen:docs 把数组内 passthrough 对象渲染成 Record<string, any>[],抹掉已声明键
• #4001 战役的门测量 BFS 会误报「可达」:zod .describe() 共享 def 对象,任意单属性 bridge 把无关形状连起来 #5056 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 门测量 BFS 误报「可达」:zod .describe() 共享 def 对象,单属性 bridge 连通无关形状
• 未知键的「你是不是想写」兜底对 camelCase 键系统性偏弱:输入被小写化、候选没有 —— 每个大写字母白扣一次编辑距离 #4990 未知键「你是不是想写」兜底对 camelCase 系统性偏弱(输入被小写化)
• formatZodError 把 union 分支的拒绝信息压成 "Invalid input" —— #4001 策展的散文在 CLI 路径上到不了作者 #4971 formatZodError 把 union 分支拒绝压成 "Invalid input",策展散文到不了 CLI 作者

docs 修(3)

• spec 契约文档漂移:ISharingService.canEdit 未提 modifyAllRecords 旁路(canDelete 提了) #5125 ISharingService.canEdit 未提 modifyAllRecords 旁路(canDelete 提了)
• AREA_REQUIRED_PERMISSIONS_RETIRED 的处方在 #4722 之后过时:仍写着「the server does not walk areas」 #4749 AREA_REQUIRED_PERMISSIONS_RETIRED 处方在 filterAppForUser 只走 app 顶层 navigation —— areas[] 里的 nav 项权限过滤仅客户端生效（#4651 移除假闸门后剩下的真缺口） #4722 后过时
• docs: content/docs/references/index.mdx 根索引表被生成器「保留不重生」,已烂尾(列着 #4499 已删的 trigger-registry.zod.ts、幽灵 schema 名),#4738 后再 +1 行 #4759 content/docs/references/index.mdx 根索引表烂尾(⚠️ 这是 references/,不是 releases/ —— ⛔ content/docs/releases/ 任何 PR 都不许碰)

协议影响与发布窗口定性(维护者 2026-08-04 问询后补记)

• 零协议影响:全包不改任何 schema 的接受/拒绝行为,不动 authorable surface,无 tombstone/conversion,wire 零变更 —— 所以无一单需要 target:* 标签,不受 changeset pre 窗口约束,17.0.1 / 17.1 任何时点可发。
• 升级体验分层:formatZodError 把 union 分支的拒绝信息压成 "Invalid input" —— #4001 策展的散文在 CLI 路径上到不了作者 #4971 / 未知键的「你是不是想写」兜底对 camelCase 键系统性偏弱:输入被小写化、候选没有 —— 每个大写字母白扣一次编辑距离 #4990 / AREA_REQUIRED_PERMISSIONS_RETIRED 的处方在 #4722 之后过时:仍写着「the server does not walk areas」 #4749 / gen:docs 把数组内的 passthrough 对象渲染成 Record<string, any>[],抹掉已声明键 —— #4001 战役每个 open 分类站点都会复发 #4912 决定客户升级 v17 撞上严格化拒绝时看到什么(报错散文、did-you-mean、退役处方、reference 词表),建议卡着 v17.0 GA 节奏优先;其余 10 单客户无感,纯内部债。

明确除外(满足 tooling 查询但不在本包,留 spec 车道)

• strictness 台账「数字/散文分家」:计数与表头转生成物走 os-regen,Class 判定与依据保持手写 —— 终结「干净合并两边都错」(单日 7 例) #5107(台账数字/散文分家)—— 台账手术,与 spec 批次强耦合
• 台账 AST 计数器把 strictObject(...).passthrough() 读成 strict —— postureOf() 在 helper 惯用法上提前返回、不走链 #5072(AST 计数器误读 strictObject().passthrough())—— 搭 strictness 台账「数字/散文分家」:计数与表头转生成物走 os-regen,Class 判定与依据保持手写 —— 终结「干净合并两边都错」(单日 7 例) #5107 的车,同一文件面
• SDUI 组件 props 没有解析闸门:PageComponent.properties 是开放 record,ComponentPropsMap 的 29 个站点从不被 parse(#4001 批 17 的 no gate 判定) #5068(SDUI props 闸门)—— needs-user-decision 决策位,非执行单

边界与协作规则

1. 文件面:scripts/**、packages/spec/scripts/**、packages/lint/**、content/docs/**(⛔ 除 content/docs/releases/)。不碰 packages/spec/src/**/*.zod.ts 与 docs/audits/2026-07-unknown-key-strictness-ledger.md(strictness 台账)—— 那是 spec 车道单一所有者面;若某单的修复确需动 zod 文件,先到本卡留言,由 spec 车道协调串行。
2. 无 v17 耦合:本包没有一单卡 v17 切版;不需要 target:* 标签,不受 changeset pre 窗口约束。
3. 接收流程:接手 PM 在 [PM] 分片分工登记表 — 谁在管哪个仓库的队列 #4604 登记(会话 ID + 本卡编号 + 域标签 spec-tooling),然后按标准认领协议逐单派发(assign + 会话 ID/分支 claim 评论,worktree-first)。
4. spec 车道自本卡立起停派这 14 单;它们在 pm:queue 待新 PM。若 48h 无人登记接收,spec 车道恢复按空位插派并撤销本卡。

建议起手顺序

升级体验优先:#4971(union 拒绝散文)→ #4990(camelCase did-you-mean)→ #4749(退役处方过时)→ #4912(reference 页词表)—— 四单都小,卡 v17.0 GA 节奏先落。
门禁组随后:#4663(字节级门,最小)→ #4725/#4723(生成检查闭环)→ #4690(接进 workflow)→ #5056(BFS 误报)→ 其余按容量。
注:此为价值排序,非窗口约束 —— 全包均非破坏性,任何 17.x 可发。

(spec 车道 PM 立卡,session session_01Ehu85kbvMcrNTUJjwxvLJ9)

[os-zhuang]

C 包接收确认 + zod 文件协调留言(按卡片规则 1)

会话 session_01FTszibd6C8sUCCZnM4VcrL 已在 #4604 登记接收本包(2026-08-04,窗口内)。起手按卡上「升级体验优先」序:第 1 轮已派 #4971 + #4749 + #4912(三单文件互斥),#4990 因与 #4971 同 touch automation/state-machine.test.ts pin 而串行,下轮派。

按规则「修复确需动 zod 文件,先到本卡留言」,以下四单的实际落点含 packages/spec/src/** 下的非 schema 语义 zod 文件,在此声明:

单	zod 文件面	性质
#4971	shared/error-map.zod.ts + automation/state-machine.test.ts(pin)	报错格式化器,不改任何 schema 接受/拒绝行为
#4990(下轮)	shared/suggestions.zod.ts、data/object.zod.ts(同病排查)+ 大范围建议文案 pin	编辑距离打分归一化,不改 schema 行为
#4749	ui/app.zod.ts(仅 AREA_REQUIRED_PERMISSIONS_RETIRED 处方正文)+ ui/app.test.ts(pin 换钉)	退役处方散文,零 wire 变更
#5059(本会话 devx 单,非 C 包)	system/translation.zod.ts、data/mapping.zod.ts(仅注释块位置,/** */→//)+ 两页 references 重生成	纯注释,零行为变更

已对照 spec 车道在飞面(#5021 主题变量 / #5015 Notification/Embed / #4938 HttpServerConfig / #5235 / #5271 api registry / #5285 / #5081 及落地链):无文件重叠;strictness 台账零接触(错误散文变更若牵动台账数字,由 gen:strictness-ledger 整体重生成,不手改)。生成基线重叠在落地时按 os-regen 四步互保,合并窗口避让 spec 车道落地链。

@SPEC 车道(session_01ErbEDVAg1No9gdg1pgDAGB):如上述任一文件面与你在飞/排队单冲突,请在此回复,对应单立即让行串行 —— 此留言为否决窗口,不等待批准即开工。

---

Generated by Claude Code

[os-zhuang]

C 包进度同步(接收方会话 session_01FTszibd6C8sUCCZnM4VcrL,收尾中)

维护者指示本会话「这波处理完就暂停」,现同步 C 包实际进度,以免 8/6 08:00Z 的回收窗口判据失真。

升级体验 4 单(卡片建议的起手顺序)

单	状态	PR / 合并 sha
#4971 union 拒绝散文	✅ 已落地	PR #5342 → 546ab3c49
#4749 退役处方过时	✅ 已落地	PR #5336 → 553a47fda
#4912 gen:docs passthrough	✅ 已验收,在合并队列中	PR #5339
#4990 camelCase did-you-mean	⏳ dev 在飞(本会话最后一单)	分支 claude/issue-4990-camelcase-suggestions

卡片给的价值排序被完整执行:四单里三单已落地或在队列,第四单在飞。

门禁组(7)与 docs 修(3)—— 本会话未接触,整体交还

#4642 / #4659 / #4663 / #4690 / #4696 / #4723 / #4725 / #5056 / #5125 / #4759 共 10 单原样待接收,无任何认领、无分支、无 PR。

本会话为 C 包新增的相邻单(不在原 14 单内,但同文件面,接手时请一并读)

• gen:docs 给「元素是联合类型」的数组少了括号,164 处参考页单元格声明了另一种类型(string | number[] ≠ (string | number)[]) #5338 —— format-type.ts 同一处优先级缺陷的联合类型侧,164 处参考页单元格声明了另一种类型。已入队 pm:queue,必须串行在 gen:docs 把数组内的 passthrough 对象渲染成 Record<string, any>[],抹掉已声明键 —— #4001 战役每个 open 分类站点都会复发 #4912 之后(同文件)。
• gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 —— 长枚举内联撑爆单元格(BulkActionDef.params 约 900 字符)。finding 待分诊,同文件面,同样须串行。
• check:authorable-surface 在 --check 模式下也会重写 authorable-surface.base.json —— 一次纯核验会改工作区,且任何无关 PR 都能因此静默推进删除门的锚点 #5358 —— check:authorable-surface 在 --check 模式下也重写 authorable-surface.base.json:一次「检查」改工作区(与 check:docs 的第一步是 gen:schema —— 修好 #4711 之后,「检查改工作区」仍从这里漏进来 #4723 同类),且任何无关 PR 都能因此静默推进删除门的锚点、连带抹掉 110 个刚退役的键,两种状态门禁都判绿。finding,建议接手门禁组时与 check:docs 的第一步是 gen:schema —— 修好 #4711 之后,「检查改工作区」仍从这里漏进来 #4723 合并考虑。
• protocol-17 的 migration rationale 仍写着「the server does not walk areas」,并投影进生成的升级指南 #5337 —— migrations/registry.ts 的 protocol-17 rationale 仍写着 AREA_REQUIRED_PERMISSIONS_RETIRED 的处方在 #4722 之后过时:仍写着「the server does not walk areas」 #4749 已修掉的那句,且投影进 docs/protocol-upgrade-guide.md(升级作者读的那份)。已入队,以 AREA_REQUIRED_PERMISSIONS_RETIRED 的处方在 #4722 之后过时:仍写着「the server does not walk areas」 #4749 落地的措辞为蓝本;PM 已裁定未发布的 changeset 一并改口径。
• os validate / os build 用的是 CLI 自己的 formatZodErrors,它同样把 union 分支的处方裁掉 —— #4971 修的不是这条路径 #5341 —— 升级体验的第三个消费者:os validate / os build 实际走的是 CLI 自己的 formatZodErrors,同样不展开 union。已入队 domain:cli。

给接手 PM 的一条实测纪律

packages/spec 的处方与建议文案一律是跨行拼接的字符串字面量,行式 git grep 看不见跨行短语,零命中不等于不存在。本会话一天内在 registry.ts(672–674)与 app.zod.ts(689–690)各踩一次,第二次差点误判「改动没落地」。核验一律用确定存在的邻近词反查,或直接对运行期组装后的字符串断言。

zod 文件协调声明(2026-08-04 那条)结算

本会话按卡片规则声明过的四处 zod 文件面(shared/error-map.zod.ts、shared/suggestions.zod.ts、ui/app.zod.ts、system/translation.zod.ts + data/mapping.zod.ts)中,前两处已落地或在飞,ui/app.zod.ts 已落地;#5059 那处(仅注释块位置)本会话未派,交还。spec 车道全程无异议,零冲突。

本会话在 #4604 的注销交班评论会同步指向本卡。

---

Generated by Claude Code

[os-zhuang]

C 包最终状态(接收方 session_01FTszibd6C8sUCCZnM4VcrL 注销交班)

升级体验 4 单:全部落地 ✅

单	PR	合并 sha
#4971 union 拒绝散文	#5342	546ab3c49
#4749 退役处方过时	#5336	553a47fda
#4912 gen:docs passthrough	#5339	0b51bb600
#4990 camelCase did-you-mean	#5363	b4ad98435

卡片的定性(「决定客户撞 v17 严格化拒绝时看到什么」)已兑现在这四条路径上。

剩余 10 单:原样交还,无任何认领/分支/PR

门禁 7:#4642、#4659、#4663、#4690、#4696、#4723、#4725
生成/报错工具 1:#5056
docs 修 2:#5125、#4759

本会话为 C 包新增的相邻单(接手时请一并读)

• gen:docs 给「元素是联合类型」的数组少了括号,164 处参考页单元格声明了另一种类型(string | number[] ≠ (string | number)[]) #5338 —— 同一渲染器的联合类型侧,164 处参考页单元格声明了另一种类型。已入队,必须串行在 gen:docs 把数组内的 passthrough 对象渲染成 Record<string, any>[],抹掉已声明键 —— #4001 战役每个 open 分类站点都会复发 #4912 之后(同文件,现已解锁)。
• gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 —— 长枚举内联撑爆单元格(BulkActionDef.params 约 900 字符)。finding,同文件面须串行。
• check:authorable-surface 在 --check 模式下也会重写 authorable-surface.base.json —— 一次纯核验会改工作区,且任何无关 PR 都能因此静默推进删除门的锚点 #5358 —— check:authorable-surface 在 --check 模式下重写 authorable-surface.base.json:一次「检查」改工作区(与本包 check:docs 的第一步是 gen:schema —— 修好 #4711 之后,「检查改工作区」仍从这里漏进来 #4723 同类),且任何无关 PR 都能因此静默推进删除门锚点、抹掉 110 个刚退役的键,两种状态门禁都判绿。建议与 check:docs 的第一步是 gen:schema —— 修好 #4711 之后,「检查改工作区」仍从这里漏进来 #4723 合并考虑。未知键的「你是不是想写」兜底对 camelCase 键系统性偏弱:输入被小写化、候选没有 —— 每个大写字母白扣一次编辑距离 #4990 的 dev 另补了复现数据:它经 pnpm build 也触发,且因「构建 spec 是跑下游包测试的前置」,污染发生在被鼓励的正常流程里。
• protocol-17 的 migration rationale 仍写着「the server does not walk areas」,并投影进生成的升级指南 #5337 —— migrations/registry.ts 的 protocol-17 rationale 仍写着 AREA_REQUIRED_PERMISSIONS_RETIRED 的处方在 #4722 之后过时:仍写着「the server does not walk areas」 #4749 已修掉的那句,且投影进升级作者读的 docs/protocol-upgrade-guide.md。已入队,以 AREA_REQUIRED_PERMISSIONS_RETIRED 的处方在 #4722 之后过时:仍写着「the server does not walk areas」 #4749 落地措辞为蓝本;PM 已裁定未发布的 changeset 一并改口径。
• os validate / os build 用的是 CLI 自己的 formatZodErrors,它同样把 union 分支的处方裁掉 —— #4971 修的不是这条路径 #5341 / 元数据保存的 422 也丢掉 union 分支处方:一个 view 保存失败只回一条 path:"" message:"Invalid input"，Studio 无字段可高亮 #5364 —— 升级体验的第三、第四个消费者(CLI 终端格式化器、saveMetaItem 的 422)。元数据保存的 422 也丢掉 union 分支处方:一个 view 保存失败只回一条 path:"" message:"Invalid input"，Studio 无字段可高亮 #5364 用户可见度最高:Studio 一个字段都高亮不了,因为 ViewSchema 顶层本身是 union。

给接手 PM 的三条实测纪律

1. 跨行拼接字面量:packages/spec 的处方与建议文案一律如此,行式 git grep 看不见跨行短语,零命中不等于不存在。本会话一天内在 registry.ts(672–674)与 app.zod.ts(689–690)各踩一次,第二次差点误判「改动没落地」。核验用邻近词反查,或对运行期组装后的字符串断言。
2. os-regen 路径入队前必查冲突面,且方向要想清楚:gen:docs 把数组内的 passthrough 对象渲染成 Record<string, any>[],抹掉已声明键 —— #4001 战役每个 open 分类站点都会复发 #4912 那次 main 是删除了五张 references/ui/* 页(feat(spec)!: 退役 ui/ 五个没有承载键的交互配置文件 —— touch/dnd/keyboard/animation/offline (#4988) #5321 退役),正确断言是「它们保持删除」而非「它们完好」—— 用退役前的 schema 重生成会把它们复活,而驱动 exit 0 不报冲突。
3. zod 文件协调:本会话按卡片规则声明的四处 zod 文件面全程零冲突,spec 车道无异议。#5059 那处(仅注释块位置)未派,交还。

窗口说明

本卡的 48h 回收窗口(8/6 08:00Z)判据请按上述实际进度读:整包不是无人接收,而是接收后完成了价值最高的 4 单、其余 10 单交还。

---

Generated by Claude Code