diff --git a/docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.md b/docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.md new file mode 100644 index 0000000..d21040e --- /dev/null +++ b/docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.md @@ -0,0 +1,158 @@ +# 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 + +## 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 + diff --git a/docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.puml b/docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.puml new file mode 100644 index 0000000..bdd14ef --- /dev/null +++ b/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 diff --git a/docs/architecture/workspace-cross-repo-reference-guard.md b/docs/architecture/workspace-cross-repo-reference-guard.md index d16f1b2..5d0e364 100644 --- a/docs/architecture/workspace-cross-repo-reference-guard.md +++ b/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`