beads/docs
Ryan ffe0dca2a3
feat(daemon): unify auto-sync config for simpler agent workflows (#904)
* feat(daemon): unify auto-sync config for simpler agent workflows

## Problem

Agents running `bd sync` at session end caused delays in the Claude Code
"event loop", slowing development. The daemon was already auto-exporting
DB→JSONL instantly, but auto-commit and auto-push weren't enabled by
default when sync-branch was configured - requiring manual `bd sync`.

Additionally, having three separate config options (auto-commit, auto-push,
auto-pull) was confusing and could get out of sync.

## Solution

Simplify to two intuitive sync modes:

1. **Read/Write Mode** (`daemon.auto-sync: true` or `BEADS_AUTO_SYNC=true`)
   - Enables auto-commit + auto-push + auto-pull
   - Full bidirectional sync - eliminates need for manual `bd sync`
   - Default when sync-branch is configured

2. **Read-Only Mode** (`daemon.auto-pull: true` or `BEADS_AUTO_PULL=true`)
   - Only receives updates from team
   - Does NOT auto-publish changes
   - Useful for experimental work or manual review before sharing

## Benefits

- **Faster agent workflows**: No more `bd sync` delays at session end
- **Simpler config**: Two modes instead of three separate toggles
- **Backward compatible**: Legacy auto_commit/auto_push settings still work
  (treated as auto-sync=true)
- **Adaptive `bd prime`**: Session close protocol adapts when daemon is
  auto-syncing (shows simplified 4-step git workflow, no `bd sync`)
- **Doctor warnings**: `bd doctor` warns about deprecated legacy config

## Changes

- cmd/bd/daemon.go: Add loadDaemonAutoSettings() with unified config logic
- cmd/bd/doctor.go: Add CheckLegacyDaemonConfig call
- cmd/bd/doctor/daemon.go: Add CheckDaemonAutoSync, CheckLegacyDaemonConfig
- cmd/bd/init_team.go: Use daemon.auto-sync in team wizard
- cmd/bd/prime.go: Detect daemon auto-sync, adapt session close protocol
- cmd/bd/prime_test.go: Add stubIsDaemonAutoSyncing for testing

* docs: add comprehensive daemon technical analysis

Add daemon-summary.md documenting the beads daemon architecture,
memory analysis (explaining the 30-35MB footprint), platform support
comparison, historical problems and fixes, and architectural guidance
for other projects implementing similar daemon patterns.

Key sections:
- Architecture deep dive with component diagrams
- Memory breakdown (SQLite WASM runtime is the main contributor)
- Platform support matrix (macOS/Linux full, Windows partial)
- Historical bugs and their fixes with reusable patterns
- Analysis of daemon usefulness without database (verdict: low value)
- Expert-reviewed improvement proposals (3 recommended, 3 skipped)
- Technical design patterns for other implementations

* feat: add cross-platform CI matrix and dual-mode test framework

Cross-Platform CI:
- Add Windows, macOS, Linux matrix to catch platform-specific bugs
- Linux: full tests with race detector and coverage
- macOS: full tests with race detector
- Windows: full tests without race detector (performance)
- Catches bugs like GH#880 (macOS path casing) and GH#387 (Windows daemon)

Dual-Mode Test Framework (cmd/bd/dual_mode_test.go):
- Runs tests in both direct mode and daemon mode
- Prevents recurring bug pattern (GH#719, GH#751, bd-fu83)
- Provides DualModeTestEnv with helper methods for common operations
- Includes 5 example tests demonstrating the pattern

Documentation:
- Add dual-mode testing section to CONTRIBUTING.md
- Document RunDualModeTest API and available helpers

Test Fixes:
- Fix sync_local_only_test.go gitPull/gitPush calls
- Add gate_no_daemon_test.go for beads-70c4 investigation

* fix(test): isolate TestFindBeadsDir tests with BEADS_DIR env var

The tests were finding the real project's .beads directory instead of
the temp directory because FindBeadsDir() walks up the directory tree.
Using BEADS_DIR env var provides proper test isolation.

* fix(test): stop daemon before running test suite guard

The test suite guard checks that tests don't modify the real repo's .beads
directory. However, a background daemon running auto-sync would touch
issues.jsonl during test execution, causing false positives.

Changes:
- Set BEADS_NO_DAEMON=1 to prevent daemon auto-start from tests
- Stop any running daemon for the repo before taking the "before" snapshot
- Uses exec to call `bd daemon --stop` to avoid import cycle issues

* chore: revert .beads/issues.jsonl to upstream/main

Per CONTRIBUTING.md, .beads/issues.jsonl should not be modified in PRs.
2026-01-06 12:52:19 -08:00
..
dev-notes docs: fix broken relative links across documentation 2025-12-16 00:46:08 -08:00
ADAPTIVE_IDS.md docs: fix broken relative links across documentation 2025-12-16 00:46:08 -08:00
ADVANCED.md docs: add Database Redirects section to ADVANCED.md (bd-8x43) 2025-12-27 22:04:25 -08:00
AIDER_INTEGRATION.md Add Aider integration for beads issue tracking 2025-11-23 15:13:54 -08:00
ANTIVIRUS.md feat: add Windows code signing infrastructure (bd-14v0) 2025-12-24 00:07:16 -08:00
ARCHITECTURE.md Add close_reason to JSONL format documentation and tests (bd-lxzx) 2025-12-30 17:05:48 -08:00
ATTRIBUTION.md Reorganize project structure: move Go files to internal/beads, docs to docs/ 2025-11-05 21:04:00 -08:00
CLAUDE.md docs: fix broken relative links across documentation 2025-12-16 00:46:08 -08:00
CLAUDE_INTEGRATION.md docs: document bd setup command 2025-12-16 01:08:42 -08:00
CLI_REFERENCE.md feat: add bd state and bd set-state helper commands (bd-7l67) 2025-12-30 15:57:08 -08:00
COLLISION_MATH.md docs: fix broken relative links across documentation 2025-12-16 00:46:08 -08:00
COMMUNITY_TOOLS.md fix: update perles community tool description (#778) 2025-12-28 12:52:29 -08:00
CONFIG.md feat(config): add validation.on-create and validation.on-sync config options (bd-t7jq) 2026-01-01 19:31:12 -08:00
CONTRIBUTOR_NAMESPACE_ISOLATION.md Design contributor namespace isolation for beads pollution prevention 2025-12-30 17:06:36 -08:00
daemon-summary.md feat(daemon): unify auto-sync config for simpler agent workflows (#904) 2026-01-06 12:52:19 -08:00
DAEMON.md fix(docs): standardize sync branch name and daemon syntax (GH#376) 2025-12-25 16:22:09 -08:00
DELETIONS.md docs: update documentation for CLI consolidation (bd-bxqv) 2025-12-27 16:21:08 -08:00
ERROR_HANDLING.md docs: Complete error handling audit 2025-11-24 00:35:04 -08:00
EXCLUSIVE_LOCK.md Reorganize project structure: move Go files to internal/beads, docs to docs/ 2025-11-05 21:04:00 -08:00
EXTENDING.md docs: update documentation for CLI consolidation (bd-bxqv) 2025-12-27 16:21:08 -08:00
FAQ.md docs: fix README and PLUGIN.md documentation issues (#763) 2025-12-27 17:20:00 -08:00
GIT_INTEGRATION.md fix(docs): standardize sync branch name and daemon syntax (GH#376) 2025-12-25 16:22:09 -08:00
graph-links.md refactor: remove Gas Town references from codebase 2025-12-30 14:13:32 -08:00
INSTALLING.md docs: update skill names from /bd-* to /beads:* (#862) 2026-01-02 17:07:49 -08:00
INTERNALS.md bd sync: 2025-11-25 11:35:26 2025-11-25 11:35:26 -08:00
LABELS.md feat: add bd state and bd set-state helper commands (bd-7l67) 2025-12-30 15:57:08 -08:00
LINTING.md Document -short flag, update linting baseline, clarify bd edit MCP exclusion 2025-11-06 19:42:01 -08:00
MOLECULES.md refactor: remove Gas Town references from codebase 2025-12-30 14:13:32 -08:00
MULTI_REPO_AGENTS.md docs: update beads.jsonl references to issues.jsonl 2025-12-16 01:08:46 -08:00
MULTI_REPO_HYDRATION.md Extract SQLite migrations into separate files (bd-fb95094c.7) 2025-11-06 20:06:45 -08:00
MULTI_REPO_MIGRATION.md Merge GH#409 2025-12-16 01:19:07 -08:00
PERFORMANCE_TESTING.md docs: add performance testing guide (bd-zj8e) 2025-11-28 23:26:24 -08:00
PLUGIN.md Update link to install script (#867) 2026-01-03 12:53:58 -08:00
pr-752-chaos-testing-review.md refactor: remove unused bd pin/unpin/hook commands (bd-x0zl) 2025-12-27 16:02:15 -08:00
PROTECTED_BRANCHES.md fix(docs): standardize sync branch name and daemon syntax (GH#376) 2025-12-25 16:22:09 -08:00
QUICKSTART.md feat: add bd admin parent command for cleanup/compact/reset (bd-3u8m) 2025-12-27 16:21:08 -08:00
README_TESTING.md DOCTOR IMPROVEMENTS: visual improvements/grouping + add comprehensive tests + fix gosec warnings (#656) 2025-12-20 03:10:06 -08:00
RELEASING.md docs: fix broken relative links across documentation 2025-12-16 00:46:08 -08:00
ROUTING.md Add routing integration tests and documentation 2025-11-04 23:12:42 -08:00
SETUP.md feat(setup): refactor to recipe-based architecture (bd-i3ed) 2026-01-04 21:57:09 -08:00
TESTING.md chore: code health review - test fix and error comments (bd-9g1z, bd-ork0) 2025-12-22 21:30:57 -08:00
TESTING_PHILOSOPHY.md DOCTOR IMPROVEMENTS: visual improvements/grouping + add comprehensive tests + fix gosec warnings (#656) 2025-12-20 03:10:06 -08:00
TROUBLESHOOTING.md docs: fix README and PLUGIN.md documentation issues (#763) 2025-12-27 17:20:00 -08:00
UI_PHILOSOPHY.md docs: consolidate duplicate UI_PHILOSOPHY files (GH#745) 2025-12-27 18:01:59 -08:00
UNINSTALLING.md chore: remove obsolete BD_GUIDE.md references 2025-12-20 20:50:33 -08:00
WORKTREES.md refactor: remove unused bd pin/unpin/hook commands (bd-x0zl) 2025-12-27 16:02:15 -08:00