About parent branches
Every Issue has a parent branch. It is declared when the Issue is planned, carried in the brief and pinned into the run. The Issue's worktree forks from the parent, and its pull request merges into the parent. The default parent is main.
An integration branch is a branch that is the parent of several Issues: planned, backlog or hot, from any tranche or none. When it is done, the Principal merges it into its own parent through the same gates.
With parent branches, every gate that reads main reads the parent instead. See Tranches and tasks.
| Role | Part |
|---|---|
| Planner | Declares **Parent:** when planning; absent means main |
| Principal | Creates an integration branch and merges it into its parent; declares the parent for a hot Issue |
| Controller | Forks, reserves, opens the pull request and measures against the frozen parent |
| Archivist | Closes the Issue when it archives a merge into a parent that is not the default branch |
How it works
- 1
Declare the parent
Add
**Parent:** <branch>to the Issue header. Leave it out to usemain. - 2
Freeze it in the brief
The frozen brief records the parent. From then on, the brief is the only source of the parent.
- 3
Fork, work and open the pull request against the parent
The worktree forks from the parent, and the pull request targets it.
- 4
Merge and close
The pull request merges into the parent. If the parent is not the default branch, the Archivist closes the Issue.
The rules
| Rule | Detail |
|---|---|
| The field | **Parent:** <branch> in the Issue header, beside **Project:**. Absent means main. The Issue gate refuses a parent that does not exist on the remote, or that equals the Issue's own branch. |
| Pinned, never live | The brief renders Parent: <branch> in place of the fixed "parent origin/main". The frozen brief is the only source. Changing the parent means superseding the brief, which voids the verdicts. |
| One resolver | A single resolver reads the Parent: line of the newest frozen brief. With no frozen brief, the parent is main. |
| Plan time | For a parent other than main, Issue validation and task preparation fetch origin/<parent> and read the premises and Surface globs from it. If the fetch fails, they refuse. |
| Controller and Developer | Every main in the loop becomes the frozen parent: worktree creation, the reservation push, the pull-request base, the ahead and fresh-branch checks, the conflict-retry base, and the merge prompt. Doctrine and brief text say origin/<parent>. |
| Status | merged means merged into the frozen parent (the pull request's base equals it). Detecting a reopen uses the time of the close event. |
| Dependencies | A Depends-on is satisfied when the dependency's merge commit is reachable from the dependent's parent tip (git merge-). |
| Close and archive | GitHub closes Issues by keyword only on the default branch, so the Archivist closes the Issue when it archives a merge into a parent. |
How each context gets the parent
| Context | Source |
|---|---|
The controller and task run | The brief they already hold |
| The check commands, run locally | The resolver, when BASE_SHA is unset |
| CI | BASE_SHA = git rev- in a new step of "Run checks". The review gate refuses when the pull request's base differs from the frozen parent. |
| Developer sandbox and reviewers | A new key, VINAYA_, passed to every dispatched role |
pr report Test Plan commands | VINAYA_ added to each command's environment |
verify-docs, verify-task, check-, open-pr | BASE_SHA, else VINAYA_, else origin/main |
| The coherence check | The frozen parent, through the resolver; never an input the pull request can edit |
Integration branches
- 1
Create the branch
The Principal creates it with
git push origin main:refs/. It becomes an integration branch the moment a frozen brief names it as a parent.heads/ <name> - 2
Run Issues against it
Issues with
**Parent:** <name>run as usual, and their pull requests merge into it. - 3
Merge it into its own parent
Write a hot Issue whose
## Surfacecoversgit diff -. Run- name- only <parent>. . . <integration> vinaya hot start -, open the pull request with- adopt- branch <integration> - - issue <m> vinaya pr create -, and review it with- head <integration> - - base <parent> vinaya hot review.
See Hot mode and the guide Deploy hot issue now for the hot steps.
What reads the parent instead of main
| Reader | With parent branches |
|---|---|
| Premises and Surface globs at plan time | origin/<parent> |
| Controller: worktree fork, reservation push, pull-request base, conflict retry | The frozen parent |
pr-, surface-scope, evidence-fresh, single-plan-pr, doc-coverage, doc-, no-disk-state, doctrine- | The resolver, or BASE_SHA |
Merge gate (review-gate) | Follows the pull request's declared base, and refuses a base that differs from the frozen parent |
Status (merged) and dependency satisfaction | Merged into the parent; merge commit reachable from the parent |
pr report | The resolver |
| Archivist workflow | branches-, with a pre-filter step |
| Direct-push audit | Every declared parent |
| Log envelope | The landing branch, filled from the frozen parent |
Gates
The planned changes to the gates:
- Issue write refuses a parent that does not exist, or that equals the Issue's branch.
review-gaterefuses a pull request whose base differs from the frozen parent.- The checks that use
BASE_compute against the parent. Their registry rows gain the optional inputsSHA || origin/ main BRANCH,AEG_REPO,GH_TOKENandGITHUB_TOKEN.
See Gates for each check.
Configuration
None. The parent is a field on the Issue, pinned by the brief, not a setting.
What gets logged
With parent branches, the Log envelope carries the landing branch, filled from the frozen parent. See Events.