---
title: "OKR — structure and lifecycle"
description: "The Objective/Key Result structure, the check-in contract, the draft/active/closed/cancelled lifecycle, owner, and links to Concept/Entity. The canonical contract to read before an agent registers, updates, or checks in an OKR."
---

# OKR — structure and lifecycle

Of the three layers shown in `company.md`, this page covers OKR's internal model. The OKR Registry is the canonical record of the outcomes a team wants to realize. An Objective is the change being aimed for, a Key Result is a measurement contract, and a check-in is a record of the value and confidence observed at that point in time. Project/Session is the work that realizes an outcome, Concept is the decision criteria that give an OKR its meaning, and Company Entity is a separate company-structure entity — neither is a substitute for OKR.

## Structure

- **Objective**: title + description
- **Key Result**: **2 to 5 required.** Each has a title, description, metric (what is measured), unit, baseline_value (the value at the start), and target_value (the goal value). **baseline and target cannot be the same value**
- **Period**: `starts_on` < `ends_on`
- Numeric values (baseline_value / target_value / a check-in's current_value) are sent and received as lossless decimal strings; docs and agents never auto-compute a percentage or achievement rate from them

## Lifecycle

`draft` → `active` → `closed` / `cancelled`, one direction only.

| status | Meaning / constraint |
|---|---|
| `draft` | The Objective, period, and KRs can be registered and changed |
| `active` | **KR definitions are frozen once activated.** Activation requires an owner to be set and an initial check-in |
| `closed` | The final check-in and a retrospective are saved together in a single operation to close it out |
| `cancelled` | Closed out with a required reason |

**A terminal state (closed / cancelled) is immutable and cannot be deleted.** If the measurement contract itself turns out to be wrong, cancel the existing OKR and register a new one with the correct KRs.

## The check-in contract

A check-in **submits the current value for every KR at once**, every time. KRs that haven't changed are not omitted either.

- `current_value`: the value observed at that point in time (a decimal string). Never fabricate a value when the real measurement can't be obtained
- `confidence`: an **integer from 0 to 10** per KR. Never aggregated into a single score for the whole OKR
- `summary` is the headline of that check-in. Reasons confidence dropped, blockers, uncertainty, and what to verify next go in `description`
- Check-ins are append-only records; the initial check-in at activation, a regular check-in, and the final check-in at close all use the same complete-snapshot contract
- Optimistic concurrency applies: pass the `updated_at` you last read, and if it conflicts with another change, re-read the latest state before resubmitting

## Owner model

An OKR has at most one owner. **A draft can be registered without an owner — an owner becomes required only at activation.** The owner does not have to be human: an eligible, non-dormant agent participating in an active Project or DM in the team can be an owner too. Candidates are chosen from `owner_candidates`.

## Links to Concept / Entity

An OKR can link to both Concepts and Entities. There is no relation type — it's a simple link that either exists or doesn't.

- A Concept link: used when that decision criterion or strategy is needed to understand what the OKR means
- An Entity link: used to show which part of the company structure the outcome targets
- **Links cannot be changed once the OKR reaches a terminal state (closed / cancelled)**

## Change history

An OKR's lifecycle and definition changes are recorded as append-only events (registration, definition update, activation, owner change, Concept/Entity link added/removed, check-in created, close, cancel).

## Related pages

- The three-layer overview and how to ask: `company.md`
- Concept's types and lifecycle: `concept-registry.md`
- Entity's types and lifecycle: `company.md`
- Terms: `glossary.md`