feat: add bd state and bd set-state helper commands (bd-7l67)

Implements convenience commands for the labels-as-state pattern:

- `bd state <id> <dimension>` - Query current state value from labels
- `bd state list <id>` - List all state dimensions on an issue
- `bd set-state <id> <dimension>=<value> --reason "..."` - Atomically:
  1. Create event bead (source of truth)
  2. Remove old dimension label
  3. Add new dimension:value label (cache)

Common dimensions: patrol, mode, health, status
Convention: <dimension>:<value> (e.g., patrol:active, mode:degraded)

Updated docs/CLI_REFERENCE.md with new State section.
Updated docs/LABELS.md to reflect implemented helpers.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-30 15:56:23 -08:00
parent a534764315
commit 48dca4ea33
4 changed files with 750 additions and 3 deletions

View File

@@ -143,6 +143,38 @@ bd label list <id> --json
bd label list-all --json
```
### State (Labels as Cache)
For operational state tracking on role beads. Uses `<dimension>:<value>` label convention.
See [LABELS.md](LABELS.md#operational-state-pattern-labels-as-cache) for full pattern documentation.
```bash
# Query current state value
bd state <id> <dimension> # Output: value
bd state witness-abc patrol # Output: active
bd state --json witness-abc patrol # {"issue_id": "...", "dimension": "patrol", "value": "active"}
# List all state dimensions on an issue
bd state list <id> --json
bd state list witness-abc # patrol: active, mode: normal, health: healthy
# Set state (creates event + updates label atomically)
bd set-state <id> <dimension>=<value> --reason "explanation" --json
bd set-state witness-abc patrol=muted --reason "Investigating stuck polecat"
bd set-state witness-abc mode=degraded --reason "High error rate"
```
**Common dimensions:**
- `patrol`: active, muted, suspended
- `mode`: normal, degraded, maintenance
- `health`: healthy, warning, failing
- `status`: idle, working, blocked
**What `set-state` does:**
1. Creates event bead with reason (source of truth)
2. Removes old `<dimension>:*` label if exists
3. Adds new `<dimension>:<value>` label (cache)
## Filtering & Search
### Basic Filters