thermograph/.claude/BRANCHING.md

Orchestrator instructions — trunk-based flow

feat/* → dev → main → release. One PR per hop, merges serialised by the orchestrator. Forgejo has no native merge queue, so you are the merge queue.

Use the Centralis forge_* tools for every remote operation — PRs, protection, merges, tags. Use local git only for rebases you have to resolve by hand. Never call the Forgejo API with curl and a pasted token; the server holds it.

The same file exists in centralis with the same rules. Where the two repos differ it is noted inline.

---

The branches

Each branch has its own environment here, and infra/deploy/env-topology.sh is the single source of truth for where each one lives:

Branch	Deploys to	Receives
feat/*, fix/*	nothing	your work
dev	dev — vps1, mesh-only, own Postgres	feature PRs
main	beta — beta.thermograph.org, vps2	promotions from dev
release	prod — thermograph.org, vps2	promotions from main, and hotfixes

deploy.yml handles all three: the branch selects the environment, a matrix covers backend and frontend, and each leg checks whether the push actually touched its domain before rolling. So FE and BE ship out of lockstep — a backend change lands without a frontend deploy. That is the point of the split, and it is why /api/version and PAYLOAD_VER discipline are load-bearing: whatever you promote, the other half may already be running something older.

dev is the default branch, so PRs target it without anyone remembering to retarget. All three are protected: everything is a PR, for humans and agents alike.

Who may merge what

This is not the same question as how a change travels, and it is deliberately asymmetric. MERGE_AUTHORITY in centralis' src/lib/promotion.ts is the whole policy; forge_pr_merge enforces it.

• Into dev — free. Merge feature PRs yourself, and do not leave them open. A PR opened against dev and abandoned is an unfinished task wearing the costume of a delivered one.
• dev → main — yours, batched. Beta is the test environment, so withholding this merge withholds the testing. The judgement being asked of you is when a batch is coherent enough to be worth testing, not whether you are allowed to test it.
• main → release — the owner's. That merge deploys to prod. Call promote(from="main", to="release"), which prepares the PR and returns what would ship, the CI evidence and a recommendation. Then put it to the owner — including "I would wait", if that is what you think. No flag overrides this, and routing around it is not an option.

confirm_protected_base is unrelated to the above: it is the hotfix path for a non-promotion PR aimed straight at main or release, and it is audited loudly.

---

Phase 1 — repo setup

Idempotent. Re-run it whenever you are unsure; every step reports "already correct" rather than erroring.

1. The three branches exist. forge_branches(create={branch:"main", from:"dev"}) and the same for release. If a branch exists but points elsewhere, the tool says so — that is a divergence to reconcile deliberately, not to overwrite.

2. dev is the default branch. forge_repo_settings(apply_flow_defaults=true) — sets the default branch and permits every merge style the chain uses, including fast-forward-only, plus rebase-updates (without which the merge queue's core primitive 403s).

3. Protection. forge_branch_protection(branch="dev", apply=true), then main, then release.

   dev and main get the required check; release does not, and that is deliberate. pr-build.yml fires only for PRs into dev and main, so a PR into release reports no status at all — requiring a context nothing produces would make every production promotion permanently unmergeable, with a 405 that names no cause. This estate has already lost an afternoon to exactly that, from a single mistyped check name. If you want it closed properly, do it in this order: add release to pr-build.yml's on.pull_request.branches, confirm on a real PR that the context appears, then pass require_checks_on_release: true. The other order blocks prod.

4. Stale branches. forge_branches() lists every branch with its age, how much unmerged work it carries, and a verdict:

   • merged — nothing on it the trunk lacks. Delete freely.
   • stale — unmerged work, untouched 14+ days. File a stale-branch: <name> issue summarising its diff first, then delete. Never discard work silently.
   • ageing — 2+ days with work still on it. Report it; do not delete.

5. Module map. .claude/ownership.md — read it before partitioning work.

Phase 2 — the ongoing loop

Dispatching subagents

Partition by module using .claude/ownership.md. Never give two concurrent agents tasks touching the same files; if that is unavoidable, sequence them.

Inject this into every subagent task:

Branch off latest `dev` as feat/<slug>. Touch only these files/modules: <scope>.
One logical change, small diff. Rebase onto dev before opening your PR.
PR targets `dev`. The description must list: what changed, how it was tested,
files touched. Do not merge your own PR — the orchestrator handles all merges.

Keep a branch alive less than a day. A task bigger than that is several stacked tasks.

The merge queue

You merge one PR into dev at a time. For each:

1. forge_prs(base="dev") — the queue, with each PR's head sha and triage flag.
2. forge_pr_update(pr=N) — replay it onto the current tip. If the head sha does not move, it was already current and no CI will re-fire; do not sit waiting for a run that was never scheduled.
3. forge_pr_await(pr=N, until="checks_complete") — checks on the rebased head. The run you saw before the update was for a merge base that no longer exists.
4. forge_pr_merge(pr=N, method="rebase", delete_branch=true).
5. Only then move to the next PR.

block_on_outdated_branch is set on dev, so Forgejo enforces step 2 rather than trusting you to remember it: after one merge, the next PR is refused until it has been replayed. Treat that 405 as the queue working, not as a fault.

If a rebase conflicts: resolve it yourself if it is trivial and mechanical (under ~20 lines), otherwise hand it back to the owning agent with the conflict context. Do not resolve a large conflict on someone else's behalf.

Promotion: dev → main

Promote when dev is green and a coherent batch is complete — not on a timer, not mid-feature. promote(from="dev", to="main") opens the PR with the divergence, the conflict prediction and the changelog written into its body. Merge it with method="merge".

Unready work belongs behind a feature flag, or not on dev yet. Never promote around it with cherry-picks.

promote refuses a hop whose two tips have identical trees — the commit counts look like real work while the content is already on the target under different SHAs, and merging it would fire the target's deploys for nothing.

Promotion: main → release

Prepare with promote, then ask. On the owner's yes, merge with method="merge" and tag it: forge_releases(create={tag:"v<semver>", target:"release", ...}).

On fast-forward. The written policy is that release moves only by fast-forward. It cannot today: every promotion so far has been a merge commit into the target, which the source never receives, so the branches are mutually divergent by construction and Forgejo will refuse a fast-forward-only merge — correctly. The style is implemented and accepted by forge_pr_merge; adopting it needs a one-time reconciliation of the protected branches, which is the owner's decision. Until that happens, promotions are merge commits. Do not attempt to "fix" this with a rebase or a force-push.

Hotfix

1. forge_branches(create={branch:"hotfix/<slug>", from:"release"}).
2. Fix, PR into release, checks green, merge with confirm_protected_base: true, tag v<semver-patch>.
3. Immediately down-merge release → main and main → dev, as merges, not cherry-picks, in the same session. A hotfix that exists only on release is a regression scheduled for the next promotion.

Note that CI does not gate PRs into release — pr-build.yml fires only for dev and main. A hotfix's green evidence therefore has to come from somewhere else; say plainly where it came from rather than implying a check passed.

A hotfix that touches only one domain deploys only that domain. Check the other half's /api/version before assuming the fix is live end to end.

Guardrails

• Never force-push dev, main or release.
• Never merge a red PR, hotfix included. Fix CI, or fix the tests in the same PR.
• Never merge two green PRs back to back without re-checking the second against the new tip.
• If two down-merges or promotions conflict beyond the trivial, stop and report rather than resolving autonomously.
• Weekly: forge_branches() and report anything ageing or stale.