Closes the two findings the release committee review identified as absolute
gaps: the platform had no structured logging and no crash reporting, so runtime
errors were invisible in every environment and operators had no way to report a
defect with evidence attached.
Addresses PROJECT_STATE_AUDIT.md findings P3.4 (structured logging infrastructure)
and P3.5 (crash reporting integration), plus the "No logging infrastructure" and
"No crash reporting" architectural risks in section 3.4.
core — new observability layer (packages/core/lib/src/observability/):
- KcLogLevel: five ordered severities (debug/info/warning/error/fatal) with
numeric severity, label, isAtLeast() threshold comparison, and fromString().
- KcLogRecord: immutable structured record (level, source, message, timestamp,
unmodifiable context, error, stackTrace) with format(), toJson(), isFailure.
- KcRedactor: credential redaction over 14 sensitive key fragments, recursing
through nested maps and lists. Applied to every logged context map and every
bug report diagnostics map.
- KcLogSink contract plus three implementations: KcConsoleLogSink (silent in
release by default), KcInMemoryLogSink (bounded ring buffer supplying bug
report evidence), KcMultiLogSink (fan-out that tolerates a failing sink).
- KcLogger: the logging facade. Drops sub-threshold records, redacts context,
and swallows sink exceptions so observability can never break a business
operation. Provides forSource() for subsystem-scoped child loggers.
- KcErrorReporter: installs FlutterError.onError and
PlatformDispatcher.instance.onError, and provides runGuarded() to wrap runApp.
restore() resets global state so tests stay isolated.
- KcBugSeverity and KcBugReport: the report model with redacted diagnostics,
hasFailureEvidence, toJson() for transmission, and toMarkdown() for export.
- KcBugReportSink contract plus KcInMemoryBugReportSink.
- KcBugReportService: validates input, attaches the recent log tail as evidence,
logs the submission outcome, and returns a failure result rather than throwing
when the tracker is unreachable.
- KcObservability: assembles logger, evidence buffer, and bug report service
together. Building them independently is the most likely way to produce empty
bug reports, so this bundle guarantees they share one buffer.
design_system:
- KcBugReportDialog and KcBugReportDraft: the shared operator reporting form
with inline validation, severity selection, optional reporter identity, and an
explicit statement that logs are attached and credentials are never included.
Kept free of a core dependency so design_system stays dependency-free.
Application wiring (kell_web and kell_mobile):
- AppServices and MobileAppServices hold a KcObservability; all four factories
(fake/wordpress/square/multi) stamp their environment label so reports are
attributable to the mode that produced them.
- Both main.dart entry points install the global error handlers before the first
frame and wrap runApp in a guarded zone, then emit a startup record capturing
the effective environment and whether a fake-mode credential fallback occurred.
- "Report a problem" action added to the AppShell and MobileShell app bars,
capturing the active screen (and tab index on mobile).
Documentation:
- docs/operations/release-checklist.md (new): per-environment release gates for
Development, Test/QA, Staging, and Production. Each environment inherits the
prior one's gates and adds its own, with build commands, functional and
observability verification, a sign-off record, rollback triggers, and the open
blocker register.
- master_development_brief.md: Stage 16A manifest, corrected baseline, Stage 16C
defined for the deferred scope (retry/rate limiting, remote sink, health
dashboard, analytics). Marked the square()/multi() factory and ID conflation
debt items resolved (fixed in Stage 10E but still listed as open).
- build_execution_tracker.md: Stage 16A slice entry.
- PRD.md: milestone table brought current; observability added to infrastructure
requirements. Added a scoped markdownlint-disable for MD011 because the PRD's
"(text)[cite: n]" citation markers are indistinguishable from reversed links
and were silently corrupted by markdownlint --fix during this review.
- mkdocs.yml and operations/index.md: register the release checklist.
Corrections made during review:
- The documented test total of 1,458 omitted feature_policy's 17 tests. The true
grand total is 1,475; both figures are now documented with the reason.
Validation:
- 85 new tests: 56 core, 10 design_system, 10 kell_web, 9 kell_mobile.
- 1,475/1,475 passing across all 11 packages and apps.
- dart analyze --fatal-infos clean across all 11 packages and apps.
- markdownlint clean on all five modified/created documents.
Known limitations (tracked as Stage 16C):
- Logs and bug reports are held in-process only. There is no remote sink, so
diagnostics are lost on restart and are unavailable off-device.
- Usage analytics and the per-channel integration health dashboard are not
implemented; IntegrationHealthCheck remains a contract with no implementation.
- Add MobileInventoryPage with search bar, horizontal status filter chips
(All / In Stock / Low Stock / Out of Stock / Draft), item count display,
compact _MobileInventoryCard list at 120px height (name, SKU, status chip,
quantity-on-hand), pull-to-refresh, and _detailPageActive guard to suppress
behind-route SnackBars
- Add MobileInventoryDetailPage wrapping shared InventoryDetailPanel; local
controller listener for SnackBar feedback; showAdjustQuantityDialog on
Adjust Quantity tap; haptic feedback (mediumImpact on result, lightImpact
on successful adjust); SafeArea wrapper
- Update MobileShell Inventory tab (case 1) from shared InventoryPage to
MobileInventoryPage; remove unused feature_inventory direct import
- Add 6 Stage 6C widget tests: Inventory tab search bar, status filter chips,
item count, card navigation to detail, adjust quantity dialog, back
navigation returning to list (26/26 kell_mobile total)
All tests passing: 26/26 kell_mobile, 75/75 feature_inventory
dart analyze --fatal-infos: no issues found
Stage 6 complete — Products, Orders, and Inventory all have mobile surfaces
- Add MobileOrdersPage with search bar, horizontal status filter chips
(All/Pending/Processing/Shipped/Delivered/Cancelled), order count
display, OrderCard list at 160px height, pull-to-refresh, and
\_detailPageActive guard to suppress behind-route SnackBars
- Add MobileOrderDetailPage wrapping shared OrderDetailPanel as a
StatefulWidget with local controller listener for SnackBar feedback,
confirmation dialog before status changes, haptic feedback
(mediumImpact for status, lightImpact for note additions), and SafeArea
- Wire Orders tab (case 3) in MobileShell to MobileOrdersPage; remove
unused feature_orders direct import from shell
- Add 6 new Stage 6B widget tests: Orders tab search bar, status filter
chips, order count, order card navigation to detail, confirmation dialog
for status change, back navigation returning to orders list
- Update build_execution_tracker.md and master_development_brief.md
Tests: 20/20 kell_mobile, 115/115 feature_orders — all passing
Analyze: dart analyze --fatal-infos — no issues found
- Restore Material Design 48x48dp minimum touch targets on 12 IconButtons
in ProductPreviewPanel by removing constraints/padding overrides
- Replace fixed-width SizedBox(width:80) on price edit TextField with
Expanded for flexible layout on narrow mobile screens
- Add tooltip 'Edit price' for consistency with other edit buttons
- Wrap ProductPreviewPanel in SafeArea in MobileProductDetailPage to
prevent content clipping under notches/gesture bars
- Add 6 new touch target rendered-size tests verifying >= 48x48dp
- Update master_development_brief.md and build_execution_tracker.md
Tests: 300/300 feature_wordpress, 14/14 kell_mobile, 24/24 kell_web,
41/41 design_system — 379 total, all passing.
Stage 6 (Android operational maturity) complete.
Validate Docs / validate-docs (push) Successful in 55sDetails
Flutter Analyze / Dart Analyze (push) Has been cancelledDetails
Flutter Test / Flutter Tests (push) Has been cancelledDetails
- Convert MobileProductDetailPage to StatefulWidget with local controller
listener for SnackBar feedback in detail page context
- Add confirmation dialogs for publish/move-to-draft status changes
- Add haptic feedback (mediumImpact for status, lightImpact for field edits)
on successful actions
- Guard MobilePublishingPage SnackBars with _detailPageActive flag to prevent
invisible behind-route feedback when detail page is pushed
- Add 4 new Stage 6A widget tests (14 total kell_mobile tests passing)
- Update build_execution_tracker.md and master_development_brief.md
Validate Docs / validate-docs (push) Successful in 3m31sDetails
Flutter Analyze / Dart Analyze (push) Has been cancelledDetails
Flutter Test / Flutter Tests (push) Has been cancelledDetails
Replace default Flutter counter template in kell_mobile with a fully
integrated mobile operations platform shell reusing shared packages.
Mobile app shell:
- MobileAppServices extending KcAppServices with fake()/wp() factories
- KellMobileApp with KcAppScope<MobileAppServices>, KcTheme, env badge
- MobileShell with 5-tab NavigationBar (Dashboard, Inventory, Orders,
Publishing, More) using IndexedStack for state preservation
- KcBootstrap entry point with --dart-define environment variables
Dashboard:
- DashboardSummary value object with fromData()/empty() constructors
- GetDashboardSummary use case aggregating inventory, orders, publishing
- DashboardController (ChangeNotifier) with loading/error/summary state
- MobileDashboardPage with GridView summary cards using design system
widgets (KcSectionHeader, KcSummaryCard, KcEmptyState)
Placeholder pages:
- FinancePlaceholderPage, IntegrationsPlaceholderPage for More tab
- Feature tab pages delegate to shared feature presentation layers
Infrastructure:
- pubspec.yaml references all shared packages (core, design_system,
feature_inventory, feature_orders, feature_policy, feature_wordpress)
- SDK constraint corrected from ^3.11.4 to ^3.11.0 across all 14
pubspec.yaml files to match installed Dart SDK 3.11.3
Tests:
- 6 new kell_mobile widget tests: shell loading, summary cards,
environment badge, navigation bar destinations, tab switching, More menu
- All existing tests remain passing (24/24 kell_web, 294/294
feature_wordpress)
Documentation:
- master_development_brief.md: Stage 5A marked complete, next branch
updated to feat/android-publishing-surface (Stage 5B), kell_mobile
platform description updated
- build_execution_tracker.md: Stage 5A entry added with full file list
Publish Docs / publish-docs (push) Successful in 1m5sDetails
- Update current status to Stage 4D complete (Stage 4 complete)
- Add feat/test-coverage-visibility slice entry with coverage baseline
- Set next branch to feat/android-app-shell (Stage 5A)
Validate Docs / validate-docs (push) Successful in 1m13sDetails
Extract AppConfig/AppEnvironment, AppServices, Bootstrap, and AppScope into core package as KcAppConfig, KcAppServices, KcBootstrap, and KcAppScope generic abstractions.
New core composition types:
- KcAppConfig: runtime config from --dart-define (KC_ENV, WC credentials)
- KcAppEnvironment: enum for fake/wordpress environments
- KcAppServices: abstract base for app service containers
- KcServiceFactory<T>: generic factory for fake/wordpress service creation
- KcBootstrap: shared bootstrap with env switch and WP credential fallback
- KcAppScope<T>: InheritedWidget exposing typed services + config to tree
kell_web backward compatibility:
- AppConfig/AppEnvironment are now typedefs to Kc-prefixed types
- AppServices extends KcAppServices with concrete repositories
- AppScope extends KcAppScope<AppServices> with direct InheritedWidget lookup
- Bootstrap delegates to KcBootstrap.run with app-specific factory
Tests: 20 new core tests, all 379 tests passing (core 20, design_system 41, feature_wordpress 294, kell_web 24). dart analyze clean.
Publish Docs / publish-docs (push) Successful in 1m10sDetails
Mark Stage 3B (list efficiency improvements) as complete with 294 tests passing. Update baseline commit reference, test count, and next recommended branch to Stage 4A (Android app shell).
Mike Kell