PR_26179_OWNER_013-project-branching-policy-document #258
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,151 @@ | ||
| # Project Branching Policy | ||
|
|
||
| Version: 2026.06.28.002 | ||
| Last Updated: 2026-06-28 | ||
| Owner: OWNER | ||
|
|
||
| ## Purpose | ||
|
|
||
| Define the repository branching policy for Independent PRs and Stacked PRs. | ||
|
|
||
| This document owns PR branching model decisions. Other Project Instructions documents may point here, but must not duplicate the full policy. | ||
|
|
||
| ## Independent PR | ||
|
|
||
| An Independent PR is a PR with no direct dependency on another open PR. | ||
|
|
||
| Rules: | ||
| - Independent PRs start from synchronized `main`. | ||
| - Independent PRs target `main`. | ||
| - Independent PRs must not reuse another feature branch as their starting point. | ||
| - Independent PR work must return to synchronized `main` before another unrelated Independent PR begins. | ||
|
|
||
| ## Stacked PR | ||
|
|
||
| A Stacked PR is a PR with a direct dependency on a previous PR branch or active team workstream branch. | ||
|
|
||
| Rules: | ||
| - Stacked PRs may start from the previous PR branch when there is a direct dependency. | ||
| - Stacked PRs belong under the documented active workstream. | ||
| - Stacked PRs must document dependency order before BUILD begins. | ||
| - A later stacked PR must not merge before every prior dependency PR is merged. | ||
|
|
||
| ## Owner Branching Rules | ||
|
|
||
| OWNER may create Independent PRs from synchronized `main` when the work has no direct dependency. | ||
|
|
||
| OWNER may also create Stacked PRs when dependency order, reviewability, or workstream continuity requires it. | ||
|
|
||
| OWNER stacked PRs must document the same dependency, review, and merge order required for all stacked work. | ||
|
|
||
| ## Non-Owner Team Branching Rules | ||
|
|
||
| Non-Owner teams use Stacked PR workstreams by default. | ||
|
|
||
| Non-Owner teams include Alfa, Bravo, Charlie, Delta, Golf, and any future non-Owner canonical team. | ||
|
|
||
| Non-Owner team PRs must start from the active team workstream branch or the documented previous PR branch unless OWNER explicitly grants a standalone/no-dependency exception. | ||
|
|
||
| ## Explicit Owner Exception Process For Team Independent PRs | ||
|
|
||
| A non-Owner team may create an Independent PR from `main` only when OWNER explicitly marks the task: | ||
|
|
||
| ```text | ||
| standalone/no-dependency | ||
| ``` | ||
|
|
||
| The exception must be documented before branch creation and must name: | ||
| - team | ||
| - PR name | ||
| - reason the PR has no dependency | ||
| - confirmation that the branch starts from synchronized `main` | ||
| - confirmation that the PR targets `main` | ||
|
|
||
| Without that explicit exception, Codex must treat the non-Owner team PR as Stacked. | ||
|
|
||
| ## Dependency Documentation Requirements | ||
|
|
||
| Every Stacked PR report must name: | ||
| - stack order | ||
| - previous PR dependency | ||
| - next PR dependency, if known | ||
| - starting branch | ||
| - intended merge order | ||
| - base branch | ||
| - source branch | ||
|
|
||
| ## Review Order | ||
|
|
||
| Stacked PRs must be reviewed in dependency order. | ||
|
|
||
| A later stacked PR may be reviewed for context, but OWNER approval must respect dependency order unless OWNER explicitly grants an exception. | ||
|
|
||
| ## Merge Order | ||
|
|
||
| Stacked PRs must be merged in dependency order. | ||
|
|
||
| A later stacked PR must not merge before all prior dependency PRs are merged and the stack base has been updated as required by GitHub. | ||
|
|
||
| ## Hard-Stop Validation Rules | ||
|
|
||
| Codex must HARD STOP before changing files when: | ||
| - the requested Independent PR does not start from `main` | ||
| - a non-Owner team PR starts from `main` without OWNER `standalone/no-dependency` approval | ||
| - the requested Stacked PR does not start from the documented previous PR branch or active workstream branch | ||
| - the Stacked PR lacks dependency order documentation | ||
| - the current branch changes unexpectedly | ||
| - the requested branch model conflicts with OWNER instructions | ||
|
|
||
| The hard-stop report must include: | ||
| - current branch | ||
| - expected branch | ||
| - requested PR model | ||
| - missing dependency or exception details | ||
| - worktree status | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Owner Independent PR | ||
|
|
||
| ```text | ||
| PR: PR_26179_OWNER_020-doc-cleanup | ||
| Model: Independent PR | ||
| Start: main | ||
| Base: main | ||
| Reason: no direct dependency | ||
| ``` | ||
|
|
||
| ### Owner Stacked PR | ||
|
|
||
| ```text | ||
| PR #1: PR_26179_OWNER_021-policy-foundation | ||
| Base: main | ||
|
|
||
| PR #2: PR_26179_OWNER_022-policy-followup | ||
| Base: PR_26179_OWNER_021-policy-foundation | ||
| Model: Stacked PR | ||
| Merge order: #1, then #2 | ||
| ``` | ||
|
|
||
| ### Non-Owner Team Stacked PR | ||
|
|
||
| ```text | ||
| PR #1: PR_26179_ALFA_030-tool-flow-foundation | ||
| Base: main | ||
|
|
||
| PR #2: PR_26179_ALFA_031-tool-flow-validation | ||
| Base: PR_26179_ALFA_030-tool-flow-foundation | ||
| Model: Stacked PR | ||
| Merge order: #1, then #2 | ||
| ``` | ||
|
|
||
| ### Non-Owner Team Independent Exception | ||
|
|
||
| ```text | ||
| OWNER exception: standalone/no-dependency | ||
| Team: Bravo | ||
| PR: PR_26179_BRAVO_040-small-doc-fix | ||
| Start: main | ||
| Base: main | ||
| Reason: isolated documentation fix with no branch dependency | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,13 +1,15 @@ | ||
| # Project Instructions Version | ||
|
|
||
| Current Project Instructions Version: 2026.06.28.002 | ||
|
|
||
| Last Updated: 2026-06-28 | ||
|
|
||
| ## Breaking Changes Summary | ||
|
|
||
| - Codex startup validation is mandatory before every task outcome. | ||
| - Project Instructions versions are repository-owned and increment independently of PR numbers. | ||
| - Added dedicated branching policy document. | ||
| - Startup validation now verifies the branching policy document was loaded instead of duplicating policy text. | ||
| - Codex must read this version file and the latest repository copy of `PROJECT_INSTRUCTIONS.md` before performing work. | ||
| - Codex must discard previously remembered Project Instructions and treat the repository copy as authoritative. | ||
| - Codex must validate canonical report and ZIP paths, branching model, and legacy path avoidance before work proceeds. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # PR_26179_OWNER_013-project-branching-policy-document Branch Validation | ||
|
|
||
| ## Result | ||
|
|
||
| PASS | ||
|
|
||
| ## Checks | ||
|
|
||
| | Check | Result | Notes | | ||
| | --- | --- | --- | | ||
| | Stacked PR model identified | PASS | This PR depends on PR #257. | | ||
| | Started from documented previous PR branch | PASS | Started from `PR_26179_OWNER_012-project-instructions-startup-validation`. | | ||
| | Worktree clean before branch creation | PASS | Verified before branch creation. | | ||
| | PR branch created | PASS | `PR_26179_OWNER_013-project-branching-policy-document`. | | ||
| | Work stayed on PR branch | PASS | No direct commit to `main`. | | ||
| | Documentation/governance scope | PASS | Only Project Instructions and reports changed. | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| # PR_26179_OWNER_013-project-branching-policy-document Manual Validation Notes | ||
|
|
||
| ## Notes | ||
|
|
||
| - Confirmed `PROJECT_BRANCHING_POLICY.md` owns the full branching policy. | ||
| - Confirmed startup validation now checks the branching policy source/version/status instead of duplicating Owner/team branch policy details. | ||
| - Confirmed `pr_workflow.md` points to `PROJECT_BRANCHING_POLICY.md` and no longer carries the full policy text. | ||
| - Confirmed Project Instructions version is `2026.06.28.002`. | ||
| - Confirmed no runtime or product files were modified. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| # PR_26179_OWNER_013-project-branching-policy-document Report | ||
|
|
||
| ## Purpose | ||
|
|
||
| Separate branching policy from startup validation mechanics. | ||
|
|
||
| ## Branching Model | ||
|
|
||
| - Model: Stacked PR | ||
| - Previous PR dependency: `PR_26179_OWNER_012-project-instructions-startup-validation` / PR #257 | ||
| - Starting branch: `PR_26179_OWNER_012-project-instructions-startup-validation` | ||
| - Merge order: PR #255, then PR #256, then PR #257, then this PR | ||
|
Comment on lines
+7
to
+12
There was a problem hiding this comment.
For this Stacked PR, the new Useful? React with 👍 / 👎. |
||
|
|
||
| ## Governance Outcome | ||
|
|
||
| - Added `dev/build/ProjectInstructions/PROJECT_BRANCHING_POLICY.md`. | ||
| - Moved full Independent PR and Stacked PR policy ownership into the dedicated branching policy document. | ||
| - Updated startup validation to verify the branching policy document was loaded instead of duplicating branch policy details. | ||
| - Incremented Project Instructions version to `2026.06.28.002`. | ||
| - Updated `PROJECT_INSTRUCTIONS_VERSION.md` with change notes for the branching policy document and startup validation change. | ||
| - Updated `pr_workflow.md` to point to the dedicated branching policy instead of duplicating full policy text. | ||
|
|
||
| ## Runtime Impact | ||
|
|
||
| None. This PR changes documentation/governance only. | ||
|
|
||
| ## ZIP | ||
|
|
||
| - `dev/workspace/zips/PR_26179_OWNER_013-project-branching-policy-document_delta.zip` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| # PR_26179_OWNER_013-project-branching-policy-document Requirement Checklist | ||
|
|
||
| | Requirement | Result | Notes | | ||
| | --- | --- | --- | | ||
| | Create `PROJECT_BRANCHING_POLICY.md` | PASS | Added under `dev/build/ProjectInstructions/`. | | ||
| | Define purpose | PASS | Included in policy document. | | ||
| | Define Independent PR | PASS | Included in policy document. | | ||
| | Define Stacked PR | PASS | Included in policy document. | | ||
| | Define Owner branching rules | PASS | Included in policy document. | | ||
| | Define non-Owner team branching rules | PASS | Included in policy document. | | ||
| | Define Owner exception process for team independent PRs | PASS | Included `standalone/no-dependency` process. | | ||
| | Define dependency documentation requirements | PASS | Included required report fields. | | ||
| | Define review order | PASS | Included dependency-order review rule. | | ||
| | Define merge order | PASS | Included dependency-order merge rule. | | ||
| | Define hard-stop validation rules | PASS | Included branch/model mismatch hard stops. | | ||
| | Include examples | PASS | Added Owner independent, Owner stacked, team stacked, and team exception examples. | | ||
| | Update startup validation to load branching policy | PASS | Startup block now includes Branching Policy source/version/status. | | ||
| | Increment version to `2026.06.28.002` | PASS | Updated version file and `PROJECT_INSTRUCTIONS.md`. | | ||
| | Preserve ZIP/report completion contract | PASS | Existing contract remains referenced and unchanged. | | ||
| | Do not modify implementation code | PASS | Documentation/governance only. | |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This catches conflicts with a requested branch model, but it does not cover the case where no Independent/Stacked model is declared. The same commit removes the previous
pr_workflow.mdhard stop for “the request does not say whether the PR is Independent or Stacked and the start branch is not clearly valid,” while this new file is now the SSoT for hard-stop rules; on an unclear BUILD/PLAN started from a feature branch, none of the listed conditions require Codex to stop before changing files.Useful? React with 👍 / 👎.