docs(explanation): add Task Lifecycle — the two-axis model

A new explanation doc making the task model explicit: lifecycle state
(outstanding → done/dropped) is orthogonal to attention (white/orange/red/
blue), attention only matters while outstanding, and On Deck (blue) is a live
"later" task — NOT the same as dropped ("let go", terminal). Covers delete/
tombstone (soft-delete that keeps the context doc) and a table of where each
task shows up (agenda / search / export). Cross-links design §6.2/§6.3 and
tech-spec §4.3/§7/§8.1/§12; wired into the explanation index.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/changelog.d/v1-prototype.doc.md

@@ -1 +1,2 @@
+- Added a [[task-lifecycle]] explanation doc: the **two-axis task model** (lifecycle state — outstanding/done/dropped — kept separate from attention white/orange/red/blue), why **On Deck (blue) is not the same as dropped**, what **delete/tombstone** does (and that it keeps the context doc), and where each task shows up across the agenda, full-text search, and export.
 - Surface strategy revised to a **three-surface model** ([[design]] §4, tech-spec §1/§8), grounded in a study of the owner's live Todoist usage (387 active tasks, 34 hierarchical projects — [[design]] §6.2.1): the **CLI** is task capture/scripting plus the complete daemon API, a planned **`heph-tui`** terminal UI (tech-spec §8.1) is the primary task agenda/triage surface, and **`heph.nvim`** is the primary context/knowledge-base surface. The study also confirms do-date-not-due-date (zero deadlines used), that task descriptions are already full of unresolved `[[wiki-links]]` (the exact task↔KB fusion heph provides), and surfaces new needs (project hierarchy, natural-language recurrence) while showing tags are negligible.

docs/explanation/explanation.md

@@ -11,3 +11,4 @@ tags:
 Background context and design decisions.
 
 - [[design]] — Hephaestus design document: vision, data model, architecture, sync, and roadmap
+- [[task-lifecycle]] — the two-axis task model (lifecycle state × attention), drop vs delete, and where each task shows up

docs/explanation/task-lifecycle.md

@@ -0,0 +1,112 @@
+---
+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 [[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 [[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
+([[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)
+- [[tech-spec]] §4.3 (task semantics), §7 (ranking), §8.1 (the TUI), §12 (tombstones)