[finding] YAML doc fences are validated by nothing — `check:skill-examples` reads only `ts`/`tsx` fences, and only opt-in, so every metadata example in `content/docs/**` is unverifiable by construction

[os-elon]

Found while fixing #12935 (the field-level visible key taught in three shapes that
no schema declares). Filed unassigned, recording only. This is the mechanism half of
that card: not another phantom key, but the reason phantom keys keep surviving sweeps.

Measured on origin/main @ db39dfc1c9b09681474475cea6e77537ab2c89ab.

What was measured

packages/spec/scripts/check-skill-examples.ts is the one gate that compiles doc prose
against the live spec. Two properties, both deliberate and both documented in its own
header, together mean it can never see the defect class #12935 belongs to:

1. It reads only TypeScript fences. Its FENCE_OPEN_RE recognises ts, tsx and
   typescript and nothing else. A yaml fence is not in the population at all — not
   as a skipped block, not as an unchecked one. It does not exist to the gate.
2. It is opt-in. Even inside the TS population, only blocks carrying an explicit
   os:check marker are compiled. Its last run over this tree reports
   260 marked example(s) across 101 file(s), 3 surface(s).

The consequence is structural rather than incidental: metadata authoring examples are
written in YAML. That is the whole authoring surface this documentation teaches — object
definitions, view layouts, sections, fields, actions. So the format that carries almost
every example a metadata author copies is precisely the format no gate reads.

Cross-check on today's tree: content/docs/protocol/objectui/layout-dsl.mdx carries an
os:check marker at its "Visibility Rule" section over a typescript fence, which is
type-checked — while the yaml fences on the same page taught a field-level visible
breakpoint map and a section-level columns orientation map, neither of which exists on
any schema, for as long as the page has existed.

Why it is worth recording

• [finding] docs teach a field-level visible key in three shapes, none of which exists — FieldSchema refuses the spelling by name #12935's own history is the argument. layout-dsl.mdx was swept twice for exactly this
  defect family — docs: layout-dsl.mdx teaches section-level virtualScroll/itemHeight/lazy/renderStrategy keys that exist on no schema #8251 (virtualScroll / itemHeight / lazy / renderStrategy) and
  docs: layout-dsl.mdx still teaches tab-level lazy/source after #8251 removed the section-level twins — same phantom-key defect, different family #8306 — same file, same shape, different keys. Both were hand sweeps. Both missed the
  keys still on the page, because a hand sweep is the only instrument there is here, and
  a third one would have the same failure rate as the first two.
• The defect this class produces is not cosmetic. FieldSchema, FormFieldSchema and
  FormSectionSchema are all strict, so a documented key they do not declare is a
  save-blocking parse error for anyone who copies the example. The docs are the
  reason a phantom spelling circulates at all: objectui#6514's census found ZERO
  field-level visible keys across the framework's 113 *.object.* files, yet the
  renderer gated on the key for its whole life.
• It bears on AI-authored metadata specifically. An agent reading these pages has no
  channel by which to discover that the YAML it is copying cannot parse.

Prior art, deliberately not duplicated

#11407 recorded a different limit of the same gate — that an os:check fence
type-checks a visibleWhen CEL string as string, so any predicate text passes. That is
about the depth of checking inside a block the gate already reads. This is about the
population the gate reads at all.

Not a decision

Recording only, and the shape of any fix is genuinely open — a YAML-fence checker keyed
to the metadata type an example declares is one option; an opt-in marker over yaml
fences mirroring os:check is another and much cheaper; declaring the whole class
unverifiable and moving authoring examples to ts fences is a third. Each has a real
cost and none of them is obviously right, so this is left for triage rather than
pre-judged.

Re-check commands:

• git grep -n "FENCE_OPEN_RE" -- packages/spec/scripts/check-skill-examples.ts
• pnpm --filter @objectstack/spec run check:skill-examples (reports its marked-block census)
• git grep -c "os:check" -- content/docs versus the count of ```yaml fences on the same pages

Generated by Claude Code

[huangyiirene]

分诊：入决策箱 + 四棱块

needs-user-decision · domain:spec · tooling · priority:p1 · type Task。三条候选里两条是新机制（YAML 检查器 / 全站示例迁移）⇒ 命中人工地板。⛔ 不代裁。

domain:spec 按落点：packages/spec/scripts/check-skill-examples.ts 在 packages/spec 内（与 #13041 / #13083 同判据）。

<!-- os-decision-facets -->

一句话问题：唯一能把文档散文对着活 spec 编译的门禁只读 ts/tsx 围栏，且还要显式 os:check 标记。而元数据 authoring 示例是用 YAML 写的 ⇒ 这份文档教学的整个 authoring 面，恰好是没有任何门禁读得到的格式。

⭐ 这不是「漏了一类」，是按构造不可见：YAML 围栏对该门禁而言根本不在人群里 —— 不是被跳过的块，不是未检查的块，是不存在。

选项 × 真实代价

	做什么	代价
A	YAML 围栏检查器，按示例声明的元数据类型校验	覆盖最真，但是一整套新机制 —— 要解析 YAML、判定类型、接错误报告，且有自己的假阳性人群要量
B	给 yaml 围栏加一个对标 os:check 的选择性标记	便宜得多，复用既有 opt-in 骨架。⚠️ 但仍是 opt-in ⇒ 没标的照旧不可见，只把「不可能」变成「取决于有没有人标」
C	宣布该类不可验证，把 authoring 示例迁到 ts 围栏	无新机制。但改的是文档的教学形态 —— 元数据作者要读 TS 而不是他们实际编写的 YAML

四棱
① 长远合理性：A 最诚实（检查作者实际写的东西）；C 最省机制但把成本转给读者；B 是折中且保留了同一个盲区结构（未标即不可见）。
② 业务拉动：⭐ 实测的，不是推演。FieldSchema / FormFieldSchema / FormSectionSchema 都是 strict ⇒ 文档教的一个未声明键，对照抄的人就是保存时的 parse 错误。#12935 就是活实例。
③ 防 AI 犯错 —— 分水岭。⭐ 卡面那句是要害：读这些页面的 agent 没有任何通道能发现它正在抄的 YAML 根本无法解析。而 #12935 的历史证明人工清扫不够 —— layout-dsl.mdx 被扫过两次（#8251 · #8306），同文件同形状不同键，两次都漏了今天还在页面上的键。⇒ 第三次手扫的失败率没有理由更低。
④ 不扩散：B 最省；A 是新机制；C 是一次文档面迁移。创业阶段 B 的性价比最高，⛔ 但要认清 B 买到的是「可以被标」，不是「已被覆盖」。

推荐：⛔ 不裁 —— 三条的取舍是「机制成本 vs 覆盖真实性」，属产品/工程投入判断。只指出一点：B 若被选，它的价值完全取决于会不会真的有人去标，而这份文档的历史（两次手扫都漏）恰恰说明「靠人记得」在这个面上失效过两次。⇒ 若选 B，值得同时问「谁负责把存量 YAML 围栏标完」。

⭐ 置信缺口

没有人数过 content/docs/** 里 YAML 围栏的总量，以及其中有多少携带 strict schema 的键。 卡面给了重查命令（git grep -c "os:check" 对比同页 yaml 围栏数）但没跑。这个数字决定三条的相对成本：

• 若 YAML 围栏只有几十个 ⇒ C（迁到 ts）可行，A 也不贵；
• 若成百上千 ⇒ C 不现实，A 的假阳性人群也需要先量。

⇒ 建议裁前先跑那条命令。它便宜，且直接决定哪条选项还在桌上。

低摩擦裁决格式：回「先数围栏」（推荐）/「A」/「B」/「C」。

裁后执行段：先数 ⇒ 留决策箱，数字回帖后再裁。裁 A 或 B ⇒ 转 pm:queue（domain:spec），⚠️ 需 --self-test 用例，且按 #11457 纪律先量假阳性人群再开。裁 C ⇒ 转 pm:queue，落点是 content/docs/**（⇒ 车道改判 domain:devx），⛔ 不预判。

---

Generated by Claude Code