@micha.bigler/ui-core-micha 3.14.3 → 4.0.0

package/work-orders/THEME-4.md

@@ -1,271 +0,0 @@
-# THEME-4 — Make it impossible for a kit component to silently defeat the baseline
-
-**Target repo:** `ui-core-micha` (branch `main` — this repo has no `develop`)
-**Tier:** 3 (shared core)
-**Review:** independent `reviewer` — mandatory (new logic). **`ui_reviewer` becomes mandatory too if
-the check surfaces findings that require touching a component's rendering**, which is likely; see
-"What test 2 will probably do".
-**Version target:** the next **minor** after `THEME-3` lands — a new exported check is additive API.
-Read the published version at implementation time; do **not** hardcode a number from this file.
-**Strand:** `DS-18`, first half
-**Sequencing:** **after `THEME-3`.** See Risks — that work order is in flight in these exact files.
-
----
-
-## A. Envelope
-
-### Goal
-
-A kit component can put a property in its own `sx` that the baseline already sets as a
-`styleOverrides` default. Inline `sx` wins, so the baseline default becomes inert — the theme is
-complete, green, and has no effect.
-
-This is not hypothetical. It happened in `SHELL-3`: `MobileBottomNav` duplicated `borderTop` and
-`borderColor` inline, killing the two defaults the same work order had just registered.
-`SHELL-4` fixed it by hand and added a test asserting key-disjointness for that one component
-(`tests/MobileBottomNav.test.jsx:215`). **Make that mechanical for the whole kit.**
-
-### Why the whole kit, measured
-
-- **51 `.jsx` files under `src/` carry an `sx=` prop.**
-- **The baseline styles 23 MUI component keys** — `MuiAlert`, `MuiBottomNavigation`,
-  `MuiBottomNavigationAction`, `MuiButton`, `MuiCard`, `MuiCheckbox`, `MuiChip`, `MuiContainer`,
-  `MuiCssBaseline`, `MuiDialog`, `MuiDivider`, `MuiDrawer`, `MuiFilledInput`, `MuiFormControlLabel`,
-  `MuiIconButton`, `MuiInput`, `MuiMenu`, `MuiOutlinedInput`, `MuiPaper`, `MuiSelect`,
-  `MuiTableCell`, `MuiTextField`, `MuiTooltip`.
-- `SHELL-4`'s test covers **one** component pair. The other 50 files are unchecked.
-
-`MobileBottomNav` was not special. `ChartFrame`, `UserMenu`, `LoginForm`, `PageLayout` and the input
-managers all render MUI components the baseline styles **and** carry their own `sx`.
-
-### Why the assertion cannot see this
-
-`assertThemeComplete` proves the theme **has** a value; nothing proves any component **uses** it.
-And a hex-value grep does not catch it either, because the duplicated value is usually *correct* — it
-is in the wrong layer, not the wrong colour. Reviewing for "no hardcoded colours" passes it. The one
-thing that caught it was a human reading a diff.
-
-### Scope
-
-**1. A convention, already demonstrated.** A kit component that carries its own `sx` for a MUI
-component the baseline styles **exports that `sx` object**. `MobileBottomNav` already does
-(`MOBILE_BOTTOM_NAV_ROOT_SX`, `MOBILE_BOTTOM_NAV_ACTION_SX`) — follow that shape rather than
-inventing a second one. A small registry maps each exported object to the MUI key it targets.
-
-**2. An exported check.** Same finding contract as the existing assertion —
-`{ findings: [{ surface, reason }] }` — so consumers and tests handle one shape, not two. For each
-registry entry, assert the key sets of the component's `sx` and the baseline's `styleOverrides` for
-that MUI key are **disjoint**. A collision names the component, the MUI key and the property.
-
-**3. A bypass check, so the convention cannot be skipped in silence.** A source-level scan that flags
-a kit component file containing an inline `sx={{ … }}` object literal which is not exported.
-**Precedent in this repo:** `reportThemeAdoption(sources)` already takes source strings and regexes
-them for `createTheme(` versus `createAppTheme(` — same module, same shape, so this is an established
-pattern here rather than a new mechanism.
-
-**4. Wire it as a hard failure in ucm's own suite.**
-
-**This check cannot turn any consuming app red.** It is entirely internal: ucm's components against
-ucm's baseline, run in ucm's tests. An earlier concern that a new invariant might break cockpit's
-fresh adoption was raised and, on designing it, does not apply — an app's *own* components shadowing
-the baseline is the broader case and is a named follow-up below.
-
-### What test 2 will probably do, and what to do about it
-
-**Expect findings.** 51 files have never been checked against 23 styled component keys. A clean first
-run would be a pleasant surprise, not the base case.
-
-- **Each finding is resolved by `SHELL-4`'s rule: one home per property.** The component owns what
-  keeps it functional on any theme; the theme owns what makes it look like this estate. A property in
-  both layers is the defect.
-- **Do not exempt your way to green.** The exemption arm exists for a component that genuinely must
-  override the baseline for its own purpose, with a stated reason — the same contract
-  `assertThemeComplete` uses, where an exemption without a reason is itself a finding. A mass
-  exemption converts this work order into a no-op.
-- **If the finding count is large enough that fixing them all exceeds this work order, stop and
-  report** with the list. Splitting into "land the check plus the fixes it can absorb" and "the
-  remainder as a follow-up" is a scope decision for the operator, not something to absorb silently.
-
-### Non-goals / do not touch
-
-- **`DS-18`'s second half — "which components *can violate* a rule".** That is the shadow-array idea:
-  nine MUI components read `shadows[…]`, three are declared, six would become findings. It is
-  deliberately **out of scope** because it rests on a `grep 'shadows\['` **lower bound** and its
-  findings demand *new* theme entries — pressure toward the gold-plating the estate's YAGNI guardrail
-  rejects. Follow-up, with the heuristic labelled as a lower bound wherever it appears.
-- **App-side scanning.** An app's own components can shadow the baseline too (a `Header` putting
-  `borderColor` in `sx` over a `MuiAppBar` default). Real, and a follow-up — `reportThemeAdoption`
-  already shows the shape for it.
-- **No rendering-based check.** Asserting that each of 23 components tracks a changed theme needs a
-  fixture per component: expensive, fragile, and not what this WO buys. `SHELL-4`'s cross-theme
-  render test stays the pattern for individual components.
-- **No baseline token or component-default change**, unless a finding forces one — and then it is a
-  fix, listed, not a redesign.
-- No change to `assertThemeComplete`'s own surface registry, `createAppTheme`'s signature, or any
-  component's public props.
-
-### Risks
-
-- **`THEME-3` is in flight in this repo right now.** Verified: `src/theme/tokens.js`,
-  `src/theme/themeCompleteness.js`, `tests/createAppTheme.test.js` and
-  `tests/themeCompleteness.test.js` are all modified in the working tree with Codex running. **Those
-  are exactly this work order's files.** Do not start concurrently: let `THEME-3` land and publish,
-  then `git pull` and work from that state. Check `git status` and `git log origin/main..HEAD` first.
-- **The convention is only as strong as its adoption**, which is what item 3 exists to guarantee. If
-  item 3 is dropped, the check degrades to "whatever someone remembered to export".
-- **Known bound, state it in the code rather than discovering it later:** the check sees only `sx`
-  objects a component exports, at their top level. A **conditional or nested** `sx` is not covered —
-  `MobileBottomNav`'s own `emphasis` circle is exactly such a case. This is a lower bound on
-  shadowing, not coverage, and must be documented as such so nobody reads green as proof.
-- **No staging net.** A version bump on `main` publishes to npm; the independent review is the only
-  gate and cannot be back-filled.
-
-### Required tests to WRITE
-
-1. **Non-vacuity, reconstructing the real incident.** A fixture component whose exported `sx`
-   duplicates a baseline `styleOverrides` key produces a finding naming the component, the MUI key
-   and the property. This is `SHELL-3`'s arrangement; the test must fail if the check is inert.
-2. **The current kit.** Run the check across the whole registry and assert the result is empty —
-   after fixing whatever it legitimately finds (see above).
-3. **The bypass check** flags an inline non-exported `sx={{ … }}` in a fixture source string and does
-   **not** flag an exported one.
-4. **The exemption contract matches the existing one:** an exemption with a reason suppresses exactly
-   one finding; an exemption without a reason is itself a finding.
-5. `SHELL-4`'s existing `MobileBottomNav` disjointness test still passes, and is **not** replaced by
-   the generic check — the specific test documents that component's split, the generic one guards the
-   kit. Keeping both is deliberate.
-
-Plus `tsc -p tsconfig.build.json --noEmit` clean. **No full-suite run** — the affected set is the
-theme module's specs plus any component spec a fix touches.
-
-### Verification
-
-Static work with no visual surface of its own, so the standing rendered gate does not apply **unless
-a finding forces a component change** — then the two-width side-by-side applies to that component,
-and `ui_reviewer` becomes mandatory alongside it. Say in the register note which of the two happened.
-
-The check's own value is proven by test 1, not by a screenshot: a check that cannot fail is worth
-nothing, and that is the assertion this work order actually has to make about itself.
-
-### Parity guardrail
-
-No intended change to any rendered output. If the kit renders differently after this work order, it
-is because a real shadowing defect was fixed — and every such change must be listed in the register
-note, not folded in as tidying.
-
----
-
-## B. Implementation map
-
-*Filled by the Orchestrator on `git pull` — see `AGENTS.md` → "Work Order".*
-
-### Execution directive (read this first)
-
-> **If you are the implementer reading this work order as your own specification: this section is
-> NOT addressed to you.** It tells the Orchestrator how to invoke you. **You ARE that invocation —
-> do NOT shell out to `codex exec`.**
->
-> Implement through `codex exec` in the background — invoked directly via Bash (never the
-> `debugger`/`*_coder` Agent wrappers) with BOTH flags `--skip-git-repo-check` and
-> `--dangerously-bypass-approvals-and-sandbox`. **Pass the WO via stdin, not as a positional
-> argument** (a positional arg hits Windows' command-line length limit — proven repeatedly in this
-> repo). Fallback to direct Claude implementation only on Codex quota/rate-limit/non-zero exit — and
-> note that the fallback flips authorship, so the independent `reviewer` stays mandatory either way.
->
-> **Two things this repo has learned the hard way, both on the two immediately preceding work
-> orders:** Codex committed its own change and wrote a self-reported review into
-> `WORK_ORDERS.md` on `SHELL-3` **and** on `SHELL-4`. Read `git log origin/main..HEAD` and
-> `git status` before your own review; an implementer commit is a blocker to surface, and a register
-> row naming a review the Orchestrator did not itself start is invalid.
-
-### Context package
-
-**Precondition confirmed:** `THEME-3` is landed and published (`1b25117`, register row `done`).
-`git log --oneline -3` at hand-off time shows the Orchestrator's own docs commits on top of it, no
-implementer commit — clean to start from.
-
-**The established `sx`-export convention (scope item 1's shape to follow), already shipped in
-`src/components/MobileBottomNav.jsx`:**
-```js
-export const MOBILE_BOTTOM_NAV_ROOT_SX = {
-  position: 'fixed', left: 0, right: 0, bottom: 0,
-  borderTop: '1px solid', borderColor: 'divider',
-  paddingBottom: 'env(safe-area-inset-bottom)',
-};
-export const MOBILE_BOTTOM_NAV_ACTION_SX = { minWidth: 0, maxWidth: 'none' };
-```
-Both are plain top-level `export const` object literals, used directly as (or spread into) the
-`sx` prop on the MUI element they style. This is the shape the registry (item 1) should match
-against — a component "carries its own `sx` for a MUI component the baseline styles" means: look for
-`<BottomNavigation`, `<Button`, `<Card`, etc. (the 23 baseline-styled MUI component names) receiving
-an `sx=` prop inside `src/**/*.jsx`, then check whether that `sx` is a top-level exported identifier
-(covered) or an inline/conditional literal (item 3's bypass check should flag the latter if it isn't
-exported).
-
-**The exemption contract to mirror exactly (scope item 2 + required test 4), from
-`src/theme/themeCompleteness.js:333-350` (`assertThemeComplete`):**
-```js
-export function assertThemeComplete(theme, { exemptions = [] } = {}) {
-  const declaredExemptions = [...(theme?.themeCompleteness?.exemptions || []), ...exemptions];
-  const validExemptions = new Set();
-  const findings = [];
-  for (const exemption of declaredExemptions) {
-    if (!exemption?.surface || !exemption?.reason?.trim()) {
-      findings.push({ surface: `exemption.${exemption?.surface || 'unknown'}`,
-        reason: 'A completeness exemption must name a surface and include a reason.' });
-      continue;
-    }
-    validExemptions.add(exemption.surface);
-  }
-  ...
-}
-```
-The new check's `{ findings: [{ surface, reason }] }` return shape and exemption handling should be
-structurally identical to this, not a reinvention — same two failure modes (missing reason is itself
-a finding; a valid exemption suppresses exactly one finding).
-
-**The bypass-check precedent (scope item 3), from `src/theme/themeCompleteness.js:370-379`
-(`reportThemeAdoption`):**
-```js
-export function reportThemeAdoption(sources = []) {
-  const normalized = sources.map((entry, index) => typeof entry === 'string'
-    ? { path: `source-${index + 1}`, source: entry }
-    : { path: entry.path || `source-${index + 1}`, source: entry.source || '' });
-  const themeBypassPaths = normalized
-    .filter(({ source }) => /\bcreateTheme\s*\(/.test(source) && !/\bcreateAppTheme\s*\(/.test(source))
-    .map(({ path }) => path);
-  ...
-}
-```
-Same module, same input shape (an array of `{ path, source }` or raw source strings), same
-regex-over-source-text technique — the new bypass check takes the same input shape and regexes for
-an inline `sx={{ ... }}` object literal that is not a reference to a top-level exported identifier.
-
-**Where to put the new code:** co-locate in `src/theme/themeCompleteness.js` alongside
-`reportThemeAdoption` (the WO's own "same module" language for item 3), or a new sibling file if
-the additions make that file unwieldy — Codex's call, but export everything new from
-`src/theme/index.js` and `src/index.js` (follow the existing export list pattern in both) so the
-check is part of the public API per the WO's "additive API is a minor" versioning note.
-
-**Discovery is the actual task, not pre-solved here:** the WO's own measurement (51 `.jsx` files
-under `src/` carry `sx=`, baseline styles 23 MUI keys) is a starting estimate, not a fixed list —
-grep `src/**/*.jsx` for `sx=` against the 23 keys named in the Envelope's "Why the whole kit,
-measured" section to build the actual registry. This is scope item 1 itself; do not skip it by
-registering only `MobileBottomNav`'s two already-known exports.
-
-**On the "stop and report if large" clause:** if fixing every real finding from test 2 would grow
-this WO well beyond a layer-relocation pass (i.e. touches component *behaviour*, not just moving an
-`sx` value into an export), STOP before committing anything and report the finding list instead of
-silently absorbing it all — this is explicitly named in the Envelope as an operator-level scope
-decision, not an implementer judgment call.
-
-**Known repeat-offense warning, restated because it has happened on the two immediately preceding
-work orders in this exact repo:** do not run `git commit` or `git push` under any circumstance. Leave
-the diff for the Orchestrator. If you find yourself about to commit "because everything passed", stop
-— that decision is not yours in this workflow, regardless of how clean the result looks.
-
-### Mini-handover
-
-Repo: `ui-core-micha` (`C:\Users\biglmi\Documents\webapps\ui-core-micha`), branch `main`.
-WO: `work-orders/THEME-4.md`. **Wait for `THEME-3` to land and publish first** — same files.
-Follow `orchestrate-codex`.

package/work-orders/THEME-5.md

@@ -1,341 +0,0 @@
-# THEME-5 — Hold the kit to its own baseline
-
-**Target repo:** `ui-core-micha` (branch `main` — this repo has no `develop`)
-**Tier:** 3 (shared core)
-**Review:** independent `reviewer` **and** `ui_reviewer` — both mandatory, concurrent. `ui_reviewer`
-applies because rendered colours change in a screen **ten apps mount**; see "Blast radius".
-**Version target:** the next **minor** after `THEME-4` — a new exported check is additive API. Read the
-published version at implementation time; do **not** hardcode a number from this file.
-**Strand:** `DS-18` follow-ups, both named in `THEME-4`'s landing notes
-
----
-
-## A. Envelope
-
-### Goal
-
-Two gaps left open by `THEME-4`, and they belong together because both are the same embarrassment:
-**the kit is not fully on the baseline it exists to enforce.**
-
-1. `THEME-4`'s shadowing check normalises **spacing** shorthands only. Other MUI `sx` aliases —
-   `bgcolor` above all — still compare as raw strings and would miss a collision.
-2. The kit carries **off-palette colour values**. No app palette reaches them.
-
-### Part 1 — finish the alias normalisation
-
-`SPACING_SHORTHAND_LONGHANDS` (`src/theme/themeCompleteness.js:383`) covers `p*` and `m*`. Extend the
-map to every MUI `sx` alias that can land on a property the baseline sets — `bgcolor` →
-`backgroundColor` is the one with a real near-term risk.
-
-**Verified state, so nobody hunts for a bug that is not there yet:** `MFA_ACTIVE_CARD_SX =
-{ bgcolor: '#f0fdf4' }` is registered against `MuiCard` (`kitSxRegistry.js:190`), and the baseline
-sets `borderRadius`, `boxShadow` and `borderColor` on `MuiCard` — **not** `backgroundColor`. So there
-is **no live collision today**. This is a latent gap whose trigger is near: `THEME-3` has just shown
-the surface-token set still grows, and the day a `backgroundColor` default lands on `Paper` or `Card`
-the miss becomes silent.
-
-**Write the bound as an open one.** `THEME-4`'s WO named its own limits as a list — nested and
-conditional `sx` — and the first real miss was something not on that list (alias spelling). Say
-"unknown normalisation gaps remain" rather than enumerating, because an enumeration reads as
-completeness.
-
-### Part 2 — an off-palette colour scan, and fix what it finds
-
-A new exported check, same finding contract as the others (`{ findings: [{ surface, reason }] }`),
-scanning `src/**` for colour values that are not baseline tokens. Wire it as a hard failure in ucm's
-own suite.
-
-**Three classes, and a hex-only scan catches just the first:**
-
-| Class | Example | In scope |
-|---|---|---|
-| Hex literal | `bgcolor: '#f5f5f5'` | **yes** |
-| Named CSS colour | `bgcolor: 'white'` (`MFAComponent.jsx:231`) | **yes** — same defect, invisible to a hex scan |
-| MUI default-ramp reference | `bgcolor: 'grey.50'` (`QrSignupManager.jsx:340`) | **report only, do not fix** |
-
-The third class routes through the theme, so it is not off-palette in the same way — but it points at
-MUI's untouched grey ramp rather than at anything the estate decided. Report it as its own category
-and leave the decision for later; folding a judgement call into a cleanup would be scope creep.
-
-**Excluded from the scan, by operator decision:** the **generated print document** in
-`QrSignupManager.jsx:185-240`. It is not app UI — it is a standalone HTML string with its own `body`,
-`@media print` rules and `font-family: Arial`, rendered outside the React tree where **no theme is
-available**. Its ten values (`#f5f7fb`, `#d9e2f2` ×3, `#e8f0ff`, `#f8faff`, `#ffffff` ×3, `#122033`,
-`#23408e`) cannot take tokens. Excluding it is a correctness requirement, not a preference: scanning it
-would produce ten permanent false positives, and exempting those one by one is exactly the
-mass-exemption that `THEME-4` warned turns a check into a no-op. **Exclude the region and state the
-reason in the code.** Making the printed poster follow each app's identity is a genuine idea and a
-separate work order — not this one.
-
-### The mappings, decided and each verified against `tokens.js`
-
-Five values in `MFAComponent.jsx`:
-
-| Where | Today | Target | Why |
-|---|---|---|---|
-| `:25` `MFA_ACTIVE_CARD_SX` background | `#f0fdf4` | `success.bg` (`#E5F4E9`) | light green tint marking the active factor |
-| `:231` border | `1px solid #eee` | `divider` | it is a border |
-| `:231` background | `bgcolor: 'white'` | `background.paper` | the named-colour case |
-| `:244` background | `bgcolor: '#eee'` | `background.subtle` (`#F4F5F6`) | **a fill, not a border** |
-| `:303` background | `bgcolor: '#f5f5f5'` | `background.subtle` (`#F4F5F6`) | near-exact match |
-| `:314` border | `1px solid #ddd` | `divider` | it is a border |
-
-**`#eee` appears in two different roles** — a border at `:231` and a **fill** at `:244`. A blind
-find-and-replace would put a translucent border colour (`rgba(33,37,41,.10)`) into a filled box, which
-is semantically wrong and visually lighter than intended. Map by role, not by value.
-
-### Blast radius, and the operator's decision on it
-
-No app imports `MFAComponent` directly — it is reached transitively: `AccountPage` renders
-`SecurityComponent` (`AccountPage.jsx:223`) which renders `MFAComponent`, and **at least ten apps
-mount `AccountPage`** — bigler-consult, cockpit, fitness-monitor, hpc-bridge, hram, innoservice,
-jg-ferien, kerzenziehen, reimbursements. This is live, widely-mounted code, not a dead corner.
-
-**Operator decision: map the values, and do not add a rendered gate for it.** The targets are near
-neighbours of the values they replace, and the estate has no prototype for this screen to compare
-against. **Do not re-add the two-width check** — but every changed value **must be listed in the
-register note**, so a shift that lands unseen is at least recorded. That listing is the substitute for
-looking.
-
-### Non-goals / do not touch
-
-- **The print document** (above). Excluded, unchanged.
-- **`grey.*` references.** Reported, not fixed.
-- **`DS-18`'s second half** — "which components can violate a rule". Still without a driver, and
-  `THEME-4` is now a cautionary data point for it: a check whose set comes from a heuristic can be
-  green while missing real cases.
-- **App-side scanning.** An app's own components shadowing the baseline stays a follow-up; it wants
-  cockpit's adoption first so there is a real consumer to test against.
-- No baseline token change. Part 2 consumes tokens; it does not add any.
-- No change to `assertThemeComplete`'s surface registry, `createAppTheme`'s signature, the
-  `kitSxRegistry` entries, or any component's public props.
-- `chartLabels.js`'s hex values are **baseline tokens** — leave them; if the scan flags them, the scan's
-  allowlist is wrong, not the file.
-
-### Risks
-
-- **A visual change in ten apps, published without a staging net.** A push to `main` touching `src/**`
-  publishes; the independent reviews are the only gate. The mitigation is the mandatory value listing,
-  plus `ui_reviewer` reading the diff against the mapping table above.
-- **Mapping by value instead of by role** — the `#eee` trap. The table above exists so this is a
-  checkable instruction rather than a matter of care.
-- **An over-eager scan.** `src/theme/` legitimately contains every token's hex definition, and
-  `chartLabels.js` consumes them. A scan without a correct allowlist floods the suite and gets
-  disabled, which is worse than no scan.
-- **Wrong allowlist shape.** The allowlist must be derived from the palette rather than hand-listed, or
-  it goes stale the next time a token lands — `THEME-3` added one three days into this strand.
-
-### Required tests to WRITE
-
-1. **Non-vacuity for the scan:** a fixture source containing `bgcolor: '#123456'` produces a finding;
-   the same source using a palette token produces none.
-2. **The named-colour class:** `bgcolor: 'white'` is flagged. This is the case a hex-only scan misses,
-   and it exists in the code today.
-3. **The exclusion holds:** the print-document region produces **no** findings, and the exclusion is
-   scoped — a hex added elsewhere in `QrSignupManager.jsx` **is** still flagged.
-4. **The allowlist is palette-derived:** adding a token to the palette makes a source using that value
-   pass, without editing the check.
-5. **Part 1:** a fixture whose `sx` uses `bgcolor` collides with a baseline `backgroundColor` default
-   and is reported. Prove non-vacuity — this must fail before the map is extended.
-6. `MFAComponent`'s existing spec stays green, and `THEME-4`'s shadowing check still returns no
-   findings for the kit.
-
-Plus `tsc -p tsconfig.build.json --noEmit` clean. **No full-suite run** — affected set is the theme
-module's specs plus `MFAComponent`'s.
-
-### Verification
-
-No rendered gate, per the operator decision above. What replaces it: the mapping table is the spec, and
-the register note must list **every value changed, from and to**. If the implementation deviates from
-the table for any of the six rows, that is a stop-and-report — the roles were resolved by reading the
-code, and a different target means the reading was wrong.
-
-### Parity guardrail
-
-Six values change in one component; everything else in the kit renders identically. No behaviour, no
-props, no permissions, no data contract.
-
----
-
-## B. Implementation map
-
-*Filled by the Orchestrator on `git pull` — see `AGENTS.md` → "Work Order".*
-
-### Execution directive (read this first)
-
-> **If you are the implementer reading this work order as your own specification: this section is
-> NOT addressed to you.** It tells the Orchestrator how to invoke you. **You ARE that invocation —
-> do NOT shell out to `codex exec`.**
->
-> Implement through `codex exec` in the background — invoked directly via Bash (never the
-> `debugger`/`*_coder` Agent wrappers) with BOTH flags `--skip-git-repo-check` and
-> `--dangerously-bypass-approvals-and-sandbox`. **Pass the WO via stdin, not as a positional
-> argument** (a positional arg hits Windows' command-line length limit — proven repeatedly in this
-> repo). Fallback to direct Claude implementation only on Codex quota/rate-limit/non-zero exit — and
-> note that the fallback flips authorship, so both reviewers stay mandatory either way.
->
-> **Read `git log origin/main..HEAD` and `git status` before your own review.** On `SHELL-3` and
-> `SHELL-4` Codex committed its own change and wrote a self-reported review into `WORK_ORDERS.md`;
-> `THEME-4` was the first of the three where it did not. An implementer commit is a blocker to
-> surface, and a register row naming a review the Orchestrator did not itself start is invalid.
-
-### Context package
-
-**Precondition confirmed:** `THEME-4` is landed and published (`c64e024`, register row `done`,
-`package.json` reads `2.34.0`). Clean starting state, no implementer commit on top.
-
-**Note on the WO's own arithmetic:** the Envelope's "Five values in `MFAComponent.jsx`" heading is
-followed by a table of **six** rows (`:25`, `:231`×2, `:244`, `:303`, `:314`) — the register's own
-summary already says "the six values it finds", so treat the table (six rows) as authoritative, the
-heading as stale, consistent with two prior stale-count mismatches in this strand (`SHELL-4`'s
-"ten to six", `THEME-4`'s "51 files").
-
-**A likely seventh value the table omits — verify before assuming the table is exhaustive:**
-`src/components/MFAComponent.jsx:313` has `bgcolor: 'white'` in the *same* sx object as the WO's row 6
-(`:314`, `border: '1px solid #ddd'` → `divider`) — a recovery-code chip box, structurally identical in
-role to row 3 (`:231`'s `bgcolor: 'white'` → `background.paper`, the QR-code box). If the new scan (Part
-2) flags `:313` and it is not in the six-row table, this is not a table deviation to stop-and-report —
-it is the same white-box-fill role already established at `:231`, map it identically to
-`background.paper` and list it in the register note as a seventh, table-omitted finding the scan
-caught. Confirm this reading against the actual code before implementing; do not assume the six-row
-table is exhaustive just because the Envelope calls it "decided".
-
-**Current file state (verified, so Codex works from real line numbers, not the WO's possibly-drifted
-ones):**
-```
-src/components/MFAComponent.jsx:25   export const MFA_ACTIVE_CARD_SX = { bgcolor: '#f0fdf4' };
-src/components/MFAComponent.jsx:231  <Box sx={{ p: 2, bgcolor: 'white', border: '1px solid #eee' }}>
-src/components/MFAComponent.jsx:244        bgcolor: '#eee',              (inside a multi-line sx, role: fill)
-src/components/MFAComponent.jsx:303  <Box sx={{ bgcolor: '#f5f5f5', p: 2, borderRadius: 1 }}>
-src/components/MFAComponent.jsx:313        bgcolor: 'white',             (inside a multi-line sx -- the omitted 7th)
-src/components/MFAComponent.jsx:314        border: '1px solid #ddd',
-```
-All six table rows' line numbers matched exactly on inspection — no drift.
-
-**Token values to map to, confirmed against `src/theme/tokens.js`:**
-- `divider: 'rgba(33,37,41,.10)'` (`tokens.js:69`)
-- `background.paper: '#FFFFFF'` / `background.default: '#FAFAFA'` (`tokens.js:65-66`)
-- `background.subtle: '#F4F5F6'` (`tokens.js:67`, landed by `THEME-3`)
-- `success.bg: '#E5F4E9'` (`tokens.js:80`)
-These are accessed in a component via `theme.palette.<path>`, i.e. `sx={{ bgcolor: 'divider' }}` /
-`sx={{ bgcolor: 'background.subtle' }}` / `sx={{ bgcolor: 'success.bg' }}` (MUI resolves a dotted
-palette-path string in `sx`) — this is the same string-token-reference pattern already used and
-proven in `SHELL-4`'s `borderColor: 'divider'` fix. Do **not** import raw hex constants.
-
-**Part 1 — extend `SPACING_SHORTHAND_LONGHANDS` (`src/theme/themeCompleteness.js:383`,
-`expandShorthandProperty` at :402):** add a `bgcolor` → `['backgroundColor']` entry (and, while
-touching this, consider whether `color`/other MUI palette-path aliases need the same treatment — the
-WO names `bgcolor` as "the one with a real near-term risk", so that is the required minimum; do not
-expand the alias table beyond what's verifiably a real MUI `sx` shorthand, to avoid the "write the
-bound as an open one" instruction turning into an unbounded audit). Required test 5 (non-vacuity):
-a fixture registry entry with `sx: { bgcolor: '#fff' }` against a MUI key whose baseline
-`styleOverrides` sets `backgroundColor` must be flagged — construct this as a **fixture-only** test
-(pass a custom `registry` + a fixture theme/component config to `assertKitSxDisjoint`, following the
-existing fixture pattern already in `tests/themeCompleteness.test.js`'s `'kit sx disjointness'`
-describe block, e.g. the `FixtureBottomNav`/`FixtureChip`/`FixtureButton` entries) since, per the
-Envelope, there is genuinely no live `backgroundColor` collision in the real kit today — do not invent
-one in the real registry just to exercise the code path.
-
-**Part 2 — the off-palette colour scan.** New exported function in
-`src/theme/themeCompleteness.js` (same file, same `{ findings: [{ surface, reason }] }` contract as
-`assertThemeComplete`/`assertKitSxDisjoint`/`reportKitSxBypasses` — name it something like
-`reportOffPaletteColours`, Codex's call). Reuse the existing hand-rolled brace/quote-aware source
-scanning approach already proven in `reportKitSxBypasses` (`themeCompleteness.js`, functions
-`jsxOpeningTag`/`topLevelSxValue` and the `sources.map(...)` normalisation shape shared with
-`reportThemeAdoption`) rather than inventing a second scanning mechanism.
-
-**Two known false-positive traps for the colour regex, found while preparing this map — test against
-both explicitly:**
-1. `src/components/charts/chartLabels.js:3-4` has a comment referencing GitHub issue numbers
-   `mui-x#18768` and `#18399` — a naive `/#[0-9a-f]{3,8}/i` pattern matches `#18768` as a false "hex
-   literal" (all five characters `1,8,7,6,8` are valid hex digits). The scan must not flag comment
-   text, or must otherwise be precise enough to skip this. This is exactly the "over-eager scan...
-   gets disabled" risk the Envelope names — verify the scan is blind to this file/line before calling
-   Part 2 done.
-2. `src/theme/createAppTheme.js:45` has a comment mentioning `'#FFFFFF'`, and `:188` has a genuine
-   `'#FFFFFF'` string literal used for contrast-ratio computation (not a component style) — per the
-   Envelope's own risk note, `src/theme/` legitimately contains token hex definitions and must be
-   excluded from the scan's target set entirely (scan `src/components/`, `src/messaging/`,
-   `src/notifications/`, `src/pages/`, `src/auth/`, `src/layout/`, `src/onboarding/` — i.e. component
-   source, not `src/theme/` itself).
-
-**The palette-derived allowlist (required test 4):** build the allowlist by walking
-`BASELINE_PALETTE`/`BASELINE_STATIC` (or the fully-resolved output of `createAppTheme(...)`) and
-collecting every hex/rgba string value found in it, rather than hand-listing values — this is what
-required test 4 (adding a token to the palette should make a source using that value pass, without
-editing the check) actually proves. `THEME-3` is cited in the Envelope as evidence a hand-listed
-allowlist goes stale fast (a new baseline token landed three days into this strand).
-
-**Named-CSS-colour detection (required test 2):** `bgcolor: 'white'` must be flagged same as a hex
-literal — CSS named colours are a small, fixed, enumerable set (`white`, `black`, `red`, `grey`,
-etc. — the 16 basic CSS colour keywords are the practical minimum; do not attempt to support the full
-147-name X11/CSS list unless a real instance demands it, per the WO's own anti-gold-plating stance).
-
-**The `grey.*` report-only class (required, do not fix):** `src/components/QrSignupManager.jsx:340`
-has `bgcolor: 'grey.50'` — this is a **dotted MUI theme-path string**, not a hex/named-colour literal,
-so it needs its own detection branch (match `/^[a-z]+\.\d+$/i`-shaped sx string values referencing
-MUI's stock palette ramps, distinct from both the hex/named-colour findings and the
-divider/background.subtle/success.bg *baseline* token-path strings this same WO is busy introducing
-elsewhere — do not let the scan flag the very token references Part 1's own fixes create). Report it
-under a distinct `reason` wording (e.g. "uses MUI's untouched grey ramp, not a baseline token — review,
-do not auto-fix") so a consumer of the findings can filter report-only from must-fix.
-
-**The print-document exclusion (required test 3):** exclude the template-literal region inside
-`QrSignupManager.jsx`'s `printWindow.document.write(\`...\`)` call — currently spans roughly
-`:178`-`:266` (verify exact bounds by locating the `printWindow.document.write(` call and its
-matching closing backtick+paren, not by trusting these line numbers, since the WO's own `:185-240`
-estimate was already off by several lines against the current file). The exclusion must be scoped
-narrowly enough that a hex literal added elsewhere in the same file (outside that one template
-literal) still gets flagged — required test 3's second half.
-
-### Invariants / do-not-touch
-
-No change to `assertThemeComplete`'s surface registry, `createAppTheme`'s signature, `kitSxRegistry`
-entries structure, or any component's public props. No baseline token added (Part 2 consumes existing
-tokens only). `chartLabels.js`'s own values are not colours to fix (see trap above) — if the finished
-scan flags anything in `src/theme/**`, that is a scan-scope bug, not a file to edit.
-
-### Addendum — operator decision on the scan's broader findings (chunk 2)
-
-The first implementation chunk correctly stopped without committing and reported a real scope
-question instead of deciding it: with the off-palette scan's detection widened beyond hex + basic
-named colours (per Part 2), it also catches two values **outside `MFAComponent`**, which the
-Envelope's Parity guardrail ("six values change in one component; everything else in the kit renders
-identically") did not anticipate:
-
-1. `src/components/SocialLoginButtons.jsx:37` — `border: '1px solid rgba(0,0,0,0.2)'` on the Google
-   icon circle. A real rendered `sx` border, same class of finding as the MFA border fixes.
-2. `src/components/charts/exportChart.js:48` — `context.fillStyle = 'white'` inside a **Canvas 2D API
-   call** (PNG export), not JSX/`sx` — structurally like the already-excluded print document in that it
-   runs outside the React/theme tree, but unlike it, plumbing a resolved colour in is straightforward
-   (the caller has `useTheme()` access; a colour can be passed as a parameter to the export function).
-
-**Operator decision (this session): fix both**, per Codex's own recommended option. This is an
-explicit, approved widening of scope beyond the original Envelope's blast radius — record it as such
-in the register note, do not fold it in as if the original Envelope already covered it.
-
-**Scope of the fix:**
-- Widen the scan's colour detection to catch `rgba(...)` literals (not just hex + the basic named-colour
-  set), so this class is caught mechanically going forward, not just this one instance.
-- `SocialLoginButtons.jsx:37`: map to `divider` (the same token every other border-role finding in this
-  WO maps to) — confirm this reads correctly next to the icon (a translucent, lighter border than the
-  current `rgba(0,0,0,0.2)`; this is the intended effect of holding to the baseline, not a regression).
-- `exportChart.js:48`: resolve the fill colour from the theme at the call site (the component invoking
-  the export utility has `useTheme()`), and pass it into `exportChart`'s existing call rather than
-  hardcoding a new default inside the utility — check `exportChart.js`'s current signature and its
-  caller(s) (`ChartFrame.jsx`, most likely) before deciding the exact parameter shape; prefer the
-  smallest signature change that removes the hardcoded literal, not a redesign of the export API.
-- Both new value changes must be listed in the register note the same way as the seven MFA values
-  (from → to, with role), per the Envelope's "every changed value must be listed" requirement, which
-  the operator's decision extends to cover these two as well.
-- Re-run both reviewers (`reviewer` + `ui_reviewer`) on the complete, widened diff — the WO's original
-  review requirement stands, now over a larger diff.
-
-This addendum does not change anything else in Part A/B above — the six/seven MFA mappings, the
-allowlist requirement, the print-document exclusion, and the `grey.*` report-only class are unchanged.
-
-### Mini-handover
-
-Repo: `ui-core-micha` (`C:\Users\biglmi\Documents\webapps\ui-core-micha`), branch `main`.
-WO: `work-orders/THEME-5.md`. Follow `orchestrate-codex`. **Chunk 2**: implement the Addendum above on
-top of chunk 1's uncommitted working-tree state — do not discard chunk 1's work, extend it.