CleanMM/Docs/DECISIONS.md

Decision Log

Frozen Decisions

D-001 Naming

• Internal product name: Atlas for Mac
• User-facing naming must not use Mole

D-002 Open-Source Attribution

• Atlas for Mac is an independent product
• Upstream attribution must acknowledge Mole by tw93 and contributors
• Shipped materials must include MIT notice when upstream-derived code is distributed

D-003 Distribution

• MVP distribution target is direct distribution
• Use Developer ID + Hardened Runtime + Notarization
• Do not target Mac App Store for MVP

D-004 MVP Scope

• In scope: Overview, Smart Clean, Apps, History, Recovery, Permissions, Settings
• Out of MVP: Storage treemap, Menu Bar, Automation

D-005 Process Boundaries

• UI must not parse terminal output directly
• Privileged actions must go through a structured helper boundary
• Worker owns long-running orchestration and progress streaming

D-006 MVP Persistence and Command Surface

• MVP workspace state is persisted locally as a structured JSON store
• Settings, history, recovery, Smart Clean execute, and app uninstall flows use structured worker commands
• UI state should reflect repository-backed worker results instead of direct mutation

D-007 Helper Execution and Native Packaging

• Destructive helper actions use a structured executable boundary with path validation
• Native MVP packaging uses xcodegen + xcodebuild, then embeds the helper into the app bundle
• Tagged GitHub Releases should publish the native .zip, .dmg, and .pkg assets from CI using the same packaging scripts as local release builds
• If CI lacks Developer ID release credentials, tagged native assets may still be published as development-signed prereleases instead of blocking the packaging path entirely
• Signing and notarization remain optional release-time steps driven by credentials
• Internal packaging should prefer a stable local app-signing identity over ad hoc signing whenever possible so macOS permission state does not drift across rebuilds

D-008 App Language Preference and Localization

• MVP now supports 简体中文 and English through a persisted app-language preference
• The default app language is 简体中文
• User-facing shell copy is localized through package-scoped resources instead of hard-coded per-screen strings
• The language preference is stored alongside other settings so worker-generated summaries stay aligned with UI language

D-009 Execution Capability Honesty

• User-facing execution flows must fail closed when real disk-backed execution is unavailable
• Atlas must not silently fall back to scaffold behavior for release-facing cleanup execution
• Smart Clean execute must not claim success until real filesystem side effects are implemented

Update Rule

Add a new decision entry whenever product scope, protocol, privilege boundaries, release route, or recovery model changes.