fix(dart): address PR #1055 review comments

Resolves all issues raised by Greptile, CodeRabbit, and Cubic bots:

rules/dart/coding-style.md:
- Replace ?.let (Kotlin idiom) with Dart-native null-safe operators
- Soften "Never use !" to "Avoid !" — reserve for programming-error assertions
- Clarify import guidance: ban relative imports, no self-contradiction

rules/dart/patterns.md:
- Add missing getAll/save/delete implementations to UserRepositoryImpl
- Remove Uuid() from domain UseCase — inject IdGenerator instead (clean arch)
- Fix GoRouter redirect: context.read<AuthState>() -> context.read<AuthCubit>()
- Add refreshListenable: GoRouterRefreshStream to wire reactive auth state

rules/dart/security.md:
- Replace deprecated pre-v4 WebView API with WebViewController/WebViewWidget
- Update bullet points to reference new v4+ API

rules/dart/testing.md:
- Change async => _map[key] = val to async { } block to avoid non-void return

skills/dart-flutter-patterns/SKILL.md:
- Add required "When to Use", "How It Works", "Examples" sections
- Fix firstWhere -> firstWhereOrNull to prevent StateError
- Add refreshListenable to GoRouter pattern
- Add one-time retry guard to Dio 401 interceptor to prevent infinite loops

README.md:
- Fix directory tree "30 specialized subagents" -> "31"

commands/flutter-review.md:
- Add Prerequisites section (build/test/analyze must pass before review)

commands/flutter-build.md:
- Fix Cubit/Bloc API mix: CartCubit.add(event) -> CartCubit.addItem(item)

manifests/install-profiles.json:
- Add flutter-dart to full profile (fixes install manifest validator)

https://claude.ai/code/session_01BQbvf8xFtJyaFiuEgdnsin

Author: claude

commands/flutter-build.md

@@ -97,7 +97,9 @@ state.items.add(item);
 ```
 To:
 ```dart
-context.read<CartCubit>().add(CartItemAdded(item));
+context.read<CartCubit>().addItem(item);
+// Note: Cubit exposes named methods (addItem, removeItem);
+// .add(event) is the BLoC event API — don't mix them.
 ```
 
 ```

commands/flutter-review.md

@@ -14,10 +14,18 @@ This command invokes the **flutter-reviewer** agent to review Flutter/Dart code
 4. **Full Review**: Apply the complete review checklist
 5. **Report Findings**: Output issues grouped by severity with fix guidance
 
+## Prerequisites
+
+Before running `/flutter-review`, ensure:
+1. **Build passes** — run `/flutter-build` first; a review on broken code is incomplete
+2. **Tests pass** — run `/flutter-test` to confirm no regressions
+3. **No merge conflicts** — resolve all conflicts so the diff reflects only intentional changes
+4. **`flutter analyze` is clean** — fix analyzer warnings before review
+
 ## When to Use
 
 Use `/flutter-review` when:
-- Before submitting a PR with Flutter/Dart changes
+- Before submitting a PR with Flutter/Dart changes (after build and tests pass)
 - After implementing a new feature to catch issues early
 - When reviewing someone else's Flutter code
 - To audit a widget, state management component, or service class

manifests/install-profiles.json

@@ -70,6 +70,7 @@
         "media-generation",
         "orchestration",
         "swift-apple",
+        "flutter-dart",
         "agentic-patterns",
         "devops-infra",
         "supply-chain-domain",

rules/dart/coding-style.md

@@ -43,18 +43,28 @@ Follow Dart conventions:
 
 ## Null Safety
 
-- Never use `!` (bang operator) — prefer `?.`, `??`, `if (x != null)`, or Dart 3 pattern matching
-- Use `?.let` style with null checks over forced unwrapping
+- Avoid `!` (bang operator) — prefer `?.`, `??`, `if (x != null)`, or Dart 3 pattern matching; reserve `!` only where a null value is a programming error and crashing is the right behaviour
 - Avoid `late` unless initialization is guaranteed before first use (prefer nullable or constructor init)
 - Use `required` for constructor parameters that must always be provided
 
 ```dart
-// BAD
+// BAD — crashes at runtime if user is null
 final name = user!.name;
 
-// GOOD
+// GOOD — null-aware operators
 final name = user?.name ?? 'Unknown';
-final name = switch (user) { User(:final name) => name, null => 'Unknown' };
+
+// GOOD — Dart 3 pattern matching (exhaustive, compiler-checked)
+final name = switch (user) {
+  User(:final name) => name,
+  null => 'Unknown',
+};
+
+// GOOD — early-return null guard
+String getUserName(User? user) {
+  if (user == null) return 'Unknown';
+  return user.name; // promoted to non-null after the guard
+}
 ```
 
 ## Sealed Types and Pattern Matching (Dart 3+)
@@ -138,9 +148,9 @@ await fetchData();      // or properly awaited
 
 ## Imports
 
-- Use `package:` imports, not relative imports — for consistency across the codebase
-- Order: dart:, package: (external), package: (internal), relative (only for same-package src files)
-- No unused imports — `dart analyze` enforces this
+- Use `package:` imports throughout — never relative imports (`../`) for cross-feature or cross-layer code
+- Order: `dart:` → external `package:` → internal `package:` (same package)
+- No unused imports — `dart analyze` enforces this with `unused_import`
 
 ## Code Generation
 

rules/dart/patterns.md

@@ -33,8 +33,26 @@ class UserRepositoryImpl implements UserRepository {
     return remote;
   }
 
+  @override
+  Future<List<User>> getAll() async {
+    final remote = await _remote.getAll();
+    for (final user in remote) {
+      await _local.save(user);
+    }
+    return remote;
+  }
+
   @override
   Stream<List<User>> watchAll() => _local.watchAll();
+
+  @override
+  Future<void> save(User user) => _local.save(user);
+
+  @override
+  Future<void> delete(String id) async {
+    await _remote.delete(id);
+    await _local.delete(id);
+  }
 }
 ```
 
@@ -161,12 +179,13 @@ class GetUserUseCase {
 }
 
 class CreateUserUseCase {
-  const CreateUserUseCase(this._repository);
+  const CreateUserUseCase(this._repository, this._idGenerator);
   final UserRepository _repository;
+  final IdGenerator _idGenerator; // injected — domain layer must not depend on uuid package directly
 
   Future<void> call(CreateUserInput input) async {
     // Validate, apply business rules, then persist
-    final user = User(id: const Uuid().v4(), name: input.name, email: input.email);
+    final user = User(id: _idGenerator.generate(), name: input.name, email: input.email);
     await _repository.save(user);
   }
 }
@@ -224,8 +243,10 @@ final router = GoRouter(
       },
     ),
   ],
+  // refreshListenable re-evaluates redirect whenever auth state changes
+  refreshListenable: GoRouterRefreshStream(authCubit.stream),
   redirect: (context, state) {
-    final isLoggedIn = context.read<AuthState>().isLoggedIn;
+    final isLoggedIn = context.read<AuthCubit>().state is AuthAuthenticated;
     if (!isLoggedIn && !state.matchedLocation.startsWith('/login')) {
       return '/login';
     }

rules/dart/security.md

@@ -101,22 +101,30 @@ if (uri != null && uri.host == 'myapp.com' && _allowedPaths.contains(uri.path))
 
 ## WebView Security
 
-- Disable JavaScript in WebView unless explicitly required
+- Use `webview_flutter` v4+ (`WebViewController` / `WebViewWidget`) — the legacy `WebView` widget is removed
+- Disable JavaScript unless explicitly required (`JavaScriptMode.disabled`)
 - Validate URLs before loading — never load arbitrary URLs from deep links
 - Never expose Dart callbacks to JavaScript unless absolutely needed and carefully sandboxed
-- Use `navigationDelegate` to intercept and validate navigation requests
+- Use `NavigationDelegate.onNavigationRequest` to intercept and validate navigation requests
 
 ```dart
-WebView(
-  javascriptMode: JavascriptMode.disabled, // default to disabled
-  navigationDelegate: (request) {
-    final uri = Uri.tryParse(request.url);
-    if (uri == null || uri.host != 'trusted.example.com') {
-      return NavigationDecision.prevent;
-    }
-    return NavigationDecision.navigate;
-  },
-)
+// webview_flutter v4+ API (WebViewController + WebViewWidget)
+final controller = WebViewController()
+  ..setJavaScriptMode(JavaScriptMode.disabled) // disabled unless required
+  ..setNavigationDelegate(
+    NavigationDelegate(
+      onNavigationRequest: (request) {
+        final uri = Uri.tryParse(request.url);
+        if (uri == null || uri.host != 'trusted.example.com') {
+          return NavigationDecision.prevent;
+        }
+        return NavigationDecision.navigate;
+      },
+    ),
+  );
+
+// In your widget tree:
+WebViewWidget(controller: controller)
 ```
 
 ## Obfuscation and Build Security

rules/dart/testing.md

@@ -128,10 +128,14 @@ class FakeUserRepository implements UserRepository {
   Stream<List<User>> watchAll() => Stream.value(_users.values.toList());
 
   @override
-  Future<void> save(User user) async => _users[user.id] = user;
+  Future<void> save(User user) async {
+    _users[user.id] = user;
+  }
 
   @override
-  Future<void> delete(String id) async => _users.remove(id);
+  Future<void> delete(String id) async {
+    _users.remove(id);
+  }
 
   void addUser(User user) => _users[user.id] = user;
 }

skills/dart-flutter-patterns/SKILL.md

@@ -6,6 +6,63 @@ origin: ECC
 
 # Dart/Flutter Patterns
 
+## When to Use
+
+Use this skill when:
+- Starting a new Flutter feature and need idiomatic patterns for state management, navigation, or data access
+- Reviewing or writing Dart code and need guidance on null safety, sealed types, or async composition
+- Setting up a new Flutter project and choosing between BLoC, Riverpod, or Provider
+- Implementing secure HTTP clients, WebView integration, or local storage
+- Writing tests for Flutter widgets, Cubits, or Riverpod providers
+- Wiring up GoRouter with authentication guards
+
+## How It Works
+
+This skill provides copy-paste-ready Dart/Flutter code patterns organized by concern:
+1. **Null safety** — avoid `!`, prefer `?.`/`??`/pattern matching
+2. **Immutable state** — sealed classes, `freezed`, `copyWith`
+3. **Async composition** — concurrent `Future.wait`, safe `BuildContext` after `await`
+4. **Widget architecture** — extract to classes (not methods), `const` propagation, scoped rebuilds
+5. **State management** — BLoC/Cubit events, Riverpod notifiers and derived providers
+6. **Navigation** — GoRouter with reactive auth guards via `refreshListenable`
+7. **Networking** — Dio with interceptors, token refresh with one-time retry guard
+8. **Error handling** — global capture, `ErrorWidget.builder`, crashlytics wiring
+9. **Testing** — unit (BLoC test), widget (ProviderScope overrides), fakes over mocks
+
+## Examples
+
+```dart
+// Sealed state — prevents impossible states
+sealed class AsyncState<T> {}
+final class Loading<T> extends AsyncState<T> {}
+final class Success<T> extends AsyncState<T> { final T data; const Success(this.data); }
+final class Failure<T> extends AsyncState<T> { final Object error; const Failure(this.error); }
+
+// GoRouter with reactive auth redirect
+final router = GoRouter(
+  refreshListenable: GoRouterRefreshStream(authCubit.stream),
+  redirect: (context, state) {
+    final authed = context.read<AuthCubit>().state is AuthAuthenticated;
+    if (!authed && !state.matchedLocation.startsWith('/login')) return '/login';
+    return null;
+  },
+  routes: [...],
+);
+
+// Riverpod derived provider with safe firstWhereOrNull
+@riverpod
+double cartTotal(Ref ref) {
+  final cart = ref.watch(cartNotifierProvider);
+  final products = ref.watch(productsProvider).valueOrNull ?? [];
+  return cart.fold(0.0, (total, item) {
+    final product = products.firstWhereOrNull((p) => p.id == item.productId);
+    return total + (product?.price ?? 0) * item.quantity;
+  });
+}
+```
+
+---
+
 Practical, production-ready patterns for Dart and Flutter applications. Library-agnostic where possible, with explicit coverage of the most common ecosystem packages.
 
 ---
@@ -345,8 +402,9 @@ double cartTotal(Ref ref) {
   final cart = ref.watch(cartNotifierProvider);
   final products = ref.watch(productsProvider).valueOrNull ?? [];
   return cart.fold(0.0, (total, item) {
-    final product = products.firstWhere((p) => p.id == item.productId);
-    return total + product.price * item.quantity;
+    // firstWhereOrNull (from collection package) avoids StateError when product is missing
+    final product = products.firstWhereOrNull((p) => p.id == item.productId);
+    return total + (product?.price ?? 0) * item.quantity;
   });
 }
 ```
@@ -358,6 +416,8 @@ double cartTotal(Ref ref) {
 ```dart
 final router = GoRouter(
   initialLocation: '/',
+  // refreshListenable re-evaluates redirect whenever auth state changes
+  refreshListenable: GoRouterRefreshStream(authCubit.stream),
   redirect: (context, state) {
     final isLoggedIn = context.read<AuthCubit>().state is AuthAuthenticated;
     final isGoingToLogin = state.matchedLocation == '/login';
@@ -402,10 +462,12 @@ dio.interceptors.add(InterceptorsWrapper(
     handler.next(options);
   },
   onError: (error, handler) async {
-    if (error.response?.statusCode == 401) {
-      // Token expired — attempt refresh
+    // Guard against infinite retry loops: only attempt refresh once per request
+    final isRetry = error.requestOptions.extra['_isRetry'] == true;
+    if (!isRetry && error.response?.statusCode == 401) {
       final refreshed = await attemptTokenRefresh();
       if (refreshed) {
+        error.requestOptions.extra['_isRetry'] = true;
         return handler.resolve(await dio.fetch(error.requestOptions));
       }
     }