How to keep working in sync when beads updates aren't tied to code merges

[geerzo]

Assumption: you are using Dolt Server (or even legacy sync-branch) and using branches and PRs

Since beads completions will be recorded prior to PRs being merged, how do you keep dependent work from being done before the code it depends on is available? This wasn't an issue with using issues.jsonl updates in the current branch but obviously that came with other issues.

[peterkc]

@geerzo — this tension is fundamental to any setup where issue state lives outside the code branch. It's not unique to Dolt Server; embedded mode has the same decoupling. The file-based (jsonl) approach avoids it by making issue updates atomic with code commits, but that comes with its own costs (merge conflicts, no concurrent access, no query capability).

I've been running Dolt Server for beads across multiple repos and have landed on some patterns that work well. The core reframe:

Beads tracks work completion. Git tracks code availability. They're complementary state machines, not redundant ones.

Deployment Mode Comparison

Aspect	File (jsonl)	Dolt Embedded	Dolt Server
Issue-code coupling	Atomic (same commit)	Decoupled	Decoupled
Concurrent agents	No (merge conflicts)	Single-writer	Multi-writer
Query capability	None (grep)	Full SQL	Full SQL
Server management	None	None	Process + auth
Cross-repo	No	Per-repo DB	Shared server
Dependency problem	Doesn't exist	Exists	Exists

The dependency problem exists in ALL modes except file-based. Moving to Dolt (any mode) means accepting this decoupling and building conventions around it.

Note: Sync-branch was removed in v0.53.0 in favor of dolt-native sync, so it's not included above.

How Dependent Work Actually Flows

Here's the sequence when issue-2 depends on issue-1:

issue-1 lifecycle            issue-2 lifecycle
-----------------            -----------------
open                         open (blocked by issue-1)
  |                            |
in_progress                    | (waiting)
  |                            |
code written                   |
PR opened                      |
  |                            |
  |  -- THE GAP --             |
  |                            |
  |  Beads: issue-1 done       |
  |  Git:   code still on      |
  |         feature branch,    |
  |         NOT on main        |
  |                            |
  |  Can issue-2 start?        |
  |                            |
PR merged -----------------> unblocked
  |                          in_progress
closed                         |
                             code written
                             PR opened
                             ...

The question is: what happens in THE GAP?

Beads Already Has the Answer: Gates

The bd gate system bridges exactly this gap. A gate is a special issue type that blocks dependent work until an external condition is met — including PR merge status:

# Create a gate that waits for PR #42 to merge
bd create --type=gate --title="Wait for PR #42" \
  --await-type=gh:pr --await-id=42

# Wire it into the dependency chain
bd dep add issue-2 <gate-id>

# Poll gates (can run in CI or on a schedule)
bd gate check

When bd gate check runs, it calls gh pr view under the hood. Once the PR state is MERGED, the gate closes automatically, and bd ready shows issue-2 as unblocked.

Gate types available:

Type	Condition	Resolution
gh:pr	PR merged	gh pr view shows MERGED
gh:run	CI passes	gh run view shows completed + success
timer	Time elapsed	Timeout expires
bead	Cross-rig issue closed	Remote bead status checked
human	Manual approval	bd gate resolve <id>

This means the full workflow becomes:

Agent A (issue-1):
  1. bd update issue-1 --status=in_progress
  2. Write code, open PR
  3. bd create --type=gate --await-type=gh:pr --await-id=<PR#>
  4. bd dep add issue-2 <gate-id>
  5. bd close issue-1             # work is done

Agent B (issue-2):
  1. bd ready                     # issue-2 not shown (gate open)
  2. ... PR merges ...
  3. bd gate check                # gate closes automatically
  4. bd ready                     # issue-2 now appears
  5. bd update issue-2 --status=in_progress

Three Conventions (With and Without Gates)

Convention 1: Don't Close Until Merged (simplest, no gates needed)

Keep issues open until the PR actually merges. Use a label or status to indicate "work done, awaiting merge."

Status flow:  open -> in_progress -> review -> closed
                                     ^^^^^^
                                     PR open, code not yet on main

Dependent work only starts when the blocker hits closed, which means code is on main. Simple, safe, no ambiguity.

Trade-off: You lose visibility into "work is done" vs "PR is stuck in review."

Convention 2: Gates for PR Merge (recommended)

Use bd gate with gh:pr type as shown above. Close the beads issue when work is complete. The gate — not the issue status — controls when dependent work unblocks.

Trade-off: Requires running bd gate check periodically. But this can be automated (CI step, cron, or agent hook).

Convention 3: Branch-Based Dependencies (advanced, no gates)

Dependent work bases its branch on the blocker's feature branch instead of main:

# issue-2 depends on issue-1
git checkout -b feature/issue-2 feature/issue-1
# work on issue-2...
# when issue-1 merges to main, rebase:
git rebase main

This lets dependent work start immediately without waiting for merge.

Trade-off: Rebase complexity. If issue-1's PR gets significant review changes, issue-2 may need rework. Works best when the dependency is stable (e.g., "add the table" before "query the table").

The Dependency Tooling

For anyone not aware, beads has a full dependency system beyond gates:

bd dep add issue-2 issue-1           # issue-2 blocked by issue-1
bd dep tree issue-1 --direction=up   # what does issue-1 block?
bd blocked                           # show all blocked issues
bd ready                             # show unblocked work
bd graph                             # DAG visualization
bd dep cycles                        # detect circular deps

Cross-repo dependencies also work via external refs:

bd dep add issue-2 external:other-project:issue-id

What I've Found Works

Running Dolt Server (Convention 2 — gates) with these practices:

1. Close beads issues when work is done, not when PR merges — this keeps the issue tracker reflecting actual work state
2. Use gh:pr gates for merge dependencies — the gate system was built for exactly this problem
3. Run bd gate check in CI or as a hook — automates the unblocking without manual intervention
4. Use bd dep tree for visibility — shows the full dependency chain including gate status

The server model's strength is exactly this decoupling — multiple agents can read/write issues concurrently without merge conflicts, and you get real SQL queries for dependency analysis. The dependency sync problem is real but already solved by the gate system.

[geerzo]

This is great. Maybe a good candidate to add to docs.

[bryanhirsch]

@peterkc, great writeup! Thanks!