docs: add Stage 4 — Platform foundations and cross-platform readiness

docs/development/build_execution_tracker.md

@@ -4,8 +4,8 @@
 
 - main baseline updated through: list-efficiency-improvements (Stage 3 complete)
 - main baseline commit: merge of `feat/list-efficiency-improvements` (2026-05-22)
-- next branch: feat/android-app-shell
+- next branch: feat/design-system-shared-widgets
-- current stage: Stage 4 — Android application foundation
+- current stage: Stage 4 — Platform foundations and cross-platform readiness
 
 ## Slice tracker
 
@@ -87,7 +87,7 @@
 - analyze: passed
 - brief updated: yes
 
-### feat/android-app-shell
+### feat/design-system-shared-widgets
 
 - status: queued (Stage 4A — next)
 - inspection: pending

docs/development/master_development_brief.md

@@ -112,7 +112,7 @@ Rules:
 
 ### Next recommended branch
 
-**`feat/android-app-shell`** — Stage 4A: Android app shell and bootstrap.
+**`feat/design-system-shared-widgets`** — Stage 4A: Design system expansion and shared widget migration.
 Branch from latest `main`. Stage 3 (web application operator efficiency) is complete.
 
 ---
@@ -207,7 +207,106 @@ Increase throughput for product triage and management using existing data.
 
 ---
 
-### Stage 4 — Android application foundation
+### Stage 4 — Platform foundations and cross-platform readiness
+
+#### Objective
+
+Strengthen the shared platform infrastructure before expanding to Android. This stage implements the key recommendations from the codebase analysis to reduce technical debt, prevent duplication, and establish quality gates.
+
+#### Key principle
+
+Invest in shared foundations now so that the Android expansion (Stage 5) and all future feature work benefits from a mature design system, shared composition patterns, automated CI/CD, and proper test coverage tracking.
+
+#### Branches
+
+- `feat/design-system-shared-widgets`
+- `feat/flutter-cicd`
+- `feat/shared-composition-pattern`
+
+#### Stage 4A — Design system expansion and shared widget migration
+
+##### Goal
+
+Expand the `design_system` package with reusable widgets and responsive layout primitives so both `kell_web` and `kell_mobile` share a common component library.
+
+##### Requirements
+
+- migrate `EmptyStatePanel`, `SectionHeader`, and `SummaryCard` from `kell_web/lib/shell/widgets/` into `design_system`
+- add shared typography scale to `design_system`
+- add responsive layout breakpoint utilities for web vs mobile
+- add shared loading state and error state widget patterns
+- update `kell_web` imports to reference `design_system` instead of local shell widgets
+- preserve existing visual behavior — no regressions
+
+##### Definition of done
+
+- shared widgets live in `design_system` package
+- `kell_web` references `design_system` for all migrated widgets
+- responsive layout utilities exist for future mobile use
+- analyze clean, existing tests passing
+
+#### Stage 4B — Cross-platform shell composition strategy
+
+##### Goal
+
+Extract or document a shared app composition pattern so `kell_mobile` can mirror the `kell_web` architecture without forking logic.
+
+##### Requirements
+
+- evaluate whether `AppServices`, `AppScope`, `AppConfig`, and `Bootstrap` should move to a shared package (e.g., `core` or new `app_shell`) or remain duplicated with a documented contract
+- if extracting: create shared composition abstractions in the chosen package
+- if duplicating: document the contract explicitly so `kell_mobile` follows the same pattern
+- do not change runtime behavior of `kell_web`
+
+##### Definition of done
+
+- composition strategy is decided and documented
+- shared abstractions extracted or duplication contract documented
+- `kell_web` still works identically
+- analyze clean, existing tests passing
+
+#### Stage 4C — Flutter CI/CD pipeline
+
+##### Goal
+
+Establish automated validation for Flutter applications in Forgejo Actions.
+
+##### Requirements
+
+- add Forgejo Actions workflow for `dart analyze` on PRs
+- add Forgejo Actions workflow for `flutter test` execution on PRs (per package)
+- add basic test result reporting (pass/fail count per package)
+- ensure workflows work for both web and Android targets
+- populate `tools/` directory with any CI helper scripts if needed
+
+##### Definition of done
+
+- PRs trigger automated analyze and test runs
+- test counts are reported in workflow output
+- workflow files committed under `.forgejo/workflows/`
+- `tools/` directory populated or removed if not needed
+
+#### Stage 4D — Test coverage visibility
+
+##### Goal
+
+Introduce lightweight test coverage tracking across packages.
+
+##### Requirements
+
+- add coverage measurement to CI pipeline (at minimum: total tests and pass rate per package)
+- document current baseline coverage in this brief or a companion document
+- do not enforce minimum thresholds yet — visibility first
+
+##### Definition of done
+
+- coverage data is generated and visible in CI output
+- baseline coverage documented
+- no regressions in existing tests
+
+---
+
+### Stage 5 — Android application foundation
 
 #### Objective
 
@@ -222,7 +321,7 @@ Business logic, domain logic, repositories, and feature application logic should
 - `feat/android-app-shell`
 - `feat/android-publishing-surface`
 
-#### Stage 4A — Android app shell and bootstrap
+#### Stage 5A — Android app shell and bootstrap
 
 ##### Goal
 
@@ -247,7 +346,7 @@ Create the Android app entry and shell for the existing platform.
 - analyze/tests remain clean
 - `kell_mobile/pubspec.yaml` references shared packages
 
-#### Stage 4B — Android publishing surface
+#### Stage 5B — Android publishing surface
 
 ##### Goal
 
@@ -267,7 +366,7 @@ Adapt the publishing workflow for mobile form factor.
 
 ---
 
-### Stage 5 — Android operational maturity
+### Stage 6 — Android operational maturity
 
 #### Objective
 
@@ -278,7 +377,7 @@ Harden Android UX after the core feature surface works.
 - `feat/android-feedback-polish`
 - `feat/android-mobile-ux-hardening`
 
-#### Stage 5A — Android feedback and action polish
+#### Stage 6A — Android feedback and action polish
 
 ##### Goal
 
@@ -290,7 +389,7 @@ Ensure action feedback patterns translate cleanly to Android.
 - adapt SnackBar/feedback timing and presentation appropriately
 - validate status/edit workflows on mobile
 
-#### Stage 5B — Android mobile workflow hardening
+#### Stage 6B — Android mobile workflow hardening
 
 ##### Goal
 
@@ -304,7 +403,7 @@ Improve ergonomics on smaller screens.
 
 ---
 
-### Stage 6 — Controlled bulk actions (only after groundwork)
+### Stage 7 — Controlled bulk actions (only after groundwork)
 
 #### Objective
 
@@ -353,7 +452,7 @@ The following packages exist as scaffolded stubs with no implementation. Each ne
 | `feature_mrp`     | Craft Manufacturing / MRP Components                | Low      | Architecture docs exist but no implementation. Defer until inventory workflows mature.                               |
 | `feature_social`  | Social Media Management Components                  | Low      | Architecture docs exist but no implementation. Defer until core platform stabilizes.                                 |
 
-**Recommendation:** Add a **Stage 7 — Infrastructure package activation** to the roadmap covering `auth`, `data`, and `integrations` before expanding into new feature domains.
+**Recommendation:** Add a **Stage 8 — Infrastructure package activation** to the roadmap covering `auth`, `data`, and `integrations` before expanding into new feature domains.
 
 ### 2. Design system expansion
 
@@ -370,7 +469,7 @@ The `design_system` package currently contains:
 - No shared empty state, loading state, or error state patterns
 - Shell widgets (`EmptyStatePanel`, `SectionHeader`, `SummaryCard`) live in `kell_web` app rather than `design_system`
 
-**Recommendation:** Before or during Stage 4 (Android), migrate reusable shell widgets into `design_system` and add responsive layout primitives. This prevents duplication between `kell_web` and `kell_mobile`.
+**Recommendation:** Now addressed in **Stage 4A** (Design system expansion and shared widget migration). Migrate reusable shell widgets into `design_system` and add responsive layout primitives before the Android expansion in Stage 5.
 
 ### 3. Cross-platform shell composition strategy
 
@@ -387,7 +486,7 @@ Currently, CI/CD exists only for MkDocs documentation publishing. There is no au
 - Flutter build validation (web + Android)
 - Test result reporting or quality gates
 
-**Recommendation:** Add a **Stage 4 prerequisite or parallel track** to establish Flutter CI/CD in Forgejo Actions before the Android expansion adds more surfaces to validate.
+**Recommendation:** Now addressed in **Stage 4C** (Flutter CI/CD pipeline). Establish Flutter CI/CD in Forgejo Actions before the Android expansion in Stage 5 adds more surfaces to validate.
 
 ### 5. Test coverage visibility and quality gates