feat: backend-driven task system with Notion agent

[chitcommit]

Summary

• Adds cc_tasks table (migration 0011) with state machine lifecycle and verification gates
• Creates 6 API endpoints at /api/tasks — webhook ingestion, list/get, status transitions, verification, recommendation spawning
• Adds Notion cron sync (Phase 9 in daily_api) that queries the Notion task database and upserts by external_id, preserving terminal states
• Adds 4 MCP tools (query_tasks, get_task, update_task_status, verify_task) for Claude Code integration
• Adds frontend Task/TaskAction types and 5 API methods in ui/src/lib/api.ts

State Machine

queued -> running -> needs_review -> verified -> done
  ^          |            |              |
  +--- failed <-----------+--------------+

• verified requires verification_artifact non-null
• Hard verification also requires ledger_record_id
• done is terminal; failed retries back to queued

Post-Merge Setup

1. Run migration 0011_tasks.sql against Neon
2. Set KV keys: notion:task_agent_token, notion:task_database_id
3. Create Notion database "Chitty Service Task Tracker" with prescribed schema
4. Configure Notion AI agent with task capture prompt

Test plan

• npm run dev starts without type errors
• GET /api/tasks returns empty list
• POST /api/tasks/webhook with test payload creates task
• PATCH /api/tasks/:id/status enforces state machine (reject queued -> done)
• POST /api/tasks/:id/verify rejects without artifact, accepts with artifact
• Hard verification rejects without ledger_record_id
• POST /api/tasks/:id/spawn-recommendation creates recommendation and links it
• MCP tools respond correctly via JSON-RPC

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Launched a comprehensive task management system with status workflow (queued, running, needs_review, verified, done, failed).
  • Added Notion webhook integration for automatic task synchronization.
  • Implemented task verification process with artifact and ledger tracking.
  • Enhanced dispute management with stage tracking and additional metadata fields.
  • Added MCP tools for task operations (querying, retrieval, status updates, verification).

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

1. @coderabbitai review
2. @copilot review
3. @codex review
4. @claude review
   Adversarial review request: evaluate security, policy bypass paths, regression risk, and merge-gating bypass attempts.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 17d89fb9-f456-4350-ace2-1be676364968

📥 Commits

Reviewing files that changed from the base of the PR and between d4d1548 and afa2bd2.

📒 Files selected for processing (8)

• migrations/0011_tasks.sql
• src/db/schema.ts
• src/index.ts
• src/lib/cron.ts
• src/lib/validators.ts
• src/routes/mcp.ts
• src/routes/tasks.ts
• ui/src/lib/api.ts

---

📝 Walkthrough

Walkthrough

Introduces a comprehensive task management system including database schema, backend CRUD and state-machine routes, Notion data synchronization, MCP tools, and frontend API layer with validation schemas and type definitions.

Changes

Cohort / File(s)	Summary
Database Schema & Migration migrations/0011_tasks.sql, src/db/schema.ts	Creates new cc_tasks table with comprehensive fields (id, externalId, notionPageId, title, priority, status, verification, assignments, metadata) and six performance indexes. Updates cc_disputes to add stage column. Establishes foreign key relationship to cc_recommendations.
Task Management Routes src/routes/tasks.ts	Implements complete task API: POST /webhook for Notion ingestion, GET / for listing with filters and pagination, GET /:id for task details with action history, PATCH /:id/status for state-machine status updates, POST /:id/verify for verification gate, POST /:id/spawn-recommendation for recommendation creation, with full validation and error handling.
Validation & Type Schemas src/lib/validators.ts	Adds task-related schemas (taskStatusSchema, taskTypeSchema, verificationTypeSchema, createTaskSchema, updateTaskStatusSchema, verifyTaskSchema, spawnRecommendationFromTaskSchema, taskQuerySchema). Refactors dispute validation (introduces disputeStageSchema, disputeStatusSchema) and updates notionWebhookPayloadSchema for nullable due_date.
Notion Synchronization src/lib/cron.ts	Introduces syncNotionTasks() function querying Notion for recently edited pages, parsing Notion properties (Title, Description, Type, Priority, Due Date, Source, Verification, Assigned To), upserting to cc_tasks with conflict handling that preserves terminal states (done/verified). Integrates into Phase 9 cron flow with error handling and logging.
MCP Tool Integration src/routes/mcp.ts	Adds four new JSON-RPC tools (query_tasks, get_task, update_task_status, verify_task) with input validation, state-machine enforcement for transitions, artifact requirements for verification, ledger constraints, and action logging.
API Route Registration src/index.ts	Registers task routes at /api/tasks endpoint and imports taskRoutes module.
UI API Client ui/src/lib/api.ts	Adds task management endpoints (getTasks, getTask, updateTaskStatus, verifyTask, spawnRecommendation), dispute endpoints (createDispute, updateDispute, getDisputeDeadlines), payment plan enqueue, enhanced document upload with dispute linking, and new Task/TaskAction type definitions. Extends Dispute and LegalDeadline types.

Sequence Diagrams

sequenceDiagram
    participant Client as Client/UI
    participant Webhook as POST /webhook
    participant TaskAPI as Task Routes
    participant DB as Database
    
    Client->>Webhook: Send Notion payload
    Webhook->>TaskAPI: Parse & validate payload
    TaskAPI->>DB: Upsert cc_tasks by external_id
    DB->>DB: Check if terminal state exists
    DB->>TaskAPI: Return created/updated task
    TaskAPI->>Client: 201 Created with task

Loading

sequenceDiagram
    participant Client as Client/MCP
    participant TaskAPI as Task Routes
    participant StateMachine as State Machine
    participant DB as Database
    participant ActionLog as cc_actions_log
    
    Client->>TaskAPI: PATCH /:id/status
    TaskAPI->>StateMachine: Validate transition
    alt Invalid Transition
        StateMachine->>TaskAPI: Return 422 error
        TaskAPI->>Client: Error response
    else Valid Transition
        StateMachine->>TaskAPI: Transition allowed
        TaskAPI->>DB: Update cc_tasks status
        TaskAPI->>ActionLog: Log state transition
        DB->>TaskAPI: Confirm update
        ActionLog->>TaskAPI: Confirm log
        TaskAPI->>Client: Updated task response
    end

Loading

sequenceDiagram
    participant Cron as Cron Job
    participant Notion as Notion API
    participant Parser as Property Parser
    participant DB as Database
    
    Cron->>Notion: Query pages (last 25 hours)
    Notion->>Cron: Return page batch
    Cron->>Parser: Extract page properties
    Parser->>Parser: Map Notion fields to task fields
    Parser->>Cron: Return parsed task data
    Cron->>DB: Upsert cc_tasks with conflict handling
    DB->>DB: Preserve terminal state fields
    DB->>Cron: Confirmation
    Cron->>Cron: Log sync completion

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 Hoppy tasks in queues we've made,
State machines through states cascade,
Notion syncs with careful grace,
Tasks now have their proper place!
From verification to the done,
A task-filled journey's just begun! 🚀

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/task-system

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}