Skip to main content
Recurring tasks apply to workspace members with edit access to the task board. Recurrence badges, summaries, and templates are member-only across task responses, realtime events, bulk operations, and mobile. Guests can still complete an ordinary task using their board access. Their completion creates no recurrence evidence or new task.

Schedule and capacity

  • Daily, weekly, monthly, and yearly schedules support intervals from 1 to 99. Weekly rules can select weekdays. Monthly and yearly dates on the 29th through 31st clamp to the last day of shorter months.
  • A task becomes eligible at the start of its local start date, normally 00:00. The start offset defaults to zero. If a civil date is entirely absent, the series is saved and that occurrence is recorded as skipped.
  • A series generates even while earlier instances are open, up to three open tasks. Further dates are recorded as held. Review still counts as open. Tasks in done or closed lists, tasks with completion or closure timestamps, and soft-deleted tasks don’t consume a slot. Archiving alone leaves slots in place.
  • A workspace can have 200 active series, with at most 50 per owner. Pausing releases the active slot. Removing a member pauses that member’s active series.
  • A member completing the latest task in its original board can trigger the next date early. If only overdue dates are eligible, scheduled generation processes the latest and records the earlier dates as skipped. Held and skipped dates are never backfilled.

Dormant rollout

The database starts with request and scheduler generation off and every workspace disabled. The dormant migration adds private storage, gate controls, capacity guards, a read-only probe, and a separate completion evidence entry point for the trusted server. The Tasks request API requires an enabled database workspace gate. The Repeat controls appear once the request API admits a workspace. The native scheduler has a separate rollout step. An operator can enable gates with the restricted database role using the current epoch. The service credential can disable gates using compare-and-set. The scheduler release must prove the database and Worker stop fences together, including bounded assignee notifications and watcher fan-out. Its pilot budget is 160 admissions per 15-minute slot across five batches, at most 32 per workspace, with fair rotation among enabled workspaces. Disabled workspaces must not advance through downtime skips. Request mutations require authorized receipts with a verified expiry of up to seven days. The database rejects expired receipt requests and persists their verified expiry. A list-status update is atomic and fails if more than 500 linked tasks would change open state or any series would exceed three open tasks. A move across boards within one workspace retains the capacity link and cannot drive generation from the destination. A linked row cannot move across workspaces.

Request API

The Tasks API at POST /api/v1/workspaces/{wsId}/tasks/recurrence accepts prepare, create, edit, status, read, and completion operations. Authenticate through the Tasks session wrapper. The server issues workspace- and actor-bound request receipts for authorized lists or tasks. Configure TASK_RECURRENCE_RECEIPT_SECRET with at least 32 UTF-8 bytes before admitting a workspace. Receipt reuse with changed business input returns a conflict. A completion reserves its receipt in the same transaction as the task transition. If generation is interrupted, the same receipt may resume the bounded synchronous request while the evidence is valid. Generated tasks copy up to 50 eligible assignees and generate at most one assignment notification and one ordinary watch per copied assignee. They copy no watchers from prior tasks. The producer keeps the global and workspace gate locks through notification, history, occurrence, and receipt writes. A stopped workspace cannot start another generated task or notification fan-out after its gate change commits. Predictable capacity conflicts on ordinary task reopen or restore return 409.

Scheduler and staging cost evidence

Cron Control owns tasks-recurrence-generation on its existing 15-minute trigger. Production configuration omits the job from the enabled list and sets TASKS_RECURRENCE_MODE=off. Absent, off, and unrecognized modes make zero database calls. Dry-run makes one read-only probe call per tick. Generate runs the native private RPCs with the database service credential. Discovery rotates from the last workspace visited using UUID order. Disabled workspaces are outside the discovery index. At most one series is selected on each visit before moving to the next workspace. Token expiry is the earlier of 180 seconds from admission and the end of its slot. A later slot retires the previous admitted slot’s unsettled tokens. Settled duplicates replay their stored summaries. The Worker checks its durable ledger before each claim and commit. Five consecutive charged runs stop the native job until an operator resumes it. The authenticated hard-stop endpoint stops the ledger first and confirms the database epoch with both write bits disabled. A pending stop returns HTTP 503. Retrying the stop confirms the database fence while the ledger stays stopped. Workspace disable uses the workspace’s compare-and-set RPC. Re-enablement admits only slots strictly after the recorded cutoff. Before pilot admission, record per-slot Worker calls, visited workspace counts, claim and occurrence totals, notification writes, and lock/statement cancellations at the hosted PostgREST endpoint. Exercise duplicate delivery, lost responses, stop during settlement and restart from stored ledger state. The ceilings are 960 database calls per day in generate mode and 96 in dry-run. Verify cap and rollback behavior with the duplicate-worker pgTAP test and settlement pgTAP test. Use the production migration runbook for the list-only dispatch gate.

Web surfaces

Every Repeat control reads eligibility from the request API and renders nothing while recurrence is unavailable. That covers the dormant default, a disabled workspace gate, guests, non-members, and a missing receipt secret. The API answers 404 in each of these cases, and the UI treats that answer as “hidden”, not as an error.
  • Quick create. Repeat is the last chip in the quick create-task dialog. It offers Daily, Weekdays, Weekly, Monthly, and Custom. The dialog asks prepare for the selected list. The chip appears only when that call returns a receipt. Drafts and creation with a parent or pending relationships keep the plain create path and show no chip, because a series template carries no relationships. The expanded editor shows no Repeat and saves a plain task. With a choice set, Save calls create and the server writes the first task. A retry of the same request reuses its receipt, so a lost response can’t create a second series.
  • Custom. The editor covers the CalendarRecurrenceRule v1 task subset: daily, weekly, monthly, or yearly; intervals from 1 to 99; weekly days; a month day, where 29–31 clamp to the last day; up to 1,000 occurrences; or an end date within five years. Relative weekdays are not offered.
  • Preview. The shared planner lists the next three dates. If the picked date isn’t a repeat date (for example, Weekdays from a Saturday, or the 31st from the 21st), an inline note names the date the first task will use. A date that doesn’t exist in the series zone is marked as skipped.
  • Timing. The series starts on the due date, else the start date, else today, in the calendar time-zone preference. A due time before 23:59 becomes the series due time. The gap from start date to due date becomes the start offset.
  • Cards. A board card shows a Repeat badge for tasks in a series the reader may see. Cards read their series in batches of up to 100 task IDs. The badge’s accessible name includes the series state.
  • Task detail. A Repeat row shows the badge with the schedule summary. Members who can manage the series can also edit the schedule, which applies to this and following tasks, and pause, resume, or end it. Ending asks for confirmation first. When the task’s fields differ from the series template, the row asks where to apply the edits. “Only this task” is the default and keeps the edit on this task. “This and following tasks” copies the current fields into the series. The prompt follows edits made since the task opened. A series edit starts after the dates the series has already created: a new schedule starts the day after this task, and a template edit keeps the schedule from its next date. Editing from an older task, once newer ones exist, asks the member to edit from the latest task.
Mobile uses the same request API and is not covered here. Component coverage lives in quick-create-repeat-chip.test.tsx and task-recurrence-eligibility.test.tsx.

Database write paths

The task guard sees row changes from the shared task detail and bulk handlers, direct task updates, the task-history restore RPC, and both functions in the task update wrapper chain. The actor-binding migration leaves those writers proof-free. The guard uses the row after list moves have assigned timestamps and display numbers and after the fleet metadata trigger has stamped updated_at. Board capacity, history, notification, and blocker triggers continue to run on their ordinary write paths. The list guard covers status changes made directly or through task list management. List hard deletion cascades through task deletion, which clears the task link and preserves the occurrence date when its series survives. Private occurrence and active-slot constraints check the final transaction state. Workspace membership loss and account erasure release active slots, and account erasure clears actor references.

Database verification

Foundation pgTAP coverage checks off-by-default gates, role access, epoch conflicts, capacity and topology, actor erasure, and forged proof attempts. The search path contract checks the exposed definer functions after a full reset. Request pgTAP coverage covers expiry, replay, completion, and generated relations. The production migration runbook requires the pending production set to match the reviewed SQL before dispatch.