docs(objectui): widen check-docs-section-name to singular section: and json fences

[claude]

Fixes#13880

① The prior question, answered first (per triage)

The customizations: overlay-diff list this page's "Layer 2: Admin Customization"
example taught ({ field: ... } / { section: ... } entries meant to patch Layer
1's fields and add a section) is not a declared shape:

• git grep -n "customizations" -- packages/spec/src finds only package-API
  merge-strategy prose (api/package-api.zod.ts, kernel/package-upgrade.zod.ts,
  contracts/package-service.ts) and tenant.zod.ts's single authorable
  customizations key: z.record(z.string(), z.unknown()) — a free-form record,
  not an overlay-diff list.
• FormViewSchema is .strict(), so authoring this fence as a real form view
  would be refused by name (Unrecognized key(s) on this page: customizations).
• The three-layer merge engine the example narrates is the paper
  metadata-customization protocol retired in @objectstack/spec 17
  (Retire the paper metadata-customization protocol with its full coupling set — spec module, authorable customizationPolicies/mergeStrategy keys, metadata API §5, optional IMetadataService overlay methods, unreachable packages/metadata limb (re-charter of #12057) #13135, ADR-0049 enforce-or-remove — see
  packages/spec/src/kernel/metadata-customization-retirement.test.ts). Its
  customizationPolicies and mergeStrategy keys are tombstoned rather than
  deleted on MetadataPluginConfig — read by nothing, because no 3-way
  merge engine ever ran and package upgrades never merge customizations
  (ADR-0126 §6 wall 3: an upgrade rewrites the packaged BASE; a tenant's
  choices live separately and are never merged into it).

Per the ruling, the fence is rewritten, not given an anchor — same register
as the steps: wizard-template ghost layout-dsl.mdx already removed (PR
that landed as 63cf416e8, "layout-dsl teaches only shapes the live schemas
accept"). It is replaced with a <Callout type="warn"> that:

1. States the overlay-diff list is not declared and cites the retirement
   (#13135, ADR-0126 §6, FormViewSchema.strict()).
2. Names the real mechanism: a per-org overlay write on the view
   metadata type (allowOrgOverride: true on its
   DEFAULT_METADATA_TYPE_REGISTRY entry, ADR-0005) — the org's own
   FormView document, authored with the same shape Layer 1 and the earlier
   "Server Response" example already use, not a diff against the base.

The "Final Merged Layout" JSON fence right below it no longer shows a
"Billing Info" section or a // ← Admin override annotation on phone
(both were only produced by the removed fictional Layer 2) — it now shows
only what the two real layers (base schema + user preferences) actually
merge, and its one remaining section carries name: "contact_information".
The page's "Multi-Layer Resolution Engine" summary diagram got one matching
line-edit so it does not contradict the worked example directly below it
(- Custom sections: Added "Billing Info" section → - Org overlay: a full FormView write, not a diff) — plain ASCII, not a fence the gate parses.

The two new selectors (② the population question)

scripts/check-docs-section-name.mjs gains, per the triage ("population by
shape, not marker, not fence language"):

• Selector ③ — a singular YAML section: mapping (any nesting: a
  document-root key, or a sequence-item value like - section: {...}),
  judged exactly like a sections: sequence item. The YAML_SECTIONS_KEY
  prefilter widens from sections\s*: to sections?\s*:.
• Selector ④ — a sections: [...] array inside a json/jsonc/json5
  fence, bracket-matched with the same comment-masked matcher the TS arm
  uses (not JSON.parse — a teaching fence carries // ← comments and
  JSON5 trailing commas; concept.mdx's own merged-layout fence does both).

Both are shape-based: fence language and key cardinality vary, the judgment
(does the section-shaped mapping/literal carry name?) does not.

Census, mechanically reproduced

Before this PR's docs fix (widened gate on the unmodifiedconcept.mdx,
run once to make the card's "4, not 3" mechanical):

✗ check-docs-section-name: 4 form-section example(s) in content/docs/** have no `name`
content/docs/protocol/objectui/concept.mdx:307 (Server Response json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:426 (Layer 2 `- section:` yaml — "Billing Info")
content/docs/protocol/objectui/concept.mdx:443 (Final Merged Layout json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:451 (Final Merged Layout json — "Billing Info")

Note the corpus-wide widened sweep surfaced a 5th site the issue itself did not
name: the same page's earlier "Server Response" example (:307, a real,
live-shape example unrelated to the retired-protocol fence) also had a
nameless "Contact Information" section. Fixed in this PR alongside the two
the issue named (listed below) — the widened gate's own directive is "fix
every new red it turns up in content/docs/**", not only the sites a card
happened to enumerate.

After (widened gate over the full corpus, clean):

✓ check-docs-section-name: 0 nameless form-section examples — 404 docs file(s) · 1180 TS-family fence(s) ·
14 `sections: [` array(s) · 22 section literal(s) JUDGED · 13 YAML fence(s) (13 parsed, 0 skipped) ·
22 YAML section mapping(s) JUDGED · 148 json/jsonc/json5 fence(s) · 3 `"sections": [` array(s) ·
2 JSON-family section literal(s) JUDGED

Sites fixed, all in content/docs/protocol/objectui/concept.mdx:

site	fence	fix
:307 ("Server Response")	json	added "name": "contact_information"
:419 (Layer 2 customizations:)	yaml	rewritten to a <Callout> — no anchor added, per ①
:443/:451 (Final Merged Layout)	json	dropped the Billing-Info section produced by the removed Layer 2; remaining section carries "name": "contact_information"

content/docs/ui/forms.mdx:183's "sections": [/* … */] elided placeholder
is judged as zero entries by the new arm (not skipped, not fabricated as
a nameless section) — no change needed there.
content/docs/protocol/objectui/layout-dsl.mdx's three singular section:
sites (from #13759) read ✓ named under the widened selector, as expected.
content/docs/ui/doc-pages.mdx:257 ("…from the previous section:", prose
outside any fence) does not enter the population — verified, no change.

No other content/docs/** page turned red under the widened gate; the corpus
sweep above is over the full 404-file tree.

Gates

• node scripts/check-docs-section-name.mjs --self-test → 85 cases pass
  (real temp trees on disk; both new selectors driven RED and GREEN, both
  cardinalities of the singular-section: mapping, the JSON elided-placeholder
  and comment/trailing-comma tolerance, every new refusal exercised).
• node scripts/check-docs-section-name.mjs → green on the merged tree (see
  census above).
• pnpm --filter @objectstack/spec run check:yaml-examples →
  concept.mdx: 0 tagged / 9 untagged (down from 0 tagged / 10 untagged —
  one fewer untagged YAML fence, since the customizations: fence is gone).
• Full derived gate list (node scripts/pm/dispatch-gates.mjs --commands,
  39 commands) run at 45312b3fb — all 39 green (three needed a one-time
  dependency-closure build first: @objectstack/spec,
  @objectstack/formula/@objectstack/lint, @objectstack/client-react —
  check:doc-formula-expressions/check:doc-security-posture/
  check:skill-examples each reported PREREQUISITE NOT MET, exit 3, before
  the build — not a finding). check:pm-dispatch-gates (node scripts/pm/check-dispatch-gates.mjs) run detached under heavy shared-lock
  contention (several sibling dispatch's PRs profiling/self-testing the same
  tool concurrently): command-exit 0, dispatch-gates self-test: 1240 cases pass.
• Re-derived the same 39-command list and re-ran check-docs-section-name.mjs
  • its --self-test at the final merge commit 38c73232d (after pulling
    main a second time, no conflicts, no overlap with this PR's two files) —
    still green; the other 38 were not re-run post-merge since none of the
    incoming commits touch scripts/check-docs-section-name.mjs or
    content/docs/protocol/objectui/** (verified via git log -- <paths>
    over the merged range).
• A pnpm lint-narrowed ESLint pass over just the two touched files was
  attempted three times (node_modules/eslint/bin/eslint.js scripts/check-docs-section-name.mjs content/docs/protocol/objectui/concept.mdx --no-inline-config) and could not complete: each attempt queued behind
  other agents' heavy jobs on the shared verify-lock and hit the 540s
  acquisition budget before reaching the front (queue-timeout, exit 99,
  NOT MEASURED — never ran, not a finding). Not one of the 39 derived
  commands; CI's required Lint & Repo Gates job runs full pnpm lint
  regardless.

Changeset

None — scripts/** + content/docs/** only, publishes nothing. skip-changeset
label applied and read back.

Out of scope

Nothing filed — the widened gate's full-corpus sweep came back clean apart
from the sites listed above, and no unrelated defect was hit along the way.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#13880

① The prior question, answered first (per triage)

The customizations: overlay-diff list this page's "Layer 2: Admin Customization"
example taught ({ field: ... } / { section: ... } entries meant to patch Layer
1's fields and add a section) is not a declared shape:

• git grep -n "customizations" -- packages/spec/src finds only package-API
  merge-strategy prose (api/package-api.zod.ts, kernel/package-upgrade.zod.ts,
  contracts/package-service.ts) and tenant.zod.ts's single authorable
  customizations key: z.record(z.string(), z.unknown()) — a free-form record,
  not an overlay-diff list.
• FormViewSchema is .strict(), so authoring this fence as a real form view
  would be refused by name (Unrecognized key(s) on this page: customizations).
• The three-layer merge engine the example narrates is the paper
  metadata-customization protocol retired in @objectstack/spec 17
  (Retire the paper metadata-customization protocol with its full coupling set — spec module, authorable customizationPolicies/mergeStrategy keys, metadata API §5, optional IMetadataService overlay methods, unreachable packages/metadata limb (re-charter of #12057) #13135, ADR-0049 enforce-or-remove — see
  packages/spec/src/kernel/metadata-customization-retirement.test.ts). Its
  customizationPolicies and mergeStrategy keys are tombstoned rather than
  deleted on MetadataPluginConfig — read by nothing, because no 3-way
  merge engine ever ran and package upgrades never merge customizations
  (ADR-0126 §6 wall 3: an upgrade rewrites the packaged BASE; a tenant's
  choices live separately and are never merged into it).

Per the ruling, the fence is rewritten, not given an anchor — same register
as the steps: wizard-template ghost layout-dsl.mdx already removed (PR
that landed as 63cf416e8, "layout-dsl teaches only shapes the live schemas
accept"). It is replaced with a <Callout type="warn"> that:

1. States the overlay-diff list is not declared and cites the retirement
   (#13135, ADR-0126 §6, FormViewSchema.strict()).
2. Names the real mechanism: a per-org overlay write on the view
   metadata type (allowOrgOverride: true on its
   DEFAULT_METADATA_TYPE_REGISTRY entry, ADR-0005) — the org's own
   FormView document, authored with the same shape Layer 1 and the earlier
   "Server Response" example already use, not a diff against the base.

The "Final Merged Layout" JSON fence right below it no longer shows a
"Billing Info" section or a // ← Admin override annotation on phone
(both were only produced by the removed fictional Layer 2) — it now shows
only what the two real layers (base schema + user preferences) actually
merge, and its one remaining section carries name: "contact_information".
The page's "Multi-Layer Resolution Engine" summary diagram got one matching
line-edit so it does not contradict the worked example directly below it
(- Custom sections: Added "Billing Info" section → - Org overlay: a full FormView write, not a diff) — plain ASCII, not a fence the gate parses.

The two new selectors (② the population question)

scripts/check-docs-section-name.mjs gains, per the triage ("population by
shape, not marker, not fence language"):

• Selector ③ — a singular YAML section: mapping (any nesting: a
  document-root key, or a sequence-item value like - section: {...}),
  judged exactly like a sections: sequence item. The YAML_SECTIONS_KEY
  prefilter widens from sections\s*: to sections?\s*:.
• Selector ④ — a sections: [...] array inside a json/jsonc/json5
  fence, bracket-matched with the same comment-masked matcher the TS arm
  uses (not JSON.parse — a teaching fence carries // ← comments and
  JSON5 trailing commas; concept.mdx's own merged-layout fence does both).

Both are shape-based: fence language and key cardinality vary, the judgment
(does the section-shaped mapping/literal carry name?) does not.

Census, mechanically reproduced

Before this PR's docs fix (widened gate on the unmodifiedconcept.mdx,
run once to make the card's "4, not 3" mechanical):

✗ check-docs-section-name: 4 form-section example(s) in content/docs/** have no `name`
content/docs/protocol/objectui/concept.mdx:307 (Server Response json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:426 (Layer 2 `- section:` yaml — "Billing Info")
content/docs/protocol/objectui/concept.mdx:443 (Final Merged Layout json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:451 (Final Merged Layout json — "Billing Info")

Note the corpus-wide widened sweep surfaced a 5th site the issue itself did not
name: the same page's earlier "Server Response" example (:307, a real,
live-shape example unrelated to the retired-protocol fence) also had a
nameless "Contact Information" section. Fixed in this PR alongside the two
the issue named (listed below) — the widened gate's own directive is "fix
every new red it turns up in content/docs/**", not only the sites a card
happened to enumerate.

After (widened gate over the full corpus, clean):

✓ check-docs-section-name: 0 nameless form-section examples — 404 docs file(s) · 1180 TS-family fence(s) ·
14 `sections: [` array(s) · 22 section literal(s) JUDGED · 13 YAML fence(s) (13 parsed, 0 skipped) ·
22 YAML section mapping(s) JUDGED · 148 json/jsonc/json5 fence(s) · 3 `"sections": [` array(s) ·
2 JSON-family section literal(s) JUDGED

Sites fixed, all in content/docs/protocol/objectui/concept.mdx:

site	fence	fix
:307 ("Server Response")	json	added "name": "contact_information"
:419 (Layer 2 customizations:)	yaml	rewritten to a <Callout> — no anchor added, per ①
:443/:451 (Final Merged Layout)	json	dropped the Billing-Info section produced by the removed Layer 2; remaining section carries "name": "contact_information"

content/docs/ui/forms.mdx:183's "sections": [/* … */] elided placeholder
is judged as zero entries by the new arm (not skipped, not fabricated as
a nameless section) — no change needed there.
content/docs/protocol/objectui/layout-dsl.mdx's three singular section:
sites (from #13759) read ✓ named under the widened selector, as expected.
content/docs/ui/doc-pages.mdx:257 ("…from the previous section:", prose
outside any fence) does not enter the population — verified, no change.

No other content/docs/** page turned red under the widened gate; the corpus
sweep above is over the full 404-file tree.

Gates

• node scripts/check-docs-section-name.mjs --self-test → 85 cases pass
  (real temp trees on disk; both new selectors driven RED and GREEN, both
  cardinalities of the singular-section: mapping, the JSON elided-placeholder
  and comment/trailing-comma tolerance, every new refusal exercised).
• node scripts/check-docs-section-name.mjs → green on the merged tree (see
  census above).
• pnpm --filter @objectstack/spec run check:yaml-examples →
  concept.mdx: 0 tagged / 9 untagged (down from 0 tagged / 10 untagged —
  one fewer untagged YAML fence, since the customizations: fence is gone).
• Full derived gate list (node scripts/pm/dispatch-gates.mjs --commands,
  39 commands) run at 45312b3fb — all 39 green (three needed a one-time
  dependency-closure build first: @objectstack/spec,
  @objectstack/formula/@objectstack/lint, @objectstack/client-react —
  check:doc-formula-expressions/check:doc-security-posture/
  check:skill-examples each reported PREREQUISITE NOT MET, exit 3, before
  the build — not a finding). check:pm-dispatch-gates (node scripts/pm/check-dispatch-gates.mjs) run detached under heavy shared-lock
  contention (several sibling dispatch's PRs profiling/self-testing the same
  tool concurrently): command-exit 0, dispatch-gates self-test: 1240 cases pass.
• Re-derived the same 39-command list and re-ran check-docs-section-name.mjs
  • its --self-test at the final merge commit 38c73232d (after pulling
    main a second time, no conflicts, no overlap with this PR's two files) —
    still green; the other 38 were not re-run post-merge since none of the
    incoming commits touch scripts/check-docs-section-name.mjs or
    content/docs/protocol/objectui/** (verified via git log -- <paths>
    over the merged range).
• A pnpm lint-narrowed ESLint pass over just the two touched files was
  attempted three times (node_modules/eslint/bin/eslint.js scripts/check-docs-section-name.mjs content/docs/protocol/objectui/concept.mdx --no-inline-config) and could not complete: each attempt queued behind
  other agents' heavy jobs on the shared verify-lock and hit the 540s
  acquisition budget before reaching the front (queue-timeout, exit 99,
  NOT MEASURED — never ran, not a finding). Not one of the 39 derived
  commands; CI's required Lint & Repo Gates job runs full pnpm lint
  regardless.

Changeset

None — scripts/** + content/docs/** only, publishes nothing. skip-changeset
label applied and read back.

Out of scope

Nothing filed — the widened gate's full-corpus sweep came back clean apart
from the sites listed above, and no unrelated defect was hit along the way.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#13880

① The prior question, answered first (per triage)

The customizations: overlay-diff list this page's "Layer 2: Admin Customization"
example taught ({ field: ... } / { section: ... } entries meant to patch Layer
1's fields and add a section) is not a declared shape:

• git grep -n "customizations" -- packages/spec/src finds only package-API
  merge-strategy prose (api/package-api.zod.ts, kernel/package-upgrade.zod.ts,
  contracts/package-service.ts) and tenant.zod.ts's single authorable
  customizations key: z.record(z.string(), z.unknown()) — a free-form record,
  not an overlay-diff list.
• FormViewSchema is .strict(), so authoring this fence as a real form view
  would be refused by name (Unrecognized key(s) on this page: customizations).
• The three-layer merge engine the example narrates is the paper
  metadata-customization protocol retired in @objectstack/spec 17
  (Retire the paper metadata-customization protocol with its full coupling set — spec module, authorable customizationPolicies/mergeStrategy keys, metadata API §5, optional IMetadataService overlay methods, unreachable packages/metadata limb (re-charter of #12057) #13135, ADR-0049 enforce-or-remove — see
  packages/spec/src/kernel/metadata-customization-retirement.test.ts). Its
  customizationPolicies and mergeStrategy keys are tombstoned rather than
  deleted on MetadataPluginConfig — read by nothing, because no 3-way
  merge engine ever ran and package upgrades never merge customizations
  (ADR-0126 §6 wall 3: an upgrade rewrites the packaged BASE; a tenant's
  choices live separately and are never merged into it).

Per the ruling, the fence is rewritten, not given an anchor — same register
as the steps: wizard-template ghost layout-dsl.mdx already removed (PR
that landed as 63cf416e8, "layout-dsl teaches only shapes the live schemas
accept"). It is replaced with a <Callout type="warn"> that:

1. States the overlay-diff list is not declared and cites the retirement
   (#13135, ADR-0126 §6, FormViewSchema.strict()).
2. Names the real mechanism: a per-org overlay write on the view
   metadata type (allowOrgOverride: true on its
   DEFAULT_METADATA_TYPE_REGISTRY entry, ADR-0005) — the org's own
   FormView document, authored with the same shape Layer 1 and the earlier
   "Server Response" example already use, not a diff against the base.

The "Final Merged Layout" JSON fence right below it no longer shows a
"Billing Info" section or a // ← Admin override annotation on phone
(both were only produced by the removed fictional Layer 2) — it now shows
only what the two real layers (base schema + user preferences) actually
merge, and its one remaining section carries name: "contact_information".
The page's "Multi-Layer Resolution Engine" summary diagram got one matching
line-edit so it does not contradict the worked example directly below it
(- Custom sections: Added "Billing Info" section → - Org overlay: a full FormView write, not a diff) — plain ASCII, not a fence the gate parses.

The two new selectors (② the population question)

scripts/check-docs-section-name.mjs gains, per the triage ("population by
shape, not marker, not fence language"):

• Selector ③ — a singular YAML section: mapping (any nesting: a
  document-root key, or a sequence-item value like - section: {...}),
  judged exactly like a sections: sequence item. The YAML_SECTIONS_KEY
  prefilter widens from sections\s*: to sections?\s*:.
• Selector ④ — a sections: [...] array inside a json/jsonc/json5
  fence, bracket-matched with the same comment-masked matcher the TS arm
  uses (not JSON.parse — a teaching fence carries // ← comments and
  JSON5 trailing commas; concept.mdx's own merged-layout fence does both).

Both are shape-based: fence language and key cardinality vary, the judgment
(does the section-shaped mapping/literal carry name?) does not.

Census, mechanically reproduced

Before this PR's docs fix (widened gate on the unmodifiedconcept.mdx,
run once to make the card's "4, not 3" mechanical):

✗ check-docs-section-name: 4 form-section example(s) in content/docs/** have no `name`
content/docs/protocol/objectui/concept.mdx:307 (Server Response json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:426 (Layer 2 `- section:` yaml — "Billing Info")
content/docs/protocol/objectui/concept.mdx:443 (Final Merged Layout json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:451 (Final Merged Layout json — "Billing Info")

Note the corpus-wide widened sweep surfaced a 5th site the issue itself did not
name: the same page's earlier "Server Response" example (:307, a real,
live-shape example unrelated to the retired-protocol fence) also had a
nameless "Contact Information" section. Fixed in this PR alongside the two
the issue named (listed below) — the widened gate's own directive is "fix
every new red it turns up in content/docs/**", not only the sites a card
happened to enumerate.

After (widened gate over the full corpus, clean):

✓ check-docs-section-name: 0 nameless form-section examples — 404 docs file(s) · 1180 TS-family fence(s) ·
14 `sections: [` array(s) · 22 section literal(s) JUDGED · 13 YAML fence(s) (13 parsed, 0 skipped) ·
22 YAML section mapping(s) JUDGED · 148 json/jsonc/json5 fence(s) · 3 `"sections": [` array(s) ·
2 JSON-family section literal(s) JUDGED

Sites fixed, all in content/docs/protocol/objectui/concept.mdx:

site	fence	fix
:307 ("Server Response")	json	added "name": "contact_information"
:419 (Layer 2 customizations:)	yaml	rewritten to a <Callout> — no anchor added, per ①
:443/:451 (Final Merged Layout)	json	dropped the Billing-Info section produced by the removed Layer 2; remaining section carries "name": "contact_information"

content/docs/ui/forms.mdx:183's "sections": [/* … */] elided placeholder
is judged as zero entries by the new arm (not skipped, not fabricated as
a nameless section) — no change needed there.
content/docs/protocol/objectui/layout-dsl.mdx's three singular section:
sites (from #13759) read ✓ named under the widened selector, as expected.
content/docs/ui/doc-pages.mdx:257 ("…from the previous section:", prose
outside any fence) does not enter the population — verified, no change.

No other content/docs/** page turned red under the widened gate; the corpus
sweep above is over the full 404-file tree.

Gates

• node scripts/check-docs-section-name.mjs --self-test → 85 cases pass
  (real temp trees on disk; both new selectors driven RED and GREEN, both
  cardinalities of the singular-section: mapping, the JSON elided-placeholder
  and comment/trailing-comma tolerance, every new refusal exercised).
• node scripts/check-docs-section-name.mjs → green on the merged tree (see
  census above).
• pnpm --filter @objectstack/spec run check:yaml-examples →
  concept.mdx: 0 tagged / 9 untagged (down from 0 tagged / 10 untagged —
  one fewer untagged YAML fence, since the customizations: fence is gone).
• Full derived gate list (node scripts/pm/dispatch-gates.mjs --commands,
  39 commands) run at 45312b3fb — all 39 green (three needed a one-time
  dependency-closure build first: @objectstack/spec,
  @objectstack/formula/@objectstack/lint, @objectstack/client-react —
  check:doc-formula-expressions/check:doc-security-posture/
  check:skill-examples each reported PREREQUISITE NOT MET, exit 3, before
  the build — not a finding). check:pm-dispatch-gates (node scripts/pm/check-dispatch-gates.mjs) run detached under heavy shared-lock
  contention (several sibling dispatch's PRs profiling/self-testing the same
  tool concurrently): command-exit 0, dispatch-gates self-test: 1240 cases pass.
• Re-derived the same 39-command list and re-ran check-docs-section-name.mjs
  • its --self-test at the final merge commit 38c73232d (after pulling
    main a second time, no conflicts, no overlap with this PR's two files) —
    still green; the other 38 were not re-run post-merge since none of the
    incoming commits touch scripts/check-docs-section-name.mjs or
    content/docs/protocol/objectui/** (verified via git log -- <paths>
    over the merged range).
• A pnpm lint-narrowed ESLint pass over just the two touched files was
  attempted three times (node_modules/eslint/bin/eslint.js scripts/check-docs-section-name.mjs content/docs/protocol/objectui/concept.mdx --no-inline-config) and could not complete: each attempt queued behind
  other agents' heavy jobs on the shared verify-lock and hit the 540s
  acquisition budget before reaching the front (queue-timeout, exit 99,
  NOT MEASURED — never ran, not a finding). Not one of the 39 derived
  commands; CI's required Lint & Repo Gates job runs full pnpm lint
  regardless.

Changeset

None — scripts/** + content/docs/** only, publishes nothing. skip-changeset
label applied and read back.

Out of scope

Nothing filed — the widened gate's full-corpus sweep came back clean apart
from the sites listed above, and no unrelated defect was hit along the way.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#13880

① The prior question, answered first (per triage)

The customizations: overlay-diff list this page's "Layer 2: Admin Customization"
example taught ({ field: ... } / { section: ... } entries meant to patch Layer
1's fields and add a section) is not a declared shape:

• git grep -n "customizations" -- packages/spec/src finds only package-API
  merge-strategy prose (api/package-api.zod.ts, kernel/package-upgrade.zod.ts,
  contracts/package-service.ts) and tenant.zod.ts's single authorable
  customizations key: z.record(z.string(), z.unknown()) — a free-form record,
  not an overlay-diff list.
• FormViewSchema is .strict(), so authoring this fence as a real form view
  would be refused by name (Unrecognized key(s) on this page: customizations).
• The three-layer merge engine the example narrates is the paper
  metadata-customization protocol retired in @objectstack/spec 17
  (Retire the paper metadata-customization protocol with its full coupling set — spec module, authorable customizationPolicies/mergeStrategy keys, metadata API §5, optional IMetadataService overlay methods, unreachable packages/metadata limb (re-charter of #12057) #13135, ADR-0049 enforce-or-remove — see
  packages/spec/src/kernel/metadata-customization-retirement.test.ts). Its
  customizationPolicies and mergeStrategy keys are tombstoned rather than
  deleted on MetadataPluginConfig — read by nothing, because no 3-way
  merge engine ever ran and package upgrades never merge customizations
  (ADR-0126 §6 wall 3: an upgrade rewrites the packaged BASE; a tenant's
  choices live separately and are never merged into it).

Per the ruling, the fence is rewritten, not given an anchor — same register
as the steps: wizard-template ghost layout-dsl.mdx already removed (PR
that landed as 63cf416e8, "layout-dsl teaches only shapes the live schemas
accept"). It is replaced with a <Callout type="warn"> that:

1. States the overlay-diff list is not declared and cites the retirement
   (#13135, ADR-0126 §6, FormViewSchema.strict()).
2. Names the real mechanism: a per-org overlay write on the view
   metadata type (allowOrgOverride: true on its
   DEFAULT_METADATA_TYPE_REGISTRY entry, ADR-0005) — the org's own
   FormView document, authored with the same shape Layer 1 and the earlier
   "Server Response" example already use, not a diff against the base.

The "Final Merged Layout" JSON fence right below it no longer shows a
"Billing Info" section or a // ← Admin override annotation on phone
(both were only produced by the removed fictional Layer 2) — it now shows
only what the two real layers (base schema + user preferences) actually
merge, and its one remaining section carries name: "contact_information".
The page's "Multi-Layer Resolution Engine" summary diagram got one matching
line-edit so it does not contradict the worked example directly below it
(- Custom sections: Added "Billing Info" section → - Org overlay: a full FormView write, not a diff) — plain ASCII, not a fence the gate parses.

The two new selectors (② the population question)

scripts/check-docs-section-name.mjs gains, per the triage ("population by
shape, not marker, not fence language"):

• Selector ③ — a singular YAML section: mapping (any nesting: a
  document-root key, or a sequence-item value like - section: {...}),
  judged exactly like a sections: sequence item. The YAML_SECTIONS_KEY
  prefilter widens from sections\s*: to sections?\s*:.
• Selector ④ — a sections: [...] array inside a json/jsonc/json5
  fence, bracket-matched with the same comment-masked matcher the TS arm
  uses (not JSON.parse — a teaching fence carries // ← comments and
  JSON5 trailing commas; concept.mdx's own merged-layout fence does both).

Both are shape-based: fence language and key cardinality vary, the judgment
(does the section-shaped mapping/literal carry name?) does not.

Census, mechanically reproduced

Before this PR's docs fix (widened gate on the unmodifiedconcept.mdx,
run once to make the card's "4, not 3" mechanical):

✗ check-docs-section-name: 4 form-section example(s) in content/docs/** have no `name`
content/docs/protocol/objectui/concept.mdx:307 (Server Response json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:426 (Layer 2 `- section:` yaml — "Billing Info")
content/docs/protocol/objectui/concept.mdx:443 (Final Merged Layout json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:451 (Final Merged Layout json — "Billing Info")

Note the corpus-wide widened sweep surfaced a 5th site the issue itself did not
name: the same page's earlier "Server Response" example (:307, a real,
live-shape example unrelated to the retired-protocol fence) also had a
nameless "Contact Information" section. Fixed in this PR alongside the two
the issue named (listed below) — the widened gate's own directive is "fix
every new red it turns up in content/docs/**", not only the sites a card
happened to enumerate.

After (widened gate over the full corpus, clean):

✓ check-docs-section-name: 0 nameless form-section examples — 404 docs file(s) · 1180 TS-family fence(s) ·
14 `sections: [` array(s) · 22 section literal(s) JUDGED · 13 YAML fence(s) (13 parsed, 0 skipped) ·
22 YAML section mapping(s) JUDGED · 148 json/jsonc/json5 fence(s) · 3 `"sections": [` array(s) ·
2 JSON-family section literal(s) JUDGED

Sites fixed, all in content/docs/protocol/objectui/concept.mdx:

site	fence	fix
:307 ("Server Response")	json	added "name": "contact_information"
:419 (Layer 2 customizations:)	yaml	rewritten to a <Callout> — no anchor added, per ①
:443/:451 (Final Merged Layout)	json	dropped the Billing-Info section produced by the removed Layer 2; remaining section carries "name": "contact_information"

content/docs/ui/forms.mdx:183's "sections": [/* … */] elided placeholder
is judged as zero entries by the new arm (not skipped, not fabricated as
a nameless section) — no change needed there.
content/docs/protocol/objectui/layout-dsl.mdx's three singular section:
sites (from #13759) read ✓ named under the widened selector, as expected.
content/docs/ui/doc-pages.mdx:257 ("…from the previous section:", prose
outside any fence) does not enter the population — verified, no change.

No other content/docs/** page turned red under the widened gate; the corpus
sweep above is over the full 404-file tree.

Gates

• node scripts/check-docs-section-name.mjs --self-test → 85 cases pass
  (real temp trees on disk; both new selectors driven RED and GREEN, both
  cardinalities of the singular-section: mapping, the JSON elided-placeholder
  and comment/trailing-comma tolerance, every new refusal exercised).
• node scripts/check-docs-section-name.mjs → green on the merged tree (see
  census above).
• pnpm --filter @objectstack/spec run check:yaml-examples →
  concept.mdx: 0 tagged / 9 untagged (down from 0 tagged / 10 untagged —
  one fewer untagged YAML fence, since the customizations: fence is gone).
• Full derived gate list (node scripts/pm/dispatch-gates.mjs --commands,
  39 commands) run at 45312b3fb — all 39 green (three needed a one-time
  dependency-closure build first: @objectstack/spec,
  @objectstack/formula/@objectstack/lint, @objectstack/client-react —
  check:doc-formula-expressions/check:doc-security-posture/
  check:skill-examples each reported PREREQUISITE NOT MET, exit 3, before
  the build — not a finding). check:pm-dispatch-gates (node scripts/pm/check-dispatch-gates.mjs) run detached under heavy shared-lock
  contention (several sibling dispatch's PRs profiling/self-testing the same
  tool concurrently): command-exit 0, dispatch-gates self-test: 1240 cases pass.
• Re-derived the same 39-command list and re-ran check-docs-section-name.mjs
  • its --self-test at the final merge commit 38c73232d (after pulling
    main a second time, no conflicts, no overlap with this PR's two files) —
    still green; the other 38 were not re-run post-merge since none of the
    incoming commits touch scripts/check-docs-section-name.mjs or
    content/docs/protocol/objectui/** (verified via git log -- <paths>
    over the merged range).
• A pnpm lint-narrowed ESLint pass over just the two touched files was
  attempted three times (node_modules/eslint/bin/eslint.js scripts/check-docs-section-name.mjs content/docs/protocol/objectui/concept.mdx --no-inline-config) and could not complete: each attempt queued behind
  other agents' heavy jobs on the shared verify-lock and hit the 540s
  acquisition budget before reaching the front (queue-timeout, exit 99,
  NOT MEASURED — never ran, not a finding). Not one of the 39 derived
  commands; CI's required Lint & Repo Gates job runs full pnpm lint
  regardless.

Changeset

None — scripts/** + content/docs/** only, publishes nothing. skip-changeset
label applied and read back.

Out of scope

Nothing filed — the widened gate's full-corpus sweep came back clean apart
from the sites listed above, and no unrelated defect was hit along the way.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#13880

① The prior question, answered first (per triage)

The customizations: overlay-diff list this page's "Layer 2: Admin Customization"
example taught ({ field: ... } / { section: ... } entries meant to patch Layer
1's fields and add a section) is not a declared shape:

• git grep -n "customizations" -- packages/spec/src finds only package-API
  merge-strategy prose (api/package-api.zod.ts, kernel/package-upgrade.zod.ts,
  contracts/package-service.ts) and tenant.zod.ts's single authorable
  customizations key: z.record(z.string(), z.unknown()) — a free-form record,
  not an overlay-diff list.
• FormViewSchema is .strict(), so authoring this fence as a real form view
  would be refused by name (Unrecognized key(s) on this page: customizations).
• The three-layer merge engine the example narrates is the paper
  metadata-customization protocol retired in @objectstack/spec 17
  (Retire the paper metadata-customization protocol with its full coupling set — spec module, authorable customizationPolicies/mergeStrategy keys, metadata API §5, optional IMetadataService overlay methods, unreachable packages/metadata limb (re-charter of #12057) #13135, ADR-0049 enforce-or-remove — see
  packages/spec/src/kernel/metadata-customization-retirement.test.ts). Its
  customizationPolicies and mergeStrategy keys are tombstoned rather than
  deleted on MetadataPluginConfig — read by nothing, because no 3-way
  merge engine ever ran and package upgrades never merge customizations
  (ADR-0126 §6 wall 3: an upgrade rewrites the packaged BASE; a tenant's
  choices live separately and are never merged into it).

Per the ruling, the fence is rewritten, not given an anchor — same register
as the steps: wizard-template ghost layout-dsl.mdx already removed (PR
that landed as 63cf416e8, "layout-dsl teaches only shapes the live schemas
accept"). It is replaced with a <Callout type="warn"> that:

1. States the overlay-diff list is not declared and cites the retirement
   (#13135, ADR-0126 §6, FormViewSchema.strict()).
2. Names the real mechanism: a per-org overlay write on the view
   metadata type (allowOrgOverride: true on its
   DEFAULT_METADATA_TYPE_REGISTRY entry, ADR-0005) — the org's own
   FormView document, authored with the same shape Layer 1 and the earlier
   "Server Response" example already use, not a diff against the base.

The "Final Merged Layout" JSON fence right below it no longer shows a
"Billing Info" section or a // ← Admin override annotation on phone
(both were only produced by the removed fictional Layer 2) — it now shows
only what the two real layers (base schema + user preferences) actually
merge, and its one remaining section carries name: "contact_information".
The page's "Multi-Layer Resolution Engine" summary diagram got one matching
line-edit so it does not contradict the worked example directly below it
(- Custom sections: Added "Billing Info" section → - Org overlay: a full FormView write, not a diff) — plain ASCII, not a fence the gate parses.

The two new selectors (② the population question)

scripts/check-docs-section-name.mjs gains, per the triage ("population by
shape, not marker, not fence language"):

• Selector ③ — a singular YAML section: mapping (any nesting: a
  document-root key, or a sequence-item value like - section: {...}),
  judged exactly like a sections: sequence item. The YAML_SECTIONS_KEY
  prefilter widens from sections\s*: to sections?\s*:.
• Selector ④ — a sections: [...] array inside a json/jsonc/json5
  fence, bracket-matched with the same comment-masked matcher the TS arm
  uses (not JSON.parse — a teaching fence carries // ← comments and
  JSON5 trailing commas; concept.mdx's own merged-layout fence does both).

Both are shape-based: fence language and key cardinality vary, the judgment
(does the section-shaped mapping/literal carry name?) does not.

Census, mechanically reproduced

Before this PR's docs fix (widened gate on the unmodifiedconcept.mdx,
run once to make the card's "4, not 3" mechanical):

✗ check-docs-section-name: 4 form-section example(s) in content/docs/** have no `name`
content/docs/protocol/objectui/concept.mdx:307 (Server Response json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:426 (Layer 2 `- section:` yaml — "Billing Info")
content/docs/protocol/objectui/concept.mdx:443 (Final Merged Layout json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:451 (Final Merged Layout json — "Billing Info")

Note the corpus-wide widened sweep surfaced a 5th site the issue itself did not
name: the same page's earlier "Server Response" example (:307, a real,
live-shape example unrelated to the retired-protocol fence) also had a
nameless "Contact Information" section. Fixed in this PR alongside the two
the issue named (listed below) — the widened gate's own directive is "fix
every new red it turns up in content/docs/**", not only the sites a card
happened to enumerate.

After (widened gate over the full corpus, clean):

✓ check-docs-section-name: 0 nameless form-section examples — 404 docs file(s) · 1180 TS-family fence(s) ·
14 `sections: [` array(s) · 22 section literal(s) JUDGED · 13 YAML fence(s) (13 parsed, 0 skipped) ·
22 YAML section mapping(s) JUDGED · 148 json/jsonc/json5 fence(s) · 3 `"sections": [` array(s) ·
2 JSON-family section literal(s) JUDGED

Sites fixed, all in content/docs/protocol/objectui/concept.mdx:

site	fence	fix
:307 ("Server Response")	json	added "name": "contact_information"
:419 (Layer 2 customizations:)	yaml	rewritten to a <Callout> — no anchor added, per ①
:443/:451 (Final Merged Layout)	json	dropped the Billing-Info section produced by the removed Layer 2; remaining section carries "name": "contact_information"

content/docs/ui/forms.mdx:183's "sections": [/* … */] elided placeholder
is judged as zero entries by the new arm (not skipped, not fabricated as
a nameless section) — no change needed there.
content/docs/protocol/objectui/layout-dsl.mdx's three singular section:
sites (from #13759) read ✓ named under the widened selector, as expected.
content/docs/ui/doc-pages.mdx:257 ("…from the previous section:", prose
outside any fence) does not enter the population — verified, no change.

No other content/docs/** page turned red under the widened gate; the corpus
sweep above is over the full 404-file tree.

Gates

• node scripts/check-docs-section-name.mjs --self-test → 85 cases pass
  (real temp trees on disk; both new selectors driven RED and GREEN, both
  cardinalities of the singular-section: mapping, the JSON elided-placeholder
  and comment/trailing-comma tolerance, every new refusal exercised).
• node scripts/check-docs-section-name.mjs → green on the merged tree (see
  census above).
• pnpm --filter @objectstack/spec run check:yaml-examples →
  concept.mdx: 0 tagged / 9 untagged (down from 0 tagged / 10 untagged —
  one fewer untagged YAML fence, since the customizations: fence is gone).
• Full derived gate list (node scripts/pm/dispatch-gates.mjs --commands,
  39 commands) run at 45312b3fb — all 39 green (three needed a one-time
  dependency-closure build first: @objectstack/spec,
  @objectstack/formula/@objectstack/lint, @objectstack/client-react —
  check:doc-formula-expressions/check:doc-security-posture/
  check:skill-examples each reported PREREQUISITE NOT MET, exit 3, before
  the build — not a finding). check:pm-dispatch-gates (node scripts/pm/check-dispatch-gates.mjs) run detached under heavy shared-lock
  contention (several sibling dispatch's PRs profiling/self-testing the same
  tool concurrently): command-exit 0, dispatch-gates self-test: 1240 cases pass.
• Re-derived the same 39-command list and re-ran check-docs-section-name.mjs
  • its --self-test at the final merge commit 38c73232d (after pulling
    main a second time, no conflicts, no overlap with this PR's two files) —
    still green; the other 38 were not re-run post-merge since none of the
    incoming commits touch scripts/check-docs-section-name.mjs or
    content/docs/protocol/objectui/** (verified via git log -- <paths>
    over the merged range).
• A pnpm lint-narrowed ESLint pass over just the two touched files was
  attempted three times (node_modules/eslint/bin/eslint.js scripts/check-docs-section-name.mjs content/docs/protocol/objectui/concept.mdx --no-inline-config) and could not complete: each attempt queued behind
  other agents' heavy jobs on the shared verify-lock and hit the 540s
  acquisition budget before reaching the front (queue-timeout, exit 99,
  NOT MEASURED — never ran, not a finding). Not one of the 39 derived
  commands; CI's required Lint & Repo Gates job runs full pnpm lint
  regardless.

Changeset

None — scripts/** + content/docs/** only, publishes nothing. skip-changeset
label applied and read back.

Out of scope

Nothing filed — the widened gate's full-corpus sweep came back clean apart
from the sites listed above, and no unrelated defect was hit along the way.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#13880

① The prior question, answered first (per triage)

The customizations: overlay-diff list this page's "Layer 2: Admin Customization"
example taught ({ field: ... } / { section: ... } entries meant to patch Layer
1's fields and add a section) is not a declared shape:

• git grep -n "customizations" -- packages/spec/src finds only package-API
  merge-strategy prose (api/package-api.zod.ts, kernel/package-upgrade.zod.ts,
  contracts/package-service.ts) and tenant.zod.ts's single authorable
  customizations key: z.record(z.string(), z.unknown()) — a free-form record,
  not an overlay-diff list.
• FormViewSchema is .strict(), so authoring this fence as a real form view
  would be refused by name (Unrecognized key(s) on this page: customizations).
• The three-layer merge engine the example narrates is the paper
  metadata-customization protocol retired in @objectstack/spec 17
  (Retire the paper metadata-customization protocol with its full coupling set — spec module, authorable customizationPolicies/mergeStrategy keys, metadata API §5, optional IMetadataService overlay methods, unreachable packages/metadata limb (re-charter of #12057) #13135, ADR-0049 enforce-or-remove — see
  packages/spec/src/kernel/metadata-customization-retirement.test.ts). Its
  customizationPolicies and mergeStrategy keys are tombstoned rather than
  deleted on MetadataPluginConfig — read by nothing, because no 3-way
  merge engine ever ran and package upgrades never merge customizations
  (ADR-0126 §6 wall 3: an upgrade rewrites the packaged BASE; a tenant's
  choices live separately and are never merged into it).

Per the ruling, the fence is rewritten, not given an anchor — same register
as the steps: wizard-template ghost layout-dsl.mdx already removed (PR
that landed as 63cf416e8, "layout-dsl teaches only shapes the live schemas
accept"). It is replaced with a <Callout type="warn"> that:

1. States the overlay-diff list is not declared and cites the retirement
   (#13135, ADR-0126 §6, FormViewSchema.strict()).
2. Names the real mechanism: a per-org overlay write on the view
   metadata type (allowOrgOverride: true on its
   DEFAULT_METADATA_TYPE_REGISTRY entry, ADR-0005) — the org's own
   FormView document, authored with the same shape Layer 1 and the earlier
   "Server Response" example already use, not a diff against the base.

The "Final Merged Layout" JSON fence right below it no longer shows a
"Billing Info" section or a // ← Admin override annotation on phone
(both were only produced by the removed fictional Layer 2) — it now shows
only what the two real layers (base schema + user preferences) actually
merge, and its one remaining section carries name: "contact_information".
The page's "Multi-Layer Resolution Engine" summary diagram got one matching
line-edit so it does not contradict the worked example directly below it
(- Custom sections: Added "Billing Info" section → - Org overlay: a full FormView write, not a diff) — plain ASCII, not a fence the gate parses.

The two new selectors (② the population question)

scripts/check-docs-section-name.mjs gains, per the triage ("population by
shape, not marker, not fence language"):

• Selector ③ — a singular YAML section: mapping (any nesting: a
  document-root key, or a sequence-item value like - section: {...}),
  judged exactly like a sections: sequence item. The YAML_SECTIONS_KEY
  prefilter widens from sections\s*: to sections?\s*:.
• Selector ④ — a sections: [...] array inside a json/jsonc/json5
  fence, bracket-matched with the same comment-masked matcher the TS arm
  uses (not JSON.parse — a teaching fence carries // ← comments and
  JSON5 trailing commas; concept.mdx's own merged-layout fence does both).

Both are shape-based: fence language and key cardinality vary, the judgment
(does the section-shaped mapping/literal carry name?) does not.

Census, mechanically reproduced

Before this PR's docs fix (widened gate on the unmodifiedconcept.mdx,
run once to make the card's "4, not 3" mechanical):

✗ check-docs-section-name: 4 form-section example(s) in content/docs/** have no `name`
content/docs/protocol/objectui/concept.mdx:307 (Server Response json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:426 (Layer 2 `- section:` yaml — "Billing Info")
content/docs/protocol/objectui/concept.mdx:443 (Final Merged Layout json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:451 (Final Merged Layout json — "Billing Info")

Note the corpus-wide widened sweep surfaced a 5th site the issue itself did not
name: the same page's earlier "Server Response" example (:307, a real,
live-shape example unrelated to the retired-protocol fence) also had a
nameless "Contact Information" section. Fixed in this PR alongside the two
the issue named (listed below) — the widened gate's own directive is "fix
every new red it turns up in content/docs/**", not only the sites a card
happened to enumerate.

After (widened gate over the full corpus, clean):

✓ check-docs-section-name: 0 nameless form-section examples — 404 docs file(s) · 1180 TS-family fence(s) ·
14 `sections: [` array(s) · 22 section literal(s) JUDGED · 13 YAML fence(s) (13 parsed, 0 skipped) ·
22 YAML section mapping(s) JUDGED · 148 json/jsonc/json5 fence(s) · 3 `"sections": [` array(s) ·
2 JSON-family section literal(s) JUDGED

Sites fixed, all in content/docs/protocol/objectui/concept.mdx:

site	fence	fix
:307 ("Server Response")	json	added "name": "contact_information"
:419 (Layer 2 customizations:)	yaml	rewritten to a <Callout> — no anchor added, per ①
:443/:451 (Final Merged Layout)	json	dropped the Billing-Info section produced by the removed Layer 2; remaining section carries "name": "contact_information"

content/docs/ui/forms.mdx:183's "sections": [/* … */] elided placeholder
is judged as zero entries by the new arm (not skipped, not fabricated as
a nameless section) — no change needed there.
content/docs/protocol/objectui/layout-dsl.mdx's three singular section:
sites (from #13759) read ✓ named under the widened selector, as expected.
content/docs/ui/doc-pages.mdx:257 ("…from the previous section:", prose
outside any fence) does not enter the population — verified, no change.

No other content/docs/** page turned red under the widened gate; the corpus
sweep above is over the full 404-file tree.

Gates

• node scripts/check-docs-section-name.mjs --self-test → 85 cases pass
  (real temp trees on disk; both new selectors driven RED and GREEN, both
  cardinalities of the singular-section: mapping, the JSON elided-placeholder
  and comment/trailing-comma tolerance, every new refusal exercised).
• node scripts/check-docs-section-name.mjs → green on the merged tree (see
  census above).
• pnpm --filter @objectstack/spec run check:yaml-examples →
  concept.mdx: 0 tagged / 9 untagged (down from 0 tagged / 10 untagged —
  one fewer untagged YAML fence, since the customizations: fence is gone).
• Full derived gate list (node scripts/pm/dispatch-gates.mjs --commands,
  39 commands) run at 45312b3fb — all 39 green (three needed a one-time
  dependency-closure build first: @objectstack/spec,
  @objectstack/formula/@objectstack/lint, @objectstack/client-react —
  check:doc-formula-expressions/check:doc-security-posture/
  check:skill-examples each reported PREREQUISITE NOT MET, exit 3, before
  the build — not a finding). check:pm-dispatch-gates (node scripts/pm/check-dispatch-gates.mjs) run detached under heavy shared-lock
  contention (several sibling dispatch's PRs profiling/self-testing the same
  tool concurrently): command-exit 0, dispatch-gates self-test: 1240 cases pass.
• Re-derived the same 39-command list and re-ran check-docs-section-name.mjs
  • its --self-test at the final merge commit 38c73232d (after pulling
    main a second time, no conflicts, no overlap with this PR's two files) —
    still green; the other 38 were not re-run post-merge since none of the
    incoming commits touch scripts/check-docs-section-name.mjs or
    content/docs/protocol/objectui/** (verified via git log -- <paths>
    over the merged range).
• A pnpm lint-narrowed ESLint pass over just the two touched files was
  attempted three times (node_modules/eslint/bin/eslint.js scripts/check-docs-section-name.mjs content/docs/protocol/objectui/concept.mdx --no-inline-config) and could not complete: each attempt queued behind
  other agents' heavy jobs on the shared verify-lock and hit the 540s
  acquisition budget before reaching the front (queue-timeout, exit 99,
  NOT MEASURED — never ran, not a finding). Not one of the 39 derived
  commands; CI's required Lint & Repo Gates job runs full pnpm lint
  regardless.

Changeset

None — scripts/** + content/docs/** only, publishes nothing. skip-changeset
label applied and read back.

Out of scope

Nothing filed — the widened gate's full-corpus sweep came back clean apart
from the sites listed above, and no unrelated defect was hit along the way.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#13880

① The prior question, answered first (per triage)

The customizations: overlay-diff list this page's "Layer 2: Admin Customization"
example taught ({ field: ... } / { section: ... } entries meant to patch Layer
1's fields and add a section) is not a declared shape:

• git grep -n "customizations" -- packages/spec/src finds only package-API
  merge-strategy prose (api/package-api.zod.ts, kernel/package-upgrade.zod.ts,
  contracts/package-service.ts) and tenant.zod.ts's single authorable
  customizations key: z.record(z.string(), z.unknown()) — a free-form record,
  not an overlay-diff list.
• FormViewSchema is .strict(), so authoring this fence as a real form view
  would be refused by name (Unrecognized key(s) on this page: customizations).
• The three-layer merge engine the example narrates is the paper
  metadata-customization protocol retired in @objectstack/spec 17
  (Retire the paper metadata-customization protocol with its full coupling set — spec module, authorable customizationPolicies/mergeStrategy keys, metadata API §5, optional IMetadataService overlay methods, unreachable packages/metadata limb (re-charter of #12057) #13135, ADR-0049 enforce-or-remove — see
  packages/spec/src/kernel/metadata-customization-retirement.test.ts). Its
  customizationPolicies and mergeStrategy keys are tombstoned rather than
  deleted on MetadataPluginConfig — read by nothing, because no 3-way
  merge engine ever ran and package upgrades never merge customizations
  (ADR-0126 §6 wall 3: an upgrade rewrites the packaged BASE; a tenant's
  choices live separately and are never merged into it).

Per the ruling, the fence is rewritten, not given an anchor — same register
as the steps: wizard-template ghost layout-dsl.mdx already removed (PR
that landed as 63cf416e8, "layout-dsl teaches only shapes the live schemas
accept"). It is replaced with a <Callout type="warn"> that:

1. States the overlay-diff list is not declared and cites the retirement
   (#13135, ADR-0126 §6, FormViewSchema.strict()).
2. Names the real mechanism: a per-org overlay write on the view
   metadata type (allowOrgOverride: true on its
   DEFAULT_METADATA_TYPE_REGISTRY entry, ADR-0005) — the org's own
   FormView document, authored with the same shape Layer 1 and the earlier
   "Server Response" example already use, not a diff against the base.

The "Final Merged Layout" JSON fence right below it no longer shows a
"Billing Info" section or a // ← Admin override annotation on phone
(both were only produced by the removed fictional Layer 2) — it now shows
only what the two real layers (base schema + user preferences) actually
merge, and its one remaining section carries name: "contact_information".
The page's "Multi-Layer Resolution Engine" summary diagram got one matching
line-edit so it does not contradict the worked example directly below it
(- Custom sections: Added "Billing Info" section → - Org overlay: a full FormView write, not a diff) — plain ASCII, not a fence the gate parses.

The two new selectors (② the population question)

scripts/check-docs-section-name.mjs gains, per the triage ("population by
shape, not marker, not fence language"):

• Selector ③ — a singular YAML section: mapping (any nesting: a
  document-root key, or a sequence-item value like - section: {...}),
  judged exactly like a sections: sequence item. The YAML_SECTIONS_KEY
  prefilter widens from sections\s*: to sections?\s*:.
• Selector ④ — a sections: [...] array inside a json/jsonc/json5
  fence, bracket-matched with the same comment-masked matcher the TS arm
  uses (not JSON.parse — a teaching fence carries // ← comments and
  JSON5 trailing commas; concept.mdx's own merged-layout fence does both).

Both are shape-based: fence language and key cardinality vary, the judgment
(does the section-shaped mapping/literal carry name?) does not.

Census, mechanically reproduced

Before this PR's docs fix (widened gate on the unmodifiedconcept.mdx,
run once to make the card's "4, not 3" mechanical):

✗ check-docs-section-name: 4 form-section example(s) in content/docs/** have no `name`
content/docs/protocol/objectui/concept.mdx:307 (Server Response json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:426 (Layer 2 `- section:` yaml — "Billing Info")
content/docs/protocol/objectui/concept.mdx:443 (Final Merged Layout json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:451 (Final Merged Layout json — "Billing Info")

Note the corpus-wide widened sweep surfaced a 5th site the issue itself did not
name: the same page's earlier "Server Response" example (:307, a real,
live-shape example unrelated to the retired-protocol fence) also had a
nameless "Contact Information" section. Fixed in this PR alongside the two
the issue named (listed below) — the widened gate's own directive is "fix
every new red it turns up in content/docs/**", not only the sites a card
happened to enumerate.

After (widened gate over the full corpus, clean):

✓ check-docs-section-name: 0 nameless form-section examples — 404 docs file(s) · 1180 TS-family fence(s) ·
14 `sections: [` array(s) · 22 section literal(s) JUDGED · 13 YAML fence(s) (13 parsed, 0 skipped) ·
22 YAML section mapping(s) JUDGED · 148 json/jsonc/json5 fence(s) · 3 `"sections": [` array(s) ·
2 JSON-family section literal(s) JUDGED

Sites fixed, all in content/docs/protocol/objectui/concept.mdx:

site	fence	fix
:307 ("Server Response")	json	added "name": "contact_information"
:419 (Layer 2 customizations:)	yaml	rewritten to a <Callout> — no anchor added, per ①
:443/:451 (Final Merged Layout)	json	dropped the Billing-Info section produced by the removed Layer 2; remaining section carries "name": "contact_information"

content/docs/ui/forms.mdx:183's "sections": [/* … */] elided placeholder
is judged as zero entries by the new arm (not skipped, not fabricated as
a nameless section) — no change needed there.
content/docs/protocol/objectui/layout-dsl.mdx's three singular section:
sites (from #13759) read ✓ named under the widened selector, as expected.
content/docs/ui/doc-pages.mdx:257 ("…from the previous section:", prose
outside any fence) does not enter the population — verified, no change.

No other content/docs/** page turned red under the widened gate; the corpus
sweep above is over the full 404-file tree.

Gates

• node scripts/check-docs-section-name.mjs --self-test → 85 cases pass
  (real temp trees on disk; both new selectors driven RED and GREEN, both
  cardinalities of the singular-section: mapping, the JSON elided-placeholder
  and comment/trailing-comma tolerance, every new refusal exercised).
• node scripts/check-docs-section-name.mjs → green on the merged tree (see
  census above).
• pnpm --filter @objectstack/spec run check:yaml-examples →
  concept.mdx: 0 tagged / 9 untagged (down from 0 tagged / 10 untagged —
  one fewer untagged YAML fence, since the customizations: fence is gone).
• Full derived gate list (node scripts/pm/dispatch-gates.mjs --commands,
  39 commands) run at 45312b3fb — all 39 green (three needed a one-time
  dependency-closure build first: @objectstack/spec,
  @objectstack/formula/@objectstack/lint, @objectstack/client-react —
  check:doc-formula-expressions/check:doc-security-posture/
  check:skill-examples each reported PREREQUISITE NOT MET, exit 3, before
  the build — not a finding). check:pm-dispatch-gates (node scripts/pm/check-dispatch-gates.mjs) run detached under heavy shared-lock
  contention (several sibling dispatch's PRs profiling/self-testing the same
  tool concurrently): command-exit 0, dispatch-gates self-test: 1240 cases pass.
• Re-derived the same 39-command list and re-ran check-docs-section-name.mjs
  • its --self-test at the final merge commit 38c73232d (after pulling
    main a second time, no conflicts, no overlap with this PR's two files) —
    still green; the other 38 were not re-run post-merge since none of the
    incoming commits touch scripts/check-docs-section-name.mjs or
    content/docs/protocol/objectui/** (verified via git log -- <paths>
    over the merged range).
• A pnpm lint-narrowed ESLint pass over just the two touched files was
  attempted three times (node_modules/eslint/bin/eslint.js scripts/check-docs-section-name.mjs content/docs/protocol/objectui/concept.mdx --no-inline-config) and could not complete: each attempt queued behind
  other agents' heavy jobs on the shared verify-lock and hit the 540s
  acquisition budget before reaching the front (queue-timeout, exit 99,
  NOT MEASURED — never ran, not a finding). Not one of the 39 derived
  commands; CI's required Lint & Repo Gates job runs full pnpm lint
  regardless.

Changeset

None — scripts/** + content/docs/** only, publishes nothing. skip-changeset
label applied and read back.

Out of scope

Nothing filed — the widened gate's full-corpus sweep came back clean apart
from the sites listed above, and no unrelated defect was hit along the way.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#13880

① The prior question, answered first (per triage)

The customizations: overlay-diff list this page's "Layer 2: Admin Customization"
example taught ({ field: ... } / { section: ... } entries meant to patch Layer
1's fields and add a section) is not a declared shape:

• git grep -n "customizations" -- packages/spec/src finds only package-API
  merge-strategy prose (api/package-api.zod.ts, kernel/package-upgrade.zod.ts,
  contracts/package-service.ts) and tenant.zod.ts's single authorable
  customizations key: z.record(z.string(), z.unknown()) — a free-form record,
  not an overlay-diff list.
• FormViewSchema is .strict(), so authoring this fence as a real form view
  would be refused by name (Unrecognized key(s) on this page: customizations).
• The three-layer merge engine the example narrates is the paper
  metadata-customization protocol retired in @objectstack/spec 17
  (Retire the paper metadata-customization protocol with its full coupling set — spec module, authorable customizationPolicies/mergeStrategy keys, metadata API §5, optional IMetadataService overlay methods, unreachable packages/metadata limb (re-charter of #12057) #13135, ADR-0049 enforce-or-remove — see
  packages/spec/src/kernel/metadata-customization-retirement.test.ts). Its
  customizationPolicies and mergeStrategy keys are tombstoned rather than
  deleted on MetadataPluginConfig — read by nothing, because no 3-way
  merge engine ever ran and package upgrades never merge customizations
  (ADR-0126 §6 wall 3: an upgrade rewrites the packaged BASE; a tenant's
  choices live separately and are never merged into it).

Per the ruling, the fence is rewritten, not given an anchor — same register
as the steps: wizard-template ghost layout-dsl.mdx already removed (PR
that landed as 63cf416e8, "layout-dsl teaches only shapes the live schemas
accept"). It is replaced with a <Callout type="warn"> that:

1. States the overlay-diff list is not declared and cites the retirement
   (#13135, ADR-0126 §6, FormViewSchema.strict()).
2. Names the real mechanism: a per-org overlay write on the view
   metadata type (allowOrgOverride: true on its
   DEFAULT_METADATA_TYPE_REGISTRY entry, ADR-0005) — the org's own
   FormView document, authored with the same shape Layer 1 and the earlier
   "Server Response" example already use, not a diff against the base.

The "Final Merged Layout" JSON fence right below it no longer shows a
"Billing Info" section or a // ← Admin override annotation on phone
(both were only produced by the removed fictional Layer 2) — it now shows
only what the two real layers (base schema + user preferences) actually
merge, and its one remaining section carries name: "contact_information".
The page's "Multi-Layer Resolution Engine" summary diagram got one matching
line-edit so it does not contradict the worked example directly below it
(- Custom sections: Added "Billing Info" section → - Org overlay: a full FormView write, not a diff) — plain ASCII, not a fence the gate parses.

The two new selectors (② the population question)

scripts/check-docs-section-name.mjs gains, per the triage ("population by
shape, not marker, not fence language"):

• Selector ③ — a singular YAML section: mapping (any nesting: a
  document-root key, or a sequence-item value like - section: {...}),
  judged exactly like a sections: sequence item. The YAML_SECTIONS_KEY
  prefilter widens from sections\s*: to sections?\s*:.
• Selector ④ — a sections: [...] array inside a json/jsonc/json5
  fence, bracket-matched with the same comment-masked matcher the TS arm
  uses (not JSON.parse — a teaching fence carries // ← comments and
  JSON5 trailing commas; concept.mdx's own merged-layout fence does both).

Both are shape-based: fence language and key cardinality vary, the judgment
(does the section-shaped mapping/literal carry name?) does not.

Census, mechanically reproduced

Before this PR's docs fix (widened gate on the unmodifiedconcept.mdx,
run once to make the card's "4, not 3" mechanical):

✗ check-docs-section-name: 4 form-section example(s) in content/docs/** have no `name`
content/docs/protocol/objectui/concept.mdx:307 (Server Response json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:426 (Layer 2 `- section:` yaml — "Billing Info")
content/docs/protocol/objectui/concept.mdx:443 (Final Merged Layout json — "Contact Information")
content/docs/protocol/objectui/concept.mdx:451 (Final Merged Layout json — "Billing Info")

Note the corpus-wide widened sweep surfaced a 5th site the issue itself did not
name: the same page's earlier "Server Response" example (:307, a real,
live-shape example unrelated to the retired-protocol fence) also had a
nameless "Contact Information" section. Fixed in this PR alongside the two
the issue named (listed below) — the widened gate's own directive is "fix
every new red it turns up in content/docs/**", not only the sites a card
happened to enumerate.

After (widened gate over the full corpus, clean):

✓ check-docs-section-name: 0 nameless form-section examples — 404 docs file(s) · 1180 TS-family fence(s) ·
14 `sections: [` array(s) · 22 section literal(s) JUDGED · 13 YAML fence(s) (13 parsed, 0 skipped) ·
22 YAML section mapping(s) JUDGED · 148 json/jsonc/json5 fence(s) · 3 `"sections": [` array(s) ·
2 JSON-family section literal(s) JUDGED

Sites fixed, all in content/docs/protocol/objectui/concept.mdx:

site	fence	fix
:307 ("Server Response")	json	added "name": "contact_information"
:419 (Layer 2 customizations:)	yaml	rewritten to a <Callout> — no anchor added, per ①
:443/:451 (Final Merged Layout)	json	dropped the Billing-Info section produced by the removed Layer 2; remaining section carries "name": "contact_information"

content/docs/ui/forms.mdx:183's "sections": [/* … */] elided placeholder
is judged as zero entries by the new arm (not skipped, not fabricated as
a nameless section) — no change needed there.
content/docs/protocol/objectui/layout-dsl.mdx's three singular section:
sites (from #13759) read ✓ named under the widened selector, as expected.
content/docs/ui/doc-pages.mdx:257 ("…from the previous section:", prose
outside any fence) does not enter the population — verified, no change.

No other content/docs/** page turned red under the widened gate; the corpus
sweep above is over the full 404-file tree.

Gates

• node scripts/check-docs-section-name.mjs --self-test → 85 cases pass
  (real temp trees on disk; both new selectors driven RED and GREEN, both
  cardinalities of the singular-section: mapping, the JSON elided-placeholder
  and comment/trailing-comma tolerance, every new refusal exercised).
• node scripts/check-docs-section-name.mjs → green on the merged tree (see
  census above).
• pnpm --filter @objectstack/spec run check:yaml-examples →
  concept.mdx: 0 tagged / 9 untagged (down from 0 tagged / 10 untagged —
  one fewer untagged YAML fence, since the customizations: fence is gone).
• Full derived gate list (node scripts/pm/dispatch-gates.mjs --commands,
  39 commands) run at 45312b3fb — all 39 green (three needed a one-time
  dependency-closure build first: @objectstack/spec,
  @objectstack/formula/@objectstack/lint, @objectstack/client-react —
  check:doc-formula-expressions/check:doc-security-posture/
  check:skill-examples each reported PREREQUISITE NOT MET, exit 3, before
  the build — not a finding). check:pm-dispatch-gates (node scripts/pm/check-dispatch-gates.mjs) run detached under heavy shared-lock
  contention (several sibling dispatch's PRs profiling/self-testing the same
  tool concurrently): command-exit 0, dispatch-gates self-test: 1240 cases pass.
• Re-derived the same 39-command list and re-ran check-docs-section-name.mjs
  • its --self-test at the final merge commit 38c73232d (after pulling
    main a second time, no conflicts, no overlap with this PR's two files) —
    still green; the other 38 were not re-run post-merge since none of the
    incoming commits touch scripts/check-docs-section-name.mjs or
    content/docs/protocol/objectui/** (verified via git log -- <paths>
    over the merged range).
• A pnpm lint-narrowed ESLint pass over just the two touched files was
  attempted three times (node_modules/eslint/bin/eslint.js scripts/check-docs-section-name.mjs content/docs/protocol/objectui/concept.mdx --no-inline-config) and could not complete: each attempt queued behind
  other agents' heavy jobs on the shared verify-lock and hit the 540s
  acquisition budget before reaching the front (queue-timeout, exit 99,
  NOT MEASURED — never ran, not a finding). Not one of the 39 derived
  commands; CI's required Lint & Repo Gates job runs full pnpm lint
  regardless.

Changeset

None — scripts/** + content/docs/** only, publishes nothing. skip-changeset
label applied and read back.

Out of scope

Nothing filed — the widened gate's full-corpus sweep came back clean apart
from the sites listed above, and no unrelated defect was hit along the way.

---

Generated by Claude Code

---

Generated by Claude Code