# Git workflow

## Branches

| Branch | Role |
|---|---|
| `master` | Stable trunk. **Protected**: changes land only via pull request; no force-push, no deletion. |
| `dev` | Integration branch — the day-to-day working branch. Cut from `master`. |
| `feat/*` | One branch per (module × surface) cell, cut from `dev`. |
| `backup-native` | The legacy pre-rebuild tree as it stood on `master` before the greenfield push. **Reference only — never merge.** |
| `togo`, `backup` | Older legacy snapshots kept from the previous repo. Reference only. |

## The loop, one cell at a time

```bash
git checkout dev && git pull                 # start from the integration branch
git checkout -b feat/m1-hydration-backend    # one cell per branch

# ... build the cell, following its session card ...
make ci                                      # vet, build, test, schema-lint

git push -u origin feat/m1-hydration-backend
gh pr create --base master --fill            # PR targets master
gh pr merge --squash --delete-branch         # merge once green

git checkout dev && git merge --ff-only master && git push   # keep dev in step
```

**Branch naming:** `feat/<module>-<surface>` (e.g. `feat/m1-hydration-backend`,
`feat/m0.6-web-theme`). Use `fix/…` for defects and `chore/…` for tooling.

**Commit messages:** conventional-commit prefix plus the cell, e.g.
`feat(m1-backend): hydration engine plugin`. Explain *why* in the body — the
protocol decisions are the valuable part.

## Rules

1. **One cell per PR.** A PR that spans two cells cannot be reviewed against a
   single session card's done-criteria.
2. **CI must be green** before merge: `vet`, `build`, unit tests, the
   NOT NULL + DEFAULT schema-lint gate, the real-Postgres integration suite,
   and the compose smoke test.
3. **The PR checklist is the gate**, not a formality — it restates the
   invariants (SSOT/thin-client, the Two Core Opinions, brand tokens, ICU/RTL,
   secrets) that a reviewer would otherwise have to remember.
4. **Squash-merge** so `master` reads as one commit per cell.
5. **Every merged cell ends with a brain handoff** and a `build-ledger` update
   (`docs/team/README.md` → handoff protocol), so the next session resumes cold.
6. **Never merge `backup-native`.** The legacy tree is reference material; its
   patterns are mined in `docs/plan/12-legacy-reference-map.md`.

## Why the repository is private

The tree vendors the private `togo-framework` modules (`vendor/`), which is what
lets CI build offline with `-mod=vendor`. That source must not be published.