docs(wake-lock): record wake-lock change workflow
Add the wake-lock SCR, discussion summary, and task artifacts that captured investigation, specification, and implementation handoff for the system-sleep-only behavior change.
This commit is contained in:
Shantur Rathore
19
tasks/current.md
Normal file
19
tasks/current.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Current Tasks
|
||||
|
||||
## Active Discussions
|
||||
|
||||
- DISCUSSION-001 — Wake lock behavior change for macOS sleep vs screen lock — summarized, routed to task 056
|
||||
|
||||
## Active
|
||||
|
||||
- 055-wake-lock-investigation.md — standard / investigation / logic — Assigned to tech_lead
|
||||
- 056-wake-lock-behavior-change.md — complex / spec / logic — Assigned to business_analyst
|
||||
- 057-implement-system-sleep-only-wake-lock.md — complex / implementation / logic — Assigned to workflow_runner
|
||||
|
||||
## Todo
|
||||
|
||||
- 023-symbol-attachments.md
|
||||
|
||||
## Blocked
|
||||
|
||||
- None.
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
id: DISCUSSION-001
|
||||
title: "Wake lock behavior change for macOS sleep vs screen lock"
|
||||
status: closed
|
||||
summarized_by: business_analyst
|
||||
source: runtime-transcript
|
||||
---
|
||||
|
||||
# Discussion Summary
|
||||
|
||||
## Topic
|
||||
Change wake lock behavior so screen lock/display sleep is allowed while system sleep is still prevented during active work.
|
||||
|
||||
## Purpose
|
||||
Capture a workflow-ready summary of a requested product behavior change affecting desktop apps and web, including current behavior, desired behavior, scope, and unresolved platform feasibility.
|
||||
|
||||
## Repository Truth Relevant To This Discussion
|
||||
- Current desktop wake lock behavior is effectively configured as a display wake lock.
|
||||
- Electron currently uses `prevent-display-sleep`.
|
||||
- Tauri currently includes `display: true` in its wake-lock-related configuration.
|
||||
- This current setup keeps the screen awake and blocks normal screen lock/display sleep on macOS.
|
||||
|
||||
## Facts Established
|
||||
- The reported problem is specific to current wake lock behavior preventing screen lock on macOS.
|
||||
- The user wants wake lock to allow screen lock while still preventing the device from going to sleep.
|
||||
- The requested scope was expanded beyond macOS-only behavior.
|
||||
- The user explicitly requested coverage for all desktop apps and web.
|
||||
- Browser/web platform limitations may affect how fully the requested behavior can be implemented.
|
||||
|
||||
## Requirements Captured
|
||||
- Wake lock must allow the display to sleep or lock normally.
|
||||
- Wake lock must prevent only system sleep while work is active.
|
||||
- On macOS, the screen should be able to turn off and lock while the machine remains awake enough to continue the task.
|
||||
- The change should be researched and then applied, not just discussed.
|
||||
- Scope should include all desktop apps and web, subject to technical feasibility.
|
||||
|
||||
## Constraints
|
||||
- The change affects multiple platforms and should not be treated as a macOS-only behavior change.
|
||||
- Web support may be constrained by browser capabilities and wake lock API limitations.
|
||||
- Platform-specific implementation details may differ between Electron, Tauri, and web.
|
||||
|
||||
## Non-Goals
|
||||
- Keeping the display continuously awake.
|
||||
- Preserving the current display-wake behavior on macOS.
|
||||
- Defining a macOS-only special case unless later justified.
|
||||
|
||||
## Decisions Made
|
||||
- Preferred product direction: allow display sleep/screen lock while preventing only system sleep during active work.
|
||||
- Scope direction confirmed by the user: all desktop apps and web.
|
||||
- The discussion should move into tracked workflow work with product and technical input before implementation.
|
||||
|
||||
## Assumptions
|
||||
- “Work is active” refers to periods when the application is performing a task that currently relies on wake lock protection.
|
||||
- The intended outcome is continued task execution while the screen is locked or asleep, not continuous visual display.
|
||||
- Some platforms may require best-effort behavior rather than identical implementation mechanics.
|
||||
|
||||
## Open Questions
|
||||
- What exact user-facing definition of “work is active” should trigger wake lock behavior across products?
|
||||
- What behavior is achievable on web given browser/API support and permission constraints?
|
||||
- If a platform cannot prevent only system sleep without also affecting display sleep, what fallback behavior is acceptable?
|
||||
- Should platform-specific differences be exposed to users or documented in product behavior notes?
|
||||
|
||||
## Risks Or Concerns
|
||||
- Web may not support the requested behavior fully or consistently across browsers.
|
||||
- A platform may not offer a clean “prevent system sleep only” mode, creating inconsistent behavior across products.
|
||||
- Changing wake lock semantics could affect long-running task reliability if background execution assumptions are wrong.
|
||||
|
||||
## Referenced Files Or Areas
|
||||
- Electron wake lock implementation using `prevent-display-sleep`
|
||||
- Tauri wake lock / `keepawake` configuration currently using `display: true`
|
||||
- Cross-platform wake lock behavior for desktop apps
|
||||
- Web wake lock behavior and browser capability research areas
|
||||
|
||||
## Recommended Workflow Next Step
|
||||
- assigned_to: product_manager
|
||||
- why: Create a tracked task and SCR-ready handoff for cross-platform research and specification, then route to business analyst and technical architect for requirements and feasibility clarification before implementation.
|
||||
54
tasks/todo/055-wake-lock-investigation.md
Normal file
54
tasks/todo/055-wake-lock-investigation.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Wake Lock Investigation
|
||||
complexity: standard
|
||||
track: investigation
|
||||
slice: logic
|
||||
status: active
|
||||
assigned_to: tech_lead
|
||||
---
|
||||
|
||||
# Goal
|
||||
|
||||
Understand and explain how wake lock is held across `packages/ui`, `packages/tauri-app`, and `packages/electron-app`, including which layer initiates the request, which native/platform APIs are used, and how acquire/release lifecycle is coordinated.
|
||||
|
||||
# Request Context
|
||||
|
||||
The Product Owner asked: "Understand how we hold wake lock in packages/ui packages/tauri-app and packages/electron-app".
|
||||
|
||||
# Acceptance Criteria
|
||||
|
||||
- AC-1: Identify all wake-lock-related code paths in `packages/ui`, `packages/tauri-app`, and `packages/electron-app`.
|
||||
- AC-2: Explain which package owns the wake-lock decision and which package executes the platform-specific hold/release behavior.
|
||||
- AC-3: Describe the acquire and release lifecycle, including triggering events, cleanup behavior, and any fallback or unsupported-platform handling.
|
||||
- AC-4: Note any discrepancies, risks, or unclear behavior discovered during the investigation.
|
||||
|
||||
# Instructions For Assigned Agent
|
||||
|
||||
1. Read this task file first.
|
||||
2. Investigate the repository code paths relevant to wake lock in the three packages named above.
|
||||
3. Produce a concise technical report using the specialist output contract sections:
|
||||
- Summary
|
||||
- Work Performed
|
||||
- Acceptance Criteria Coverage
|
||||
- Documentation Impact
|
||||
- Open Risks
|
||||
- Recommended Next Step
|
||||
4. Include file paths and function/module names for the relevant wake-lock implementation points.
|
||||
5. Update this task file with a `# Post Implementation Task Updates` section and `## Tech Lead: Post Implementation Expectations` bullets describing the observable outputs of your investigation.
|
||||
|
||||
# Discussion Record
|
||||
|
||||
- Created by PMA to answer a direct user investigation request about wake-lock behavior across UI and native app shells.
|
||||
|
||||
# Notes
|
||||
|
||||
- This is investigation only. Do not implement changes.
|
||||
- Repository has unrelated untracked items in the working tree (`.nomadworks/`, `.playwright-cli/`, `cloudsecrets`, `tmp/`). Treat them as pre-existing and out of scope unless directly relevant.
|
||||
|
||||
# Post Implementation Task Updates
|
||||
|
||||
## Tech Lead: Post Implementation Expectations
|
||||
|
||||
- Deliver a wake-lock investigation report that traces the call flow from `packages/ui/src/App.tsx` through `packages/ui/src/lib/native/wake-lock.ts` into the Electron preload/main IPC path and the Tauri command path.
|
||||
- Identify which session states cause the UI to request wake lock and which native APIs actually hold or release the lock on Electron and Tauri.
|
||||
- Document lifecycle behavior for acquire, release, fallback handling, unsupported-platform behavior, and any cleanup gaps or discrepancies discovered during review.
|
||||
76
tasks/todo/056-wake-lock-behavior-change.md
Normal file
76
tasks/todo/056-wake-lock-behavior-change.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Wake Lock Behavior Change
|
||||
complexity: complex
|
||||
track: spec
|
||||
slice: logic
|
||||
status: active
|
||||
assigned_to: business_analyst
|
||||
scr: SCR-2026-04-21-001
|
||||
---
|
||||
|
||||
# Goal
|
||||
|
||||
Research and define the cross-platform wake-lock behavior change so implementation can safely shift from display wake to system-sleep-only behavior wherever feasible.
|
||||
|
||||
# Request Context
|
||||
|
||||
The Product Owner requested: allow screen lock/display sleep while preventing device sleep during active work, across desktop apps and web, and asked to research options and apply the change.
|
||||
|
||||
# Inputs
|
||||
|
||||
- `tasks/discussions/DISCUSSION-001-wake-lock-behavior-change-for-macos-sleep-vs-screen-lock.md`
|
||||
- `tasks/todo/055-wake-lock-investigation.md`
|
||||
- `docs/scrs/SCR-2026-04-21-001-wake-lock-system-sleep-only.md`
|
||||
|
||||
# Acceptance Criteria
|
||||
|
||||
- AC-1: Define product intent for when wake lock should engage, using explicit user-observable terms.
|
||||
- AC-2: Document platform feasibility/options for Electron, Tauri, and web, including unsupported cases.
|
||||
- AC-3: Recommend a product-safe fallback policy for any platform that cannot prevent system sleep without also preventing screen lock.
|
||||
- AC-4: Update the SCR with clarified scope and implementation-ready acceptance criteria.
|
||||
|
||||
# Instructions For Assigned Agents
|
||||
|
||||
## Business Analyst
|
||||
|
||||
1. Read this task file and all listed inputs in full.
|
||||
2. Clarify the product behavior and fallback expectations.
|
||||
3. Update the SCR with product-facing scope, terminology, and refined ACs.
|
||||
4. Return the specialist output contract sections.
|
||||
|
||||
## Tech Lead
|
||||
|
||||
1. After BA input, assess technical feasibility and implementation options for Electron, Tauri, and web.
|
||||
2. Identify the safest implementation direction and any platform gaps.
|
||||
3. Return the specialist output contract sections.
|
||||
|
||||
# Discussion Record
|
||||
|
||||
- Discussion summary captured in `tasks/discussions/DISCUSSION-001-wake-lock-behavior-change-for-macos-sleep-vs-screen-lock.md`.
|
||||
- User confirmed scope should include all desktop apps and web.
|
||||
- User asked to research options and apply the resulting change.
|
||||
|
||||
# Notes
|
||||
|
||||
- This task starts as spec/discovery. Implementation should not begin until product and technical feasibility are clear enough to proceed safely.
|
||||
|
||||
# Reviews
|
||||
|
||||
- Business Analyst review completed: clarified that product intent is consistent across platforms but platform execution is best-effort, defined "active work" in user-observable terms, and set the fallback rule to prefer no wake lock over display-wake behavior when system-sleep-only support is unavailable.
|
||||
- Tech Lead review completed: Electron can switch safely to `powerSaveBlocker.start("prevent-app-suspension")`; Tauri can target `keepawake` with `display: false, idle: true, sleep: false` as the closest cross-platform system-idle-sleep-only mode; web has no viable standards-based system-sleep-only API and must fall back to no wake lock. Scope is implementation-ready with explicit platform limitation notes and verification of long-running background behavior per desktop runtime.
|
||||
|
||||
# Post Implementation Task Updates
|
||||
|
||||
## Business Analyst: Post Implementation Expectations
|
||||
|
||||
- The SCR defines "active work" as only currently running in-app work that should continue without continuous foreground interaction, and excludes idle, paused, completed, cancelled, or waiting-for-input states.
|
||||
- The SCR states a consistent product rule across platforms: allow screen lock/display sleep, use system-sleep-only protection where available, and release protection promptly when qualifying work ends.
|
||||
- The SCR defines unsupported-platform fallback behavior, including the explicit rule that web or any other unsupported runtime must not use display/screen wake as a substitute and should instead fall back to no wake lock.
|
||||
- The SCR leaves final platform feasibility validation to technical review without expanding scope into implementation or new user settings.
|
||||
|
||||
## Tech Lead: Post Implementation Expectations
|
||||
|
||||
- Electron wake lock behavior changes from `prevent-display-sleep` to `prevent-app-suspension`, so active work keeps the machine awake without intentionally blocking display sleep or screen lock.
|
||||
- Tauri wake lock requests use the native `keepawake` path with `display: false, idle: true, sleep: false`, aligning behavior to prevent idle system sleep without requesting display wake or explicit-sleep inhibition.
|
||||
- Web no longer attempts `navigator.wakeLock.request("screen")` for this feature path and instead degrades to no wake lock with a documented limitation because the web platform does not expose a true system-sleep-only primitive.
|
||||
- Runtime behavior releases protection promptly when qualifying active work ends, pauses, fails, is cancelled, or the app cleans up, and desktop verification confirms long-running work continues while the display can sleep or lock.
|
||||
64
tasks/todo/057-implement-system-sleep-only-wake-lock.md
Normal file
64
tasks/todo/057-implement-system-sleep-only-wake-lock.md
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Implement System-Sleep-Only Wake Lock
|
||||
complexity: complex
|
||||
track: implementation
|
||||
slice: logic
|
||||
status: active
|
||||
assigned_to: workflow_runner
|
||||
scr: SCR-2026-04-21-001
|
||||
---
|
||||
|
||||
# Goal
|
||||
|
||||
Implement the approved wake-lock behavior change so qualifying active work prevents idle system sleep where supported, allows screen lock/display sleep, and degrades to no wake lock on unsupported platforms.
|
||||
|
||||
# Scope
|
||||
|
||||
- Update wake-lock decision logic in UI so only qualifying active work engages wake lock.
|
||||
- Update Electron to use system-sleep-only behavior instead of display wake.
|
||||
- Update Tauri to request system-idle-sleep prevention without display wake.
|
||||
- Remove the web screen wake-lock fallback for this feature path.
|
||||
- Add/adjust tests and documentation impacted by the behavior change.
|
||||
|
||||
# Inputs
|
||||
|
||||
- `docs/scrs/SCR-2026-04-21-001-wake-lock-system-sleep-only.md`
|
||||
- `tasks/todo/055-wake-lock-investigation.md`
|
||||
- `tasks/todo/056-wake-lock-behavior-change.md`
|
||||
- `tasks/discussions/DISCUSSION-001-wake-lock-behavior-change-for-macos-sleep-vs-screen-lock.md`
|
||||
|
||||
# Acceptance Criteria
|
||||
|
||||
- AC-1: Wake lock engages only for qualifying active work and does not engage for idle, paused, completed, cancelled, or waiting-for-user-input states.
|
||||
- AC-2: Electron uses a system-sleep-only mode that allows screen lock/display sleep while active work is running.
|
||||
- AC-3: Tauri requests the closest supported system-idle-sleep prevention mode without requesting display wake.
|
||||
- AC-4: Web does not use screen/display wake lock as a fallback for this feature path and instead degrades to no wake lock.
|
||||
- AC-5: Wake lock is released promptly when qualifying active work ends or the app cleans up.
|
||||
- AC-6: Required verification demonstrates the new desktop behavior and confirms fallback handling/documentation for unsupported web behavior.
|
||||
|
||||
# Implementation Guidance
|
||||
|
||||
- Align the UI definition of qualifying active work with the SCR. In particular, do not treat waiting-for-input / permission-question states as wake-lock-worthy unless technical review finds a repository truth conflict that must be escalated.
|
||||
- Electron target behavior from Tech Lead review: `powerSaveBlocker.start("prevent-app-suspension")`.
|
||||
- Tauri target behavior from Tech Lead review: use `keepawake` configuration `display: false, idle: true, sleep: false`.
|
||||
- Web fallback from BA/Tech Lead review: no wake lock for this feature path; do not use `navigator.wakeLock.request("screen")` as a substitute.
|
||||
- Update product-facing and/or code-adjacent docs as needed to record the supported-platform limitation and resulting behavior.
|
||||
- Collect clear verification evidence mapped back to AC-1 through AC-6.
|
||||
|
||||
# Specialist Expectations
|
||||
|
||||
- Workflow Runner should orchestrate implementation plus verification using the appropriate specialists.
|
||||
- Introduce specialist roles in verification feedback.
|
||||
- Do not create a final git commit unless PMA explicitly instructs you to do so.
|
||||
|
||||
# Notes
|
||||
|
||||
- Existing unrelated untracked files in the repository are out of scope unless they block verification.
|
||||
|
||||
# Post Implementation Task Updates
|
||||
|
||||
## Workflow Runner: Post Implementation Expectations
|
||||
|
||||
- UI wake-lock eligibility now follows the SCR definition of qualifying active work and excludes sessions waiting on permission or question input.
|
||||
- Electron now requests `prevent-app-suspension`, Tauri now requests `display: false, idle: true, sleep: false`, and web no longer falls back to screen wake lock for this feature path.
|
||||
- Verification covers UI eligibility logic, workspace typechecks/build checks, and the documented unsupported web fallback behavior.
|
||||
Reference in New Issue
Block a user