[finding] The recorded reason for refusing `headerColor` on the strict record:details schema is now obsolete — objectui#6294 makes the renderer deliver it

[os-litant]

Filed by the domain:ui @ objectui execution seat, PM session session_01Mn4BZ5AVDM81pvfij1WwM9, 2026-08-25. Unassigned and ungraded — ⛔ this seat does not touch packages/spec and does not grade for the domain:spec lane. Routing per the cross-seat rule: the work lands where the fix lands, and this one lands in spec.

Provenance: raised as an open question by the dev on objectui#6178, whose fix is objectui#6294 (draft). ⛔ Not blocking that PR — it lands independently.

The one-line criterion

@objectstack/spec refuses headerColor on the strict record:details section schema, and the recorded reason for the refusal is a renderer defect that objectui#6294 fixes. The refusal now outlives its stated justification.

The evidence

packages/spec/src/ui/component.zod.ts withholds the key, pinned by component.test.ts — "still refuses the two keys #11661 deliberately withholds". The reason recorded alongside it:

declaring it would advertise a capability the renderer does not deliver

⚠️ That was true, and it is no longer true. Measured on the objectui side while fixing #6178:

• DetailSection read the key as `bg-${value}` — a template literal. Tailwind v4 has no runtime; it scans source text for complete class tokens, and this workspace ships no bg-* safelist. ⇒ The call site contributed nothing to the compiled stylesheet. Measured, not inferred: compiling apps/console/src/index.css with that expression deleted produced a byte-identical sheet (441302 bytes, same sha256).
• ⚠️ But it was not inert in effect — it was live by accident. Both values the @object-ui/types mirror documents are present in the built console CSS today (.bg-muted, .bg-primary/10 — 2 of 227 bg-* selectors), because other files author those literals 691 and 63 times. That liveness was unversioned and moved with unrelated edits in unrelated packages.
• objectui#6294 replaces the interpolation with a lookup of complete literals declared in a file every consuming app scans, plus a bg-* pass-through. ⇒ The renderer now delivers the key because the module declares it, not because a neighbour happens to.

⇒ The capability-illusion the refusal exists to prevent is the thing that got fixed. The pin's own comment anticipates this and says a later batch must flip it consciously.

The question for the spec lane

Should the key now be declared — and over which vocabulary?

The dev's options, with its recommendation, carried verbatim in substance so the spec seat does not have to re-derive them:

• A — declare it as z.enum over the six tokens objectui#6294 ships (muted, muted/50, accent, primary/10, secondary/10, destructive/10) and narrow the @object-ui/types mirror to match. Declared = enforced: objectstack validate rejects anything else at authoring time.
• B — declare it as z.string() (mirroring today's objectui type). Keeps a pass-through escape hatch authorable, but re-advertises an open set the renderer delivers only for the enumerated half plus whatever the host app's Tailwind build happens to generate — the capability-illusion shape the refusal exists to prevent.
• C — leave the refusal standing, treat it as an objectui-only renderer key. Costs nothing now; the objectui type mirror keeps advertising a key ObjectStack authors cannot legally write.
• D — retire the key instead. Still available: zero producers author it anywhere in either repo. objectui#6294 would be reverted rather than extended.

Dev's recommendation: A. Its decisive argument is the AI-authoring axis — an enum makes it structurally hard to get wrong: an author (or an AI writing metadata) putting headerColor: 'blue-100' is rejected at authoring time instead of shipping a header that silently does not paint, which is exactly the failure mode objectui#6178 documents. B preserves that silent failure by contract.

⚠️ It flags two residual judgements as not its own: whether the vocabulary should be exactly those six (it chose tints only because CardHeader sets no foreground, so a solid bg-primary would leave the title unreadable without a paired text-*-foreground), and whether D is the stricter reading — it would not argue against D, but objectui triage already ruled the disposition there as a Bug with "make it work" as the direction, so retiring now would re-litigate a settled call in the other repo.

Back-links

• objectstack#11661 — the batch that declared three sibling section keys and withheld this one; carries the pin and the reason quoted above.
• objectui#6178 — the renderer defect · objectui#6294 — the fix (draft).

⛔ This seat does not grade, does not assign, and does not edit packages/spec.

[os-steve]

Maintainer ruling recorded — A: declare headerColor as a closed enum

Provenance: maintainer, 2026-08-26, live PM chat (decision-inbox batch 3, session session_01JANH3y7qe3MD8aLaLXci8N), verbatim: 「其他接受你的建议」 — accepting the presented recommendation A.

• packages/spec declares headerColor on the strict record:details section schema as z.enum over the six tokens objectui#6294 ships (muted, muted/50, accent, primary/10, secondary/10, destructive/10), and the @object-ui/types mirror narrows to match. Declared = enforced: objectstack validate rejects anything else at authoring time — an AI author writing headerColor: 'blue-100' is refused at compile time instead of shipping a header that silently does not paint.
• The implementing spec seat sanity-checks the six-token vocabulary once at dispatch (the tints-only reasoning: CardHeader sets no foreground, so solid backgrounds would need paired text-*-foreground) — a vocabulary adjustment within the enum shape needs no re-ruling; switching shapes (to B's open string) would.
• ⛔ B (open string — re-advertises the capability illusion), C (keep the refusal against a repaired renderer), D (retire — re-litigates objectui's settled Bug disposition) are not taken.
• The record:details sections: five more renderer-honoured keys remain undeclared by the strict section schema (title / defaultCollapsed / icon / description / headerColor) #11661 pin flips consciously, as its own comment anticipated. Precondition: verify objectui#6294 has MERGED (it was draft at filing); not merged ⇒ pm:blocked on it rather than dispatch.

State: needs-user-decision → pm:queue (domain:spec stands; Feature-class accept-set widening ⇒ clause-② discipline at that seat's dispatch).

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round R8, wave 7 — implementing the recorded ruling A (maintainer 2026-08-26, comment 5419726057, verbatim provenance 「其他接受你的建议」): declare headerColor on the strict record:details section schema as a closed z.enum over the six objectui#6294 tokens
Session: session_012xGvxcwPRTJfA7RfjXEYA4
Branch: claude/issue-12126-headercolor-enum
Worktree: objectstack-issue-12126
Domain: domain:spec
File surface: the record:details section schema in packages/spec/src/ui/** (the enum declaration), the #11661 pin (flips consciously, per its own comment's anticipation), tests, generated baselines/docs the gates demand, one changeset. The @object-ui/types mirror narrowing is the objectui leg — NOT this PR; this seat files the objectui follow-up card at ACCEPT (contract-first split). Precondition VERIFIED at claim: objectui#6294 is MERGED (2026-08-25T10:39Z, merge commit into objectui main). Stop on breach.
Container & model: M, mode:subagent, model: claude-fable-5 — clause-② per the ruling (Feature-class accept-set widening); path limb fires
Clause-②: yes
Serial constraints cleared: landing-watch PRs #12613 (kernel/cli-extension + registries) and #12614 (ui/action.zod.ts + plugin-security) — #12614 touches the SAME packages/spec/src/ui/ directory, different file (action.zod vs the record:details section schema); merge current origin/main immediately before PR and re-merge if either lands mid-flight. Parked #12206 (pm:blocked) and #12606 (contract review) — disjoint. Batch sibling #12038 is a read-only survey, zero file surface. H17 — no intersection.

---

Generated by Claude Code

[os-zhuang]

os-dev-report

{
  "issue": 12126,
  "status": "done",
  "branch": "claude/issue-12126-headercolor-enum",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/12616",
  "premise_still_valid": true,
  "summary": "Declared headerColor on the strict record:details section schema as a closed z.enum over the six objectui#6294 tokens (muted, muted/50, accent, primary/10, secondary/10, destructive/10), optional with no schema default, describe() stating the closed vocabulary and the layer fact. Sanity check the ruling delegated: read objectui/packages/plugin-detail/src/headerColor.ts at objectui origin/main — its lookup ships exactly those six tokens, so no vocabulary adjustment and no shape question. The #11661 pin flipped consciously: title-only refusal pin (comment rewritten citing this ruling) plus two new pins on the accept/reject boundary. Guidance machinery checked: no curated headerColor guidance/alias entry exists in packages/spec/src, nothing to remove for the #5013 audit. Changeset: minor on @objectstack/spec, matching the #11661 batch precedent for accept-set widening. Both landing-watch PRs (#12614, then #12613) landed mid-flight; each was merged in and the union re-run. Zero objectui edits; the @object-ui/types mirror narrowing stays with the PM's follow-up card.",
  "tests": "All via scripts/pm/os-verify-lock.sh, exit codes captured before any pipe, verdict lines quoted from the gates themselves. Union at final head 342070617 (tree clean): spec build green (check-dts-emitted 34/34); full spec suite 'Tests  11525 passed (11525)' (435 files); typecheck green incl. 'check:test-typecheck: OK — test layer compiles under packages/spec/tsconfig.test.json'; check:generated '✓ All 14 generated artifacts are up to date.'; check:authorable-surface green ('authorable-defaults/ verified against upstream 7a25e7d606b7 — 1255 default(s) unchanged'); check:spec-parsed-alias, check:engine-double-contract (OK — 689 pinned), check:where-matcher (303/303), check:query-options-erasure (ratchet holds, none new), check-nul-bytes (OK, 6978 files) all green. Reverse verification from the committed state at 410f85825: component.zod.ts reverted to base d7b3963c2, mutation confirmed on disk (grep -c 'headerColor: z.enum' = 0), both new pins turned RED as predicted (accept pin on the unrecognized key, reject pin on the issue-code mismatch), restore proven by empty git diff HEAD, direction observed: turned red. No ablation of built artifacts was needed (tests resolve src, not dist); the one dist-staleness the reverse leg caused was caught by check:generated, rebuilt, and api-surface regenerated byte-identical. Declared narrowing: remaining derived docs/parity families left to CI which runs the farm on every PR; check:type-check-debt unmoved because the edited test file sits in an existing tsc program with no ledger entry. CI on PR #12616 was in_progress at report time per the report-at-draft contract.",
  "mcp_calls": "5 — create_pull_request, pull_request_read x2 (body read-backs), update_pull_request, add_issue_comment (this report); all reads of the issue and its comments went through the zero-quota web-embedded JSON channel",
  "open_questions": [],
  "out_of_scope_findings": []
}

---

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

ACCEPT — reviewer of record: spec seat R8, session_012xGvxcwPRTJfA7RfjXEYA4. PR: #12616 (draft, head 342070617, 4 files).

Checked against the PR itself: the enum is exactly the six ruled tokens and the delegated sanity check was DONE — objectui/packages/plugin-detail/src/headerColor.ts's HEADER_COLOR_CLASSES matches one-to-one, so no vocabulary adjustment and no shape fork; the renderer's bg-* pass-through deliberately NOT declared (that is option B's capability illusion, explicitly not taken). The #11661 pin flipped consciously with its comment rewritten to cite the ruling, title stays withheld with its fork left on #11661, and the new accept/reject boundary pins cover both sides (six tokens accepted with no materialized default; blue-100 / bg-muted / solid primary/destructive refused with invalid_value at the key's path). Guidance machinery checked — no curated headerColor entry existed, nothing to remove for #5013. Reverse verification ran in the predicted direction with disk-confirmed mutation and clean restore. Changeset minor per the #11661 batch precedent. Both landing-watch PRs (#12614, #12613) were merged in mid-flight with full union re-runs each — the transient TypeScript Type Check red CI reported on intermediate head 533fc01b is superseded by the final head and is not a standing failure.

Cross-repo follow-up filed per the contract-first split (this stroke): the @object-ui/types mirror narrowing is an objectui card blocked on this PR's landing.

Clause-② enqueue gate: path + declaration limbs fire; dispatch tier claude-fable-5 = CONTRACT_REVIEW_TIER — satisfied. Landing path: ready → merge queue once every check on 342070617 is green; this seat watches to MERGED.

---

Generated by Claude Code