docs(blueprint-platform): add restaurant propagation guardrails

docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.md

@@ -0,0 +1,169 @@
+# Stage 44-48 Shared Restaurant Lifecycle Guardrails
+
+## Purpose
+
+This document turns the Stage 44 master plan into an execution guard for Stages 45-48.
+
+Use it before starting any task in the following waves:
+
+- Stage 45: shared restaurant lifecycle domain and persistence backbone
+- Stage 46: restaurant service and BFF orchestration over the shared lifecycle
+- Stage 47: restaurant web integration for organic cross-app flow
+- Stage 48: end-to-end restaurant flow validation and demo hardening
+
+## Stage Baseline
+
+- Active master plan: `plan/2026-03-31-s44-master-shared-restaurant-lifecycle.md`
+- Supporting review: `plan/2026-03-27-review-current-gap.md`
+- Current execution audit: `plan/2026-03-27-audit-task-execution.md`
+
+Default wave choices locked by Stage 44:
+
+- workflow realism before broader feature expansion
+- restaurant integration before remaining furniture depth work
+- operations owns restaurant order and check lifecycle
+- kitchen owns ticket execution state
+- POS eligibility is derived from shared lifecycle state, not isolated UI actions
+
+## Architecture Constraints
+
+The workspace remains locked to:
+
+```text
+Blueprint -> BuildingBlock -> Domain -> DAL -> Service -> BFF
+```
+
+Execution safety rules:
+
+- no cross-repo `ProjectReference`
+- no repo may reference `legacy/`
+- BFF repos talk only to Service repos
+- Service repos must not depend on BFF repos
+- DAL repos must not depend on Service or BFF repos
+- Identity ownership remains inside Thalos
+- restaurant apps must share workflow state through service and domain contracts, not through UI-local projection
+
+Before any implementation task is closed:
+
+1. validate dependency direction against `rules/15-workspace-dependency-graph.md`
+2. validate no cross-repo `ProjectReference` was introduced
+3. confirm docs were updated in the same repo as the code change
+4. confirm any remaining demo-bounded limitation is documented explicitly
+
+## Wave Dependency Order
+
+The default flow for the Stage 45-48 task graph is:
+
+1. `ARC-WORKSPACE-GUARD-1000`
+2. domain backbone:
+   - `DOM-OPERATIONS-DOMAIN-1000`
+   - `DOM-KITCHEN-DOMAIN-1000`
+3. persistence backbone:
+   - `ARC-OPERATIONS-DAL-1010`
+   - `ARC-KITCHEN-DAL-1010`
+4. orchestration layer:
+   - `ARC-OPERATIONS-SERVICE-1020`
+   - `ARC-KITCHEN-SERVICE-1020`
+5. restaurant BFF integration:
+   - `ARC-WAITER-FLOOR-BFF-1030`
+   - `ARC-CUSTOMER-ORDERS-BFF-1030`
+   - `ARC-KITCHEN-OPS-BFF-1030`
+   - `ARC-POS-TRANSACTIONS-BFF-1030`
+6. restaurant web integration:
+   - `WEB-WAITER-FLOOR-WEB-1040`
+   - `WEB-CUSTOMER-ORDERS-WEB-1040`
+   - `WEB-KITCHEN-OPS-WEB-1040`
+   - `WEB-POS-TRANSACTIONS-WEB-1040`
+7. `ARC-RESTAURANT-DEMO-FLOW-1050`
+
+`DependsOn` remains authoritative when a task file is more specific than this summary.
+
+## Shared Restaurant Lifecycle Boundary
+
+The canonical restaurant flow for this wave is:
+
+`Draft -> Submitted -> Accepted -> InKitchen -> Preparing -> Ready -> Served -> Payable -> Paid`
+
+Ownership of the lifecycle is split deliberately:
+
+- `operations-domain`: order, check, eligibility, and status history rules
+- `kitchen-domain`: ticket and work-item transition rules
+- `operations-service`: orchestration of customer and waiter entry points plus payment eligibility
+- `kitchen-service`: orchestration of ticket progression and completion feedback
+- restaurant BFF/web repos: role-specific views and actions only
+
+This means:
+
+- waiter and customer apps must converge on the same order identity
+- kitchen must progress tickets linked to that order identity
+- POS must operate only on payable state derived from the shared lifecycle
+
+## Validation Gates
+
+### Gate A: Stage 45
+
+Before Stage 46 starts:
+
+- lifecycle ownership is documented in `operations-domain` and `kitchen-domain`
+- persistence tasks are ready to implement against explicit lifecycle contracts
+- no repo bypasses Domain ownership while introducing persistence
+
+### Gate B: Stage 46
+
+Before Stage 47 starts:
+
+- `operations-service` and `kitchen-service` build and test successfully
+- waiter, customer, kitchen, and POS BFF routes are backed by shared-lifecycle service behavior
+- service docs explain any remaining demo limitations clearly
+
+### Gate C: Stage 47
+
+Before Stage 48 starts:
+
+- waiter-floor, customer-orders, kitchen-ops, and POS web repos pass container-first validation
+- shared identifiers and lifecycle states are visible in the role-specific UIs
+- the apps reflect one workflow rather than isolated status projections
+
+### Gate D: Stage 48
+
+Wave completion requires:
+
+- the deployed restaurant demo proves an order can move from customer or waiter submission into kitchen and then into POS eligibility
+- docs and runbooks are updated in every touched repo
+- no stale `.repo-tasks/active` entries remain from Stage 45-48 work
+
+## Documentation And Comment Rules
+
+Every implementation task in this wave must:
+
+- update repo docs in the same change set
+- add meaningful comments where workflow logic is non-trivial
+- keep commit messages free of task, stage, or AI wording
+
+Web repos additionally must:
+
+- validate using container-first test and build flow
+- document which lifecycle states and actions are visible to the role-specific UI
+
+## Follow-Up Wave
+
+Stage 48 validation exposed a runtime propagation gap that is now tracked by Stage 49.
+
+Continue with:
+
+- `plan/2026-03-31-s49-master-restaurant-propagation-and-runtime-alignment.md`
+- `docs/architecture/stage49-52-restaurant-propagation-guardrails.md`
+
+Use Stage 49 when newly accepted orders do not yet appear consistently across customer, waiter, kitchen, and POS reads in the deployed demo.
+
+## Known Boundaries
+
+This wave expands restaurant workflow realism, not the entire workspace architecture.
+
+That means:
+
+- no new repositories in Stage 45-48
+- no auth provider redesign
+- no furniture feature expansion inside this wave unless a restaurant dependency explicitly forces it
+- no UI-level coordination that bypasses service contracts
+

docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.puml

@@ -0,0 +1,71 @@
+@startuml
+title Stage 44-48 Shared Restaurant Lifecycle Guardrails
+
+skinparam packageStyle rectangle
+skinparam shadowing false
+
+package "Blueprint" {
+  [Workspace Guard]
+}
+
+package "Domain" {
+  [Operations Domain]
+  [Kitchen Domain]
+}
+
+package "DAL" {
+  [Operations DAL]
+  [Kitchen DAL]
+}
+
+package "Service" {
+  [Operations Service]
+  [Kitchen Service]
+}
+
+package "BFF" {
+  [Waiter Floor BFF]
+  [Customer Orders BFF]
+  [Kitchen Ops BFF]
+  [POS Transactions BFF]
+}
+
+package "Web" {
+  [Waiter Floor Web]
+  [Customer Orders Web]
+  [Kitchen Ops Web]
+  [POS Transactions Web]
+}
+
+[Workspace Guard] --> [Operations Domain]
+[Workspace Guard] --> [Kitchen Domain]
+[Operations Domain] --> [Operations DAL]
+[Kitchen Domain] --> [Kitchen DAL]
+[Operations DAL] --> [Operations Service]
+[Kitchen DAL] --> [Kitchen Service]
+[Operations Service] --> [Waiter Floor BFF]
+[Operations Service] --> [Customer Orders BFF]
+[Operations Service] --> [POS Transactions BFF]
+[Kitchen Service] --> [Kitchen Ops BFF]
+[Operations Service] --> [Kitchen Ops BFF]
+[Waiter Floor BFF] --> [Waiter Floor Web]
+[Customer Orders BFF] --> [Customer Orders Web]
+[Kitchen Ops BFF] --> [Kitchen Ops Web]
+[POS Transactions BFF] --> [POS Transactions Web]
+
+note right of [Operations Domain]
+Defines restaurant order/check lifecycle
+and payment eligibility rules.
+end note
+
+note right of [Kitchen Domain]
+Defines kitchen ticket progression
+linked to restaurant orders.
+end note
+
+note bottom of [POS Transactions Web]
+UI must only expose payment actions
+for payable lifecycle state.
+end note
+
+@enduml

docs/architecture/stage49-52-restaurant-propagation-guardrails.md

@@ -0,0 +1,137 @@
+# Stage 49-52 Restaurant Propagation Guardrails
+
+## Purpose
+
+This document turns the Stage 49 master plan into an execution guard for Stages 50-52.
+
+Use it before starting any task in the following waves:
+
+- Stage 50: restaurant propagation backend fixes
+- Stage 51: BFF read-model alignment and runtime rollout
+- Stage 52: demo reseed, redeploy, and public-host revalidation
+
+## Stage Baseline
+
+- Active master plan: `plan/2026-03-31-s49-master-restaurant-propagation-and-runtime-alignment.md`
+- Supporting review: `plan/2026-03-27-review-current-gap.md`
+- Current execution audit: `plan/2026-03-27-audit-task-execution.md`
+- Prior restaurant flow validation: `docs/consumption/restaurant-demo-flow-validation.md`
+
+Default wave choices locked by Stage 49:
+
+- runtime propagation realism before additional feature breadth
+- deployed restaurant behavior must match repo state before validation can pass
+- customer, waiter, kitchen, and POS reads must all reflect the same shared lifecycle records
+- deterministic seeds help walkthroughs, but they do not replace live mutation proof
+
+## Architecture Constraints
+
+The workspace remains locked to:
+
+```text
+Blueprint -> BuildingBlock -> Domain -> DAL -> Service -> BFF
+```
+
+Execution safety rules:
+
+- no cross-repo `ProjectReference`
+- no repo may reference `legacy/`
+- BFF repos talk only to Service repos
+- Service repos must not depend on BFF repos
+- DAL repos must not depend on Service or BFF repos
+- runtime rollout must not skip a repo that materially changes lifecycle propagation
+- no summary-only projection may hide a successful shared-lifecycle mutation during Stage 52 validation
+
+Before any implementation task is closed:
+
+1. validate dependency direction against `rules/15-workspace-dependency-graph.md`
+2. validate no cross-repo `ProjectReference` was introduced
+3. confirm docs were updated in the same repo as the code change
+4. confirm any remaining demo limitation is documented explicitly
+
+## Wave Dependency Order
+
+The default flow for the Stage 50-52 task graph is:
+
+1. `ARC-WORKSPACE-GUARD-1100`
+2. backend propagation:
+   - `ARC-OPERATIONS-SERVICE-1110`
+   - `ARC-KITCHEN-SERVICE-1110`
+3. BFF read-model alignment:
+   - `ARC-CUSTOMER-ORDERS-BFF-1120`
+   - `ARC-WAITER-FLOOR-BFF-1120`
+   - `ARC-KITCHEN-OPS-BFF-1120`
+   - `ARC-POS-TRANSACTIONS-BFF-1120`
+4. runtime rollout:
+   - `ARC-RESTAURANT-RUNTIME-ROLLOUT-1130`
+5. deterministic reset and revalidation:
+   - `ARC-RESTAURANT-DEMO-RESEED-1140`
+   - `ARC-RESTAURANT-DEMO-FLOW-1150`
+
+`DependsOn` remains authoritative when a task file is more specific than this summary.
+
+## Propagation Success Criteria
+
+A Stage 52 validation pass is only considered successful when the deployed public demo proves this flow:
+
+1. a customer or waiter submits a new restaurant order
+2. the order becomes visible through customer detail or history
+3. the same order becomes visible to the kitchen board
+4. kitchen progression advances the shared lifecycle
+5. waiter-facing reads reflect the live progression
+6. POS exposes the resulting check only when lifecycle state makes it payable
+
+If any step is still backed by seeded-only or summary-only data, the validation task stays open or blocked.
+
+## Validation Gates
+
+### Gate A: Stage 50
+
+Before Stage 51 starts:
+
+- `operations-service` exposes lifecycle-backed detail and history reads
+- `kitchen-service` exposes ticket visibility for newly accepted orders
+- service docs describe any remaining bounded simplifications explicitly
+
+### Gate B: Stage 51
+
+Before Stage 52 starts:
+
+- customer, waiter, kitchen, and POS BFF reads no longer depend on summary-only fallbacks for the core flow
+- the latest images are published and the deployed restaurant runtime is refreshed together
+- rollout docs distinguish repo state, image state, and deployed state clearly
+
+### Gate C: Stage 52
+
+Wave completion requires:
+
+- public-host validation proves newly accepted orders flow across customer, waiter, kitchen, and POS
+- deterministic seed guidance remains aligned with the actual demo files
+- the Stage 48 blocked finding is explicitly resolved or narrowed with evidence
+- no stale `.repo-tasks/active` entries remain from Stage 49-52 work
+
+## Documentation And Comment Rules
+
+Every implementation task in this wave must:
+
+- update repo docs in the same change set
+- add meaningful comments where propagation logic or fallback removal is non-trivial
+- call out any remaining projection shortcuts clearly in code or docs
+- keep commit messages free of task, stage, or AI wording
+
+Rollout and validation tasks additionally must:
+
+- use the public auth host plus public demo hosts as the primary validation path
+- distinguish deterministic seed walkthroughs from live mutation proof
+- record any runtime drift that would invalidate public conclusions
+
+## Known Boundaries
+
+This wave fixes restaurant propagation and runtime truthfulness, not the whole workspace roadmap.
+
+That means:
+
+- no new repositories in Stage 49-52
+- no auth provider redesign
+- no furniture expansion inside this wave unless restaurant propagation work proves a shared dependency
+- no UI-side workaround that bypasses the service and BFF boundaries

docs/architecture/stage49-52-restaurant-propagation-guardrails.puml

@@ -0,0 +1,52 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam packageStyle rectangle
+
+title Stage 49-52 Restaurant Propagation Guardrails
+
+rectangle "Stage 49\nPlanning Guard" as S49 {
+  [ARC-WORKSPACE-GUARD-1100]
+}
+
+rectangle "Stage 50\nBackend Propagation" as S50 {
+  [ARC-OPERATIONS-SERVICE-1110]
+  [ARC-KITCHEN-SERVICE-1110]
+}
+
+rectangle "Stage 51\nBFF Alignment + Rollout" as S51 {
+  [ARC-CUSTOMER-ORDERS-BFF-1120]
+  [ARC-WAITER-FLOOR-BFF-1120]
+  [ARC-KITCHEN-OPS-BFF-1120]
+  [ARC-POS-TRANSACTIONS-BFF-1120]
+  [ARC-RESTAURANT-RUNTIME-ROLLOUT-1130]
+}
+
+rectangle "Stage 52\nReset + Validation" as S52 {
+  [ARC-RESTAURANT-DEMO-RESEED-1140]
+  [ARC-RESTAURANT-DEMO-FLOW-1150]
+}
+
+[ARC-WORKSPACE-GUARD-1100] --> [ARC-OPERATIONS-SERVICE-1110]
+[ARC-WORKSPACE-GUARD-1100] --> [ARC-KITCHEN-SERVICE-1110]
+[ARC-OPERATIONS-SERVICE-1110] --> [ARC-KITCHEN-SERVICE-1110]
+
+[ARC-OPERATIONS-SERVICE-1110] --> [ARC-CUSTOMER-ORDERS-BFF-1120]
+[ARC-OPERATIONS-SERVICE-1110] --> [ARC-WAITER-FLOOR-BFF-1120]
+[ARC-KITCHEN-SERVICE-1110] --> [ARC-KITCHEN-OPS-BFF-1120]
+[ARC-OPERATIONS-SERVICE-1110] --> [ARC-POS-TRANSACTIONS-BFF-1120]
+[ARC-KITCHEN-SERVICE-1110] --> [ARC-POS-TRANSACTIONS-BFF-1120]
+
+[ARC-CUSTOMER-ORDERS-BFF-1120] --> [ARC-RESTAURANT-RUNTIME-ROLLOUT-1130]
+[ARC-WAITER-FLOOR-BFF-1120] --> [ARC-RESTAURANT-RUNTIME-ROLLOUT-1130]
+[ARC-KITCHEN-OPS-BFF-1120] --> [ARC-RESTAURANT-RUNTIME-ROLLOUT-1130]
+[ARC-POS-TRANSACTIONS-BFF-1120] --> [ARC-RESTAURANT-RUNTIME-ROLLOUT-1130]
+
+[ARC-RESTAURANT-RUNTIME-ROLLOUT-1130] --> [ARC-RESTAURANT-DEMO-RESEED-1140]
+[ARC-RESTAURANT-DEMO-RESEED-1140] --> [ARC-RESTAURANT-DEMO-FLOW-1150]
+
+note bottom
+Validation only passes when a newly accepted order propagates across
+customer, waiter, kitchen, and POS through the deployed public demo hosts.
+end note
+@enduml

docs/architecture/workspace-cross-repo-reference-guard.md

@@ -37,3 +37,5 @@ greenfield/blueprint-platform/tools/validate-no-cross-repo-projectrefs.sh
 
 - `docs/architecture/stage40-43-execution-guardrails.md`
 - `docs/architecture/stage40-43-execution-guardrails.puml`
+- `docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.md`
+- `docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.puml`

docs/consumption/restaurant-demo-flow-validation.md

@@ -0,0 +1,58 @@
+# Restaurant Demo Flow Validation
+
+## Scope
+
+This document records the Stage 48 validation pass for the deployed restaurant demo hosted behind the public `dream-views.com` demo domains.
+
+## Validated On
+
+- Date: `2026-03-31`
+- Auth entrypoint: `https://auth.dream-views.com`
+- Demo hosts:
+  - `https://waiter-floor-demo.dream-views.com`
+  - `https://customer-orders-demo.dream-views.com`
+  - `https://kitchen-ops-demo.dream-views.com`
+  - `https://pos-transactions-demo.dream-views.com`
+
+## Confirmed Working
+
+- Public Thalos session login and cookie-backed session validation work through the public host path.
+- The four restaurant web apps serve the updated lifecycle-oriented SPA bundles.
+- Public routes for waiter, customer, kitchen, and POS demos return `200`.
+- UI copy now describes the intended restaurant flow:
+  - order accepted
+  - kitchen preparation
+  - ready for handoff
+  - served and payable
+  - payment captured
+
+## Important Runtime Note
+
+- Session cookies are scoped to the public `dream-views.com` hosts.
+- Validation against `127.0.0.1` BFF ports will not accurately exercise the deployed session behavior because those cookies do not round-trip on localhost.
+- End-to-end validation for the deployed demo should use the public auth host plus the public demo hosts.
+
+## Current Limitation
+
+The deployed demo still does not fully propagate a newly submitted order through the shared restaurant lifecycle:
+
+- `POST /api/customer/orders` accepts a new order and returns success.
+- The same order is not yet visible in customer detail queries.
+- The order does not appear on the kitchen board.
+- Waiter activity does not reflect the new order.
+- POS summary does not expose that order as newly payable.
+
+This means the public SPAs now describe a connected flow more clearly, but the runtime still contains static or partially projected demo read models that do not fully reflect live mutations.
+
+## Recommended Follow-Up
+
+The blocked Stage 48 finding now rolls into Stage 49:
+
+- `plan/2026-03-31-s49-master-restaurant-propagation-and-runtime-alignment.md`
+- `docs/architecture/stage49-52-restaurant-propagation-guardrails.md`
+
+Execution focus:
+
+- replace remaining static or summary-only restaurant read projections with lifecycle-backed projections sourced from the shared operations and kitchen stores
+- redeploy aligned restaurant runtime images before re-validating the public demo
+- keep the seeded PostgreSQL data as deterministic walkthrough material, not as proof of the runtime mutation path