groundwork-method 0.0.1 → 0.11.0

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

@@ -0,0 +1,122 @@
+# Navigation
+
+## Table of Contents
+- [The Router Is go_router](#the-router-is-go_router)
+- [The Route Table](#the-route-table)
+- [Typed Routes](#typed-routes)
+- [Tab Scaffolds: StatefulShellRoute](#tab-scaffolds-statefulshellroute)
+- [Auth Guards: Centralized redirect](#auth-guards-centralized-redirect)
+- [The Route as State](#the-route-as-state)
+- [Deep Links](#deep-links)
+- [What Remains for Navigator 1.0](#what-remains-for-navigator-10)
+
+---
+
+## The Router Is go_router
+
+go_router (flutter.dev verified publisher, declared feature-complete — a stable platform piece) owns app-level navigation. The router lives in one module as a provider:
+
+```dart
+final routerProvider = Provider<GoRouter>((ref) {
+  return GoRouter(
+    routes: [/* the route table */],
+    redirect: (context, state) => _guard(ref, state),
+  );
+});
+```
+
+`MaterialApp.router(routerConfig: ref.watch(routerProvider))` is the only place the router meets the widget tree. Hand-rolled `RouterDelegate`/Navigator 2.0 code is legacy — it is the API go_router exists to hide. Do not write it, and refactor it away on contact.
+
+## The Route Table
+
+One table, hierarchical, every destination declared:
+
+```dart
+GoRoute(
+  path: '/orders',
+  name: 'orders',
+  builder: (context, state) => const OrdersView(),
+  routes: [
+    GoRoute(
+      path: ':orderId',
+      name: 'order-detail',
+      builder: (context, state) =>
+          OrderDetailView(orderId: state.pathParameters['orderId']!),
+    ),
+  ],
+)
+```
+
+Conventions:
+
+- Paths are URL-shaped and lowercase-kebab; names exist for every route.
+- The view receives parsed parameters via its constructor — it does not read `GoRouterState` internally.
+- New screens are added to the table, never pushed ad hoc from a feature file.
+
+## Typed Routes
+
+As the table grows past a few routes, adopt `go_router_builder` typed routes — route paths and parameters as generated, compile-checked classes:
+
+```dart
+@TypedGoRoute<OrderDetailRoute>(path: '/orders/:orderId')
+class OrderDetailRoute extends GoRouteData {
+  const OrderDetailRoute({required this.orderId});
+  final String orderId;
+
+  @override
+  Widget build(BuildContext context, GoRouterState state) =>
+      OrderDetailView(orderId: orderId);
+}
+
+// Navigation becomes compile-checked:
+const OrderDetailRoute(orderId: '42').go(context);
+```
+
+Stringly-typed `context.go('/orders/$id')` calls scattered through features are the navigation equivalent of hand-rolled JSON — acceptable only while the table is a handful of routes, refactored to typed routes as it grows.
+
+## Tab Scaffolds: StatefulShellRoute
+
+Bottom-bar/tab UIs use `StatefulShellRoute.indexedStack` — per-tab navigation stacks whose state survives tab switches:
+
+```dart
+StatefulShellRoute.indexedStack(
+  builder: (context, state, shell) => AppScaffold(shell: shell),
+  branches: [
+    StatefulShellBranch(routes: [GoRoute(path: '/home', ...)]),
+    StatefulShellBranch(routes: [GoRoute(path: '/settings', ...)]),
+  ],
+)
+```
+
+Do not hand-roll tab stacks with nested Navigators.
+
+## Auth Guards: Centralized redirect
+
+Auth is one `redirect` function on the router — never per-screen checks:
+
+```dart
+String? _guard(Ref ref, GoRouterState state) {
+  final signedIn = ref.read(sessionProvider).isSignedIn;
+  final signingIn = state.matchedLocation == '/sign-in';
+  if (!signedIn && !signingIn) return '/sign-in?from=${state.matchedLocation}';
+  if (signedIn && signingIn) return '/';
+  return null;
+}
+```
+
+Wire the session provider to the router with `refreshListenable` (or rebuild the router provider on session change) so guard decisions re-evaluate when auth state changes.
+
+## The Route as State
+
+The URL is a first-class state container. Selected entity id, active tab, current screen — if the route encodes it, **no provider duplicates it**; a provider mirroring the route will drift. This also makes navigation state survive process death for free, which matters because mobile processes die constantly.
+
+## Deep Links
+
+Anything declared as a `GoRoute` is deep-linkable across Android/iOS — that falls out of the declarative table. Practical consequences:
+
+- Every route must render sensibly when entered **directly** (cold start onto `/orders/42`): the view model fetches what it needs from its id parameters; no route depends on in-memory state a previous screen happened to leave behind.
+- Guard-sensitive routes are protected by the central `redirect`, so deep links cannot skip auth.
+
+## What Remains for Navigator 1.0
+
+Imperative `showDialog`, `showModalBottomSheet`, and one-off local flows are fine — they are transient UI, not app navigation. The boundary: if a destination should be linkable, restorable, or guarded, it is a `GoRoute`; if it is a momentary overlay, Navigator 1.0 primitives are correct.

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

@@ -0,0 +1,37 @@
+# Observability
+
+A Flutter client emits no OpenTelemetry server spans. Distributed tracing lives at the capability core, where the gateway owns the request trace and asserts it with an in-memory exporter — which is why trace-assertions are N/A on the client (`references/testing.md`). The client's observability job is **crash and UX telemetry**: what broke, where, and what the user was doing when it did. Instrument for the questions you will ask when a crash report lands; the discipline is the framework canon adapted to a device you do not control (`docs/principles/quality/observability.md`).
+
+## Crash and Error Reporting
+
+A crash/error sink (Sentry or Firebase Crashlytics shape) captures unhandled failures. Two handlers are mandatory, because they catch different errors:
+
+- `FlutterError.onError` — errors raised inside the Flutter framework (build, layout, paint).
+- `PlatformDispatcher.instance.onError` — uncaught async and platform errors that never enter the framework.
+
+Wiring only the first leaves the async crash invisible — the one you never see is the one outside the handler you wired. Native engine and platform-channel crashes report through the sink's native layer.
+
+## Structured Breadcrumb Logging
+
+Breadcrumbs, not `print`. A trail of structured events — navigation, command fired, repository call, state transition — lets a crash report reconstruct the path to the failure. `print()` is dropped in release builds and carries no structure even in debug. Attach the screen/route and the operation to each event; emit at an agreed severity rather than as free text.
+
+## Performance Traces
+
+Custom performance traces (Firebase Performance shape) wrap the spans the user *feels*: app start, screen render, and the gateway round-trip as seen from the device. This is client-perceived latency — a different number from the server span the core owns, and the only one that includes the user's network and frame budget. Add frame/jank metrics where smoothness is the product.
+
+## What to Capture vs PII
+
+- **Capture** error type and stack, the breadcrumb trail, screen, operation, client-perceived latency, and device/OS/app-version context.
+- **Never** put tokens, PII, or full payloads in breadcrumbs or crash context. The sink is third-party — scrub before the event leaves the device.
+
+## Where Distributed Tracing Lives
+
+The end-to-end request trace is the capability core's, asserted there. The client does not mirror it with spans of its own; it correlates by attaching a request/correlation id it can surface in a breadcrumb, so a crash report points back at the server trace.
+
+## Anti-Patterns
+
+- **`print` as telemetry.** Dropped in release, structureless in debug.
+- **One error handler.** `FlutterError.onError` alone lets async errors escape uncaught.
+- **PII in crash context.** Emails, tokens, and payloads following the event off-device.
+- **A client tracing story.** Re-implementing spans to mirror the backend — there is no client span surface; correlate, don't duplicate.
+- **Over-instrumenting.** Custom traces nobody reads are cost without a question behind them.

package/src/engineer-skills/groundwork-flutter-engineer/references/performance-and-reliability.md

@@ -0,0 +1,100 @@
+# Performance & Reliability
+
+## Table of Contents
+- [Two Budgets a Client Spends](#two-budgets-a-client-spends)
+- [The Frame Budget](#the-frame-budget)
+- [List Virtualization](#list-virtualization)
+- [Image and Asset Memory](#image-and-asset-memory)
+- [Isolates for Heavy Compute](#isolates-for-heavy-compute)
+- [Startup Time](#startup-time)
+- [Resilience on the Typed Client](#resilience-on-the-typed-client)
+- [Optimistic UI and Offline](#optimistic-ui-and-offline)
+- [Graceful Degradation](#graceful-degradation)
+- [What Lives in the Core, Not Here](#what-lives-in-the-core-not-here)
+- [Anti-Patterns](#anti-patterns)
+
+---
+
+## Two Budgets a Client Spends
+
+Performance is a budget spent deliberately, not "fast enough" tuned afterward (`docs/principles/quality/performance.md`). A client spends two budgets. The **frame budget** is local: 16ms to produce a frame at 60Hz, 8ms at 120Hz, and a build that overruns it drops the frame the user feels as jank. The **round-trip budget** is remote: the time from a tap to a rendered result, most of which is the gateway call the app does not control. Allocate both top-down — decide the interaction's target before building it — and measure the tail, not the average: the one stutter in a scroll is the experience users remember (`docs/principles/quality/performance.md`).
+
+## The Frame Budget
+
+Jank is a build that does too much, too often. The mechanics of keeping builds cheap live in the widget and state references; this is the performance lens on them:
+
+- **`const` and extracted widgets** canonicalise subtrees the framework skips on rebuild — the cheapest performance work available (`references/widgets-and-composition.md`).
+- **`RepaintBoundary`** isolates a frequently-repainting subtree (an animation, a progress indicator) so its repaint does not invalidate the rest of the layer tree. Wrap the moving part, not the whole screen — a boundary has its own cost, so it earns its place only where repaint actually churns.
+- **Narrow rebuild scope.** A god-provider per screen rebuilds everything when one field changes; split providers by concern so the graph recomputes at the right granularity (`references/state-management.md`). Watch the narrowest provider a widget needs, never the whole state object for one field.
+- **Pure builds.** A `build` that fires work or mutates state turns rebuild cadence into behaviour and into cost (`references/widgets-and-composition.md`).
+
+Profile before you optimise — the obvious cause of a jank is usually wrong. Flutter DevTools' timeline and the raster/UI thread split tell you whether a frame overran in build or in paint; the "obvious" bottleneck almost always isn't (`docs/principles/quality/performance.md`).
+
+## List Virtualization
+
+A scrollable collection of unknown or large length is built lazily — `ListView.builder` / `GridView.builder` / `SliverList`, never a `ListView(children: [...])` that constructs every row up front. Eager construction allocates the whole list before the first frame and is the most common source of scroll jank and startup memory spikes. Give reorderable or filterable rows a `ValueKey(item.id)` so element state follows identity through rebuilds (`references/widgets-and-composition.md`).
+
+## Image and Asset Memory
+
+Decoded images dominate a client's memory; a full-resolution image rendered into a thumbnail wastes most of what it decoded. Constrain the decode, not just the display:
+
+```dart
+Image.network(
+  url,
+  cacheWidth: 320, // decode to the size actually shown, not the source resolution
+  fit: BoxFit.cover,
+);
+```
+
+Size on-disk and remote assets to their rendered footprint, and let the framework's image cache evict — do not hold decoded bytes in app state. Oversized decodes are a memory budget overrun the same way an unbounded queue is a latency bomb.
+
+## Isolates for Heavy Compute
+
+The UI isolate renders frames; anything that can take longer than a frame must not run on it. Parsing a large payload, hashing, cryptographic work, image transforms — move them to a background isolate with `compute()` or a long-lived `Isolate`, so the work never blocks the frame loop:
+
+```dart
+final parsed = await compute(parseLargeReport, rawBytes);
+```
+
+This is the client's version of the hot-path discipline: the scoped, profiled paths that demand care, not every function (`docs/principles/quality/performance.md`). Repository translation of an ordinary payload stays on the UI isolate; reach for an isolate when a profile shows the work itself overrunning the frame.
+
+## Startup Time
+
+Cold start is the first interaction, and it spends the round-trip and frame budgets at once. Keep `main()` and the first frame thin: `ProviderScope` at the root and nothing else, no synchronous I/O before `runApp`, and defer non-critical provider initialisation until after the first frame paints. Render a skeleton from the first frame and let real data arrive into it — the app should be visible before it is fully loaded, never blank while it fetches.
+
+## Resilience on the Typed Client
+
+Reliability is designed in, not hoped for (`docs/principles/quality/reliability.md`). For a client, that discipline lives at the one seam that talks to the gateway — the `Dio` instance and the repositories above it (`references/data-and-contracts.md`):
+
+- **Timeout always.** Every outbound call has connect and receive timeouts set on the one configured `Dio` instance — a hung connection otherwise holds a loading spinner forever.
+- **Retry transient failures only, with jitter.** A retry interceptor retries connection errors and timeouts with bounded, jittered exponential backoff; jitter is not optional, because a fleet of clients retrying in lockstep is a thundering herd against the gateway. A `4xx` is permanent — retrying it wastes the budget. Retry at this one layer, not in every repository on top of it.
+- **Map transport failures to domain states.** `DioException` never crosses above the data layer; the repository turns an unreachable gateway into a domain state the UI renders, and lets a contract violation surface as an error (`references/data-and-contracts.md`).
+
+## Optimistic UI and Offline
+
+A mobile process dies constantly and a network drops mid-interaction; state the app cannot rebuild from the core or the route is state it silently loses (`references/state-management.md`). Two patterns follow:
+
+- **Optimistic update.** Reflect the user's action in state immediately, fire the mutation, and reconcile on the result — invalidate the provider to re-derive from the repository on success, roll back on failure. A Riverpod `Mutation` surfaces the pending/error lifecycle without a hand-rolled boolean (`references/state-management.md`).
+- **Offline read-through.** A repository that caches can serve its last-known value while a refresh is in flight, so a dropped connection degrades to stale-but-present rather than empty. Mark served-stale state so the UI can show it honestly.
+
+## Graceful Degradation
+
+Every feature that depends on the gateway has a defined behaviour when the gateway is down — decided at design time, built alongside the happy path, never "we'll figure out what to show later" (`docs/principles/quality/reliability.md`). A view renders `loading` / `error` / `data` exhaustively, and the error case is a real designed state with a retry affordance, not a thrown exception reaching the user (`references/state-management.md`). A non-critical panel whose data is unavailable renders its own empty or "unavailable" state while the rest of the screen works — partial function beats a blank screen.
+
+## What Lives in the Core, Not Here
+
+Server reliability patterns do not belong on a client, and importing them here is miscategorised work. They live in the capability core and its services (`docs/principles/quality/reliability.md`):
+
+- **SLOs and error budgets** are defined per service in the core, measured server-side. The client contributes client-observed latency to that picture; it does not own the objective.
+- **Load shedding** protects the server from overload and must work regardless of client behaviour — it is a server-side backstop, not something a well-behaved client implements for it.
+- **Circuit breakers** are earned against slow downstreams and tuned against real traffic at the service layer. A client's bounded, budgeted retry is the right amount of resilience at the edge; a breaker estimated locally by one app trips on noise. The business rules about a failure — whether it is recoverable, the retry budget — are proven in the core, and the surface renders the result.
+
+## Anti-Patterns
+
+- **Jank shipped, fixed later.** If you ship a stuttering scroll, users remember slow.
+- **`ListView(children: [...])` for a dynamic or long list.** Eager construction of every row — use the `.builder` constructor.
+- **Heavy work on the UI isolate.** A parse or hash that overruns a frame freezes the app — `compute()` it.
+- **Full-resolution decode for a thumbnail.** Decoded image memory, wasted — constrain `cacheWidth`/`cacheHeight`.
+- **Retry without jitter, or at every layer.** Lockstep retries are a thundering herd; layered retries multiply one tap into a storm.
+- **No degraded state.** A feature with no defined behaviour when the gateway is down ships a blank screen or a raw exception.
+- **Reimplementing server reliability on the client.** Load shedding, SLOs, and reflexive circuit breakers belong in the core, not the surface.

package/src/engineer-skills/groundwork-flutter-engineer/references/platform-channels.md

@@ -0,0 +1,93 @@
+# Platform Channels
+
+## Table of Contents
+- [The Decision Ladder](#the-decision-ladder)
+- [Check the Plugin Shelf First](#check-the-plugin-shelf-first)
+- [Pigeon: the Default for Structured APIs](#pigeon-the-default-for-structured-apis)
+- [Wrapping the Native Module](#wrapping-the-native-module)
+- [ffigen/jnigen: the Tracked Destination](#ffigenjnigen-the-tracked-destination)
+- [Raw MethodChannel](#raw-methodchannel)
+- [iOS Build Wiring](#ios-build-wiring)
+- [Testing the Boundary](#testing-the-boundary)
+
+---
+
+## The Decision Ladder
+
+When a capability is not reachable from Dart:
+
+1. **pub.dev** — a maintained, verified-publisher plugin is a dependency decision, not an interop project.
+2. **Pigeon module** — write Swift/Kotlin behind a generated, typed boundary.
+3. **Raw MethodChannel** — a single fire-and-forget call with no evolving surface, nothing more.
+
+Dropping to native is a **capability decision, never a performance reflex**. Profile in Dart first — rendering and isolates cover almost every performance complaint, and a native detour taken for imagined speed buys two codebases for one feature. Legitimate native triggers: a platform API with no maintained plugin (HealthKit details, background modes, vendor SDKs), OS-integrated UI Flutter cannot render (widgets/complications, App Intents), hardware access below the plugin ecosystem.
+
+## Check the Plugin Shelf First
+
+Before writing native code: search pub.dev, check publisher verification, maintenance cadence, and issue tracker health. Rewriting a maintained verified-publisher plugin is negative work. Write native code when the shelf is empty or unmaintained.
+
+## Pigeon: the Default for Structured APIs
+
+Define the API once in Dart; Pigeon generates type-safe stubs on both sides — misspelled methods and mistyped arguments become compile errors instead of runtime channel exceptions:
+
+```dart
+// pigeons/battery_api.dart
+import 'package:pigeon/pigeon.dart';
+
+@ConfigurePigeon(PigeonOptions(
+  dartOut: 'lib/data/services/gen/battery_api.g.dart',
+  kotlinOut: 'android/app/src/main/kotlin/.../BatteryApi.kt',
+  swiftOut: 'ios/Runner/BatteryApi.swift',
+))
+@HostApi()
+abstract class BatteryApi {
+  int batteryLevel();
+  bool isCharging();
+}
+```
+
+Run `dart run pigeon --input pigeons/battery_api.dart` and implement the generated interface in Kotlin/Swift. **Every structured Flutter↔native API goes through Pigeon** — keep the native side a small module the agent can regenerate.
+
+## Wrapping the Native Module
+
+The Dart side of a Pigeon API is a **service in the data layer**, like any other platform API:
+
+```dart
+class BatteryService {
+  BatteryService(this._api);
+  final BatteryApi _api;
+
+  Future<BatteryReading> read() async => BatteryReading(
+        level: await _api.batteryLevel(),
+        charging: await _api.isCharging(),
+      );
+}
+
+final batteryServiceProvider = Provider<BatteryService>(
+  (ref) => BatteryService(BatteryApi()),
+);
+```
+
+Repositories/view models consume the service; nothing above the data layer knows a channel exists. **Native code never grows business rules** — it is transport to an OS capability; rules live in the core or the view model where they are proven.
+
+## ffigen/jnigen: the Tracked Destination
+
+The ecosystem is mid-migration to channel-free codegen interop: `ffigen` (C/Obj-C/Swift; stable) and `jnigen` (Java/Kotlin via JNI; pre-1.0), on build hooks / native assets (default-enabled since Flutter 3.38). The stance:
+
+- **Adopt where a dependency already ships it** — that is the dependency's choice.
+- **Pigeon remains the app-code default** until the jnigen path reaches 1.0.
+- Aim refactors at the destination; re-evaluate at the next ecosystem survey.
+
+## Raw MethodChannel
+
+Acceptable for exactly one shape: a single trivial call with no evolving surface (toggle a platform flag, read one value). The moment a channel grows a second method or a structured payload, it becomes a Pigeon definition. Hand-written channels for any real API surface are legacy — stringly-typed, runtime-failing, agent-hostile.
+
+## iOS Build Wiring
+
+**Swift Package Manager is the iOS/macOS default as of Flutter 3.44.** New native modules and plugin dependencies use SwiftPM; CocoaPods is the legacy path kept only where a required dependency has not migrated. Do not add new Podfile-based wiring.
+
+## Testing the Boundary
+
+- **Unit/widget tiers:** fake the Pigeon-fronted **service** in Dart like any other service — the native side does not run.
+- **Emulator tier:** the native implementation is exercised by `integration_test` (or Patrol, when the flow crosses into OS UI) only where the capability is observable.
+- Pure pass-through wrappers over OS APIs get a thin smoke test, not a re-proof of the OS.

package/src/engineer-skills/groundwork-flutter-engineer/references/releases-and-distribution.md

@@ -0,0 +1,84 @@
+# Releases and Distribution
+
+## Table of Contents
+- [Why This Is Architecture](#why-this-is-architecture)
+- [Signing](#signing)
+- [CI/CD Pipeline](#cicd-pipeline)
+- [Versioning](#versioning)
+- [Forced Upgrade: the Compatibility Floor](#forced-upgrade-the-compatibility-floor)
+- [Shorebird Code Push](#shorebird-code-push)
+- [Release Checklist](#release-checklist)
+
+---
+
+## Why This Is Architecture
+
+A mobile surface cannot be rolled back and cannot be force-refreshed: every version ever shipped is potentially still running, store review adds days of latency, and a signing mistake can permanently lock the listing. Treat release engineering as the half of the contract-compatibility story that lives outside the repo — and keep it CI-driven, because a human clicking through Xcode is a step the delivery loop stalls on.
+
+## Signing
+
+**Android**
+
+- One upload keystore per app, generated once, stored in a secret manager **with an independent secure copy** — the official docs warn it is unrecoverable.
+- `key.properties` and the keystore are never in git; CI injects them from encrypted secrets (or Codemagic code-signing identities).
+- **Play App Signing** holds the actual app signing key, so a compromised upload key is rotatable.
+
+**iOS**
+
+- **App Store Connect API keys** authenticate CI — no human Apple ID sessions in automation.
+- Certificates/provisioning profiles are fastlane-match-style: encrypted, centrally stored, CI-fetched. Codemagic's managed signing is the equivalent.
+
+A keystore or service-account JSON committed to a repo is an **incident**, not a finding: rotate it, scrub history, then fix the pipeline. The generated `.gitignore` already excludes signing material — keep it that way.
+
+## CI/CD Pipeline
+
+Default stack: **GitHub Actions + fastlane** (`supply` → Play, `deliver`/`pilot` → App Store Connect/TestFlight). **Codemagic** is the recorded Flutter-native alternative; fastlane is preinstalled there, so the stacks compose. Pick one per product and record it.
+
+The standard flow:
+
+```
+PR        → analyze + widget tests + emulator integration lane (the test gate)
+main      → build signed release artifacts (CI-owned build number)
+artifact  → internal track / TestFlight first
+promote   → staged rollout to production
+```
+
+No artifact reaches a store that CI did not build, sign, and test. Manual store uploads are unrepeatable releases — refuse them.
+
+## Versioning
+
+pubspec carries `version: x.y.z+buildNumber`:
+
+- **Humans own `x.y.z`** — the user-visible, compatibility-relevant part.
+- **CI owns the build number**, auto-incrementing per release build via `--build-number` (and `--build-name` when overriding the version). Hand-bumped build numbers collide, and collided build numbers are store-upload rejections.
+
+## Forced Upgrade: the Compatibility Floor
+
+The core's stance is that a published contract field is never broken — because the fleet lags releases by months and cannot be recalled. Forced upgrade is the other half of that bargain:
+
+- The core (or a config endpoint / Firebase Remote Config) publishes a **minimum supported version**; the app compares at startup.
+- The **`upgrader`** package implements the prompt: `minAppVersion` below the floor auto-hides "Later"/"Ignore".
+- Two tiers, used deliberately:
+  - **Soft prompt** (dismissible) — new features, gentle migration pressure.
+  - **Hard force** (blocking) — security issues, or a contract the core can no longer serve.
+
+Operational rules: the floor advances slowly and each advance is a recorded product decision; between "never break a field" and the floor, every fleet version is served correctly. **Shipping a contract-breaking core change without first raising the floor and waiting out adoption is a sequencing defect** — flag it whenever a slice proposes it.
+
+## Shorebird Code Push
+
+Shorebird (stable on Android and iOS, store-policy compliant) is the OTA lane for **Dart-only hotfixes** — it skips store latency for Dart-level defects, with `shorebird_code_push` for in-app patch checks. Boundaries:
+
+- Native-code changes (plugins, Pigeon modules, SDK bumps) still require a store release.
+- A patched 1.4.2 is still 1.4.2 to the contract — OTA never substitutes for the version floor.
+- It is a hotfix channel, not the release process; features and floors move through the stores.
+
+## Release Checklist
+
+Before a release slice closes:
+
+- [ ] CI builds, signs, and tests the artifact; no manual store steps.
+- [ ] Build number CI-assigned; `x.y.z` deliberately chosen.
+- [ ] No signing material, `key.properties`, ASC keys, or service-account JSON in the diff.
+- [ ] Contract changes verified against the version floor (raise the floor first, then ship the change after adoption).
+- [ ] Internal track / TestFlight before production; staged rollout configured.
+- [ ] If Shorebird patched anything since the last release, the patch content is folded into this store release.

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

@@ -0,0 +1,96 @@
+# Security
+
+## Table of Contents
+- [The Posture](#the-posture)
+- [No Secrets in the Binary](#no-secrets-in-the-binary)
+- [Secure Storage for Tokens](#secure-storage-for-tokens)
+- [Transport and Certificate Pinning](#transport-and-certificate-pinning)
+- [Deep Link and Intent Validation](#deep-link-and-intent-validation)
+- [Biometric and Auth-Token Handling](#biometric-and-auth-token-handling)
+- [Obfuscation's Real Limits](#obfuscations-real-limits)
+- [Security Review Checklist](#security-review-checklist)
+
+---
+
+## The Posture
+
+A shipped mobile binary runs on a device the attacker owns. It can be pulled off the device, decompiled, patched, and run under a debugger or a proxy. So the client is **not** a trust boundary — it is hostile territory you are deploying into. Every security guarantee that matters is enforced server-side, behind the gateway (`references/data-and-contracts.md` → The Seam); the client's job is to handle credentials carefully and fail safe, not to keep secrets or enforce rules. This file is the Flutter idiom of the framework security canon (`docs/principles/quality/security.md`); when this file and the canon disagree, the canon wins and this file is the one to fix.
+
+The recurring mistake is treating the app as trusted because it is "your" code. It stops being yours the moment it ships.
+
+## No Secrets in the Binary
+
+There is no secure place in the app bundle for a secret. API keys, signing keys, and shared credentials compiled into Dart — or passed via `--dart-define`, or baked into a `.env` asset — are all recoverable from the binary. The config seam already states this: no `.env` files baked in, no secrets in `--dart-define` (`references/data-and-contracts.md` → Configuration).
+
+- A capability that needs a secret (a third-party API key, a server-to-server credential) lives **server-side**, behind a core endpoint the app calls with its user session. The surface never embeds a provider key — one owner per capability, keys stay server-side.
+- `--dart-define` is for non-secret configuration only: the gateway base URL, build flavour, feature toggles.
+- If the app appears to need a secret to call a third party directly, that call belongs on the server; route it through the core.
+
+## Secure Storage for Tokens
+
+Session and refresh tokens go in the platform keystore via `flutter_secure_storage`, which is backed by the iOS **Keychain** and the Android **Keystore**/EncryptedSharedPreferences. `SharedPreferences` and plain files are world-readable on a rooted/jailbroken device — they are never used for anything sensitive.
+
+```dart
+const _storage = FlutterSecureStorage(
+  aOptions: AndroidOptions(encryptedSharedPreferences: true),
+  iOptions: IOSOptions(accessibility: KeychainAccessibility.first_unlock_this_device),
+);
+
+Future<void> saveSession(String token) =>
+    _storage.write(key: 'session_token', value: token);
+```
+
+- Tokens read out of secure storage are injected as a header by a single dio interceptor (`references/data-and-contracts.md` → dio Conventions), not stored in widget state or passed through constructors.
+- `first_unlock_this_device` keeps the credential off device backups and off other devices; widen it only with a recorded reason.
+- Clear secure storage on sign-out and on detected token invalidation — a lingering token is a credential waiting to be lifted.
+
+## Transport and Certificate Pinning
+
+All traffic is HTTPS; the dio client rejects plaintext. For an app handling sensitive data, pin the gateway's certificate (or its public-key/SPKI hash) so a user-installed or malicious root CA cannot transparently proxy the connection.
+
+```dart
+(dio.httpClientAdapter as IOHttpClientAdapter).createHttpClient = () {
+  final client = HttpClient();
+  client.badCertificateCallback = (cert, host, port) =>
+      _spkiSha256(cert) == _pinnedSpkiHash;  // pin to the key, not the leaf cert
+  return client;
+};
+```
+
+- Pin to the SPKI hash, not a specific leaf certificate, so routine certificate renewal does not brick the app; ship at least one backup pin for rotation.
+- Pinning raises the bar against interception but is bypassable on a fully compromised device — it is defence in depth, not a substitute for server-side authorization.
+
+## Deep Link and Intent Validation
+
+Every `GoRoute` is deep-linkable, and a deep link is untrusted input from another app or a web page (`references/navigation.md` → Deep Links). Route parameters arriving cold are hostile until proven otherwise.
+
+- Validate and parse path/query parameters in the view model that receives them; never assume a deep-linked id exists, belongs to the user, or is well-formed. The server authorizes the fetch — the client renders the result or an error state.
+- Guard-sensitive destinations are protected by the central `redirect` (`references/navigation.md` → Auth Guards), so a deep link cannot skip authentication. Confirm new protected routes are covered by the guard, not by a per-screen check.
+- Treat any token or credential arriving *in* a deep link (an OAuth callback) as single-use, validated server-side, and never logged.
+
+## Biometric and Auth-Token Handling
+
+Biometric unlock (`local_auth`) gates access to a credential already held in the keystore; it does not authenticate the user to the server. The server trusts the session token, not the fingerprint.
+
+- Use biometrics to unlock or re-confirm before a sensitive action, then present the keystore-held token to the gateway. The biometric check is a local gate, not a replacement for a verified session.
+- Token refresh runs through the dio interceptor against the auth provider; the app does not mint, sign, or verify tokens itself. Auth is boring technology — `docs/principles/system-design/identity-and-access.md`.
+- On biometric failure or lockout, fall back to full re-authentication, never to an unguarded path.
+
+## Obfuscation's Real Limits
+
+`flutter build --obfuscate --split-debug-info` renames symbols and raises the cost of reverse engineering. It is a speed bump, not a control: it does not encrypt logic, hide strings reliably, or protect anything the earlier sections cover. An obfuscated binary still hands a determined attacker every embedded secret and every client-side check.
+
+Ship it for the marginal friction, and depend on it for nothing. The actual protections are: no secrets in the binary, tokens in the keystore, TLS pinning, and authorization on the server.
+
+## Security Review Checklist
+
+For any PR touching auth, secure storage, the dio client, deep-link routes, or build config:
+
+- [ ] No secret, key, or credential embedded in Dart, assets, or `--dart-define`
+- [ ] Tokens and credentials in `flutter_secure_storage` — never `SharedPreferences` or plain files
+- [ ] Secure storage cleared on sign-out and token invalidation
+- [ ] Transport is HTTPS only; pinning present (with a backup pin) for sensitive apps
+- [ ] Deep-link parameters validated in the view model; protected routes covered by the central guard
+- [ ] No client-side check standing in for a server-side authorization decision
+- [ ] Biometrics gate a keystore credential — they do not authenticate to the server
+- [ ] Obfuscation enabled, and relied on for nothing