docs(cli): move the graph plan schema into an embedded doc supplement
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 <noreply@anthropic.com>
This commit is contained in:
parent
f162fb8951
commit
aadd21c40b
9 changed files with 341 additions and 0 deletions
|
|
@ -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
|
||||
|
|
|
|||
20
cmd/bd/help_supplements.go
Normal file
20
cmd/bd/help_supplements.go
Normal file
|
|
@ -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,
|
||||
}
|
||||
88
cmd/bd/help_supplements/create_graph_plan.md
Normal file
88
cmd/bd/help_supplements/create_graph_plan.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
33
docs/cli-reference/heartbeat.md
Normal file
33
docs/cli-reference/heartbeat.md
Normal file
|
|
@ -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 <id> [flags]
|
||||
```
|
||||
|
||||
**Aliases:** hb
|
||||
33
docs/cli-reference/migrate-personal.md
Normal file
33
docs/cli-reference/migrate-personal.md
Normal file
|
|
@ -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
|
||||
```
|
||||
37
docs/cli-reference/reclaim.md
Normal file
37
docs/cli-reference/reclaim.md
Normal file
|
|
@ -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)
|
||||
```
|
||||
34
docs/cli-reference/unclaim.md
Normal file
34
docs/cli-reference/unclaim.md
Normal file
|
|
@ -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
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue