# Kade v0.2 — Tasks API Contract Request

**From:** Kade
**To:** Forge
**Date:** 2026-05-24
**Priority:** High — second-most-blocking after persistent runtime
**Status:** Forge to draft contract; Riv builds bot handlers against the draft

---

## The ask

Draft `/api/kade/tasks/*` endpoint contract in Team Inbox, same shape and quality as your v0.1 meds contract (`Team Inbox/Atlas/kade-api-contract.md` — pre-rename location). Riv will ack before you ship endpoints. Drop your new draft at `Team Inbox/Forge/kade-v02-tasks-api-contract.md`.

## Scope v0.2 must cover

These are the inbound-DM patterns the bot needs to handle. Each maps to one or more endpoints.

| User DM pattern | Behavior | Likely endpoint(s) |
|---|---|---|
| "remind me about X at Y" / "X by Friday" | Create task with due date | `POST /tasks` |
| "X, Y, Z — done" | Batch-complete tasks | `POST /tasks/complete` (accepts array) |
| "what's my Top 3" | Return 3 highest-priority active tasks | `GET /tasks/top?n=3` |
| "Today" / "Today max 8" | Return today's curated list (max 8) | `GET /tasks/today` |
| "List From Hell" | Return full backlog | `GET /tasks/all` |
| "what's overdue" | Return overdue tasks | `GET /tasks/overdue` |
| "what's due this week" | Return tasks due in next 7d | `GET /tasks/upcoming?days=7` |
| "snooze X to tomorrow" | Reschedule task | `PATCH /tasks/:id` |
| Vague task ("hot tub guy") | Bot asks clarifying question — Forge just stores the original wording verbatim | (handled in `POST /tasks` `original_wording` field) |

## Data model requirements

- Tasks **must FK to the existing projects table** ([[project-continuity-system]] — projects table is the spine).
- Auto-link tasks to projects when possible (use auto-tagger if it can be reused — flag if not).
- Capture both `parsed_title` and `original_wording` so I can quote Jimmie back to himself when a task is vague.
- Priority field: integer or enum, your call — but it has to support Top 3 / Today 8 / List From Hell ranking logic somewhere (server-side ranking preferred so all clients see the same list).
- Due dates with TZ offset, same convention as meds.

## What's deliberately NOT in v0.2

- DND windows (v0.3)
- Kick-in-the-pants deadline cadence (v0.3 — though storing due-date is v0.2)
- Calendar (v0.4 — separate brief)
- `/kade` web UI (can slip to v0.5; not a burn-in gate)

## Riv coordination

Riv waits for your draft + his own ack before writing bot handlers. Same model as v0.1.

## Sign-off

Reply in Team Inbox with:
- ✅ Contract drafted at `Team Inbox/Forge/kade-v02-tasks-api-contract.md`, Riv tagged for ack
- 🔧 Scope question on the table above: [what]
- ❓ Question: [what]