From f45c987d0c271a4b5a74edf05d5964965991bd3d Mon Sep 17 00:00:00 2001 From: Bailey Dixon Date: Wed, 15 Jul 2026 14:06:15 -0400 Subject: [PATCH] docs: declare project-specific branch topology --- AGENTS.md | 6 +++++ DEVLOG.md | 15 +++++++++++++ RELEASE.md | 17 ++++++++++++-- docs/engineering/work-management.md | 35 +++++++++++++++++++++++++---- 4 files changed, 67 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2bba1bac..d99022a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -170,3 +170,9 @@ hardcoded — those should stay small regardless of Appearance. serialized. See `docs/engineering/work-management.md` and `RELEASE.md`. - Use timestamped Prisma migration directories to prevent parallel numbering collisions. +- Forge's branch contract is trunk-based: integration branch `main`, release + branch `main`, tag source `main`, staging source an exact `main` SHA, and + production source an immutable `v*` tag. Hotfixes branch from and return to + `main`; there is no back-merge target. Other repositories may declare a + different contract, such as Hermes Relay's `feature → dev → main → tag` + release train. diff --git a/DEVLOG.md b/DEVLOG.md index 39d7847f..bf60e79c 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -2,6 +2,21 @@ > Append-only session log. Read at session start. Update at session end. +## 2026-07-16 — Project-declared branch topology + +Reconciled the shared delivery policy after clarifying Forge's trunk-based flow +against Hermes-Relay's integration train. Repository guidance now requires each +project to declare its integration branch, release branch, tag source, staging +and production sources, hotfix base, and back-merge target. Forge explicitly +uses `feature → main → tag`; staging may deploy an exact `main` SHA and does not +justify a branch by itself. + +The durable Obsidian Development Standards and Axiom Delivery Workflows no +longer prescribe GitFlow-lite universally. Forge's release note mirrors its +trunk contract, Hermes runtime integration defers to the target repository, and +the Hermes-Relay project note now defines `feature → dev → release PR → main → +surface tag`, including separate release ownership and hotfix back-merge rules. + ## 2026-07-15 — Clean-checkout worker image follow-up The first guarded v0.20.0 deployment correctly stopped before production when diff --git a/RELEASE.md b/RELEASE.md index 590572d4..fb2e857d 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -25,8 +25,21 @@ fix/-* ← bugfix branches from main resumed or abandoned, never silently replaced. - The checkout used for production is deployment-only. Development happens in task-owned worktrees and never in the production or integration checkout. -- No long-lived `dev`/`staging` branch. Reintroduce one only if/when a separate - **staging deploy target** exists (then: `feat/* → PR → dev (staging) → PR → main (prod)`). +- No long-lived `dev`/`staging` branch. Staging may deploy an exact `main` SHA; + an environment does not require a matching branch. Introduce `dev` only if + Forge needs a genuine integration/stabilization train, then document the new + PR, release, hotfix, and back-merge rules before using it. + +Forge's explicit branch contract: + +| Setting | Value | +| --- | --- | +| Integration branch / normal PR base | `main` | +| Release branch / tag source | `main` | +| Staging source | Exact tested `main` SHA | +| Production source | Immutable `vX.Y.Z` tag contained in `main` | +| Hotfix base | Current production tag or `main` | +| Back-merge target | None; `main` is the only long-lived branch | ## Versioning diff --git a/docs/engineering/work-management.md b/docs/engineering/work-management.md index c1181c5d..2aa1c3a6 100644 --- a/docs/engineering/work-management.md +++ b/docs/engineering/work-management.md @@ -8,7 +8,9 @@ state. The same rules apply to humans, agents, and outside contributors. Before changing code: -1. Start from current `origin/main`. +1. Read the repository's `AGENTS.md` and `RELEASE.md`, then start from its + declared integration branch (`origin/main` for Forge, `origin/dev` for + Hermes Relay). 2. Check the issue's **Delivery** card for active ownership. 3. Claim one work session with the repository, branch, base branch, and isolated worktree path. @@ -17,7 +19,31 @@ Before changing code: Branch names include the issue key and owner namespace, for example `codex/axi-123-short-description` or `bailey/axi-123-short-description`. -Never work directly in `main` or in the production checkout. +Never work directly in a long-lived integration/release branch or in the +production checkout. + +## Project branch contract + +Branch topology is project configuration, not an Axiom-wide constant. Every +maintained repository declares these seven facts in `AGENTS.md` or +`RELEASE.md`: + +| Fact | Meaning | +| --- | --- | +| Integration branch | Normal feature/fix PR target | +| Release branch | Durable released-code history | +| Tag source | Branch/commit from which immutable release tags are cut | +| Staging source | Exact branch SHA or tag deployed to staging | +| Production source | Exact tag/SHA accepted by production | +| Hotfix base | Ref used to begin an emergency fix | +| Back-merge target | Branches that must receive the hotfix afterward | + +Supported shapes include trunk-based (`feature → main → tag`), an integration +train (`feature → dev → release PR → main → tag`), upstream-tracking forks, and +an external maintainer's contribution model. A staging environment does not by +itself require a `dev` branch: staging can deploy an exact `main` SHA. Add a +long-lived integration branch only when the project needs multi-change +integration, scheduled stabilization, or an upstream convention. ## During implementation @@ -51,7 +77,8 @@ serialized. - Every code change lands through a PR, including agent work and hotfixes. - CI must be green on the current head. - Address unresolved review threads before merge. -- Refresh from `origin/main` when the base changed materially. +- Refresh from the declared integration branch when the base changed + materially. - Squash-merge, delete the remote branch, then remove the local worktree. - The issue is not done merely because an agent stopped or a PR opened. @@ -74,7 +101,7 @@ Production builds an exact tag or commit from a dedicated clean checkout. The development checkout is never a deployment source. A deploy is accepted only when: -- the target commit is on `origin/main`; +- the target commit is contained in the repository's declared release branch; - the checkout is clean; - CI/local release gates passed; - the deployment lock is held;