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