Skip to content

ADR-0003: Merge Request Workflow and Dedicated Worktrees per Increment

Status

Accepted

Context

As collaboration on Swayrm accelerates across human developers and multiple AI agents (Gemini, Claude, GPT, etc.), two critical challenges emerged in repository management:

  1. Uncontrolled Direct Pushes: Committing directly to default or protected branches bypasses code review, automated CI validation pipelines, and deliberate change control.
  2. Workspace Contamination and Concurrent Tasks: Working on concurrent tasks, evolutionary deliberations, or experimental features within a single working directory introduces risk of dirty working trees, untracked artifact contamination, and tangled commits.

To maintain radical transparency, auditability, and reproducible delivery, our collaboration workflow requires strict isolation mechanics.

Decision

  1. Merge Request Workflow: All changes and contributions targeting the Swayrm Git repository must follow a Merge Request (MR) workflow. Direct commits and pushes to primary/protected branches are strictly forbidden. Every increment must be prepared on a dedicated, reviewable feature branch.
  2. Dedicated Git Worktree per Increment: Every increment of work must be executed within its own dedicated Git worktree (git worktree add) and corresponding feature branch. This guarantees physical directory isolation, preserves clean working copies, and prevents cross-contamination across concurrent tasks.
  3. Formalization in Universal Agent Guidelines: Incorporate the MR workflow and worktree mandate into Section 1.4 of AGENTS.md to ensure all autonomous and assisted workflows strictly adhere to this protocol.

Consequences

Positive

  • Strict Task Isolation: Each increment operates in an independent directory tree, eliminating accidental carry-over of uncommitted changes or temporary build artifacts.
  • Reviewability & Traceability: All changes are audited through GitLab Merge Requests before landing on the default branch.
  • Safety: Direct pushes to production/main branches are prevented by convention and policy.
  • Concurrent Agility: Multiple branches/tasks can be explored in parallel across distinct worktrees without stash/switch overhead or stash collision.

Negative / Trade-offs

  • Contributors and agents must manage worktree lifecycles (creating worktrees with git worktree add and pruning them with git worktree remove upon merge).
  • Disk space usage is slightly higher due to multiple checkouts of the repository tree.