diff --git a/docs/dev/cloud-task-integration.md b/docs/dev/cloud-task-integration.md new file mode 100644 index 0000000..965728a --- /dev/null +++ b/docs/dev/cloud-task-integration.md @@ -0,0 +1,65 @@ +# Backlog Wave Orchestrator: Cloud Task Integration Protocol + +## Purpose +This protocol defines how parallel cloud-task branches are integrated into `feat/backlog-batch-1` in controlled merge waves. + +## Branch roles +- **Target integration branch:** `feat/backlog-batch-1` +- **Wave coordinator branch (this docs branch):** `agent/orchestrator-docs` +- **Contributor branches:** task branches opened by cloud agents (infra/backend/frontend) + +## Merge wave order (required) +Use this fixed order to minimize cross-domain conflicts and keep root-cause analysis simple: + +1. **Wave 1: Low-risk infrastructure changes first** + - Examples: CI tweaks, tooling updates, non-functional config/docs. + - Exclude backend behavior and UI-visible logic. +2. **Wave 2: Backend changes second** + - API handlers, services, DB migrations, auth/business logic. +3. **Wave 3: Frontend changes last** + - UI components, routes, state wiring, API consumption. + +Do not start the next wave until the current wave passes all required verification commands. + +## Conflict policy +When conflicts occur while merging a wave branch into `feat/backlog-batch-1`: + +1. Stop and classify conflict type: + - **Ownership conflict:** two branches changed same lines in same area. + - **Contract conflict:** backend and frontend assumptions differ. + - **Behavior conflict:** tests pass locally but behavior deviates. +2. Resolution priority: + 1. Preserve previously merged wave guarantees. + 2. Preserve explicit acceptance criteria from backlog task. + 3. Prefer smaller, reversible changes over broad rewrites. +3. Escalation rule: + - If resolution requires changing behavior outside wave scope, pause merge and open a follow-up task branch. +4. Documentation rule: + - Record the conflict and decision in the merge checklist before continuing. + +## Rebase policy +Before merging any branch in a wave: + +1. Rebase candidate branch onto latest `feat/backlog-batch-1`. +2. Resolve conflicts on the candidate branch (not directly on target). +3. Re-run the required verification commands. +4. Force-push only the candidate branch when needed (`--force-with-lease`). +5. Merge only after green checks. + +If a branch cannot be cleanly rebased within 30 minutes, defer it to a follow-up wave. + +## Required verification gate before each merge wave +Run these commands from repo root before wave start and after each merged PR in that wave: + +```bash +git fetch --all --prune +git checkout feat/backlog-batch-1 +git pull --ff-only +``` + +Then run the checklist commands from `docs/dev/merge-checklist.md` and require all pass criteria to be met. + +## Operating cadence +- Merge one PR at a time within a wave. +- After each PR merge, rerun verification gate. +- If a gate fails, freeze wave, revert or patch forward, and resume only after all checks pass. diff --git a/docs/dev/merge-checklist.md b/docs/dev/merge-checklist.md new file mode 100644 index 0000000..2f1ed3b --- /dev/null +++ b/docs/dev/merge-checklist.md @@ -0,0 +1,85 @@ +# Merge Checklist for `feat/backlog-batch-1` + +Use this checklist for every merge wave (infra → backend → frontend). + +## 1) Pre-wave sync (required) + +```bash +git fetch --all --prune +git checkout feat/backlog-batch-1 +git pull --ff-only +``` + +**Pass criteria** +- Local branch is up to date with remote. +- Working tree is clean (`git status` shows no pending changes). + +**Fail criteria** +- Pull/rebase conflicts. +- Dirty working tree or detached HEAD. + +## 2) Candidate branch rebase (required per PR) + +```bash +git checkout +git rebase origin/feat/backlog-batch-1 +``` + +**Pass criteria** +- Rebase completes with no unresolved conflicts. +- Branch pushed successfully if history changed (`git push --force-with-lease`). + +**Fail criteria** +- Unresolved conflicts remain. +- Rebase exceeds timebox (30 minutes) without safe resolution. + +## 3) Verification commands (required before merge and after each merged PR) + +```bash +# Repository integrity +git status --short --branch + +# Backend smoke checks (if backend touched) +python -m py_compile $(rg --files server_api server_pytc | rg '\\.py$') + +# Frontend lint/build smoke checks (if frontend touched) +cd client && npm run -s lint && npm run -s build && cd - +``` + +**Pass criteria** +- `git status` shows expected branch and clean tree. +- Python compile check exits 0. +- Frontend lint and build exit 0 when frontend scope is part of wave. + +**Fail criteria** +- Any command exits non-zero. +- New warnings/errors indicate regression risk. + +## 4) Merge execution (one PR at a time) + +```bash +git checkout feat/backlog-batch-1 +git merge --no-ff +``` + +**Pass criteria** +- Merge commit created without unresolved conflicts. +- Post-merge verification commands all pass. + +**Fail criteria** +- Merge conflicts unresolved. +- Post-merge checks fail. + +## 5) Conflict log (required when applicable) +For each conflict, record: +- PR/branch name +- Files affected +- Conflict type (ownership/contract/behavior) +- Resolution chosen +- Follow-up action (if deferred) + +## 6) Wave completion gate +Wave is complete only when: +- All PRs assigned to wave are merged or explicitly deferred. +- Verification commands pass after final merge. +- Conflict log is updated for any incidents.