Merge GH#409

.beads-hooks/pre-commit

@@ -1,5 +1,5 @@
 #!/bin/sh
-# bd-hooks-version: 0.24.2
+# bd-hooks-version: 0.29.0
 #
 # bd (beads) pre-commit hook
 #
@@ -29,10 +29,12 @@ fi
 # Flush pending changes to JSONL
 # Use --flush-only to skip git operations (we're already in a git hook)
 # Suppress output unless there's an error
+# Note: We warn but don't fail - this allows commits to proceed even if
+# beads has issues (e.g., user removed .beads from their branch)
 if ! bd sync --flush-only >/dev/null 2>&1; then
-    echo "Error: Failed to flush bd changes to JSONL" >&2
+    echo "Warning: Failed to flush bd changes to JSONL" >&2
     echo "Run 'bd sync --flush-only' manually to diagnose" >&2
-    exit 1
+    # Don't block the commit - user may have removed beads or have other issues
 fi
 
 # Stage all tracked JSONL files (issues.jsonl is canonical, beads.jsonl for backward compat, deletions.jsonl for deletion propagation)

cmd/bd/templates/hooks/pre-commit

@@ -54,11 +54,20 @@ fi
 # Flush pending changes to JSONL
 # Use --flush-only to skip git operations (we're already in a git hook)
 # Suppress output unless there's an error
+<<<<<<< HEAD
 # Note: We don't block commits on flush failure - beads issues shouldn't prevent code commits
 if ! bd sync --flush-only >/dev/null 2>&1; then
     echo "Warning: Failed to flush bd changes to JSONL" >&2
     echo "Run 'bd sync --flush-only' manually to diagnose" >&2
     # Continue with commit - don't block code changes due to beads issues
+=======
+# Note: We warn but don't fail - this allows commits to proceed even if
+# beads has issues (e.g., user removed .beads from their branch)
+if ! bd sync --flush-only >/dev/null 2>&1; then
+    echo "Warning: Failed to flush bd changes to JSONL" >&2
+    echo "Run 'bd sync --flush-only' manually to diagnose" >&2
+    # Don't block the commit - user may have removed beads or have other issues
+>>>>>>> origin/bd-l0pg-slit
 fi
 
 # Stage all tracked JSONL files (issues.jsonl is canonical, beads.jsonl for backward compat, deletions.jsonl for deletion propagation)

docs/ADVANCED.md

@@ -231,16 +231,16 @@ The conflicts you'll encounter are **git merge conflicts** in the JSONL file whe
 **Resolution:**
 ```bash
 # After git merge creates conflict
-git checkout --theirs .beads/beads.jsonl  # Accept remote version
+git checkout --theirs .beads/issues.jsonl  # Accept remote version
 # OR
-git checkout --ours .beads/beads.jsonl    # Keep local version
+git checkout --ours .beads/issues.jsonl    # Keep local version
 # OR manually resolve in editor (keep line with newer updated_at)
 
 # Import the resolved JSONL
-bd import -i .beads/beads.jsonl
+bd import -i .beads/issues.jsonl
 
 # Commit the merge
-git add .beads/beads.jsonl
+git add .beads/issues.jsonl
 git commit
 ```
 

docs/ARCHITECTURE.md

@@ -33,7 +33,7 @@ bd's core design enables a distributed, git-backed issue tracker that feels like
                                v
 ┌─────────────────────────────────────────────────────────────────┐
 │                       JSONL File                                 │
-│                   (.beads/beads.jsonl)                           │
+│                   (.beads/issues.jsonl)                          │
 │                                                                  │
 │  - Git-tracked source of truth                                   │
 │  - One JSON line per entity (issue, dep, label, comment)         │
@@ -246,7 +246,7 @@ open ──▶ in_progress ──▶ closed
 ```
 .beads/
 ├── beads.db          # SQLite database (gitignored)
-├── beads.jsonl       # JSONL source of truth (git-tracked)
+├── issues.jsonl      # JSONL source of truth (git-tracked)
 ├── bd.sock           # Daemon socket (gitignored)
 ├── daemon.log        # Daemon logs (gitignored)
 ├── config.yaml       # Project config (optional)

docs/CLI_REFERENCE.md

@@ -250,7 +250,7 @@ bd --allow-stale list --status open --json
 
 ```bash
 # Force metadata update even when DB appears synced
-bd import --force -i .beads/beads.jsonl
+bd import --force -i .beads/issues.jsonl
 ```
 
 **When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.

docs/GIT_INTEGRATION.md

@@ -595,7 +595,7 @@ git config merge.beads.driver
 bd init --skip-db  # Only reconfigure git, don't touch database
 
 # Verify .gitattributes
-grep "beads.jsonl" .gitattributes
+grep "issues.jsonl" .gitattributes
 # Expected: .beads/issues.jsonl merge=beads
 ```
 

docs/MULTI_REPO_AGENTS.md

@@ -303,7 +303,7 @@ bd daemons killall        # Restart all daemons
 - ❌ Don't manually override routing without good reason
 
 ### Teams
-- ✅ Commit `.beads/beads.jsonl` to shared repo
+- ✅ Commit `.beads/issues.jsonl` to shared repo
 - ✅ Use `bd sync` to ensure changes are committed/pushed
 - ✅ Link related issues across repos with dependencies
 - ❌ Don't gitignore `.beads/` - you lose the git ledger
@@ -328,14 +328,14 @@ Multi-repo mode is fully backward compatible:
 **Without multi-repo config:**
 ```bash
 bd create "Issue" -p 1
-# → Creates in .beads/beads.jsonl (single-repo mode)
+# → Creates in .beads/issues.jsonl (single-repo mode)
 ```
 
 **With multi-repo config:**
 ```bash
 bd create "Issue" -p 1
 # → Auto-routed based on config
-# → Old issues in .beads/beads.jsonl still work
+# → Old issues in .beads/issues.jsonl still work
 ```
 
 **Disabling multi-repo:**

docs/MULTI_REPO_MIGRATION.md

@@ -14,7 +14,7 @@ This guide helps you adopt beads' multi-repo workflow for OSS contributions, tea
 
 ## What is Multi-Repo Mode?
 
-By default, beads stores issues in `.beads/beads.jsonl` in your current repository. Multi-repo mode lets you:
+By default, beads stores issues in `.beads/issues.jsonl` in your current repository. Multi-repo mode lets you:
 
 - **Route issues to different repositories** based on your role (maintainer vs. contributor)
 - **Aggregate issues from multiple repos** into a unified view
@@ -223,7 +223,7 @@ bd ready
 bd list --json
 
 # Complete team work
-git add .beads/beads.jsonl
+git add .beads/issues.jsonl
 git commit -m "Updated issue tracker"
 git push origin main
 ```
@@ -394,7 +394,7 @@ bd sync
 bd list --json
 ```
 
-### Git merge conflicts in .beads/beads.jsonl
+### Git merge conflicts in .beads/issues.jsonl
 
 **Problem:** Multiple repos modifying same JSONL file.
 
@@ -432,12 +432,12 @@ No migration needed! Multi-repo mode is opt-in:
 ```bash
 # Before (single repo)
 bd create "Issue" -p 1
-# → Creates in .beads/beads.jsonl
+# → Creates in .beads/issues.jsonl
 
 # After (multi-repo configured)
 bd create "Issue" -p 1
 # → Auto-routed based on role
-# → Old issues in .beads/beads.jsonl still work
+# → Old issues in .beads/issues.jsonl still work
 ```
 
 ### Disabling Multi-Repo
@@ -461,7 +461,7 @@ bd create "Issue" -p 1
 - ❌ Don't mix planning and implementation in the same repo
 
 ### Teams
-- ✅ Commit `.beads/beads.jsonl` to shared repository
+- ✅ Commit `.beads/issues.jsonl` to shared repository
 - ✅ Use protected branch workflow for main/master
 - ✅ Review issue changes in PRs like code changes
 - ❌ Don't gitignore `.beads/` - you lose the git ledger
@@ -481,7 +481,14 @@ bd create "Issue" -p 1
 
 ## Related Issues
 
+<<<<<<< HEAD
 - `bd-8rd` - Migration and onboarding epic
 - `bd-mlcz` - `bd migrate` command (planned)
 - `bd-kla1` - `bd init --contributor` wizard ✅ implemented
 - `bd-twlr` - `bd init --team` wizard ✅ implemented
+=======
+- [bd-8rd](/.beads/issues.jsonl#bd-8rd) - Migration and onboarding epic
+- [bd-mlcz](/.beads/issues.jsonl#bd-mlcz) - `bd migrate` command (planned)
+- [bd-kla1](/.beads/issues.jsonl#bd-kla1) - `bd init --contributor` wizard ✅ implemented
+- [bd-twlr](/.beads/issues.jsonl#bd-twlr) - `bd init --team` wizard ✅ implemented
+>>>>>>> origin/bd-l0pg-slit

docs/PROTECTED_BRANCHES.md

@@ -62,7 +62,7 @@ Files that are automatically gitignored (do NOT commit):
 - `.beads/beads.left.jsonl`, `beads.right.jsonl` - Temporary merge artifacts
 
 The sync branch (beads-metadata) will contain:
-- `.beads/beads.jsonl` - Issue data in JSONL format (committed automatically by daemon)
+- `.beads/issues.jsonl` - Issue data in JSONL format (committed automatically by daemon)
 - `.beads/metadata.json` - Metadata about the beads installation
 - `.beads/config.yaml` - Configuration template (optional)
 
@@ -100,10 +100,10 @@ your-project/
 │   └── beads-worktrees/
 │       └── beads-metadata/  # Worktree (only .beads/ checked out)
 │           └── .beads/
-│               └── beads.jsonl
+│               └── issues.jsonl
 ├── .beads/                  # Your main copy
 │   ├── beads.db
-│   ├── beads.jsonl
+│   ├── issues.jsonl
 │   └── .gitignore
 ├── .gitattributes           # Merge driver config (in main branch)
 └── src/                     # Your code (untouched)
@@ -116,7 +116,7 @@ Main branch (protected):
 - `.gitattributes` - Merge driver configuration
 
 Sync branch (beads-metadata):
-- `.beads/beads.jsonl` - Issue data (committed by daemon)
+- `.beads/issues.jsonl` - Issue data (committed by daemon)
 - `.beads/metadata.json` - Repository metadata
 - `.beads/config.yaml` - Configuration template
 
@@ -136,7 +136,7 @@ Not tracked (gitignored):
 When you update an issue:
 
 1. Issue is updated in `.beads/beads.db` (SQLite database)
-2. Daemon exports to `.beads/beads.jsonl` (JSONL file)
+2. Daemon exports to `.beads/issues.jsonl` (JSONL file)
 3. JSONL is copied to worktree (`.git/beads-worktrees/beads-metadata/.beads/`)
 4. Daemon commits the change in the worktree to `beads-metadata` branch
 5. Main branch stays untouched (no commits on `main`)
@@ -295,11 +295,11 @@ If you encounter conflicts during merge:
 # bd sync --merge will detect conflicts and show:
 Error: Merge conflicts detected
 Conflicting files:
-  .beads/beads.jsonl
+  .beads/issues.jsonl
 
 To resolve:
-1. Fix conflicts in .beads/beads.jsonl
+1. Fix conflicts in .beads/issues.jsonl
-2. git add .beads/beads.jsonl
+2. git add .beads/issues.jsonl
 3. git commit
 4. bd import  # Reimport to sync database
 ```
@@ -308,7 +308,7 @@ To resolve:
 
 JSONL files are append-only and line-based, so conflicts are rare. When they occur:
 
-1. Open `.beads/beads.jsonl` and look for conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
+1. Open `.beads/issues.jsonl` and look for conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
 2. Both versions are usually valid - keep both lines
 3. Remove the conflict markers
 4. Save and commit
@@ -332,8 +332,8 @@ Example conflict resolution:
 Then:
 
 ```bash
-git add .beads/beads.jsonl
+git add .beads/issues.jsonl
-git commit -m "Resolve beads.jsonl merge conflict"
+git commit -m "Resolve issues.jsonl merge conflict"
 bd import  # Import to database (will use latest timestamp)
 ```
 

docs/TROUBLESHOOTING.md

@@ -656,7 +656,7 @@ bd --allow-stale list --status open
 ```bash
 # Most reliable for sandboxed environments
 bd --sandbox ready
-bd --sandbox import -i .beads/beads.jsonl
+bd --sandbox import -i .beads/issues.jsonl
 ```
 
 ---
@@ -670,7 +670,7 @@ If stuck in a sandboxed environment:
 bd --sandbox ready
 
 # Step 2: If you get staleness errors, force import
-bd import --force -i .beads/beads.jsonl
+bd import --force -i .beads/issues.jsonl
 
 # Step 3: If still blocked, use allow-stale (emergency only)
 bd --allow-stale ready

examples/contributor-workflow/README.md

@@ -58,7 +58,7 @@ When you create issues as a contributor:
 bd create "Fix authentication bug" -p 1
 ```
 
-Beads automatically routes this to your planning repo (`~/.beads-planning/.beads/beads.jsonl`), not the current repo.
+Beads automatically routes this to your planning repo (`~/.beads-planning/.beads/issues.jsonl`), not the current repo.
 
 ### Viewing Issues
 

examples/git-hooks/README.md

@@ -129,11 +129,11 @@ This solves bd-my64: changes made between commit and push (or pending debounced
 After a git pull or merge, the hook runs:
 
 ```bash
-bd import -i .beads/beads.jsonl
+bd import -i .beads/issues.jsonl
 ```
 
 This ensures your local database reflects the merged state. The hook:
-- Only runs if `.beads/beads.jsonl` exists (also checks `issues.jsonl` for backward compat)
+- Only runs if `.beads/issues.jsonl` exists (also checks `issues.jsonl` for backward compat)
 - Imports any new issues or updates from the merge
 - Warns on failure but doesn't block the merge
 

examples/git-hooks/pre-commit

@@ -23,20 +23,12 @@ if ! command -v bd >/dev/null 2>&1; then
     exit 0
 fi
 
-# Check if we're in a bd workspace with an actual database
+# Check if we're in a bd workspace
-# Just having a .beads directory isn't enough - it must be properly initialized
 if [ ! -d .beads ]; then
     # Not a bd workspace, nothing to do
     exit 0
 fi
 
-# Verify beads is actually initialized (has database or config)
-# This handles the case where .beads was removed from git but directory lingers
-if [ ! -f .beads/beads.db ] && [ ! -f .beads/config.yaml ] && [ ! -f .beads/issues.jsonl ]; then
-    # Directory exists but beads not initialized, nothing to do
-    exit 0
-fi
-
 # Check if sync-branch is configured in config.yaml or env var
 # If so, .beads changes go to a separate branch via worktree, not the current branch
 SYNC_BRANCH="${BEADS_SYNC_BRANCH:-}"
@@ -54,27 +46,18 @@ fi
 # Flush pending changes to JSONL
 # Use --flush-only to skip git operations (we're already in a git hook)
 # Suppress output unless there's an error
-# Note: We don't block commits on flush failure - beads issues shouldn't prevent code commits
+# Note: We warn but don't fail - this allows commits to proceed even if
+# beads has issues (e.g., user removed .beads from their branch)
 if ! bd sync --flush-only >/dev/null 2>&1; then
     echo "Warning: Failed to flush bd changes to JSONL" >&2
     echo "Run 'bd sync --flush-only' manually to diagnose" >&2
-    # Continue with commit - don't block code changes due to beads issues
+    # Don't block the commit - user may have removed beads or have other issues
 fi
 
-# Stage all tracked JSONL files (issues.jsonl is canonical, beads.jsonl for backward compat, deletions.jsonl for deletion propagation)
+# Stage all tracked JSONL files (beads.jsonl, issues.jsonl for backward compat, deletions.jsonl for deletion propagation)
-# For worktrees, .beads is in the main repo's working tree, not the worktree,
+# git add is harmless if file doesn't exist
-# so we can't use git add. Skip staging for worktrees.
+for f in .beads/beads.jsonl .beads/issues.jsonl .beads/deletions.jsonl; do
-if [ "$(git rev-parse --git-dir)" = "$(git rev-parse --git-common-dir)" ]; then
-    # Regular repo: files are in the working tree, safe to add
-    # git add is harmless if file doesn't exist
-    for f in .beads/beads.jsonl .beads/issues.jsonl .beads/deletions.jsonl; do
     [ -f "$f" ] && git add "$f" 2>/dev/null || true
-    done
+done
-else
-    # Worktree: .beads is in the main repo's working tree, not this worktree
-    # Git rejects adding files outside the worktree, so we skip it.
-    # The main repo will see the changes on the next pull/sync.
-    :  # do nothing
-fi
 
 exit 0

examples/protected-branch/README.md

@@ -176,11 +176,11 @@ my-project/
 │   ├── beads-worktrees/       # Hidden worktree directory
 │   │   └── beads-metadata/    # Lightweight checkout of sync branch
 │   │       └── .beads/
-│   │           └── beads.jsonl
+│   │           └── issues.jsonl
 │   └── ...
 ├── .beads/                    # Main beads directory (in your workspace)
 │   ├── beads.db               # SQLite database
-│   ├── beads.jsonl            # JSONL export
+│   ├── issues.jsonl            # JSONL export
 │   └── bd.sock                # Daemon socket (if running)
 ├── src/                       # Your application code
 │   └── ...
@@ -209,7 +209,7 @@ my-project/
 
 ### Troubleshooting
 
-**"Merge conflicts in beads.jsonl"**
+**"Merge conflicts in issues.jsonl"**
 
 JSONL is append-only and line-based, so conflicts are rare. If they occur:
 1. Both versions are usually valid - keep both lines

examples/team-workflow/README.md

@@ -244,20 +244,20 @@ Hash-based IDs prevent most conflicts. If conflicts occur:
 ```bash
 # During git pull/merge
 git pull origin beads-metadata
-# CONFLICT in .beads/beads.jsonl
+# CONFLICT in .beads/issues.jsonl
 
 # Option 1: Accept remote
-git checkout --theirs .beads/beads.jsonl
+git checkout --theirs .beads/issues.jsonl
-bd import -i .beads/beads.jsonl
+bd import -i .beads/issues.jsonl
 
 # Option 2: Accept local
-git checkout --ours .beads/beads.jsonl
+git checkout --ours .beads/issues.jsonl
-bd import -i .beads/beads.jsonl
+bd import -i .beads/issues.jsonl
 
 # Option 3: Use beads-merge tool (recommended)
 # See docs/GIT_INTEGRATION.md for merge conflict resolution
 
-git add .beads/beads.jsonl
+git add .beads/issues.jsonl
 git commit
 ```
 
@@ -299,7 +299,7 @@ git commit
 
 ### Q: How do team members see each other's issues?
 
-A: Issues are stored in `.beads/beads.jsonl` which is version-controlled. Pull from git to sync.
+A: Issues are stored in `.beads/issues.jsonl` which is version-controlled. Pull from git to sync.
 
 ```bash
 git pull
@@ -372,9 +372,9 @@ bd daemon --start --auto-commit --auto-push
 Use beads-merge or resolve manually (see [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md)):
 
 ```bash
-git checkout --theirs .beads/beads.jsonl
+git checkout --theirs .beads/issues.jsonl
-bd import -i .beads/beads.jsonl
+bd import -i .beads/issues.jsonl
-git add .beads/beads.jsonl
+git add .beads/issues.jsonl
 git commit
 ```
 

skills/beads/references/CLI_REFERENCE.md

@@ -249,7 +249,7 @@ bd --allow-stale list --status open --json
 
 ```bash
 # Force metadata update even when DB appears synced
-bd import --force -i .beads/beads.jsonl
+bd import --force -i .beads/issues.jsonl
 ```
 
 **When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.