Canonicalize ProjectInstructions branch lifecycle

Author: ToolboxAid

docs_build/dev/BUILD_PR.md

@@ -14,7 +14,7 @@ This `BUILD_PR.md`, `PLAN_PR.md`, and the user request are the source of truth f
 - Establish `docs_build/dev/ProjectInstructions/` as the only active source.
 - Mark all other ProjectInstructions-style sources changed by this PR as deprecated references.
 - Update active team start/governance docs to reference only `docs_build/dev/ProjectInstructions/`.
-- Add EOD main lock, next-day reset governance, and explicit START / WORK / END branch lifecycle rules.
+- Add EOD main lock, next-day reset governance, and canonical START / WORK / END branch lifecycle rules.
 - Add required reports under `docs_build/dev/reports/`.
 
 ## Exact Targets
@@ -46,7 +46,7 @@ Run:
 
 ```powershell
 rg -n 'project-instructions/addendums|docs_build/dev/PROJECT_INSTRUCTIONS.md.*source of truth|Codex must always read `docs_build/dev/PROJECT_INSTRUCTIONS.md`|Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`' docs_build/dev/ProjectInstructions docs_build/dev/PROJECT_INSTRUCTIONS.md project-instructions
-rg -n "START RULE|WORK RULE|END RULE|HARD STOP before committing|Codex commits only to the PR branch|HEAD SHA recorded as new EOD baseline|End of Day:|Next Day Start:|HEAD.*published EOD SHA|only active Project Instructions source" docs_build/dev/ProjectInstructions
+rg -n "Branch Lifecycle \\(Canonical\\)|Every PR follows exactly three phases|^START$|^WORK$|^END$|Mandatory Hard Stops|tomorrow's official baseline|No commits on main|Never checkout main|Only after ALL four pass" docs_build/dev/ProjectInstructions
 git diff --name-only -- src assets toolbox games api serverside package.json package-lock.json docs_build/dev/start_of_day
 git diff --check
 ```

docs_build/dev/PLAN_PR.md

@@ -10,7 +10,7 @@ Make `docs_build/dev/ProjectInstructions/` the only active Project Instructions
 - Mark legacy ProjectInstructions-style sources as deprecated reference material.
 - Move active legacy addendums into `docs_build/dev/ProjectInstructions/addendums/`.
 - Update active team start and governance docs to reference only `docs_build/dev/ProjectInstructions/`.
-- Add EOD main lock, next-day reset, team PR branch creation gate, and explicit START / WORK / END branch lifecycle rules.
+- Add EOD main lock, next-day reset, team PR branch creation gate, and canonical START / WORK / END branch lifecycle rules.
 - Add required Codex reports under `docs_build/dev/reports/`.
 
 ## Out Of Scope
@@ -23,6 +23,6 @@ Make `docs_build/dev/ProjectInstructions/` the only active Project Instructions
 ## Validation Plan
 
 1. Run targeted grep/search proving no active duplicate ProjectInstructions source remains.
-2. Confirm EOD/Next Day and START / WORK / END branch lifecycle rules appear in active governance docs.
+2. Confirm EOD/Next Day and canonical START / WORK / END branch lifecycle rules appear in active governance docs.
 3. Confirm no product/runtime files changed.
 4. Run `git diff --check`.

docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md

@@ -49,7 +49,7 @@ Existing Project Instructions outside `docs_build/dev/ProjectInstructions/` rema
 
 ## Single Source and Main Lock Governance
 
-`docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md` defines the single active Project Instructions source, EOD main lock, next-day reset, and team branch creation gate.
+`docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md` defines the single active Project Instructions source, canonical START / WORK / END branch lifecycle, EOD main lock, next-day reset, team branch creation gate, daily synchronization baseline, and mandatory hard stops.
 
 ## Merge Control
 

docs_build/dev/ProjectInstructions/README.txt

@@ -13,7 +13,10 @@ Team assignment workflow:
 Team assignments are tracked under team_assignments/. A team pulls work from BACKLOG_MASTER.md, marks the item building when assigned, and records the active assignment under the owning team. Teams work only on assigned items unless an OWNER override explicitly changes the assignment.
 
 No direct commits to main:
-Do not commit directly to main unless the owner explicitly instructs that exception. Normal work must use PR branches, draft PRs, validation evidence, and owner-controlled merge approval.
+Do not commit directly to main. Normal work must use PR branches, draft PRs, validation evidence, and owner-controlled merge approval.
+
+Branch lifecycle:
+Every PR follows exactly three phases: START, WORK, END. The canonical lifecycle is `docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`.
 
 OWNER override rule:
 An OWNER override must use this wording:
@@ -40,6 +43,7 @@ READ THIS FIRST
 9. Follow OWNER governance decisions.
 10. When guidance conflicts, newest OWNER-approved guidance wins.
 11. Batch Governance Mode is the default for governance, documentation, and administrative work.
+12. Follow the canonical START / WORK / END lifecycle.
 
 Addendum index:
 - Single Source and EOD Main Lock: docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md

docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md

@@ -11,31 +11,15 @@ No team creates a PR branch until all checks pass:
 
 Use `docs_build/dev/ProjectInstructions/` as the only active Project Instructions source.
 
-START RULE:
-- Every team starts on `main`.
-- `main` must be clean.
-- `main...origin/main` must be `0 0`.
-- `HEAD` SHA must match published EOD SHA.
-- Only then create or switch to the PR branch.
-- No commits are allowed on `main`.
-
-WORK RULE:
-- Codex must remain on the PR branch during implementation.
-- Codex commits only to the PR branch.
-- Codex pushes only the PR branch.
-- HARD STOP if branch changes unexpectedly.
-- HARD STOP before committing if current branch is `main`.
-
-END RULE:
-- After PR validation, push the PR branch.
-- Merge PR into `main` only when approved.
-- Checkout `main`.
-- Run `git fetch origin`.
-- Run `git pull --ff-only origin main`.
-- Confirm current branch is `main`.
-- Confirm worktree is clean.
-- Confirm `main...origin/main` is `0 0`.
-- Record `HEAD` SHA as new EOD baseline.
+Branch Lifecycle (Canonical):
+- Every PR follows exactly three phases: START, WORK, END.
+- Follow `docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`.
+- START begins on synchronized `main` and creates the PR branch only after all gates pass.
+- WORK remains on the PR branch. Never checkout `main`.
+- END merges, returns to synchronized `main`, publishes branch, HEAD SHA, and date/time, then stops all work.
+- No commits on `main`.
+- No implementation on `main`.
+- No validation on `main` except start validation.
 
 ## Start Team Alfa
 
@@ -180,4 +164,6 @@ git pull --ff-only origin main
 git status
 git rev-list --left-right --count main...origin/main
 git rev-parse HEAD
+
+Publish Branch, HEAD SHA, and Date/time. This becomes tomorrow's official baseline.
 ```

docs_build/dev/ProjectInstructions/addendums/branch_context_governance.md

@@ -21,6 +21,8 @@ At the start of work, report or validate:
 - active PR number/name or explicit `PLAN_ONLY`
 - previous PR Closed status unless this is an explicitly documented stacked PR chain
 
+Session start must follow the canonical START phase in `docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`.
+
 ## Stop Conditions
 
 Stop and report before changing files when:
@@ -38,6 +40,8 @@ Stop and report before changing files when:
 
 After a branch is created, the branch remains the working context.
 
+This is the canonical WORK phase: remain on the PR branch, never checkout `main`, commit only on the PR branch, push only the PR branch, validate from the PR branch, and open/update the PR from the PR branch.
+
 Do not automatically return to `main` after:
 
 - commit
@@ -47,7 +51,7 @@ Do not automatically return to `main` after:
 - review updates
 - additional commits
 
-Return to `main` only after the PR is merged, the branch is retired, or OWNER explicitly says to return to `main`.
+Return to `main` only in the canonical END phase after the PR is merged, the branch is retired, or OWNER explicitly says to return to `main`.
 
 Returning to `main` is required before Closed can be recorded.
 
@@ -58,6 +62,7 @@ Closed branch context requires:
 - local/origin sync is `0/0`
 - no untracked files
 - source branch disposition recorded as `retained`
+- branch, HEAD SHA, and date/time recorded as the new EOD baseline when this is EOD closeout
 
 ## GitHub Authority
 

docs_build/dev/ProjectInstructions/addendums/branch_lock_governance.md

@@ -24,6 +24,7 @@ Keep active work attached to the correct assigned team, branch, and OWNER decisi
 - Start from current `main`.
 - Pull latest `origin/main` before creating a work branch.
 - Do not create a PR branch unless current branch is `main`, worktree is clean, `main...origin/main` is `0 0`, and `HEAD` SHA matches the published EOD SHA.
+- Follow the canonical START / WORK / END lifecycle in `docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`.
 - Keep work on the active branch until the PR is merged, the branch is retired, or OWNER says to return to `main`.
 - Do not commit directly to `main`.
 - HARD STOP before committing if current branch is `main`.
@@ -34,34 +35,23 @@ Keep active work attached to the correct assigned team, branch, and OWNER decisi
 - Retain source branches by default after merge and closeout.
 - Record branch disposition before Closed as `retained`.
 
-## START RULE
+## Branch Lifecycle (Canonical)
 
-- Every team starts on `main`.
-- `main` must be clean.
-- `main...origin/main` must be `0 0`.
-- `HEAD` SHA must match published EOD SHA.
-- Only then create or switch to the PR branch.
-- No commits are allowed on `main`.
+Every PR follows exactly three phases:
 
-## WORK RULE
+```text
+START
+WORK
+END
+```
 
-- Codex must remain on the PR branch during implementation.
-- Codex commits only to the PR branch.
-- Codex pushes only the PR branch.
-- HARD STOP if branch changes unexpectedly.
-- HARD STOP before committing if current branch is `main`.
+The canonical lifecycle lives in `docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`.
 
-## END RULE
-
-- After PR validation, push the PR branch.
-- Merge PR into `main` only when approved.
-- Checkout `main`.
-- Run `git fetch origin`.
-- Run `git pull --ff-only origin main`.
-- Confirm current branch is `main`.
-- Confirm worktree is clean.
-- Confirm `main...origin/main` is `0 0`.
-- Record `HEAD` SHA as new EOD baseline.
+Branch lock governance enforces:
+- START on synchronized `main`.
+- WORK only on the PR branch.
+- END by merging, returning to synchronized `main`, publishing branch, HEAD SHA, and date/time, then stopping all work.
+- Mandatory hard stops before commits on `main`, dirty branch creation, non-`0 0` main sync, baseline SHA mismatch, unvalidated merge, or new PR work before synchronized main return.
 
 ## OWNER Override
 

docs_build/dev/ProjectInstructions/addendums/codex_project_instructions_startup.md

@@ -23,31 +23,25 @@ Codex must use this as the only active source of truth for:
 
 ## Branch Lifecycle Start Gate
 
-START RULE:
-- Every team starts on `main`.
-- `main` must be clean.
-- `main...origin/main` must be `0 0`.
-- `HEAD` SHA must match published EOD SHA.
-- Only then create or switch to the PR branch.
-- No commits are allowed on `main`.
-
-WORK RULE:
-- Codex must remain on the PR branch during implementation.
-- Codex commits only to the PR branch.
-- Codex pushes only the PR branch.
-- HARD STOP if branch changes unexpectedly.
-- HARD STOP before committing if current branch is `main`.
-
-END RULE:
-- After PR validation, push the PR branch.
-- Merge PR into `main` only when approved.
-- Checkout `main`.
-- Run `git fetch origin`.
-- Run `git pull --ff-only origin main`.
-- Confirm current branch is `main`.
-- Confirm worktree is clean.
-- Confirm `main...origin/main` is `0 0`.
-- Record `HEAD` SHA as new EOD baseline.
+Every PR follows exactly three phases:
+
+```text
+START
+WORK
+END
+```
+
+Codex must follow the canonical lifecycle in:
+
+`docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`
+
+Startup enforcement:
+- START begins on synchronized `main`.
+- WORK remains on the PR branch. Never checkout `main`.
+- END merges, returns to synchronized `main`, publishes branch, HEAD SHA, and date/time, then stops all work.
+- STOP if current branch is `main` before commit.
+- STOP if attempting to push `main`.
+- STOP if a new PR starts before returning to synchronized `main`.
 
 Deprecated Project Instructions material outside `docs_build/dev/ProjectInstructions/` is reference-only and must not override active governance.
 

docs_build/dev/ProjectInstructions/addendums/multi_team.md

@@ -51,6 +51,7 @@ Rules:
 - One Codex session may execute multiple sequential PRs.
 - Each PR must still have one clear purpose.
 - Each PR must create or use its own approved branch.
+- Each PR must follow the canonical START / WORK / END lifecycle in `docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`.
 - Each PR may be committed and pushed during active work.
 - Each PR may be opened as a draft PR during active work.
 - Do not commit directly to main.
@@ -69,13 +70,14 @@ During active work:
 - Pushes are allowed and expected.
 - Draft PRs are allowed and expected.
 - Direct commits to main are prohibited.
+- WORK remains on the PR branch; never checkout main during WORK.
 - Merges to main are prohibited unless explicitly approved by the owner.
 
 At end of day:
 - Owner reviews ready PRs.
 - Owner explicitly approves which PRs merge.
 - Only owner-approved PRs may merge to main.
-- After merge, return to main and pull latest main.
+- After merge, execute the canonical END phase, return to synchronized main, and publish branch, HEAD SHA, and date/time.
 - Do not treat sequential PR completion as merge approval.
 
 Commit/push during the day is allowed only on assigned team/OWNER/PR branches.

docs_build/dev/ProjectInstructions/addendums/pr_workflow.md

@@ -26,36 +26,33 @@ Define the standard pull request workflow for Game Foundry Studio.
 15. Pull latest main before starting the next PR.
 16. Verify Main Verified and Closed gates.
 
-## Branch Lifecycle Governance
-
-### START RULE
-
-- Every team starts on `main`.
-- `main` must be clean.
-- `main...origin/main` must be `0 0`.
-- `HEAD` SHA must match published EOD SHA.
-- Only then create or switch to the PR branch.
-- No commits are allowed on `main`.
-
-### WORK RULE
-
-- Codex must remain on the PR branch during implementation.
-- Codex commits only to the PR branch.
-- Codex pushes only the PR branch.
-- HARD STOP if branch changes unexpectedly.
-- HARD STOP before committing if current branch is `main`.
-
-### END RULE
-
-- After PR validation, push the PR branch.
-- Merge PR into `main` only when approved.
-- Checkout `main`.
-- Run `git fetch origin`.
-- Run `git pull --ff-only origin main`.
-- Confirm current branch is `main`.
-- Confirm worktree is clean.
-- Confirm `main...origin/main` is `0 0`.
-- Record `HEAD` SHA as new EOD baseline.
+## Branch Lifecycle (Canonical)
+
+Every PR follows exactly three phases:
+
+```text
+START
+WORK
+END
+```
+
+The canonical START, WORK, END, Daily Synchronization, and Mandatory Hard Stops rules live in:
+
+`docs_build/dev/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`
+
+PR workflow must follow that lifecycle exactly.
+
+Summary:
+- START happens on synchronized `main` only and creates the PR branch only after all required gates pass.
+- WORK happens only on the PR branch.
+- END validates, commits, pushes, opens/updates the PR, merges, returns to synchronized `main`, publishes branch, HEAD SHA, and date/time, then stops all work.
+- No commits on `main`.
+- No implementation on `main`.
+- No validation on `main` except start validation.
+- Never checkout `main` during WORK.
+- STOP before commit if current branch is `main`.
+- STOP if current branch changes unexpectedly.
+- STOP if attempting to push `main`.
 
 ## PR Lifecycle States