fix: harden internal beta execution trust
This commit is contained in:
zhukang
@@ -46,6 +46,11 @@
|
||||
- `EPIC-08` Permissions and System Integration
|
||||
- `EPIC-09` Quality and Verification
|
||||
- `EPIC-10` Packaging, Signing, and Release
|
||||
- `EPIC-16` Beta Stabilization and Execution Truthfulness
|
||||
- `EPIC-17` Signed Public Beta Packaging
|
||||
- `EPIC-18` Public Beta Feedback and Trust Closure
|
||||
- `EPIC-19` GA Recovery and Execution Hardening
|
||||
- `EPIC-20` GA Launch Readiness
|
||||
|
||||
## Now / Next / Later
|
||||
|
||||
@@ -195,6 +200,88 @@
|
||||
- `ATL-115` Measure perceived latency and remove avoidable visual jumps in core flows — `QA Agent`
|
||||
- `ATL-116` Polish Week 2 gate review — `Product Agent`
|
||||
|
||||
## Internal Beta Hardening Track
|
||||
|
||||
### Current Status
|
||||
|
||||
- `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.
|
||||
|
||||
### Focus
|
||||
|
||||
- Keep the roadmap inside the frozen MVP modules.
|
||||
- Hard-fix execution truthfulness before any broader distribution plan resumes.
|
||||
- Make recovery claims match shipped restore behavior.
|
||||
- Keep signed public beta work as a conditional branch, not the active mainline.
|
||||
|
||||
### Epics
|
||||
|
||||
- `EPIC-16` Beta Stabilization and Execution Truthfulness
|
||||
- `EPIC-17` Signed Public Beta Packaging
|
||||
- `EPIC-18` Public Beta Feedback and Trust Closure
|
||||
- `EPIC-19` GA Recovery and Execution Hardening
|
||||
- `EPIC-20` GA Launch Readiness
|
||||
|
||||
### Now / Next / Later
|
||||
|
||||
#### Now
|
||||
|
||||
- Remove or gate silent fallback in release-facing execution flows
|
||||
- Run bilingual manual QA on a clean machine
|
||||
- Validate packaged first-launch behavior with a fresh state file
|
||||
- Tighten release-facing copy where execution or recovery is overstated
|
||||
|
||||
#### Next
|
||||
|
||||
- Expand real `Smart Clean` execute coverage for the highest-value safe targets
|
||||
- Add stronger `scan -> execute -> rescan` contract coverage
|
||||
- Implement physical restore for file-backed recoverable actions, or narrow product claims
|
||||
- Freeze recovery-related copy only after behavior is proven
|
||||
|
||||
#### Later
|
||||
|
||||
- Obtain Apple signing and notarization credentials
|
||||
- Produce signed and notarized `.app`, `.dmg`, and `.pkg` artifacts
|
||||
- Validate signed install behavior on a clean machine
|
||||
- Run a small hardware-diverse public beta cohort only after signed distribution is available
|
||||
|
||||
### Seed Issues
|
||||
|
||||
#### Release Phase 1: Beta Stabilization
|
||||
|
||||
- `ATL-201` Remove or development-gate silent XPC fallback in release-facing execution flows — `System Agent`
|
||||
- `ATL-202` Add explicit failure states when real worker execution is unavailable — `Mac App Agent`
|
||||
- `ATL-203` Run bilingual manual QA on a clean machine — `QA Agent`
|
||||
- `ATL-204` Validate fresh-state first launch from packaged artifacts — `QA Agent`
|
||||
- `ATL-205` Narrow release-facing recovery and execution copy where needed — `UX Agent` + `Docs Agent`
|
||||
- `ATL-206` Beta stabilization gate review — `Product Agent`
|
||||
|
||||
#### Release Phase 2: Smart Clean Execution Credibility
|
||||
|
||||
- `ATL-211` Expand real `Smart Clean` execute coverage for top safe target classes — `System Agent`
|
||||
- `ATL-212` Carry executable structured targets through the worker path — `Core Agent`
|
||||
- `ATL-213` Add stronger `scan -> execute -> rescan` contract coverage — `QA Agent`
|
||||
- `ATL-214` Make history and completion states reflect real side effects only — `Mac App Agent`
|
||||
- `ATL-215` Execution credibility gate review — `Product Agent`
|
||||
|
||||
#### Release Phase 3: Recovery Credibility
|
||||
|
||||
- `ATL-221` Implement physical restore for file-backed recoverable actions where safe — `System Agent`
|
||||
- `ATL-222` Validate shipped restore behavior on real file-backed test cases — `QA Agent`
|
||||
- `ATL-223` Narrow README, in-app, and release-note recovery claims if needed — `Docs Agent` + `Product Agent`
|
||||
- `ATL-224` Freeze recovery contract and acceptance evidence — `Product Agent`
|
||||
- `ATL-225` Recovery credibility gate review — `Product Agent`
|
||||
|
||||
#### Conditional Release Phase 4: Signed Distribution and External Beta
|
||||
|
||||
- `ATL-231` Obtain Apple release signing credentials — `Release Agent`
|
||||
- `ATL-232` Pass `signing-preflight.sh` on the release machine — `Release Agent`
|
||||
- `ATL-233` Produce signed and notarized native artifacts — `Release Agent`
|
||||
- `ATL-234` Validate signed DMG and PKG install on a clean machine — `QA Agent`
|
||||
- `ATL-235` Run a trusted hardware-diverse signed beta cohort — `Product Agent`
|
||||
- `ATL-236` Triage public-beta issues before any GA candidate naming — `Product Agent`
|
||||
|
||||
## Definition of Ready
|
||||
|
||||
- Scope is clear and bounded
|
||||
|
||||
@@ -54,6 +54,7 @@
|
||||
|
||||
- Core frozen MVP workflows are complete end to end.
|
||||
- Recovery-first behavior is visible in both Smart Clean and Apps flows.
|
||||
- Physical on-disk restore is currently limited to recovery items that carry a supported restore path; older or unstructured records may still be model-only restore.
|
||||
- Settings and permission refresh flows are functional.
|
||||
- The app now defaults to `简体中文` and supports switching to `English` through persisted settings.
|
||||
|
||||
@@ -85,6 +86,7 @@
|
||||
## Conditions
|
||||
|
||||
- Internal beta / trusted-user beta can proceed with the current ad hoc-signed local artifacts.
|
||||
- Recovery and execution copy must stay explicit about supported restore paths and unsupported cleanup targets during internal beta.
|
||||
- Public beta or broad external distribution must wait until signing and notarization credentials are available and the release packaging path is re-run.
|
||||
|
||||
## Follow-up Actions
|
||||
|
||||
@@ -54,7 +54,7 @@
|
||||
|
||||
## Current Blockers
|
||||
|
||||
- `Smart Clean` execute now supports a real Trash-based path for structured safe targets, and those targets can be physically restored. Full disk-backed coverage is still incomplete, and unsupported targets fail closed. See `Docs/Execution/Execution-Chain-Audit-2026-03-09.md`.
|
||||
- `Smart Clean` execute now supports a real Trash-based path for structured safe targets, and those targets can be physically restored when recovery mappings are present. Full disk-backed coverage is still incomplete, and unsupported targets fail closed. See `Docs/Execution/Execution-Chain-Audit-2026-03-09.md`.
|
||||
- Silent fallback from XPC to the scaffold worker can mask execution-path failures in user-facing flows. See `Docs/Execution/Execution-Chain-Audit-2026-03-09.md`.
|
||||
- Public signed distribution is still blocked by missing Apple release credentials:
|
||||
- `Developer ID Application`
|
||||
|
||||
370
Docs/Execution/Implementation-Plan-ATL-201-202-205-2026-03-12.md
Normal file
370
Docs/Execution/Implementation-Plan-ATL-201-202-205-2026-03-12.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# ATL-201 / ATL-202 / ATL-205 Implementation Plan
|
||||
|
||||
> **For Codex:** Execute this plan task-by-task. Keep changes small, verify each layer narrowly first, and commit frequently.
|
||||
|
||||
**Goal:** Remove release-facing silent scaffold fallback, expose explicit execution-unavailable failures in the app UI, and narrow bilingual execution/recovery copy so Atlas only claims behavior it can actually prove today.
|
||||
|
||||
**Architecture:** Keep the worker fallback capability available only as an explicit development override, but make the default app path fail closed. Surface worker rejection reasons through the application layer as user-facing localized errors, then render those errors in `Smart Clean` as a danger-state callout instead of a quiet summary string. Tighten copy in the app and release-facing docs so “recoverable” and “restore” only describe the currently shipped behavior.
|
||||
|
||||
**Tech Stack:** Swift 6, SwiftUI, Swift Package Manager tests, package-scoped localization resources, Markdown docs.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Lock Release-Facing Worker Fallback Behind Explicit Development Mode
|
||||
|
||||
**Files:**
|
||||
- Modify: `Apps/AtlasApp/Sources/AtlasApp/AtlasAppModel.swift`
|
||||
- Modify: `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasXPCTransport.swift`
|
||||
- Test: `Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasXPCTransportTests.swift`
|
||||
- Test: `Apps/AtlasApp/Tests/AtlasAppTests/AtlasAppModelTests.swift`
|
||||
|
||||
**Step 1: Write the failing transport tests**
|
||||
|
||||
Add tests in `Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasXPCTransportTests.swift` that cover:
|
||||
|
||||
- release/default mode does **not** fall back when XPC rejects `executionUnavailable`
|
||||
- explicit development mode still can fall back when `allowFallback == true`
|
||||
|
||||
Use the existing rejected-result fixture style:
|
||||
|
||||
```swift
|
||||
let rejected = AtlasWorkerCommandResult(
|
||||
request: request,
|
||||
response: AtlasResponseEnvelope(
|
||||
requestID: request.id,
|
||||
response: .rejected(code: .executionUnavailable, reason: "simulated packaged worker failure")
|
||||
),
|
||||
events: [],
|
||||
snapshot: AtlasScaffoldWorkspace.snapshot(),
|
||||
previewPlan: nil
|
||||
)
|
||||
```
|
||||
|
||||
**Step 2: Run the transport tests to verify the current fallback behavior**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
swift test --package-path Packages --filter AtlasXPCTransportTests
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- one new test fails because the current app-facing setup still allows fallback when XPC rejects `executionUnavailable`
|
||||
|
||||
**Step 3: Make fallback opt-in for development only**
|
||||
|
||||
In `Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasXPCTransport.swift` and `Apps/AtlasApp/Sources/AtlasApp/AtlasAppModel.swift`:
|
||||
|
||||
- keep `AtlasPreferredWorkerService` capable of fallback for explicit dev usage
|
||||
- stop hardcoding `allowFallback: true` in `AtlasAppModel`
|
||||
- derive fallback permission from an explicit development-only env path, for example:
|
||||
|
||||
```swift
|
||||
let allowScaffoldFallback = ProcessInfo.processInfo.environment["ATLAS_ALLOW_SCAFFOLD_FALLBACK"] == "1"
|
||||
```
|
||||
|
||||
- pass that value into `AtlasPreferredWorkerService(...)`
|
||||
|
||||
The key result is:
|
||||
|
||||
- installed/release-facing app path fails closed by default
|
||||
- developers can still opt in locally with an env var
|
||||
|
||||
**Step 4: Add an app-model test for the default worker policy**
|
||||
|
||||
In `Apps/AtlasApp/Tests/AtlasAppTests/AtlasAppModelTests.swift`, add a focused test around a worker rejection path using an injected fake worker or a small helper constructor so the app model no longer assumes fallback-enabled behavior in default/release configuration.
|
||||
|
||||
Target behavior:
|
||||
|
||||
```swift
|
||||
XCTAssertFalse(model.canExecuteCurrentSmartCleanPlan)
|
||||
XCTAssertTrue(model.latestScanSummary.contains("unavailable"))
|
||||
```
|
||||
|
||||
**Step 5: Run tests and verify**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
swift test --package-path Packages --filter AtlasXPCTransportTests
|
||||
swift test --package-path Apps --filter AtlasAppModelTests
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- transport tests pass
|
||||
- app-model tests still pass with the new fail-closed default
|
||||
|
||||
**Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add Packages/AtlasInfrastructure/Sources/AtlasInfrastructure/AtlasXPCTransport.swift Apps/AtlasApp/Sources/AtlasApp/AtlasAppModel.swift Packages/AtlasInfrastructure/Tests/AtlasInfrastructureTests/AtlasXPCTransportTests.swift Apps/AtlasApp/Tests/AtlasAppTests/AtlasAppModelTests.swift
|
||||
git commit -m "fix: gate scaffold fallback behind dev mode"
|
||||
```
|
||||
|
||||
### Task 2: Surface Explicit Execution-Unavailable Failure States in Smart Clean
|
||||
|
||||
**Files:**
|
||||
- Modify: `Packages/AtlasApplication/Sources/AtlasApplication/AtlasApplication.swift`
|
||||
- Modify: `Packages/AtlasDomain/Sources/AtlasDomain/Resources/en.lproj/Localizable.strings`
|
||||
- Modify: `Packages/AtlasDomain/Sources/AtlasDomain/Resources/zh-Hans.lproj/Localizable.strings`
|
||||
- Modify: `Apps/AtlasApp/Sources/AtlasApp/AtlasAppModel.swift`
|
||||
- Modify: `Apps/AtlasApp/Sources/AtlasApp/AppShellView.swift`
|
||||
- Modify: `Packages/AtlasFeaturesSmartClean/Sources/AtlasFeaturesSmartClean/SmartCleanFeatureView.swift`
|
||||
- Test: `Packages/AtlasApplication/Tests/AtlasApplicationTests/AtlasApplicationTests.swift`
|
||||
- Test: `Apps/AtlasApp/Tests/AtlasAppTests/AtlasAppModelTests.swift`
|
||||
|
||||
**Step 1: Write the failing application-layer tests**
|
||||
|
||||
Add tests in `Packages/AtlasApplication/Tests/AtlasApplicationTests/AtlasApplicationTests.swift` for:
|
||||
|
||||
- `executionUnavailable` rejection maps to a user-facing localized error
|
||||
- `helperUnavailable` rejection maps to a user-facing localized error
|
||||
|
||||
Use the existing `FakeWorker` and a rejected response:
|
||||
|
||||
```swift
|
||||
let result = AtlasWorkerCommandResult(
|
||||
request: request,
|
||||
response: AtlasResponseEnvelope(
|
||||
requestID: request.id,
|
||||
response: .rejected(code: .executionUnavailable, reason: "XPC worker offline")
|
||||
),
|
||||
events: [],
|
||||
snapshot: AtlasScaffoldWorkspace.snapshot(),
|
||||
previewPlan: nil
|
||||
)
|
||||
```
|
||||
|
||||
Assert on `error.localizedDescription`.
|
||||
|
||||
**Step 2: Run the application tests to verify they fail**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
swift test --package-path Packages --filter AtlasApplicationTests
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- new rejection-mapping tests fail because `AtlasWorkspaceControllerError` still uses the generic `application.error.workerRejected`
|
||||
|
||||
**Step 3: Add code-specific user-facing error strings**
|
||||
|
||||
In `Packages/AtlasApplication/Sources/AtlasApplication/AtlasApplication.swift`, replace the one-size-fits-all rejection mapping with explicit cases:
|
||||
|
||||
```swift
|
||||
case let .rejected(code, reason):
|
||||
switch code {
|
||||
case .executionUnavailable:
|
||||
return AtlasL10n.string("application.error.executionUnavailable", reason)
|
||||
case .helperUnavailable:
|
||||
return AtlasL10n.string("application.error.helperUnavailable", reason)
|
||||
default:
|
||||
return AtlasL10n.string("application.error.workerRejected", code.rawValue, reason)
|
||||
}
|
||||
```
|
||||
|
||||
Add matching bilingual keys in both `.strings` files.
|
||||
|
||||
**Step 4: Write the failing app-model/UI-state tests**
|
||||
|
||||
In `Apps/AtlasApp/Tests/AtlasAppTests/AtlasAppModelTests.swift`, add tests that verify:
|
||||
|
||||
- executing a plan with `executionUnavailable` leaves the plan non-busy
|
||||
- the model stores an explicit Smart Clean execution issue
|
||||
- the summary and/or issue text is specific, not a silent generic fallback success
|
||||
|
||||
Introduce a small fake worker actor in the test file if needed:
|
||||
|
||||
```swift
|
||||
private actor RejectingWorker: AtlasWorkerServing {
|
||||
func submit(_ request: AtlasRequestEnvelope) async throws -> AtlasWorkerCommandResult { ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Step 5: Implement explicit Smart Clean failure state**
|
||||
|
||||
In `Apps/AtlasApp/Sources/AtlasApp/AtlasAppModel.swift`:
|
||||
|
||||
- add a dedicated published property such as:
|
||||
|
||||
```swift
|
||||
@Published private(set) var smartCleanExecutionIssue: String?
|
||||
```
|
||||
|
||||
- clear it before a new scan / preview / execute attempt
|
||||
- set it when `executeCurrentPlan()` catches `executionUnavailable` or `helperUnavailable`
|
||||
|
||||
In `Apps/AtlasApp/Sources/AtlasApp/AppShellView.swift`, pass the new issue through to `SmartCleanFeatureView`.
|
||||
|
||||
In `Packages/AtlasFeaturesSmartClean/Sources/AtlasFeaturesSmartClean/SmartCleanFeatureView.swift`:
|
||||
|
||||
- add an optional `executionIssue: String?`
|
||||
- render a danger-tone callout or status state when this value exists
|
||||
- prefer this explicit issue over a normal “ready” or cached-plan state
|
||||
|
||||
The UI target is:
|
||||
|
||||
- a failed real execution attempt is visually obvious
|
||||
- the user sees “unavailable” or “helper unavailable”, not just a stale summary string
|
||||
|
||||
**Step 6: Run tests and verify**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
swift test --package-path Packages --filter AtlasApplicationTests
|
||||
swift test --package-path Apps --filter AtlasAppModelTests
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- rejection mapping tests pass
|
||||
- app-model tests show explicit failure-state behavior
|
||||
|
||||
**Step 7: Commit**
|
||||
|
||||
```bash
|
||||
git add Packages/AtlasApplication/Sources/AtlasApplication/AtlasApplication.swift Packages/AtlasDomain/Sources/AtlasDomain/Resources/en.lproj/Localizable.strings Packages/AtlasDomain/Sources/AtlasDomain/Resources/zh-Hans.lproj/Localizable.strings Apps/AtlasApp/Sources/AtlasApp/AtlasAppModel.swift Apps/AtlasApp/Sources/AtlasApp/AppShellView.swift Packages/AtlasFeaturesSmartClean/Sources/AtlasFeaturesSmartClean/SmartCleanFeatureView.swift Packages/AtlasApplication/Tests/AtlasApplicationTests/AtlasApplicationTests.swift Apps/AtlasApp/Tests/AtlasAppTests/AtlasAppModelTests.swift
|
||||
git commit -m "fix: expose explicit smart clean execution failures"
|
||||
```
|
||||
|
||||
### Task 3: Narrow Bilingual Execution and Recovery Copy to Shipped Behavior
|
||||
|
||||
**Files:**
|
||||
- Modify: `Packages/AtlasDomain/Sources/AtlasDomain/Resources/en.lproj/Localizable.strings`
|
||||
- Modify: `Packages/AtlasDomain/Sources/AtlasDomain/Resources/zh-Hans.lproj/Localizable.strings`
|
||||
- Modify: `README.md`
|
||||
- Modify: `README.zh-CN.md`
|
||||
- Modify: `Docs/HELP_CENTER_OUTLINE.md`
|
||||
- Modify: `Docs/Execution/Current-Status-2026-03-07.md`
|
||||
- Modify: `Docs/Execution/Beta-Gate-Review.md`
|
||||
- Modify: `Docs/Execution/Smart-Clean-Execution-Coverage-2026-03-09.md`
|
||||
|
||||
**Step 1: Write the copy audit checklist directly into the diff**
|
||||
|
||||
Before editing text, create a short checklist in your working notes and verify every claim against current behavior:
|
||||
|
||||
- does this line claim physical restore for all recoverable items?
|
||||
- does this line imply History/Recovery always means on-disk restore?
|
||||
- does this line distinguish “supported restore path” from “model-only restore”?
|
||||
- does this line imply direct execution for unsupported Smart Clean items?
|
||||
|
||||
**Step 2: Tighten in-app copy first**
|
||||
|
||||
Update the localized strings most likely to overclaim current behavior:
|
||||
|
||||
- `smartclean.execution.coverage.full.detail`
|
||||
- `smartclean.preview.callout.safe.detail`
|
||||
- `application.recovery.completed`
|
||||
- `infrastructure.restore.summary.one`
|
||||
- `infrastructure.restore.summary.other`
|
||||
- `history.callout.recovery.detail`
|
||||
- `history.detail.recovery.callout.available.detail`
|
||||
- `history.restore.hint`
|
||||
|
||||
The wording rule is:
|
||||
|
||||
- say “when supported” or “when a restore path is available” where true
|
||||
- avoid implying every recoverable item restores physically
|
||||
- avoid implying every Smart Clean item is directly executable
|
||||
|
||||
**Step 3: Tighten release-facing docs**
|
||||
|
||||
Update:
|
||||
|
||||
- `README.md`
|
||||
- `README.zh-CN.md`
|
||||
- `Docs/HELP_CENTER_OUTLINE.md`
|
||||
- `Docs/Execution/Current-Status-2026-03-07.md`
|
||||
- `Docs/Execution/Beta-Gate-Review.md`
|
||||
- `Docs/Execution/Smart-Clean-Execution-Coverage-2026-03-09.md`
|
||||
|
||||
Specific goals:
|
||||
|
||||
- README should keep “recovery-first” as a principle without implying universal physical restore
|
||||
- `Current-Status` and `Beta-Gate-Review` must match the current subset reality
|
||||
- help content should explicitly include the case where restore cannot return a file physically
|
||||
|
||||
**Step 4: Run the narrowest verification**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
swift test --package-path Packages --filter AtlasApplicationTests
|
||||
swift test --package-path Apps --filter AtlasAppModelTests
|
||||
```
|
||||
|
||||
Then manually verify:
|
||||
|
||||
- Smart Clean empty/ready/error copy still reads correctly in both Chinese and English
|
||||
- History / Recovery copy still makes sense after narrowing restore claims
|
||||
|
||||
Expected:
|
||||
|
||||
- tests stay green
|
||||
- docs and UI no longer overclaim physical restore or execution breadth
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add Packages/AtlasDomain/Sources/AtlasDomain/Resources/en.lproj/Localizable.strings Packages/AtlasDomain/Sources/AtlasDomain/Resources/zh-Hans.lproj/Localizable.strings README.md README.zh-CN.md Docs/HELP_CENTER_OUTLINE.md Docs/Execution/Current-Status-2026-03-07.md Docs/Execution/Beta-Gate-Review.md Docs/Execution/Smart-Clean-Execution-Coverage-2026-03-09.md
|
||||
git commit -m "docs: narrow execution and recovery claims"
|
||||
```
|
||||
|
||||
### Task 4: Final Verification and Handoff
|
||||
|
||||
**Files:**
|
||||
- Review only: `Docs/Execution/Beta-Acceptance-Checklist.md`
|
||||
- Review only: `Docs/Execution/Execution-Chain-Audit-2026-03-09.md`
|
||||
- Review only: `Docs/ROADMAP.md`
|
||||
- Review only: `Docs/Backlog.md`
|
||||
|
||||
**Step 1: Run focused regression commands**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
swift test --package-path Packages --filter AtlasXPCTransportTests
|
||||
swift test --package-path Packages --filter AtlasApplicationTests
|
||||
swift test --package-path Apps --filter AtlasAppModelTests
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- all targeted tests pass
|
||||
|
||||
**Step 2: Run broader package and app tests if the focused tests are green**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
swift test --package-path Packages
|
||||
swift test --package-path Apps
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- no regressions in package or app test suites
|
||||
|
||||
**Step 3: Manual product verification**
|
||||
|
||||
Verify on the latest local packaged or debug build:
|
||||
|
||||
1. Force an execution-unavailable path and confirm Smart Clean shows a visible danger-state failure.
|
||||
2. Confirm no silent fallback success path is visible in normal app mode.
|
||||
3. Confirm Smart Clean still executes supported safe targets.
|
||||
4. Confirm Recovery/History wording no longer implies guaranteed physical restore for every item.
|
||||
|
||||
**Step 4: Handoff notes**
|
||||
|
||||
Record:
|
||||
|
||||
- what was changed
|
||||
- which files changed
|
||||
- which tests passed
|
||||
- whether physical restore remains partial after copy hardening
|
||||
- whether signed-release work is still blocked by missing credentials
|
||||
153
Docs/Execution/Release-Roadmap-2026-03-12.md
Normal file
153
Docs/Execution/Release-Roadmap-2026-03-12.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Internal Beta Hardening and Conditional Release Roadmap — 2026-03-12
|
||||
|
||||
## Product Conclusion
|
||||
|
||||
Atlas for Mac should not optimize around public beta dates right now. The correct near-term program is `internal beta hardening`: execution truthfulness first, recovery credibility second, signed public distribution later when Apple release credentials exist.
|
||||
|
||||
This plan assumes:
|
||||
|
||||
- the frozen MVP module list does not change
|
||||
- direct distribution remains the eventual release route
|
||||
- no public beta or GA milestone is active until signing credentials are available
|
||||
|
||||
## Starting Evidence
|
||||
|
||||
- `Docs/Execution/Current-Status-2026-03-07.md` marks Atlas as internal-beta ready.
|
||||
- `Docs/Execution/Beta-Gate-Review.md` passes the beta candidate gate with conditions.
|
||||
- `Docs/Execution/Execution-Chain-Audit-2026-03-09.md` identifies the two biggest trust gaps:
|
||||
- silent fallback from XPC to scaffold worker
|
||||
- partial real execution and non-physical restore behavior
|
||||
- `Docs/Execution/Release-Signing.md` shows public distribution is blocked by missing Apple release credentials on the current machine.
|
||||
|
||||
## Active Phase Plan
|
||||
|
||||
### Phase 1: Internal Beta Hardening
|
||||
|
||||
- Dates: `2026-03-16` to `2026-03-28`
|
||||
- Outcome: a truthful internal-beta build that no longer overclaims execution or recovery capability
|
||||
|
||||
#### Workstreams
|
||||
|
||||
- `System Agent`
|
||||
- remove or development-gate silent XPC fallback in release-facing flows
|
||||
- surface explicit user-facing errors when real worker execution is unavailable
|
||||
- `QA Agent`
|
||||
- rerun clean-machine validation for first launch, language switching, and install flow
|
||||
- rerun `Smart Clean` and `Apps` end-to-end manual flows against packaged artifacts
|
||||
- `UX Agent` + `Docs Agent`
|
||||
- tighten copy where `Recovery` or `Smart Clean` implies broader on-disk behavior than shipped
|
||||
|
||||
#### Exit Gate
|
||||
|
||||
- latest packaged build passes internal beta checklist again
|
||||
- unsupported execution paths are visible and honest
|
||||
- recovery language matches the current shipped restore model
|
||||
|
||||
### Phase 2: Smart Clean Execution Credibility
|
||||
|
||||
- Dates: `2026-03-31` to `2026-04-18`
|
||||
- Outcome: highest-value safe cleanup paths have proven real side effects
|
||||
|
||||
#### Workstreams
|
||||
|
||||
- `System Agent` + `Core Agent`
|
||||
- expand real `Smart Clean` execute coverage for top safe target classes
|
||||
- carry executable structured targets through the worker path
|
||||
- route privileged cleanup through the helper boundary where necessary
|
||||
- `QA Agent`
|
||||
- add stronger `scan -> execute -> rescan` contract coverage
|
||||
- verify history and completion states only claim real success
|
||||
- `Mac App Agent`
|
||||
- align completion and failure states with true execution outcomes
|
||||
|
||||
#### Exit Gate
|
||||
|
||||
- supported cleanup paths show real post-execution scan improvement
|
||||
- unsupported paths fail clearly
|
||||
- history only claims completion when the filesystem side effect happened
|
||||
|
||||
### Phase 3: Recovery Credibility
|
||||
|
||||
- Dates: `2026-04-21` to `2026-05-09`
|
||||
- Outcome: Atlas's recovery promise is either physically true for file-backed actions or explicitly narrowed before release planning resumes
|
||||
|
||||
#### Workstreams
|
||||
|
||||
- `System Agent`
|
||||
- implement physical restore for file-backed recoverable actions where safe
|
||||
- or freeze a narrower recovery contract if physical restore cannot be landed safely
|
||||
- `QA Agent`
|
||||
- validate restore behavior on real file-backed test cases
|
||||
- `Docs Agent` + `Product Agent`
|
||||
- freeze README, release-note, and in-app recovery wording only after behavior is confirmed
|
||||
|
||||
#### Exit Gate
|
||||
|
||||
- file-backed recoverable actions either restore physically or are no longer described as if they do
|
||||
- QA evidence exists for shipped restore behavior
|
||||
- recovery claims are consistent across docs and product copy
|
||||
|
||||
## Conditional Release Plan
|
||||
|
||||
This branch is dormant until Apple release credentials exist.
|
||||
|
||||
### Conditional Phase A: Signed Public Beta Candidate
|
||||
|
||||
- Trigger:
|
||||
- `Developer ID Application`
|
||||
- `Developer ID Installer`
|
||||
- `ATLAS_NOTARY_PROFILE`
|
||||
- Workstreams:
|
||||
- run `./scripts/atlas/signing-preflight.sh`
|
||||
- rerun signed packaging
|
||||
- validate signed install behavior on a clean machine
|
||||
- prepare public beta notes and known limitations
|
||||
- Exit Gate:
|
||||
- signed and notarized artifacts exist
|
||||
- clean-machine install verification passes
|
||||
|
||||
### Conditional Phase B: Public Beta Learn Loop
|
||||
|
||||
- Trigger:
|
||||
- Conditional Phase A complete
|
||||
- Workstreams:
|
||||
- run a small hardware-diverse trusted beta cohort
|
||||
- triage install, permission, execution, and restore regressions
|
||||
- close P0 issues before any GA candidate is named
|
||||
- Exit Gate:
|
||||
- no public-beta P0 remains open
|
||||
- primary workflows are validated across more than one machine profile
|
||||
|
||||
### Conditional Phase C: GA Candidate and Launch
|
||||
|
||||
- Trigger:
|
||||
- Conditional Phase B complete
|
||||
- Workstreams:
|
||||
- rerun full acceptance and signed packaging on the GA candidate
|
||||
- freeze release notes, notices, acknowledgements, and checksums
|
||||
- validate launch-candidate install and first-run flow on a clean machine
|
||||
- Exit Gate:
|
||||
- no open P0 release blocker
|
||||
- signed packaging, install validation, and release docs are complete
|
||||
- `v1.0` is published
|
||||
|
||||
## Workstream Priorities
|
||||
|
||||
### Priority 1: Execution Truthfulness
|
||||
|
||||
Atlas cannot afford a release where `Smart Clean` appears to succeed while only Atlas state changes. Silent fallback removal, explicit execution failures, and `scan -> execute -> rescan` proof are the current highest-value work.
|
||||
|
||||
### Priority 2: Recovery Credibility
|
||||
|
||||
`Recovery` is part of Atlas's core trust story. Before broad release planning resumes, Atlas must either ship physical restore for file-backed recoverable actions or narrow its promise to the behavior that actually exists.
|
||||
|
||||
### Priority 3: Signed Distribution When Unblocked
|
||||
|
||||
Signing and notarization matter, but they are not the active critical path until credentials exist. When the credentials arrive, Gatekeeper-safe installation becomes a release gate, not a background task.
|
||||
|
||||
## Decision Rules
|
||||
|
||||
- Do not add P1 modules during this roadmap window.
|
||||
- Do not call the current branch `public beta`.
|
||||
- Do not claim broader cleanup coverage than the worker/helper path can prove.
|
||||
- Do not claim physical recovery until file-backed restore is validated.
|
||||
@@ -124,6 +124,7 @@ Use these statements consistently in user-facing communication:
|
||||
- `Smart Clean runs real cleanup only for supported items in the current plan.`
|
||||
- `Unsupported items stay review-only until Atlas can execute them safely.`
|
||||
- `Recoverable items can be restored when a recovery path is available.`
|
||||
- `Some recoverable items restore on disk, while older or unstructured records restore Atlas state only.`
|
||||
- `If Atlas cannot prove the cleanup step, it should fail instead of claiming success.`
|
||||
|
||||
Avoid saying:
|
||||
|
||||
@@ -26,6 +26,7 @@
|
||||
|
||||
- Where to find past runs
|
||||
- When recovery restores a file physically
|
||||
- When recovery only restores Atlas workspace state
|
||||
- Which actions are recoverable
|
||||
- What happens when recovery expires
|
||||
|
||||
|
||||
@@ -17,15 +17,17 @@ This directory contains the working product, design, engineering, and compliance
|
||||
- `Protocol.md` — local JSON protocol and core schemas
|
||||
- `TaskStateMachine.md` — task lifecycle rules
|
||||
- `ErrorCodes.md` — user-facing and system error registry
|
||||
- `ROADMAP.md` — 12-week MVP execution plan
|
||||
- `ROADMAP.md` — active internal-beta hardening roadmap and conditional release branch
|
||||
- `Backlog.md` — epics, issue seeds, and board conventions
|
||||
- `DECISIONS.md` — frozen product and architecture decisions
|
||||
- `RISKS.md` — active project risk register
|
||||
- `Execution/` — weekly execution plans, status snapshots, beta checklists, gate reviews, manual test SOPs, and release execution notes
|
||||
- `Execution/Current-Status-2026-03-07.md` — current engineering status snapshot
|
||||
- `Execution/Release-Roadmap-2026-03-12.md` — internal-beta hardening plan plus conditional signed release path
|
||||
- `Execution/UI-Audit-2026-03-08.md` — UI design audit and prioritized remediation directions
|
||||
- `Execution/UI-Copy-Walkthrough-2026-03-09.md` — page-by-page UI copy glossary, consistency checklist, and acceptance guide
|
||||
- `Execution/Execution-Chain-Audit-2026-03-09.md` — end-to-end review of real vs scaffold execution paths and release-facing trust gaps
|
||||
- `Execution/Implementation-Plan-ATL-201-202-205-2026-03-12.md` — implementation plan for internal-beta hardening tasks ATL-201, ATL-202, and ATL-205
|
||||
- `Execution/Smart-Clean-Execution-Coverage-2026-03-09.md` — user-facing summary of what Smart Clean can execute for real today
|
||||
- `Execution/Smart-Clean-QA-Checklist-2026-03-09.md` — QA checklist for scan, execute, rescan, and physical restore validation
|
||||
- `Execution/Smart-Clean-Manual-Verification-2026-03-09.md` — local-machine fixture workflow for validating real Smart Clean execution and restore
|
||||
|
||||
@@ -46,7 +46,7 @@
|
||||
- Probability: Medium
|
||||
- Owner: `Release Agent`
|
||||
- Risk: Helper signing or notarization may fail late in the schedule.
|
||||
- Mitigation: Validate packaging flow before feature-complete milestone. Current repo now includes native build/package scripts and CI workflow, but signing and notarization still depend on release credentials.
|
||||
- Mitigation: Keep signed distribution off the active critical path until Apple release credentials exist. Once credentials are available, validate packaging flow before any public beta naming or broad external distribution.
|
||||
|
||||
## R-007 Experience Polish Drift
|
||||
|
||||
@@ -96,3 +96,19 @@
|
||||
- Owner: `System Agent`
|
||||
- Risk: Silent fallback from XPC to the scaffold worker can make user-facing execution appear successful even when the primary worker path is unavailable.
|
||||
- Mitigation: Restrict fallback to explicit development mode or surface a concrete error when real execution infrastructure is unavailable.
|
||||
|
||||
## R-013 Public Beta Coverage Blind Spot
|
||||
|
||||
- Impact: High
|
||||
- Probability: Medium
|
||||
- Owner: `QA Agent`
|
||||
- Risk: When signing credentials eventually arrive, a public beta that is too small, too homogeneous, or too unstructured may miss install, permission, or cleanup regressions that only appear on different hardware, macOS states, or trust settings.
|
||||
- Mitigation: Keep this as a conditional release risk. Use a deliberately hardware-diverse trusted beta cohort, require structured issue intake, and rerun clean-machine install and first-run validation before calling any signed build GA-ready.
|
||||
|
||||
## R-014 GA Recovery Claim Drift
|
||||
|
||||
- Impact: High
|
||||
- Probability: Medium
|
||||
- Owner: `Product Agent`
|
||||
- Risk: GA release notes, README copy, or in-app messaging may overstate Atlas's recovery model before physical restore is actually shipped for file-backed recoverable actions.
|
||||
- Mitigation: Treat recovery wording as a gated release artifact. Either ship physical restore for file-backed recoverable actions before GA or narrow all GA-facing recovery claims to the shipped behavior.
|
||||
|
||||
147
Docs/ROADMAP.md
147
Docs/ROADMAP.md
@@ -1,59 +1,134 @@
|
||||
# MVP Roadmap
|
||||
# Roadmap
|
||||
|
||||
## Timeline
|
||||
## Current Starting Point
|
||||
|
||||
### Week 1
|
||||
- Date: `2026-03-12`
|
||||
- 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
|
||||
- Release-path blocker:
|
||||
- no Apple signing and notarization credentials are available on the current machine
|
||||
|
||||
- Freeze MVP scope
|
||||
- Freeze naming, compliance, and acknowledgement strategy
|
||||
- Freeze product goals and success metrics
|
||||
## Roadmap Guardrails
|
||||
|
||||
### Week 2
|
||||
- Keep scope inside the frozen MVP modules:
|
||||
- `Overview`
|
||||
- `Smart Clean`
|
||||
- `Apps`
|
||||
- `History`
|
||||
- `Recovery`
|
||||
- `Permissions`
|
||||
- `Settings`
|
||||
- Do not pull `Storage treemap`, `Menu Bar`, or `Automation` into this roadmap.
|
||||
- Treat trust and recovery honesty as release-critical product work, not polish.
|
||||
- Keep direct distribution as the only eventual release route.
|
||||
- Do not plan around public beta dates until signing credentials exist.
|
||||
|
||||
- Freeze IA and high-fidelity design input for key screens
|
||||
- Freeze interaction states and permission explainers
|
||||
## Active Milestones
|
||||
|
||||
### Week 3
|
||||
### Milestone 1: Internal Beta Hardening
|
||||
|
||||
- Freeze architecture, protocol, state machine, and helper boundaries
|
||||
- Dates: `2026-03-16` to `2026-03-28`
|
||||
- Goal: harden the current internal-beta build until user-visible execution and recovery claims are defensible.
|
||||
- Focus:
|
||||
- remove or explicitly development-gate silent XPC fallback
|
||||
- show explicit failure states when real worker execution is unavailable
|
||||
- rerun bilingual manual QA on a clean machine
|
||||
- verify packaged first-launch behavior with a fresh state file
|
||||
- tighten README, in-app copy, and help content where recovery or execution is overstated
|
||||
- Exit criteria:
|
||||
- internal beta checklist rerun against the latest packaged build
|
||||
- unsupported execution paths fail clearly instead of appearing successful
|
||||
- recovery wording matches the shipped restore behavior
|
||||
|
||||
### Week 4
|
||||
### Milestone 2: Smart Clean Execution Credibility
|
||||
|
||||
- Create engineering scaffold and mock-data application shell
|
||||
- Dates: `2026-03-31` to `2026-04-18`
|
||||
- Goal: prove that the highest-value safe cleanup paths have real disk-backed side effects.
|
||||
- Focus:
|
||||
- expand real `Smart Clean` execute coverage for top safe target classes
|
||||
- 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
|
||||
- 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
|
||||
|
||||
### Week 5
|
||||
### Milestone 3: Recovery Credibility
|
||||
|
||||
- Ship scan initiation and result pipeline
|
||||
- Dates: `2026-04-21` to `2026-05-09`
|
||||
- Goal: close the gap between Atlas's recovery promise and its shipped restore behavior.
|
||||
- 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
|
||||
- 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
|
||||
|
||||
### Week 6
|
||||
## Conditional Release Branch
|
||||
|
||||
- Ship action-plan preview and cleanup execution path
|
||||
These milestones do not start until Apple release credentials are available.
|
||||
|
||||
### Week 7
|
||||
### Conditional Milestone A: Signed Public Beta Candidate
|
||||
|
||||
- Ship apps list and uninstall preview flow
|
||||
- Trigger:
|
||||
- `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
|
||||
- validate signed `.app`, `.dmg`, and `.pkg` install paths on a clean machine
|
||||
- prepare public beta notes and known limitations
|
||||
- Exit criteria:
|
||||
- signed and notarized artifacts install without bypass instructions
|
||||
- clean-machine install verification passes on the signed candidate
|
||||
|
||||
### Week 8
|
||||
### Conditional Milestone B: Public Beta Learn Loop
|
||||
|
||||
- Ship permissions center, history, and recovery views
|
||||
- Trigger:
|
||||
- Conditional Milestone A is complete
|
||||
- Goal: run a small external beta after internal hardening is already complete.
|
||||
- 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
|
||||
- primary workflows are validated on more than one machine profile
|
||||
|
||||
### Week 9
|
||||
### Conditional Milestone C: GA Candidate and Launch
|
||||
|
||||
- Integrate privileged helper path and audit trail
|
||||
- Trigger:
|
||||
- Conditional Milestone B is complete
|
||||
- Goal: publish `v1.0` only after trust, recovery, and signed distribution all align.
|
||||
- Focus:
|
||||
- rerun full acceptance and signed packaging on the GA candidate
|
||||
- freeze release notes, notices, acknowledgements, and checksums
|
||||
- validate launch candidate install and first-run flow on a clean machine
|
||||
- Exit criteria:
|
||||
- no open P0 release blocker
|
||||
- signed packaging, install validation, and release docs are complete
|
||||
- `v1.0` artifacts are published
|
||||
|
||||
### Week 10
|
||||
## Current Decision Rules
|
||||
|
||||
- Run quality, regression, and performance hardening
|
||||
- Do not call the current workstream `public beta`.
|
||||
- Do not claim broader cleanup coverage than the worker/helper path can prove.
|
||||
- Do not claim physical recovery until file-backed restore is actually validated.
|
||||
- Do not schedule a public release date before signing credentials exist.
|
||||
|
||||
### Week 11
|
||||
## Not In This Roadmap
|
||||
|
||||
- Produce beta candidate and packaging pipeline
|
||||
|
||||
### Week 12
|
||||
|
||||
- Internal beta wrap-up and release-readiness review
|
||||
|
||||
## MVP Scope
|
||||
|
||||
- In scope: `Overview`, `Smart Clean`, `Apps`, `History`, `Recovery`, `Permissions`
|
||||
- Deferred to P1: `Storage treemap`, `Menu Bar`, `Automation`
|
||||
- `Storage treemap`
|
||||
- `Menu Bar`
|
||||
- `Automation`
|
||||
- new non-MVP modules
|
||||
|
||||
Reference in New Issue
Block a user