Tasks and notes

Tasks and notes

Task versus note

A task is actionable work with a status lifecycle: not_started → in_progress → done, with archived and cancelled as terminal resting states. A note is durable long-form content with no actionable state: research, decisions, vendor briefs, handover text. Both live in the same store, both are project-scoped, both keep history.

Create either with create_task_or_note (one call, type selects). Move them with update_task, which applies only the supplied non-empty fields (CLEAR nulls one explicitly).

Everyday flows

• Capture: create with title, project, section (inbox, today, next, someday, waiting), priority, due date. Put substance in description; keep notes for auxiliary or machine-readable metadata.
• Work: query_tasks lists live work (finished content stays out unless asked for, by design), task_digest orients a fresh session, ready_context scores what is actually ready, blocked, or waiting.
• Remember half a title: find_by_title searches tasks, notes, and entities together, ranking live work first.
• Converge, don't duplicate: upsert_note_by_title_project creates-or-updates one note per title per project, so repeated agent runs converge instead of spawning near-duplicates.
• Hand over: assign_task sets a free-form hint plus the caller's identity as shared_by. Assignment grants nothing; it is coordination metadata, and the actor, not the hint, carries authority. Unassigning clears both fields.

Maintenance sweeps

Two tools keep the lists quiet: archive_done_tasks retires old done tasks to archived; bump_overdue_priority raises past-due live tasks to a target priority. Both walk only content visible under the caller's grants, move each item through the audited mutation path, and succeed with zero counts when nothing is in scope. They are operator tools (advanced audience), not everyday reads.

Lifecycle instead of deletion

There is no task/note delete API. Done work archives; abandoned work cancels; both preserve the full trail. Reflection runs retire through their own discard transition. If content must stop participating, move its state, and never expect removal, because removal does not exist.

When to use, when not to

• Use tasks for anything with a doer and a done state; use notes for anything you will re-read.
• Use sections as triage (inbox → today/next/someday), not as archives; archive explicitly.
• Do not encode authority in assignee: it is a hint. Authority lives in grants, roles, and quorum decisions.
• Do not use sweeps as queries: they mutate. Read first with query_tasks, then sweep deliberately.