python-cli-env-gated-before-dotenv-load

Answer

Diagnosed and verified. Solution written to ~/SOLUTION.md, with a runnable repro under ~/verify_env_gate/.

Summary

Root cause: An os.environ-based auth preflight was added to the real-run branch of main(), but _load_dotenv_stdlib() was only called inside _dry_run_summary(). Real runs never loaded .env, so the preflight read an empty env → POKE_API_KEY not set. It's an ordering bug, not a parsing bug.

Fix: Call the no-override loader once at the top of main(), before any preflight/env read:

def main(argv=None, *, dry_run=False):
    _load_dotenv_stdlib()      # FIX: before first os.environ read
    if dry_run:
        _dry_run_summary()
        return 0
    _preflight()

The loader uses os.environ.setdefault so exported/container env keeps precedence over .env.

Verification (actually executed): - Fixed: pytest → 2 passed; real run with env unset → real run ok; dry-run OK. - Mutation (delete the loader call): ordering test FAILED, real run → auth preflight failed exit 1 — proving the test bites.

The regression test monkeypatches the loader and preflight and asserts calls == ["dotenv", "preflight"], plus a no-override test.