droboticflow/docs/agents/branch-workflow.md
Codex 0040988fe9
Some checks are pending
web-ci / checks (push) Waiting to run
web-ci / pool-search-mongo (push) Waiting to run
🧭 Enforce dev mainline and release identity
2026-11-10 01:35:25 -08:00

3.4 KiB

Dev mainline workflow

Effective 2026-11-10, replacing the previous automatic task-branch/worktree workflow.

Daily work

  1. Use local-data/worktrees/recent-integration on dev. Preserve the main checkout's local-only work and existing unmerged worktrees.
  2. Inspect the working tree and run bash scripts/local/branch-freshness.sh. Fetch and compare dev with origin/dev before starting; retain concurrent edits and resolve divergence explicitly.
  3. Complete one authorized task at a time in the unified checkout. Stage only that task's changes, verify its scope, and commit with an English emoji-prefixed message.
  4. Push only with explicit authorization. A request to synchronize remote dev permits the corresponding fast-forward push. PR creation and deployment remain separately authorized actions. Never force-push or truncate dev history.

New branches and worktrees require the user's explicit request. Before creating one, record its purpose, base, owner, file scope and merge-back plan in .scratch/<slug>/work.md. An independent feature or parallel agent is not implicit permission to create another branch. Existing unmerged branches stay frozen until integration or disposal is requested.

Release identity

Every new release commit must equal both refs/heads/dev and refs/remotes/origin/dev. A detached build checkout is allowed only at that exact commit. An ancestor of dev, an unmerged feature tip or a local-only commit is not a release candidate.

scripts/release.py prepare compares the local refs without network access. deploy refreshes origin/dev and repeats the comparison before any cluster read or write. A changed or unreachable remote blocks deployment. Complete the remaining checks, immutable image provenance and explicit deployment approval in the release workflow.

Freeze the selected dev tip for the release window. If it changes before deployment, prepare and approve a new candidate. Components not included in that release keep their recorded versions. A later development commit may advance dev; historical verification does not require the old deployment to equal today's tip.

Cleanup

  • Preserve all unmerged commits, dirty worktrees, running services and release/recovery evidence. Branch age alone does not make work disposable.
  • Delete a merged local branch only after it is no longer checked out. python3 scripts/agent_status.py --prune checks containment in origin/dev and never deletes unmerged branches.
  • For an authorized remote cleanup, verify the actual remote tip is contained in origin/dev. Preserve remote counterparts of local unmerged/dirty work. Use the observed tip as a deletion lease so concurrent work cannot be deleted.
  • Before removing a merged worktree, preserve its ignored artifacts and release ledger, check dependency links and running-process working directories, then remove it through Git. Do not delete unaccepted release evidence or dependency directories still used by another checkout.
  • Keep the recent changes summary to ten application changes. Preserve complete Git history and authoritative ADR, release and verification evidence; the summary is not a history-retention limit.

At delivery, run python3 scripts/agent_status.py --no-fetch and report local/remote dev, pending work and cleanup counts. Push, PR and cluster-write approvals continue to follow AGENTS.md.