bead doctor

ddx bead doctor

Detect (and optionally repair) beads.jsonl rows with oversized fields

Synopsis

Scan the bead tracker for fields that exceed the per-field size cap.

Bead fields (description, acceptance, notes, events[].body, events[].summary) are capped at 65,535 bytes so DDx-authored beads round-trip cleanly through bd import (upstream’s Dolt TEXT column limit). Fields over the cap usually come from a writer bug that landed before the cap was enforced — for example a reviewer stream dumped verbatim into an event body.

Without –fix this command only reports offending rows and exits non-zero. With –fix it:

1. Writes a timestamped backup to .ddx/backups/ before any mutation.
2. Truncates each oversized field to the cap using head+tail+marker.
3. Writes the full original payload to .ddx/executions//repair-/.log so forensics remain possible.
4. Appends a kind=repair event to every rewritten bead.

Idempotent: once a tracker is clean, running –fix again is a no-op.

ddx bead doctor [flags]

Options

      --fix    Rewrite oversized fields in place after writing a backup
  -h, --help   help for doctor
      --json   Output findings as JSON

Options inherited from parent commands

      --config string              config file (default is $HOME/.ddx.yml)
      --library-base-path string   override path for DDx library location
  -v, --verbose                    verbose output

SEE ALSO

• ddx bead - Manage beads (portable work items)

Auto generated by spf13/cobra on 21-Apr-2026