docs(spec): kanban.lanes TSDoc states what the board draws; checkKanbanLanes docblock names its option map (#28343)

<!-- claude-projects-attribution: {"github_login":"os-tesla"} -->
_Requested by **Tesla** · [project
thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6Jao1SJdy8FRAJZyYtYYDAwKHH)_

Fixes #28319

Clause-②: no
Metadata-protocol: none

## 维护者速读

- 改了什么:`kanban.lanes` 的 TSDoc
去掉「看板暂不读这个键」那段过时说明,改成如实描述:只画列出的泳道、按作者写的顺序,未列出的值落进
`Uncategorized`,不写该键则每个选项一条泳道;lint 的 `checkKanbanLanes` 注释补一句:将来若扩展
`groupByField` 可带的内联选项,必须并入它读的选项表。
- 为什么改:#28291 合入后看板已经按 `kanban.lanes` 画泳道,旧说明会让读参考文档的作者(包括
AI)以为这个键没用而不去用它;写错一句给 AI 看的文档等于产品缺陷。
- 风险与回滚:只改注释文字,不改 schema、不改行为;生成产物无变化(`check:generated` 全绿)。回滚即 revert 本
PR。
- 先看:`packages/spec/src/ui/view.zod.ts` 中 `lanes` 的 TSDoc
末段;`packages/lint/src/validate-list-view-field-refs.ts` 中
`checkKanbanLanes` 的注释;`.changeset/28319-kanban-lanes-tsdoc.md`。
- 两分钟验证:`git grep -n "Lands ahead of its reader: the board draws one
lane" origin/main -- packages/spec` 在 main 上有一处命中,本分支零命中。
- 需要你做的:无,席位落地(TSDoc 属于 spec 源码,先走契约复审)。

## What changes

- `packages/spec/src/ui/view.zod.ts`: the last paragraph of the
`KanbanConfigSchema.lanes` TSDoc said the board drew one lane per option
until the Console read the key. It now says what the board draws: the
listed lanes and no others, in the order the author wrote them; a record
whose value is not listed lands in `Uncategorized`; without the key, one
lane per option in the options' own order. The `.describe()` text was
checked and already says this (no "ahead of its reader" clause), so it
is unchanged.
- `packages/lint/src/validate-list-view-field-refs.ts`: the
`checkKanbanLanes` docblock gains the line review rider S2 asked for:
the rule reads only the option map built from inline `options[].value`,
and a future `FieldSchema` key that widens the inline options a
`groupByField` may carry must join that map, or a lane naming a widened
option is reported as unknown.
- `.changeset/28319-kanban-lanes-tsdoc.md`: a `patch` for
`@objectstack/spec`, because the TSDoc ships in the package (`dist`
chunks and `src/**/*.zod.ts` are in its `files`). `@objectstack/lint`
gets no changeset entry: its built `dist` carries none of the edited
docblock (measured below).

No schema, type, export or behaviour change.

## Why

Since #28291 the board draws only the declared `kanban.lanes`, in order.
The TSDoc still told authors, and agents reading the spec source, that
the board ignores the key, so an author would not use a live key.

## Tests

- `pnpm --filter @objectstack/lint exec vitest run --maxWorkers=2
validate-list-view-field-refs.test.ts`: Test Files 1 passed, Tests 171
passed.
- `pnpm --filter @objectstack/spec run typecheck` and `pnpm --filter
@objectstack/lint run typecheck`: exit 0.

## Verification

Local gates at head `fb157ea7` (the last commit; nothing pushed after).

<details><summary>Derived gate families: 74 derived, 73 run green, 1 NOT
MEASURED</summary>

- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 74 commands against the diff (2
source files + the changeset). Each ran with stdin closed and its exit
code recorded before any pipe.
- `dispatch-gates.mjs --repo objectstack-ai/objectstack --ran`
reconciles: "74 derived famil(ies) accounted for — 73 run, 1
NOT-MEASURED".
- NOT MEASURED: `pnpm check:dual-build-cjs-loads` exits 3 (prerequisite:
it needs every package's `dist`, a whole-workspace build; this diff
changes comments only). CI runs it.
- First attempts that exited 3 and were re-run green after their
prerequisite was met: `check-plugin-teardown-shape.mjs --self-test`
(after fetching its pinned fixture commit) and `pnpm
check:lean-entry-closure` (after building `@objectstack/objectql`).
- Doc-authoring gates named by the order: `pnpm check:doc-authoring`,
`pnpm check:issue-citations`, `node scripts/check-issue-citations.mjs`,
`pnpm check:spec-docblock-symbol-anchors`: all exit 0.

</details>

<details><summary>Generated artefacts and the order's per-card
gates</summary>

- `pnpm --filter @objectstack/spec build` then `pnpm --filter
@objectstack/spec check:generated`: exit 0, every artefact up to date
(including `check:docs` over `content/docs/references/**` and
`check:authorable-surface` over the JSON schemas). The TSDoc does not
reach a generated reference, so nothing was regenerated.
- `git grep` for the old sentence across the tree (including
`content/docs`) found it only in `view.zod.ts`.
- `node scripts/check-sdui-manifest.mjs`: exit 0.

</details>

<details><summary>Changeset measurement (which package ships the edited
text)</summary>

- After `pnpm --filter @objectstack/spec build`, the new TSDoc sentence
is in `packages/spec/dist/chunk-*.mjs` and `chunk-*.js`, and the old one
is in no `dist` file; `src/**/*.zod.ts` also ships. So
`@objectstack/spec` publishes it: `patch`.
- After building `@objectstack/lint`, neither the new docblock line nor
the neighbouring existing docblock sentence is in `packages/lint/dist`,
while a message string from the same function is (positive control: `is
not an option of` in `dist/runtime.js` and `dist/index.cjs`). So lint
publishes nothing new.

</details>

## Acceptance notes

- The order also asked to check `.describe()` for the stale clause: it
never carried one, so it is unchanged.
- Rider S2 asked for "a note on the module docblock"; the card and the
order place it on the `checkKanbanLanes` docblock, which is where it
went. The module's `kanban.lanes` section is unchanged.
- A contract review is owed (the TSDoc is spec source); the seat routes
it.

## Human Minimum

- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm exec eslint --no-inline-config` over
the two edited files exits 0 (the repo-wide `pnpm lint` is CI's).
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed.
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English.
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01L9qibxLWeJZCXoRVU2rMLD)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/28319-kanban-lanes-tsdoc.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the `kanban.lanes` TSDoc states what the board draws
+
+Clause-②: no
+Metadata-protocol: none
+
+The `KanbanConfigSchema.lanes` TSDoc still said the board drew one lane per option until the Console read the key. The Console reads it now, so the paragraph says what is drawn: the listed lanes and no others, in the order the author wrote them; a record whose value is not listed lands in `Uncategorized`; without the key, one lane per option in the options' own order. The `.describe()` text already said this and is unchanged. No schema or behaviour change.

packages/lint/src/validate-list-view-field-refs.ts

@@ -1083,6 +1083,11 @@ export function validateListViewFieldRefs(
    * [#28018] `kanban.lanes`, judged once a list view's bound object resolves:
    * every entry must be an inline option of `groupByField`. See the section of
    * that name on this module.
+   *
+   * It reads only the option map above, built from inline `options[].value`.
+   * A future `FieldSchema` key that widens the inline options a `groupByField`
+   * may carry must join that map, or a lane naming a widened option is
+   * reported as unknown.
    */
   const checkKanbanLanes = (listView: AnyRec, object: string, where: string, path: string): void => {
     const kanban = listView.kanban;

packages/spec/src/ui/view.zod.ts

@@ -2094,8 +2094,10 @@ export const KanbanConfigSchema = lazySchema(() => strictObject({
    * ⛔ No spec-side default: absence keeps every board stored before this key
    * exactly as it was, one lane per option.
    *
-   * Lands ahead of its reader: the board draws one lane per option until the
-   * console half reads this key where it builds its lanes.
+   * What the board draws: the listed lanes and no others, in the order the
+   * author wrote them; a record whose value is not listed lands in
+   * `Uncategorized`. Without the key it draws one lane per option, in the
+   * options' own order.
    */
   lanes: z.array(SystemIdentifierSchema)
     .min(1, { message: '`kanban.lanes` lists at least one lane. To draw one lane per option, omit the key.' })