# Contributing to `groombook/api`

Thanks for contributing. This document is the human-facing companion to
[`AGENTS.md`](./AGENTS.md) and the authoritative
[`groombook/org`](https://git.farh.net/groombook/org) skills. The org skills
govern; this file is a quick-reference for the human/agent PR flow in this
repo.

## Branch strategy

Three long-lived branches; one PR per promotion step.

| Branch  | Environment | Who merges | Prerequisites for merge |
|---------|-------------|-----------|-------------------------|
| `dev`   | Dev         | Engineer  | CI passes               |
| `uat`   | UAT         | Engineer  | QA code review approval |
| `main`  | Production  | Engineer  | UAT validation + CTO Gitea Approve when the `uat→main` merge-gate policy applies (see below) |

Engineers always target `dev` first. Feature branches: `<agent-name>/<short-description>`.

## Phase-by-phase PR flow

### Phase 1 — Dev

1. Branch from `dev`: `git checkout -b <name>/<short-description> origin/dev`.
2. Write code + tests. Run unit tests, type check, and lint locally (or rely on CI).
3. Open a PR against `dev`:
   ```bash
   tea pr create --base dev --title "..." --body "..."
   ```
   Include `cc @cpfarhood` at the bottom of the body for board visibility.
4. CI must pass. CI green → engineer self-merges.
5. CI builds and deploys to Dev automatically.

### Phase 2 — UAT promotion

1. Open a PR from `dev` to `uat`.
2. CI must pass.
3. **QA (Lint Roller)** reviews and approves on the Gitea PR.
4. QA approved → engineer self-merges.
5. CI builds and deploys to UAT automatically.

### Phase 3 — UAT regression + Security review

1. **UAT (Shedward Scissorhands)** runs full regression against UAT — every
   feature, old and new, no exceptions.
2. **Security (Barkley Trimsworth)** reviews the changes.
3. Failures in either gate bounce back to Phase 1.

### Phase 4 — Production promotion (`uat → main`)

This is the gate the org PR
[`groombook/org#13`](https://git.farh.net/groombook/org/pulls/13) defines.
The full rule is in
[`groombook/org/skills/sdlc/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/sdlc/SKILL.md)
and
[`groombook/org/skills/coding-standards/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/coding-standards/SKILL.md);
the summary is below.

**The CTO Gitea Approve click is NOT the default gate.** Once the four
pre-gates (QA, UAT deploy, UAT regression, security) are green, the engineer
self-merges.

**A CTO Gitea Approve click IS required** only for PRs in one of three
categories:

1. **Novel auth / session paths** — login, OIDC, OOBE, session middleware,
   token issuance, password reset, MFA, new auth provider integrations.
   Routine auth-gated UI (button styling, error messages, form layout) is
   **not** in this category.
2. **Infra / prod-affecting merges** — deploys, infra manifests, secrets,
   GitOps overlays, CI/CD, `main` branch protection, production
   routing/ingress, prod state mutations. All Phase 5 infra overlay PRs in
   `groombook/infra` require CTO Gitea Approve without exception.
3. **Risk-flagged merges** — `risk:cto-approve` label, or explicit CTO/CEO
   sign-off request in the PR or issue thread.

The engineer opens the `uat→main` PR, classifies it against the three
categories above, and adds `cc @cpfarhood`. If the PR is in scope, the CTO
clicks Approve; once approved (and the four pre-gates are green), the
engineer merges.

### Phase 5 — Production deployment

A separate PR in `groombook/infra` bumps the overlay image tag for prod.
Handed to QA (Lint Roller) for review, then self-merged by the engineer.

## The four pre-gates (uat→main)

A `uat→main` PR is mergeable when **all four** are green:

1. **QA code review** — done on the dev→uat promotion PR.
2. **UAT deploy** — the UAT image built from the uat tip is live in UAT.
3. **UAT regression** — Shedward's full-feature UAT pass is green (no
   pre-existing defects, no new defects).
4. **Security review** — Barkley's security code review is green.

Issue-thread QA / UAT / security approvals do **not** clear the Gitea
`required_approvals` gate. Only a Gitea **Approve** click from a member of
the `approvals_whitelist_username` for `main` clears it. In this repo that
whitelist is the engineer team (`gb_flea`, `gb_dogfather`).

## Style, tests, and quality bar

See
[`groombook/org/skills/coding-standards/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/coding-standards/SKILL.md)
for the engineering priority ordering, test requirements, no-hardcoded-values
rules, CalVer versioning policy, and the `git.farh.net` container registry
policy.

## Safety

See
[`groombook/org/skills/safety/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/safety/SKILL.md)
for the non-negotiable rules: no plaintext secrets, no `kubectl apply` to
`groombook`, no self-merge, no direct `tofu` runs, board approval for
destructive actions, escalation protocol.