Erich Blume 6514296b87 docs: reframe tech-spec as historical; heph self-hosts its roadmap

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>

2026-06-03 20:19:35 -07:00

4.9 KiB

Raw Blame History

title

modified

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

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)

4.9 KiB Raw Blame History