docs: update briefs for merged feat/flutter-cicd (Stage 4C)

- master_development_brief.md: mark Stage 4C complete, update baseline commit, next recommended branch (Stage 4D), tools/ description, resolve improvement #9 - build_execution_tracker.md: update current status to Stage 4C, add missing feat/shared-composition-pattern and feat/flutter-cicd slice entries
Merge feat/flutter-cicd into main (Stage 4C complete)
2026-05-22 10:11:51 -04:00 · 2026-05-22 10:09:49 -04:00 · 2026-05-22 10:09:42 -04:00
6 changed files with 438 additions and 30 deletions
--- a/.forgejo/workflows/flutter-analyze.yml
+++ b/.forgejo/workflows/flutter-analyze.yml
@ -0,0 +1,77 @@
+name: Flutter Analyze
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - "**"
+      - "!main"
+
+jobs:
+  analyze:
+    name: Dart Analyze
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/cirruslabs/flutter:stable
+
+    defaults:
+      run:
+        working-directory: kell_creations_apps
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies — core
+        run: cd packages/core && flutter pub get
+
+      - name: Install dependencies — design_system
+        run: cd packages/design_system && flutter pub get
+
+      - name: Install dependencies — feature_wordpress
+        run: cd packages/feature_wordpress && flutter pub get
+
+      - name: Install dependencies — feature_inventory
+        run: cd packages/feature_inventory && flutter pub get
+
+      - name: Install dependencies — feature_orders
+        run: cd packages/feature_orders && flutter pub get
+
+      - name: Install dependencies — feature_policy
+        run: cd packages/feature_policy && flutter pub get
+
+      - name: Install dependencies — kell_web
+        run: cd apps/kell_web && flutter pub get
+
+      - name: Install dependencies — kell_mobile
+        run: cd apps/kell_mobile && flutter pub get
+
+      - name: Analyze — core
+        run: cd packages/core && dart analyze --fatal-infos
+
+      - name: Analyze — design_system
+        run: cd packages/design_system && dart analyze --fatal-infos
+
+      - name: Analyze — feature_wordpress
+        run: cd packages/feature_wordpress && dart analyze --fatal-infos
+
+      - name: Analyze — feature_inventory
+        run: cd packages/feature_inventory && dart analyze --fatal-infos
+
+      - name: Analyze — feature_orders
+        run: cd packages/feature_orders && dart analyze --fatal-infos
+
+      - name: Analyze — feature_policy
+        run: cd packages/feature_policy && dart analyze --fatal-infos
+
+      - name: Analyze — kell_web
+        run: cd apps/kell_web && dart analyze --fatal-infos
+
+      - name: Analyze — kell_mobile
+        run: cd apps/kell_mobile && dart analyze --fatal-infos
+
+      - name: Summary
+        if: always()
+        run: echo "✅ Dart analyze completed for all packages and apps"
--- a/.forgejo/workflows/flutter-test.yml
+++ b/.forgejo/workflows/flutter-test.yml
@ -0,0 +1,127 @@
+name: Flutter Test
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - "**"
+      - "!main"
+
+jobs:
+  test:
+    name: Flutter Tests
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/cirruslabs/flutter:stable
+
+    defaults:
+      run:
+        working-directory: kell_creations_apps
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies — core
+        run: cd packages/core && flutter pub get
+
+      - name: Install dependencies — design_system
+        run: cd packages/design_system && flutter pub get
+
+      - name: Install dependencies — feature_wordpress
+        run: cd packages/feature_wordpress && flutter pub get
+
+      - name: Install dependencies — kell_web
+        run: cd apps/kell_web && flutter pub get
+
+      - name: Test — core
+        run: |
+          cd packages/core
+          flutter test --reporter expanded 2>&1 | tee test_output.txt
+          echo ""
+          echo "=== core test summary ==="
+          TOTAL=$(grep -cE '^\s*✓' test_output.txt || echo "0")
+          FAILED=$(grep -cE '^\s*✗' test_output.txt || echo "0")
+          echo "  Passed: $TOTAL"
+          echo "  Failed: $FAILED"
+          # Fail the step if any tests failed
+          if [ "$FAILED" -gt 0 ]; then exit 1; fi
+
+      - name: Test — design_system
+        run: |
+          cd packages/design_system
+          flutter test --reporter expanded 2>&1 | tee test_output.txt
+          echo ""
+          echo "=== design_system test summary ==="
+          TOTAL=$(grep -cE '^\s*✓' test_output.txt || echo "0")
+          FAILED=$(grep -cE '^\s*✗' test_output.txt || echo "0")
+          echo "  Passed: $TOTAL"
+          echo "  Failed: $FAILED"
+          if [ "$FAILED" -gt 0 ]; then exit 1; fi
+
+      - name: Test — feature_wordpress
+        run: |
+          cd packages/feature_wordpress
+          flutter test --reporter expanded 2>&1 | tee test_output.txt
+          echo ""
+          echo "=== feature_wordpress test summary ==="
+          TOTAL=$(grep -cE '^\s*✓' test_output.txt || echo "0")
+          FAILED=$(grep -cE '^\s*✗' test_output.txt || echo "0")
+          echo "  Passed: $TOTAL"
+          echo "  Failed: $FAILED"
+          if [ "$FAILED" -gt 0 ]; then exit 1; fi
+
+      - name: Test — kell_web
+        run: |
+          cd apps/kell_web
+          flutter test --reporter expanded 2>&1 | tee test_output.txt
+          echo ""
+          echo "=== kell_web test summary ==="
+          TOTAL=$(grep -cE '^\s*✓' test_output.txt || echo "0")
+          FAILED=$(grep -cE '^\s*✗' test_output.txt || echo "0")
+          echo "  Passed: $TOTAL"
+          echo "  Failed: $FAILED"
+          if [ "$FAILED" -gt 0 ]; then exit 1; fi
+
+      - name: Aggregate test report
+        if: always()
+        run: |
+          echo ""
+          echo "╔══════════════════════════════════════╗"
+          echo "║     Flutter Test Results Summary     ║"
+          echo "╠══════════════════════════════════════╣"
+          echo "║ Package              Pass    Fail    ║"
+          echo "╠══════════════════════════════════════╣"
+
+          TOTAL_PASS=0
+          TOTAL_FAIL=0
+
+          for pkg in packages/core packages/design_system packages/feature_wordpress apps/kell_web; do
+            NAME=$(basename "$pkg")
+            OUTPUT="$pkg/test_output.txt"
+            if [ -f "$OUTPUT" ]; then
+              PASS=$(grep -cE '^\s*✓' "$OUTPUT" || echo "0")
+              FAIL=$(grep -cE '^\s*✗' "$OUTPUT" || echo "0")
+            else
+              PASS="—"
+              FAIL="—"
+            fi
+            printf "║ %-20s %-7s %-7s ║\n" "$NAME" "$PASS" "$FAIL"
+            if [ "$PASS" != "—" ]; then TOTAL_PASS=$((TOTAL_PASS + PASS)); fi
+            if [ "$FAIL" != "—" ]; then TOTAL_FAIL=$((TOTAL_FAIL + FAIL)); fi
+          done
+
+          echo "╠══════════════════════════════════════╣"
+          printf "║ %-20s %-7s %-7s ║\n" "TOTAL" "$TOTAL_PASS" "$TOTAL_FAIL"
+          echo "╚══════════════════════════════════════╝"
+
+          if [ "$TOTAL_FAIL" -gt 0 ]; then
+            echo ""
+            echo "❌ Some tests failed. See individual package results above."
+            exit 1
+          else
+            echo ""
+            echo "✅ All $TOTAL_PASS tests passed across all packages."
+          fi
--- a/docs/development/build_execution_tracker.md
+++ b/docs/development/build_execution_tracker.md
@ -2,9 +2,9 @@

 ## Current status

- main baseline updated through: design-system-shared-widgets (Stage 4A complete)
- main baseline commit: merge of `feat/design-system-shared-widgets` (2026-05-22)
- next branch: feat/shared-composition-pattern
+- main baseline updated through: flutter-cicd (Stage 4C complete)
+- main baseline commit: merge of `feat/flutter-cicd` (2026-05-22)
+- next branch: feat/test-coverage-visibility (Stage 4D)
 - current stage: Stage 4 — Platform foundations and cross-platform readiness

 ## Slice tracker
@ -111,3 +111,33 @@
 - tests: passed (41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web)
 - analyze: passed (dart analyze — no issues found in design_system and kell_web)
 - brief updated: yes
+
+### feat/shared-composition-pattern
+
+- status: merged to main
+- date: 2026-05-22
+- inspection: complete
+- implementation: complete
+- files changed:
+  - `core/lib/src/app/` — extracted shared composition abstractions (KcAppConfig, KcAppEnvironment, KcAppServices, KcServiceFactory, KcBootstrap, KcAppScope)
+  - `core/lib/core.dart` — expanded barrel exports for app composition
+  - `core/test/core_test.dart` — added 20 tests for shared composition abstractions
+  - `kell_web/` — updated to use core composition abstractions
+- tests: passed (20/20 core, 41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web)
+- analyze: passed
+- brief updated: yes
+
+### feat/flutter-cicd
+
+- status: merged to main
+- date: 2026-05-22
+- inspection: complete
+- implementation: complete
+- files changed:
+  - `.forgejo/workflows/flutter-analyze.yml` — new Forgejo Actions workflow for dart analyze on all 8 packages/apps
+  - `.forgejo/workflows/flutter-test.yml` — new Forgejo Actions workflow for flutter test per package with aggregate pass/fail summary
+  - `kell_creations_apps/tools/run_all_tests.sh` — new local CI helper script with optional --analyze flag
+  - `kell_creations_apps/tools/README.md` — documents scripts and CI workflow inventory
+- tests: passed (20/20 core, 41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web — 379 total)
+- analyze: passed (dart analyze — no issues found across all 8 packages/apps)
+- brief updated: yes
--- a/docs/development/master_development_brief.md
+++ b/docs/development/master_development_brief.md
@ -61,7 +61,7 @@ Rules:
  - `feature_finance` — financial analysis feature (stub only)
  - `feature_mrp` — craft manufacturing/MRP feature (stub only)
  - `feature_social` — social media management feature (stub only)
- `tools/` directory exists but is empty.
+- `tools/` directory contains CI helper scripts (`run_all_tests.sh`, `README.md`).
 - App shell, routing, dashboard, reusable shell widgets, `AppServices`, and `AppScope` are implemented.
 - Dashboard uses app-composed repository data.
 - Vertical slices exist for Inventory, Products/Publishing, Orders, and Policy/Governance.
@ -94,6 +94,7 @@ Rules:
 - ✅ List efficiency improvements landed (Stage 3B complete — merged `feat/list-efficiency-improvements` → `main`, 2026-05-22). Stage 3 complete.
 - ✅ Design system expansion and shared widget migration landed (Stage 4A complete — merged `feat/design-system-shared-widgets` → `main`, 2026-05-22).
 - ✅ Cross-platform shell composition strategy landed (Stage 4B complete — merged `feat/shared-composition-pattern` → `main`, 2026-05-22).
+- ✅ Flutter CI/CD pipeline landed (Stage 4C complete — merged `feat/flutter-cicd` → `main`, 2026-05-22).

 ### Current narrow edit capabilities on `main`

@ -114,12 +115,12 @@ Rules:
 - latest reported count for `design_system`: `41/41 passed`
 - latest reported count for `feature_wordpress`: `294/294 passed`
 - latest reported count for `kell_web`: `24/24 passed`
- baseline commit: merge of `feat/shared-composition-pattern` (2026-05-22)
+- baseline commit: merge of `feat/flutter-cicd` (2026-05-22)

 ### Next recommended branch

-**`feat/flutter-cicd`** — Stage 4C: Flutter CI/CD pipeline.
-Branch from latest `main`. Stage 4B (cross-platform shell composition) is complete.
+**`feat/test-coverage-visibility`** — Stage 4D: Test coverage visibility.
+Branch from latest `main`. Stage 4C (Flutter CI/CD pipeline) is complete.

 ---

@ -254,26 +255,10 @@ Extract or document a shared app composition pattern so `kell_mobile` can mirror
 - `kell_web` still works identically
 - analyze clean, existing tests passing

-#### Stage 4C — Flutter CI/CD pipeline
+#### ~~Stage 4C — Flutter CI/CD pipeline~~ ✅ COMPLETE

-##### 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
+> Merged `feat/flutter-cicd` → `main` (2026-05-22).
+> Added Forgejo Actions workflows: `flutter-analyze.yml` (runs `dart analyze --fatal-infos` on all 8 packages/apps) and `flutter-test.yml` (runs `flutter test` per package with per-package pass/fail count and aggregate summary table). Workflows trigger on PRs to main and all non-main branch pushes using `ghcr.io/cirruslabs/flutter:stable` container. Populated `tools/` directory with `run_all_tests.sh` (local test runner with optional `--analyze` flag) and `README.md` documenting scripts and CI workflow inventory. All existing tests passing (20 core, 41 design_system, 294 feature_wordpress, 24 kell_web — 379 total). Analyze clean.

 #### Stage 4D — Test coverage visibility

@ -514,11 +499,9 @@ No monitoring, error tracking, or analytics strategy exists for the Flutter appl

 **Recommendation:** Add lightweight error reporting and observability as a future stage, particularly important before any production WP-mode deployment beyond a single operator.

-### 9. Empty tools directory
+### 9. ~~Empty tools directory~~ ✅ RESOLVED

-The `tools/` directory under `kell_creations_apps` exists but contains nothing.
-
-**Recommendation:** Either populate with development tooling (code generation scripts, analysis helpers, CI scripts) or remove to avoid confusion. If CI/CD scripts are planned, this is a natural home.
+> Now populated with `run_all_tests.sh` and `README.md` as part of Stage 4C (Flutter CI/CD pipeline).

 ### 10. Missing feature parity documentation

--- a/kell_creations_apps/tools/README.md
+++ b/kell_creations_apps/tools/README.md
@ -0,0 +1,44 @@
+# Tools
+
+CI/CD helper scripts for the Kell Creations Flutter monorepo.
+
+## Scripts
+
+### `run_all_tests.sh`
+
+Runs `flutter test` across all testable packages and apps, producing a per-package pass/fail summary.
+
+**Usage:**
+
+```bash
+# From kell_creations_apps/ directory
+./tools/run_all_tests.sh           # Run tests only
+./tools/run_all_tests.sh --analyze # Run dart analyze + tests
+```
+
+**What it does:**
+
+1. Installs dependencies (`flutter pub get`) for all packages and apps.
+2. Optionally runs `dart analyze --fatal-infos` on each package/app.
+3. Runs `flutter test --reporter expanded` for packages with tests.
+4. Prints an aggregate pass/fail summary table.
+
+**Adding new packages:**
+
+When a new package gains tests, add its path to the `TESTABLE` array in the script. For packages that should be analyzed but have no tests yet, add to the `ANALYZABLE` array only.
+
+**Exit codes:**
+
+- `0` — all tests passed (and analyze clean, if `--analyze` was used)
+- `1` — one or more failures detected
+
+## CI Workflows
+
+The corresponding Forgejo Actions workflows live in `.forgejo/workflows/`:
+
+| Workflow              | Trigger           | Purpose                                      |
+| --------------------- | ----------------- | -------------------------------------------- |
+| `flutter-analyze.yml` | PRs and branches  | Runs `dart analyze` on all packages and apps |
+| `flutter-test.yml`    | PRs and branches  | Runs `flutter test` with result reporting    |
+| `validate-docs.yml`   | Non-main branches | Validates MkDocs documentation build         |
+| `publish-docs.yml`    | Push to main      | Publishes documentation to docs host         |
--- a/kell_creations_apps/tools/run_all_tests.sh
+++ b/kell_creations_apps/tools/run_all_tests.sh
@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────────────
+# run_all_tests.sh — Run flutter test for all testable packages and apps
+#
+# Usage:
+#   ./tools/run_all_tests.sh           # Run from kell_creations_apps/
+#   ./tools/run_all_tests.sh --analyze # Also run dart analyze first
+#
+# Exit codes:
+#   0 — all tests passed (and analyze clean, if requested)
+#   1 — one or more failures
+# ──────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Packages/apps with tests (add new ones here as they gain tests)
+TESTABLE=(
+  packages/core
+  packages/design_system
+  packages/feature_wordpress
+  apps/kell_web
+)
+
+# All packages/apps to analyze (includes those without tests)
+ANALYZABLE=(
+  packages/core
+  packages/design_system
+  packages/feature_wordpress
+  packages/feature_inventory
+  packages/feature_orders
+  packages/feature_policy
+  apps/kell_web
+  apps/kell_mobile
+)
+
+RUN_ANALYZE=false
+if [[ "${1:-}" == "--analyze" ]]; then
+  RUN_ANALYZE=true
+fi
+
+OVERALL_EXIT=0
+
+# ── Dependency install ───────────────────────────────────────────────
+echo ""
+echo "══════════════════════════════════════"
+echo "  Installing dependencies"
+echo "══════════════════════════════════════"
+
+for pkg in "${ANALYZABLE[@]}"; do
+  echo "  → $pkg"
+  (cd "$ROOT_DIR/$pkg" && flutter pub get --no-example) > /dev/null 2>&1
+done
+
+# ── Analyze (optional) ──────────────────────────────────────────────
+if $RUN_ANALYZE; then
+  echo ""
+  echo "══════════════════════════════════════"
+  echo "  Running dart analyze"
+  echo "══════════════════════════════════════"
+
+  ANALYZE_FAILURES=()
+  for pkg in "${ANALYZABLE[@]}"; do
+    NAME=$(basename "$pkg")
+    printf "  %-25s" "$NAME"
+    if (cd "$ROOT_DIR/$pkg" && dart analyze --fatal-infos) > /dev/null 2>&1; then
+      echo "✅ clean"
+    else
+      echo "❌ issues found"
+      ANALYZE_FAILURES+=("$NAME")
+      OVERALL_EXIT=1
+    fi
+  done
+
+  if [ ${#ANALYZE_FAILURES[@]} -gt 0 ]; then
+    echo ""
+    echo "  ❌ Analyze failures: ${ANALYZE_FAILURES[*]}"
+  else
+    echo ""
+    echo "  ✅ All packages analyze clean"
+  fi
+fi
+
+# ── Tests ────────────────────────────────────────────────────────────
+echo ""
+echo "══════════════════════════════════════"
+echo "  Running flutter test"
+echo "══════════════════════════════════════"
+
+declare -A RESULTS_PASS
+declare -A RESULTS_FAIL
+TEST_FAILURES=()
+
+for pkg in "${TESTABLE[@]}"; do
+  NAME=$(basename "$pkg")
+  echo ""
+  echo "  ── $NAME ──"
+
+  TMPFILE=$(mktemp)
+  if (cd "$ROOT_DIR/$pkg" && flutter test --reporter expanded 2>&1) | tee "$TMPFILE"; then
+    : # tests passed
+  else
+    TEST_FAILURES+=("$NAME")
+    OVERALL_EXIT=1
+  fi
+
+  PASS=$(grep -cE '^\s*✓' "$TMPFILE" 2>/dev/null || echo "0")
+  FAIL=$(grep -cE '^\s*✗' "$TMPFILE" 2>/dev/null || echo "0")
+  RESULTS_PASS[$NAME]=$PASS
+  RESULTS_FAIL[$NAME]=$FAIL
+  rm -f "$TMPFILE"
+done
+
+# ── Summary ──────────────────────────────────────────────────────────
+echo ""
+echo "╔══════════════════════════════════════╗"
+echo "║     Flutter Test Results Summary     ║"
+echo "╠══════════════════════════════════════╣"
+echo "║ Package              Pass    Fail    ║"
+echo "╠══════════════════════════════════════╣"
+
+TOTAL_PASS=0
+TOTAL_FAIL=0
+
+for pkg in "${TESTABLE[@]}"; do
+  NAME=$(basename "$pkg")
+  P=${RESULTS_PASS[$NAME]:-0}
+  F=${RESULTS_FAIL[$NAME]:-0}
+  printf "║ %-20s %-7s %-7s ║\n" "$NAME" "$P" "$F"
+  TOTAL_PASS=$((TOTAL_PASS + P))
+  TOTAL_FAIL=$((TOTAL_FAIL + F))
+done
+
+echo "╠══════════════════════════════════════╣"
+printf "║ %-20s %-7s %-7s ║\n" "TOTAL" "$TOTAL_PASS" "$TOTAL_FAIL"
+echo "╚══════════════════════════════════════╝"
+
+if [ $OVERALL_EXIT -ne 0 ]; then
+  echo ""
+  echo "❌ Failures detected. See details above."
+else
+  echo ""
+  echo "✅ All $TOTAL_PASS tests passed across all packages."
+fi
+
+exit $OVERALL_EXIT