From aadd21c40bc874b5f7c8d7179d8b8cb1773bb286 Mon Sep 17 00:00:00 2001 From: Isis Anisoptera Date: Fri, 17 Jul 2026 19:44:38 -0700 Subject: [PATCH] docs(cli): move the graph plan schema into an embedded doc supplement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The --graph schema section was hand-written into the generated docs/CLI_REFERENCE.md, which the byte-exact drift gate rejects and any regeneration (including the docs-autofix bot) would erase — breaking TestDocsGraphPlanExampleValidates. Long: strings can't carry it either: escapeMDXText would mangle the fenced JSON example. Add a command doc-supplement mechanism: raw Markdown embedded from cmd/bd/help_supplements/ and appended after a command's flags by the docs generator, so regeneration reproduces the section byte-for-byte in both CLI_REFERENCE.md and the per-command create.md page. Document the parent/estimate aliases and their precedence while moving the text. Regeneration also restores the four per-command pages (heartbeat, migrate-personal, reclaim, unclaim) that docs.json already listed but the committed tree was missing. Co-Authored-By: Claude Fable 5 --- cmd/bd/help_all.go | 5 ++ cmd/bd/help_supplements.go | 20 +++++ cmd/bd/help_supplements/create_graph_plan.md | 88 +++++++++++++++++++ docs/CLI_REFERENCE.md | 2 + docs/cli-reference/create.md | 89 ++++++++++++++++++++ docs/cli-reference/heartbeat.md | 33 ++++++++ docs/cli-reference/migrate-personal.md | 33 ++++++++ docs/cli-reference/reclaim.md | 37 ++++++++ docs/cli-reference/unclaim.md | 34 ++++++++ 9 files changed, 341 insertions(+) create mode 100644 cmd/bd/help_supplements.go create mode 100644 cmd/bd/help_supplements/create_graph_plan.md create mode 100644 docs/cli-reference/heartbeat.md create mode 100644 docs/cli-reference/migrate-personal.md create mode 100644 docs/cli-reference/reclaim.md create mode 100644 docs/cli-reference/unclaim.md diff --git a/cmd/bd/help_all.go b/cmd/bd/help_all.go index 1ac505587..4b8b7ae54 100644 --- a/cmd/bd/help_all.go +++ b/cmd/bd/help_all.go @@ -241,6 +241,11 @@ func writeCommandBody(w io.Writer, cmd *cobra.Command) { if localFlags.HasFlags() { fmt.Fprintf(w, "**Flags:**\n\n```\n%s```\n\n", localFlags.FlagUsages()) } + + // Embedded doc supplement (raw Markdown, no MDX escaping). + if sup, ok := commandDocSupplements[cmd.CommandPath()]; ok { + fmt.Fprintf(w, "%s\n\n", strings.TrimSpace(sup)) + } } // writeSingleCommandDoc generates one command's documentation page as generic diff --git a/cmd/bd/help_supplements.go b/cmd/bd/help_supplements.go new file mode 100644 index 000000000..9e971fe87 --- /dev/null +++ b/cmd/bd/help_supplements.go @@ -0,0 +1,20 @@ +package main + +import ( + _ "embed" +) + +// Command doc supplements are extra reference Markdown appended after a +// command's flags in the generated CLI docs (bd help --docs-root and the +// per-command staging tree). They are embedded sources, not hand edits: +// regeneration always reproduces them, so the docs drift gate stays +// byte-exact. Supplements are raw Markdown (fenced code allowed) and are +// emitted without MDX escaping — keep prose MDX-safe outside code fences. + +//go:embed help_supplements/create_graph_plan.md +var createGraphPlanSupplement string + +// commandDocSupplements maps a cobra CommandPath() to its supplement. +var commandDocSupplements = map[string]string{ + "bd create": createGraphPlanSupplement, +} diff --git a/cmd/bd/help_supplements/create_graph_plan.md b/cmd/bd/help_supplements/create_graph_plan.md new file mode 100644 index 000000000..b70cc4461 --- /dev/null +++ b/cmd/bd/help_supplements/create_graph_plan.md @@ -0,0 +1,88 @@ +**Graph plan schema (`--graph`):** + +`bd create --graph plan.json` creates a whole issue graph atomically from a +JSON plan. Node field names follow the issue model's JSON tags (the same +names `bd show --json` emits), and every field single-issue `bd create` can +set is addressable from a plan — plus an initial `status` and `pinned`, +which `bd create` has no flags for: + +```json +{ + "commit_message": "optional Dolt commit message", + "nodes": [ + { + "key": "api", + "title": "Design the API", + "type": "task", + "description": "…", "design": "…", "acceptance_criteria": "…", "notes": "…", + "status": "in_progress", + "priority": 1, + "assignee": "alice", "assign_after_create": false, + "owner": "alice@example.com", + "labels": ["backend"], + "estimated_minutes": 45, + "due_at": "2030-01-02T15:04:05Z", + "defer_until": "2030-01-01T00:00:00Z", + "spec_id": "bd-spec1", "external_ref": "gh-42", + "metadata": {"any": "json", "count": 3}, + "metadata_refs": {"tracker": "impl"}, + "id": "bd-a1b2c3", + "ephemeral": false, "no_history": false, + "wisp_type": "heartbeat", "mol_type": "swarm", + "pinned": false + }, + { "key": "impl", "title": "Implement it", "parent_key": "api" }, + { "key": "gate", "title": "Fanout gate" }, + { "key": "launch", "title": "Launch announced", "type": "event", + "event_kind": "agent.started", "actor": "agent://a", "target": "bead://b", "payload": "{}" } + ], + "edges": [ + { "from_key": "gate", "to_key": "api", "type": "blocks" }, + { "from_key": "gate", "to_key": "impl", "type": "waits-for", + "gate": "any-children", "spawner_key": "impl" } + ] +} +``` + +Node notes: + +- `key` is a plan-local symbolic name; the result maps each key to the minted + issue ID. `id` optionally pins an explicit issue ID instead (must match the + database prefix, like `bd create --id`). +- `parent_key` (a plan node key) or `parent_id` (an existing issue ID) adds a + `parent-child` dependency on the created node. +- `parent` and `estimate` are accepted aliases for `parent_key` and + `estimated_minutes`; the canonical field wins when both spellings are set. +- `status` sets the initial status (default `open`, or `deferred` when + `defer_until` is in the future). Nodes created `closed` get `closed_at` + auto-filled. Timestamps are RFC3339; relative forms like `+6h` are not + accepted in plans. +- `ephemeral` / `no_history` override the plan-wide `--ephemeral` / + `--no-history` flags per node (mutually exclusive per node; in + proxied-server mode the effective storage class must be uniform across the + plan). +- `event_kind`, `actor`, `target`, and `payload` require `"type": "event"`. +- `metadata` accepts arbitrary JSON values; `metadata_refs` values name other + node keys and are replaced with their minted IDs after creation. +- Unlike `bd create --parent`, graph children do not inherit parent labels + and receive flat (non-hierarchical) IDs; plans are explicit artifacts. + +Edge notes: + +- `type` defaults to `blocks`. `parent_key`/`parent_id` on nodes already + create `parent-child` edges; don't repeat them in `edges`. +- `gate` (`all-children` | `any-children`) and `spawner_key`/`spawner_id` + attach fanout-gate metadata to `waits-for` edges, mirroring + `--waits-for`/`--waits-for-gate`. The `to` endpoint of a `waits-for` edge + *is* the spawner (gate evaluation watches its children), so `spawner_key` + must match `to_key` and `spawner_id` must match `to_id`; they exist to make + plans self-documenting. Since an explicit `to_id` overrides `to_key` as the + target, `spawner_key` cannot be combined with `to_id` — use `spawner_id`. +- Edges with ready-work-affecting types (`blocks`, `waits-for`, …) may not + duplicate or reverse a `parent_key`/`parent_id` relationship, and a parent + may not be connected to its own child through them. +- `thread_id` threads conversation edges (e.g. `replies-to`). + +Comments cannot be created from a plan; use `bd comments add` after creation. +Model fields without `bd create` flags (`sender`, `work_type`, `is_template`, +`await_*`, `bonded_from`, `source_*`) are likewise not settable from plans. diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 5a691f974..ffaba1f03 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -572,6 +572,8 @@ Node notes: database prefix, like `bd create --id`). - `parent_key` (a plan node key) or `parent_id` (an existing issue ID) adds a `parent-child` dependency on the created node. +- `parent` and `estimate` are accepted aliases for `parent_key` and + `estimated_minutes`; the canonical field wins when both spellings are set. - `status` sets the initial status (default `open`, or `deferred` when `defer_until` is in the future). Nodes created `closed` get `closed_at` auto-filled. Timestamps are RFC3339; relative forms like `+6h` are not diff --git a/docs/cli-reference/create.md b/docs/cli-reference/create.md index 2e9341cb8..afcec5562 100644 --- a/docs/cli-reference/create.md +++ b/docs/cli-reference/create.md @@ -61,3 +61,92 @@ bd create [title] [flags] --waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children") --wisp-type string Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation ``` + +**Graph plan schema (`--graph`):** + +`bd create --graph plan.json` creates a whole issue graph atomically from a +JSON plan. Node field names follow the issue model's JSON tags (the same +names `bd show --json` emits), and every field single-issue `bd create` can +set is addressable from a plan — plus an initial `status` and `pinned`, +which `bd create` has no flags for: + +```json +{ + "commit_message": "optional Dolt commit message", + "nodes": [ + { + "key": "api", + "title": "Design the API", + "type": "task", + "description": "…", "design": "…", "acceptance_criteria": "…", "notes": "…", + "status": "in_progress", + "priority": 1, + "assignee": "alice", "assign_after_create": false, + "owner": "alice@example.com", + "labels": ["backend"], + "estimated_minutes": 45, + "due_at": "2030-01-02T15:04:05Z", + "defer_until": "2030-01-01T00:00:00Z", + "spec_id": "bd-spec1", "external_ref": "gh-42", + "metadata": {"any": "json", "count": 3}, + "metadata_refs": {"tracker": "impl"}, + "id": "bd-a1b2c3", + "ephemeral": false, "no_history": false, + "wisp_type": "heartbeat", "mol_type": "swarm", + "pinned": false + }, + { "key": "impl", "title": "Implement it", "parent_key": "api" }, + { "key": "gate", "title": "Fanout gate" }, + { "key": "launch", "title": "Launch announced", "type": "event", + "event_kind": "agent.started", "actor": "agent://a", "target": "bead://b", "payload": "{}" } + ], + "edges": [ + { "from_key": "gate", "to_key": "api", "type": "blocks" }, + { "from_key": "gate", "to_key": "impl", "type": "waits-for", + "gate": "any-children", "spawner_key": "impl" } + ] +} +``` + +Node notes: + +- `key` is a plan-local symbolic name; the result maps each key to the minted + issue ID. `id` optionally pins an explicit issue ID instead (must match the + database prefix, like `bd create --id`). +- `parent_key` (a plan node key) or `parent_id` (an existing issue ID) adds a + `parent-child` dependency on the created node. +- `parent` and `estimate` are accepted aliases for `parent_key` and + `estimated_minutes`; the canonical field wins when both spellings are set. +- `status` sets the initial status (default `open`, or `deferred` when + `defer_until` is in the future). Nodes created `closed` get `closed_at` + auto-filled. Timestamps are RFC3339; relative forms like `+6h` are not + accepted in plans. +- `ephemeral` / `no_history` override the plan-wide `--ephemeral` / + `--no-history` flags per node (mutually exclusive per node; in + proxied-server mode the effective storage class must be uniform across the + plan). +- `event_kind`, `actor`, `target`, and `payload` require `"type": "event"`. +- `metadata` accepts arbitrary JSON values; `metadata_refs` values name other + node keys and are replaced with their minted IDs after creation. +- Unlike `bd create --parent`, graph children do not inherit parent labels + and receive flat (non-hierarchical) IDs; plans are explicit artifacts. + +Edge notes: + +- `type` defaults to `blocks`. `parent_key`/`parent_id` on nodes already + create `parent-child` edges; don't repeat them in `edges`. +- `gate` (`all-children` | `any-children`) and `spawner_key`/`spawner_id` + attach fanout-gate metadata to `waits-for` edges, mirroring + `--waits-for`/`--waits-for-gate`. The `to` endpoint of a `waits-for` edge + *is* the spawner (gate evaluation watches its children), so `spawner_key` + must match `to_key` and `spawner_id` must match `to_id`; they exist to make + plans self-documenting. Since an explicit `to_id` overrides `to_key` as the + target, `spawner_key` cannot be combined with `to_id` — use `spawner_id`. +- Edges with ready-work-affecting types (`blocks`, `waits-for`, …) may not + duplicate or reverse a `parent_key`/`parent_id` relationship, and a parent + may not be connected to its own child through them. +- `thread_id` threads conversation edges (e.g. `replies-to`). + +Comments cannot be created from a plan; use `bd comments add` after creation. +Model fields without `bd create` flags (`sender`, `work_type`, `is_template`, +`await_*`, `bonded_from`, `source_*`) are likewise not settable from plans. diff --git a/docs/cli-reference/heartbeat.md b/docs/cli-reference/heartbeat.md new file mode 100644 index 000000000..d6e48d9ef --- /dev/null +++ b/docs/cli-reference/heartbeat.md @@ -0,0 +1,33 @@ +--- +title: "bd heartbeat" +description: "Refresh the lease on an issue you hold in_progress" +--- + +{/* AUTO-GENERATED: do not edit manually */} + +Generated from `bd help --doc heartbeat`. + +Refresh the lease on an issue you currently hold in_progress. + +A claim carries a lease that expires after a TTL. A worker keeps its claim alive +by heartbeating faster than the TTL; once it stops (because it died), the lease +goes stale and 'bd reclaim' reverts the issue to ready so another worker can pick +it up. Heartbeat pushes lease_expires_at forward and stamps heartbeat_at = now. + +Only the current owner may heartbeat. If the lease has already been reclaimed or +the issue closed, heartbeat fails so the worker learns to stop. + +Leases live in an ephemeral, node-local table: heartbeats write no Dolt commit +and no history, so any cadence comfortably below the TTL is fine. Leases are +only enforceable on the node that granted them; cross-machine claim visibility +rides the issue's status and assignee, which do commit. + +Examples: + bd heartbeat bd-123 + bd hb bd-123 + +``` +bd heartbeat [flags] +``` + +**Aliases:** hb diff --git a/docs/cli-reference/migrate-personal.md b/docs/cli-reference/migrate-personal.md new file mode 100644 index 000000000..eed704bfe --- /dev/null +++ b/docs/cli-reference/migrate-personal.md @@ -0,0 +1,33 @@ +--- +title: "bd migrate-personal" +description: "Move personal planning issues from the project database to your planning repo" +--- + +{/* AUTO-GENERATED: do not edit manually */} + +Generated from `bd help --doc migrate-personal`. + +Identify issues you created in the project database and move them to your +personal planning repository (~/.beads-planning by default). + +This is a one-time migration for contributors who created personal planning +issues before contributor routing was configured. + +The command: + 1. Finds all issues in the project database created by your git identity + 2. Shows you the list and asks for confirmation + 3. Moves them to the planning repo configured in routing.contributor + +EXAMPLES: + bd migrate-personal # Interactive: show list and prompt + bd migrate-personal -y # Non-interactive: skip confirmation + +``` +bd migrate-personal [flags] +``` + +**Flags:** + +``` + -y, --yes Skip confirmation prompt +``` diff --git a/docs/cli-reference/reclaim.md b/docs/cli-reference/reclaim.md new file mode 100644 index 000000000..f7e04a582 --- /dev/null +++ b/docs/cli-reference/reclaim.md @@ -0,0 +1,37 @@ +--- +title: "bd reclaim" +description: "Revert stale-lease in_progress issues back to ready (dead-worker recovery)" +--- + +{/* AUTO-GENERATED: do not edit manually */} + +Generated from `bd help --doc reclaim`. + +Revert in_progress issues whose lease has gone stale back to ready. + +When a worker claims an issue it takes a lease that expires after a TTL, kept +alive by 'bd heartbeat'. A worker that dies stops heartbeating, so its lease +expires and its issue would otherwise stay in_progress forever. reclaim is the +reaper: it finds in_progress issues whose lease expired more than --older-than +ago, clears the assignee, and sets them back to open so another worker can +claim them. The previous owner's stale lease is recorded as a recovery event. + +--older-than is a grace window past lease expiry: only leases that expired at +least this long ago are reclaimed, so a worker briefly paused (GC, clock skew) +is not robbed of live work. Run it from a supervisor on a timer with a window +of roughly 2× the claim TTL. + +Examples: + bd reclaim # default grace window (2× the lease TTL) + bd reclaim --older-than 10m # reclaim leases expired >10m ago + bd reclaim --older-than 0s # reclaim every currently-expired lease + +``` +bd reclaim [flags] +``` + +**Flags:** + +``` + --older-than duration Only reclaim leases that expired at least this long ago (grace window) (default 10m0s) +``` diff --git a/docs/cli-reference/unclaim.md b/docs/cli-reference/unclaim.md new file mode 100644 index 000000000..1c620ec6b --- /dev/null +++ b/docs/cli-reference/unclaim.md @@ -0,0 +1,34 @@ +--- +title: "bd unclaim" +description: "Release a claimed issue" +--- + +{/* AUTO-GENERATED: do not edit manually */} + +Generated from `bd help --doc unclaim`. + +Release a claimed issue by clearing the assignee and resetting status to 'open'. + +Use this when an agent crashes mid-work or you need to abandon a claimed task. +The issue becomes available for re-claiming by other agents. + +Only the current assignee can release its own claim. Releasing another +actor's claim requires --force and should be coordinated with the holder +first — their claim may be live even if the issue looks idle. Prefer +letting lease expiry reclaim genuinely abandoned work. + +Examples: + bd unclaim bd-123 + bd unclaim bd-123 --reason "Agent crashed" + bd unclaim bd-123 bd-456 + +``` +bd unclaim [id...] [flags] +``` + +**Flags:** + +``` + --force Release the claim even if held by a different actor (admin/reaper use) + -r, --reason string Reason for unclaiming +```