Branch and Merge Rules

Purpose

This document is the practical branch, worktree, pull request, and merge protocol for Prox OS development. It applies to humans and AI agents.

Branch Rules

• Do not work directly on main for non-trivial changes.
• Use one branch per task and one owner per branch.
• Prefer a separate git worktree for each concurrent AI agent.
• Keep branch names scoped and reviewable.
• Rebase or merge the latest main before final review.
• Use draft PRs for broad, risky, or still-moving work.

Recommended branch names:

• agent/<task-id>-<short-scope>
• docs/<topic>
• app/<app-name>
• pkg/<package-name>
• fix/<issue-id>-<short-desc>

Local Worktree Setup

Example:

git worktree add ../prox-os-docs -b docs/os-collaboration-model
git worktree add ../prox-os-app-hola -b app/hola-follow-up
git worktree add ../prox-os-ui -b pkg/os-ui-toolbar

Open each worktree in a separate Codex window, Cursor window, Warp tab, or terminal agent session. Do not ask multiple agents to write in the same working tree.

PR Requirements

Use this template in PR descriptions or final agent summaries:

## What changed

-

## Why

-

## Files touched

-

## Architecture impact

- None / describe package, runtime, state, API, registry, or deployment impact.

## Docs updated

-

## Validation

- [ ] `pnpm lint`
- [ ] `pnpm typecheck`
- [ ] `pnpm arch:check`
- [ ] `pnpm check:cjk`
- [ ] Other:

## UI evidence

- Screenshots, browser notes, or "not applicable".

## Risk level

- Low / medium / high

## Follow-ups

-

If a check was skipped, state why. If a check failed for a pre-existing reason, include the exact command and failure summary.

Merge Order for Parallel Agent Work

Default order:

1. Docs-only changes.
2. Isolated leaf apps.
3. Isolated packages.
4. Shared UI additions.
5. App registry changes.
6. App contract changes.
7. OS Shell runtime changes.
8. Root config and tooling changes.

This order is a starting point. If a leaf app depends on a contract change, the contract branch must be reviewed and merged first. If a root tooling change would invalidate all other branches, serialize it before assigning parallel workers.

Backend Branch Safety

Backend work follows the Backend Foundation v0 safety model:

• Contract branches land before real API branches.
• Mock branches land before backend route or database branches.
• UI branches can move faster when they stay static or mock-backed.
• Real API branches should be small and reviewed carefully.
• Database schema branches are serialized with one migration owner.
• Do not let multiple branches modify schema, environment files, Wrangler config, root scripts, or app registry core at the same time without explicit coordination.

See Backend Foundation v0 for the vertical slice model and recommended branch naming.

Human Review Required

Always require human review before merging:

• App contract changes.
• Window manager, shell routing, or runtime protocol changes.
• App registry composition changes.
• Design token changes.
• Root package scripts, package manager, Nx, ESLint, TypeScript, or dependency-cruiser changes.
• Database schema or migration changes.
• Deployment, domain, Access, secret, or production environment changes.
• Auth, billing, permission, audit, or legal/compliance work.
• Large file moves, package extraction, or cross-cutting refactors.

Integration Summary

After parallel work, the integrator or human owner should summarize:

• Branches or PRs reviewed.
• Conflicts found.
• Merge order.
• Checks that passed or still need to run.
• Documentation drift risk.
• Follow-up issues.