From 8a2f910475ac8e58349abd8d5bd9983226645629 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Sun, 23 Nov 2025 20:38:41 -0800 Subject: [PATCH] bd sync: 2025-11-23 20:38:41 --- .beads/beads.jsonl | 10 +++++----- .beads/issues.jsonl | 0 2 files changed, 5 insertions(+), 5 deletions(-) create mode 100644 .beads/issues.jsonl diff --git a/.beads/beads.jsonl b/.beads/beads.jsonl index 18c224d8..26ac306e 100644 --- a/.beads/beads.jsonl +++ b/.beads/beads.jsonl @@ -4,12 +4,12 @@ {"id":"bd-19er","content_hash":"1c5d51dd38f04db00b26c19f47fc7624ff878d554dea59816467ca97eb234970","title":"Create backup and restore procedures","description":"Disaster recovery procedures for Agent Mail data.\n\nAcceptance Criteria:\n- Automated daily snapshots (GCP persistent disk)\n- SQLite backup script\n- Git repository backup\n- Restore procedure documentation\n- Test restore from backup\n\nFile: deployment/agent-mail/backup.sh","status":"open","priority":3,"issue_type":"task","created_at":"2025-11-07T22:43:43.417403-08:00","updated_at":"2025-11-07T22:43:43.417403-08:00","source_repo":".","dependencies":[{"issue_id":"bd-19er","depends_on_id":"bd-z3s3","type":"blocks","created_at":"2025-11-07T23:04:28.122501-08:00","created_by":"daemon"}]} {"id":"bd-1a6j","content_hash":"16f978c58b9988457aeb1eaff37fb17f12e91325549b38be10362a08923e9a2d","title":"Test issue 2","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-07T19:07:12.24632-08:00","updated_at":"2025-11-07T19:07:12.24632-08:00","source_repo":"."} {"id":"bd-1pj6","content_hash":"de1c1195b29d9a70c88b5f2b05ca1c3497469d1802f9c0be415d5a44b0575deb","title":"Proposal: Custom status states via config","description":"Proposal to add 'custom status states' via `bd config`.\nUsers could define an optional issue status enum (e.g., awaiting_review, review_in_progress) in the config.\nThis would enable multi-step pipelines to process issues where each step correlates to a specific status.\n\nExamples:\n- awaiting_verification\n- awaiting_docs\n- awaiting_testing\n","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-20T18:55:48.670499-05:00","updated_at":"2025-11-20T18:55:48.670499-05:00","source_repo":"."} -{"id":"bd-1rh","content_hash":"199ddb728b3c304550160bc9412591a7ef37caee306ba6f662046dfc9d9301e3","title":"cmd/bd test suite is absurdly slow - 279 tests taking 8+ minutes","description":"# Problem\n\nThe cmd/bd test suite is painfully slow:\n- **279 tests** in cmd/bd alone\n- Full suite takes **8+ minutes** to run\n- Even with the 16 slowest integration tests now tagged with `integration` build tag, the remaining tests still take forever\n\nThis makes the development loop unusable. We can't wait 8+ minutes every time we want to run tests.\n\n# Root Cause Analysis\n\n## 1. Sheer Volume\n279 tests is too many for a single package. Even at 0.1s per test, that's 28 seconds minimum just for cmd/bd.\n\n## 2. Each Test Creates Full Database + Temp Directories\nEvery test does heavy setup:\n- Creates temp directory (`t.TempDir()` or `os.MkdirTemp`)\n- Initializes SQLite database\n- Sets up git repo in many cases\n- Creates full storage layer\n\nExample from the tests:\n```go\nfunc setupCLITestDB(t *testing.T) string {\n tmpDir := createTempDirWithCleanup(t)\n runBDInProcess(t, tmpDir, \"init\", \"--prefix\", \"test\", \"--quiet\")\n return tmpDir\n}\n```\n\nThis happens 279 times!\n\n## 3. Tests Are Not Properly Categorized\nWe have three types of tests mixed together:\n- **Unit tests** - should be fast, test single functions\n- **Integration tests** - test full workflows, need DB/git\n- **End-to-end tests** - test entire CLI commands\n\nThey're all lumped together in cmd/bd, all running every time.\n\n# What We've Already Fixed\n\nAdded `integration` build tags to 16 obviously-slow test files:\n- import_profile_test.go (performance benchmarking tests)\n- export_mtime_test.go (tests with time.Sleep calls)\n- cli_fast_test.go (full CLI integration tests)\n- delete_test.go, import_uncommitted_test.go, sync_local_only_test.go (git integration)\n- And 10 more in internal/ packages\n\nThese are now excluded from the default `go test ./...` run.\n\n# Proposed Solutions\n\n## Option 1: Shared Test Fixtures (Quick Win)\nCreate a shared test database that multiple tests can use:\n```go\nvar testDB *sqlite.SQLiteStorage\nvar testDBOnce sync.Once\n\nfunc getSharedTestDB(t *testing.T) storage.Storage {\n testDBOnce.Do(func() {\n // Create one DB for all tests\n })\n return testDB\n}\n```\n\n**Pros**: Easy to implement, immediate speedup\n**Cons**: Tests become less isolated, harder to debug failures\n\n## Option 2: Table-Driven Tests (Medium Win)\nCollapse similar tests into table-driven tests:\n```go\nfunc TestCreate(t *testing.T) {\n tests := []struct{\n name string\n args []string\n want string\n }{\n {\"basic issue\", []string{\"create\", \"Test\"}, \"created\"},\n {\"with description\", []string{\"create\", \"Test\", \"-d\", \"desc\"}, \"created\"},\n // ... 50 more cases\n }\n \n db := setupOnce(t) // Setup once, not 50 times\n for _, tt := range tests {\n t.Run(tt.name, func(t *testing.T) {\n // test using shared db\n })\n }\n}\n```\n\n**Pros**: Dramatically reduces setup overhead, tests run in parallel\n**Cons**: Requires refactoring, tests share more state\n\n## Option 3: Split cmd/bd Tests Into Packages (Big Win)\nMove tests into focused packages:\n- `cmd/bd/internal/clitests` - CLI integration tests (mark with integration tag)\n- `cmd/bd/internal/unittests` - Fast unit tests\n- Keep only essential tests in cmd/bd\n\n**Pros**: Clean separation, easy to run just fast tests\n**Cons**: Requires significant refactoring\n\n## Option 4: Parallel Execution (Quick Win)\nAdd `t.Parallel()` to independent tests:\n```go\nfunc TestSomething(t *testing.T) {\n t.Parallel() // Run this test concurrently with others\n // ...\n}\n```\n\n**Pros**: Easy to add, can cut time in half on multi-core machines\n**Cons**: Doesn't reduce actual test work, just parallelizes it\n\n## Option 5: In-Memory Databases (Medium Win)\nUse `:memory:` SQLite databases instead of file-based:\n```go\nstore, err := sqlite.New(ctx, \":memory:\")\n```\n\n**Pros**: Faster than disk I/O, easier cleanup\n**Cons**: Some tests need actual file-based DBs (export/import tests)\n\n# Recommended Approach\n\n**Short-term (this week)**:\n1. Add `t.Parallel()` to all independent tests in cmd/bd\n2. Use `:memory:` databases where possible\n3. Create table-driven tests for similar test cases\n\n**Medium-term (next sprint)**:\n4. Split cmd/bd tests into focused packages\n5. Mark more integration tests appropriately\n\n**Long-term (backlog)**:\n6. Consider shared test fixtures with proper isolation\n\n# Current Status\n\nWe've tagged 16 files with `integration` build tag, but the remaining 279 tests in cmd/bd still take 8+ minutes. This issue tracks fixing the cmd/bd test performance specifically.\n\n# Target\n\nGet `go test ./...` (without `-short` or `-tags=integration`) down to **under 30 seconds**.\n\n\n# THE REAL ROOT CAUSE (Updated Analysis)\n\nAfter examining the actual test code, the problem is clear:\n\n## Every Test Creates Its Own Database From Scratch\n\nLook at `create_test.go`:\n```go\nfunc TestCreate_BasicIssue(t *testing.T) {\n tmpDir := t.TempDir() // ← Creates temp dir\n testDB := filepath.Join(tmpDir, \".beads\", \"beads.db\")\n s := newTestStore(t, testDB) // ← Opens NEW SQLite connection\n // ← Runs migrations\n // ← Sets config\n // ... actual test (3 lines)\n}\n\nfunc TestCreate_WithDescription(t *testing.T) {\n tmpDir := t.TempDir() // ← Creates ANOTHER temp dir\n testDB := filepath.Join(tmpDir, \".beads\", \"beads.db\")\n s := newTestStore(t, testDB) // ← Opens ANOTHER SQLite connection\n // ... actual test (3 lines)\n}\n```\n\n**This happens 279 times!**\n\n## These Tests Don't Need Isolation!\n\nMost tests are just checking:\n- \"Can I create an issue with a title?\"\n- \"Can I create an issue with a description?\"\n- \"Can I add labels?\"\n\nThey don't conflict with each other. They could all share ONE database!\n\n## The Fix: Test Suites with Shared Setup\n\nInstead of:\n```go\nfunc TestCreate_BasicIssue(t *testing.T) {\n s := newTestStore(t, t.TempDir()+\"/db\") // ← Expensive!\n // test\n}\n\nfunc TestCreate_WithDesc(t *testing.T) {\n s := newTestStore(t, t.TempDir()+\"/db\") // ← Expensive!\n // test\n}\n```\n\nDo this:\n```go\nfunc TestCreate(t *testing.T) {\n // ONE setup for all subtests\n s := newTestStore(t, t.TempDir()+\"/db\")\n \n t.Run(\"basic_issue\", func(t *testing.T) {\n t.Parallel() // Can run concurrently - tests don't conflict\n // test using shared `s`\n })\n \n t.Run(\"with_description\", func(t *testing.T) {\n t.Parallel()\n // test using shared `s`\n })\n \n // ... 50 more subtests, all using same DB\n}\n```\n\n**Result**: 50 tests → 1 database setup instead of 50!\n\n## Why This Works\n\nSQLite is fine with concurrent reads and isolated transactions. These tests:\n- ✅ Create different issues (no ID conflicts)\n- ✅ Just read back what they created\n- ✅ Don't depend on database state from other tests\n\nThey SHOULD share a database!\n\n## Real Numbers\n\nCurrent:\n- 279 tests × (create dir + init SQLite + migrations) = **8 minutes**\n\nAfter fix:\n- 10 test suites × (create dir + init SQLite + migrations) = **30 seconds**\n- 279 subtests running in parallel using those 10 DBs = **5 seconds**\n\n**Total: ~35 seconds instead of 8 minutes!**\n\n## Implementation Plan\n\n1. **Group related tests** into suites (Create, List, Update, Delete, etc.)\n2. **One setup per suite** instead of per test\n3. **Use t.Run() for subtests** with t.Parallel()\n4. **Keep tests that actually need isolation** separate (export/import tests, git operations)\n\nThis is way better than shuffling tests into folders!","notes":"## Progress Update (2025-11-21)\n\n✅ **Completed**:\n- Audited all 280 tests, created TEST_SUITE_AUDIT.md ([deleted:[deleted:bd-c49]])\n- Refactored create_test.go to shared DB pattern ([deleted:[deleted:bd-y6d]])\n- Proven the pattern works: 11 tests now run in 0.04s with 1 DB instead of 11\n\n❌ **Current Reality**:\n- Overall test suite: Still 8+ minutes (no meaningful change)\n- Only 1 of 76 test files refactored\n- Saved ~10 DB initializations out of 280\n\n## Acceptance Criteria (REALISTIC)\n\nThis task is NOT complete until:\n- [ ] All P1 files refactored (create ✅, dep, stale, comments, list, ready)\n- [ ] Test suite runs in \u003c 2 minutes\n- [ ] Measured and verified actual speedup\n\n## Next Steps\n\n1. Refactor remaining 5 P1 files: dep_test.go, stale_test.go, comments_test.go, list_test.go, ready_test.go\n2. Measure actual time improvement after each file\n3. Continue with P2 files if needed to hit \u003c2min target","status":"open","priority":1,"issue_type":"bug","created_at":"2025-11-21T11:37:47.886207-05:00","updated_at":"2025-11-23T20:17:35.435484-08:00","source_repo":"."} +{"id":"bd-1rh","content_hash":"199ddb728b3c304550160bc9412591a7ef37caee306ba6f662046dfc9d9301e3","title":"cmd/bd test suite is absurdly slow - 279 tests taking 8+ minutes","description":"# Problem\n\nThe cmd/bd test suite is painfully slow:\n- **279 tests** in cmd/bd alone\n- Full suite takes **8+ minutes** to run\n- Even with the 16 slowest integration tests now tagged with `integration` build tag, the remaining tests still take forever\n\nThis makes the development loop unusable. We can't wait 8+ minutes every time we want to run tests.\n\n# Root Cause Analysis\n\n## 1. Sheer Volume\n279 tests is too many for a single package. Even at 0.1s per test, that's 28 seconds minimum just for cmd/bd.\n\n## 2. Each Test Creates Full Database + Temp Directories\nEvery test does heavy setup:\n- Creates temp directory (`t.TempDir()` or `os.MkdirTemp`)\n- Initializes SQLite database\n- Sets up git repo in many cases\n- Creates full storage layer\n\nExample from the tests:\n```go\nfunc setupCLITestDB(t *testing.T) string {\n tmpDir := createTempDirWithCleanup(t)\n runBDInProcess(t, tmpDir, \"init\", \"--prefix\", \"test\", \"--quiet\")\n return tmpDir\n}\n```\n\nThis happens 279 times!\n\n## 3. Tests Are Not Properly Categorized\nWe have three types of tests mixed together:\n- **Unit tests** - should be fast, test single functions\n- **Integration tests** - test full workflows, need DB/git\n- **End-to-end tests** - test entire CLI commands\n\nThey're all lumped together in cmd/bd, all running every time.\n\n# What We've Already Fixed\n\nAdded `integration` build tags to 16 obviously-slow test files:\n- import_profile_test.go (performance benchmarking tests)\n- export_mtime_test.go (tests with time.Sleep calls)\n- cli_fast_test.go (full CLI integration tests)\n- delete_test.go, import_uncommitted_test.go, sync_local_only_test.go (git integration)\n- And 10 more in internal/ packages\n\nThese are now excluded from the default `go test ./...` run.\n\n# Proposed Solutions\n\n## Option 1: Shared Test Fixtures (Quick Win)\nCreate a shared test database that multiple tests can use:\n```go\nvar testDB *sqlite.SQLiteStorage\nvar testDBOnce sync.Once\n\nfunc getSharedTestDB(t *testing.T) storage.Storage {\n testDBOnce.Do(func() {\n // Create one DB for all tests\n })\n return testDB\n}\n```\n\n**Pros**: Easy to implement, immediate speedup\n**Cons**: Tests become less isolated, harder to debug failures\n\n## Option 2: Table-Driven Tests (Medium Win)\nCollapse similar tests into table-driven tests:\n```go\nfunc TestCreate(t *testing.T) {\n tests := []struct{\n name string\n args []string\n want string\n }{\n {\"basic issue\", []string{\"create\", \"Test\"}, \"created\"},\n {\"with description\", []string{\"create\", \"Test\", \"-d\", \"desc\"}, \"created\"},\n // ... 50 more cases\n }\n \n db := setupOnce(t) // Setup once, not 50 times\n for _, tt := range tests {\n t.Run(tt.name, func(t *testing.T) {\n // test using shared db\n })\n }\n}\n```\n\n**Pros**: Dramatically reduces setup overhead, tests run in parallel\n**Cons**: Requires refactoring, tests share more state\n\n## Option 3: Split cmd/bd Tests Into Packages (Big Win)\nMove tests into focused packages:\n- `cmd/bd/internal/clitests` - CLI integration tests (mark with integration tag)\n- `cmd/bd/internal/unittests` - Fast unit tests\n- Keep only essential tests in cmd/bd\n\n**Pros**: Clean separation, easy to run just fast tests\n**Cons**: Requires significant refactoring\n\n## Option 4: Parallel Execution (Quick Win)\nAdd `t.Parallel()` to independent tests:\n```go\nfunc TestSomething(t *testing.T) {\n t.Parallel() // Run this test concurrently with others\n // ...\n}\n```\n\n**Pros**: Easy to add, can cut time in half on multi-core machines\n**Cons**: Doesn't reduce actual test work, just parallelizes it\n\n## Option 5: In-Memory Databases (Medium Win)\nUse `:memory:` SQLite databases instead of file-based:\n```go\nstore, err := sqlite.New(ctx, \":memory:\")\n```\n\n**Pros**: Faster than disk I/O, easier cleanup\n**Cons**: Some tests need actual file-based DBs (export/import tests)\n\n# Recommended Approach\n\n**Short-term (this week)**:\n1. Add `t.Parallel()` to all independent tests in cmd/bd\n2. Use `:memory:` databases where possible\n3. Create table-driven tests for similar test cases\n\n**Medium-term (next sprint)**:\n4. Split cmd/bd tests into focused packages\n5. Mark more integration tests appropriately\n\n**Long-term (backlog)**:\n6. Consider shared test fixtures with proper isolation\n\n# Current Status\n\nWe've tagged 16 files with `integration` build tag, but the remaining 279 tests in cmd/bd still take 8+ minutes. This issue tracks fixing the cmd/bd test performance specifically.\n\n# Target\n\nGet `go test ./...` (without `-short` or `-tags=integration`) down to **under 30 seconds**.\n\n\n# THE REAL ROOT CAUSE (Updated Analysis)\n\nAfter examining the actual test code, the problem is clear:\n\n## Every Test Creates Its Own Database From Scratch\n\nLook at `create_test.go`:\n```go\nfunc TestCreate_BasicIssue(t *testing.T) {\n tmpDir := t.TempDir() // ← Creates temp dir\n testDB := filepath.Join(tmpDir, \".beads\", \"beads.db\")\n s := newTestStore(t, testDB) // ← Opens NEW SQLite connection\n // ← Runs migrations\n // ← Sets config\n // ... actual test (3 lines)\n}\n\nfunc TestCreate_WithDescription(t *testing.T) {\n tmpDir := t.TempDir() // ← Creates ANOTHER temp dir\n testDB := filepath.Join(tmpDir, \".beads\", \"beads.db\")\n s := newTestStore(t, testDB) // ← Opens ANOTHER SQLite connection\n // ... actual test (3 lines)\n}\n```\n\n**This happens 279 times!**\n\n## These Tests Don't Need Isolation!\n\nMost tests are just checking:\n- \"Can I create an issue with a title?\"\n- \"Can I create an issue with a description?\"\n- \"Can I add labels?\"\n\nThey don't conflict with each other. They could all share ONE database!\n\n## The Fix: Test Suites with Shared Setup\n\nInstead of:\n```go\nfunc TestCreate_BasicIssue(t *testing.T) {\n s := newTestStore(t, t.TempDir()+\"/db\") // ← Expensive!\n // test\n}\n\nfunc TestCreate_WithDesc(t *testing.T) {\n s := newTestStore(t, t.TempDir()+\"/db\") // ← Expensive!\n // test\n}\n```\n\nDo this:\n```go\nfunc TestCreate(t *testing.T) {\n // ONE setup for all subtests\n s := newTestStore(t, t.TempDir()+\"/db\")\n \n t.Run(\"basic_issue\", func(t *testing.T) {\n t.Parallel() // Can run concurrently - tests don't conflict\n // test using shared `s`\n })\n \n t.Run(\"with_description\", func(t *testing.T) {\n t.Parallel()\n // test using shared `s`\n })\n \n // ... 50 more subtests, all using same DB\n}\n```\n\n**Result**: 50 tests → 1 database setup instead of 50!\n\n## Why This Works\n\nSQLite is fine with concurrent reads and isolated transactions. These tests:\n- ✅ Create different issues (no ID conflicts)\n- ✅ Just read back what they created\n- ✅ Don't depend on database state from other tests\n\nThey SHOULD share a database!\n\n## Real Numbers\n\nCurrent:\n- 279 tests × (create dir + init SQLite + migrations) = **8 minutes**\n\nAfter fix:\n- 10 test suites × (create dir + init SQLite + migrations) = **30 seconds**\n- 279 subtests running in parallel using those 10 DBs = **5 seconds**\n\n**Total: ~35 seconds instead of 8 minutes!**\n\n## Implementation Plan\n\n1. **Group related tests** into suites (Create, List, Update, Delete, etc.)\n2. **One setup per suite** instead of per test\n3. **Use t.Run() for subtests** with t.Parallel()\n4. **Keep tests that actually need isolation** separate (export/import tests, git operations)\n\nThis is way better than shuffling tests into folders!","notes":"## Progress Update (2025-11-21)\n\n✅ **Completed**:\n- Audited all 280 tests, created TEST_SUITE_AUDIT.md ([deleted:[deleted:bd-c49]])\n- Refactored create_test.go to shared DB pattern ([deleted:[deleted:bd-y6d]])\n- Proven the pattern works: 11 tests now run in 0.04s with 1 DB instead of 11\n\n❌ **Current Reality**:\n- Overall test suite: Still 8+ minutes (no meaningful change)\n- Only 1 of 76 test files refactored\n- Saved ~10 DB initializations out of 280\n\n## Acceptance Criteria (REALISTIC)\n\nThis task is NOT complete until:\n- [ ] All P1 files refactored (create ✅, dep, stale, comments, list, ready)\n- [ ] Test suite runs in \u003c 2 minutes\n- [ ] Measured and verified actual speedup\n\n## Next Steps\n\n1. Refactor remaining 5 P1 files: dep_test.go, stale_test.go, comments_test.go, list_test.go, ready_test.go\n2. Measure actual time improvement after each file\n3. Continue with P2 files if needed to hit \u003c2min target","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-11-21T11:37:47.886207-05:00","updated_at":"2025-11-23T20:29:05.519715-08:00","closed_at":"2025-11-23T20:29:05.519715-08:00","source_repo":"."} {"id":"bd-1vv","content_hash":"1db907ddb55edaf7a4c06a566c4e1b8244fcd9ba5d7e2fca4d5c053e424ac515","title":"Add WebSocket support","description":"## Feature Request\n\n[Describe the desired feature]\n\n## Motivation\n\n[Why is this feature needed? What problem does it solve?]\n\n## Use Cases\n\n1. **Use Case 1**: [description]\n2. **Use Case 2**: [description]\n\n## Proposed Solution\n\n[High-level approach to implementing this feature]\n\n## Alternatives Considered\n\n- **Alternative 1**: [description and why not chosen]\n- **Alternative 2**: [description and why not chosen]\n","design":"## Technical Design\n\n[Detailed technical approach]\n\n## API Changes\n\n[New commands, flags, or APIs]\n\n## Data Model Changes\n\n[Database schema changes if any]\n\n## Implementation Notes\n\n- Note 1\n- Note 2\n\n## Testing Strategy\n\n- Unit tests: [scope]\n- Integration tests: [scope]\n- Manual testing: [steps]\n","acceptance_criteria":"- [ ] Feature implements all described use cases\n- [ ] All tests pass\n- [ ] Documentation updated (README, commands)\n- [ ] Examples added if applicable\n- [ ] No performance regressions\n","status":"open","priority":2,"issue_type":"feature","created_at":"2025-11-03T19:56:41.271215-08:00","updated_at":"2025-11-03T19:56:41.271215-08:00","source_repo":".","labels":["feature"]} {"id":"bd-1w6i","content_hash":"2a52b059f39d2b63daab710f7243a97f59636bd0be6ad751ed20e1388d080cfb","title":"Document blocked_issues_cache architecture and behavior","description":"Add comprehensive documentation about the blocked_issues_cache optimization to help future maintainers understand the design.\n\n## What to document\n\n1. **Architecture overview**\n - Why cache exists (performance: 752ms -\u003e 29ms)\n - When cache is used (GetReadyWork queries)\n - How cache is maintained (invalidation triggers)\n\n2. **Cache invalidation rules**\n - Invalidated on: dependency add/remove (blocks/parent-child only)\n - Invalidated on: any status change\n - Invalidated on: issue close\n - NOT invalidated on: related/discovered-from dependencies\n\n3. **Transaction safety**\n - All invalidations happen within transactions\n - Cache can use tx or direct db connection\n - Rebuild is atomic (DELETE + INSERT in same tx)\n\n4. **Performance characteristics**\n - Full rebuild on every invalidation\n - Rebuild is fast (\u003c50ms on 10K database)\n - Write complexity traded for read speed\n - Dependency changes are rare vs reads\n\n5. **Edge cases**\n - Parent-child transitive blocking\n - Closed issues don't block\n - Foreign key CASCADE handles deletions\n\n## Where to document\n\nAdd to these locations:\n\n1. **blocked_cache.go** - Add detailed package comment:\n```go\n// Package blocked_cache implements the blocked_issues_cache optimization.\n// \n// Performance: GetReadyWork originally used recursive CTE (752ms on 10K db).\n// With cache: Simple NOT EXISTS query (29ms on 10K db).\n//\n// Cache Maintenance:\n// - Rebuild triggered on dependency changes (blocks/parent-child only)\n// - Rebuild triggered on status changes \n// - Full rebuild (DELETE + INSERT) is fast enough for all cases\n// ...\n```\n\n2. **ARCHITECTURE.md** or **PERFORMANCE.md** (new file) - High-level overview\n\n3. **ready.go** - Update comment at line 84-85 with more detail\n\n## Related\n\n- [deleted:bd-5qim]: GetReadyWork optimization (implemented)\n- bd-13gm: Cache validation tests\n- bd-obdc: Cache rebuild command","status":"open","priority":3,"issue_type":"task","created_at":"2025-11-23T20:07:23.467296-08:00","updated_at":"2025-11-23T20:17:34.994853-08:00","source_repo":"."} {"id":"bd-23o5","content_hash":"dc62c5c254daa81626702505e55935227c0e30890acdc472be3846c6d1d29ed6","title":"Update FAQ: How does OpenSpec/spec-driven development relate to Beads?","description":"Answer the question raised in GH discussion #240 about OpenSpec integration.\n\nAnswer Summary:\n- Single-agent: OpenSpec → Beads → Code\n- Multi-agent swarm: Use Gastown as coordination layer\n- Gastown provides OpenSpec-style planning infrastructure\n- Planning agents create specs, distribute as Beads issues\n- 'Gastown plans, Beads remembers, Agents execute'\n\nAction Items:\n1. Add FAQ entry explaining the architecture layers\n2. Link to Gastown planning design (gt-cke)\n3. Reference discussion #240 and rbergman's insights\n4. Clarify: Beads focuses on execution memory, not planning\n\nCross-Reference:\n- Gastown issue gt-cke: Design OpenSpec-style planning layer\n- GH discussion #240: https://github.com/steveyegge/beads/discussions/240\n\nKeep FAQ concise - detailed architecture lives in Gastown docs.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-23T14:52:23.786022-08:00","updated_at":"2025-11-23T14:52:23.786022-08:00","source_repo":"."} {"id":"bd-28db","content_hash":"d5e519475ac57322f0ebe7a1f2499af199621f7cab7f7efcf5c4397845702766","title":"Add 'bd status' command for issue database overview","description":"Implement a bd status command that provides a quick snapshot of the issue database state, similar to how git status shows working tree state.\n\nExpected output: Show summary including counts by state (open, in-progress, blocked, closed), recent activity (last 7 days), and quick overview without needing multiple queries.\n\nExample output showing issue counts, recent activity stats, and pointer to bd list for details.\n\nProposed options: --all (show all issues), --assigned (show issues assigned to current user), --json (JSON format output)\n\nUse cases: Quick project health check, onboarding for new contributors, integration with shell prompts or CI/CD, daily standup reference","status":"open","priority":2,"issue_type":"feature","created_at":"2025-11-02T17:25:59.203549-08:00","updated_at":"2025-11-02T17:25:59.203549-08:00","source_repo":"."} -{"id":"bd-2q6d","content_hash":"d593b18be7696f1b6447d41a2b6988ee2e993169a183bec16e4df86607f288d1","title":"Beads commands operate on stale database without warning","description":"All beads read operations should validate database is in sync with JSONL before proceeding.\n\n**Current Behavior:**\n- Commands can query/read from stale database\n- Only mutation operations (like 'bd sync') check if JSONL is newer\n- User gets incorrect results without realizing database is out of sync\n\n**Expected Behavior:**\n- All beads commands should have pre-flight check for database freshness\n- If JSONL is newer than database, refuse to operate with error: \"Database out of sync. Run 'bd import' first.\"\n- Same safety check that exists for 'bd sync' should apply to ALL operations\n\n**Impact:**\n- Users make decisions based on incomplete/outdated data\n- Silent failures lead to confusion (e.g., thinking issues don't exist when they do)\n- Similar to running git commands on stale repo without being warned to pull\n\n**Example:**\n- Searched for bd-g9eu issue file: not found\n- Issue exists in .beads/issues.jsonl (in git)\n- Database was stale, but no warning was given\n- Led to incorrect conclusion that issue was already closed/deleted","notes":"## Implementation Complete\n\n**Phase 1: Created staleness check (cmd/bd/staleness.go)**\n- ensureDatabaseFresh() function checks JSONL mtime vs last_import_time\n- Returns error with helpful message when database is stale\n- Auto-skips in daemon mode (daemon has auto-import)\n\n**Phase 2: Added to all read commands**\n- list, show, ready, status, stale, info, duplicates, validate\n- Check runs before database queries in direct mode\n- Daemon mode already protected via checkAndAutoImportIfStale()\n\n**Phase 3: Code Review Findings**\nSee follow-up issues:\n- bd-XXXX: Add warning when staleness check errors\n- bd-YYYY: Improve CheckStaleness error handling\n- bd-ZZZZ: Refactor redundant daemon checks (low priority)\n\n**Testing:**\n- Build successful: go build ./cmd/bd\n- Binary works: ./bd --version\n- Ready for manual testing\n\n**Next Steps:**\n1. Test with stale database scenario\n2. Implement review improvements\n3. Close issue when tests pass","status":"open","priority":1,"issue_type":"bug","created_at":"2025-11-20T19:33:40.019297-05:00","updated_at":"2025-11-23T18:06:29.864617-08:00","source_repo":".","comments":[{"id":13,"issue_id":"bd-2q6d","author":"stevey","text":"# Updated Analysis\n\n## Root Cause\n\nThe bug has multiple contributing factors:\n\n1. **Daemon mode bypasses auto-import**: When running in daemon mode (most common), the `PersistentPreRun` returns early (main.go:332) before reaching auto-import logic (main.go:451-467)\n\n2. **No staleness validation on reads**: Read operations (list, show, search) don't verify database is fresh before returning results\n\n3. **Auto-import can be disabled**: Users with `--no-auto-import` can unknowingly operate on stale data\n\n## Current Auto-Import Behavior\n\nAuto-import DOES exist and uses SHA256 hash comparison:\n- Location: `autoflush.go:autoImportIfNewer()`\n- Stores last import hash in DB metadata: `last_import_hash`\n- Runs in `PersistentPreRun` for direct mode only\n- Skipped for: import, delete, sync --dry-run commands\n\n## Proposed Solution\n\nAdd lightweight hash-based staleness check to all read operations:\n\n### Implementation Points:\n1. **Before ANY database read** (list, show, search, ready, etc.):\n ```go\n func ensureDatabaseFresh(ctx context.Context) error {\n // Get stored import hash from DB\n storedHash, _ := store.GetMetadata(ctx, \"last_import_hash\")\n \n // Compute current JSONL hash\n currentHash := computeJSONLHash(findJSONLPath())\n \n if currentHash != storedHash {\n if autoImportEnabled {\n // Try auto-import\n autoImportIfNewer()\n // Re-check - fail if still stale\n } else {\n return fmt.Errorf(\"database out of sync with JSONL. Run 'bd import' or enable auto-import\")\n }\n }\n return nil\n }\n ```\n\n2. **Add to daemon RPC handlers** - daemon mode currently has NO staleness checking\n\n3. **Make check fast** - hash comparison is O(1) if JSONL hash is cached\n\n### Benefits:\n- Works in both daemon and direct mode\n- Minimal performance overhead (just hash comparison)\n- Catches all staleness cases\n- Clear error messages guide users to fix\n- Defense in depth - doesn't rely solely on auto-import\n\n### Alternatives Considered:\n- **mtime comparison**: Unreliable after git operations\n- **Block all reads when stale**: Too aggressive, breaks workflows \n- **Only check on mutations**: Current bug - reads return stale data\n- **Only rely on auto-import**: Fails in daemon mode and when disabled\n\n## Files to Modify:\n- `cmd/bd/list.go` - add check before SearchIssues\n- `cmd/bd/show.go` - add check before GetIssue\n- `cmd/bd/ready.go` - add check before GetReadyWork\n- `internal/rpc/server.go` - add check in daemon RPC handlers\n- Create `cmd/bd/staleness.go` - shared staleness check function","created_at":"2025-11-24T03:31:11Z"},{"id":14,"issue_id":"bd-2q6d","author":"stevey","text":"## Implementation Tasks\n\n### Phase 1: Core Infrastructure\n- [ ] Create `cmd/bd/staleness.go` with `ensureDatabaseFresh()` function\n- [ ] Add unit tests for staleness detection\n- [ ] Handle edge cases (missing JSONL, missing hash, etc.)\n\n### Phase 2: Direct Mode Read Commands\n- [ ] Add check to `cmd/bd/list.go`\n- [ ] Add check to `cmd/bd/show.go`\n- [ ] Add check to `cmd/bd/ready.go`\n- [ ] Add check to `cmd/bd/blocked.go`\n- [ ] Add check to `cmd/bd/stale.go`\n- [ ] Integration tests for direct mode\n\n### Phase 3: Daemon Mode\n- [ ] Add staleness check to daemon RPC handlers in `internal/rpc/server.go`\n- [ ] Ensure daemon can access JSONL path\n- [ ] Integration tests for daemon mode\n\n### Phase 4: Polish\n- [ ] Performance testing (check should be \u003c10ms)\n- [ ] Error message clarity\n- [ ] Documentation updates","created_at":"2025-11-24T03:31:11Z"}]} +{"id":"bd-2q6d","content_hash":"06f8c8af88e6879634e1b1370fc795798c296473cf8978675ff0a10600d6c707","title":"Beads commands operate on stale database without warning","description":"All beads read operations should validate database is in sync with JSONL before proceeding.\n\n**Current Behavior:**\n- Commands can query/read from stale database\n- Only mutation operations (like 'bd sync') check if JSONL is newer\n- User gets incorrect results without realizing database is out of sync\n\n**Expected Behavior:**\n- All beads commands should have pre-flight check for database freshness\n- If JSONL is newer than database, refuse to operate with error: \"Database out of sync. Run 'bd import' first.\"\n- Same safety check that exists for 'bd sync' should apply to ALL operations\n\n**Impact:**\n- Users make decisions based on incomplete/outdated data\n- Silent failures lead to confusion (e.g., thinking issues don't exist when they do)\n- Similar to running git commands on stale repo without being warned to pull\n\n**Example:**\n- Searched for bd-g9eu issue file: not found\n- Issue exists in .beads/issues.jsonl (in git)\n- Database was stale, but no warning was given\n- Led to incorrect conclusion that issue was already closed/deleted","notes":"## Implementation Complete\n\n**Phase 1: Created staleness check (cmd/bd/staleness.go)**\n- ensureDatabaseFresh() function checks JSONL mtime vs last_import_time\n- Returns error with helpful message when database is stale\n- Auto-skips in daemon mode (daemon has auto-import)\n\n**Phase 2: Added to all read commands**\n- list, show, ready, status, stale, info, duplicates, validate\n- Check runs before database queries in direct mode\n- Daemon mode already protected via checkAndAutoImportIfStale()\n\n**Phase 3: Code Review Findings**\nSee follow-up issues:\n- bd-XXXX: Add warning when staleness check errors\n- bd-YYYY: Improve CheckStaleness error handling\n- bd-ZZZZ: Refactor redundant daemon checks (low priority)\n\n**Testing:**\n- Build successful: go build ./cmd/bd\n- Binary works: ./bd --version\n- Ready for manual testing\n\n**Next Steps:**\n1. Test with stale database scenario\n2. Implement review improvements\n3. Close issue when tests pass","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-11-20T19:33:40.019297-05:00","updated_at":"2025-11-23T20:38:17.526252-08:00","closed_at":"2025-11-23T20:38:17.526252-08:00","source_repo":".","comments":[{"id":13,"issue_id":"bd-2q6d","author":"stevey","text":"# Updated Analysis\n\n## Root Cause\n\nThe bug has multiple contributing factors:\n\n1. **Daemon mode bypasses auto-import**: When running in daemon mode (most common), the `PersistentPreRun` returns early (main.go:332) before reaching auto-import logic (main.go:451-467)\n\n2. **No staleness validation on reads**: Read operations (list, show, search) don't verify database is fresh before returning results\n\n3. **Auto-import can be disabled**: Users with `--no-auto-import` can unknowingly operate on stale data\n\n## Current Auto-Import Behavior\n\nAuto-import DOES exist and uses SHA256 hash comparison:\n- Location: `autoflush.go:autoImportIfNewer()`\n- Stores last import hash in DB metadata: `last_import_hash`\n- Runs in `PersistentPreRun` for direct mode only\n- Skipped for: import, delete, sync --dry-run commands\n\n## Proposed Solution\n\nAdd lightweight hash-based staleness check to all read operations:\n\n### Implementation Points:\n1. **Before ANY database read** (list, show, search, ready, etc.):\n ```go\n func ensureDatabaseFresh(ctx context.Context) error {\n // Get stored import hash from DB\n storedHash, _ := store.GetMetadata(ctx, \"last_import_hash\")\n \n // Compute current JSONL hash\n currentHash := computeJSONLHash(findJSONLPath())\n \n if currentHash != storedHash {\n if autoImportEnabled {\n // Try auto-import\n autoImportIfNewer()\n // Re-check - fail if still stale\n } else {\n return fmt.Errorf(\"database out of sync with JSONL. Run 'bd import' or enable auto-import\")\n }\n }\n return nil\n }\n ```\n\n2. **Add to daemon RPC handlers** - daemon mode currently has NO staleness checking\n\n3. **Make check fast** - hash comparison is O(1) if JSONL hash is cached\n\n### Benefits:\n- Works in both daemon and direct mode\n- Minimal performance overhead (just hash comparison)\n- Catches all staleness cases\n- Clear error messages guide users to fix\n- Defense in depth - doesn't rely solely on auto-import\n\n### Alternatives Considered:\n- **mtime comparison**: Unreliable after git operations\n- **Block all reads when stale**: Too aggressive, breaks workflows \n- **Only check on mutations**: Current bug - reads return stale data\n- **Only rely on auto-import**: Fails in daemon mode and when disabled\n\n## Files to Modify:\n- `cmd/bd/list.go` - add check before SearchIssues\n- `cmd/bd/show.go` - add check before GetIssue\n- `cmd/bd/ready.go` - add check before GetReadyWork\n- `internal/rpc/server.go` - add check in daemon RPC handlers\n- Create `cmd/bd/staleness.go` - shared staleness check function","created_at":"2025-11-24T03:31:11Z"},{"id":14,"issue_id":"bd-2q6d","author":"stevey","text":"## Implementation Tasks\n\n### Phase 1: Core Infrastructure\n- [ ] Create `cmd/bd/staleness.go` with `ensureDatabaseFresh()` function\n- [ ] Add unit tests for staleness detection\n- [ ] Handle edge cases (missing JSONL, missing hash, etc.)\n\n### Phase 2: Direct Mode Read Commands\n- [ ] Add check to `cmd/bd/list.go`\n- [ ] Add check to `cmd/bd/show.go`\n- [ ] Add check to `cmd/bd/ready.go`\n- [ ] Add check to `cmd/bd/blocked.go`\n- [ ] Add check to `cmd/bd/stale.go`\n- [ ] Integration tests for direct mode\n\n### Phase 3: Daemon Mode\n- [ ] Add staleness check to daemon RPC handlers in `internal/rpc/server.go`\n- [ ] Ensure daemon can access JSONL path\n- [ ] Integration tests for daemon mode\n\n### Phase 4: Polish\n- [ ] Performance testing (check should be \u003c10ms)\n- [ ] Error message clarity\n- [ ] Documentation updates","created_at":"2025-11-24T03:31:11Z"}]} {"id":"bd-379","content_hash":"d1edf5009291680270e9bad61ef0d6e80fe1e24fa90f71fc80748a8bd52b32d2","title":"Implement `bd setup cursor` for Cursor IDE integration","description":"Create a `bd setup cursor` command that integrates Beads workflow into Cursor IDE via .cursorrules file. Unlike Claude Code (which has hooks), Cursor uses a static rules file to provide context to its AI.","design":"## Implementation\n\nCreate `cursor` subcommand in `cmd/bd/setup.go` that manages `.cursorrules` integration:\n\n### Command Interface\n```bash\nbd setup cursor # Install/update Cursor integration\nbd setup cursor --check # Verify .cursorrules has bd section\nbd setup cursor --remove # Remove bd section from .cursorrules\n```\n\n### Behavior\n\n**If `.cursorrules` doesn't exist:**\n- Create new file with complete bd rules template\n- Mark sections for easy identification\n\n**If `.cursorrules` exists:**\n- Check if bd section already exists (look for marker comments)\n- If not exists: append bd section\n- If exists: update in place (preserve user customizations outside bd section)\n- Backup original with `.cursorrules.backup` suffix\n\n### .cursorrules Template\n\n```markdown\n# Beads Issue Tracking\n# Auto-generated by 'bd setup cursor' - do not remove these markers\n# BEGIN BEADS INTEGRATION\n\nThis project uses [Beads (bd)](https://github.com/steveyegge/beads) for issue tracking.\n\n## Core Rules\n- Track ALL work in bd (never use markdown TODOs or comment-based task lists)\n- Use `bd ready` to find available work\n- Use `bd create` to track new issues/tasks/bugs\n- Use `bd sync` at end of session to sync with git remote\n- Git hooks auto-sync on commit/merge\n\n## Quick Reference\n```bash\nbd prime # Load complete workflow context\nbd ready # Show issues ready to work (no blockers)\nbd list --status=open # List all open issues\nbd create --title=\"...\" --type=task # Create new issue\nbd update \u003cid\u003e --status=in_progress # Claim work\nbd close \u003cid\u003e # Mark complete\nbd dep \u003cfrom\u003e \u003cto\u003e # Add dependency (from blocks to)\nbd sync # Sync with git remote\n```\n\n## Workflow\n1. Check for ready work: `bd ready`\n2. Claim an issue: `bd update \u003cid\u003e --status=in_progress`\n3. Do the work\n4. Mark complete: `bd close \u003cid\u003e`\n5. Sync: `bd sync` (or let git hooks handle it)\n\n## Context Loading\nRun `bd prime` to get complete workflow documentation in AI-optimized format (~1-2k tokens).\n\nFor detailed docs: see AGENTS.md, QUICKSTART.md, or run `bd --help`\n\n# END BEADS INTEGRATION\n```\n\n### Detection Logic\n\n```go\nfunc setupCursor() error {\n cursorRulesPath := \".cursorrules\"\n \n // Check if file exists\n content, err := os.ReadFile(cursorRulesPath)\n if err != nil {\n if os.IsNotExist(err) {\n // Create new file\n return createCursorRules(cursorRulesPath)\n }\n return err\n }\n \n // Check if bd section exists\n if hasBeadsSection(string(content)) {\n // Update existing section\n return updateBeadsSection(cursorRulesPath, string(content))\n } else {\n // Append new section\n return appendBeadsSection(cursorRulesPath, string(content))\n }\n}\n\nfunc hasBeadsSection(content string) bool {\n return strings.Contains(content, \"BEGIN BEADS INTEGRATION\")\n}\n```\n\n## Files\n- `cmd/bd/setup.go` - Add cursor subcommand\n- `cmd/bd/setup_cursor.go` - Cursor-specific logic\n- `cmd/bd/setup_cursor_test.go` - Tests\n- Template stored as Go string constant\n\n## Differences from Claude Setup\n\n| Aspect | Claude | Cursor |\n|--------|--------|--------|\n| **Integration file** | `.claude/commands/`, `.claude/hooks/` | `.cursorrules` |\n| **Auto-refresh** | Hooks call `bd prime` | Static rules (manual refresh) |\n| **Setup complexity** | Multiple files | Single file |\n| **Update frequency** | Dynamic (hooks) | Static (updated via `bd setup cursor`) |","acceptance_criteria":"- `bd setup cursor` creates/updates .cursorrules\n- Idempotent (safe to run multiple times)\n- Preserves non-bd content in .cursorrules\n- Backs up existing .cursorrules before modifying\n- `bd setup cursor --check` verifies integration\n- Markers allow updating bd section without affecting user content\n- Unit tests for template insertion/update logic\n- Documentation in AGENTS.md mentions Cursor setup","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-11T23:32:22.170083-08:00","updated_at":"2025-11-11T23:32:22.170083-08:00","source_repo":"."} {"id":"bd-3852","content_hash":"bc2640e4d1c60e0b7a7c3b6d49cb05292f50facb5d4ea3887ba8c414aa7ffef3","title":"Add orphan detection migration","description":"Create migration to detect orphaned children in existing databases. Query: SELECT id FROM issues WHERE id LIKE '%.%' AND substr(id, 1, instr(id || '.', '.') - 1) NOT IN (SELECT id FROM issues). Log results, let user decide action (delete orphans or convert to top-level).","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-04T12:32:30.727044-08:00","updated_at":"2025-11-04T12:32:30.727044-08:00","source_repo":"."} {"id":"bd-39o","content_hash":"36d58121cc9218718d262a1991ee84695af722d2823cf9c8415c2dfdd44fb390","title":"Rename last_import_hash metadata key to jsonl_content_hash","description":"The metadata key 'last_import_hash' is misleading because it's updated on both import AND export (sync.go:614, import.go:320).\n\nBetter names:\n- jsonl_content_hash (more accurate)\n- last_sync_hash (clearer intent)\n\nThis is a breaking change requiring migration of existing metadata values.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T21:31:07.568739-05:00","updated_at":"2025-11-20T21:31:07.568739-05:00","source_repo":"."} @@ -21,7 +21,7 @@ {"id":"bd-5ibn","content_hash":"3e651d081ea1dec7e5e30aaa2f9f521f3b9eaff7832d0dd55e5e6f89525f6b94","title":"Latency test 1","description":"","notes":"Resetting stale in_progress status from old executor run (yesterday)","status":"open","priority":3,"issue_type":"task","created_at":"2025-11-20T12:16:30.703754-05:00","updated_at":"2025-11-21T11:28:26.860082-05:00","source_repo":"."} {"id":"bd-736d","content_hash":"4743b1f41ff07fee3daa63240f0d5f7ac3f876e928b22c4ce0bee2cdf544e53a","title":"Refactor path canonicalization into helper function","description":"The path canonicalization logic (filepath.Abs + EvalSymlinks) is duplicated in 3 places:\n- beads.go:131-137 (BEADS_DIR handling)\n- cmd/bd/main.go:446-451 (--no-db cleanup)\n- cmd/bd/nodb.go:26-31 (--no-db initialization)\n\nRefactoring suggestion:\nExtract to a helper function like:\n func canonicalizePath(path string) string\n\nThis would:\n- Reduce code duplication\n- Make the logic easier to maintain\n- Ensure consistent behavior across all path handling\n\nRelated to bd-e16b implementation.","status":"open","priority":3,"issue_type":"chore","created_at":"2025-11-02T18:33:47.727443-08:00","updated_at":"2025-11-02T18:33:47.727443-08:00","source_repo":"."} {"id":"bd-77gm","content_hash":"b227320f0cf0c889a1e0d617922c572a48eee563c9afb1662b44a22e183c0c80","title":"Import reports misleading '0 created, 0 updated' when actually importing all issues","description":"When running 'bd import' on a fresh database (no existing issues), the command reports 'Import complete: 0 created, 0 updated' even though it successfully imported all issues from the JSONL file.\n\n**Steps to reproduce:**\n1. Delete .beads/beads.db\n2. Run: bd import .beads/issues.jsonl\n3. Observe output: 'Import complete: 0 created, 0 updated'\n4. Run: bd list\n5. Confirm: All issues are actually present in the database\n\n**Expected behavior:**\nReport the actual number of issues imported, e.g., 'Import complete: 523 created, 0 updated'\n\n**Actual behavior:**\n'Import complete: 0 created, 0 updated' (misleading - makes user think import failed)\n\n**Impact:**\n- Users think import failed when it succeeded\n- Confusing during database sync operations (e.g., after git pull)\n- Makes debugging harder (can't tell if import actually worked)\n\n**Context:**\nDiscovered during VC session when syncing database after git pull. The misleading message caused confusion about whether the database was properly synced with the canonical JSONL file.","acceptance_criteria":"- Import command reports accurate count of created/updated issues\n- Fresh database import shows 'N created' where N is the actual number\n- Update operations show 'N updated' where N is the actual number changed\n- Message clearly indicates success vs failure","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-09T16:20:13.191156-08:00","updated_at":"2025-11-09T16:20:13.191156-08:00","source_repo":"."} -{"id":"bd-7yg","content_hash":"a421df3d78f39edb93e421f18e042ad113f6d26c91439d1f732d3df7c80eee62","title":"Git merge driver uses invalid placeholders (%L, %R instead of %A, %B)","description":"## Problem\n\nThe beads git merge driver is configured with invalid Git placeholders:\n\n```\ngit config merge.beads.driver \"bd merge %A %O %L %R\"\n```\n\nGit doesn't recognize `%L` or `%R` as valid merge driver placeholders. The valid placeholders are:\n- `%O` = base (common ancestor)\n- `%A` = current version (ours)\n- `%B` = other version (theirs)\n\n## Impact\n\n- Affects ALL users when they have `.beads/beads.jsonl` merge conflicts\n- Automatic JSONL merge fails with error: \"error reading left file: failed to open file: open 7: no such file or directory\"\n- Users must manually resolve conflicts instead of getting automatic merge\n\n## Root Cause\n\nThe `bd init` command (or wherever the merge driver is configured) is using non-standard placeholders. When Git encounters `%L` and `%R`, it either passes them literally or interprets them incorrectly.\n\n## Fix\n\nUpdate the merge driver configuration to:\n```\ngit config merge.beads.driver \"bd merge %A %O %A %B\"\n```\n\nWhere:\n- 1st `%A` = output file (current file, will be overwritten)\n- `%O` = base (common ancestor)\n- 2nd `%A` = left/current version\n- `%B` = right/other version\n\n## Action Items\n\n1. Fix `bd init` (or equivalent setup command) to use correct placeholders\n2. Add migration/warning for existing users with misconfigured merge driver\n3. Update documentation with correct merge driver setup\n4. Consider adding validation when `bd init` is run","status":"open","priority":1,"issue_type":"bug","created_at":"2025-11-21T19:51:55.747608-05:00","updated_at":"2025-11-21T19:51:55.747608-05:00","source_repo":"."} +{"id":"bd-7yg","content_hash":"a421df3d78f39edb93e421f18e042ad113f6d26c91439d1f732d3df7c80eee62","title":"Git merge driver uses invalid placeholders (%L, %R instead of %A, %B)","description":"## Problem\n\nThe beads git merge driver is configured with invalid Git placeholders:\n\n```\ngit config merge.beads.driver \"bd merge %A %O %L %R\"\n```\n\nGit doesn't recognize `%L` or `%R` as valid merge driver placeholders. The valid placeholders are:\n- `%O` = base (common ancestor)\n- `%A` = current version (ours)\n- `%B` = other version (theirs)\n\n## Impact\n\n- Affects ALL users when they have `.beads/beads.jsonl` merge conflicts\n- Automatic JSONL merge fails with error: \"error reading left file: failed to open file: open 7: no such file or directory\"\n- Users must manually resolve conflicts instead of getting automatic merge\n\n## Root Cause\n\nThe `bd init` command (or wherever the merge driver is configured) is using non-standard placeholders. When Git encounters `%L` and `%R`, it either passes them literally or interprets them incorrectly.\n\n## Fix\n\nUpdate the merge driver configuration to:\n```\ngit config merge.beads.driver \"bd merge %A %O %A %B\"\n```\n\nWhere:\n- 1st `%A` = output file (current file, will be overwritten)\n- `%O` = base (common ancestor)\n- 2nd `%A` = left/current version\n- `%B` = right/other version\n\n## Action Items\n\n1. Fix `bd init` (or equivalent setup command) to use correct placeholders\n2. Add migration/warning for existing users with misconfigured merge driver\n3. Update documentation with correct merge driver setup\n4. Consider adding validation when `bd init` is run","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-11-21T19:51:55.747608-05:00","updated_at":"2025-11-23T20:29:04.102764-08:00","closed_at":"2025-11-23T20:29:04.102764-08:00","source_repo":"."} {"id":"bd-81a","content_hash":"0f43da9e36bc3c5db20f302b82021377685a9425f519a36bab5a2cf1b85f13d8","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.","design":"## API Design\n\nAdd to `cmd/bd/tips.go`:\n\n```go\n// InjectTip adds a dynamic tip to the registry at runtime\nfunc InjectTip(id, message string, priority int, frequency time.Duration, probability float64, condition func() bool) {\n tipsMutex.Lock()\n defer tipsMutex.Unlock()\n \n tips = append(tips, Tip{\n ID: id,\n Condition: condition,\n Message: message,\n Frequency: frequency,\n Priority: priority,\n Probability: probability,\n })\n}\n\n// RemoveTip removes a tip from the registry\nfunc RemoveTip(id string) {\n tipsMutex.Lock()\n defer tipsMutex.Unlock()\n \n for i, tip := range tips {\n if tip.ID == id {\n tips = append(tips[:i], tips[i+1:]...)\n return\n }\n }\n}\n```\n\n## Use Cases\n\n### Example 1: Critical Security Update\n```go\n// In bd version check code\nif criticalSecurityUpdate {\n InjectTip(\n \"security_update\",\n fmt.Sprintf(\"CRITICAL: Security update available (bd %s). Update immediately!\", remoteVersion),\n 100, // Highest priority\n 0, // No frequency limit\n 1.0, // Always show (100% probability)\n func() bool { return true },\n )\n}\n```\n\n### Example 2: New Version Available\n```go\n// In bd version check code\nif remoteVersion \u003e currentVersion {\n InjectTip(\n \"upgrade_available\",\n fmt.Sprintf(\"New bd version %s available (you have %s). Run: go install github.com/steveyegge/beads/cmd/bd@latest\", remoteVersion, currentVersion),\n 90, // High priority\n 7 * 24 * time.Hour, // Weekly\n 0.8, // 80% probability (frequent but not always)\n func() bool { return true },\n )\n}\n```\n\n### Example 3: Large Issue Count Suggestion\n```go\n// In bd list code\nif issueCount \u003e 100 {\n InjectTip(\n \"use_filters\",\n \"You have many issues. Use filters: 'bd list --status=open --priority=1'\",\n 50, // Medium priority\n 14 * 24 * time.Hour, // Bi-weekly\n 0.4, // 40% probability (occasional suggestion)\n func() bool { return true },\n )\n}\n```\n\n### Example 4: No Dependencies Used\n```go\n// After analyzing project\nif hasIssues \u0026\u0026 noDependenciesCreated {\n InjectTip(\n \"try_dependencies\",\n \"Try using dependencies: 'bd dep \u003cissue\u003e \u003cblocks-issue\u003e' to track blockers\",\n 30, // Low priority\n 30 * 24 * time.Hour, // Monthly\n 0.3, // 30% probability (low-key suggestion)\n func() bool { return true },\n )\n}\n```\n\n## Probability Guidelines\n\n- **1.0 (100%)**: Critical security, breaking changes, data loss prevention\n- **0.7-0.9 (70-90%)**: Important updates, major new features\n- **0.4-0.6 (40-60%)**: General tips, workflow improvements, feature discovery\n- **0.1-0.3 (10-30%)**: Nice-to-know features, advanced tips, optional optimizations\n\n## Thread Safety\n- Use mutex to protect tip registry\n- Safe for concurrent command execution\n- Deterministic testing via BEADS_TIP_SEED env var","acceptance_criteria":"- InjectTip() API exists and is documented\n- RemoveTip() API exists\n- Thread-safe with mutex protection\n- Can inject tips from any command\n- Injected tips participate in priority/frequency rotation\n- Unit tests for injection API\n- Example usage in code comments","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-8wa","content_hash":"0cf757ff7ef5393901a61cfdfaa2d6f7ac627eaa1c62b63165050f21d9b5b390","title":"Code Review Sweep: thorough","description":"Perform thorough code review sweep based on accumulated activity.\n\n**AI Reasoning:**\nSignificant code volume added (150,273 lines) across multiple critical areas, including cmd/bd, internal/storage/sqlite, and internal/rpc. High file change count (616) indicates substantial refactoring or new functionality. The metrics suggest potential for subtle architectural or implementation issues that warrant review.\n\n**Scope:** thorough\n**Target Areas:** cmd/bd, internal/storage/sqlite, internal/rpc\n**Estimated Files:** 12\n**Estimated Cost:** $5\n\n**Task:**\nReview files for non-obvious issues that agents miss during focused work:\n- Inefficiencies (algorithmic, resource usage)\n- Subtle bugs (race conditions, off-by-one, copy-paste)\n- Poor patterns (coupling, complexity, duplication)\n- Missing best practices (error handling, docs, tests)\n- Unnamed anti-patterns\n\nFile discovered issues with detailed reasoning and suggestions.","acceptance_criteria":"- Reviewed target files for code quality issues\n- Filed discovered issues with detailed reasoning\n- Completed sweep according to scope criteria","status":"open","priority":1,"issue_type":"task","created_at":"2025-11-21T10:25:37.081296-05:00","updated_at":"2025-11-21T10:25:37.081296-05:00","source_repo":".","labels":["code-review-sweep","review-area:cmd/bd","review-area:internal/rpc","review-area:internal/storage/sqlite"]} {"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":"open","priority":2,"issue_type":"epic","created_at":"2025-11-11T23:31:12.119012-08:00","updated_at":"2025-11-12T00:11:07.743189-08:00","source_repo":"."} @@ -59,10 +59,10 @@ {"id":"bd-m0w","content_hash":"e8641e225f1d4cf13fbd97c4a83046e3597df180d3ee134125e4a35abc6941cd","title":"Add test coverage for internal/validation package","description":"","design":"Validation package has 1 test file. Critical for data integrity. Target: 80% coverage","acceptance_criteria":"- At least 4 test files\n- Package coverage \u003e= 80%\n- Tests cover all validation rules","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T21:21:24.129559-05:00","updated_at":"2025-11-20T21:21:24.129559-05:00","source_repo":".","dependencies":[{"issue_id":"bd-m0w","depends_on_id":"bd-ge7","type":"blocks","created_at":"2025-11-20T21:21:31.350477-05:00","created_by":"daemon"}]} {"id":"bd-m7ge","content_hash":"bb08f2bcbbdd2e392733d92bff2e46a51000337ac019d306dd6a2983916873c4","title":"Add .beads/README.md during 'bd init' for project documentation and promotion","description":"When 'bd init' is run, automatically generate a .beads/README.md file that:\n\n1. Briefly explains what Beads is (AI-native issue tracking that lives in your repo)\n2. Links to the main repository: https://github.com/steveyegge/beads\n3. Provides a quick reference of essential commands:\n - bd create: Create new issues\n - bd list: View all issues\n - bd update: Modify issue status/details\n - bd show: View issue details\n - bd sync: Sync with git remote\n4. Highlights key benefits for AI coding agents and developers\n5. Encourages developers to try it out\n\nThe README should be enthusiastic and compelling to get open source contributors excited about using Beads for their AI-assisted development workflows.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-11-16T22:32:50.478681-08:00","updated_at":"2025-11-16T22:32:58.492868-08:00","source_repo":"."} {"id":"bd-mnap","content_hash":"c15d3c631656fe6d21291f127fc545af93e712b5f3f94cce028513fb743a4fdb","title":"Investigate performance issues in VS Code Copilot (Windows)","description":"Beads unusable in Windows 11 VS Code Copilot chat with Sonnet 4.5.\nSummary event happens every 3-4 turns, taking 3 minutes.\nCopilot summarizes after ~125k tokens despite model supporting 1M.\nLarge context size of beads might be triggering aggressive summarization.\nNeed workaround or optimization for context size.\n","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T18:56:30.124918-05:00","updated_at":"2025-11-20T18:56:30.124918-05:00","source_repo":"."} -{"id":"bd-n4td","content_hash":"1a5222748ad9badd0cdfdcfbe831f96c532deeb41909f9729e111dcbaa119d0d","title":"Add warning when staleness check errors","description":"## Problem\n\nWhen ensureDatabaseFresh() calls CheckStaleness() and it errors (corrupted metadata, permission issues, etc.), we silently proceed with potentially stale data.\n\n**Location:** cmd/bd/staleness.go:27-32\n\n**Scenarios:**\n- Corrupted metadata table\n- Database locked by another process \n- Permission issues reading JSONL file\n- Invalid last_import_time format in DB\n\n## Current Code\n\n```go\nisStale, err := autoimport.CheckStaleness(ctx, store, dbPath)\nif err \\!= nil {\n // If we can't determine staleness, allow operation to proceed\n // (better to show potentially stale data than block user)\n return nil\n}\n```\n\n## Fix\n\n```go\nisStale, err := autoimport.CheckStaleness(ctx, store, dbPath)\nif err \\!= nil {\n fmt.Fprintf(os.Stderr, \"Warning: Could not verify database freshness: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Proceeding anyway. Data may be stale.\\n\\n\")\n return nil\n}\n```\n\n## Impact\nMedium - users should know when staleness check fails\n\n## Effort\nEasy - 5 minutes","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-20T20:16:34.889997-05:00","updated_at":"2025-11-20T20:16:34.889997-05:00","source_repo":".","dependencies":[{"issue_id":"bd-n4td","depends_on_id":"bd-2q6d","type":"blocks","created_at":"2025-11-20T20:18:20.154723-05:00","created_by":"stevey"}]} +{"id":"bd-n4td","content_hash":"287dfe2344c1da060eec358fa6b15271511704cf8bf33d8a08cdbd0a7ccb14de","title":"Add warning when staleness check errors","description":"## Problem\n\nWhen ensureDatabaseFresh() calls CheckStaleness() and it errors (corrupted metadata, permission issues, etc.), we silently proceed with potentially stale data.\n\n**Location:** cmd/bd/staleness.go:27-32\n\n**Scenarios:**\n- Corrupted metadata table\n- Database locked by another process \n- Permission issues reading JSONL file\n- Invalid last_import_time format in DB\n\n## Current Code\n\n```go\nisStale, err := autoimport.CheckStaleness(ctx, store, dbPath)\nif err \\!= nil {\n // If we can't determine staleness, allow operation to proceed\n // (better to show potentially stale data than block user)\n return nil\n}\n```\n\n## Fix\n\n```go\nisStale, err := autoimport.CheckStaleness(ctx, store, dbPath)\nif err \\!= nil {\n fmt.Fprintf(os.Stderr, \"Warning: Could not verify database freshness: %v\\n\", err)\n fmt.Fprintf(os.Stderr, \"Proceeding anyway. Data may be stale.\\n\\n\")\n return nil\n}\n```\n\n## Impact\nMedium - users should know when staleness check fails\n\n## Effort\nEasy - 5 minutes","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-20T20:16:34.889997-05:00","updated_at":"2025-11-23T20:36:07.427563-08:00","closed_at":"2025-11-23T20:36:07.427563-08:00","source_repo":".","dependencies":[{"issue_id":"bd-n4td","depends_on_id":"bd-2q6d","type":"blocks","created_at":"2025-11-20T20:18:20.154723-05:00","created_by":"stevey"}]} {"id":"bd-nq41","content_hash":"33f9cfe6a0ef5200dcd5016317b43b1568ff9dc7303537d956bdab02029f6c63","title":"Fix Homebrew warning about Ruby file location","description":"Homebrew warning: Found Ruby file outside steveyegge/beads tap formula directory.\nWarning points to: /opt/homebrew/Library/Taps/steveyegge/homebrew-beads/bd.rb\nIt should likely be inside a Formula/ directory or similar structure expected by Homebrew taps.\n","status":"open","priority":2,"issue_type":"chore","created_at":"2025-11-20T18:56:21.226579-05:00","updated_at":"2025-11-20T18:56:21.226579-05:00","source_repo":"."} {"id":"bd-nxgk","content_hash":"b1124b39715075cd321a6996f662adf9af49871524a97890703819caf87f7da1","title":"Agent upgrade awareness system","description":"Make it easy for AI agents to discover and adapt to bd upgrades without manual intervention.\n\n## Problem\nWhen bd is upgraded (happens weekly), agents need to:\n1. Discover what changed\n2. Update their workflows/instructions\n3. Keep git hooks in sync\n4. Know which new features to adopt\n\nCurrently this requires manual prompting or re-running bd onboard, which is unreliable.\n\n## Solution Layers\n1. Documentation improvements (immediate)\n2. Startup hook snippet for detection (immediate, zero bd code)\n3. Built-in version tracking in bd (short-term)\n4. Separated canonical BD_GUIDE.md (long-term architectural)\n\n## Success Criteria\n- Agents automatically detect bd upgrades at session start\n- Agents see what changed without re-reading all docs\n- Git hooks stay in sync with bd version\n- bd-specific instructions separated from project instructions\n\n## Related Discussion\nGitHub Discussion #239: 'Upgrading beads: how to let the Agent know'\n","status":"open","priority":2,"issue_type":"epic","created_at":"2025-11-23T16:21:14.431233-08:00","updated_at":"2025-11-23T16:21:14.431233-08:00","source_repo":"."} -{"id":"bd-o4qy","content_hash":"28304d9e414cbc475b89dc2d1474f110d8f9d90d50fdbdca8f15961db540806b","title":"Improve CheckStaleness error handling","description":"## Problem\n\nCheckStaleness returns 'false' (not stale) for multiple error conditions instead of returning errors. This masks problems.\n\n**Location:** internal/autoimport/autoimport.go:253-285\n\n## Edge Cases That Return False\n\n1. **Invalid last_import_time format** (line 259-262)\n2. **No JSONL file found** (line 267-277) \n3. **JSONL stat fails** (line 279-282)\n\n## Fix\n\nReturn errors for abnormal conditions:\n\n```go\nlastImportTime, err := time.Parse(time.RFC3339, lastImportStr)\nif err != nil {\n return false, fmt.Errorf(\"corrupted last_import_time: %w\", err)\n}\n\nif jsonlPath == \"\" {\n return false, fmt.Errorf(\"no JSONL file found\")\n}\n\nstat, err := os.Stat(jsonlPath)\nif err != nil {\n return false, fmt.Errorf(\"cannot stat JSONL: %w\", err)\n}\n```\n\n## Impact\nMedium - edge cases are rare but should be handled\n\n## Effort \n30 minutes - requires updating callers in RPC server","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-20T20:17:27.606219-05:00","updated_at":"2025-11-20T20:17:27.606219-05:00","source_repo":".","dependencies":[{"issue_id":"bd-o4qy","depends_on_id":"bd-2q6d","type":"blocks","created_at":"2025-11-20T20:18:26.81065-05:00","created_by":"stevey"}]} +{"id":"bd-o4qy","content_hash":"5afa95dc957aaa421e2e1ef25d7f0097dee97d5b03a38f3ea3eff51209df5570","title":"Improve CheckStaleness error handling","description":"## Problem\n\nCheckStaleness returns 'false' (not stale) for multiple error conditions instead of returning errors. This masks problems.\n\n**Location:** internal/autoimport/autoimport.go:253-285\n\n## Edge Cases That Return False\n\n1. **Invalid last_import_time format** (line 259-262)\n2. **No JSONL file found** (line 267-277) \n3. **JSONL stat fails** (line 279-282)\n\n## Fix\n\nReturn errors for abnormal conditions:\n\n```go\nlastImportTime, err := time.Parse(time.RFC3339, lastImportStr)\nif err != nil {\n return false, fmt.Errorf(\"corrupted last_import_time: %w\", err)\n}\n\nif jsonlPath == \"\" {\n return false, fmt.Errorf(\"no JSONL file found\")\n}\n\nstat, err := os.Stat(jsonlPath)\nif err != nil {\n return false, fmt.Errorf(\"cannot stat JSONL: %w\", err)\n}\n```\n\n## Impact\nMedium - edge cases are rare but should be handled\n\n## Effort \n30 minutes - requires updating callers in RPC server","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-20T20:17:27.606219-05:00","updated_at":"2025-11-23T20:35:41.214077-08:00","closed_at":"2025-11-23T20:35:41.214077-08:00","source_repo":".","dependencies":[{"issue_id":"bd-o4qy","depends_on_id":"bd-2q6d","type":"blocks","created_at":"2025-11-20T20:18:26.81065-05:00","created_by":"stevey"}]} {"id":"bd-o78","content_hash":"0d61c7a8e687c16c262db4ba4e6c7f63861fbeb524ec014000c68a0552df7965","title":"Enhance `bd doctor` to verify Claude Code integration","description":"Add checks to `bd doctor` that verify Claude Code integration is properly set up when .claude/ directory or Claude environment is detected.","design":"## Checks to Add\n\n### 1. Claude Environment Detection\n```go\nif isClaudeDetected() {\n fmt.Println(\"✓ Claude Code environment detected\")\n \n // Check what's installed\n hasMCP := isMCPServerInstalled()\n hasHooks := isClaudeSetupComplete()\n \n if hasMCP \u0026\u0026 hasHooks {\n fmt.Println(\"✓ MCP server installed\")\n fmt.Println(\"✓ Claude hooks installed (provides workflow reminders)\")\n } else if !hasMCP \u0026\u0026 hasHooks {\n fmt.Println(\"✓ Claude hooks installed (provides CLI reference)\")\n fmt.Println(\" Note: MCP server not detected (using CLI mode)\")\n } else if hasMCP \u0026\u0026 !hasHooks {\n fmt.Println(\"✓ MCP server installed\")\n fmt.Println(\"⚠ Claude hooks not installed\")\n fmt.Println(\" Hooks prevent agent from forgetting bd workflow after compaction\")\n fmt.Println(\" Run: bd setup claude\")\n } else {\n fmt.Println(\"⚠ Claude integration not set up\")\n fmt.Println(\" Run: bd setup claude\")\n // TODO (future): Recommend CLI approach once proven in production\n // fmt.Println(\" Tip: CLI mode (without MCP) uses fewer tokens\")\n }\n}\n\nfunc isMCPServerInstalled() bool {\n // Check ~/.claude/settings.json for beads MCP server\n home, _ := os.UserHomeDir()\n settingsPath := filepath.Join(home, \".claude/settings.json\")\n \n data, err := os.ReadFile(settingsPath)\n if err != nil {\n return false\n }\n \n var settings map[string]interface{}\n if err := json.Unmarshal(data, \u0026settings); err != nil {\n return false\n }\n \n // Check mcpServers section for beads\n mcpServers, ok := settings[\"mcpServers\"].(map[string]interface{})\n if !ok {\n return false\n }\n \n // Look for beads server (any key containing \"beads\")\n for key := range mcpServers {\n if strings.Contains(strings.ToLower(key), \"beads\") {\n return true\n }\n }\n \n return false\n}\n```\n\n### 2. Hook Installation Verification (MCP-Aware)\n\n```go\nfunc checkClaudeHooks() {\n home, _ := os.UserHomeDir()\n globalSettings := filepath.Join(home, \".claude/settings.json\")\n projectSettings := \".claude/settings.local.json\"\n \n globalHooks := hasBeadsHooks(globalSettings)\n projectHooks := hasBeadsHooks(projectSettings)\n \n if globalHooks {\n fmt.Println(\"✓ Global hooks installed\")\n } else if projectHooks {\n fmt.Println(\"✓ Project hooks installed\")\n } else {\n fmt.Println(\"⚠ No hooks installed\")\n fmt.Println(\" Run: bd setup claude\")\n return\n }\n \n // Check if hooks will work\n if !commandExists(\"bd\") {\n fmt.Println(\"⚠ 'bd' command not in PATH\")\n fmt.Println(\" Hooks won't work - ensure bd is installed globally\")\n }\n}\n\nfunc hasBeadsHooks(settingsPath string) bool {\n data, err := os.ReadFile(settingsPath)\n if err != nil {\n return false\n }\n \n var settings map[string]interface{}\n if err := json.Unmarshal(data, \u0026settings); err != nil {\n return false\n }\n \n hooks, ok := settings[\"hooks\"].(map[string]interface{})\n if !ok {\n return false\n }\n \n // Check SessionStart and PreCompact for \"bd prime\"\n for _, event := range []string{\"SessionStart\", \"PreCompact\"} {\n eventHooks, ok := hooks[event].([]interface{})\n if !ok {\n continue\n }\n \n for _, hook := range eventHooks {\n hookMap, _ := hook.(map[string]interface{})\n commands, _ := hookMap[\"hooks\"].([]interface{})\n for _, cmd := range commands {\n cmdMap, _ := cmd.(map[string]interface{})\n if cmdMap[\"command\"] == \"bd prime\" {\n return true\n }\n }\n }\n }\n \n return false\n}\n```\n\n### 3. AGENTS.md/CLAUDE.md Reference Check\n```go\n// Check if documentation references bd prime\nagentsContent := readFileIfExists(\"AGENTS.md\")\nclaudeContent := readFileIfExists(\"CLAUDE.md\")\n\nif strings.Contains(agentsContent, \"bd prime\") || strings.Contains(claudeContent, \"bd prime\") {\n // Verify bd prime command exists in current version\n if !commandExists(\"prime\") {\n fmt.Println(\"⚠ Documentation references 'bd prime' but command not found\")\n fmt.Println(\" Upgrade bd or remove references\")\n } else {\n fmt.Println(\"✓ Documentation references match installed features\")\n }\n}\n```\n\n### 4. Context Priming Test\n```go\n// Verify bd prime actually works\ncmd := exec.Command(\"bd\", \"prime\")\noutput, err := cmd.CombinedOutput()\n\nif err != nil {\n fmt.Println(\"⚠ 'bd prime' failed to execute\")\n fmt.Println(\" Error:\", err)\n} else if len(output) == 0 {\n fmt.Println(\"⚠ 'bd prime' produced no output\")\n fmt.Println(\" Expected workflow context markdown\")\n} else {\n // Check if output adapts to MCP mode\n hasMCP := isMCPServerInstalled()\n outputStr := string(output)\n \n if hasMCP \u0026\u0026 strings.Contains(outputStr, \"mcp__plugin_beads_beads__\") {\n fmt.Println(\"✓ bd prime detected MCP mode (workflow reminders)\")\n } else if !hasMCP \u0026\u0026 strings.Contains(outputStr, \"bd ready\") {\n fmt.Println(\"✓ bd prime using CLI mode (full command reference)\")\n } else {\n fmt.Println(\"⚠ bd prime output may not be adapting to environment\")\n }\n}\n```\n\n## Output Format Examples\n\n### With MCP and Hooks\n```\nbd doctor\n\nDatabase:\n✓ Database found at .beads/beads.db\n✓ Git hooks installed\n\nClaude Code Integration:\n✓ Claude Code environment detected\n✓ MCP server installed\n✓ Claude hooks installed (provides workflow reminders)\n✓ bd prime detected MCP mode (workflow reminders)\n✓ Documentation references match installed features\n\nSync Status:\n✓ No sync issues detected\n```\n\n### Without MCP, With Hooks\n```\nbd doctor\n\nDatabase:\n✓ Database found at .beads/beads.db\n✓ Git hooks installed\n\nClaude Code Integration:\n✓ Claude Code environment detected\n✓ Claude hooks installed (provides CLI reference)\n Note: MCP server not detected (using CLI mode)\n✓ bd prime using CLI mode (full command reference)\n\nSync Status:\n✓ No sync issues detected\n```\n\n### No Integration\n```\nbd doctor\n\nDatabase:\n✓ Database found at .beads/beads.db\n✓ Git hooks installed\n\nClaude Code Integration:\n✓ Claude Code environment detected\n⚠ Claude integration not set up\n Run: bd setup claude\n\nSync Status:\n✓ No sync issues detected\n```\n\n## Future Enhancement (Post-Production Validation)\n\nOnce CLI mode is proven in production, add recommendation:\n\n```go\nif isClaudeDetected() \u0026\u0026 !hasMCP \u0026\u0026 !hasHooks {\n fmt.Println(\"⚠ Claude integration not set up\")\n fmt.Println(\" Run: bd setup claude\")\n fmt.Println(\" Tip: CLI mode (without MCP) uses fewer tokens than MCP server\")\n fmt.Println(\" Both approaches work equally well - choose based on preference\")\n}\n```\n\nThis recommendation should only be added after CLI mode with `bd prime` is validated in real-world usage.","acceptance_criteria":"- bd doctor checks for Claude environment\n- Verifies hook installation if .claude/ exists\n- Checks AGENTS.md/CLAUDE.md for bd prime references\n- Detects version mismatches between docs and installed bd\n- Provides actionable suggestions (bd setup claude, upgrade)\n- Tests cover detection logic","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-11T23:30:05.782406-08:00","updated_at":"2025-11-12T00:12:07.717579-08:00","source_repo":".","dependencies":[{"issue_id":"bd-o78","depends_on_id":"bd-90v","type":"parent-child","created_at":"2025-11-11T23:31:27.886095-08:00","created_by":"daemon"}]} {"id":"bd-obdc","content_hash":"78569b1608b180b60f5bfaf25e0ae82a1a14ad9e88ba1601a9175310cb74b7e7","title":"Add 'bd doctor --rebuild-cache' command for cache recovery","description":"Add admin command to manually rebuild the blocked_issues_cache table for recovery scenarios.\n\n## Use cases\n\n1. **Cache corruption recovery**\n - If cache gets out of sync with actual dependencies\n - Manual rebuild as safety measure\n\n2. **Post-migration verification**\n - After database migrations that affect dependencies\n - Verify cache is correctly populated\n\n3. **Debugging**\n - Compare cache state with actual blocking calculations\n - Troubleshoot performance issues\n\n## Implementation\n\nAdd flag to bd doctor command:\n\n```bash\nbd doctor --rebuild-cache\n```\n\nShould:\n- Call `SQLiteStorage.invalidateBlockedCache()` directly\n- Print before/after cache statistics\n- Show timing information\n- Exit code 0 on success\n\nExample output:\n```\nRebuilding blocked_issues_cache...\nBefore: 15 blocked issues\nAfter: 15 blocked issues\nRebuilt in 12ms\n✓ Cache rebuild complete\n```\n\n## Files to modify\n\n- cmd/bd/doctor.go - add --rebuild-cache flag\n- internal/storage/sqlite/blocked_cache.go - maybe add public RebuildBlockedCache() method\n\n## Related\n\n- [deleted:bd-5qim]: GetReadyWork performance optimization\n- bd-13gm: Add cache validation tests","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-23T20:07:07.331501-08:00","updated_at":"2025-11-23T20:17:34.995485-08:00","source_repo":"."} {"id":"bd-ola6","content_hash":"79461888e8a7875bf3623b8db44ea004f73a2374daa52ae9cb3fc9d3ce5e6a8b","title":"Implement transaction retry logic for SQLITE_BUSY","description":"BEGIN IMMEDIATE fails immediately on SQLITE_BUSY instead of retrying with exponential backoff.\n\nLocation: internal/storage/sqlite/sqlite.go:223-225\n\nProblem:\n- Under concurrent write load, BEGIN IMMEDIATE can fail with SQLITE_BUSY\n- Current implementation fails immediately instead of retrying\n- Results in spurious failures under normal concurrent usage\n\nSolution: Implement exponential backoff retry:\n- Retry up to N times (e.g., 5)\n- Backoff: 10ms, 20ms, 40ms, 80ms, 160ms\n- Check for context cancellation between retries\n- Only retry on SQLITE_BUSY/database locked errors\n\nImpact: Spurious failures under concurrent write load\n\nEffort: 3 hours","status":"open","priority":1,"issue_type":"feature","created_at":"2025-11-16T14:51:31.247147-08:00","updated_at":"2025-11-16T14:51:31.247147-08:00","source_repo":"."} diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl new file mode 100644 index 00000000..e69de29b