# Release Checklist **Owner:** Release Committee **Applies to:** `kell_web` (Flutter Web / Windows Desktop) and `kell_mobile` (Flutter Android) **Last reviewed:** 2026-08-29 **Review cycle:** Every release; document reviewed at least quarterly --- ## Purpose This document defines the **mandatory gates** a build must pass before it is promoted into each target environment. Each environment inherits every gate from the environment before it, then adds its own. Promotion is **sequential**: Development → Test/QA → Staging → Production. A build may not skip an environment. --- ## 1. Environment Matrix | Environment | Target | `KC_ENV` | Square mode | Data | Audience | Approver | | --------------- | --------------------------------- | --------------------- | ------------ | ----------------------- | ------------- | ----------------- | | **Development** | Local workstation | `fake` | n/a | In-memory fakes | Engineer | Self | | **Test / QA** | CI runner + internal test devices | `wordpress` | n/a | WooCommerce staging | Engineer + QA | Engineering lead | | **Staging** | Pre-production host + test device | `multi` | `sandbox` | Staging WC + Square SBX | QA + business | Release committee | | **Production** | Live web host + Play Store track | `wordpress` / `multi` | `production` | Live WC + Square live | Operators | Release committee | > **Rule:** `KC_SQUARE_ENVIRONMENT=production` is permitted **only** in the > Production environment. Any lower environment using a live Square token is an > immediate stop-ship defect. --- ## 2. Universal Gates (all environments) These must pass before any promotion. - [ ] `dart analyze --fatal-infos` is clean for all 11 packages and both apps - [ ] Full test suite passes — current baseline **1,475 / 1,475** - [ ] No test is skipped, `@Skip`-ed, or commented out without a linked issue - [ ] `docs/development/build_execution_tracker.md` has a slice entry for the change - [ ] `docs/development/master_development_brief.md` reflects the new baseline - [ ] No secrets committed — credentials supplied only via `--dart-define` - [ ] No `TODO`/`FIXME` introduced without a linked tracker item Commands: ```bash cd kell_creations_apps ./tools/run_all_tests.sh --analyze ``` --- ## 3. Development Environment **Purpose:** Fast inner-loop work against in-memory fakes. No external calls. ### Build ```bash flutter run -d chrome --dart-define=KC_ENV=fake # kell_web flutter run -d android --dart-define=KC_ENV=fake # kell_mobile ``` ### Gates - [ ] Universal gates pass - [ ] Feature branch is cut from current `main` - [ ] Slice is vertical and reviewable (domain → application → data → presentation) - [ ] New public APIs carry doc comments - [ ] Environment badge renders `FAKE` - [ ] "Report a problem" action opens the dialog and submits successfully - [ ] No unexpected `ERROR`/`FATAL` records in the console during a smoke pass ### Exit criteria Analyze clean, tests green, tracker updated. Open PR into `main`. --- ## 4. Test / QA Environment **Purpose:** Validate real WooCommerce integration and cross-platform parity. ### Build ```bash flutter build web --dart-define=KC_ENV=wordpress \ --dart-define=KC_WC_SITE_URL=https://staging.kellcreations.com \ --dart-define=KC_WC_CONSUMER_KEY=ck_xxx \ --dart-define=KC_WC_CONSUMER_SECRET=cs_xxx flutter build apk --debug --dart-define=KC_ENV=wordpress \ --dart-define=KC_WC_SITE_URL=https://staging.kellcreations.com \ --dart-define=KC_WC_CONSUMER_KEY=ck_xxx \ --dart-define=KC_WC_CONSUMER_SECRET=cs_xxx ``` ### Gates - [ ] All Development gates pass - [ ] Forgejo `Flutter Test` workflow green - [ ] Forgejo `Flutter Analyze` workflow green - [ ] Coverage reported in the CI summary; no unexplained decrease - [ ] Credentials point at **staging** WooCommerce — never production - [ ] Environment badge renders `WP` - [ ] Missing-credential path verified: app falls back to `FAKE` **and logs a warning** ### Functional verification (WooCommerce) - [ ] Product list loads, filters, searches, and sorts - [ ] Single-field edits persist (name, price, description, category) - [ ] Status transitions behave (`unpublished` → `draft`, `pendingReview` → `published`) - [ ] Product creation completes on web (`CreateProductDialog`) and mobile (`MobileCreateProductPage`) - [ ] Category CRUD works - [ ] Bulk actions (move-to-draft, publish, submit-for-review) work - [ ] API failures surface a user-visible error — never a silent failure ### Observability verification - [ ] Startup record written with the effective environment - [ ] A forced API failure produces an `ERROR` record with source and context - [ ] Bug report submission attaches the recent log tail - [ ] **Credential redaction confirmed** — no token, key, or secret appears in any log or report ### Mobile-specific - [ ] Touch targets meet the 48×48dp minimum - [ ] Haptics fire (`mediumImpact` state changes, `lightImpact` field edits) - [ ] Layout is correct on a notch/gesture-bar device - [ ] Back navigation behaves throughout ### Exit criteria CI green, functional pass recorded, no open Critical or High defects. --- ## 5. Staging Environment **Purpose:** Production rehearsal with both channels live in sandbox mode. ### Build ```bash flutter build web --release --dart-define=KC_ENV=multi \ --dart-define=KC_WC_SITE_URL=https://staging.kellcreations.com \ --dart-define=KC_WC_CONSUMER_KEY=ck_xxx \ --dart-define=KC_WC_CONSUMER_SECRET=cs_xxx \ --dart-define=KC_SQUARE_ACCESS_TOKEN=EAAAl_sandbox_xxx \ --dart-define=KC_SQUARE_LOCATION_ID=L_xxx \ --dart-define=KC_SQUARE_ENVIRONMENT=sandbox ``` The Android build uses the same defines with `flutter build apk --release`. ### Gates - [ ] All Test/QA gates pass - [ ] Built in **release** mode (not debug/profile) - [ ] `KC_SQUARE_ENVIRONMENT=sandbox` — confirmed, not `production` - [ ] Square token is a **sandbox** token - [ ] Environment badge renders `MULTI` - [ ] Incomplete-credential path falls back to `FAKE` with a logged warning ### Multi-channel verification - [ ] Square catalog sync completes; `SquareSyncStatusPanel` reports the result - [ ] `ProductIdMapping` records are created correctly — **no duplicate listings** - [ ] Already-synced products reuse their existing mapping (ID conflation regression check) - [ ] Square inventory counts load and reconcile - [ ] Partial sync failure surfaces per-item `SyncError` detail - [ ] Integrations page reflects live sync state on web and mobile ### Mobile POS verification (sandbox) - [ ] Product selection → cart → payment flow completes - [ ] Cash payment records correctly - [ ] Card payment completes against Square sandbox - [ ] Receipt renders with the correct total - [ ] Payment failure is handled without data loss ### Non-functional - [ ] Release build starts within an acceptable time on a representative device - [ ] No memory growth across an extended session - [ ] Web build loads over the target network profile - [ ] Offline/interrupted-network behaviour is understood and documented > **Known limitation:** Offline caching and the sales queue (Stage 14) are **not > implemented**. Network loss during a market sale is currently unrecoverable. > This must be stated in release notes for any field use. ### Exit criteria Business sign-off recorded, no open Critical/High defects, rollback plan agreed. --- ## 6. Production Environment **Purpose:** Live operator use against real customers and real money. ### Pre-flight - [ ] All Staging gates pass - [ ] Release committee approval recorded - [ ] Release notes drafted, including known limitations - [ ] Rollback plan documented and the previous artifact retained - [ ] Version bumped in both `pubspec.yaml` files - [ ] `AppServices.appVersion` and `MobileAppServices.appVersion` match `pubspec.yaml` - [ ] Release tagged in Git ### Credential and safety gates - [ ] Production WooCommerce credentials sourced from the secret store — **not** the repo - [ ] `KC_SQUARE_ENVIRONMENT=production` set deliberately - [ ] Square production token scoped to the minimum required permissions - [ ] Square location ID matches the intended physical location - [ ] A staging credential is confirmed absent from the production build - [ ] Credential redaction verified once more in the production artifact ### Build ```bash flutter build web --release --dart-define=KC_ENV=multi \ --dart-define=KC_WC_SITE_URL=https://store.kellcreations.com \ --dart-define=KC_WC_CONSUMER_KEY=$WC_KEY \ --dart-define=KC_WC_CONSUMER_SECRET=$WC_SECRET \ --dart-define=KC_SQUARE_ACCESS_TOKEN=$SQUARE_TOKEN \ --dart-define=KC_SQUARE_LOCATION_ID=$SQUARE_LOCATION \ --dart-define=KC_SQUARE_ENVIRONMENT=production ``` The Android release build uses the same defines with `flutter build appbundle --release`. ### Post-deployment verification - [ ] App loads and the environment badge is correct - [ ] A read-only operation succeeds (product list loads) - [ ] A single low-risk write succeeds and is confirmed in WooCommerce admin - [ ] Square sync runs once and mappings are correct - [ ] **One low-value real transaction** processed end-to-end and reconciled in Square - [ ] Bug reporting works from the production build - [ ] No `ERROR`/`FATAL` records during the verification pass ### Monitoring window - [ ] Observed for the first operating session - [ ] Bug report queue reviewed before sign-off - [ ] Operators briefed on "Report a problem" and known limitations ### Rollback triggers Roll back immediately on any of: - Incorrect pricing, inventory, or payment amounts - Duplicate product listings from a sync defect - Failed or double-charged payments - Credential leakage in any log or report - Any Critical defect without a workaround --- ## 7. Release Sign-Off Record | Field | Value | | ------------------ | ------------------- | | Release version | | | Git tag / commit | | | Target environment | | | Test result | \_\_ / 1475 passing | | Analyze result | | | Known limitations | | | Approver | | | Date | | --- ## 8. Open Release Blockers Carried from `PROJECT_STATE_AUDIT.md`. Each must be closed or explicitly accepted as a documented limitation before the affected environment is used in earnest. | ID | Item | Blocks | | ----- | ------------------------------------------------------------- | -------------------------- | | P2.5 | `WooCommerceOrdersRepository` not wired into `AppServices` | Test/QA orders workflow | | P2.6 | `WooCommerceInventoryRepository` not wired into `AppServices` | Test/QA inventory workflow | | P2.8 | Offline cache and sales queue not implemented (Stage 14) | Production field use | | P3.2 | `SecureCredentialStore` not implemented | Production | | P3.3 | Auth guard not wired into either shell | Production | | P3.1 | `RetryPolicy` / `RateLimiter` not wired into API clients | Staging, Production | | P3.6 | `feature_policy` has only a smoke test | Test/QA | | P2.10 | Policy register CSVs contain headers only | Governance compliance | > **Committee position:** With Stage 16A complete, the platform now has error > logging and bug reporting. It is **approved for Development and Test/QA**. > **Staging is conditionally approved** pending P3.1. **Production is not > approved** until P3.2, P3.3, and P2.8 are closed — the platform currently has > no authentication guard, no secure credential storage, and no offline > resilience for in-person sales.