docs(blueprint-platform): add stage 40 workspace guardrails
This commit is contained in:
José René White Enciso
parent
e65d681245
commit
57c406302b
135
docs/architecture/stage40-43-execution-guardrails.md
Normal file
135
docs/architecture/stage40-43-execution-guardrails.md
Normal file
@ -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
|
||||
59
docs/architecture/stage40-43-execution-guardrails.puml
Normal file
59
docs/architecture/stage40-43-execution-guardrails.puml
Normal file
@ -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
|
||||
@ -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`
|
||||
|
||||
@ -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.
|
||||
|
||||
120
docs/consumption/demo-runtime-source-of-truth.md
Normal file
120
docs/consumption/demo-runtime-source-of-truth.md
Normal file
@ -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.
|
||||
@ -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`.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user