fix(spec)!: refuse a padded groupByField on kanban, gantt and timeline instead of handing the renderer a lookup that always misses

[os-bill]

Fixes #17499
Clause-②: no

What changed

KanbanConfigSchema.groupByField (required), GanttConfigSchema.groupByField and TimelineConfigSchema.groupByField were bare z.string(), so ' stage' was valid authored metadata. All three now carry the non-padded pattern this repo already chose for the same defect on the sibling axis — grouping.fields[].field, landed as f8e5790593 (#17360 / PR #17498), which scoped this axis out by name.

The refusal is addressed to the offending key (kanban.groupByField, gantt.groupByField, timeline.groupByField), quotes the offending spelling so the invisible whitespace is visible, and carries the name to write instead.

Reusing the precedent, and the three places it does not fit

• The regex is the precedent's, not a second one. Its module-private constant is renamed GROUPING_FIELD_NON_PADDED_PATTERN to NON_PADDED_FIELD_NAME_PATTERN and now serves both axes. No exported symbol moves (check:api-surface is clean with no regeneration).
• The kanban key is REQUIRED — the precedent's is not. That is the whole reason this is its own card: a padded value there cannot be withdrawn by omitting the key, so a .trim() producer would be the author's only feedback channel and it would say nothing. The refusal is sharper here, not milder.
• Refuse, not .trim() — the precedent's stated reason, re-checked and unchanged: a trimming schema makes ' stage' and 'stage' silently equivalent, the consumer-tolerance direction AGENTS.md #0.1 refuses. None of these three rows honestly wants the other answer, and the required key is the strongest case against it.
• No ruling citation in the message. The precedent's message ends with its ruling date; ruling C on objectui#7347 is about grouping.fields[].field and explicitly not about this axis, so quoting it here would attribute a decision nobody made. The code comment says so.

ADR-0087 disposition: registered, and the entry is in this PR

The changeset carries an adr-0087: registered ui-list-view-groupbyfield-padded-refused marker (the HTML-comment form the gate reads), and packages/spec/src/migrations/entries/semantic/18.ui-list-view-groupbyfield-padded-refused.ts registers it under protocol major 18, with the regeneration lap committed beside it.

Why registered and not a not-required category, measured against the gate's closed vocabulary:

category	verdict here
unpublished	refused — @objectstack/spec publishes to npm.
already-registered	false. The precedent's entry scopes itself to grouping.fields[].field and says in its own text that the groupByField axis is not touched by it.
no-migration-prescription	refused — the changeset body carries a FROM/TO block, and there genuinely is a prescription: stored views with a padded name are refused on their next authoring-path save and must be re-authored.
runtime-interface-only	refused — this is a spec schema, not a runtime TS interface.
type-surface-only	refused — the narrowing is a parse-time refusal, not a type-only change.

The same-defect precedent took registered with a new semantic entry, for the same stored-metadata reason.

The regeneration lap, and why two of its three files show no diff. pnpm --filter @objectstack/spec gen:migration-registry inserted the entry into registry.ts's generated region (56 lines, insertion-only, comment run carried through; nothing hand-edited inside the markers). gen:spec-changes and gen:upgrade-guide both ran and wrote byte-identical files: each projects majors up to PROTOCOL_VERSION, which is 17.0.0, and this entry registers under 18. The control is the landed sibling f8e5790593 — its file list touched neither projection either. check:migration-registry, check:spec-changes and check:upgrade-guide are all green.

Evidence

Red before green — ablation, on-disk proof, hash-verified restore. The fix was committed first; the mutation removed the three superRefine calls from packages/spec/src/ui/view.zod.ts (the subject resolves through the same-package relative import ./view.zod, so there is no dist leg to prove — the test never resolves through exports).

BEFORE   HEAD blob 6ff7ba320a8fa445fa34e421b39716359194bc1b == on-disk hash; 3 occurrences
MUTATED  on-disk hash bf9424b852ac545affc8d69abc8548e1114817da; 0 occurrences; git diff --stat: 3 deletions
ABLATED  24 failed | 40 passed   (exit 1)
RESTORE  git checkout HEAD -- packages/spec/src/ui/view.zod.ts; on-disk hash back to 6ff7ba32…, git status clean
GREEN    64 passed | 387 skipped (exit 0)

The direction was predicted before the run and observed as predicted: turning red, 24 of the 64 arms. The 40 that stayed green are the LIT and no-trim arms, which is what makes the 24 a reading rather than a restatement.

⭐ LIT — the narrowing does not over-reach. Every distinct groupByField spelling this repo carries still parses, on all three schemas: harvested across every .ts / .tsx / .mdx / .json / .mjs outside node_modules, 14 distinct literals, zero of them padded. owner.name is the load-bearing member and is pinned — these keys hold a field reference, not a machine name, which is why the snake_case grammar /^[a-z_][a-z0-9_]*$/ is the wrong vocabulary (packages/lint's validate-list-view-field-refs.test.ts carries kanban: { groupByField: 'owner.name' } in a case asserting no findings; that suite is green here, 137 tests). Three of the 14 — 'warning', 'error', a bracketed select_or_status_field placeholder — are a severity-map value and prose in a completeness hint, so they are not authored names and are not pinned.

⭐ DARK — three readings that must be 0, before and after.

reading	before	after
other bare z.string() keys in view.zod.ts reached by this change	0	0 — the edit touches exactly the 3 groupByField declarations; git diff shows 3 changed property sites and no other schema key. A per-schema test probes every sibling string key (summarizeField, titleField, startDateField, endDateField, progressField, colorField) with a padded value and requires it to still parse.
authorable-surface/ rows moved	0	0 — check:authorable-surface green with no regeneration; a value-level refusal adds no key.
api-surface/ entries moved	0	0 — check:api-surface green with no regeneration; the published type surface is byte-unchanged.

Which gate can actually go red on this — measured, not guessed. check:docs reads these three describe() strings: it exited 1 naming content/docs/references/ui/view.mdx and content/docs/references/ui/component.mdx before gen:schema && gen:docs, and 0 after. check:adr-0087-registration reads the changeset and exited 1 before the ledger entry landed, naming exactly the missing id, and 0 after it — red before green on that gate too. The remaining 13 of the 15 spec artifact gates were green throughout — they structurally cannot see a value-level refine, and are recorded as DARK rather than claimed as coverage.

Commands run. The schema and test blobs have not moved since the first lap (view.zod.ts is 6ff7ba320a8fa445fa34e421b39716359194bc1b at both heads and on disk, view.test.ts is 162772c6…), so the ablation above stands unrepeated; every other reading below was re-taken at ca0dd6ce0e after the ledger entry landed:

command	result
pnpm --filter @objectstack/spec test	485 files / 13932 passed
pnpm --filter @objectstack/spec typecheck	exit 0 (test layer compiles; debt ledger held)
pnpm --filter @objectstack/spec check:generated	all 15 artifacts up to date (both laps)
pnpm --filter @objectstack/lint exec vitest run src/validate-list-view-field-refs.test.ts src/runtime-gate.view-writes.test.ts	137 passed
pnpm exec eslint . --no-inline-config	6819 files, 0 errors, 0 warnings — the whole population at ca0dd6ce0e, no narrowing claimed; both files this lap added or changed are provably in the run
pnpm check:nul-bytes	8804 files, no raw control bytes
pnpm check:empty-changeset, check-changeset-no-major.mjs	exit 0
check-adr-0087-registration.mjs	exit 0 — 1 declared-breaking changeset(s), each carrying an ADR-0087 disposition … registered ui-list-view-groupbyfield-padded-refused (new here)

Acceptance notes

• The empty string still parses on all three keys, deliberately: this card narrows padding only, and widening the pattern to catch '' would be a second, undeclared narrowing riding on it. On the required kanban key a blank name is a blank board, refused one layer down by the field-reference rules, not by this pattern.
• Noted, not filed — objectui's packages/i18n carries groupByField: 'Group by field' / '分组字段'. Those are i18n label entries keyed by the same name, not values of this spec key, so they are neither affected nor evidence about accepted values. Recorded because a reader harvesting the sibling repo will hit them.
• Noted, not filed — packages/spec/src/kernel/functional-completeness.ts documents the kanban fallback chain as groupBy = groupByField || groupField || ..., and groupField is a live legacy alias declared in objectui, not in this repo. Nothing here is wrong; it is the context a future reader of this key needs. Carrier: whoever next touches the kanban completeness hint.

Authored by the domain:spec execution seat, session session_01JbZnqu8bt6YqfJsr9vaFb3.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 11 documentable anchor(s).

⛔ 2 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v17/17-1.mdx (via GanttConfigSchema (symbol, a top-level const))
• content/docs/releases/v17/17-4.mdx (via GanttConfigSchema (symbol, a top-level const))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 7 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 136 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 1bc22b3dcddc8a30b4826da8625e7787d5518a8f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 4c7701dfc8fb1a1e58e96bbc89770c4a37ccd575 — the merge of head ca0dd6ce0ef3ba7cc351629c557a13cb8a24d5c4 into base 1bc22b3dcddc8a30b4826da8625e7787d5518a8f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 4c7701dfc8fb1a1e58e96bbc89770c4a37ccd575 && git checkout 4c7701dfc8fb1a1e58e96bbc89770c4a37ccd575
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 1bc22b3dcddc8a30b4826da8625e7787d5518a8f ca0dd6ce0ef3ba7cc351629c557a13cb8a24d5c4 && git checkout -B drift-repro 1bc22b3dcddc8a30b4826da8625e7787d5518a8f && git merge --no-ff ca0dd6ce0ef3ba7cc351629c557a13cb8a24d5c4

node scripts/docs-audit/affected-docs.mjs --json 1bc22b3dcddc8a30b4826da8625e7787d5518a8f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 1bc22b3dcddc8a30b4826da8625e7787d5518a8f → pass the list as
args.docs, on the commit named under Which tree this was computed on.