Evolve installed recipes

Goal

Upgrade definitions from an already installed recipe without replacing bundle-owned values or writing from a stale plan. This how-to is for bundle maintainers using the current stable release.

The stable behavior and package identity are recorded in the current release evidence.

What recipe evolution can change

recipe evolve is an additive convention-upgrade path. It may add supported declarations to installed recipe definitions after validating existing instances. It does not perform a general merge or replace bundle-owned content.

The preflight blocks changes such as:

• replacing or removing existing declared values;

• making a previously optional field or body section required when current instances do not comply;

• changing terminal workflow semantics incompatibly;

• replacing active View assets or undeclared artifacts;

• removing definitions that are absent from the new recipe source;

• relationship or schema changes outside the supported additive rules.

Prerequisites

• Back up or commit the bundle according to its normal sharing model.

• Identify the built-in recipe name or local recipe folder.

• Run superbee recipes and confirm the recipe is already installed.

• Inspect local edits to the installed convention; evolution preserves and reports bundle-owned drift rather than silently overwriting it.

1. Produce a read-only plan

superbee recipe evolve context-notes

For a local folder, pass a path such as ./recipes/my-domain. A bare name selects a built-in recipe. Planning performs no writes. Review:

• the definitions that would change;

• additive operations for each target;

• existing-instance validation;

• blockers and drift;

• the exact apply command and plan token.

Continue only when the plan reports ready and every proposed definition change is expected.

2. Apply the exact plan

Run the apply command returned by the plan. Its shape is:

superbee recipe evolve context-notes \
  --apply PLAN_TOKEN \
  --actor openai/codex/root

Apply recomputes the complete preflight, binds the token to the current recipe source and target heads, and writes each changed convention with exact-version compare-and-swap. A token from another bundle, another recipe source, or an earlier state is refused.

3. Verify the live conventions and instances

superbee kinds
superbee status
superbee recipes

Inspect each evolved Kind, then read representative existing instances and create one disposable new instance when the change adds an authoring capability. The recipe is fully applied only when definitions match and the bundle remains valid.

Concurrency and partial completion

Evolution preflights the whole operation before writing. Each target still has its own versioned write, so a concurrent change can interrupt a multi-target apply. The receipt separates completed targets from pending targets and reports any concurrent non-target change discovered by the final postcondition check.

Do not replay the old token after a partial result. Inspect the completed writes and concurrent changes, rerun the read-only plan, and apply only a newly reviewed token. Additive operations are idempotent, so a fresh plan should omit definitions already brought to the intended state.

Recovery

Evidence and related guidance

The planner and apply state machine are implemented in the tagged recipe evolve command and exercised by its integration tests. See Kind conventions and recipes for the static recipe model and Migrate or upgrade safely for package-level recovery.