openapi: 3.0.3
info:
  title: NewCo - AI-Native Task Management
  description: |
    The Eisenhower Matrix for AI Agents. Manage tasks through Claude, ChatGPT, or any AI assistant.
    
    ## V2.0 Features
    - WIP limits on Do Now (Q1) quadrant
    - Task blockers with block/unblock workflow
    - Daily briefing endpoint
    - Completed timestamp tracking
    
    ## Authentication
    All endpoints (except health and OpenAPI spec) require Bearer token authentication.
    Use OAuth 2.0 to obtain an access token.
    
    ## Quadrant Values
    - `q1_urgent_important` - Do First (Urgent AND Important)
    - `q2_not_urgent_important` - Schedule (Important, NOT Urgent)
    - `q3_urgent_not_important` - Delegate (Urgent, NOT Important)
    - `q4_not_urgent_not_important` - Eliminate (Neither)
    - `inbox` - Triage (Unclassified)
    
    ## Accountability
    Every task action requires a "why" field explaining the reason for the action.
    All changes are logged immutably.
  version: 2.0.0
  contact:
    name: Strategos Support
    url: https://strategos-ai.app

servers:
  - url: https://strategos-ai.app
    description: Production

paths:
  /dashboard:
    get:
      operationId: getDashboard
      summary: Get Dashboard
      description: Returns all active tasks grouped by Eisenhower quadrant with stats.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Dashboard data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /tasks:
    post:
      operationId: createTask
      summary: Create Task
      description: Create a new task. The "why" field is required to explain why this task is being created.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /tasks/{taskId}:
    get:
      operationId: getTask
      summary: Get Task
      description: Retrieve a single task by ID.
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Task details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      operationId: updateTask
      summary: Update Task
      description: |
        Update a task. The "why" field is REQUIRED when:
        - Changing the quadrant
        - Completing the task (status = "completed")
        - Archiving the task (status = "archived")
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
      responses:
        '200':
          description: Task updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /tasks/{taskId}/history:
    get:
      operationId: getTaskHistory
      summary: Get Task History
      description: Returns the immutable changelog for a task, showing all changes with reasons.
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Task history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskHistoryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /sync:
    post:
      operationId: syncTasks
      summary: Sync Tasks
      description: Trigger sync with external task managers (Todoist, Notion, TickTick). Currently returns stub response - full implementation coming in Phase 2.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Sync status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: not_configured
                  message:
                    type: string

  /sync/status:
    get:
      operationId: getSyncStatus
      summary: Get Sync Status
      description: Get current sync configuration and last sync times.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Sync configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  configured:
                    type: boolean
                  providers:
                    type: array
                    items:
                      type: string

  # ============================================================================
  # V2 ENDPOINTS
  # ============================================================================

  /tasks/blocked:
    get:
      operationId: getBlockedTasks
      summary: Get Blocked Tasks (V2)
      description: Returns all tasks with status=blocked for the authenticated user.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of blocked tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  count:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'

  /tasks/{taskId}/complete:
    patch:
      operationId: completeTask
      summary: Complete Task (V2)
      description: Mark a task as complete with timestamp. Sets status=complete and completed_at=now.
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                why:
                  type: string
                  description: Optional reason for completion
      responses:
        '200':
          description: Task completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /tasks/{taskId}/block:
    patch:
      operationId: blockTask
      summary: Block Task (V2)
      description: Add a blocker to a task. Sets status=blocked and appends to blockers array.
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reason
              properties:
                reason:
                  type: string
                  description: What is blocking this task?
                  example: Waiting for client approval
      responses:
        '200':
          description: Task blocked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /tasks/{taskId}/unblock:
    patch:
      operationId: unblockTask
      summary: Unblock Task (V2)
      description: Resolve a blocker on a task. If no unresolved blockers remain, sets status=active.
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                blocker_index:
                  type: integer
                  description: Which blocker to resolve (0-indexed). Defaults to first unresolved.
      responses:
        '200':
          description: Blocker resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /briefing/daily:
    get:
      operationId: getDailyBriefing
      summary: Get Daily Briefing (V2)
      description: |
        Returns morning briefing with:
        - Do Now items sorted by due date proximity
        - Overdue flags on each task
        - All blocked tasks
        - WIP status (count, limit, at_capacity)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Daily briefing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyBriefingResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token (starts with "nk_")

  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        quadrant:
          $ref: '#/components/schemas/Quadrant'
        why:
          type: string
          description: Reason for the current state
        status:
          type: string
          enum: [active, completed, archived]
        due_date:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Quadrant:
      type: string
      enum:
        - q1_urgent_important
        - q2_not_urgent_important
        - q3_urgent_not_important
        - q4_not_urgent_not_important
        - inbox
      description: |
        Eisenhower Matrix quadrant:
        - q1_urgent_important: Do First
        - q2_not_urgent_important: Schedule
        - q3_urgent_not_important: Delegate
        - q4_not_urgent_not_important: Eliminate
        - inbox: Triage

    CreateTaskRequest:
      type: object
      required:
        - title
        - why
      properties:
        title:
          type: string
          description: Task title
          example: Review investor deck
        quadrant:
          $ref: '#/components/schemas/Quadrant'
        why:
          type: string
          description: Reason for creating this task
          example: Need to prepare for Friday meeting
        due_date:
          type: string
          format: date-time
          nullable: true
          example: "2025-01-17T00:00:00Z"

    UpdateTaskRequest:
      type: object
      properties:
        title:
          type: string
        quadrant:
          $ref: '#/components/schemas/Quadrant'
        status:
          type: string
          enum: [active, completed, archived]
        why:
          type: string
          description: Required when changing quadrant, completing, or archiving
        due_date:
          type: string
          format: date-time
          nullable: true

    DashboardResponse:
      type: object
      properties:
        quadrants:
          type: object
          properties:
            q1_urgent_important:
              type: array
              items:
                $ref: '#/components/schemas/Task'
            q2_not_urgent_important:
              type: array
              items:
                $ref: '#/components/schemas/Task'
            q3_urgent_not_important:
              type: array
              items:
                $ref: '#/components/schemas/Task'
            q4_not_urgent_not_important:
              type: array
              items:
                $ref: '#/components/schemas/Task'
            inbox:
              type: array
              items:
                $ref: '#/components/schemas/Task'
        stats:
          type: object
          properties:
            total_active:
              type: integer
            overdue:
              type: integer
            due_today:
              type: integer
            completed_this_week:
              type: integer
        wip_status:
          $ref: '#/components/schemas/WipStatus'

    WipStatus:
      type: object
      description: Work-in-progress limit status for Do Now quadrant
      properties:
        count:
          type: integer
          description: Current number of tasks in Q1
        limit:
          type: integer
          description: Maximum allowed tasks in Q1
        at_capacity:
          type: boolean
          description: True if count >= limit

    Blocker:
      type: object
      properties:
        description:
          type: string
        created_at:
          type: string
          format: date-time
        resolved_at:
          type: string
          format: date-time
          nullable: true

    DailyBriefingResponse:
      type: object
      properties:
        do_now:
          type: array
          description: Tasks in Q1 sorted by due date, with overdue flags
          items:
            allOf:
              - $ref: '#/components/schemas/Task'
              - type: object
                properties:
                  overdue:
                    type: boolean
        blocked_tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        overdue_count:
          type: integer
        wip_status:
          $ref: '#/components/schemas/WipStatus'
        generated_at:
          type: string
          format: date-time

    TaskHistoryResponse:
      type: object
      properties:
        task_id:
          type: string
          format: uuid
        history:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              action:
                type: string
                enum: [created, moved, updated, completed, archived, blocked, unblocked]
              from_quadrant:
                $ref: '#/components/schemas/Quadrant'
              to_quadrant:
                $ref: '#/components/schemas/Quadrant'
              why:
                type: string
              actor:
                type: string
              created_at:
                type: string
                format: date-time

    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: string

  responses:
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    ValidationError:
      description: Invalid request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'