stack/docs/scratchpads/B4-wizard-step-dedup.md

B4 — Wizard step deduplication

Problem

Greenfield wizard testing showed completed wizard steps could be executed again after the menu marked them [done]. In practice this made the Providers/API-key flow and Skills flow appear twice in one wizard run.

There was a second related API-key duplication path: when the Providers step was completed with no key, gatewayConfigStage still prompted for ANTHROPIC_API_KEY during Finish because it only skipped the gateway API-key prompt when providerKey was non-empty.

Diagnosis

• runMenuLoop labeled completed sections with [done], but still dispatched the selected step again if the user selected that row.
• Quick Start ran Providers and Skills but did not mark those sections complete in completedSections.
• runFinishPath/quickStartPath defaulted providerType to none for gateway config, which made it impossible for gatewayConfigStage to distinguish:
  • provider step completed and user intentionally skipped the key, vs.
  • provider step was never run.

Fix

• Added a shared menu section key helper and a completed-step guard in runMenuLoop.
• Completed menu steps now log a skip message instead of re-running their stage.
• Quick Start marks Providers and Skills complete after running them.
• Finish/Quick Start now pass state.providerType as-is to gateway config instead of defaulting to none.
• gatewayConfigStage treats providerType: 'none' as an explicit completed provider setup with no key and skips the second gateway API-key prompt.

Verification

• Added unified wizard regression coverage asserting repeated Providers/Skills menu selections only execute each stage once.
• Added gateway config coverage asserting providerType: 'none' does not prompt for a gateway API key and writes no API key env var.
• Targeted: pnpm --filter @mosaicstack/mosaic test -- unified-wizard gateway-config
• pnpm format:check
• pnpm typecheck
• pnpm lint
• pnpm build
• pnpm test
• Codex code review: approve.
• Codex security review: no findings.