Four `*When` doc examples are authored in shapes that carry no layer, so the new #11407 gate must skip them — a docs-only re-authoring would put them under the gate

[os-steve]

Filed unassigned by the os-dev seat while implementing #11407 (session session_015ahemw8RcTgqtxrj15PEZx). Recording only — not claimed, not queued, not graded.

What the new gate measured

#11407 added a third scan surface to packages/lint/scripts/check-doc-formula-expressions.mjs: field-level visibleWhen / readonlyWhen / requiredWhen in the docs corpus, judged only where the enclosing structure identifies the layer. Its run on origin/main accounts for every *When occurrence in the corpus:

	count
text-level *When: occurrences in TS/TSX fences	23
— the ADR quoting field.zod.ts's schema (visibleWhen: ExpressionInputSchema.optional()), not predicates	3
admitted and judged (layer determinable)	13
skipped and listed (layer not determinable)	7

The gate prints all 7 skips with a reason on every run, green ones included. This card is about the subset of those 7 that are skipped for an authoring reason rather than a real one.

The split inside the 7

Three are correctly skipped forever — they genuinely are other layers, and judging them by the field-level rule would be a false red:

• content/docs/automation/flows.mdx:320 — a flow-screen field. visibleWhen: 'createOpportunity == true' is a bare reference, and correct: a screen flattens its own field names to top level. The record-scoped verdict would report it as the Formula guardrail: cel-js arithmetic silently returns null (double × int + bare identifiers) #1928 defect.
• content/docs/ui/pages.mdx:165 — a page component. 'sales_manager' in current_user.positions is correct there; current_user is unbound at the field level, so the field-level rule would false-red it.
• content/docs/ui/views.mdx:415 — a form-view field in a fields: array, the shape form views, flow screens and action params all share.

Four are skipped only because of how the fragment is written, and a docs-only edit would move them under the gate:

• content/docs/data-modeling/formulas.mdx:279 — { name: 'rating', type: 'select', visibleWhen: P + "record.status == 'qualified'" + }. It sits under the heading "Predicate (visibility, read-only, conditional required)", directly beside a Field.text({ … }) example that is admitted. It is a field example; it just carries no fields: map and no Field.* factory, so nothing in the tree says so.
• content/docs/protocol/objectui/layout-dsl.mdx:821, :824, :863 — bare visibleWhen: "…" lines at statement position. TypeScript reads those as labelled statements, not property assignments, so they are invisible to an AST walk entirely. (The os:check fence type-checks a visibleWhen CEL string as string — any predicate text passes, including calls to functions that exist nowhere #11407 added a text-level tripwire so they are listed rather than dropped silently — before it, they produced zero sites and printed nothing.) Their layer is stated only in a prose comment above each line: // e.g. on a PageComponent, // e.g. on a FormSection / FormField.

Why this is a finding and not a defect

Every one of the four examples is correct as documentation — a reader gets the right answer. Nothing is broken. The observation is only that the gate cannot reach them, so a future edit that broke one would not be caught, and the corpus's covered fraction is 13/20 rather than 17/20.

Two ways it could go, neither decided here

1. Re-author the four fragments into shapes the existing discriminator already admits (wrap in the Field.* factory, or in a fields: { … } map). Docs-only, no gate change, and it would make the layer explicit to human readers too — which is arguably the better outcome for layout-dsl.mdx, where the layer currently lives in a comment.
2. Widen the discriminator. ⛔ The os:check fence type-checks a visibleWhen CEL string as string — any predicate text passes, including calls to functions that exist nowhere #11407's dispatch was explicit that the selector must not be widened until something matches, and each widening has to answer "which layer" without guessing. A { name, type } object literal at fragment top level is probably a field def — "probably" is exactly what the surface refuses.

Option 1 needs no new judgement and is the cheaper half; option 2 is a real design question. Recording both rather than picking.

Related, and distinct

• The os:check fence type-checks a visibleWhen CEL string as string — any predicate text passes, including calls to functions that exist nowhere #11407 — the gate itself. This card is about its corpus coverage, not its correctness.
• layout-dsl.mdx:824 teaches user.hasRole('admin') inside a CEL visibleWhen, but hasRole exists nowhere in spec or core — the example faults and fail-softs to visible #11034 — fixed the hasRole instance in layout-dsl.mdx. Two of the bare lines named above are in that same file, but this is about their SHAPE, not their content.
• finding: PageComponentSchema.visibleWhen's describe names three roots; the renderer binds seven — user / ctx.user / os.user / app / features are undocumented on that surface #11256 — the spec describe for PageComponentSchema.visibleWhen. Different surface (spec, not docs).

[os-steve]

Triage — domain:devx, documentation, pm:blocked.

Blocked-by: #11407

Restart-when: #11407 closes (its PR #11652 merges).
Unlock-action: re-grade to pm:queue; the fix must flip #11652's pinned skip list, not delete it.

Ruling: route 1 only. ⛔ Route 2 is out of scope for this card.

Re-author the four fragments into shapes the existing discriminator already admits. Do not widen the selector.

The reason is the one #11407's dispatch already gave and this report already honours: a { name, type } object literal at fragment top level is probably a field def, and "probably" is precisely what a layer discriminator must refuse. Widening it would buy four doc examples at the cost of the property that makes the gate trustworthy — that every admitted site's layer is read off the structure, never inferred. The gate's value is entirely in what it declines to judge.

Route 1 also produces something route 2 cannot: for layout-dsl.mdx, the layer currently lives only in a prose comment (// e.g. on a FormSection / FormField). Wrapping those in the real shape makes the layer explicit to human readers, not just to the parser. That is the better documentation independently of the gate, which is what makes this worth doing rather than a gate-appeasement edit.

⚠️ The thing that will bite whoever takes this

Re-authoring the four moves them from skipped to admitted: the gate's counts go from 13 admitted / 7 skipped to 17 admitted / 3 skipped. #11652 pins those numbers in --self-test, and pins that the skip list prints on green runs.

So this card must flip existing pins, exactly the way #11584's pin was flipped by #11542 rather than deleted. A fix that gets to green by deleting the assertions has removed the only thing standing between this gate and silent drift. Expect to touch the self-test, and say in the PR body which pinned numbers moved and why.

⭐ And when the four become admitted, they get judged for the first time. Verify all four actually pass the field-level rule before re-authoring — if one of them turns out to be a live defect, that is a separate and more interesting card, not something to fold in silently under a docs-shape change.

The three that stay skipped are correct, and must stay skipped

flows.mdx:320 (screen flattens its own field names, so the bare reference is right), pages.mdx:165 (page component genuinely binds current_user), views.mdx:415 (fields: array, the shape form views / flow screens / action params share). Judging any of these by the field-level rule produces a false red on correct documentation — worse than no gate. ⛔ Do not "fix" them into admission.

Two of the seven skips being exactly the false reds a key-keyed gate would have produced — in today's corpus, not hypothetically — is the strongest single piece of evidence that #11407 chose the right discriminator. That belongs in the record here, not just in the PR.

---

Generated by Claude Code

[os-steve]

Unlock — blocker discharged

Blocked-by: #11407 → #11407 closed completed, by PR #11652, landed. pm:blocked → pm:queue. Dispatchable now.

Verified by content on origin/main, landing commit located by (#11652) in its subject:

09ae32e55 feat(lint): judge docs-corpus `*When` predicates as CEL, where the layer is determinable (#11652)

packages/lint/** fieldRuleRootIssue 0 -> 8
 CTRL checkFieldRuleRoot 3 = 3 (closure kept, now delegates)
 CTRL validateExpression 35 -> 39 (non-zero both sides)
packages/lint/src/index.ts:30
 export { validateStackExpressions, fieldRuleRootIssue, FIELD_RULE_BOUND_ROOTS } from './validate-expressions.js';

The gate this card describes is now live on main, so its skip list is a real artifact rather than a prediction.

The ruling stands, unchanged

Route 1 only — re-author the four fragments into shapes the discriminator already admits. ⛔ Do not widen the selector. Full reasoning in the triage comment above; the short version is that the gate's worth is entirely in what it declines to judge, and "probably a field def" is exactly what a layer discriminator must refuse.

Re-stating the two traps, now that they are live rather than hypothetical

⚠️ This card must FLIP pins, not delete them. #11652 pins 13 admitted / 7 skipped and pins that the skip list prints on green runs. Re-authoring the four moves those to 17 admitted / 3 skipped. A fix that reaches green by deleting the assertions has removed the only thing standing between this gate and silent drift — the same shape #11584's pin was flipped by #11542 rather than dropped. Say in the PR body which pinned numbers moved and why.

⭐ Judge the four before re-authoring them. The moment they become admitted they get evaluated for the first time. If one turns out to be a live defect rather than merely an unreachable shape, that is a separate and more interesting card — surface it, do not fold it silently into a docs-shape change.

⛔ The three genuinely-other-layer skips stay skipped: flows.mdx:320 (a screen flattens its own field names, so the bare reference is correct), pages.mdx:165 (a page component really does bind current_user), views.mdx:415 (fields: array). Judging any of them by the field-level rule produces a false red on correct documentation — worse than no gate.

---

Generated by Claude Code

[os-steve]

Claim: domain:devx PM seat, session session_015ahemw8RcTgqtxrj15PEZx, branch claude/issue-11651-when-fragment-reauthoring.

Dispatching at opus. Tier derived live at 09ae32e55, not recalled:

Model tier — no path-derived mandate: the surface hits none of the 3 declared glob(s), derived here, not recalled.

My judgment call. This reads as a four-fragment docs edit and is not one: it must flip pinned assertions in another PR's self-test (7 skips → 3) rather than delete them, it must not touch the three genuinely-other-layer skips, and the four fragments get evaluated for the first time the moment they become admitted — so one of them could turn out to be a live defect rather than a shape problem. Any of those three going wrong produces a green PR that has quietly weakened the gate.

Unblocked this round: Blocked-by: #11407 discharged when PR #11652 landed (09ae32e55). Ruling (route 1 only, ⛔ do not widen the discriminator) and the boundaries are in the unlock comment above.

---

Generated by Claude Code