Skip to content

Commit 66e943c

Browse files
author
DavidQ
committed
Adds deploy documentation and operator handoff guidance for Docker deployment flow.
BUILD_PR_LEVEL_09_32_DEPLOY_DOCUMENTATION_AND_HANDOFF
1 parent 32a2638 commit 66e943c

8 files changed

Lines changed: 169 additions & 62 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,10 @@ MODEL: GPT-5.4
22
REASONING: high
33

44
COMMAND:
5-
- implement deploy monitoring/ops layer
6-
- add post-deploy verification checks
7-
- standardize logging and operator messaging
8-
- define rollback/abort expectations where practical
9-
- keep deploy work under scripts/PS/deploy/
5+
- create deploy documentation covering full flow
6+
- include usage examples for scripts/PS/deploy/
7+
- include dry-run and validation usage
8+
- include monitoring + rollback guidance
109
- commit format:
1110
description first line
1211
PR name last line

‎docs/dev/CODEX_WEBSITE_REPO_DEPLOYMENT_SCRIPTING.md‎

Lines changed: 124 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,155 @@
11
# Codex Website Repo Deployment Scripting
22

3-
Use these scripts from `scripts/PS/deploy/` to stage repo content for website deployment with safe defaults and Docker compatibility artifacts.
3+
This document is the operator handoff for the Docker-based website staging flow under `scripts/PS/deploy/`.
44

5-
## Scripts
5+
## Script Roles
66
- `scripts/PS/deploy/Prep-WebsiteRepoDeployment.ps1`
7+
- prepares staging folders
8+
- writes plan + docker artifacts
79
- `scripts/PS/deploy/Update-WebsiteRepoDeployment.ps1`
10+
- refreshes staged site content
11+
- runs post-deploy verification by default
12+
- supports controlled rollback behavior
813
- `scripts/PS/deploy/Clean-WebsiteRepoDeployment.ps1`
14+
- removes staged output
15+
- optionally removes metadata + ops artifacts
916

1017
## Safety Defaults
11-
- All scripts default to dry-run mode.
12-
- No files are written or deleted unless `-Apply` is provided.
13-
- `-DryRun` is available explicitly on each script.
14-
- Clean operations are restricted to staging paths under `<repo>/tmp`.
18+
- scripts default to dry-run when `-Apply` is not provided
19+
- destructive paths require explicit confirmation (`-ConfirmDestructive`)
20+
- staging is restricted under `<repo>/tmp`
21+
- update verification failures abort by default
1522

16-
## Typical Flow
17-
Prepare staging plan and Docker artifacts:
23+
## Config Contract
24+
Config precedence is:
25+
1. explicit script parameters
26+
2. `.env` (or `-EnvFilePath`)
27+
3. built-in defaults
28+
29+
Normalized deploy env names:
30+
- `DEPLOY_STAGING_ROOT`
31+
- `DEPLOY_INCLUDE_PATHS`
32+
- `DEPLOY_REMOVE_METADATA`
33+
- `DEPLOY_WEB_PORT`
34+
35+
Legacy aliases are still accepted with warning logs:
36+
- `STAGING_ROOT`, `INCLUDE_PATHS`, `REMOVE_METADATA`, `PORT`
37+
38+
## Full Flow (Quick Start)
39+
1. Validate script structure placement:
40+
41+
```powershell
42+
.\scripts\PS\validate\Validate-ScriptStructure.ps1
43+
```
44+
45+
2. Preview prep plan:
46+
47+
```powershell
48+
.\scripts\PS\deploy\Prep-WebsiteRepoDeployment.ps1 -DryRun
49+
```
50+
51+
3. Apply prep:
1852

1953
```powershell
2054
.\scripts\PS\deploy\Prep-WebsiteRepoDeployment.ps1 -Apply
2155
```
2256

23-
Update staged website content:
57+
4. Preview update:
58+
59+
```powershell
60+
.\scripts\PS\deploy\Update-WebsiteRepoDeployment.ps1 -DryRun
61+
```
62+
63+
5. Apply update with explicit destructive confirmation:
2464

2565
```powershell
26-
.\scripts\PS\deploy\Update-WebsiteRepoDeployment.ps1 -Apply
66+
.\scripts\PS\deploy\Update-WebsiteRepoDeployment.ps1 -Apply -ConfirmDestructive
2767
```
2868

29-
Clean staged site output only:
69+
6. Preview cleanup:
70+
71+
```powershell
72+
.\scripts\PS\deploy\Clean-WebsiteRepoDeployment.ps1 -DryRun
73+
```
74+
75+
7. Apply cleanup with metadata removal:
76+
77+
```powershell
78+
.\scripts\PS\deploy\Clean-WebsiteRepoDeployment.ps1 -Apply -ConfirmDestructive -RemoveMetadata
79+
```
80+
81+
## Example Using `.env`
82+
Example `tmp/deploy.env`:
83+
84+
```dotenv
85+
DEPLOY_STAGING_ROOT=tmp/website-deploy-ops
86+
DEPLOY_INCLUDE_PATHS=index.html,src,tools
87+
DEPLOY_WEB_PORT=9090
88+
DEPLOY_REMOVE_METADATA=true
89+
```
90+
91+
Use it across all scripts:
92+
93+
```powershell
94+
.\scripts\PS\deploy\Prep-WebsiteRepoDeployment.ps1 -EnvFilePath tmp/deploy.env -Apply
95+
.\scripts\PS\deploy\Update-WebsiteRepoDeployment.ps1 -EnvFilePath tmp/deploy.env -Apply -ConfirmDestructive
96+
.\scripts\PS\deploy\Clean-WebsiteRepoDeployment.ps1 -EnvFilePath tmp/deploy.env -Apply -ConfirmDestructive
97+
```
98+
99+
## Dry-Run + Validation Usage
100+
Dry-run every stage first:
101+
102+
```powershell
103+
.\scripts\PS\deploy\Prep-WebsiteRepoDeployment.ps1 -EnvFilePath tmp/deploy.env -DryRun
104+
.\scripts\PS\deploy\Update-WebsiteRepoDeployment.ps1 -EnvFilePath tmp/deploy.env -DryRun
105+
.\scripts\PS\deploy\Clean-WebsiteRepoDeployment.ps1 -EnvFilePath tmp/deploy.env -DryRun
106+
```
107+
108+
Post-deploy verification output (after update apply):
109+
- `tmp/<staging>/meta/website-deploy-last-verify.json`
110+
111+
Expected quick checks:
112+
- `passed` is `true`
113+
- `failedCheckCount` is `0`
114+
- required include paths exist under staged `site/`
115+
116+
## Monitoring + Ops Artifacts
117+
Deploy scripts emit:
118+
- state file: `meta/website-deploy-ops-state.json`
119+
- event log: `meta/website-deploy-ops-log.jsonl`
120+
- verification report: `meta/website-deploy-last-verify.json`
121+
122+
Use these for operator triage:
123+
- last known stage/status: `website-deploy-ops-state.json`
124+
- chronological events: `website-deploy-ops-log.jsonl`
125+
- verification gate result: `website-deploy-last-verify.json`
126+
127+
## Rollback / Abort Expectations
128+
- default behavior on verification failure:
129+
- update operation aborts
130+
- failure details are written to verify report + ops logs
131+
- optional rollback mode:
132+
- pass `-RollbackOnVerificationFailure`
133+
- requires `-ConfirmDestructive`
134+
- rollback uses cleanup of staged artifacts
135+
136+
Example:
30137

31138
```powershell
32-
.\scripts\PS\deploy\Clean-WebsiteRepoDeployment.ps1 -Apply
139+
.\scripts\PS\deploy\Update-WebsiteRepoDeployment.ps1 -Apply -ConfirmDestructive -RollbackOnVerificationFailure
33140
```
34141

35-
Clean staged site output plus metadata and Docker files:
142+
Skip verification only when explicitly needed:
36143

37144
```powershell
38-
.\scripts\PS\deploy\Clean-WebsiteRepoDeployment.ps1 -RemoveMetadata -Apply
145+
.\scripts\PS\deploy\Update-WebsiteRepoDeployment.ps1 -Apply -ConfirmDestructive -SkipPostDeployVerification
39146
```
40147

41-
## Outputs
148+
## Output Locations
42149
- default staging root: `tmp/website-deploy/`
43-
- staged content root: `tmp/website-deploy/site/`
150+
- staged site root: `tmp/website-deploy/site/`
44151
- metadata root: `tmp/website-deploy/meta/`
45-
- `website-deploy-plan.json`
46-
- `website-deploy-last-update.json`
47-
- docker compatibility files in `tmp/website-deploy/`
152+
- docker artifacts:
48153
- `Dockerfile`
49154
- `docker-compose.yml`
50155
- `.dockerignore`

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,2 @@
1-
Adds a meaningful deploy-operations layer with post-deploy verification, monitoring/logging expectations, clearer operator messaging, and rollback/abort guidance so the Docker deployment flow is easier to validate and run.
2-
3-
BUILD_PR_LEVEL_09_31_DEPLOY_MONITORING_AND_OPERATIONS
1+
Add full deploy operator handoff documentation with script examples, dry-run/validation workflows, monitoring artifacts, and rollback/abort guidance.
2+
BUILD_PR_LEVEL_09_32_DEPLOY_DOCUMENTATION_AND_HANDOFF

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
BUILD_PR_LEVEL_09_32_DEPLOY_DOCUMENTATION_AND_HANDOFF
1+
BUILD_PR_LEVEL_10_01_TRANSITION_TO_NEXT_PHASE

‎docs/dev/reports/change_summary.txt‎

Lines changed: 14 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,20 @@
1-
BUILD_PR_LEVEL_09_31_DEPLOY_MONITORING_AND_OPERATIONS
1+
BUILD_PR_LEVEL_09_32_DEPLOY_DOCUMENTATION_AND_HANDOFF
22

33
Scope:
4-
- Implemented a deploy monitoring/ops layer under `scripts/PS/deploy/`.
5-
- Added post-deploy verification checks and standardized operator-facing messaging.
6-
- Defined practical rollback/abort behavior in update flow.
4+
- Docs-only deploy lane finalization and operator handoff.
5+
- No engine/runtime/tool UI/script behavior changes.
76

87
Implemented:
9-
- `WebsiteRepoDeploymentCommon.ps1`
10-
- Added ops artifacts to deployment paths:
11-
- `meta/website-deploy-last-verify.json`
12-
- `meta/website-deploy-ops-log.jsonl`
13-
- `meta/website-deploy-ops-state.json`
14-
- Added reusable ops helpers:
15-
- `Write-DeployOpsEvent`
16-
- `Write-DeployOpsState`
17-
- `Get-WebsiteDeploymentVerificationResult`
18-
- `Prep-WebsiteRepoDeployment.ps1`
19-
- Added start/success ops state/event writes around staging preparation.
20-
- `Update-WebsiteRepoDeployment.ps1`
21-
- Added post-deploy verification stage after apply.
22-
- Emits verification report JSON.
23-
- Aborts on verification failure with explicit operator guidance.
24-
- Supports practical rollback behavior with `-RollbackOnVerificationFailure`.
25-
- Enforces rollback safety by requiring `-ConfirmDestructive` when rollback is requested.
26-
- `Clean-WebsiteRepoDeployment.ps1`
27-
- Includes new ops/verify artifacts in metadata cleanup path.
28-
- Adds cleanup stage ops state/event writes.
8+
- Expanded `docs/dev/CODEX_WEBSITE_REPO_DEPLOYMENT_SCRIPTING.md` to document:
9+
- full deploy flow across prep/update/clean scripts
10+
- script usage examples under `scripts/PS/deploy/`
11+
- `.env` config usage and normalized `DEPLOY_*` variables
12+
- dry-run workflow and validation usage
13+
- monitoring artifacts (`ops-state`, `ops-log`, `last-verify`)
14+
- rollback/abort expectations with practical command examples
15+
- Updated commit comment to required format:
16+
- description on first line
17+
- PR identifier on last line
2918

3019
Outcome:
31-
- Deploy scripts now expose a consistent operational trail (state + event log + verify report),
32-
with standardized success/failure messaging and practical rollback/abort expectations.
20+
- Deploy lane now has a clear, end-to-end operator runbook aligned to the current deploy script surface.

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
1-
[x] PowerShell parse/readiness checks pass on touched deploy scripts
2-
[x] Update apply path emits post-deploy verification report and verification passes in smoke run
3-
[x] Ops monitoring artifacts are generated (`ops-log`, `ops-state`, `last-verify`) during deploy flow
4-
[x] Operator messaging standardized for stage start/success/failure/next-step outputs
5-
[x] Rollback guard enforced: `-RollbackOnVerificationFailure` requires `-ConfirmDestructive`
6-
[x] Metadata cleanup removes ops/verify artifacts when `DEPLOY_REMOVE_METADATA=true`
7-
[x] Script structure validation smoke run passes
1+
[x] Deploy documentation covers full prep/update/clean flow
2+
[x] Usage examples included for scripts under `scripts/PS/deploy/`
3+
[x] Dry-run and validation usage documented
4+
[x] Monitoring artifacts and operator triage guidance documented
5+
[x] Rollback/abort expectations documented with command examples
6+
[x] Commit comment format matches requirement (description first line, PR name last line)
87
[x] Roadmap updated with status-only change

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -626,7 +626,7 @@
626626
- [.] continue exact-cluster shared extraction until the current lane reaches a stable stop point
627627
- [x] finish active promotion-gate lane enough to remove it from half-active status
628628
- [.] convert repo structure normalization into exact move-map BUILDs with explicit validation
629-
- [.] re-baseline this roadmap after active execution lanes stabilize
629+
- [x] re-baseline this roadmap after active execution lanes stabilize
630630
- [x] split future implementation into small dependency-ordered PRs
631631
- [ ] avoid broad repo-wide cleanup passes until the active lanes above are materially further along
632632

‎docs/pr/BUILD_PR_LEVEL_09_32_DEPLOY_DOCUMENTATION_AND_HANDOFF.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# BUILD_PR — LEVEL 09_32 — DEPLOY DOCUMENTATION AND HANDOFF
2+
3+
## Objective
4+
Finalize deploy lane with clear documentation and operator handoff for Docker-based deployment flow.
5+
6+
## Scope
7+
- document full deploy flow (scripts/PS/deploy)
8+
- document validation + dry-run usage
9+
- document monitoring + rollback expectations
10+
- provide operator quick-start
11+
12+
## Out of Scope
13+
- no runtime changes
14+
- no tool UI changes
15+
16+
## Roadmap Instruction
17+
- update roadmap status only

0 commit comments

Comments
 (0)