prometeu-runtime/discussion/workflow/plans/PLN-0059-plan-task-window-contract-specs.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0059	task-owned-shell-windows	Plan - Task Window Contract Specs	done	2026-05-15	2026-05-15	DEC-0027	runtime os task window-manager shell lifecycle specs

Plan - Task Window Contract Specs

Briefing

Document the task-owned shell window contract from DEC-0027 in the canonical runtime specs before code execution changes the observable model.

Decisions de Origem

• DEC-0027 - Task-Owned Shell Windows

Alvo

The canonical specs must state that:

• Process is technical execution.
• Task is navigable presence.
• Window is visual presence for shell/system tasks managed by the WindowManager.
• Game cartridges are not WindowManager windows and continue as fullscreen GameRunningStep sessions.
• Shell app windows use WindowOwner::Task(TaskId).
• Hub and Overlay are not shell task windows.
• v1 ShellRunningStep continues only while the focused window belongs to its own task.

Escopo

Included:

• Update docs/specs/runtime/12-firmware-pos-and-prometeuhub.md with the contract.
• Add or adjust terminology in the same file if the existing terms section is the best local home.
• Link the contract to firmware states, AppMode behavior, and Hub/system window responsibilities.

Fora de Escopo

• Code changes in crates/.
• Overlay/modal policy.
• Background services, minimization, app switcher, or dock behavior.
• Multiple-window semantics beyond preserving future compatibility.
• Rewriting unrelated firmware spec sections.

Plano de Execucao

1. Locate the normative spec home. Use docs/specs/runtime/12-firmware-pos-and-prometeuhub.md as the primary target because it already owns POS, Hub, AppMode, and firmware states.

2. Extend the terms section. Add concise definitions for Process, Task, Window, WindowOwner, and shell task windows if they are not already present.

3. Add a Task-Owned Shell Windows section. State the v1 predicate explicitly:

   TaskState::Foreground
   +
   focused window owner == WindowOwner::Task(task_id)
   

   State that the runtime API is os.windows().focused_window_belongs_to_task(task_id).

4. Clarify AppMode separation. Under Game, state that games are fullscreen firmware sessions and must not be modeled as WindowManager windows. Under System, state that shell apps are represented through task-owned windows.

5. Clarify lifecycle consequence. State that when a shell task loses its eligible focused window, ShellRunningStep must close the task through SystemOS lifecycle and then return to Hub.

6. Keep excluded topics explicit. Add a short note that overlay policy, minimization, app switcher, dock, and background services are future contracts, not part of v1.

Criterios de Aceite

• The spec describes the Process / Task / Window model in English.
• The spec states that games are not WindowManager windows.
• The spec states that shell app windows use WindowOwner::Task(TaskId).
• The spec states the v1 ShellRunningStep focused-window predicate.
• The spec states that loss of the eligible focused window closes the task through lifecycle before returning to Hub.
• The spec does not introduce overlay, background, minimization, app switcher, dock, or multiple-window policy.

Tests / Validacao

• Run discussion validate.
• Review the changed spec for English-only normative text.
• Confirm every normative point from DEC-0027 has a corresponding spec line.

Riscos

• The spec may become too implementation-specific if it describes current Rust call sites instead of the contract.
• The spec may accidentally imply overlay/modal behavior. Keep overlay behavior explicitly out of scope.
• Future work may need a dedicated OS/window spec chapter; this plan keeps the change local to the existing firmware/Hub spec.