Skip to main content

Initiative lifecycle & health

Initiatives are the one place in the work plane where a stored status is allowed — because an initiative's stage is a decision, not a measurement. The doctrine that governs everything else is unchanged: derive what the world can tell you; store what only a human can tell you. Task rungs, milestone states, progress and evidence remain derived on every read; the initiative's stage and its asserted health are speech acts, attributed and logged.

The five-state machine​

An initiative moves through a closed machine with six named transitions:

planning ── start ──▶ active ⇄ paused
                        │
                        ├─ complete ─▶ completed ── reopen ─▶ active
                        └─ cancel ──▶ canceled ── restore ─▶ planning
  • Illegal moves teach. An out-of-order transition answers 409 with allowedTransitions — the API tells you the legal next states rather than making you guess.
  • Terminal moves are signatures. Complete, cancel, reopen and restore are human-only — an agent or automation actor gets a typed human_only refusal, enforced in the model and again at the API. The console renders these moves with an explicit confirmation for the same reason.
  • Pausing has teeth. A paused (or canceled) initiative closes the dispatch gate for its member tasks; a human can override, attributed.
  • Transitions are idempotent via clientToken: a retried request replays the original answer instead of double-writing.

The console renders the stage pill as the transition control — clicking it shows exactly the legal moves for the current stage.

Health is the headline of an update​

There is no health dropdown. Health is asserted by posting an update — one honest paragraph plus a headline (on_track / at_risk / off_track), stamped with the author's name. The initiative's health IS the latest update's headline; editing history is preserved.

  • Staleness derives at read. An active initiative whose latest update is older than the staleness window renders · stale beside the chip — old good news is not fresh bad news, so the color never changes; the age does.
  • No update yet renders honestly — the console says "no update yet" instead of inventing a green dot.

Signals nudge, humans assert​

The old derived-health formula still runs — demoted to a signal. When the fold sees trouble (an idle milestone, a drifted approval), it renders a nudge — "the fold suggests at risk — post an update?" — with its named evidence, and pre-fills the update composer. It never overwrites the asserted headline, and it stays quiet while it agrees with a fresh one.

Yours: addressed attention​

GET /work/yours is the personal queue: every reason the plane can derive that something waits on a person — a drifted approval (the signer), an open review (the requested reviewer), an idle milestone (the epic's assignee), a design in review — resolved to a person, a sentence, and the one gesture that clears it. An item that cannot name its person or its action is not emitted: unaddressed attention is noise by definition.

Yours is the only attention renderer in the product — the console's band on the Initiatives home, orun work yours in the CLI, and the work_yours MCP tool all read the same queue, and every chip carries its source badge. The read long-polls (after + waitSeconds) so agents and dashboards can wait for the next decision instead of polling.

Archival is a view concern​

Archiving hides an initiative from the default portfolio; it is not a status and moves nothing in the machine. Completed and canceled initiatives shelve themselves after a window; unarchive restores visibility. The console's Archived facet is the shelf, with the one gesture back.