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 the merge styles the chain uses, plus rebase-updates (without which
   the merge queue's core primitive 403s).

   The chain uses exactly two: **squash** for `feat/*` → `dev`, and
   **fast-forward-only** for both promotions. Merge commits and rebase merges
   are disabled deliberately — see the merge-style table in the root
   `CLAUDE.md`. If `apply_flow_defaults` re-enables them, that is the tool
   disagreeing with the policy, not permission to use them.
3. **Protection.** `forge_branch_protection(branch="dev", apply=true)`, then
   `main`, then `release`.

   **All three** branches get the required check. `release` was the exception
   until 2026-08-01: `pr-build.yml` fired only for PRs into `dev` and `main`, so
   a PR into `release` reported no status at all, and requiring a context
   nothing produces makes every production promotion permanently unmergeable —
   a 405 that names no cause. This estate has already lost an afternoon to
   exactly that, from a single mistyped check name.

   It was closed in the only safe order, and that order still governs any change
   to the context name, or a new protected branch: add the branch to
   `pr-build.yml`'s `on.pull_request.branches`, confirm **on a real PR** that
   the context appears, *then* require it. Confirmed on #167 — the gate reported
   `PR build (required check) / gate (pull_request)` — before the check was
   enabled. 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="squash", 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="fast-forward-only"`.

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="fast-forward-only"` and tag it: `forge_releases(create={tag:"v<semver>", target:"release", ...})`.

**On fast-forward.** Both promotions move by fast-forward, and as of
2026-08-01 that is in force rather than aspirational. It was blocked until then
for a structural reason worth remembering: every promotion had been a merge
commit *into* the target, which the source never receives, so the branches were
mutually divergent by construction and Forgejo refused `fast-forward-only` —
correctly. The one-time reconciliation the old policy was waiting for has
happened; the trees were already identical, so it carried no content.

`release ⊆ main ⊆ dev` now holds, and a promotion lands the branches on the
same SHA rather than merely the same tree. Merge commits and rebase merges are
disabled repo-wide, so a slip fails loudly instead of quietly re-diverging the
chain. If Forgejo refuses with "diverging branches", the target has picked up a
commit the source lacks — reconcile it once, target into source, fast-forward.
Do not attempt to "fix" it 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.

### When you genuinely need to push directly

`apply_to_admins` is on, which means these rules bind the owner too. That is
deliberate — protection an admin walks straight through is documentation, not a
control, and every account here is an admin — but it does remove the escape
hatch, so the way back in is worth writing down before it is needed at 3am.

There is no force flag. The supported route is to lift the rule, do the thing,
and put it back:

```
forge_branch_protection(branch="dev", delete=true)   # rule gone; direct push allowed
git push origin dev                                   # the emergency change
forge_branch_protection(branch="dev", apply=true)     # restored to policy
```

Both the removal and the restore are audited, which is the point: the hatch is
open on the record rather than by a quiet exception. Restore it in the same
session — a protection rule "temporarily" removed is how a repo ends up
unprotected for a month.

The failure mode that actually justifies this: if the required status context
is ever renamed and no longer matches, **nothing can merge into `dev` or `main`
at all**, including by you, because `apply_to_admins` no longer exempts anyone.
`forge_pr_await` and `forge_pr_merge` both name that case explicitly when they
see it. The fix is to correct `pr-build.yml`'s workflow/job names and
`CENTRALIS_REQUIRED_CHECK` together — but if you need to land the fix itself,
lift the rule as above.

## 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`.