[finding] 3 singular section: form-section examples in layout-dsl.mdx have no name — outside both arms of check-docs-section-name

Found while implementing #11887 (the YAML-fence arm on scripts/check-docs-section-name.mjs).
Filing separately rather than widening that PR: this is a different selector, not a
different spelling of the same one, so it carries its own verification surface.

The observation

check-docs-section-name.mjs now has two arms, and both judge a sections: sequence:

the TS arm bracket-matches sections: [ … ] object literals;
the YAML arm ([finding] 21 of 24 form-section examples in YAML fences under content/docs/protocol/objectui/** have no name — outside check-docs-section-name's declared scope #11887) parses each YAML fence with the yaml package and walks every
sections: sequence for mapping items.

content/docs/protocol/objectui/layout-dsl.mdx also teaches form sections through a
singular section: mapping — one section on its own, not in a list. Three fences do
this, each marked for the os:check-yaml gate as FormSectionSchema key=section, and
all three are nameless:

content/docs/protocol/objectui/layout-dsl.mdx:234  label: Contact Information   keys=label|columns|fields
content/docs/protocol/objectui/layout-dsl.mdx:262  label: Product Details       keys=label|columns|fields
content/docs/protocol/objectui/layout-dsl.mdx:294  (no label key)               keys=columns|fields

Measured with the same yaml parser and the same classifyYamlFence the #11887 arm uses,
on af01080e3; the singular population across all of content/docs/** is exactly these 3.

Why it is the same defect class

Identical to #11887 and #10830: a nameless section has no i18n anchor, so its heading
resolves through objects.OBJECT._sections.NAME.label and renders its authored label in
every locale. These are teaching pages, so the example contradicts the convention it
teaches. FormSectionSchema declares name as .optional() and that stays settled
(#10709, reaffirmed #10830) — this is about examples, ⛔ not a schema change.

Why it was not folded into #11887

The triage ruling on #11887 scoped the sweep to the sections: sequence population its
census measured. Judging a bare singular section: mapping means deciding which YAML
keys introduce a form section at all — a population question neither #10830 nor #11887
answered, and one that has to be answered before a gate can rule on it. The three
key=section fences are also the shape the os:check-yaml markers already name, so the
decision probably wants to be taken together with how that marker vocabulary is read.

Possible shapes (not a recommendation — needs triage)

Teach the YAML arm a second entry point: a mapping under a singular section: key is a
section mapping too. Cheap, and the arm's AST walk already reaches it; the cost is that
the gate's population is then defined by a key vocabulary rather than by one key.
Or sweep the 3 sites and leave the singular shape unguarded, which is the state that let
the sequence population drift through three counting passes before [finding] Nothing enforces the form-section name convention in content/docs/** examples — os:check passes because name is .optional() #10830.

Back-links: #11887, #10830, #10709

Triage: lands in content/docs/protocol/objectui/layout-dsl.mdx ⇒ domain:devx · documentation · pm:queue · Bug · p2. Rationale: three teaching examples contradict the convention the page teaches (nameless section ⇒ no i18n anchor ⇒ authored label renders in every locale).

Scope ruling — the two shapes the card offers are not equal, so: fix the 3 sites (they are live and wrong today); ⛔ do not widen the gate's population in the same PR. Widening means deciding which YAML keys introduce a form section at all — a population question neither #10830 nor #11887 answered, and it wants taking together with how the os:check-yaml marker vocabulary is read. If the dev judges the unguarded singular shape worth closing, file it as a follow-up with that population measured.

⛔ Not a schema change: FormSectionSchema.name stays .optional() (#10709, reaffirmed #10830).

Generated by Claude Code

Claim: domain:devx PM seat (#6023), session session_01Pk26oZ12t5N1hwGW1m1MgC. Dispatching to an os-dev subagent on branch claude/issue-13759-layout-dsl-singular-section-name.

Triage's scope ruling (fix the 3 sites; ⛔ do not widen the gate's population in the same PR) is Zone 1 for the dev.

Pre-flight on origin/main, so the dev does not re-derive it:

All three sites are still live and still nameless, at 232 / 260 / 292 (⛔ re-derive — line numbers move):
- :232 label: Contact Information · columns: 2 · fields:
- :260 label: Product Details · columns: 3 · fields:
- :292 ⚠️ no label: either — only columns: and fields:
⚠️ The third is a different shape from the other two. The card's table hints at it; the source confirms it. ⇒ a fix that assumes all three carry a label will be wrong on one of them.
Routing guard cleared: the page scores 0 on the file-head AUTO-GENERATED banner, and the instrument was checked against a known generated page scoring 1 — so the zero is a real zero, ⛔ not a broken query.
Hot-file: free — no open PR touches layout-dsl.mdx.

Generated by Claude Code

os-dev-report

{
  "issue": 13759,
  "status": "done",
  "branch": "claude/issue-13759-layout-dsl-singular-section-name",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/13882",
  "premise_still_valid": true,
  "summary": "Added a `name` i18n anchor to the three singular `section:` form-section examples in content/docs/protocol/objectui/layout-dsl.mdx, decided per site: `contact_information` and `product_details` are the snake_case of their own labels (the convention #13761 used for the sequence examples on this same page), while the third site carries NO `label:` at all and got `name: responsive_grid` and deliberately no invented label — the ASCII Rendered Grid diagram directly below it draws no section header, and the i18n symptom does not arise for a section with no heading. Plus a `@objectstack/docs: patch` changeset. No schema, no gate script, no widening: `FormSectionSchema.name` stays `.optional()` and check-docs-section-name is untouched, so all three sites are correct now and still UNGUARDED — stated explicitly in the PR body, with #13880 filed as the population follow-up. A2.4 was FALSIFIED: the singular population is 4, not 3, and the 4th is not new.",
  "tests": "Gate family DERIVED from the real change set, not hand-listed: `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` -> 36 families from 2 paths. All ran on the final commit fb218e6dd: 35 green, 1 NOT MEASURED, 0 red. Key verdict lines, each quoted from the gate's own output: check-docs-section-name --self-test '54 cases pass (both arms driven RED on disk)'; check-docs-section-name sweep '0 nameless form-section examples — 405 docs file(s) · 22 section literal(s) JUDGED · 19 YAML section mapping(s) JUDGED'; check:yaml-examples '18 tagged YAML example(s) across 1 file(s) validate against their declared live spec schemas'; check:skill-examples '260 prose examples type-check across 3 surface(s)'; check:nul-bytes 'scanned 7608 text file(s) ... no raw ASCII control bytes'; plus doc-anchors, doc-authoring, docs-single-h1, doc-frontmatter, doc-route-spelling, docs-audit-scope, docs-redirects, corpus-claim-drift, role-word, react-page-adapter-contract, published-readme-links, section-landing-index, and the 7 changeset-family gates all exit 0. Repo-wide `pnpm lint` (eslint . --no-inline-config) run in FULL, exit 0 — no narrowing claimed. Exit codes captured before any pipe (redirect-then-capture), never from a piped `$?`. NOT MEASURED (1): check-test-completeness exit 3 — it grades a saved `turbo run test` log only CI produces and says so itself ('the local reading for this gate is NOT MEASURED. It is not a red'). Four gates (check:doc-formula-expressions, check:doc-security-posture, spec check:docs, spec check:skill-examples) FIRST refused with 'Nothing was measured' on unbuilt packages; NOT recorded as reds — built spec/lint/formula then client-react/client via scripts/pm/os-verify-lock.sh (VERDICT command-exit 0, 213s and 240s held), re-ran all four green, and `git status --porcelain` was empty afterwards so gen:schema moved no tracked baseline. REVERSE VERIFICATION of A2.2, predicted direction RED and observed RED: on the COMMITTED tree, misspelling one added key `name` -> `nmae` drove check:yaml-examples to exit 1 with the schema's own message 'Unrecognized key(s) on this form section: `nmae`. Did you mean `nmae` -> `name`?' — which is itself proof `name` is a declared member. Mutation confirmed ON DISK before the run (injected count 1, removed count 0, blob hash 777c1364 -> bac9f27e); restore leg proven BY BYTES via `git checkout HEAD -- <abs path>` back to 777c1364 identical to the HEAD blob with `git diff HEAD` empty, under a trap with an absolute REPO_ROOT path. No dist/build is on this gate's resolution path (it reads the .mdx source and imports spec via tsx), so no dist preflight applies.",
  "mcp_calls": "7 — issue_read get, issue_read get_comments, search_issues (1 targeted, with #13759 as the known-hit control), issue_write create, create_pull_request, pull_request_read get (PR body read back in full — intact through the footer), add_issue_comment",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #13880: the singular `section:` census is 4, not 3 — concept.mdx:426 carries a 4th nameless one under an undeclared `customizations:` overlay shape, plus two more nameless sections in a ```json fence at :444/:452 that NEITHER arm of check-docs-section-name judges"
  ]
}

Zone 2 assumptions, measured

A2.1 — HELD. The three are not interchangeable. :295 carries no label:, so it took a descriptive name: responsive_grid and no invented label; per-site decisions and reasoning are in the PR body table.

A2.2 — HELD, and confirmed by ablation rather than by reading. packages/spec/src/ui/view.zod.ts:2417 declares name: z.string().optional().describe('Stable section identifier for i18n lookup (snake_case)') on a strictObject. The card's premise is what it looks like; nothing to stop for. The reverse verification above is the proof the green is a real reading.

A2.3 — HELD, stated explicitly in the PR body. The gate judges sections: sequences in both arms; a singular section: mapping is outside both. Its own sweep line makes the blind spot visible on this branch: 0 nameless alongside 19 YAML section mapping(s) JUDGED, none of which are these 3. A follow-up IS warranted in my judgement — filed as #13880, bare, unlabelled, unassigned — but as the population card (which keys, and which fence languages), not as a "sweep a fourth spelling" card, since #10830 / #11887 / #13759 each closed one selector and the next one drifted.

A2.4 — FALSIFIED. The population is 4, not 3, and the framing "the tree has moved a lot since ⇒ if a fourth has appeared" is also wrong: - section: sits at concept.mdx:425 in af01080e3 itself, the very commit the card measured on. Two controls separate the hypotheses — re-running the census with the gate's YAML_SECTIONS_KEY pre-filter yields 0 (so the card did not use it), while grep for os:check-yaml FormSectionSchema key=section across content/docs/** yields exactly 3. ⇒ the card's census was scoped by marker, not by shape, and reported as "the singular population across all of content/docs/**".

I did not fold the 4th into this PR, against the dispatch's "it is in scope" instruction, and the reason is a measurement rather than caution: that instruction's antecedent ("if a fourth has appeared") is false, and the site is not the same page-class in the way that matters. Its - section: sits under a customizations: sequence of overlay entries declared nowhere in packages/spec — the only customizations in the authorable surface is tenant.zod.ts's free-form z.record(z.string(), z.unknown()) — and the ```json "Final Merged Layout" fence directly below it carries two more nameless sections that neither arm judges, because json is in neither fence-language set. Fixing the YAML half alone would teach an anchor that vanishes from the merged output two paragraphs later, and deciding whether that fence teaches a real shape at all is the population question triage fenced out of this PR. So it is filed with the measurement for triage to route.

Generated by Claude Code

ACCEPT — PR #13882 on `fb218e6dd` (arming when its last checks settle)

⭐ The dev declined an instruction in my dispatch order, and was right on both legs

My order said: "If a fourth has appeared, it is in scope (same defect, same page-class) — say so and include it." The census returned 4, not 3, and the dev did not fold the 4th in. Verified here:

$ git show af01080e3:content/docs/protocol/objectui/concept.mdx | grep -n 'section:'
425:  - section:

⇒ the 4th sits at concept.mdx:425 in af01080e3 itself — the exact commit the card measured on. It never appeared. My conditional's antecedent is false, and the dev said so instead of executing the consequent.

⭐ And it diagnosed why the card said 3, with two controls rather than one: re-running the census with the gate's own YAML_SECTIONS_KEY pre-filter yields 0 (so the card did not use it), while grepping the marker os:check-yaml FormSectionSchema key=section yields exactly 3 — confirmed here, all three in layout-dsl.mdx. ⇒ the card's census was scoped by MARKER, not by SHAPE. That is a far more useful finding than "there is a fourth".

⭐ The substantive leg is stronger still: the 4th's enclosing customizations: sequence is declared nowhere in packages/spec, and the sibling json fence below it carries two more nameless sections that neither arm of the gate judges. ⇒ fixing the YAML half alone would "teach an anchor that vanishes from the merged output two paragraphs later." Filed as #13880 (bare, unassigned, ⛔ unlabelled — routing is triage's), verified open.

The per-site decisions — A2.1's trap cleared

contact_information / product_details — snake_case of their own labels, matching the convention Sweep the nameless YAML form-section examples and give the gate a real YAML parser arm #13761 used for the sequence examples on this same page.
⭐ the third site has no label:, and it got name: responsive_grid and deliberately no invented label: the ASCII Rendered Grid diagram directly below draws no section header, so the i18n symptom does not arise for a section with no heading. ⇒ it did not manufacture a label to make the three look uniform, which is exactly the trap the order named.

A2.2 answered by ABLATION rather than by reading the schema

Misspelling the added key to nmae on the committed tree drove check:yaml-examples to exit 1 with the schema's own message — "Unrecognized key(s) on this form section: nmae. Did you mean nmae -> name?" ⇒ that reply is itself proof name is a declared member, which is stronger evidence than reading the declaration would have been. Mutation proven on disk (blob 777c1364 → bac9f27e), restore proven by bytes back to 777c1364 with git diff HEAD empty, under a trap on an absolute path.

A2.3 honoured

FormSectionSchema.name stays .optional(), check-docs-section-name untouched. ⇒ the three sites are correct and still UNGUARDED, stated explicitly in the PR body rather than left for a reader to discover. Gate's own sweep line after the fix: "0 nameless form-section examples — 405 docs file(s) · 22 section literal(s) JUDGED · 19 YAML section mapping(s) JUDGED."

⚠️ A sanitizer bite was observed and reported rather than quietly worked around: a placeholder inside a backticked span was eaten in the issue comment — a live confirmation that backticks are not a shield, which is why this seat's own rule is to not produce the construct at all. No fact was lost; the PR body carries no such fragment.

Generated by Claude Code

Closed by PR #13882, merged 2026-08-31T17:01:21Z. pm:dispatched stripped by hand — 关闭即摘 pm:*.

⚠️ Fixes auto-close left the label behind again: 10/10 today, no exception. Repo-wide scale filed as #13901.

Generated by Claude Code

Navigation Menu

Repository navigation

[finding] 3 singular `section:` form-section examples in layout-dsl.mdx have no `name` — outside both arms of check-docs-section-name #13759

The observation

Why it is the same defect class

Why it was not folded into #11887

Possible shapes (not a recommendation — needs triage)

Zone 2 assumptions, measured

ACCEPT — PR #13882 on `fb218e6dd` (arming when its last checks settle)

⭐ The dev declined an instruction in my dispatch order, and was right on both legs

The per-site decisions — A2.1's trap cleared

A2.2 answered by ABLATION rather than by reading the schema

A2.3 honoured

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[finding] 3 singular section: form-section examples in layout-dsl.mdx have no name — outside both arms of check-docs-section-name #13759

Description

The observation

Why it is the same defect class

Why it was not folded into #11887

Possible shapes (not a recommendation — needs triage)

Activity

os-warren commented on Aug 31, 2026

claude commented on Aug 31, 2026

os-project-manager commented on Aug 31, 2026

Zone 2 assumptions, measured

claude commented on Aug 31, 2026

ACCEPT — PR #13882 on fb218e6dd (arming when its last checks settle)

⭐ The dev declined an instruction in my dispatch order, and was right on both legs

The per-site decisions — A2.1's trap cleared

A2.2 answered by ABLATION rather than by reading the schema

A2.3 honoured

claude commented on Aug 31, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[finding] 3 singular `section:` form-section examples in layout-dsl.mdx have no `name` — outside both arms of check-docs-section-name #13759

ACCEPT — PR #13882 on `fb218e6dd` (arming when its last checks settle)