npm - @getarbiter/cli - Versions diffs - 0.5.0 - Mend

@getarbiter/cli 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (989) hide show

package/dist/templates/e2e/playwright-python/test_a11y.py.ejs ADDED Viewed

@@ -0,0 +1,38 @@
+# pytest a11y spec — INV-61 (#1149).
+#
+# Exercises run_axe against representative views. Extend the VIEWS list
+# as new top-level routes ship.
+#
+# `page` and `base_url` fixtures come from the arbiter-generated conftest.py.
+# base_url defaults to E2E_BASE_URL env var or http://localhost:8000.
+from typing import NamedTuple
+import pytest
+from playwright.sync_api import Page
+from a11y.run_axe import run_axe
+class View(NamedTuple):
+    label: str
+    path: str
+VIEWS = [
+    View("home", "/"),
+]
+# Guard: empty VIEWS silently produces zero tests and bypasses INV-61.
+if not VIEWS:
+    raise RuntimeError(
+        "test_a11y.py: VIEWS list is empty — add at least one View entry. "
+        "INV-61 requires at least the home route ('/')."
+    )
+@pytest.mark.parametrize("view", VIEWS, ids=lambda v: v.label)
+def test_a11y(page: Page, base_url: str, view: View) -> None:
+    """a11y gate — INV-61 (WCAG 2.2 AA, axe-playwright-python)."""
+    page.goto(f"{base_url}{view.path}")
+    run_axe(page, view.label)

package/dist/templates/e2e/playwright-python/test_smoke.py.ejs ADDED Viewed

@@ -0,0 +1,28 @@
+# pytest-playwright smoke spec — #366.
+#
+# Liveness assertions: navigating to the home route must return a non-error
+# response, the document must have a non-empty title, and a <body> must be
+# visible. Failure here means the ephemeral server (#358) is up but the
+# application is dead — exactly the regression class the playwright gate
+# is meant to catch.
+import re
+from playwright.sync_api import Page, expect
+def test_home_page_status(page: Page, base_url: str) -> None:
+    response = page.goto(base_url)
+    assert response is not None, "page.goto returned no response"
+    status = response.status
+    assert status < 400, f"home returned HTTP {status} — server liveness regression"
+def test_home_page_title(page: Page, base_url: str) -> None:
+    page.goto(base_url)
+    expect(page).to_have_title(re.compile(r".+"))
+def test_home_page_body_visible(page: Page, base_url: str) -> None:
+    page.goto(base_url)
+    expect(page.locator("body")).to_be_visible()

package/dist/templates/e2e/playwright-ts/a11y.spec.ts.ejs ADDED Viewed

@@ -0,0 +1,20 @@
+// a11y.spec.ts — INV-61 (#349).
+//
+// Exercises the runAxe wrapper against representative views. Extend the
+// `views` array as new top-level routes ship.
+import { test } from '@playwright/test'
+import { runAxe } from './a11y/run-axe'
+const BASE_URL = process.env.E2E_BASE_URL ?? 'http://localhost:4173'
+const views: ReadonlyArray<{ label: string; path: string }> = [
+  { label: 'home', path: '/' },
+]
+for (const view of views) {
+  test(`a11y — ${view.label} (INV-61)`, async ({ page }) => {
+    await page.goto(`${BASE_URL}${view.path}`)
+    await runAxe(page, view.label)
+  })
+}

package/dist/templates/e2e/playwright-ts/render-smoke.spec.ts.ejs ADDED Viewed

@@ -0,0 +1,90 @@
+<%
+const _fw = (typeof frontend !== 'undefined' && frontend && frontend.framework)
+  ? frontend.framework : 'react';
+// Framework-aware mount root. The smoke test asserts this node mounted with
+// real content — not a blank/error page. Extend the selector list if your
+// app uses a custom root id.
+const _mountSelector = _fw === 'vue' || _fw === 'svelte'
+  ? '#app'
+  : _fw === 'angular'
+  ? 'app-root'
+  : '#root';
+-%>
+// render-smoke.spec.ts — INV-127 (#1366).
+//
+// The MINIMUM behavioural gate for a frontend: a headless browser boots the
+// BUILT SPA (served at E2E_BASE_URL — the same ephemeral-server convention as
+// the a11y lane) and proves, for each key screen, that:
+//   1. the app shell mounted with real content (not a blank/error page), and
+//   2. ZERO console errors / uncaught page errors fired during mount.
+//
+// This catches the failure mode a token-purity gate cannot: the screen renders
+// as broken empty boxes while every lint/token check stays green. A render-smoke
+// failure is a HARD gate — do not merge a frontend that does not mount.
+//
+// Extend `screens` as new top-level routes ship. Keep each screen's anchor a
+// stable, content-bearing selector (a [data-testid], heading, or landmark).
+import { test, expect } from '@playwright/test'
+const BASE_URL = process.env.E2E_BASE_URL ?? 'http://localhost:4173'
+// Mount root for <%= _fw %>. The shell screen asserts this node has rendered children.
+const MOUNT_SELECTOR = '<%- _mountSelector %>'
+const screens: ReadonlyArray<{ label: string; path: string; anchor?: string }> = [
+  // The app shell itself — the first screen that must mount.
+  { label: 'app shell', path: '/' },
+  // Add key screens here, e.g.:
+  // { label: 'dashboard', path: '/dashboard', anchor: '[data-testid="dashboard-root"]' },
+]
+for (const screen of screens) {
+  test(`render smoke — ${screen.label} mounts without console errors (INV-127)`, async ({
+    page,
+  }) => {
+    const consoleErrors: string[] = []
+    const pageErrors: string[] = []
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text())
+    })
+    page.on('pageerror', (err) => {
+      pageErrors.push(err.message)
+    })
+    const response = await page.goto(`${BASE_URL}${screen.path}`, {
+      waitUntil: 'networkidle',
+    })
+    // The document must have been served (not a 4xx/5xx error page).
+    expect(
+      response?.ok(),
+      `expected a 2xx/3xx response for ${screen.path}, got ${response?.status()}`,
+    ).toBeTruthy()
+    // The app shell must have mounted with real content — not a blank page.
+    const root = page.locator(screen.anchor ?? MOUNT_SELECTOR)
+    await expect(
+      root,
+      `expected mount node "${screen.anchor ?? MOUNT_SELECTOR}" to be visible on ${screen.path}`,
+    ).toBeVisible()
+    const childCount = await root.evaluate((el) => el.childElementCount)
+    expect(
+      childCount,
+      `expected mount node to contain rendered children on ${screen.path} (got an empty shell)`,
+    ).toBeGreaterThan(0)
+    // Zero console errors / uncaught exceptions during mount — broken layout
+    // and runtime crashes both surface here.
+    expect(
+      consoleErrors,
+      `console errors on ${screen.path}:\n${consoleErrors.join('\n')}`,
+    ).toEqual([])
+    expect(
+      pageErrors,
+      `uncaught page errors on ${screen.path}:\n${pageErrors.join('\n')}`,
+    ).toEqual([])
+  })
+}

package/dist/templates/e2e/playwright-ts/run-axe.ts.ejs ADDED Viewed

@@ -0,0 +1,74 @@
+// a11y axe-core wrapper — INV-61 (#349, CANON-02).
+// Updated to WCAG 2.2 AA in #1127.
+//
+// Threshold policy (deliberate, not negotiable without an INV revision):
+//   - HARD-throw on impact === 'critical'
+//   - HARD-throw on unclassified impact (null / undefined) — never silently pass
+//   - LOG without throw on serious / moderate / minor — captured as evidence
+//
+// Downstream projects may ratchet the policy stricter (e.g. throw on
+// 'serious' too) by wrapping or replacing this helper. They may NOT loosen
+// it without recording a project-level exception that cites INV-61.
+//
+// Tag set: full WCAG 2.2 AA — wcag2a + wcag2aa + wcag21a + wcag21aa + wcag22aa.
+// Covers: target-size (2.5.8), focus-appearance (2.4.11), accessible-auth (3.3.8).
+// WCAG 2.2 AA is the 2026 baseline — do NOT drop to wcag2a+wcag2aa only.
+import AxeBuilder from '@axe-core/playwright'
+import type { Page } from '@playwright/test'
+type ImpactLevel = 'critical' | 'serious' | 'moderate' | 'minor'
+interface AxeViolation {
+  id: string
+  impact?: ImpactLevel | null
+  description: string
+  help: string
+  helpUrl: string
+  nodes: ReadonlyArray<{ target: ReadonlyArray<string> }>
+}
+interface AxeResults {
+  violations: ReadonlyArray<AxeViolation>
+}
+const HARD_FAIL_IMPACTS = new Set<ImpactLevel>(['critical'])
+export async function runAxe(page: Page, label: string): Promise<void> {
+  const results = (await new AxeBuilder({ page })
+    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
+    .analyze()) as unknown as AxeResults
+  const hardFailures: AxeViolation[] = []
+  const unclassified: AxeViolation[] = []
+  const soft: AxeViolation[] = []
+  for (const v of results.violations) {
+    if (v.impact === null || v.impact === undefined) {
+      unclassified.push(v)
+    } else if (HARD_FAIL_IMPACTS.has(v.impact)) {
+      hardFailures.push(v)
+    } else {
+      soft.push(v)
+    }
+  }
+  for (const v of soft) {
+    // eslint-disable-next-line no-console
+    console.warn(`[a11y][${label}] ${v.impact ?? '?'}: ${v.id} — ${v.help}`)
+  }
+  if (unclassified.length > 0) {
+    const ids = unclassified.map((v) => v.id).join(', ')
+    throw new Error(
+      `[a11y][${label}] INV-61: unclassified-impact violations not permitted: ${ids}`,
+    )
+  }
+  if (hardFailures.length > 0) {
+    const summary = hardFailures
+      .map((v) => `${v.id} (${v.nodes.length} node${v.nodes.length === 1 ? '' : 's'})`)
+      .join(', ')
+    throw new Error(`[a11y][${label}] INV-61: critical violations detected: ${summary}`)
+  }
+}

package/dist/templates/e2e/smoke-journeys/journeys.spec.ts.ejs ADDED Viewed

@@ -0,0 +1,53 @@
+// smoke-journeys.spec.ts — INV-137 (#2080), the login/CRUD acceptance floor.
+//
+// The MINIMUM user-journey gate for a frontend: a headless browser boots the BUILT
+// SPA (served at E2E_BASE_URL — the same ephemeral-server convention as render-smoke
+// and the a11y lane) and drives each MANDATORY journey end-to-end. This is the layer
+// that catches "every unit test green, but a real user cannot log in or save a record".
+//
+// These are HONEST STARTERS, not pass-throughs: each block navigates the real app and
+// asserts a real, journey-specific outcome. Replace the // TODO(#2080) selectors/paths
+// with your app's, and keep the assertion meaningful — an empty test() here is a lie the
+// smoke-journeys gate (presence-only) cannot catch, but INV-118 (anti-proforma) can.
+//
+// Declared in smoke-journeys.json:
+//   auth  — Authentication flow        (required)
+//   crud  — Core CRUD operation        (required)
+//   authz — Authorization enforcement  (n/a for frontend-spa — the backend archetype's floor)
+import { test, expect } from '@playwright/test'
+const BASE_URL = process.env.E2E_BASE_URL ?? 'http://localhost:4173'
+test('auth — a user can complete the login flow (INV-137)', async ({ page }) => {
+  const consoleErrors: string[] = []
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text())
+  })
+  // TODO(#2080): drive your real login form. Replace path + selectors + credentials.
+  // NOTE: the placeholder below is intentionally not email-shaped (arbiter's own PII
+  // scan flags an @-address pattern in scaffolded source, #2257) — swap in a real
+  // fixture identity (via E2E_USER) once your login form is wired up.
+  await page.goto(`${BASE_URL}/login`, { waitUntil: 'networkidle' })
+  await page.getByLabel(/email|username/i).fill(process.env.E2E_USER ?? 'smoke-test-user')
+  await page.getByLabel(/password/i).fill(process.env.E2E_PASS ?? 'password')
+  await page.getByRole('button', { name: /log ?in|sign ?in/i }).click()
+  // The journey succeeds only if the app leaves the login screen for an authed view.
+  await expect(page).not.toHaveURL(/\/login\b/)
+  expect(consoleErrors, `console errors during login: ${consoleErrors.join('; ')}`).toHaveLength(0)
+})
+test('crud — a user can create then read back a record (INV-137)', async ({ page }) => {
+  // TODO(#2080): drive your real create-then-read path. Replace path + selectors.
+  // Keep the assertion journey-specific: the created record must be visible on read-back,
+  // proving the write persisted and the read wiring surfaces it (not just a 200).
+  await page.goto(`${BASE_URL}/`, { waitUntil: 'networkidle' })
+  await expect(page.locator('body')).toBeVisible()
+  // e.g.:
+  //   await page.getByRole('button', { name: /new|create|add/i }).click()
+  //   await page.getByLabel(/title|name/i).fill('smoke-journey record')
+  //   await page.getByRole('button', { name: /save|submit/i }).click()
+  //   await expect(page.getByText('smoke-journey record')).toBeVisible()
+})

package/dist/templates/evidence-files.json.ejs ADDED Viewed

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "_comment": "Defines which files are load-bearing for done evidence (SHA-pinning). Generated by arbiter.",
+  "pin_dirs": [<% if (language === 'typescript') { %>"src", "__tests__"<% } else if (language === 'java') { %>"src/main/java", "src/test/java"<% } else if (language === 'python') { %>"src", "tests"<% } else if (language === 'rust') { %>"src", "tests"<% } else if (language === 'go') { %>"."<% } else { %>"src"<% } %>],
+  "pin_extensions": [<% if (language === 'typescript') { %>".ts", ".tsx", ".mjs", ".js"<% } else if (language === 'java') { %>".java"<% } else if (language === 'python') { %>".py"<% } else if (language === 'rust') { %>".rs"<% } else if (language === 'go') { %>".go"<% } else { %>".ts"<% } %>],
+  "exclude_dirs": ["node_modules", "dist", "build", "coverage", ".git", "target", "vendor", "__pycache__", ".venv"],
+  "reality_contact": {
+    "archetype": "<%- archetype %>",
+    "required": <% if (archetype === 'backend-web-db' || archetype === 'frontend-spa') { %>true<% } else { %>false<% } %>,
+    "suite": "<% if (archetype === 'frontend-spa') { %>render-smoke<% } else { %>live-api-e2e<% } %>",
+    "command": <% if (archetype === 'backend-web-db') { %>"./tests/api/run.sh"<% } else if (archetype === 'frontend-spa') { %>["node", "scripts/lib/ephemeral-server.mjs", "--start", "npm run start:test", "--test", "npx playwright test tests/e2e/render-smoke.spec.ts", "--port", "4173"]<% } else { %>""<% } %>
+  }
+}

package/dist/templates/frontend/FE_DESIGN_PRINCIPLES.md.ejs ADDED Viewed

@@ -0,0 +1,115 @@
+<%
+const _fw = (typeof frontend !== 'undefined' && frontend && frontend.framework)
+  ? frontend.framework
+  : 'the frontend framework'
+%>
+# FE Design Principles — <%= projectName %>
+<!-- arbiter-managed: frontend-governance (#1124) -->
+**Framework:** <%= _fw %>
+**Authority:** Binding project policy. Violations are defects, not style suggestions.
+---
+## P1: Semantic Tokens Only
+Every color reference in UI templates MUST come from the semantic token layer.
+- **NO** raw palette colors (`bg-amber-500`, `text-red-600`, `border-slate-200`)
+- **NO** phantom tokens (undefined CSS vars produce zero CSS output → invisible elements)
+- **NO** numbered shades outside the token system
+**Why:** Semantic tokens are theme-aware. Raw palette classes break dark mode and require
+per-component manual overrides. Using semantic tokens makes multi-theme correctness structural.
+**Enforcement:** CI grep check for raw palette classes in UI source.
+---
+## P2: Page Header Consistency
+All route-level views MUST use a shared `<PageHeader>` (or equivalent) component for
+title/subtitle rendering. This enforces visual consistency across all pages.
+**Exceptions (explicit, not default):**
+- Dashboard — hero-card layout with custom visual hierarchy
+- Auth / Error pages — centered full-page layouts
+- Mobile execution views with full-bleed layouts
+---
+## P3: Explicit Component Imports (Runtime Safety)
+Every component used in a template MUST have an explicit import in its script block.
+Auto-import plugins are opt-in, not the default.
+**Why:** Without explicit imports, a missing component renders as a raw HTML element
+(e.g., `<appcard>`) with zero styling — invisible to users with no console error.
+This is a runtime safety rule, not a style preference.
+---
+## P4: Container Heights Flow Down
+The parent provides the height constraint. The child fills with `height: 100%`.
+- **NEVER:** child forces a fixed height inside a smaller parent container
+- **Pattern:** parent wraps with a fixed-height container, child chart/component uses `h-full`
+**Why:** Prevents layout overflow and ensures chart/canvas components resize correctly.
+---
+## P5: Layout Fills Available Width
+Page content containers MUST fill the layout shell's available width.
+No `max-width` constraints on page content unless it is explicitly a reading layout.
+**Why:** The layout shell controls the outer constraint. Per-page `max-width` overrides
+create inconsistent widths across pages.
+---
+## P6: i18n Governance
+All user-facing strings MUST use the i18n translation function (`t('key')`).
+Keys MUST exist in all supported locale files. No raw UI literals.
+**Enforcement:** CI grep check for unlocalized string literals in UI template files.
+---
+## P7: Visual Verification Protocol
+Any layout or styling change requires:
+1. **Unit tests** — component renders without crash
+2. **Local visual verification** — rendered page inspected in browser
+3. **Responsive check** — 375px mobile and 1280px desktop minimum
+4. **Dark mode check** — verify no raw palette breakage
+**Unit tests passing does NOT equal visual correctness.** Browser evidence is mandatory
+for any visual claim.
+---
+## P8: Dark Mode by Design
+Semantic tokens are theme-aware via CSS custom properties scoped to `[data-theme]`.
+Raw palette colors break dark mode. Using semantic tokens makes dark-mode correctness
+a structural guarantee, not a per-component concern.
+**Corollary:** Every phantom token fix is simultaneously a dark-mode fix.
+---
+## P9: Accessibility by Default
+All interactive elements MUST be keyboard-accessible and meet WCAG 2.1 AA contrast ratios.
+- Form inputs MUST have associated labels (not just placeholder text).
+- Icon-only buttons MUST have `aria-label` or equivalent.
+- Focus indicators MUST be visible and not suppressed with `outline: none` without replacement.
+**Enforcement:** Automated a11y checks in CI (e.g., axe-core Playwright integration).

package/dist/templates/frontend/FRONTEND_CONSTITUTION.md.ejs ADDED Viewed

@@ -0,0 +1,170 @@
+<%
+const _fw = (typeof frontend !== 'undefined' && frontend && frontend.framework)
+  ? frontend.framework
+  : 'the frontend layer'
+const _sm = (typeof frontend !== 'undefined' && frontend && frontend.stateManager)
+  ? frontend.stateManager
+  : (_fw === 'vue' ? 'Pinia' : _fw === 'react' ? 'Zustand' : 'the state store')
+const _vl = (typeof frontend !== 'undefined' && frontend && frontend.validationLib)
+  ? frontend.validationLib
+  : 'Zod'
+%>
+# Frontend Constitution — <%= projectName %>
+<!-- arbiter-managed: frontend-governance (#1124) -->
+**Framework:** <%= _fw %>
+**Status:** RATIFIED
+**Scope:** FE001–FE006
+---
+## 1. Definitions
+**Adapter / API layer**
+Infrastructure boundary implementing all I/O operations (HTTP, storage, external APIs).
+No business logic lives here.
+**Domain layer**
+Pure business logic with zero framework coupling (no UI framework, no browser APIs, no state libraries).
+**Application layer**
+Glue connecting domain logic to UI via composables / hooks / services.
+**State store**
+Restricted to synchronous, client-only state. No async actions, no API caching.
+---
+## 2. Non-Negotiables (MUST)
+- All HTTP calls to the backend API MUST occur within the adapter/API layer.
+- The domain layer MUST contain pure business logic — no UI framework, state library, or browser API imports.
+- Server state MUST be managed via a data-fetching library with stale-while-revalidate strategy.
+- Every API response MUST be validated by a schema validator (<%= _vl %>) at the system boundary.
+- All errors MUST be normalized to a standard `AppError` shape and routed via a centralized notification bus.
+- UI components MUST use semantic design tokens (`--bg-*`, `--text-*`, etc.), NOT raw palette colors.
+---
+## 3. Pillar Rules (FE001–FE006)
+### FE001 — Governed ACL (Anti-Corruption Layer)
+**MUST:**
+- All I/O and external mutations MUST occur within the adapter/API layer.
+- Access to external systems MUST be via port interfaces or data-fetching hooks.
+- Linting MUST restrict `fetch`/HTTP client imports to the API layer only.
+**FORBIDDEN:**
+- Direct `fetch`, `axios`, or equivalent HTTP calls in UI components, composables/hooks, or state stores.
+- Cross-module HTTP calls outside the API layer.
+**Enforcement:**
+- ESLint `no-restricted-imports`: forbid HTTP clients outside the adapter layer.
+- CI grep check: `rg "fetch\(|axios\." src/*/ui` MUST be empty.
+---
+### FE002 — Headless Domain Logic
+**MUST:**
+- The domain layer MUST contain pure business logic with zero framework coupling.
+- Domain modules MUST import only pure language constructs, validation schemas, date utilities, and standard `Error` classes.
+**FORBIDDEN:**
+- Importing the UI framework (<%= _fw %>) in the domain layer.
+- Importing state management libraries in the domain layer.
+- Accessing browser APIs (`window`, `document`, `localStorage`, `matchMedia`) in the domain layer.
+**Enforcement:**
+- CI grep check: `rg "localStorage|matchMedia|document\.|window\." src/*/domain` MUST be empty.
+- Architectural boundary tests enforce domain purity.
+---
+### FE003 — Application Layer & State Management
+**MUST:**
+- Server state MUST be managed via a data-fetching library with stale-while-revalidate strategy.
+- <%= _sm %> MUST be restricted to synchronous, client-only state (no async actions, no API caching).
+- Query keys MUST be co-located with their API functions.
+**FORBIDDEN:**
+- Async actions in <%= _sm %>.
+- Business logic in store getters.
+- Manually caching API responses in a client store.
+**Enforcement:**
+- Code review: verify no async/await in <%= _sm %> actions.
+---
+### FE004 — Centralized Error Handling
+**MUST:**
+- All exceptions MUST be normalized to a standard `AppError` schema.
+- Errors MUST be routed via a centralized feedback/notification bus.
+- A global error interceptor MUST convert 4xx/5xx responses to `AppError` objects.
+- UI components MUST consume `AppError` to display user-friendly messages.
+**FORBIDDEN:**
+- Swallowing errors without reporting.
+- Ad-hoc alerts or component-level `try/catch` blocks that suppress errors.
+- `console.error` as the primary error handling mechanism in production code.
+**Enforcement:**
+- Code review: verify all API errors route through the global interceptor.
+---
+### FE005 — Async UX Policy
+**MUST:**
+- User intent MUST be acknowledged immediately via visual feedback.
+- A loading/skeleton state MUST appear for first loads (no cached data available).
+- A background-refresh indicator MUST appear for stale-while-revalidate refreshes.
+- Skeleton components MUST have fixed heights matching real content dimensions (anti-layout-shift).
+- Interactive elements MUST enter a disabled/loading state during in-flight operations.
+**FORBIDDEN:**
+- Frozen UI (blocking the main thread).
+- Interactive elements lacking a loading state during operations.
+- Silent failures (errors must surface via the notification bus).
+- Manual `isLoading` refs duplicating what the data-fetching library already provides.
+**Enforcement:**
+- Code review: verify loading-state semantics (first load vs. background refetch).
+- Design QA: verify skeleton heights match loaded content.
+---
+### FE006 — Design Tokens & Multi-Theme
+**MUST:**
+- UI components MUST use semantic design tokens (`--bg-*`, `--text-*`, etc.) exclusively.
+- Foundation/primitive tokens are abstract values and MUST NOT be referenced directly by components.
+- Theme switching MUST be controlled via a `data-theme` attribute on `<html>`.
+- The app MUST support at minimum `light`, `dark`, and `system` (default) themes.
+- FOUC prevention MUST be implemented via an inline script applied BEFORE CSS loads.
+**FORBIDDEN:**
+- Raw palette color classes (`bg-white`, `text-gray-500`, etc.) in production UI files.
+- Foundation/primitive tokens used directly in component styles.
+- Side-effects (DOM manipulation, localStorage) in the dumb state store.
+**Enforcement:**
+- CI grep check: `rg "bg-white|text-gray-|bg-slate-" src/*/ui` MUST be empty.
+- Code review: verify `ThemeController` location and state-store purity.
+---
+## 4. Ratification Checklist (PR Reviewers)
+- [ ] All HTTP calls originate from the adapter/API layer.
+- [ ] Domain layer contains only pure logic (no UI framework, state lib, browser APIs).
+- [ ] Server state managed via data-fetching library; state store restricted to client-only sync state.
+- [ ] All API responses validated by <%= _vl %> at boundary.
+- [ ] Errors normalized to `AppError` and routed via notification bus.
+- [ ] Loading-state semantics correct (first load vs. background refetch).
+- [ ] Semantic tokens used exclusively in UI components.