Fixes GH#409 - Documentation inconsistently referred to beads.jsonl
as the canonical filename when issues.jsonl has been the default
since v0.25.1 (bd-6xd).
Updated files:
- docs/ARCHITECTURE.md
- docs/CLI_REFERENCE.md
- docs/PROTECTED_BRANCHES.md
- docs/ADVANCED.md
- docs/GIT_INTEGRATION.md
- docs/MULTI_REPO_AGENTS.md
- docs/MULTI_REPO_MIGRATION.md
- docs/TROUBLESHOOTING.md
- examples/*/README.md
- skills/beads/references/CLI_REFERENCE.md
Note: beads.jsonl is still supported for backward compatibility.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add comprehensive documentation for the blocked_issues_cache optimization
that improved GetReadyWork performance from 752ms to 29ms (25x speedup).
Documentation locations:
- blocked_cache.go: Detailed package comment covering architecture,
invalidation strategy, transaction safety, edge cases, and future
optimizations
- ready.go: Enhanced comment at query site explaining the optimization
and maintenance triggers
- ARCHITECTURE.md: New section with diagrams, blocking semantics,
performance characteristics, and testing instructions
Closes bd-1w6i
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Critical fixes to code review findings:
1. Remove global state access from flushToJSONLWithState
- FlushManager now has true single ownership of flush state
- No more race conditions from concurrent global state access
- flushToJSONLWithState trusts only the flushState parameter
- Legacy wrapper handles success detection via failure count
2. Fix shutdown timeout data loss risk
- Increased timeout from 5s → 30s to prevent data loss
- Added detailed comments explaining the timeout rationale
- Better error message indicates potential data loss scenario
Implementation details:
- New FlushManager uses event-driven single-owner pattern
- Channels eliminate shared mutable state (markDirtyCh, flushNowCh, etc.)
- Comprehensive race detector tests verify concurrency safety
- Backward compatible with existing tests via legacy code path
- ARCHITECTURE.md documents design principles and guarantees
Test results:
- All race detector tests pass (TestFlushManager*)
- Legacy API compatibility verified (TestMarkDirtyAndScheduleFlush*)
- No race conditions detected under concurrent load
Future improvements tracked as beads:
- bd-gdn: Add functional tests for flush correctness verification
- bd-5xt: Log errors from timer-triggered flushes
- bd-i00: Convert magic numbers to named constants
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
