beads/NEXT_SESSION.md

Next Session: Complete bd-d19a (Fix Import Failure on Missing Parents)

Current Status

Branch: fix/import-missing-parents
Epic: bd-d19a (P0 - Critical)
Progress: Phase 1 & 2 Complete ✅

Completed Work

Phase 1: Topological Sorting ✅

• Commit: f2cb91d
• What: Added depth-based sorting to importer.go to ensure parents are created before children
• Files: internal/importer/importer.go
• Result: Fixes latent ordering bug where parent-child pairs in same batch could fail

Phase 2: Parent Resurrection ✅

• Commit: b41d65d
• Implemented Issues:
  • bd-cc4f: TryResurrectParent function
  • bd-d76d: Modified EnsureIDs to call resurrection
  • bd-02a4: Modified CreateIssue to call resurrection
• Files Created: internal/storage/sqlite/resurrection.go
• Files Modified:
  • internal/storage/sqlite/ids.go
  • internal/storage/sqlite/sqlite.go
  • internal/storage/sqlite/batch_ops.go
  • internal/storage/sqlite/batch_ops_test.go

How Resurrection Works:

1. When child issue has missing parent, search .beads/issues.jsonl for parent in git history
2. If found, create tombstone issue (status=closed, priority=4)
3. Tombstone preserves original title, type, created_at
4. Description marked with [RESURRECTED] prefix + original description
5. Dependencies copied if targets exist
6. Recursively handles entire parent chains (e.g., bd-abc.1.2 → resurrects both bd-abc and bd-abc.1)

---

Next Steps: Phase 3 - Testing & Documentation

1. Add Comprehensive Tests

Create: internal/storage/sqlite/resurrection_test.go

Test Cases Needed:

• ✅ Parent exists → no resurrection needed
• ✅ Parent found in JSONL → successful resurrection
• ✅ Parent not in JSONL → proper error message
• ✅ Multi-level chain (bd-abc.1.2) → resurrects entire chain
• ✅ JSONL file missing → graceful failure
• ✅ Malformed JSONL lines → skip with warning
• ✅ Dependencies preserved → only if targets exist
• ✅ Tombstone properties → correct status, priority, description format
• ✅ Concurrent resurrection → idempotent behavior

Integration Test: Add to beads_integration_test.go:

TestImportWithDeletedParent
- Create parent and child
- Delete parent
- Export to JSONL (preserves parent in git)
- Clear DB
- Import from JSONL
- Verify: parent resurrected as tombstone, child imported successfully

2. Update Documentation

Files to Update:

1. README.md - Add resurrection behavior to import section
2. QUICKSTART.md - Mention parent resurrection for multi-repo workflows
3. docs/import-bug-analysis-bd-3xq.md - Add "Implementation Complete" section
4. AGENTS.md - Document resurrection for AI agents

Example Addition to README.md:

## Parent Resurrection

When importing issues with hierarchical IDs (e.g., `bd-abc.1`), bd automatically
resurrects deleted parent issues from git history to maintain referential integrity.

Resurrected parents are created as tombstones:
- Status: `closed`
- Priority: 4 (lowest)
- Description: `[RESURRECTED]` prefix + original description

This enables multi-repo workflows where different clones may delete different issues.

3. Manual Testing Workflow

# Terminal 1: Create test scenario
cd /tmp/bd-test
git init
bd init --prefix test --quiet
bd create "Parent epic" -t epic -p 1 --json  # Returns test-abc123
bd create "Child task" -p 1 --json            # Auto-creates test-abc123.1

# Verify hierarchy
bd dep tree test-abc123

# Delete parent (simulating normal database hygiene)
bd delete test-abc123 --force

# Export state (child exists, parent deleted)
bd export -o backup.jsonl

# Simulate fresh clone
rm -rf .beads/beads.db
bd init --prefix test --quiet

# Import - should resurrect parent as tombstone
bd import -i backup.jsonl

# Verify resurrection
bd show test-abc123 --json | grep -i resurrected
bd show test-abc123.1 --json  # Should exist
bd dep tree test-abc123  # Should show full tree

4. Edge Cases to Handle

Potential Issues:

1. JSONL path detection: Currently assumes .beads/issues.jsonl - verify works with symlinks, worktrees
2. Performance: Large JSONL files (10k+ issues) - may need optimization (indexing?)
3. Memory: Scanner buffer is 1MB - test with very large issue descriptions
4. Concurrent access: Multiple processes resurrecting same parent simultaneously

Optimizations to Consider (Future work):

• Build in-memory index of JSONL on first resurrection call (cache for session)
• Use grep or ripgrep for fast ID lookup before JSON parsing
• Add resurrection stats to import summary (Resurrected: 3 parents)

5. Create Pull Request

Once testing complete:

# Update CHANGELOG.md
# Add entry under "Unreleased"

# Create PR
gh pr create \
  --title "Fix import failure on missing parent issues (bd-d19a)" \
  --body "Implements topological sorting + parent resurrection.

Fixes #XXX (if there's a GitHub issue)

## Changes
- Phase 1: Topological sorting for import ordering
- Phase 2: Parent resurrection from JSONL history
- Creates tombstones for deleted parents to preserve hierarchical structure

## Testing
- [x] Unit tests for resurrection logic
- [x] Integration test for deleted parent scenario
- [x] Manual testing with multi-level hierarchies

See docs/import-bug-analysis-bd-3xq.md for full design rationale."

---

Commands for Next Session

# Resume work
cd /Users/stevey/src/dave/beads
git checkout fix/import-missing-parents

# Run existing tests
go test ./internal/storage/sqlite -v -run Resurrection

# Create new test file
# (See test template above)

# Run integration tests
go test -v -run TestImport

# Manual testing
# (See workflow above)

# When ready to merge
git checkout main
git merge fix/import-missing-parents
git push origin main

---

Issues Tracking

Epic: bd-d19a (Fix import failure on missing parent issues) - OPEN
Subtasks:

• bd-cc4f: Implement TryResurrectParent - DONE ✅
• bd-d76d: Modify EnsureIDs - DONE ✅
• bd-02a4: Modify CreateIssue - DONE ✅
• TODO: Create test issue for Phase 3
• TODO: Create docs issue for Phase 3

Files Modified:

• ✅ internal/importer/importer.go (topological sorting)
• ✅ internal/storage/sqlite/resurrection.go (new file)
• ✅ internal/storage/sqlite/ids.go
• ✅ internal/storage/sqlite/sqlite.go
• ✅ internal/storage/sqlite/batch_ops.go
• ✅ internal/storage/sqlite/batch_ops_test.go
• ⏳ internal/storage/sqlite/resurrection_test.go (TODO)
• ⏳ beads_integration_test.go (TODO - add import test)
• ⏳ README.md (TODO - document resurrection)
• ⏳ AGENTS.md (TODO - document for AI agents)

---

Key Design Decisions

1. Tombstone Status: Using closed (not a new "deleted" status) to avoid schema changes
2. Search Strategy: Linear scan of JSONL (acceptable for <10k issues, can optimize later)
3. Idempotency: TryResurrectParent checks existence first, safe to call multiple times
4. Recursion: TryResurrectParentChain handles multi-level hierarchies automatically
5. Dependencies: Best-effort resurrection (logs warnings, doesn't fail if targets missing)

---

Reference Documents

• Design Doc: docs/import-bug-analysis-bd-3xq.md (comprehensive analysis)
• Current Branch: fix/import-missing-parents
• GitHub PR URL: (To be created)
• Related Issues: bd-4ms (multi-repo support), bd-a101 (separate branch workflow)

---

Status: Ready for Phase 3 (Testing & Documentation)
Estimate: 2-3 hours for comprehensive tests + 1 hour for docs
Risk: Low - core logic implemented and builds successfully