groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-flutter-engineer/references/state-management.md

@@ -0,0 +1,166 @@
+# State Management
+
+## Table of Contents
+- [The Rules](#the-rules)
+- [Providers Are the Graph](#providers-are-the-graph)
+- [Notifier and AsyncNotifier](#notifier-and-asyncnotifier)
+- [Mutations for Action Lifecycle](#mutations-for-action-lifecycle)
+- [App State vs Ephemeral State](#app-state-vs-ephemeral-state)
+- [ref.watch vs ref.read](#refwatch-vs-refread)
+- [Testing Providers](#testing-providers)
+- [Refused Packages and Patterns](#refused-packages-and-patterns)
+
+---
+
+## The Rules
+
+1. **Riverpod 3.x** is the state-management and DI mechanism. One tool for both; no second container.
+2. Everything shared is a provider; everything provider-shaped is testable through overrides.
+3. Pin 3.x conservatively — the experimental offline-persistence API never enters load-bearing paths.
+4. `setState` survives only for ephemeral widget-local state.
+
+---
+
+## Providers Are the Graph
+
+Repositories, services, the contract client, view models, and derived state are all providers. The provider graph **is** the dependency-injection graph:
+
+```dart
+final apiClientProvider = Provider<ApiClient>((ref) => ApiClient(/* ... */));
+
+final userRepositoryProvider = Provider<UserRepository>(
+  (ref) => RemoteUserRepository(ref.watch(apiClientProvider)),
+);
+
+// Derived read-only state: a plain provider, not a class.
+final unreadCountProvider = Provider<int>(
+  (ref) => ref.watch(inboxViewModelProvider).valueOrNull?.unread.length ?? 0,
+);
+```
+
+Construction order, disposal, and test substitution fall out of the graph. Do not write a `Notifier` class where a derived provider (a function) suffices.
+
+`ProviderScope` at the root of `main.dart` is the only composition root. There is no `get_it`, no manually threaded constructors across features, no `InheritedWidget` plumbing for app state.
+
+---
+
+## Notifier and AsyncNotifier
+
+A view model is a `Notifier` (synchronous initial state) or `AsyncNotifier` (asynchronous initial state). `build` declares dependencies with `ref.watch` — when a dependency changes, state recomputes:
+
+```dart
+class InboxViewModel extends AsyncNotifier<InboxState> {
+  @override
+  Future<InboxState> build() async {
+    final messages = await ref.watch(messageRepositoryProvider).inbox();
+    return InboxState(messages: messages);
+  }
+
+  // Commands: the only way the view mutates anything.
+  Future<void> archive(String id) async {
+    await ref.read(messageRepositoryProvider).archive(id);
+    ref.invalidateSelf(); // re-derive from the source of truth
+  }
+}
+
+final inboxViewModelProvider =
+    AsyncNotifierProvider<InboxViewModel, InboxState>(InboxViewModel.new);
+```
+
+Prefer `ref.invalidateSelf()` (re-derive from the repository) over hand-patching state when the repository is cheap to re-read — hand-patched state drifts from the source of truth.
+
+In views, render `AsyncValue` exhaustively:
+
+```dart
+final state = ref.watch(inboxViewModelProvider);
+return state.when(
+  loading: () => const InboxSkeleton(),
+  error: (e, _) => ErrorPanel(error: e, onRetry: ...),
+  data: (inbox) => InboxList(inbox: inbox),
+);
+```
+
+Never `.valueOrNull!` your way past the loading and error cases in a view.
+
+---
+
+## Mutations for Action Lifecycle
+
+User actions that need pending/success/error surfacing — submit, delete, retry — use Riverpod 3 **Mutations** instead of hand-rolled `isLoading` booleans:
+
+```dart
+final archiveMessage = Mutation<void>();
+
+// In the view model / command site:
+archiveMessage.run(ref, (tsx) async {
+  await tsx.get(messageRepositoryProvider).archive(id);
+});
+
+// In the view:
+final archiveState = ref.watch(archiveMessage);
+// idle / pending / success / error — render the spinner or the failure from this.
+```
+
+One mutation per user action. If you are writing `bool _submitting` into a state class, reach for a Mutation instead.
+
+---
+
+## App State vs Ephemeral State
+
+The boundary question: **does anything outside this widget care?**
+
+| State | Mechanism |
+|---|---|
+| Session, fetched data, feature view state | provider / Notifier |
+| Selected tab, selected entity id, current screen | the **route** (go_router) — never duplicated in a provider |
+| Text-field focus, animation progress, tile expanded | `setState` in a `StatefulWidget` |
+
+Two corollaries:
+
+- **Route-mirroring providers drift.** If go_router already encodes it, read it from the route.
+- **State must be recoverable.** Mobile processes die constantly; anything not rebuildable from the core or the route is state the app silently loses. Design state so `build()` can reconstruct it.
+
+---
+
+## ref.watch vs ref.read
+
+- `ref.watch` — in `build` methods (Notifier and widget alike). Declares a reactive dependency.
+- `ref.read` — inside callbacks and commands only. A `ref.read` in `build` silently opts out of reactivity and is a bug even when it appears to work.
+- `ref.listen` — for side-effects on state change (showing a snackbar on error) — never for deriving state.
+
+---
+
+## Testing Providers
+
+Providers test without widgets. `ProviderContainer` plus overrides substitutes fakes at any node:
+
+```dart
+test('archiving removes the message from inbox state', () async {
+  final fakeRepo = FakeMessageRepository(seed: [message1, message2]);
+  final container = ProviderContainer(
+    overrides: [messageRepositoryProvider.overrideWithValue(fakeRepo)],
+  );
+  addTearDown(container.dispose);
+
+  await container.read(inboxViewModelProvider.future);
+  await container.read(inboxViewModelProvider.notifier).archive(message1.id);
+
+  final state = await container.read(inboxViewModelProvider.future);
+  expect(state.messages, [message2]);
+});
+```
+
+Widget tests use the same seam through `ProviderScope(overrides: [...])`. Test the **real Notifier with fake repositories** — mocking the Notifier itself proves nothing. Fakes over mocks throughout (see `references/testing.md`).
+
+---
+
+## Refused Packages and Patterns
+
+These are named so they are recognised and refused in review:
+
+- **GetX** — global mutable service locators, context-free magic. Never, in any role.
+- **provider as state management** — the 2019–2022 pattern; Riverpod is its successor by the same author. With Riverpod, even provider's DI role is subsumed — do not run both.
+- **setState as architecture** — app state in `StatefulWidget`s threaded through constructors.
+- **Riverpod experimental persistence** — explicitly experimental; not in load-bearing paths.
+- **Bloc** — not wrong, but a deliberate alternative for regulated/large-team contexts. Adopting it is a recorded decision, not a drift; never mix it with Riverpod in one app.
+- **One god-provider per screen** — split by concern; the graph recomputes at the right granularity only if you let it.

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

@@ -0,0 +1,160 @@
+# Testing
+
+## Table of Contents
+- [The Taxonomy](#the-taxonomy)
+- [The Prove-Once Rule](#the-prove-once-rule)
+- [Unit Tests](#unit-tests)
+- [Widget Tests](#widget-tests)
+- [Integration Tests](#integration-tests)
+- [Patrol — the OS Boundary Only](#patrol--the-os-boundary-only)
+- [Golden Tests](#golden-tests)
+- [CI Lanes](#ci-lanes)
+- [Test Commands](#test-commands)
+
+---
+
+## The Taxonomy
+
+| Tier | Scope | Runs on | Budget |
+|---|---|---|---|
+| Unit | view models, repositories, mappers (pure Dart) | anywhere, milliseconds | generous |
+| Widget | feature views via `testWidgets` | headless, seconds | **the bulk of coverage** |
+| `integration_test` | happy-path E2E through the real binary | headless Android emulator | thin — minutes per test |
+| Patrol | flows crossing the Flutter/OS boundary | emulator/device | only when the OS is in the flow |
+| Goldens (alchemist) | design-system-level components | CI with text-as-blocks variants | component library only |
+
+Pick the **cheapest tier that can carry the assertion**. If a widget test can prove it, an integration test that proves it is waste.
+
+This taxonomy is the Flutter idiom of the framework testing canon (`docs/principles/foundations/testing.md`): widget tests are the fat middle that the canon's honeycomb puts the weight on, unit tests are the thin solitary layer, and `integration_test` is the few-end-to-end top. When this file and the canon disagree, the canon wins and this file is the one to fix.
+
+Above all of these sits the front-door proof the canon now demands: an `integration_test` harness driving the real shipping app the way a user does — end to end against the real backend, not a fake gateway — because widget tests that each pass against fakes can still assemble into an app that does nothing on the real data path. And the fake-needs-a-real-test rule follows from it: a mock repository or fixture standing in for a real stage is a debt that some integration test of the real producer must pay. Seeded inputs are fine; faking the work in the middle with nothing real behind it is a green light wired to nothing. See `docs/principles/foundations/testing.md`.
+
+## The Prove-Once Rule
+
+Capability behaviour is proven once, headless, at the core's contract. The surface suite proves three things only:
+
+1. **Wiring** — the typed client/repository is called with the right inputs.
+2. **Rendering** — core state renders correctly (including error and empty states).
+3. **Interaction** — commands fire, navigation moves, errors surface.
+
+A widget or integration test re-asserting a business rule (price calculation, permission logic, validation semantics) is a review finding: it duplicates a proof that exists at the contract and couples this suite to core internals.
+
+## Unit Tests
+
+Pure Dart, **fakes over mocks**. An in-memory fake implementing the abstract repository survives refactors that stub-and-verify mocks break on, and doubles as the widget-test fixture:
+
+```dart
+class FakeOrderRepository implements OrderRepository {
+  FakeOrderRepository({List<Order> seed = const []}) : _orders = [...seed];
+  final List<Order> _orders;
+  Order? lastPlaced;
+
+  @override
+  Future<List<Order>> recent({bool refresh = false}) async => _orders;
+
+  @override
+  Future<Order> place(PlaceOrderRequest req) async {
+    final order = Order(id: 'fake-${_orders.length}', /* ... */);
+    _orders.add(order);
+    lastPlaced = order;
+    return order;
+  }
+}
+```
+
+View models are tested through `ProviderContainer` with overrides — no widget tree (see `references/state-management.md` for the pattern). Test the real Notifier; never mock the unit under test.
+
+## Widget Tests
+
+The bulk of coverage. Pump the View inside a `ProviderScope` with fake repositories; assert through **semantics and visible text**, not widget types or internal keys:
+
+```dart
+testWidgets('placing an order shows the confirmation', (tester) async {
+  final fakeRepo = FakeOrderRepository(seed: [draftOrder]);
+  await tester.pumpWidget(ProviderScope(
+    overrides: [orderRepositoryProvider.overrideWithValue(fakeRepo)],
+    child: MaterialApp(theme: buildLightTheme(), home: const OrderView()),
+  ));
+  await tester.pumpAndSettle();
+
+  await tester.tap(find.bySemanticsLabel('Place order'));
+  await tester.pumpAndSettle();
+
+  expect(find.text('Order placed'), findsOneWidget);
+  expect(fakeRepo.lastPlaced, isNotNull);
+});
+```
+
+Conventions:
+
+- Finder priority: `find.bySemanticsLabel` → `find.text` → `find.byTooltip` → `find.byIcon` → (`find.byType`/keys only as a last resort). Semantics-based finds break on user-visible regressions only — and they keep the UI accessible, because inaccessible UI is untestable UI.
+- Pump with the real theme (`buildLightTheme()`) so theme extensions resolve; pump both themes for theme-sensitive components.
+- Cover error and empty states, not just the happy path — rendering core failure states is half the surface's job.
+- `pumpAndSettle` is for settling real transitions, not a sleep. If a test needs settling tricks, the awaited state is not modelled — assert on it explicitly.
+
+## Integration Tests
+
+`integration_test/` drives the real app binary. Keep it to **happy paths, one flow per critical journey**, with the gateway faked or staged:
+
+```dart
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+  testWidgets('the app boots to the home view', (tester) async {
+    await tester.pumpWidget(ProviderScope(
+      overrides: [statusRepositoryProvider.overrideWithValue(FakeStatusRepository())],
+      child: const App(),
+    ));
+    await tester.pumpAndSettle();
+    expect(find.text('Wired to the workspace gateway'), findsOneWidget);
+  });
+}
+```
+
+Every integration test costs emulator minutes — the most expensive test currency in this stack. If a widget test can carry the assertion, move it down a tier.
+
+## Patrol — the OS Boundary Only
+
+Add Patrol (LeanCode) only when a flow **leaves Flutter for the OS**: permission dialogs, push notifications, system sign-in sheets, WebViews, home/recents behaviour. It also brings full test isolation and sharding. A Patrol suite duplicating pure-Flutter flows `integration_test` already covers is scope creep — the boundary is the OS, not preference for its `$` finder DSL.
+
+## Golden Tests
+
+Goldens guard **design-system-level components** (the token-projected theme made visible), via **alchemist** with its platform-test vs CI-test split (CI variants render text as blocks, killing font flakiness). Scope is the component library, not full screens — screen-level goldens churn on every copy change and teach rubber-stamping. `golden_toolkit` is discontinued: migrate, never adopt.
+
+## CI Lanes
+
+- **PR gate:** `flutter analyze` + `flutter test` (unit + widget, headless, fast).
+- **Boot lane:** `flutter test integration_test` on a headless Android emulator — `reactivecircus/android-emulator-runner@v2`, x86_64, `-no-window -gpu swiftshader_indirect -no-snapshot-load -no-snapshot-save`, KVM-enabled runner.
+- **iOS is a local-only / device-farm lane (Firebase Test Lab, Codemagic), never a CI gate** — it needs macOS runners and hands, and putting it in the gate breaks the headless loop.
+- A runner without the Flutter SDK reports the tier **skipped-with-reason, never silently green**.
+
+## Assertion Quality — Mutation Testing and Its Absence
+
+The canon's assertion-quality read-out is mutation testing — inject a fault, confirm a test fails. Dart has **no production-grade mutation tool** (the existing packages are experimental and unmaintained), so that automated read-out is not available here. The discipline it enforces is carried by review instead: fakes over mocks (a stub-and-verify mock asserts the call, not the outcome), assert on semantics and visible text rather than widget types, and cover error and empty states — the failure modes mutation testing would otherwise catch. When a dense pure-Dart algorithm genuinely warrants it, a hand-run experimental tool is a spot check, never a gate.
+
+## Generate the Inputs You Can't Enumerate
+
+Example-based tests check the cases you thought of (canon principle 7). The generative surface on a Flutter client is narrow but real: a **dense, pure-Dart unit** with an invariant — a mapper round-trip (`fromJson ∘ toJson = id`), a date/currency formatter, a validator that must never throw — can state the property and let the framework generate counterexamples. `glados` is the Dart property-based option; it is niche, so reach for it only where a genuine invariant lives in pure logic, never for widget trees. The service-boundary generative tools the canon names — Schemathesis, coverage-guided fuzzing — do not apply to a client: the gateway's contract is fuzzed once at the capability core, and re-running it from the surface duplicates a proof that already exists (the Prove-Once Rule).
+
+## Naming Tests by Behaviour
+
+A test name must let an engineer form a hypothesis from the failure log alone. State the observable behaviour and the condition — `'placing an order shows the confirmation'`, not `'OrderView test'`. Names that describe what the user sees survive refactors and double as living documentation; names that describe the widget under test convey nothing the file tree doesn't.
+
+## Test Commands
+
+| Command | Purpose |
+|---|---|
+| `npx nx run <app>:test` | unit + widget tests (guarded: skips-with-reason without the SDK) |
+| `npx nx run <app>:analyze` | static analysis |
+| `npx nx run <app>:test-integration` | integration_test against a device/emulator |
+| `flutter test test/home_view_test.dart` | single file |
+| `flutter test --name 'refresh'` | by test name |
+
+## Bet Slice Rollout — the permanent tests a slice owes
+
+When a bet slice's progress tests go green, the slice rolls out permanent coverage before it closes (bet workflow, Delivery). The bet-progress tests prove the capability once and are archived; these stay. The Prove-Once Rule governs the whole rollout — surface tests prove wiring, rendering, and interaction; they never re-prove a business rule the capability core already owns.
+
+- **Widget tests (always).** The bulk of the slice's coverage: pump each View the slice delivered inside a `ProviderScope` with fake repositories, assert through semantics and visible text, and cover its error and empty states — not just the happy path.
+- **Unit tests (when logic earned them).** Pure-Dart tests for branching logic the slice introduced in a view model, mapper, or repository — through `ProviderContainer`, testing the real Notifier. Plumbing does not earn one; the widget test already covers it.
+- **Golden tests (when the slice touched a design-system component).** A new or changed token-projected component extends the alchemist goldens; screen-level goldens do not — they churn on every copy change.
+- **Integration / Patrol (only when the journey or the OS boundary is new).** A new critical journey earns one happy-path `integration_test`; a flow that newly leaves Flutter for the OS earns Patrol. Trace assertions do not apply — a Flutter client emits no OpenTelemetry traces, so there is no span surface to assert on.

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

@@ -0,0 +1,109 @@
+# Theming and Design Tokens
+
+## Table of Contents
+- [The Projection Model](#the-projection-model)
+- [The Generated Palette Module](#the-generated-palette-module)
+- [Consuming the Theme](#consuming-the-theme)
+- [Theme Extensions for Semantic Roles](#theme-extensions-for-semantic-roles)
+- [Dark Mode](#dark-mode)
+- [Typography](#typography)
+- [Evolving the Brand](#evolving-the-brand)
+- [Material/Cupertino Freeze Note](#materialcupertino-freeze-note)
+
+---
+
+## The Projection Model
+
+The theme is **generated from the design system's brand tokens**, not authored in the app. The chain:
+
+```
+docs/design-system.md  →  .groundwork/config/brand-tokens.json (visual block)
+                       →  lib/ui/core/theme/brand_palette.dart   (GENERATED)
+                       →  lib/ui/core/theme/app_theme.dart       (builds ThemeData)
+                       →  Theme.of(context) in widgets
+```
+
+The same tokens drive every surface of the product (web, CLI, mobile), so cross-surface visual consistency is a build artifact, not a review hope. The consequence for implementation work: **a hex literal in a widget file is a review finding** — it forks the design system silently.
+
+## The Generated Palette Module
+
+`brand_palette.dart` carries the projected token values and is regenerated, never hand-edited:
+
+- Palette roles in both themes: `primaryLight/primaryDark`, `accent…`, `surface…`, `surfaceAlt…`, `textBody…`, `success…`, `error…`, `warning…`, `info…`.
+- Typography families and weights: `displayFontFamily`, `bodyFontFamily`.
+- Shape: `radiusBase`.
+
+Widgets do **not** import `brand_palette.dart`. Only `app_theme.dart` reads it, building `ThemeData` (ColorScheme, TextTheme, component themes, ThemeExtensions) from the constants. The palette is the projection artifact; the theme is the API.
+
+## Consuming the Theme
+
+```dart
+@override
+Widget build(BuildContext context) {
+  final theme = Theme.of(context);
+  return Container(
+    decoration: BoxDecoration(
+      color: theme.colorScheme.surfaceContainerHighest,
+      borderRadius: BorderRadius.circular(BrandPalette.radiusBase), // only via shared components
+    ),
+    child: Text('Title', style: theme.textTheme.titleLarge),
+  );
+}
+```
+
+Resolution order when you need a colour or style:
+
+1. A `ColorScheme` role (`primary`, `surface`, `error`, `onSurface`, ...).
+2. A `ThemeExtension` (semantic roles the scheme lacks — see below).
+3. A shared component (e.g. a `Card` whose shape the component theme already sets).
+4. If none fits, the design system is missing a decision — raise it; do not inline a value.
+
+Never: `Color(0xFF...)`, `TextStyle(fontSize: 13)`, `EdgeInsets.all(13)` with non-scale values, opacity-hacked variants of brand colours.
+
+## Theme Extensions for Semantic Roles
+
+Material's `ColorScheme` has no success/warning/info roles. The theme defines them as a `ThemeExtension` built from the palette:
+
+```dart
+final status = Theme.of(context).extension<StatusColors>()!;
+Icon(Icons.check_circle, color: status.success);
+```
+
+When a new semantic role is needed (e.g. a "highlight" colour), extend the `ThemeExtension` in `app_theme.dart` from a palette/token value — do not scatter one-off colours.
+
+## Dark Mode
+
+Both themes are built from the same palette (each role carries light and dark values — a design-system commitment, not an option):
+
+```dart
+MaterialApp.router(
+  theme: buildLightTheme(),
+  darkTheme: buildDarkTheme(),
+  themeMode: ThemeMode.system,
+)
+```
+
+Implementation rules:
+
+- Never branch on `Theme.of(context).brightness` to pick hardcoded colours — the scheme and extensions already resolved per-theme values.
+- Every visual change is verified in both themes (widget tests pump both when the component is theme-sensitive — see `references/testing.md`).
+
+## Typography
+
+`app_theme.dart` applies the projected families to the `TextTheme` (display family on headlines/titles, body family elsewhere). Widgets use `textTheme` slots — `headlineMedium`, `titleLarge`, `bodyMedium` — never raw `TextStyle`s with families or sizes.
+
+The families only render once their font assets are bundled in `pubspec.yaml` (`fonts:` section). Until then Flutter falls back silently — if the type looks wrong, check the asset bundling before the theme code.
+
+## Evolving the Brand
+
+When the design system changes:
+
+1. The design-system run updates `brand-tokens.json`.
+2. Regenerate (or mechanically update) `brand_palette.dart` to match — the file header marks it as generated.
+3. `app_theme.dart` and all widgets pick the change up for free.
+
+If a visual change cannot be expressed through tokens → palette → theme, that is a design-system gap to raise, not a license to hand-edit the palette.
+
+## Material/Cupertino Freeze Note
+
+Material and Cupertino are frozen in the core framework as of Flutter 3.44 and are moving to standalone `material_ui`/`cupertino_ui` packages with independent versioning. When those packages land in this app's pubspec, pin them deliberately and review the theme builder against their migration notes — expect the dependency shift; do not be surprised by it.

package/src/engineer-skills/groundwork-flutter-engineer/references/widgets-and-composition.md

@@ -0,0 +1,123 @@
+# Widgets and Composition
+
+## Table of Contents
+- [Composition Over Inheritance](#composition-over-inheritance)
+- [Extract Widgets, Not Helper Methods](#extract-widgets-not-helper-methods)
+- [const Discipline](#const-discipline)
+- [Build Purity](#build-purity)
+- [Keys](#keys)
+- [Layout Decisions](#layout-decisions)
+- [Review Checklist](#review-checklist)
+
+---
+
+## Composition Over Inheritance
+
+New UI composes existing widgets; it never subclasses a widget to alter behaviour. A `PrimaryButton` wraps and configures `FilledButton`; it does not extend it:
+
+```dart
+class PrimaryButton extends StatelessWidget {
+  const PrimaryButton({super.key, required this.label, this.onPressed});
+
+  final String label;
+  final VoidCallback? onPressed;
+
+  @override
+  Widget build(BuildContext context) {
+    return FilledButton(
+      onPressed: onPressed,
+      child: Text(label),
+    );
+  }
+}
+```
+
+Flutter's rendering model rewards exactly one style — small, pure, const-friendly widgets composed deeply. Every deviation is something the next change must special-case.
+
+---
+
+## Extract Widgets, Not Helper Methods
+
+`Widget _buildHeader()` defeats const canonicalisation and rebuild isolation — the framework cannot skip a subtree it cannot identify. Extract a widget class instead:
+
+```dart
+// WRONG — helper method
+Widget _buildHeader(BuildContext context) => Row(children: [...]);
+
+// RIGHT — extracted widget, rebuild-isolated, const-capable
+class _Header extends StatelessWidget {
+  const _Header({required this.title});
+  final String title;
+  @override
+  Widget build(BuildContext context) => Row(children: [...]);
+}
+```
+
+Extract when a subtree is reused, when it can become `const`, or when a build method stops fitting on a screen.
+
+---
+
+## const Discipline
+
+Every constructor that can be `const` is `const`; every instantiation site that can use `const` does. A `const` widget is canonicalised and skipped during rebuilds — the cheapest performance work in the framework. `flutter_lints` (`prefer_const_constructors` and friends) enforces this; treat those lints as errors, not suggestions.
+
+Practical habit: when a `const` keyword fails to compile, ask why the widget isn't const-capable before deleting the keyword — often a value should be passed in rather than computed inline.
+
+---
+
+## Build Purity
+
+`build` reads state and returns widgets. It never:
+
+- mutates state (including provider state),
+- fires network requests,
+- shows dialogs or snackbars,
+- starts animations or timers.
+
+Flutter may call `build` at any frequency; an impure build turns rebuild cadence into behaviour. Side effects belong in view-model commands, lifecycle hooks (`initState`, `ref.listen`), or explicit handlers:
+
+```dart
+// Side-effect on state change: ref.listen, not build.
+ref.listen(submitOrder, (prev, next) {
+  if (next is MutationError) {
+    ScaffoldMessenger.of(context).showSnackBar(/* ... */);
+  }
+});
+```
+
+A conditional in `build` that encodes a business rule belongs in the view model; `build` branches on view state only.
+
+---
+
+## Keys
+
+Keys appear in exactly three situations:
+
+1. **Reorderable/filterable lists** — `ValueKey(item.id)` on each child, so state follows identity, not position.
+2. **Tree-shape changes around stateful widgets** — preserving state when conditionals restructure the tree.
+3. **`GlobalKey` for the rare imperative handle** — forms (`FormState`), nothing else.
+
+A key sprinkled "to be safe" is noise. A missing key on a reorderable list is a state-corruption bug. A `GlobalKey` reaching into another widget's state is a view model that wasn't written.
+
+---
+
+## Layout Decisions
+
+- **`LayoutBuilder` over `MediaQuery.of(context).size`** — a widget responds to its parent's constraints, not the screen. MediaQuery-based layout breaks the moment the widget is placed in a pane, sheet, or test harness.
+- Spacing and sizes come from the theme/density system, not magic numbers (see `references/theming-and-design-tokens.md`).
+- Tap targets meet the 48dp minimum (see `references/accessibility.md`).
+
+---
+
+## Review Checklist
+
+Flag in review:
+
+- [ ] Any subclassed framework widget (composition exists).
+- [ ] `Widget _buildX()` helper methods returning subtrees.
+- [ ] Missing `const` where the lint reports it.
+- [ ] Side effects (mutation, requests, dialogs, animation starts) inside `build`.
+- [ ] Business-rule conditionals inside `build`.
+- [ ] `Color(0xFF...)`, raw `TextStyle(...)`, or magic paddings (theme violation — see theming reference).
+- [ ] Lists built from dynamic collections without `ValueKey`s.
+- [ ] `MediaQuery.size` used for layout branching.

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

@@ -0,0 +1,24 @@
+# Sync Anchor
+
+This file pins the principle files this skill embeds — both the per-stack
+Flutter idiom docs and the cross-cutting central canon this skill distils. When
+any listed file changes, this skill must be reviewed in the same commit (and the
+matching per-stack idiom doc reconciled to the canon). CI verifies the hashes
+match.
+
+| Principle file | SHA-256 | Last reviewed |
+|---|---|---|
+| src/generators/flutter-app/docs/principles/stack/flutter/index.md | 45c86182ebbaf4be599f54a22a7e8bbebbc455bbdcacda4fbec845f2de041885 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/architecture.md | ac10c2c87da358157973ebbfe07657491d68a248b946b00697fdc5e18f3af596 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/state-management.md | a690a3476453cb8ed0af0d3f48566d8ba6a2d508ac1ef782fd27bbffd2268994 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/widgets-and-composition.md | b45c55220f14a7886837c4d4159b33febceed772db32a7efb277e7dba00512e8 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/testing.md | e337a0e1c4a6c5502f69745b0a4e0be35dd3303fbf11ed1f2f3688e93f16ed4f | 2026-06-27 |
+| src/generators/flutter-app/docs/principles/stack/flutter/platform-channels.md | 6b5a54dcb8b55433b7175cf715a6a3abf03c86c317f2037af6155a131691cfb2 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/releases-and-distribution.md | 70ecdca2be6d8476359dbc2e72e3510157b49db0f5512cded76e0e3f19bed46f | 2026-06-12 |
+| src/docs/principles/foundations/testing.md | 205ac40d4c643e7b61cf1e4295df8a7b8b46dcd7c81b857aa8c642ea353f62ef | 2026-06-27 |
+| src/docs/principles/quality/observability.md | 8aa60e213ba03e989c93263153e3a1ac10b2336f6d0360c394f473660d565a0b | 2026-06-26 |
+| src/docs/principles/quality/security.md | 61157d97677142737ec537954dc5aaad7a04012cc8a3dcc855e2d324287fdc64 | 2026-06-26 |
+| src/docs/principles/quality/performance.md | 18b6d3391c57d97342068f9f1da732b24de4221489d0459bb6ad8900fac0a02e | 2026-06-26 |
+| src/docs/principles/quality/reliability.md | 9c9788504e0963458667d2727c3fc2359776108be593a2efc6603f6470002252 | 2026-06-26 |
+| src/docs/principles/quality/accessibility.md | f921e7bf6256bc105b127b841d0a30af8a70ad1ddd7632d492589f052e6501b2 | 2026-06-26 |
+| src/docs/principles/foundations/documentation.md | 8b576072eaf4970f1251b560781e3e755c864a7920faa599b2834c921cbb8734 | 2026-06-26 |