@micha.bigler/ui-core-micha 2.41.1 → 2.41.3

package/work-orders/DX-2.md

@@ -0,0 +1,188 @@
+# DX-2 — Declare `sideEffects` so consumers can tree-shake the kit
+
+**Target repo:** `ui-core-micha` (branch `main`)
+**Tier:** 3 — shared-core, and it changes what every consumer's bundler is permitted to discard.
+
+---
+
+## A. Envelope
+
+### Goal
+
+`package.json` declares **no `sideEffects` field**. Without it a bundler must assume every module in the
+package can have an import side effect and therefore cannot drop unused exports. **Twelve consumers ship the
+whole kit regardless of what they import.**
+
+This is not a theory. `hram/THEME-2` switched hram from three named translation bundles to the full
+`uiCoreTranslations` aggregate and measured the built-size delta at **−11 bytes** — not the increase everyone
+expected, because the three-bundle import was already pulling all seven.
+
+### Why this is worth a Tier-3 change
+
+Two decisions currently rest on a number that this defect makes meaningless:
+
+- **`I18N-1` measured `+28,943 B` raw / `+7,327 B` gzip** for an auth-only app switching to the aggregate.
+  That measured a real difference in *source* reachability which the build never realises. As a decision input
+  it is void.
+- **`I18N-2` is `blocked` on exactly this.** It was framed as a bundle-size optimisation via
+  self-registration, and its stated input is a size delta that cannot be measured until the package can
+  tree-shake at all. **This WO is its unblocker**, and it is a far smaller change than reworking how twelve
+  consumers resolve strings.
+
+### Scope
+
+1. **Prove it first, per module.** Walk every module reachable from the package root and establish that
+   importing it has **no** side effect: no top-level statement with an observable effect, no polyfill or
+   registry mutation, no `import './x.css'` or equivalent, no module-scope singleton creation whose existence
+   something depends on. **This is the work**; the field is one line.
+2. **`package.json`** — add `"sideEffects": false` if step 1 holds for everything. If it does **not** hold for
+   some module, add the array form listing exactly those files rather than the blanket `false`.
+3. **Re-measure the delta `I18N-1` got wrong**: the built size of an auth-only app importing only
+   `authTranslations` versus the full aggregate, against a package that can now tree-shake. Report the number.
+4. Update `I18N-2`'s register note with that number, so it is either authorable or droppable on evidence.
+
+### Non-goals / do not touch
+
+- **No `exports` map.** It would allow subpath imports and give a further size win, but it changes which
+  import paths resolve at all — a breaking-change risk for twelve consumers in the same commit. Separate
+  decision, and this WO's measurement is its input.
+- **No component, theme, chart or i18n change.** Nothing in `src/` is edited for its own sake; the only source
+  changes permitted are ones step 1 proves are needed to make a module genuinely side-effect-free, and each
+  must be reported rather than folded in silently.
+- **No consumer pin bumps.** Apps pick this up when they next bump.
+- **`I18N-2` itself.** This unblocks it; it does not implement it.
+
+### Risks
+
+- **The real failure mode is a false `sideEffects: false`.** If a module *does* have an import side effect and
+  the field says otherwise, a bundler silently drops it and the consuming app breaks at runtime in a way no
+  test here will catch. That is why step 1 is the scope and the field is an afterthought. **If any module is
+  uncertain, use the array form and list it** — a partial declaration that is true beats a blanket one that is
+  nearly true.
+- **`side effect` includes the theme.** `createAppTheme`, the token module and the registry are the places to
+  look hardest: a module that builds an object at import time is fine, but one that *registers* itself
+  somewhere is not.
+- **Every consumer's bundle changes shape**, even though no source behaviour changes. That is the intent, and
+  it is why this is Tier 3 rather than a chore.
+
+### Required tests to WRITE
+
+- **A test asserting the field matches reality** is not really possible in-repo — a bundler is what enforces
+  it. So instead: **one build-level check** that the package builds and its entry points still resolve after
+  the declaration, plus the measurement in scope item 3 recorded as a number in the register note.
+- If step 1 finds a module needing a source change to become side-effect-free, that change gets a test.
+- Otherwise **no new unit tests** — and saying so is the correct answer for a `package.json` field.
+
+Scoped run: the existing suite, to confirm nothing regressed. Not a full-estate exercise.
+
+### Parity guardrail
+
+No API, behaviour or visual change. Every currently-working import must keep working; what changes is only
+what a consumer's bundler may discard.
+
+---
+
+## B. Implementation map
+
+*Filled by the Orchestrator on `git pull` — see `AGENTS.md` → "Work Order".*
+
+**Repo root:** `ui-core-micha` (this is the package root — `package.json` lives here, `src/index.js` is
+the package entry per `"main"`/`"module"`). Build: `pnpm run build` (tsc, `tsconfig.build.json`,
+`rootDir: src` → `outDir: dist`). Tests: `pnpm test` (vitest run), config likely under `tests/` or
+`vite.config.mjs`.
+
+**Entry point to walk:** [`src/index.js`](../src/index.js) — every export re-exported from here is a
+module the audit must cover. Rough module groups, in the order they're exported: `theme/` (7 exports),
+`auth/` (AuthContext, UserMenu, apiClient, authApi, authService), `layout/` (PageLayout, SectionNav),
+`pages/` (7 page components), `components/` (12 components incl. charts subtree), `i18n/` (7 translation
+bundle modules, pure data objects), `notifications/` (7 exports incl. a `realtime` module — check for
+WebSocket/EventSource construction at module scope, not just component-body), `messaging/` (13 exports,
+same realtime-connection caution), `onboarding/` (8 exports).
+
+**Known non-trivial finding — do not silently "fix" this, report it:**
+[`src/theme/createAppTheme.js:1-3`](../src/theme/createAppTheme.js) has three top-level
+`import '@fontsource/dm-sans/400.css'` (+ `/500.css`, `/600.css`) — these ARE import-level side effects
+(CSS injected into the document on import, unconditionally, regardless of whether `createAppTheme` is
+even called). This module must be **excluded** from a blanket `sideEffects: false` — either list
+`src/theme/createAppTheme.js` explicitly in the array form, or (better, since it's a source-level fix
+consistent with the WO's "no false negatives" risk framing) move the three font-CSS imports into a
+separate module (e.g. `src/theme/fonts.css.js` or inline at the one leaf that needs them) so the rest of
+`theme/` stays tree-shakeable and only that one file is excluded. Whichever path is taken, it must be
+**reported explicitly** in the WO's audit output, not folded in silently (Envelope: "each must be
+reported rather than folded in silently").
+
+**Areas most likely to hide further side effects (audit these hardest, per the Envelope's own risk
+note):** `theme/` (registry singletons — `KIT_COMPONENT_SX_REGISTRY` is exported as a value; confirm it's
+a plain object literal built at import with no external registration call), `notifications/realtime.js`
+and `messaging/` (anything opening a socket/listener at module scope rather than inside a hook/effect),
+`auth/apiClient.js` (axios instance creation is fine — a side-effect-free object build — but check for
+any `axios.interceptors.*.use(...)` called at module scope outside a factory function, which would be a
+real side effect since it mutates a shared axios default instance).
+
+**Do-not-touch:** no `exports` map in `package.json` (Envelope non-goal). No component/theme/chart/i18n
+behaviour change — only source edits that make a module genuinely side-effect-free, each reported.
+
+**Progress contract:** emit `PLAN: …` first, then `PROGRESS: [n/total] <module-group>` before auditing
+each group above and `… done` after, and a final `RESULT: DONE` or `RESULT: BLOCKED <reason>`. No gap
+> ~2 min. Work from this package — open files only to verify specific claims, not a blind full-repo read.
+
+## Preamble
+
+The text above is the COMPLETE spec — the committed WO file's content, not a plan to refine; there is
+no separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and
+the app `MEMORY.md` ONLY for conventions. Stay in scope; do not touch auth/permissions/deps/schema/CI
+unless the spec says so; do not update `MEMORY.md`. **Do NOT edit `WORK_ORDERS.md`** — the register row
+and the review verdicts are the orchestrator's alone. Do NOT `git add`/`commit`/`push` — leave every
+change uncommitted in the working tree for the orchestrator's independent review. WRITE the tests the
+"Required tests to WRITE" section calls for AND **RUN the tests you just wrote** to confirm they execute
+and pass — that is the ONLY test run you do (NOT the app's affected/full suite, NOT any review). The
+orchestrator re-runs the authoritative set + does the independent review after you finish — those are
+the gate; your own run does not count as the gate.
+
+Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on
+completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
+`RESULT: DONE|BLOCKED <reason>`.
+
+---
+
+## C. Orchestrator only
+
+> **STOP — if you are the implementer reading this work order as your own specification, this section is NOT
+> addressed to you. Skip it entirely.** It tells the Orchestrator how to invoke you. **You ARE that
+> invocation — do NOT shell out to `codex exec`, do NOT spawn reviewers, do NOT edit `WORK_ORDERS.md`, and do
+> NOT `git add`/`commit`/`push`.**
+
+### Execution directive
+
+Check `.claude/codex-status.md` first. **No line for the current date means use Codex.** A dated `unavailable`
+line for today means skip the attempt, implement directly in Claude and name the record — that flips
+authorship. Otherwise one probe, outcome written back either way.
+
+### Review routing
+
+Tier 3: **independent `reviewer`** — mandatory, and the substantive one here: ask it to **independently
+re-check the side-effect audit**, module by module, rather than accept the implementer's list. That audit is
+the entire safety argument. **No `ui_reviewer`** — nothing renders. No `sec_reviewer`.
+
+### Verification
+
+Nothing renders, so no gate. The verification is the audit plus the re-measured delta, both reported as
+findings rather than assertions.
+
+**A push to `main` here IS the npm publish** — `publish.yml` triggers on `push: branches: [main]` with `paths`
+covering `package.json` and `src/**`, and npm publishes cannot be undone. So decide the version deliberately
+before pushing: this is a **patch** by scope (no new capability, no API change), and it will go out the moment
+it lands.
+
+### Register + commit
+
+One row, `DX-2`. `done` only with the independent reviewer and verdict named, plus the measured delta.
+Update `I18N-2`'s note in the same commit — that cross-reference is half the point of this WO.
+
+### Mini-handover
+
+Repo: `ui-core-micha`, branch `main`. WO: `work-orders/DX-2.md`. The one-line field is trivial; **the
+per-module side-effect audit is the work**, and a wrong `false` breaks consumers silently at runtime. Use the
+array form if anything is uncertain. Re-measure the aggregate delta and write it into `I18N-2`. Tier 3,
+`reviewer` mandatory and asked to redo the audit. **Pushing to main publishes.** Follow `orchestrate-codex`.

package/work-orders/DX-3.md

@@ -0,0 +1,195 @@
+# DX-3 — `publish.yml` tests before it builds, so `2.41.2` cannot publish
+
+**Target repo:** `ui-core-micha` (branch `main`)
+**Tier:** 3 — CI is a Tier-3 surface regardless of diff size.
+
+Short-form WO: two steps swapped, then an operator-confirmed dispatch.
+
+---
+
+## A. Envelope
+
+### Goal
+
+`DX-2` landed on `main` (`31675d8`, `e75192f`) and **its publish failed**, so `@micha.bigler/ui-core-micha`
+is still at `2.41.1` on the registry while `package.json` says `2.41.2`. Nothing DX-2 produced can be
+consumed until this is fixed.
+
+Cause, from run
+[32029216699](https://github.com/bigler-webapps/ui-core-micha/actions/runs/32029216699) —
+`completed/failure`:
+
+```
+FAIL tests/packageTreeShaking.test.js > built package entries resolve and unused translation bundles tree-shake
+Error: ENOENT: no such file or directory, lstat '.../ui-core-micha/dist'
+Test Files  1 failed | 64 passed (65)
+      Tests  1 failed | 510 passed (511)
+```
+
+`publish.yml` runs **`Run tests` before `Build`**. `DX-2`'s new test copies the package's own `dist/` to
+assemble a fake installed consumer, and **`dist/` is gitignored** (`.gitignore:2`), so in a clean checkout
+it does not exist yet. The test is not flaky and it is not wrong — it inspects the built artifact, which is
+the whole point of it. **It simply cannot pass in the order the workflow runs.**
+
+It passed locally at 511/511 because a `dist/` from an earlier `pnpm run build` was lying around. That is
+the failure mode, not the test.
+
+### Scope
+
+1. **`.github/workflows/publish.yml`** — move the `Build` step **above** `Run tests`.
+   **Both steps carry `if: steps.version_check.outputs.should_publish == 'true'`; that condition must stay
+   on each.** Nothing else in the file changes.
+2. **Publish `2.41.2`** — see the dispatch note below, which is the part most likely to be missed.
+
+### The dispatch is required, and it is not automatic
+
+`publish.yml` triggers on `push` to `main` filtered to `package.json`, `pnpm-lock.yaml`, `src/**` and
+`tsconfig.build.json`. **`.github/workflows/**` is not in that list**, so landing this fix does **not**
+re-trigger the publish. `2.41.2` would sit unpublished until some unrelated `src/**` change happened to
+push it out.
+
+So: after the fix lands, **dispatch `publish.yml` on `main`**. `publish.yml` is **not** on the dispatch
+safe-allowlist (`weekly-routines`, `terraform-plan`), so per `AGENTS.md` name the exact workflow and inputs
+and **wait for an explicit operator go** before running it.
+
+`should_publish` compares `package.json` against the registry, so with `2.41.2` local and `2.41.1`
+published it will evaluate true and the dispatch will publish. No version bump is needed for this WO — and
+none should be added, because the artifact being published is DX-2's, not this WO's.
+
+### Non-goals / do not touch
+
+- **`tests/packageTreeShaking.test.js`.** It is correct. Do not make it build `dist/` itself, do not skip it
+  when `dist/` is absent, and above all do not delete it — a skip would silently retire the only check that
+  the `sideEffects` declaration actually tree-shakes, which is DX-2's entire deliverable.
+- **The `sideEffects` array, `src/theme/fonts.js`, or anything else DX-2 landed.** Reviewed and correct.
+- **The trigger `paths` list.** Adding `.github/workflows/**` would make every workflow edit attempt a
+  publish. That is a worse default than one dispatch.
+- **The version.** Stays `2.41.2`.
+- Any other workflow, any source file.
+
+### Recorded, deliberately out of scope
+
+**`publish.yml` is the only workflow in this repo that runs tests, and it runs them only when
+`should_publish == 'true'`.** So ucm's suite executes in CI *only on a version bump* — a `src/**` change
+that does not bump the version is never tested by CI at all. That is a real gap in a shared-core package
+consumed by twelve apps, and it is a separate decision (a `ci.yml` for this repo, or a `pull_request`
+trigger), not something to fold into a two-line reorder.
+
+### Risks
+
+- **Low, and the shape is known**: after the swap a build failure surfaces before test results instead of
+  after. That is an improvement, not a regression — you want to know the artifact is buildable before
+  spending 64 s on tests against it.
+- **The real risk is stopping at the commit.** A landed reorder with no dispatch leaves `2.41.2`
+  unpublished and looks done. The acceptance criterion below is the registry, not the workflow file.
+
+### Required tests to WRITE
+
+**None.** Nothing to unit-test in a step reorder, and manufacturing one would be noise. The verification is
+a green run plus the registry.
+
+### Acceptance
+
+1. A `publish.yml` run on `main` completes **green**, with `tests/packageTreeShaking.test.js` **passing**
+   rather than skipped — 511/511.
+2. **`npm view @micha.bigler/ui-core-micha version` returns `2.41.2`.** The registry is the acceptance,
+   not the commit and not the green tile.
+
+### Parity guardrail
+
+No source, API, behaviour or visual change. What changes is the order two CI steps run in.
+
+---
+
+## B. Implementation map
+
+*Filled by the Orchestrator on `git pull` — see `AGENTS.md` → "Work Order".*
+
+**Repo root:** `ui-core-micha` (workflow lives at repo root, `.github/workflows/publish.yml`).
+
+**Exact change:** in [`.github/workflows/publish.yml`](../.github/workflows/publish.yml), the step
+order today (verified on `git pull`, lines 112-118) is:
+
+```yaml
+      - name: Run tests
+        if: steps.version_check.outputs.should_publish == 'true'
+        run: pnpm run test
+
+      - name: Build
+        if: steps.version_check.outputs.should_publish == 'true'
+        run: pnpm run build
+```
+
+Swap so `Build` runs first, `Run tests` second — same two `if:` conditions, unchanged, one on each
+step. Nothing else in the file (`Check out code`, `Set up Node`, `Decide whether to publish`,
+`Set up pnpm`, `Show version from package.json`, `Install dependencies (pnpm)`,
+`Ensure recent npm for trusted publishing`, `Publish to npm`) moves or changes.
+
+**Do-not-touch (repeat of the Envelope's non-goals, stated here for the implementer):**
+`tests/packageTreeShaking.test.js`, the `sideEffects` array / `src/theme/fonts.js` (DX-2, already
+landed and reviewed), the `on: push: paths` trigger list, `package.json`'s version (stays `2.41.2`).
+This WO touches exactly one file.
+
+**Progress contract:** `PLAN: …` naming the single edit, `PROGRESS: [1/1] swap Build/Run-tests order
+in publish.yml … done`, then `RESULT: DONE`.
+
+## Preamble
+
+The text above is the COMPLETE spec — the committed WO file's content, not a plan to refine; there is
+no separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and
+the app `MEMORY.md` ONLY for conventions. Stay in scope; do not touch auth/permissions/deps/schema/CI
+beyond the one named swap. Do not update `MEMORY.md`. **Do NOT edit `WORK_ORDERS.md`** — the register
+row and the review verdicts are the orchestrator's alone. Do NOT `git add`/`commit`/`push`, and do NOT
+dispatch any workflow — leave every change uncommitted in the working tree for the orchestrator's
+independent review. This WO's "Required tests to WRITE" is explicitly **none** — do not write or run
+any test; there is nothing to verify locally that the orchestrator's own read of the diff and the
+reviewer's pass don't already cover.
+
+Narrate continuously: a `PLAN: <step1> | …` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on
+completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
+`RESULT: DONE|BLOCKED <reason>`.
+
+---
+
+## C. Orchestrator only
+
+> **STOP — if you are the implementer reading this work order as your own specification, this section is NOT
+> addressed to you. Skip it entirely.** It tells the Orchestrator how to invoke you. **You ARE that
+> invocation — do NOT shell out to `codex exec`, do NOT spawn reviewers, do NOT edit `WORK_ORDERS.md`, do
+> NOT dispatch any workflow, and do NOT `git add`/`commit`/`push`.**
+
+### Execution directive
+
+Check `.claude/codex-status.md` first. **No line for the current date means use Codex.** A dated
+`unavailable` line for today means skip the attempt, implement directly in Claude and name the record —
+that flips authorship, which keeps the independent `reviewer` mandatory. Otherwise one probe, outcome
+written back either way.
+
+### Review routing
+
+Tier 3: **independent `reviewer`** — mandatory even for two lines, because CI is the surface. **No
+`ui_reviewer`** (nothing renders), no `sec_reviewer`. Ask the reviewer to confirm the `if:` conditions
+survived the move on **both** steps — dropping one would make a step run unconditionally, which is the only
+way a two-line reorder can go wrong.
+
+### Verification
+
+Acceptance criterion 2 is the verification: **read the registry.** A green tile is not a publish, and this
+session has now had the publish status misreported in both directions on the same package — once assumed
+published when it was not, once assumed unpublished when it was. `npm view`, every time.
+
+### Register + commit
+
+One row, `DX-3`. `done` only with the reviewer's verdict named **and** the registry showing `2.41.2`. Also
+update `DX-2`'s note: it currently reads as fully delivered, and it was not — its publish failed. Leaving
+that uncorrected is how the next person concludes `2.41.2` is available when it is not.
+
+### Mini-handover
+
+Repo: `ui-core-micha`, branch `main`. WO: `work-orders/DX-3.md`. Move `Build` above `Run tests` in
+`.github/workflows/publish.yml`, keeping the `if: should_publish` condition on both. Then **ask the operator
+to confirm a `publish.yml` dispatch on `main`** — the workflow's own path filter excludes
+`.github/workflows/**`, so landing the fix does not re-trigger it, and `2.41.2` stays unpublished until
+someone dispatches. Acceptance is `npm view` returning `2.41.2`, not a green tile. Tier 3, `reviewer`
+mandatory. Follow `orchestrate-codex`.

package/work-orders/I18N-3.md

@@ -0,0 +1,207 @@
+# I18N-3 — Backfill Swahili in `messagingTranslations` and restore the four-locale shape test
+
+**Target repo:** `ui-core-micha` (branch `main`)
+**Tier:** 3 — shared-core, and it re-tightens a test the estate deliberately loosened.
+
+---
+
+## A. Envelope
+
+### Goal
+
+`src/i18n/messagingTranslations.ts` carries **116 keys with `de`/`fr`/`en` and zero `sw`**. Every one of the
+other six bundles carries all four locales:
+
+| bundle | de | fr | en | sw |
+|---|---|---|---|---|
+| `auth` | ✓ | ✓ | ✓ | ✓ |
+| `charts` | 12 | 12 | 12 | 12 |
+| **`messaging`** | **116** | **116** | **116** | **0** |
+| `notifications` | 30 | 30 | 30 | 30 |
+| `onboarding` | 27 | 27 | 27 | 27 |
+| `sectionNav` | 3 | 3 | 3 | 3 |
+| `userMenu` | 3 | 3 | 3 | 3 |
+
+`I18N-1` hit this while writing its aggregate test: the required "every value keeps its `{de,fr,en,sw}` shape"
+assertion failed, the gap was confirmed as pre-existing rather than caused by the merge, and the operator
+scoped the test down to `{de,fr,en}` with the backfill recorded as a follow-up. **The follow-up was never
+written, and a scoped-down test tends to stay scoped down.** That is what this WO closes.
+
+### Scope
+
+1. **`src/i18n/messagingTranslations.ts`** — add `sw` to all 116 keys.
+2. **`tests/i18nAggregate.test.js`** — restore the shape assertion to `{de,fr,en,sw}` and **remove the comment
+   recording the scope-down**, since it no longer describes the state.
+3. Nothing else. No other bundle is touched; they already conform.
+
+### The translation quality question, which is this WO's real risk
+
+**Machine-translated UI strings that nobody on the team can check are a worse outcome than an honest gap.**
+Messaging strings are user-facing and include the kinds of phrase that go wrong invisibly — actions,
+confirmations, error states, relative time. So:
+
+- **Name the source of the translations in the register note.** If they are machine-produced, say so plainly
+  rather than shipping them as if reviewed.
+- **Flag any key the translator was unsure of** rather than guessing. A `sw` value that is wrong is harder to
+  find later than one that is missing, because the shape test will then pass.
+- **Do not invent terminology.** Where `notifications` or `onboarding` already has a Swahili term for the same
+  concept — send, reply, unread, conversation, attachment — **reuse their wording** rather than coining a
+  second one. Those bundles are the existing precedent and consistency across them matters more than any
+  individual phrasing.
+
+### Who this is actually for
+
+`sw` is configured as a locale in **hram** and in no other app measured. hram does **not** register
+`messagingTranslations` today, so nothing is currently broken for a user — this is prevention, and the honest
+framing is: it closes an inconsistency and re-arms a test, rather than fixing a live defect.
+
+That matters for the effort trade-off, and it is why the quality bar above is not negotiable: there is no
+urgency justifying unreviewed strings.
+
+### Non-goals / do not touch
+
+- **The other six bundles.** They conform.
+- **The aggregate itself, the directory ratchet, or the key/value fidelity and collision checks.** Only the
+  locale-shape assertion changes.
+- **`de`/`fr`/`en` values.** Not a re-translation pass.
+- **Adding an eighth locale**, or any change to how consumers register strings (`I18N-2`'s territory).
+
+### Risks
+
+- **116 unreviewable strings.** The mitigation is disclosure, not confidence — see above.
+- **Re-tightening the test is the irreversible half.** Once the assertion demands four locales, any future
+  bundle addition must supply `sw` or fail CI. That is the intent, and it is worth stating so the next person
+  adding a bundle is not surprised.
+- **A push to `main` publishes.** See Part C.
+
+### Required tests to WRITE
+
+None new — **`tests/i18nAggregate.test.js`'s restored four-locale assertion IS the test**, and re-arming it is
+scope item 2. It will fail until the backfill is complete, which is the correct behaviour and the reason it
+belongs in the same change.
+
+Scoped run: `i18nAggregate` plus the messaging export specs. Not the full suite — no dependency or theme
+change.
+
+### Parity guardrail
+
+No API, behaviour or visual change for `de`/`fr`/`en` consumers. Purely additive.
+
+---
+
+## B. Implementation map
+
+*Filled by the Orchestrator on `git pull` — see `AGENTS.md` → "Work Order".*
+
+**Files to change (exactly two):**
+- [`src/i18n/messagingTranslations.ts`](../src/i18n/messagingTranslations.ts) — 118 lines, 116 keys
+  (`export const messagingTranslations = { 'Key': { de, en, fr }, ... }`), every value currently a
+  3-locale object. Add a fourth `sw: '...'` to every one, matching the existing key ordering
+  `de, en, fr` → append `sw` last (matches the property order already used in
+  `notificationsTranslations.ts`/`onboardingTranslations.ts`, both `de, fr, en, sw`, so put `sw`
+  last regardless of the de/en/fr internal order already in this file — do not reorder de/en/fr).
+- [`tests/i18nAggregate.test.js`](../tests/i18nAggregate.test.js) — line 30:
+  `const REQUIRED_LOCALES = ['de', 'en', 'fr'];` → `['de', 'en', 'fr', 'sw'];`, and delete the
+  explanatory comment at lines 27-29 (`// Scoped to the three locales ... see the Notiz on the
+  I18N-1 register row ...`) since it will no longer describe the state. Nothing else in this file
+  changes — the other three `it()` blocks (aggregate completeness, no-collision, per-bundle
+  availability) are untouched.
+
+**Existing Swahili glossary to reuse — do not coin alternate wording for these concepts** (grep
+`sw:` across `src/i18n/*.ts` yourself to see full context; this is not exhaustive, check for any
+other overlap you find):
+- Notification/notify → **Arifa** (`notificationsTranslations.ts`, `onboardingTranslations.ts`)
+- Save → **Hifadhi** (`onboardingTranslations.ts`: `Onboarding.SAVE`)
+- Close → **Funga** (`notificationsTranslations.ts`: `PopupSurface.CLOSE`)
+- Continue → **Endelea** (`onboardingTranslations.ts`: `Onboarding.CONTINUE`)
+- Skip → **Ruka** (`onboardingTranslations.ts`: `Onboarding.SKIP`)
+- Change/switch (section) → **Badilisha** (`sectionNavTranslations.ts`)
+- User menu / profile / logout → **Menyu ya mtumiaji / Wasifu / Toka** (`userMenuTranslations.ts`)
+- "Could not be saved/loaded" error pattern → e.g. **"...haikuweza kuhifadhiwa"** /
+  **"...haikuweza kupakiwa"** (`notificationsTranslations.ts` `SAVE_ERROR`/`LOAD_ERROR`) — messaging
+  has the same error-string shape repeated ~15 times (`... konnte nicht ... werden: {{message}}`),
+  reuse this grammatical pattern rather than inventing a new one per key.
+- "Please try again" → **"Tafadhali jaribu tena"** (`onboardingTranslations.ts`)
+
+**None of messaging's specific domain terms (conversation, reply, attachment, reaction, poll,
+announcement, unread, archive, mute) exist in the other bundles' Swahili** — those need fresh
+translation. That is expected and fine; the instruction above is narrower: reuse wording only where
+the *same* concept (save/cancel/close/error phrasing/etc.) already has a Swahili rendering
+elsewhere, don't invent a second one for it.
+
+**Do-not-touch:** `de`/`en`/`fr` values in `messagingTranslations.ts` (verify byte-identical before
+and after — a diff review will check this); the other six bundles; `tests/i18nAggregate.test.js`'s
+other three tests, the aggregate export, the directory ratchet, the ordering (`de, en, fr` internal
+order in messaging stays as-is, `sw` only appended).
+
+**Progress contract:** `PLAN: …` naming the two files, `PROGRESS: [1/2] backfill sw into
+messagingTranslations.ts … done`, `PROGRESS: [2/2] restore REQUIRED_LOCALES + drop scope-down
+comment in i18nAggregate.test.js … done`, then run the scoped tests named below and report which
+keys (if any) you were unsure of, then `RESULT: DONE`.
+
+## Preamble
+
+The text above is the COMPLETE spec — the committed WO file's content, not a plan to refine; there is
+no separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and
+the app `MEMORY.md` ONLY for conventions. Stay in scope; do not touch auth/permissions/deps/schema/CI
+unless the spec says so; do not update `MEMORY.md`. **Do NOT edit `WORK_ORDERS.md`** — the register row
+and the review verdicts are the orchestrator's alone. Do NOT `git add`/`commit`/`push` — leave every
+change uncommitted in the working tree for the orchestrator's independent review. This WO's "Required
+tests to WRITE" is explicitly **none new** — the restored `REQUIRED_LOCALES` assertion IS the test;
+run it (and the messaging export specs) to confirm your backfill makes it pass — that is the ONLY test
+run you do (NOT the app's affected/full suite, NOT any review). **State plainly in your final report:
+the source of the Swahili translations (e.g. "machine-translated via <tool>, not reviewed by a fluent
+speaker" — say so honestly, do not imply review that didn't happen) and list any specific key you were
+uncertain of**, per the Envelope's explicit disclosure requirement. The orchestrator re-runs the
+authoritative set + does the independent review after you finish — those are the gate; your own run
+does not count as the gate.
+
+Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on
+completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
+`RESULT: DONE|BLOCKED <reason>`.
+
+---
+
+## C. Orchestrator only
+
+> **STOP — if you are the implementer reading this work order as your own specification, this section is NOT
+> addressed to you. Skip it entirely.** It tells the Orchestrator how to invoke you. **You ARE that
+> invocation — do NOT shell out to `codex exec`, do NOT spawn reviewers, do NOT edit `WORK_ORDERS.md`, and do
+> NOT `git add`/`commit`/`push`.**
+
+### Execution directive
+
+Check `.claude/codex-status.md` first. **No line for the current date means use Codex.** A dated `unavailable`
+line for today means skip the attempt, implement directly in Claude and name the record — that flips
+authorship. Otherwise one probe, outcome written back either way.
+
+### Review routing
+
+Tier 3: **independent `reviewer`** — mandatory. Ask it specifically to check **terminology consistency against
+`notifications` and `onboarding`**, and to confirm that no `de`/`fr`/`en` value was altered in passing. **No
+`ui_reviewer`** — nothing renders. No `sec_reviewer`.
+
+Neither reviewer can validate Swahili. **Say that in the note** rather than letting a clean verdict imply the
+translations were checked.
+
+### Verification
+
+The restored four-locale assertion passing is the verification. Nothing renders, so no gate.
+
+**A push to `main` here IS the npm publish** — `publish.yml` triggers on `push: branches: [main]` with `src/**`
+in its paths, and publishes cannot be undone. Additive strings, so a **patch** by scope.
+
+### Register + commit
+
+One row, `I18N-3`. `done` only with the reviewer and verdict named, **the translation source stated**, and any
+uncertain keys listed. Also update `I18N-1`'s note: its recorded follow-up is now closed, and leaving it open
+there is how the same gap gets rediscovered.
+
+### Mini-handover
+
+Repo: `ui-core-micha`, branch `main`. WO: `work-orders/I18N-3.md`. 116 `sw` values into
+`messagingTranslations.ts`, then restore `i18nAggregate.test.js` to `{de,fr,en,sw}` and drop the scope-down
+comment. **Reuse `notifications`/`onboarding` terminology; disclose the translation source; flag uncertain
+keys instead of guessing.** No app is broken today — this closes an inconsistency and re-arms a test. Tier 3,
+`reviewer` mandatory. **Pushing to main publishes.** Follow `orchestrate-codex`.