Migration from Legacy Configs

This page describes safe migration from existing run/workflow TOML usage to pleb.toml UX usage.

Migration goals

• keep behavior parity,

• keep backward compatibility,

• reduce direct editing of many files.

Recommended migration plan

Step 1: Baseline snapshot

• identify currently used legacy config file(s),

• capture command invocations and run outputs used for comparison.

Step 2: Initialize UX file

pleb init --config pleb.toml

Step 3: Copy core paths/scope

Populate:

• [paths]

• [data]

with values equivalent to your existing legacy profile.

Step 4: Set mode and core toggles

Populate:

• [run] section

with equivalent stage toggles.

Step 5: Move policy by group

Populate:

• [policy.fix]

• [policy.pqc]

• [policy.report]

• [workflow] (if needed)

Step 6: Preserve advanced keys

For any unmapped advanced setting, place it under [pipeline] exactly as legacy flat key.

Step 7: Compare and validate

• run pleb doctor and pleb explain,

• run pilot on small scope,

• compare branch output files and run outputs with legacy baseline.

Parity checklist

• same target repo/data roots,

• same branch/base branch semantics,

• same pulsar selection,

• same stage toggles,

• same policy keys (especially fix/pqc action behavior),

• same workflow file in workflow mode.

Rollback strategy

Because execution internals are unchanged, rollback is trivial:

• run legacy command/config directly,

• keep UX wrapper changes in separate commit/branch until parity is proven.

Team adoption strategy

• adopt UX wrapper for new users first,

• keep legacy configs for power users during transition,

• gradually codify team presets in configs/presets.