# Worklist (/docs/app/worklist)

> Study: a study of the work. Defines nothing. No package exists.

> App study: where any Worker, human or agent, inside or outside the Business, takes the Tasks routed to it and closes each with evidence.



A Worklist is the App where a Worker acts on the Tasks routed to it. The Worker is a human or an agent, the Business's own or outside supply. The work is digital, such as approving a refund or attesting a filing, or physical, such as picking a pallet or checking in to a shift.

Every Task closes with declared evidence, never a checkbox. The Task is one record in every case, so an approval desk, a frontline scanner, a credentialed review queue and a closer's console are deployments of one type.

worklists.app, in design, is its deepest instance and worklists.dev, in design, the work layer's API. The gigs.lawyer Signer app and the closers.deals console, both in design, are two more. The type merges two earlier studies, the HITL inbox and the worker app. The study describes the work; how an App is defined is open, see [What every App needs](https://next.mdxui.dev/docs/app/every-app).

## Why one type

The five questions give one answer. The side is a Worker acting on Tasks routed to it, the unit is a Task, and the ball is the current filler of the Role. Authority is exactly the authority for this act.

Two answers differ: whether the act is paid, and what settles it. Both are declared axes of one deployment, the way startupbuilder.dev rules one Task grammar for every Worker.

The same reserved act can route to the firm's own lawyers or to an eligible outside pool by configuration. The boundary was never the side.

| Axis | Values |
| --- | --- |
| Relation to the Business | Its own Role (founder, approver, officer, employee); matched supply (contractor, credentialed professional); a principal's own staff working its reserved decisions |
| Register, what settles it | **authority**: approve or refuse; **attest**: sign, send back or decline, and a decline is final; **propose**: the Worker proposes and a Gate commits; **capture**: a scan or an attested event; **presence**: check-in at a Site in a Time Window, then completion evidence; **do**: a finished task with its artifact |
| Regime | mandated, worker-held, contractor, credentialed contractor, agent; fixed when the deployment is built |
| Pay basis and unit | none; per act, posted before claim; commission at outcome over a span; a shift spread |
| Arrival | pull from a pool; a pushed offer; assignment; a scheduled shift; dispatch from a step, a document or an exception |
| Device | rugged handheld, phone, desk, headless |
| Grain | seconds for a pick, days for a matter on a deadline ladder |

The [delivery and dispatch console](https://next.mdxui.dev/docs/app/delivery-console) stays a separate type over the same Tasks. The Worklist answers "what needs me". The console answers "is the work flowing, where is the ball, what is at risk", and no supervisor view enters this App.

## Actors

| Actor | Relation | Register | Work |
| --- | --- | --- | --- |
| Founder or owner | Own Role, often the only human | authority, do | Approves spend, answers an agent, fixes what broke; the root of every escalation |
| Approver, warrantor, second approver | Own Role | authority | Settles over-Limit asks; lists and revokes standing authority; differs from the initiator |
| Officer, credentialed signer | Own Role | attest | Performs an act the law reserves to a person |
| Support operator | Own Role | authority | Approves an agent-drafted reply before it is sent |
| Frontline employee | Own Role, mandated | capture | Closes a pick by scanning; records a short delivery |
| Worker-held member | Outside any employer | capture | Keeps a dated record no employer reads |
| Credentialed contractor | Matched supply | attest | Signs a filing, decides coverage, verifies income; may decline |
| Span performer | Supply or the Business's agent | propose | Works one Role's span of a Deal and proposes each advance |
| Shift worker, field attestor | Matched supply | presence, attest | Shows up at a Site; audits a lot; notarizes in person |
| Agent performer | Seated in a Role, or ordered | any register not reserved | Drains the same queue through the same Verbs and evidence |

Agents also raise asks, draft what a human signs, dispatch and match, run the Gate and the clock, check evidence and accrue payouts. An agent holding a Role answers Approvals addressed to it under the Role's Policy, and never approves its own ask.

Parties who never sign in here reach the same Tasks from other types. The operator works from the console and [Admin](https://next.mdxui.dev/docs/app/admin), and a requester from the [party portal](https://next.mdxui.dev/docs/app/service-portal). A firm or union steward holds grants, not accounts.

## Interfaces

| Reader | Screens | Renderings |
| --- | --- | --- |
| Every Worker | Mine; Pool as teasers; Waiting on others, each with its pending reason; Done or "Your record"; the item with its register's panel; receipt; a private block; ask a Role, never a person; settings with "Your data" | Push as a count only; email digests and signed links; Markdown and JSON of the same reading |
| Authority register | The ask, the Policy that raised it and where it is set, the chain of authority, the prior decision of its kind, what happens after the answer; standing authority with a revoke on every row; learning exits | Slack or Teams items pressed only from a linked account; one-tap only for a single action with no input, by opt-in |
| Attest register | Disclosure sheet before claim, recorded when viewed; clearance; the packet; attest, send back with defects, decline with a memo | A teaser push with no party names |
| Capture and presence | Scan sheet with outcomes settled, which one, recorded; check-in with site confirmation; completion photos; a deadline ladder acknowledgment | Widgets, Controls and hardware scanners; ICS for shifts |
| Duties, money, standing | Earnings by outcome, cash out, tax documents, Credentials with expiry, holds, suspension with an appeal | |
| Agent performer | none | API, MCP and CLI: next, claim, complete with evidence, return, escalate; a reserved Verb absent with a typed refusal |

Each authority item keeps the deterministic Action (Verb, object, amount, destination) apart from the agent's note.

## Records and actions

Two lifecycles run side by side. The waiting Action is the Business's work, and the requester reads a projection of it. The Task is the wait on a Worker, and its states are about attention.

| Record | States |
| --- | --- |
| Task | pending (awaiting a Worker), held under a lease, in progress, blocked privately, escalated, timed out (not terminal), settled with an outcome, canceled; no reopen, no edit |
| Settle outcome | approved, refused with a cause, attested, sent back, declined, captured, verified, accepted |
| Waiting Action | pending with one reason (awaiting a Worker, input, a source, an Action or time), then done, refused, canceled or failed |
| Lease | granted, renewed, released, expired, converted on settle |
| Standing authority | minted only from an answered ask; active, expired, revoked |
| Credential | verified with expiry, expiring, lapsed, suspended |
| Register | built only from settled outcomes, owned by the performer; exists only where the regime allows |
| Autonomy of a step | assist, supervised, full; promoted on evidence, demoted automatically |

One settle contract closes every register. The evidence matches the Task's declared type or the close is refused. The external effect runs first, the first valid answer wins, and "already settled" is a receipt.

The settle binds to exactly what was shown. A refusal renders verbatim and keeps the claim, and a draft is never an answer.

Refusals name what refills them. A throttle returns 429 with a retry time, a paid management Verb 402 with a checkout cure, and a reserved act 403 with a claim or Approval link.

The performer's own Verbs are never priced: complete, block, escalate, query and trace. Dispatch, assign, unassign and start are the management of work, and that is what an operator pays for.

### Terms

| Term | In startupbuilder.dev | Definition, quoted from [startupbuilder.dev](https://startupbuilder.dev) or the gap |
| --- | --- | --- |
| Worker | [Worker](https://startupbuilder.dev/business/nouns/worker) | "A Worker is a Human or an Agent that fills a Role and acts on Tasks." |
| Task | [Task](https://startupbuilder.dev/business/nouns/task) | "A Task is an Action waiting on a Worker, with an assignee, a due time, and a place in that Worker's inbox." One Noun for an inbox item, a step run and a worklist task. |
| Approval | [Approval](https://startupbuilder.dev/business/nouns/approval) | "An Approval is a Task to allow or refuse one pending Action that exceeds a Limit or a Mandate." |
| Attestation | [Attestation](https://startupbuilder.dev/business/nouns/attestation) | "An Attestation is the signed, frozen act by which a credentialed Worker performs or declines a Reserved Act." Three senses in use: a signed act, an attested capture, a statement of fact. |
| Reserved Act | [Reserved Act](https://startupbuilder.dev/business/nouns/reserved-act) | "A Reserved Act is a Verb the law reserves to the holder of a named Credential, so its Function is always human." |
| Supplier | [Supplier](https://startupbuilder.dev/business/nouns/supplier) | "A Supplier is a Person or Company that delivers work through a Startup's human supply: recruited, credentialed, and paid out." Read for any Business. |
| Worklist | lacks | startupbuilder.dev calls a Worker's open Tasks its worklist, a generated view, not a core Noun. Also a brand and a Startup. |
| Pool, lease, envelope, packet, Gate, Proposal, regime, Site, Time Window | lack | |
| Register | collides | A performer's record, a mode of work, and a holding register. |
| Declared evidence | collides | startupbuilder.dev's Evidence is a customer-discovery record. |
| Watcher, Supervisor | collide | startupbuilder.dev's Supervisor lists Watcher as a word to avoid; its delay windows name Watchers. |

## Workflows

1. **The founder's authority loop.** Guards, Evaluators, the Role's agent and standing Mandates settle what they can. What remains reaches the founder on the phone, in Slack or over MCP, and the answer runs the work on. "Stop asking me under $100" edits the Policy, with Undo.
2. **Credentialed attestation.** A gig posts with a flat fee and a teaser. The disclosure sheet, recorded when viewed, leads to pass or claim, eligibility, clearance, the packet, then attest, send back or decline. The fee is credited on all three.
3. **Propose under a Gate.** A closer proposes a stage advance; the Gate holding the seller's bounds commits or refuses, and the refusal reaches the closer verbatim.
4. **Frontline capture.** A scan emits first with its document frozen. One match completes with the event's hash, several ask "Which one?", none records the scan anyway.
5. **Dispatched presence.** A shift posts, is claimed and dispatched; check-in needs a geofence and site confirmation. A silent site past its timeout verifies the shift, because silence never withholds pay.
6. **One job across two registers.** A field visit and the coverage decision are two linked Tasks, optionally bound to one Worker. Neither payment releases on the other's fact.

A deterministic commodity act, such as service of process, goes to a vendor rail instead of a Task, and the wait is on the vendor's record.

## Boundaries

What may be measured depends on who did the work and for whom.

| Subject | The Worker sees | The operator or employer sees |
| --- | --- | --- |
| Employee, mandated regime | Own counts and timestamps, never a rate or rank | Work reached from work, by Site and window; never a person's history |
| Worker-held member | Own dated record | Nothing |
| Independent or credentialed contractor | Own Register and earnings | Never; the Register routes work and sets standing inside the market, and no score crosses eligibility |
| Agent | The same figures as Markdown | Everything, except a rate on a key a named human deputized |
| A Business's own approver or officer | Own items | Unsettled |

- No roster, no online-now, no two performers side by side; another performer's block is absent, not withheld.
- The regime is a build-time constant, because a regime set by configuration turns a guarantee back into a promise.
- One Worklist per tenant. A founder's stream across Startups is a union of separately authorized reads, and each settle routes back to its tenant.
- A field the reader may not see renders as withheld, which differs from absent.

## Agents

Agents act upstream so a Task never reaches a person, and inside it: they prepare packets, draft replies, rank fixes, check photos and geofences. An agent performer drains the same queue with the same evidence; reserved Verbs are absent to it.

Humans stay on reserved acts, a credentialed refusal, first-of-kind authority and minting standing authority. They also keep signing, four-eyes money moves and approving a drafted outbound message where the mode says so. Deactivation and suspension need a human decision.

## Hard parts

1. **The authority register succeeds by shrinking.** Every item needs an exit to "never ask again", or the queue grows with agent count.
2. **Rubber-stamping.** One tap only without input; approve and refuse never adjacent targets of one size; the prior decision shown.
3. **Five recorded contradictions.** Per-person numbers, the founder's cross-Startup stream, settle without a holder check, two offline models, and whether a robot is an actor or an embodied agent.
4. **Silence differs by kind.** An Approval cancels, a delay window proceeds, an ask stays open one rung up, and a statute allows no extension. The screen says which.
5. **Push content.** A count-only push is the floor; content and one-tap are an opt-in for authority items, never for attestations.
6. **Classification.** Push assignment, schedules and rankings direct work and read as employment. Pull first and no rates is a legal posture as well as an ethical one.
7. **Physical work beyond a Site.** Travel between Sites, route order, parts consumed and custody of carried goods have no design.
8. **Hostile conditions.** Gloves, freezers, sunlight and no shared language: the close needs no reading, and a shared handheld purges on sign-out.

## Day one

For a founder alone with agents, the first Worklist is the founder's authority worklist across one Startup. It exists the moment a Service with a human step is defined. Day one holds:

- next, claim, complete with evidence, return and approve or refuse, on the API, MCP and CLI;
- one shell with For you, Waiting on others and Done, and one count;
- approval, question and broken kinds, plus review-and-sign where a human finish is sold;
- the settle contract, the pending reasons and the refusal classes, which are breaking changes later;
- a silence default stated per kind, and one reminder;
- email with signed links, count-only push, Slack only from a linked account;
- "Remember this", "Stop asking me under $X" and approve-and-stand;
- the non-view list: no rate, no roster, no person-to-history query;
- an installable web app on the Business's own Domain.

| Trigger | Turns on |
| --- | --- |
| A second human | Routing by approval chain and amount, reassign and take over, escalation ladders, a backup approver |
| First outside supply | The envelope with a posted price, staged disclosure, leases, payouts, the Register where allowed |
| First reserved act | Eligibility, clearance, the packet, Attestation over a frozen hash, a paid decline, the deadline ladder |
| First physical work | Capture or presence, offline capture per Verb, Show-up Minimum, backfill |
| A frontline employer | A native build from the operator's own store account, hardware triggers, shared devices |
| Studio scale | The officer desk across held Companies, cross-entity confidentiality |

A frontline build compiles without the approvals mode. In an Autonomous or Single-human Startup, the founder's operator App is mostly this Worklist, so it comes before a full [Admin](https://next.mdxui.dev/docs/app/admin).

## Related studies

## Prototypes this study needs