Functional Specification Document: TaskPilot

Formal Specification: Personal & Team Task Management Foundation (v2.0)

A task management system designed for immediate personal use with foundational multi-tenant architecture for ChainAlign team scaling. Features FSD-aware task generation, session continuity through checkpointing, and live progress dashboards for demos and standups.

Feature Name	TaskPilot
Component Layer	Internal Productivity Tool + Product Foundation
Status	Final Design (Ready for Implementation)
Core Goal	Provide immediate personal task management while building foundational system for team collaboration and demo visibility
Primary Metrics	Session resume time <30s, zero manual task-FSD sync, live milestone dashboard, team-ready architecture

1. Executive Summary & Strategic Context

TaskPilot solves three immediate problems:

Personal Productivity Crisis: You're blocked without a proper task manager (tasks.md at 3000+ lines, unmanageable)
Session Continuity: Context reloading consumes 50% of session tokens reading FSD/docs
Demo Readiness: Need "show my process" dashboard for investor/stakeholder presentations

The system is designed with forward vision for ChainAlign team scaling:

Multi-tenant architecture from day 1
FSD ↔ Task bidirectional linking (foundation for future Judgment Engine)
Live milestone progress visibility (demo + internal dashboard)
Milestone-scoped document storage (FSD, dev summary, TDD summary)

Design Decisions (Validated Nov 2, 2025)

✅ Decision 1: Judgment Engine integration deferred to Phase 2+ ✅ Decision 2: Demo-ready milestone progress dashboard included in Phase 1 ✅ Decision 3: Tasks link to Milestones as primary ChainAlign entity

2. System Architecture

2.1 High-Level Data Flow

[Web UI (React)]          [CLI Wrapper]           [File Upload]
(text, forms, files)      (task commands)         (.md, .txt)
      |                         |                       |
      └─────────────────┬───────┴───────────────────────┘
                        V
            [API Gateway + Auth (Better Auth)]
                        |
                        V
         [GraphQL Server (Apollo Server)]
              |                    |
        ┌─────┴────────┐      ┌────┴─────┐
        V              V      V           V
   [Task Service]  [Session   [Milestone [Search &
                  Manager]   Documents] Analytics]
        |              |          |           |
        └──────┬───────┴──────────┴───────────┘
               V
       [Unified Data Plane]
            |          |
       [PostgreSQL] [pgvector]
       - tasks      - semantic search
       - milestones - session context
       - sessions
       - documents

2.2 Core Components

Client Layer:

Web UI (React): Primary interface for task management, milestone views, session resume
CLI Tool: For quick task ops (task add, task done, task list)
File Ingestion: Upload markdown/text files as task context

Backend Layer:

GraphQL Server: Task CRUD, milestone aggregation, session management
FSD Parser Service: Extract tasks from FSD documents (Phase 2+)
Session Manager: Checkpoint/resume context preservation

Data Layer:

PostgreSQL: All structured data (tasks, milestones, sessions, documents)
Vector Storage: Semantic search on task content (Phase 2+)

3. Database Schema (MVP)

3.1 Core Tables

`tasks`

CREATE TABLE tasks (
  task_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID NOT NULL REFERENCES tenants(tenant_id),
  pseudo_id VARCHAR(50) UNIQUE,  -- M56-001, M56-002, etc.

  -- Content
  title TEXT NOT NULL,
  description TEXT,

  -- Organization
  project VARCHAR(255) NOT NULL,
  milestone VARCHAR(100) NOT NULL,  -- M56, M57, etc.
  status VARCHAR(50) NOT NULL DEFAULT 'pending',
  priority VARCHAR(20),

  -- Hierarchy
  parent_task_id UUID REFERENCES tasks(task_id),
  depends_on UUID[],

  -- Implementation Tracking
  implementation_status JSONB DEFAULT '{
    "files_modified": [],
    "fsd_sections_completed": [],
    "last_checkpoint": null,
    "verified": false
  }',

  -- Scheduling
  due_date TIMESTAMPTZ,
  started_at TIMESTAMPTZ,
  completed_at TIMESTAMPTZ,

  -- Effort
  estimated_hours NUMERIC(5,2),
  actual_hours NUMERIC(5,2),

  -- Metadata
  tags TEXT[] DEFAULT '{}',
  created_by_user_id UUID NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  CONSTRAINT valid_status CHECK (status IN (
    'pending', 'in_progress', 'completed', 'blocked', 'cancelled'
  ))
);

CREATE INDEX idx_tasks_tenant_id ON tasks(tenant_id);
CREATE INDEX idx_tasks_milestone ON tasks(milestone);
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_pseudo_id ON tasks(pseudo_id);

`milestones`

CREATE TABLE milestones (
  milestone_id VARCHAR(50) PRIMARY KEY,  -- M56
  project VARCHAR(255) NOT NULL,
  tenant_id UUID NOT NULL REFERENCES tenants(tenant_id),

  -- Document Links (Phase 1 schema prep, Phase 2 implementation)
  fsd_document_id UUID REFERENCES source_documents(id),
  dev_summary_id UUID REFERENCES source_documents(id),
  tdd_summary_id UUID REFERENCES source_documents(id),

  -- Approval Status
  fsd_approved_at TIMESTAMPTZ,
  fsd_approved_by UUID REFERENCES users(user_id),

  -- Progress Tracking
  tasks_completed INT DEFAULT 0,
  tasks_total INT DEFAULT 0,

  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_milestones_tenant_id ON milestones(tenant_id);

`work_sessions`

CREATE TABLE work_sessions (
  session_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(user_id),
  task_id UUID REFERENCES tasks(task_id),
  milestone VARCHAR(50),

  -- Context Preservation
  fsd_section TEXT,
  files_in_progress TEXT[],
  last_command TEXT,
  cursor_position JSONB,
  git_branch VARCHAR(255),
  git_commit_sha VARCHAR(40),

  -- Summary
  session_summary TEXT,
  token_budget_used INT,
  context_preserved JSONB,

  -- Timing
  started_at TIMESTAMPTZ DEFAULT NOW(),
  ended_at TIMESTAMPTZ,
  ended_reason VARCHAR(50)
);

CREATE INDEX idx_work_sessions_user_id ON work_sessions(user_id);
CREATE INDEX idx_work_sessions_active ON work_sessions(user_id, ended_at)
  WHERE ended_at IS NULL;

`task_comments`

CREATE TABLE task_comments (
  comment_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  task_id UUID NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
  user_id UUID NOT NULL REFERENCES users(user_id),
  content TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_task_comments_task_id ON task_comments(task_id);

4. Implementation Roadmap

Phase 1: MVP Web Backend + UI + Dashboard (2 weeks)

Deliverables:

PostgreSQL schema (tasks, milestones, sessions, comments)
Pseudo-ID generation (M56-001, M56-002, etc.)
GraphQL API (task CRUD, milestone views, session management)
React Web UI with:
- Task list/board/tree views
- Create/edit/complete tasks
- Session resume banner
- Live Milestone Progress Dashboard (new: shows M56: 10/23 tasks, etc.)
CLI wrapper for quick task ops
Better Auth integration
Pseudo-ID generation function
Document schema prep (milestones table with *_document_id fields)

What you'll have by end of Week 1:

Working task manager for personal use
Live demo dashboard showing your process
Ready for team onboarding (multi-tenant ready)

Success Criteria:

✅ Create, edit, complete 20+ tasks in milestone
✅ Session resume <30 seconds
✅ Dashboard accurately reflects milestone progress
✅ CLI commands work for rapid entry

Phase 2: Document Linking + FSD Import (Weeks 3-4)

New Capabilities:

Milestone documents (FSD, dev summary, TDD summary)
FSD parser to auto-generate tasks from markdown
Gap detection (which FSD sections lack tasks)
Document linking UI (view/edit milestone documents)

Implementation:

FSD parser service
Milestone document endpoints
Gap detection GraphQL queries
Document upload/linking UI

Phase 3: iOS App + Offline Sync (Weeks 5-6)

Deferred to later. When needed for mobile capture, add:

SwiftUI iOS app
Core Data offline storage
Bidirectional sync
Push notifications

Phase 4+: Future (Post-MVP)

Judgment Engine integration (decisions as meta-layer)
Advanced AI analysis (entity extraction, intent classification)
Graph store for decision lineage
Team collaboration features (assignments, comments, @mentions)
Integration APIs (Slack, GitHub, Zoom)

5. GraphQL Schema (MVP)

Core Types

type Task {
  taskId: ID!
  pseudoId: String
  title: String!
  description: String
  project: String!
  milestone: String!
  status: TaskStatus!
  priority: TaskPriority

  parentTask: Task
  subtasks: [Task!]!
  dependencies: [Task!]!

  dueDate: DateTime
  startedAt: DateTime
  completedAt: DateTime

  estimatedHours: Float
  actualHours: Float

  tags: [String!]!
  comments: [TaskComment!]!

  createdAt: DateTime!
  updatedAt: DateTime!
}

type Milestone {
  milestoneId: String!
  project: String!
  tasks: [Task!]!
  taskCount: Int!
  completedCount: Int!
  progress: Float!

  fsdDocument: Document
  devSummary: Document
  tddSummary: Document
  fsdApprovedAt: DateTime
}

type WorkSession {
  sessionId: ID!
  task: Task
  milestone: String
  fsdSection: String
  filesInProgress: [String!]!
  lastWorked: String!
  lastSummary: String
  suggestedNext: [String!]!
  summary: String!
  tokenEstimate: Int!
}

enum TaskStatus {
  PENDING
  IN_PROGRESS
  COMPLETED
  BLOCKED
  CANCELLED
}

enum TaskPriority {
  LOW
  MEDIUM
  HIGH
  CRITICAL
}

Key Queries

type Query {
  tasks(project: String, milestone: String, status: TaskStatus): [Task!]!
  task(taskId: ID!): Task
  taskByPseudoId(pseudoId: String!): Task

  milestones(project: String!): [Milestone!]!
  milestone(milestoneId: String!): Milestone

  resumeContext: WorkSession
  sessionHistory(limit: Int): [WorkSession!]!
}

Key Mutations

type Mutation {
  createTask(input: CreateTaskInput!): Task!
  updateTask(taskId: ID!, input: UpdateTaskInput!): Task!
  completeTask(taskId: ID!, actualHours: Float): Task!

  checkpointSession(input: CheckpointInput!): WorkSession!
}

6. CLI Interface

# Task Management
task add -p chainalign -m M56 "Implement GraphQL schema"
task list -m M56
task done M56-001 --hours 4
task start M56-002
task modify M56-003 --priority high

# Resume
task resume

# Document Linking (Phase 2)
task link-fsd M56 docs/M56-architecture.md
task gaps M56

7. UI Mockup Components

Primary Views:

Task List (with filtering by milestone, status, priority)
Milestone Board (showing M56: 10/23 tasks, progress bar)
Task Detail (with comments, history, related docs)
Session Resume Banner (top of dashboard)
Dashboard (live milestone progress for demos)

ChainAlign Brand Integration:

Navy (#0B1D3A) headers
Signal Green (#00D084) for actions
Inter font
8px spacing grid
Clean, data-focused layout

8. Authentication & Multi-Tenancy

Auth Provider: Better Auth (self-hosted, OAuth ready)
Token Exchange: Secure endpoint for internal token generation
Tenant Isolation: All queries filtered by tenant_id immutably
Audit Logging: All task changes logged to system_audit_log

9. Success Criteria (Phase 1)

✅ You use it daily for actual M56+ task management
✅ Session resume time <30 seconds
✅ Can show live milestone progress in demos
✅ Web UI is responsive and intuitive
✅ Can onboard team member with zero changes to codebase (multi-tenant ready)
✅ Zero data loss during normal operation

10. Risk Mitigation

Risk	Mitigation
Token limit during implementation	Session checkpointing + resume banner keeps context <500 tokens
Multi-tenant data leakage	Row-level security via PostgreSQL policies + immutable tenant_id scoping
Performance at scale	Indexed queries, pagination, pagination on all list endpoints
Scope creep	Phase boundaries enforced; document linking & iOS deferred to Phases 2-3

11. Deployment & Integration

Hosting:

PostgreSQL: Supabase (existing ChainAlign database)
GraphQL: Same Node backend as ChainAlign (port 4000 new path)
Web UI: Embedded in ChainAlign frontend under /admin/tasks or standalone

Future ChainAlign Integration:

Embed task widget in dashboard
Link to M36 Judgment Engine (Phase 2+)
Team member onboarding without code changes
Notification integration via existing WebSocket layer

Approval & Sign-off

Role	Name	Status
Author	Pramod Prasanth	✅ Approved
Validated Design	Brainstorming Session	✅ Nov 2, 2025
Ready for Implementation	Phase 1	✅ GO

Document Version History

Version	Date	Status
1.0	Nov 2, 2025	Research & Planning
2.0	Nov 2, 2025	Final Design (Validated)

Formal Specification: Personal & Team Task Management Foundation (v2.0)​

1. Executive Summary & Strategic Context​

Design Decisions (Validated Nov 2, 2025)​

2. System Architecture​

2.1 High-Level Data Flow​

2.2 Core Components​

3. Database Schema (MVP)​

3.1 Core Tables​

tasks​

milestones​

work_sessions​

task_comments​

4. Implementation Roadmap​

Phase 1: MVP Web Backend + UI + Dashboard (2 weeks)​

Phase 2: Document Linking + FSD Import (Weeks 3-4)​

Phase 3: iOS App + Offline Sync (Weeks 5-6)​

Phase 4+: Future (Post-MVP)​

5. GraphQL Schema (MVP)​

Core Types​

Key Queries​

Key Mutations​

6. CLI Interface​

7. UI Mockup Components​

8. Authentication & Multi-Tenancy​

9. Success Criteria (Phase 1)​

10. Risk Mitigation​

11. Deployment & Integration​

Approval & Sign-off​