chore: update beads issue tracker files

[flowerornament]

Sync bd database files after installing beads-rs.

[claude]

PR Review: Beads Database Sync

Summary

This PR syncs beads-rs (bd) database files after installation by replacing the direct .beads/issues.jsonl file with a symlink to the beads-rs export location, and backing up the original content.

---

Code Quality: ✅ Good

Strengths:

• Clean approach to integrating beads-rs managed exports
• Preserves original data in .beads/issues.jsonl.bak
• Follows standard symlink pattern for tool integration

Considerations:

• The symlink path /root/.local/share/beads-rs/exports/9a90550f4d157154668154c9b2bec226/issues.jsonl is absolute and environment-specific. This will break for:
  • Other users (different home directories)
  • CI/CD environments
  • Collaborative development
• Consider adding .beads/issues.jsonl to .gitignore since it's now a symlink to a local tool's data

---

Potential Issues: ⚠️ Medium Priority

1. Portability Issue 🔴

   • The symlink uses an absolute path specific to the current machine
   • Other developers checking out this repo will have a broken symlink
   • Recommendation: Either:
     • Add .beads/issues.jsonl to .gitignore (since it's tool-managed)
     • Use relative paths if beads-rs supports it
     • Document in README that developers must run bd sync to initialize

2. Backup File in Git 🟡

   • .beads/issues.jsonl.bak is committed - is this intentional?
   • If beads-rs manages this, the backup might not need version control
   • Recommendation: Consider adding *.bak to .gitignore

3. Missing Documentation 🟡

   • No documentation about beads-rs setup requirements
   • New contributors won't know why the symlink exists
   • Recommendation: Add to README or AGENTS.md:
     • How to install beads-rs
     • Initial setup steps (bd sync, etc.)
     • What to do if symlink is broken

---

Performance: ✅ No Concerns

• Symlinks have no performance impact
• Issue tracker data is read infrequently

---

Security: ✅ No Concerns

• Issue tracking data appears to be project-specific
• No credentials or sensitive data exposed
• Symlink points to user's local data directory (appropriate)

---

Test Coverage: ⚠️ Missing

• No tests exist for beads integration
• Consider adding:
  • Script to verify .beads/issues.jsonl exists and is readable
  • Documentation tests for setup instructions
  • CI check that doesn't fail on missing beads setup

---

Recommendations

High Priority:

1. Add .beads/issues.jsonl to .gitignore
2. Document beads-rs setup in AGENTS.md or README
3. Consider adding .beads/issues.jsonl.bak to .gitignore as well

Medium Priority:
4. Add setup verification script (e.g., scripts/verify-beads.sh)
5. Update AGENTS.md "Issue Tracking" section with initialization steps
6. Consider adding a .beads/README.md explaining the directory structure

Example for AGENTS.md:

## First-Time Setup

After cloning the repository:

1. Install beads-rs: `cargo install beads-rs`
2. Initialize the issue tracker: `bd sync`
3. Verify setup: `bd ready`

The `.beads/issues.jsonl` file is a symlink to beads-rs managed data and should not be committed.

---

Verdict

Conditional Approval ✅ (with follow-up)

The core change is sound, but needs supporting updates for team collaboration:

• Works fine for single-developer workflow
• Needs documentation and gitignore updates for multi-developer use
• No blocking issues, but follow-up PR recommended for portability improvements

Suggested next steps:

1. Merge this PR if it unblocks your workflow
2. Create follow-up issue to address portability concerns
3. Add documentation in next session per AGENTS.md workflow

---

🤖 Generated with Claude Code