Implement cycle detection and prevention improvements

- Add diagnostic warnings when cycles detected after dep add (bd-309)
- Add semantic validation for parent-child dependency direction (bd-308)
- Document cycle handling behavior in code, README, and DESIGN (bd-310)

Changes:
- cmd/bd/dep.go: Add DetectCycles() call and warning after dep add
- internal/storage/sqlite/dependencies.go: Add parent-child direction validation and comprehensive cycle prevention comments
- internal/storage/sqlite/dependencies_test.go: Add TestParentChildValidation
- README.md: Add dependency types and cycle prevention section with examples
- DESIGN.md: Add detailed cycle prevention design rationale and trade-offs
This commit is contained in:
Steve Yegge
2025-10-16 13:17:32 -07:00
parent 6753024eb0
commit 1e32041fe6
6 changed files with 531 additions and 385 deletions

View File

@@ -408,6 +408,38 @@ bd dep tree bd-2
bd dep cycles
```
#### Dependency Types
- **blocks**: Hard blocker (default) - issue cannot start until blocker is resolved
- **related**: Soft relationship - issues are connected but not blocking
- **parent-child**: Hierarchical relationship (child depends on parent)
- Correct: `bd dep add bd-task bd-epic --type parent-child` (task → epic)
- Wrong: `bd dep add bd-epic bd-task --type parent-child` (reversed!)
- **discovered-from**: Issue discovered during work on another issue
#### Cycle Prevention
beads maintains a directed acyclic graph (DAG) of dependencies and prevents cycles across **all** dependency types. This ensures:
- **Ready work is accurate**: Cycles can hide issues from `bd ready` by making them appear blocked when they're actually part of a circular dependency
- **Dependencies are clear**: Circular dependencies are semantically confusing (if A depends on B and B depends on A, which should be done first?)
- **Traversals work correctly**: Commands like `bd dep tree` rely on DAG structure
**Example - Prevented Cycle:**
```bash
bd dep add bd-1 bd-2 # bd-1 blocks on bd-2 ✓
bd dep add bd-2 bd-3 # bd-2 blocks on bd-3 ✓
bd dep add bd-3 bd-1 # ERROR: would create cycle bd-3 → bd-1 → bd-2 → bd-3 ✗
```
Cross-type cycles are also prevented:
```bash
bd dep add bd-1 bd-2 --type blocks # bd-1 blocks on bd-2 ✓
bd dep add bd-2 bd-1 --type parent-child # ERROR: would create cycle ✗
```
If you try to add a dependency that creates a cycle, you'll get a clear error message. After successfully adding dependencies, beads will warn you if any cycles are detected elsewhere in the graph.
### Finding Work
```bash