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.