groundwork-method 0.0.1 → 0.10.0

package/src/engineer-skills/groundwork-electron-engineer/references/testing-and-smoke.md

@@ -0,0 +1,107 @@
+# Testing & Smoke
+
+## Table of Contents
+- [The Three Tiers](#the-three-tiers)
+- [Unit: Node Project (Main Policy)](#unit-node-project-main-policy)
+- [Unit: Renderer Project (Fake the Bridge)](#unit-renderer-project-fake-the-bridge)
+- [The Playwright _electron Smoke](#the-playwright-_electron-smoke)
+- [_electron Patterns](#_electron-patterns)
+- [CI: xvfb and Skip-with-Reason](#ci-xvfb-and-skip-with-reason)
+- [Keeping the Smoke Thin](#keeping-the-smoke-thin)
+- [Test Commands](#test-commands)
+
+---
+
+## The Three Tiers
+
+| Tier | Tool | Environment | Proves |
+|---|---|---|---|
+| Unit (main) | vitest, `main` project | plain Node | The pure security/policy rules |
+| Unit (renderer) | vitest, `renderer` project | jsdom, bridge faked | Components against the bridge contract |
+| Smoke (boot) | Playwright `_electron` | the real built app | Boot, rendering, IPC wiring, theme push |
+
+This maps onto the multi-surface verification contract: generation (snapshot, framework-side), compilation (`tsc` + lint), boot (the smoke). Business rules are **not** on this list — they are proven once at the capability core's contract; surface tests assert wiring and rendering only.
+
+`vitest.config.ts` defines the two unit projects with per-process environments. Test placement follows the process split: `src/main/**/*.test.ts` runs in Node, `src/renderer/**/*.test.tsx` runs in jsdom. A test that needs the wrong environment is in the wrong process.
+
+## Unit: Node Project (Main Policy)
+
+Main's testable logic lives in pure modules (`policy.ts` — no Electron imports), so it runs in plain Node with zero mocking:
+
+```ts
+it.each(['http://example.com', 'file:///etc/passwd', 'javascript:alert(1)'])(
+  'rejects %s', (url) => expect(isAllowedExternalUrl(url)).toBe(false),
+);
+```
+
+When adding privileged logic, keep this shape: decision in a pure module + test; wiring in the thin Electron glue, proven by the smoke. Do not import `electron` in a vitest file — in plain Node the module resolves to the binary path string, not the API, and mocking the whole surface buys nothing the pure-module split doesn't buy better.
+
+## Unit: Renderer Project (Fake the Bridge)
+
+The renderer's platform surface is `window.api`, so tests fake exactly that seam:
+
+```tsx
+const fakeApi: RendererApi = {
+  getStatus: async () => ({ status: 'ok', version: '0.1.0-test', platform: 'test' }),
+  openExternal: async () => ({ opened: false }),
+  onThemeChanged: () => () => undefined,
+};
+beforeEach(() => {
+  Object.defineProperty(window, 'api', { value: fakeApi, configurable: true });
+});
+```
+
+Typing the fake as `RendererApi` keeps it honest: a contract change breaks the fake at compile time. Async UI rule: query-backed components render their pending state first — `await screen.findByText(...)` past it; asserting on the container immediately races the resolution.
+
+Everything else about component testing — Testing Library idiom, what to assert, accessibility queries — is the web stack's, unchanged: `groundwork-nextjs-engineer/references/testing.md`.
+
+## The Playwright _electron Smoke
+
+Playwright's Electron support is officially "experimental" but is the de-facto standard (VS Code tests with it); it is the reason GroundWork picked this stack — the strongest agent-closable loop of any desktop option. The driver needs **no browser downloads** (`playwright install` is unnecessary): it launches the app's own Electron binary.
+
+The generated smoke (`tests/smoke/app.spec.ts`) is the canonical shape: launch the **built** app, first window, title + rendered heading, one IPC round-trip, the theme push channel, one main-process assertion.
+
+## _electron Patterns
+
+```ts
+import { _electron as electron } from 'playwright';
+
+const app = await electron.launch({ args: ['out/main/index.js'] });
+const page = await app.firstWindow();          // a normal Playwright Page
+```
+
+- **Renderer assertions** — everything Playwright can do to a web page: `expect(page).toHaveTitle(...)`, `getByRole`, `getByTestId`, screenshots.
+- **Bridge round-trips** — `page.evaluate(() => globalThis.api.foo())` exercises preload + sender validation + handler end-to-end. (Cast `globalThis`; the smoke compiles under the node tsconfig, which has no DOM types.)
+- **Main-process assertions** — `app.evaluate(({ app, nativeTheme }) => ...)` runs **inside main** with the electron module injected: assert on windows, theme state, app metadata. This hook is unique to Electron among desktop options.
+- **Push-channel proof** — assert the DOM consequence, e.g. `toHaveAttribute('data-theme', /^(light|dark)$/)` after main's initial broadcast.
+- **Always `await app.close()`** in a `finally` — a leaked Electron process wedges CI workers.
+- Launching a **packaged** binary instead of the dev build: `electron.launch({ executablePath })` — worth one lane before releases; the day-to-day smoke uses the built output for speed.
+- Driver/runtime pairings can regress across Electron majors (the 36.x `Process failed to launch!` Linux regression, fixed in 37) — when a major bump breaks launch, check the pairing before debugging the app.
+
+## CI: xvfb and Skip-with-Reason
+
+Electron is never truly headless — Linux CI needs a display server. The `smoke` target routes through `tool/electron_exec.sh`, which:
+
+1. Verifies `node_modules` and the Electron binary exist (bootstrap state) — else **"tier skipped"** with the bootstrap command.
+2. On Linux with no `DISPLAY`/`WAYLAND_DISPLAY`: wraps the run in `xvfb-run --auto-servernum` when available — else **"smoke tier skipped"** naming xvfb.
+3. Builds, then runs `playwright test`.
+
+The contract is *skipped-with-reason, never silently green*: a missing toolchain degrades exactly the way a missing Docker daemon degrades `./dev`. CI installs `xvfb` to run the lane for real; macOS/Windows runners and desktop sessions need no wrapper. Artifacts on failure (screenshot, trace) are configured in `playwright.config.ts`.
+
+## Keeping the Smoke Thin
+
+Boot minutes are this stack's expensive test currency. The smoke proves the app **boots and is wired** — it is not an E2E suite:
+
+- One spec, happy path, serial (`workers: 1`).
+- New IPC channels get unit tests (policy + renderer fake) by default; extend the smoke only when a channel's *wiring* is novel (new push mechanism, new window).
+- Feature behaviour belongs in renderer unit tests; business rules belong at the core's contract. A fat smoke is the fat-integration-suite antipattern wearing a desktop coat.
+
+## Test Commands
+
+```bash
+npx nx run <app>:test        # both vitest projects (node + jsdom)
+npx nx run <app>:test -- --project renderer   # one project
+npx nx run <app>:smoke       # build + Playwright _electron (display-guarded)
+npx nx run <app>:typecheck   # tsc, both process tsconfigs
+npx nx run <app>:lint        # eslint incl. process-boundary rules
+```

package/src/engineer-skills/groundwork-electron-engineer/references/theming-and-tokens.md

@@ -0,0 +1,74 @@
+# Theming & Tokens — the Desktop Delta
+
+This reference covers **only what the desktop shell adds** to theming. Tailwind composition rules, styling discipline, visual language, and accessibility are the web stack's, unchanged: `groundwork-nextjs-engineer/references/tailwind-and-styling.md` and `groundwork-nextjs-engineer/references/visual-language.md` (or `docs/principles/stack/typescript/frontend.md` when no web surface is installed).
+
+## Table of Contents
+- [The Projection Chain](#the-projection-chain)
+- [The Generated brand.css](#the-generated-brandcss)
+- [The @theme Mapping](#the-theme-mapping)
+- [nativeTheme Sync (the Desktop Dark Mode)](#nativetheme-sync-the-desktop-dark-mode)
+- [Evolving the Brand](#evolving-the-brand)
+
+---
+
+## The Projection Chain
+
+The theme is **generated from the design system's brand tokens**, not authored in the app:
+
+```
+docs/design-system.md → .groundwork/config/brand-tokens.json (visual block)
+                      → src/renderer/src/assets/brand.css      (GENERATED)
+                      → @theme inline mapping in main.css       (static)
+                      → Tailwind utilities in components
+```
+
+The same tokens drive every surface of the product (web, CLI, mobile, desktop), so cross-surface visual consistency is a build artifact, not a review hope. A hex literal in a component is a review finding — it forks the design system silently.
+
+## The Generated brand.css
+
+`brand.css` carries the projected values as CSS custom properties and is regenerated, never hand-edited:
+
+- Palette roles in both themes: `--gw-primary`, `--gw-accent`, `--gw-surface`, `--gw-surface-alt`, `--gw-text-body`, `--gw-success`, `--gw-error`, `--gw-warning`, `--gw-info` — light values on `:root`, dark values on `:root[data-theme='dark']`.
+- Typography: `--gw-font-display`/`--gw-font-body` (+ weights). Families render once they are bundled or system-available.
+- Shape: `--gw-radius-base`.
+
+Unlike the Dart projection (which resolves OKLCH at generation time), the renderer is CSS — token values pass through verbatim and Chromium resolves OKLCH natively. The file header records the projection source (`visual-block`, `identity-only`, or `default` — the three-tier fallback every token consumer implements).
+
+## The @theme Mapping
+
+`main.css` maps the custom properties into Tailwind v4 theme tokens once:
+
+```css
+@theme inline {
+  --color-primary: var(--gw-primary);
+  --color-surface: var(--gw-surface);
+  --color-foreground: var(--gw-text-body);
+  --font-display: var(--gw-font-display);
+  --radius-base: var(--gw-radius-base);
+  /* ... */
+}
+```
+
+Components consume the utilities these tokens create (`bg-surface`, `text-primary`, `font-display`, `rounded-base`) and **never read `--gw-*` variables directly** — the mapping is the API, the variables are the projection artifact. Tailwind v4 is CSS-first: there is no `tailwind.config.js`; the plugin loads in the **renderer section** of `electron.vite.config.ts` and applies to the renderer only (main and preload have no styling surface). Needing a new semantic token means extending the `@theme` mapping from a `--gw-*` value — and if no token expresses the need, that is a design-system gap to raise, not a license to inline a value.
+
+## nativeTheme Sync (the Desktop Dark Mode)
+
+On desktop, the OS owns dark mode and **main is the source of truth** — this is the structural difference from the web stack's `next-themes` approach:
+
+1. Main broadcasts `nativeTheme.shouldUseDarkColors` on the `theme:changed` push channel — once after `did-finish-load`, and on every `nativeTheme.on('updated')`.
+2. The renderer's entry point subscribes via the bridge and mirrors the value onto `<html data-theme="dark|light">`.
+3. `brand.css` resolves every `--gw-*` per theme from that attribute; utilities update without component involvement.
+
+Implementation rules:
+
+- Components never branch on theme to pick values — the custom properties already resolved per-theme. (Conditional *structure* via a `data-theme` selector is fine; conditional *colours* is the antipattern.)
+- Every role carries light **and** dark values — a design-system commitment, not an option; verify visual changes in both themes (flip the OS setting, or `app.evaluate(({ nativeTheme }) => { nativeTheme.themeSource = 'dark'; })` in a smoke-side check).
+- A user-facing theme override (light/dark/system menu) is implemented by setting `nativeTheme.themeSource` in main via an IPC channel — keeping main the single source of truth — never by writing `data-theme` directly from a component.
+
+## Evolving the Brand
+
+1. The design-system run updates `brand-tokens.json`.
+2. Regenerate (or mechanically update) `brand.css` to match — the header marks it generated; keep the `:root` / `:root[data-theme='dark']` structure intact.
+3. The `@theme` mapping and all components pick the change up for free. New palette roles need one new mapping line in `main.css`.
+
+If a visual change cannot be expressed through tokens → brand.css → @theme → utilities, raise the design-system gap; do not hand-edit the projection.

package/src/engineer-skills/groundwork-electron-engineer/sync-anchor.md

@@ -0,0 +1,14 @@
+# Sync Anchor
+
+This file pins the principle files this skill embeds. When any listed file
+changes, this skill must be reviewed in the same commit. CI verifies the
+hashes match.
+
+| Principle file | SHA-256 | Last reviewed |
+|---|---|---|
+| src/generators/electron-app/docs/principles/stack/electron/index.md | b983b5455f03d97c36647021a1c05aa6f2f0a0a23b9a0ffc284b161a0185fbd2 | 2026-06-24 |
+| src/generators/electron-app/docs/principles/stack/electron/process-model.md | d510797d59a06786fb6bd35f537566ee7f1024ce35a8985c9c94d305e3de5c43 | 2026-06-12 |
+| src/generators/electron-app/docs/principles/stack/electron/ipc-contracts.md | 11d728db5d33c0c9cb3a082a58a55c96d6195f61558ca38fae91806db72da9e3 | 2026-06-12 |
+| src/generators/electron-app/docs/principles/stack/electron/security.md | 316c118dcfb6de110d3d62b8a4c95ca79b58f5368e1b41881cd842628b3902f8 | 2026-06-12 |
+| src/generators/electron-app/docs/principles/stack/electron/packaging-and-updates.md | b5f91ed102290dd73e52890fd389bce5be825a3d76a0f0353673cfe32ae09871 | 2026-06-12 |
+| src/generators/electron-app/docs/principles/stack/typescript/frontend.md | 98232d067ad03c08d6c1ca5f2caec30e7c3400da55c3afb7754482bc121d7554 | 2026-06-12 |

package/src/engineer-skills/groundwork-flutter-engineer/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: groundwork-flutter-engineer
+description: >
+  Implement, review, and refactor Flutter mobile applications using the
+  official two-layer MVVM architecture, Riverpod state management, go_router
+  navigation, token-projected theming, widget and integration testing, Pigeon
+  platform channels, and store release engineering. Use for work touching
+  views, view models, repositories, services, providers, routing, theming,
+  widget tests, integration tests, native interop, or mobile release
+  pipelines. Make sure to use this skill whenever a user is working in a
+  Flutter or Dart codebase, building mobile UI features, fixing mobile bugs,
+  or reviewing Flutter code.
+---
+
+# Flutter Engineer
+
+Mobile execution engineer for Flutter applications. This skill guides implementation within the official Flutter architecture — MVVM features over a repository data layer, a compile-safe Riverpod provider graph, token-projected theming, and a test pyramid whose expensive tiers stay thin because the surface proves wiring, not business logic.
+
+## Operating Contract
+
+1. Locate the architectural layer before editing. Views, view models, repositories, services, and domain models each have distinct responsibilities; a change that blurs them is wrong even when it works.
+2. The capability core owns business logic. The surface is wired to it through a typed client in the data layer — never re-implement a rule the core's contract already proves.
+3. Route durable mobile policy to the canonical docs (`docs/principles/stack/flutter/`) instead of duplicating it in code comments or this skill.
+4. Verify lints, widget tests, theme consumption, and accessibility semantics before declaring work complete.
+
+## Code intelligence (repo map + Serena)
+
+GroundWork gives you a deterministic **repo map** (`npx groundwork-method repo-map` — tree-sitter import edges + PageRank centrality, cached to `.groundwork/cache/repo-map.json`) and the **Serena** MCP server (LSP-backed symbol navigation and editing), registered at init. Orient before reading widely: refresh the map, read its `centrality` ranking to find the hubs, then use Serena to navigate them (`get_symbols_overview` / `find_symbol` / `find_referencing_symbols`) and make reference-aware edits (`replace_symbol_body` / `rename`). Full workflow and the graceful-degradation contract live in `.groundwork/skills/code-intelligence.md`; fall back to ordinary reads and edits when they are unavailable.
+
+## Core Pillars
+
+1. **MVVM Over Two Layers** — Every feature is one View (widgets only) paired with one ViewModel (state + commands). Repositories are the data layer's source of truth; services wrap external interfaces. A Domain layer is added only when it earns its place. This is the official Flutter architecture, adopted wholesale — code written against it is code every Flutter engineer recognises.
+
+2. **The Provider Graph Is the App** — Riverpod 3.x providers carry shared state and double as dependency injection. Construction order, disposal, and test substitution fall out of the graph. There is no service locator, no `provider`-package DI, and no GetX — ever.
+
+3. **Theming Is a Projection** — `ThemeData` is built from a palette module generated from the design system's brand tokens. Widgets consume `Theme.of(context)` and theme extensions; a `Color(0xFF...)` literal in a widget file is a review finding.
+
+4. **Tests Prove Wiring, Not Rules** — Widget tests are the bulk of coverage; `integration_test` happy paths run on a headless Android emulator; Patrol enters only at the Flutter/OS boundary. Business rules are proven once at the core's contract — surface tests never re-prove them.
+
+5. **Native Is a Disciplined Hatch** — Dropping to Swift/Kotlin is a capability decision made through Pigeon's typed boundary, wrapped as a data-layer service. Never a performance reflex, never a raw `MethodChannel` for a real API surface.
+
+## How to Use This Skill
+
+Match the user's task to the smallest relevant reference set. Most tasks touch one or two references.
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Architecture & Layers | `references/architecture.md` | Placing new code, understanding the MVVM/repository split, file organization, the core-access seam. |
+| State Management | `references/state-management.md` | Providers, Notifiers, Mutations, ephemeral vs app state, provider testing seams. |
+| Widgets & Composition | `references/widgets-and-composition.md` | Building or refactoring widgets, const discipline, build purity, keys, extraction. |
+| Theming & Design Tokens | `references/theming-and-design-tokens.md` | Theme consumption, the generated palette, ThemeExtensions, dark mode, typography. |
+| Navigation | `references/navigation.md` | go_router routes, shell routes, redirects, typed routes, deep links. |
+| Data & Contracts | `references/data-and-contracts.md` | Repositories, services, the dio contract client, error mapping, contract-client tooling. |
+| Testing | `references/testing.md` | Unit/widget/integration taxonomy, fakes, emulator CI, Patrol, goldens, test commands. |
+| Platform Channels | `references/platform-channels.md` | Pigeon APIs, native modules, when to drop to Swift/Kotlin, SwiftPM wiring. |
+| Releases & Distribution | `references/releases-and-distribution.md` | Signing, CI/CD pipelines, versioning, forced upgrade, Shorebird code push. |
+| Accessibility | `references/accessibility.md` | Semantics, tap targets, dynamic type, contrast, a11y-driven testing. |
+
+## Task Routing
+
+- **New feature/screen** → Load `references/architecture.md`. One View + one ViewModel under `ui/<feature>/`; repository access only through the view model.
+- **State or data-flow work** → Load `references/state-management.md`. Verify what is app state (provider) vs ephemeral (`setState`).
+- **UI/visual work** → Load `references/widgets-and-composition.md` and `references/theming-and-design-tokens.md`. Check the generated palette before adding any colour.
+- **API/contract work** → Load `references/data-and-contracts.md`. The client is the seam; repositories translate payloads to domain models.
+- **Routing/deep-link work** → Load `references/navigation.md`. Check the existing route table conventions first.
+- **Test work** → Load `references/testing.md`. Pick the cheapest tier that can carry the assertion.
+- **Native capability work** → Load `references/platform-channels.md`. Check pub.dev for a maintained plugin before writing native code.
+- **Release/store work** → Load `references/releases-and-distribution.md`. Signing material never enters the repo.
+
+## Safety Gates
+
+- Do not put business logic in widgets or `build` methods — it belongs in the view model, or more likely in the capability core.
+- Do not introduce hardcoded colours, text styles, radii, or spacing. The theme module is generated from brand tokens.
+- Do not add state-management or DI packages (`provider`, `get_it`, GetX, Bloc) without a recorded decision; Riverpod is the standing default.
+- Do not re-implement a rule the core's contract proves, and do not hand-map a large promoted contract — generated clients exist for that.
+- Do not build on experimental Riverpod APIs (offline persistence) in load-bearing paths.
+- Run `flutter analyze` and `flutter test` where the SDK is available; report the tier as skipped (never silently green) where it is not.
+
+## Hallucination Controls
+
+Before presenting Flutter guidance as factual:
+
+- Check `pubspec.yaml` for actual package versions and available dependencies.
+- Check the existing `ui/`, `data/`, and `domain/` directories for naming conventions and patterns before proposing new ones.
+- Check the generated theme module for colour and shape values before recommending visual changes.
+- Check the route table in the router module before inventing paths or navigation flows.
+- Label any recommendation based on general Flutter knowledge (rather than project-specific patterns) as an inference.
+
+## Output Expectations
+
+- Feature changes name the layer each file belongs to and why.
+- UI changes reference the theme roles or extensions used, or justify an explicit deviation.
+- New features include accessibility considerations (semantic labels, tap targets, dynamic type behaviour).
+- Verification steps include the specific Nx targets or `flutter` commands to run, with the skipped-with-reason caveat when the SDK is absent.
+- Recommendations distinguish project conventions from general Flutter practice.
+
+## Antipatterns
+
+Reject these patterns:
+
+- **Logic in build methods** — Domain branching inside widgets instead of the view model. Build renders state.
+- **setState as architecture** — App state held in `StatefulWidget`s and threaded through constructors. Ephemeral state only.
+- **Hardcoded visual values** — Hex colours, raw `TextStyle`s, magic paddings that fork the design system silently.
+- **Hand-written clients for large promoted contracts** — The contract is promoted precisely so clients can be generated from it.
+- **Re-proving core logic on the surface** — Surface tests assert wiring and rendering; the contract suite already proved the rules.
+- **Fat integration suites** — Emulator minutes are the most expensive test currency; widget tests carry the bulk.
+- **Raw MethodChannels for real APIs** — Stringly-typed, runtime-failing. Pigeon exists.
+- **Preemptive Domain layers** — Pass-through use-case classes add indirection and remove nothing.

package/src/engineer-skills/groundwork-flutter-engineer/references/accessibility.md

@@ -0,0 +1,92 @@
+# Accessibility
+
+## Table of Contents
+- [The Baseline](#the-baseline)
+- [Semantics](#semantics)
+- [Tap Targets](#tap-targets)
+- [Dynamic Type](#dynamic-type)
+- [Contrast](#contrast)
+- [Accessibility as the Test Seam](#accessibility-as-the-test-seam)
+- [Review Checklist](#review-checklist)
+
+---
+
+## The Baseline
+
+Accessibility is a merge gate, not a backlog item. The baseline for every feature: semantic labels on interactive widgets, 48dp tap targets, WCAG AA contrast (inherited from the token palette), and layouts that survive large text scales. An accessibility failure blocks the slice the way a failing test does.
+
+## Semantics
+
+Every interactive widget exposes a meaningful semantic label — through the widget's built-in semantics (`Text`, `Tooltip`, button labels) or an explicit `Semantics` wrapper when the visual content alone is ambiguous:
+
+```dart
+// Icon-only button: the tooltip doubles as the semantic label.
+IconButton(
+  icon: const Icon(Icons.refresh),
+  tooltip: 'Refresh gateway status',
+  onPressed: onRefresh,
+)
+
+// Composite tile whose meaning isn't the sum of its texts:
+Semantics(
+  label: 'Order ${order.id}, ${order.statusLabel}',
+  button: true,
+  child: OrderTile(order: order),
+)
+```
+
+Guidelines:
+
+- Labels describe **meaning, not appearance** ("Refresh gateway status", not "circular arrow icon").
+- Don't over-wrap: redundant `Semantics` around already-labelled widgets produces double announcements. Use `MergeSemantics` to combine fragments that should read as one.
+- Purely decorative visuals get `ExcludeSemantics`.
+- Dynamic state (loading, error) is announced — render it as text or update the label, don't communicate it by colour alone.
+
+## Tap Targets
+
+Interactive targets meet the **48dp minimum** in both dimensions. Material widgets enforce this by default (`materialTapTargetSize`); the rule bites with custom `GestureDetector`/`InkWell` wrappers around small visuals:
+
+```dart
+// Small visual, full-size target:
+InkWell(
+  onTap: onTap,
+  child: const SizedBox(
+    width: 48,
+    height: 48,
+    child: Center(child: Icon(Icons.close, size: 20)),
+  ),
+)
+```
+
+## Dynamic Type
+
+Layouts must not break at large text scales. Practical rules:
+
+- Never set fixed heights on text-bearing containers; let text size drive layout.
+- Test at scale: pump widget tests with `MediaQuery(textScaler: TextScaler.linear(2.0))` for layout-sensitive components, and exercise device large-text settings during manual passes.
+- Truncation (`overflow: TextOverflow.ellipsis`) is for genuinely unbounded user content, not a fix for layouts that can't absorb scale.
+
+## Contrast
+
+Contrast meets WCAG AA **via the token palette** — it is enforced at the design-system layer and inherited here. The implementation duty: consume theme roles (see `references/theming-and-design-tokens.md`) so the audited pairs stay paired. Hand-mixed colours (opacity hacks, lightened variants) silently break audited contrast and are review findings on two counts.
+
+## Accessibility as the Test Seam
+
+Flutter's semantics tree is also the widget-test seam: tests find by `find.bySemanticsLabel` and visible text, so **inaccessible UI is untestable UI**. This makes the baseline self-enforcing — a widget you cannot address semantically in a test is a widget a screen reader cannot address either. When a test reaches for `find.byType` or a key because nothing semantic exists, treat it as the accessibility defect it is and label the widget.
+
+```dart
+testWidgets('refresh is reachable by semantics', (tester) async {
+  await tester.pumpWidget(harness());
+  expect(find.bySemanticsLabel('Refresh gateway status'), findsOneWidget);
+});
+```
+
+## Review Checklist
+
+- [ ] Every interactive widget has a meaningful semantic label.
+- [ ] Icon-only buttons carry `tooltip` or `Semantics`.
+- [ ] Custom gesture surfaces meet 48dp.
+- [ ] No state communicated by colour alone.
+- [ ] Layout verified (or tested) at 2.0 text scale.
+- [ ] All colours via theme roles — no hand-mixed variants.
+- [ ] Widget tests find by semantics, not widget types.

package/src/engineer-skills/groundwork-flutter-engineer/references/architecture.md

@@ -0,0 +1,189 @@
+# Architecture
+
+## Table of Contents
+- [The Layer Model](#the-layer-model)
+- [File Organization](#file-organization)
+- [Views and ViewModels](#views-and-viewmodels)
+- [Repositories and Services](#repositories-and-services)
+- [The Core-Access Seam](#the-core-access-seam)
+- [Domain Models and Immutability](#domain-models-and-immutability)
+- [When a Domain Layer Is Earned](#when-a-domain-layer-is-earned)
+- [Placement Checklist](#placement-checklist)
+
+---
+
+## The Layer Model
+
+This codebase follows the official Flutter architecture: a **UI layer** of MVVM features over a **data layer** of repositories and services. A Domain layer of use-cases exists only where it has earned its place. Dependency direction is strict and single-direction:
+
+```
+View  →  ViewModel  →  Repository (abstract)  →  Service (ApiClient, platform APIs)
+                              ↓
+                       domain models
+```
+
+- A View never imports a repository, a service, or `dio`.
+- A ViewModel never imports widgets or `BuildContext`.
+- A repository never imports another repository — cross-repository orchestration belongs in a view model (or an earned use-case).
+- Services are stateless and never aware of repositories.
+
+The app is a **surface adapter** over the workspace's capability core. Business rules live behind the promoted contracts and are proven there; if you find yourself implementing a pricing rule, a permission check, or validation semantics in Dart, stop — that logic belongs in the core, and the surface renders its results.
+
+---
+
+## File Organization
+
+`ui/` is feature-first; `data/` and `domain/` are type-first:
+
+```
+lib/
+├── main.dart                  # ProviderScope root — nothing else
+├── app.dart                   # MaterialApp.router + theme wiring
+├── router.dart                # the go_router route table
+├── config/app_config.dart     # --dart-define configuration
+├── ui/
+│   ├── core/theme/            # generated palette + theme builder
+│   └── <feature>/
+│       ├── <feature>_view.dart
+│       └── <feature>_view_model.dart
+├── data/
+│   ├── repositories/          # <entity>_repository.dart: abstract + impl
+│   └── services/              # api_client.dart, platform service wrappers
+└── domain/
+    └── models/                # immutable models
+```
+
+Naming is the official convention and is load-bearing — predictable names are how the next agent finds the right file on the first try: `HomeView`/`HomeViewModel`, `UserRepository`/`RemoteUserRepository`, `AuthService`. Do not invent variants (`HomeScreen`, `HomeController`, `UserStore`).
+
+For large apps, split features into local packages with Dart pub workspaces (`resolution: workspace`); Melos 7.x (configured under the `melos:` key in the root pubspec) handles scripts and versioning. Layer-first roots (`/screens`, `/widgets`, `/models`) are legacy — do not recreate them.
+
+---
+
+## Views and ViewModels
+
+Every feature is exactly one View paired with exactly one ViewModel.
+
+**The View** is widgets only — layout, animation, conditional rendering, simple navigation calls. It watches its view model provider and dispatches commands:
+
+```dart
+class ProfileView extends ConsumerWidget {
+  const ProfileView({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final state = ref.watch(profileViewModelProvider);
+    return state.when(
+      loading: () => const CircularProgressIndicator(),
+      error: (e, _) => ErrorPanel(error: e),
+      data: (profile) => ProfileBody(
+        profile: profile,
+        onRename: (name) =>
+            ref.read(profileViewModelProvider.notifier).rename(name),
+      ),
+    );
+  }
+}
+```
+
+**The ViewModel** is an `AsyncNotifier` (or `Notifier` for synchronous state) exposing an immutable state object and methods as commands:
+
+```dart
+class ProfileViewModel extends AsyncNotifier<ProfileState> {
+  @override
+  Future<ProfileState> build() async {
+    final user = await ref.watch(userRepositoryProvider).current();
+    return ProfileState(user: user);
+  }
+
+  Future<void> rename(String name) async {
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(() async {
+      final user = await ref.read(userRepositoryProvider).rename(name);
+      return ProfileState(user: user);
+    });
+  }
+}
+```
+
+Red flags: a `build` method with an `if` on a domain rule; a view model importing `material.dart`; a widget calling a repository.
+
+---
+
+## Repositories and Services
+
+**Repositories** are the source of truth. They own caching, retry, polling, and translating contract payloads into domain models. Always an abstract class plus an implementation, exposed as a provider:
+
+```dart
+abstract class OrderRepository {
+  Future<List<Order>> recent();
+  Stream<Order> watch(String id);
+}
+
+class RemoteOrderRepository implements OrderRepository {
+  RemoteOrderRepository(this._client);
+  final ApiClient _client;
+  // translate contract DTOs → domain models here, nowhere else
+}
+
+final orderRepositoryProvider = Provider<OrderRepository>(
+  (ref) => RemoteOrderRepository(ref.watch(apiClientProvider)),
+);
+```
+
+The abstract class is the test seam: an in-memory `FakeOrderRepository` serves unit and widget tests without a mocking framework.
+
+**Services** are stateless wrappers over external interfaces — the contract client, platform APIs (via Pigeon), local storage — exposing `Future`/`Stream`. They hold no app state and know nothing about repositories or features.
+
+---
+
+## The Core-Access Seam
+
+The typed contract client lives in `data/services/` and is consumed only by repositories:
+
+- The client is **thin and hand-rolled while the contract surface is small**: one method per promoted-contract operation, typed models in `domain/models/`. (This is the recorded tooling stance; see `references/data-and-contracts.md`.)
+- When the promoted `openapi.yaml` grows past a handful of operations, switch to generated clients (`openapi_generator` dart-dio) — the repositories keep their shape, so nothing above the data layer changes.
+- **Nothing above the data layer knows the transport.** A view model cannot tell whether the core is REST or gRPC, hosted or embedded. If a view model is constructing URLs or reading `DioException`s, the seam has leaked.
+
+---
+
+## Domain Models and Immutability
+
+Domain models are immutable. Plain `const` classes suffice while models are trivial; introduce **freezed** when models carry real shape — unions, `copyWith`, exhaustive matching, JSON round-trips — because at that point its codegen earns the build_runner step:
+
+```dart
+@freezed
+sealed class Order with _$Order {
+  const factory Order.draft({required String id}) = DraftOrder;
+  const factory Order.placed({required String id, required DateTime at}) = PlacedOrder;
+  factory Order.fromJson(Map<String, dynamic> json) => _$OrderFromJson(json);
+}
+```
+
+Never add a mutable field to a domain model to "simplify" an update path — that is the unidirectional flow breaking.
+
+---
+
+## When a Domain Layer Is Earned
+
+Add a use-case class only when at least one of these is true:
+
+1. Logic **merges multiple repositories** (and would otherwise live awkwardly in one view model).
+2. The logic is **genuinely complex** and burying it in a view model harms testability.
+3. The logic is **reused across view models**.
+
+A use-case that forwards a single repository call is indirection tax — delete it. Default is two layers.
+
+---
+
+## Placement Checklist
+
+Before creating a file, answer:
+
+| The code... | It goes in |
+|---|---|
+| renders widgets | `ui/<feature>/<feature>_view.dart` |
+| holds feature state / handles user events | `ui/<feature>/<feature>_view_model.dart` |
+| decides which data is the truth (cache, retry, merge) | `data/repositories/` |
+| talks to the network, OS, or storage | `data/services/` |
+| is a value the app passes around | `domain/models/` |
+| is a business rule | the capability core, not this app |