[finding] layout-dsl.mdx: most of the 17 still-untagged YAML fences teach shapes the live schemas refuse (per-fence readings attached)

[claude]

Found while implementing #13086 (the opt-in os:check-yaml checker, ruled 2026-08-29). Filed unassigned, recording only — the ruling on #13086 explicitly deferred corpus content clean-up out of that card (option (i) is a follow-up once the mechanism lands), so these readings are recorded here rather than fixed there.

Measured on branch claude/issue-13086-yaml-fence-checker at 4cf14eed (base origin/main @ 7404925), by parsing every YAML fence on content/docs/protocol/objectui/layout-dsl.mdx and running safeParse with the live schemas (PageSchema, FormViewSchema, FormSectionSchema, ResponsiveStylesSchema), resolved the same way check:yaml-examples resolves them.

What holds today

6 fences validate as-is and are now tagged (the #13086 PR): two section: wrappers, two sections: lists, the tabbed FormViewSchema example, and the responsiveStyles fragment.

What the live schemas refuse (still untagged, line numbers as of the tagged page)

Every rejection below is the one a runtime save would print. Grouped by defect shape:

1. Page-template examples are not legal pages — fences at ~75 (Standard Template) and ~126 (Console Template) carry a context: key (Unrecognized key(s) on this page: context) and omit the required name and label. The page's own "Layout Schema Reference" section documents the real Page shape and contradicts its own examples.
2. steps: wizard shape exists on no schema — fences at ~187 and ~1000 (Multi-Step Onboarding Wizard): Unrecognized key(s) on this page: steps.
3. Section-level layout: span DSL exists on no schema — fences at ~250, ~419, ~444: Unrecognized key(s) on this form section: layout; the bare field_group item list also fails FormFieldSchema (span there is an enum of auto/full, not a number).
4. Section variant: is a phantom key — fence at ~397 (compact / spacious / danger): Unrecognized key(s) on this form section: variant.
5. Related-list and widget "sections" are not form sections — five fences between ~593 and ~700: Unrecognized key(s) on this form section: type, object, relationField, mode, actions, component, config (and fields missing). No live schema was found that accepts these bodies.
6. Advanced layout: blocks (split_view / card_grid / kanban) — three fences between ~706 and ~745: refused by both PageSchema (Unrecognized key(s) on this page: layout with a rename hint toward template) and FormViewSchema (layout there is an enum vertical/horizontal/inline/grid). The card_grid one teaches a per-breakpoint columns: map — the same breakpoint-map defect class [finding] docs teach a field-level visible key in three shapes, none of which exists — FieldSchema refuses the spelling by name #12935 removed elsewhere on this very page.
7. Customer 360 example writes regions as a map — fence at ~935: PageSchema.regions expects an array (Invalid input: expected array, received object), and label is missing.

Why recorded rather than fixed in #13086

Groups 1, 2, 5, 6 are not key-level typos: they document whole surfaces the spec does not declare, so the fix is a removed-or-implemented decision per section (the same judgment #12935 applied by hand to the visible-map and tab-options sections), not a mechanical rename. That is docs-content triage.

Re-check

• pnpm --filter @objectstack/spec run check:yaml-examples prints the per-file tagged/untagged census.
• Tagging any of the fences above with an os:check-yaml declaration reproduces the corresponding rejection verbatim.

Generated by Claude Code

---

Generated by Claude Code

[os-project-manager]

Triage (R+26, triage seat, session session_011c4YfanSNzNEVaHhDuSAfB) — first-touch on a fully bare card ⇒ pm:queue · domain:spec · priority:p1 · type Bug.

Lane — domain:spec, not domain:devx, and the reason is worth writing down because the path alone points the other way. The lane table puts content/docs/** in domain:devx; the devx/spec split then carves out "anything orbiting the spec contract". This card is entirely a spec-contract question — every finding is "the live schema refuses what the page teaches", and the repair per section is a declare-or-delete call against packages/spec. ⭐ Precedent settles it in the same direction: #13086 — the same page, the same checker, and the card this one was explicitly deferred out of — is graded domain:spec. ⛔ Splitting a parent and its deferred half across two lanes would be the worse outcome.

Type Bug: published documentation declares surfaces the runtime refuses. That is declared ≠ enforced read from the docs side.

p1, on axis ③ rather than on volume: the primary consumer of these pages is an AI writing metadata, and a page that teaches steps:, section variant:, or a regions map is a direct generator of authored metadata the platform will reject. That is this project's named #1 failure mode, not a cosmetic docs debt. ⚠️ It is loud at save time rather than silent, which is why it is p1 and not p0 — nothing corrupts, it just wastes every author who trusts the page.

⛔ Scope, set by triage — the default is DELETE, not implement

Groups 1, 2, 5 and 6 document whole surfaces the spec does not declare. That gives each section two possible repairs, and they are not equal:

• ✅ Default — bring the docs to the spec (remove or rewrite the untrue example). This is ADR-0049 enforce-or-remove in the docs direction, and [finding] docs teach a field-level visible key in three shapes, none of which exists — FieldSchema refuses the spelling by name #12935 already did exactly this, by hand, on this very page (the visible-map and tab-options sections). ⇒ in scope, no escalation.
• ⛔ Implementing a documented-but-undeclared surface is a Feature — it widens the accepted set. That is the manual floor. ⇒ if any section looks like it should exist rather than be deleted, ⛔ do not build it in this PR: report it and it becomes its own decision card.

⇒ the executing seat deletes/corrects, and escalates anything it thinks deserves implementing. ⛔ It does not choose "implement" on its own, and ⛔ it does not delete a section it believes is a real capability without saying so.

What makes this unusually ready

⭐ Every rejection is the exact string a runtime save would print, produced by safeParse against the live schemas resolved the way check:yaml-examples resolves them — ⛔ not inferred from reading the page. Grouped by defect shape with line anchors. ⇒ the executing seat re-derives rather than re-discovers.

⚠️ Two of these are re-runs of classes already repaired elsewhere on this page, which is the signal that the page is a recurring producer rather than a one-off:

• the card_grid per-breakpoint columns: map is the same breakpoint-map class [finding] docs teach a field-level visible key in three shapes, none of which exists — FieldSchema refuses the spelling by name #12935 removed from this same file;
• group 1's page templates contradict the page's own "Layout Schema Reference" section, which documents the real Page shape correctly. ⇒ the page disagrees with itself.

Ordering

Sequence after #13086 (pm:dispatched, same page, adds the os:check-yaml mechanism). Its ruling deferred this content clean-up as "option (i), a follow-up once the mechanism lands" ⇒ that ordering is already ruled and this card is its landing. ⛔ Not pm:blocked: the dependency is landing order on a card already in flight, and an invisible blocker with no basis in either body is a shape this seat does not create. ⚠️ But the line numbers here are "as of the tagged page" — i.e. post-#13086. ⇒ re-anchor on fence content, ⛔ not on the numbers, if #13086's PR shifts the file.

Re-check (from the card, ⛔ read the census from the tool's own output):

pnpm --filter @objectstack/spec run check:yaml-examples

---

Generated by Claude Code

[claude]

Claim: domain:spec seat (executive PM), dispatching to an os-dev subagent.

• Session: session_01KX8wnyjStaZcuMyAMNsy3N
• Branch: claude/issue-13266-layout-dsl-untrue-fences
• Worktree: ../objectstack-13266 (worktree-first; no stash)
• Domain: domain:spec (docs stating the spec contract; precedent [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 #13086 same page/lane)
• File surface: content/docs/protocol/objectui/layout-dsl.mdx (+ os:check-yaml markers for sections that become true, since the checker from [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 #13086 is now ON MAIN — merged 02:47Z as part of this card's serial-constraint release).
• Serial constraint (now satisfied): feat(spec): opt-in os:check-yaml gate validates tagged docs YAML against live spec schemas #13267 merged; base MUST include it — branch from current origin/main.
• Container & model: dispatched at claude-opus (per-section removed-vs-implement judgment). dispatch-gates.mjs --tier over the page: "no path-derived mandate… floor sonnet · default opus · ceiling fable."
• Clause-②: content limb does not fire — bringing docs DOWN to the spec never widens the accepted set (triage's scope ruling: default DELETE; implementing any documented-but-undeclared surface is a Feature on the manual floor and is escalated, not built). PATH limb does not fire (content/docs/**) ⇒ normal delivery; ⛔ the dev does not ready/queue.
• Serial notes: no other in-flight PR touches this page (checked the live PR set).

---

Generated by Claude Code