Replace main branch guard with workstream guard - PR_26171_GAMMA_010-replace-main-branch-guard-with-workstream-guard

Author: ToolboxAid

docs_build/dev/PROJECT_INSTRUCTIONS.md

@@ -91,30 +91,56 @@ User:
 - Do not expand scope beyond the PR
 - Do not modify `start_of_day` folders unless requested
 
-## MAIN BRANCH EXECUTION GUARD
+## WORKSTREAM BRANCH EXECUTION GUARD
 
 Before any BUILD execution, Codex must verify the current git branch.
 
 Rules:
-- The required execution branch is:
+- Approved execution branches are:
   - `main`
-- If the current branch is not `main`:
+  - approved team workstream branches
+- Approved team workstream branch format:
+  - `team/<TEAM>/<workstream>`
+- Workstream branch examples:
+  - `team/ALPHA/game-hub`
+  - `team/BETA/messages`
+  - `team/GAMMA/admin`
+- The repository must be clean before file changes.
+- The current branch must not be detached HEAD.
+- The current branch must have an origin upstream unless a new PR branch has just been created from an approved execution branch.
+- Local branch HEAD must match origin branch HEAD when an origin upstream exists.
+- TEAM ownership must match the approved workstream branch and requested PR scope.
+- PR scope must stay inside TEAM ownership.
+- If the current branch is neither `main` nor an approved team workstream branch:
   - HARD STOP.
   - Do not create code changes.
   - Do not create implementation PRs.
   - Do not create ZIP artifacts.
   - Do not continue execution.
+- If the repository is dirty, HARD STOP.
+- If the current branch is detached HEAD, HARD STOP.
+- If local branch HEAD does not equal origin branch HEAD when an origin upstream exists, HARD STOP.
+- If the current branch is ahead of origin or has unpushed commits, HARD STOP.
+- If TEAM ownership mismatches the branch or scope, HARD STOP.
+- If cross-team scope is attempted without explicit Master Control assignment, HARD STOP.
 - Codex must report:
   - current branch
-  - expected branch (`main`)
+  - expected branch (`main` or approved `team/<TEAM>/<workstream>`)
   - local branches found
-- Codex may continue only after the user explicitly returns to `main`.
+  - upstream branch
+  - local/origin sync PASS/FAIL
+  - TEAM ownership PASS/FAIL
+- Codex may continue only after the user explicitly moves to `main` or an approved team workstream branch and all guard checks pass.
 
 Exception:
-- Explicit branch-audit or branch-comparison PRs may inspect non-main branches but must not perform implementation work on them.
+- Explicit branch-audit or branch-comparison PRs may inspect unapproved branches but must not perform implementation work on them.
 
 Required report output:
 - Current branch
+- Expected branch
+- Upstream branch
+- Local/origin sync PASS/FAIL
+- TEAM ownership PASS/FAIL
 - Branch validation PASS/FAIL
 
 ## SLIDER VALUE VISIBILITY REQUIREMENT
@@ -1988,8 +2014,8 @@ Codex owns Git execution for implementation PRs.
 
 Required workflow:
 1. Verify current branch.
-2. Checkout main.
-3. Pull latest main.
+2. Checkout `main` or the approved team workstream branch.
+3. Pull latest approved execution branch.
 4. Verify clean repository.
 5. Create PR branch.
 6. Implement changes.
@@ -1999,7 +2025,7 @@ Required workflow:
 10. Create Pull Request automatically.
 11. Resolve merge conflicts if encountered.
 12. Re-run validation after conflict resolution.
-13. Merge PR.
+13. Merge PR only after explicit owner/EOD approval.
 14. Return to main.
 15. Pull latest main.
 16. Continue to next approved PR.
@@ -2009,7 +2035,9 @@ Rules:
 - Do not ask the user if a branch should be pushed.
 - Treat PR creation as required.
 - Treat branch push as required.
-- Treat merge as required after validation passes.
+- Treat merge as required only after validation passes and explicit owner/EOD approval is provided.
+- Local-only commits are prohibited as completed workstream state.
+- Every completed PR scope must be committed and pushed before Codex continues to another PR.
 - If GitHub prompts `Would you like to create a Pull Request?`, answer YES automatically.
 - If merge conflicts occur:
   - preserve latest main
@@ -2025,15 +2053,58 @@ Required Git workflow report fields:
 - merge result
 - final main commit
 
+## GITHUB AUTHORITATIVE WORKSTREAM RULE
+
+GitHub is the authoritative workstream record.
+
+Rules:
+- GitHub branches, commits, and pull requests are the authoritative record for active and completed Codex workstreams.
+- Local-only commits are prohibited.
+- A PR scope is not complete until its scoped changes are committed and pushed to GitHub.
+- Every completed PR scope must be committed and pushed before Codex continues to another PR.
+- Push failure is a hard stop until resolved.
+- A branch ahead of origin is a hard stop because it contains unpushed commits.
+- Detached HEAD execution is prohibited for PR work.
+- Ownership mismatch is a hard stop.
+- This rule does not authorize merging.
+- EOD merge approval remains owner-controlled and requires explicit approval.
+
+Start-gate sync validation:
+- PASS when:
+  - current branch is not detached
+  - repository is clean
+  - current branch has an origin upstream
+  - `local == origin`
+  - local branch HEAD equals origin branch HEAD
+  - TEAM ownership matches the requested PR scope
+- FAIL when:
+  - current branch is detached HEAD
+  - repository is dirty
+  - branch is ahead of origin
+  - branch has unpushed commits
+  - local branch HEAD does not equal origin branch HEAD
+  - push failure is unresolved
+  - TEAM ownership mismatches the requested PR scope
+
+Required report output:
+- current branch
+- upstream branch
+- local commit
+- origin commit
+- local/origin sync PASS/FAIL
+- push result
+- TEAM ownership PASS/FAIL
+
 ## OWNER-CONTROLLED STABLE AND MERGE APPROVAL
 
 Stable promotion and merge approval are owner-controlled.
 
 Rules:
 - Codex may prepare scoped changes, reports, validation evidence, ZIP artifacts, branches, and PRs.
-- Codex must not merge a PR or mark a workstream stable without explicit approval from the assigned Team Alpha or Team Beta owner.
+- Codex must not merge a PR or mark a workstream stable without explicit approval from the assigned Team Alpha, Team Beta, or Team Gamma owner.
 - Master Control may recommend sequencing or assignment, but affected workstream owners control stable and merge approval.
 - This targeted section supersedes older automatic-merge wording when approval ownership is in question.
+- EOD merge approval remains owner-controlled and requires explicit approval.
 
 ## CODEX INSTRUCTION ENFORCEMENT START GATE
 
@@ -2047,14 +2118,19 @@ Required instruction reads:
 
 Required pre-change report:
 - Codex must report instruction compliance as `PASS` or `FAIL` before making file changes.
-- The report must include branch, clean status, PR TEAM owner, implementation path, validation scope, required report list, and ZIP requirement.
+- The report must include branch, expected branch, upstream branch, local/origin sync status, clean status, PR TEAM owner, implementation path, validation scope, required report list, and ZIP requirement.
 - Any `FAIL` is a hard stop unless the PR explicitly scopes branch audit or recovery documentation without implementation.
 
 Hard stops before changes:
-- If the current branch is not `main`, HARD STOP.
+- If the current branch is neither `main` nor an approved team workstream branch, HARD STOP.
 - If the repository is not clean before the PR branch is created, HARD STOP.
+- If the current branch is detached HEAD, HARD STOP.
+- If local branch HEAD does not equal origin branch HEAD when an origin upstream exists, HARD STOP.
+- If the current branch is ahead of origin or has unpushed commits, HARD STOP.
+- If a previous push failed and remains unresolved, HARD STOP.
 - If the PR name does not include a required TEAM token, HARD STOP.
 - If the PR TEAM owner does not match the team ownership map in `PROJECT_MULTI_PC.txt`, HARD STOP.
+- If cross-team scope is attempted without explicit Master Control assignment, HARD STOP.
 - If the PR asks for implementation and the implementation path is wrong, HARD STOP.
 - If a PR asks for functional parity and only placeholder-only work is possible, HARD STOP and report the missing source or blocker.
 - If scoped validation is skipped without a documented reason, HARD STOP.

docs_build/dev/PROJECT_MULTI_PC.txt

@@ -524,13 +524,44 @@ Governance, recovery, diagnostics, and instruction-hardening PRs:
 - Must document TEAM ownership compliance in the PR report.
 - Recovery reports must include TEAM ownership.
 
+Workstream Branch Execution Guard:
+- Approved execution branches are `main` and approved team workstream branches.
+- Approved team workstream branch format:
+  - `team/<TEAM>/<workstream>`
+- Workstream branch examples:
+  - `team/ALPHA/game-hub`
+  - `team/BETA/messages`
+  - `team/GAMMA/admin`
+- Hard stops include dirty repo, unapproved branch, TEAM mismatch, cross-team scope, detached HEAD, local/origin mismatch, and unpushed commits.
+- TEAM ownership must match the approved workstream branch and requested PR scope.
+- Cross-team work remains prohibited unless Master Control splits or assigns each PR to the correct TEAM token.
+
+GitHub Authoritative Workstream Rule:
+- GitHub is the authoritative workstream record.
+- GitHub branches, commits, and pull requests are the authoritative record for active and completed Codex workstreams.
+- Local-only commits are prohibited.
+- Every completed PR scope must be committed and pushed before Codex continues to another PR.
+- Start-gate sync validation is PASS only when the branch is clean and `local == origin`, meaning local HEAD equals origin HEAD.
+- Start-gate sync validation is FAIL when:
+  - branch is ahead of origin
+  - branch has unpushed commits
+  - current branch is detached HEAD
+  - push failure is unresolved
+  - TEAM ownership mismatches the requested PR scope
+- Branch ahead of origin is a hard stop.
+- Push failure is a hard stop until resolved.
+- Ownership mismatch is a hard stop.
+- EOD merge approval remains owner-controlled and requires explicit approval.
+
 Stable and merge approval:
 - Stable promotion and merge approval are controlled by the assigned Team Alpha, Team Beta, or Team Gamma owner.
 - Master Control may recommend sequencing, but Codex must not merge or mark stable without explicit owner approval for the affected workstream.
 
 Hard stop rules:
 - If the PR name does not include a TEAM token, stop before changes.
 - If the TEAM token does not match the owner map or explicit Master Control assignment, stop before changes.
+- If the execution branch is neither `main` nor an approved team workstream branch, stop before changes.
+- If branch sync validation fails, stop before changes.
 - If the PR scope belongs to another TEAM owner, stop before changes.
 - If the PR crosses multiple team ownership areas, stop and require Master Control to split or assign the work.
 - If the requested implementation path conflicts with the active owner path, stop before changes.

docs_build/dev/reports/PR_26171_GAMMA_010-replace-main-branch-guard-with-workstream-guard-instruction-compliance-checklist.md

@@ -0,0 +1,28 @@
+# Instruction Compliance Checklist - PR_26171_GAMMA_010
+
+- PR has one purpose only: PASS
+- Exact PR name provided: PASS
+- PR name includes TEAM token `GAMMA`: PASS
+- Exact branch name provided: PASS
+- Branch started from latest `main`: PASS
+- `docs_build/dev/PROJECT_INSTRUCTIONS.md` read before changes: PASS
+- `docs_build/dev/PROJECT_MULTI_PC.txt` read before changes: PASS
+- Instruction enforcement start gate run before changes: PASS
+- Repository clean before branch creation: PASS
+- `main` local/origin sync verified before branch creation: PASS
+- TEAM ownership verified as Gamma governance/instruction-hardening work: PASS
+- Scope limited to requested governance docs: PASS
+- Main-only branch guard replaced: PASS
+- Main-only BUILD start hard stop removed: PASS
+- Approved workstream branches allowed: PASS
+- Required hard stops preserved: PASS
+- GitHub authoritative sync rule preserved: PASS
+- Local-only commits remain prohibited: PASS
+- Owner-controlled EOD merge approval preserved: PASS
+- Runtime code unchanged: PASS
+- Required reports created: PASS
+- Manual validation notes created: PASS
+- ZIP required and pending final packaging: PASS
+- Playwright skipped with reason documented: PASS
+- Samples skipped with reason documented: PASS
+- PR merge withheld until explicit EOD approval: PASS

docs_build/dev/reports/PR_26171_GAMMA_010-replace-main-branch-guard-with-workstream-guard-manual-validation-notes.md

@@ -0,0 +1,27 @@
+# Manual Validation Notes - PR_26171_GAMMA_010
+
+## Scope Review
+
+Reviewed the governance docs after edit:
+- `docs_build/dev/PROJECT_INSTRUCTIONS.md`
+- `docs_build/dev/PROJECT_MULTI_PC.txt`
+
+Confirmed:
+- `MAIN BRANCH EXECUTION GUARD` is no longer present.
+- `WORKSTREAM BRANCH EXECUTION GUARD` is present.
+- The main-only BUILD start hard stop is gone.
+- Execution is allowed from `main` or approved team workstream branches.
+- Approved branch format is `team/<TEAM>/<workstream>`.
+- Hard stops remain for dirty repo, unapproved branch, TEAM mismatch, cross-team scope, detached HEAD, local/origin mismatch, and unpushed commits.
+- GitHub authoritative sync governance remains present.
+- Local-only commits remain prohibited.
+- Runtime code was not changed.
+- EOD merge approval remains owner-controlled and requires explicit approval.
+
+## Validation Notes
+
+Static validation was sufficient because this PR updates governance documentation only.
+
+Skipped lanes:
+- Playwright was not run because no UI route, component, or browser behavior changed.
+- Samples smoke was not run because samples are outside the requested docs/static validation scope.

docs_build/dev/reports/PR_26171_GAMMA_010-replace-main-branch-guard-with-workstream-guard.md

@@ -0,0 +1,64 @@
+# PR_26171_GAMMA_010-replace-main-branch-guard-with-workstream-guard
+
+## Summary
+
+This PR replaces the main-only branch execution guard with a workstream branch execution guard.
+
+Scope completed:
+- Replaced `MAIN BRANCH EXECUTION GUARD` with `WORKSTREAM BRANCH EXECUTION GUARD`.
+- Removed the main-only BUILD start hard stop.
+- Allowed execution from `main` or approved team workstream branches.
+- Added approved workstream branch format `team/<TEAM>/<workstream>`.
+- Preserved hard stops for dirty repo, unapproved branch, TEAM mismatch, cross-team scope, detached HEAD, local/origin mismatch, and unpushed commits.
+- Preserved GitHub authoritative workstream sync governance.
+- Preserved owner-controlled EOD merge approval.
+- Did not change runtime code.
+
+## Start Gate
+
+Instruction compliance start gate: PASS
+
+- Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`: PASS
+- Read `docs_build/dev/PROJECT_MULTI_PC.txt`: PASS
+- Checked out `main`: PASS
+- Pulled latest `main`: PASS
+- Verified current branch was `main` before creating PR branch: PASS
+- Verified repository was clean before creating PR branch: PASS
+- Verified `main` local/origin sync was `0 0`: PASS
+- Created PR branch from `main`: PASS
+- PR name includes TEAM token `GAMMA`: PASS
+- TEAM ownership verified as Gamma governance/instruction-hardening scope: PASS
+- Base `main` commit: `e8845dae6`
+
+## Git Workflow
+
+- PR branch: `pr/26171-GAMMA-010-replace-main-branch-guard-with-workstream-guard`
+- Branch created from: `main`
+- Branch push: pending at initial report generation
+- Pull request: pending at initial report generation
+- Merge status: not merged; EOD merge requires explicit owner approval
+- ZIP artifact path: `tmp/PR_26171_GAMMA_010-replace-main-branch-guard-with-workstream-guard_delta.zip`
+
+## Validation
+
+Requested validation scope was docs/static only.
+
+Executed:
+- `git diff --check`: PASS
+- Targeted text check verifying the old main-only hard stop is gone.
+- Targeted text check verifying approved workstream branches are allowed.
+- Targeted text check verifying local-only commits remain prohibited.
+- Targeted text check verifying GitHub authoritative sync governance remains present.
+- Targeted text check verifying EOD merge approval remains owner-controlled.
+
+Skipped:
+- Playwright: skipped by request; this PR modifies governance docs only.
+- Samples smoke: skipped by request; this PR modifies governance docs only.
+
+## Required Reports
+
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+- `docs_build/dev/reports/PR_26171_GAMMA_010-replace-main-branch-guard-with-workstream-guard.md`
+- `docs_build/dev/reports/PR_26171_GAMMA_010-replace-main-branch-guard-with-workstream-guard-manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26171_GAMMA_010-replace-main-branch-guard-with-workstream-guard-instruction-compliance-checklist.md`