generated from eblume/project-template
Erich Blume
6514296b87
v1 reached Todoist feature-parity, so remaining/future work is now tracked in heph itself — tasks in the Hephaestus project (heph view ondeck) — not in a doc. Renamed docs/reference/tech-spec.md -> v1-prototype-tech-spec.md and rewrote all 27 [[tech-spec]] wiki-links + README/changelog path refs (docs checks green). Retitled + bannered the spec as a historical v1 build record and froze its §14 tracker. AGENTS.md gains a "Planning future work" section (capture via `heph task --project Hephaestus`, triage in heph-tui On Deck); README status reflects parity + the three daily-driver surfaces. The design doc remains the living rationale. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
112 lines
4.9 KiB
Markdown
112 lines
4.9 KiB
Markdown
---
|
|
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)
|