Kell Creations Operations Platform — Master Development Brief¶

Recommended repo location¶

Place this document in the repository at:

docs/development/master_development_brief.md

Why this location:

keeps it versioned with the code
makes it easy for Cline to read and update
separates implementation planning from feature code
works for both web and Android roadmap tracking

If docs/development/ does not exist yet, create it.

Purpose¶

This document is the master implementation brief for continuing development of the Kell Creations Flutter operations platform across web and Android. It is intended for use by Cline in Windows 11 VS Code.

This brief should be treated as the working source of truth for planned development after the current completed slices already landed on main.

Platform Vision¶

The Kell Creations platform is a multi-channel commerce operations system for managing an online product catalog, conducting in-person market sales via a mobile app, taking custom orders, and tracking supplies and inventory — all synchronized across WooCommerce (online storefront) and Square (point-of-sale and payments).

Core business workflows¶

Online Catalog Management — Create, edit, publish, and manage products on the WooCommerce store from both web and mobile.
Market Sales (Mobile POS) — Use the Android app at craft markets/shows to browse the catalog, process sales via Square, and capture customer information.
Custom Orders — Accept and track custom/made-to-order requests from both online and in-person channels, with specifications, deposits, and fulfillment tracking.
Supplies & Inventory — Track raw materials (supplies) and finished goods (inventory), with stock levels synchronized bidirectionally across WooCommerce and Square.
Multi-Channel Sync — Keep product catalog, inventory quantities, pricing, and order data consistent between WooCommerce and Square as the two sales channels.

Working model¶

Development must proceed in small, reviewable vertical slices.

Rules:

Branch from current main for each stage or sub-slice.
Implement on a feature branch.
Validate locally.
Open a PR into main.
Merge only after tests/analyze are clean.
Do not stack broad unfinished work directly on main.
After each merged slice, update this brief so it remains aligned to main.

Current confirmed baseline on `main`¶

Platform structure¶

apps/kell_web exists — active, wired to shared packages.
apps/kell_mobile exists — integrated with shared packages, mobile-optimized shell with bottom navigation, dashboard, and placeholder pages for all features.
Shared packages include:
core — shared domain/application abstractions and cross-platform composition pattern (KcAppConfig, KcAppServices, KcBootstrap, KcAppScope)
design_system — theme (KcColors, KcSpacing, KcTheme), typography (KcTypography), layout (KcBreakpoints), and 7 shared widgets (KcCard, KcStatusChip, KcEmptyState, KcSectionHeader, KcSummaryCard, KcLoadingState, KcErrorState)
feature_inventory — domain, application, data (fake), and presentation layers
feature_wordpress — domain, application, data (fake + WooCommerce), and presentation layers (most mature feature)
feature_orders — domain, application, data (fake), and presentation layers
feature_policy — domain, application, data (fake), and presentation layers
Scaffolded but empty stub packages (created, no implementation yet):
auth — ✅ authentication foundation activated (Stage 8C complete); KcUser/KcUserRole domain models, AuthState sealed hierarchy, AuthService contract, AuthException, CredentialStore/CredentialKeys contract, InMemoryCredentialStore, FakeAuthService implemented; KcAppEnvironment.square added to core
integrations — ✅ integration contracts activated (Stage 8A complete); ApiClient, ApiException, RetryPolicy, RateLimiter, IntegrationHealthCheck, WebhookHandler, ChannelAdapter contracts defined; WooCommerceApiClient and WooCommerceApiException refactored to implement shared contracts
data — ✅ shared data layer contracts activated (Stage 8B complete); LocalCache<T>, SyncQueue, ConflictResolver<T>, ChangeTracker<T>, DataMapper<TLocal, TRemote> contracts defined with in-memory implementations
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 contains CI helper scripts (run_all_tests.sh, collect_coverage.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.
Cross-feature navigation handoffs and shared filtering/search/selection persistence are implemented.
Runtime bootstrap uses:
KC_ENV
KC_WC_SITE_URL
KC_WC_CONSUMER_KEY
KC_WC_CONSUMER_SECRET
App supports FAKE and WP modes with visible shell badge.

Product publishing workflow already landed on `main`¶

Controlled WooCommerce publish action landed.
ProductDraft.copyWith landed.
unpublished -> draft UI exposure landed.
pendingReview -> draft UI exposure landed.
unpublished semantics clarified as a read-only abstraction.
Status action success/failure feedback landed.
Publishing page polish landed.
Richer read-side detail preview landed.
Price-only product edit landed.
Search/filter/sort refinement landed.
Name-only product edit landed.
✅ Description-only product edit landed (Stage 1A complete — merged feat/description-only-edit → main at cebac4c, 2026-04-11).
✅ Category-only product edit landed (Stage 1B complete — merged feat/category-only-edit → main at 8e7e4cb, 2026-04-11). Stage 1 complete.
✅ Post-write consistency hardening landed (Stage 2A complete — merged feat/post-write-consistency → main at 7acff83, 2026-04-11).
✅ Publishing workflow UX hardening landed (Stage 2B complete — merged feat/publishing-ux-hardening → main at b81016d, 2026-04-11). Stage 2 complete.
✅ Multi-select groundwork landed (Stage 3A complete — merged feat/multi-select-groundwork → main, 2026-05-22).
✅ 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).
✅ Test coverage visibility landed (Stage 4D complete — merged feat/test-coverage-visibility → main, 2026-05-22).
✅ Android app shell and bootstrap landed (Stage 5A complete — merged feat/android-app-shell → main, 2026-05-28).
✅ Android publishing surface landed (Stage 5B complete — merged feat/android-publishing-surface → main, 2026-05-29). Stage 5 complete.
✅ Android feedback and action polish landed (Stage 6A complete — merged feat/android-feedback-polish → main, 2026-05-29).
✅ Android mobile workflow hardening landed (Stage 6B complete — merged feat/android-mobile-ux-hardening → main, 2026-05-30).
✅ Bulk move-to-draft action landed (Stage 7A complete — merged feat/bulk-status-actions → main, 2026-05-30).
✅ Inventory domain expansion landed (Stage 5A-inv complete — merged feat/inventory-domain-expansion → main, 2026-07-10).
✅ Inventory page UI landed (Stage 5B-inv complete — merged feat/inventory-page-ui → main, 2026-07-10).
✅ Orders domain expansion landed (Stage 5C complete — merged feat/orders-domain → main, 2026-07-10).
✅ Orders page UI landed (Stage 5D complete — merged feat/orders-page-ui → main, 2026-07-10).
✅ Orders mobile surface landed (Stage 6B-orders complete — merged feat/orders-mobile-surface → main, 2026-07-10).
✅ Inventory mobile surface landed (Stage 6C complete — merged feat/inventory-mobile-surface → main, 2026-07-10). Stage 6 complete.
✅ Bulk publish and bulk submit-for-review actions landed (Stage 7B complete — merged feat/bulk-operator-workflows → main, 2026-07-11). Stage 7 complete.
✅ Integration abstractions activated (Stage 8A complete — merged feat/integrations-contracts → main, 2026-07-11).
✅ Shared data layer contracts activated (Stage 8B complete — merged feat/data-layer-contracts → main, 2026-07-11).
✅ Authentication foundation activated (Stage 8C complete — merged feat/auth-foundation → main, 2026-07-11). Stage 8 complete.
✅ Square API client and authentication activated (Stage 10A complete — merged feat/square-api-client → main, 2026-07-19).
✅ Square catalog and inventory sync mappers + ProductIdMapping domain landed (Stage 10B complete — merged feat/square-catalog-sync → main, 2026-07-25).
✅ SquareCatalogRepository and SquareInventoryRepository landed (Stage 10C complete — merged feat/square-catalog-sync-repositories → main, 2026-07-25).
✅ SquareSyncController, AppServices.square()/multi(), MobileAppServices.square()/multi(), ID conflation fix, and KcBootstrap credential validation landed (Stage 10E complete — branch feat/square-catalog-sync-service-controller ready for merge, 2026-07-25).
✅ SquareSyncStatusPanel, IntegrationsPage, MobileIntegrationsPage, and squareSyncController wired into both shells landed (Stage 10F complete — branch feat/square-sync-ui ready for merge, 2026-07-25).
✅ Square Mobile POS / Checkout landed (Stage 10C-POS complete — merged feat/square-mobile-pos → main, commit 7bf8f55, 2026-07-25).
✅ Platform observability activated (Stage 16A complete — merged feat/observability-error-logging → main, 2026-08-29). Structured logging (KcLogger, KcLogRecord, KcLogLevel), log sinks (KcConsoleLogSink, KcInMemoryLogSink, KcMultiLogSink), credential redaction (KcRedactor), global uncaught-error capture (KcErrorReporter), and operator bug reporting (KcBugReport, KcBugReportService, KcBugReportDialog) wired into both app shells.
✅ Custom order domain and data landed (Stage 11A complete — merged feat/custom-order-domain → main, commit 85501fd, 2026-08-29). OrderType, CustomOrderSpec, DepositInfo (integer cents), the FulfillmentStatus pipeline with domain-enforced transitions, and four new OrdersRepository methods across both implementations.
✅ Custom order intake UI landed (Stage 11B complete — merged feat/custom-order-ui → main, commit 6c299e8, 2026-09-25). CustomOrderFormController, CustomOrderFormPage, CustomOrderConfirmationPage, the /orders/custom web route, and MobileCustomOrderPage.
✅ Custom order tracking and fulfillment landed (Stage 11C complete — merged feat/custom-order-tracking → main, commit 07e7e08, 2026-09-25). FulfillmentEvent timeline, MaterialUsage + MaterialConsumptionPort, CustomOrderTrackingController, CustomOrderTrackingPage, FulfillmentTimeline, showAdvanceStageDialog, the /orders/tracking web route, MobileCustomOrderTrackingPage, and InventoryMaterialConsumptionAdapter in both composition layers. Stage 11 complete; audit finding P2.2 closed.

Current narrow edit capabilities on `main`¶

update product status through controlled workflow
update product price only
update product name only
update product description only
update product category only

Latest known validation state on `main`¶

Last verified: 2026-09-25 — Stage 11C validation run (feat/custom-order-tracking)

dart analyze --fatal-infos clean across all 11 packages/apps
All packages passing
latest reported count for core: 90/90 passed
latest reported count for design_system: 51/51 passed
latest reported count for feature_inventory: 167/167 passed
latest reported count for feature_orders: 1,085/1,085 passed ← +293 new (Stage 11C custom order tracking)
latest reported count for feature_wordpress: 545/545 passed
latest reported count for kell_web: 81/81 passed ← +14 new (custom order tracking route)
latest reported count for integrations: 123/123 passed
latest reported count for data: 63/63 passed
latest reported count for auth: 42/42 passed
latest reported count for kell_mobile: 109/109 passed ← +22 new (MobileCustomOrderTrackingPage, inventory adapter)
latest reported count for feature_policy: 17/17 passed (single smoke-test file)
total: 2,373/2,373 passed (+329 new from Stage 11C branch feat/custom-order-tracking)
main baseline updated through: feat/custom-order-tracking (Stage 11C complete, merged 2026-09-25, commit 07e7e08)
current branch work: none — Stage 11 complete; next slice not yet started
next branch: feat/inventory-write-ops (Stage 12A) — Inventory write operations and domain expansion

Note: The historically quoted total of 1,458 excluded feature_policy, which was not listed in the tracker's counted set. Including its 17 tests, the true grand total is 1,475. feature_policy coverage remains thin — all 17 tests live in one smoke-test file with no controller or widget tests. Expanding it is tracked as P3.6 and remains a Test/QA release blocker.

Baseline test coverage (established 2026-05-22)¶

Package	Tests	Lines Hit	Lines Found	Coverage
`core`	20	42	49	85.7%
`design_system`	41	88	88	100.0%
`feature_wordpress`	294	857	1012	84.7%
`kell_web`	24	191	353	54.1%
Total	379	1178	1502	78.4%

No minimum thresholds are enforced — this is visibility-only tracking. Coverage is measured via flutter test --coverage (generates lcov.info) and reported in the CI workflow summary table.

Stage 10D — complete (2026-07-25)¶

feat/square-catalog-sync-service — SquareCatalogSyncService + SquareSyncResult + SyncError + InventorySyncAdapter

Delivered:

SquareCatalogSyncService in feature_wordpress/lib/src/application/square_catalog_sync_service.dart
SyncError value object (itemId, message, ==/hashCode/toString())
SquareSyncResult value object (catalogSynced, inventorySynced, catalogFailed, inventoryFailed, errors, totalProcessed, allSucceeded, merge())
InventorySyncAdapter abstract contract (syncItem(itemId, remoteQuantity) → Future<bool>)
syncCatalog() — fetches products via ProductPublishingRepository, reconciles ProductIdMappingRepository, per-item error capture
syncInventory() — iterates mappings with squareVariationId, delegates to InventorySyncAdapter, per-item error capture
syncAll() — runs catalog then inventory, merges results
Exported from feature_wordpress.dart barrel
31 new tests (506/506 feature_wordpress total, 167/167 feature_inventory — all passing, analyze clean)

Stage 10E — complete (2026-07-25)¶

feat/square-catalog-sync-service-controller — SquareSyncController + AppServices.square()/multi() + ID conflation fix + KcBootstrap credential validation

Delivered:

SquareSyncController ChangeNotifier in feature_wordpress/lib/src/application/square_sync_controller.dart
AppServices.square() and AppServices.multi() factory constructors (P1.1)
MobileAppServices.square() and MobileAppServices.multi() factory constructors (P1.1)
KcBootstrap Square credential validation with fallback to fake mode (P1.5)
ProductDraft.squareCatalogObjectId nullable field; ID conflation bug fixed in syncCatalog() (P1.2)
18 new SquareSyncController tests + 10 new composition tests per app (834 total across tested packages)
Analyze clean

Stage 10F — complete (2026-07-25)¶

feat/square-sync-ui — SquareSyncStatusPanel + IntegrationsPage + MobileIntegrationsPage

Delivered:

SquareSyncStatusPanel StatefulWidget in feature_wordpress/lib/src/presentation/widgets/square_sync_status_panel.dart
IntegrationsPage in kell_web/lib/pages/integrations_page.dart — shows panel when squareSyncController is non-null, placeholder otherwise
MobileIntegrationsPage in kell_mobile/lib/pages/mobile_integrations_page.dart — mirrors web layout for mobile
AppRoute.integrations wired in kell_web routing
More tab in kell_mobile shell switched from placeholder to MobileIntegrationsPage
8 new panel tests + 4 integrations page tests per app + 5 composition tests per app (651 total across tested packages)
Analyze clean

Stage 10C — complete (2026-07-25)¶

feat/square-mobile-pos — Square Mobile POS / Checkout

Delivered:

PaymentMethod enum (cash, card) with label and iconHint extensions in feature_orders
PaymentResult immutable value object (transactionId, amountCents, method, completedAt, receiptUrl, amountFormatted) in feature_orders
PaymentService abstract contract + PaymentException in feature_orders
CheckoutController (ChangeNotifier) with sealed CheckoutState hierarchy (idle/processing/success/error) and CartEntry in feature_orders
FakePaymentService (always succeeds, counter-based IDs) in feature_orders
MobileCheckoutPage — product selection → cart → payment → receipt flow; Cash + Card buttons; confirmation dialog; haptic feedback in kell_mobile
Sales tab (index 4) added to MobileShell bottom navigation (6 tabs total)
paymentService + checkoutCatalogue fields wired into all MobileAppServices factory constructors
45 new tests (36 feature_orders + 18 kell_mobile − 9 pre-existing kell_mobile); 1373 total across all packages
Analyze clean

Stage 16A — complete (2026-08-29)¶

feat/observability-error-logging — Error logging, crash capture, and bug reporting

Closes audit findings P3.4 (structured logging), P3.5 (crash reporting), and the "No logging infrastructure" / "No crash reporting" architectural risks.

Delivered in core:

KcLogLevel — five ordered severities (debug, info, warning, error, fatal) with threshold comparison
KcLogRecord — immutable structured record with format(), toJson(), and isFailure
KcRedactor — credential redaction applied to every logged context map, traversing nested maps and lists
KcLogSink contract with KcConsoleLogSink (release-silent by default), KcInMemoryLogSink (bounded ring buffer), and KcMultiLogSink (fault-tolerant fan-out)
KcLogger — the logging facade; drops sub-threshold records, redacts context, and never throws
KcErrorReporter — installs FlutterError.onError, PlatformDispatcher.instance.onError, and a guarded zone around runApp
KcBugReport / KcBugSeverity — the bug report model with redacted diagnostics, toJson(), and toMarkdown()
KcBugReportSink contract + KcInMemoryBugReportSink
KcBugReportService — validates input, attaches the recent log tail as evidence, and degrades gracefully when the tracker is unreachable
KcObservability — assembles logger, evidence buffer, and bug report service so they always share one buffer

Delivered in design_system:

KcBugReportDialog + KcBugReportDraft — the shared operator reporting form with inline validation and a stated no-credentials guarantee

Wired into both app targets:

KcObservability held by AppServices and MobileAppServices; every factory stamps its environment label (FAKE, WP, SQ, MULTI)
KcErrorReporter.install(...) + runGuarded(...) in both main.dart entry points, with a startup record capturing the effective environment and any fake-mode fallback
"Report a problem" action in the AppShell app bar and the MobileShell app bar, capturing the active screen

Validation:

85 new tests (56 core, 10 design_system, 10 kell_web, 9 kell_mobile); 1,475 total
dart analyze --fatal-infos clean across all packages and apps

Stage 11A — complete (2026-08-29)¶

feat/custom-order-domain — Custom order domain and data

Closes audit finding P2.2 (domain and data layers only — the custom order UI remains open as Stage 11B/11C) and P3.8 (feature_orders scaffolding files).

Delivered in feature_orders — domain:

OrderType — standard / custom with label, wireValue, and a fromWire() parser that defaults to standard so orders written by an older client are never mis-classified as commissions
CustomOrderSpec — immutable value object (material, color, size, dimensions, reference image URLs, notes, estimated completion) with copyWith, ==/hashCode (list-aware), toString, plus isProductionReady, hasReferenceImages, and summary
DepositInfo — immutable value object; all money as integer cents, consistent with PaymentResult.amountCents. Deposit and total amounts, deposit/settlement dates, paid flag, derived balanceDueCents (clamped at zero), markDepositPaid(), markSettled(), formatCents()
FulfillmentStatus — the workshop pipeline quoted → depositReceived → inProduction → qualityCheck → readyForPickup → completed, plus cancelled from any non-terminal stage and a qualityCheck → inProduction rework path
FulfillmentTransition extension — allowedNextStatuses, canTransitionTo(), and rejectionReason(). Illegal jumps are rejected by the domain, not silently applied; same-stage advances and any move out of a terminal stage are rejected
Order extended with orderType, nullable customOrderSpec, nullable depositInfo, and nullable fulfillmentStatus, plus isCustom, hasDeposit, and balanceDueCents. Every existing field, default, and copyWith semantic is preserved — orderType defaults to standard
OrdersRepository extended with createCustomOrder(), updateCustomOrderSpec(), recordDeposit(), and advanceFulfillmentStatus()

Delivered in feature_orders — data:

FakeOrdersRepository — all four methods implemented, plus five seeded custom orders (KC-C2001…KC-C2005) covering every non-terminal pipeline stage; the six standard orders are unchanged
WooCommerceOrdersRepository — all four methods implemented. Custom order state round-trips through _kc_-prefixed order meta_data; the complete key table is documented on WooCommerceOrderMapper
WooCommerceOrderMapper — reads and writes the custom order meta set, keeping internal _-prefixed keys out of Order.customFields
WooCommerceApiClient.updateOrder() — new generic order PUT in feature_wordpress, mirroring updateProduct(), so meta can be written back without disturbing an order's commercial fields

Observability (Stage 16A layer):

Both repositories accept an injected KcLogger, defaulting to KcLogger.silent(). Domain rejections log at warning; API failures log at error with the status code and the originating exception
No silent catch (_) {} blocks — every swallowed error produces both a log record and a failure result
Log context is restricted to identifiers, operation names, and status names. Customer identity, addresses, money amounts, and payment identifiers are never logged; KcLogger additionally routes all context through KcRedactor
The deposit payment/transaction identifier is deliberately absent from DepositInfo and from the WooCommerce meta mapping — it lives on PaymentResult alone, because order meta is readable by any store admin

Also closed:

P3.8 — .metadata, CHANGELOG.md, LICENSE, and README.md added to feature_orders so it matches every other package (.gitignore already existed). The README documents the pipeline, the meta mapping, and the privacy rules

Validation:

423 new tests in feature_orders (234 → 657): every value object, the full 7 × 7 legal/illegal transition matrix, and every new repository method on both implementations
1,898 total across all packages; no regression from the 1,475 baseline
dart analyze --fatal-infos clean across all 11 packages and apps

Stage 11B — complete (2026-09-25)¶

feat/custom-order-ui — Custom order creation UI

Closes the UI half of audit finding P2.2. Application and presentation layers plus app wiring only — no domain or data change; every repository contract delivered in Stage 11A is consumed as-is.

Delivered in feature_orders — application:

CreateCustomOrder and RecordDeposit use cases. RecordDeposit accepts no payment identifier, matching the repository contract
CustomOrderFormController (ChangeNotifier) — field state, field-keyed validation via the CustomOrderField enum, buildSpec(), submit(), reset(), and derived estimatedPriceCents / depositAmountCents / balanceDueCents (clamped at zero). The clock and the ID generator are injectable so tests are deterministic
CustomOrderFormController.parseMoneyToCents() — typed money ('$1,299.5') becomes integer cents before it reaches the domain. No double arithmetic ever decides a price

Delivered in feature_orders — presentation:

CustomOrderFormPage — customer capture, description, spec fields, reference images, pricing with a live balance, deposit collection with a method selector, estimated completion picker, and intake source. Owns a controller unless one is injected, and swaps to the confirmation page on success
CustomOrderConfirmationPage — commission summary plus a deposit receipt showing amount, method, date, and balance. No payment identifier appears on screen; that stays on PaymentResult
FulfillmentStatusChip over the design-system KcStatusChip, and showReferenceImageDialog() with URL validation
OrdersPage gains an optional onCreateCustomOrder callback; the action is omitted entirely when the host has no intake route

Wired into both app targets:

kell_web — new /orders/custom route inside AppShell, plus AppNavigation.ordersToCustomOrder() / customOrderToOrders() handoffs
kell_mobile — MobileCustomOrderPage hosts the shared form in a SafeArea; MobileOrdersPage pushes it from an extended FAB and reloads on return

Validation:

146 new tests (135 feature_orders, 6 kell_mobile, 5 kell_web); 2,044 total across all packages
dart analyze --fatal-infos clean across all 11 packages and apps

Deferred to Stage 11C: product-base selection from the catalogue is not offered — intake is free-text description only, which is what market capture actually needs. Reference images are captured as URLs to already-uploaded media; the platform camera and file pickers land with the media pipeline.

Stage 11C — complete (2026-09-25)¶

feat/custom-order-tracking — Custom order tracking and fulfillment

Closes audit finding P2.2 entirely. Stage 11 is now complete.

Delivered in feature_orders — domain:

FulfillmentEvent — an append-only record of every accepted transition (stage from, stage to, timestamp, optional operator note). Its wire format strips separators and newlines out of notes, and fromWire() skips a malformed line rather than discarding a whole timeline — order meta is editable by any store administrator
MaterialUsage — what a commission consumes, as SKU and quantity
MaterialConsumptionPort + MaterialDeductionResult — the outbound port for stock deduction, with per-SKU failures so one short count cannot discard the other deductions
Order gained fulfillmentHistory, materialUsage, and the derived currentStage / allowedNextStages / isFulfillmentComplete / deductibleMaterials, plus the append-only withFulfillmentEvent(). Every existing field, default, and copyWith semantic is preserved

Delivered in feature_orders — data:

advanceFulfillmentStatus() now records an event, with an optional operator note and an injectable clock; recordMaterialUsage() added
Both repositories implement the widened contract; WooCommerce round-trips the timeline and materials through two further _kc_ meta keys
All five seeded commissions carry realistic histories — KC-C2004 includes a rework loop, so the timeline surface has a backwards transition to render

Delivered in feature_orders — application and presentation:

AdvanceFulfillment, CompleteCustomOrder, CustomOrderTrackingController
CustomOrderTrackingPage, CustomOrderTrackingCard, CustomOrderTrackingDetail, FulfillmentTimeline, showAdvanceStageDialog
OrdersPage gains an optional onTrackCustomOrders action

Wired into both app targets:

kell_web — /orders/tracking route plus AppNavigation.ordersToCustomOrderTracking()
kell_mobile — MobileCustomOrderTrackingPage behind a tracking FAB
Both — InventoryMaterialConsumptionAdapter in the composition layer

Two decisions worth recording:

Inventory deduction goes through a port, not a dependency. feature_orders and feature_inventory are siblings; a direct dependency would couple the custom order pipeline to a stock implementation. The orders layer declares MaterialConsumptionPort and each app supplies the adapter.
Completion advances first, deducts second. Deducting first would decrement stock for a completion the domain then rejected. A deduction failure yields a warning, never a failed commission — an operator handing over finished work must not be blocked by a stock discrepancy.

Validation:

329 new tests (293 feature_orders, 22 kell_mobile, 14 kell_web); 2,373 total across all packages
dart analyze --fatal-infos clean across all 11 packages and apps

Next recommended branch¶

feat/inventory-write-ops — Stage 12A: Inventory write operations and domain expansion

ItemType enum and an expanded InventoryItem (reorder point, supplier, cost per unit, location, last count date)
InventoryAdjustment value object and the adjustment history it implies
InventoryRepository write operations: addItem(), updateItem(), getAdjustmentHistory(), getLowStockItems(), getItemsByType()
InventoryController mirroring the ProductPublishingController pattern
Tests for the new domain models, repository methods, and controller

Note: Stage 11C's InventoryMaterialConsumptionAdapter already calls adjustQuantity() with a custom-order reason string. Stage 12A's adjustment history should capture those calls, giving the workshop an audit trail of which commission consumed which material.

Comprehensive State Audit (2026-07-25)¶

Audit reference: PROJECT_STATE_AUDIT.md — Kell Creations Operations Platform Comprehensive Code Audit
Audit date: 2026-07-25
Baseline: Stage 10C complete (feat/square-catalog-sync-repositories → main)
Total tests verified: 1,015 / 1,015 passing; dart analyze --fatal-infos clean across all 11 packages/apps

Platform scorecard (as of 2026-07-25)¶

Subsystem	Status	Completeness	Blocking Issues
`core`	✅ COMPLETE	95%	Square/multi bootstrap validation missing
`design_system`	✅ COMPLETE	100%	None
`auth`	⚠️ PARTIAL	40%	No production impl, not wired into app
`data`	⚠️ PARTIAL	35%	No SQLite impl, not wired into any feature
`integrations`	⚠️ PARTIAL	70%	RetryPolicy/RateLimiter not wired; ChannelAdapter not implemented
`feature_wordpress`	✅ COMPLETE	95%	SquareSyncController (Stage 10E) pending
`feature_inventory`	⚠️ PARTIAL	65%	No unified sync engine; ItemType/Supplier/PurchaseOrder missing
`feature_orders`	⚠️ PARTIAL	70%	Custom orders missing; WC/Square repos not wired into AppServices
`feature_policy`	⚠️ PARTIAL	50%	Fake-only; minimal tests; policy register empty
`feature_finance`	❌ MISSING	0%	Pure stub
`feature_mrp`	❌ MISSING	0%	Pure stub
`feature_social`	❌ MISSING	0%	Pure stub
`kell_web`	⚠️ PARTIAL	75%	Finance/Integrations placeholder; no square/multi factory
`kell_mobile`	⚠️ PARTIAL	70%	No POS/checkout; no square/multi factory
Architecture docs	⚠️ PARTIAL	80%	Square not represented; multi-channel model missing
Policy register	❌ MISSING	10%	All CSVs empty
CI/CD	✅ COMPLETE	85%	No coverage thresholds enforced

Audit engineering backlog¶

The full backlog is captured in PROJECT_STATE_AUDIT.md §4. The prioritized summary follows.

Phase 1 — High-priority / blocking (core fixes and missing execution paths)¶

These items block correct runtime behavior or represent data integrity risks. All Phase 1 items should be addressed in feat/square-catalog-sync-service-controller (Stage 10E) or immediately after.

ID	Item	Branch
P1.1	Wire `square` and `multi` factory constructors into `AppServices`/`MobileAppServices`	`feat/square-catalog-sync-service-controller`
P1.2	Fix `SquareCatalogSyncService.syncCatalog()` ID conflation (`product.id` vs Square ID)	`feat/square-catalog-sync-service-controller`
P1.3	Merge Stage 10D (`feat/square-catalog-sync-service`) → `main`	Immediate — prerequisite for Stage 10E
P1.4	`SquareSyncController` (Stage 10E) — UI trigger for `SquareCatalogSyncService`	`feat/square-catalog-sync-service-controller`
P1.5	Add `hasSquareConfig` credential check in `KcBootstrap` for `square`/`multi` modes	`feat/square-catalog-sync-service-controller`

Phase 2 — Feature completion and integration¶

These items complete planned stages and wire existing contracts into production paths.

ID	Item	Target Stage
P2.1	Square Mobile POS / Checkout (`MobileCheckoutPage`, Square Reader SDK)	Stage 10C
P2.2	~~Custom Orders Workflow~~ - DONE: domain + data (11A), intake UI (11B), tracking (11C)	Complete
P2.3	Inventory Write Ops & Supplies Tracking (`ItemType`, `Supplier`, `PurchaseOrder`)	Stage 12A/B
P2.4	Multi-Channel Inventory Sync Engine (`InventorySyncEngine`, `ChannelStockMapping`)	Stage 12C
P2.5	Wire `WooCommerceOrdersRepository` into `AppServices.wordpress()`	Stage 10E or standalone
P2.6	Wire `WooCommerceInventoryRepository` into `AppServices.wordpress()`	Stage 10E or standalone
P2.7	Unified Order View (`OrderChannel`, `UnifiedOrdersController`)	Stage 13B
P2.8	Offline Data Cache & Sales Queue (SQLite `LocalCache`, `SyncQueue`)	Stage 14
P2.9	`feature_finance` Activation (sales reporting, inventory valuation)	Stage 15
P2.10	Populate Policy Register CSVs (2 active governance documents)	Immediate — no dependencies

Phase 3 — Defensive engineering, logging, and test harness expansion¶

These items harden the platform for production deployment.

ID	Item	Target Stage
P3.1	Wire `RetryPolicy` and `RateLimiter` into `SquareApiClient` and `WooCommerceApiClient`	Stage 16C
P3.2	Implement `SecureCredentialStore` (`flutter_secure_storage`)	Stage 16B
P3.3	Auth guard wired into app shell (login screen, route guard)	Stage 16B
P3.4	~~Structured logging infrastructure~~ - DONE: `KcLogger` (Stage 16A)	Complete
P3.5	~~Crash reporting integration~~ - DONE: `KcErrorReporter` (Stage 16A)	Complete
P3.6	Expand `feature_policy` test coverage (controller, widget tests; target >80%)	Standalone
P3.7	Expand `kell_web` test coverage from 54.1% (routing, shell, factory tests; target >75%)	Standalone
P3.8	~~Add `feature_orders` standard scaffolding files~~ - DONE (Stage 11A)	Complete
P3.9	Update architecture diagrams for Square and multi-channel	Stage 13 planning
P3.10	Implement `ChannelAdapter` for WooCommerce and Square	Stage 13A
P3.11	Enforce minimum test coverage thresholds in CI (e.g., 75% floor)	Standalone
P3.12	Evaluate and activate `feature_mrp` after Stage 12 completion	Post-Stage 12

Key technical debt findings¶

~~AppServices/MobileAppServices have no square() or multi() factory~~ — ✅ RESOLVED in Stage 10E; both factories exist and KcBootstrap validates Square credentials
~~SquareCatalogSyncService ID conflation~~ — ✅ RESOLVED in Stage 10E; syncCatalog() now reads draft.squareCatalogObjectId
~~No logging infrastructure~~ — ✅ RESOLVED in Stage 16A; KcLogger with structured records and credential redaction
~~No crash reporting~~ — ✅ RESOLVED in Stage 16A; KcErrorReporter captures framework, platform, and zone errors
RetryPolicy/RateLimiter defined but not wired — all API calls are single-attempt with no retry or rate limiting (HIGH)
auth package not imported by any app or feature — app is completely unguarded (HIGH)
No remote log or crash sink — diagnostics are in-process only and lost on restart; unavailable off-device (HIGH)
data package not imported by any feature — all data is in-memory only; no persistence path (MEDIUM)
InventoryController not wired to InventorySyncService — sync cannot be triggered from UI (MEDIUM)
feature_policy has only a smoke test — 17 tests in one file; no controller or widget tests (MEDIUM)
kell_web at 54.1% line coverage — routing, shell, and navigation largely untested (MEDIUM)
No dependency injection / state management framework — ChangeNotifier + direct construction will strain as the sync engine and offline queue land (MEDIUM)

Senior Audit Report (2026-05-30)¶

Audit scope¶

Full structural, feature, and build plan review conducted against the target platform vision: multi-channel commerce operations with online catalog management, mobile market sales, custom orders, supplies/inventory tracking, and WooCommerce + Square integration.

Audit summary — strengths¶

Area	Assessment
Architecture	Excellent C4 coverage (19 diagrams), clean package boundaries, well-documented composition pattern. The monorepo structure with shared domain/application layers is sound and extensible.
Code quality	393 tests across 5 packages, 78.4% line coverage, `dart analyze` clean. Strict vertical-slice discipline with thorough PR tracking.
WooCommerce integration	Production-ready product publishing via REST API v3. Clean `WooCommerceApiClient` abstraction with Basic Auth, pagination, and error handling.
Cross-platform	Shared composition pattern (`KcAppServices`, `KcBootstrap`, `KcAppScope`) enables both web and mobile to reuse identical business logic. Zero logic forking for Android.
Design system	Foundation-ready with 7 shared widgets, typography, breakpoints, and 100% test coverage.
CI/CD	Forgejo Actions for analyze + test with per-package coverage reporting.
Mobile app	Android shell with 5-tab navigation, mobile-optimized publishing surface, haptic feedback, confirmation dialogs.

Audit summary — critical gaps for target vision¶

Gap 1: No product creation capability¶

The platform can only edit existing WooCommerce products. There is no workflow to create new products — neither in the domain model, repository contract, nor UI. The ProductPublishingRepository has no createProduct() method. This is a blocker for online catalog management.

Impact: Cannot manage a catalog without the ability to add products.

Gap 2: No image/media management¶

The ProductDraft model has an imageUrl field but it is read-only. No upload, selection, or gallery management exists. The WooCommerceApiClient has no media endpoints. Product images cannot be added or changed.

Impact: Catalog products without images have severely reduced sales conversion.

Gap 3: Orders are read-only with fake data¶

The OrdersRepository contract has only getOrders(). There is no createOrder(), updateOrderStatus(), or any write operation. The Order domain model lacks custom order fields (notes, customizations, deposit tracking). The repository has no real backend — only FakeOrdersRepository.

Impact: Cannot take custom orders or sync orders from WooCommerce.

Gap 4: Inventory is read-only with fake data¶

The InventoryRepository contract has only getInventoryItems(). No write operations (adjust quantity, add item, record usage). No concept of raw materials vs. finished goods. No real backend. No WooCommerce stock sync.

Impact: Cannot track supplies or update inventory levels. No stock accuracy across channels.

Gap 5: Square integration is completely absent¶

No Square API client, no Square SDK references, no Square-related domain models, no payment processing, no POS capability. The integrations package is an empty stub containing only a placeholder Calculator class.

Impact: Cannot process payments at markets. Cannot sync catalog or inventory with Square.

Gap 6: No multi-channel sync engine¶

No mechanism to synchronize products, inventory, or orders between WooCommerce and Square. No unified product ID mapping, no conflict resolution strategy, no webhook handling for external change detection.

Impact: Running two sales channels without sync leads to overselling and data inconsistency.

Gap 7: No authentication¶

The auth package is a stub. All access is uncontrolled. No user identity, no role-based access, no secure credential storage beyond --dart-define.

Impact: Cannot deploy to multiple users or secure API credentials on-device.

Gap 8: No offline capability¶

The mobile app requires network connectivity for all operations. Markets frequently have poor or no cellular coverage. No local data caching, no offline queue, no sync-on-reconnect.

Impact: Mobile app is unusable at markets without reliable network.

Gap 9: WooCommerce integration is products-only¶

The WooCommerceApiClient supports only the Products endpoint (GET /products, PUT /products/{id}). Missing: Orders API, Customers API, Categories API (CRUD), Product Images/Media API, Stock/Inventory API, Webhooks, Coupons.

Impact: Cannot pull orders from the online store or sync inventory levels with WooCommerce.

Gap 10: No financial/reporting capability¶

feature_finance is a stub. No sales reports, inventory valuation, cost tracking, or revenue analytics. No data aggregation from orders across channels.

Impact: No business intelligence for decision-making.

Audit recommendations¶

The gaps above are addressed in the revised development roadmap below (Stages 8–16). The roadmap is ordered to deliver the highest-value capabilities first while respecting architectural dependencies.

Non-negotiable architectural constraints¶

These must be preserved in all future work:

Preserve strict package boundaries.
Fake repositories remain in feature packages.
Real integrations are incremental alongside fake ones.
Runtime selection stays via --dart-define, not a settings UI.
No credentials hardcoded or committed.
Do not broaden into generic product editing prematurely.
Keep WooCommerce details inside the WP repository layer.
Keep Square details inside a dedicated Square integration layer.
Keep diffs small and reviewable.
Prefer inspection-first development.
Android support should reuse shared feature/domain/application layers rather than fork logic.
Multi-channel sync must be abstraction-first: define channel-agnostic contracts before platform-specific implementations.

Toolchain baseline¶

Last verified: 2026-09-25 — chore/state-reconciliation-flutter-347

Tool	Version
Flutter	3.47.0 (stable, revision `4cf2416426`)
Dart	3.13.0
SDK constraint in every `pubspec.yaml`	`^3.11.0`

Known toolchain caveat — `analysis_options.yaml` is tool-managed¶

Flutter 3.47 ships AnalysisOptionsMigration, which unconditionally rewrites every analysis_options.yaml in the workspace to contain:

analyzer:
  exclude:
    - build/**
    - android/**
    - ios/**
    - web/**
    - windows/**
    - macos/**
    - linux/**

The list is a hardcoded constant — it is not derived from the platforms a project actually has. The migration runs from ensureReadyForPlatformSpecificTooling, so flutter pub get, flutter analyze, flutter run, and flutter build all restore it. There is no opt-out. Upstream: flutter#191160, flutter#191131.

Rule for all future slices: treat this block as generated content and leave it in place. Do not open a slice to strip it — an earlier attempt (92d83e0) was undone by the very next flutter command and only produced a permanently dirty working tree. If a diff shows only this block appearing, commit it or ignore it; it is never a real change.

Caveat to re-check if the repo layout changes: the web/** entry will silently drop real Dart sources from analysis in any package that uses web/ as a source directory (as dart create -t web does). This is safe today because neither kell_web/web/ nor kell_mobile/web/ contains .dart files — they are pure browser-asset scaffolds. Re-verify this if a Dart web package is ever added.

Development stages¶

Stage 1 — Web application completion: controlled product editing¶

Objective¶

Extend the publishing workflow with additional single-field edit capabilities using the same narrow pattern already established by price-only and name-only update.

Branching model¶

Use one branch per edit slice:

feat/description-only-edit
feat/category-only-edit

Stage 1A — Description-only product edit ✅ COMPLETE¶

Merged feat/description-only-edit → main at cebac4c (2026-04-11). All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline description edit UI, and targeted tests (212 total feature_wordpress tests passing).

Stage 1B — Category-only product edit ✅ COMPLETE¶

Merged feat/category-only-edit → main at 8e7e4cb (2026-04-11). All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline category edit UI, snack bar feedback, and targeted tests (223 total feature_wordpress tests passing). Stage 1 complete.

Stage 2 — Web application operational hardening¶

Objective¶

Improve operator consistency, predictability, and usability after writes.

Branches¶

feat/post-write-consistency
feat/publishing-ux-hardening

Stage 2A — Post-write consistency hardening ✅ COMPLETE¶

Merged feat/post-write-consistency → main at 7acff83 (2026-04-11). Added _refreshSelection() to ProductPublishingController to preserve/refresh selection after all write-triggered reloads. 11 new post-write consistency tests added (234 total feature_wordpress tests passing).

Stage 2B — Publishing workflow UX hardening ✅ COMPLETE¶

Merged feat/publishing-ux-hardening → main at b81016d (2026-04-11). Added inline validation error messages for all four single-field edits (name, price, description, category), disabled text fields and save buttons during isUpdating, and appended error detail to failure snack bars. 13 new tests added (247 total feature_wordpress tests passing). Stage 2 complete.

Stage 3 — Web application operator efficiency¶

Objective¶

Increase throughput for product triage and management using existing data.

Branches¶

feat/multi-select-groundwork
feat/list-efficiency-improvements

Stage 3A — Multi-select groundwork (read/state only first) ✅ COMPLETE¶

Merged feat/multi-select-groundwork → main (2026-05-22). Added multi-selection state to ProductPublishingController (toggleMultiSelect, clearMultiSelection, selectAllVisible, isMultiSelected, multiSelectedIds, multiSelectedCount). Updated ProductDraftCard with optional leading checkbox for multi-select mode. Added _MultiSelectBar to ProductPublishingPage with selected-count display, Select All, and Clear actions. Single-item preview selection preserved independently. 15 new multi-select tests added (262 total feature_wordpress tests passing). No bulk writes introduced.

Stage 3B — List efficiency improvements ✅ COMPLETE¶

Merged feat/list-efficiency-improvements → main (2026-05-22). Added compact/standard view toggle (ListDensity enum), staleness detection (isStale(), staleCount() with 30-day threshold), keyboard navigation (selectNextDraft/selectPreviousDraft with wrapping), description snippet in standard card, and stale indicator icon. Updated ProductDraftCard with compact two-row layout variant and Flexible overflow handling. Page wires up Focus+onKeyEvent for arrow keys and density toggle button. 32 new tests added (294 total feature_wordpress tests passing). Stage 3 complete.

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

Merged feat/design-system-shared-widgets → main (2026-05-22). Migrated EmptyStatePanel, SectionHeader, and SummaryCard from kell_web/lib/shell/widgets/ into design_system as KcEmptyState, KcSectionHeader, and KcSummaryCard. Added KcTypography shared typography scale, KcBreakpoints responsive layout breakpoint utilities, KcLoadingState and KcErrorState shared state widgets. Updated kell_web dashboard to use design_system widgets directly; shell widget files now contain backward-compatible typedefs. Theme updated to use KcTypography.applyKcTypography(). 41 new design_system tests added (41 total design_system tests, 294 feature_wordpress tests, 24 kell_web tests — all passing). Analyze clean.

Stage 4B — Cross-platform shell composition strategy ✅ COMPLETE¶

Merged feat/shared-composition-pattern → main at 0a0abc2 (2026-05-22). Extracted shared composition abstractions into core package: KcAppConfig, KcAppEnvironment, KcAppServices (abstract), KcServiceFactory<T>, KcBootstrap, KcAppScope<T>. Updated kell_web to delegate to shared types via backward-compatible typedefs (AppConfig, AppEnvironment, AppServices, AppScope, Bootstrap). Contract for new app targets documented in kell_creations_apps/docs/composition-strategy.md. kell_web runtime behavior unchanged. 20 core tests added covering all composition abstractions (20/20 core, 41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web — all passing). Analyze clean.

Stage 4C — Flutter CI/CD pipeline ✅ COMPLETE¶

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 ✅ COMPLETE¶

Merged feat/test-coverage-visibility → main (2026-05-22). Enhanced flutter-test.yml CI workflow to run flutter test --coverage and parse lcov.info files, producing an aggregate summary table with per-package pass/fail counts and line coverage percentages. Added collect_coverage.sh local coverage helper script and updated tools/README.md. Established baseline coverage: core 85.7% (42/49), design_system 100.0% (88/88), feature_wordpress 84.7% (857/1012), kell_web 54.1% (191/353) — overall 78.4% (1178/1502). No minimum thresholds enforced — visibility first. All 379 tests passing. Analyze clean. Stage 4 complete.

Stage 5 — Android application foundation¶

Objective¶

Bring the current operations platform capabilities to Android using shared packages first and platform-specific UI only where required.

Key principle¶

Business logic, domain logic, repositories, and feature application logic should remain shared. Android should primarily add a dedicated app shell and mobile-optimized presentation.

Branches¶

feat/android-app-shell
feat/android-publishing-surface

Stage 5A — Android app shell and bootstrap ✅ COMPLETE¶

Merged feat/android-app-shell → main (2026-05-28). Replaced the default Flutter counter template with a fully integrated mobile app shell. Created MobileAppServices extending KcAppServices with shared composition pattern, KellMobileApp with KcAppScope<MobileAppServices> and KcBootstrap, MobileShell with 5-tab NavigationBar (Dashboard, Inventory, Orders, Publishing, More). Dashboard reuses shared DashboardSummary/DashboardController with mobile-optimized GridView layout and design system widgets. Placeholder pages for Finance, Integrations, and feature tab content. pubspec.yaml references all shared packages (core, design_system, feature_inventory, feature_orders, feature_policy, feature_wordpress). Environment badge shows runtime mode. SDK constraint corrected to ^3.11.0 across all 14 pubspec files. 6 new kell_mobile widget tests added (6/6 kell_mobile, 24/24 kell_web, 294/294 feature_wordpress — all passing).

Stage 5B — Android publishing surface ✅ COMPLETE¶

Merged feat/android-publishing-surface → main (2026-05-29). Created mobile-optimized publishing workspace: MobilePublishingPage with search bar, horizontal filter chips, sort dropdown with ascending/descending toggle, product count display, compact card list with pull-to-refresh, and push navigation to detail page. MobileProductDetailPage wraps the shared ProductPreviewPanel with all narrow edit callbacks (status, price, name, description, category). Products tab in MobileShell switched from web ProductPublishingPage to MobilePublishingPage. Expanded feature_wordpress barrel exports for mobile consumption (ProductPublishingController, ProductSortField, ProductDraftCard, ProductPreviewPanel, all 5 use cases, snack bar helpers). Zero business logic forked — all shared layers reused. 4 new mobile publishing surface tests added (10 total kell_mobile tests passing). Analyze clean. Stage 5 complete.

Stage 6 — Android operational maturity¶

Objective¶

Harden Android UX after the core feature surface works.

Branches¶

feat/android-feedback-polish
feat/android-mobile-ux-hardening

Stage 6A — Android feedback and action polish ✅ COMPLETE¶

Merged feat/android-feedback-polish → main (2026-05-29). Converted MobileProductDetailPage to StatefulWidget with its own controller listener for local SnackBar feedback. Added confirmation dialogs for publish/move-to-draft status changes. Added haptic feedback (mediumImpact for status, lightImpact for field edits) on successful actions. Guarded list page SnackBars with _detailPageActive flag to prevent invisible behind-route feedback. 4 new tests added (14 total kell_mobile tests passing).

Stage 6B — Android mobile workflow hardening ✅ COMPLETE¶

Merged feat/android-mobile-ux-hardening → main (2026-05-30). Restored Material Design 48×48dp minimum touch targets on 12 IconButtons in ProductPreviewPanel by removing constraints: BoxConstraints() and padding: EdgeInsets.zero overrides. Replaced fixed-width SizedBox(width: 80) on price edit TextField with Expanded for flexible layout on narrow mobile screens. Added tooltip: 'Edit price' for consistency. Wrapped ProductPreviewPanel in SafeArea in MobileProductDetailPage to prevent content clipping under system UI on devices with notches/gesture bars. 6 new touch target rendered-size tests added (300 total feature_wordpress tests passing, 14 kell_mobile, 24 kell_web, 41 design_system — 379 total). Stage 6 complete.

Stage 7 — Controlled bulk actions (only after groundwork)¶

Objective¶

Add carefully scoped bulk operations once single-item workflows are stable across web and Android.

Branches¶

feat/bulk-status-actions
feat/bulk-operator-workflows

Entry criteria ✅ ALL MET¶

✅ single-item edit/status flows are stable
✅ multi-select groundwork is complete
✅ post-write consistency is hardened
✅ Android core publishing surface exists

Stage 7A — Bulk move-to-draft (web) ✅ COMPLETE¶

Merged feat/bulk-status-actions → main (2026-05-30). Added BulkActionResult value class, bulkUpdateStatus() controller method (sequential processing with per-row updating state, single reload after completion, auto-clear multi-selection), showBulkActionSnackBar() with success/partial-failure/total-failure messaging. Updated _MultiSelectBar with "Move to Draft" button and confirmation dialog. 11 new bulk action tests added (311 total feature_wordpress tests passing, 24 kell_web tests passing).

Stage 7B — Bulk operator workflows ✅ COMPLETE¶

Merged feat/bulk-operator-workflows → main (2026-05-30). Enabled pendingReview status in WordPressProductMapper.toWooCommerceStatus() (maps to WooCommerce 'pending'). Added "Publish" and "Submit for Review" bulk action buttons to _MultiSelectBar with confirmation dialogs. Refactored bar layout from Row to Wrap for responsive overflow. 8 new tests added across mapper, controller, page, and repository test suites (319 total feature_wordpress tests passing). Stage 7 complete.

Explicitly defer¶

bulk generic edit
bulk category management
destructive bulk deletion unless separately justified

Stage 8 — Infrastructure package activation¶

Objective¶

Activate the three infrastructure stub packages (auth, data, integrations) to provide shared foundations required by all subsequent feature work — especially multi-channel commerce, custom orders, and inventory management.

Key principle¶

These packages define contracts and abstractions first, with concrete implementations added incrementally. Do not build full implementations in one pass.

Branches¶

feat/integrations-contracts
feat/data-layer-contracts
feat/auth-foundation

Stage 8A — Integration abstractions (`integrations` package)¶

Goal¶

Replace the placeholder Calculator class in integrations with shared integration contracts that formalize the API client pattern already proven in feature_wordpress.

Requirements¶

Define ApiClient abstract class (lifecycle, auth, error handling, dispose)
Define ApiException base class with status code, message, body
Define RetryPolicy and RateLimiter abstractions
Define IntegrationHealthCheck contract
Define WebhookHandler contract for incoming webhook processing
Define ChannelAdapter contract — the abstraction for a sales channel (WooCommerce, Square, future channels) with standard operations: products, orders, inventory, customers
Refactor WooCommerceApiClient and WooCommerceApiException to implement the shared contracts
Tests for all contracts

Stage 8B — Shared data layer (`data` package)¶

Goal¶

Provide shared data abstractions for local caching, offline storage, and cross-feature data patterns.

Requirements¶

Define LocalCache<T> contract for in-memory and persistent caching
Define SyncQueue abstraction for offline operation queuing
Define ConflictResolver<T> contract for multi-channel sync conflicts
Define ChangeTracker<T> for tracking local modifications pending sync
Define DataMapper<TLocal, TRemote> for local ↔ remote model mapping
Implement SQLite-backed persistent cache (using sqflite or drift)
Tests for all abstractions

Stage 8C — Authentication foundation (`auth` package)¶

Goal¶

Provide basic authentication and secure credential storage so the app can be deployed beyond a single operator.

Requirements¶

Define AuthService contract (login, logout, current user, token refresh)
Define CredentialStore contract for secure storage of API keys (WooCommerce, Square)
Implement SecureCredentialStore using flutter_secure_storage
Define User and AuthState domain models
Add KC_ENV extension: support SQUARE mode alongside FAKE and WP
Update KcAppEnvironment enum and KcBootstrap to support the new mode
Tests for auth contracts and credential store

Stage 9 — WooCommerce integration expansion¶

Objective¶

Extend the WooCommerce integration from products-only to full commerce coverage: orders, inventory/stock, categories, images, and customers.

Key principle¶

Each API surface is added as a separate sub-stage with its own repository contract, implementation, and tests. The WooCommerceApiClient gains new endpoint methods; feature packages gain new repository methods.

Branches¶

feat/wc-orders-integration
feat/wc-inventory-sync
feat/wc-catalog-expansion

Stage 9A — WooCommerce Orders API integration¶

Goal¶

Connect the orders feature to WooCommerce so orders placed online appear in the app and order status can be updated.

Requirements¶

Add getOrders(), getOrder(id), updateOrderStatus(), createOrder() to WooCommerceApiClient
Extend Order domain model: add orderNotes, paymentMethod, source (online vs. market), customFields map for custom order specifications
Extend OrderItem domain model: add productId, variationId, customizations (map for custom order specs like color, size, material)
Add OrderStatus values: onHold, refunded, failed (WooCommerce standard statuses)
Extend OrdersRepository contract: getOrders(), getOrder(id), createOrder(), updateOrderStatus(), addOrderNote()
Implement WooCommerceOrdersRepository
Update FakeOrdersRepository with matching methods
Add order mapper for WooCommerce JSON ↔ domain
Tests for repository, mapper, and API client extensions

Stage 9B — WooCommerce stock/inventory sync¶

Goal¶

Enable bidirectional stock quantity synchronization between the app's inventory and WooCommerce product stock levels.

Requirements¶

Add getProductStock(id), updateProductStock(id, quantity), batchUpdateStock(updates) to WooCommerceApiClient
Extend InventoryItem domain model: add wooCommerceProductId (nullable — not all inventory items are WooCommerce products), lastSyncedAt, syncStatus
Extend InventoryRepository contract: updateQuantity(), adjustQuantity(), getItemBySku(), syncWithRemote()
Add InventorySyncService in application layer — orchestrates comparing local vs. remote stock and resolving differences
Implement WooCommerceInventoryRepository
Update FakeInventoryRepository with matching write methods
Tests for sync service, repository, and stock update flows

Stage 9C — WooCommerce catalog expansion ✅ COMPLETE¶

Goal¶

Add product creation, image management, and category CRUD to complete full catalog management via WooCommerce.

Requirements¶

✅ Add createProduct(data), deleteProduct(id) to WooCommerceApiClient
✅ Add getCategories(), createCategory(), updateCategory(), deleteCategory() to WooCommerceApiClient
✅ Add getProductImages(productId), setProductImages(productId, mediaIds) to WooCommerceApiClient
✅ Extend ProductPublishingRepository: createProduct(), deleteProduct(), updateProductImages(), getCategories(), createCategory(), updateCategory(), deleteCategory(), getProductImages()
✅ Add ProductCategory domain model (id, name, slug, parentId, count) with copyWith, equality, toString
✅ Add ProductImage domain model (id, url, alt, position) with copyWith, equality
✅ Implement all new methods in FakeProductPublishingRepository (with seed categories)
✅ Implement all new methods in WordPressProductPublishingRepository
✅ Add use cases: CreateProduct, DeleteProduct, GetCategories, CreateCategory, UpdateProductImages
✅ Update barrel exports in feature_wordpress.dart
✅ Update test stubs in dashboard_controller_test.dart and product_publishing_page_test.dart
✅ 69 new tests in wc_catalog_expansion_test.dart covering domain models, fake repo, API client, real repo, and use cases
✅ Product creation UI — CreateProductDialog (web) and MobileCreateProductPage (mobile) with name, price, SKU, category dropdown, description, initial status (Stage 9D)
✅ Image management scaffolding — UpdateProductImages use case wired; full image picker UI deferred to Stage 10+
✅ Category management page — CategoryManagementPage with list, add, rename, delete, empty/loading/error states (Stage 9D)

Branch¶

feat/wc-catalog-expansion — merged to main

Stage 9D — Product creation UI and category management ✅ COMPLETE¶

Merged feat/wc-catalog-expansion-ui → main (2026-07-11). Added CreateProductDialog (web) — StatefulWidget with name (required), price (required), SKU, category dropdown, description, and initial-status SegmentedButton (Draft / Review); inline validation errors; CreateProductDialogResult value object; showCreateProductDialog() helper. Added CategoryManagementPage with category list, add-category FAB, inline rename, delete with confirmation dialog, empty/loading/error states. Extended ProductPublishingController with CreateProductResult sealed class, createNewProduct() (calls CreateProduct use case, auto-selects new product, reloads), and fetchCategories(). Wired "New Product" button and "Manage Categories" link into ProductPublishingPage toolbar. Added MobileCreateProductPage full-screen form for mobile. Added "New Product" FAB to MobilePublishingPage. Expanded barrel exports. 34 new tests added (13 dialog, 14 category page, 7 controller) — 424 total feature_wordpress tests passing. Analyze clean.

Branch¶

feat/wc-catalog-expansion-ui — merged to main

Stage 10 — Square integration foundation¶

Objective¶

Introduce Square as a second sales channel, enabling in-person payment processing and catalog/inventory synchronization.

Key principle¶

Square integration must follow the same architectural pattern as WooCommerce: API client in a data layer, repository contracts in domain layer, and runtime selection via --dart-define. The integrations package ChannelAdapter contract (Stage 8A) provides the abstraction both channels implement.

Branches¶

feat/square-api-client
feat/square-catalog-sync
feat/square-payments

Stage 10A — Square API client and authentication ✅ COMPLETE¶

Merged feat/square-api-client → main (2026-07-19). Added SquareApiClient in integrations package implementing ApiClient contract; sandbox() and production() factory constructors; full lifecycle (initialize(), dispose(), isReady, execute<T>()); Catalog API (listCatalogItems() with cursor pagination, getCatalogItem(), upsertCatalogItem(), deleteCatalogItem()); Inventory API (getInventoryCount(), batchChangeInventory()); Orders API (createOrder(), listOrders(), getOrder()); Payments API (createPayment(), getPayment()); Bearer token + Square-Version headers on all requests. Added SquareApiException extending ApiException. Added KC_SQUARE_ACCESS_TOKEN, KC_SQUARE_LOCATION_ID, KC_SQUARE_ENVIRONMENT dart-define key constants to KcAppConfig. Added KcAppEnvironment.multi value. 50 new tests in square_api_client_test.dart — 88 total integrations tests. 24 total core tests. Analyze clean across all 11 packages/apps.

Branch¶

feat/square-api-client — merged to main

Stage 10B — Square catalog and inventory sync¶

Goal¶

Synchronize the product catalog and inventory levels between the app and Square.

Requirements¶

Create SquareProductMapper for Square CatalogObject ↔ ProductDraft mapping
Create SquareInventoryMapper for Square InventoryCount ↔ InventoryItem mapping
Create SquareCatalogRepository implementing ProductPublishingRepository (or a shared catalog contract)
Create SquareInventoryRepository implementing InventoryRepository
Create ProductIdMapping domain model — maps product IDs across WooCommerce and Square
Create ProductIdMappingRepository for persisting cross-channel ID mappings
Update FakeProductPublishingRepository and FakeInventoryRepository with matching operations
Tests for mappers, repositories, and ID mapping

Stage 10C — Square payment processing (mobile POS)¶

Goal¶

Enable the Android app to accept payments via Square at craft markets.

Requirements¶

Integrate Square Mobile Payments SDK (or Square Reader SDK) for Android
Create PaymentService abstraction in application layer
Create PaymentResult domain model (amount, method, transactionId, receiptUrl)
Create MobileCheckoutPage — product selection → cart → payment flow
Support cash recording (manual entry, no Square hardware needed)
Support card payment via Square Reader
Generate digital receipt (or link to Square receipt)
After payment: create order record, deduct inventory
Add Sales tab to mobile navigation (replaces or supplements current Products tab for market mode)
Tests for payment service, checkout flow, and order creation

Stage 11 — Custom orders workflow¶

Objective¶

Enable operators to accept custom/made-to-order requests from both online and in-person channels, track specifications, manage deposits, and fulfill orders.

Key principle¶

Custom orders extend the existing Order domain model with additional fields rather than creating a parallel system. Custom orders flow through the same order management pipeline.

Branches¶

feat/custom-order-domain
feat/custom-order-ui
feat/custom-order-tracking

Stage 11A — Custom order domain and data ✅ COMPLETE¶

Delivered on feat/custom-order-domain (2026-08-29). See "Stage 11A — complete (2026-08-29)" above for the full manifest.

Goal¶

Extend the order domain model and repository to support custom order creation with specifications.

Requirements¶

✅ Add OrderType enum: standard, custom
✅ Add CustomOrderSpec value object: material, color, size, dimensions, reference image URLs, free-text notes, estimated completion date
✅ Add DepositInfo value object: deposit amount, deposit date, balance due, settlement date, paid flag — all money as integer cents, consistent with PaymentResult
✅ Extend Order model: orderType, customOrderSpec (nullable), depositInfo (nullable), fulfillmentStatus (nullable). All existing fields and equality semantics preserved
✅ Extend the fulfillment pipeline: quoted → depositReceived → inProduction → qualityCheck → readyForPickup → completed, with legal transitions enforced in the domain (FulfillmentTransition) — illegal jumps are rejected, not silently allowed
✅ Extend OrdersRepository: createCustomOrder(), updateCustomOrderSpec(), recordDeposit(), advanceFulfillmentStatus()
✅ Implement in both FakeOrdersRepository (seeded custom orders across every pipeline stage) and WooCommerceOrdersRepository (_kc_-prefixed order meta-data; mapping documented on WooCommerceOrderMapper)
✅ KcLogger injected into both repositories; no silent catch (_) {}; no customer PII or deposit payment identifiers in log context
✅ Tests for domain models and repository methods (423 new)

Deferred to Stage 11C: estimatedCompletionDate currently lives on CustomOrderSpec rather than on Order, and there is no dedicated updateEstimatedCompletion() — a date revision goes through updateCustomOrderSpec(). internalNotes was not added; Order.notes already serves that purpose.

Stage 11B — Custom order creation UI ✅ COMPLETE¶

Delivered on feat/custom-order-ui (2026-09-25). See "Stage 11B — complete (2026-09-25)" above for the full manifest.

Goal¶

Provide mobile and web interfaces for creating custom orders, especially at markets.

Requirements¶

✅ Create CustomOrderFormPage (shared presentation, hosted by both targets)
✅ Customer information capture (name, email, phone)
⚠️ Free-text description delivered; product base selection from the catalogue deferred to Stage 11C
✅ Customization fields: material, color, size/dimensions, special instructions
⚠️ Reference images captured as URLs to already-uploaded media; the platform camera / file picker lands with the media pipeline
✅ Pricing: estimated price, deposit amount, deposit payment method, live balance due — all money as integer cents
✅ Estimated completion date picker, with past dates rejected
✅ Create CustomOrderConfirmationPage — summary with a deposit receipt that carries no payment identifier
✅ Wire into mobile shell navigation (MobileCustomOrderPage + orders FAB) and web routing (/orders/custom + OrdersPage action)
✅ Tests for form validation and the creation flow (146 new)

Stage 11C — Custom order tracking and fulfillment ✅ COMPLETE¶

Delivered on feat/custom-order-tracking (2026-09-25). See "Stage 11C — complete (2026-09-25)" above for the full manifest.

Goal¶

Provide order tracking dashboard and status management for custom orders.

Requirements¶

✅ Create CustomOrderTrackingPage — custom orders filtered by fulfillment stage, with live per-stage counts, free-text search over customer / ID / specification, and a master-detail layout above KcBreakpoints.medium
✅ Status progression quoted → depositReceived → inProduction → qualityCheck → readyForPickup → completed driven through showAdvanceStageDialog, which offers only domain-legal stages. Illegal transitions are rejected by the repository and surfaced as FulfillmentTransition.rejectionReason verbatim — the UI never invents wording for a rule it does not own
⚠️ Notification triggers not built. They need an outbound messaging channel the platform does not yet have; FulfillmentEvent is the natural hook when one lands. Deferred rather than stubbed
✅ Order history / timeline view — FulfillmentEvent is appended on every accepted transition and rendered by FulfillmentTimeline with timestamps, operator notes, and a rework marker
✅ Custom order completion linked to inventory deduction via MaterialConsumptionPort and each app's InventoryMaterialConsumptionAdapter. Completion advances first and deducts second, so a rejected transition can never decrement stock
✅ Tests for the tracking UI and every status progression path (329 new)

Deferred: notification triggers (above). MaterialUsage is recorded through recordMaterialUsage() but has no editing UI yet — the natural home for one is Stage 12B's supplies workflows, where materials and suppliers are already on screen.

Stage 12 — Inventory and supplies management¶

Objective¶

Transform the inventory feature from a read-only fake-data display into a full supplies and inventory management system with write operations, supply tracking, and multi-channel stock sync.

Key principle¶

Distinguish between raw materials/supplies (inputs to production) and finished goods (products for sale). Both are tracked in the inventory system but have different lifecycles.

Branches¶

feat/inventory-write-ops
feat/supplies-tracking
feat/inventory-sync-engine

Stage 12A — Inventory write operations and domain expansion¶

Goal¶

Add write operations to inventory and expand the domain model for real-world tracking.

Requirements¶

Add ItemType enum: rawMaterial, finishedGood, packaging, tool
Extend InventoryItem: itemType, reorderPoint, reorderQuantity, supplier, costPerUnit, location, lastCountDate, notes
Add InventoryAdjustment value object: itemId, adjustmentType (received, used, damaged, returned, counted), quantity, reason, timestamp, operator
Extend InventoryRepository: addItem(), updateItem(), adjustQuantity(), getAdjustmentHistory(), getLowStockItems(), getItemsByType()
Implement write operations in FakeInventoryRepository
Add InventoryController (ChangeNotifier) for state management — mirrors the pattern from ProductPublishingController
Tests for all new domain models, repository methods, and controller

Stage 12B — Supplies tracking¶

Goal¶

Add supply-specific workflows: receiving shipments, recording material usage in production, and reorder alerts.

Requirements¶

Add Supplier domain model: name, contact, leadTime, minimumOrder
Add PurchaseOrder domain model: supplier, items, orderDate, expectedDelivery, status, totalCost
Add SupplierRepository contract and fake implementation
Add PurchaseOrderRepository contract and fake implementation
Create supply receiving workflow: record incoming shipments → auto-adjust inventory
Create material usage workflow: when fulfilling orders (standard or custom) → deduct raw materials
Add low-stock alert system: surface items below reorder point on dashboard
Create SuppliesPage UI (list, filter by type, quick-adjust, reorder alerts)
Tests for supply workflows, reorder logic, and UI

Stage 12C — Multi-channel inventory sync engine¶

Goal¶

Keep inventory quantities consistent across the local app, WooCommerce, and Square.

Requirements¶

Create InventorySyncEngine in application layer:
Poll or webhook-triggered sync from WooCommerce and Square
Conflict resolution: last-write-wins with operator override option
Sync status tracking per item (synced, pending, conflict, error)
Batch sync support for efficiency
Create ChannelStockMapping — maps inventory item IDs to WooCommerce product IDs and Square catalog item IDs
Implement WooCommerceStockSync using Stage 9B foundations
Implement SquareStockSync using Stage 10B foundations
Add sync status indicators to inventory UI
Add manual sync trigger and conflict resolution UI
Tests for sync engine, conflict resolution, and channel adapters

Stage 13 — Multi-channel sync and unified operations¶

Objective¶

Provide a unified view across WooCommerce and Square as two sales channels, with consistent product catalog, pricing, and order visibility.

Key principle¶

The sync engine is event-driven where possible (webhooks) and poll-based as fallback. The app is the source of truth for catalog data; channels are synchronized outward.

Branches¶

feat/unified-catalog-sync
feat/unified-order-view
feat/webhook-integration

Stage 13A — Unified catalog sync¶

Goal¶

Synchronize the product catalog bidirectionally between WooCommerce and Square, with the app as the authoritative source.

Requirements¶

Create CatalogSyncService orchestrating WooCommerce ↔ app ↔ Square product sync
Product changes in the app push to both channels
Product changes detected from channels pull into the app (with conflict detection)
Handle field mapping differences between platforms (e.g., WooCommerce categories vs. Square categories)
Handle price sync across channels (same price or channel-specific pricing)
Create SyncDashboard widget showing last sync time, pending changes, errors per channel
Tests for sync service, conflict detection, and field mapping

Stage 13B — Unified order view¶

Goal¶

Aggregate orders from all channels (WooCommerce online, Square in-person, custom orders) into a single order management interface.

Requirements¶

Add OrderChannel enum: woocommerce, square, manual
Extend Order model with channel field
Create UnifiedOrdersController that merges orders from all repositories
Create unified orders page showing all orders with channel indicator and filters
Order detail page shows channel-specific information
Tests for unified controller and merged order display

Stage 13C — Webhook integration (stretch)¶

Goal¶

Set up real-time change detection from WooCommerce and Square via webhooks.

Requirements¶

Define WebhookHandler endpoints for WooCommerce webhooks (order created, product updated, stock changed)
Define WebhookHandler endpoints for Square webhooks (payment completed, inventory changed)
Requires a lightweight backend/proxy (n8n workflow or serverless function) to receive webhooks and forward to the app
Alternatively: implement polling with configurable intervals as interim solution
Tests for webhook payload parsing and event routing

Stage 14 — Offline capability and field operations¶

Objective¶

Make the mobile app usable at markets with poor or no network connectivity.

Key principle¶

Offline-first for critical market operations (viewing catalog, recording sales, capturing custom orders). Sync when connectivity is available.

Branches¶

feat/offline-data-cache
feat/offline-sales-queue
feat/barcode-scanning

Stage 14A — Offline data cache¶

Goal¶

Cache product catalog and inventory data locally so the mobile app can display products and check stock without network.

Requirements¶

Implement LocalCache<T> from data package (Stage 8B) using SQLite
Cache product catalog, inventory items, and categories on successful fetch
Detect offline state and serve from cache with "offline" indicator
Cache invalidation strategy: time-based + manual refresh
Pre-market sync: "Prepare for Market" action that forces a full cache refresh
Tests for cache storage, retrieval, offline detection, and invalidation

Stage 14B — Offline sales queue¶

Goal¶

Queue sales transactions made offline and sync them when connectivity returns.

Requirements¶

Implement SyncQueue from data package (Stage 8B)
Queue offline sales with all order details (items, quantities, payment method, customer)
Queue offline inventory adjustments
Queue offline custom order captures
Auto-sync on connectivity restoration with progress indicator
Handle sync conflicts (e.g., item sold out in both channels during offline period)
Manual sync trigger with error reporting
Tests for queue operations, sync flow, and conflict handling

Stage 14C — Barcode/SKU scanning (stretch)¶

Goal¶

Enable quick product lookup via barcode scanning on the mobile app.

Requirements¶

Integrate camera-based barcode scanning (using mobile_scanner or similar package)
Scan → product lookup by SKU → add to cart or view details
Support standard product barcodes and QR codes
SKU label printing integration (stretch)
Tests for scan → lookup flow

Stage 15 — Reporting and business intelligence¶

Objective¶

Activate the feature_finance package to provide sales reporting, inventory valuation, and basic business analytics.

Key principle¶

Reports aggregate data from orders, inventory, and product repositories across all channels. Start with simple aggregations before adding charts or advanced analytics.

Branches¶

feat/sales-reporting
feat/inventory-reporting
feat/financial-dashboard

Stage 15A — Sales reporting¶

Goal¶

Provide daily, weekly, and monthly sales summaries across all channels.

Requirements¶

Sales by channel (WooCommerce, Square, custom orders)
Sales by product/category
Sales by time period with comparison to previous period
Top-selling products
Average order value
Revenue tracking
Exportable reports (CSV)
Tests for aggregation logic

Stage 15B — Inventory valuation and reporting¶

Goal¶

Provide inventory value, turnover, and supply usage reports.

Requirements¶

Current inventory value (cost and retail)
Inventory turnover rate
Low stock alerts summary
Supply usage history
Reorder recommendations based on usage trends
Tests for valuation calculations

Stage 15C — Financial dashboard¶

Goal¶

Create a unified financial dashboard combining sales, costs, and margins.

Requirements¶

Revenue vs. cost of goods
Gross margin by product and category
Market event profitability (sales at specific markets)
Period-over-period trends
Wire into existing dashboard page as additional summary cards
Tests for dashboard aggregations

Stage 16 — Production readiness¶

Objective¶

Harden the platform for production deployment beyond a single operator.

Branches¶

feat/error-tracking
feat/secure-deployment

Stage 16A — Error tracking and observability ✅ COMPLETE¶

Delivered on feat/observability-error-logging (2026-08-29). See "Stage 16A — complete (2026-08-29)" above for the full manifest.

Goal¶

Add crash reporting, error tracking, and basic usage analytics.

Requirements¶

✅ Crash/error capture — KcErrorReporter installs FlutterError.onError, PlatformDispatcher.instance.onError, and a guarded zone around runApp. Implemented as a first-party abstraction rather than binding directly to Sentry so no vendor dependency is introduced before the deployment model is settled; KcLogSink is the extension point for a hosted backend.
✅ Structured logging for errors and state transitions — KcLogger with five severities, threshold filtering, and mandatory credential redaction.
⏳ Usage analytics (feature usage frequency, sync success rates) — deferred. KcLogRecord carries the structured context needed to derive these, but no aggregation or reporting surface exists yet.
⏳ Health check dashboard per channel — deferred. The IntegrationHealthCheck contract exists in integrations but has no implementation or UI.

Remaining scope (tracked as Stage 16C)¶

Remote log/crash sink (KcLogSink implementation posting to a backend)
Integration health dashboard driven by IntegrationHealthCheck
Usage analytics aggregation
In-app log viewer for operator self-service diagnostics

Stage 16B — Secure deployment configuration¶

Goal¶

Move beyond --dart-define for credential management in production.

Requirements¶

Secure credential storage on device (via auth package Stage 8C)
First-run setup wizard for entering API credentials
Connection testing UI (verify WooCommerce and Square connectivity)
Environment-specific configuration (dev/staging/production)

Stage 16C — Resilience and remote diagnostics¶

Goal¶

Make integrations survive transient failure, and make diagnostics visible off-device.

Requirements¶

Wire ExponentialBackoffRetryPolicy into SquareApiClient and WooCommerceApiClient for 5xx and network errors (P3.1)
Wire TokenBucketRateLimiter into Square calls — Square enforces rate limits and currently a burst sync can be throttled with no recovery
Implement IntegrationHealthCheck per channel and surface it on the Integrations page
Remote KcLogSink implementation so ERROR/FATAL records and submitted bug reports leave the device
In-app log viewer for operator self-service diagnostics
Usage analytics aggregation (feature usage frequency, sync success rates)

Suggested improvements (identified from codebase analysis)¶

This section captures structural improvements, coverage gaps, and maturity enhancements identified through codebase analysis against the architecture documentation and current implementation state. Items here are candidates for future stages or can be woven into existing stages as appropriate.

1. Stub package activation roadmap¶

The following packages exist as scaffolded stubs with no implementation. Each needs an activation plan aligned to architecture documentation:

Package	Architecture Reference	Priority	Notes
`auth`	Enterprise Identity & Access Architecture	High	No auth layer exists; all access is currently uncontrolled. Required before any multi-user or production deployment.
`data`	Enterprise Data Architecture	Medium	Shared data abstractions/caching could reduce duplication across feature repositories.
`integrations`	Enterprise Integration & Orchestration Architecture	Medium	Shared integration contracts could formalize API client patterns currently embedded in `feature_wordpress`.
`feature_finance`	Financial Analysis Components	Low	Architecture docs exist but no implementation. Defer until core WordPress/Inventory workflows mature.
`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: Addressed in Stage 8 — Infrastructure package activation. Auth, data, and integrations are activated before expanding into new feature domains.

2. Design system expansion ✅ RESOLVED¶

Addressed in Stage 4A (Design system expansion and shared widget migration), merged 2026-05-22. All previously identified gaps have been resolved:

✅ Shared typography scale → KcTypography with full Material 3 hierarchy and applyKcTypography() helper

✅ Responsive layout utilities → KcBreakpoints with compact/medium/expanded/large queries and grid column helper

✅ Shared empty state, loading state, error state patterns → KcEmptyState, KcLoadingState, KcErrorState

✅ Shell widgets migrated → EmptyStatePanel, SectionHeader, SummaryCard moved from kell_web to design_system as KcEmptyState, KcSectionHeader, KcSummaryCard; backward-compatible typedefs retained in kell_web

The design_system package now contains: theme (KcColors, KcSpacing, KcTheme), typography (KcTypography), layout (KcBreakpoints), and 7 widgets (KcCard, KcStatusChip, KcEmptyState, KcSectionHeader, KcSummaryCard, KcLoadingState, KcErrorState). 41 tests, 100% line coverage.

Remaining gap: No shared button/action component library. This can be addressed in a future stage as needed.

3. Cross-platform shell composition strategy ✅ RESOLVED¶

Addressed in Stage 4B (Cross-platform shell composition strategy), merged feat/shared-composition-pattern → main at 0a0abc2 (2026-05-22). Shared composition abstractions extracted into core package: KcAppConfig, KcAppEnvironment, KcAppServices (abstract), KcServiceFactory<T>, KcBootstrap, KcAppScope<T>. kell_web updated to delegate to shared types via backward-compatible typedefs. Contract for new app targets (including kell_mobile) documented in kell_creations_apps/docs/composition-strategy.md. 20 core tests passing. Analyze clean.

4. CI/CD for Flutter applications ✅ RESOLVED¶

Addressed in Stage 4C (Flutter CI/CD pipeline), merged feat/flutter-cicd → main at 6a6323e (2026-05-22). Two Forgejo Actions workflows established: flutter-analyze.yml (runs dart analyze --fatal-infos on all 8 packages/apps) and flutter-test.yml (runs flutter test per package with aggregate summary table). Workflows trigger on PRs to main and all non-main branch pushes. Local CI helper scripts added to tools/.

Remaining gap: Flutter build validation (web + Android) is not yet automated in CI. This can be added as Android work progresses in Stage 5.

5. Test coverage visibility and quality gates ✅ PARTIALLY RESOLVED¶

Automated test count reporting and line coverage measurement now addressed in Stage 4D (test coverage visibility). CI workflow produces per-package pass/fail counts and coverage percentages. Baseline documented. Minimum threshold enforcement and trend tracking remain future enhancements.

6. Build execution tracker synchronization ✅ RESOLVED¶

The build_execution_tracker.md has been fully updated through Stage 6A. All 13 merged branches are tracked with status, dates, files changed, test counts, and analysis results. Current status correctly reflects Stage 6A complete and next branch as feat/android-mobile-ux-hardening (Stage 6B). Last synchronized 2026-05-30.

7. Image and media management¶

Architecture documentation (traceability-index.md coverage gaps) identifies "Product image / media synchronization workflow" as a gap. The current publishing workflow handles text fields only.

Recommendation: Addressed in Stage 9C — WooCommerce catalog expansion which includes image upload, gallery management, and product image assignment via the WooCommerce Media API.

8. Error tracking and observability ✅ PARTIALLY RESOLVED¶

Resolved for error capture and diagnostics by Stage 16A (2026-08-29). Runtime errors are now captured by KcErrorReporter, recorded through KcLogger, and attachable to operator bug reports via KcBugReportService. Credential redaction (KcRedactor) is enforced on every logged context map.

Still open: logs and reports are held in-process only — there is no remote sink, so diagnostics are lost when the app restarts and are unavailable to anyone but the operator on the device. Usage analytics remain unimplemented. Both are tracked as Stage 16C.

9. Empty tools directory ✅ RESOLVED¶

Now populated with run_all_tests.sh and README.md as part of Stage 4C (Flutter CI/CD pipeline).

10. Missing feature parity documentation ✅ PARTIALLY RESOLVED¶

A feature maturity matrix has been added to this brief (see Appendix: Feature maturity matrix at the end of this document). It maps all 12 packages across domain, application, data (fake/real), presentation, test count, and maturity level. Added 2026-05-22 during full project analysis.

Remaining gap: The matrix does not yet map architecture documentation aspirations to implementation status per feature (e.g., which architecture-described capabilities exist vs. are missing within each feature package). This can be expanded as feature packages mature.

11. Policy register CSVs are empty¶

The policy repository has 2 active governance documents (KC-POL-GOV-001, KC-PRO-GOV-001), but the register CSVs (policy-register.csv, document-control-log.csv, review-calendar.csv) contain headers only with no data rows. This means the controlled document lifecycle described in the Document Control Policy is not being followed for the governance documents themselves.

Recommendation: Populate the register CSVs with entries for the 2 active governance documents. This should be done before any additional policies are created.

12. `feature_orders` package missing standard scaffolding¶

The feature_orders package is missing standard scaffolding files (.gitignore, .metadata, CHANGELOG.md, LICENSE, README.md) that are present in all other packages. This creates inconsistency across the monorepo.

Recommendation: Add the missing files to feature_orders to match the structure of other packages. This is a low-effort, high-consistency improvement.

13. Architecture documentation shows wrong diagram¶

The Enterprise Data Architecture documentation page (docs/architecture/containers/enterprise-data-architecture.md) was referencing the wrong SVG image (showing the enterprise services diagram instead of the data architecture diagram).

Resolution: ✅ Fixed 2026-05-22 during full project analysis. Image reference corrected to enterprise-data-architecture.svg.

14. Missing diagram source references in architecture docs¶

Three architecture documentation pages were missing the standard "Diagram Source" section pointing to their PlantUML file:

docs/architecture/system-landscape.md
docs/architecture/containers/platform-containers.md
docs/architecture/components/inventory.md

Resolution: ✅ Fixed 2026-05-22 during full project analysis. Diagram source references added for consistency.

15. Empty documentation sections need initial content¶

The Standards, Integrations, and Brand documentation sections had placeholder-only index pages with no substantive content.

Resolution: ✅ Populated 2026-05-22 during full project analysis. Each section now includes current state assessment, recommendations, and actionable next steps.

16. ADR index needs retroactive entries¶

The Architecture Decision Record (ADR) index exists but contained no entries. Seven significant architecture decisions are already in effect across the platform.

Resolution: ✅ Populated 2026-05-22 during full project analysis. Seven candidate ADRs documented with status, context, decision, and consequences.

17. Square integration not represented in architecture¶

The architecture documentation (system landscape, integration architecture, deployment architecture) makes no mention of Square. Square needs to be added as an external system in the system landscape and as an integration target in the enterprise integration architecture.

Recommendation: Update architecture diagrams before or during Stage 10 (Square integration foundation):

Add Square to system-landscape.puml as an external system
Add Square to enterprise-integration-orchestration-architecture.puml
Add Square to context-kellcreations-platform.puml
Create a new dynamic workflow: dynamic-market-sale-checkout.puml

18. No multi-channel data model in architecture¶

The current architecture documents describe a single-channel model (WordPress/WooCommerce). The multi-channel reality (WooCommerce + Square) requires:

A unified product ID mapping concept
Cross-channel inventory reconciliation
Multi-source order aggregation
Channel-specific vs. channel-agnostic data separation

Recommendation: Add enterprise-multi-channel-architecture.puml capturing the channel adapter pattern, product ID mapping, sync engine, and conflict resolution strategy. This should be created during Stage 13 planning.

19. `feature_mrp` activation alignment¶

The feature_mrp (Craft Manufacturing/MRP) package is architecturally described but stubbed. Custom orders (Stage 11) and supplies tracking (Stage 12B) together provide the foundation for basic manufacturing planning. The MRP package should be evaluated for activation after Stage 12 to determine if its scope is already covered by custom orders + inventory or if it adds distinct value (e.g., production scheduling, work orders, bill of materials).

Recommendation: Re-evaluate feature_mrp scope after Stage 12 completion. It may be partially or fully absorbed by custom order fulfillment and supplies tracking.

Required development workflow for every slice¶

For every branch/stage:

Start from latest main.
Inspect first.
Write a brief inspection report.
Propose the smallest implementation plan.
Implement only the current slice.
Run targeted tests.
Run flutter analyze or dart analyze as appropriate.
Summarize changed files and validation results.
Open PR into main.
Merge only after clean review and validation.
Update this brief and the build execution tracker after merge.

Standard Cline operating prompt¶

Use this at the start of any new slice:

Continue the Kell Creations Flutter operations platform workstream from current main.

Read docs/development/master_development_brief.md first and follow it as the authoritative planning document.

Constraints:
- Preserve strict package boundaries.
- Fake repositories remain in feature packages.
- Real integrations are incremental alongside fake ones.
- Runtime selection stays via --dart-define, not settings UI.
- No credentials hardcoded or committed.
- Do not broaden into generic product editing prematurely.
- Keep WooCommerce details inside the WP repository layer.
- Keep Square details inside a dedicated Square integration layer.
- Multi-channel sync contracts before implementations.
- Use small, reviewable steps only.
- Work is being driven through Cline in Windows 11 VS Code.

Working rules:
1. Inspect first. Do not edit immediately.
2. Summarize current relevant state from main.
3. Propose the smallest implementation plan for the requested slice.
4. Implement only that slice.
5. Add/update focused tests.
6. Run validation.
7. Report changed files and validation results.
8. Update master_development_brief.md and build_execution_tracker.md after merge.

Appendix A: Feature maturity matrix¶

Last updated: 2026-09-25 — chore/state-reconciliation-flutter-347 (test counts verified by a full local run: 1,898 / 1,898 passing)

Package	Domain Layer	Application Layer	Data (Fake)	Data (Real)	Presentation	Tests	Maturity
`feature_wordpress`	✅ Complete	✅ Complete + SquareSync	✅ Complete	✅ WooCommerce + Square	✅ Complete + sync panel	545	Production-ready (100%)
`feature_inventory`	✅ Complete	✅ Write ops	✅ Complete	✅ WooCommerce + Square	✅ Complete	167	Partial (65%)
`feature_orders`	✅ Complete	✅ Write ops + custom orders	✅ Complete	✅ WooCommerce	⚠️ Standard orders only (custom order UI open)	657	Partial (85%)
`feature_policy`	✅ Complete	✅ Complete	✅ Complete	❌ None	✅ Complete	17	Fake-only (50%)
`feature_finance`	❌ Stub	❌ Stub	❌ Stub	❌ None	❌ Stub	1	Scaffolded only (0%)
`feature_mrp`	❌ Stub	❌ Stub	❌ Stub	❌ None	❌ Stub	1	Scaffolded only (0%)
`feature_social`	❌ Stub	❌ Stub	❌ Stub	❌ None	❌ Stub	1	Scaffolded only (0%)
`auth`	✅ Complete	✅ FakeAuthService	✅ InMemory	❌ None (SecureStore TBD)	N/A	42	Foundation ready (40%)
`data`	✅ Contracts	N/A	✅ InMemory	❌ None (SQLite TBD)	N/A	63	Foundation ready (35%)
`integrations`	✅ Contracts	N/A	N/A	✅ WooCommerce + Square	N/A	123	Partial (70%)
`design_system`	N/A	N/A	N/A	N/A	✅ Expanded (theme, typography, layout, 7 widgets)	51	Complete (100%)
`core`	✅ Complete	✅ Composition + observ.	N/A	N/A	N/A	90	Complete (100%)
`kell_web`	N/A	✅ AppServices ×4 modes	N/A	N/A	✅ 7 routes (1 placeholder)	62	Partial (85%)
`kell_mobile`	N/A	✅ MobileAppServices ×4	N/A	N/A	✅ 5-tab shell + POS checkout	81	Partial (85%)

Key changes from previous matrix (updated 2026-09-25)¶

All test counts re-verified by a full local run — 1,898 / 1,898 passing; previous figures predated Stages 10C–10F, 11A, and 16A.
feature_orders 198 → 657 and upgraded to 85%: custom order domain and data landed (Stage 11A). Custom order UI is the remaining gap (Stage 11B).
feature_wordpress 506 → 545 and promoted to 100%: SquareSyncController and the sync panel landed (Stages 10E/10F).
core 24 → 90 and promoted to 100%: observability (KcLogger, KcErrorReporter, KcRedactor) plus square/multi bootstrap validation landed.
kell_web 24 → 62 and kell_mobile 26 → 81, both to 85%: all four KC_ENV modes are wired, the Integrations page is real, and mobile POS checkout landed (Stage 10C). Finance remains a placeholder on both.
design_system 41 → 51, feature_policy ~5 → 17.
Completeness percentages sourced from the re-baselined PROJECT_STATE_AUDIT.md §5 scorecard (2026-09-25).

Appendix B: Integration landscape¶

Last updated: 2026-07-25 — Comprehensive State Audit

Integration	Package/Location	Protocol	Current Status	Target Stage
WooCommerce Products	`feature_wordpress`	REST API v3	✅ Production-ready (full CRUD + categories + images)	—
WooCommerce Orders	`feature_orders`	REST API v3	✅ Repository complete; not wired into AppServices	Stage 9A ✅
WooCommerce Stock	`feature_inventory`	REST API v3	✅ Repository complete; not wired into AppServices	Stage 9B ✅
WooCommerce Catalog	`feature_wordpress`	REST API v3	✅ Full CRUD + categories + images	Stage 9C ✅
WooCommerce Media	`feature_wordpress`	REST API v3	⚠️ Use case wired; image picker UI deferred	Stage 10+
Square Catalog	`feature_wordpress`	Square API v2	✅ Repository complete; no UI trigger (Stage 10E next)	Stage 10B ✅
Square Inventory	`feature_inventory`	Square API v2	✅ Repository complete; not wired into AppServices	Stage 10B ✅
Square Payments	`kell_mobile`	Mobile SDK	❌ Not implemented	Stage 10C (P2.1)
Square Orders	`feature_orders`	Square API v2	❌ No SquareOrdersRepository exists	Stage 13B (P2.7)
Facebook API	`feature_social`	Graph API	❌ Stub only	Deferred
Instagram API	`feature_social`	Graph API	❌ Stub only	Deferred
X (Twitter) API	`feature_social`	REST API v2	❌ Stub only	Deferred
n8n Workflows	(external)	Webhooks/REST	❌ Not implemented	Stage 13C
Mail Server	(external)	SMTP	❌ Not implemented	Deferred

Appendix C: Runtime configuration keys¶

Current¶

Key	Description	Default	Used By
`KC_ENV`	`fake`, `wordpress`	`fake`	All
`KC_WC_SITE_URL`	WordPress site URL	(empty)	WP mode
`KC_WC_CONSUMER_KEY`	WooCommerce REST API consumer key	(empty)	WP mode
`KC_WC_CONSUMER_SECRET`	WooCommerce REST API consumer secret	(empty)	WP mode

Active Square keys (Stage 10A — live on `main`)¶

Key	Description	Default	Used By
`KC_SQUARE_ACCESS_TOKEN`	Square API access token	(empty)	Square mode
`KC_SQUARE_LOCATION_ID`	Square location ID	(empty)	Square mode
`KC_SQUARE_ENVIRONMENT`	`sandbox` or `production`	`sandbox`	Square mode

`KC_ENV` values¶

Value	Description	Status
`fake`	All fake repositories	✅ Active
`wordpress`	WooCommerce real + others fake	✅ Active
`square`	Square real + others fake	✅ Active — `square()` factory + `KcBootstrap` validation (Stage 10E)
`multi`	Both WooCommerce and Square real	✅ Active — `multi()` factory + `KcBootstrap` validation (Stage 10E)

Credential handling: All four modes fall back to fake with a logged warning when required credentials are absent. Credential values are never written to logs or bug reports — KcRedactor masks any context key containing token, secret, key, auth, or credential.

Appendix D: Stage dependency graph¶

Stages 1–6 (COMPLETE/IN PROGRESS) — Foundation
    │
    ├── Stage 7 — Bulk actions (independent, can proceed in parallel)
    │
    └── Stage 8 — Infrastructure activation (PREREQUISITE for 9–16)
            │
            ├── Stage 9 — WooCommerce expansion
            │       │
            │       ├── Stage 11 — Custom orders (depends on 9A orders API)
            │       │
            │       └── Stage 12 — Inventory management (depends on 9B stock sync)
            │               │
            │               └── Stage 12C — Multi-channel inventory sync (depends on 10B)
            │
            ├── Stage 10 — Square integration
            │       │
            │       └── Stage 10C — Mobile POS (depends on 10A + 10B)
            │
            ├── Stage 13 — Multi-channel sync (depends on 9 + 10 + 12C)
            │
            ├── Stage 14 — Offline capability (depends on 8B data layer)
            │
            ├── Stage 15 — Reporting (depends on 9A + 10 + 12)
            │
            └── Stage 16 — Production readiness (depends on 8C auth)

Kell Creations Operations Platform — Master Development Brief¶

Recommended repo location¶

Purpose¶

Platform Vision¶

Core business workflows¶

Working model¶

Current confirmed baseline on main¶

Platform structure¶

Product publishing workflow already landed on main¶

Current narrow edit capabilities on main¶

Latest known validation state on main¶

Baseline test coverage (established 2026-05-22)¶

Stage 10D — complete (2026-07-25)¶

Stage 10E — complete (2026-07-25)¶

Stage 10F — complete (2026-07-25)¶

Stage 10C — complete (2026-07-25)¶

Stage 16A — complete (2026-08-29)¶

Stage 11A — complete (2026-08-29)¶

Stage 11B — complete (2026-09-25)¶

Stage 11C — complete (2026-09-25)¶

Next recommended branch¶

Comprehensive State Audit (2026-07-25)¶

Platform scorecard (as of 2026-07-25)¶

Audit engineering backlog¶

Phase 1 — High-priority / blocking (core fixes and missing execution paths)¶

Phase 2 — Feature completion and integration¶

Phase 3 — Defensive engineering, logging, and test harness expansion¶

Key technical debt findings¶

Senior Audit Report (2026-05-30)¶

Audit scope¶

Audit summary — strengths¶

Audit summary — critical gaps for target vision¶

Gap 1: No product creation capability¶

Gap 2: No image/media management¶

Gap 3: Orders are read-only with fake data¶

Gap 4: Inventory is read-only with fake data¶

Gap 5: Square integration is completely absent¶

Gap 6: No multi-channel sync engine¶

Gap 7: No authentication¶

Gap 8: No offline capability¶

Gap 9: WooCommerce integration is products-only¶

Gap 10: No financial/reporting capability¶

Audit recommendations¶

Non-negotiable architectural constraints¶

Toolchain baseline¶

Known toolchain caveat — analysis_options.yaml is tool-managed¶

Development stages¶

Stage 1 — Web application completion: controlled product editing¶

Objective¶

Branching model¶

~~Stage 1A — Description-only product edit~~ ✅ COMPLETE¶

~~Stage 1B — Category-only product edit~~ ✅ COMPLETE¶

Stage 2 — Web application operational hardening¶

Objective¶

Branches¶

~~Stage 2A — Post-write consistency hardening~~ ✅ COMPLETE¶

~~Stage 2B — Publishing workflow UX hardening~~ ✅ COMPLETE¶

Stage 3 — Web application operator efficiency¶

Objective¶

Branches¶

~~Stage 3A — Multi-select groundwork (read/state only first)~~ ✅ COMPLETE¶

~~Stage 3B — List efficiency improvements~~ ✅ COMPLETE¶

Stage 4 — Platform foundations and cross-platform readiness¶

Objective¶

Key principle¶

Branches¶

~~Stage 4A — Design system expansion and shared widget migration~~ ✅ COMPLETE¶

~~Stage 4B — Cross-platform shell composition strategy~~ ✅ COMPLETE¶

~~Stage 4C — Flutter CI/CD pipeline~~ ✅ COMPLETE¶

~~Stage 4D — Test coverage visibility~~ ✅ COMPLETE¶

Stage 5 — Android application foundation¶

Objective¶

Key principle¶

Branches¶

~~Stage 5A — Android app shell and bootstrap~~ ✅ COMPLETE¶

~~Stage 5B — Android publishing surface~~ ✅ COMPLETE¶

Stage 6 — Android operational maturity¶

Objective¶

Branches¶

~~Stage 6A — Android feedback and action polish~~ ✅ COMPLETE¶

Current confirmed baseline on `main`¶

Product publishing workflow already landed on `main`¶

Current narrow edit capabilities on `main`¶

Latest known validation state on `main`¶

Known toolchain caveat — `analysis_options.yaml` is tool-managed¶

Stage 1A — Description-only product edit ✅ COMPLETE¶

Stage 1B — Category-only product edit ✅ COMPLETE¶

Stage 2A — Post-write consistency hardening ✅ COMPLETE¶

Stage 2B — Publishing workflow UX hardening ✅ COMPLETE¶

Stage 3A — Multi-select groundwork (read/state only first) ✅ COMPLETE¶

Stage 3B — List efficiency improvements ✅ COMPLETE¶

Stage 4A — Design system expansion and shared widget migration ✅ COMPLETE¶

Stage 4B — Cross-platform shell composition strategy ✅ COMPLETE¶

Stage 4C — Flutter CI/CD pipeline ✅ COMPLETE¶

Stage 4D — Test coverage visibility ✅ COMPLETE¶

Stage 5A — Android app shell and bootstrap ✅ COMPLETE¶

Stage 5B — Android publishing surface ✅ COMPLETE¶

Stage 6A — Android feedback and action polish ✅ COMPLETE¶

Stage 6B — Android mobile workflow hardening ✅ COMPLETE¶

Stage 7A — Bulk move-to-draft (web) ✅ COMPLETE¶

Stage 7B — Bulk operator workflows ✅ COMPLETE¶

Stage 8A — Integration abstractions (`integrations` package)¶

Stage 8B — Shared data layer (`data` package)¶

Stage 8C — Authentication foundation (`auth` package)¶

Stage 11A — Custom order domain and data ✅ COMPLETE¶

Stage 11B — Custom order creation UI ✅ COMPLETE¶

Stage 11C — Custom order tracking and fulfillment ✅ COMPLETE¶