fix(spec): the object-kanban quickAdd retirement prescribes "delete the key", not the unregistered kanban-ui block

[objectstack-fleet]

Fixes #21017

Clause-②: no

The object-kanban quickAdd retirement told authors the control "is unchanged on the kanban-ui block". objectui retired that block (objectui#8257) and this spec never declared it as a component type, so a node written there saves clean and resolves no renderer. Every author-facing copy of the remedy now says one sentence: Delete the key; object-kanban offers no quick-add control. The refusal itself is unchanged: same key, same invalid_type code at path quickAdd, same accept set. Prose only.

The copies

Copy	File	Change
tombstone message (shown at the save door and in the generated reference)	packages/spec/src/ui/component.zod.ts	the sentence
D2 conversion object-kanban-quick-add-removed summary	packages/spec/src/conversions/registry.ts	the sentence
D3 entry object-kanban-quick-add-retired: replacement, reason, acceptanceCriteria (what os migrate meta prints)	migrations/entries/semantic/18.object-kanban-quick-add-retired.ts, generated copy in migrations/registry.ts	the sentence; the second way out "move the board to a host that renders the kanban-ui block" is dropped
step 18 rationale fragment (the paragraph the upgrade guide prints)	migrations/registry.ts, the hand-written region outside the generated markers	the sentence. A sixth copy the card did not list, found by the git grep of the order's H2
docblocks: two in component.zod.ts, two in conversions/registry.ts, the retired-key entry's header, the pin test's header	same files	the ruling is still quoted, now with what objectui did to the block it named
generated	migrations/registry.ts (gen:migration-registry), content/docs/references/ui/component.mdx (gen:docs)	regenerated, never hand-typed

Measured before writing

• H1, is there a rendering route. objectui at the pin e420df310f5b and at main 770cc5ba4d15: 0 code lines naming kanban-ui under packages and apps outside tests and CHANGELOGs; 22 comment lines in 6 files, all recording the retirement. No register call carries the key. ObjectKanban passes neither half of the pair to KanbanBoardCore; objectui's own docblock there says "An object-kanban board draws no Quick Add control, whatever its document carries". The pair is read only by the exported KanbanRenderer React component, which a host mounts directly, so no metadata node reaches it. No route to name, so triage's sentence stands.
• H2, every copy. Base git grep of kanban-ui under packages/spec/src lists the files in the order plus the step 18 rationale fragment above. After this PR no author-facing text names the block; the remaining mentions are docblocks and comments that explain why it is not named.
• H3, what PR chore(objectui): bump the console pin to e420df310f5b (carries objectui#11163 and objectui#11199) #20990 already did. It added the "Re-read at e420df310" qualification to the second docblock. That qualification is kept, re-wrapped, with the same facts and citations. The sentence just above it still said the control "stays on kanban-ui", contradicting it; that sentence is the one rewritten.
• The dead-node claim. Probe on this branch: PageComponentSchema.safeParse of a node with type kanban-ui succeeds (true), and ComponentPropsMap['object-kanban'].safeParse({ objectName: 'task', quickAdd: true }) fails with one issue, code invalid_type, path quickAdd.

Pin

ui/component.test.ts (ObjectKanbanPropsSchema quickAdd is retired): the existing refusal test now pins "Delete the key" in place of the block name, and one new test asserts that the refusal still carries invalid_type at quickAdd, that the tombstone carries the sentence, and that none of the tombstone, the D2 summary, the D3 entry's three texts and the step 18 rationale contains kanban-ui. The generated copies are held to their sources by check:migration-registry.

Ablation, each leg through scripts/ablation-replace.mjs in wrap mode against the committed fix: the tool printed anchor 1 to 0 and the blob hash changing before the run, and blob == HEAD with an empty git diff HEAD after it. Direction in every leg was red, exactly one failing test: leg 1 the tombstone sentence reverted (assertion on the sentence), leg 2 the D2 summary reverted, leg 3 the generated semantic copy reverted, leg 4 the step 18 rationale reverted (each of the last three on not.toContain('kanban-ui')). The test imports the sources by relative path, so no dist/ is in the resolution path and no rebuild is owed between legs.

Verified at head 83d99268a

• pnpm --filter @objectstack/spec build exit 0; check:generated all 15 artifacts up to date, with check:migration-registry, check:spec-changes, check:upgrade-guide, check:docs, check:authorable-surface and check:api-surface green. check:docs was stale after the tombstone edit and was regenerated: the diff of content/docs/references/ui/component.mdx is the one sentence.
• dispatch-gates.mjs --commands --repo objectstack-ai/objectstack over the actual diff: 112 commands. --ran verdict: "112 derived famil(ies) accounted for — 112 run, 0 NOT-MEASURED", every recorded exit 0. The four artifact-roster gates whose roster sits under the touched paths (check:meta-url-spelling, check:authz-resolver, check:error-code-casing, check:filter-alias-parity) also exit 0. The seven gates that first answered exit 3 (workspace not built) were re-run after turbo run build of the closure and exit 0.
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/ui src/conversions src/migrations scripts/step18-rationale-merge.test.ts scripts/conversions-major18-merge.test.ts: 114 files, 4190 tests passed. pnpm --filter @objectstack/spec typecheck exit 0.
• origin/main was merged with scripts/pm/os-regen-merge.sh (main at 8368f1c00); regenerating the migration registry afterwards changed nothing. The repo-wide lint union and the rest of the farm are CI's.

Acceptance notes

• packages/spec/CHANGELOG.md, the 17.5.0 entry for the retirement (about lines 1580-1629), carries the same prescription ("It stays on the kanban-ui block ...", and "live kanban-ui spelling"). It is release-owned and published, so it is not touched here; it needs an amendment in a dedicated docs-only PR. Carrier: none.
• .changeset/objectui-pin-citations-e420df310f5b.md already says the block was retired in objectui and is correct; untouched.
• No governed surface is touched (no .claude/**, skills/**, ADR or AGENTS.md). The claim records that the at-tier contract review of the packages/spec/src/** face is owed before enqueue.
• Changeset: patch for @objectstack/spec, Clause-②: no. The diff widens no accept set and no public surface.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

3 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ⚠️ 1 changed file(s) yielded no anchor (packages/spec/src/migrations/entries/retired-keys/18.ui__ObjectKanbanProps__quickAdd.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/src/migrations/entries/retired-keys/18.ui__ObjectKanbanProps__quickAdd.ts) — pages documenting those are invisible to this run
• 6 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 137 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 c6954d6d09080179d3af72c80a820c7c24cf6053 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 1a6e0400f3fb6aebcb6109f6532785091cc54b5c — the merge of head 83d99268a356566efa67280cd4007a14b2989ea2 into base c6954d6d09080179d3af72c80a820c7c24cf6053, 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 1a6e0400f3fb6aebcb6109f6532785091cc54b5c && git checkout 1a6e0400f3fb6aebcb6109f6532785091cc54b5c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin c6954d6d09080179d3af72c80a820c7c24cf6053 83d99268a356566efa67280cd4007a14b2989ea2 && git checkout -B drift-repro c6954d6d09080179d3af72c80a820c7c24cf6053 && git merge --no-ff 83d99268a356566efa67280cd4007a14b2989ea2

node scripts/docs-audit/affected-docs.mjs --json c6954d6d09080179d3af72c80a820c7c24cf6053

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 83d99268a356566efa67280cd4007a14b2989ea2
Local-runs: none

Rendered 2026-10-01T09:35Z by an isolated reviewer subagent from card #21017 (body and its four comments: the triage grade, the serial note, the claim, the os-dev-report), PR #21141 (body, its 8 files, the net diff against the merge-base 8368f1c00), the head's tree read with git show on a fetched ref, objectui main read over the REST contents API, and the head's check-runs, read last at 2026-10-01T09:33Z. Nothing built, run or re-run.

① Derived judgments

1. The tombstone ObjectKanbanPropsSchema.quickAdd (component.zod.ts:4334-4341) — prose only, right. The only non-comment change is the guidance string handed to retiredKey(). At the head, shared/retired-key.ts:179 builds the schema as z.never() whose error callback returns guidance, then .optional() and .describe() with the [REMOVED] prefix on the same guidance: the accept set (absence accepted, every authored value refused), the issue code invalid_type and the path quickAdd all come from z.never(), not from the string. So the refusal's code, path and verdict are byte-identical and only its message changes. Clause-②: no is right.
2. The [REMOVED] … describe text flows into the generated reference content/docs/references/ui/component.mdx:827; the diff regenerates it and the change is the one sentence. Right. At the head a whole-tree grep for kanban-ui (excluding node_modules, dist, lockfile and CHANGELOGs) finds no other generated artifact carrying the old sentence: spec-changes.json, the authorable-surface baseline and docs/protocol-upgrade-guide.md have no hit.
3. D2 conversion object-kanban-quick-add-removed (conversions/registry.ts:8974-8977) — summary string only; apply(), its type scoping and its fixtures are untouched (the hunk at :9002-9005 is a comment inside the fixture). A published string changes, no behaviour. Right.
4. D3 semantic entry 18.object-kanban-quick-add-retired.ts — replacement, reason and acceptanceCriteria change; id and surface do not. The second way out ("move the board to a host that renders the kanban-ui block") is dropped, which is what the triage sentence requires. Its generated copy at migrations/registry.ts:14117-14135 (inside the semantic:18 generated region, which opens at :6065) carries the identical text; check:migration-registry holds the two together and is CI's (Lint & Repo Gates, in progress at read time; the dev reports it green locally). Right.
5. Retired-key entry 18.ui__ObjectKanbanProps__quickAdd.ts — header comment only, mirrored in the generated copy at migrations/registry.ts:23122-23144. Right.
6. The sixth copy, the step-18 rationale fragment (migrations/registry.ts:5693-5697) — inside the family and the surface, right. It sits in the hand-written STEP18_RATIONALE table (declared at :5024, between the close of the semantic:17 generated region at :4973 and the open of the semantic:18 region at :6065), so it is edited by hand, not regenerated, and the dev did that. It is published: step18.rationale is joinRationale(STEP18_RATIONALE) at :6053, exported through MIGRATIONS_BY_MAJOR[18], and scripts/build-upgrade-guide.ts:89 prints step.rationale; the guide at the head covers protocol 16 to 17 only, so no guide regeneration was owed now (consistent with check:upgrade-guide up to date and no guide file in the diff), and the sentence would have reached the guide when 18 is cut. The claim's file surface names migrations/registry.ts, the sentence is the same false claim ("quickAdd stays LIVE on the kanban-ui block"), and triage's direction is that the remedy text stops steering to kanban-ui and "does not name a block objectui does not register". Fixing it here is in scope; flagging it as a deviation was the right handling.
7. The docblocks — two in component.zod.ts (:4252-4259, :4315-4332), two in conversions/registry.ts (:8929-8936, :8950-8956), the retired-key entry header and the test header. Each keeps the ruling quoted (option B named kanban-ui) and adds what objectui did since (objectui#8257). The PR chore(objectui): bump the console pin to e420df310f5b (carries objectui#11163 and objectui#11199) #20990 "Re-read at e420df310" qualification is kept with its citations. After the diff, every remaining kanban-ui under packages/spec/src is one of these docblocks, a comment, or the test: none is author-facing at the save door, in os migrate meta output or in the generated reference. Right.
8. The pin (component.test.ts:3630-3671) — the existing refusal test now matches Delete the key instead of the block name, and the new test asserts invalid_type at quickAdd, the shared sentence on the tombstone and the D3 replacement, and not.toContain('kanban-ui') over the six remedy texts (tombstone, D2 summary, D3 three texts, step-18 rationale through MIGRATIONS_BY_MAJOR[18].rationale). Triage's two pins are covered: the tombstone names no unregistered block (this test), and the generated copy matches its source (the existing generation check). Right.
9. H1 holds — no metadata route renders quick-add, so triage's sentence is used and no route is named. objectui main at d0fba91aa (read over REST today; the dev measured the pin e420df310 and main 770cc5ba): packages/plugin-kanban/src/index.tsx carries one registration, ComponentRegistry.register('object-kanban', ObjectKanbanRenderer, …) at :678; KanbanRenderer (:344-350) is exported but registered under no key and is the only reader of the quickAdd/onQuickAdd pair; its docblock states ObjectKanban renders KanbanBoardCore directly and supplies neither half. Triage's own re-measure in the card (0 non-test hits under packages/*/src) agrees. Right.
10. Public surface — no export added or removed, no schema shape changed, no key accepted or refused differently. The published values that change are strings only: the tombstone message and describe text, the D2 summary, the D3 three texts, the step-18 rationale. The dev reports check:api-surface "public API surface + factory signatures unchanged"; Build Core is green on the head.

② Semver level

.changeset/21017-quickadd-remedy.md declares '@objectstack/spec': patch and carries Clause-②: no; no ADR-0087 marker, and none is owed (nothing breaking). The diff publishes changed prose in a released package (17.5.0), so a changeset is owed and patch is the right level; skip-changeset would be wrong. Clause-②: no matches the diff: the accept set of object-kanban is unchanged (quickAdd absent accepted, any value refused with the same invalid_type at quickAdd), and the PR body's Clause-②: no line and triage's "prose only, so Clause-②: no" agree. Check Changeset is green on the head.

③ Boundary flags

• Dev deviation 1, the sixth copy — answered in ① item 6: inside the card's family and the claimed surface; right.
• Dev deviations 2 to 5 (background gate loops, a stray untracked /home/user/tmp deleted, two private refs in the sibling objectui checkout deleted at wrap-up with that checkout's origin/main ref advanced and no working tree changed, model-free trailers per the os-dev rule) — process notes with no trace in the diff; nothing to answer at contract level.
• open_questions — empty; none to answer.
• Out-of-scope finding 1, the released packages/spec/CHANGELOG.md 17.5.0 entry (:1580, :1586, :1616, :1629 at the head) still carries the old sentence — closing the card is right. packages/spec/package.json is 17.5.0, so the entry is released. AGENTS.md's Documentation Guardrails row for packages/*/CHANGELOG.md is explicit: release-owned, never edited in a code PR, and a factual error in a released entry is amended "in a dedicated docs-only PR, never a rider on code changes". Leaving it untouched here was required, not a choice. Triage's direction, the governing ruling on the card, enumerates the four texts, the two docblocks and the pins; the card body lists the same copies; neither names the CHANGELOG. This PR satisfies every item of that direction, so Fixes #21017 is right and the card closes on it. Escalated to the seat: the finding reads carrier: none. The CHANGELOG amendment is distinct work under a distinct rule, and it needs a carrier (the dedicated docs-only PR, or a point card) at or before the family close-out so the released sentence does not survive untracked. That is the seat's close-out item, not a block on this PR.
• Out-of-scope finding 2 (objectui comment drift in plugin-kanban/src/index.tsx) — cross-repo, no consumer; noted, nothing owed here.
• The claim's "assertion that pins the old sentence, if any" — there was one (the regex on kanban-ui); it is updated. Right.

Check-runs on the head, as read at 2026-10-01T09:33Z: 32 runs; 17 success (Auto Label, Build Core, Build Docs, Check Changeset, Check Documentation Links, Check PR Size, Dogfood Verify CLI, Flag docs affected by code changes, Governed Surface Queue Guard, No other open PR may claim the same issue, No other open PR may claim the same single-writer path, Part-of PR must not also close its card, Spec property liveness, The card this PR closes must claim this branch, Type Check · debt ledger, Type Check · source gates, filter); 2 skipped (Console Pin Gate, Packed-tarball smoke (opt-in)); 13 in progress (Dogfood Regression Gate 1/3, 2/3, 3/3; Lint & Repo Gates; Temporal Conformance (live PG + MySQL); Test Core 1/6 through 6/6; Type Check · consumer gates; Type Check · workspace). None failed. check:generated and check:migration-registry sit under Lint & Repo Gates, still in progress at read time; the seat re-reads every check before landing.

Implemented-by: claude/issue-21017-quickadd-prescription
Reviewed-by: session_017VaLJnYwhPsanVCe9dMCJU

VERDICT: PASS

---

Generated by Claude Code