---
id: PLN-0059
ticket: task-owned-shell-windows
title: Plan - Task Window Contract Specs
status: open
created: 2026-05-15
completed:
ref_decisions: [DEC-0027]
tags: [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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/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:

   ```text
   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.