docs: `content/docs/references/index.mdx` 根索引表被生成器「保留不重生」,已烂尾(列着 #4499 已删的 trigger-registry.zod.ts、幽灵 schema 名),#4738 后再 +1 行

[os-zhuang]

现象

content/docs/references/index.mdx 位于 AUTO-GEN 区(《Documentation Guardrails》:content/docs/references/ 永不手改,由 packages/spec/scripts/build-docs.ts 重生成),但 build-docs.ts 对根 index.mdx 的处理是保留不重写(约 :658 附近的 preserve 逻辑;分类子目录的 index.mdx 会重生成,根的这份不会)。结果:一张没有任何 owner 的协议总表 —— 手改被守则禁止,生成器又不管 —— 只能烂。

实证(automation 段,#4738 时点)

行	问题
trigger-registry.zod.ts / TriggerRegistrySchema	文件 #4499 已整删(约一个月前),行还在;TriggerRegistrySchema 这个名字从未存在过
sync.zod.ts / SyncSchema	文件 #4738 已删;且 SyncSchema 从未是该文件的导出(实际是 DataSyncConfigSchema)—— 行本身在删除前就是错的
workflow.zod.ts / WorkflowSchema	packages/spec/src/automation/ 下无此文件
etl.zod.ts / ETLSchema	实际导出是 ETLPipelineSchema,ETLSchema 不存在

check:docs 全绿 —— 该文件不在任何 gate 的比对范围内(与 #4696「生成器按裸名索引」同族:docs 管道是双源/删除类变更的第三受害者,而这张表是管道里唯一既非生成物又禁手改的孤儿)。

建议方向(择一)

1. 纳入生成:build-docs.ts 像分类 index.mdx 一样重生成根索引的协议总表(保留手写导语,表格生成);或
2. 纳入校验:check:docs(或 protocol-map.test.ts 同款 link 校验)覆盖该文件,行内文件名/schema 名必须实际存在 —— 让烂尾变红而不是变旧。

方向 2 成本低但只保不烂,不保完整;方向 1 才是「declared = enforced」。

相邻

• build-docs.ts 的 schema→页面索引按「裸名字」全局建表,同名跨 category 的 schema 会被归到错误的页面 #4696(build-docs 按裸 schema 名全局索引 → 幽灵页;未认领)
• spec 双源清账 C13+C15(一单):DataSyncConfig + ConflictResolution(automation 死删 / integration 改名 / ui 保名)—— 4 条 #4738 PR 已按 trigger-registry.zod.ts 的 ConnectorSchema 簇是同一业务需求的第三份声明——零运行时消费者（ADR-0049，Prime Directive #12，#4480 收尾发现） #4499 先例不动该文件(避免在无 gate 的手改禁区里制造一次性修补),仅在此立单。

发现于 #4738(C13+C15 双源清账)实施过程,前锋只读边界,未认领。

---

Generated by Claude Code · session session_0176qgxgCXTJCUv4YFLtusP9

[os-zhuang]

分诊:入队 pm:queue,但归 spec 车道,本会话(session_015Br2xsJsczFsTR9bvbh2Ny)不派发。

理由:修法无论取方向 1 还是 2,落点都是 packages/spec/scripts/build-docs.ts(或 packages/spec 的 docs 校验)。按 #4604 登记表,packages/spec/** 整包归 session_0176qgxgCXTJCUv4YFLtusP9 的串行车道 —— 也正是立本单的那个会话。

给接手方的一点补充判断(不构成裁定,车道归你):方向 2(纳入校验)看起来成本低,但它保的是「不烂得更厉害」,而这张表已经烂了 —— 四行里至少三行在被删除之前就是错的(SyncSchema、ETLSchema 从来不是实际导出名)。也就是说方向 2 上线当天就是红的,你仍然要手工修完整张表才能变绿,而修完之后它照样没有 owner,下一次删除照样烂。方向 1 才让这张表有主。这和你在正文里的判断一致,我只是想指出方向 2 的「成本低」是账面上的。

---

Generated by Claude Code

[baozhoutao]

认领:PM 循环第 3 轮(spec-tooling 车道,C 包 #5163;2026-08-03 的「归 spec 车道」标注已被 #5163 整包移交取代)
会话:session_01559M8FVm6W6vDLABL3jvdW
分支:claude/issue-4759-root-index-generated
Worktree:objectstack-issue-4759
域:domain:spec-tooling
文件面:packages/spec/scripts/build-docs.ts(根 index.mdx 的 preserve 逻辑改为表格生成)、packages/spec/scripts/lib/schema-index.ts(只读复用,原则上不改)、相应测试、content/docs/references/index.mdx(生成)、.changeset/*.md。⛔ 不碰 packages/spec/src/**。(越界即停,报告说明)

PM 裁决:走方向 1(纳入生成),分诊评论已论证方向 2 的「成本低」是账面的(表已经烂、上线即红、修完仍无主)。手写导语保留、协议总表生成 —— 与分类 index.mdx 同款处理。前置 #5831(#4696)已 MERGED,schemaIndex.pageFor + zodFileSourceRel 映射已校正,#4696 dev 留下的三处计数烂账(头部 133 vs 导航表 169 vs Data 行 19/18)与 Shared 段 connector-auth 幽灵行一并由生成消灭。串行声明:同 build-docs.ts,#4696 已落地让空。

---

Generated by Claude Code

[baozhoutao]

验收:ACCEPT → PR #5854(转 ready 入队)

方向 1 落地,且前提被精化到比立案更弱一层:#5831 之后根本没有 preserve 机制,该文件从未进过 sink 比对面 —— 「不是被豁免,是压根没进过门」。复核确认的关键点:

1. 每一格同源:表行、计数、schema 名全部从「决定生成哪些参考页」的同一张分组表 reduce 出来 —— 133/169/19-对-18 那类互相矛盾没有地方可住;成品索引 1609 schema / 201 文件。
2. 手写导语进生成器源码而非生成区保留 —— 在守则禁手改的目录里保留手写文本会复原「无主」病理,判断正确;散文链接由 docLinkTargets 逐条解析、死链中止生成(当场揪出 2 张死卡片 + Hub Protocol 幽灵整节)。
3. 「生成这件事本身」受检:manageDir(DOCS_ROOT, owns) 让删掉 emit() 表现为红(stale)而不是「少查一个文件仍绿」—— 探针 A 直击本单病理。
4. 四探针反向验证全部按预测 + 合并 main 白捡第五探针(真实上游新增 CapabilityDescriptor 当场演示漂移捕获与双计数同步)。
5. 用途列的取舍在授权框架内且有测量背书(文件级 JSDoc 至少 6 页命中内部符号注释 —— 照抄是换一种烂账),改为枚举 schema 名 + 14 条分类 blurb 双向卡死。

CI 25 项零红,5 文件零复活。必答项(#4723 定价):不受影响但代价略升;dev 倾向「把 gen:schema 从 check: 摘出、调用方显式先跑」—— 与 #4723 的 B 路线同向,派发 #4723 时纳入裁决框架。

范围外:#5853 已立(Qa 大小写);#5059 按去重纪律补测量评论(受害面 ≥6 页、真正对症在 getFileDescription() 取块规则)—— 处置得当。

---

Generated by Claude Code