Adds the workshop-side counterpart to Stage 11B's intake form: a tracking workspace filtered by fulfillment stage, an auditable timeline of stage changes, and inventory deduction on completion. Closes audit finding P2.2; Stage 11 is complete.
Domain: FulfillmentEvent (append-only transition record with operator notes and a malformed-line-tolerant wire format), MaterialUsage, MaterialConsumptionPort + MaterialDeductionResult. Order gains fulfillmentHistory, materialUsage, derived stage accessors, and withFulfillmentEvent(). All existing fields, defaults, and copyWith semantics preserved.
Data: advanceFulfillmentStatus() records an event with an optional note and injectable clock; recordMaterialUsage() added. WooCommerce round-trips both through _kc_ meta keys, skipping malformed lines and never blanking remote values.
Application/presentation: AdvanceFulfillment, CompleteCustomOrder, CustomOrderTrackingController, CustomOrderTrackingPage, FulfillmentTimeline, showAdvanceStageDialog. Illegal transitions surface the domain rejection reason verbatim.
Architecture: inventory deduction crosses the feature boundary through an outbound port, not a package dependency. feature_orders still has no dependency on feature_inventory; each app supplies InventoryMaterialConsumptionAdapter. Completion advances first and deducts second, so a rejected transition can never decrement stock, and a deduction failure warns rather than failing the commission.
Tests: 329 new (293 feature_orders, 22 kell_mobile, 14 kell_web). 1085/1085 feature_orders, 109/109 kell_mobile, 81/81 kell_web. dart analyze --fatal-infos clean.
Adds the operator-facing intake flow for made-to-order commissions on top of
the Stage 11A domain and data layers. The form, validation, and confirmation
receipt all live in feature_orders, so web and mobile host the same widget
rather than forking business logic per platform.
Stage 11C still covers the tracking page, the status-change timeline, and
inventory deduction on completion.
Application:
- CreateCustomOrder and RecordDeposit use cases wrapping the repository
methods added in Stage 11A, so presentation never assembles a custom order
aggregate by hand. RecordDeposit deliberately accepts no payment identifier.
- CustomOrderFormController with field-keyed validation, so each input renders
its own error rather than a single form-level message. Clock and ID
generator are injected, which keeps created-at stamps and order IDs
deterministic under test.
- All money is typed as text and converted to integer cents by
parseMoneyToCents before it reaches DepositInfo, consistent with
PaymentResult.amountCents. Thousands separators, currency symbols, excess
precision, and negatives are rejected or normalised at the boundary. The
only double is the derived OrderItem.unitPrice, computed once from cents.
- Derived balance clamps at zero rather than reporting a credit when a deposit
exceeds the quoted total, matching DepositInfo.balanceDueCents.
Presentation:
- CustomOrderFormPage — sectioned intake (customer, specification, pricing and
deposit, reference images) over the shared design-system widgets.
- CustomOrderConfirmationPage — order summary, spec rendering, and a deposit
receipt showing amount, method, date, and balance only.
- FulfillmentStatusChip over the design-system KcStatusChip, covering all
seven pipeline values.
- showReferenceImageDialog() plus ReferenceImageDialogResult with URL
validation and de-duplication.
- OrdersPage gains an optional onCreateCustomOrder callback. When null the
"New Custom Order" action is not rendered, so the page stays usable in hosts
that have no intake route.
Hosts:
- kell_web: new /orders/custom route rendering CustomOrderFormPage inside
AppShell, with ordersToCustomOrder() and customOrderToOrders() handoffs on
AppNavigation. Confirmation returns to Orders pre-selecting the new order.
- kell_mobile: new MobileCustomOrderPage, a full-screen SafeArea host for the
shared form, reached from an extended FAB on the orders list. Market intake
is the primary custom-order use case, so mobile gets a dedicated route
rather than an inline panel. The list reloads on return.
Privacy:
- The deposit receipt renders amount, method, date, and balance only. The
transaction ID stays on PaymentResult and is asserted absent from the
rendered confirmation by test. The controller holds no payment identifier at
any point.
Deferred to Stage 11C, recorded in the Stage 11B section:
- Product-base selection from the catalogue; the form captures a free-text
specification instead.
- Platform camera and file-picker capture for reference images; the dialog
accepts validated URLs only.
Validation:
- 146 new tests: 82 on CustomOrderFormController (money parsing, setters,
derived balance and clamping, reference image add/remove/dedupe, the full
validation matrix, buildSpec mapping, submission, quoted vs. collected
deposit, repository failure, duplicate ID, reset), 26 on the form page, 24
on the confirmation page including the no-payment-identifier assertion, 3 on
the OrdersPage entry point, 6 on MobileCustomOrderPage, and 5 on the web
route.
- 2,044/2,044 passing across all 11 packages and apps, up from the 1,898
baseline at 0e3987b, with no regression.
- dart analyze --fatal-infos clean across all packages and apps.
- dart format --line-length 100 clean on every file touched by this slice.
Test-harness note: the intake form is taller than the default 800x600 test
view, so the submit-button tests resize tester.view rather than working around
a layout defect. The page scrolls normally on device.
Toolchain note: kell_web/pubspec.lock picked up SDK-pinned transitive bumps on
flutter pub get (matcher 0.12.19 to 0.12.20, meta 1.18.0 to 1.19.0, test_api
0.7.11 to 0.7.12, vector_math 2.2.0 to 2.4.3). Same accepted class as the
kell_mobile bumps recorded under chore/state-reconciliation-flutter-347;
committed so the lock file matches the toolchain in use.
Closes: P2.2 (intake UI portion)
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.
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.
Mike Kell