Task¶

A Task is the durable, per-project object that carries one implementation stream from the moment it is triaged to the moment it is delivered. It is not one pod, not one PR, and not one issue. It owns the SCM artifacts it spans - which are separate Issue and MergeRequest CRs, listed in status.issueRefs and status.mrRefs - and it outlives every pod that ever runs for it.

apiVersion: tatara.dev/v1alpha1
kind: Task

Two enums on this CR are easy to confuse, and the whole model hangs on the difference between them.

spec.kind is the ORIGIN. It is immutable and baked into the Task's name.

status.agentKind is the AGENT THAT IS RUNNING RIGHT NOW. It changes as the Task moves through its states. Seven values.

clarify is gone, platform-wide, as of the #521 lifecycle redesign - both as an agent kind and as an origin: spec.kind: implement is its direct replacement in MintIssueTask (SweepIssueKind = "implement"), the same function that mints a Task from any new issue, whether webhook-delivered or sweep-discovered. Its three decisions folded into action values on the implement outcome (see Approval Gates), so the pod that judges approval is the same pod that goes on to write the code, and the origin kind that starts that conversation is implement itself.

Eight spec.kind values now, not six. takeover is the pre-existing maintainer-gated MR hand-over path, unrelated to the #521 rename. upgrade (2026-08-13) is the newest addition - a scheduled, opt-in, disabled-by-default agent that takes one dependency-upgrade unit per Task; like documentation, it mints straight into under-implementation because its submitted/declined outcome schema has no approval gate to drive at refined. See Upgrade.

The Task's name is <project>-<kind>-<YYYY-MM-DD>-<uid5>, capped at 49 characters. Its pod's name is computed independently - see Pod naming for both formats, and for why 49.

Progress lives in exactly one field, status.state, and it has eight members - down from the pre-redesign machine's fifteen status.stage members, with parking and pod-liveness split out into their own orthogonal properties. The transition table, the three clocks that bound every state, the cycle caps and the closed set of reasons are all on their own page: the Task state machine.

Continuation state lives in exactly one field, status.notes, and it is an append-only journal: Task notes.

TaskSpec¶

type TaskSpec struct {
    ProjectRef string `json:"projectRef"`
    // RepositoryRef is the PRIMARY repo, set ONLY on documentation Tasks.
    // +optional
    RepositoryRef string `json:"repositoryRef,omitempty"`
    // +kubebuilder:validation:MaxLength=16384
    Goal string `json:"goal"`
    // Kind is the ORIGIN. Immutable, baked into the name. NOT the running agent
    // kind (that is Status.AgentKind).
    // +kubebuilder:validation:Enum=brainstorm;incident;implement;refine;review;documentation;takeover;upgrade
    Kind string `json:"kind,omitempty"`
    // +optional
    // +kubebuilder:validation:MaxItems=20
    MergeOrder []string `json:"mergeOrder,omitempty"`
    // +optional
    // +kubebuilder:validation:MaxItems=50
    AlertRules []string `json:"alertRules,omitempty"`
    // +optional
    DedupKey string `json:"dedupKey,omitempty"`
    // +optional
    // +kubebuilder:validation:MaxItems=100
    DocumentsTasks []string `json:"documentsTasks,omitempty"`
    // +optional
    MaxTurnsPerTask int `json:"maxTurnsPerTask,omitempty"`
}

The old single spec.maxTurns is gone, split into maxTurnsPerPod / maxTurnsPerTask (the split survives on the schema), and both of those - along with maxReviewRounds and maxPodRecreations - are now deprecated with zero enforcement. A turn or round count measures how much an agent has done, not whether it is stuck; see Project.spec.agent for what replaced them (probe-based stall detection and a hardcoded 24h residency cap).

TaskStatus¶

The five cycle-cap counters above are the Task-side half of the story. The sixth, reviewRounds, lives on the MergeRequest - see cycle caps for all six in one table.

!!! warning "There is no deployDeadline, no mergeWaitDeadline, no reviewResolveDeadline" The per-edge deadline family is gone, generalised into stateEnteredAt plus the three-clock model. Three clocks - admission, readiness, work/idle - are armed by which timestamps are set, and every state carries a budget. There is no per-edge deadline field left to forget on a new edge. See the deadline invariant.

Note¶

type Note struct {
    At    metav1.Time `json:"at"`
    // Agent is the WRITER. The REST layer stamps it from Status.AgentKind; an
    // agent can NEVER produce "operator".
    // +kubebuilder:validation:Enum=brainstorm;incident;clarify;refine;review;documentation;implement;operator;upgrade
    Agent string `json:"agent"`
    // +kubebuilder:validation:Enum=note;plan;handoff
    Kind string `json:"kind"`
    // +kubebuilder:validation:MaxLength=4096
    Body string `json:"body"`
}

Full semantics on Task notes.

TaskEvent¶

type TaskEvent struct {
    At metav1.Time `json:"at"`
    // +kubebuilder:validation:Enum=issue_comment;mr_comment;mr_review;label;alert
    Kind   string `json:"kind"`
    Repo   string `json:"repo"`   // Repository CR name
    Number int    `json:"number"` // 0 for kind=alert
    Author string `json:"author"`
    // +kubebuilder:validation:MaxLength=4096
    Body string `json:"body"`
}

TaskStats¶

type TaskStats struct {
    TokensInput         int64    `json:"tokensInput,omitempty"`
    TokensOutput        int64    `json:"tokensOutput,omitempty"`
    TokensCacheRead     int64    `json:"tokensCacheRead,omitempty"`
    TokensCacheCreation int64    `json:"tokensCacheCreation,omitempty"`
    Turns               int      `json:"turns,omitempty"`
    PodRuns             int      `json:"podRuns,omitempty"`
    WallSeconds         int64    `json:"wallSeconds,omitempty"`
    AgentsRun           []string `json:"agentsRun,omitempty"`
    IssueCount          int      `json:"issueCount,omitempty"`
    MRCount             int      `json:"mrCount,omitempty"`
    PodRecreations      int      `json:"podRecreations,omitempty"`
    NotesSpilled        int      `json:"notesSpilled,omitempty"`
    NotesSpilledRefs    []string `json:"notesSpilledRefs,omitempty"`
    AgentStops          int      `json:"agentStops,omitempty"`
}

Print columns¶

kubectl get task shows: State (.status.state), Park (.status.parkReason), Agent (.status.agentKind), Kind (.spec.kind), Project (priority 1), Turns (.status.stats.turns), Description, plus kubectl's own default Age.

State and Kind next to each other is the fastest way to see the thing people get wrong: a Task named ...-refine-... sitting at state=under-implementation with agentKind=implement is not an anomaly. It is the normal path - state is kind-agnostic, and Park being non-empty is what actually means the Task is stalled, not any particular state value.

The etcd object budget¶

A Task is a hot object with unbounded-ish lists on it, and an object that grows past the API server's ceiling becomes permanently unwritable. That is the worst failure mode in the design - every writer fails, and the Task's Issues stay pinned open by ownership forever - so it is foreclosed before it can happen.

Every write is sized before it is issued. fitForWrite marshals the object and evicts oldest comments and oldest notes until it is under 800,000 bytes - half the ~1.5 MiB etcd ceiling.

The headroom is not timidity. metadata.managedFields grows unboundedly under repeated server-side-apply patches on a hot object and is counted against the same limit, so half the ceiling is reserved for the part of the object the operator does not control.

The eviction itself is ordered: the spill to tatara-memory happens once, outside the retry closure, and a note or comment is dropped only on spill success. Nothing is ever dropped into a hole. The in-cluster trim that follows is pure and in-memory, so it is safe to re-run on a conflict.

When the guard cannot win - the object exceeds the budget with nothing left to evict - the Task parks loudly at parkReason=object-too-large, written through a minimal status patch (MinimalFailPatch) that touches only status.parkReason / status.parkedAt, carries none of the oversized lists, and therefore cannot itself 413. This is uniform across every state now - there is no separate failed terminal for pod-less states to route to instead. object-too-large is UnparkNever: it has no re-entry and ages out at ParkRetention like any other terminal park. A note write is never rejected on a count cap (an agent must always be able to write its handoff), and a Task that genuinely cannot fit dies with a recorded reason instead of becoming a silently unwritable zombie.

Mid-flight events¶

status.pendingEvents is how new SCM activity reaches an agent that is already running. Events are delivered at the turn boundary - never mid-turn - and render ahead of the context bundle, so the agent reads the delta first and the refreshed baseline second. If no pod is running, one spawns and they ride in turn 0.

The list is capped at 20, drop-oldest, in Go, before the write. MaxItems=25 is a backstop only: an API-server 422 is not retried by RetryOnConflict and would hot-loop webhook redelivery.

It is cleared by set-difference inside the retry closure, keyed on (kind, repo, number, at), and never by nil-assign - a webhook arriving between render and clear must not be silently dropped - and only after the wrapper has accepted the submit.

Removed fields¶

Everything below was on the pre-redesign Task and is gone. If you have automation, dashboards or jsonpath queries reading any of it, this table is the migration.

The #521 rename: stage (15 members) became state (8) plus parkReason¶

A second redesign, independent of the migration above, replaced status.stage and its fifteen members with three orthogonal properties. This is not a removal in the same sense as the table above - it is a field rename plus a decomposition, and it is recent enough that dashboards and jsonpath built against the first redesign's stage field need this table too:

Note.Agent's enum still lists clarify as a valid historical value (notes already in etcd say clarify) even though nothing can write it any more - removing an already-used enum value breaks CRD ratcheting on every Task that still carries one. See the note on AgentKindFor having no clarify case above.

spec.dedupKey is kept. Five of the six old dedup mechanisms fold into the (repo, number) natural key of the Issue and MergeRequest CRs and are genuinely deleted. The sixth does not: dedupKey is the incident alert-group hash, and a firing alert arrives from Grafana with no issue and no PR to key on. There is no natural key for it to fold into.

The internal/harness REST endpoints are also deleted. QueuedEvent is not deleted.

Example¶

apiVersion: tatara.dev/v1alpha1
kind: Task
metadata:
  name: tatara-incident-2026-07-12-m4z8q
  namespace: tatara
spec:
  projectRef: tatara
  kind: incident
  goal: |
    Resolve tatara-operator#291: the reaper deletes a Task whose pod is
    mid-turn. Confirm scope with the maintainer, then implement.
  mergeOrder:
    - tatara-operator
    - tatara-cli

mergeOrder is set here because this stream is expected to touch two repos and the operator merges them in that order, one at a time, each on green CI.

Inspecting a Task¶

# Every Task on a project, with State / Park / Agent / Kind / Turns
kubectl -n tatara get task -l tatara.dev/project=tatara

# Why is it parked?
kubectl -n tatara get task tatara-incident-2026-07-12-m4z8q \
  -o jsonpath='{.status.state}{" "}{.status.parkReason}{"\n"}'

# The journal - this is the continuation state, and the first thing to read
kubectl -n tatara get task tatara-incident-2026-07-12-m4z8q \
  -o jsonpath='{.status.notes}' | jq -r '.[] | "\(.at) \(.agent)/\(.kind): \(.body)"'

# What it owns
kubectl -n tatara get task tatara-incident-2026-07-12-m4z8q \
  -o jsonpath='{.status.issueRefs}{"\n"}{.status.mrRefs}{"\n"}'

# Stream the current pod's logs
kubectl -n tatara logs \
  "$(kubectl -n tatara get task tatara-incident-2026-07-12-m4z8q \
      -o jsonpath='{.status.podName}')" \
  -c tatara-claude-code-wrapper -f

See also¶

• The Task state machine - the eight states, parkReason, liveness, the transition table, the three clocks
• Task notes - the journal
• Issue and MergeRequest - the SCM mirrors a Task owns
• Project - the levers: maxConcurrentAgents, maxOpenTasks, modelByKind
• QueuedEvent - the admission unit
• MCP tools - submit_outcome, task_note, task_context