pbakaus/impeccable · error

build-phase: start needs --comp <approved comp png> (comp al

Error message

build-phase: start needs --comp <approved comp png> (comp already approved) or --direction <seed key> (comp round still to run)

What it means

The `build-phase start` subcommand requires exactly one of two inputs: an approved comp image (--comp <png>) when the comp is already approved, or a seed direction key (--direction <key>) when a comp round is still to run. Supplying neither prints this error and exits 1.

Source

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

    lines.push(format!("NEXT {}", next_instruction(io, state)));
    lines.join("\n")
}

// ---- CLI -------------------------------------------------------------------

/// `impeccable build-phase <cmd> ...`
pub fn run(argv: &[String], io: &mut Io, organic_scan: OrganicScan) -> i32 {
    let cmd = argv.first().map(String::as_str);
    if cmd.is_none() || flag(argv, "help") {
        io.err("usage: build-phase.mjs start --comp <png> [--breakpoint WxH] | status [--json] | advance [--force --reason \"...\"] | record hero --build <png> | scaffold | note \"<text>\" | finish --disposition <word>\n");
        return 1;
    }
    let cmd = cmd.unwrap();
    if cmd == "start" {
        let comp = arg(argv, "comp");
        let direction = arg(argv, "direction");
        if comp.is_none() && direction.is_none() {
            io.err("build-phase: start needs --comp <approved comp png> (comp already approved) or --direction <seed key> (comp round still to run)\n");
            return 1;
        }
        if let Some(c) = comp {
            if !abs(io, c).exists() {
                io.err(&format!("build-phase: comp {c} does not exist\n"));
                return 1;
            }
        }
        if direction.is_some() && arg(argv, "kind").is_some() {
            io.out("choice ping skipped\n");
        }
        let _ = std::fs::remove_file(abs(io, &format!("{BUILD_DIR}/pending.json")));
        let build_path = read_build_path(io);
        if direction.is_some() && comp.is_none() && build_path.as_deref() == Some("code") {
            io.out("CODE-LED (from .impeccable config): no comp round and no phase gates. Write the direction contract (reference/new-work.md section 5), build, and finish per section 7. The chosen decision comp, if any, rides to the finish review as the critique reference.\n");
            return 0;
        }
        let mut breakpoint = arg(argv, "breakpoint").map(String::from);

View on GitHub (pinned to 2bc2879276)

Solutions

1. Add --comp <approved comp png> if the design comp is approved
2. Add --direction <seed key> if the comp round is still to run
3. Check flag spelling; paths must use --comp, not positional args

Example fix

// before
$ impeccable build-phase start
// after
$ impeccable build-phase start --comp .impeccable/comps/hero-approved.png

[ -n "$COMP" ] || [ -n "$DIRECTION" ] || { echo 'need --comp <png> or --direction <key>'; exit 1; }

impeccable build-phase start --comp "$COMP" || impeccable build-phase --help

When it happens

Trigger: `impeccable build-phase start` with neither --comp nor --direction flags; both arg() lookups return None and the guard fires.

Common situations: Omitting the flags because the usage string is long; passing the comp path positionally instead of via --comp; using a misspelled flag like --com or --seed.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• comp-spec: pass --grid to get the coordinate grid, then --re
• usage: font-match.mjs --measure <text-region-id> | --rank <t
• "init" is not a CLI command. Type /impeccable init in your A
• Unknown command: "{other}" To see a list of supported comma
• usage: build-phase.mjs start --comp <png> [--breakpoint WxH]

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