# Recovery Credibility Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Freeze Atlas recovery semantics against shipped behavior by adding missing restore coverage and publishing explicit acceptance evidence and a gate review for ATL-221 through ATL-225.

**Architecture:** The worker already supports restore mappings for file-backed recovery items and Atlas-only rehydration for older/state-only records. This slice should avoid widening restore scope; instead it should prove the current contract with focused automated tests, then freeze that contract in execution docs and a recovery gate review.

**Tech Stack:** Swift Package Manager, XCTest, Markdown docs

---

### Task 1: Add helper-backed app restore coverage

**Files:**
- Modify: `Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift`
- Check: `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift`

**Step 1: Write the failing test**

Add a test that:
- creates a fake installed app under `~/Applications/AtlasExecutionTests/...`
- injects a stub `AtlasPrivilegedActionExecuting`
- executes app uninstall
- restores the resulting recovery item
- asserts the app bundle returns to its original path and the restore summary uses the disk-backed wording

**Step 2: Run test to verify it fails**

Run: `swift test --package-path Packages --filter AtlasInfrastructureTests/testExecuteAppUninstallRestorePhysicallyRestoresAppBundle`
Expected: FAIL until the stub/helper-backed path is wired correctly in the test.

**Step 3: Write minimal implementation**

Implement only the test support needed:
- a stub helper executor that handles `.trashItems` and `.restoreItem`
- deterministic assertions for returned `restoreMappings`

**Step 4: Run test to verify it passes**

Run: `swift test --package-path Packages --filter AtlasInfrastructureTests/testExecuteAppUninstallRestorePhysicallyRestoresAppBundle`
Expected: PASS

**Step 5: Commit**

```bash
git add Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift
git commit -m "test: cover helper-backed app restore"
```

### Task 2: Add mixed recovery summary coverage

**Files:**
- Modify: `Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift`
- Check: `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasInfrastructure.swift:1086`

**Step 1: Write the failing test**

Add a test that restores:
- one recovery item with `restoreMappings`
- one recovery item without `restoreMappings`

Assert the task summary contains both:
- disk restore wording
- Atlas-only restore wording

**Step 2: Run test to verify it fails**

Run: `swift test --package-path Packages --filter AtlasInfrastructureTests/testRestoreItemsMixedSummaryIncludesDiskAndStateOnlyClauses`
Expected: FAIL if the combined contract is not proven yet.

**Step 3: Write minimal implementation**

If needed, adjust only test fixtures or summary generation so mixed restores preserve both clauses without overstating physical restore.

**Step 4: Run test to verify it passes**

Run: `swift test --package-path Packages --filter AtlasInfrastructureTests/testRestoreItemsMixedSummaryIncludesDiskAndStateOnlyClauses`
Expected: PASS

**Step 5: Commit**

```bash
git add Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift
git commit -m "test: cover mixed recovery summaries"
```

### Task 3: Freeze recovery contract and evidence

**Files:**
- Create: `Docs/Execution/Recovery-Contract-2026-03-13.md`
- Create: `Docs/Execution/Recovery-Credibility-Gate-Review-2026-03-13.md`
- Modify: `Docs/README.md`
- Check: `Docs/Protocol.md`
- Check: `README.md`
- Check: `README.zh-CN.md`
- Check: `Packages/AtlasDomain/Sources/AtlasDomain/Resources/en.lproj/Localizable.strings`
- Check: `Packages/AtlasDomain/Sources/AtlasDomain/Resources/zh-Hans.lproj/Localizable.strings`

**Step 1: Write the contract doc**

Document exactly what Atlas promises today:
- file-backed recovery physically restores only when `restoreMappings` exist
- Atlas-only recovery rehydrates workspace state without claiming on-disk return
- helper-backed restore is required for protected paths like app bundles
- restore fails closed when the trash source is gone, the destination already exists, or helper capability is unavailable

**Step 2: Write the evidence section**

Reference automated proof points:
- direct-trash cache restore test
- helper-backed app uninstall restore test
- mixed summary/state-only tests
- existing `scan -> execute -> rescan` coverage for supported targets

**Step 3: Write the gate review**

Mirror the existing execution gate format and record:
- scope reviewed (`ATL-221` to `ATL-225`)
- evidence reviewed
- automated validation summary
- remaining limits
- decision and follow-up conditions

**Step 4: Update docs index**

Add the new recovery contract and gate review docs to `Docs/README.md`.

**Step 5: Commit**

```bash
git add Docs/Execution/Recovery-Contract-2026-03-13.md Docs/Execution/Recovery-Credibility-Gate-Review-2026-03-13.md Docs/README.md
git commit -m "docs: freeze recovery contract and gate evidence"
```

### Task 4: Run focused validation

**Files:**
- Check: `Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift`
- Check: `Docs/Execution/Recovery-Contract-2026-03-13.md`
- Check: `Docs/Execution/Recovery-Credibility-Gate-Review-2026-03-13.md`

**Step 1: Run targeted infrastructure tests**

Run: `swift test --package-path Packages --filter AtlasInfrastructureTests`
Expected: PASS

**Step 2: Run broader package tests**

Run: `swift test --package-path Packages`
Expected: PASS

**Step 3: Sanity-check docs claims**

Verify every new doc line matches one of:
- protocol contract
- localized UI copy
- automated test evidence

**Step 4: Summarize remaining limits**

Call out that:
- physical restore is still partial by design
- unsupported or older recovery items remain Atlas-state-only
- broader restore scope should not expand without new allowlist and QA evidence

**Step 5: Commit**

```bash
git add Docs/README.md Docs/Execution/Recovery-Contract-2026-03-13.md Docs/Execution/Recovery-Credibility-Gate-Review-2026-03-13.md Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasInfrastructureTests.swift
git commit -m "chore: validate recovery credibility slice"
```