From e2818b40750cdb450af82f4ed26393a58d1355d6 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Thu, 30 Oct 2025 14:17:17 -0700 Subject: [PATCH] bd sync: 2025-10-30 14:17:17 --- .beads/beads.jsonl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.beads/beads.jsonl b/.beads/beads.jsonl index 44c2e869..25bd586d 100644 --- a/.beads/beads.jsonl +++ b/.beads/beads.jsonl @@ -61,7 +61,7 @@ {"id":"bd-165","content_hash":"d429410e478f428289b91d4fd258797d1140adf105b54a05fb6b7fa62c91f67f","title":"Hash-based IDs with hierarchical children","description":"Replace sequential auto-increment IDs (bd-1, bd-2) with content-hash based IDs (bd-af78e9a2) and hierarchical sequential children (bd-af78e9a2.1, .2, .3).\n\n## Motivation\nCurrent sequential IDs cause collision problems when multiple clones work offline:\n- Non-deterministic convergence in N-way scenarios (bd-108, bd-109)\n- Complex collision resolution logic (~2,100 LOC)\n- UNIQUE constraint violations during import\n- Requires coordination between workers\n\nHash-based IDs eliminate collisions entirely at the top level, while hierarchical sequential children provide human-friendly IDs within naturally-coordinated contexts (epic ownership).\n\n## Benefits\n- ✅ Collision-free distributed ID generation (top-level)\n- ✅ Human-friendly IDs for related work (epic children)\n- ✅ Eliminates ~2,100 LOC of collision handling code\n- ✅ Better git merge behavior (different IDs = different JSONL lines)\n- ✅ True offline-first workflows\n- ✅ Simpler than dual-system (no alias counter to coordinate)\n- ✅ Natural work breakdown structure encoding in IDs\n- ✅ Enables parallel CI/CD workers without coordination\n\n## Design\n\n### ID Structure\n- **Storage:** bd-af78e9a2 (prefix + 8-char SHA256)\n- **CLI input:** Both bd-af78e9a2 AND a3f8e9 accepted (prefix optional)\n- **CLI output:** bd-af78e9a2 (always show prefix for copy-paste clarity)\n- **External refs:** bd-af78e9a2 (in commits, docs, unambiguous)\n\n**Why keep prefix in storage:**\n- Clear in external contexts (git commits, docs, Slack)\n- Grep-able across files\n- Distinguishable from git commit SHAs\n- Supports multiple databases (bd-, ticket-, bug- prefixes)\n\n**Why make optional in CLI:**\n- Less typing: bd show a3f8e9 works\n- Git-style convenience\n- Prefix inferred from context (bd command)\n\n### Hierarchical Children\n- **Epic children:** bd-af78e9a2.1, bd-af78e9a2.2, bd-af78e9a2.3 (sequential per parent)\n- **Nested epics:** bd-af78e9a2.1.1, bd-af78e9a2.1.2 (up to 3 levels deep)\n- **Leaf tasks:** Any issue without children\n\n### Example Hierarchy\n```\nbd-a3f8e9 [epic] \"Auth System\"\n ├─ bd-a3f8e9.1 [epic] \"Login Flow\"\n │ ├─ bd-a3f8e9.1.1 [task] \"Design login UI\"\n │ ├─ bd-a3f8e9.1.2 [task] \"Backend validation\"\n │ └─ bd-a3f8e9.1.3 [task] \"Integration tests\"\n ├─ bd-a3f8e9.2 [epic] \"Password Reset\"\n │ └─ bd-a3f8e9.2.1 [task] \"Email templates\"\n └─ bd-a3f8e9.3 [task] \"Update documentation\"\n```\n\n### CLI Usage\n```bash\n# All of these work (prefix optional in input):\nbd show a3f8e9\nbd show bd-a3f8e9\nbd show a3f8e9.1\nbd show bd-a3f8e9.1.2\n\n# Output always shows prefix:\nbd-a3f8e9 [epic] Auth System\n Status: open\n ...\n\n# External references use full ID:\ngit commit -m \"Implement login (bd-a3f8e9.1)\"\n```\n\n### Collision Characteristics\n- **Top-level:** NONE (content-based hash)\n- **Epic children:** RARE (epics have natural ownership, sequential creation)\n- **When they occur:** Easy to resolve (small scope, clear context)\n\n### Storage\n- JSONL stores full hierarchical IDs with prefix: bd-a3f8e9.1.2\n- Child counters table: child_counters(parent_id, last_child)\n- Counter per parent at any depth\n\n### Limits\n- Max depth: 3 levels (prevents over-decomposition)\n- Max breadth: Unlimited (tested up to 347 children)\n- Max ID length: ~20 chars at depth 3 (bd-a3f8e9.12.34.56)\n\n## Breaking Change\nThis is a v2.0 feature requiring migration. Provide bd migrate --hash-ids tool.\n\n## Timeline\n~8 weeks (Phase 1: Hash IDs 3w, Phase 2: Hierarchical children 3w, Phase 3: Testing 2w)\nSimplified from original 9-week estimate due to removal of alias system.\n\n## Dependencies\nShould complete after bd-74 (cleanup validation).","status":"open","priority":1,"issue_type":"epic","created_at":"2025-10-29T21:23:49.592315-07:00","updated_at":"2025-10-30T00:32:21.431272-07:00"} {"id":"bd-166","content_hash":"e5e68e05a19b8e08b51a6d91cda937b5a5006651d6db7aa47d9ad43473b98a2f","title":"Design hash ID generation algorithm","description":"Design and specify the hash-based ID generation algorithm.\n\n## Requirements\n- Deterministic: same inputs → same ID\n- Collision-resistant: ~2^32 space for 8-char hex\n- Fast: \u003c1μs per generation\n- Includes timestamp for uniqueness\n- Includes creator/workspace for distributed uniqueness\n\n## Proposed Algorithm\n```go\nfunc GenerateIssueID(title, desc string, created time.Time, workspaceID string) string {\n h := sha256.New()\n h.Write([]byte(title))\n h.Write([]byte(desc))\n h.Write([]byte(created.Format(time.RFC3339Nano)))\n h.Write([]byte(workspaceID))\n hash := hex.EncodeToString(h.Sum(nil))\n return \"bd-\" + hash[:8] // 8-char prefix = 2^32 space\n}\n```\n\n## Open Questions\n1. 8 chars (2^32) or 16 chars (2^64) for collision resistance?\n2. Include priority/type in hash? (Pro: more entropy. Con: immutable)\n3. How to handle workspace ID generation? (hostname? UUID?)\n4. What if title+desc change? (Answer: ID stays same - hash only used at creation)\n\n## Deliverables\n- Design doc: docs/HASH_ID_DESIGN.md\n- Collision probability analysis\n- Performance benchmarks\n- Prototype implementation in internal/types/id_generator.go","notes":"## Next Session: Continue bd-168\n\nWe've completed:\n- ✅ bd-166: Hash ID algorithm (returns full 64-char hash)\n- ✅ bd-167: child_counters table + getNextChildNumber()\n- ✅ Docs updated for 6-char progressive design\n\n**TODO for bd-168:**\nImplement progressive collision retry in CreateIssue():\n1. Try hash[:6] first (bd-a3f2dd)\n2. On UNIQUE constraint → try hash[:7] (bd-a3f2dda) \n3. On collision again → try hash[:8] (bd-a3f2dda8)\n4. Max 3 attempts, then error\n\nLocation: internal/storage/sqlite/sqlite.go CreateIssue() around line 748\nPattern: Detect sqlite UNIQUE constraint error, retry with longer hash\n\nSee: internal/types/id_generator.go GenerateHashID() - now returns full hash","status":"in_progress","priority":1,"issue_type":"task","created_at":"2025-10-29T21:24:01.843634-07:00","updated_at":"2025-10-30T14:04:13.585075-07:00","dependencies":[{"issue_id":"bd-166","depends_on_id":"bd-165","type":"parent-child","created_at":"2025-10-29T21:24:01.844994-07:00","created_by":"stevey"}]} {"id":"bd-167","content_hash":"64ad81d1a67f119ed3b9c66e215252aab9e569926e0a60586a61bc38bd8659b8","title":"Add child_counters table to database schema","description":"Add child_counters table to support sequential child ID generation within parent contexts.\n\n## Schema\n```sql\nCREATE TABLE child_counters (\n parent_id TEXT PRIMARY KEY,\n last_child INTEGER NOT NULL DEFAULT 0,\n FOREIGN KEY (parent_id) REFERENCES issues(id) ON DELETE CASCADE\n);\n```\n\n## Usage\n- Counter per parent (at any depth)\n- Atomic increment: INSERT...ON CONFLICT DO UPDATE\n- bd-a3f8e9 → .1, .2, .3\n- bd-a3f8e9.1 → .1.1, .1.2, .1.3\n- Works up to 3 levels deep","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-29T21:24:13.968241-07:00","updated_at":"2025-10-30T13:32:05.83292-07:00","closed_at":"2025-10-30T13:32:05.83292-07:00","dependencies":[{"issue_id":"bd-167","depends_on_id":"bd-165","type":"parent-child","created_at":"2025-10-29T21:24:13.96959-07:00","created_by":"stevey"},{"issue_id":"bd-167","depends_on_id":"bd-166","type":"blocks","created_at":"2025-10-29T21:29:45.952824-07:00","created_by":"stevey"}]} -{"id":"bd-168","content_hash":"c2041472fbce7fbe3fc32be28f61d276ea725f649344c87a1fca0f9c054999b3","title":"Implement hash ID generation in CreateIssue","description":"Implement hash ID generation in CreateIssue function.\n\n## For Top-Level Issues\n```go\nfunc generateHashID(prefix, title, description, creator string, timestamp time.Time) string {\n content := fmt.Sprintf(\"%s|%s|%s|%d\", title, description, creator, timestamp.UnixNano())\n hash := sha256.Sum256([]byte(content))\n shortHash := hex.EncodeToString(hash[:4]) // 8 hex chars\n return fmt.Sprintf(\"%s-%s\", prefix, shortHash)\n}\n```\n\n## For Child Issues\n```go\nfunc (s *SQLiteStorage) createChildIssue(parentID string, issue *types.Issue) error {\n // Validate parent exists and depth \u003c= 3\n childNum := s.getNextChildID(parentID)\n issue.ID = fmt.Sprintf(\"%s.%d\", parentID, childNum)\n // ... create issue\n}\n```\n\n## CLI Integration\n```bash\nbd create \"Auth System\" # → bd-a3f8e9a2\nbd create \"Login Flow\" --parent a3f8e9 # → bd-a3f8e9a2.1\nbd create \"Design UI\" --parent a3f8e9.1 # → bd-a3f8e9a2.1.1\n```\n\n## Validation\n- Reject depth \u003e 3\n- Ensure parent exists\n- Check parent is epic type (optional, for UX)","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-29T21:24:29.412237-07:00","updated_at":"2025-10-30T14:12:17.327987-07:00","closed_at":"2025-10-30T14:12:17.327987-07:00","dependencies":[{"issue_id":"bd-168","depends_on_id":"bd-165","type":"parent-child","created_at":"2025-10-29T21:24:29.413417-07:00","created_by":"stevey"},{"issue_id":"bd-168","depends_on_id":"bd-166","type":"blocks","created_at":"2025-10-29T21:24:29.413823-07:00","created_by":"stevey"}]} +{"id":"bd-168","content_hash":"1a53798d7a2eaf014f90a399745beb62b4bb265c9d03713f0b00dbc54c3073e2","title":"Implement hash ID generation in CreateIssue","description":"Implement hash ID generation in CreateIssue function.\n\n## For Top-Level Issues\n```go\nfunc generateHashID(prefix, title, description, creator string, timestamp time.Time) string {\n content := fmt.Sprintf(\"%s|%s|%s|%d\", title, description, creator, timestamp.UnixNano())\n hash := sha256.Sum256([]byte(content))\n shortHash := hex.EncodeToString(hash[:4]) // 8 hex chars\n return fmt.Sprintf(\"%s-%s\", prefix, shortHash)\n}\n```\n\n## For Child Issues\n```go\nfunc (s *SQLiteStorage) createChildIssue(parentID string, issue *types.Issue) error {\n // Validate parent exists and depth \u003c= 3\n childNum := s.getNextChildID(parentID)\n issue.ID = fmt.Sprintf(\"%s.%d\", parentID, childNum)\n // ... create issue\n}\n```\n\n## CLI Integration\n```bash\nbd create \"Auth System\" # → bd-a3f8e9a2\nbd create \"Login Flow\" --parent a3f8e9 # → bd-a3f8e9a2.1\nbd create \"Design UI\" --parent a3f8e9.1 # → bd-a3f8e9a2.1.1\n```\n\n## Validation\n- Reject depth \u003e 3\n- Ensure parent exists\n- Check parent is epic type (optional, for UX)","notes":"Work completed on feature/hash-ids branch. Reverted from main to avoid breaking changes. Will merge after migration strategy (bd-173) is ready.","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-29T21:24:29.412237-07:00","updated_at":"2025-10-30T14:17:14.485149-07:00","dependencies":[{"issue_id":"bd-168","depends_on_id":"bd-165","type":"parent-child","created_at":"2025-10-29T21:24:29.413417-07:00","created_by":"stevey"},{"issue_id":"bd-168","depends_on_id":"bd-166","type":"blocks","created_at":"2025-10-29T21:24:29.413823-07:00","created_by":"stevey"}]} {"id":"bd-169","content_hash":"c27f166d842efb8caa1c104b1eaf430e430b3da84cfb13a085cc732a713faaf9","title":"Update JSONL format to use hash IDs","description":"Update JSONL format to store hierarchical hash-based IDs.\n\n## Changes\n- ID field: bd-af78e9a2 (top-level) or bd-af78e9a2.1.2 (hierarchical)\n- No alias field needed (removed from original plan)\n- All other fields remain the same\n\n## Example\n```json\n{\"id\":\"bd-af78e9a2\",\"title\":\"Auth System\",\"type\":\"epic\",...}\n{\"id\":\"bd-af78e9a2.1\",\"title\":\"Login Flow\",\"type\":\"epic\",...}\n{\"id\":\"bd-af78e9a2.1.1\",\"title\":\"Design UI\",\"type\":\"task\",...}\n```\n\n## Benefits\n- Hierarchical structure visible in JSONL\n- Git merge conflicts reduced (different IDs = different lines)\n- Easy to grep for epic children: grep \"bd-af78e9a2\\.\" issues.jsonl\n\n## Backward Compatibility\nMigration tool will convert bd-1 → bd-{hash} with mapping preserved.","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-29T21:24:47.408106-07:00","updated_at":"2025-10-30T00:25:26.029456-07:00","dependencies":[{"issue_id":"bd-169","depends_on_id":"bd-165","type":"parent-child","created_at":"2025-10-29T21:24:47.409489-07:00","created_by":"stevey"},{"issue_id":"bd-169","depends_on_id":"bd-168","type":"blocks","created_at":"2025-10-29T21:24:47.409977-07:00","created_by":"stevey"},{"issue_id":"bd-169","depends_on_id":"bd-167","type":"blocks","created_at":"2025-10-29T21:29:45.975499-07:00","created_by":"stevey"}]} {"id":"bd-17","content_hash":"404b82a19dde2fdece7eb6bb3b816db7906e81a03a5a05341ed631af7a2a8e87","title":"Remove unreachable RPC methods","description":"Several RPC server and client methods are unreachable and should be removed:\n\nServer methods (internal/rpc/server.go):\n- `Server.GetLastImportTime` (line 2116)\n- `Server.SetLastImportTime` (line 2123)\n- `Server.findJSONLPath` (line 2255)\n\nClient methods (internal/rpc/client.go):\n- `Client.Import` (line 311) - RPC import not used (daemon uses autoimport)\n\nEvidence:\n```bash\ngo run golang.org/x/tools/cmd/deadcode@latest -test ./...\n```\n\nImpact: Removes ~80 LOC of unused RPC code","acceptance_criteria":"- Remove the 4 unreachable methods (~80 LOC total)\n- Verify no callers: `grep -r \"GetLastImportTime\\|SetLastImportTime\\|findJSONLPath\" .`\n- All tests pass: `go test ./internal/rpc/...`\n- Daemon functionality works: test daemon start/stop/operations","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-27T20:30:19.962209-07:00","updated_at":"2025-10-28T16:07:26.103703-07:00","closed_at":"2025-10-28T16:07:26.103703-07:00","labels":["cleanup","dead-code","phase-1","rpc"],"dependencies":[{"issue_id":"bd-17","depends_on_id":"bd-26","type":"parent-child","created_at":"2025-10-27T20:30:19.965239-07:00","created_by":"daemon"}]} {"id":"bd-170","content_hash":"9a2120c5d56a818ae4d0b2acc3518b6705d62b6cb866703dd524e3bc1a462397","title":"CLI accepts hash ID prefixes (Git-style)","description":"Implement prefix-optional parsing for hash IDs throughout CLI.\n\n## Parsing Logic\n```go\n// internal/utils/id_parser.go\nfunc ParseIssueID(input string) (issueID string, err error) {\n // Already has prefix: bd-a3f8e9 or bd-a3f8e9.1.2\n if strings.HasPrefix(input, \"bd-\") {\n return input, nil\n }\n \n // Add prefix: a3f8e9 → bd-a3f8e9\n // Works with hierarchical too: a3f8e9.1.2 → bd-a3f8e9.1.2\n return \"bd-\" + input, nil\n}\n\n// Prefix matching for partial IDs\nfunc ResolvePartialID(input string) (fullID string, err error) {\n parsedID := ParseIssueID(input) // Ensure prefix\n \n // Query with LIKE for prefix match\n matches := storage.FindByPrefix(parsedID)\n \n if len(matches) == 0 {\n return \"\", fmt.Errorf(\"no issue found matching %q\", input)\n }\n if len(matches) \u003e 1 {\n return \"\", fmt.Errorf(\"ambiguous ID %q matches: %v\", input, matches)\n }\n return matches[0].ID, nil\n}\n```\n\n## Behavior Examples\n```bash\n# All these inputs work:\nbd show a3f8e9 # Add prefix → bd-a3f8e9\nbd show bd-a3f8e9 # Already has prefix\nbd show a3f8 # Shorter prefix match\nbd show a3f8e9.1 # Hierarchical without prefix\nbd show bd-a3f8e9.1.2 # Full hierarchical with prefix\n\n# Output always shows full ID with prefix:\nbd-a3f8e9 [epic] Auth System\nbd-a3f8e9.1 [epic] Login Flow\nbd-a3f8e9.1.2 [task] Backend validation\n```\n\n## Error Handling\n```bash\n# Not found\n$ bd show xyz789\nError: no issue found matching \"bd-xyz789\"\n\n# Ambiguous (multiple matches)\n$ bd show a3\nError: ambiguous ID \"bd-a3\" matches: bd-a3f8e9, bd-a34721, bd-a38f92\nUse more characters to disambiguate.\n```\n\n## Commands to Update\nAll commands that accept issue IDs:\n\n### Read operations\n- bd show \u003cid\u003e\n- bd list --id \u003cids\u003e\n- bd dep tree \u003cid\u003e\n\n### Write operations\n- bd update \u003cid\u003e\n- bd close \u003cid\u003e\n- bd reopen \u003cid\u003e\n- bd label add \u003cid\u003e\n- bd dep add \u003cid1\u003e \u003cid2\u003e\n- bd comment add \u003cid\u003e\n\n### Multiple IDs\n```bash\n# All work with optional prefix:\nbd show a3f8e9 b7c2d1 # → bd-a3f8e9 bd-b7c2d1\nbd dep add a3f8e9.1 b7c2d1 # → bd-a3f8e9.1 blocks bd-b7c2d1\n```\n\n## Display Format\n**Always show full ID with prefix** in output for:\n- Copy-paste clarity\n- External reference (git commits, docs)\n- Unambiguous identification\n\n```bash\n$ bd list\nbd-a3f8e9 [P1] Auth System [epic] open\nbd-b7c2d1 [P2] Fix daemon crash [bug] open\nbd-1a2b3c4d [P3] Add logging [task] open\n```\n\n## Files to Create/Modify\n- internal/utils/id_parser.go (new - parsing logic)\n- cmd/bd/show.go\n- cmd/bd/update.go\n- cmd/bd/close.go\n- cmd/bd/reopen.go\n- cmd/bd/dep.go\n- cmd/bd/label.go\n- cmd/bd/comment.go\n- cmd/bd/list.go\n\n## Testing\n- Test prefix omitted: a3f8e9 → bd-a3f8e9\n- Test prefix included: bd-a3f8e9 → bd-a3f8e9\n- Test hierarchical: a3f8e9.1.2 → bd-a3f8e9.1.2\n- Test partial match: a3f8 → bd-a3f8e9\n- Test ambiguous ID error\n- Test not found error\n- Test mixed input: bd show a3f8e9 bd-b7c2d1","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-29T21:25:06.256317-07:00","updated_at":"2025-10-30T00:32:47.510446-07:00","dependencies":[{"issue_id":"bd-170","depends_on_id":"bd-165","type":"parent-child","created_at":"2025-10-29T21:25:06.257796-07:00","created_by":"stevey"},{"issue_id":"bd-170","depends_on_id":"bd-167","type":"blocks","created_at":"2025-10-29T21:25:06.258307-07:00","created_by":"stevey"},{"issue_id":"bd-170","depends_on_id":"bd-169","type":"blocks","created_at":"2025-10-29T21:29:45.993274-07:00","created_by":"stevey"}]}