Merge pull request #2167 from peterkc/docs/dependencies

docs(deps): add DEPENDENCIES.md for dependency system and gates
This commit is contained in:
Steve Yegge 2026-02-27 13:08:49 -08:00 • committed by GitHub
commit 68752a6c51
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 361 additions and 0 deletions

View file

@ -547,6 +547,39 @@ bd mol burn <ephemeral-id> --force --json
**Note:** Mol commands use the standard Dolt database access path.
## Gates
Gates are async wait conditions that block dependent work until external conditions are met.
See [DEPENDENCIES.md](DEPENDENCIES.md) for full documentation.
```bash
# List open gates
bd gate list
bd gate list --all # Including closed
# Show gate details
bd gate show <gate-id>
# Evaluate gates and close resolved ones
bd gate check # All gates
bd gate check --type=gh:pr # Only PR merge gates
bd gate check --type=gh:run # Only CI run gates
bd gate check --type=timer # Only timer gates
bd gate check --type=bead # Only cross-rig bead gates
bd gate check --dry-run # Preview without changes
bd gate check --escalate # Escalate failed gates
# Manually resolve a gate
bd gate resolve <gate-id> --reason "Approved"
# Auto-discover CI run IDs for gh:run gates
bd gate discover
bd gate discover --dry-run --branch main
# Add a waiter to a gate
bd gate add-waiter <gate-id> <waiter>
```
## Database Management
### Import/Export

326
docs/DEPENDENCIES.md Normal file
View file

@ -0,0 +1,326 @@
# Dependencies and Gates
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
```bash
# 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
```bash
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` | Replaces another issue |
Specify with `--type`:
```bash
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:
```bash
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.
```bash
# 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
```bash
bd blocked
```
Shows every blocked issue and what blocks it. Use after closing an issue
to see what just unblocked.
## Visualizing Dependencies
### Dependency Tree
```bash
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
```bash
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
```bash
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
```bash
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:
```bash
bd dep add local-issue external:other-project:remote-issue
```
External dependencies always block. When the remote issue closes,
`bd ready` reflects the change (checked at query time).
## 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
```bash
# 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:
```bash
# 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:
```bash
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
```bash
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:
```bash
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):
```bash
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:
```bash
# 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
```bash
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
```bash
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
- [QUICKSTART.md](QUICKSTART.md) — First steps with dependencies
- [MOLECULES.md](MOLECULES.md) — Molecule workflows using gates and dependencies
- [MULTI_REPO_AGENTS.md](MULTI_REPO_AGENTS.md) — Cross-repo dependency patterns
- [DOLT.md](DOLT.md) — Dolt backend configuration
- [CLI_REFERENCE.md](CLI_REFERENCE.md) — Full command reference

View file

@ -340,5 +340,6 @@ rm .beads/*.backup-*.db
## See Also
- [CONFIG.md](CONFIG.md) - Full configuration reference
- [DEPENDENCIES.md](DEPENDENCIES.md) - Dependencies and gates
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git worktrees and protected branches
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - General troubleshooting

View file

@ -251,5 +251,6 @@ bd admin cleanup --force
- Filter ready work: `./bd ready --priority 1`
- Search issues: `./bd list --status open`
- Detect cycles: `./bd dep cycles`
- Use gates for PR/CI sync: See [DEPENDENCIES.md](DEPENDENCIES.md)
See [README.md](../README.md) for full documentation.