beads/docs/METADATA.md
Afik 674561360d
schema: make DROP COLUMN migrations idempotent (fixes migration 0032 loop) (#3418)
* cmd/bd: extract sanitizeDBName to its own file for CGO_ENABLED=0 lint

sanitizeDBName lived in store_factory.go which is //go:build cgo,
but init.go (no tag) calls it. The pre-commit golangci-lint runs
with CGO_ENABLED=0 and flagged it as undefined. Move the pure-Go
function to its own untagged file and drop the now-unused strings
import from store_factory.go. No behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* schema: tolerate "does not have column" errors in migration runner

Broadens isConcurrentInitError to also treat "does not have column"
as a benign migration error, symmetric with the existing "duplicate
column" tolerance for ADD races. Makes DROP COLUMN migrations
idempotent across databases bootstrapped with different base schemas.

Observed failure: migration 0032 (DROP COLUMN applied_at) loops
forever on any database that lands at v31 without the column. Dolt
has no DROP COLUMN IF EXISTS, so the SQL itself can't be guarded;
handling it in the runner keeps the migration file trivial.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Add migration 0032 idempotence tests (bd-7mh.3)

* Document bd execution metadata workflow (bd-b1a)

* Revert "Document bd execution metadata workflow (bd-b1a)"

This reverts commit 0d6a96babd.

* Reapply "Document bd execution metadata workflow (bd-b1a)"

This reverts commit df90cf5404.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-04-27 09:15:20 -07:00

49 lines
1.9 KiB
Markdown

# Issue Metadata
The `metadata` field on issues accepts arbitrary JSON. Any valid JSON value is stored as-is.
## Agent Execution Metadata
Automation may store execution hints in issue metadata so agents can make
routing decisions without parsing prose. Agents enacting an issue should read
metadata first, then use description and notes for scope and rationale:
```bash
bd show <id> --json | jq '.[0] | {id,title,metadata,description,notes}'
```
Current execution hint keys:
| Key | Meaning |
|-----|---------|
| `execution_agent_type` | Suggested worker class, such as `explorer`, `worker`, or `mixed`. |
| `execution_suggested_model` | Suggested model for the parent agent or spawned subagent. |
| `execution_reasoning_effort` | Suggested reasoning effort, such as `low`, `medium`, `high`, or `xhigh`. |
| `execution_mode` | Whether work should be local, delegated, or staged between delegated and local execution. |
| `execution_parallel_group` | Grouping hint for work that can run alongside related tasks. |
These keys are advisory metadata, but when present they take precedence over
free-form notes for execution routing. Notes remain useful for rationale,
ownership, and exact prompts.
Parent/orchestrator agents must consume these keys before spawning subagents.
Model and reasoning effort are normally fixed at launch, so reading metadata
after delegation is too late.
Do not add a first-class helper such as `bd show <id> --execution` or
`bd plan <id> --json` yet. Keep using the JSON/JQ snippet until upstream
issue gh-3541 determines whether schedulers or runners need these fields as a
stable CLI surface.
## Reserved Key Prefixes
| Prefix | Reserved For |
|--------|------------|
| `bd:` | Beads internal use |
| `_` | Internal/private keys |
Avoid these prefixes in user-defined keys to prevent conflicts with future Beads features.
## Related
- [#1416](https://github.com/gastownhall/beads/issues/1416) — Optional schema enforcement (future)