Project Governance and Task Lifecycle Management

The Work Execution module follows a Project-First hierarchy: every task must belong to an approved project, ensuring all logged effort ties back to a sanctioned business objective. Projects move through an approval gate before any tasks can be assigned under them, and tasks have their own multi-stage lifecycle complete with complexity scoring, blocked-state handling, and a formal completion-request flow for interns and junior employees.

Project Lifecycle

Employee submits a project request

Any authenticated user can call POST /api/v1/projects with a title, description, priority, and optional due date. The project is created in pending_approval status.

Manager or Admin reviews the request

POST /api/v1/projects/{project_id}/approve accepts a ProjectDecision payload. The approver sets decision to approved or rejected and may attach a reason.

Project becomes task-eligible

Once approved, the project status advances and it appears in the GET /api/v1/projects/task-eligible endpoint, making it available for task creation dropdowns. Only approved or active projects are returned here.

Project progresses through active and completed states

When a project is approved it transitions immediately to active. From there it advances to completed as work concludes. A project can also move to on_hold or be soft-deleted via PATCH /api/v1/projects/{project_id}/archive.

Full Project Status Lifecycle

Status	Description
`draft`	Not yet submitted for approval
`pending_approval`	Awaiting manager or admin decision
`approved`	Cleared for task creation
`active`	Work is actively underway
`on_hold`	Temporarily paused
`completed`	All work finished
`rejected`	Approval denied
`archived`	Soft-deleted; excluded from default listings

Project Priority Values

`priority`	Use case
`low`	Background or nice-to-have work
`medium`	Standard delivery
`high`	Elevated urgency
`critical`	Immediate attention required

Creating a Project

POST /api/v1/projects
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Onboarding Portal Redesign",
  "description": "Revamp the new-hire onboarding UI for Q3.",
  "priority": "high",
  "due_date": "2025-09-30"
}

The response returns project_status: pending_approval. Tasks cannot be created under this project until a manager or admin calls the approve endpoint and sets the project to active.

Task Lifecycle

Tasks are the atomic units of work. Each task belongs to exactly one project and is assigned to exactly one employee.

Status Progression

`status`	Meaning
`created`	Task exists but work has not started
`approved`	Task explicitly approved (used in certain flows)
`in_progress`	Employee is actively working on it
`blocked`	Work is stalled — a `blocked_reason` is mandatory
`completed`	Work is done; pending review
`reviewed`	Manager has reviewed the completed work
`reopened`	Sent back for additional work
`archived`	Soft-deleted from default views

Setting a task status to blocked without providing blocked_reason is a validation error. The frontend must surface a mandatory text input whenever an employee moves a task to the blocked state.

Creating a Task

POST /api/v1/tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assigned_to": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "title": "Design new employee profile card component",
  "description": "Create a reusable React component with avatar, name, role, and status.",
  "priority": "medium",
  "due_date": "2025-08-15"
}

Task Create Fields

project_id

UUID

required

Must reference an approved or active project. The API rejects tasks under pending_approval or rejected projects.

assigned_to

UUID

required

UUID of the employee who will own and execute the task.

title

string

required

1–255 character task title. This is the label shown everywhere in the UI — never the UUID.

description

string | null

Optional detailed description of the deliverable.

parent_id

UUID | null

Set to create this task as a subtask of an existing task.

priority

string

low, medium (default), high, or critical.

due_date

date | null

Target completion date. Tasks past this date and not completed are flagged as overdue.

Complexity Scoring

Managers and admins assign a complexity level and expected duration to help calibrate workload and productivity analytics.

POST /api/v1/tasks/{task_id}/complexity
Authorization: Bearer <token>
Content-Type: application/json

{
  "complexity_level": 5,
  "expected_duration_minutes": 240
}

complexity_level

integer (1–10)

required

Relative difficulty score. Typical values follow a Fibonacci-like scale: 1, 2, 3, 5, 8.

expected_duration_minutes

integer (> 0)

required

The manager’s estimate of how long the task should take in minutes.

The actual_duration_minutes field on TaskRead is updated automatically as time logs accumulate. Comparing expected_duration_minutes to actual_duration_minutes powers the efficiency metrics in the employee growth view.

Task Completion Request Flow

Interns and junior employees cannot mark a task as completed directly. They must submit a completion request that a manager then approves or rejects.

Employee submits completion request

POST /api/v1/tasks/{task_id}/completion-requests with an optional request_note string. A TaskCompletionRequest record is created with status pending.

Manager reviews pending requests

GET /api/v1/tasks/completion-requests?status=pending returns all requests in the manager’s team scope.

Manager approves or rejects

Approve: POST /api/v1/tasks/completion-requests/{request_id}/approve — task status advances to completed.
Reject: POST /api/v1/tasks/completion-requests/{request_id}/reject — task returns to its previous state and the rejection reason is recorded.

Completion Request Statuses

Status	Meaning
`pending`	Awaiting manager review
`approved`	Task marked completed
`rejected`	Request denied; task stays in prior state
`cancelled`	Employee withdrew the request
`superseded`	A newer request replaced this one

Task Action Flags

Every TaskRead response carries computed boolean flags that the frontend uses to gate UI controls:

Flag	When `true`
`can_complete`	The current user may mark this task as completed directly
`can_update_status`	The current user may change the task status
`can_start_timer`	The current user may start a timer session on this task

Time cannot be logged against tasks in blocked, completed, or archived status. The can_start_timer flag will be false for those states.

Subtasks

Tasks support one level of parent–child nesting. Subtasks are created by setting parent_id on the create request.

GET /api/v1/tasks/{task_id}/subtasks
Authorization: Bearer <token>

Returns the list of tasks whose parent_id equals task_id.

Task Comments

Team members can leave threaded comments on any task for async collaboration.

Add Comment
List Comments

POST /api/v1/tasks/{task_id}/comments
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Designs approved by the product team. Proceeding to implementation."
}

GET /api/v1/tasks/{task_id}/comments
Authorization: Bearer <token>

Comment Fields:

user_id

UUID

Author of the comment (display user_full_name in the UI, not the UUID).

content

string

Minimum 1 character. No maximum enforced by the schema.

created_at

datetime (UTC ISO-8601)

Timestamp of when the comment was posted.

Role-Based Access Summary

Employees / Interns / Junior Employees

Submit project requests
View assigned tasks
Update status and log time on own tasks
Submit completion requests (interns/juniors)
Add comments on accessible tasks

Managers / Team Leads

All employee actions above
Approve or reject project requests
Create and assign tasks to their team
Set complexity and expected duration
Review and approve/reject completion requests

Admin / HR Operations

All manager actions above
Full project and task visibility across the org
Access to GET /api/v1/tasks/admin/overview dashboard
Archive projects and tasks
Override task statuses

Listing Filters

GET /api/v1/tasks accepts project_id, assigned_to, status, and include_archived query params. Results are automatically scoped to the caller’s access level — employees see only their own tasks; managers see their team’s tasks; admins see all.

Admin Task Overview Dashboard

The GET /api/v1/tasks/admin/overview endpoint (admin role required) provides an organisation-wide snapshot:

{
  "summary": {
    "total_tasks": 142,
    "active_tasks": 89,
    "in_progress": 34,
    "completed": 53,
    "overdue": 7,
    "currently_working": 12
  },
  "total_count": 142,
  "tasks": [ ... ],
  "active_work": [ ... ]
}

The active_work array lists every currently running or paused timer session with the employee name, task title, project title, timer state, and live elapsed seconds.

UI Identification Rules

UUIDs are never displayed in the interface. Follow these label rules everywhere — dropdowns, headings, tables, and notifications:

Tasks → Task Title
Projects → Project Title
Users → Full Name
URLs → Use the UUID in the path (e.g., /tasks/{uuid}) but display the title as the page heading

Get Started

Core Concepts

Features

Deployment

Project Lifecycle

Full Project Status Lifecycle

Project Priority Values

Creating a Project

Task Lifecycle

Status Progression

Creating a Task

Task Create Fields

Complexity Scoring

Task Completion Request Flow

Completion Request Statuses

Task Action Flags

Subtasks

Task Comments

Role-Based Access Summary

Employees / Interns / Junior Employees

Managers / Team Leads

Admin / HR Operations

Listing Filters

Admin Task Overview Dashboard

UI Identification Rules

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Deployment

Documentation Index

​Project Lifecycle

​Full Project Status Lifecycle

​Project Priority Values

​Creating a Project

​Task Lifecycle

​Status Progression

​Creating a Task

​Task Create Fields

​Complexity Scoring

​Task Completion Request Flow

​Completion Request Statuses

​Task Action Flags

​Subtasks

​Task Comments

​Role-Based Access Summary

Employees / Interns / Junior Employees

Managers / Team Leads

Admin / HR Operations

Listing Filters

​Admin Task Overview Dashboard

​UI Identification Rules

Build docs developers (and LLMs) love

Project Lifecycle

Full Project Status Lifecycle

Project Priority Values

Creating a Project

Task Lifecycle

Status Progression

Creating a Task

Task Create Fields

Complexity Scoring

Task Completion Request Flow

Completion Request Statuses

Task Action Flags

Subtasks

Task Comments

Role-Based Access Summary

Admin Task Overview Dashboard

UI Identification Rules