Work Items

A work item is one task. It is the only task object in NEXUS: an item handed to an agent is not a copy filed in a parallel table, it is this row with its delegation fields filled in (see Delegation).

An item carries a title, optional body text, an optional priority, a status, an optional parent, a schedule, and an ordering rank. Delegation adds four more fields, all optional and all absent on an item a person created — "call the plumber" owes no acceptance command, no evidence, no owned-file list and no tool request, and is a completely valid item.

Schedule is a range, not a due date

There is no "due date" field. An item's schedule is an interval built from four values plus an all-day flag:

Value	Meaning
Start date	The day the item begins.
Start time	The time of day it begins, when it is not all-day.
End date	The last day it occupies. For an all-day item this end is inclusive.
End time	The time of day it ends, when it is not all-day.
All-day	Whether the item occupies whole days rather than a time span.

The four legal states

Only these four shapes are accepted. Anything else is refused with the reason named.

State	What is set	Notes
Unscheduled	No start date. Every other schedule value empty; all-day is true.	The item has no place on a calendar and waits in the Unscheduled drawer.
All-day, one day	Start date only, no times.	Its end is implicitly the same day.
All-day span	Start date and end date, no times.	The end date is inclusive and may not fall before the start.
Timed	Start date, start time, end date and end time — all four.	The end instant may not fall before the start instant. It may cross midnight.

The refusals are specific rather than a generic "invalid date": an unscheduled item that carries a leftover time, an all-day item carrying times, a timed item missing one of its four values, and an end before its start are each reported as themselves.

Two rules worth knowing

• Clearing the start clears everything. Removing the start date empties the start time, the end date and the end time and restores the all-day default, so a partially cleared schedule cannot be left behind.
• Rescheduling carries the end along. Moving an item's start date moves an existing end date by the same number of calendar days, and never lets the end land before the new start. A three-day block dragged forward stays three days long.

Priority

Priority is one of p1, p2, p3, p4, or absent. p1 is the highest, and the ordering is deliberately ascending so that sorting by priority puts critical work first. An item with no priority is not low priority — it is unprioritised, which is a distinct state the Matrix shows as its own lane.

Priority is a judgement the person makes. Nothing derives it from dates, and no date raises it: an item scheduled for tomorrow is not "urgent" anywhere in this build unless you said so.

Values the build does not recognise are read and preserved rather than rejected, so a row written by a newer version stays readable.

Status lifecycle

Status	Meaning
pending	Open work.
completed	Done. Completion stamps a timestamp the first time it happens; moving the item back out of completed clears it.
skipped	Closed without being done.
failed	Closed, unsuccessfully.
archived	Filed away, closed.
deleted	Soft-deleted. Not settable as a status.

Two distinctions the surfaces rely on:

• Closed is not completed. failed, skipped and archived all close an item, but only a genuine completed satisfies a dependency. A failed upstream item never unblocks the work waiting on it.
• Deleting is a separate verb. Deletion soft-deletes the item, stamps the time, and cascades to every descendant beneath it; deleted rows disappear from every read. A separate purge removes long-deleted rows permanently. The local work_* tools expose no destructive verb at all — work_item_set_status accepts pending, completed, skipped, failed and archived, and an agent that wants an item out of the way archives it.

Batch moves are one operation: a selection is validated in full first and committed once, so a batch either happened or did not, and a selection containing one item that cannot be completed is refused whole rather than half-applied.

Hierarchy

An item may name a parent, forming sub-items.

• An item cannot be its own parent, and a parent chain may not contain a cycle.
• A parent chain may be at most ten edges deep.
• Deleting a parent deletes its descendants with it. The confirmation counts them, so what you are told matches what happens.

Relations

Beyond parenthood, items can be joined by typed edges: dependency, sequence, parallel, conditional, aiTrigger and reference. An edge can be marked blocking, and carries an optional weight and metadata.

The dependency edges must form an acyclic graph — an edge that would close a cycle is refused and the cycle is named. Dependency edges are what tell a delegated item what it is waiting on, so a board's idea of "blocked" and the task handed to an agent cannot disagree.

What is not here yet: the planning surfaces offer no relation editor, and the work_* tool namespace exposes no relation verb. Relations exist in the model and are enforced by the store; creating them from the UI is not something this build does.

Where to go next

• Boards — how an item gets onto a column, and how ordering works.
• Matrix — what priority and completion mean for the quadrant.
• Calendar — how the four schedule states are drawn.
• Delegation — the optional fields an item gains when it is handed to an agent.