Branches and releases

mdBoard uses three branch roles and one active iteration. There are no feature branches per idea and no per-feature worktrees in the 1.0 model.

The branch roles

The merge direction is always downward:

upstream → nightly → stable

Never the reverse. The agent never merges into nightly or stable, and never pushes those branches.

The upstream iteration

A iteration is one period in which upstream is open:

.mdboard/upstream.md
  iteration: 7
  status: open
  base: <nightly commit>
  writer: agent
  lease_expires: ...
  started_at: ...
  merged_at: null

• Start: the agent opens the iteration, fast-forwards upstream to nightly, and takes the writer lease.
• Work: all cards and code changes happen on upstream.
• Merge: the owner merges upstream → nightly once the active work is accepted and no batch is blocked, in breakdown, doing or handover.
• Next iteration: upstream is fast-forwarded to the new nightly; the iteration record is closed.

The branch name stays upstream; the iteration record and merge commits distinguish iterations.

One writer

Only one agent session holds the writer lease. It renews the lease on each write action. A stale lease can be cleared by the owner.

This is why parallel agents do not collide:

• one writer;
• one active batch;
• one working task.

If you want more human throughput, add reviewers, not parallel code writers.

What the agent may do

The agent may:

• write card and event files on upstream;
• commit each finished task;
• commit the report draft at handover;
• commit the final report and changelog at completion;
• prepare a merge check and release notes.

The agent may not:

• merge upstream → nightly;
• merge nightly → stable;
• push nightly or stable;
• rewrite history after handover;
• work outside upstream during an open iteration.

What the human does

The owner:

• starts a iteration when needed;
• merges an accepted iteration into nightly;
• releases nightly into stable on the release train;
• tags the release.

A member can review and recommend, but only the owner merges or releases.

Commits

Each completed task gets a commit. The subject is prefixed with the task id:

#0007-02 Add streamed CSV endpoint

Batch: #0007
Task: #0007-02
Evidence: tests/api/csv.test.js

Batch-level commits use the batch id:

#0007 Complete CSV export batch

The body names the batch, the task, the review round and the evidence. The agent does not rewrite these commits after handover.

Use mdboard commit -m "…" at task and batch boundaries. It stages the tree, enforces the open iteration and writer lease, and prints the commit SHA. upstream merge and release refuse a dirty worktree, so the agent must commit before the owner runs them.

Merge check

Before a human merge, the agent prepares:

• no active batch in breakdown, doing or handover;
• no blocked batch;
• clean checkout;
• event journal present and consistent;
• completed batches have reports and changelog bullets;
• roadmap and estimates are valid.

The owner executes the merge. The agent reports the result and opens the next iteration when asked.

Release train

nightly → stable happens on a fixed cadence (default biweekly) at the release-readiness meeting. The agent prepares the release notes and changelog window; the owner performs the release and tag.

An open upstream iteration does not block a release of already-merged nightly work, but the release notes must not include unmerged work.

Conflicts

With one writer, code conflicts should not occur. If they do:

1. the agent stops writing;
2. it reconstructs the timeline with the event journal and mdboard history;
3. it reports the conflicting card/state/event to a human;
4. the human decides.

The agent never silently chooses a side. A human editing files directly is outside the protocol and is reported by mdboard check.

Chat examples

Human: Start a new iteration.

Agent: Iteration 4 is open from nightly. I hold the writer lease.
          The board is ready.

Human: Prepare the merge for iteration 4.

Agent: The pending batch is complete, the worktree is clean, and the
          merge check passes. Only you can merge. Summary is ready.

Human: I merged it. Open the next iteration.

Agent: Iteration 4 is marked merged. Iteration 5 is open from the new nightly.

Next

• Checks and guarantees
• Meetings
• Configuration