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.

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.

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.

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.

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).

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:<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).

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.

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).

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