# Tasks - Behavior Rules

This document explains how tasks work in tududi from a user behavior perspective (excluding recurring tasks, which are covered in [01-recurring-tasks-behavior.md](01-recurring-tasks-behavior.md)). For technical implementation details, see the backend code in `/backend/modules/tasks/` and `/backend/models/task.js`.

---

## **Task Creation**

### Basic Task Creation

1. **A task requires only a name to be created**
   - All other fields (due date, priority, project, etc.) are optional
   - Task name cannot be empty or just whitespace
   - Tasks are created with "Not Started" status by default

2. **Every task gets a unique identifier (UID)**
   - Used in URLs and API calls
   - Never changes during the task's lifetime
   - Example: `tsk_abc123def456`

3. **Tasks belong to a user**
   - The creator becomes the owner
   - Only the owner (or those with shared access) can view/modify the task
   - Admins can access all tasks

### Quick Capture

4. **Tasks can be created from multiple places:**
   - Main task list (+ button)
   - Today page quick add
   - Inbox (converted from inbox items)
   - Quick capture modal (keyboard shortcut)
   - Telegram bot
   - API

---

## **Task Fields & Properties**

### Name & Description

5. **Task name is the primary identifier**
   - Required field, maximum length varies by database
   - Displayed in lists, calendars, and notifications
   - Can be edited at any time

6. **Task note is for detailed information**
   - Optional text field for longer descriptions
   - Supports plain text (no markdown formatting)
   - Useful for context, instructions, or reference materials

### Status Lifecycle

7. **Seven status states exist:**
   - **Not Started (0):** Default state, task hasn't been worked on yet
   - **In Progress (1):** Task is actively being worked on
   - **Done (2):** Task is completed
   - **Archived (3):** Task is finished and archived for historical record
   - **Waiting (4):** Task is blocked or waiting on something/someone
   - **Cancelled (5):** Task was abandoned or is no longer needed
   - **Planned (6):** Task is scheduled to be worked on

8. **Status changes affect visibility:**
   - "Done", "Archived", and "Cancelled" remove tasks from active views
   - "In Progress", "Planned", and "Waiting" appear in Today page Planned section
   - Status determines which section of the Today page shows the task

9. **Completion tracking is automatic:**
   - Changing status to "Done" sets `completed_at` timestamp to current time
   - Changing status from "Done" to anything else clears `completed_at`
   - Completed tasks show in "Completed" section of Today page

### Priority Levels

10. **Three priority levels:**
    - **Low (0):** Default priority, no special urgency
    - **Medium (1):** Moderate importance
    - **High (2):** Urgent or critical task

11. **Priority affects sorting:**
    - In most views, tasks are sorted High → Medium → Low
    - Priority is a visual indicator (colored flag icons)
    - Does not affect task behavior, only display order

### Due Dates

12. **Due dates are optional:**
    - Tasks without due dates are considered "someday/maybe"
    - Due dates are stored with date and time
    - Displayed in user's timezone

13. **Due date behavior:**
    - Tasks become "overdue" if due date passes and status is not "Done"
    - Overdue tasks appear in "Overdue" section on Today page
    - Due today tasks appear in "Suggested" section (if not in Planned status)
    - No automatic status changes when due date passes

### Defer Until

14. **Defer Until hides tasks until a specific time:**
    - Set a date/time when you want the task to become visible
    - Task is completely hidden from all views until defer time passes
    - Useful for "start this task on Monday" or "remind me in 2 hours"

15. **Defer Until behavior:**
    - System checks every 5 minutes for tasks whose defer time has passed
    - When defer time is reached, task becomes visible in appropriate sections
    - Optional notification sent when task becomes active (configurable)
    - Defer time can be edited or cleared at any time

16. **Defer Until is different from due date:**
    - Defer = "don't show me this until..."
    - Due date = "this needs to be finished by..."
    - A task can have both defer and due date
    - If both exist: task hidden until defer time, then due date determines urgency

---

## **Subtasks**

### Subtask Hierarchy

17. **Tasks can have subtasks (one level deep)**
    - Subtasks are full tasks with all properties (status, priority, due date, etc.)
    - Maximum one level: tasks can have subtasks, but subtasks cannot have their own subtasks
    - Parent-child relationship is tracked via `parent_task_id`

18. **Subtasks are displayed under their parent:**
    - Parent task shows a summary (e.g., "2 of 5 completed")
    - Subtasks can be collapsed/expanded in the UI
    - Subtasks are ordered by `order` field, then creation date

19. **Subtasks have their own lifecycle:**
    - Each subtask has independent status, priority, due date
    - Completing all subtasks doesn't auto-complete the parent
    - Completing the parent doesn't auto-complete subtasks
    - Deleting the parent deletes all subtasks (cascade)

20. **Subtask visibility rules:**
    - Subtasks don't appear in main task lists (only under parent)
    - Subtasks don't show in Today page sections independently
    - Searching for subtasks shows them with parent context
    - Filtering applies to parent tasks, not individual subtasks

### Subtask Ordering

21. **Subtasks can be manually reordered:**
    - Drag-and-drop in the UI updates the `order` field
    - Order is sequential integers (1, 2, 3, etc.)
    - New subtasks are added at the end (highest order + 1)

---

## **Attachments**

### File Uploads

22. **Tasks can have file attachments:**
    - Multiple files can be attached to a single task
    - File size limit: 10MB per file
    - Stored in `/uploads/tasks/` directory

23. **Allowed file types:**
    - Images: jpg, jpeg, png, gif, webp, svg
    - Documents: pdf, doc, docx, xls, xlsx, ppt, pptx
    - Text: txt, md, csv
    - Archives: zip, tar, gz
    - Other common formats

24. **Attachment metadata:**
    - Original filename is preserved in database
    - File is renamed on disk for uniqueness (task-[timestamp]-[random].[ext])
    - Each attachment gets a unique UID
    - Attachments track: filename, file size, MIME type, upload date

25. **Attachment management:**
    - Uploaded by task owner or users with write access
    - Can be downloaded by anyone with read access to the task
    - Deleting attachment removes file from disk
    - Deleting task removes all attachments and their files

---

## **Project Assignment**

### Linking to Projects

26. **Tasks can belong to a project:**
    - Optional `project_id` field links task to project
    - Tasks without a project are "standalone"
    - Project assignment determines which project view shows the task

27. **Project assignment effects:**
    - Task inherits project's sharing permissions
    - If user has access to project, they have same access to project's tasks
    - Deleting a project can orphan or delete tasks (depends on user choice)
    - Task completion contributes to project's progress metrics

28. **Changing project assignment:**
    - Can move task from one project to another
    - Can remove task from project (makes it standalone)
    - Subtasks inherit parent task's project
    - Changing parent's project doesn't automatically update subtasks

---

## **Tags**

### Tagging System

29. **Tasks can have multiple tags:**
    - Tags are flexible labels for categorization
    - Same tag can be used across tasks, notes, and projects
    - Tags are created automatically when first used
    - Tags are case-insensitive and normalized

30. **Tag behavior:**
    - Adding/removing tags doesn't affect task status or visibility
    - Tags enable filtering: "show all tasks with #urgent"
    - Tags appear as clickable chips in the UI
    - Tag autocomplete suggests existing tags while typing

31. **Tag inheritance:**
    - Subtasks have their own independent tags
    - Tags are not inherited from parent task or project
    - Deleting a tag removes it from all tasks (but doesn't delete tasks)

---

## **Task Completion**

### Marking Tasks as Done

32. **Completing a task:**
    - Change status to "Done" (manually or via checkbox)
    - `completed_at` timestamp is set to current time
    - Task moves to "Completed" section on Today page
    - Task disappears from active task lists

33. **Completion behavior for subtasks:**
    - Parent can be completed even if subtasks are not done
    - Subtasks can be completed independently
    - Completing the parent doesn't complete subtasks
    - Progress indicator shows "X of Y completed" for subtasks

34. **Un-completing a task:**
    - Changing status from "Done" to any other status
    - Clears the `completed_at` timestamp
    - Task reappears in active views
    - Task history preserves the completion event

### Completed Task Visibility

35. **Where completed tasks appear:**
    - "Completed" section on Today page (if completed today)
    - Project details page with "Show completed" filter
    - Search results (if specifically queried)
    - Task history and timeline views

36. **Completed tasks are excluded from:**
    - Main task lists by default
    - Today page "Planned" and "Suggested" sections
    - Overdue calculations
    - Upcoming view (future due dates)

---

## **Task Events & History**

### Activity Tracking

37. **Every task change is logged:**
    - Task creation event
    - Status changes
    - Field updates (name, due date, priority, etc.)
    - Assignment to project
    - Tag additions/removals
    - Attachment uploads/deletions

38. **Event data includes:**
    - Event type (created, status_changed, field_updated, etc.)
    - User who made the change
    - Timestamp of the change
    - Old value and new value (for field changes)
    - Additional metadata (source: web, API, Telegram, etc.)

39. **Task timeline:**
    - Events are displayed in chronological order
    - Shows full audit trail of task's lifecycle
    - Useful for understanding when and why changes occurred
    - Cannot be edited or deleted (immutable history)

---

## **Habit Mode**

### Habit Tracking

40. **Tasks can be habit trackers:**
    - `habit_mode` flag enables habit-specific features
    - Different from recurring tasks (habits focus on streak tracking)
    - Example: "Exercise 3 times per week"

41. **Habit properties:**
    - **Target count:** How many times per period (e.g., 3 times)
    - **Frequency period:** daily, weekly, or monthly
    - **Streak mode:**
      - Calendar: Count consecutive days
      - Scheduled: Count consecutive completions on scheduled days
    - **Flexibility mode:**
      - Strict: Must complete on exact schedule
      - Flexible: Can complete within the period

42. **Habit tracking:**
    - `habit_current_streak`: Current consecutive completions
    - `habit_best_streak`: Longest streak ever achieved
    - `habit_total_completions`: Total times completed
    - `habit_last_completion_at`: When last completed

43. **Habit completion:**
    - Completing a habit increments counters
    - Streak breaks if missed according to mode rules
    - Habit widgets show progress toward target count
    - Visual indicators for streak status (on track, at risk, broken)

---

## **Task Deletion**

### Deleting Tasks

44. **Deleting a task:**
    - Removes the task from the database
    - Cascade deletes all subtasks
    - Removes all attachments (files deleted from disk)
    - Removes task events/history
    - Removes tag associations (tags themselves remain)

45. **Soft delete is not implemented:**
    - Deletion is permanent (no trash/recycle bin)
    - No undo operation
    - Completed tasks can be archived instead of deleted

46. **Deleting a parent task:**
    - All subtasks are deleted (cannot be orphaned)
    - Warning shown if parent has subtasks
    - User must confirm deletion

47. **Permission to delete:**
    - Only task owner can delete their tasks
    - Users with write access via project sharing can delete
    - Admins can delete any task

---

## **Task Sharing & Permissions**

### Access Control

48. **Tasks inherit permissions from projects:**
    - If a task belongs to a project, anyone with project access has same access to task
    - Access levels: none, read-only (ro), read-write (rw), admin
    - Owner always has full access

49. **Standalone tasks:**
    - Tasks without a project are only visible to owner
    - Cannot be shared directly (must assign to a project to share)
    - Admins can view all tasks regardless of ownership

50. **Permission effects:**
    - **Read-only:** Can view task, cannot edit or delete
    - **Read-write:** Can edit task fields, add subtasks, upload attachments
    - **Admin/Owner:** Can delete task, change project assignment, share

---

## **Task Ordering & Sorting**

### Default Sort Order

51. **Tasks are typically sorted by:**
    1. Priority (High → Medium → Low)
    2. Due date (earliest first, nulls last)
    3. Created date (newest first for same priority/due date)

52. **Custom sorting options:**
    - Name (alphabetical)
    - Status
    - Created date
    - Updated date
    - Manual order (drag-and-drop, for subtasks)

53. **Grouping options:**
    - By project
    - By status
    - By priority
    - By due date (today, tomorrow, this week, later)
    - By tags

---

## **Task Notifications**

### Notification Types

54. **Tasks trigger notifications for:**
    - Task due soon (based on due date)
    - Task overdue
    - Defer Until time reached
    - Task assigned to you (shared via project)

55. **Notification channels:**
    - In-app notifications (navbar indicator)
    - Email (configurable per notification type)
    - Telegram (configurable per notification type)
    - Push notifications (configurable per notification type)

56. **Notification preferences:**
    - User can enable/disable per notification type
    - User can choose which channels for each type
    - Notifications can be dismissed or marked as read
    - Duplicate notifications are prevented (deduplication logic)

---

## **Special Behaviors**

### Task Visibility Rules

57. **A task is hidden from views if:**
    - Defer Until time has not yet passed
    - Status is "Done", "Archived", or "Cancelled" (unless showing completed)
    - User doesn't have permission to view it
    - It's a subtask (only shown under parent)
    - It's a recurring parent template (only instances shown)

58. **Overdue detection:**
    - Task is overdue if: `due_date < now` AND `status != Done/Archived/Cancelled`
    - Overdue tasks appear in "Overdue" section on Today page
    - Overdue count shows in navbar and project metrics
    - No automatic status change occurs

### Task Intelligence

59. **Task intelligence features (optional, can be disabled):**
    - Auto-suggest next actions based on task context
    - Smart suggestions for tasks to work on (Today page "Suggested" section)
    - Productivity insights and patterns
    - Next task recommendation based on priority, due date, and context

60. **Suggestion algorithm considers:**
    - Due dates (tasks due soon ranked higher)
    - Priority level
    - Project deadlines
    - Task age (older tasks surfaced)
    - Completion patterns (time of day you usually work on similar tasks)

---

## **Key Concepts**

### Task Instance

A single task record in the database with a unique ID and UID. Contains all task properties (name, status, priority, dates, etc.).

### Parent-Child Relationship

Hierarchical link between a parent task and its subtasks. One level deep only. Tracked via `parent_task_id` field.

### Completion Timestamp

The exact date and time when a task's status changed to "Done". Stored in `completed_at` field. Used for filtering "completed today" tasks.

### Task Events

Immutable audit log of all changes to a task. Each event records who changed what, when, and the before/after values.

### Defer Until

A feature that hides a task from all views until a specified date/time. Different from due dates - it's about when to START thinking about the task, not when to FINISH it.

### Task Ownership

The user who created the task owns it by default. Ownership can be transferred via project sharing, but the original `user_id` doesn't change.

### Habit Tracking

A mode that transforms a task into a habit tracker with streak counting, target counts, and flexible scheduling. Useful for building consistent behaviors.

---

## **Related Documentation**

- [Recurring Tasks Behavior](01-recurring-tasks-behavior.md) - How recurring tasks work
- [Today Page Sections](02-today-page-sections.md) - Task filtering and display on Today page
- [Upcoming View](03-upcoming-view.md) - 7-day task preview
- [Projects](06-projects.md) - Project assignment and task organization
- [Tags System](09-tags-system.md) - Tagging and categorization
- [User Management](08-user-management.md) - Permissions and sharing

**Technical Implementation Files:**
- Task model: `/backend/models/task.js`
- Task service: `/backend/modules/tasks/`
- Task completion: `/backend/modules/tasks/operations/completion.js`
- Subtasks: `/backend/modules/tasks/operations/subtasks.js`
- Attachments: `/backend/modules/tasks/attachments.js`
- Task events: `/backend/modules/tasks/taskEventService.js`
- Deferred tasks: `/backend/modules/tasks/deferredTaskService.js`

---

**Document Version:** 1.0.0
**Last Updated:** 2026-03-15
**Audience:** Developers, AI assistants, and end users