upgrade

Ironflow upgrade

Moves a project to a newer Ironflow release and brings its code up to the idioms of that release. Arguments: $ARGUMENTS.

Arguments	Mode
none	upgrade to the latest release
2.43.0 or ironflow-core@4.8.0	upgrade to that release (a bare version is ironflow-engine)
--from <git-rev>	the bump is already done: analyse from the Cargo.lock of that revision
audit	no bump: check the code against the current idioms, whatever its history
--apply	apply without asking, except adopt entries and anything ambiguous

Semver does not protect an Ironflow project: author-API breaks ship in minor releases (ironflow-engine 2.39.0 retyped the whole author API). The compiler, the changelog and the catalogue in ${CLAUDE_SKILL_DIR}/references/ are the source of truth.

1. Preflight

git status --porcelain                                  # must be empty, or ask
grep -rn --include=Cargo.toml '^ironflow-' . | grep -v '/target/'
cargo check --workspace --all-targets 2>&1 | tail -3    # baseline

• Uncommitted changes: ask before going on. The migration must be one reviewable diff.
• An ironflow dependency declared with path = or git =: stop. It follows its checkout, not crates.io.
• Baseline already broken: note the errors. They are not the upgrade's to fix.

2. Bump (upgrade only)

Target versions: cargo search <crate> --limit 5, keep the line <crate> = "<version>". Move every ironflow crate together, never one alone.

• Each package: cargo add -p <package> <crate>@<version> (--dev for a dev-dependency). It keeps the features. A workspace = true dependency: edit [workspace.dependencies].
• Then cargo update <crate> <crate> ... with every ironflow crate, nothing else.
• Target older than latest: require =<version> for the named crate, run cargo update on the ironflow crates (cargo picks the others compatible with it), then write back the versions Cargo.lock resolved, without =. No downgrade.
• awk '/^name = "ironflow-/ {print $3}' Cargo.lock | sort | uniq -d must print nothing. Two versions of one crate give errors like expected ironflow_core::X, found ironflow_core::X: raise the requirement that holds the old one.

3. What changed

"${CLAUDE_SKILL_DIR}/scripts/changes.sh"              # HEAD:Cargo.lock vs Cargo.lock
"${CLAUDE_SKILL_DIR}/scripts/changes.sh" <git-rev>    # --from: lock of that revision

It prints the versions before and after, then every changelog entry in between, deduplicated across crates. Skip it in audit mode. Find the revision before a past bump with git log --oneline -- Cargo.lock.

Keep the entries that touch the project: handler code, server or worker wiring, environment, runtime behavior. Most have a catalogue entry (same issue number). For an author-facing entry without one, read the issue (its Solution and Specs sections):

curl -s https://gitlab.com/api/v4/projects/ThomasTartrau%2Fironflow/issues/<n> | jq -r '.title, .description'

4. Where it hits the code

cargo check --workspace --all-targets --message-format short 2>&1 | grep -E '^[^ ]+: (error|warning)'
"${CLAUDE_SKILL_DIR}/scripts/scan.sh" .

• Every compiler error and deprecation warning maps to a catalogue entry (compiler: line) or to a changelog entry. Neither: read the item in the new crate source, ~/.cargo/registry/src/*/<crate>-<version>/src/. Its rustdoc names the replacement. Never guess an API.
• Every scan.sh hit is a candidate. Read the code around it before keeping it: some patterns (json::<, ServerConfig::from_env) also match correct code.
• Upgrade mode: catalogue entries whose since falls in the bumped range apply even without a hit when they are behavior (environment, defaults, model aliases).
• Wiring: compare the project's server and worker main.rs with ${CLAUDE_SKILL_DIR}/../setup/assets/{server,worker}/src/main.rs. Report only a missing piece that changes behavior: a background task, a required variable.
• audit mode also reads every handler for what a line pattern cannot catch: an expression in a string, a Value read by key over several lines, a step name copied by hand to reach what that step produced.

5. Report, then ask

Kind	Meaning	Default
breaking	does not compile after the bump	apply, required to build
deprecated	compiles with a warning	apply
behavior	compiles, runs differently (env, defaults, models)	apply the code part, list the ops part
idiom	compiles, but not the typed way: a typo would pass in silence	apply
adopt	a new feature replaces a workaround	propose one by one

One table per kind: entry, file:line, the fix in a few words, effort (S/M/L). Then the versions before and after, and what needs a human outside the code (secrets to generate, a decision provider to wire). Ask with one multi-select AskUserQuestion, one option per kind present. In --apply mode, skip the question for everything but adopt.

6. Apply

• One catalogue entry at a time, in the order of the table above. After each: cargo check --workspace --all-targets. Do not start the next with new errors.
• The + side of each entry and the compiled snippets of ${CLAUDE_SKILL_DIR}/../workflow/references/steps.md and sub-workflows.md are the target form. Imports go at the top of the file with use.
• Steps are replay keys. A run waiting on an approval, a human input or a signal replays its handler by step name and order; a changed sequence fails it with ReplayDivergence. Never rename a step during a migration. An entry that adds, removes or reorders steps (most adopt ones) bumps the handler's version(), and the user drains ironflow-cli run list --status awaiting_approval and --status sleeping first.
• Never weaken a test to make it pass. A test that asserted the old behavior is updated to the new one, and the report says so.
• At the end: cargo test --workspace, and cargo clippy --workspace --all-targets if the project runs it in CI. Then offer the ironflow:workflow-reviewer agent on the handlers that changed.

7. Hand over

Five lines at most: versions before and after, entries applied, entries left and why, what to do before deploying (secrets, environment, Postgres migrations run at server boot: back up first). Suggest the commit, do not make it: chore: bump ironflow to <engine version>.