Docs · Reference

Glossary

Key terms used across Zero docs. Source state, Work mode, and verification status are distinct concepts — this page explains the differences.

Work concepts

Work item: The unit of structured intent in Zero. Describes what needs to be done — a bug, feature, investigation, refactor, greenfield project, or epic. Zero tracks how the Work was done (sessions, proof, memory), not just that it was requested.
Work type: The kind of Work: bug, feature, investigation, refactor, greenfield, or epic. Determines which memory templates and session patterns Zero uses.
Work item state: An internal execution tracking label: OPEN, INVESTIGATING, IMPLEMENTING, VERIFYING, BLOCKED, RESOLVED. State reflects execution progress. It is not the same as the source issue state (open/closed in GitHub) or the session mode (Plan/Work).
Outcome: A classification attached when a Work item resolves. Describes what was learned or delivered — e.g. ConfirmedCodeBug, FeatureShipped, WontFix. Used for regression memory and reporting.

Session: A bounded agent run within a Work item. One session = one plan + one execution attempt. Sessions are typed (planning, implementing, verifying) and always start in Plan mode.
Plan mode: The first phase of every session. The agent reads context and proposes a plan. No execution happens. The operator reviews and decides whether to approve.
Work mode: The second phase of a session. Begins when the operator approves the plan. The agent executes the approved plan and produces a diff. Work mode is unlocked by an explicit operator gate — not automatic.
Approval: The operator action that transitions a session from Plan mode to Work mode. Approval is an execution gate, not a state transition. It does not change the Work item state directly — it authorizes the session to execute.

Proof: Evidence that a session run worked. Attached by the operator after execution: test logs, diffs, operator notes, screenshots. Proof is run-level verification — it documents what the session did and that it worked, not that a tracker state changed.
Proof gate: An operator-controlled requirement that proof must be attached and verified before a Work item can reach RESOLVED. Configured per-plan. Not an automated check — the operator attaches and verifies manually.
Verification status: Whether a proof artifact has been reviewed and marked verified by the operator. Separate from Work item state and session mode. A Work item can be in VERIFYING state with unverified proof — the operator must explicitly verify before resolving.

Source system: An external system where Work originates: GitHub Issues, Jira, Linear, or manual entry. Source systems supply Work items to Zero via import. They are input channels — not the execution model. Zero does not continuously sync with sources after import.
Source state: The status of an item in the source system (e.g. GitHub issue open/closed). Source state is not the same as Work item state in Zero. A GitHub issue can be closed while the Zero Work item is still IMPLEMENTING. They are independent.
Source metadata: The data Zero imports from a source issue: title, description, labels, acceptance criteria, linked PRs. Stored in github-context.md (or equivalent) in the Work item's memory. Source metadata informs the Work item context — it does not control session execution.

Compatibility path: An API or event that reflects historical state-machine semantics preserved for integration compatibility. Examples: PUT /cases/:id/state, case_state_changed webhook. Prefer Work-centered flows (session-based approval, session_completed, proof_created) for new integrations.
case_state_changed: A compatibility webhook event that fires when the Work item execution state changes. Useful for dashboards or external sync. Not the primary integration signal — prefer session_completed and proof_created for most integrations.
Provider: The AI execution backend that runs sessions. Current builds use local CLI transport (e.g. claude CLI must be installed locally). Providers are not the execution core — Zero core manages Work state, sessions, memory, and proof independently of the provider used.

NEXT STEP

On this page