mosaicstack/stack
25
0
Fork 1
Code Issues 340 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

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

Merged
fred merged 1 commits from docs/1214-branch-process into next 2026-08-20 20:19:40 +00:00
Conversation 2 Commits 1 Files Changed 1
+67
Ghost commented 2026-08-13 17:20:24 +00:00
Copy Link
Copy Source

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.
Ghost 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.
rev-code-02 approved these changes 2026-08-20 16:19:27 +00:00
rev-code-02 left a comment
Member
Copy Link
Copy Source

Verdict: APPROVE — reviewed against measured present-day repo state, nothing in the section is false

Reviewer rev-code-02. Tree measured: origin/next @ 20ad89c; PR head 2d7a932 (fetched via refs/pull/1215/head — the remote branch is deleted; see note below).

Checked against today, not against 2026-08-13

  • Repo default_branch is next (API, measured 2026-08-20). The section does not mention the default branch — see the one should-fix below. Nothing it does state is falsified by the flip; the routing rule ("every PR targets next") is now backed by the repo setting itself.
  • main tip 7102ccb (08-13, #1200, inside the divergence window); main is 0-ahead / 193-behind next. The #1152 divergence the section cites as its live lesson was resolved exactly per the section's own remedy (absorb via #1324). History and forward policy both hold.
  • No competing branch-model content landed on next meanwhile; the insertion point (after Development Workflow) is intact; the rest of AGENTS.md contains zero main references, so the section is internally consistent with its file.
  • Recorded base 216cd722 is still an ancestor of next (base pin valid).
  • Step 5's "fork PRs start blocked" is consistent with an observed blocked pipeline (#1228, pipeline 2417); the block cause is not attributable from outside, so recorded as consistent, not proven.

Findings

[SHOULD FIX — follow-up PR, not blocking] The section names every branch's role but never states which is the repo default. It was written when the default was main; today it is next. One line ("the repository default branch is next") makes the section checkable against the repo setting and immune to a future silent flip. Requesting changes for one sentence would force an adoption cycle on a deleted branch; land it as a trivial follow-up.

[SUGGESTION] Step 5 reads as blocked = fork awaiting maintainer approval. CI is also serialized now (9abd7e3, "chore: serialize CI run"), so blocked can mean queued. An optional clause distinguishing the two would prevent agents misreading a queued pipeline as awaiting their approval.

[NOTE — adoption logistics] The head branch docs/1214-branch-process is deleted from the remote; Gitea still holds refs/pull/1215/head @ 2d7a932 and the PR remains mergeable. Any seat amending this PR must recreate the branch at that SHA first.

[CI] Pipeline 2411 is green, but this PR predates the base-image pin: its pipeline config runs ci-base:latest (mutable); the immutable pin ci-base:lock-9cb7ffcd8828 landed cb9a0d1 2026-08-19 23:42:05Z. The green is real but not a pinned green — a rerun could differ. Low materiality for a docs-only diff; stated for the record.

## Verdict: APPROVE — reviewed against measured present-day repo state, nothing in the section is false Reviewer rev-code-02. Tree measured: `origin/next` @ 20ad89c; PR head 2d7a932 (fetched via `refs/pull/1215/head` — the remote branch is deleted; see note below). ### Checked against today, not against 2026-08-13 - Repo `default_branch` is `next` (API, measured 2026-08-20). The section does not mention the default branch — see the one should-fix below. Nothing it does state is falsified by the flip; the routing rule ("every PR targets `next`") is now backed by the repo setting itself. - `main` tip 7102ccb (08-13, #1200, inside the divergence window); `main` is 0-ahead / 193-behind `next`. The #1152 divergence the section cites as its live lesson was resolved exactly per the section's own remedy (absorb via #1324). History and forward policy both hold. - No competing branch-model content landed on `next` meanwhile; the insertion point (after Development Workflow) is intact; the rest of AGENTS.md contains zero `main` references, so the section is internally consistent with its file. - Recorded base 216cd722 is still an ancestor of `next` (base pin valid). - Step 5's "fork PRs start blocked" is consistent with an observed blocked pipeline (#1228, pipeline 2417); the block cause is not attributable from outside, so recorded as consistent, not proven. ### Findings [SHOULD FIX — follow-up PR, not blocking] The section names every branch's role but never states which is the repo default. It was written when the default was `main`; today it is `next`. One line ("the repository default branch is `next`") makes the section checkable against the repo setting and immune to a future silent flip. Requesting changes for one sentence would force an adoption cycle on a deleted branch; land it as a trivial follow-up. [SUGGESTION] Step 5 reads as blocked = fork awaiting maintainer approval. CI is also serialized now (9abd7e3, "chore: serialize CI run"), so blocked can mean queued. An optional clause distinguishing the two would prevent agents misreading a queued pipeline as awaiting their approval. [NOTE — adoption logistics] The head branch `docs/1214-branch-process` is deleted from the remote; Gitea still holds `refs/pull/1215/head` @ 2d7a932 and the PR remains mergeable. Any seat amending this PR must recreate the branch at that SHA first. [CI] Pipeline 2411 is green, but this PR predates the base-image pin: its pipeline config runs `ci-base:latest` (mutable); the immutable pin `ci-base:lock-9cb7ffcd8828` landed cb9a0d1 2026-08-19 23:42:05Z. The green is real but not a pinned green — a rerun could differ. Low materiality for a docs-only diff; stated for the record.
rev-code-02 approved these changes 2026-08-20 16:19:55 +00:00
rev-code-02 left a comment
Member
Copy Link
Copy Source

Verdict: APPROVE — reviewed against measured present-day repo state, nothing in the section is false

Reviewer rev-code-02. Tree measured: origin/next @ 20ad89c; PR head 2d7a932 (fetched via refs/pull/1215/head — the remote branch is deleted; see note below).

Checked against today, not against 2026-08-13

  • Repo default_branch is next (API, measured 2026-08-20). The section does not mention the default branch — see the one should-fix below. Nothing it does state is falsified by the flip; the routing rule ("every PR targets next") is now backed by the repo setting itself.
  • main tip 7102ccb (08-13, #1200, inside the divergence window); main is 0-ahead / 193-behind next. The #1152 divergence the section cites as its live lesson was resolved exactly per the section's own remedy (absorb via #1324). History and forward policy both hold.
  • No competing branch-model content landed on next meanwhile; the insertion point (after Development Workflow) is intact; the rest of AGENTS.md contains zero main references, so the section is internally consistent with its file.
  • Recorded base 216cd722 is still an ancestor of next (base pin valid).
  • Step 5's "fork PRs start blocked" is consistent with an observed blocked pipeline (#1228, pipeline 2417); the block cause is not attributable from outside, so recorded as consistent, not proven.

Findings

[SHOULD FIX — follow-up PR, not blocking] The section names every branch's role but never states which is the repo default. It was written when the default was main; today it is next. One line ("the repository default branch is next") makes the section checkable against the repo setting and immune to a future silent flip. Requesting changes for one sentence would force an adoption cycle on a deleted branch; land it as a trivial follow-up.

[SUGGESTION] Step 5 reads as blocked = fork awaiting maintainer approval. CI is also serialized now (9abd7e3, "chore: serialize CI run"), so blocked can mean queued. An optional clause distinguishing the two would prevent agents misreading a queued pipeline as awaiting their approval.

[NOTE — adoption logistics] The head branch docs/1214-branch-process is deleted from the remote; Gitea still holds refs/pull/1215/head @ 2d7a932 and the PR remains mergeable. Any seat amending this PR must recreate the branch at that SHA first.

[CI] Pipeline 2411 is green, but this PR predates the base-image pin: its pipeline config runs ci-base:latest (mutable); the immutable pin ci-base:lock-9cb7ffcd8828 landed cb9a0d1 2026-08-19 23:42:05Z. The green is real but not a pinned green — a rerun could differ. Low materiality for a docs-only diff; stated for the record.

## Verdict: APPROVE — reviewed against measured present-day repo state, nothing in the section is false Reviewer rev-code-02. Tree measured: `origin/next` @ 20ad89c; PR head 2d7a932 (fetched via `refs/pull/1215/head` — the remote branch is deleted; see note below). ### Checked against today, not against 2026-08-13 - Repo `default_branch` is `next` (API, measured 2026-08-20). The section does not mention the default branch — see the one should-fix below. Nothing it does state is falsified by the flip; the routing rule ("every PR targets `next`") is now backed by the repo setting itself. - `main` tip 7102ccb (08-13, #1200, inside the divergence window); `main` is 0-ahead / 193-behind `next`. The #1152 divergence the section cites as its live lesson was resolved exactly per the section's own remedy (absorb via #1324). History and forward policy both hold. - No competing branch-model content landed on `next` meanwhile; the insertion point (after Development Workflow) is intact; the rest of AGENTS.md contains zero `main` references, so the section is internally consistent with its file. - Recorded base 216cd722 is still an ancestor of `next` (base pin valid). - Step 5's "fork PRs start blocked" is consistent with an observed blocked pipeline (#1228, pipeline 2417); the block cause is not attributable from outside, so recorded as consistent, not proven. ### Findings [SHOULD FIX — follow-up PR, not blocking] The section names every branch's role but never states which is the repo default. It was written when the default was `main`; today it is `next`. One line ("the repository default branch is `next`") makes the section checkable against the repo setting and immune to a future silent flip. Requesting changes for one sentence would force an adoption cycle on a deleted branch; land it as a trivial follow-up. [SUGGESTION] Step 5 reads as blocked = fork awaiting maintainer approval. CI is also serialized now (9abd7e3, "chore: serialize CI run"), so blocked can mean queued. An optional clause distinguishing the two would prevent agents misreading a queued pipeline as awaiting their approval. [NOTE — adoption logistics] The head branch `docs/1214-branch-process` is deleted from the remote; Gitea still holds `refs/pull/1215/head` @ 2d7a932 and the PR remains mergeable. Any seat amending this PR must recreate the branch at that SHA first. [CI] Pipeline 2411 is green, but this PR predates the base-image pin: its pipeline config runs `ci-base:latest` (mutable); the immutable pin `ci-base:lock-9cb7ffcd8828` landed cb9a0d1 2026-08-19 23:42:05Z. The green is real but not a pinned green — a rerun could differ. Low materiality for a docs-only diff; stated for the record.
fred merged commit c671290d77 into next 2026-08-20 20:19:40 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
rev-code-02
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-dogfood-01 (Mosaic fleet seat code-dogfood-01) code-infra-01 (Mosaic fleet seat code-infra-01) darkwing (Mosaic fleet seat darkwing) dewey (Mosaic fleet seat dewey) fargo filbert (Mosaic fleet seat filbert) fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) marcie merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) orch-01 (Mosaic fleet seat orch-01) pepper resume rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) rocko (Mosaic fleet seat rocko) sanity scooby (Scooby) scrappy shaggy tiny topher (Mosaic fleet seat topher) velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1215