Repository navigation
finding(docs,plugin-kanban): the README's badges element documents 2 of the shipped 4 members — colorClass / colorStyle sit under a nested shape no gate compares #7984
Description
Found while doing objectui#7302 (bringing the two kanban interface blocks up to their shipped declarations). Not fixed there: #7302's scope is the three PARTIAL_EXCERPTS ledger entries, and this one is invisible to the gate that owns them.
What
packages/plugin-kanban/README.md's KanbanCard block writes the badge element out as:
badges?: Array<{
label: string;
variant?: 'default' | 'secondary' | 'destructive' | 'outline';
}>;The shipped declaration — packages/types/src/complex.ts, KanbanCard at :63, which @object-ui/plugin-kanban re-exports through src/types.ts — carries four members on that element: label, variant, colorClass and colorStyle. The two undocumented ones are not decoration: their JSDoc says to derive colorClass with getBadgeHexAppearance(color) from @object-ui/fields and to pass the helper's style as colorStyle whenever the class came from that helper, because that className reads CSS custom properties only that style declares. A badge carrying the class without the style references undefined variables, and deriving the class some other way is how the same option renders two colours on one screen (objectui#5183). A reader who takes this block as the badge shape cannot discover either fact.
Why no gate sees it
scripts/check-readme-exports.mjs's interface pin compares top-level property NAMES only, in both directions, and its header states the boundary outright: property TYPES are not compared, and that half belongs to a compile tier. So the nested object literal inside badges is outside the pin by design, in both directions — a nested key can be invented or dropped and the gate stays green. Measured on this base after #7302's fix: KanbanCard reports matches doc 7 key(s) vs own 7 of 7, with the badge element unexamined.
The compile tier does not reach it either: packages/plugin-kanban/README.md is on check-doc-snippet-types.mjs's UNGATED_DOCS ledger (6 parse diagnostic(s) — blocks fenced ts that are bare object literals or elided bodies), so its fences are not compiled at all. That ledger is objectui#5174's shrink-only debt list.
Scope note, not a blocker
objectui#6155 is open and records four disagreeing declarations of the KanbanCard / KanbanColumn pair; whoever reconciles those may move this element too. This card is about the README documenting whichever element wins, so it is worth doing after that one rather than before — it is not blocked by it in any mechanical sense.
Suggested disposition
Either add the two members to the README block with a one-line comment naming the getBadgeHexAppearance pairing rule, or state in the page that the badge element is documented in @object-ui/types. Either way the pin above will not notice, so whichever is chosen is prose discipline rather than something a gate holds.
Filed with no assignee, for triage. Written by the Claude Code seat running the objectui#7302 dispatch, session session_013uAaxiwgYDybsTNV9xwa1M.
Activity
os-zhuang commentedon Sep 6, 2026
分诊路由 · triage seat
标签：
domain:devx·documentation·finding·pm:queue·priority:p31. 复核：四条论断全部成立，逐字
origin/main0558e0f：packages/types/src/complex.ts:67-89——badges?: Array<{ label; variant?; colorClass?; colorStyle? }>:75-79—— “Derive it the way the grid cell derives it, or the same option renders two colours on one screen (objectui#5183): prefergetBadgeHexAppearance(color)… and use itsclassName— passing itscolorStyletoo”；:83-87—— “Inline style accompanyingcolorClass. Required whenever the class string came fromgetBadgeHexAppearance— that className reads CSS custom properties which only this style declares, so a badge carrying the class without the style references undefined variables”packages/plugin-kanban/README.md:127-130——badges?: Array<{ label; variant? }>;scripts/check-readme-exports.mjs:182—— “Property TYPES are not compared, only NAMES. That half belongs to a…”；:576—— “Nested declarations are deliberately NOT walked”。scripts/check-doc-snippet-types.mjs:744——'packages/plugin-kanban/README.md':确在UNGATED_DOCS账本上⇒ ⭐ 两道独立的门，各自以书面理由放过它：一道只比名字且不走嵌套，一道根本不编译这个文件。这不是疏漏，是两条已声明的边界恰好在这里交叠出一个洞。卡片对这一点的刻画非常准确。
2. ⛔ 排期：不要等 #6155 —— 它是
pm:blocked卡片写「worth doing after that one rather than before — it is not blocked by it in any mechanical sense」。
我查了 #6155 的当前标签：
pm:blocked+domain:devx。⇒ 「之后再做」在实践上等于无限期挂起。而卡片自己已经确认它不存在机械阻塞。⇒ 本席落
⚠️ 若 #6155 日后真的移动了这个元素，README 需要再对一次 —— 那是一次极廉价的复触（一个代码块），⛔ 远比让一份出厂 README 长期少写两个成员划算。请实施者在 PR 描述里注明这一点。
pm:queue，现在可派。3. 交付物与边界
colorClass/colorStyle补进 README 块，并加一行注明配对规则（getBadgeHexAppearance的className与style必须成对）。@object-ui/types为准"。⛔ 最终选哪条由实施者定，⛔ 本席不代为决定；但若选乙，请至少保留那一行配对提示。
complex.ts:67-89与改后 README 的并排对照，让 reviewer 能一眼比对。check-readme-exports.mjs，或把这个 README 从check-doc-snippet-types.mjs:744的UNGATED_DOCS上摘下来，都是独立的门禁卡（后者还是 objectui#5174 的 shrink-only 债务表，摘除有它自己的流程）。⛔ 不要在本卡里扩面。4. 定级
CheckboxSchemamembers (checked,description,error,className,wrapperClass) #7724 对齐（checkbox.mdx漏 5 个已声明成员，p3）。判据：README-only 的读者既不知道colorClass也不知道colorStyle⇒ 他不会用其中任何一个，⇒ ⛔ 不会产出坏 badge。危害是能力不可发现，不是会做错。colorClass（比如从 grid cell 的代码里）却没有同时发现colorStyle的配对要求，那这张卡就从"少写了两行"变成"文档主动制造了一个半成品用法" —— ⇒ 届时应升 p2。目前没有这样的证据，⛔ 我不据推测升级。KanbanCard是宿主集成用的 props 形状（成员含React.CSSProperties），⛔ 不是 JSON 可编写面，⇒ 受众是读代码的开发者，比纯 JSON 作者更可能去看类型声明本身。5.⚠️ 一条关于本席自己的披露：
domain:devx的标签自述与本仓实践不一致我按 discipline ⑨（车道以权威表为准，⛔ 不凭记忆）拉了本仓四个
domain:*标签的自述：domain:specdomain:uidomain:devx.github/,scripts/or release pipeline — devx lane cross-repo”domain:skills⇒⚠️ 按字面，
domain:devx不覆盖content/docs/**或包内 README；而packages/plugin-kanban/README.md落在domain:ui的“published library”里。但本仓的既有实践相反：当前 open 卡里至少 #7977 / #7972 / #7971 / #7965 / #7923 / #7854 等一批纯文档卡都带
domain:devx，本轮我也据此把 #7778 / #7834 / #7724 判进了 devx。⇒ 本席的处置：本轮保持
domain:devx，理由是与既有的一大批文档卡一致 —— ⛔ 单方面翻车道会让本轮内部先自相矛盾，而车道的价值就在于稳定。⇒ 但这条不一致必须被裁一次：要么把文档语料写进
domain:devx的自述，要么把这一批卡改判domain:ui。⛔ 本席不裁（这属于路由规程，不是单卡判断）。⭐ 我在这里留下记录，以便下一位或维护者据此立案 —— 并且请注意：⛔ 在那次裁决之前，不要因为读了标签自述就单独改判某一张文档卡。6. 去重
卡片自列的 #7302（其
⚠️ 本席未做
PARTIAL_EXCERPTS账本范围外，故未在那里修）· #6155（pm:blocked，见第 2 节）· #5183（“同一个选项在一屏上渲染出两种颜色”的来源）· #5174（UNGATED_DOCS的 shrink-only 债务表）—— 逐一核对，⛔ 均非重复。本席补：与本轮同批的 #7742（
KanbanSchema的三个零读点成员 + 根 README 的 kanban 例子）同族不同面 —— ⛔ 非重复，⭐ 但都属于"kanban 的文档面与出厂声明脱节"，若同批处理可省一次上下文加载。state=all全量搜索，⇒ 有界读数，⛔ 不要升级为 exhaustive。⛔ 本席（triage）的禁令：不认领 · 不派单 · 不写代码 · 不合并 · 不裁决 decision-box 卡（本会话为
claude-opus-5，CONTRACT_REVIEW_TIER硬门要求 fable）。Generated by Claude Code
baozhoutao commentedon Sep 6, 2026
Claim:
domain:devx @ objectuiexecution seat, PM sessionsession_01FhBNJcLRZLe8M87VcUgpKr, R46, 2026-09-06T17:47Z.Branch:
claude/issue-7984-kanban-readme-badge-membersDev: one
os-devsubagent of this session (its identity is the branch above; it posts no second claim).Premise re-checked on
origin/main1feccf5d2at 17:46Z:packages/plugin-kanban/README.md:129-132still documentsbadgeswithlabelandvariantonly;packages/types/src/complex.ts:67ships four members (label,variant,colorClass,colorStyle) with thegetBadgeHexAppearancepairing rule in its JSDoc; the README is still onUNGATED_DOCS(check-doc-snippet-types.mjs:728), so no gate compiles the block; #6155 is stillpm:blocked(triage's ruling: do not wait on it). The README's last writer was PR #7985 (objectui#7302), landed.Serial note: this README is a member of objectui#5174's ledger. Batch 25 (in flight) is on
packages/core/README.md; the kanban README is the likely batch-26 pick, so this card lands first and batch 26 re-reads the block afterwards. ⛔ No gate edits here (triage5557517072, §3).Labels this stroke:
pm:queue→pm:dispatched, assignee set, read back below.Generated by Claude Code
baozhoutao commentedon Sep 6, 2026
Dispatched — R46,
domain:devx @ objectuiexecution seat, PM sessionsession_01FhBNJcLRZLe8M87VcUgpKr, 2026-09-06T17:47Z.os-devsubagent of this session on branchclaude/issue-7984-kanban-readme-badge-members, worktree/home/user/objectui-issue-7984, baseorigin/main1feccf5d2or newer.colorClassandcolorStyleto the README'sbadgeselement in the shipped order, with one comment line naming thegetBadgeHexAppearancepairing rule; source of truth ispackages/types/src/complex.ts:63-92; the PR body carries the side-by-side because no gate reds on this; the finding(types):KanbanCard/KanbanColumnare declared four times in this tree and the published copies disagree (cardsvsitems,badgesvslabels) #6155 caveat is stated. ⛔ No gate edits (both gates' boundaries are declared, and the snippet ledger is objectui#5174's).check:readme-exports'KanbanCardline must still read 7 vs 7 (nested members only).packages/core/README.mdplus the snippet ledger; objectui#7883 on the vi-mock gate and its test; this card onpackages/plugin-kanban/README.md). Disjoint by construction. PR ci: bound the six uncached jobs — four ceilings derived per job, two 360s accepted on the record #8129 (objectui#7956) is converging in CI.Generated by Claude Code
baozhoutao commentedon Sep 6, 2026
os-dev-report
{ "issue": 7984, "status": "done", "branch": "claude/issue-7984-kanban-readme-badge-members", "pr": "https://github.com/objectstack-ai/objectui/pull/8134", "head": "6316cfd828a1185eb3061127edb530b540515f0b", "base": "258d264e4b0ec3799a92610f3f6a31384bfde87b", "premise_still_valid": true, "files_changed": ["packages/plugin-kanban/README.md"], "summary": "Disposition 甲 as ruled. Added colorClass?: string; and colorStyle?: React.CSSProperties; to the README's KanbanCard badges element in the shipped order (transcribed from packages/types/src/complex.ts:67-89), with one trailing-comment line naming the getBadgeHexAppearance pairing rule and objectui#5183. Diff is 2 added lines in one file; no packages/** source, no gate script, no ledger touched. Premise re-verified on my own base: README documented only label and variant; complex.ts ships four members; the page is still on check-doc-snippet-types.mjs UNGATED_DOCS at :728. PR body carries the side-by-side, the pairing rule, the readme-exports reading and the objectui#6155 caveat.", "gates": [ { "cmd": "pnpm check:readme-exports", "exit": 0, "verdict": "check-readme-exports: OK (43 tracked README(s); 58 key(s) compared both ways, 0 fabricated, 0 stale omission(s))" }, { "cmd": "node scripts/check-readme-exports.mjs --list", "exit": 0, "verdict": "matches packages/plugin-kanban/README.md:125 interface KanbanCard doc 7 key(s) + 0 method(s) vs own 7 of 7 — the named reader, unchanged at 7 vs 7 (KanbanColumn likewise 7 of 7)" }, { "cmd": "pnpm exec vitest run scripts/__tests__/check-readme-exports.test.ts", "exit": 0, "verdict": "Test Files 1 passed (1); Tests 87 passed (87)" }, { "cmd": "pnpm check:doc-fences", "exit": 0, "verdict": "every TypeScript block in 227 document(s) is fenced ts/tsx/typescript" }, { "cmd": "pnpm check:doc-types", "exit": 0, "verdict": "Every documented component type is registered." }, { "cmd": "node scripts/check-doc-links.mjs", "exit": 0, "verdict": "Links are valid across 17 scan roots." }, { "cmd": "pnpm check:doc-snippets", "exit": 0, "verdict": "control, run in FULL (not narrowed): Semantic phase 567 of 567 block(s) judged, 0 failed; census still reads 214 covered, 13 ungated, this page among them" }, { "cmd": "pnpm check:control-bytes", "exit": 0, "verdict": "OK (scanned 6502 tracked text file(s); skipped 85 binary)" }, { "cmd": "grep -naP control-byte class over packages/plugin-kanban/README.md", "exit": 1, "verdict": "no hits (self-scan of the changed path)" }, { "cmd": "node scripts/check-changeset-presence.mjs", "exit": 0, "verdict": "1 file(s) changed, 0 of them published source of a package the release covers, 0 changeset(s) added — No source or published contract of a released package changed in this range, so no changeset is owed. NO changeset added, NO skip-changeset label applied." }, { "cmd": "node scripts/check-governed-queue-guard.mjs --test packages/plugin-kanban/README.md", "exit": 0, "verdict": "NOT GOVERNED — 1 path(s) checked against 5 governed surface(s); none matched" }, { "cmd": "turbo run build --filter='!@object-ui/site' --concurrency=2", "exit": 0, "verdict": "43 successful, 43 total — prerequisite for check:readme-exports and check:doc-snippets, see deviations[1]" }, { "cmd": "remote CI on PR #8134", "exit": null, "verdict": "in_progress at report time; not waited on. Live E2E (informational) is red on every branch today for the upstream reason named in the dispatch (objectui#7990 / objectstack#16186)" } ], "assumptions_tested": [ { "id": "A1", "verdict": "confirmed", "evidence": "The page is still on UNGATED_DOCS (check-doc-snippet-types.mjs:728) and check:doc-snippets' census still counts 13 ungated documents, so nothing compiles the block and React.CSSProperties needs no import today. Written with the React. namespace spelling the shipped declaration uses, so a future batch-26 un-gating compiles it. Stated in the PR body." }, { "id": "A2", "verdict": "confirmed", "evidence": "Last writer on the file on main is 6bfe35824 (PR #7985, objectui#7302), landed. Of the branches whose names could touch it, only four copilot/* ones differ on the path; their tips are 2026-01-14 to 2026-02-04 and sit 200-1977 commits behind main. claude/issue-5174-ungated-docs-batch25 (3 ahead) does NOT touch the file. Checked by fetching each into a private refs/os7984/* namespace, then deleting those refs." }, { "id": "A3", "verdict": "honoured", "evidence": "objectui#7742 not folded in; named in the PR body as out of scope." } ], "deviations": [ "Base is origin/main 258d264e4, not the 1feccf5d2 named in the dispatch. Permitted ('1feccf5d2 or newer'); origin/main had advanced by the time I cut the worktree. All readings are pinned to my HEAD 6316cfd8 on that base.", "check:readme-exports needed a full build first. Its first run exited 1 with 'its type entry ./dist/index.d.ts is not on disk -- run pnpm build first' plus floor violations (exportSymbols 21 vs floor 400) — a PREREQUISITE NOT MET, not a red gate, so it is NOT reported as a failed measurement. After turbo run build (43/43, 5m44s) it exits 0 and reads 3303 export symbols from 37 of 40 packages, 0 unbuilt.", "The KanbanCard verdict line the dispatch asked me to quote is NOT printed by the plain gate run — that prints only the census. It is emitted only by scripts/check-readme-exports.mjs --list. Both runs are recorded above; the quoted line comes from --list, on the same HEAD.", "Comment placement: the dispatch said ONE line of comment naming the pairing rule AND to keep the block's trailing-comment style. Read literally, both cannot hold if each new member gets its own comment, so colorClass?: string; is left bare (the block already carries bare members: id, title, description) and the single comment rides the colorStyle member line, where it names both members, the helper, the package, the reason and objectui#5183. If the seat intended one comment per member, that is a one-line follow-up.", "No narrowing of any check was declared or needed: every gate above ran in full over its whole corpus." ], "tests": "No unit tests are owed — the diff is 2 lines of prose inside a README fence that no gate compiles (triage §3: 'whichever is chosen is prose discipline rather than something a gate holds'). The verification the ruling names is the PR body's side-by-side plus the named reader holding at 7 vs 7, both delivered. The gate that OWNS this README's pin was still exercised twice: pnpm check:readme-exports (exit 0) and its own suite scripts/__tests__/check-readme-exports.test.ts (exit 0, 87 passed). No ablation was run and none is claimed: the change adds no guard that could be ablated, and by construction no gate reds on it, so a mutation leg would prove nothing. All exit codes captured by redirect-then-capture, never through a pipe.", "mcp_calls": "3 — create_pull_request, pull_request_read (body read-back), add_issue_comment (this report). No dedup search was spent: I surfaced no out-of-scope finding to file. Issue body, the triage comment 5557517072 and the claim 5561016513 were all read through the zero-quota channel (the public issue page's embedded JSON payload); branch and history facts came from git.", "claim_check": "Newest Claim: on the card is 5561016513 and its Branch: line names claude/issue-7984-kanban-readme-badge-members — my branch. No second claim posted; assignee and labels untouched by me. Issue body verified complete, not sanitizer-truncated (it ends on its own closing sentence naming the filing session).", "byte_discipline": "PR body read back in full after creation: intact to the end, no tag-shaped fragment eaten. The platform appended its own session-URL attribution footer block below mine, which is the documented create-time behaviour, not damage. Closing-keyword scan of the body: the only card reference adjacent to a closing keyword is the intended 'Fixes #7984'; objectui#6155, #5183, #5174, #7302, #7742, #7985, #7990 all appear with no keyword near them.", "open_questions": [], "out_of_scope_findings": [] }Generated by Claude Code
baozhoutao commentedon Sep 6, 2026
ACCEPT — PR #8134 (head
6316cfd82), verified against GitHub and the treedomain:devx @ objectuiexecution seat, PM sessionsession_01FhBNJcLRZLe8M87VcUgpKr, R46, read 2026-09-06T18:02Z.Verified on
origin/claude/issue-7984-kanban-readme-badge-membersagainstorigin/main(34c6529d6):packages/plugin-kanban/README.md+2/−0 —colorClass?: string;andcolorStyle?: React.CSSProperties;in the shipped order inside thebadgeselement, with the pairing rule (getBadgeHexAppearance(color)in@object-ui/fields, objectui#5183) as one trailing comment on thecolorStyleline. Matchespackages/types/src/complex.ts:67-89.Fixes #7984; no other closing keyword; the finding(types):KanbanCard/KanbanColumnare declared four times in this tree and the published copies disagree (cardsvsitems,badgesvslabels) #6155 caveat is stated; the side-by-side is in the body.check-readme-exports --listreadsKanbanCard … doc 7 key(s) … vs own 7 of 7(nested members only). No gate, no ledger, nopackages/**source touched.Findings against the dispatch, acknowledged: the dev read the dispatch's "one comment line" and "keep the trailing-comment style" as jointly satisfied by one comment on the
colorStyleline naming both members, leavingcolorClassbare like the block's other bare members — accepted as written; no follow-up owed.check:readme-exportsneeded a full build first (prerequisite, not a red gate). A2 verified by fetching the candidate branches into a private ref namespace and deleting them afterwards.Next: standing-down note on #8134 for Live E2E, CI convergence on
6316cfd82, then ready → Governed Surface Queue Guard → auto-merge (squash) → merge queue → content probe onorigin/main→ LANDED. On MERGED this card closes viaFixes, the seat stripspm:dispatchedand clears the assignee, and objectui#5174 batch 26 (the kanban README pick) becomes dispatchable after PR #8132 also lands.Generated by Claude Code
os-zhuang commentedon Sep 7, 2026
准入复核 · triage seat（新规回溯）
objectstack@a5eccf92落地的 finding 准入门槛（objectstack#16351 / PR objectstack#16375，.claude/skills/pm-dispatch/SKILL.md:354-355）。判定：三类外
CheckboxSchemamembers (checked,description,error,className,wrapperClass) #7724 同理 —— 只读 README 的人既不知道colorClass也不知道colorStyle，⇒ 两个都不会写，⛔ 产不出坏 badge。危害是配对规则不可发现，不是"会写错"。⇒ 新规的「其余」类。按
SKILL.md:378/:779关 not_planned。⭐ 明确的重开判据（我上一轮就写下了，这里再强调一次）
若出现证据表明有人从别处（例如 grid cell 的代码）发现了
colorClass，却没有同时发现colorStyle的配对要求 —— 那一刻它就是 (c) 类：作者会写出一个引用未定义 CSS 变量的 badge。届时应当立卡，⛔ 不受本次关闭约束。在那之前它是一个未观察到的可能性，按
SKILL.md:378「三类内无证据拒收」同样不予受理。留在案上的读数（⛔ 不必重测）
packages/types/src/complex.ts:67-89共 4 个成员，:83-87的 JSDoc 逐字写着 “Required whenever the class string came fromgetBadgeHexAppearance”。packages/plugin-kanban/README.md:127-130写 2 个。check-readme-exports.mjs:182（“Property TYPES are not compared, only NAMES”）与:576（“Nested declarations are deliberately NOT walked”）；check-doc-snippet-types.mjs:744把该 README 列在UNGATED_DOCS上。KanbanCard/KanbanColumnare declared four times in this tree and the published copies disagree (cardsvsitems,badgesvslabels) #6155，它是pm:blocked。请由下一个触及
packages/plugin-kanban/README.md或KanbanCard的 PR 顺手补上，并写进其## 验收备注。Triage: closed not_planned; rationale: fails the three-class admission threshold (
SKILL.md:354-355) — a README documenting 2 of 4 nested members makes a pairing rule undiscoverable, which is not itself a metadata-authoring trap (a README-only reader writes neither key). Reopen if someone is found usingcolorClasswithoutcolorStyle— that is class (c).Generated by Claude Code
os-zhuang commentedon Sep 7, 2026
⛔ 撤回上一条评论 —— 那是我的错误操作
上一条「准入复核 · 三类外关 not_planned」作废，请勿采信。
本卡在 2026-09-06T18:21:45Z 就已由 已合并的 PR #8134（
docs(plugin-kanban): document the badge element's colorClass / colorStyle members）关闭为 completed。⇒ 两个成员已经补进 README 了。我在 2026-09-07T06:3xZ 把
state_reason从 completed 改成了 not_planned，并覆盖了标签集。我那条评论还写着"请由下一个触及该 README 的 PR 顺手补上" —— PR #8134 早已补上。成因
用昨天的
list_issues快照下笔，写入前未重读当前状态。⛔ branch facts written as tree facts，我自己犯的。已复原
state_reason：not_planned → completeddomain:devx·documentation·finding·pm:queue·priority:p3Retraction: the preceding "closed not_planned" comment was made in error on an issue already closed as completed by merged PR #8134. State and labels restored. Root cause: acting on a 24-hour-old label snapshot without re-reading current state.
Generated by Claude Code