beads/docs/core-concepts/dependencies.md
Bee 83184f4c6a
docs: supersedes is a replacement link, not a version chain (#6212)
* docs: supersedes is a replacement link, not a version chain

Reword the DepSupersedes comment (internal/types/types.go), the
`bd supersede` help text, and the graph-links doc: `supersedes` marks an
old issue as replaced by a different issue. It is not a version relation
and does not imply a version chain. The behavior is unchanged.

Promised on #5898 (Q8, quad341 revision 4): a replacement link, not a
version-chain link. docs/CLI_REFERENCE.md is pinned to v1.2.2 and picks
this up at the next release bump (generate-cli-docs.sh --check passes).

Wyvern bead wy-h4xd6f.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PvjeDsoyDfjptvjKZWzcqA

* docs: finish the supersedes rewording pass in graph-links + dependencies

Maintainer review fixup for PR #6212.

The PR's new assertion "This is a replacement link, not a version relation"
left the rest of graph-links.md still telling the version-chain story, so
the page contradicted itself. Each residual line is byte-identical to base,
but the contradiction is new with this commit. Extends the same wording pass
to the sites that actually assert version semantics:

- frontmatter description: "supersedes chains" -> "supersedes (replacement)
  links" (this is the rendered page description)
- the example comment "# View shows the chain" -> "# View shows the
  replacement"
- "### Version History" -> "### Replacement History" and "# bd-rfc3 is now
  the current version" -> "# bd-rfc3 is now the live issue"
- Best Practice 4 "Document supersedes chains - Note why version changed" ->
  "Document replacements - Note why the issue was replaced"

The use-case list ("Design document versions", "Artifact versioning", "RFC
chains") and "Track document evolution" are deliberately left alone:
chained replacements legitimately model document evolution without the link
itself being a version relation.

Also rewords the sibling core-concepts table, docs/core-concepts/
dependencies.md:56, from "Replaced by a newer issue" to "Replaced by a
different issue" so both hand-written pages frame the edge the same way.

No in-repo reference targets the renamed #version-history anchor.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
2026-09-12 06:41:33 -07:00

9.2 KiB

title description
Dependencies and Gates Ordering work with blocking and non-blocking dependencies, and gates that wait on PRs, CI, or timers

Beads includes a full dependency system for ordering work and a gate system for bridging external conditions (PR merges, CI runs, timers) into the dependency graph.

Adding Dependencies

# issue-2 depends on issue-1 (issue-1 blocks issue-2)
bd dep add issue-2 issue-1

# Shorthand: issue-1 blocks issue-2
bd dep issue-1 --blocks issue-2

# Alternative flags (equivalent)
bd dep add issue-2 --blocked-by issue-1
bd dep add issue-2 --depends-on issue-1

When issue-1 is open, issue-2 won't appear in bd ready. Once issue-1 is closed, issue-2 unblocks automatically.

Removing Dependencies

bd dep remove issue-2 issue-1
bd dep rm issue-2 issue-1        # alias

Dependency Types

Dependencies have a type that determines whether they block work.

Blocking types (affect bd ready):

Type Meaning Example
blocks (default) B cannot start until A closes Task ordering
parent-child Children blocked when parent blocked Epic hierarchies
conditional-blocks B runs only if A fails Error handling paths
waits-for B waits for all of A's children Fanout aggregation

Non-blocking types (graph annotations only):

Type Meaning
related Informational link
tracks Tracks progress of another issue
discovered-from Found during work on another issue
caused-by Root cause link
validates Test or verification link
supersedes Replaced by a different issue (bd supersede old --with new)

Specify with --type:

bd dep add issue-2 issue-1 --type tracks
bd dep add issue-2 issue-1 --type caused-by

Finding Ready Work

bd ready shows issues with no open blocking dependencies:

bd ready

Output:

📋 Ready work (1 issues with no blockers):

1. [P1] bd-a1b2: Set up database

An issue is ready when ALL of its blocking dependencies are closed.

# Filter ready work
bd ready --priority 1              # By priority
bd ready --label backend           # By label
bd ready --assignee alice          # By assignee
bd ready --unassigned              # Unassigned only
bd ready --type task               # By issue type
bd ready --sort oldest             # Oldest first

Viewing Blocked Issues

bd blocked

Shows every blocked issue and what blocks it. Use after closing an issue to see what just unblocked.

Visualizing Dependencies

Dependency Tree

bd dep tree issue-id                    # What does this issue depend on?
bd dep tree issue-id --direction=up     # What depends on this issue?
bd dep tree issue-id --direction=both   # Both directions
bd dep tree issue-id --status=open      # Only open issues
bd dep tree issue-id --max-depth=3      # Limit depth
bd dep tree issue-id --format=mermaid   # Mermaid.js output

Dependency Graph

bd graph issue-id                       # Single issue DAG
bd graph --all                          # All open issues

# Output formats
bd graph --compact issue-id             # One line per issue
bd graph --box issue-id                 # ASCII boxes with layers
bd graph --dot issue-id | dot -Tsvg > graph.svg   # Graphviz
bd graph --html issue-id > graph.html   # Interactive D3.js

The graph organizes issues into layers:

  • Layer 0: No dependencies (can start immediately)
  • Layer 1: Depends on layer 0
  • Higher layers: Depend on lower layers
  • Same layer: Can run in parallel

Dependency List

bd dep list issue-id                    # What does this depend on?
bd dep list issue-id --direction=up     # What depends on this?
bd dep list issue-id --type=tracks      # Filter by type

Cycle Detection

bd dep cycles

Beads also rejects cycles at write time — bd dep add checks for cycles before committing.

Cross-Repo Dependencies

Dependencies can reference issues in other beads rigs:

bd dep add local-issue external:other-project:checkout-ready

Configure the project path under external_projects, then label a target project issue provides:checkout-ready. The dependency blocks until an issue with that label is closed. bd ready, bd blocked, and bd dep tree resolve the capability at query time; an unconfigured or unavailable project remains blocking.

Gates

Gates are special issues that block dependent work until an external condition is met. They bridge the gap between beads (which tracks work) and external systems (which track code, CI, or time).

The Problem Gates Solve

When you use Dolt (server or embedded), issue state is decoupled from code state. Closing a beads issue means "work is done" but the code may still be on a feature branch, waiting for PR review:

issue-1: closed in beads     (work done)
PR #42:  open on GitHub      (code not yet on main)
issue-2: blocked by issue-1  (should it start?)

With file-based storage (JSONL), issue updates land atomically with code in the same commit. With Dolt, they don't. Gates solve this by making the dependency wait for the external condition — not just the beads issue status.

Gate Types

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

Creating Gates

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

# Wait for CI run
bd create --type=gate --title="Wait for CI" \
  --await-type=gh:run --await-id=12345

# Wait 30 minutes
bd create --type=gate --title="Cooldown" \
  --await-type=timer --await-id=30m

# Wait for a cross-rig bead to close
bd create --type=gate --title="Wait for upstream fix" \
  --await-type=bead --await-id=other-rig:issue-id

# Manual approval gate
bd create --type=gate --title="Deploy approval"

Wiring Gates into Dependencies

A gate is an issue. Wire it into the dependency graph like any other:

# issue-2 waits for the gate (which waits for PR #42)
bd dep add issue-2 <gate-id>

Checking Gates

bd gate check evaluates all open gates and closes resolved ones:

bd gate check                    # Check all gates
bd gate check --type=gh:pr       # Only PR gates
bd gate check --type=gh:run      # Only CI gates
bd gate check --type=timer       # Only timers
bd gate check --dry-run          # Preview without changes
bd gate check --escalate         # Escalate failed gates

Escalation marks gates whose conditions failed (e.g., PR closed without merge, CI run failed) so they surface for attention.

Listing and Inspecting Gates

bd gate list                     # Open gates
bd gate list --all               # Including closed
bd gate show <gate-id>           # Full details

Manual Resolution

For human gates or overrides:

bd gate resolve <gate-id> --reason "Approved by team lead"

Discovering CI Run IDs

When you create a gh:run gate before the run starts, bd gate discover matches gates to GitHub Actions runs using heuristics (commit SHA, branch, timing):

bd gate discover                 # Auto-match gates to runs
bd gate discover --dry-run       # Preview matches
bd gate discover --branch main   # Filter by branch

Automating Gate Checks

Run bd gate check periodically to auto-close resolved gates:

  • CI step: Add to your GitHub Actions workflow
  • Cron: */5 * * * * cd /path/to/repo && bd gate check
  • Agent hook: Run at session start or after PR operations

Recipes

PR Merge Gate (Common)

Agent A finishes work, opens PR, creates a gate so Agent B waits for merge:

# Agent A
bd update issue-1 --status=in_progress
# ... write code, open PR #42 ...
bd create --type=gate --title="Wait for PR #42" \
  --await-type=gh:pr --await-id=42
bd dep add issue-2 <gate-id>
bd close issue-1

# Agent B
bd ready                         # issue-2 not shown (gate open)
# ... PR #42 merges ...
bd gate check                    # gate closes
bd ready                         # issue-2 appears

CI Gate Before Deploy

bd create --type=gate --title="CI green on main" \
  --await-type=gh:run --await-id=<run-id>
bd dep add deploy-task <gate-id>

Epic with Ordered Phases

bd create "Auth System" -t epic
bd create "Design" --parent <epic>
bd create "Implement" --parent <epic>
bd create "Test" --parent <epic>

bd dep add <implement> <design>
bd dep add <test> <implement>

bd dep tree <epic>
bd ready                         # Only "Design" is ready

See Also