Problem
When beans update rewrites a bean's YAML frontmatter (on any status change, body update, etc.), it silently drops keys it doesn't recognize. Any frontmatter field that isn't part of beans' known schema (title, status, type, parent, created_at, updated_at, priority, tags) is stripped.
This causes silent data loss for tools and agents that extend beans with custom metadata.
Reproduction
# Create a bean
beans create "Demo" -t task
# Simulate an external tool adding a custom frontmatter key
sed -i '/^status:/a custom_field: preserved?' .beans/<id>--demo.md
# Verify it's there
grep custom_field .beans/<id>--demo.md
# → custom_field: preserved?
# Update the bean via beans CLI
beans update <id> -s in-progress
# The custom key is gone
grep custom_field .beans/<id>--demo.md
# → (no output — beans rewrote the frontmatter without it)
Why it matters
Beans explicitly targets agentic workflows (beans prime). Custom workflow management tools and agents built on top of beans often need to store their own metadata on beans — pipeline stage, workflow state, content metadata, signal IDs, etc.
The current behavior forces these consumers into fragile workarounds: storing metadata as JSON blobs inside the bean body (wrapped in HTML comment markers) or in sidecar files, purely because beans would strip custom frontmatter keys on the next beans update. This makes beans harder to read, harder to query via beans list --json, and forces every ecosystem tool to invent its own metadata-in-body encoding.
Proposed fix
When beans update performs its read-modify-write on the frontmatter, preserve unknown keys instead of dropping them:
- Read all existing frontmatter keys.
- Update only the keys beans knows about (
status, body, parent, etc.).
- Write back all keys (known + unknown).
This is a small change in the frontmatter serialization path and is fully backwards compatible — existing beans without custom keys are unaffected, and beans' own schema validation continues to work (it just doesn't destroy what it doesn't recognize).
Problem
When
beans updaterewrites a bean's YAML frontmatter (on any status change, body update, etc.), it silently drops keys it doesn't recognize. Any frontmatter field that isn't part of beans' known schema (title,status,type,parent,created_at,updated_at,priority,tags) is stripped.This causes silent data loss for tools and agents that extend beans with custom metadata.
Reproduction
Why it matters
Beans explicitly targets agentic workflows (
beans prime). Custom workflow management tools and agents built on top of beans often need to store their own metadata on beans — pipeline stage, workflow state, content metadata, signal IDs, etc.The current behavior forces these consumers into fragile workarounds: storing metadata as JSON blobs inside the bean body (wrapped in HTML comment markers) or in sidecar files, purely because beans would strip custom frontmatter keys on the next
beans update. This makes beans harder to read, harder to query viabeans list --json, and forces every ecosystem tool to invent its own metadata-in-body encoding.Proposed fix
When
beans updateperforms its read-modify-write on the frontmatter, preserve unknown keys instead of dropping them:status,body,parent, etc.).This is a small change in the frontmatter serialization path and is fully backwards compatible — existing beans without custom keys are unaffected, and beans' own schema validation continues to work (it just doesn't destroy what it doesn't recognize).