From 8530902a326f45daaade01bbf2f331ae3cd362c6 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Tue, 4 Nov 2025 13:18:32 -0800 Subject: [PATCH] docs: add next session guide for Phase 3 of bd-d19a --- NEXT_SESSION.md | 239 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 NEXT_SESSION.md diff --git a/NEXT_SESSION.md b/NEXT_SESSION.md new file mode 100644 index 00000000..42c75fc3 --- /dev/null +++ b/NEXT_SESSION.md @@ -0,0 +1,239 @@ +# 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`: +```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**: +```markdown +## 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 + +```bash +# 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: + +```bash +# 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 + +```bash +# 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