stack/docs/MISSION-MANIFEST.md

Mission Manifest — Install UX Hardening

Persistent document tracking full mission scope, status, and session history. Updated by the orchestrator at each phase transition and milestone completion.

Mission

ID: install-ux-hardening-20260405 Statement: Close the remaining gaps in the Mosaic Stack first-run and teardown experience uncovered by the post-cli-unification audit. A user MUST be able to cleanly uninstall the stack; the wizard MUST make security-sensitive surfaces visible (hooks, password entry); and CI/headless installs MUST NOT hang on interactive prompts. The longer-term goal is a single cohesive first-run flow that collapses mosaic wizard and mosaic gateway install into one state-bridged experience. Phase: Execution Current Milestone: IUH-M02 Progress: 1 / 3 milestones Status: active Last Updated: 2026-04-05 Parent Mission: cli-unification-20260404 (complete)

Context

Post-merge audit of cli-unification-20260404 (AC-1, AC-6) validated that the first-run wizard covers first user, password, admin tokens, gateway instance config, skills, and SOUL.md/USER.md init. The audit surfaced six gaps, grouped into three tracks of independent value.

Success Criteria

• AC-1: mosaic uninstall (top-level) cleanly reverses every mutation made by tools/install.sh — framework data, npm CLI, nested stack deps, runtime asset injections in ~/.claude/, npmrc scope mapping, PATH edits. Dry-run supported. --keep-data preserves memory + user files + gateway DB. (PR #429)
• AC-2: curl … | bash -s -- --uninstall works without requiring a functioning CLI. (PR #429)
• AC-3: Password entry in bootstrapFirstUser is masked (no plaintext echo); confirm prompt added.
• AC-4: Wizard has an explicit hooks stage that previews which hooks will be installed, asks for confirmation, and records the user's choice. mosaic config hooks list|enable|disable surface exists.
• AC-5: runConfigWizard and bootstrapFirstUser accept a headless path (env vars + --yes) so tools/install.sh --yes + MOSAIC_ASSUME_YES=1 completes end-to-end in CI without TTY.
• AC-6: mosaic wizard and mosaic gateway install are collapsed into a single cohesive entry point with shared state (no two-phase handoff via the 10-minute session file).
• AC-7: All milestones ship as merged PRs with green CI, closed issues, updated release notes.

Milestones

#	ID	Name	Status	Branch	Issue	Started	Completed
1	IUH-M01	mosaic uninstall — top-level teardown + shell wrapper	done	feat/mosaic-uninstall	#425	2026-04-05	2026-04-05
2	IUH-M02	Wizard remediation — hooks visibility, pwd mask, headless	in-progress	feat/wizard-remediation	#426	2026-04-05	—
3	IUH-M03	Unified first-run wizard (collapse wizard + gateway)	blocked	feat/unified-first-run	#427	—	—

Subagent Delegation Plan

Milestone	Recommended Tier	Rationale
IUH-M01	sonnet	Standard feature work — new command surface mirroring existing install
IUH-M02	sonnet	Small surgical fixes across 3-4 files
IUH-M03	opus	Architectural refactor; state machine design decisions

Risks

• Reversal completeness — runtime asset linking creates .mosaic-bak-* backups; uninstall must honor them vs. when to delete. Ambiguity without an install manifest.
• npm global nested deps — npm uninstall -g @mosaicstack/mosaic removes nested @mosaicstack/*, but ownership conflicts with explicitly installed peer packages (@mosaicstack/gateway, @mosaicstack/memory) need test coverage.
• Headless bootstrap — admin password via env var is a credential on disk; needs clear documentation that MOSAIC_ADMIN_PASSWORD is intended for CI-only and should be rotated post-install.

Out of Scope

• mosaicstack.dev/install.sh vanity URL (blocked on marketing site work)
• Uninstall for the @mosaicstack/gateway database contents — delegated to mosaic gateway uninstall semantics already in place
• Signature/checksum verification of install scripts