> ## Documentation Index
> Fetch the complete documentation index at: https://codexceed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# avatar.state

TaskState — the structured source of truth for one task (§7).

The model's message history is *derived* from this; it is not the source of
truth. State is explicit, append-mostly, and fully serializable so a run can be
inspected and replayed. The runner owns all mutation (§8); these helpers are the
only sanctioned mutations.

## Classes

### `CheckResult`

One verifier check with an explicit status (§12).

A skipped check is not a passed check: `skip_reason` is required when
`status == "skip"` so the gate can distinguish allowed skips from evasions.

```python theme={null}
CheckResult(*, name: str, kind: Literal['required', 'optional'], status: Literal['pass', 'fail', 'skip'], evidence: str, skip_reason: str | None = None) -> None
```

**Fields**

| Field         | Type                              | Required |    |
| ------------- | --------------------------------- | -------- | -- |
| `name`        | `str`                             | yes      |    |
| `kind`        | `Literal['required', 'optional']` | yes      |    |
| `status`      | `Literal['pass', 'fail', 'skip']` | yes      |    |
| `evidence`    | `str`                             | yes      |    |
| `skip_reason` | \`str                             | None\`   | no |

### `CommandRecord`

A command the harness ran on the workspace's behalf.

```python theme={null}
CommandRecord(*, step: int, command: str, exit_code: int | None = None, summary: str = '') -> None
```

**Fields**

| Field       | Type  | Required |    |
| ----------- | ----- | -------- | -- |
| `step`      | `int` | yes      |    |
| `command`   | `str` | yes      |    |
| `exit_code` | \`int | None\`   | no |
| `summary`   | `str` | no       |    |

### `ConversationTurn`

One cross-goal conversation turn, replayed to the model as a real chat message (ADR-0017).

Distinct from `Evidence`: prior user goals and agent replies are sent as genuine
`role="user"`/`role="assistant"` messages preceding the working packet, not flattened
into "Recent evidence" bullets the model under-weights.

```python theme={null}
ConversationTurn(*, role: Literal['user', 'assistant'], content: str) -> None
```

**Fields**

| Field     | Type                           | Required |
| --------- | ------------------------------ | -------- |
| `role`    | `Literal['user', 'assistant']` | yes      |
| `content` | `str`                          | yes      |

### `DecisionRecord`

Why the agent chose what it chose, and how it turned out (§7).

`outcome` is filled in after the action runs (tool summary/error, verifier
verdict, block reason) so the action ledger can show `chosen → outcome`.

```python theme={null}
DecisionRecord(*, step: int, rationale: str, chosen: str, key: str = '', rejected: list[str] = <factory>, outcome: str = '') -> None
```

**Fields**

| Field       | Type        | Required |
| ----------- | ----------- | -------- |
| `step`      | `int`       | yes      |
| `rationale` | `str`       | yes      |
| `chosen`    | `str`       | yes      |
| `key`       | `str`       | no       |
| `rejected`  | `list[str]` | no       |
| `outcome`   | `str`       | no       |

### `Evidence`

A test output, command result, file finding, or error (§7).

```python theme={null}
Evidence(*, step: int, kind: str, summary: str, detail: str | None = None) -> None
```

**Fields**

| Field     | Type  | Required |    |
| --------- | ----- | -------- | -- |
| `step`    | `int` | yes      |    |
| `kind`    | `str` | yes      |    |
| `summary` | `str` | yes      |    |
| `detail`  | \`str | None\`   | no |

### `PlannedCheck`

One resolved verification check: what runs, and where it came from (ADR-0007).

The unit of the per-session verification plan. `provenance` names the artifact
the command was resolved from (`config:AVATAR_TEST_COMMAND`, `ci:.github/...`,
`Makefile:test`, `llm:&lt;cited path>`, `model-smoke`, `model-declared`), so every
run's rubric is auditable. `smoke` is the greenfield floor (ADR-0014): a model-authored
check the harness still runs itself, resolved at verification time rather than frozen up
front. `declared` is a greenfield model-declared contract (ADR-0038): a real executing
check the model authors up front (mandatory for greenfield edits), frozen like tiers 1-3
but semi-frozen — amendable only through a gated action. `floor` is the immutable
non-vacuity anchor beneath a declared contract; the model can never amend it away.

`chain` links checks split from one `&&` line (ADR-0045): the verifier stops a chain
at its first failure, preserving shell short-circuit semantics — a failing segment
still guards a later mutating one. `None` for independent checks. Optional with a
default, so journals written before the field parse unchanged (version-skew rule).

```python theme={null}
PlannedCheck(*, name: str, command: str, kind: Literal['test', 'lint', 'smoke', 'declared', 'floor'], provenance: str, chain: str | None = None) -> None
```

**Fields**

| Field        | Type                                                    | Required |    |
| ------------ | ------------------------------------------------------- | -------- | -- |
| `name`       | `str`                                                   | yes      |    |
| `command`    | `str`                                                   | yes      |    |
| `kind`       | `Literal['test', 'lint', 'smoke', 'declared', 'floor']` | yes      |    |
| `provenance` | `str`                                                   | yes      |    |
| `chain`      | \`str                                                   | None\`   | no |

### `TaskState`

The full, serializable state of one task — the harness's source of truth (§7).

Carries the two independent axes (`phase` = where the work is, `outcome` =
how it ended), the bounding counters, and the accumulated evidence/decisions
the context builder draws on. The model's message history is derived from this.

```python theme={null}
TaskState(*, task_id: str = <factory>, goal: str, constraints: list[str] = <factory>, task_kind: Literal['edit', 'investigate', 'test_only'] = 'edit', mode_source: str | None = None, phase: Literal['investigating', 'editing', 'verifying'] = 'investigating', outcome: Literal['success', 'incomplete', 'blocked', 'failed'] | None = None, iterations: int = 0, consecutive_failures: int = 0, repair_failures: int = 0, declaration_nudges: int = 0, smoke_floor_attempted: bool = False, escalated: bool = False, escalation_thrash_streak: int = 0, escalation_nudged: bool = False, prompt_tokens: int = 0, completion_tokens: int = 0, files_read: set[str] = <factory>, files_modified: set[str] = <factory>, commands_run: list[CommandRecord] = <factory>, conversation: list[ConversationTurn] = <factory>, evidence: list[Evidence] = <factory>, decisions: list[DecisionRecord] = <factory>, verifier_results: list[VerifierResult] = <factory>, verification_plan: list[PlannedCheck] | None = None, declared_change_kinds: list[str] | None = None, current_plan: list[str] = <factory>, open_questions: list[str] = <factory>, latest_error: str | None = None, final_answer: str | None = None) -> None
```

**Fields**

| Field                      | Type                                                     | Required |    |
| -------------------------- | -------------------------------------------------------- | -------- | -- |
| `task_id`                  | `str`                                                    | no       |    |
| `goal`                     | `str`                                                    | yes      |    |
| `constraints`              | `list[str]`                                              | no       |    |
| `task_kind`                | `Literal['edit', 'investigate', 'test_only']`            | no       |    |
| `mode_source`              | \`str                                                    | None\`   | no |
| `phase`                    | `Literal['investigating', 'editing', 'verifying']`       | no       |    |
| `outcome`                  | \`Literal\['success', 'incomplete', 'blocked', 'failed'] | None\`   | no |
| `iterations`               | `int`                                                    | no       |    |
| `consecutive_failures`     | `int`                                                    | no       |    |
| `repair_failures`          | `int`                                                    | no       |    |
| `declaration_nudges`       | `int`                                                    | no       |    |
| `smoke_floor_attempted`    | `bool`                                                   | no       |    |
| `escalated`                | `bool`                                                   | no       |    |
| `escalation_thrash_streak` | `int`                                                    | no       |    |
| `escalation_nudged`        | `bool`                                                   | no       |    |
| `prompt_tokens`            | `int`                                                    | no       |    |
| `completion_tokens`        | `int`                                                    | no       |    |
| `files_read`               | `set[str]`                                               | no       |    |
| `files_modified`           | `set[str]`                                               | no       |    |
| `commands_run`             | `list[CommandRecord]`                                    | no       |    |
| `conversation`             | `list[ConversationTurn]`                                 | no       |    |
| `evidence`                 | `list[Evidence]`                                         | no       |    |
| `decisions`                | `list[DecisionRecord]`                                   | no       |    |
| `verifier_results`         | `list[VerifierResult]`                                   | no       |    |
| `verification_plan`        | \`list\[PlannedCheck]                                    | None\`   | no |
| `declared_change_kinds`    | \`list\[str]                                             | None\`   | no |
| `current_plan`             | `list[str]`                                              | no       |    |
| `open_questions`           | `list[str]`                                              | no       |    |
| `latest_error`             | \`str                                                    | None\`   | no |
| `final_answer`             | \`str                                                    | None\`   | no |

#### `TaskState.add_feedback(self, summary: str, *, detail: str | None = None, kind: str = 'feedback') -> None`

Append evidence the next context build will surface (§5 repair loop).

Args:
summary: One-line evidence the next context build surfaces.
detail: Optional verbatim detail kept out of the model's summary view.
kind: Evidence category, e.g. `feedback` or `blocker`.

#### `TaskState.amend_declared_contract(self, checks: list[PlannedCheck]) -> None`

Replace the model-declared checks in the frozen plan, preserving the floor (ADR-0038).

The one sanctioned mid-run rewrite of a declared contract, applied by the runner only
after a gated `alter_verification` is approved. Entries whose kind is not `"declared"`
(the immutable floor, any detected checks) are preserved — the model can move its own
goalposts, never the harness's floor.

Args:
checks: The new declared checks (`kind="declared"`) replacing the old ones.

Raises:
RuntimeError: When there is no frozen plan to amend.

#### `TaskState.append_verification_floor(self, check: PlannedCheck) -> None`

Append the immutable non-vacuity floor beneath a model-declared contract (ADR-0038).

The floor is a harness-authored check the model can never declare or amend; it is
appended (`kind="floor"`) to the frozen plan so `success` always requires it *in
addition* to whatever the model declared. Applied at most once — a plan that already
carries a floor is left untouched.

Args:
check: The floor check to append (`kind="floor"`).

Raises:
RuntimeError: When no plan is frozen yet.

#### `TaskState.block(self, reason: str) -> None`

Terminal: the task needs human input (§5 ask\_user in a non-interactive run).

Args:
reason: Why the task is blocked.

#### `TaskState.freeze_verification_plan(self, plan: list[PlannedCheck]) -> None`

Freeze the resolved verification plan — once, before editing begins (ADR-0007).

The freeze is an authority transfer away from the model: after it, the
rubric cannot move. A second freeze attempt is a harness bug, not a retry.

Args:
plan: The resolved checks (may be empty: "nothing discovered").

Raises:
RuntimeError: When a plan is already frozen onto this state.

#### `TaskState.set_smoke_floor(self, checks: list[PlannedCheck]) -> None`

Late-bind the greenfield smoke floor onto an otherwise-empty frozen plan (ADR-0014).

The one sanctioned exception to "the rubric never moves mid-run": it applies
ONLY when tiers 1-3 discovered nothing (`verification_plan == []`), turning the
empty no-contract plan into a model-authored smoke check resolved at verify time.
A non-empty (a real contract won) or unfrozen (`None`) plan is never touched.

Args:
checks: The resolved smoke check(s) to bind.

Raises:
RuntimeError: When the frozen plan is not the empty no-contract plan.

#### `TaskState.terminal`

Whether the task has reached a terminal outcome (loop should stop).

### `VerifierResult`

The verifier's verdict for one verification attempt (§12).

```python theme={null}
VerifierResult(*, passed: bool, summary: str, checks: list[CheckResult] = <factory>, recommended_next_action: str | None = None) -> None
```

**Fields**

| Field                     | Type                | Required |    |
| ------------------------- | ------------------- | -------- | -- |
| `passed`                  | `bool`              | yes      |    |
| `summary`                 | `str`               | yes      |    |
| `checks`                  | `list[CheckResult]` | no       |    |
| `recommended_next_action` | \`str               | None\`   | no |