PR_26175_OWNER_048 define PR open closed governance

Author: ToolboxAid

docs_build/dev/PROJECT_INSTRUCTIONS.md

@@ -5,6 +5,11 @@ You are working in a docs-first repo workflow.
 Workflow:
 PLAN_PR → BUILD_PR → APPLY_PR
 
+PR lifecycle gate:
+PR Open → Building → Validation → Approved → Merged → Main Verified → Closed
+
+The PLAN_PR → BUILD_PR → APPLY_PR workflow remains preserved. PR Open is the first lifecycle status for active work, and Closed is the final repository-state gate.
+
 # WORKFLOW & EXECUTION
 
 ## PR NAMING STANDARD
@@ -44,6 +49,60 @@ Rules:
 - Existing PC/LAPTOP, desktop/laptop, workspace, environment, or machine-parity examples are historical only
 - Future PR reports, recovery reports, validation reports, and manual validation notes must include TEAM ownership
 
+## PR LIFECYCLE STATE GATE
+
+Required state order:
+
+1. PR Open
+2. Building
+3. Validation
+4. Approved
+5. Merged
+6. Main Verified
+7. Closed
+
+Definitions:
+- PR Open is the first active lifecycle state.
+- PR Open means the PR or branch has been created and named, and the work has a tracked PR identity before implementation begins.
+- No BUILD_PR may proceed without a PR name and active branch/PR identity unless it is explicitly marked `PLAN_ONLY`.
+- Building means scoped implementation, audit, report, validation, governance, or cleanup work is in progress for that PR identity.
+- Validation means requested checks, required report creation, manual validation notes, and ZIP packaging are being completed.
+- Approved means the owner or required reviewer has approved the PR outcome or intentionally approved closure without merge.
+- Merged means the PR has merged or has been intentionally closed without merge with the reason recorded.
+- Main Verified means Codex is back on `main`, `main` includes the merge commit or recorded final commit, the worktree is clean, local/origin sync is `0/0`, and no untracked files remain.
+- Closed means every Closed gate below is PASS.
+
+Closed is valid only when all are PASS:
+- PR merged or intentionally closed without merge with reason recorded.
+- Changes pushed.
+- Current branch is `main`.
+- `main` includes the merge commit or recorded final commit.
+- Worktree clean.
+- Local/origin sync is `0/0`.
+- No untracked files.
+- Branch disposition recorded as `deleted`, `retained for follow-up`, or `archived`.
+- Required reports exist.
+- Required repo-structured ZIP under `tmp/` exists.
+
+Hard stop:
+- A team must not begin another PR if its previous PR is not Closed.
+- Exception is allowed only for explicitly documented stacked PR chains.
+
+Required final closeout output:
+
+```text
+FINAL REPOSITORY STATE:
+- Branch
+- Worktree
+- Local/origin sync
+- PR number/name
+- PR status
+- Merge/final commit
+- Branch disposition
+- ZIP path
+- Closeout PASS/FAIL
+```
+
 ## CHATGPT EXECUTION ROLE
 
 ChatGPT no longer creates PLAN_PR, BUILD_PR, APPLY_PR docs, ZIP bundles, or implementation code.
@@ -1662,6 +1721,8 @@ Before packaging any PR, Codex must:
 
 Codex must not package partially completed PRs.
 
+PR completion is not the same as Closed. Closed requires the final repository-state gate from `PR LIFECYCLE STATE GATE`.
+
 ## ERROR HANDLING CONTRACT
 
 - No silent fallback.

docs_build/dev/ProjectInstructions/addendums/branch_context_governance.md

@@ -18,6 +18,8 @@ At the start of work, report or validate:
 - worktree status
 - active team
 - active assignment
+- active PR number/name or explicit `PLAN_ONLY`
+- previous PR Closed status unless this is an explicitly documented stacked PR chain
 
 ## Stop Conditions
 
@@ -28,6 +30,8 @@ Stop and report before changing files when:
 - worktree has unrelated changes
 - active assignment is missing or unclear
 - active team does not match the branch or OWNER instruction
+- BUILD_PR work has no PR name and active branch/PR identity, unless explicitly marked `PLAN_ONLY`
+- the team's previous PR is not Closed and no stacked PR chain is documented
 - the requested work would modify files outside the approved scope
 
 ## Continuation Rule
@@ -45,6 +49,16 @@ Do not automatically return to `main` after:
 
 Return to `main` only 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.
+
+Closed branch context requires:
+- current branch is `main`
+- `main` includes the merge commit or recorded final commit
+- worktree clean
+- local/origin sync is `0/0`
+- no untracked files
+- branch disposition recorded as `deleted`, `retained for follow-up`, or `archived`
+
 ## GitHub Authority
 
 GitHub is authoritative for open PR state, merged PR state, review state, and remote branch state.

docs_build/dev/ProjectInstructions/addendums/branch_lock_governance.md

@@ -13,6 +13,9 @@ Keep active work attached to the correct assigned team, branch, and OWNER decisi
 - An assigned work item keeps its owner of record until complete or OWNER reassignment.
 - Work must not move to another team, branch, or PR without OWNER approval.
 - A team with no active assignment, active branch, or active PR is inactive.
+- A team with a previous PR that is not Closed must not begin another PR unless OWNER documented an explicit stacked PR chain.
+- PR Open begins only after the branch and PR identity are named.
+- Closed ends only after the final main-return, clean-worktree, local/origin `0/0`, no-untracked-files, required-report, required-ZIP, and branch-disposition gates pass.
 - Project Instructions must not assume a permanent team roster.
 
 ## Branch Rules
@@ -22,6 +25,7 @@ Keep active work attached to the correct assigned team, branch, and OWNER decisi
 - 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` unless OWNER explicitly approves.
 - Do not merge stale historical branches directly unless they are current, clean, still needed, and OWNER-approved.
+- Record branch disposition before Closed as one of: `deleted`, `retained for follow-up`, or `archived`.
 
 ## OWNER Override
 

docs_build/dev/ProjectInstructions/addendums/multi_team.md

@@ -122,6 +122,7 @@ Required gate:
    - next review queue
    - final branch/worktree/local-origin sync
    - repo-structured ZIP path under `tmp/`
+   - final repository state block
 
 OWNER_049 lesson:
 - PRs #129, #132, and #134 were merge-approved and still required merge execution.
@@ -150,6 +151,8 @@ Required steps:
 5. Record final main commit.
 6. Report final repository state.
 7. Produce a repo-structured ZIP under `tmp/` that includes the EOD report and all changed or preserved repo files from the closeout.
+8. Record branch disposition as `deleted`, `retained for follow-up`, or `archived`.
+9. Mark the PR Closed only when every Closed gate passes.
 
 Required final state:
 
@@ -167,11 +170,27 @@ Rules:
 - A workstream is not considered closed until the repository is returned to main.
 - A PI is not considered complete until main is current and synchronized.
 - Do not leave Codex on a feature, team, workstream, recovery, governance, or owner branch after successful merge.
+- A PR is not Closed until the PR merged or an intentional no-merge close reason is recorded, changes are pushed, the repository is on `main`, `main` includes the merge or final commit, the worktree is clean, local/origin sync is `0/0`, no untracked files exist, branch disposition is recorded, required reports exist, and the required repo-structured ZIP exists under `tmp/`.
 - A completed EOD closeout must produce the required ZIP even when the closeout changed no repo files; in that case, the ZIP must contain the EOD report proving the no-change result.
 - The EOD ZIP does not replace the EOD report or other required reports under `docs_build/dev/reports/`.
 - If merge succeeds but repository is not returned to main:
   closeout status = FAIL.
 
+Required final closeout output:
+
+```text
+FINAL REPOSITORY STATE:
+- Branch
+- Worktree
+- Local/origin sync
+- PR number/name
+- PR status
+- Merge/final commit
+- Branch disposition
+- ZIP path
+- Closeout PASS/FAIL
+```
+
 ## Workstream Hygiene Governance
 
 At workstream closeout, Codex must review repository collaboration state before reporting the workstream closed.

docs_build/dev/ProjectInstructions/addendums/pr_workflow.md

@@ -12,16 +12,53 @@ Define the standard pull request workflow for Game Foundry Studio.
 1. Start from main.
 2. Pull latest origin/main.
 3. Verify clean worktree.
-4. Create a PR branch.
-5. Make scoped changes only.
-6. Validate the change.
-7. Commit with a clear OWNER/team message.
-8. Push the branch.
-9. Open a draft PR.
-10. Review the PR.
-11. OWNER approves merge.
-12. Merge to main.
-13. Pull latest main before starting the next PR.
+4. Create a PR branch and PR identity.
+5. Mark lifecycle state as PR Open.
+6. Make scoped changes only.
+7. Validate the change.
+8. Commit with a clear OWNER/team message.
+9. Push the branch.
+10. Open or update the draft PR.
+11. Review the PR.
+12. OWNER approves merge or intentional close without merge.
+13. Merge to main or record the approved no-merge close reason.
+14. Pull latest main before starting the next PR.
+15. Verify Main Verified and Closed gates.
+
+## PR Lifecycle States
+
+Required state order:
+
+1. PR Open
+2. Building
+3. Validation
+4. Approved
+5. Merged
+6. Main Verified
+7. Closed
+
+Definitions:
+- PR Open is the first active lifecycle state.
+- PR Open means the branch and PR identity are created and named before implementation begins.
+- No BUILD_PR may proceed without a PR name and active branch/PR identity unless explicitly marked `PLAN_ONLY`.
+- Building means scoped work is in progress.
+- Validation means requested checks, required reports, manual validation notes, and ZIP packaging are underway.
+- Approved means OWNER or required reviewer approval exists for merge or intentional close without merge.
+- Merged means the PR merged, or the approved no-merge close reason is recorded.
+- Main Verified means current branch is `main`, `main` includes the merge or final commit, worktree is clean, local/origin sync is `0/0`, and no untracked files remain.
+- Closed is valid only after every Closed gate passes.
+
+Closed gates:
+- PR merged or intentionally closed without merge with reason recorded.
+- Changes pushed.
+- Current branch is `main`.
+- `main` includes the merge commit or recorded final commit.
+- Worktree clean.
+- Local/origin sync is `0/0`.
+- No untracked files.
+- Branch disposition is recorded as `deleted`, `retained for follow-up`, or `archived`.
+- Required reports exist.
+- Required repo-structured ZIP under `tmp/` exists.
 
 ## Rules
 
@@ -31,6 +68,8 @@ Define the standard pull request workflow for Game Foundry Studio.
 - Do not mix unrelated scopes.
 - Do not start dependent PRs until the required base PR is merged.
 - Always return to main before starting the next PR.
+- A team must not begin another PR if its previous PR is not Closed.
+- Exception is allowed only for explicitly documented stacked PR chains.
 - If validation fails, stop and report.
 - If conflict occurs, stop and report.
 - If OWNER decision is required, stop and report.

docs_build/dev/ProjectInstructions/addendums/team_release_readiness.md

@@ -20,6 +20,9 @@ Teams may start only when all of the following are true:
 - No-direct-main rule exists.
 - Out-of-scope stop rule exists.
 - Build Path sync rule exists.
+- PR lifecycle states exist in order: PR Open, Building, Validation, Approved, Merged, Main Verified, Closed.
+- Previous-PR Closed gate exists before a team starts another PR, except explicitly documented stacked PR chains.
+- Final closeout output includes branch, worktree, local/origin sync, PR number/name, PR status, merge/final commit, branch disposition, ZIP path, and Closeout PASS/FAIL.
 
 ## Gate Outcome
 

docs_build/dev/ProjectInstructions/addendums/team_start_and_release.md

@@ -19,6 +19,7 @@ Before a team starts, validate:
 - active assignment is selected or confirmed by OWNER
 - assigned team uses NATO phonetic naming
 - work remains with the assigned team until complete or OWNER reassignment
+- the team's previous PR is Closed, unless OWNER documented an explicit stacked PR chain
 
 ## Current Four-Team Start Set
 
@@ -60,10 +61,12 @@ For backlog-driven work:
 1. Read `docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md`.
 2. Select only the OWNER-approved backlog item.
 3. Use the approved status model from `status_model.md`.
-4. Create or use the approved team branch.
-5. Record active work in the active team registry when required.
-6. Open a draft PR after validation.
-7. Merge only through OWNER-approved PR workflow.
+4. Confirm the previous PR for the team is Closed, unless this is an explicitly documented stacked PR chain.
+5. Create or use the approved team branch and PR identity.
+6. Mark lifecycle state as PR Open before BUILD_PR work begins.
+7. Record active work in the active team registry when required.
+8. Open or update a draft PR during active work.
+9. Merge only through OWNER-approved PR workflow.
 
 ## Team Command Examples
 
@@ -87,6 +90,19 @@ A team or OWNER PR is release-ready when:
 - branch context is correct
 - active assignment or OWNER ownership is clear
 - PR summary states the validation result
+- lifecycle state is at least Validation
+- required reports and repo-structured ZIP under `tmp/` exist before Closed
+
+Closed readiness requires:
+- PR merged or intentionally closed without merge with reason recorded
+- current branch is `main`
+- worktree clean
+- local/origin sync is `0/0`
+- no untracked files
+- merge or final commit recorded
+- branch disposition recorded as `deleted`, `retained for follow-up`, or `archived`
+- required reports exist
+- required repo-structured ZIP under `tmp/` exists
 
 ## Gate Behavior
 

docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md

@@ -17,6 +17,7 @@ Rules:
 - Registry must be updated when assignments change.
 - Registry must be updated when branches are retired.
 - Registry must be updated when PRs merge.
+- Registry must record when a team PR reaches Closed before that team begins another PR, unless OWNER documented an explicit stacked PR chain.
 - Teams with no active work are omitted.
 
 A team is Active when:
@@ -138,6 +139,9 @@ Rules:
 - Each PR must still have one clear purpose.
 - Each PR must create its own branch.
 - Each PR must be committed, pushed, and opened as a draft PR.
+- Each PR starts at PR Open after the branch and PR identity are named.
+- Each PR reaches Closed only after main-return, clean-worktree, local/origin `0/0`, no-untracked-files, required-report, required-ZIP, and branch-disposition gates pass.
+- A team must not begin another PR until its previous PR is Closed unless OWNER documented an explicit stacked PR chain.
 - Do not commit directly to main.
 - Do not merge without explicit owner approval.
 - If later PRs depend on earlier unmerged PRs, Codex must either:
@@ -164,6 +168,8 @@ Rules:
 - Each PR must create or use its own approved branch.
 - Each PR may be committed and pushed during active work.
 - Each PR may be opened as a draft PR during active work.
+- Each PR must move through PR Open, Building, Validation, Approved, Merged, Main Verified, and Closed in order.
+- A team must not begin another PR until its previous PR is Closed unless OWNER documented an explicit stacked PR chain.
 - Do not commit directly to main.
 - Do not merge to main during active work unless the owner explicitly says: "Merge this PR now."
 - If later PRs depend on earlier unmerged PRs, Codex must either: