chore: Remove work-tracking markdown files, dogfood beads

- 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 <noreply@anthropic.com>
2025-10-14 19:21:57 -07:00
parent 01b606fe7b
commit 00c324e797
3 changed files with 7 additions and 573 deletions
--- a/.beads/bd-9-design.md
+++ b/.beads/bd-9-design.md
@@ -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.
--- 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
+We dogfood beads for all project tracking! For current work and roadmap, see:
- [ ] Project setup (go.mod, directory structure)
+- `bd list` - All tracked issues
- [ ] Data model (types, interfaces)
+- `bd ready` - Available work
- [ ] SQLite storage implementation
+- `.beads/issues.jsonl` - Full issue database
 - [ ] Basic CLI (create, list, show, update, close)
 - [ ] Dependency management (add, remove, tree)
 - [ ] Ready work detection
 - [ ] Tests
-### Phase 2: Polish & Features
+The project is mature and feature-complete for 1.0. Most core features are implemented.
 - [ ] 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
 ---
@@ -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. 🔗✨
--- a/TESTING_NEXT.md
+++ b/TESTING_NEXT.md
@@ -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! 🚀