build-phase: finish --disposition ship|fix|rebuild|recapture

Error message

build-phase: finish --disposition ship|fix|rebuild|recapture

What it means

The `build-phase finish` subcommand requires a --disposition flag whose value is one of the four allowed words: ship, fix, rebuild, recapture. Any other value or a missing flag prints this usage error and exits 1 before any state transition happens.

Source

Thrown at crates/comp-verbs/src/build_phase.rs:1998

                return 2;
            }
            io.out(&format!(
                "ADVANCED {} -> {}{}{}\n",
                res.phase,
                res.next.clone().unwrap_or_default(),
                if res.forced { " (FORCED; recorded)" } else { "" },
                res.gate_summary.map(|s| format!("  {s}")).unwrap_or_default()
            ));
            for a in &res.advisories {
                io.out(&format!("  {a}\n"));
            }
            io.out(&format!("NEXT {}\n", next_instruction(io, &state)));
            0
        }
        "finish" => {
            let disposition = arg(argv, "disposition");
            if !matches!(disposition, Some("ship") | Some("fix") | Some("rebuild") | Some("recapture")) {
                io.err("build-phase: finish --disposition ship|fix|rebuild|recapture\n");
                return 1;
            }
            let disposition = disposition.unwrap();
            let open_before: Vec<String> = PHASES
                .iter()
                .filter(|&&ph| {
                    ph != "review"
                        && state
                            .pointer(&format!("/phases/{ph}/status"))
                            .and_then(Value::as_str)
                            .map(|st| st != "closed" && st != "skipped")
                            .unwrap_or(false)
                })
                .map(|s| s.to_string())
                .collect();
            if disposition == "ship" && !open_before.is_empty() {
                let phase = state.get("phase").and_then(Value::as_str).unwrap_or("");
                io.err(&format!(

View on GitHub (pinned to 2bc2879276)

Solutions

Pass exactly one of: --disposition ship, fix, rebuild, or recapture (lowercase)
If unsure which disposition applies, run `impeccable build-phase status` to see the current phase guidance
Avoid synonyms like 'shipped' or 'Done'; the enum is strict

Example fix

// before
$ impeccable build-phase finish --disposition Done
// after
$ impeccable build-phase finish --disposition ship

Defensive patterns

Strategy: validation

Validate before calling

case "$DISPOSITION" in ship|fix|rebuild|recapture) ;; *) echo 'disposition must be ship|fix|rebuild|recapture'; exit 1;; esac

Try / catch

impeccable build-phase finish --disposition "$DISPOSITION" || impeccable build-phase --help

Prevention

Treat disposition as a strict lowercase enum: ship|fix|rebuild|recapture
Use status output to decide the disposition before finishing
Never pass free-form words; script the exact enum values

When it happens

Trigger: `impeccable build-phase finish` with no --disposition, or --disposition with an unrecognized value (e.g. 'done', 'Ship', 'shipped') — the matches! guard only accepts the exact lowercase words.

Common situations: Free-form disposition words instead of the enum; capitalized values (matching is case-sensitive); forgetting the flag entirely.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/0c126947755467d6. Report an issue: GitHub.