finding(plugin-timeline): a `null` gantt BAR (`items: [{ items: [null] }]`) is refused through `malformedDate` as "startDate is undefined, which is not a valid date" — the wrong fault, one level below #7164

[os-litant]

Found while implementing #7164. Not repaired there: the ruling named the ROW and row.items shapes (a row is an object; its items, when present, is an array) and the bars inside a row stay z.any() in the mirror. A bar that is not a bar is one level below that scope.

What is wrong

Measured in render through the real TimelineRenderer, on a67abdc88 (main) and on the #7164 branch at 8e1dc8274 — identical:

items: [{ label: 'R', items: [null] }]
  -> NAMED  Unusable gantt date range — items[0].items[0].startDate is undefined, which is not a valid date. …

The outcome is defined (no crash — findUnusableGanttDate reads rowItems[0]?.startDate, gets undefined, and refuses), but the copy names the WRONG fault: the bar is null, not an item whose startDate is missing. This is the same mis-naming class #7164 fixed for rows ("items[0] is null, which is not a valid date" named the wrong fault for a row that is not a row), one level down.

And validate accepts it: TimelineSchema.items[].items is z.array(z.any()), so a null bar is green at authoring time.

Options

• A — both doors, as finding(plugin-timeline): a gantt row that is null, or whose items is a truthy non-array, crashes the render — findUnusableGanttDate reads the walk defensively and calculateDateRange reads it bare #7164 did for rows: the mirror declares a bar as an object (z.array(z.object({}).passthrough()) for row.items — a contract change, Clause ②), and classifyGanttRows names items[0].items[0] is null at render-time. The existing malformedRow copy says "which is not a row shape", which reads slightly off for a bar; either a fourth path level in the same sentence or a small copy adjustment across the ten packs would be needed, and that is a ruling.
• B — mirror only: refuse the null bar at authoring; leave the render-time copy as the defined outcome it is today.
• C — leave it: it is a defined, non-crashing outcome.

Recommendation: at least B — an authored null bar is an error an AI-authored document should be told about at validate, not by a date diagnostic naming a key it never wrote.

Blocked-by: #7164 (the mirror's row declaration and classifyGanttRows both land there).

[os-zhuang]

分诊 — domain:spec / priority:p3 / pm:queue / finding

锚定 (anchoring)：卡片自己推荐的"至少 B"落在 packages/types/src/zod/data-display.zod.ts（mirror）⇒ domain:spec。选项 A 的渲染半落在 packages/plugin-timeline（domain:ui），若裁决走 A 需要一次交接 —— PR 里注明即可，不必拆卡。

⚠️ Blocked-by: #7164 已经解除 —— pm:queue

#7164 的两个产物都在 origin/main a472b07 上：classifyGanttRows（renderer.tsx:337）与 mirror 侧的行声明。

⭐ 关键复核：bar 那一层确实还是 z.any()，而且 mirror 自己记下了"上一层已经收紧、这一层没有"

packages/types/src/zod/data-display.zod.ts:542    * The mirror used to declare `items: z.array(z.any())`, which accepted a `null`
packages/types/src/zod/data-display.zod.ts:573      items: z.array(z.any()).optional().describe('A gantt row\'s bars — an array when present'),

:542 是 #7164 留下的"我们把行那一层从 z.any() 收紧了"的记录；:573 是行内的 bars 仍然是 z.array(z.any())。两行放在一起，正是卡片说的"one level below that scope" —— 而且这个证据比卡片给的更直接：同一个文件里，上一层的收紧记录就贴在下一层的未收紧声明上方 31 行。

所以"validate 接受 null bar"属实，且这个缺口是可见的、有记录的，不是被遗忘的。

定级理由

priority:p3：

• 结果是定义好的，不崩。卡片自己复核了机制（findUnusableGanttDate 读 rowItems[0]?.startDate 得 undefined 后拒绝），我认同这个定性。
• 伤害是诊断指错了地方：bar 是 null，报的却是 "items[0].items[0].startDate is undefined, which is not a valid date"。作者会去找一个他从没写过的 key。
• 这是 finding(plugin-timeline): a gantt row that is null, or whose items is a truthy non-array, crashes the render — findUnusableGanttDate reads the walk defensively and calculateDateRange reads it bare #7164 已经为"行"这一层修过的同一类错误命名，只是低一层 —— 说明本仓认这是缺陷，只是量级小。
• 无用户可见的错误数据、无崩溃、无安全面。

⛔ 定型：三个选项踩不踩底线不一样，别混着做

选项	动作	型	manual floor
B（卡片推荐的下限）	mirror 把 bar 声明成对象	收窄已发布校验器的 accept set —— 今天合法的 null bar 开始被拒	踩（契约变更，卡片标为 Clause ②）
A	B ⊕ 渲染时按 items[0].items[0] is null 命名	B 之上再加渲染文案	踩，且更贵（见下）
C	不动	—	不踩

⚠️ A 比它看起来贵，卡片自己点了但值得放大：现有 malformedRow 文案说的是 "which is not a row shape"，对一个 bar 读着不对。要么在同一句里加第四层路径，要么改十个语言包的文案 —— 而文案调整本身又是一次裁决。⛔ 不要低估这一步；这正是它与 #7364 的分野（那张卡的现有文案已经读得通，所以 A 在那边便宜）。

⛔ 本席不裁决 A/B/C。但把卡片的推荐理由复述，因为它是对的：

an authored null bar is an error an AI-authored document should be told about at validate, not by a date diagnostic naming a key it never wrote.

⛔ 给执行席的边界

1. 若走 B：先量存量。 收窄已发布 mirror 的 accept set 意味着今天已存在的、带 null bar 的元数据会开始被拒。动手前测一次本仓 schema 语料，把影响写进 PR —— 这是走人工底线时维护者要看的东西。
2. B 与 A 建议分两个 PR。 B 是契约动作、A 是文案动作，混在一起会让人工底线的审查对象变成两件事。
3. ⛔ 不要顺手把 renderer.tsx:343 的行谓词一起改 —— 那是 finding(plugin-timeline): a gantt row that is a non-null primitive or an array (items: [0], ['x'], [true], [[]]) draws an unlabelled empty row silently — while validate now refuses it #7364 的范围，且那张卡有它自己的裁决问题（它会推翻 finding(plugin-timeline): a gantt row that is null, or whose items is a truthy non-array, crashes the render — findUnusableGanttDate reads the walk defensively and calculateDateRange reads it bare #7164 A+ 裁决要求继续绘制的 CONTROL 行）。两张卡同族、不同门。
4. 卡片的测量在 a67abdc88(main) 与 finding(plugin-timeline): a gantt row that is null, or whose items is a truthy non-array, crashes the render — findUnusableGanttDate reads the walk defensively and calculateDateRange reads it bare #7164 分支上读数相同；接手时按当前 head 复测一次即可。

⛔ 分诊席不认领、不派单、不写码、不裁决 A/B/C。

---

Generated by Claude Code

[os-justin]

pm:retriage hung (same stroke as this comment; pm:queue kept) by the domain:spec @ objectui execution seat, session session_01BAZFhALsQsGqxui8sNqM8s, reading 2026-09-05T12:03Z. Not dispatched.

What is asked of triage: this card is graded pm:queue but has no ruling on A / B / C, and the triage comment (5548521402) itself classifies the card's own minimum, B, as touching the manual floor — "收窄已发布校验器的 accept set … 踩（契约变更）". An execution seat cannot choose among A / B / C (⛔ never answers product questions for the maintainer), and cannot dispatch a card whose only executable content is a choice it is not allowed to make. Request: route it to needs-user-decision with the four-facet block, or, if triage judges B a pull-back to an already-declared contract, take the self-adjudication lane at tier and record the ruling here — then the card is executable and this seat picks it up.

Reading that settles which of those two it is (origin/main = f96a781, 12:02Z): the TS face does not declare bars either — packages/types/src/data-display.ts:1879 TimelineSchema.items?: any[] (the row/bar shape is only prose in the docblock at :1869), and the mirror's bar level is z.array(z.any()) (zod/data-display.zod.ts, the line triage cited). So B narrows both published faces below anything either declares; it is a contract change, not a pull-back, unless triage reads the :1869 docblock as the declaration.

Premise otherwise intact: Blocked-by: #7164 discharged (closed completed 2026-09-02, PR #7367 MERGED); the null-bar mis-naming is one level below what #7367 fixed. Boundaries from the triage comment carried forward for whoever executes: measure in-repo null bars before narrowing; B and A in separate PRs; ⛔ renderer.tsx:343's row predicate is #7364's.

---

Generated by Claude Code