kell_creations/docs/operations/release-checklist.md

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:

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

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

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

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

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.