From 00c324e797b81943e85a269b82d2e3af60791b1c Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Tue, 14 Oct 2025 19:21:57 -0700 Subject: [PATCH] chore: Remove work-tracking markdown files, dogfood beads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove TESTING_NEXT.md (content tracked in bd-64) - Remove .beads/bd-9-design.md (designs belong in issue design field) - Update DESIGN.md: replace Implementation Roadmap with pointer to bd list - All work tracking now in beads database, not markdown files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .beads/bd-9-design.md | 303 ------------------------------------------ DESIGN.md | 54 +------- TESTING_NEXT.md | 223 ------------------------------- 3 files changed, 7 insertions(+), 573 deletions(-) delete mode 100644 .beads/bd-9-design.md delete mode 100644 TESTING_NEXT.md diff --git a/.beads/bd-9-design.md b/.beads/bd-9-design.md deleted file mode 100644 index 2cda8f3c..00000000 --- a/.beads/bd-9-design.md +++ /dev/null @@ -1,303 +0,0 @@ -# BD-9: Collision Resolution Design Document - -**Status**: In progress, design complete, ready for implementation -**Date**: 2025-10-12 -**Issue**: bd-9 - Build collision resolution tooling for distributed branch workflows - -## Problem Statement - -When branches diverge and both create issues, auto-incrementing IDs collide on merge: -- Branch A creates bd-10, bd-11, bd-12 -- Branch B (diverged) creates bd-10, bd-11, bd-12 (different issues!) -- On merge: 6 issues, but 3 duplicate IDs -- References to "bd-10" in descriptions/dependencies are now ambiguous - -## Design Goals - -1. **Preserve brevity** - Keep bd-302 format, not bd-302-branch-a-uuid-mess -2. **Minimize disruption** - Renumber issues with fewer references -3. **Update all references** - Text fields AND dependency table -4. **Atomic operation** - All or nothing -5. **Clear feedback** - User must understand what changed - -## Algorithm Design - -### Phase 1: Collision Detection - -``` -Input: JSONL issues + current DB state -Output: Set of colliding issues - -for each issue in JSONL: - if DB contains issue.ID: - if DB issue == JSONL issue: - skip (already imported, idempotent) - else: - mark as COLLISION -``` - -### Phase 2: Reference Counting (The Smart Part) - -Renumber issues with FEWER references first because: -- If bd-10 is referenced 20 times and bd-11 once -- Renumbering bd-11→bd-15 updates 1 reference -- Renumbering bd-10→bd-15 updates 20 references - -``` -for each colliding_issue: - score = 0 - - // Count text references in OTHER issues - for each other_issue in JSONL: - score += count_mentions(other_issue.all_text, colliding_issue.ID) - - // Count dependency references - deps = DB.get_dependents(colliding_issue.ID) // who depends on me? - score += len(deps) - - // Store score - collision_scores[colliding_issue.ID] = score - -// Sort ascending: lowest score = fewest references = renumber first -sorted_collisions = sort_by(collision_scores) -``` - -### Phase 3: ID Allocation - -``` -id_mapping = {} // old_id -> new_id -next_num = DB.get_next_id_number() - -for collision in sorted_collisions: - // Find next available ID - while true: - candidate = f"{prefix}-{next_num}" - if not DB.exists(candidate) and candidate not in id_mapping.values(): - id_mapping[collision.ID] = candidate - next_num++ - break - next_num++ -``` - -### Phase 4: Reference Updates - -This is the trickiest part - must update: -1. Issue IDs themselves -2. Text field references (description, design, notes, acceptance_criteria) -3. Dependency records (when they reference old IDs) - -``` -updated_issues = [] -reference_update_count = 0 - -for issue in JSONL: - new_issue = clone(issue) - - // 1. Update own ID if it collided - if issue.ID in id_mapping: - new_issue.ID = id_mapping[issue.ID] - - // 2. Update text field references - for old_id, new_id in id_mapping: - for field in [title, description, design, notes, acceptance_criteria]: - if field: - pattern = r'\b' + re.escape(old_id) + r'\b' - new_text, count = re.subn(pattern, new_id, field) - field = new_text - reference_update_count += count - - updated_issues.append(new_issue) -``` - -### Phase 5: Dependency Handling - -**Approach A: Export dependencies in JSONL** (PREFERRED) -- Extend export to include `"dependencies": [{...}]` per issue -- Import dependencies along with issues -- Update dependency records during phase 4 - -Why preferred: -- Self-contained JSONL (better for git workflow) -- Easier to reason about -- Can detect cross-file dependencies - -### Phase 6: Atomic Import - -``` -transaction: - for issue in updated_issues: - if issue.ID was remapped: - DB.create_issue(issue) - else: - DB.upsert_issue(issue) - - // Update dependency table - for issue in updated_issues: - for dep in issue.dependencies: - // dep IDs already updated in phase 4 - DB.create_or_update_dependency(dep) - - commit -``` - -### Phase 7: User Reporting - -``` -report = { - collisions_detected: N, - remappings: [ - "bd-10 → bd-15 (Score: 3 references)", - "bd-11 → bd-16 (Score: 15 references)", - ], - text_updates: M, - dependency_updates: K, -} -``` - -## Edge Cases - -1. **Chain dependencies**: bd-10 depends on bd-11, both collide - - Sorted renumbering handles this naturally - - Lower-referenced one renumbered first - -2. **Circular dependencies**: Shouldn't happen (DB has cycle detection) - -3. **Partial ID matches**: "bd-1" shouldn't match "bd-10" - - Use word boundary regex: `\bbd-10\b` - -4. **Case sensitivity**: IDs are case-sensitive (bd-10 ≠ BD-10) - -5. **IDs in code blocks**: Will be replaced - - Could add `--preserve-code-blocks` flag later - -6. **Triple merges**: Branch A, B, C all create bd-10 - - Algorithm handles N collisions - -7. **Dependencies pointing to DB-only issues**: - - JSONL issue depends on bd-999 (only in DB) - - No collision, works fine - -## Performance Considerations - -- O(N*M) for reference counting (N issues × M collisions) -- For 1000 issues, 10 collisions: 10,000 text scans -- Acceptable for typical use (hundreds of issues) -- Could optimize with index/trie if needed - -## API Design - -```bash -# Default: fail on collision (safe) -bd import -i issues.jsonl -# Error: Collision detected: bd-10 already exists - -# With auto-resolution -bd import -i issues.jsonl --resolve-collisions -# Resolved 3 collisions: -# bd-10 → bd-15 (3 refs) -# bd-11 → bd-16 (1 ref) -# bd-12 → bd-17 (7 refs) -# Imported 45 issues, updated 23 references - -# Dry run (preview changes) -bd import -i issues.jsonl --resolve-collisions --dry-run -``` - -## Implementation Breakdown - -### Child Issues to Create - -1. **bd-10**: Extend export to include dependencies in JSONL - - Modify export.go to include dependencies array - - Format: `{"id":"bd-10","dependencies":[{"depends_on_id":"bd-5","type":"blocks"}]}` - - Priority: 1, Type: task - -2. **bd-11**: Implement collision detection in import - - Create collision.go with detectCollisions() function - - Compare incoming JSONL against DB state - - Distinguish: exact match (skip), collision (flag), new (create) - - Priority: 1, Type: task - -3. **bd-12**: Implement reference scoring algorithm - - Count text mentions + dependency references - - Sort collisions by score ascending (fewest refs first) - - Minimize total updates during renumbering - - Priority: 1, Type: task - -4. **bd-13**: Implement ID remapping with reference updates - - Allocate new IDs for colliding issues - - Update text field references with word-boundary regex - - Update dependency records - - Build id_mapping for reporting - - Priority: 1, Type: task - -5. **bd-14**: Add --resolve-collisions flag and user reporting - - Add import flags: --resolve-collisions, --dry-run - - Display clear report with remappings and counts - - Default: fail on collision (safe) - - Priority: 1, Type: task - -6. **bd-15**: Write comprehensive collision resolution tests - - Test cases: simple/multiple collisions, dependencies, text refs - - Edge cases: partial matches, case sensitivity, triple merges - - Add to import_test.go and collision_test.go - - Priority: 1, Type: task - -7. **bd-16**: Update documentation for collision resolution - - Update README.md with collision resolution section - - Update CLAUDE.md with new workflow - - Document flags and example scenarios - - Priority: 1, Type: task - -### Additional Issue: Add Design Field Support - -**NEW ISSUE**: Add design field to bd update command -- Currently: `bd update` doesn't support --design flag (discovered during work) -- Need: Allow updating design, notes, acceptance_criteria fields -- This would make bd-9's design easier to attach to the issue itself -- Priority: 2, Type: feature - -## Current State - -- bd-9 is in_progress (claimed) -- bd-10 was successfully created (first child issue) -- bd-11+ creation failed with UNIQUE constraint (collision!) - - This demonstrates the exact problem we're solving - - Need to manually create remaining issues with different IDs - - Or implement collision resolution first! (chicken/egg) - -## Data Structures Involved - -- **Issues table**: id, title, description, design, notes, acceptance_criteria, status, priority, issue_type, assignee, estimated_minutes, created_at, updated_at, closed_at -- **Dependencies table**: issue_id, depends_on_id, type, created_at, created_by -- **Text fields with ID references**: description, design, notes, acceptance_criteria (title too?) - -## Files to Modify - -1. `cmd/bd/export.go` - Add dependency export -2. `cmd/bd/import.go` - Call collision resolution -3. `cmd/bd/collision.go` - NEW FILE - Core algorithm -4. `cmd/bd/collision_test.go` - NEW FILE - Tests -5. `internal/types/types.go` - May need collision report types -6. `README.md` - Documentation -7. `CLAUDE.md` - AI agent workflow docs - -## Next Steps - -1. ✅ Design complete -2. 🔄 Create child issues (bd-10 created, bd-11+ need different IDs) -3. ⏳ Implement Phase 1: Export enhancement -4. ⏳ Implement Phase 2-7: Core algorithm -5. ⏳ Tests -6. ⏳ Documentation -7. ⏳ Export issues to JSONL before committing - -## Meta: Real Collision Encountered! - -While creating child issues, we hit the exact problem: -- bd-10 was created successfully -- bd-11, bd-12, bd-13, bd-14, bd-15, bd-16 all failed with "UNIQUE constraint failed" -- This means the DB already has bd-11+ from a previous session/import -- Perfect demonstration of why we need collision resolution! - -Resolution: Create remaining child issues manually with explicit IDs after checking what exists. diff --git a/DESIGN.md b/DESIGN.md index 9845f32c..9ea728b3 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -58,7 +58,7 @@ graph TB style DB2 fill:#f5f5f5 ``` -**Current Status:** Only SQLite is implemented. PostgreSQL support is designed and planned for Phase 3 (see Implementation Roadmap below). +**Current Status:** Only SQLite is implemented. PostgreSQL support is tracked as bd-181 (storage driver interface). ### Entity Relationship Diagram @@ -874,40 +874,14 @@ actor: $USER --- -## Implementation Roadmap +## Current Status & Roadmap -### Phase 1: Core Foundation -- [ ] Project setup (go.mod, directory structure) -- [ ] Data model (types, interfaces) -- [ ] SQLite storage implementation -- [ ] Basic CLI (create, list, show, update, close) -- [ ] Dependency management (add, remove, tree) -- [ ] Ready work detection -- [ ] Tests +We dogfood beads for all project tracking! For current work and roadmap, see: +- `bd list` - All tracked issues +- `bd ready` - Available work +- `.beads/issues.jsonl` - Full issue database -### Phase 2: Polish & Features -- [ ] Labels support -- [ ] Comments and events -- [ ] Full-text search -- [ ] Cycle detection -- [ ] Statistics -- [ ] Colored CLI output -- [ ] JSON/YAML output formats - -### Phase 3: PostgreSQL -- [ ] PostgreSQL storage implementation -- [ ] Config file support -- [ ] Backend switching -- [ ] Migration utilities -- [ ] Performance optimization - -### Phase 4: Advanced -- [ ] Export/import -- [ ] GitHub/GitLab/Jira migration tools -- [ ] TUI (bubble tea?) -- [ ] Web UI (templ?) -- [ ] API server mode -- [ ] Multi-user workflows +The project is mature and feature-complete for 1.0. Most core features are implemented. --- @@ -1076,17 +1050,3 @@ Beads is successful if: 4. **Portability**: Database file can be moved between machines, checked into git 5. **Adoption**: Used by at least 3 other developers/teams within 6 months ---- - -## Next Steps - -1. Create `~/src/beads` directory structure -2. Initialize Go module -3. Implement core types (Issue, Dependency, Storage interface) -4. Build SQLite storage implementation -5. Build basic CLI (create, show, list) -6. Test with VibeCoder's issue data (export and import) -7. Iterate toward parity with scripts/issue.ts -8. Release v0.1.0 - -Let's build something beautiful. 🔗✨ diff --git a/TESTING_NEXT.md b/TESTING_NEXT.md deleted file mode 100644 index 7428fdfb..00000000 --- a/TESTING_NEXT.md +++ /dev/null @@ -1,223 +0,0 @@ -# Claude Code Plugin Testing - Handoff Document - -**Status**: Plugin implementation complete, ready for testing -**Date**: 2025-10-14 -**Session**: Plugin development and version management - -## What Was Completed This Session - -### 1. Claude Code Plugin (GitHub #28, bd-52) -✅ Created complete plugin structure in `.claude-plugin/`: -- `plugin.json` - Metadata with MCP server configuration -- `marketplace.json` - Local marketplace config -- 9 slash commands in `commands/` -- 1 agent in `agents/` - -✅ Slash commands implemented: -- `/bd-ready` - Find ready work -- `/bd-create` - Create issues interactively -- `/bd-show` - Show issue details -- `/bd-update` - Update issues -- `/bd-close` - Close issues -- `/bd-workflow` - Show workflow guide -- `/bd-init` - Initialize beads -- `/bd-stats` - Project statistics -- `/bd-version` - Version compatibility checking - -✅ Documentation: -- `PLUGIN.md` - Complete plugin documentation -- Updated `README.md` with plugin section -- Updated `examples/README.md` - -### 2. Version Management (bd-66, bd-67) -✅ Fixed version inconsistencies: -- All components synced to 0.9.2 -- bd CLI, Plugin, MCP server, README, PLUGIN.md - -✅ Created `scripts/bump-version.sh`: -- Automated version syncing across all files -- Validates semantic versioning -- Shows diff preview -- Auto-commit option - -✅ Updated `CLAUDE.md`: -- Added "Version Management" section -- Instructions for future agents on version bumps -- Common user phrases to recognize - -### 3. Code Review -✅ Comprehensive review identified and fixed: -- Commands were in wrong location (moved to `.claude-plugin/`) -- All issues addressed from review - -## What Needs Testing (bd-64) - -### Critical Tests - -1. **Plugin Installation** - ```bash - /plugin marketplace add steveyegge/beads - /plugin install beads - # Restart Claude Code - ``` - -2. **Slash Commands** - ```bash - /bd-version # Should show 0.9.2 - /bd-workflow # Show workflow - /bd-stats # Project stats - /bd-ready # Find work - /bd-create "Test" task 2 - ``` - -3. **MCP Server** - ```bash - /mcp # Verify 'beads' appears - ``` - -4. **Task Agent** - ```bash - @task-agent # If supported - ``` - -### Potential Issues to Watch For - -1. **MCP Server Path** - - Uses `${CLAUDE_PLUGIN_ROOT}` variable - - May need adjustment if not supported - -2. **Prerequisites** - - Requires `bd` CLI in PATH - - Requires `uv` for Python MCP server - -3. **Agent Syntax** - - Task agent syntax may differ from `@task-agent` - - May need adjustment based on Claude Code version - -## Important Files for Next Agent - -### Key Implementation Files -- `.claude-plugin/plugin.json` - Plugin metadata -- `.claude-plugin/commands/*.md` - All 9 slash commands -- `.claude-plugin/agents/task-agent.md` - Autonomous agent -- `PLUGIN.md` - Complete documentation -- `scripts/bump-version.sh` - Version management script - -### Key Documentation Files -- `CLAUDE.md` - **READ THIS FIRST** - Has version management instructions -- `PLUGIN.md` - Plugin user documentation -- `scripts/README.md` - Script documentation -- `bd-64` issue notes - Detailed testing instructions - -### Commit History (for context) -``` -a612b92 - docs: Add version management to CLAUDE.md -a5c71f0 - feat: Add version bump script -c0f1044 - fix: Sync all component versions to 0.9.2 -d25fc53 - feat: Add version compatibility checking -9f38375 - feat: Add Claude Code plugin for beads -``` - -## How to Continue - -### Immediate Next Steps -1. Read bd-64 notes (has complete testing instructions) -2. Install plugin from GitHub -3. Test all slash commands -4. Document any issues found -5. Fix issues or update documentation -6. Close bd-64 when testing complete - -### If Plugin Testing Succeeds -1. Update bd-64 with test results -2. Close bd-64 -3. Consider announcing plugin availability -4. Update PLUGIN.md if any corrections needed - -### If Plugin Testing Fails -1. Document specific failures in bd-64 -2. Create new issues for each problem -3. Link to bd-64 with `discovered-from` -4. Fix issues systematically -5. Retest - -## User Context - -The user (Steve) is working rapidly on beads, fixing "dozens of major bugs a day" (his words). He wants: - -1. **Version Management**: Clear process for version bumps - - Just say "bump to X.Y.Z" and agent should use script - - All versions must stay in sync - -2. **Plugin Testing**: Real-world GitHub installation test - - Not local, use `steveyegge/beads` marketplace - - Document any issues for iteration - -3. **Clean Handoffs**: Each session should leave clear instructions - - What was done - - What needs doing - - How to do it - -## Important Notes - -### Version Bumping -When user says any of: -- "Bump to 0.9.3" -- "Update version to X.Y.Z" -- "Rev the project to X.Y.Z" -- "Increment the version" - -**You should:** -```bash -./scripts/bump-version.sh X.Y.Z --commit -git push origin main -``` - -See CLAUDE.md "Version Management" section for details. - -### Plugin Development Status -- **Structure**: Complete ✅ -- **Implementation**: Complete ✅ -- **Documentation**: Complete ✅ -- **Testing**: Not started ⏳ -- **Release**: Pending testing results - -### Known Limitations -1. MCP server uses `${CLAUDE_PLUGIN_ROOT}` - may need verification -2. Task agent syntax untested -3. Plugin requires separate bd CLI installation -4. No icon for marketplace (nice-to-have) - -## Questions for Testing Agent - -While testing, please document: -1. Did plugin install successfully from GitHub? -2. Did all slash commands work? -3. Did MCP server connect? -4. Were there any error messages? -5. Is documentation accurate? -6. What needs improvement? - -## Success Criteria - -Plugin is ready for users when: -- ✅ Installs via `/plugin install beads` -- ✅ All 9 slash commands work -- ✅ MCP server connects and tools accessible -- ✅ Version checking works correctly -- ✅ Documentation is accurate -- ✅ No major bugs or blocking issues - -## Where We Are in the Bigger Picture - -This plugin work relates to: -- **GitHub Issue #28**: Claude Code plugin request -- **bd-52**: Main plugin epic (now complete) -- **bd-64**: Testing task (next up) -- **Goal**: Make beads easy to install and use in Claude Code - -The plugin leverages the existing MCP server (integrations/beads-mcp/) which is mature and tested. We're just packaging it nicely for Claude Code users. - ---- - -**Next Agent**: Start by reading bd-64 notes, then test the plugin from GitHub. Good luck! 🚀