agentic-mobile-control/openspec/changes/planner-reflection-history/specs/world-model/spec.md

MODIFIED Requirements

Requirement: Bounded history of recent scene/action pairs

The system SHALL maintain WorldState.history as a fixed-size, bounded collection of the most recent per-step records, automatically evicting the oldest entry when a new entry is added past the configured bound. Each history record SHALL store the action name, executable action arguments, success flag, page context (from WorldState.current_page at the time of recording), and optional rationale, thinking, purpose, and expected-outcome fields sourced from the executed PlannedStep. The scene_summary field SHALL be retained as an optional field for backward compatibility but SHALL NOT be required for new entries.

Scenario: WorldState survives across steps within a task

• WHEN a task executes multiple steps in sequence
• THEN the WorldState object associated with the task is the same object (or reflects continuously accumulated updates) across those steps, not reset between steps

Scenario: WorldState is scoped to a single task

• WHEN two different tasks run (sequentially or concurrently) against the same or different devices
• THEN each task has its own independent WorldState, and neither task's WorldState reflects the other task's app/page/variables/history

Scenario: History record includes rationale when planner provides it

• WHEN the executed PlannedStep carries a non-None rationale
• THEN the resulting WorldEvent stores that rationale string

Scenario: History record stores None rationale when planner does not provide one

• WHEN the executed PlannedStep has rationale=None
• THEN the resulting WorldEvent stores rationale=None without error

Scenario: History record includes thinking when planner provides it

• WHEN the executed PlannedStep carries a non-None thinking
• THEN the resulting WorldEvent stores that thinking string

Scenario: History record includes reusable action metadata

• WHEN an executed PlannedStep carries a purpose and expected outcome
• THEN the resulting WorldEvent stores both values for the next planning turn and later reuse

Scenario: History record includes executed action arguments

• WHEN a PlannedStep executes with action arguments such as a tap's x and y coordinates
• THEN the resulting WorldEvent stores those executable arguments with the action name

Scenario: History record captures current page at time of recording

• WHEN a step is appended to history and WorldState.current_page is non-None at that moment
• THEN WorldEvent.page is set to that page value

Scenario: History record stores None page when current_page is unavailable

• WHEN a step is appended to history and WorldState.current_page is None
• THEN WorldEvent.page is None without error

Scenario: History size remains bounded

• WHEN steps are appended beyond the configured history bound
• THEN the oldest entries are evicted so history size never exceeds the bound