docs: define main/next branch model, sequencing, responsibilities, and merge process (#1214) #1215

2026-08-13T17:20:24Z

mos-dt-0 commented

2026-08-13 17:20:24 +00:00

Closes #1214. Commissioned by Jason (2026-08-13): write the main/next branch-handling process into AGENTS.md so every agent knows the route.

Base: next @ 216cd722. Docs-only — one new section, "Branch Model and Merge Process — main and next (CANONICAL)", inserted after Development Workflow.

What it codifies

next-first, no exceptions: every contribution (feature, fix, docs, test, policy) targets next via branch + PR; agents never commit to or merge into main.
main = promotion-only: receives Jason-owned reconciliation merges from next; expedited promotion is the hotfix route, never a direct commit.
Eight-step contribution sequence: issue → branch from next head (base SHA recorded) → evidence + hooks respected → PR to next with documented pre-existing failures → terminal-green CI on the exact head (fork pipelines need maintainer approval; approving CI ≠ approving the PR) → independent review with exact-head verification and no self-merge → pinned-head merge into next → done (promotion is not part of the contributor lifecycle).
Responsibilities: contributor / reviewer-merge-gate / orchestrator-adjudicator / Jason (promotions, authority grants, collaborators, tokens — agents cannot grant these to themselves or each other).
Divergence rule with the live lesson: #1152 landed on main without reaching next; the documented remedy is provenance-preserving transplant onto a next-based branch through normal gates, never hand-patching main.

Verification

Docs-only change; prettier --check AGENTS.md passes on the head. No code paths touched.

Closes #1214. Commissioned by Jason (2026-08-13): write the `main`/`next` branch-handling process into AGENTS.md so every agent knows the route. Base: `next` @ 216cd722. Docs-only — one new section, "Branch Model and Merge Process — `main` and `next` (CANONICAL)", inserted after Development Workflow. ## What it codifies - **next-first, no exceptions**: every contribution (feature, fix, docs, test, policy) targets `next` via branch + PR; agents never commit to or merge into `main`. - **`main` = promotion-only**: receives Jason-owned reconciliation merges from `next`; expedited promotion is the hotfix route, never a direct commit. - **Eight-step contribution sequence**: issue → branch from next head (base SHA recorded) → evidence + hooks respected → PR to next with documented pre-existing failures → terminal-green CI on the exact head (fork pipelines need maintainer approval; approving CI ≠ approving the PR) → independent review with exact-head verification and no self-merge → pinned-head merge into next → done (promotion is not part of the contributor lifecycle). - **Responsibilities**: contributor / reviewer-merge-gate / orchestrator-adjudicator / Jason (promotions, authority grants, collaborators, tokens — agents cannot grant these to themselves or each other). - **Divergence rule with the live lesson**: #1152 landed on `main` without reaching `next`; the documented remedy is provenance-preserving transplant onto a next-based branch through normal gates, never hand-patching `main`. ## Verification Docs-only change; `prettier --check AGENTS.md` passes on the head. No code paths touched.

mos-dt-0 added 1 commit 2026-08-13 17:20:25 +00:00

docs: define main/next branch model, sequencing, responsibilities, and merge process (#1214 )

ci/woodpecker/pr/ci Pipeline was successful

Details

2d7a932d8d

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.

mos-dt-0 referenced this pull request

2026-08-13 17:37:27 +00:00

Branch-model layering conflict: L0 Constitution gates 5/15 hardcode `main`; commissioned next-first policy (#1214/PR #1215) cannot merge until controlling sources align #1216

mos-dt-0 referenced this pull request

2026-08-13 18:36:52 +00:00

Branch-model layering conflict: L0 Constitution gates 5/15 hardcode `main`; commissioned next-first policy (#1214/PR #1215) cannot merge until controlling sources align #1216

mos-dt-0 referenced this pull request

2026-08-13 18:46:26 +00:00

docs(l0): parameterize hard gates on the project's integration trunk (#1216, Option A) #1217

mos-dt-0 referenced this pull request

2026-08-13 22:11:44 +00:00

Branch-model layering conflict: L0 Constitution gates 5/15 hardcode `main`; commissioned next-first policy (#1214/PR #1215) cannot merge until controlling sources align #1216