---
title: Task Lifecycle
modified: 2026-06-03
tags:
  - explanation
  - tasks
---

# Task Lifecycle

How a committed task moves through heph — and the one idea that makes the whole
thing click: a task has **two independent axes**, not one status field.

> Scope: this is about **committed tasks** (the things that appear in "what is
> next"). Ephemeral **context items** (the `- [ ]` checklist lines inside a
> task's context doc) are a separate concept — see [[design]] §6.3.

## The two axes

| Axis | Values | Question it answers |
|---|---|---|
| **Lifecycle state** | `outstanding` → `done` / `dropped` | Is this still a live thing? |
| **Attention** | `white` · `orange` · `red` · **`blue`** | How much should it be on my mind *right now*? |

They are orthogonal. Attention only means anything **while a task is
outstanding** — a `done` task has no useful attention. This separation is what
keeps the system honest (see [[design]] §6.2): you decide *whether* you're still
doing something separately from *how loud* it should be.

### Lifecycle state

- **`outstanding`** — a live commitment. Every task starts here. Only
  outstanding tasks appear in the agenda (the §8.2 views, project views, "what
  is next").
- **`done`** — you did it. Terminal. For a **recurring** task, completing rolls
  it *forward* to its next occurrence with a fresh checklist (it reappears as a
  new outstanding instance — see [[design]] §3.3 and [[v1-prototype-tech-spec]] §4.4), rather
  than ending.
- **`dropped`** — you've decided **not** to do it ("let it go"). Terminal, and
  the sibling of `done`: "didn't do" vs "did". The distinction from `done` is
  kept on purpose. Dropping a recurring task ends it — it does **not** roll
  forward (only `done` rolls forward).

Both `done` and `dropped` are "not outstanding", so both leave every agenda
surface — but they remain in the store as a record.

### Attention (only while outstanding)

The colors, thought of as feeling, not number ([[design]] §6.2):

- **white** — doable once its do-date arrives (the default).
- **orange** — top of mind (keep ≤ ~6, reconfirm daily).
- **red** — top of mind **and a consequence exists if it's late** (consequence,
  not importance).
- **blue — On Deck** — a backlog item, deliberately cooled. **Still
  outstanding** — a real, live task you intend to do *later*. Blue is the
  pressure-relief valve that keeps the active set light.

The common trap is conflating **blue (On Deck)** with **dropped**. They are not
the same: blue = "later", dropped = "not at all". The §6.2 *blue keep/drop
review* is precisely the act of looking at your On Deck pile and, for each item,
either keeping it blue ("later") or **dropping** it ("let go").

## Delete (tombstone) — a third thing, below the lifecycle

`dropped` still leaves a record. **Tombstoning** (delete) goes further: it marks
the task node `tombstoned` and removes it from *everything* — the agenda,
full-text search, and export. It is a **soft delete** (the row is retained with
a flag, recoverable at the database level, and CRDT-safe — heph never hard-deletes,
see [[v1-prototype-tech-spec]] §12), but for all practical purposes the task is gone.

Deleting a task tombstones **only the task node** — its canonical-context doc
(your notes/checklist for it) is **kept**, so deleting a task doesn't throw away
the writing attached to it.

## Where each task shows up

This is the practical payoff of the model — what's visible where:

| | outstanding (incl. blue / On Deck) | dropped | tombstoned (deleted) |
|---|---|---|---|
| Agenda views (`next` / `list` / `view` / project) | ✅ shown | ❌ gone | ❌ gone |
| Full-text search (`/`) | ✅ | ✅ still findable | ❌ gone |
| Export / raw store | ✅ | ✅ retained | ❌ (flagged deleted) |

A `dropped` task is gone from **all** agendas (including project views) but
stays findable in search — so "let go" is recoverable if you change your mind,
without cluttering your working set.

## How you move a task between states

The model is surface-agnostic; the gestures differ per surface. In the TUI
([[v1-prototype-tech-spec]] §8.1):

| Gesture | Effect |
|---|---|
| `a` | capture a new task → `outstanding` |
| `A` | cycle attention (white → orange → red → blue) |
| `b` | push to **blue / On Deck** (still outstanding) |
| `x` | **done** (a recurring task rolls forward) |
| `s` | **skip** a recurring task to its next occurrence (no completion logged) |
| `d` | **drop** (terminal "let go") |
| `D` | **delete / tombstone** (with confirmation) |

The CLI mirrors these (`heph done` / `drop` / `skip` / `attention` /
`node rm`), and a context item can be **promoted** into a brand-new outstanding
committed task ([[design]] §6.3).

## Related

- [[design]] §6.2 (the lived priority discipline), §6.3 (commitments vs context items)
- [[v1-prototype-tech-spec]] §4.3 (task semantics), §7 (ranking), §8.1 (the TUI), §12 (tombstones)