From 2d7a932d8d095df999a20fd9218fa5d004d69ae9 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Thu, 13 Aug 2026 12:19:55 -0500 Subject: [PATCH] docs: define main/next branch model, sequencing, responsibilities, and merge process (#1214) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Commissioned by Jason 2026-08-13: agents need the branch-handling process written down — next-first for every contribution, Jason-only promotion merges to main, the gate sequence (issue, next-head base, terminal-green CI on the exact head, independent review, no self-merge, pinned-head merge), role responsibilities, and the hotfix/divergence rules motivated by the #1152 main-only landing. --- AGENTS.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a15279dd..f6c76683 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,6 +81,73 @@ pnpm format:check # Prettier check pnpm build # Build all packages and applications ``` +## Branch Model and Merge Process — `main` and `next` (CANONICAL) + +**Every contribution targets `next` first. No exceptions.** Features, fixes, tests, +docs, and policy changes all take the same route; urgency changes queue priority, +never the route. Agents never commit to or merge into `main`. + +| Branch | Role | Who merges into it | +| ------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------- | +| `next` | Integration trunk — the only PR target for contributions | The designated merge-gate agent, after all gates pass. Never the PR author. | +| `main` | Stable/release line — receives promotion merges from `next` only | Jason only (or an agent he explicitly delegates for a named promotion). | + +### Contribution sequencing (in order, no skipping) + +1. **Issue first.** Work is tracked in a Gitea issue before a branch exists. The + issue number appears in the branch name and the PR body. +2. **Branch from the current `origin/next` head.** Name it + `feat/…`, `fix/…`, `docs/…`, or `test/…` with the issue number + (e.g. `docs/1214-branch-process`). Record the base SHA in the PR body. +3. **Develop with evidence.** Applicable tests accompany the change. Hooks are + never bypassed (`--no-verify` is prohibited). Stage explicit paths — never + `git add -A`. +4. **Open the PR against `next`.** The body states: scope, base SHA, + verification commands with results, and any known pre-existing failures on + the base — documented, not retried to green and not absorbed silently. +5. **CI must be terminal-green on the exact head.** All bounded Woodpecker + steps succeed (`verify-terminal-green` contract). Pipelines for fork PRs + start `blocked`; a maintainer approves the run — approving CI is not + approving the PR. +6. **Independent review. Self-merge is prohibited** — for every agent, on every + PR, including trivial ones. Where the change touches protected or + contract-bearing content, the reviewer verifies the exact head + (exact-byte/exact-blob comparison), not a description of it. An `AMEND` + verdict returns the PR to its author; the reviewer's gate stays held until + a fresh exact head passes. +7. **Merge into `next`** happens only after CI green + review pass, pinned to + the reviewed head SHA (a post-review push voids the review). +8. **Promotion `next` → `main`** is a deliberate, Jason-owned reconciliation + merge — not part of any contribution's lifecycle. Contributors are done at + step 7. + +### Responsibilities + +- **Contributor** — base pinning, green CI, evidence in the PR body, + responding to AMEND verdicts, never merging own work. +- **Reviewer / merge gate** — independent verification on the exact head; + holds and lifts gates; executes the merge into `next`. +- **Orchestrator / adjudicator** — cross-PR sequencing, disposition when PRs + collide, conflict adjudication. +- **Jason** — `next` → `main` promotions, merge-authority grants, collaborator + and token provisioning. Agents cannot grant themselves or each other any of + these. + +### Hotfixes and divergence + +- A hotfix follows the same path: branch from `next`, PR to `next`, gates, + merge, then an expedited Jason-owned promotion if `main` needs it urgently. + Committing the fix to `main` directly is prohibited even under pressure. +- **Never land work on `main` that is not on `next`.** This has happened + (issue #1152's goal controller reached `main` without reaching `next`) and + every later PR paid for it. If it happens anyway: transplant the work onto + a `next`-based branch with provenance-preserving commits + (`git cherry-pick -x` or explicit SHA references in the messages), PR it + through the normal gates, and let promotion re-align `main`. Do not + hand-patch `main` to compensate. +- Force-pushing a branch you do not own is prohibited; rebasing your own PR + branch is fine before review, and voids any review already given. + ## Database and Local Runtime Safety - Current local data-layer work uses in-process PGlite; leave `DATABASE_URL` unset. -- 2.54.0