Apply the same enhanced error classification to PRAGMA integrity_check
failures as we do for database open failures.
This ensures users see detailed, actionable recovery steps regardless of
which stage the corruption is detected (open vs integrity check).
Tested with real corruption scenarios - all error paths now provide
specific recovery guidance with exact commands.
Add comprehensive database corruption recovery capabilities to bd doctor.
## Changes
### New Command Flags
- --force: Force repair mode that bypasses database validation
- --source: Choose source of truth (auto/jsonl/db) for recovery
### Enhanced Error Classification
Improved CheckDatabaseIntegrity() to detect and classify:
- Database locked errors (suggests killing processes, removing locks)
- Invalid SQLite files (suggests JSONL recovery with exact commands)
- Migration/validation failures (orphaned dependencies, etc.)
- Generic database errors (context-aware suggestions)
Each error type provides:
- Specific diagnosis
- Step-by-step recovery instructions
- Appropriate command examples with new flags
### Force Recovery Implementation
New DatabaseCorruptionRecoveryWithOptions() function:
- Bypasses database validation when --force is used
- Supports explicit source of truth selection
- Auto-detects best recovery path when source=auto
- Comprehensive rollback on failure
- Uses --force --no-git-history in import during force mode
### Integration
Updated fix orchestration to pass force and source flags to recovery.
## Usage Examples
```bash
# Unopenable database with validation errors
bd doctor --fix --force --source=jsonl
# Choose specific source of truth
bd doctor --fix --source=jsonl # Trust JSONL
bd doctor --fix --source=db # Trust database
bd doctor --fix --source=auto # Auto-detect (default)
# Force recovery with auto-detection
bd doctor --fix --force
```
## Problem Solved
Before: When database had validation errors (orphaned dependencies,
foreign key violations), all bd commands failed in a catch-22 situation.
Could not open database to fix database. Users had to manually delete
database files and reinit.
After: bd doctor --fix --force detects unopenable databases, provides
clear recovery steps, and forces rebuild from JSONL even when database
validation fails.
## Backward Compatibility
- All new flags are optional with safe defaults
- --source defaults to 'auto' (existing behavior)
- --force is opt-in only
- Existing bd doctor behavior unchanged when flags not used
- DatabaseCorruptionRecovery() still exists for compatibility
Fixes: bd-pgza
- Add BD_JIRA_SCRIPT env var to let users specify script location
- Improve error message with clear instructions for binary users
- Show all locations that were searched
Changes:
- Default to excluding closed issues (use --all to include)
- Default limit of 50 issues (use --limit 0 for unlimited)
- --all flag now overrides the closed filter
This addresses agent context blowout from seeing hundreds of closed issues.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changes:
- Default --limit changed from 0 (unlimited) to 50
- --limit 0 explicitly means unlimited (override default)
- Show truncation hint when results are limited:
"Showing N issues (use --limit 0 for all)"
This protects agents and humans from overwhelming output.
Follows precedent from gh cli (30) and jira-cli (50).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Previously mol burn only worked on wisps (Ephemeral=true), erroring
on persistent mols. Now it works on both:
- Wisps: direct delete without tombstones (original behavior)
- Mols: cascade delete with tombstones (syncs to remotes)
This makes the 'burn' metaphor consistent: burn = destroy a molecule,
regardless of phase.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update version across all components:
- cmd/bd/version.go
- .claude-plugin/plugin.json, marketplace.json
- npm-package/package.json
- integrations/beads-mcp/pyproject.toml
- Git hook templates
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changed all --var flags from StringSlice to StringArray.
StringSlice splits on commas, breaking values like 'desc=A, B, C'.
StringArray only splits on separate --var flags.
Affected commands: pour, cook, wisp, mol distill, mol bond, template instantiate
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add explicit error checking for fmt.Fprintf/Fprintln in claude.go
- Add gosec nolint for safe exec.CommandContext calls in sync_git.go
- Remove unused error return from findTownRoutes in routes.go
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The --cascade flag was documented but not working for single-issue
deletes. The bug had two causes:
1. CLI direct mode: Single-issue deletes bypassed the batch path where
cascade expansion actually happens. Fixed by routing cascade deletes
through deleteBatch() regardless of issue count.
2. Daemon/RPC mode: handleDelete() iterated through IDs individually
without expanding dependents. Fixed by using DeleteIssues() with
cascade flag when SQLite storage is available.
Now `bd delete <id> --cascade --force` correctly deletes the target
issue plus all issues that depend on it (recursively).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The CheckSyncBranchHookCompatibility was checking core.hooksPath first,
while CheckGitHooks always uses .git/hooks/. This caused inconsistent
results when core.hooksPath was set globally.
Fix: Remove core.hooksPath check from CheckSyncBranchHookCompatibility
to match CheckGitHooks behavior. Both now consistently use .git/hooks/.
Note: A future improvement could make both respect core.hooksPath.
The negation patterns (!issues.jsonl, !interactions.jsonl, etc.) in
.beads/.gitignore had higher precedence than the fork protection
exclusion in .git/info/exclude, effectively defeating fork protection.
Contributors could accidentally stage and commit upstream issue
databases because:
1. Fork protection added .beads/issues.jsonl to .git/info/exclude
2. .beads/.gitignore had !issues.jsonl which overrode the exclusion
3. .gitignore files have higher precedence than .git/info/exclude
The negation patterns were unnecessary anyway since no pattern in
.beads/.gitignore matches those files. Added a comment explaining
why negations should not be added.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Solaris/illumos use Statvfs (POSIX standard) rather than Statfs.
Add daemon_health_solaris.go and exclude illumos/solaris from the
generic unix build constraint.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
bd has 70+ commands, which can be overwhelming for human users who just
want to track issues. The new `bd human` command displays a curated list
of ~15 essential commands organized by workflow:
- Working With Issues: create, list, show, update, close, reopen, comment
- Finding Work: ready, search, status, stats
- Dependencies: dep add/remove/tree, graph, blocked
- Setup & Sync: init, sync, doctor
- Getting Help: quickstart, help, --help
Also includes quick examples showing common workflows.
Changes:
- Add cmd/bd/human.go with curated help output
- Add "human" to noDbCommands list in main.go (no database needed)
Consolidated 5 duplicate IssueDetails struct definitions into a single
types.IssueDetails in internal/types/types.go:
- Removed 4 inline definitions from cmd/bd/show.go
- Removed 1 inline definition from internal/rpc/server_issues_epics.go
The shared type embeds types.Issue by value and includes:
Labels, Dependencies, Dependents, Comments, and Parent fields.
This improves maintainability and reduces risk of inconsistency.
bd config list now shows a warning when config.yaml or environment
variables override database settings. This addresses the confusion when
sync.branch from config.yaml takes precedence over the database value.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rename followRedirect to FollowRedirect in internal/beads (export it)
- Update doctor/maintenance.go to use beads.FollowRedirect
- Update doctor/fix/common.go to use beads.FollowRedirect
- Remove 66 lines of duplicated code across 3 implementations
This ensures consistent redirect handling with path canonicalization,
chain prevention, and proper error warnings.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add exitWithError helper to ensure JSON output is used when --json
flag is set during orphan detection errors.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add resolveBeadsDir helper to fix/common.go to follow redirect files
- Update OrphanedDependencies, ChildParentDependencies, and MergeArtifacts
to use resolveBeadsDir instead of hardcoded .beads path
- Add --verbose/-v flag to bd doctor command
- Only print individual items if verbose or count < 20, always show summary
(bd-dq74, bd-v55y)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Check comments table for orphaned issue_id references
- Check events table for orphaned issue_id references
- Delete orphaned comments/events in repair transaction
- Add --json flag for machine-readable output with:
- orphan_counts by type (dependencies, labels, comments, events)
- orphan_details with full reference info
- status (success, no_orphans, dry_run, error)
- backup_path when applicable
(bd-2wm2, bd-ie7j)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Code review fixes for critical issues:
- Wrap all DELETEs in a transaction with rollback on error
- Create .pre-repair backup before any destructive operations
- Mark parent issues as dirty when deleting orphaned depends_on refs
- Fix misleading PreRun comment
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When the database has orphaned dependencies or labels, the migration
invariant check fails and prevents the database from opening. This
creates a chicken-and-egg problem where bd doctor --fix cannot run.
The new bd repair command:
- Opens SQLite directly, bypassing invariant checks
- Deletes orphaned dependencies (issue_id or depends_on_id not in issues)
- Deletes orphaned labels (issue_id not in issues)
- Runs WAL checkpoint to persist changes
- Supports --dry-run to preview what would be cleaned
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Eliminate code duplication between importFromGit and importFromLocalJSONL
by extracting the common JSONL parsing and import logic.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds --from-jsonl flag that imports from the current working tree's
.beads/issues.jsonl file instead of scanning git history. This prevents
deleted issues from being resurrected during re-initialization.
Use case: After running bd compact --purge-tombstones and committing
the cleaned JSONL, a subsequent bd init would previously re-import
all historical issues from git, defeating the cleanup.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Unlike --prune which removes tombstones by age, --purge-tombstones removes
tombstones that have no open issues depending on them, regardless of age.
Also cleans stale deps from closed issues to tombstones.
Usage:
bd compact --purge-tombstones --dry-run # Preview what would be purged
bd compact --purge-tombstones # Actually purge
Note: Use --no-daemon to prevent daemon from re-exporting after cleanup.
- Add findExistingSwarm helper and duplicate swarm check with --force flag
- Add bd swarm list command for discovering swarm molecules with progress stats
- Fix empty coordinator display in swarm create output
- Allow swarm status to accept swarm molecule ID (follows relates-to link)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add EpicChildren struct and getEpicChildren() helper function
- Define SwarmStore interface for dependency injection
- Refactor analyzeEpicForSwarm to use shared helper
- Refactor getSwarmStatus to use shared helper
- Eliminates duplicate code for fetching epic children and building
dependency maps across both functions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Displays each issue on a single line with format:
<id> [<status>] P<priority> <type>: <title>
Example:
bd show bd-nlzv --short
bd-nlzv [open] P2 feature: bd show --short flag for compact output
Useful for quick status checks of multiple issues. (bd-nlzv)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Build status map upfront from childIssues instead of calling
GetIssue for each dependency. Reduces queries from O(issues * deps)
to O(issues).
Also removes unused GetIssue from the interface.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements `bd swarm create <epic-id>` to create a swarm molecule
that orchestrates parallel work on an epic.
Features:
- Creates molecule with mol_type=swarm for discovery
- Links to epic via relates-to dependency
- Validates epic structure before creation
- Auto-wraps single issues in an epic when needed
- Optional --coordinator flag to specify coordinator agent
- Supports JSON output for machine consumption
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Show current swarm status computed from beads:
- Completed: closed issues with timestamps
- Active: in_progress issues with assignees
- Ready: open issues with all deps satisfied
- Blocked: open issues waiting on deps
- Progress percentage
State is COMPUTED from beads, not stored separately.
Supports --json for programmatic use.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add mol_type field to beads for swarm coordination:
- Values: 'swarm' (multi-polecat), 'patrol' (recurring ops), 'work' (default)
- Nullable, defaults to empty string (treated as 'work')
Changes:
- Add mol_type column to SQLite schema and migration 031
- Add MolType type with IsValid() validation in types.go
- Update insertIssue/GetIssue to handle mol_type
- Add --mol-type flag to create command
- Add mol_type filtering to list and ready commands
- Update RPC protocol for daemon mode support
- Update test schema in migrations_test.go
🤝 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds validation of epic structure for swarm execution:
- Computes ready fronts (waves of parallel work)
- Detects structural issues (cycles, orphans, missing deps)
- Reports estimated worker-sessions and max parallelism
- Warns about potential dependency inversions
- Returns exit code for CI integration
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extract init.go into multiple focused files:
- init_git_hooks.go: Git hooks installation and merge driver setup (~480 lines)
- init_stealth.go: Stealth mode and fork/exclude configuration (~310 lines)
- init_agent.go: AGENTS.md and Claude settings setup (~170 lines)
- init_templates.go: config.yaml and README.md templates (~180 lines)
This reduces init.go from 1928 lines to 705 lines, meeting the <800 line target.
Each extracted file handles a cohesive set of functionality.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Created 7 new beads to track TODOs that were previously inline comments:
- bd-7l27: Integrate migration detection into bd doctor (5 files)
- bd-6x6g: Add multi-repo target repo switching in bd create
- bd-ag35: Add daemon RPC endpoints for config and stale check
- bd-2dwo: Remove deprecated daemon logger function
- bd-0qx5: Implement Jira issue timestamp comparison for sync
- bd-7zka: Implement formula features (repeat, for_each, branch, gate, split)
- bd-h048: Refactor sync_test to use direct import logic
Updated 16 TODO comments to include bead ID references for tracking.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extracted 8 helper functions from the monolithic flushToJSONLWithState:
- recordFlushFailure/recordFlushSuccess: Failure tracking and counter management
- readExistingJSONL: Parse existing JSONL file for incremental merging
- fetchAndMergeIssues: Fetch dirty issues from DB and merge into map
- filterWisps: Remove ephemeral (wisp) issues from export
- filterByMultiRepoPrefix: Multi-repo prefix filtering for non-primary repos
- updateFlushExportMetadata: Store hashes and timestamps after export
- getIssuesToExport: Determine full vs incremental export issue list
Main function now reads as a clear pipeline:
1. Validate integrity -> 2. Get issues -> 3. Read existing JSONL
4. Merge from DB -> 5. Filter wisps -> 6. Filter by prefix
7. Write atomically -> 8. Update metadata
Benefits:
- Each helper is single-responsibility and testable
- Main function reduced from ~280 to ~94 lines
- Logic is clearly separated and documented
- Easier to understand and maintain
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replaced three near-identical functions with a single unified collectSteps()
that uses a callback strategy for label handling:
- Removed collectStepsRecursive() (DB version)
- Removed collectStepsToSubgraph() (in-memory version)
- Removed collectStepIDMappings() (now handled by unified function)
The new collectSteps() function:
- Takes optional labelHandler callback for DB path (extracts labels separately)
- Takes optional issueMap for in-memory path
- Always builds idMapping for dependency resolution
- Eliminates ~60 lines of duplicated code
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extracted duplicated switch statement for mapping step type strings to
types.IssueType into a single helper function. This removes code
duplication between collectStepsToSubgraph() and collectStepsRecursive().
The new stepTypeToIssueType() function:
- Converts 'task', 'bug', 'feature', 'epic', 'chore' to types
- Returns types.TypeTask for empty or unrecognized types
- Used by both functions with children-override-to-epic logic preserved
