Updated hash ID design to explicitly document hybrid approach:
- Storage: Always use prefix (bd-a3f8e9)
- CLI input: Prefix optional (a3f8e9 or bd-a3f8e9 both work)
- CLI output: Always show prefix (for external clarity)
Rationale:
✅ External references are unambiguous: "Fixed in bd-a3f8e9"
✅ CLI convenience: Less typing when using bd commands
✅ Grep-able: Can search for bd-a3f8e9 across files
✅ Future-proof: Supports multiple database prefixes
✅ No conflict with git SHAs in commit messages
Updated issues:
- bd-165: Added "ID Structure" section with prefix behavior
- bd-170: Detailed prefix parsing logic and examples
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Moved collision-resolution-failure-analysis.md to docs/
(better organization with other architecture docs)
- Created bd-191: Add --parent flag to bd list command
Useful for listing children of an epic, will be even better
with hierarchical IDs (bd-165)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major simplification of the hash ID proposal:
- Remove separate alias system (was adding complexity)
- Add hierarchical sequential children: bd-{hash}.1.2.3
- Up to 3 levels deep for natural work breakdown structure
- Git-style prefix matching instead of #aliases
Benefits:
✅ Simpler architecture (no alias counter to coordinate)
✅ Human-friendly IDs where it matters (epic children)
✅ Natural WBS encoding in IDs
✅ Collision-free at top level, rare within epics
✅ -1000 LOC vs dual-system approach
Updated issues:
- bd-165: Core epic with new design doc
- bd-167: child_counters table (not alias table)
- bd-168: hierarchical child ID generation
- bd-169: JSONL format stores hierarchical IDs
- bd-170: Git-style prefix matching (not aliases)
- bd-171: Hierarchical child logic (not alias conflicts)
- bd-173: Migration preserves hierarchy
- bd-174: Tree visualization (not alias commands)
- bd-176: Updated docs plan
Timeline: ~8 weeks (down from 9 due to simplification)
Also added collision-resolution-failure-analysis.md documenting
current architecture issues to inform the redesign.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Release highlights:
- Fix bd-160: JSONL integrity validation prevents export deduplication data loss
- Add comprehensive integration tests for export/import workflows
- Clear export_hashes on imports to prevent staleness
- Created bd-179 epic for remaining test coverage improvements
This release fixes a critical P0 bug that could cause silent data loss
when JSONL and export_hashes diverged after git operations.
## Problem
Export deduplication feature broke when JSONL and export_hashes diverged
(e.g., after git pull/reset). This caused exports to skip issues that
weren't actually in the file, leading to silent data loss.
## Solution
1. JSONL integrity validation before every export
- Store JSONL file hash after export
- Validate hash before export, clear export_hashes if mismatch
- Automatically recovers from git operations changing JSONL
2. Clear export_hashes on all imports
- Prevents stale hashes from causing future export failures
- Import operations invalidate export_hashes state
3. Add Storage interface methods:
- GetJSONLFileHash/SetJSONLFileHash for integrity tracking
- ClearAllExportHashes for recovery
## Tests Added
- TestJSONLIntegrityValidation: Unit tests for validation logic
- TestImportClearsExportHashes: Verifies imports clear hashes
- TestExportIntegrityAfterJSONLTruncation: Simulates git reset (would have caught bd-160)
- TestExportIntegrityAfterJSONLDeletion: Tests recovery from file deletion
- TestMultipleExportsStayConsistent: Tests repeated export integrity
## Follow-up
Created bd-179 epic for remaining integration test gaps (multi-repo sync,
daemon auto-sync, corruption recovery tests).
Closes bd-160
The timestamp-only deduplication feature causes data loss when
export_hashes table gets out of sync with JSONL file (after git
operations, imports, etc). This leads to exports skipping issues
that aren't actually in the file.
Symptoms we saw:
- Export reports 'Skipped 128 issues with timestamp-only changes'
- JSONL only has 38 lines but DB has 149 issues
- Two repos on same commit show different issue counts
- Auto-import doesn't trigger (hash matches despite missing data)
Fix: Disable the feature entirely until we can implement proper
JSONL integrity validation (see bd-160 for proposed solutions).
