Module setup_state 

Unified setup-state model for the v0.8.67 constitution-first setup lane (#3403).

This is the single record every setup step (#3404–#3412) reads and writes so that “configured”, “skipped”, “verified”, and “ready” mean the same thing everywhere. It is persisted as a JSON sidecar (setup_state.json) under $CODEWHALE_HOME, written atomically through crate::persistence so it is independent of config.toml’s comment-preserving writes and can never leave a half-written file.

The record holds two things:

1. A per-SetupStep StepEntry (status, required, safe summary, writing lane version).
2. The constitution-first fields the wizard, the update checkpoint, and /constitution all coordinate on.

Readiness is a derived property (first_run_ready / update_ready); it is never persisted, so the rules can evolve without a migration.

Secrets never appear here: StepEntry::result is a short human-facing summary (provider name, model id, mode name), never a key.

Structs

InheritedConfigFacts

Observable, secret-free facts about existing config used to derive a safe inherited setup-state for users who upgrade without a setup_state.json.

SetupState

The persisted, per-version setup-state record.

StepEntry

One persisted entry per setup step.

Enums

ConstitutionAuthoring

How the active custom constitution was authored. Recorded alongside ConstitutionChoice::GuidedCustom so /setup, doctor, and the report can show provenance without parsing free-text step results.

ConstitutionChoice

The user’s constitution decision. Every value except Unset counts as an explicit choice for readiness.

ConstitutionSource

Which constitution surface is currently the active user-global law.

ConstitutionValidity

Validity of the active user-global constitution file, if any.

RuntimePostureSource

Where the current runtime posture came from. Mirrors the rule that a constitution may recommend posture but only an explicit config action (#3406) applies it.

SetupStep

Canonical setup step ids. The ordering matches the first-run spine so a BTreeMap<SetupStep, _> renders in wizard order.

StepStatus

Status of a single setup step. Shared vocabulary so /setup, doctor, and the context report never invent their own meanings.

Constants

SETUP_STATE_FILE_NAME

Filename of the setup-state sidecar under $CODEWHALE_HOME.

SETUP_STATE_SCHEMA_VERSION

Current schema version of the persisted setup-state record.

TELEMETRY_NOTICE_VERSION

Version of the telemetry notice content — not the app version.