ralph-loop[epic-a-to-d-mainline]: checkpoint before iteration

2026-03-23 17:14:09 +08:00
parent 889cecd383
commit 0550568a2b
4 changed files with 197 additions and 68 deletions
--- a/Docs/Backlog.md
+++ b/Docs/Backlog.md
@@ -52,6 +52,10 @@
 - `EPIC-19` GA Recovery and Execution Hardening
 - `EPIC-20` GA Launch Readiness
 - `EPIC-21` Marketing Site and Direct Distribution Landing Page
+- `EPIC-A` Apps Evidence Execution
+- `EPIC-B` Smart Clean Safe Coverage Expansion
+- `EPIC-C` Recovery Payload Hardening
+- `EPIC-D` Release Readiness

 ## Now / Next / Later

@@ -208,6 +212,7 @@
 - `Complete` — frozen MVP is implemented and internally beta-ready.
 - `Blocked` — release trust still depends on removing silent fallback and tightening execution/recovery honesty.
 - `Dormant` — signed public beta work is inactive until Apple signing/notarization credentials exist.
+- `Superseded` — the live post-hardening epic sequence now lives in `Current Mainline Priority Order` below.

 ### Focus

@@ -302,6 +307,85 @@
 - `ATL-245` Surface release-channel state, download guidance, and prerelease install help on the page — `UX Agent`
 - `ATL-246` Add privacy-respecting analytics and launch QA for desktop/mobile — `QA Agent`

+## Current Mainline Priority Order
+
+### Current Status
+
+- `Complete` — internal beta hardening established the current execution-honesty baseline.
+- `Open` — the most visible comparison pressure is now concentrated in `Apps` and `Smart Clean`.
+- `Blocked` — final public-signing work still depends on `Developer ID` and notarization materials, so release mechanics are not the immediate product-path blocker.
+
+### Order Rule
+
+Execute the next mainline epics in this order only:
+
+1. `EPIC-A` Apps Evidence Execution
+2. `EPIC-B` Smart Clean Safe Coverage Expansion
+3. `EPIC-C` Recovery Payload Hardening
+4. `EPIC-D` Release Readiness
+
+Reason:
+
+- the clearest competitive differentiation pressure is in `Apps` and `Smart Clean`
+- the current release chain is already mostly working in pre-signing form
+- the gating blocker for public release remains missing signing materials, not packaging mechanics
+
+### Epics
+
+- `EPIC-A` Apps Evidence Execution
+- `EPIC-B` Smart Clean Safe Coverage Expansion
+- `EPIC-C` Recovery Payload Hardening
+- `EPIC-D` Release Readiness
+
+### Now / Next / Later
+
+#### Now
+
+- `EPIC-A` Apps Evidence Execution
+
+#### Next
+
+- `EPIC-B` Smart Clean Safe Coverage Expansion
+
+#### Later
+
+- `EPIC-C` Recovery Payload Hardening
+- `EPIC-D` Release Readiness
+
+### Seed Issues
+
+#### EPIC-A: Apps Evidence Execution
+
+- `ATL-251` Define the fixture app baseline for mainstream and developer-heavy uninstall scenarios — `QA Agent`
+- `ATL-252` Make `Apps` preview, completion, and history render the same uninstall evidence model end to end — `Core Agent` + `Mac App Agent`
+- `ATL-253` Define the restore-triggered app-footprint refresh policy and stale-evidence behavior after recovery — `Core Agent` + `System Agent`
+- `ATL-254` Script the manual acceptance flow for uninstall evidence, restore, and post-restore refresh verification — `QA Agent`
+- `ATL-255` Apps evidence execution gate review — `Product Agent`
+
+#### EPIC-B: Smart Clean Safe Coverage Expansion
+
+- `ATL-256` Define the next batch of high-confidence safe roots outside app containers and freeze the no-go boundaries — `System Agent`
+- `ATL-257` Stabilize `review-only` vs `executable` boundary metadata and UI cues across scan, review, execute, completion, and history — `Core Agent` + `Mac App Agent`
+- `ATL-258` Add `scan -> execute -> rescan` evidence capture and contract coverage for the expanded safe roots — `QA Agent`
+- `ATL-259` Implement and validate the next safe-root execution slice without widening into high-risk cleanup paths — `System Agent`
+- `ATL-260` Smart Clean safe coverage gate review — `Product Agent`
+
+#### EPIC-C: Recovery Payload Hardening
+
+- `ATL-261` Freeze the recovery payload schema, versioning rules, and compatibility contract — `Core Agent`
+- `ATL-262` Add migration and compatibility handling for older workspace and history state files — `Core Agent` + `System Agent`
+- `ATL-263` Expand `History` detail evidence to show restore payload, conflict, expiry, and partial-restore outcomes — `Mac App Agent`
+- `ATL-264` Add regression coverage for restore conflict, expired payload, and partial-restore scenarios — `QA Agent`
+- `ATL-265` Recovery payload hardening gate review — `Product Agent`
+
+#### EPIC-D: Release Readiness
+
+- `ATL-266` Make `full-acceptance` a routine gate on the candidate build instead of a one-off release exercise — `QA Agent`
+- `ATL-267` Stabilize UI automation for trust-critical `Overview`, `Smart Clean`, `Apps`, `History`, and `Recovery` flows — `QA Agent` + `Mac App Agent`
+- `ATL-268` Freeze packaging, install, and launch smoke checks as repeatable release scripts — `Release Agent`
+- `ATL-269` Switch from the pre-signing release chain to `Developer ID + notarization` once credentials are available — `Release Agent`
+- `ATL-270` Release readiness gate review — `Product Agent`
+
 ## Definition of Ready

 - Scope is clear and bounded
--- a/Docs/Execution/Selective-Parity-Week-2026-03-23.md
+++ b/Docs/Execution/Selective-Parity-Week-2026-03-23.md
@@ -22,10 +22,12 @@ Related docs:

 ## Goal

-Prepare Atlas's next coding phase so that development can start immediately on the two highest-pressure competitive surfaces:
+Prepare Atlas's next coding phase with a strict mainline order so development starts on the highest-pressure competitive surfaces first and does not drift into premature release work:

- `Smart Clean` selective parity against `Mole` and `Lemon`
- `Apps` depth and uninstall trust against `Pearcleaner` and `Lemon`
+- `EPIC-A` `Apps` evidence execution against `Pearcleaner` and `Lemon`
+- `EPIC-B` `Smart Clean` safe coverage expansion against `Mole` and `Lemon`
+- `EPIC-C` `Recovery` payload hardening
+- `EPIC-D` release readiness only after the product-path epics stabilize

 ## Scope

@@ -47,40 +49,57 @@ Do not expand into:
 - duplicate-file or similar-photo cleanup as new Atlas modules
 - privacy-cleaning as a new standalone module

+## Sequencing Rule
+
+Execute the next mainline epics in this order only:
+
+1. `EPIC-A` Apps Evidence Execution
+2. `EPIC-B` Smart Clean Safe Coverage Expansion
+3. `EPIC-C` Recovery Payload Hardening
+4. `EPIC-D` Release Readiness
+
+Why this order:
+
+- the clearest competitive comparison pressure is already concentrated in `Apps` and `Smart Clean`
+- the release chain is mostly working in pre-signing form
+- public release remains blocked by missing signing materials, not by packaging mechanics
+
 ## 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
+- A concrete fixture-backed baseline for `EPIC-A` uninstall evidence work
+- One implementation-ready plan for the first `Apps` evidence coding slice
+- A bounded target list for the next `Smart Clean` safe roots after `Apps`
+- Updated acceptance criteria for `Apps`, `Smart Clean`, and `Recovery`
+- Updated release-facing beta checklist so release work stays downstream of the product-path epics

 ## 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
+- `ATL-251` Define the fixture app baseline for mainstream and developer-heavy uninstall scenarios
+- `ATL-252` Make `Apps` preview, completion, and history render the same uninstall evidence model end to end
+- `ATL-253` Define the restore-triggered app-footprint refresh policy and stale-evidence behavior after recovery
+- `ATL-254` Script the manual acceptance flow for uninstall evidence, restore, and post-restore refresh verification
+- `ATL-256` Define the next batch of high-confidence safe roots outside app containers and freeze the no-go boundaries
+- `ATL-257` Stabilize `review-only` vs `executable` boundary metadata and UI cues across scan, review, execute, completion, and history
+- `ATL-261` Freeze the recovery payload schema, versioning rules, and compatibility contract
+- `ATL-266` Make `full-acceptance` a routine gate on the candidate build instead of a one-off release exercise

 ## Day Plan

 - `Day 1`
-  - finalize competitor-pressure matrix
-  - freeze non-goals and no-go boundaries for selective parity work
+  - freeze the `EPIC-A -> EPIC-D` execution order
+  - finalize the fixture app baseline and non-go boundaries for the first `Apps` slice
 - `Day 2`
-  - define fixture app set and Smart Clean target-class benchmark set
-  - confirm acceptance and validation expectations
+  - define the cross-surface uninstall evidence model for preview, completion, and history
+  - confirm restore-refresh expectations and acceptance criteria for `Apps`
 - `Day 3`
-  - write the detailed implementation plan for the first coding slice
+  - write the detailed implementation plan for the first `Apps` 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
+  - define the next `Smart Clean` safe roots and the `review-only` vs `executable` boundary rules
+  - align roadmap, risks, and acceptance docs with the ordered epic sequence
 - `Day 5`
  - hold an internal doc gate for development readiness
-  - confirm the next coding session can begin without planning gaps
+  - confirm the next coding session can begin with `EPIC-A` and without another sequencing pass

 ## Owner Tasks

@@ -119,10 +138,11 @@ Do not expand into:

 - 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
+- next coding session can start on `EPIC-A` 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
+- release readiness still cannot close the public-distribution gap until Apple signing materials exist
--- a/Docs/RISKS.md
+++ b/Docs/RISKS.md
@@ -144,3 +144,11 @@
 - Owner: `Docs Agent`
 - Risk: Competitive pressure may tempt reuse of code or assets from `Tencent Lemon Cleaner`, `GrandPerspective`, or GPL-constrained `Czkawka` components, creating license conflict with Atlas's shipping posture. `Pearcleaner` also remains unsuitable for monetized derivative reuse due `Commons Clause`.
 - Mitigation: Treat these projects as product and technical references only, require explicit license review before adapting any third-party implementation, and prefer MIT-compatible upstream or original Atlas implementations for shipped code.
+
+## R-019 Release-First Sequencing Drift
+
+- Impact: High
+- Probability: Medium
+- Owner: `Product Agent`
+- Risk: The team may over-rotate toward release mechanics because the packaging chain mostly works, even though the real public-release blocker is still missing signing materials and the sharper product pressure is in `Apps` and `Smart Clean`.
+- Mitigation: Keep the active mainline order at `Apps -> Smart Clean -> Recovery -> Release`, and treat the `Developer ID + notarization` switch as the final convergence step once product-path evidence and credentials both exist.
--- a/Docs/ROADMAP.md
+++ b/Docs/ROADMAP.md
@@ -6,10 +6,10 @@
 - Product state: `Frozen MVP complete`
 - Validation state: `Internal beta passed with conditions on 2026-03-07`
 - Immediate priorities:
-  - remove silent XPC fallback from release-facing trust assumptions
-  - make `Smart Clean` execution honesty match real filesystem behavior
-  - make `Recovery` claims match shipped restore behavior
-  - convert competitor research into a selective parity plan against `Mole`, `Lemon`, and `Pearcleaner` without reopening MVP scope
+  - turn `Apps` review-only evidence into verifiable and comparable uninstall evidence
+  - expand `Smart Clean` safe coverage only on the next high-confidence roots
+  - harden `Recovery` payload compatibility and restore evidence after execution boundaries stabilize
+  - keep release-readiness work behind the product-path epics until signing materials exist
 - Release-path blocker:
  - no Apple signing and notarization credentials are available on the current machine

@@ -36,8 +36,10 @@
 - Atlas should compete as an `explainable, recovery-first Mac maintenance workspace`, not as a generic all-in-one cleaner.
 - The roadmap response is:
  - preserve trust as the primary release gate
-  - close the most visible `Smart Clean` coverage gaps users compare against `Mole` and `Lemon`
-  - deepen the `Apps` module where `Pearcleaner` and `Lemon` set expectations
+  - deepen the `Apps` module first where `Pearcleaner` and `Lemon` set expectations
+  - then close the most visible `Smart Clean` safe-coverage gaps users compare against `Mole` and `Lemon`
+  - harden `Recovery` only after execution boundaries and evidence models are stable
+  - treat release readiness as the final convergence step because signing materials, not packaging mechanics, remain the public-release blocker
  - keep `Storage treemap`, `Menu Bar`, and `Automation` out of scope

 ## Active Milestones
@@ -57,80 +59,95 @@
  - unsupported execution paths fail clearly instead of appearing successful
  - recovery wording matches the shipped restore behavior

-### Milestone 2: Smart Clean Execution Credibility
+### Milestone 2: Apps Evidence Execution

- Dates: `2026-03-31` to `2026-04-18`
- Goal: prove that the highest-value safe cleanup paths have real disk-backed side effects.
+- Dates: `2026-03-31` to `2026-04-11`
+- Goal: turn `Apps` review-only evidence from merely visible into verifiable, comparable, and recoverably consistent.
 - Focus:
-  - expand real `Smart Clean` execute coverage for top safe target classes most likely compared to `Mole` and `Lemon`
-  - carry executable structured targets through the worker path
-  - add stronger `scan -> execute -> rescan` contract coverage
-  - make history and completion states reflect real side effects only
+  - define the fixture app baseline for mainstream and developer-heavy uninstall scenarios
+  - make preview, completion, and history reflect the same uninstall evidence model
+  - define the restore-triggered app-footprint refresh strategy and stale-evidence handling
+  - script the manual acceptance flow for uninstall evidence and restore verification
 - Exit criteria:
-  - top safe cleanup paths show real post-execution scan improvement
-  - history does not claim success without real side effects
-  - release-facing docs clearly distinguish supported vs unsupported cleanup paths
+  - supported fixture apps produce consistent evidence across preview, completion, and history
+  - restore follows a defined footprint refresh path or shows explicit stale-evidence state
+  - the `Apps` acceptance path is scriptable and repeatable

-### Milestone 3: Recovery Credibility
+### Milestone 3: Smart Clean Safe Coverage Expansion

- Dates: `2026-04-21` to `2026-05-09`
- Goal: close the gap between Atlas's recovery promise and its shipped restore behavior.
+- Dates: `2026-04-14` to `2026-05-02`
+- Goal: expand only the next batch of high-confidence safe cleanup roots and prove real side effects without widening into high-risk cleanup.
 - Focus:
-  - implement physical restore for file-backed recoverable actions where safe
-  - or narrow product and release messaging if physical restore cannot land safely
-  - validate restore behavior on real file-backed test cases
-  - freeze recovery-related copy only after behavior is confirmed
+  - add the next safe roots outside app containers
+  - stabilize the `review-only` vs `executable` boundary across scan, review, execute, completion, and history
+  - strengthen the `scan -> execute -> rescan` evidence chain for the expanded safe roots
+  - keep unsupported or high-risk paths explicitly non-executable
 - Exit criteria:
-  - recovery language matches shipped behavior
-  - file-backed recoverable actions either restore physically or are no longer described as if they do
-  - QA has explicit evidence for restore behavior on the candidate build
+  - newly supported safe roots show real post-execution rescan improvement
+  - unsupported roots remain clearly marked as `review-only`
+  - release-facing surfaces distinguish supported and unsupported execution scope without ambiguity

-### Milestone 4: Apps Competitive Depth
+### Milestone 4: Recovery Payload Hardening

- Dates: `2026-05-12` to `2026-05-30`
- Goal: close the highest-value `Apps` depth gaps versus `Pearcleaner` and `Lemon` without reopening MVP scope.
+- Dates: `2026-05-05` to `2026-05-23`
+- Goal: make recovery state structurally stable, backward-compatible, and historically trustworthy.
 - Focus:
-  - deepen uninstall preview taxonomy and leftover visibility
-  - improve clarity around launch items, service artifacts, and other app-adjacent footprint categories where Atlas can safely reason about them
-  - surface recoverability and audit cues directly in the uninstall flow
-  - validate uninstall flows against mainstream and developer-heavy fixture apps
+  - stabilize the recovery payload schema and versioning contract
+  - add migration and compatibility handling for older workspace and history state files
+  - deepen `History` detail evidence for restore payloads, conflicts, expiry, and partial restore outcomes
+  - add regression coverage for conflict, expired payload, and partial-restore scenarios
 - Exit criteria:
-  - `Apps` uninstall preview clearly explains footprint scope, leftovers, and recovery implications for supported flows
-  - supported uninstall fixtures show better uninstall depth and clearer completion evidence than the current baseline
-  - release-facing product copy can describe the `Apps` module as a trust-differentiated uninstall workflow, not just an app list with delete actions
+  - recovery payloads follow a stable versioned schema
+  - older state files migrate cleanly or fail with explicit compatibility behavior
+  - `History` detail can explain real restore evidence and degraded outcomes
+  - regression coverage exists for the main restore edge cases
+
+### Milestone 5: Release Readiness
+
+- Dates: `2026-05-26` to `2026-06-13`
+- Goal: turn the stabilized product path into a repeatable release candidate process, then switch to the signing chain when credentials exist.
+- Focus:
+  - make `full-acceptance` a routine gate on candidate builds
+  - stabilize UI automation for trust-critical MVP flows
+  - freeze packaging, install, and launch smoke checks as repeatable release scripts
+  - switch from the pre-signing release chain to `Developer ID + notarization` once credentials become available
+- Exit criteria:
+  - `full-acceptance` runs routinely on candidate builds
+  - trust-critical UI automation is stable enough for release gating
+  - packaging, install, and launch smoke checks are repeatable
+  - the signed chain either passes with credentials present or remains explicitly blocked only by missing credentials

 ## Conditional Release Branch

-These milestones do not start until Apple release credentials are available.
+These milestones do not start until Milestone `5` is complete and Apple release credentials are available.

-### Conditional Milestone A: Signed Public Beta Candidate
+### Conditional Milestone A: Signed External Beta Candidate

 - Trigger:
-  - Milestones `1` through `4` are complete
+  - Milestones `1` through `5` are complete
  - `Developer ID Application` is available
  - `Developer ID Installer` is available
  - `ATLAS_NOTARY_PROFILE` is available
 - Goal: produce a signed and notarized external beta candidate.
 - Focus:
-  - pass `./scripts/atlas/signing-preflight.sh`
-  - rerun signed packaging
+  - rerun the release scripts on the signed chain
  - validate signed `.app`, `.dmg`, and `.pkg` install paths on a clean machine
-  - prepare public beta notes and known limitations
+  - prepare external beta notes and known limitations
 - Exit criteria:
  - signed and notarized artifacts install without bypass instructions
  - clean-machine install verification passes on the signed candidate

-### Conditional Milestone B: Public Beta Learn Loop
+### Conditional Milestone B: External Beta Learn Loop

 - Trigger:
  - Conditional Milestone A is complete
- Goal: run a small external beta after internal hardening is already complete.
+- Goal: run a small external beta only after the mainline product path is stable.
 - Focus:
  - use a hardware-diverse trusted beta cohort
  - triage install, permission, execution, and restore regressions
  - close P0 issues before any GA candidate is named
 - Exit criteria:
-  - no public-beta P0 remains open
+  - no external-beta P0 remains open
  - primary workflows are validated on more than one machine profile

 ### Conditional Milestone C: GA Candidate and Launch