Skip to content

Commit 02ac94c

Browse files
author
DavidQ
committed
Adds a dedicated PowerShell repo-governance validation layer for script structure, keeps script-tree enforcement out of the JS runtime test suite, and makes script placement rules explicit, non-destructive, and ready for future CI use.
BUILD_PR_LEVEL_09_24_SCRIPT_STRUCTURE_VALIDATION_LAYER & Refines Docker deployment scripts, improves safety, logging, and consistency across deploy pipeline. BUILD_PR_LEVEL_09_25_DOCKER_DEPLOY_SCRIPT_REFINEMENT
1 parent 8afb916 commit 02ac94c

16 files changed

Lines changed: 486 additions & 282 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 12 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,12 @@
1-
# MODEL
2-
GPT-5.4
3-
4-
# REASONING
5-
high
6-
7-
# COMMAND
8-
Create BUILD_PR_LEVEL_09_23_SCRIPT_STRUCTURE_FINALIZATION as a docs-first, surgical PR.
9-
10-
## Mission
11-
Finalize the PowerShell script tree after the recent move/rename work so each script location clearly matches its purpose and all references are aligned.
12-
13-
## Required scope
14-
- finalize and enforce folder roles:
15-
- `scripts/PS/` for general operator scripts
16-
- `scripts/PS/codex/` for Codex-only scripts
17-
- `scripts/PS/deploy/` for deployment scripts
18-
- update references after the moved/renamed template game creation script
19-
- normalize naming where touched so names match actual purpose
20-
- add focused validation that script placement matches responsibility
21-
- document the final structure expectations
22-
23-
## Hard rules
24-
- do not change engine code
25-
- do not add gameplay/runtime features
26-
- do not redesign tools
27-
- do not expand deployment capability beyond structure/finalization
28-
- keep the PR surgical and purpose-specific
29-
30-
## Commit comment format
31-
- description starts on first line
32-
- no leading blank line / no leading CR
33-
- PR identifier goes on the last line
34-
35-
## Roadmap instruction
36-
Update roadmap status only where this PR clearly advances tracked work.
37-
Do not change roadmap prose except for previously approved additions already in flight.
38-
39-
## Deliverables
40-
Return a single repo-structured ZIP at:
41-
`<project folder>/tmp/BUILD_PR_LEVEL_09_23_SCRIPT_STRUCTURE_FINALIZATION.zip`
42-
43-
Include:
44-
- docs/pr/BUILD_PR_LEVEL_09_23_SCRIPT_STRUCTURE_FINALIZATION.md
45-
- docs/dev/codex_commands.md
46-
- docs/dev/commit_comment.txt
47-
- docs/dev/next_command.txt
48-
- docs/dev/reports/change_summary.txt
49-
- docs/dev/reports/validation_checklist.txt
50-
51-
## Validation
52-
Run focused checks only:
53-
- PowerShell parse/readiness checks on touched scripts
54-
- focused reference/path checks
55-
- focused structure checks ensuring scripts live in the correct folders
56-
57-
## Success definition
58-
- general scripts live in `scripts/PS/`
59-
- Codex-only scripts live in `scripts/PS/codex/`
60-
- deployment scripts live in `scripts/PS/deploy/`
61-
- references and names align with actual purpose
62-
- roadmap gets status-only updates where applicable
63-
- final output is one ZIP in `<project folder>/tmp/`
1+
MODEL: GPT-5.4
2+
REASONING: high
3+
4+
COMMAND:
5+
- refine scripts in scripts/PS/deploy/
6+
- ensure docker-ready deployment flow
7+
- standardize parameters and logging
8+
- enforce script structure rules
9+
- commit format:
10+
description first line
11+
PR name last line
12+
- update roadmap status only

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,2 @@
1-
Finalizes the PowerShell script tree by renaming/moving template game creation to `scripts/PS/New-Game-from-Template.ps1`, updating references, and enforcing `scripts/PS/`, `scripts/PS/codex/`, and `scripts/PS/deploy/` role boundaries.
2-
3-
BUILD_PR_LEVEL_09_23_SCRIPT_STRUCTURE_FINALIZATION
1+
Refine Docker deploy scripts with standardized mode handling/logging and deploy-folder enforcement checks.
2+
BUILD_PR_LEVEL_09_25_DOCKER_DEPLOY_SCRIPT_REFINEMENT

‎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_24_DOCKER_DEPLOY_SCRIPT_REFINEMENT
1+
BUILD_PR_LEVEL_09_26_DEPLOY_VALIDATION_AND_DRYRUN

‎docs/dev/POWERSHELL_SCRIPT_STRUCTURE.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,13 @@ This repo uses a purpose-based PowerShell layout:
88
- codex session/operator scripts
99
- `scripts/PS/deploy/`
1010
- deployment/staging scripts
11+
- `scripts/PS/validate/`
12+
- repo-governance validation scripts for script-tree structure
1113

1214
## Current Canonical Scripts
1315

1416
General (`scripts/PS/`):
1517
- `New-Game-from-Template.ps1`
16-
- `Validate-ScriptStructure.ps1`
1718

1819
Codex (`scripts/PS/codex/`):
1920
- `CodexOperatorState.ps1`
@@ -29,16 +30,20 @@ Deploy (`scripts/PS/deploy/`):
2930
- `Update-WebsiteRepoDeployment.ps1`
3031
- `Clean-WebsiteRepoDeployment.ps1`
3132

33+
Validate (`scripts/PS/validate/`):
34+
- `Validate-ScriptStructure.ps1`
35+
- `Validate-All.ps1`
36+
3237
## Validation
3338

3439
Run:
3540

3641
```powershell
37-
.\scripts\PS\Validate-ScriptStructure.ps1
42+
.\scripts\PS\validate\Validate-ScriptStructure.ps1
3843
```
3944

4045
Optional JSON output:
4146

4247
```powershell
43-
.\scripts\PS\Validate-ScriptStructure.ps1 -Json
48+
.\scripts\PS\validate\Validate-ScriptStructure.ps1 -Json
4449
```

‎docs/dev/reports/change_summary.txt‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,17 @@
1-
Summary
2-
- Finalized script placement/naming for the template game creation script:
3-
- removed `scripts/PS/New-TemplateGame.ps1`
4-
- added `scripts/PS/New-Game-from-Template.ps1`
5-
- Updated all active references to the renamed script path:
6-
- `docs/dev/CODEX_TEMPLATE_GAME_CREATION_SCRIPTING.md`
7-
- generation-note path in `scripts/PS/New-Game-from-Template.ps1`
8-
- Added focused structure validation script:
9-
- `scripts/PS/Validate-ScriptStructure.ps1`
10-
- Added final structure expectations doc:
11-
- `docs/dev/POWERSHELL_SCRIPT_STRUCTURE.md`
12-
- Preserved and validated folder roles:
13-
- `scripts/PS/` (general)
14-
- `scripts/PS/codex/` (Codex-only)
15-
- `scripts/PS/deploy/` (deployment)
16-
- Applied roadmap status-only update for script naming policy finalization.
1+
BUILD_PR_LEVEL_09_25_DOCKER_DEPLOY_SCRIPT_REFINEMENT
2+
3+
Scope:
4+
- Refined deploy scripts under scripts/PS/deploy/ only.
5+
- Kept behavior surgical and non-destructive by default.
6+
7+
Implemented:
8+
- Added shared deploy execution mode normalization (`-Apply` / `-DryRun`) in WebsiteRepoDeploymentCommon.ps1.
9+
- Added shared structured deploy logging helper with consistent level+timestamp output.
10+
- Added deploy script placement enforcement (`scripts/PS/deploy/`) with actionable failure text.
11+
- Added Docker artifact readiness assertion after artifact writes in prep/update flows.
12+
- Updated prep/update/clean entry scripts to use shared mode/logging enforcement helpers.
13+
14+
Docs/Tracking:
15+
- Updated commit comment format (description first line, PR name last line).
16+
- Updated validation checklist for focused PowerShell/deploy checks.
17+
- Updated roadmap with status-only progression tied to acceptance enforcement.

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 6 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,6 @@
1-
Validation Checklist - BUILD_PR_LEVEL_09_23_SCRIPT_STRUCTURE_FINALIZATION
2-
3-
Scope
4-
[x] PR remains in the script-structure lane only
5-
[x] No engine changes introduced
6-
[x] No gameplay/runtime feature changes introduced
7-
[x] No tool UI redesign introduced
8-
[x] No unrelated deployment feature expansion introduced
9-
10-
Structure
11-
[x] General operator/template scripts live under `scripts/PS/`
12-
[x] Codex-only scripts live under `scripts/PS/codex/`
13-
[x] Deployment scripts live under `scripts/PS/deploy/`
14-
[x] No misplaced general script remains in `scripts/PS/codex/`
15-
[x] References point to the updated script paths
16-
[x] Names match actual purpose where touched
17-
18-
Validation
19-
[x] Touched PowerShell files parse/read cleanly
20-
[x] Focused reference/path checks pass
21-
[x] Focused structure checks pass
22-
[x] Focused template script dry-run/apply smoke check passes
23-
24-
Roadmap
25-
[x] Roadmap status updated only where applicable
26-
[x] No unapproved roadmap prose changes made
27-
28-
Packaging
29-
[x] docs/pr document included
30-
[x] docs/dev/codex_commands.md included
31-
[x] docs/dev/commit_comment.txt included
32-
[x] docs/dev/next_command.txt included
33-
[x] docs/dev/reports/change_summary.txt included
34-
[x] docs/dev/reports/validation_checklist.txt included
35-
[x] Single ZIP produced at `<project folder>/tmp/BUILD_PR_LEVEL_09_23_SCRIPT_STRUCTURE_FINALIZATION.zip`
1+
[x] PowerShell parse/readiness checks on touched deploy scripts
2+
[x] focused dry-run smoke checks for prep/update/clean deploy flow
3+
[x] focused apply smoke checks in tmp staging path for prep/update/clean deploy flow
4+
[x] Docker artifact readiness assertions pass after prep/update apply flows
5+
[x] script structure validation smoke run passes
6+
[x] roadmap updated with status-only change

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -551,8 +551,8 @@
551551
- [.] integration coverage aligned to state/replay/rendering/tools
552552
- [x] smoke validation aligned to samples/tools/games
553553
- [ ] fixtures/helpers organization normalized
554-
- [.] move/refactor validation strategy documented
555-
- [.] post-PR acceptance criteria consistently enforced
554+
- [x] move/refactor validation strategy documented
555+
- [x] post-PR acceptance criteria consistently enforced
556556

557557
---
558558

‎docs/pr/BUILD_PR_LEVEL_09_24_SCRIPT_STRUCTURE_VALIDATION_LAYER.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# BUILD_PR — LEVEL 09_24 — SCRIPT STRUCTURE VALIDATION LAYER
2+
3+
## Objective
4+
Add a dedicated PowerShell validation layer for repo script governance so script placement, naming, and folder-role rules can be enforced outside the runtime/tool test suite.
5+
6+
## Why This PR Exists
7+
The recent script lane established and refined:
8+
- `scripts/PS/`
9+
- `scripts/PS/codex/`
10+
- `scripts/PS/deploy/`
11+
12+
A follow-up question exposed the missing enforcement layer:
13+
`Validate-ScriptStructure.ps1` should exist, but it should not live inside the JavaScript runtime/tool test suite.
14+
15+
This PR turns that insight into a clean repo-governance validation slice.
16+
17+
## Required Direction
18+
Create a validation layer under:
19+
20+
- `scripts/PS/validate/`
21+
22+
Primary script:
23+
- `scripts/PS/validate/Validate-ScriptStructure.ps1`
24+
25+
Optional companion if helpful:
26+
- `scripts/PS/validate/Validate-All.ps1`
27+
28+
## Scope
29+
- add a PowerShell validation layer for script-tree governance
30+
- validate script placement against intended folder roles
31+
- validate naming matches actual purpose where practical
32+
- validate required high-value scripts exist in their expected locations
33+
- keep this validation outside the Node/MJS runtime test suite
34+
- document how operators should run the validation
35+
- add focused smoke checks for the validation scripts themselves if practical
36+
37+
## Out of Scope
38+
- no engine changes
39+
- no gameplay/runtime feature changes
40+
- no tool UI work
41+
- no migration into the JS runtime test runner
42+
- no auto-fix / auto-move behavior in the validator
43+
- no broad deployment feature expansion
44+
45+
## Folder Ownership Rules To Enforce
46+
- `scripts/PS/`
47+
- general operator scripts
48+
- template/game creation scripts
49+
- non-Codex, non-deploy shared operator scripts
50+
51+
- `scripts/PS/codex/`
52+
- Codex-only scripts
53+
- plan-switch / API-key / Codex workflow scripts
54+
- no general game/template creation scripts
55+
56+
- `scripts/PS/deploy/`
57+
- deployment scripts
58+
- Docker web-server deployment prep/update/cleanup scripts only
59+
60+
- `scripts/PS/validate/`
61+
- validation/governance scripts only
62+
63+
## Validation Behavior
64+
The validation layer should:
65+
1. inspect the script tree
66+
2. fail loudly on misplaced scripts
67+
3. report actionable messages
68+
4. remain non-destructive
69+
5. be easy to run manually
70+
6. be suitable for future CI/pre-commit use
71+
72+
## Explicit Rule
73+
Do not place this validation in the JavaScript test suite.
74+
Treat it as repo governance validation, not runtime/tool contract testing.
75+
76+
## Commit Comment Format
77+
- description starts on first line
78+
- no leading blank line / no leading CR
79+
- PR identifier goes on the last line
80+
81+
## Roadmap Instruction
82+
Update roadmap status only where this PR clearly advances tracked work.
83+
Do not change roadmap prose except for previously approved roadmap additions already in flight.
84+
85+
## Acceptance Criteria
86+
- `scripts/PS/validate/Validate-ScriptStructure.ps1` exists
87+
- validator enforces the intended script folder roles
88+
- validator is non-destructive
89+
- validator is documented and manually runnable
90+
- no JS test-suite coupling is introduced
91+
- focused checks pass
92+
- roadmap receives status-only updates where applicable
93+
94+
## Deliverables
95+
Return a repo-structured ZIP at:
96+
`<project folder>/tmp/BUILD_PR_LEVEL_09_24_SCRIPT_STRUCTURE_VALIDATION_LAYER.zip`
97+
98+
Include:
99+
- docs/pr/BUILD_PR_LEVEL_09_24_SCRIPT_STRUCTURE_VALIDATION_LAYER.md
100+
- docs/dev/codex_commands.md
101+
- docs/dev/commit_comment.txt
102+
- docs/dev/next_command.txt
103+
- docs/dev/reports/change_summary.txt
104+
- docs/dev/reports/validation_checklist.txt

‎docs/pr/BUILD_PR_LEVEL_09_25_DOCKER_DEPLOY_SCRIPT_REFINEMENT.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# BUILD_PR — LEVEL 09_25 — DOCKER DEPLOY SCRIPT REFINEMENT
2+
3+
## Objective
4+
Refine deployment scripts for Docker-based web server environments and align them with validated script structure.
5+
6+
## Scope
7+
- refine scripts in scripts/PS/deploy/
8+
- ensure docker compatibility
9+
- standardize inputs/outputs
10+
- improve logging and safety
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)