v0.8.67 Setup: require a localized constitution checkpoint after update

[Hmbown]

Checkpoint sequencing update (2026-06-29)

For update users, the v0.8.67 checkpoint should jump straight to constitution review, but it should still preserve the same variable separation:

• The checkpoint asks the user to keep bundled/default, create/review a structured user-global constitution, or handle an advanced full-prompt override.
• If review reveals that the user wants a different default mode/approval/sandbox posture, the checkpoint should hand off to v0.8.67 Setup: trust, approvals, sandbox, network, and privacy step #3406 or show an explicit config-change confirmation. It must not let constitutional prose silently mutate enforced runtime policy.
• Completion remains valid when the user chooses bundled/default with no custom constitution file.
• Noninteractive/headless update continues on bundled law and marks checkpoint deferred; it must not call a model just to draft/polish constitution text.
• /constitution (v0.8.67 Setup: make /constitution the primary constitution management surface #3806) is the reopen/edit/status surface after the checkpoint.

---

Maintainer direction update (2026-06-29)

This checkpoint is about the user-global constitution choice, not repo .codewhale/constitution.json and not a required full-prompt Markdown override.

The v0.8.67 update checkpoint should present these choices:

1. Use bundled Constitution: no user-global constitution file is created; the bundled Markdown law remains active.
2. Use or generate a structured user-global constitution: guided/preset answers are saved under $CODEWHALE_HOME as structured policy data, then rendered into a prose <codewhale_user_constitution> prompt block.
3. Review an existing structured user-global constitution: show source, rendered preview, validation state, and keep/edit/disable actions.
4. Handle advanced full-prompt overrides: if $CODEWHALE_HOME/prompts/constitution.md exists, clearly label it as an advanced exposed main prompt for broader use cases #3638 full-base-prompt override and offer keep/disable/repair. Do not make that path the default creator output.

The checkpoint should record completion once the user explicitly chooses bundled/default, keeps or creates a structured user-global constitution, or disables/keeps an advanced override knowingly.

Docs and UI must explain the layer order:

bundled Constitution markdown -> rendered user-global constitution -> repo .codewhale/constitution.json -> AGENTS.md/project instructions -> memory/handoff -> current user request.

Related cleanup: WHALE.md should be removed as an active context surface in #3798 so setup does not teach a legacy path.

---

Non-goals

• Not forcing the user to author a custom constitution; "use bundled/default" is a fully valid completion — this is the central guarantee of the checkpoint.
• Not re-running provider/API-key setup; the checkpoint is additive and must not invalidate an existing working route.
• Not repeating every launch — completion is recorded once per lane version (constitution_checkpoint_completed_for = "0.8.67").
• Not editing the repo .codewhale/constitution.json or any repo surface; the checkpoint governs only the user-global constitution choice.

Safe fallback

• A noninteractive/headless launch that cannot render the interactive checkpoint records checkpoint_deferred and proceeds on the bundled constitution, rather than blocking work or hanging scripts.
• An unreadable/empty/flag-disabled existing override routes to clear localized repair choices, not a crash.
• If the checkpoint is interrupted, the next launch re-offers it — completion is only recorded on an explicit choice.

Product shape

For v0.8.67, existing users who update should go through a constitution checkpoint, not just new installs. This should feel like a versioned “welcome back” moment: CodeWhale explains that the setup model now has a constitution layer, asks the user to make an explicit choice, records that choice, and then gets out of the way.

This is a required checkpoint, but it must not force custom prompt writing. Valid completion paths are:

1. use the bundled CodeWhale constitution,
2. choose a preset and generate a user-global constitution,
3. inspect/edit an existing user-global constitution,
4. restore/disable a previous override and use the bundled constitution.

The key is explicit consent and comprehension, not mandatory customization.

Why this matters

v0.8.67 changes onboarding from “configure a provider” to “configure how CodeWhale should behave.” Users who update already have config, keys, sessions, and habits. If they never see the constitution checkpoint, they will miss the new authority/personalization model and support/debugging will be harder because there is no durable record of which standing behavior they chose.

Desired behavior

• On first launch after updating to v0.8.67, CodeWhale detects that the user has not completed the v0.8.67 constitution checkpoint.
• The user is routed to a short constitution checkpoint before normal work begins.
• Users with a valid existing user-global constitution see a review/keep/edit/disable path.
• Users without one can choose bundled/default, preset-generated, or advanced edit.
• Completion is recorded in versioned setup state so the checkpoint does not appear every launch.
• /setup can reopen the checkpoint and show whether the current version is complete.
• Doctor/context reports show the active constitution source and v0.8.67 checkpoint status.
• Emergency or noninteractive contexts get a documented fallback path, but interactive TUI users must make the explicit choice.

Localization requirements

The constitution checkpoint must be localizable across every shipped setup language, not only English.

At minimum, localization must cover:

• checkpoint title and “why you are seeing this after update” copy,
• bundled/default constitution option,
• preset-generated constitution option,
• inspect/edit existing constitution option,
• disable override / restore bundled option,
• global vs repo constitution explanation,
• completion and skipped/deferred status,
• validation and repair messages,
• final setup report rows.

If a locale is incomplete, the fallback behavior must be intentional and visible in tests or docs, not accidental English bleed-through.

Suggested implementation shape

• Add a versioned setup-state field such as constitution_checkpoint_completed_for = "0.8.67" or equivalent.
• Treat the checkpoint as complete when the user chooses bundled/default, generated custom, existing custom, or disable override.
• Keep the generated/edited constitution behavior in v0.8.67 Setup: build a guided localized constitution creator, not a blank prompt editor #3793; this issue owns the update gate and localized completion state.
• Keep one-key provider/default-model setup from v0.8.67 Setup: make first-run onboarding feel like starting CodeWhale, not editing config #3792/v0.8.67 Setup: provider/model step with catalog, auth, picker, and live health checks #3405 intact; do not force users to redo API-key setup just because they are completing the constitution checkpoint.

Acceptance criteria

• Updating an existing CODEWHALE_HOME to v0.8.67 triggers the constitution checkpoint exactly once until the user reopens /setup.
• Choosing “use bundled constitution” satisfies the required checkpoint without creating a custom prompt file.
• Existing valid user-global constitution files can be reviewed and kept without rewriting them.
• Invalid, empty, unreadable, or flag-disabled override states route to clear localized repair choices.
• Setup state records the v0.8.67 checkpoint completion and can be shown in /setup, doctor, or context report output.
• All user-visible checkpoint strings use localization IDs or an explicit fallback layer.
• At least one non-English test/snapshot covers the update checkpoint; zh-Hans and zh-Hant coverage is included or the fallback is documented.
• Noninteractive/headless behavior is documented so scripts do not hang on an interactive wizard.

Related

• Setup epic: v0.8.67 EPIC: Setup wizard and user-global constitution #3402
• First-run onboarding: v0.8.67 Setup: make first-run onboarding feel like starting CodeWhale, not editing config #3792
• Guided constitution creator: v0.8.67 Setup: build a guided localized constitution creator, not a blank prompt editor #3793
• Provider/model happy path: v0.8.67 Setup: provider/model step with catalog, auth, picker, and live health checks #3405
• Setup docs/localization: v0.8.67 Setup: docs, screenshots, localization, and constitution copy refresh #3412
• Hotbar localization precedent: v0.8.68: Localize Hotbar setup wizard chrome and add non-English coverage #3759