Glossary: Task Sync

Mirrored from docs/design/task-sync/references/glossary.md. Edit the source document in the repository, not this generated page.

Vocabulary specific to the task-sync feature. Standard git terms (orphan branch in the abstract, refspec, fast-forward) are excluded except where task sync gives them a specific meaning. Standard distributed-systems terms (CRDT, OT, eventual consistency) are excluded — the 3_vision.md §2 section names them in their generic form when needed.

Term	Meaning
Materialized state	The local .orbit/tasks/ tree as hydrated from the task registry — i.e., the YAML files an Orbit operator reads with orbit task list and orbit task show. The registry on the orphan branch is the canonical store; the workspace tree is the materialized view. See 2_design.md §2.3.
Operation kind	One of a fixed set of structured task mutations (task.add, task.transition, task.comment.append, task.history.append, task.review.append, task.field.update, task.artifacts.upsert, task.delete) recorded in commit messages on the registry. Replay rules in 2_design.md §3.2 are keyed by operation kind.
Operation replay	The behavior on push reject: instead of text-merging, the sync coordinator re-fetches the registry, applies the original operation’s replay rule against the new tip, and pushes again. Some operations always converge (comment.append, history.append); some surface a structured conflict when their baseline has changed (field.update, transition). See 2_design.md §3.2.
Orphan branch	In task sync specifically: the git branch at refs/heads/orbit/tasks that holds the canonical task registry. It has no shared history with code branches, is created with git checkout --orphan, and is never merged into product branches. The pattern itself is a generic git feature; in this feature it’s the registry’s storage. See 2_design.md §2.1.
Registry pull	The operation orbit task sync pull. Fetches the orphan branch ref and updates the workspace’s .orbit/tasks/ tree from it. Local-only changes are surfaced rather than overwritten. See 2_design.md §6.2.
Registry seed	The first-time enablement operation orbit task sync push --init. Verifies the registry ref does not exist (or is empty) on the remote and seeds it from the workspace’s existing .orbit/tasks/ tree. Subsequent enablements on the same workspace use regular pull/push, not --init. See 2_design.md §6.2.
Same-task conflict	The class of conflict where two operators concurrently mutate the same task (status transition divergence, concurrent same-field edits). Distinguished from counter collision (concurrent ADD with the same allocated ID), which is auto-resolvable. Same-task conflicts may resolve automatically (append-only operations) or surface to the user as a structured conflict (task.field.update, divergent task.transition). See 2_design.md §3.1.
Soft-claim	An advisory assigned_to field on a task indicating an operator has expressed intent to work on it. A soft-claim is not a lock — it does not prevent another operator from editing the task. The convention is “look before you leap”; the mechanism is a hint. Open questions about expiry, stealing, and per-status claims live in 3_vision.md §1.3.
Structured conflict	A conflict the replay logic could not resolve automatically. Written to .orbit/tasks/_conflicts/<task-id>.yaml with both sides recorded; resolved by the user via orbit task sync resolve <task-id>. Distinct from a git text-merge conflict — structured conflicts are field-level, not line-level. See 2_design.md §3.2.
Sync coordinator	The new code component (orbit-store::sync::TaskSyncCoordinator) that owns git transport, operation classification, and replay logic. Sits above the file store (orbit-store/src/file/task_store/) and below runtime/CLI/web entry points. See 2_design.md §5.1.
Task registry	The canonical store of task bundles for a team, materialized as a git tree on the orphan branch refs/heads/orbit/tasks. The workspace’s .orbit/tasks/ is a hydrated view of the registry; the registry is the source of truth when sync is enabled. See 2_design.md §2.1.
Tombstone	A _tombstones/<task-id>.yaml entry on the registry recording that a task was deleted, by whom, and when. The regular task directory is removed; the tombstone prevents an offline operator’s older task version from resurrecting the task on push. See 2_design.md §3.4 and 4_decisions.md ADR-008.