johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add v0.24.4 changelog entry

Browse Source 
Comprehensive changelog documenting all changes since v0.24.3:
- Transaction API for atomic multi-operation workflows
- Tip system infrastructure for smart user hints
- Sorting flags for bd list and bd search
- Claude integration verification in bd doctor
- ARM Linux support (PR #371)
- Multiple bug fixes and improvements

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-11-24 22:28:04 -08:00
parent 45464ca3f9
commit 9b13c422ca
2 changed files with 90 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.beads/beads.jsonl
View File

@@ -11,6 +11,7 @@
{"id":"bd-4ri","content_hash":"d2d8749ed02a35e0207ec699b3936fccf86f80073774800e40bfe69c49bc6f39","title":"Fix TestFallbackToDirectModeEnablesFlush deadlock causing 10min test timeout","description":"## Problem\n\nTestFallbackToDirectModeEnablesFlush in direct_mode_test.go deadlocks for 9m59s before timing out, causing the entire test suite to take 10+ minutes instead of \u003c10 seconds.\n\n## Root Cause\n\nDatabase lock contention between test cleanup and flushToJSONL():\n- Test cleanup (line 36) tries to close DB via defer\n- flushToJSONL() (line 132) is still accessing DB\n- Results in deadlock: database/sql.(*DB).Close() waits for mutex while GetJSONLFileHash() holds it\n\n## Stack Trace Evidence\n\n```\ngoroutine 512 [sync.Mutex.Lock, 9 minutes]:\ndatabase/sql.(*DB).Close(0x14000643790)\n .../database/sql/sql.go:927 +0x84\ngithub.com/steveyegge/beads/cmd/bd.TestFallbackToDirectModeEnablesFlush.func1()\n .../direct_mode_test.go:36 +0xf4\n\nWhile goroutine running flushToJSONL() holds DB connection via GetJSONLFileHash()\n```\n\n## Impact\n\n- Test suite: 10+ minutes → should be \u003c10 seconds\n- ALL other tests pass in ~4 seconds\n- This ONE test accounts for 99.9% of test runtime\n\n## Related\n\nThis is the EXACT same issue documented in MAIN_TEST_REFACTOR_NOTES.md for why main_test.go refactoring was deferred - global state manipulation + DB cleanup = deadlock.\n\n## Fix Approaches\n\n1. **Add proper cleanup sequencing** - stop flush goroutines BEFORE closing DB\n2. **Use test-specific DB lifecycle** - ensure flush completes before cleanup\n3. **Mock the flush mechanism** - avoid real DB for testing this code path \n4. **Add explicit timeout handling** - fail fast with clear error instead of hanging\n\n## Files\n\n- cmd/bd/direct_mode_test.go:36-132\n- cmd/bd/autoflush.go:353 (validateJSONLIntegrity)\n- cmd/bd/autoflush.go:508 (flushToJSONLWithState)\n\n## Acceptance\n\n- Test passes without timeout\n- Test suite completes in \u003c10 seconds\n- No deadlock between cleanup and flush operations","status":"open","priority":1,"issue_type":"bug","created_at":"2025-11-21T20:09:00.794372-05:00","updated_at":"2025-11-21T20:09:00.794372-05:00","source_repo":"."}
{"id":"bd-5qim","content_hash":"5117e87c5a56b5b8254402d982e85bea1478c1961f05654a50cf2df11e7ad6bf","title":"Optimize GetReadyWork performance - 752ms on 10K database (target: \u003c50ms)","description":"","notes":"# Performance Analysis (10K Issue Database)\n\nAnalyzed using CPU profiles from benchmark suite on Apple M2 Pro.\n\n## Operation Performance\n\n| Operation | Time | Allocations | Memory |\n|----------------------------------|---------|-------------|--------|\n| bd ready (GetReadyWork) | ~752ms | 167,466 | 16MB |\n| bd list (SearchIssues no filter) | ~11.6ms | 89,214 | 5.8MB |\n| bd list (SearchIssues filtered) | ~9.2ms | 62,365 | 3.5MB |\n| bd create (CreateIssue) | ~2.6ms | 146 | 8.6KB |\n| bd update (UpdateIssue) | ~0.32ms | 364 | 15KB |\n| bd close (UpdateIssue) | ~0.32ms | 364 | 15KB |\n\n**Target: \u003c50ms for all operations on 10K database**\n\n**Current issue: GetReadyWork is 15x over target (752ms vs 50ms)**\n\n## Root Cause\n\nGetReadyWork (internal/storage/sqlite/ready.go:90-128) uses recursive CTE to propagate blocking:\n- 65x slower than SearchIssues\n- Recalculates entire blocked issue tree on every call\n- Algorithm:\n 1. Find directly blocked issues via 'blocks' dependencies\n 2. Recursively propagate blockage to descendants (max depth: 50)\n 3. Exclude all blocked issues from results\n\n## CPU Profile Analysis\n\n- Database syscalls (pthread_cond_signal, syscall6): ~75%\n- SQLite engine overhead: inherent to recursive CTE\n- Application code (query construction): \u003c1%\n\n**Bottleneck is the recursive CTE query execution, not application code.**\n\n## Optimization Recommendations\n\n### High Impact (Likely to achieve \u003c50ms target)\n\n1. **Cache blocked issue calculation**\n - Add `blocked_issues` table updated on dependency changes\n - Trade write complexity for read speed (ready called \u003e\u003e dependency changes)\n - Eliminates recursive CTE on every read\n\n2. **Add/verify database indexes**\n ```sql\n CREATE INDEX IF NOT EXISTS idx_dependencies_blocked \n ON dependencies(issue_id, type, depends_on_id);\n CREATE INDEX IF NOT EXISTS idx_issues_status \n ON issues(status);\n ```\n\n### Medium Impact\n\n3. **Reduce allocations** (167K allocations for GetReadyWork)\n - Profile `scanIssues()` for object pooling opportunities\n - Reuse slice capacity for repeated calls\n\n### Low Impact (Not recommended)\n- Query optimization for CRUD operations (already \u003c3ms)\n- Connection pooling tuning (not showing in profiles)\n\n## Verification\n\nRun benchmarks to validate optimization:\n```bash\nmake bench-quick\ngo tool pprof -http=:8080 internal/storage/sqlite/bench-cpu-*.prof\n```\n\nProfile files automatically generated in `internal/storage/sqlite/`.","status":"open","priority":0,"issue_type":"bug","created_at":"2025-11-14T09:02:46.507526-08:00","updated_at":"2025-11-14T09:03:44.073236-08:00","source_repo":"."}
{"id":"bd-81a","content_hash":"9177d5018975629174d1e4a531fedb1f3cbcf908ae740a80f224ebfb02e3b000","title":"Add programmatic tip injection API","description":"Allow tips to be programmatically injected at runtime based on detected conditions. This enables dynamic tips (not just pre-defined ones) to be shown with custom priority and frequency.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-11-11T23:29:46.645583-08:00","updated_at":"2025-11-11T23:50:12.209135-08:00","source_repo":".","dependencies":[{"issue_id":"bd-81a","depends_on_id":"bd-d4i","type":"blocks","created_at":"2025-11-11T23:29:46.646327-08:00","created_by":"daemon"}]}
{"id":"bd-870","content_hash":"303d42ce08633e610fc70d47bdbdba76fdb639fbf688d4a7a150f68ca78f52f8","title":"Fix Nix flake: stale vendorHash and version","description":"The Nix flake in default.nix has:\n1. version = \"0.9.9\" (should track current release version)\n2. vendorHash needs regeneration after dependency updates\n\nThis causes 'Test Nix Flake' CI to fail consistently.\n\nTo fix:\n1. Update version to 0.24.4\n2. Run 'nix build' and copy the correct vendorHash from the error message\n3. Update vendorHash in default.nix","status":"open","priority":1,"issue_type":"bug","created_at":"2025-11-24T22:25:38.397825-08:00","updated_at":"2025-11-24T22:25:38.397825-08:00","source_repo":"."}
{"id":"bd-90v","content_hash":"9863bc4154603ebc58c4649f8a74b5508f8b30aae6db360e84485e2d7f19fb30","title":"bd prime: AI context loading and Claude Code integration","description":"Implement `bd prime` command and Claude Code hooks for context recovery. Hooks work with BOTH MCP server and CLI approaches - they solve the context memory problem (keeping bd workflow fresh after compaction) not the tool access problem (MCP vs CLI).","design":"## Epic Scope\n\nThis epic covers:\n1. Core `bd prime` command implementation with MCP-aware output\n2. Claude Code hooks via `bd setup claude` (works with MCP OR CLI)\n3. Automatic context recovery via SessionStart/PreCompact hooks\n4. `bd doctor` verification for Claude setup\n5. Documentation updates\n\n## Goals\n- Keep bd workflow fresh in agent context (prevent markdown TODO reversion)\n- Enable automatic context recovery after compaction/clear\n- Adapt to user's workflow preference (MCP vs CLI) automatically\n- Support multi-user projects (mixed Claude/non-Claude teams)\n- Verify setup with `bd doctor`\n\n## Architecture Understanding\n\n**MCP vs CLI is a user preference (not project-level):**\n- User installs MCP server globally → gets native bd tools\n- User doesn't install MCP → uses CLI via Bash tool\n- `bd prime` auto-detects which mode and adapts output\n- Same hooks work for all users regardless of preference\n\n**Hooks complement both approaches:**\n- **With MCP**: Hooks output workflow reminders (~500 tokens) - prevents forgetting to use MCP tools\n- **Without MCP**: Hooks output full CLI reference (~1-2k tokens) - provides command syntax\n- **Both cases**: Prevents markdown TODO reversion after compaction\n\n**Why hooks matter even with MCP:**\n- MCP tools can be forgotten after compaction\n- Hooks refresh \"use bd, not markdown\" reminder\n- PreCompact keeps bd workflow fresh in memory\n- Works in both MCP and CLI scenarios\n\n## Token Optimization\n\n**MCP mode** (~500 tokens):\n- Workflow reminders only\n- No CLI syntax (user has native tools)\n- References to MCP tool names\n\n**Non-MCP mode** (~1-2k tokens):\n- Full workflow rules\n- Complete CLI command reference\n- Examples and common patterns\n\n**Why adaptive output matters:**\n- MCP users waste tokens on CLI docs they don't need\n- Non-MCP users need full command reference\n- Same hook works for everyone, adapts automatically\n- Multi-user projects: each dev gets appropriate output for their setup\n\n## Out of Scope\n- Tip system infrastructure (separate epic)\n- Cursor/Windsurf integration (separate issues)\n- MCP server modifications","acceptance_criteria":"- `bd prime` command exists and outputs AI-optimized markdown\n- `bd setup claude` installs hooks and slash commands\n- Hooks auto-call `bd prime` when .beads/ detected\n- `bd doctor` verifies Claude integration\n- Documentation complete in AGENTS.md, README.md, QUICKSTART.md\n- All child issues closed","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-11-11T23:31:12.119012-08:00","updated_at":"2025-11-24T22:06:07.57205-08:00","closed_at":"2025-11-24T22:06:07.57205-08:00","source_repo":"."}
{"id":"bd-9li4","content_hash":"7ae7b885e82a2de333584c01f690dbc3ecb924603f18e316f5c91cc44e2256f8","title":"Create Docker image for Agent Mail","description":"Containerize Agent Mail server for easy deployment.\n\nAcceptance Criteria:\n- Dockerfile with Python 3.14\n- Health check endpoint\n- Volume mount for storage\n- Environment variable configuration\n- Multi-arch builds (amd64, arm64)\n\nFile: deployment/agent-mail/Dockerfile","status":"closed","priority":3,"issue_type":"task","created_at":"2025-11-07T22:43:43.231964-08:00","updated_at":"2025-11-24T22:05:47.676443-08:00","closed_at":"2025-11-24T22:05:47.676443-08:00","source_repo":"."}
{"id":"bd-au0","content_hash":"755c63ab5b27bc77ee20034d16cc63614a0b3f10a81728f1bde5503cf6615813","title":"Command Set Standardization \u0026 Flag Consistency","description":"Comprehensive improvements to bd command set based on 2025 audit findings.\n\n## Background\nSee docs/command-audit-2025.md for detailed analysis.\n\n## Goals\n1. Standardize flag naming and behavior across all commands\n2. Add missing flags for feature parity\n3. Fix naming confusion\n4. Improve consistency in JSON output\n\n## Success Criteria\n- All mutating commands support --dry-run (no --preview variants)\n- bd update supports label operations\n- bd search has filter parity with bd list\n- Priority flags accept both int and P0-P4 format everywhere\n- JSON output is consistent across all commands","status":"open","priority":2,"issue_type":"epic","created_at":"2025-11-21T21:05:55.672749-05:00","updated_at":"2025-11-21T21:05:55.672749-05:00","source_repo":"."}

89
CHANGELOG.md
View File

@@ -7,6 +7,95 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
## [0.24.4] - 2025-11-25
### Added
- **Transaction API**: Full transactional support for atomic multi-operation workflows (bd-8bq)
- New `storage.Transaction` interface with CreateIssue, UpdateIssue, CloseIssue, DeleteIssue
- Dependency operations: AddDependency, RemoveDependency within transactions
- Label operations: AddLabel, RemoveLabel with transactional semantics
- Config/Metadata operations for atomic config+issue workflows
- Uses `BEGIN IMMEDIATE` mode to prevent deadlocks
- Automatic rollback on error or panic, commit on success
- 1,147 lines of new implementation with comprehensive tests
- **Tip System Infrastructure**: Smart contextual hints for users (bd-d4i)
- Tips shown after successful commands (list, ready, create, show)
- Condition-based filtering, priority ordering, probability rolls
- Frequency limits prevent tip spam
- Respects `--json` and `--quiet` flags
- Deterministic testing via `BEADS_TIP_SEED` env var
- **Sorting for bd list and bd search**: New `--sort` and `--reverse` flags (bd-22g)
- Sort by: priority, created, updated, closed, status, id, title, type, assignee
- Smart defaults: priority ascending (P0 first), dates descending (newest first)
- Works with all existing filters
- **Claude Integration Verification**: New bd doctor checks (bd-o78)
- `CheckBdInPath`: verifies 'bd' is in PATH (needed for hooks)
- `CheckDocumentationBdPrimeReference`: detects version mismatches in docs
- **ARM Linux Support**: GoReleaser now builds for linux/arm64 (PR #371 by @tjg184)
- Enables bd on ARM-based Linux systems like Raspberry Pi, AWS Graviton
- **Orphan Detection Migration**: Identifies orphaned child issues (bd-3852)
- Detects issues with hierarchical IDs where parent no longer exists
- Logs suggestions: delete, convert to standalone, or restore parent
- Idempotent and safe to run multiple times
### Fixed
- **Transaction Cache Invalidation**: blocked_issues_cache now invalidates correctly (bd-1c4h)
- UpdateIssue status changes trigger cache invalidation
- CloseIssue always invalidates (closed issues don't block)
- AddDependency/RemoveDependency invalidate for blocking types
- **SQLITE_BUSY Retry Logic**: Exponential backoff for concurrent writes (bd-ola6)
- `beginImmediateWithRetry()` with 5 retries (10ms, 20ms, 40ms, 80ms, 160ms)
- Eliminates spurious failures under normal concurrent usage
- Context cancellation respected between retry attempts
- **bd import Argument Validation**: Helpful error for common mistake (bd-77gm)
- Running `bd import file.jsonl` (without `-i`) now shows clear error
- Previously silently read from stdin, confusing users with "0 created"
- **ZFC Import Export Skip**: Preserve JSONL source of truth (bd-l0r)
- After stale DB import from JSONL, skip export to avoid overwriting
- Fixes scenario where DB with fewer issues would overwrite JSONL
- **Daemon Reopen with Reason**: `--reason` flag now works in daemon mode (bd-r46)
- Previously ignored in daemon RPC calls
- **Windows Test Failures**: Skip file permission tests on Windows
- Windows doesn't support Unix-style permissions (0600, 0755)
- Core functionality still tested, only permission checks skipped
### Changed
- **bd daemon UX**: New `--start` flag, help text when no args (bd-gfu)
- `bd daemon` now shows help instead of immediately starting
- Use `bd daemon --start` to explicitly start
- Auto-start still works (uses `--start` internally)
- More discoverable for new users
### Documentation
- **blocked_issues_cache Architecture**: Document cache behavior and invalidation
- **Antivirus False Positives**: Guide for handling security software alerts (bd-t4u1)
- **import.orphan_handling**: Complete documentation (bd-9cdc)
- **Error Handling Patterns**: Comprehensive audit and guidelines
### Dependencies
- Bump github.com/tetratelabs/wazero from 1.10.0 to 1.10.1 (#374)
- Bump github.com/anthropics/anthropic-sdk-go from 1.18.0 to 1.18.1 (#373)
- Bump actions/checkout from 4 to 6 (#372)
### Community
- PR #371: ARM Linux support (@tjg184)
## [0.24.3] - 2025-11-24
### Added