feat(macos): project Task 7 first-run research flow

[jasoncavinder]

Summary

• project the canonical Project WOW first-run scenario through Helm's shipping Environment Brief host behind paired Debug-only research gates
• present the exact brief -> reviewed plan -> verified progress -> Action Receipt sequence using fixture-local state only
• fail closed on missing, invalid, reordered, or canonically drifted Task 7 data
• localize the complete flow across all seven supported locales and preserve canonical/bundled catalog parity
• prevent research completion from persisting onboarding state or starting service, database, updater, discovery, network, authorization, or mutation work

Safety and contracts

• Task 7 requires both HELM_WAYFINDER_RESEARCH_DATASET and HELM_ENVIRONMENT_BRIEF_FIRST_RUN=preview in a Debug build
• Release builds and Tasks 1-6 retain their existing behavior
• copied evidence is restricted to aggregate status, counts, network/auth booleans, OS family, and architecture
• exact record order, UUID identity, full canonical first-run snapshot, legal stage transitions, and completion policy are regression-protected
• owner QA exposed a literal {manager} in the expected-state sentence; the projection now carries the manager substitution as a localized fact and a focused regression protects it

Validation

• full arm64 repository quality gate passed
• Rust workspace tests, cargo fmt, and cargo clippy -D warnings passed
• 335 Swift tests passed on the macOS 13 arm64 target
• locale integrity, overflow, and canonical/bundled parity checks passed
• release contract tests and dry-run preflight passed
• docs-sync and git diff --check passed

Owner QA

An isolated arm64 Debug build on macOS 26.6.2 passed the bounded canonical flow, aggregate-only copied summary, corrected mise verification text, receipt dismissal, and same-build/same-database relaunch check. The broader Light/Dark, Full Keyboard Access, VoiceOver, representative-locale, +40% expansion, and missing/invalid-dataset matrix remains explicitly open and is not represented as participant validation.

Detailed evidence and artifact hashes are recorded in docs/validation/v0.20-wayfinder-popover-research-readiness.md.

[cloudflare-workers-and-pages]

Deploying helm with    Cloudflare Pages

Latest commit:	e87d30d
Status:	✅  Deploy successful!
Preview URL:	https://174361d2.helm-6xn.pages.dev
Branch Preview URL:	https://feat-v020-first-run-task7.helm-6xn.pages.dev

View logs

[jasoncavinder]

Independent review findings (head 57146fa0)

I completed an independent review across runtime safety, UI/accessibility, tests, docs, and the current CI signal. I found four actionable issues:

1. [P1] The fixed 960×600 research flow has no reliable overflow path. The stage layout is a non-scrollable vertical stack, while plan and receipt content is forced into horizontal card rows. Supported text expansion and longer locales can push the footer actions outside the fixed, non-resizable first-run window. The flow needs a reachable vertical overflow path and compact-width card reflow.

2. [P2] The documented paired preview gate is not enforced. WholeWorkflowResearchDatasetProvider.firstRunRuntimeState checks only the research dataset selector, so HELM_WHOLE_WORKFLOW_DATASET=research with HELM_ENVIRONMENT_BRIEF_FIRST_RUN=enabled still projects Task 7. Completion then suppresses persisted onboarding because a research dataset is selected, while enabled mode ignores preview dismissal. This leaves every completion action unable to dismiss the flow. Projection and completion policy should require the paired preview gate, with a mode/dataset matrix test.

3. [P2] Stage transitions and copy feedback are incomplete for assistive technology. Replacing the stage subtree via .id(session.stage) can strand VoiceOver focus without moving focus or announcing the new stage. The receipt copy action also ignores the Boolean result from NSPasteboard.setString and always reports success without an accessibility announcement. Focus/announcement handling and truthful pasteboard feedback should match the existing app precedent.

4. [P3] Readiness and current-state documentation overstate or contradict the evidence. The readiness checklist marks all three completion entry points as covered, but automation currently exercises only the pure persistence-policy Boolean and owner QA directly rechecked only the receipt path. Separately, several current-status sections still say Task 7 is open or unprojected alongside newer completion claims. The checklist should reflect actual evidence and the source-of-truth docs should be reconciled rather than layering superseding statements.

The existing safety fences and canonical payload validation otherwise look sound. The current required checks are green apart from the still-running Swift CodeQL job; I am proceeding with remediation without waiting for it, as requested.

[jasoncavinder]

Remediation follow-up

All independent-review findings are remediated in commit e87d30d3:

• Task 7 runtime projection and non-persistent completion now share one paired Debug-only condition: a selected whole-workflow dataset plus HELM_ENVIRONMENT_BRIEF_FIRST_RUN=preview. Dataset-only and enabled configurations remain outside the research flow, and valid/missing preview combinations are regression-tested.
• Plan, progress, and receipt stages now have a vertical overflow path in the fixed first-run window; plan and receipt card groups also reflow vertically when their horizontal layout does not fit.
• Stage replacement explicitly transfers accessibility focus and announces the localized destination. Copy Summary now reports success only when NSPasteboard.setString succeeds and posts the same localized accessibility announcement used by the visible success state.
• The readiness checklist now preserves the receipt-only owner evidence and leaves direct brief/plan completion checks open. Current-state, next-step, roadmap, migration-map, and readiness wording no longer contradict whether Task 7 is implemented.

Verification on the remediated head:

• full arm64 Debug app-target quality gate: 335 tests passed
• SwiftLint 0.59.1 strict: 0 violations
• locale integrity, length heuristic, and canonical/bundled parity: passed
• docs sync: passed
• git diff --check: passed
• independent commit-level runtime, UI/accessibility, and docs/test re-review: no remaining actionable findings

The remote PR head is now e87d30d3 and GitHub reports it mergeable. Fresh-head CI had not populated immediately after the push; per the request, I did not wait for every check. Based on the independent review and completed local gates, the PR is ready for merging once repository-required checks permit it.

[jasoncavinder]

Remediation follow-up

All findings from the independent review are addressed in e87d30d3:

• Task 7 runtime projection and onboarding non-persistence now share one paired HELM_WAYFINDER_RESEARCH_DATASET + HELM_ENVIRONMENT_BRIEF_FIRST_RUN=preview condition. Dataset-only and enabled configurations remain inactive, and the valid/missing preview matrix is regression-tested.
• Plan, progress, and receipt stages now have a vertical overflow path inside the fixed first-run window; plan/receipt cards also have compact-width vertical fallbacks.
• Stage changes move accessibility focus and announce the new stage. Copy Summary now reports success only when NSPasteboard.setString succeeds and announces that success.
• The completion-evidence checklist is narrowed to the evidence actually collected, and stale Task 7 open/unprojected statements are reconciled across the current-state, next-steps, roadmap, and migration-map sources.

Verification completed on the remediation commit:

• full arm64 macOS app-target gate: 335 tests passed
• SwiftLint 0.59.1 strict: 0 violations
• locale integrity, length heuristic, and canonical/bundled parity: passed
• docs-sync: passed
• git diff --check: passed
• independent commit-level runtime, UI/accessibility, and docs/test re-reviews: no remaining actionable findings

Fresh GitHub checks may still be running on the updated head; per request, I did not wait for all of them. Based on the completed local gates and re-review, the PR is ready for merging once required branch checks permit it.