fix: tasks REST assignee end-to-end on numeric assigneeId

The REST tasks API had a 3-way mismatch that silently broke the entire assignee
feature for any client going through HTTP (the MCP path was correct):

  1. createTaskSchema validated 'assignee: string' but the handler destructured
     'assigneeId' from req.body — so the value was always undefined.
  2. UI sent 'assignee: <slug-string>' which Zod silently dropped (extra key
     stripped, no error).
  3. Even if the value reached the store, TaskRecord.assigneeId is a numeric
     FK to team_members.id, but the production /team endpoint returned the
     config-user slug as 'id' (string), and the team_members table itself was
     never populated by any production code path.

Fix the whole pipeline on numeric IDs:

* TeamStore: add upsertBySlug() — idempotent insert/update by slug.
* /api/projects/:id/team: source members from config users or .team/{slug}.md
  files, upsert each into team_members, and return { id: number, slug, name,
  email }. This finally wires the team_members table into production.
* validation.ts: createTaskSchema/updateTaskSchema take assigneeId (number,
  nullable, optional). taskListSchema takes assigneeId (coerced number).
* tasks.ts handler: pass assigneeId straight through, no string coercion.
* UI Task type: assignee: string → assigneeId: number | null.
* UI TeamMember: id: string → id: number, plus slug: string.
* TaskForm / QuickCreateDialog / [taskId].tsx / list.tsx / board.tsx /
  summary.tsx / new.tsx / groupConfig.ts: Select stores numeric value, all
  filtering, sorting, grouping and team lookups go through numeric ids. The
  URL filter param key remains 'assignee' (Number(filters.assignee) at point
  of use) so existing bookmarks stay functional.
* P19.14: end-to-end test that writes .team/qa-bot.md, hits /team to trigger
  the upsert, creates a task with the resulting numeric id, round-trips on
  GET, filters via ?assigneeId=N, and exercises null clear / restore via PUT.
* P3 'Create task with all optional fields': drop the dead 'assignee: alice'
  argument that the schema was silently stripping anyway.

All 1580 Jest tests + all 499 sandbox tests pass.

Author: prih

demo-projects/test-sandbox/tests/03-tasks.ts

@@ -487,7 +487,6 @@ test('Create task with all optional fields', async () => {
     tags: ['full', 'test'],
     dueDate: now + 86400000,
     estimate: 8,
-    assignee: 'alice',
     order: 42,
   });
   assertOk(res);

demo-projects/test-sandbox/tests/19-coverage-gaps.ts

@@ -13,7 +13,7 @@
 
 import {
   group, test, runPhase,
-  get, post, del,
+  get, post, put, del,
   mcpCall,
   assert, assertEqual, assertExists, assertOk, assertStatus, assertMcpOk,
   printSummary, runStandalone, wait,
@@ -680,6 +680,83 @@ test('Cleanup cross-graph file-link fixtures', async () => {
   await del(`/tasks/${linkedTaskId}`);
 });
 
+// ─── 19.14 Tasks assignee end-to-end (numeric assigneeId) ────────
+//
+// Verifies the full pipeline:
+//   .team/{slug}.md  →  GET /team (upserts into team_members table, returns numeric id)
+//   POST /tasks { assigneeId } → store
+//   GET /tasks/:id → assigneeId round-trips
+//   GET /tasks?assigneeId=N → filter
+// Replaces the historically broken `assignee: <slug>` REST field which was
+// silently dropped because the validation schema accepted it but the handler
+// read a different key.
+
+group('19.14 Tasks assignee end-to-end (numeric assigneeId)');
+
+let assigneeMemberId: number;
+let assigneeTaskId: number;
+const TEAM_FILE = projectPath('.team', 'qa-bot.md');
+
+test('Setup: write .team/qa-bot.md and trigger /team upsert', async () => {
+  // Standalone mode reads team members from `.team/{slug}.md` in the project dir.
+  const { mkdirSync } = await import('fs');
+  mkdirSync(projectPath('.team'), { recursive: true });
+  writeFileSync(TEAM_FILE, '---\nname: QA Bot\nemail: qa@test.dev\n---\n# QA Bot\n', 'utf-8');
+
+  const res = await get('/team');
+  assertOk(res);
+  const members = res.data.results ?? res.data;
+  assert(Array.isArray(members), 'team is array');
+  const qa = members.find((m: any) => m.slug === 'qa-bot');
+  assertExists(qa, 'qa-bot in team listing');
+  assert(typeof qa.id === 'number' && qa.id > 0, 'team member id is positive number');
+  assertEqual(qa.name, 'QA Bot', 'name');
+  assigneeMemberId = qa.id;
+});
+
+test('POST /tasks with numeric assigneeId persists the assignment', async () => {
+  const res = await post('/tasks', {
+    title: 'Assigned Task',
+    description: 'has an assignee',
+    priority: 'medium',
+    assigneeId: assigneeMemberId,
+  });
+  assertOk(res);
+  assertEqual(res.data.assigneeId, assigneeMemberId, 'assigneeId in create response');
+  assigneeTaskId = res.data.id;
+});
+
+test('GET /tasks/:id round-trips assigneeId', async () => {
+  const res = await get(`/tasks/${assigneeTaskId}`);
+  assertOk(res);
+  assertEqual(res.data.assigneeId, assigneeMemberId, 'assigneeId on read');
+});
+
+test('GET /tasks?assigneeId=N filters by numeric assigneeId', async () => {
+  const res = await get(`/tasks?assigneeId=${assigneeMemberId}`);
+  assertOk(res);
+  const items = res.data.results ?? res.data;
+  assert(Array.isArray(items) && items.length > 0, 'at least one task in filter');
+  assert(items.every((t: any) => t.assigneeId === assigneeMemberId), 'all results have matching assigneeId');
+});
+
+test('PUT /tasks/:id with assigneeId=null unassigns', async () => {
+  const res = await put(`/tasks/${assigneeTaskId}`, { assigneeId: null });
+  assertOk(res);
+  assertEqual(res.data.assigneeId, null, 'assigneeId cleared on update');
+});
+
+test('PUT /tasks/:id with assigneeId restores assignment', async () => {
+  const res = await put(`/tasks/${assigneeTaskId}`, { assigneeId: assigneeMemberId });
+  assertOk(res);
+  assertEqual(res.data.assigneeId, assigneeMemberId, 'assigneeId restored');
+});
+
+test('Cleanup assignee fixtures', async () => {
+  await del(`/tasks/${assigneeTaskId}`);
+  try { unlinkSync(TEAM_FILE); } catch { /* ignore */ }
+});
+
 // ─── Run ─────────────────────────────────────────────────────────
 
 export async function run() {

src/api/rest/index.ts

@@ -405,17 +405,26 @@ export function createRestApp(projectManager: ProjectManager, options?: RestAppO
       );
       if (!hasAnyAccess) return res.status(403).json({ error: 'Access denied' });
     }
-    // When auth is configured, team = users from config (no .team/ files needed)
+    // Source members from config (auth) or .team/ markdown (no auth), then sync
+    // them into the team_members table so the rest of the system has stable
+    // numeric IDs to reference (tasks.assigneeId is a FK into team_members.id).
+    type SourceMember = { slug: string; name: string; email: string | null };
+    let source: SourceMember[];
     if (hasUsers) {
-      const members = Object.entries(users).map(([id, u]) => ({ id, name: u.name, email: u.email }));
-      return res.json({ results: members });
+      source = Object.entries(users).map(([slug, u]) => ({ slug, name: u.name, email: u.email ?? null }));
+    } else {
+      const p = req.project!;
+      const ws = p.workspaceId ? projectManager.getWorkspace(p.workspaceId) : undefined;
+      const baseDir = ws ? ws.config.mirrorDir : p.config.projectDir;
+      source = scanTeamDir(path.join(baseDir, '.team')).map(m => ({ slug: m.id, name: m.name, email: m.email || null }));
     }
-    // No auth — read from .team/ directory
-    const p = req.project!;
-    const ws = p.workspaceId ? projectManager.getWorkspace(p.workspaceId) : undefined;
-    const baseDir = ws ? ws.config.mirrorDir : p.config.projectDir;
-    const members = scanTeamDir(path.join(baseDir, '.team'));
-    res.json({ results: members });
+
+    const teamStore = req.project!.storeManager.store.team;
+    const results = source.map(m => {
+      const rec = teamStore.upsertBySlug({ slug: m.slug, name: m.name, email: m.email ?? undefined });
+      return { id: rec.id, slug: rec.slug, name: rec.name, email: rec.email ?? '' };
+    });
+    res.json({ results });
   });
 
   // Middleware: require a specific manager to be enabled, or return 404

src/api/rest/tasks.ts

@@ -85,7 +85,7 @@ export function createTasksRouter(_users?: Record<string, unknown>): Router {
           tags,
           dueDate,
           estimate,
-          assigneeId: assigneeId != null ? Number(assigneeId) : undefined,
+          assigneeId,
           order,
         });
       });

src/api/rest/validation.ts

@@ -8,7 +8,6 @@ import {
   MAX_SEARCH_QUERY_LEN,
   MAX_SEARCH_TOP_K,
   MAX_DESCRIPTION_LEN,
-  MAX_ASSIGNEE_LEN,
   MAX_SKILL_STEP_LEN,
   MAX_SKILL_STEPS_COUNT,
   MAX_SKILL_TRIGGER_LEN,
@@ -95,7 +94,7 @@ export const createTaskSchema = z.object({
   tags:        z.array(z.string().max(MAX_TAG_LEN)).max(MAX_TAGS_COUNT).optional().default([]),
   dueDate:     z.number().nullable().optional(),
   estimate:    z.number().nullable().optional(),
-  assignee:    z.string().max(MAX_ASSIGNEE_LEN).nullable().optional(),
+  assigneeId:  z.number().int().positive().nullable().optional(),
   order:       z.number().int().optional(),
 });
 
@@ -108,7 +107,7 @@ export const updateTaskSchema = z.object({
   order:       z.number().int().optional(),
   dueDate:     z.number().nullable().optional(),
   estimate:    z.number().nullable().optional(),
-  assignee:    z.string().max(MAX_ASSIGNEE_LEN).nullable().optional(),
+  assigneeId:  z.number().int().positive().nullable().optional(),
   version:     z.number().int().positive().optional(),
 });
 
@@ -156,13 +155,13 @@ export const taskSearchSchema = z.object({
 });
 
 export const taskListSchema = z.object({
-  status:   z.enum(['backlog', 'todo', 'in_progress', 'review', 'done', 'cancelled']).optional(),
-  priority: z.enum(['critical', 'high', 'medium', 'low']).optional(),
-  tag:      z.string().max(MAX_TAG_LEN).optional(),
-  filter:   z.string().max(500).optional(),
-  assignee: z.string().max(MAX_ASSIGNEE_LEN).optional(),
-  limit:    z.coerce.number().int().positive().max(1000).optional(),
-  offset:   z.coerce.number().int().min(0).max(100_000).optional().default(0),
+  status:     z.enum(['backlog', 'todo', 'in_progress', 'review', 'done', 'cancelled']).optional(),
+  priority:   z.enum(['critical', 'high', 'medium', 'low']).optional(),
+  tag:        z.string().max(MAX_TAG_LEN).optional(),
+  filter:     z.string().max(500).optional(),
+  assigneeId: z.coerce.number().int().positive().optional(),
+  limit:      z.coerce.number().int().positive().max(1000).optional(),
+  offset:     z.coerce.number().int().min(0).max(100_000).optional().default(0),
 });
 
 // ---------------------------------------------------------------------------

src/store/sqlite/stores/team.ts

@@ -84,6 +84,20 @@ export class SqliteTeamStore implements TeamStore {
     return row ? this.toRecord(row) : null;
   }
 
+  upsertBySlug(data: TeamMemberCreate): TeamMemberRecord {
+    const existing = this.getBySlug(data.slug);
+    if (existing) {
+      // Only patch fields that differ to avoid bumping updated_at unnecessarily.
+      const patch: TeamMemberPatch = {};
+      if (data.name !== existing.name) patch.name = data.name;
+      if ((data.email ?? null) !== existing.email) patch.email = data.email;
+      if ((data.role ?? null) !== existing.role) patch.role = data.role;
+      if (Object.keys(patch).length > 0) return this.update(existing.id, patch);
+      return existing;
+    }
+    return this.create(data);
+  }
+
   list(pagination?: PaginationOptions): { results: TeamMemberRecord[]; total: number } {
     const limit = pagination?.limit ?? 50;
     const offset = pagination?.offset ?? 0;

src/store/types/team.ts

@@ -33,5 +33,13 @@ export interface TeamStore extends MetaMixin {
   delete(memberId: number): void;
   get(memberId: number): TeamMemberRecord | null;
   getBySlug(slug: string): TeamMemberRecord | null;
+  /**
+   * Idempotent insert/update by slug. If a member with the slug exists, updates
+   * name/email/role from data; otherwise creates a new row. Returns the resulting
+   * record (with numeric id). Used to sync external sources (config users, .team/
+   * markdown files) into the database so the rest of the system has stable
+   * numeric IDs to reference.
+   */
+  upsertBySlug(data: TeamMemberCreate): TeamMemberRecord;
   list(pagination?: PaginationOptions): { results: TeamMemberRecord[]; total: number };
 }

ui/src/content/help/guides/task-tools.md

@@ -42,7 +42,7 @@ Tasks here are tightly integrated with your project's knowledge graph:
 | `tags` | string[] | Free-form | For filtering |
 | `dueDate` | number | Unix timestamp in milliseconds | Optional deadline |
 | `estimate` | number | Hours | Optional effort estimate |
-| `assignee` | string \| null | Team member ID | Optional assignee from `users:` config |
+| `assigneeId` | number \| null | Numeric team member id (from `/api/projects/:id/team`) | Optional assignee |
 | `completedAt` | number | Unix timestamp (auto-managed) | Set on done/cancelled, cleared on reopen |
 | `createdAt` | number | Unix timestamp (auto) | Set at creation |
 | `updatedAt` | number | Unix timestamp (auto) | Updated on every change |
@@ -68,7 +68,7 @@ Create a new task. Automatically embedded for semantic search.
 | `tags` | string[] | No | `[]` | Tags for filtering |
 | `dueDate` | number | No | — | Due date as Unix timestamp in milliseconds |
 | `estimate` | number | No | — | Estimated effort in hours |
-| `assignee` | string | No | — | Team member ID to assign the task to |
+| `assigneeId` | number | No | — | Numeric team member id to assign the task to |
 
 **Returns:** `{ taskId }`
 
@@ -86,7 +86,7 @@ Update an existing task. Only provided fields change. Re-embeds if title or desc
 | `tags` | string[] | No | Replace tags array (include all you want to keep) |
 | `dueDate` | number \| null | No | New due date (ms timestamp), or `null` to clear |
 | `estimate` | number \| null | No | New estimate (hours), or `null` to clear |
-| `assignee` | string \| null | No | Team member ID to assign, or `null` to unassign |
+| `assigneeId` | number \| null | No | Numeric team member id to assign, or `null` to unassign |
 
 **Returns:** `{ taskId, updated: true }`
 
@@ -113,7 +113,7 @@ Return full task details including all relations. This is the most complete view
 **Returns:**
 ```
 {
-  id, title, description, status, priority, tags, assignee,
+  id, title, description, status, priority, tags, assigneeId,
   dueDate, estimate, completedAt, createdAt, updatedAt,
   subtasks: [{ id, title, status }],
   blockedBy: [{ id, title, status }],
@@ -134,10 +134,10 @@ List tasks with optional filters. Sorted by priority (critical → low) then due
 | `priority` | enum | No | — | Filter by priority |
 | `tag` | string | No | — | Filter by tag (exact match, case-insensitive) |
 | `filter` | string | No | — | Substring match on title or ID |
-| `assignee` | string | No | — | Filter by assignee (team member ID) |
+| `assigneeId` | number | No | — | Filter by numeric team member id |
 | `limit` | number | No | 50 | Maximum results |
 
-**Returns:** `[{ id, title, description, status, priority, tags, dueDate, estimate, assignee, completedAt, createdAt, updatedAt }]`
+**Returns:** `[{ id, title, description, status, priority, tags, dueDate, estimate, assigneeId, completedAt, createdAt, updatedAt }]`
 
 ### tasks_search
 

ui/src/entities/project/api.ts

@@ -41,7 +41,10 @@ export function getProjectStats(projectId: string) {
 }
 
 export interface TeamMember {
-  id: string;
+  /** Numeric id from the team_members table — stable across slug renames. */
+  id: number;
+  /** Human-readable identifier (matches user config key or .team/{slug}.md filename). */
+  slug: string;
   name: string;
   email: string;
 }

ui/src/entities/task/api.ts

@@ -14,30 +14,30 @@ export interface Task {
   dueDate: number | null;
   estimate: number | null;
   completedAt: number | null;
-  assignee: string | null;
+  assigneeId: number | null;
   createdAt: number;
   updatedAt: number;
   version: number;
   createdBy?: string;
   updatedBy?: string;
 }
 
-export function listTasks(projectId: string, params?: { status?: TaskStatus; priority?: TaskPriority; tag?: string; assignee?: string; limit?: number; offset?: number }) {
-  return request<PaginatedResponse<Task>>(`/projects/${projectId}/tasks${qs({ status: params?.status, priority: params?.priority, tag: params?.tag, assignee: params?.assignee, limit: params?.limit, offset: params?.offset })}`).then(unwrapPaginated);
+export function listTasks(projectId: string, params?: { status?: TaskStatus; priority?: TaskPriority; tag?: string; assigneeId?: number; limit?: number; offset?: number }) {
+  return request<PaginatedResponse<Task>>(`/projects/${projectId}/tasks${qs({ status: params?.status, priority: params?.priority, tag: params?.tag, assigneeId: params?.assigneeId, limit: params?.limit, offset: params?.offset })}`).then(unwrapPaginated);
 }
 
 export function getTask(projectId: string, taskId: string) {
   return request<Task>(`/projects/${projectId}/tasks/${taskId}`);
 }
 
-export function createTask(projectId: string, data: { title: string; description?: string; status?: TaskStatus; priority?: TaskPriority; tags?: string[]; dueDate?: number | null; estimate?: number | null; assignee?: string | null }) {
+export function createTask(projectId: string, data: { title: string; description?: string; status?: TaskStatus; priority?: TaskPriority; tags?: string[]; dueDate?: number | null; estimate?: number | null; assigneeId?: number | null }) {
   return request<Task>(`/projects/${projectId}/tasks`, {
     method: 'POST',
     body: JSON.stringify(data),
   });
 }
 
-export function updateTask(projectId: string, taskId: string, data: Partial<Pick<Task, 'title' | 'description' | 'status' | 'priority' | 'tags' | 'dueDate' | 'estimate' | 'assignee'>>) {
+export function updateTask(projectId: string, taskId: string, data: Partial<Pick<Task, 'title' | 'description' | 'status' | 'priority' | 'tags' | 'dueDate' | 'estimate' | 'assigneeId'>>) {
   return request<Task>(`/projects/${projectId}/tasks/${taskId}`, {
     method: 'PUT',
     body: JSON.stringify(data),