Skip to content

beans update drops unknown frontmatter keys (data loss for tools and agents) #208

Description

@xeroc

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:

  1. Read all existing frontmatter keys.
  2. Update only the keys beans knows about (status, body, parent, etc.).
  3. 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).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions