Implements a smart contextual hint system that shows helpful messages
to users after successful commands. Tips are filtered by conditions,
priority, frequency limits, and probability rolls to provide useful
information without being annoying.
Core Features:
- Tip struct with condition, message, frequency, priority, probability
- selectNextTip() filters eligible tips and applies probability
- Metadata storage tracks when tips were last shown
- Respects --json and --quiet flags
- Deterministic testing via BEADS_TIP_SEED env var
Integration Points:
- bd list: Shows tip after listing issues
- bd ready: Shows tip after showing ready work (or no work)
- bd create: Shows tip after creating issue
- bd show: Shows tip after showing issue details
Testing:
- Unit tests for tip selection logic
- Tests for frequency limits and probability
- Tests for metadata tracking
- Example tip definitions for documentation
Next Steps:
- bd-81a: Add programmatic tip injection API
- bd-tne: Add Claude setup tip with dynamic priority
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
## Problem
When bd sync detected stale DB (>50% divergence), it would import JSONL to fix the DB,
but then immediately export the DB back to JSONL. This caused the stale DB to overwrite
the JSONL after a git pull, undoing cleanup work.
Example scenario:
1. Clone has 688 stale issues in DB (628 closed)
2. git pull brings JSONL with 62 issues (cleanup applied)
3. bd sync detects 1009.7% divergence and imports JSONL (DB → 62 issues) ✓
4. bd sync exports DB to JSONL (JSONL still 62 issues) ✓
5. But this marks JSONL as "changed" and commits/pushes it ✗
## Solution
After ZFC (JSONL First Consistency) import, set skipExport flag to prevent the export step.
JSONL is the source of truth after import - DB should sync to match, not export back.
## Changes
- cmd/bd/sync.go: Add skipExport flag, set it after ZFC import
- cmd/bd/sync.go: Wrap export logic in `if !skipExport` block
- CHANGELOG.md: Update ZFC entry with accurate description
- cmd/bd/sync_test.go: Add TestZFCSkipsExportAfterImport
Fixes #bd-l0r
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Documentation for import.orphan_handling was completed in commit e0e6dff.
All files (AGENTS.md, README.md, TROUBLESHOOTING.md, CLI_REFERENCE.md)
have comprehensive coverage of:
- Resurrection behavior and tombstones
- All 4 config modes (allow, resurrect, skip, strict)
- Troubleshooting guidance for missing parent errors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
When users forget the -i flag and run 'bd import file.jsonl', the command
would silently read from stdin instead of the file, resulting in '0 created,
0 updated' output that was misleading.
Root cause: The import command doesn't validate positional arguments, so
'bd import file.jsonl' would be interpreted as 'bd import' with an ignored
argument, reading empty stdin.
Fix: Add validation at the start of the import command to detect positional
arguments and show a helpful error message with the correct syntax.
Closes bd-77gm
Add comprehensive documentation for the blocked_issues_cache optimization
that improved GetReadyWork performance from 752ms to 29ms (25x speedup).
Documentation locations:
- blocked_cache.go: Detailed package comment covering architecture,
invalidation strategy, transaction safety, edge cases, and future
optimizations
- ready.go: Enhanced comment at query site explaining the optimization
and maintenance triggers
- ARCHITECTURE.md: New section with diagrams, blocking semantics,
performance characteristics, and testing instructions
Closes bd-1w6i
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The reopen command now properly adds the reason as a comment when
using daemon mode, matching the behavior of direct mode. Uses the
existing RPC AddComment operation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add exponential backoff retry for BEGIN IMMEDIATE transactions to handle
concurrent write load without spurious failures.
Changes:
- Add IsBusyError() helper to detect database locked errors
- Add beginImmediateWithRetry() with exponential backoff (10ms, 20ms, 40ms, 80ms, 160ms)
- Update CreateIssue and CreateIssuesInBatch to use retry logic
- Add comprehensive tests for error detection and retry behavior
- Handles context cancellation between retry attempts
- Fails fast on non-busy errors
This eliminates spurious SQLITE_BUSY failures under normal concurrent usage
while maintaining proper error handling for other failure modes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Document known Kaspersky false positive issue with Go binaries and
provide user workarounds.
Changes:
- Add comprehensive docs/ANTIVIRUS.md with:
- Explanation of why Go binaries trigger AV false positives
- Step-by-step exclusion instructions for Kaspersky, Windows Defender
- File integrity verification procedures
- False positive reporting guide
- FAQ section
- Update docs/TROUBLESHOOTING.md with quick reference section
- Close bd-t4u1: Kaspersky PDM:Trojan.Win32.Generic detection
Root cause: Kaspersky's heuristic detection flags Go binary patterns as
suspicious. This is an industry-wide issue affecting many Go projects.
Build already uses recommended optimizations (-s -w flags). Future
improvements (code signing, vendor whitelist) tracked separately.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Standardized error handling across the SQLite storage layer by
consistently using wrapDBError() helper functions that were already
defined in errors.go.
Changes:
- config.go: Applied wrapDBError to all config/metadata functions
- queries.go: Fixed bare 'return err' in CreateIssue, UpdateIssue, DeleteIssues
- store.go: Changed %v to %w for proper error chain preservation
- errors_test.go: Added comprehensive test coverage for error wrapping
All error paths now:
- Wrap errors with operation context using %w
- Convert sql.ErrNoRows to ErrNotFound consistently
- Preserve error chains for unwrapping and type checking
This improves debugging by maintaining operation context throughout
the error chain and enables type-safe error checking with sentinel
errors.
All tests passing ✓
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
