johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add command documentation and improve daemon UX

Browse Source 
- Added human-readable uptime formatting (51m 59s vs 3119.4 seconds)
- Fixed daemon stop race condition with SIGKILL
- Added markdown docs for 19 commands: blocked, comments, compact, daemon,
  delete, dep, epic, export, import, label, list, quickstart, rename-prefix,
  renumber, reopen, repos, restore, stale, sync
- Closed: bd-159, bd-152, bd-168
- Deleted test issues: bd-144, bd-145

Amp-Thread-ID: https://ampcode.com/threads/T-9f7c3fed-62de-4bcd-a059-8c1b77cdb841
Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
2025-10-19 22:24:14 -07:00
parent 581ea11a7c
commit 7658c4a8e8
21 changed files with 560 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
.beads/issues.jsonl
View File

@@ -48,8 +48,6 @@
{"id":"bd-141","title":"Add daemon RPC support for comments and label subcommands","description":"The 'bd comments' and 'bd label' subcommands don't work in direct mode because they don't inherit PersistentPreRun from root command. Need to add daemon RPC handlers similar to how show/update/create work.\n\nAffected commands:\n- bd comments \u003cid\u003e\n- bd comments add \u003cid\u003e \"text\"\n- bd label list \u003cid\u003e\n- bd label add \u003cid\u003e \u003clabel\u003e\n- bd label remove \u003cid\u003e \u003clabel\u003e\n\nSolution: Add RPC handlers in daemon.go for these operations and update the CLI commands to use daemon RPC when available (check daemonClient != nil pattern used in other commands).","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-10-19T16:08:42.16553-07:00","updated_at":"2025-10-19T21:14:12.233179-07:00","closed_at":"2025-10-19T21:14:12.233179-07:00"}
{"id":"bd-142","title":"MCP server workspace routing broken - using wrong server for workspace","description":"When working in ~/src/beads, AI agent is calling mcp__beads-wyvern__* functions which are configured for ~/wyvern workspace. This causes MCP commands to fail or operate on wrong database.\n\nExpected: Should use correct MCP server based on current workspace\nActual: Using beads-wyvern MCP server when in beads repo\n\nNeed to investigate:\n- How MCP server routing/selection works\n- Why wrong server is being selected\n- How to fix workspace detection","notes":"Root cause: Using multiple MCP servers (beads-adar, beads-wyvern, beads-vc, beads) instead of single MCP server with global daemon. AI randomly selects wrong server for workspace.\n\nFixed:\n1. Started global daemon: bd daemon --global\n2. Simplified config to single MCP server in ~/.config/amp/settings.json\n3. Updated AGENTS.md to emphasize single MCP server as RECOMMENDED approach\n4. Marked legacy multiple-server approach with warning about workspace routing issues\n\nUser needs to restart Amp for config changes to take effect.","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-10-19T18:32:04.513755-07:00","updated_at":"2025-10-19T20:52:23.598206-07:00","closed_at":"2025-10-19T18:35:00.167234-07:00"}
{"id":"bd-143","title":"Renumber command fails with foreign key constraint error","description":"When running 'bd renumber --force' after deleting issues, the command fails with: 'failed to rename bd-73 to temp ID: failed to update issue ID: constraint failed: FOREIGN KEY constraint failed (787)'. This suggests the renumber implementation doesn't properly handle foreign key constraints during the ID swap process. May need to disable foreign keys temporarily or use a different renumbering strategy.","notes":"Deeper investigation: All child tables (dependencies, labels, events, dirty_issues, issue_snapshots, compaction_snapshots, comments) have FK constraints to issues(id) ON DELETE CASCADE. When renumbering tries to UPDATE issues SET id = temp-uuid WHERE id = bd-32, the FK checks fire immediately despite PRAGMA foreign_keys = OFF being called. Issue might be that Go sql.DB connection pooling means the PRAGMA isn't applied to the actual connection doing the UPDATE. Testing with explicit connection (s.db.Conn()) to ensure PRAGMA sticks.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-19T19:33:20.324768-07:00","updated_at":"2025-10-19T20:52:23.598384-07:00","closed_at":"2025-10-19T19:35:57.175627-07:00"}
{"id":"bd-144","title":"Concurrent test issue 2","description":"","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-19T19:51:16.598972-07:00","updated_at":"2025-10-19T20:52:23.598558-07:00"}
{"id":"bd-145","title":"Concurrent test issue 1","description":"","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-19T19:51:16.670081-07:00","updated_at":"2025-10-19T20:52:23.598726-07:00"}
{"id":"bd-146","title":"Single-user issue","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T19:51:36.918878-07:00","updated_at":"2025-10-19T20:52:23.598889-07:00"}
{"id":"bd-147","title":"Direct mode test","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T19:52:19.768858-07:00","updated_at":"2025-10-19T20:52:23.599056-07:00"}
{"id":"bd-148","title":"Direct mode test2","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T19:52:25.87028-07:00","updated_at":"2025-10-19T20:52:23.599218-07:00"}
@@ -57,14 +55,14 @@
{"id":"bd-15","title":"Implement full cross-type cycle prevention in AddDependency","description":"Expand cycle prevention in AddDependency to check for cycles across ALL dependency types, not just 'blocks'. Currently only 'blocks' type dependencies are checked for cycles, allowing cross-type circular dependencies to form (e.g., A blocks B, B parent-child A). This can cause semantic confusion and is a maintenance hazard for future operations that traverse dependencies.","design":"Implementation approach:\n1. Modify the cycle check in AddDependency (postgres.go:559-599)\n2. Remove the 'type = blocks' filter from the recursive CTE\n3. Check for cycles regardless of dependency type being added\n4. Return a clear error message indicating which types form the cycle\n\nTrade-offs to consider:\n- This is more mathematically correct (no cycles in dependency DAG)\n- May break legitimate use cases where cross-type cycles are intentional\n- Need to evaluate whether ANY cross-type cycles are valid in practice\n- Alternative: make this configurable with a --allow-cycle flag\n\nBefore implementing, should investigate:\n- Are there legitimate reasons for cross-type cycles?\n- What's the performance impact on large graphs (1000+ issues)?\n- Should certain type combinations be allowed to cycle?","acceptance_criteria":"- AddDependency prevents cycles across all dependency types, not just 'blocks'\n- Clear error message when cycle would be created, including dependency types\n- All existing tests pass\n- Performance benchmarked on large dependency graphs (100+ issues)\n- Decision documented on whether to add --allow-cycle flag or exception rules","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.599577-07:00","closed_at":"2025-10-16T20:31:19.174534-07:00"}
{"id":"bd-150","title":"Direct mode test clean","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T19:52:56.4305-07:00","updated_at":"2025-10-19T20:52:23.600206-07:00"}
{"id":"bd-151","title":"Multi-repo daemon routing fails in testing","description":"Test 4 from DAEMON_ARCHITECTURE.md showed daemon starts but doesn't route requests correctly to multi-repo databases. When running bd list in repo A after creating an issue, it shows 0 issues. Debug output shows 'daemon socket not ready after 5 seconds' despite daemon process running.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-19T20:01:18.977976-07:00","updated_at":"2025-10-19T20:52:23.600406-07:00","closed_at":"2025-10-19T20:07:40.203797-07:00"}
{"id":"bd-152","title":"Daemon stop has race condition with SIGKILL","description":"When stopping daemon, sometimes see 'Warning: daemon did not stop after 5 seconds, sending SIGKILL' followed by 'Error killing process: os: process already finished'. Indicates timing issue where process exits between check and kill.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-10-19T20:01:18.979589-07:00","updated_at":"2025-10-19T20:52:23.600571-07:00"}
{"id":"bd-152","title":"Daemon stop has race condition with SIGKILL","description":"When stopping daemon, sometimes see 'Warning: daemon did not stop after 5 seconds, sending SIGKILL' followed by 'Error killing process: os: process already finished'. Indicates timing issue where process exits between check and kill.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-10-19T20:01:18.979589-07:00","updated_at":"2025-10-19T21:49:35.916052-07:00","closed_at":"2025-10-19T21:49:35.916052-07:00"}
{"id":"bd-153","title":"Implement storage cache eviction and memory limits","description":"Implement LRU cache eviction and memory pressure detection for daemon storage cache to prevent unbounded memory growth.","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-19T20:13:59.761129-07:00","updated_at":"2025-10-19T20:52:23.600736-07:00","closed_at":"2025-10-19T20:14:24.888631-07:00"}
{"id":"bd-154","title":"Clean up MCP integration for daemon reliability","description":"Ensure MCP server properly handles daemon lifecycle, connection failures, and recovery scenarios.","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-19T20:13:59.764086-07:00","updated_at":"2025-10-19T20:52:23.600903-07:00","closed_at":"2025-10-19T20:15:11.006871-07:00"}
{"id":"bd-155","title":"Add daemon health checks and monitoring","description":"Add health check endpoint that validates daemon state, storage connections, and resource usage.","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-19T20:13:59.764154-07:00","updated_at":"2025-10-19T20:52:23.601114-07:00","closed_at":"2025-10-19T20:14:38.291678-07:00"}
{"id":"bd-156","title":"Implement daemon crash recovery and restart","description":"Detect stale daemon processes, clean up orphaned resources, and auto-restart daemon after crashes.","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-19T20:13:59.766856-07:00","updated_at":"2025-10-19T20:52:23.601346-07:00","closed_at":"2025-10-19T20:15:02.211576-07:00"}
{"id":"bd-157","title":"Implement resource limits and connection pooling","description":"Add configurable limits for connections, file descriptors, and memory usage.","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T20:13:59.768745-07:00","updated_at":"2025-10-19T20:52:23.601547-07:00"}
{"id":"bd-158","title":"Add daemon telemetry and metrics","description":"Track and report daemon metrics: request count, latency, cache hits/misses, error rates.","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T20:13:59.77094-07:00","updated_at":"2025-10-19T20:52:23.601784-07:00"}
{"id":"bd-159","title":"Improve daemon visibility and status reporting","description":"Add clear daemon status output, uptime reporting, and user-friendly error messages.","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-19T20:13:59.772435-07:00","updated_at":"2025-10-19T20:52:23.602042-07:00"}
{"id":"bd-159","title":"Improve daemon visibility and status reporting","description":"Add clear daemon status output, uptime reporting, and user-friendly error messages.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-19T20:13:59.772435-07:00","updated_at":"2025-10-19T21:44:50.340047-07:00","closed_at":"2025-10-19T21:44:50.340047-07:00"}
{"id":"bd-16","title":"Refactor duplicate flush logic in PersistentPostRun","description":"PersistentPostRun contains a complete copy of the flush logic instead of calling flushToJSONL(). This violates DRY principle and makes maintenance harder. Refactor to use flushToJSONL() with a force parameter to bypass isDirty check, or extract shared logic into a helper function. Located in cmd/bd/main.go:104-138.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.602241-07:00","closed_at":"2025-10-18T09:44:24.167574-07:00"}
{"id":"bd-160","title":"Add daemon/client version compatibility checks","description":"Verify daemon and client versions are compatible before allowing connections.","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-19T20:13:59.774304-07:00","updated_at":"2025-10-19T20:52:23.602618-07:00"}
{"id":"bd-161","title":"Enhance label functionality and documentation","description":"Improve beads label system to support cross-cutting concerns and contextual metadata beyond structured fields (status, priority, type).\n\nCurrent state: Basic label storage exists (labels table, Add/GetLabels methods)\nTarget state: Full label lifecycle management with CLI, filtering, automation, and documentation\n\nCore principles:\n- Labels for cross-cutting concerns (technical metadata, scope, effort, quality gates)\n- Structured fields for workflow state (status, priority, type remain primary)\n- Multi-dimensional tagging without schema changes\n\nSee removed LABELS.md for detailed use cases and design rationale.","status":"open","priority":2,"issue_type":"epic","created_at":"2025-10-19T20:45:24.163728-07:00","updated_at":"2025-10-19T20:52:23.602796-07:00"}
@@ -74,6 +72,7 @@
{"id":"bd-165","title":"Document label best practices and use cases","description":"Create documentation covering:\n- When to use labels vs structured fields\n- Common label sets (coding agents, open source, product dev, SRE)\n- Naming conventions (kebab-case, specificity, present tense)\n- Anti-patterns (too many labels, overlapping, personal labels)\n- Label lifecycle management\n\nContent from LABELS.md analysis document.","status":"open","priority":3,"issue_type":"task","created_at":"2025-10-19T20:45:36.867864-07:00","updated_at":"2025-10-19T20:52:23.603503-07:00"}
{"id":"bd-166","title":"Implement label CLI commands (add, remove, list)","description":"Add CLI commands for label management:\n- bd label add \u003cissue\u003e \u003clabel...\u003e\n- bd label remove \u003cissue\u003e \u003clabel...\u003e\n- bd label list \u003cissue\u003e\n- bd labels (list all labels in use)\n\nBackend already has AddLabel/GetLabels/RemoveLabel methods in storage layer.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-19T20:49:44.344807-07:00","updated_at":"2025-10-19T21:14:12.231668-07:00","closed_at":"2025-10-19T21:14:12.231668-07:00"}
{"id":"bd-167","title":"MCP server tools should accept workspace_root parameter","description":"","design":"After set_context is called, Amp appears to inject workspace_root as a parameter to subsequent tool calls. The beads-mcp server should accept this parameter (likely ignore it or map it to working_dir) to avoid errors.","notes":"Oracle review found two additional issues: 1) Missing workspace_root on where_am_i tool, 2) set_context should always set env vars even when DB not found (so init works right after). Both fixed.","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-10-19T21:17:06.93365-07:00","updated_at":"2025-10-19T21:36:07.030443-07:00","closed_at":"2025-10-19T21:29:38.326609-07:00"}
{"id":"bd-168","title":"Update commands/ directory with new commands (comments, labels, etc)","description":"The commands/ directory contains documentation for bd commands, but several new commands have been added that aren't documented there yet: 'comments', 'labels', and possibly others. Need to audit what's missing and add documentation.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-19T21:54:04.65288-07:00","updated_at":"2025-10-19T21:57:28.943347-07:00","closed_at":"2025-10-19T21:57:28.943347-07:00"}
{"id":"bd-17","title":"Test issue with explicit ID","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.603831-07:00","closed_at":"2025-10-16T10:07:34.124331-07:00"}
{"id":"bd-18","title":"Critical bug","description":"","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.604005-07:00","closed_at":"2025-10-14T14:16:08.107546-07:00"}
{"id":"bd-19","title":"Verify auto-export works","description":"","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.604167-07:00","closed_at":"2025-10-14T14:16:09.268591-07:00"}