Initial commit: Grounded Flutter frontend

A to-do app that doesn't believe you — an enforcement layer rather than a
neutral ledger.

Architecture ported from Autoreceptives/Frontend/Receptive: stacked MVVM with
the mandatory 4-file screen pattern, one ParentViewModel owning the loading /
network / error overlays and the handleError decision tree, one AppDataManager
gateway, dio comms carrying the three identity headers, secure storage with
random-suffixed keys, and a single-chokepoint Navigator. Package root and Dart
package name are both Grounded; org is nya.

The enforcement engine, one unit per formula in utils/:

- DebtEngine      w(class) x severity(d) x decay(t), sublinear severity so old
                  misses cannot swamp the score; abandonment 2x with 30-day
                  decay immunity; late complete retains 30%
- StandingEngine  Good -> Warned -> Grounded -> Lockdown, derived not set;
                  Grounded replaces home with the overdue queue
- CapacityEngine  blocks over-scheduling against p50 of historically completed
                  minutes, with a learned per-category estimation multiplier
- IntegrityEngine session integrity, weekly volume, plyometric contact ceiling
                  and enforced recovery gaps
- ExcuseAnalyser  on-device excuse clustering plus the confrontation copy
- GuardrailEngine distress detection and rationed amnesty
- ToneEngine      all enforcement copy, so the tone cap lives in one place

CommitmentEvent is append-only and is the source of truth rather than the
status field, which is what makes honest history and excuse analysis possible.

Goals contain commitments via parentId, and a task can be run from a
full-screen runner that derives elapsed time from wall-clock so screen-off
cannot lose time. Backgrounding pauses the clock and is counted. The runner is
mirrored into an ongoing notification, with alarm-class full-screen intents
reserved for non-negotiables.

Design language, fonts, icon and native splash are in place; Mason bricks are
retargeted to this project and verified end-to-end.

flutter analyze lib/ reports no errors.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mfu2gQLSFN21YRBcU2NrTt

frontend/lib/Grounded/configs/Env.dart

@@ -0,0 +1,7 @@
+import 'package:flutter_dotenv/flutter_dotenv.dart';
+
+String groundedRouteProd = dotenv.get('GROUNDED_PRODUCTION_PATH', fallback: '');
+
+String groundedRouteLocal = dotenv.get('GROUNDED_LOCAL_PATH', fallback: '');
+
+String localisedAppVersion = dotenv.get('LOCALISED_APP_VERSION', fallback: '');

frontend/lib/Grounded/configs/Navigator.dart

@@ -0,0 +1,61 @@
+import 'package:flutter/material.dart';
+import 'package:page_transition/page_transition.dart';
+
+import '../about/internal/application/NavigatorType.dart';
+
+/// Every transition in the app funnels through here. Destinations are widget
+/// instances, not named routes, and the single choke point is what lets a
+/// device-integrity check gate all routing.
+class GroundedNavigation {
+  void navigateToPage(NavigatorType type, dynamic path, BuildContext context) {
+    _runSec(context, type, path);
+  }
+
+  Future _runSec(BuildContext context, NavigatorType type, dynamic path) async {
+    switch (type) {
+      case NavigatorType.openFully:
+        Navigator.of(context).pushReplacement(
+            MaterialPageRoute(builder: (BuildContext context) => path));
+        break;
+      case NavigatorType.justOpen:
+        Navigator.push(
+            context,
+            PageTransition(
+                type: PageTransitionType.size,
+                alignment: Alignment.center,
+                child: path));
+        break;
+      case NavigatorType.replaceCurrent:
+        Navigator.pushReplacement(
+            context,
+            PageTransition(
+                type: PageTransitionType.scale,
+                alignment: Alignment.center,
+                curve: Curves.ease,
+                duration: const Duration(microseconds: 9000),
+                child: path));
+        break;
+      case NavigatorType.makeNewMain:
+        Navigator.pushAndRemoveUntil(
+            context,
+            PageTransition(
+                type: PageTransitionType.fade,
+                alignment: Alignment.center,
+                child: path),
+            ModalRoute.withName('/'));
+        break;
+    }
+  }
+
+  /// The reload-on-return channel: the child pops with a result and the parent
+  /// refreshes on it.
+  Future<dynamic> navigateToPageWithData(
+      dynamic path, BuildContext context) async {
+    return await Navigator.push(
+      context,
+      MaterialPageRoute(
+        builder: (context) => path,
+      ),
+    );
+  }
+}

frontend/lib/Grounded/configs/NotificationServiceConfig.dart

@@ -0,0 +1,204 @@
+import 'dart:io';
+
+import 'package:flutter_local_notifications/flutter_local_notifications.dart';
+
+import '../about/external/data/Commitment.dart';
+import '../about/external/data/LiveSession.dart';
+import '../about/internal/application/CommitmentClass.dart';
+import '../about/internal/application/EscalationTier.dart';
+import '../about/internal/application/ToneLevel.dart';
+import '../utils/CommonUtils.dart';
+import '../utils/ToneEngine.dart';
+
+/// Notification channels, the ongoing "task running" notification, and the
+/// full-screen alarm used for non-negotiables.
+class LocalNotificationEngine {
+  static final FlutterLocalNotificationsPlugin plugin =
+      FlutterLocalNotificationsPlugin();
+
+  /// Ordinary reminders — respects quiet hours.
+  static const String reminderChannel = "grounded_reminders";
+
+  /// The ongoing notification attached to a running task. Not dismissable, so
+  /// a task in progress is always one tap away from the lock screen.
+  static const String sessionChannel = "grounded_session";
+
+  /// Alarm-class, full-screen. Reserved for non-negotiables, and the only
+  /// channel that overrides quiet hours.
+  static const String alarmChannel = "grounded_alarm";
+
+  static const int sessionNotificationId = 9000;
+
+  static bool _ready = false;
+
+  static Future<void> init() async {
+    if (_ready) {
+      return;
+    }
+
+    const AndroidInitializationSettings android =
+        AndroidInitializationSettings('@mipmap/ic_launcher');
+
+    const DarwinInitializationSettings apple = DarwinInitializationSettings(
+      requestAlertPermission: true,
+      requestBadgePermission: true,
+      requestSoundPermission: true,
+      // Critical alerts need Apple entitlement approval; requesting without it
+      // is simply ignored rather than failing.
+      requestCriticalPermission: true,
+    );
+
+    await plugin.initialize(
+      settings: const InitializationSettings(
+          android: android, iOS: apple, macOS: apple),
+    );
+
+    if (Platform.isAndroid) {
+      await _createAndroidChannels();
+    }
+
+    _ready = true;
+  }
+
+  static Future<void> _createAndroidChannels() async {
+    final AndroidFlutterLocalNotificationsPlugin? android =
+        plugin.resolvePlatformSpecificImplementation<
+            AndroidFlutterLocalNotificationsPlugin>();
+
+    if (android == null) {
+      return;
+    }
+
+    await android.createNotificationChannel(const AndroidNotificationChannel(
+      reminderChannel,
+      'Reminders',
+      description: 'Nudges about commitments that are due.',
+      importance: Importance.defaultImportance,
+    ));
+
+    await android.createNotificationChannel(const AndroidNotificationChannel(
+      sessionChannel,
+      'Task in progress',
+      description: 'The ongoing notification for a task you are running.',
+      importance: Importance.low,
+      playSound: false,
+      enableVibration: false,
+    ));
+
+    await android.createNotificationChannel(const AndroidNotificationChannel(
+      alarmChannel,
+      'Non-negotiables',
+      description:
+          'Full-screen alarms for non-negotiable commitments. These ignore quiet hours.',
+      importance: Importance.max,
+      playSound: true,
+      enableVibration: true,
+    ));
+
+    await android.requestNotificationsPermission();
+
+    // Exact alarms are what let a window actually close on time rather than
+    // whenever the OS feels like it.
+    await android.requestExactAlarmsPermission();
+  }
+
+  /// The ongoing notification for a running task. Shows the live remaining
+  /// time so it is useful from the lock screen without unlocking.
+  static Future<void> showSessionNotification(LiveSession session) async {
+    await init();
+
+    final String remaining = session.requiredSeconds > 0
+        ? "${formatClock(session.remainingSeconds())} remaining"
+        : "${formatClock(session.elapsedSeconds())} elapsed";
+
+    final AndroidNotificationDetails android = AndroidNotificationDetails(
+      sessionChannel,
+      'Task in progress',
+      channelDescription: 'The ongoing notification for a running task.',
+      importance: Importance.low,
+      priority: Priority.low,
+      ongoing: true,
+      autoCancel: false,
+      onlyAlertOnce: true,
+      showWhen: true,
+      usesChronometer: session.requiredSeconds <= 0,
+      category: AndroidNotificationCategory.workout,
+      actions: const <AndroidNotificationAction>[
+        AndroidNotificationAction('pause', 'Pause'),
+        AndroidNotificationAction('finish', 'Finish'),
+      ],
+    );
+
+    await plugin.show(
+      id: sessionNotificationId,
+      title: session.title,
+      body: session.goalTitle.isEmpty
+          ? remaining
+          : "${session.goalTitle} · $remaining",
+      notificationDetails: NotificationDetails(
+        android: android,
+        iOS: const DarwinNotificationDetails(presentBanner: false),
+      ),
+      payload: session.commitmentId,
+    );
+  }
+
+  static Future<void> cancelSessionNotification() async {
+    await init();
+    await plugin.cancel(id: sessionNotificationId);
+  }
+
+  /// A due-window nudge. Non-negotiables go out full-screen and alarm-class so
+  /// they surface over the lock screen; everything else is an ordinary
+  /// notification.
+  static Future<void> showCommitmentNudge(
+    Commitment commitment,
+    EscalationTier tier,
+    ToneLevel tone,
+  ) async {
+    await init();
+
+    final bool nonNegotiable =
+        commitment.commitmentClass == CommitmentClass.NonNegotiable;
+
+    final AndroidNotificationDetails android = AndroidNotificationDetails(
+      nonNegotiable ? alarmChannel : reminderChannel,
+      nonNegotiable ? 'Non-negotiables' : 'Reminders',
+      importance: nonNegotiable ? Importance.max : Importance.defaultImportance,
+      priority: nonNegotiable ? Priority.max : Priority.defaultPriority,
+      // The full-screen intent is what turns this into a lock-screen takeover
+      // rather than a banner that can be swiped past.
+      fullScreenIntent: nonNegotiable,
+      category: nonNegotiable
+          ? AndroidNotificationCategory.alarm
+          : AndroidNotificationCategory.reminder,
+      actions: <AndroidNotificationAction>[
+        const AndroidNotificationAction('start', 'Start now'),
+        if (!nonNegotiable)
+          const AndroidNotificationAction('snooze', 'Snooze'),
+      ],
+    );
+
+    await plugin.show(
+      id: commitment.id.hashCode,
+      title: commitment.title,
+      body: ToneEngine.nudge(tier, tone, commitment.title),
+      notificationDetails: NotificationDetails(
+        android: android,
+        iOS: DarwinNotificationDetails(
+          // Critical alerts bypass Do Not Disturb, and are the iOS equivalent
+          // of the Android full-screen intent. Requires Apple approval.
+          interruptionLevel: nonNegotiable
+              ? InterruptionLevel.critical
+              : InterruptionLevel.active,
+        ),
+      ),
+      payload: commitment.id,
+    );
+  }
+
+  static Future<void> cancelAll() async {
+    await init();
+    await plugin.cancelAll();
+  }
+}