spec(ui): retire ObjectKanbanProps.quickAdd from object-kanban — tombstone, D2 conversion and baselines (#17792)

Fixes #17260

Executes the objectui#8285 director-seat ruling (comment 5583979207,
decision batch #91, 2026-09-08, standing maintainer delegation) — ruled
**option B**: `quickAdd` is retired from the `object-kanban` board and
stays only on the `kanban-ui` block, where a React host can supply the
runtime function the control needs. This PR is the tombstone half that
ruling assigns to this repo. A vs B is not re-opened here.

- **Clause-②: yes** — this PR narrows a published accept set:
`ObjectKanbanProps.quickAdd` is retired from `object-kanban`.

## The premise, re-measured rather than relayed

The card's body said an author writing `quickAdd: true` got "nothing,
with no diagnostic". The filer corrected that themselves, and the
correction is what holds — re-measured here at the objectui sha this
repo pins (`.objectui-sha` = `53ded82bf`), not at that checkout's HEAD:

| probe at the pinned sha | reading | control (same instrument, same
file) |
|:--|--:|:--|
| `onQuickAdd` in `plugin-kanban/src/ObjectKanban.tsx` | **0** |
`onCardClick` — **6** |
| `quickAdd` in the same file | **0** | `objectName` — **38** |
| `object-kanban` registration `inputs` (`index.tsx:421-431`) |
`objectName`, `columns` — `quickAdd` absent | `objectName` present |

The board **forwards** the key — `ObjectKanban.tsx:931` spreads the
authored bag into `KanbanRenderer`, which passes
`quickAdd={schema.quickAdd}` alongside `onQuickAdd={schema.onQuickAdd}`
(`index.tsx:196`) — but `KanbanImpl` gates the affordance on **both**
(`:355`, `:368`), and `onQuickAdd` is a host-supplied function JSON
cannot carry and no producer puts on an `object-kanban` node. So the
gate was permanently false: accepted-and-dropped, exactly as the card
classifies it.

Two readings the card's numbers came from could **not** be reproduced at
the pin, and are reported as such rather than passed on:
`OBJECT_KANBAN_INPUTS` (the 13-key constant) and the `inert-quick-add`
interim diagnostic do not exist at `53ded82bf` at all — both are later
objectui work. `OBJECT_KANBAN_INPUTS` does resolve at that checkout's
HEAD (control lit, 3 files), and the registry-spec ledger records the
key verbatim there as `ESCALATED (object-kanban.quickAdd — measured NOT
honoured)`. The pin's own equivalent reading is the `inputs` row in the
table above, and it says the same thing.

## The retirement kit

| carrier | what changed |
|:--|:--|
| `ObjectKanbanPropsSchema.quickAdd` | `retiredKey()` tombstone — `tsc`
types it `never`, and a value reaching the parse raises the prescription
instead of a bare unknown-key verdict |
| the schema's docblock | it listed `quickAdd` among the keys reached
"via the forwarded schema" — true about the FORWARD, false about the
READ, which is how the key kept re-authorizing itself. Corrected in the
same stroke |
| `src/conversions/registry.ts` | D2 conversion
`object-kanban-quick-add-removed` — a pure lossless delete (the key
never had an effect to preserve), scoped by component `type` so the LIVE
`kanban-ui` spelling stays out of its reach |
|
`migrations/entries/retired-keys/18.ui__ObjectKanbanProps__quickAdd.ts`
| `RETIRED_KEYS_BY_MAJOR[18]` entry `ui/ObjectKanbanProps:quickAdd`,
plus the D3 chain-step wiring and rationale |
| `authorable-surface/ui.json` | the row becomes
`ui/ObjectKanbanProps:quickAdd [RETIRED]` |
| `content/docs/references/ui/component.mdx` | regenerated — the row now
prints the prescription |
| `src/ui/component.test.ts` | four pins (see the ablation below) |
| `.changeset/17260-object-kanban-quick-add-retired.md` | `minor`,
`adr-0087: registered object-kanban-quick-add-removed` |

`packages/spec/src/ui/view.zod.ts` is untouched — it is another round's
declared face this batch. The `kanban-ui` block's `quickAdd` is
untouched by design: it is not a component type this spec declares at
all, which is why the conversion is scoped by `type` rather than by key
name.

## Liveness — measured, with a lit control

Zero stored or example stacks in this repo carry `quickAdd`, because
**no `object-kanban` component is authored anywhere under `examples/` or
`apps/`**. The zero is a reading, not a dark probe: the same instrument
over the same corpora returns `object-grid` 3 and `object-metric` 8.
Repo-wide, `quickAdd` occurred in exactly four places before this PR —
the schema key, the docblock sentence, the ratchet row and the generated
docs row — i.e. only the carriers being retired here. Out-of-repo
authors are unknown and unknowable from here, which is what the D2
conversion and the prescription exist for.

## Verification

| run | result |
|:--|:--|
| `pnpm --filter @objectstack/spec build` | `VERDICT command-exit 0` |
| `pnpm --filter @objectstack/spec test` | `VERDICT command-exit 0` —
Test Files 473 passed (473), Tests 13443 passed (13443) |
| `pnpm --filter @objectstack/spec typecheck` | exit 0 |
| `pnpm --filter @objectstack/spec check:generated` | 15/15 artifacts
current (one lap: `gen:migration-registry`, then the build's
`gen:schema`, then `gen:docs`) |
| `pnpm --filter @objectstack/spec check:migration-registry` | `✓
src/migrations/registry.ts is current (202 semantic, 168 retired-key,
178 retired-def)` |
| `node scripts/check-adr-0087-registration.mjs --base origin/main` | `✓
1 declared-breaking changeset(s), each carrying an ADR-0087 disposition`
— `registered object-kanban-quick-add-removed (new here)` |
| `node scripts/check-changeset-no-major.mjs --base origin/main` | `✓
This diff introduces no major bump` |
| `pnpm check:nul-bytes` | OK — 8453 text files scanned |

The registry was regenerated by the repo's own generator (`pnpm --filter
@objectstack/spec gen:migration-registry` → `✓ wrote
src/migrations/registry.ts`), never by hand; the first build before that
run failed loudly with `1 key(s) were tombstoned with no registered
retirement`, which is the gate doing its job.

**Ablation — the pins can fail.** On `HEAD`: 4 passed. With the
tombstone mutated back to a live `z.boolean().optional()` in source
(mutation proven on disk: tombstone-call count 1 → 0, injected marker 1,
blob hash `106299e7…` → `e657a7e3…`), the same run goes **2 failed / 2
passed**: the two refusal pins are the discriminating half. Restored
from `HEAD` and proven byte-identical (blob back to `106299e7…`, `git
diff HEAD` empty). Reported honestly: the `not.toHaveProperty` pin does
**not** flip under that mutation — an optional key absent from the input
is not materialized either way — so it guards the strip direction and
not the refusal.

## Changeset — measured, not assumed

Owed, at `minor`.

- **Subject**: the tombstone's prescription text reaches the published
`dist` — 2 hits, `dist/ui/index.js` and `dist/ui/index.mjs`, both inside
`packages/spec`'s `files[]`.
- **Positive control**: a pre-existing shipped describe from the same
schema — 2 hits, same files.
- **Negative control**: text that exists only in `component.test.ts` —
**0** hits in `dist`.

Level is `minor`, not `major`: `scripts/check-changeset-no-major.mjs`
forbids `major` during the launch window (lockstep versioning would
promote ~70 packages), and the sibling retirement one entry over
(`ui/ObjectGridProps:defaultSort`, #11805) is registered under protocol
18 on the same reading. `api-surface/` is unchanged and correctly so —
it ratchets export existence, and `ObjectKanbanProps` still exists, one
key narrower.

## Not flipping this ready

An at-tier contract-review verdict is owed on the head that lands;
`needs:contract-review` rides this PR. Draft, not enqueued.

Co-Authored-By: Claude <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

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

Author: os-bill

.changeset/17260-object-kanban-quick-add-retired.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: retire `ObjectKanbanProps.quickAdd` — the `object-kanban` board forwarded it and nothing ever read it (ADR-0049)
+
+<!-- adr-0087: registered object-kanban-quick-add-removed -->
+
+**BREAKING** — `quickAdd` is retired from the `object-kanban` component props. Executes the
+objectui#8285 director-seat ruling (decision batch #91, 2026-09-08, standing maintainer
+delegation), ruled **option B**: the key leaves the board and stays only on the `kanban-ui`
+block, where a React host can supply the runtime function the control needs.
+
+| | before | after |
+|:--|:--|:--|
+| `object-kanban` | `quickAdd: true` parsed clean and did nothing | refused by the tombstone, with the prescription |
+| `kanban-ui` (objectui block) | the control works when the host passes `onQuickAdd` | **unchanged** |
+
+**What was actually wrong.** Measured at the `.objectui-sha` pin this repo builds against
+(`53ded82bf`): the board FORWARDS the key — `ObjectKanban.tsx:931` spreads the authored bag
+into `KanbanRenderer`, which passes `quickAdd={schema.quickAdd}` alongside
+`onQuickAdd={schema.onQuickAdd}` (`plugin-kanban/src/index.tsx:196`) — but `KanbanImpl`
+gates the affordance on **both** (`:355`, `:368`), and `onQuickAdd` is a host-supplied
+FUNCTION that JSON cannot carry and that no producer puts on an `object-kanban` node.
+`ObjectKanban.tsx` names neither half of the pair (0 occurrences each, against 6 for the
+sibling `onCardClick` in the same file), so the gate was permanently false.
+
+**And the drop was not silent, which is what made it worse than silence.** objectui's html
+tier reported the published key as `unknown-prop` — the same diagnostic a typo gets — and
+its registry↔spec ledger records it as `ESCALATED (object-kanban.quickAdd — measured NOT
+honoured)`. An author following the published contract met a tool that contradicted it, with
+nothing in either message to say which side was wrong. The tombstone collapses both halves
+onto one answer.
+
+## What to write instead
+
+Nothing, on this board: there is no per-column quick-add affordance on `object-kanban` and
+there never was one. Delete the key.
+
+```ts
+// before — parsed clean, rendered nothing
+{ type: 'object-kanban', properties: { objectName: 'crm_task', groupBy: 'status', quickAdd: true } }
+// after
+{ type: 'object-kanban', properties: { objectName: 'crm_task', groupBy: 'status' } }
+```
+
+The control itself is not withdrawn from the platform. It stays on the `kanban-ui` block,
+which a React host renders directly and can hand the `onQuickAdd` slot to — that is what the
+ruling preserved deliberately.
+
+Existing sources: `os migrate meta --from 17` lists the mechanical edits; apply them by hand.
+
+The retirement kit:
+
+- a `retiredKey()` tombstone on `ObjectKanbanPropsSchema` — `tsc` types the key `never`, and
+  a value reaching the parse raises the prescription rather than a bare unknown-key verdict
+- the D2 conversion `object-kanban-quick-add-removed` (`RETIRED_KEYS_BY_MAJOR[18]` entry
+  `ui/ObjectKanbanProps:quickAdd`, wired into the protocol-18 chain step) — a **pure lossless
+  delete**, since the key never had an effect to preserve, scoped by component `type` so the
+  live `kanban-ui` spelling stays out of its reach
+- the `authorable-surface/ui.json` row becomes `ui/ObjectKanbanProps:quickAdd [RETIRED]`, and
+  the generated reference page prints the prescription in place of the old describe
+- the schema docblock's read-point list is corrected in the same stroke: it named `quickAdd`
+  among the keys reached "via the forwarded schema", a sentence true about the FORWARD and
+  false about the READ — which is how the key kept re-authorizing itself
+- pin tests (`ui/component.test.ts`): the refusal carries the prescription; a clean parse does
+  not materialize the key; and the control pair separating the tombstone's answer from the
+  strict unknown-key arm's, so a shape that had merely DROPPED the key could not pass
+- no liveness-ledger row (component props are not an enrolled ledger type) and no form or
+  i18n edit: zero `object-kanban` components are authored anywhere under `examples/` or
+  `apps/` (control: `object-grid` 3, `object-metric` 8 in the same corpora, same instrument)
+- `api-surface/` is unchanged, correctly: it ratchets export existence, and no export leaves —
+  `ObjectKanbanProps` still exists, one key narrower

content/docs/references/ui/component.mdx

@@ -502,7 +502,7 @@ Sort field and direction pair
 | **cardFields** | `string[]` | optional | Fields rendered on each card |
 | **swimlaneField** | `string` | optional | Field for horizontal swimlanes (in addition to columns) |
 | **grouping** | `any` | optional | View grouping config; its first field is the swimlane fallback |
-| **quickAdd** | `boolean` | optional | Show the per-column quick-add affordance |
+| **quickAdd** | `never` | optional | [REMOVED] `object-kanban` property `quickAdd` was removed in @objectstack/spec 17 (ADR-0049) — the board forwarded it, but the per-column affordance is gated on both `quickAdd` and `onQuickAdd`, and `onQuickAdd` is a host-supplied function JSON cannot carry and no producer ever put on an `object-kanban` node, so authoring it was a parse-clean no-op. Delete the key. The quick-add control is unchanged on the `kanban-ui` block, where a React host supplies the `onQuickAdd` slot the control needs. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand. |
 | **coverImageField** | `string` | optional | Image field rendered as the card cover |
 | **conditionalFormatting** | `any` | optional | Card conditional formatting rules |
 

packages/spec/authorable-surface/ui.json

@@ -780,7 +780,7 @@
     "ui/ObjectKanbanProps:grouping",
     "ui/ObjectKanbanProps:limit",
     "ui/ObjectKanbanProps:objectName",
-    "ui/ObjectKanbanProps:quickAdd",
+    "ui/ObjectKanbanProps:quickAdd [RETIRED]",
     "ui/ObjectKanbanProps:swimlaneField",
     "ui/ObjectKanbanProps:titleField",
     "ui/ObjectListView:addRecord",

packages/spec/src/conversions/registry.ts

@@ -8010,6 +8010,189 @@ const objectGridDefaultSortRemoved: MetadataConversion = {
   },
 };
 
+/**
+ * `object-kanban`'s per-column quick-add switch leaves the contract (protocol
+ * 18, #17260, ADR-0049 enforce-or-remove; the spec half of the objectui#8285
+ * director-seat ruling, decision batch #91, 2026-09-08 — ruled option B,
+ * `quickAdd` is retired from the board and stays only on the `kanban-ui`
+ * block, where a React host can supply the runtime function the control
+ * needs).
+ *
+ * **A pure lossless delete.** The key never had an effect to preserve.
+ * Measured at the `.objectui-sha` pin (`53ded82bf`): the board FORWARDS it —
+ * `ObjectKanban.tsx:931` spreads the authored bag into `KanbanRenderer`,
+ * which passes `quickAdd={schema.quickAdd}` alongside
+ * `onQuickAdd={schema.onQuickAdd}` (`plugin-kanban/src/index.tsx:196`) — but
+ * `KanbanImpl` gates the affordance on BOTH (`:355`, `:368`), and
+ * `onQuickAdd` is a host-supplied FUNCTION that JSON cannot carry and that no
+ * producer puts on an `object-kanban` node (`ObjectKanban.tsx` names neither
+ * half of the pair: 0 occurrences each, against 6 for the sibling
+ * `onCardClick` in the same file). So the gate was permanently false and
+ * deleting the key preserves observed behaviour exactly.
+ *
+ * ⚠️ Scoped by component `type`, never by key name. `quickAdd` is LIVE on the
+ * `kanban-ui` block — the same renderer chain, reached by a React host that
+ * hands in `onQuickAdd` — and the ruling keeps it there deliberately. That
+ * block is objectui-side and is not a component type this spec declares, so no
+ * stack this walk reaches can carry it; the type scoping is what keeps the
+ * strip from generalising into a name-keyed one if it ever is declared. The
+ * fixture's non-carrier control is an `object-grid` authoring the same key
+ * name.
+ *
+ * The neighbouring forwarded keys `coverImageField` and `conditionalFormatting`
+ * are LIVE and survive untouched (both are read on this very path, by
+ * `KanbanRenderer` / `bucketCardsIntoColumns`).
+ *
+ * Zero authored occurrences in this repo's corpora — no `object-kanban`
+ * component is authored anywhere under `examples/` or `apps/` at all (control:
+ * `object-grid` 3, `object-metric` 8 in the same corpora, same instrument) —
+ * so this entry exists for stored `sys_metadata` rows and for authors outside
+ * the repo, which the filing seat explicitly could not measure.
+ */
+const objectKanbanQuickAddRemoved: MetadataConversion = {
+  id: 'object-kanban-quick-add-removed',
+  toMajor: 18,
+  retiredFromLoadPath: true,
+  surface: 'page.component.object-kanban.quickAdd',
+  summary:
+    "object-kanban component prop 'quickAdd' removed (#17260 — the affordance is gated on a "
+    + "host-supplied 'onQuickAdd' function no producer puts on an object-kanban node, so the key "
+    + "was accepted and dropped; the quick-add control stays on the React-host 'kanban-ui' block)",
+  apply(stack, emit) {
+    return mapPageComponents(stack, (component, path) => {
+      if (component.type !== 'object-kanban') return component;
+      const properties = component.properties;
+      if (!isDict(properties) || !('quickAdd' in properties)) return component;
+      const stripped = stripKeys(properties, ['quickAdd'], emit, `${path}.properties`);
+      return { ...component, properties: stripped };
+    });
+  },
+  fixture: {
+    before: {
+      pages: [
+        {
+          name: 'delivery_board',
+          regions: [
+            {
+              name: 'main',
+              components: [
+                // The carrier: an `object-kanban` authoring the retired key.
+                {
+                  type: 'object-kanban',
+                  id: 'k1',
+                  properties: { objectName: 'crm_task', groupBy: 'status', quickAdd: true },
+                },
+                // ⚠️ The same key name on a component that is NOT an
+                // `object-kanban` — not this entry's key. Untouched: the strip
+                // is scoped by component type, never by key name, which is what
+                // keeps the LIVE `kanban-ui` spelling out of its reach.
+                {
+                  type: 'object-grid',
+                  id: 'g1',
+                  properties: { objectName: 'crm_task', quickAdd: true },
+                },
+                // A board WITHOUT the key rides through untouched — the strip
+                // dispatches on key presence and the copy-on-write contract
+                // keeps the reference.
+                {
+                  type: 'object-kanban',
+                  id: 'k3',
+                  properties: { objectName: 'crm_task', cardFields: ['title'] },
+                },
+                // The nested position (#6775's lesson): a board inside a
+                // card's `children` is still a component.
+                {
+                  type: 'page:card',
+                  id: 'c1',
+                  properties: {
+                    children: [
+                      {
+                        type: 'object-kanban',
+                        id: 'k4',
+                        properties: { objectName: 'crm_lead', groupBy: 'stage', quickAdd: false },
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          ],
+        },
+        // The named-slot shape (#6776): a board authored into a slotted page.
+        {
+          name: 'delivery_board_detail',
+          kind: 'slotted',
+          regions: [],
+          slots: {
+            details: {
+              type: 'object-kanban',
+              id: 'k5',
+              properties: { objectName: 'crm_task', groupBy: 'status', quickAdd: true },
+            },
+          },
+        },
+      ],
+    },
+    after: {
+      pages: [
+        {
+          name: 'delivery_board',
+          regions: [
+            {
+              name: 'main',
+              components: [
+                {
+                  type: 'object-kanban',
+                  id: 'k1',
+                  properties: { objectName: 'crm_task', groupBy: 'status' },
+                },
+                {
+                  type: 'object-grid',
+                  id: 'g1',
+                  properties: { objectName: 'crm_task', quickAdd: true },
+                },
+                {
+                  type: 'object-kanban',
+                  id: 'k3',
+                  properties: { objectName: 'crm_task', cardFields: ['title'] },
+                },
+                {
+                  type: 'page:card',
+                  id: 'c1',
+                  properties: {
+                    children: [
+                      {
+                        type: 'object-kanban',
+                        id: 'k4',
+                        properties: { objectName: 'crm_lead', groupBy: 'stage' },
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'delivery_board_detail',
+          kind: 'slotted',
+          regions: [],
+          slots: {
+            details: {
+              type: 'object-kanban',
+              id: 'k5',
+              properties: { objectName: 'crm_task', groupBy: 'status' },
+            },
+          },
+        },
+      ],
+    },
+    // Three notices: the region-level board, the nested one and the slotted
+    // one. The `object-grid` sibling and the board without the key emit none.
+    expectedNotices: 3,
+  },
+};
+
 /**
  * Object-permission lifecycle bits `allowRestore` / `allowPurge` removed
  * (protocol 18, #12497 — ADR-0049 enforce-or-remove, maintainer ruling
@@ -9170,6 +9353,7 @@ export const CONVERSIONS_BY_MAJOR: Readonly<Record<number, readonly MetadataConv
     translationComponentSubmitLabelRemoved,
     pageComponentResponsiveRemoved,
     objectGridDefaultSortRemoved,
+    objectKanbanQuickAddRemoved,
     permissionAllowRestorePurgeRemoved,
     formViewOptionDefaultRemoved,
     fieldReferenceToAlias,

packages/spec/src/migrations/entries/retired-keys/18.ui__ObjectKanbanProps__quickAdd.ts

@@ -0,0 +1,30 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+// #17260 — ADR-0049 enforce-or-remove, executing the objectui#8285
+// director-seat ruling (comment 5583979207, decision batch #91, 2026-09-08,
+// standing maintainer delegation): ruled option B — `quickAdd` is retired from
+// the `object-kanban` board and stays only on the `kanban-ui` block, where a
+// React host can supply the runtime function the control needs.
+// The board FORWARDED the key but never honoured it: measured at the
+// `.objectui-sha` pin `53ded82bf`, `ObjectKanban.tsx:931` spreads the authored
+// bag into `KanbanRenderer` (`plugin-kanban/src/index.tsx:196` passes both
+// `quickAdd` and `onQuickAdd`), and `KanbanImpl` gates the affordance on BOTH
+// (`:355`, `:368`) — while `onQuickAdd` is a host-supplied FUNCTION that JSON
+// cannot carry and no producer puts on an `object-kanban` node
+// (`ObjectKanban.tsx` names neither half: 0 each, against 6 for the sibling
+// `onCardClick` in the same file). The drop was not silent, which is the sharp
+// edge: objectui's html tier reported the published key as `unknown-prop` —
+// the SAME diagnostic a typo gets — and its registry-spec ledger records it as
+// `ESCALATED (object-kanban.quickAdd — measured NOT honoured)`, so the author
+// met a tool contradicting the contract with no way to tell which side was
+// wrong. Tombstoned with `retiredKey()` in `ObjectKanbanPropsSchema` (the
+// surface baseline line carries `[RETIRED]`); sources are stripped by the D2
+// conversion `object-kanban-quick-add-removed`, a pure lossless delete scoped
+// by component `type` so the LIVE `kanban-ui` spelling is untouched.
+//
+// Registered under 18, not 17: v17.0.0 was cut before this landed, so the
+// removal ships on the 17.x line (launch-window convention: accept-set
+// narrowings ride minor releases) and the prescription lives at the major
+// boundary where `migrate meta` users look — the `ui/ObjectGridProps:defaultSort`
+// precedent one entry over.
+export const entry = 'ui/ObjectKanbanProps:quickAdd';