GetHub/CleanMM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: add selective parity strategy planning

Browse Source
This commit is contained in:
zhukang
2026-03-23 16:48:26 +08:00
parent 92da918281
commit 1f62600532
10 changed files with 1198 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
Docs/Execution/Competitive-Strategy-Plan-2026-03-21.md Normal file
View File

@@ -0,0 +1,249 @@
# Competitive Strategy Plan — 2026-03-21
## Purpose
Turn the findings in [Open-Source-Competitor-Research-2026-03-21.md](./Open-Source-Competitor-Research-2026-03-21.md) into a practical strategy for Atlas for Mac's next execution window.
This plan assumes:
- MVP scope remains frozen to the current modules
- direct distribution remains the only MVP release route
- strategy should improve competitive position by deepening existing flows, not by reopening deferred scope
## Strategic Options Considered
### Option A: Breadth Race
Try to match `Mole` and `Lemon` feature-for-feature as quickly as possible.
- Upside:
- easier feature checklist comparisons
- broader marketing claims
- Downside:
- high scope pressure
- weakens Atlas's current trust advantage
- increases risk of half-implemented cleanup claims
- encourages pulling deferred items like `Storage treemap`
Decision: reject.
### Option B: Trust-Only Niche
Ignore breadth pressure and compete only on recovery, permissions, and execution honesty.
- Upside:
- strongest alignment with Atlas architecture
- lowest scope risk
- Downside:
- leaves obvious product comparison gaps open
- makes Atlas look elegant but underpowered next to `Mole`, `Lemon`, and `Pearcleaner`
Decision: reject.
### Option C: Recommended Strategy
Compete on `trust-first native workspace`, while selectively closing the most visible parity gaps inside frozen MVP.
- Upside:
- preserves Atlas's strongest differentiation
- improves user-visible competitiveness where comparison pressure is highest
- avoids scope creep
- Downside:
- requires disciplined prioritization and clear no-go boundaries
Decision: adopt.
## Strategic Thesis
Atlas should not try to become a generic all-in-one cleaner. It should become the most trustworthy native Mac maintenance workspace, then remove the most painful reasons users would otherwise choose `Mole`, `Lemon`, or `Pearcleaner`.
That means:
1. Win on execution honesty, recoverability, auditability, and permission clarity.
2. Close only the highest-pressure breadth gaps inside existing MVP flows.
3. Make Atlas's differentiation visible enough that users can understand it without reading architecture docs.
## Competitive Reading
### `Mole`
Primary pressure:
- broad cleanup coverage
- developer-oriented cleanup
- disk analysis and status breadth
- strong dry-run and automation posture
Atlas response:
- do not chase terminal ergonomics
- close the most visible safe cleanup coverage gaps in `Smart Clean`
- keep the trust advantage by failing closed and showing real side effects only
### `Tencent Lemon Cleaner`
Primary pressure:
- native GUI breadth
- large-file / duplicate / privacy / uninstall / startup-item utility expectations
- Chinese-speaking user familiarity with one-click cleaner workflows
Atlas response:
- stay native and polished
- avoid claiming equivalent breadth until behavior is real
- compete with safer workflows, clearer recommendations, and higher trust in destructive actions
### `Pearcleaner`
Primary pressure:
- uninstall depth
- leftovers and app-adjacent cleanup
- macOS-native integration quality
Atlas response:
- treat `Apps` as a serious competitive surface, not just an MVP checklist module
- deepen uninstall preview and explain what will be removed, what is recoverable, and what remains review-only
### `Czkawka` and `GrandPerspective`
Primary pressure:
- high-performance file hygiene primitives
- treemap-based storage analysis
Atlas response:
- borrow architectural lessons only
- keep `Storage treemap` deferred
- do not import GPL-constrained UI paths into Atlas
## Strategic Pillars
### Pillar 1: Build a Trust Moat
Atlas's strongest defendable position is trust architecture:
- structured worker/helper boundaries
- recoverable destructive actions
- history and auditability
- permission explanations instead of permission ambush
- honest failure when Atlas cannot prove execution
This must remain the primary product story and the primary release gate.
### Pillar 2: Close Selective Parity Gaps
Atlas should close the gaps users notice immediately in side-by-side evaluation:
- `Smart Clean` coverage on high-confidence safe targets users expect from `Mole` and `Lemon`
- `Apps` uninstall depth and leftovers clarity users expect from `Pearcleaner` and `Lemon`
This is selective parity, not full parity. The rule is: only deepen flows already inside frozen MVP.
### Pillar 3: Make Differentiation Visible
Atlas cannot rely on architecture alone. The product must visibly communicate:
- what is recoverable
- what is executable now
- what requires permission and why
- what changed on disk after execution
- what Atlas intentionally refuses to do
If users cannot see these differences in the UI and release materials, Atlas will be compared as "another cleaner" and lose to broader tools.
## 90-Day Execution Direction
### Phase 1: Trust and Claim Discipline
Target outcome:
- Atlas's release-facing claims are narrower than its real behavior, never broader
Priority work:
- execution honesty
- recovery claim discipline
- permission and limited-mode clarity
- visible trust markers in `Smart Clean`, `Apps`, `History`, and `Permissions`
### Phase 2: Smart Clean Competitive Depth
Target outcome:
- the highest-value safe cleanup classes compared against `Mole` and `Lemon` have real execution paths
Priority work:
- expand safe cleanup target coverage
- strengthen `scan -> execute -> rescan` proof
- make history reflect only real side effects
### Phase 3: Recovery Credibility
Target outcome:
- Atlas's recovery promise is provable and product-facing copy can be frozen without caveats that undercut trust
Priority work:
- physical restore where safe
- clear split between file-backed restore and Atlas-only state restore
- explicit validation evidence
### Phase 4: Apps Competitive Depth
Target outcome:
- Atlas's `Apps` module is defensible against `Pearcleaner` and `Lemon` for the most common uninstall decision paths
Priority work:
- deeper uninstall preview taxonomy
- clearer leftovers and footprint reasoning
- visible recoverability and audit cues in the uninstall flow
- fixture-based validation on mainstream and developer-heavy apps
## No-Go Boundaries
The competitor response must not trigger:
- `Storage treemap`
- `Menu Bar`
- `Automation`
- duplicate-file or similar-photo modules as new product surfaces
- privacy-cleaning module expansion outside existing MVP framing
- code reuse from `Lemon`, `GrandPerspective`, or GPL-constrained `Czkawka` paths
- monetization-sensitive reuse from `Pearcleaner`
## Metrics and Gates
### Product Metrics
- first scan completion rate
- scan-to-execution conversion rate
- uninstall preview-to-execute conversion rate
- permission completion rate
- recovery success rate
- user-visible reclaimed space
### Competitive Readiness Gates
- `Smart Clean` can prove meaningful gains on the top safe categories users compare against `Mole` and `Lemon`
- `Apps` uninstall preview is detailed enough that users understand footprint, leftovers, and recoverability before confirmation
- no release-facing copy implies full parity with broader tools when Atlas only supports a narrower subset
- recovery language stays tied to shipped behavior only
## Resulting Strategy Call
For the next planning window, Atlas should be managed as:
- a `trust-first Mac maintenance workspace`
- with `selective parity` against `Mole` and `Lemon` in `Smart Clean`
- with `targeted depth` against `Pearcleaner` and `Lemon` in `Apps`
- while keeping all non-MVP expansion pressure explicitly frozen
This is the narrowest strategy that still improves Atlas's competitive position in a way users will actually feel.

243
Docs/Execution/Implementation-Plan-ATL-211-214-226-230-2026-03-21.md Normal file
View File

@@ -0,0 +1,243 @@
# ATL-211 / ATL-214 / ATL-226-230 Implementation Plan
> **For Codex:** Use this as the first coding-slice plan for the selective-parity strategy. Keep scope inside frozen MVP. Verify behavior with narrow tests and fixture-driven checks before broader UI validation.
## Goal
Make Atlas more defensible against `Mole`, `Tencent Lemon Cleaner`, and `Pearcleaner` without expanding beyond MVP:
- increase `Smart Clean` competitive credibility on the most visible safe cleanup classes
- deepen the `Apps` module so uninstall preview and completion evidence feel trustworthy and specific
## Product Rules
- Do not add new top-level product surfaces.
- Do not imply parity with broader tools when Atlas still supports only a narrower subset.
- Prefer explicit supported-vs-review-only states over speculative or partial execution.
- Prefer categories Atlas can prove and recover over categories that merely look complete in the UI.
## Target Outcomes
### Smart Clean
- Atlas can execute more of the high-confidence safe cleanup classes users naturally compare to `Mole` and `Lemon`.
- Completion and history copy only describe real disk-backed side effects.
- Unsupported paths remain explicit and fail closed.
### Apps
- Atlas explains what an uninstall preview actually contains.
- Users can understand bundle footprint, leftovers, launch-item/service implications, and recoverability before confirming.
- The uninstall flow leaves stronger audit and completion evidence than the current baseline.
## Competitive Pressure Matrix
### Smart Clean comparison pressure
Top overlap with `Mole` and `Lemon`:
- user cache roots
- logs and temp data
- developer artifact roots
- high-confidence app-specific junk paths already represented structurally in Atlas
Non-goals for this slice:
- duplicate file cleanup
- similar photos
- privacy-cleaning as a standalone surface
- treemap storage analysis
### Apps comparison pressure
Top overlap with `Pearcleaner` and `Lemon`:
- uninstall leftovers clarity
- launch-item / service-adjacent footprint awareness
- better explanation of what Atlas will remove, what it will not remove, and what is recoverable
Non-goals for this slice:
- Homebrew manager as a new standalone module
- PKG manager as a new standalone module
- plugin manager as a new standalone module
- auto-cleaning daemon behavior
## Task 1: Freeze Fixture and Benchmark Set
### Goal
Define the exact scenarios the coding slice must satisfy before implementation starts drifting.
### Deliverables
- a `Smart Clean` target-class list used for parity work
- an `Apps` fixture list covering:
- mainstream GUI app
- developer-heavy app
- app with launch item or service artifact
- app with sparse leftovers
### Proposed file touch map
- `Docs/Execution/MVP-Acceptance-Matrix.md`
- `Docs/Execution/Beta-Acceptance-Checklist.md`
- future test fixtures under `Testing/` or package test directories as implementation chooses
### Acceptance
- each benchmark scenario is tied to a real competitor comparison pressure
- each benchmark scenario is tied to a current MVP surface
## Task 2: Smart Clean Selective Parity Increment
### Goal
Land one implementation slice that widens competitive coverage without weakening trust.
### Likely code areas
- `Packages/AtlasCoreAdapters/Sources/AtlasCoreAdapters/MoleSmartCleanAdapter.swift`
- `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift`
- `Packages/AtlasApplication/Sources/AtlasApplication/AtlasApplication.swift`
- `Apps/AtlasApp/Sources/AtlasApp/AtlasAppModel.swift`
- `Packages/AtlasFeaturesSmartClean/Sources/AtlasFeaturesSmartClean/SmartCleanFeatureView.swift`
### Work shape
- extend safe allowlisted target support only where Atlas already has structured evidence
- tighten plan/execution/result summaries so history reflects actual side effects only
- expose unsupported findings as review-only rather than ambiguous ready-to-run items
### Tests
- package-level contract tests for `scan -> execute -> rescan`
- app-model tests for explicit unsupported or unavailable states
### Acceptance
- at least one new high-confidence safe target class is supported end to end
- unsupported target classes remain visibly unsupported
- no history or completion surface overclaims what happened on disk
## Task 3: Apps Preview Taxonomy and Evidence
### Goal
Make uninstall preview feel materially stronger against `Pearcleaner` and `Lemon`.
### Likely code areas
- `Packages/AtlasApplication/Sources/AtlasApplication/AtlasApplication.swift`
- `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift`
- `Packages/AtlasProtocol/`
- `Packages/AtlasFeaturesApps/Sources/AtlasFeaturesApps/AppsFeatureView.swift`
- `Apps/AtlasApp/Sources/AtlasApp/AtlasAppModel.swift`
### Work shape
- expand preview categories so the UI can group footprint evidence more explicitly
- distinguish:
- application bundle
- support files
- caches
- preferences
- logs
- launch/service-adjacent items where Atlas can safely classify them
- keep unclear or unsupported items explicitly separate instead of silently mixing them into a generic leftover count
### Tests
- application-layer tests for preview taxonomy
- infrastructure tests for structured footprint generation
- UI snapshot or app-model assertions for preview grouping if feasible
### Acceptance
- uninstall preview provides more than a count and byte total
- supported footprint categories are explicit and user-comprehensible
- ambiguous items are clearly labeled rather than overstated
## Task 4: Apps Trust Cues and Completion Evidence
### Goal
Turn `Apps` from a functional uninstall screen into a trust-differentiated uninstall workflow.
### Likely code areas
- `Packages/AtlasFeaturesApps/Sources/AtlasFeaturesApps/AppsFeatureView.swift`
- `Apps/AtlasApp/Sources/AtlasApp/AppShellView.swift`
- localization resources in `Packages/AtlasDomain`
### Work shape
- add supported-vs-review-only messaging where relevant
- show recoverability and audit implications before destructive confirmation
- tighten completion summaries so they state what Atlas actually removed and what was recorded for recovery/history
### Tests
- app-model tests for completion summaries and history-driven state
- focused UI verification for uninstall preview -> execute -> history/recovery path
### Acceptance
- the flow answers, before confirm:
- what will be removed
- what evidence Atlas has
- what is recoverable
- the flow answers, after confirm:
- what was actually removed
- what was recorded
## Task 5: Fixture-Based Validation and Gate
### Goal
Prove the coding slice against realistic comparison cases instead of synthetic happy-path only.
### Validation layers
- narrow package tests first
- app-model tests second
- manual or scripted fixture walkthrough third
### Required fixture scenarios
- one mainstream app uninstall
- one developer-heavy app uninstall
- one `Smart Clean` scenario with newly supported target class
- one unsupported scenario that must fail closed visibly
### Gate outputs
- evidence summary for `ATL-229`
- short gate review for `ATL-230`
- any claim narrowing needed in UI or release-facing docs
## Recommended Coding Order
1. freeze fixtures and target classes
2. implement one `Smart Clean` selective-parity increment
3. land uninstall preview taxonomy changes
4. land uninstall trust cues and completion evidence
5. rerun fixture validation and produce gate evidence
## Commands To Prefer During Implementation
```bash
swift test --package-path Packages
swift test --package-path Apps
swift test --package-path Packages --filter AtlasInfrastructureTests
swift test --package-path Apps --filter AtlasAppModelTests
```
Add narrower filters once the exact tests are created.
## Done Criteria
- `Smart Clean` parity increment is real and test-backed
- `Apps` preview is structurally richer and more trustworthy
- fixture validation shows visible improvement against the current baseline
- docs remain honest about supported vs unsupported behavior

479
Docs/Execution/Open-Source-Competitor-Research-2026-03-21.md Normal file
View File

@@ -0,0 +1,479 @@
# Open-Source Competitor Research — 2026-03-21
## Objective
Research open-source competitors relevant to `Atlas for Mac` and compare them against Atlas from two angles:
- feature overlap with the frozen MVP
- technical patterns worth copying, avoiding, or tracking
This report is scoped to Atlas MVP as defined in [PRD.md](../PRD.md): `Overview`, `Smart Clean`, `Apps`, `History`, `Recovery`, `Permissions`, and `Settings`. Deferred items such as `Storage treemap`, `Menu Bar`, and `Automation` are treated as adjacent references, not MVP targets.
## Method
- Internal product/architecture baseline:
- [PRD.md](../PRD.md)
- [Architecture.md](../Architecture.md)
- [Smart-Clean-Execution-Coverage-2026-03-09.md](./Smart-Clean-Execution-Coverage-2026-03-09.md)
- External research date:
- All GitHub and SourceForge metadata in this report was checked on `2026-03-21`.
- External research workflow:
- 2 focused web searches to identify the relevant open-source landscape
- deep reads of the most representative projects: `Mole`, `Pearcleaner`, `Czkawka`
- repo metadata, release metadata, license files, and selected source files for technical verification
## Middle Findings
- There is no single open-source product that matches Atlas's intended combination of `native macOS UI + explainable action plan + history + recovery + permission guidance`.
- The market is fragmented:
- `Mole` is the closest breadth benchmark for cleanup depth and developer-oriented coverage.
- `腾讯柠檬清理 / lemon-cleaner` is the closest native-GUI breadth benchmark from the Chinese Mac utility ecosystem.
- `Pearcleaner` is the strongest open-source benchmark for app uninstall depth on macOS.
- `Czkawka` is the strongest reusable file-analysis engine pattern, but it is not a Mac maintenance workspace.
- `GrandPerspective` is the strongest adjacent open-source reference for storage visualization, but Atlas has explicitly deferred treemap from MVP.
- Licensing is a major strategic boundary:
- `Mole` uses `MIT`, which aligns with Atlas's current reuse strategy.
- `Pearcleaner` is `Apache 2.0 + Commons Clause`, so it is source-available but not a safe upstream for monetized derivative shipping.
- `Czkawka` mixes `MIT` and `GPL-3.0-only` depending on component.
- `GrandPerspective` is `GPL`.
- Atlas's strongest differentiation is architectural trust. Atlas's current weakest point is breadth of release-grade executable cleanup compared with how broad `Mole` already looks to users.
## Executive Summary
If Atlas wants to win in open source, it should not position itself as "another cleaner." That lane is already occupied by `Mole` on breadth and `Pearcleaner` on uninstall specialization. Atlas's credible lane is a `native macOS maintenance workspace` with structured worker/helper boundaries, honest permission handling, and recovery-first operations.
The biggest threat is not that an open-source competitor already matches Atlas end to end. The threat is that users may compare Atlas's current MVP against a combination of `Mole + Pearcleaner + GrandPerspective/Czkawka` and conclude Atlas is cleaner in design but behind in raw capability. That makes execution credibility, uninstall depth, and product messaging more important than adding new surface area.
The one important omission in an open-source-only Mac comparison would be `腾讯柠檬清理 / Tencent lemon-cleaner`, because it is both open-source and closer than most projects to a native GUI maintenance suite. Atlas should treat it as a real comparison point, especially for Chinese-speaking users.
## Landscape Map
| Project | Type | Why it matters to Atlas | Current signal |
| --- | --- | --- | --- |
| `tw93/Mole` | Direct breadth competitor | Closest open-source "all-in-one Mac maintenance" positioning | Very strong community and recent release activity |
| `Tencent/lemon-cleaner` | Direct breadth competitor | Closest open-source native GUI maintenance suite, especially relevant in Chinese market | Established product and recognizable feature breadth |
| `alienator88/Pearcleaner` | Direct module competitor | Strongest open-source benchmark for `Apps` uninstall depth on macOS | Strong adoption, but maintainer bandwidth is constrained |
| `qarmin/czkawka` | Adjacent engine competitor | Best open-source file hygiene / duplicate / temporary-file engine pattern | Mature and active, but not macOS-native |
| `GrandPerspective` | Adjacent UX competitor | Best open-source reference for storage visualization / treemap | Active, but outside Atlas MVP scope |
| `sanketk2020/MacSpaceCleaner` | Emerging minor competitor | Shows appetite for lightweight native Mac cleaners | Low maturity; not a primary benchmark |
## Functional Comparison
Legend:
- `Strong` = clear product strength
- `Partial` = present but narrower or less central
- `No` = not a meaningful capability
| Capability | Atlas for Mac | Mole | Lemon | Pearcleaner | Czkawka | GrandPerspective |
| --- | --- | --- | --- | --- | --- | --- |
| Broad junk / cache cleanup | Partial | Strong | Strong | Partial | Partial | No |
| App uninstall with leftovers | Strong | Strong | Strong | Strong | No | No |
| Developer-oriented cleanup | Strong | Strong | Partial | Partial | Partial | No |
| Disk usage analysis | Partial | Strong | Strong | No | Partial | Strong |
| Live health / system status | Partial | Strong | Strong | No | No | No |
| History / audit trail | Strong | Partial | Low | No | No | No |
| Recovery / restore model | Strong | Partial | No | No | No | No |
| Permission guidance UX | Strong | Low | Partial | Partial | Low | Low |
| Native macOS GUI | Strong | No | Strong | Strong | Partial | Strong |
| CLI / automation surface | Partial | Strong | Low | Partial | Strong | No |
### Notes Behind The Table
- Atlas:
- Atlas is strongest where it combines cleanup with `History`, `Recovery`, and `Permissions`.
- Atlas already has real `Apps` list / preview uninstall / execute uninstall flows in the current architecture and protocol, with recovery-backed app uninstall behavior; the remaining question is depth and polish versus Pearcleaner, not whether the module exists.
- Per [Smart-Clean-Execution-Coverage-2026-03-09.md](./Smart-Clean-Execution-Coverage-2026-03-09.md), real Smart Clean execution is still limited to a safe structured subset. So Atlas's cleanup breadth is not yet at `Mole` level.
- Mole:
- Mole covers `clean`, `uninstall`, `optimize`, `analyze`, `status`, `purge`, and `installer`, which is broader than Atlas's current release-grade execution coverage.
- Mole exposes JSON for some commands and has strong dry-run patterns, but it does not center recovery/history as a product promise.
- Lemon:
- Lemon combines deep cleaning, large-file cleanup, duplicate cleanup, similar-photo cleanup, privacy cleaning, app uninstall, login-item management, and status-bar monitoring in one native Mac app.
- It is a much more direct GUI comparison than Mole for users who expect a polished desktop utility instead of a terminal-first tool.
- Pearcleaner:
- Pearcleaner is deep on `Apps`, but it is not a full maintenance workspace.
- It extends beyond uninstall into Homebrew, PKG, plugin, services, and updater utilities.
- Czkawka:
- Czkawka is powerful for duplicate finding, big files, temp files, similar media, broken files, and metadata cleanup.
- It is not a Mac workflow app and does not cover uninstall, permissions guidance, or recovery.
- GrandPerspective:
- Very strong for treemap-based disk visualization.
- It is analysis-first, not cleanup-orchestration-first.
## Technical Comparison
| Area | Atlas for Mac | Mole | Lemon | Pearcleaner | Czkawka | GrandPerspective |
| --- | --- | --- | --- | --- | --- | --- |
| App shape | Native macOS app | CLI / TUI plus scripts | Native macOS app | Native macOS app | Cross-platform workspace | Native macOS app |
| Main stack | SwiftUI + AppKit bridges + XPC/helper | Shell + Go | Objective-C/Cocoa + Xcode workspace + pods | SwiftUI + AppKit + helper targets | Rust workspace with core/CLI/GTK/Slint frontends | Cocoa / Objective-C / Xcode project |
| Process boundary | App + worker + privileged helper | Mostly single local toolchain | App plus multiple internal modules/daemons | App + helper + Finder extension + Sentinel monitor | Shared core with multiple frontends | Single app process |
| Privileged action model | Structured helper boundary | Direct shell operations with safety checks | Native app cleanup modules; license files indicate separate daemon licensing | Privileged helper plus Full Disk Access | Mostly user-space file operations | Read/analyze oriented |
| Recoverability | Explicit product-level recovery model | Safety-focused, but not recovery-first | No clear recovery-first model | No clear recovery-first model | No built-in recovery model | Not applicable |
| Auditability | History and structured recovery items | Operation logs | No first-class history model | No first-class history model | No first-class history model | Not applicable |
| Packaging | `.zip`, `.dmg`, `.pkg`, direct distribution | Homebrew, install script, prebuilt binaries | Native app distribution via official site/App ecosystem | DMG/ZIP/Homebrew cask | Large prebuilt binary matrix | SourceForge / App Store / source tree |
| License shape | MIT, with attribution for reused upstream code | MIT | GPL v2 for daemon, GPL v3 for most other modules | Apache 2.0 + Commons Clause | Mixed: MIT plus GPL-3.0-only for some frontends | GPL |
## Competitor Deep Dives
### 1. Mole
#### Why it matters
`Mole` is the closest open-source breadth competitor and also Atlas's most important upstream-adjacent reference. It markets itself as an all-in-one Mac maintenance toolkit and already bundles many of the comparisons users naturally make against commercial utilities.
#### What it does well
- Broad feature surface in one install:
- cleanup
- app uninstall
- disk analyze
- live status
- project artifact purge
- installer cleanup
- Strong developer-user fit:
- Xcode and Node-related cleanup are explicitly called out
- `purge` is a strong developer-specific wedge
- Safe defaults are well communicated:
- dry-run
- path validation
- protected directories
- explicit confirmation
- operation logs
- Good automation posture:
- `mo analyze --json`
- `mo status --json`
#### Technical takeaways
- Repo composition is pragmatic rather than layered:
- heavy Shell footprint
- Go core dependencies including `bubbletea`, `lipgloss`, and `gopsutil`
- Distribution is optimized for speed and reach:
- Homebrew
- shell install script
- architecture-specific binaries
- Safety is implemented inside one local toolchain, not via an app-worker-helper separation.
#### Weaknesses relative to Atlas
- Terminal-first experience limits mainstream Mac adoption.
- Product trust is based on careful scripting and dry-run, not on a native explainable workflow with recovery.
- History, audit, and restore are not a first-class user-facing value proposition.
#### Implication for Atlas
`Mole` should be treated as Atlas's primary benchmark for `Smart Clean` breadth and developer-oriented cleanup coverage. Atlas should not try to beat Mole on shell ergonomics. Atlas should beat it on:
- explainability
- permissions UX
- structured execution boundaries
- history / recovery credibility
- native product polish
### 2. Pearcleaner
#### Why it matters
`Pearcleaner` is the strongest open-source benchmark for Atlas's `Apps` module. It is native, widely adopted, and much deeper on uninstall-adjacent workflows than most open-source Mac utilities.
#### What it does well
- Strong uninstall-centered feature cluster:
- app uninstall
- orphaned file search
- file search
- Homebrew manager
- PKG manager
- plugin manager
- services manager
- updater
- Native platform integrations:
- Finder extension
- helper target
- Sentinel monitor for automatic cleanup when apps hit Trash
- CLI support and deep-link automation
- Clear macOS assumptions:
- Full Disk Access required for search
- privileged helper required for system-folder actions
#### Technical takeaways
- Repo structure shows native macOS product thinking:
- `Pearcleaner.xcodeproj`
- `Pearcleaner`
- `PearcleanerHelper`
- `PearcleanerSentinel`
- `FinderOpen`
- Source confirms a SwiftUI app entrypoint:
- `import SwiftUI`
- `@main struct PearcleanerApp: App`
- Helper code confirms XPC-like privileged helper behavior with code-sign validation before accepting client requests.
#### Weaknesses relative to Atlas
- It is not a full maintenance workspace.
- No strong user-facing recovery/history model.
- Maintainer note in the README says updates slowed due to limited spare time, which is a maintainability risk.
- Licensing is a hard boundary:
- Apache 2.0 with Commons Clause prevents monetized derivative use.
#### Implication for Atlas
For `Apps`, Atlas should benchmark against Pearcleaner rather than against generic cleaners. The gap to close is not "can Atlas delete apps" but:
- uninstall footprint depth
- service / launch item cleanup coverage
- package-manager and installer awareness
- native workflow polish
Atlas should not depend on Pearcleaner code for shipped product behavior due license constraints.
### 3. Tencent Lemon Cleaner
#### Why it matters
`Tencent/lemon-cleaner` is one of the most relevant omissions if Atlas only compares itself with Western or terminal-first open-source tools. It is a native macOS maintenance utility with broad GUI feature coverage and obvious overlap with what many users expect from a Mac cleaning app.
#### What it does well
- Broad native GUI utility bundle:
- deep scan cleanup
- large-file cleanup
- duplicate-file cleanup
- similar-photo cleanup
- browser privacy cleanup
- app uninstall
- startup item management
- status-bar monitoring
- disk space analysis
- Product positioning is close to mainstream cleaner expectations:
- one-click cleaning
- software-specific cleanup rules
- real-time device status in menu bar / status area
- Chinese-market relevance is high:
- the README and official site are aimed directly at Chinese macOS users and their cleanup habits
#### Technical takeaways
- Repo structure is a classic native Mac app workspace:
- `Lemon.xcodeproj`
- `Lemon.xcworkspace`
- multiple feature modules such as `LemonSpaceAnalyse`, `LemonUninstaller`, `LemonPrivacyClean`, `LemonLoginItemManager`, and `LemonCleaner`
- The repository is primarily `Objective-C` and keeps a separate daemon license file.
- This is a good example of a feature-suite style monolithic Mac utility rather than Atlas's more explicitly layered app/worker/helper model.
#### Weaknesses relative to Atlas
- No visible recovery-first promise comparable to Atlas.
- No obvious user-facing history/audit model.
- Architecture appears more utility-suite oriented than trust-boundary oriented.
- License is restrictive for Atlas reuse:
- GPL v2 for the daemon
- GPL v3 for most other modules
#### Implication for Atlas
Lemon is a direct product benchmark, especially for:
- native GUI breadth
- large-file / duplicate / privacy / startup-item utility coverage
- Chinese-language market expectations
Atlas should study Lemon as a product benchmark, but not as a code-reuse candidate.
### 4. Czkawka
#### Why it matters
`Czkawka` is not a direct Mac maintenance workspace competitor, but it is the strongest open-source reference for fast multi-platform file analysis and cleanup primitives.
#### What it does well
- High-performance file hygiene coverage:
- duplicates
- empty files/folders
- big files
- temp files
- similar images/videos
- broken files
- Exif remover
- video optimizer
- Strong engineering posture:
- memory-safe Rust emphasis
- reusable `czkawka_core`
- CLI plus multiple GUI frontends
- explicit note that it does not collect user data or access the Internet
- Platform strategy is mature:
- macOS, Linux, Windows, FreeBSD, Android
#### Technical takeaways
- Workspace composition is clear:
- `czkawka_core`
- `czkawka_cli`
- `czkawka_gui`
- `krokiet`
- `cedinia`
- The newer `Krokiet` frontend is built in `Slint` because the maintainer found GTK inconsistent and high-friction on Windows and macOS.
- This is a strong example of separating reusable scan logic from frontends.
#### Weaknesses relative to Atlas
- It is not macOS-native in product feel.
- It does not cover uninstall, permissions workflow, history, or restore semantics.
- Mixed licensing matters:
- core/CLI/GTK app are MIT
- `Krokiet` and `Cedinia` are GPL-3.0-only due Slint-related restrictions
#### Implication for Atlas
`Czkawka` is best used as an engineering reference, not as a product model. Atlas can learn from:
- reusable core logic boundaries
- fast scanning primitives
- cross-front-end separation
Atlas should avoid importing GPL-constrained UI paths into shipping code.
### 5. GrandPerspective
#### Why it matters
`GrandPerspective` is not an MVP competitor but it is the clearest open-source reference for treemap-based storage visualization on macOS.
#### What it does well
- Strong single-purpose focus:
- visual treemap disk usage analysis
- Mature native Mac implementation:
- `GrandPerspective.xcodeproj`
- `main.m`
- Still active:
- SourceForge tree shows commits in January and February 2026 and a `3.6.3` version update in January 2026.
#### Weaknesses relative to Atlas
- It is an analyzer, not a cleanup workspace.
- GPL license makes it unattractive for direct reuse in Atlas.
#### Implication for Atlas
Keep `GrandPerspective` as a post-MVP reference for `Storage treemap` only. Do not let it pull Atlas out of frozen MVP scope without an explicit product decision update.
### 6. Watchlist: MacSpaceCleaner
`MacSpaceCleaner` is useful as a signal, not as a primary benchmark.
- Positives:
- native Swift-based Mac utility
- MIT licensed
- explicit developer/Xcode cleanup slant
- Limitations:
- only `136` GitHub stars on `2026-03-21`
- much weaker ecosystem signal than Mole, Pearcleaner, or Czkawka
- repository structure is less mature and less informative
It is worth monitoring for specific ideas, but it should not drive Atlas roadmap decisions.
## What Atlas Is Actually Competing With
The real competitive picture is not one app. It is a user assembling a toolkit:
- `Mole` for broad cleanup and monitoring
- `Lemon` for native GUI all-in-one cleanup expectations
- `Pearcleaner` for uninstall depth
- `GrandPerspective` or similar tools for disk visualization
- `Czkawka` for duplicate / large-file hygiene
That means Atlas wins only if it makes the integrated workflow meaningfully safer and easier than stitching together multiple specialist tools.
## Strategic Implications For Atlas
### 1. Atlas should own the trust architecture lane
This is the strongest differentiator that the current open-source set does not combine well:
- explainable findings
- structured worker/helper boundary
- visible permission rationale
- history
- recoverable actions
### 2. `Smart Clean` breadth is the highest product risk
Per [Smart-Clean-Execution-Coverage-2026-03-09.md](./Smart-Clean-Execution-Coverage-2026-03-09.md), Atlas currently executes a safe structured subset of targets. That is honest and correct, but it also means Atlas can lose obvious comparisons to `Mole` unless release messaging stays precise and execution coverage expands.
### 3. `Apps` depth should be benchmarked against Pearcleaner, not generic cleaners
Atlas already includes app uninstall flows, but the market standard for open-source Mac uninstall depth is closer to Pearcleaner's footprint search, services/package awareness, and native integrations.
### 4. License hygiene must stay strict
- `Mole` is the only clearly safe major upstream from this set for Atlas's current MIT-oriented posture.
- `Lemon`, `GrandPerspective`, and parts of `Czkawka` carry GPL constraints and should be treated as product/UX references, not casual reuse candidates.
- `Pearcleaner` and `GrandPerspective` should be treated as product references, not code reuse candidates.
- `Czkawka` components need per-component license review before any adaptation.
### 5. Deferred scope must stay deferred
`GrandPerspective` makes storage treemap look attractive, but Atlas has explicitly deferred `Storage treemap` from MVP. The correct move is to use it as future design reference, not as a reason to reopen MVP.
## Recommended Next Steps
- Product:
- Position Atlas explicitly as an `explainable, recovery-first Mac maintenance workspace`, not just a cleaner.
- Smart Clean:
- Expand release-grade execution coverage on the categories users will compare most directly with Mole: caches, developer artifacts, and high-confidence junk roots.
- Apps:
- Run a gap review against Pearcleaner feature depth for uninstall leftovers, services, package artifacts, and automation entry points.
- Architecture:
- Keep leaning into worker/helper and structured recovery. That is Atlas's most defensible open-source differentiation.
- Messaging:
- Be exact about what runs for real today. Over-claiming breadth would erase Atlas's trust advantage.
## Sources
### Internal Atlas docs
1. [PRD.md](../PRD.md)
2. [Architecture.md](../Architecture.md)
3. [Smart-Clean-Execution-Coverage-2026-03-09.md](./Smart-Clean-Execution-Coverage-2026-03-09.md)
### Mole
1. [tw93/Mole](https://github.com/tw93/Mole)
2. [Mole README](https://raw.githubusercontent.com/tw93/Mole/main/README.md)
3. [Mole go.mod](https://raw.githubusercontent.com/tw93/Mole/main/go.mod)
4. [Mole latest release `V1.30.0` published on 2026-03-08](https://github.com/tw93/Mole/releases/tag/V1.30.0)
### Pearcleaner
1. [alienator88/Pearcleaner](https://github.com/alienator88/Pearcleaner)
2. [Pearcleaner README](https://raw.githubusercontent.com/alienator88/Pearcleaner/main/README.md)
3. [Pearcleaner app entrypoint](https://github.com/alienator88/Pearcleaner/blob/main/Pearcleaner/PearcleanerApp.swift)
4. [Pearcleaner helper entrypoint](https://github.com/alienator88/Pearcleaner/blob/main/PearcleanerHelper/main.swift)
5. [Pearcleaner license](https://github.com/alienator88/Pearcleaner/blob/main/LICENSE.md)
6. [Pearcleaner latest release `5.4.3` published on 2025-11-26](https://github.com/alienator88/Pearcleaner/releases/tag/5.4.3)
### Lemon
1. [Tencent/lemon-cleaner](https://github.com/Tencent/lemon-cleaner)
2. [Lemon README](https://raw.githubusercontent.com/Tencent/lemon-cleaner/master/README.md)
3. [腾讯柠檬清理官网](https://lemon.qq.com)
### Czkawka
1. [qarmin/czkawka](https://github.com/qarmin/czkawka)
2. [Czkawka README](https://raw.githubusercontent.com/qarmin/czkawka/master/README.md)
3. [Czkawka Cargo workspace](https://github.com/qarmin/czkawka/blob/master/Cargo.toml)
4. [Krokiet README](https://github.com/qarmin/czkawka/blob/master/krokiet/README.md)
5. [Czkawka latest release `11.0.1` published on 2026-02-21](https://github.com/qarmin/czkawka/releases/tag/11.0.1)
### GrandPerspective
1. [GrandPerspective SourceForge source tree](https://sourceforge.net/p/grandperspectiv/source/ci/master/tree/)
### MacSpaceCleaner
1. [sanketk2020/MacSpaceCleaner](https://github.com/sanketk2020/MacSpaceCleaner)
2. [MacSpaceCleaner README](https://raw.githubusercontent.com/sanketk2020/MacSpaceCleaner/main/README.md)

22
Docs/Execution/RalphLoop-ATL-211-214-226-230.task.yaml Normal file
View File

@@ -0,0 +1,22 @@
task_id: atl-211-214-226-230
goal: >
按 Docs/Execution/Implementation-Plan-ATL-211-214-226-230-2026-03-21.md
实现第一阶段 selective parity 开发切片：提升 Smart Clean 在高置信安全清理类目上的竞争可信度，
并增强 Apps 卸载预览、完成态与审计/恢复线索。必须保持 MVP 冻结，不引入新产品面。
constraints:
- 不要扩展出 frozen MVP 范围之外的新模块或新表面。
- 不要引入 Storage treemap、Menu Bar、Automation、重复文件/相似照片/隐私清理新模块。
- 不要在 UI、文档或完成态中暗示 Atlas 已与 Mole、Lemon、Pearcleaner 全面同等。
- unsupported 或 review-only 路径必须保持 fail-closed 和明确提示。
verify_commands:
- swift test --package-path Packages --filter AtlasInfrastructureTests
- swift test --package-path Packages --filter AtlasApplicationTests
- swift test --package-path Apps --filter AtlasAppModelTests
adapter: codex_cli
adapter_config:
sandbox: workspace-write
full_auto: true
timeout_seconds: 600
max_iterations: 5
timeout_minutes: 45
rollback_on_fail: false

128
Docs/Execution/Selective-Parity-Week-2026-03-23.md Normal file
View File

@@ -0,0 +1,128 @@
# Selective Parity Week — 2026-03-23
## Context
Atlas now has a documented competitive strategy:
- keep MVP frozen
- preserve trust as the primary moat
- selectively close the most visible comparison gaps against `Mole`, `Tencent Lemon Cleaner`, and `Pearcleaner`
This week plan turns that strategy into the next development-ready execution window.
Related docs:
- [Open-Source-Competitor-Research-2026-03-21.md](./Open-Source-Competitor-Research-2026-03-21.md)
- [Competitive-Strategy-Plan-2026-03-21.md](./Competitive-Strategy-Plan-2026-03-21.md)
- [ROADMAP.md](../ROADMAP.md)
## Planned Window
- `2026-03-23` to `2026-03-27`
## Goal
Prepare Atlas's next coding phase so that development can start immediately on the two highest-pressure competitive surfaces:
- `Smart Clean` selective parity against `Mole` and `Lemon`
- `Apps` depth and uninstall trust against `Pearcleaner` and `Lemon`
## Scope
Stay inside frozen MVP:
- `Overview`
- `Smart Clean`
- `Apps`
- `History`
- `Recovery`
- `Permissions`
- `Settings`
Do not expand into:
- `Storage treemap`
- `Menu Bar`
- `Automation`
- duplicate-file or similar-photo cleanup as new Atlas modules
- privacy-cleaning as a new standalone module
## Must Deliver
- A concrete competitor-pressure matrix for `Smart Clean` and `Apps`
- A fixture-backed validation plan for uninstall depth and supported cleanup classes
- One implementation-ready plan for the first selective-parity coding slice
- Updated acceptance criteria for `Smart Clean` and `Apps`
- Updated release-facing beta checklist so validation reflects competitive trust requirements
## Backlog Mapping
- `ATL-211` Expand real `Smart Clean` execute coverage for top safe target classes most likely compared to `Mole` and `Lemon`
- `ATL-214` Make history and completion states reflect real side effects only
- `ATL-226` Build a competitor-pressure matrix for `Apps` using representative `Pearcleaner` and `Lemon` uninstall scenarios
- `ATL-227` Expand uninstall preview taxonomy and leftover evidence for supported app footprint categories
- `ATL-228` Surface recoverability, auditability, and supported-vs-review-only cues directly in the `Apps` flow
- `ATL-229` Validate uninstall depth on mainstream and developer-heavy fixture apps
## Day Plan
- `Day 1`
- finalize competitor-pressure matrix
- freeze non-goals and no-go boundaries for selective parity work
- `Day 2`
- define fixture app set and Smart Clean target-class benchmark set
- confirm acceptance and validation expectations
- `Day 3`
- write the detailed implementation plan for the first coding slice
- identify likely file-touch map and contract-test map
- `Day 4`
- align beta checklist and MVP acceptance matrix with the selective-parity strategy
- verify risks and roadmap still match
- `Day 5`
- hold an internal doc gate for development readiness
- confirm the next coding session can begin without planning gaps
## Owner Tasks
- `Product Agent`
- keep parity work bounded to visible comparison pressure only
- reject backlog inflation that does not strengthen the frozen MVP
- `UX Agent`
- define visible trust cues for supported, unsupported, and review-only actions
- keep Atlas's UI difference legible against broader cleaner tools
- `Mac App Agent`
- identify concrete UI surfaces that must change in `Smart Clean`, `Apps`, `History`, and completion states
- `Core Agent`
- define the preview taxonomy and structured evidence that the UI can actually render
- `System Agent`
- define which additional safe cleanup classes are realistic next targets for `Smart Clean`
- `QA Agent`
- define the fixture set, comparison scenarios, and contract-style checks
- `Docs Agent`
- keep strategy, acceptance, roadmap, and release-check documents aligned
## Validation Plan
### Planning Validation
- every new task maps to existing MVP surfaces
- every new acceptance criterion is testable
- every parity goal has an explicit competitor reference and an explicit Atlas non-goal
### Readiness Validation
- at least one implementation-ready plan exists for the next coding slice
- acceptance matrix and beta checklist reflect the new competitive gates
- no document implies that Atlas is reopening deferred scope
## Exit Criteria
- selective parity work is expressed as tasks, acceptance, and validation rather than just strategy prose
- `Smart Clean` and `Apps` both have explicit competitor-driven targets
- next coding session can start without another planning pass
## Known Blockers
- signed public beta remains blocked by missing Apple release credentials
- `Smart Clean` breadth still has to stay subordinate to execution honesty
- `Apps` depth work must remain bounded by what Atlas can safely prove and recover