# PRD: mosaic-queue

**Version:** 0.0.1
**Status:** Approved
**Source:** ~/src/jarvis-brain/docs/planning/MOSAIC-QUEUE-PRD.md

---

## Problem Statement

Current task management relies on HEARTBEAT.md + MEMORY.md files (fragile, manual), with no cross-agent coordination, no transactional guarantees, state lost on session crash/compaction, and AI drift in task state management.

## Solution

A Valkey/Redis-backed task queue exposed via MCP (and optional REST), providing atomic task claims with TTL, cross-agent visibility, crash recovery, and zero AI involvement in state management.

## Core Interface

### Task Schema
```typescript
interface Task {
  id: string;
  project: string;
  mission: string;
  taskId: string;
  title: string;
  description?: string;
  status: 'pending' | 'claimed' | 'in-progress' | 'completed' | 'failed' | 'blocked';
  priority: 'critical' | 'high' | 'medium' | 'low';
  dependencies: string[];
  lane: 'planning' | 'coding' | 'any';
  claimedBy?: string;
  claimedAt?: number;
  claimTTL?: number;
  completedAt?: number;
  failedAt?: number;
  failureReason?: string;
  retryCount: number;
  metadata?: object;
  createdAt: number;
  updatedAt: number;
}
```

### CLI Commands (Phase 1)
```bash
mosaic queue create <project> <mission> <taskId> --title "..." [--priority high] [--lane coding]
mosaic queue list [--project X] [--mission Y] [--status pending]
mosaic queue show <taskId>
mosaic queue claim <taskId> --agent <agentId> --ttl 3600
mosaic queue heartbeat <taskId>
mosaic queue release <taskId>
mosaic queue complete <taskId> [--summary "..."]
```

### MCP Tools (Phase 1)
- `queue_list` — list tasks with filters
- `queue_get` — single task details
- `queue_claim` — atomic claim
- `queue_heartbeat` — extend TTL
- `queue_release` — release claim
- `queue_complete` — mark complete
- `queue_fail` — mark failed with reason
- `queue_status` — queue health/stats

## State Machine
`pending` → `claimed` (via claim) → `in-progress` (via start) → `completed` | `failed`
`claimed` → `pending` (TTL expiry, via watchdog)

## Configuration
```yaml
redis:
  url: redis://localhost:6379
defaults:
  claimTTL: 3600
  maxRetries: 3
  deadLetterAfter: 3
lanes:
  planning:
    maxConcurrent: 2
  coding:
    maxConcurrent: 4
watchdog:
  interval: 60
openbrain:
  url: ${OPENBRAIN_URL}  # required — no default
  autoCapture: false
```

## Tech Stack
- TypeScript (Node.js)
- ioredis for Valkey/Redis
- @modelcontextprotocol/sdk for MCP server
- commander for CLI
- Valkey instance: existing mosaic-stack deployment

## Phases
- **Phase 1 (this milestone):** Core queue, CLI, MCP server
- **Phase 2:** TTL watchdog, dead letter queue, TASKS.md sync
- **Phase 3:** Coordinator integration, lane enforcement
- **Phase 4:** OpenBrain integration (finding capture)

## Acceptance Criteria (Phase 1)
1. `mosaic queue create` creates a task in Valkey
2. `mosaic queue claim` atomically claims (no double-claim race)
3. `mosaic queue list` filters by project/mission/status
4. `mosaic queue complete` marks done, optionally with summary
5. MCP server exposes all tools above
6. TypeScript strict, ESLint clean, tests green
7. README with setup + usage docs