docs/task.md

# Task Schema

**Source file:** `core/task.py`

---

## Overview

A `Task` object defines everything about one episode: the goal, the state the agent operates in, what can happen during the episode, how success is measured, and how long the agent has. `LifeStackEnv.reset()` takes a `Task` and builds the entire episode state from it.

---

## `Task` dataclass

| Field | Type | Description |
|-------|------|-------------|
| `id` | `str` | Unique task identifier |
| `domain` | `str` | Task domain: `"flight_crisis"`, `"code_merge_crisis"`, etc. |
| `goal` | `str` | Human-readable objective shown to the agent |
| `constraints` | `dict` | Budget and deadline keys, e.g. `{"budget_max": 400, "deadline_step": 18}` |
| `hidden_state` | `dict` | Full truth; agent cannot see directly (e.g. `{"card_available": True}`) |
| `mutable_world` | `dict` | Partial truth; some keys visible, some only revealed by inspect |
| `visible_world` | `dict` | Always-visible subset of `mutable_world` |
| `success_conditions` | `list[dict]` | Terminal predicates, e.g. `[{"key": "flight_rebooked", "value": True}]` |
| `failure_conditions` | `list[dict]` | Episode-ending failure predicates |
| `event_schedule` | `list[ExoEvent]` | Events that fire during the episode |
| `viable_routes` | `list[Route]` | Paths the agent can execute |
| `milestones` | `list[Milestone]` | Intermediate progress gates |
| `horizon` | `int` | Max steps (e.g. 30 for `FlightCrisisTask`, 10 for `CodeMergeCrisisTask`) |
| `difficulty` | `int` | 1–5 curriculum index |
| `domain_metadata` | `dict` | Story text and domain-specific generator hints |

---

## `Route` dataclass

A route is a structured path the agent can execute by targeting it with `action_type="execute"` (or any matching `required_action_types` entry). When a route's preconditions are met and it's executed, its `consequences` are applied to `world_state`, which can trigger success conditions.

| Field | Description |
|-------|-------------|
| `id` | Route identifier, shown to agent in prompt |
| `name` | Human-readable name |
| `required_action_types` | The model must use one of these action types to execute the route |
| `preconditions` | World/hidden state checks that must be true before the route is available |
| `consequences` | World state mutations on route completion |
| `closes_routes` | Route IDs that become unavailable after this route is taken |
| `milestones_unlocked` | Milestone IDs this route can trigger |
| `final_reward` | Bonus added on route completion |

Example from `FlightCrisisTask`:
```python
Route(
    id="rebook_premium",
    name="Rebook Premium Option",
    required_action_types=["communicate", "execute"],
    preconditions={"card_available": True},
    consequences={"flight_rebooked": True},
    closes_routes=["wait_lounge"],
    final_reward=2.5
)
```

---

## `Milestone` dataclass

Intermediate checkpoints that reward partial progress. `LifeStackVerifier.check_new_milestones()` scans milestones every step.

| Field | Description |
|-------|-------------|
| `id` | Milestone identifier |
| `condition_key` | World/hidden key to check |
| `condition_value` | Required value |
| `reward` | Added to episode reward when milestone is hit |

---

## `ExoEvent` dataclass

World events that fire during the episode, potentially changing state and closing routes.

| Field | Description |
|-------|-------------|
| `step` | Fire at this step; -1 = probabilistic |
| `probability` | 1.0 = always fire; <1.0 = fire with this probability when step=-1 |
| `world_mutation` | Dict applied to `world_state` when event fires |
| `hidden_state_mutation` | Dict applied to `hidden_state` when event fires |
| `closes_routes` | Route IDs made unavailable after this event |

---

## Built-in task factories

`FlightCrisisTask()` — "Survive Airport Cancellation", horizon=30, difficulty=4. Two competing routes (`rebook_premium` requires `card_available=True`; `wait_lounge` requires `lounge_access=True`). Two timed events: a `price_surge` at step 5 sets `card_available=False`, and `lounge_full` at step 8 closes `wait_lounge`.

`CodeMergeCrisisTask()` — "Resolve Production Outage", horizon=10, difficulty=4. Two competing routes: revert the commit (`revert_commit`) or push a hotfix (`hotfix`). No scheduled events.

`TaskGenerator` in `core/task.py` holds only these two. The richer `TaskGenerator` in `agent/conflict_generator.py` covers all 8 task domains with template-based generation and is the one used by `scripts/train_trl.py`.

---

## Related files

- `core/lifestack_env.py` — `WorldEngine` fires `ExoEvent` objects during `step()`
- `core/verifier.py` — `LifeStackVerifier` checks success/failure/milestone conditions
- `agent/conflict_generator.py` — full `TaskGenerator` for all 8 domains
- `docs/lifestack_env.md` — how tasks integrate with the environment