diff --git a/docs/architecture/stage40-43-execution-guardrails.md b/docs/architecture/stage40-43-execution-guardrails.md new file mode 100644 index 0000000..f1af464 --- /dev/null +++ b/docs/architecture/stage40-43-execution-guardrails.md @@ -0,0 +1,135 @@ +# Stage 40-43 Execution Guardrails + +## Purpose + +This document turns the Stage 39 master plan into an execution guard for Stages 40-43. + +Use it before starting any task in the following waves: + +- Stage 40: ops source-of-truth sync and Thalos auth hardening +- Stage 41: restaurant backend and restaurant web workflow depth +- Stage 42: furniture backend and furniture web workflow depth +- Stage 43: end-to-end demo validation and completion hardening + +## Stage Baseline + +- Active master plan: `plan/2026-03-27-s39-master-spa-depth-and-ops-hardening.md` +- Guiding 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 39: + +- balanced hardening +- restaurant-first execution +- manual or simulated login stays dev-only and must be hidden from production UX + +## 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 +- Identity ownership remains inside Thalos + +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 + +## Wave Dependency Order + +The default flow for the Stage 40-43 task graph is: + +1. `ARC-WORKSPACE-GUARD-900` +2. `ARC-DEMO-SOURCE-OF-TRUTH-910` +3. `SEC-THALOS-SERVICE-900` +4. `SEC-THALOS-BFF-900` +5. `WEB-THALOS-WEB-900` +6. `ARC-OPERATIONS-SERVICE-920` +7. `ARC-KITCHEN-SERVICE-920` +8. restaurant BFF tasks: + - `ARC-WAITER-FLOOR-BFF-930` + - `ARC-CUSTOMER-ORDERS-BFF-930` + - `ARC-KITCHEN-OPS-BFF-930` + - `ARC-POS-TRANSACTIONS-BFF-930` + - `ARC-RESTAURANT-ADMIN-BFF-930` +9. restaurant web tasks: + - `WEB-WAITER-FLOOR-WEB-940` + - `WEB-CUSTOMER-ORDERS-WEB-940` + - `WEB-KITCHEN-OPS-WEB-940` + - `WEB-POS-TRANSACTIONS-WEB-940` + - `WEB-RESTAURANT-ADMIN-WEB-940` +10. furniture workflow depth: + - `ARC-FURNITURE-SERVICE-950` + - `ARC-FURNITURE-BFF-960` + - `WEB-FURNITURE-WEB-970` +11. `ARC-DEMO-VALIDATION-980` + +`DependsOn` remains authoritative when a task file is more specific than this summary. + +## Validation Gates + +### Gate A: Stage 40 + +Before Stage 41 starts: + +- Portainer, Caddy, Vault, and demo source-of-truth ownership is documented +- Thalos auth hardening tasks are completed +- Thalos web production auth UX is documented as canonical + +### Gate B: Stage 41 + +Before Stage 42 starts: + +- `operations-service` and `kitchen-service` build and test successfully +- restaurant BFF contracts expose the required workflow routes +- every restaurant web repo passes container-first build and test validation + +### Gate C: Stage 42 + +Before Stage 43 starts: + +- `furniture-service` and `furniture-bff` build and test successfully +- `furniture-web` no longer relies on local reservation projection +- furniture web passes container-first build and test validation + +### Gate D: Stage 43 + +Wave completion requires: + +- authenticated demo flows validated on deployed hosts +- docs and runbooks updated in every touched repo +- no stale `.repo-tasks/active` entries left from Stage 40-43 work + +## Documentation And Comment Rules + +Every implementation task in this wave must: + +- update repo docs in the same change set +- add meaningful comments where logic is non-trivial +- keep commit messages free of task/stage/AI wording + +Web repos additionally must: + +- validate using container-first test/build flow +- keep auth/session behavior aligned with deployed host routing + +## Known Boundaries + +This wave expands workflow depth, not architecture shape. + +That means: + +- no new repos in Stage 40-43 +- no auth provider expansion beyond the current Google path +- no DAL or persistence redesign unless a task explicitly requires it to unblock a defined workflow +- no UI work that bypasses BFF ownership boundaries diff --git a/docs/architecture/stage40-43-execution-guardrails.puml b/docs/architecture/stage40-43-execution-guardrails.puml new file mode 100644 index 0000000..a4d4a1c --- /dev/null +++ b/docs/architecture/stage40-43-execution-guardrails.puml @@ -0,0 +1,59 @@ +@startuml +title Stage 40-43 Execution Guardrails + +skinparam monochrome true +skinparam shadowing false + +rectangle "Stage 40" as S40 { + component "ARC-WORKSPACE-GUARD-900" as G900 + component "ARC-DEMO-SOURCE-OF-TRUTH-910" as D910 + component "SEC-THALOS-SERVICE-900" as TS900 + component "SEC-THALOS-BFF-900" as TB900 + component "WEB-THALOS-WEB-900" as TW900 +} + +rectangle "Stage 41" as S41 { + component "ARC-OPERATIONS-SERVICE-920" as OS920 + component "ARC-KITCHEN-SERVICE-920" as KS920 + component "Restaurant BFF Tasks" as RBFF930 + component "Restaurant Web Tasks" as RWEB940 +} + +rectangle "Stage 42" as S42 { + component "ARC-FURNITURE-SERVICE-950" as FS950 + component "ARC-FURNITURE-BFF-960" as FB960 + component "WEB-FURNITURE-WEB-970" as FW970 +} + +rectangle "Stage 43" as S43 { + component "ARC-DEMO-VALIDATION-980" as DV980 +} + +G900 --> D910 +G900 --> TS900 +TS900 --> TB900 +TB900 --> TW900 + +TB900 --> OS920 +TB900 --> KS920 + +OS920 --> RBFF930 +KS920 --> RBFF930 +RBFF930 --> RWEB940 +TW900 --> RWEB940 + +TB900 --> FS950 +FS950 --> FB960 +FB960 --> FW970 +TW900 --> FW970 + +D910 --> DV980 +RWEB940 --> DV980 +FW970 --> DV980 + +note bottom +DependsOn in each task file is authoritative. +This diagram is the planning guardrail summary. +end note + +@enduml diff --git a/docs/architecture/workspace-cross-repo-reference-guard.md b/docs/architecture/workspace-cross-repo-reference-guard.md index 8341fc0..d16f1b2 100644 --- a/docs/architecture/workspace-cross-repo-reference-guard.md +++ b/docs/architecture/workspace-cross-repo-reference-guard.md @@ -32,3 +32,8 @@ greenfield/blueprint-platform/tools/validate-no-cross-repo-projectrefs.sh - Execute this guard before merge to `development`. - Keep only intra-repo `ProjectReference` entries. - Use package references for cross-repo consumption. + +## Related Governance Docs + +- `docs/architecture/stage40-43-execution-guardrails.md` +- `docs/architecture/stage40-43-execution-guardrails.puml` diff --git a/docs/consumption/demo-auth-routing-runbook.md b/docs/consumption/demo-auth-routing-runbook.md index c3c940f..335072c 100644 --- a/docs/consumption/demo-auth-routing-runbook.md +++ b/docs/consumption/demo-auth-routing-runbook.md @@ -8,6 +8,10 @@ This runbook defines the centralized login routing contract used by demo environ - Session endpoints are routed through Thalos (`auth.dream-views.com` and identity API paths). - Domain BFF APIs remain host-scoped by path. +Related runtime ownership reference: + +- `docs/consumption/demo-runtime-source-of-truth.md` + ## Active Public Hosts | Host | Role | @@ -74,4 +78,5 @@ All web containers must provide: 2. Validate Caddy config before reload. 3. Reload Caddy. 4. Run demo auth-routing validation checklist (see `docs/consumption/demo-auth-routing-validation.md`). -5. Record route changes in this runbook in the same change set. +5. Confirm the updated route behavior still matches `docs/consumption/demo-runtime-source-of-truth.md`. +6. Record route changes in this runbook in the same change set. diff --git a/docs/consumption/demo-runtime-source-of-truth.md b/docs/consumption/demo-runtime-source-of-truth.md new file mode 100644 index 0000000..ac2c600 --- /dev/null +++ b/docs/consumption/demo-runtime-source-of-truth.md @@ -0,0 +1,120 @@ +# Demo Runtime Source Of Truth + +## Purpose + +This document defines which system is authoritative for demo runtime behavior, how repo docs relate to deployed state, and how to validate or change that state safely. + +The goal is to remove ambiguity between: + +- Portainer stack definitions +- VPS Caddy site files +- Vault runtime and bootstrap material +- repo-owned runbooks and planning documents + +## Ownership Model + +The source-of-truth model is split by concern. + +| Concern | Canonical Source | Live Materialization | Validation Path | +|---|---|---|---| +| Wave intent and execution order | `plan/2026-03-27-s39-master-spa-depth-and-ops-hardening.md` | N/A | Confirm task graph and plan links | +| Demo routing contract | `docs/consumption/demo-auth-routing-runbook.md` | Caddy site files on VPS | Validate hosts, path routing, and auth flow behavior | +| Demo container composition | Portainer stack definitions for demo stacks | Running Docker containers on VPS | Validate stack config against docs and deployed services | +| Secret operations and recovery | `general_information/Vault.md` | Vault host paths and `core-vault` container | Validate unseal, health, and expected secret paths | +| Registry endpoints and publication targets | `general_information/Gitea.md` | Gitea package and registry services | Validate package/image endpoints and login/pull paths | +| Cross-repo dependency safety | `docs/architecture/workspace-cross-repo-reference-guard.md` | `.csproj` graph in workspace | Run `tools/validate-no-cross-repo-projectrefs.sh` | + +## Canonical Interpretation Rules + +Use the following rules when repo docs and runtime state disagree: + +1. Planning files define intended execution order and scope. +2. Repo runbooks define the expected runtime contract for routing, validation, and operational ownership. +3. Portainer and Caddy define the actual deployed runtime and must be reconciled back to the repo runbooks. +4. Vault operational recovery steps remain owned by `general_information/Vault.md` until a repo-owned ops runbook replaces them. +5. Gitea publication endpoints remain owned by `general_information/Gitea.md` until a repo-owned publication runbook replaces them. + +This means: + +- repo docs are canonical for expected behavior +- deployed systems are authoritative for current runtime +- any mismatch must be documented and reconciled, not silently accepted + +## Required Change Order + +When changing demo runtime behavior, use this order: + +1. Update the relevant repo docs first. +2. Apply runtime changes in the owning platform: + - Portainer for demo stacks + - Caddy for ingress and host routing + - Vault for runtime secret operations +3. Validate deployed behavior against the updated docs. +4. Record any recovery or rollback notes in the same repo-owned runbook. + +## Current Runtime Boundaries + +### Portainer + +Portainer owns: + +- demo stack definitions +- container image references +- environment variable and mount bindings at stack level + +Portainer does not own: + +- public hostnames +- Caddy route logic +- application behavior contracts + +### Caddy + +Caddy owns: + +- public hostnames +- reverse proxy path routing +- auth host and demo host ingress behavior + +Caddy does not own: + +- app container composition +- secret values +- application workflow semantics + +### Vault + +Vault owns: + +- secret storage +- seal and unseal lifecycle +- bootstrap and recovery material + +Vault does not own: + +- auth UX behavior +- route ownership +- application feature flags outside secret-backed configuration + +## Validation Checklist + +Before closing any runtime or auth-alignment task: + +- Confirm the active plan and mini plan still match the intended work. +- Confirm Portainer stacks match the documented demo service layout. +- Confirm Caddy host and path routing match the documented auth and demo routing contract. +- Confirm Vault paths and operations notes still match the expected runtime secret behavior. +- Confirm no cross-repo `ProjectReference` violations were introduced while adjusting repo docs or validation scripts. + +## Rollback Principle + +Rollback is not automatic. + +If runtime validation fails: + +1. stop at the system that drifted +2. restore the last known-good runtime configuration in that system +3. update the repo runbook if the rollback exposed undocumented behavior + +Do not treat repo docs and deployed systems as independent sources of truth. +They must converge after every runtime-facing change. diff --git a/docs/consumption/secret-provider-rollout.md b/docs/consumption/secret-provider-rollout.md index 1918660..db72129 100644 --- a/docs/consumption/secret-provider-rollout.md +++ b/docs/consumption/secret-provider-rollout.md @@ -32,3 +32,11 @@ The default fallback returns unresolved lookups and never introduces provider-sp - Stage 33 keeps this contract-only baseline. - Concrete Vault/OIDC provider integration should be implemented in infrastructure/runtime layers only. - Existing identity logic ownership remains in Thalos repositories. + +## Runtime Ownership Note + +Provider contract ownership and runtime operational ownership are separate concerns. + +- Contract ownership for provider-agnostic secret access remains in Blueprint and consuming repos. +- Vault runtime ownership, bootstrap, and recovery operations currently remain documented in `general_information/Vault.md`. +- Demo runtime reconciliation guidance is documented in `docs/consumption/demo-runtime-source-of-truth.md`.