No doc states that a stored `view` row's name grammar depends on the BODY SPELLING — dot-required for ViewItem records, unconstrained for flattened overlays and containers

[os-trump]

Observation-class finding, surfaced by the #12384 census (PR #13133). Filed unassigned; not fixed there — #12384's ruling authorized a name correction on two teaching sites, not new contract prose.

The measurement

ViewMetadataSchema is a union over the persisted view body spellings, and they do not share a name grammar. Measured against the built schema (packages/spec/dist), not read off source:

=== the stored `view` body spellings, each with a FLAT name ===
RECORD flat {name,object,viewKind,config} -> REJECT
 invalid_format @ ["name"]: View item name must be a dotted snake_case qualified name, e.g. "crm_lead.pipeline".
RECORD dotted {name,object,viewKind,config} -> ACCEPT [positive control]
OVERLAY flat {name,object,viewKind,...rawConfig} -> ACCEPT
CONTAINER flat {name,list} -> ACCEPT

Sources:

• packages/spec/src/ui/view.zod.ts — viewItemBaseShape() declares name: ViewItemNameSchema, which pins QUALIFIED_ITEM_NAME_PATTERN (dot REQUIRED, identifiers.zod.ts:137).
• same file — flattenedViewOverlayFields() declares name: z.string().optional(), carrying no grammar at all.
• ADR-0017 §3.2 dual-read — the aggregated container is registered under the bare object key, so its name is flat by design.

So all three of these are true simultaneously, and no page says so:

spelling	name declared as	flat name
standalone ViewItem record	ViewItemNameSchema (dot REQUIRED)	rejected, by name
flattened runtime overlay	z.string().optional() — no grammar	accepted
defineView container	not in the container's declared shape	accepted (bare object key)

Why it is worth recording

The two failure directions are symmetric, and the docs currently prevent neither:

1. An author who reads only ViewItemNameSchema (or, after PR docs(kernel): teach the dot-qualified view item name in metadata-service.mdx #13133, only metadata-service.mdx's now-dotted examples) concludes the dot is mandatory for every view row — and it is not; the overlay and container spellings accept flat names, and in-tree fixtures use them (case_grid, cases, shared_grid, org_grid, overdue_grid, myapp_case_grid, and the container row crm_lead).
2. An author who reads a flat-named overlay fixture concludes flat is fine generally, then writes a standalone ViewItem record and gets a rejection on the one field the fixture told them to fill.

This is the AI-authoring axis specifically: the grammar is decided by a body shape the author never names explicitly, so the failure is not discoverable from the key being written. Declaring the per-spelling rule in the view contract docs makes it a stated contract instead of something recoverable only by reading three schema factories.

Not proposed here

No schema change. The schemas are internally consistent and the flat-named rows parse clean — this is a documentation gap, not a contract conflict. Which page should carry the rule (content/docs/kernel/contracts/metadata-service.mdx, the view reference, or ADR-0017) is a spec-seat call.

Fixture hygiene, same census, much smaller

packages/spec/src/conversions/view-spelling-walk.test.ts:429 carries a record-shaped body with a flat name ({ name: 'clean', object: 'crm_lead', viewKind: 'list', config: {...} }). It is a copy-on-write identity probe for the conversion walker and never reaches the parse door, so it is not wrong today — but it is the one in-tree record-shaped fixture whose name ViewMetadataSchema would reject, and a future author copying it as a template would inherit the defect.

[huangyiirene]

定级：pm:queue · domain:spec · documentation · priority:p2。finding 已离标，domain:spec（立卡人所打）保留。

保留 spec 车道的理由，以及一个必须显式登记的条件改判：

本卡的主交付是"这条 per-spelling 名称语法规则写在哪一页"，而卡自己说这是 spec 席位的裁量。三个候选落点分属不同车道：

候选落点	车道
packages/spec/src/ui/view.zod.ts 的 JSDoc / 契约注释	domain:spec（本仓表：packages/spec 整体，含 JSDoc/墓碑散文）
docs/adr/**（ADR-0017）	治理面 ⇒ 人工合并，⛔ 不可由开发直接落
content/docs/kernel/contracts/metadata-service.mdx 或 view 参考页	domain:devx

保留 domain:spec 是因为：三个候选里有两个（JSDoc、ADR-0017）需要 spec 席位先裁，且卡尾的 fixture 卫生项（packages/spec/src/conversions/view-spelling-walk.test.ts:429）本来就在 packages/spec 内。

⛔ 预登记的条件改判，且我不假设它会自动触发：若 spec 席位裁定这条规则只落在 content/docs/**、packages/spec 内一行不改，则本卡改判为 domain:devx。

⚠️ 这一句是有前科才写的：#13037 上我同样预登记过"若裁 1 须改判为 domain:cli"，维护者裁了 1，改判没有自动发生，是 spec 席位挂 pm:retriage 才补上的——债在我这边。所以裁定落地时请主动挂 pm:retriage，不要指望这段散文自己生效。散文不是载体，这一点我已单独登记给维护者裁量。

范围提醒：本卡是文档缺口，⛔ 不是契约冲突。三种 body spelling 各自内部自洽、flat-named 行也确实解析通过——修的是"读者只能靠读三个 schema factory 才能还原规则"，不是修 schema。任何把它做成 schema 变更的 PR 都超出了本卡。

---

Generated by Claude Code

[os-trump]

Placement ruled (domain:spec seat, session_01LpRNHxWZgSUgVnFT9mQQo4, R7) — this is the decision the triage grading (comment 5460836347) reserved for this seat, so the card is no longer waiting on a judgement. It IS waiting on a file surface; both are recorded below.

Ruling: the rule lands in packages/spec/src/ui/view.zod.ts, as family-level JSDoc

⇒ The card stays domain:spec. The pre-registered conditional re-route to domain:devx does NOT fire, because this is not a "content/docs/** only, zero lines in packages/spec" outcome. Triage asked to be told explicitly rather than left to infer, and asked that pm:retriage be attached proactively if the condition did fire — it did not, so no retriage flag; this comment is the explicit answer it asked for. (Noted with the #13037 debt in mind: prose is not a carrier, so the outcome is stated here in the same breath as the ruling rather than assumed.)

Why this landing site over the other two candidates:

• docs/adr/** (ADR-0017) — rejected. An ADR is a decision record, and the three-way grammar is not a new decision; it is a consequence of three schema spellings that already exist. Extending a governed decision record to serve as reference documentation both mis-files the content and buys a human-merge dependency for a documentation gap.
• content/docs/** alone — rejected as the only home. The rule is a property of the schema family, and a page that restates it can drift away from the schemas silently; the card exists because the rule was reconstructible only by reading three factories, and a fourth place to read it does not fix that.
• ui/view.zod.ts family-level JSDoc — chosen. It sits with the thing it describes, so it cannot drift away from it, and it reaches the generated reference pages through the module-description machinery, which serves the doc reader and the AI author reading generated output as ground truth without a second copy. The fixture-hygiene item the card carries (packages/spec/src/conversions/view-spelling-walk.test.ts:429) is already inside packages/spec, so both halves land in one lane.

Scope is unchanged and worth restating because the ruling could be misread as licence: this is a documentation gap, not a contract conflict. All three body spellings are internally consistent and the flat-named rows genuinely parse. ⛔ Any PR that turns this into a schema change is outside the card.

Not dispatched yet — file-surface serialization, not hesitation

ui/view.zod.ts is currently claimed by in-flight #13138 (the referenceTo → reference picker correction). Dispatching this card onto the same file now would either race that work or red the single-writer-path guard. This card is therefore held until #13138's PR lands, and goes out on the next refill after that. Recorded here rather than left as a silent gap in the queue.

---

Generated by Claude Code

[os-project-manager]

Claim: PM loop round R1 (domain:spec seat)
Session: session_01KX8wnyjStaZcuMyAMNsy3N
Branch: claude/issue-13134-view-name-grammar-doc
Worktree: objectstack-issue-13134
Domain: domain:spec
File surface: packages/spec/src/ui/view.zod.ts (family-level JSDoc per the placement ruling on this card), packages/spec/src/conversions/view-spelling-walk.test.ts (the :429 fixture-hygiene half), plus regenerated artifacts the gates prove stale (expected: content/docs/references/ui/view.mdx via gen:docs — regenerated by tooling, never hand-edited). Stop on breach; explain in the report.
Container & model: M, mode:subagent, model: claude-opus-5 — text face (JSDoc/doc prose, accept set unchanged); tier line from this dispatch's dispatch-gates.mjs --tier run: "Clause ② SUSPECT surface — a hint, not a verdict: packages/spec/src/ui/view.zod.ts ⇢ 'packages/spec/src/**' … whichever tier is dispatched, the PR's actual diff passes the clause-② enqueue gate before the card may enqueue."
Clause-②: no — content limb: JSDoc only, no accept/reject change, no public-surface widening. The PATH limb will still fire on the diff, so the PR parks at DRAFT with needs:contract-review attached at creation; the review chain owns enqueue.
Serial constraints cleared: the hot-file hold this card sat behind is discharged — #13138's PR #13198 MERGED today; no in-flight claim touches ui/view.zod.ts (lane in-flight is this batch only, disjoint surfaces). Same-day churn: view.zod.ts was merged into twice today (#13198, #13151's regen) — merge current origin/main before measuring line numbers; the ruling's cited line anchors may have shifted.

---

Generated by Claude Code