Adds script safety hardening across Codex/deploy PowerShell automation by enforcing scripts/PS/deploy/ for deployment scripts, scripts/PS/codex/ for codex scripts, dry-run-first behavior, input/path validation, and Docker-compatible staging artifacts.

DavidQ · DavidQ · commit 905b6969de7e · 2026-04-14T11:09:10.000-04:00
BUILD_PR_LEVEL_09_21_SCRIPT_VALIDATION_AND_SAFETY
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,10 +2,12 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-- use scripts/PS/codex/ path
-- implement repo prep/update/clean scripts for website deployment
-- ensure safe, non-destructive defaults
+- enforce scripts/PS/deploy/ for deployment scripts
+- enforce scripts/PS/codex/ for codex scripts
+- add validation and safety checks to all scripts
+- add dry-run capability
+- ensure docker deployment compatibility
 - enforce commit format:
-  description starts first line (no leading CR)
+  description starts first line
   PR name last line
 - update roadmap status only (no text changes except approved additions)
diff --git a/docs/dev/CODEX_PLAN_AND_API_KEY_SCRIPTING.md b/docs/dev/CODEX_PLAN_AND_API_KEY_SCRIPTING.md
@@ -20,7 +20,7 @@ This repo includes a focused operator scripting surface in `scripts/PS/codex` fo
 Switch to Pay-as-you-go mode:
 
 ```powershell
-.\scripts\PS\codex\Switch-CodexPlanMode.ps1 -Mode payg
+.\scripts\PS\codex\Switch-CodexPlanMode.ps1 -Mode payg -DryRun
 ```
 
 Switch to Codex mode:
@@ -32,7 +32,7 @@ Switch to Codex mode:
 Set or update API key for current process only (safe for smoke checks):
 
 ```powershell
-.\scripts\PS\codex\Set-CodexApiKey.ps1 -ApiKey "sk-your-key" -Scope Process
+.\scripts\PS\codex\Set-CodexApiKey.ps1 -ApiKey "sk-your-key" -Scope Process -DryRun
 ```
 
 Set or update API key for current user profile:
@@ -44,7 +44,7 @@ Set or update API key for current user profile:
 Validate configured key state:
 
 ```powershell
-.\scripts\PS\codex\Validate-CodexApiKey.ps1 -EnvVarName OPENAI_API_KEY -RequireStateRecord
+.\scripts\PS\codex\Validate-CodexApiKey.ps1 -EnvVarName OPENAI_API_KEY -RequireStateRecord -DryRun
 ```
 
 Inspect current mode + metadata:
@@ -56,5 +56,6 @@ Inspect current mode + metadata:
 ## Guardrails
 - Use `-Scope Process` for temporary sessions and script smoke checks.
 - Use `-Scope User` only when you intentionally want persistent user configuration.
+- Use `-DryRun` first for switch/set/validate/get scripts before applying persistent updates.
 - Validation checks local readiness and metadata consistency without printing raw secrets.
 - Keep the state file local to the repo; do not commit generated secret material.
diff --git a/docs/dev/CODEX_TEMPLATE_GAME_CREATION_SCRIPTING.md b/docs/dev/CODEX_TEMPLATE_GAME_CREATION_SCRIPTING.md
@@ -7,7 +7,7 @@ Use `scripts/PS/codex/New-CodexTemplateGame.ps1` to create a new game scaffold f
 
 ## Example
 ```powershell
-.\scripts\PS\codex\New-CodexTemplateGame.ps1 -GameId "my-new-game" -DisplayName "My New Game"
+.\scripts\PS\codex\New-CodexTemplateGame.ps1 -GameId "my-new-game" -DisplayName "My New Game" -Apply
 ```
 
 ## Generated Structure
@@ -23,4 +23,6 @@ Use `scripts/PS/codex/New-CodexTemplateGame.ps1` to create a new game scaffold f
 ## Guardrails
 - Script normalizes `-GameId` to slug format for deterministic paths.
 - Script fails if the target game folder already exists.
+- Script defaults to dry-run output unless `-Apply` is provided.
+- `-DryRun` is supported explicitly for preview checks.
 - Script writes empty scaffold metadata only; no engine or gameplay files are altered.
diff --git a/docs/dev/CODEX_WEBSITE_REPO_DEPLOYMENT_SCRIPTING.md b/docs/dev/CODEX_WEBSITE_REPO_DEPLOYMENT_SCRIPTING.md
@@ -1,40 +1,41 @@
 # Codex Website Repo Deployment Scripting
 
-Use these scripts from `scripts/PS/codex/` to stage repo content for website deployment with safe defaults.
+Use these scripts from `scripts/PS/deploy/` to stage repo content for website deployment with safe defaults and Docker compatibility artifacts.
 
 ## Scripts
-- `scripts/PS/codex/Prep-WebsiteRepoDeployment.ps1`
-- `scripts/PS/codex/Update-WebsiteRepoDeployment.ps1`
-- `scripts/PS/codex/Clean-WebsiteRepoDeployment.ps1`
+- `scripts/PS/deploy/Prep-WebsiteRepoDeployment.ps1`
+- `scripts/PS/deploy/Update-WebsiteRepoDeployment.ps1`
+- `scripts/PS/deploy/Clean-WebsiteRepoDeployment.ps1`
 
 ## Safety Defaults
-- All scripts default to preview-only mode.
+- All scripts default to dry-run mode.
 - No files are written or deleted unless `-Apply` is provided.
+- `-DryRun` is available explicitly on each script.
 - Clean operations are restricted to staging paths under `<repo>/tmp`.
 
 ## Typical Flow
-Prepare staging plan:
+Prepare staging plan and Docker artifacts:
 
 ```powershell
-.\scripts\PS\codex\Prep-WebsiteRepoDeployment.ps1 -Apply
+.\scripts\PS\deploy\Prep-WebsiteRepoDeployment.ps1 -Apply
 ```
 
 Update staged website content:
 
 ```powershell
-.\scripts\PS\codex\Update-WebsiteRepoDeployment.ps1 -Apply
+.\scripts\PS\deploy\Update-WebsiteRepoDeployment.ps1 -Apply
 ```
 
 Clean staged site output only:
 
 ```powershell
-.\scripts\PS\codex\Clean-WebsiteRepoDeployment.ps1 -Apply
+.\scripts\PS\deploy\Clean-WebsiteRepoDeployment.ps1 -Apply
 ```
 
-Clean staged site output plus metadata files:
+Clean staged site output plus metadata and Docker files:
 
 ```powershell
-.\scripts\PS\codex\Clean-WebsiteRepoDeployment.ps1 -RemoveMetadata -Apply
+.\scripts\PS\deploy\Clean-WebsiteRepoDeployment.ps1 -RemoveMetadata -Apply
 ```
 
 ## Outputs
@@ -43,3 +44,7 @@ Clean staged site output plus metadata files:
 - metadata root: `tmp/website-deploy/meta/`
   - `website-deploy-plan.json`
   - `website-deploy-last-update.json`
+- docker compatibility files in `tmp/website-deploy/`
+  - `Dockerfile`
+  - `docker-compose.yml`
+  - `.dockerignore`
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,3 +1,3 @@
-Adds safe website deployment staging automation with prep/update/clean scripts under `scripts/PS/codex/`, preview-only defaults, and constrained clean behavior under `<repo>/tmp`.
+Adds script safety hardening across Codex/deploy PowerShell automation by enforcing `scripts/PS/deploy/` for deployment scripts, `scripts/PS/codex/` for codex scripts, dry-run-first behavior, input/path validation, and Docker-compatible staging artifacts.
 
-BUILD_PR_LEVEL_09_20_WEBSITE_REPO_PREP_SCRIPTING
+BUILD_PR_LEVEL_09_21_SCRIPT_VALIDATION_AND_SAFETY
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_09_21_SCRIPT_VALIDATION_AND_SAFETY
+BUILD_PR_LEVEL_09_22_DEPLOYMENT_PIPELINE_INTEGRATION
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,11 +1,26 @@
 Summary
-- Added website deployment scripting under `scripts/PS/codex/`:
+- Enforced script boundaries:
+  - deployment scripts now live under `scripts/PS/deploy/`
+  - codex scripts remain under `scripts/PS/codex/`
+- Added deployment safety/validation helpers in `scripts/PS/deploy/WebsiteRepoDeploymentCommon.ps1`.
+- Added/updated deployment scripts with dry-run and apply guards:
+  - `scripts/PS/deploy/Prep-WebsiteRepoDeployment.ps1`
+  - `scripts/PS/deploy/Update-WebsiteRepoDeployment.ps1`
+  - `scripts/PS/deploy/Clean-WebsiteRepoDeployment.ps1`
+- Removed deployment script duplicates from `scripts/PS/codex/`:
   - `Prep-WebsiteRepoDeployment.ps1`
   - `Update-WebsiteRepoDeployment.ps1`
   - `Clean-WebsiteRepoDeployment.ps1`
-  - shared helper: `WebsiteRepoDeploymentCommon.ps1`
-- Implemented safe non-destructive defaults: scripts run in preview mode unless `-Apply` is provided.
-- Added deployment scripting usage/guardrails doc:
+  - `WebsiteRepoDeploymentCommon.ps1`
+- Added Docker deployment compatibility artifacts to deploy flow (`Dockerfile`, `docker-compose.yml`, `.dockerignore` in staging root).
+- Hardened codex scripts with dry-run and validation where applicable:
+  - `Switch-CodexPlanMode.ps1`
+  - `Set-CodexApiKey.ps1`
+  - `Validate-CodexApiKey.ps1`
+  - `Get-CodexOperatorState.ps1`
+  - `New-CodexTemplateGame.ps1`
+- Updated docs for new deploy path and script guardrails:
   - `docs/dev/CODEX_WEBSITE_REPO_DEPLOYMENT_SCRIPTING.md`
-- Updated roadmap with status-only bracket change for the website prep/update/delete scripting lane.
-- Commit comment format is description on first line and PR name on last line.
+  - `docs/dev/CODEX_TEMPLATE_GAME_CREATION_SCRIPTING.md`
+  - `docs/dev/CODEX_PLAN_AND_API_KEY_SCRIPTING.md`
+- Updated roadmap with status-only bracket change.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,9 +1,12 @@
-Validation Checklist - BUILD_PR_LEVEL_09_20_WEBSITE_REPO_PREP_SCRIPTING
+Validation Checklist - BUILD_PR_LEVEL_09_21_SCRIPT_VALIDATION_AND_SAFETY
 
-[x] website deployment scripts added under `scripts/PS/codex/`
-[x] scripts default to preview mode unless `-Apply` is provided
-[x] clean script safety checks restrict deletes to staging paths under `<repo>/tmp`
+[x] deployment scripts moved/enforced to `scripts/PS/deploy/`
+[x] codex scripts remain/enforced under `scripts/PS/codex/`
+[x] validation and safety checks added to touched codex/deploy scripts
+[x] dry-run capability added to touched codex/deploy scripts
+[x] deploy flow writes Docker-compatible artifacts in staging
 [x] focused PowerShell parse checks pass on touched scripts
-[x] focused prep/update/clean smoke checks pass
+[x] focused dry-run/apply smoke checks pass for deploy scripts
+[x] focused dry-run/apply smoke checks pass for touched codex scripts
 [x] roadmap updated with status-only bracket changes
 [x] commit format enforced: description first line, PR name last line
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -552,7 +552,7 @@
 - [x] smoke validation aligned to samples/tools/games
 - [ ] fixtures/helpers organization normalized
 - [.] move/refactor validation strategy documented
-- [ ] post-PR acceptance criteria consistently enforced
+- [.] post-PR acceptance criteria consistently enforced
 
 ---
 
diff --git a/docs/pr/BUILD_PR_LEVEL_09_21_SCRIPT_VALIDATION_AND_SAFETY.md b/docs/pr/BUILD_PR_LEVEL_09_21_SCRIPT_VALIDATION_AND_SAFETY.md
@@ -0,0 +1,24 @@
+# BUILD_PR — LEVEL 09_21 — SCRIPT VALIDATION AND SAFETY
+
+## Objective
+Add validation, safety checks, and guardrails across all PowerShell scripting introduced so far.
+
+## Key Updates
+- 09_20 deploy scripts must reside in: scripts/PS/deploy/
+- Target deployment: Docker-based web servers
+- Codex scripts remain in: scripts/PS/codex/
+- Commit format: description first line, no leading CR, PR name last
+
+## Scope
+- validate all script inputs
+- add dry-run / safe execution modes
+- prevent destructive actions without confirmation
+- enforce correct script locations
+
+## Out of Scope
+- no runtime changes
+- no tool UI changes
+
+## Roadmap Instruction
+- Update roadmap status only
+- Maintain previously added roadmap items
diff --git a/scripts/PS/codex/Get-CodexOperatorState.ps1 b/scripts/PS/codex/Get-CodexOperatorState.ps1
@@ -1,6 +1,7 @@
 [CmdletBinding()]
 param(
-    [string]$StatePath
+    [string]$StatePath,
+    [switch]$DryRun
 )
 
 Set-StrictMode -Version Latest
@@ -9,6 +10,13 @@ $ErrorActionPreference = "Stop"
 . (Join-Path $PSScriptRoot "CodexOperatorState.ps1")
 
 $resolvedStatePath = Get-CodexOperatorStatePath -StatePath $StatePath
+
+if ($DryRun.IsPresent) {
+    Write-Host "Dry-run only. No state read performed."
+    Write-Host "Would read codex state from: $resolvedStatePath"
+    exit 0
+}
+
 $state = Read-CodexOperatorState -StatePath $resolvedStatePath
 
 $summary = [ordered]@{
diff --git a/scripts/PS/codex/New-CodexTemplateGame.ps1 b/scripts/PS/codex/New-CodexTemplateGame.ps1
@@ -1,10 +1,12 @@
-[CmdletBinding()]
+[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "Medium")]
 param(
     [Parameter(Mandatory = $true)]
     [string]$GameId,
     [string]$DisplayName,
     [string]$GamesRoot,
-    [string]$TemplatePath
+    [string]$TemplatePath,
+    [switch]$Apply,
+    [switch]$DryRun
 )
 
 Set-StrictMode -Version Latest
@@ -58,6 +60,20 @@ function Ensure-File {
     }
 }
 
+function Test-PathWithinRoot {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$Path,
+        [Parameter(Mandatory = $true)]
+        [string]$RootPath
+    )
+
+    $resolvedPath = [System.IO.Path]::GetFullPath($Path)
+    $resolvedRoot = [System.IO.Path]::GetFullPath($RootPath)
+    $normalizedRoot = $resolvedRoot.TrimEnd('\', '/') + [System.IO.Path]::DirectorySeparatorChar
+    return $resolvedPath.StartsWith($normalizedRoot, [StringComparison]::OrdinalIgnoreCase)
+}
+
 function Write-JsonFile {
     param(
         [Parameter(Mandatory = $true)]
@@ -104,6 +120,10 @@ function New-ToolIntegrationEntry {
 $repoRoot = Get-CodexRepoRoot
 $normalizedGameId = ConvertTo-CodexSlug -Value $GameId -Fallback "new-game"
 
+if ($Apply.IsPresent -and $DryRun.IsPresent) {
+    throw "Use either -Apply or -DryRun, not both."
+}
+
 if ($normalizedGameId -ne $GameId) {
     Write-Host "Normalized game id: $normalizedGameId"
 }
@@ -121,13 +141,19 @@ if ([string]::IsNullOrWhiteSpace($GamesRoot)) {
 else {
     $GamesRoot = [System.IO.Path]::GetFullPath($GamesRoot)
 }
+if (-not (Test-PathWithinRoot -Path $GamesRoot -RootPath $repoRoot)) {
+    throw "Games root must remain within repo root: $GamesRoot"
+}
 
 if ([string]::IsNullOrWhiteSpace($TemplatePath)) {
     $TemplatePath = Join-Path $GamesRoot "_template"
 }
 else {
     $TemplatePath = [System.IO.Path]::GetFullPath($TemplatePath)
 }
+if (-not (Test-PathWithinRoot -Path $TemplatePath -RootPath $repoRoot)) {
+    throw "Template path must remain within repo root: $TemplatePath"
+}
 
 if (-not (Test-Path -LiteralPath $TemplatePath)) {
     throw "Template path not found: $TemplatePath"
@@ -137,6 +163,22 @@ $targetGamePath = Join-Path $GamesRoot $normalizedGameId
 if (Test-Path -LiteralPath $targetGamePath) {
     throw "Target game path already exists: $targetGamePath"
 }
+if (-not (Test-PathWithinRoot -Path $targetGamePath -RootPath $GamesRoot)) {
+    throw "Target game path must remain within games root: $targetGamePath"
+}
+
+if (-not $Apply.IsPresent -or $DryRun.IsPresent) {
+    Write-Host "Dry-run only. No files were created."
+    Write-Host "Run with -Apply to create the game scaffold."
+    Write-Host "Template source: $TemplatePath"
+    Write-Host "Target game path: $targetGamePath"
+    exit 0
+}
+
+if (-not $PSCmdlet.ShouldProcess($targetGamePath, "Create template game scaffold")) {
+    Write-Host "Game scaffold creation cancelled."
+    exit 0
+}
 
 Ensure-Directory -Path $GamesRoot
 Ensure-Directory -Path $targetGamePath
diff --git a/scripts/PS/codex/Set-CodexApiKey.ps1 b/scripts/PS/codex/Set-CodexApiKey.ps1
@@ -1,10 +1,12 @@
-[CmdletBinding()]
+[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "Medium")]
 param(
     [string]$ApiKey,
     [ValidateSet("Process", "User")]
     [string]$Scope = "User",
+    [ValidatePattern("^[A-Za-z_][A-Za-z0-9_]*$")]
     [string]$EnvVarName = "OPENAI_API_KEY",
-    [string]$StatePath
+    [string]$StatePath,
+    [switch]$DryRun
 )
 
 Set-StrictMode -Version Latest
@@ -28,6 +30,9 @@ function ConvertTo-PlainText {
 }
 
 if ([string]::IsNullOrWhiteSpace($ApiKey)) {
+    if ($DryRun.IsPresent) {
+        throw "Dry-run mode requires -ApiKey so the script can validate format and report the planned update."
+    }
     $secureInput = Read-Host -Prompt "Enter OpenAI API key (input hidden)" -AsSecureString
     $ApiKey = ConvertTo-PlainText -SecureValue $secureInput
 }
@@ -36,6 +41,19 @@ if (-not (Test-CodexApiKeyFormat -ApiKey $ApiKey)) {
     throw "API key format appears invalid. Expected a non-empty key that starts with 'sk-' and is at least 20 characters."
 }
 
+if ($DryRun.IsPresent) {
+    $fingerprint = Get-CodexApiKeyFingerprint -ApiKey $ApiKey
+    Write-Host "Dry-run only. No environment or state updates were made."
+    Write-Host "Would set $EnvVarName in $Scope scope."
+    Write-Host "Would record fingerprint: $fingerprint"
+    exit 0
+}
+
+if (-not $PSCmdlet.ShouldProcess($EnvVarName, "Configure API key in $Scope scope and update codex state metadata")) {
+    Write-Host "API key update cancelled."
+    exit 0
+}
+
 if ($Scope -eq "Process") {
     Set-Item -Path "Env:$EnvVarName" -Value $ApiKey
 }
diff --git a/scripts/PS/codex/Switch-CodexPlanMode.ps1 b/scripts/PS/codex/Switch-CodexPlanMode.ps1
diff --git a/scripts/PS/codex/Validate-CodexApiKey.ps1 b/scripts/PS/codex/Validate-CodexApiKey.ps1
diff --git a/scripts/PS/deploy/Clean-WebsiteRepoDeployment.ps1 b/scripts/PS/deploy/Clean-WebsiteRepoDeployment.ps1
diff --git a/scripts/PS/deploy/Prep-WebsiteRepoDeployment.ps1 b/scripts/PS/deploy/Prep-WebsiteRepoDeployment.ps1
diff --git a/scripts/PS/deploy/Update-WebsiteRepoDeployment.ps1 b/scripts/PS/deploy/Update-WebsiteRepoDeployment.ps1
diff --git a/scripts/PS/deploy/WebsiteRepoDeploymentCommon.ps1 b/scripts/PS/deploy/WebsiteRepoDeploymentCommon.ps1

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_09_21_SCRIPT_VALIDATION_AND_SAFETY`
	`1`	`+BUILD_PR_LEVEL_09_22_DEPLOYMENT_PIPELINE_INTEGRATION`