diff --git a/docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.md b/docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.md index d21040e..0aa733d 100644 --- a/docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.md +++ b/docs/architecture/stage44-48-shared-restaurant-lifecycle-guardrails.md @@ -145,6 +145,17 @@ 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. diff --git a/docs/architecture/stage49-52-restaurant-propagation-guardrails.md b/docs/architecture/stage49-52-restaurant-propagation-guardrails.md new file mode 100644 index 0000000..bf6ceda --- /dev/null +++ b/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 diff --git a/docs/architecture/stage49-52-restaurant-propagation-guardrails.puml b/docs/architecture/stage49-52-restaurant-propagation-guardrails.puml new file mode 100644 index 0000000..53b5f23 --- /dev/null +++ b/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 diff --git a/docs/consumption/restaurant-demo-flow-validation.md b/docs/consumption/restaurant-demo-flow-validation.md index 45ce9e5..95fbd39 100644 --- a/docs/consumption/restaurant-demo-flow-validation.md +++ b/docs/consumption/restaurant-demo-flow-validation.md @@ -46,6 +46,13 @@ This means the public SPAs now describe a connected flow more clearly, but the r ## Recommended Follow-Up -- Replace remaining static demo projections in restaurant read paths with lifecycle-backed projections sourced from the shared operations and kitchen stores. -- Re-run Stage 48 validation after that propagation work lands. -- Keep the seeded PostgreSQL data as deterministic walkthrough material, not as proof of the runtime mutation path. +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