Documentation

Completion semantics.

Completion is the one thing that crosses in both directions, and it crosses under rules you chose. This page is the full contract, including the edge cases.

The lifecycle policy

Each Linear team in a bridge has exactly one lifecycle policy, configured in the wizard as two questions:

1. When you complete a task in Todoist, which workflow state does the issue move to?
2. When you un-complete a task, where does the issue return?

The app states each policy as the sentences it will act on:

Completing from Todoist

Checking off a mirror task never writes Linear directly from the webhook. Reconciliation rereads both providers and then applies the transition — only if all of the following still hold:

• The task link still names the same Linear issue and Todoist task.
• Todoist’s completion state and generation still match what was observed during planning.
• The issue has not become deleted, unassigned, canceled, or archived.

The issue then moves to the one configured state for its team, and Linear’s fresh pre-completion workflow state is recorded as the restore target.

Reopening

• Un-completing the Todoist task restores the Linear issue to its durably recorded prior state — and only that state. The restore applies only while Linear is still in the exact completed state TaskBridge put it in.
• Reopening the Linear issue reopens the Todoist task, regardless of which side initiated the earlier completion.

When systems disagree

Completing either linked endpoint completes the other. When they conflict, authority is explicit:

• If Linear remains completed and TaskBridge never owned that completion — someone on your team closed the issue — Linear is authoritative. A reopened Todoist task is re-closed rather than guessed into a Linear state.
• Linear stays authoritative for arbitrary engineering workflow states. TaskBridge synchronizes only Todoist’s active/completed lifecycle and does not map each Linear status into Todoist.

Holds

When a completion cannot proceed — for example, the configured target state was deleted in Linear — TaskBridge holds the work, counts it on the bridge page as blocked, and names the problem:

Choosing a new state releases the held completions. Holds never expire into silent failure, and holding never modifies Linear.

Safety checks before every write

Delayed and retried operations go through the durable outbox, and every one re-verifies the world before touching a provider:

• The durable link id, Linear issue id, and Todoist task id must still name one active relationship.
• Providers are reread; stale generations are discarded so an old retry can never overwrite a newer edit.
• Retries that find the target already in the desired state do not repeat the mutation. Todoist create retries reuse a request id derived from the durable deduplication key, so a retried create cannot produce a duplicate task.