Internal beta hardening: pnpm cleanup and recovery semantics

- update internal beta hardening docs and Smart Clean execution coverage for the 2026-03-16 hardening slice - add pnpm store detection, execution fixtures, and regression coverage across adapters, infrastructure, and app model tests - distinguish file-backed vs Atlas-only recovery messaging in History and restore summaries - preserve completed Smart Clean recovery entries when later targets fail, and report failed findings explicitly instead of losing side effects
2026-03-12 23:19:18 +08:00
parent 534329b72f
commit 11405a4b55
13 changed files with 963 additions and 45 deletions
--- a/Docs/Execution/Internal-Beta-Hardening-Week-2026-03-16.md
+++ b/Docs/Execution/Internal-Beta-Hardening-Week-2026-03-16.md
@@ -1,6 +1,15 @@
-# Internal Beta Hardening Week Plan
+# Internal Beta Hardening Week — 2026-03-16

-## Window
+## Context
+
+This document now serves two purposes:
+
+- the **week plan** for the internal-beta hardening window
+- the **execution record** for the hardening work completed on **2026-03-12** before the week formally opens
+
+The path `Docs/Execution/Internal-Beta-Hardening-Week-2026-03-16.md` did not exist at the start of the hardening pass. One side of the rebase introduced the week plan, while the other introduced the initial execution record, so this merged version keeps both.
+
+## Planned Window

 - `2026-03-16` to `2026-03-20`

@@ -103,3 +112,183 @@ Do not expand into:

 - Public release work remains blocked by missing Apple signing and notarization credentials
 - Recovery still requires explicit wording discipline wherever physical restore is not yet guaranteed
+
+## Outcome Snapshot
+
+### Landed in this pass
+
+- Added one new real Smart Clean execute target class for `~/Library/pnpm/store/*`.
+- Added stronger worker-side truthfulness so Atlas only records recovery/history side effects when a real file move happened.
+- Split History recovery messaging between:
+  - file-backed restore entries with `restoreMappings`
+  - Atlas-only recovery entries with no supported on-disk restore path
+- Rebuilt the latest native artifacts and verified packaged install plus fresh-state launch.
+
+### Current blocker
+
+- Interactive bilingual UI automation on this machine is **blocked** by macOS Accessibility trust for the current terminal process.
+- `./scripts/atlas/ui-automation-preflight.sh` reported `Accessibility trusted for current process: false` on **2026-03-12**.
+
+This means the packaged-build install and fresh-state launch checks below are complete, but a full click-through clean-machine bilingual UI walkthrough still requires either:
+
+- Accessibility trust to be granted on this Mac, or
+- a separate clean machine for the final interactive pass.
+
+## Packaged-Build Evidence
+
+### Latest artifacts built on 2026-03-12
+
+- App: `dist/native/Atlas for Mac.app`
+- DMG: `dist/native/Atlas-for-Mac.dmg`
+- PKG: `dist/native/Atlas-for-Mac.pkg`
+- ZIP: `dist/native/Atlas-for-Mac.zip`
+- Checksums: `dist/native/Atlas-for-Mac.sha256`
+
+### Checksum record
+
+```text
+b85425649c5d781f234cdf1690ce01f330e3216d963cbf7d8f720a2e66611ffa  Atlas-for-Mac.zip
+2d5f480110d13f83c38e2296fafaa72617fc122d694d78c2c32c3a260f0ae110  Atlas-for-Mac.dmg
+d71c45b0312ceeb045e390d851e246fe7f59e90961f2a482cfb21ee4f65d56ec  Atlas-for-Mac.pkg
+```
+
+### Verified commands
+
+- `./scripts/atlas/package-native.sh` — **pass** on 2026-03-12
+- `KEEP_INSTALLED_APP=1 ./scripts/atlas/verify-dmg-install.sh` — **pass** on 2026-03-12
+- `STATE_DIR="$PWD/.build/atlas-hardening-fresh-state-2026-03-12" ./scripts/atlas/verify-app-launch.sh` — **pass** on 2026-03-12
+
+### Fresh-state file evidence
+
+- State directory: `.build/atlas-hardening-fresh-state-2026-03-12`
+- New state file: `.build/atlas-hardening-fresh-state-2026-03-12/workspace-state.json`
+- First-launch persisted language in that brand-new state file: `zh-Hans`
+
+This is a machine-local fresh-state packaged-build verification, not a claim of having used a second physical clean Mac.
+
+## Must-Deliver Status
+
+### 1. Clean-machine bilingual QA
+
+**Status:** `Partially complete / locally blocked`
+
+Completed evidence:
+
+- Packaged install path verified to `~/Applications/Atlas for Mac.app`
+- Fresh-state packaged launch verified with a brand-new workspace-state directory
+- Default first-launch language persisted as `zh-Hans`
+- Language-switch persistence covered by app-model test evidence
+- Smart Clean, Apps, and Recovery trust paths covered by package and app tests listed below
+
+Remaining blocker:
+
+- Interactive packaged-app UI walkthrough for first launch + bilingual control verification is blocked on local Accessibility trust
+
+### 2. Fresh-state verification with latest packaged build
+
+**Status:** `Complete`
+
+- Latest packaged build created in `dist/native`
+- DMG install verification passed
+- Fresh-state launch verification passed against `.build/atlas-hardening-fresh-state-2026-03-12`
+
+### 3. One concrete increment in real Smart Clean execute coverage
+
+**Status:** `Complete`
+
+New safe direct-trash target class added:
+
+- `~/Library/pnpm/store/*`
+
+Code path:
+
+- Allowlist: `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift`
+- Parser/title recognition: `Packages/AtlasCoreAdapters/Sources/AtlasCoreAdapters/MoleSmartCleanAdapter.swift`
+
+### 4. Stronger `scan -> execute -> rescan` contract evidence
+
+**Status:** `Complete`
+
+New and existing contract evidence now covers:
+
+- existing cache-backed real path
+- new pnpm-store real path
+- stale-target handling where Atlas must not claim a physical move
+
+### 5. History/completion surfaces only claim real side effects
+
+**Status:** `Complete`
+
+Behavior tightened so that:
+
+- no recovery entry is created when the selected Smart Clean target is already absent on disk
+- restore summaries distinguish file-backed restore from Atlas-only state restoration
+- History callouts and restore button hints distinguish on-disk restore from Atlas-only restore
+
+## Test Evidence
+
+### Adapter + infrastructure
+
+- `swift test --package-path Packages --filter MoleSmartCleanAdapterTests` — **pass** on 2026-03-12
+- `swift test --package-path Packages --filter AtlasInfrastructureTests` — **pass** on 2026-03-12
+
+Key tests:
+
+- `testParseDetailedFindingsBuildsExecutableTargets`
+- `testPnpmStoreTargetIsSupportedExecutionTarget`
+- `testScanExecuteRescanRemovesExecutedPnpmStoreTargetFromRealResults`
+- `testExecutePlanDoesNotCreateRecoveryEntryWhenTargetIsAlreadyGone`
+- `testRestoreItemsStateOnlySummaryDoesNotClaimOnDiskRestore`
+- `testRestoreRecoveryItemPhysicallyRestoresRealTargets`
+
+### App-model coverage
+
+- `swift test --package-path Apps --filter AtlasAppModelTests` — **pass** on 2026-03-12
+
+Key tests:
+
+- `testSetLanguagePersistsThroughWorkerAndUpdatesLocalization`
+- `testPreferredXPCWorkerPathFailsClosedWhenScanIsRejected`
+- `testExecuteCurrentPlanExposesExplicitExecutionIssueWhenWorkerRejectsExecution`
+- `testExecuteCurrentPlanOnlyRecordsRecoveryForRealSideEffects`
+- `testRestoreRecoveryItemReturnsFindingToWorkspace`
+
+## QA Matrix
+
+| Area | Evidence | Status |
+| --- | --- | --- |
+| First launch | packaged app launch smoke with new state dir | Pass |
+| Install path | DMG install validation to `~/Applications` | Pass |
+| Default language | fresh packaged state file persisted `zh-Hans` | Pass |
+| Language switching | app-model persistence test; UI click-through still blocked locally | Partial |
+| Smart Clean execute | package tests + real file-backed contract tests | Pass |
+| Apps | app-model and infrastructure uninstall/recovery tests | Pass |
+| History / Recovery | file-backed vs Atlas-only summary/copy split + restore tests | Pass |
+
+## Copy Guardrails After This Pass
+
+Do keep saying:
+
+- `Smart Clean only claims real cleanup for supported targets it actually moved.`
+- `History distinguishes on-disk restore from Atlas-only restoration.`
+- `Recovery can only claim physical return when a supported restore mapping exists.`
+
+Do not say:
+
+- `Every recoverable item returns to disk.`
+- `Smart Clean moved an item` when the file was already absent.
+- `Restore succeeded on disk` for Atlas-only recovery records.
+
+## Files Changed for Hardening
+
+- `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift`
+- `Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift`
+- `Packages/AtlasCoreAdapters/Sources/AtlasCoreAdapters/MoleSmartCleanAdapter.swift`
+- `Packages/AtlasCoreAdapters/Tests/AtlasCoreAdaptersTests/MoleSmartCleanAdapterTests.swift`
+- `Packages/AtlasFeaturesHistory/Sources/AtlasFeaturesHistory/HistoryFeatureView.swift`
+- `Packages/AtlasDomain/Sources/AtlasDomain/Resources/en.lproj/Localizable.strings`
+- `Packages/AtlasDomain/Sources/AtlasDomain/Resources/zh-Hans.lproj/Localizable.strings`
+- `Apps/AtlasApp/Tests/AtlasAppTests/AtlasAppModelTests.swift`
+- `scripts/atlas/smart-clean-manual-fixtures.sh`
+- `Docs/Execution/Smart-Clean-Execution-Coverage-2026-03-09.md`
+- `Docs/Execution/Smart-Clean-Manual-Verification-2026-03-09.md`
--- a/Docs/Execution/Smart-Clean-Execution-Coverage-2026-03-09.md
+++ b/Docs/Execution/Smart-Clean-Execution-Coverage-2026-03-09.md
@@ -31,6 +31,7 @@ These user-owned targets can be moved to Trash directly by the worker when they
 - `~/Library/Suggestions/*`
 - `~/Library/Messages/Caches/*`
 - `~/Library/Developer/Xcode/DerivedData/*`
+- `~/Library/pnpm/store/*`
 - `~/.npm/*`
 - `~/.npm_cache/*`
 - `~/.oh-my-zsh/cache/*`
@@ -117,6 +118,11 @@ That means:
 - the item can reappear in Atlas UI state
 - the underlying file may not be physically restored on disk

+The History surface now needs to reflect this split explicitly:
+
+- file-backed recovery entries can claim on-disk return only when `restoreMappings` exist
+- Atlas-only recovery entries must describe themselves as workspace-state restoration, not physical file restoration
+
 ## Product Messaging Guidance

 Use these statements consistently in user-facing communication:
--- a/Docs/Execution/Smart-Clean-Manual-Verification-2026-03-09.md
+++ b/Docs/Execution/Smart-Clean-Manual-Verification-2026-03-09.md
@@ -28,6 +28,7 @@ The helper creates disposable fixtures under these locations:
 - `~/Library/Logs/AtlasExecutionFixturesLogs`
 - `~/Library/Developer/Xcode/DerivedData/AtlasExecutionFixturesDerivedData`
 - `~/Library/Caches/AtlasExecutionFixturesPycache`
+- `~/Library/pnpm/store/v3/files/AtlasExecutionFixturesPnpm`

 These locations are chosen because the current Smart Clean implementation can execute and restore them for real.

@@ -41,7 +42,7 @@ These locations are chosen because the current Smart Clean implementation can ex

 Expected:
 - The script prints the created roots and files.
- `status` shows non-zero size under all four fixture roots.
+- `status` shows non-zero size under all five fixture roots.

 ### 2. Confirm upstream dry-run sees the fixtures

@@ -54,6 +55,7 @@ Expected:
  - `~/Library/Caches`
  - `~/Library/Logs`
  - `~/Library/Developer/Xcode/DerivedData`
+  - `~/Library/pnpm/store`
 - The fixture helper `status` output gives you the exact on-disk paths to compare before and after execution.

 ### 3. Run Smart Clean scan in the app
--- a/Docs/plans/2026-03-12-internal-beta-hardening-week.md
+++ b/Docs/plans/2026-03-12-internal-beta-hardening-week.md
@@ -0,0 +1,166 @@
+# Internal Beta Hardening Week Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make the internal-beta candidate truthful for the 2026-03-16 hardening week by adding one new real Smart Clean execution path, tightening history/recovery claims, and capturing packaged-build QA evidence.
+
+**Architecture:** Keep the existing real scan → worker execute → recovery-mapping model, but extend the Smart Clean execution allowlist for one high-value safe target class that the upstream Mole runtime already exports. Tighten worker summaries and History UI copy so Atlas only claims physical side effects when a real file move or restore mapping exists, then document packaged-build fresh-state verification in a dedicated execution note.
+
+**Tech Stack:** Swift Package Manager, SwiftUI, XCTest, shell packaging scripts, Xcode build/package flow.
+
+---
+
+### Task 1: Add One New Safe Smart Clean Target Class
+
+**Files:**
+- Modify: `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift`
+- Modify: `Packages/AtlasCoreAdapters/Sources/AtlasCoreAdapters/MoleSmartCleanAdapter.swift`
+- Test: `Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift`
+- Test: `Packages/AtlasCoreAdapters/Tests/AtlasCoreAdaptersTests/MoleSmartCleanAdapterTests.swift`
+
+**Step 1: Write the failing adapter and support tests**
+
+Add tests for a `~/Library/pnpm/store/...` target so the repo proves:
+
+- the detailed scan parser exposes a recognizable pnpm finding with structured `targetPaths`
+- the worker allowlist treats `~/Library/pnpm/store/*` as a directly trashable safe target
+- a file-backed `scan -> execute -> rescan` flow works for that target class
+
+**Step 2: Run the focused tests to verify they fail**
+
+Run:
+
+```bash
+swift test --package-path Packages --filter MoleSmartCleanAdapterTests
+swift test --package-path Packages --filter AtlasInfrastructureTests
+```
+
+Expected:
+
+- the pnpm target is not yet recognized or supported
+
+**Step 3: Add the minimal implementation**
+
+Implement:
+
+- `~/Library/pnpm/store/*` in `AtlasSmartCleanExecutionSupport.isDirectlyTrashable`
+- a readable title mapping such as `pnpm store` in `MoleSmartCleanAdapter.makeDetailedTitle`
+
+**Step 4: Re-run the focused tests**
+
+Run the same package tests and confirm the pnpm-target coverage passes.
+
+**Step 5: Commit**
+
+```bash
+git add Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift Packages/AtlasCoreAdapters/Sources/AtlasCoreAdapters/MoleSmartCleanAdapter.swift Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift Packages/AtlasCoreAdapters/Tests/AtlasCoreAdaptersTests/MoleSmartCleanAdapterTests.swift
+git commit -m "feat: support pnpm store smart clean execution"
+```
+
+### Task 2: Make History and Completion Claims Match Real Side Effects
+
+**Files:**
+- Modify: `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift`
+- Modify: `Packages/AtlasFeaturesHistory/Sources/AtlasFeaturesHistory/HistoryFeatureView.swift`
+- Modify: `Packages/AtlasDomain/Sources/AtlasDomain/Resources/en.lproj/Localizable.strings`
+- Modify: `Packages/AtlasDomain/Sources/AtlasDomain/Resources/zh-Hans.lproj/Localizable.strings`
+- Test: `Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift`
+
+**Step 1: Write the failing truthfulness tests**
+
+Add tests that prove:
+
+- executing a supported plan whose file is already gone does not create a recovery item that implies Atlas moved it
+- restore summaries distinguish physical restore from Atlas-state-only restore records
+
+**Step 2: Run the focused infrastructure tests to verify failure**
+
+Run:
+
+```bash
+swift test --package-path Packages --filter AtlasInfrastructureTests
+```
+
+Expected:
+
+- current summaries and recovery bookkeeping still overclaim physical side effects
+
+**Step 3: Implement the worker-side fix**
+
+Update the scaffold worker so that:
+
+- only findings with real `RecoveryPathMapping` entries create recovery items and count as “moved”
+- missing-on-disk findings are cleared without being counted as physical execution
+- restore summaries explicitly distinguish on-disk restore from Atlas-only state restoration
+
+**Step 4: Implement the History UI copy split**
+
+Update `HistoryFeatureView` and localization keys so recovery callouts and button hints reflect:
+
+- supported file-backed restore paths
+- Atlas-only restore records with no physical restore path
+
+**Step 5: Re-run the focused tests**
+
+Run the package tests again and confirm the truthfulness assertions pass.
+
+**Step 6: Commit**
+
+```bash
+git add Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift Packages/AtlasFeaturesHistory/Sources/AtlasFeaturesHistory/HistoryFeatureView.swift Packages/AtlasDomain/Sources/AtlasDomain/Resources/en.lproj/Localizable.strings Packages/AtlasDomain/Sources/AtlasDomain/Resources/zh-Hans.lproj/Localizable.strings Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift
+git commit -m "fix: keep history claims aligned with real side effects"
+```
+
+### Task 3: Capture Hardening-Week QA and Packaged-Build Evidence
+
+**Files:**
+- Create: `Docs/Execution/Internal-Beta-Hardening-Week-2026-03-16.md`
+- Modify: `Docs/Execution/Smart-Clean-Execution-Coverage-2026-03-09.md`
+- Modify: `Docs/Execution/Smart-Clean-Manual-Verification-2026-03-09.md`
+- Modify: `scripts/atlas/smart-clean-manual-fixtures.sh`
+
+**Step 1: Update the manual fixture coverage**
+
+Add the new safe target class to the fixture script and manual verification doc so QA can create disposable evidence for the new real execution path.
+
+**Step 2: Build the latest packaged app**
+
+Run:
+
+```bash
+./scripts/atlas/package-native.sh
+```
+
+Expected:
+
+- latest `.app`, `.dmg`, and `.pkg` artifacts land in `dist/native`
+
+**Step 3: Verify install and fresh-state launch**
+
+Run:
+
+```bash
+KEEP_INSTALLED_APP=1 ./scripts/atlas/verify-dmg-install.sh
+STATE_DIR="$PWD/.build/atlas-hardening-fresh-state" ./scripts/atlas/verify-app-launch.sh
+```
+
+Expected:
+
+- packaged install succeeds
+- packaged app launches against a brand-new workspace-state directory
+
+**Step 4: Document bilingual QA and contract evidence**
+
+Create `Docs/Execution/Internal-Beta-Hardening-Week-2026-03-16.md` with:
+
+- clean-machine bilingual QA checklist/results for first launch, language switching, install path, Smart Clean, Apps, and History/Recovery
+- fresh-state packaged-build verification notes and exact artifact paths
+- test evidence for the new safe target class and `scan -> execute -> rescan`
+- explicit copy constraints that prevent restore/execution overclaiming
+
+**Step 5: Commit**
+
+```bash
+git add Docs/Execution/Internal-Beta-Hardening-Week-2026-03-16.md Docs/Execution/Smart-Clean-Execution-Coverage-2026-03-09.md Docs/Execution/Smart-Clean-Manual-Verification-2026-03-09.md scripts/atlas/smart-clean-manual-fixtures.sh dist/native
+git commit -m "docs: capture internal beta hardening evidence"
+```