orizu 0.4.0 → 0.4.1

package/dist/help.js

@@ -450,20 +450,20 @@ export const COMMAND_DOCS = [
     },
     {
         path: ['tasks', 'create'],
-        usage: 'orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]',
-        summary: 'Create a draft review task by default, or publish immediately with --publish and assignees.',
+        usage: 'orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2> | --assignment-file <path>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]',
+        summary: 'Create a draft review task by default, with auto distribution or an explicit row-assignment JSONL file.',
         group: 'Tasks',
     },
     {
         path: ['tasks', 'publish'],
-        usage: 'orizu tasks publish --task <taskId> --assignees <userId1,userId2> [--json]',
+        usage: 'orizu tasks publish --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--json]',
         summary: 'Publish an approved draft task and assign reviewers.',
         group: 'Tasks',
     },
     {
         path: ['tasks', 'assign'],
-        usage: 'orizu tasks assign --task <taskId> --assignees <userId1,userId2>',
-        summary: 'Assign a task to canonical user IDs.',
+        usage: 'orizu tasks assign --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--replace-existing] [--json]',
+        summary: 'Assign a task with auto distribution or an explicit row-assignment JSONL file.',
         group: 'Tasks',
     },
     {

package/dist/index.js

@@ -17,6 +17,7 @@ import { extractErrorMessage } from './error-response.js';
 import { parseGlobalFlags } from './global-flags.js';
 import { getCapabilities, renderHelpForArgs, renderRootHelp } from './help.js';
 import { runLocalAppPreview } from './preview-runtime.js';
+import { parseAssignmentManifestJsonl } from './task-assignment-manifest.js';
 import { assertSecureTokenTransport, authedFetch, getBaseUrl, resolveLoginBaseUrl, setGlobalFlags, } from './http.js';
 import { computeSkillContentHash, getSkillInstallPath, getSkillTargetStatus, getTargetForAgent, installSkillTarget, isSkillInstallAgent, isSkillInstallTarget, resolveSkillSource, SKILL_INSTALL_AGENTS, SKILL_INSTALL_TARGETS, targetNeedsOverwrite, } from './skill-installer.js';
 import { renderBanner } from './banner.js';
@@ -2986,39 +2987,65 @@ function parseCommaSeparated(value) {
         .map(item => item.trim())
         .filter(Boolean);
 }
+function readAssignmentManifest(path) {
+    if (!path) {
+        return null;
+    }
+    const content = readFileSync(expandHomePath(path), 'utf8');
+    return parseAssignmentManifestJsonl(content);
+}
 async function createTask() {
     const projectSlug = getArg('--project');
     const datasetId = getArg('--dataset');
     const appId = getArg('--app');
     const title = getArg('--title');
     const assignees = parseCommaSeparated(getArg('--assignees'));
+    const assignmentFile = getArg('--assignment-file');
     const publish = hasArg('--publish');
     const versionArg = getArg('--version');
     const instructions = getArg('--instructions');
     const labelsPerItemArg = getArg('--labels-per-item');
-    const labelsPerItem = labelsPerItemArg ? Number(labelsPerItemArg) : 1;
+    const parsedLabelsPerItem = labelsPerItemArg ? Number(labelsPerItemArg) : 1;
+    const labelsPerItem = Number.isInteger(parsedLabelsPerItem) && parsedLabelsPerItem > 0
+        ? parsedLabelsPerItem
+        : null;
     const parsedVersionNum = versionArg ? Number(versionArg) : Number.NaN;
     const versionNum = Number.isInteger(parsedVersionNum) && parsedVersionNum > 0 ? parsedVersionNum : null;
-    if (!projectSlug || !datasetId || !appId || !title || (publish && assignees.length === 0)) {
-        throw new Error('Usage: orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]');
+    if (assignmentFile && assignees.length > 0) {
+        throw new Error('Use either --assignment-file or --assignees, not both.');
+    }
+    const explicitAssignments = readAssignmentManifest(assignmentFile);
+    if (!projectSlug || !datasetId || !appId || !title || (publish && assignees.length === 0 && !explicitAssignments)) {
+        throw new Error('Usage: orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2> | --assignment-file <path>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]');
     }
     if (versionArg && versionNum === null) {
         throw new Error('--version must be a positive integer');
     }
+    if (labelsPerItemArg && labelsPerItem === null) {
+        throw new Error('--labels-per-item must be a positive integer');
+    }
+    const requestBody = {
+        projectSlug,
+        datasetId,
+        appId,
+        versionNum,
+        title,
+        publish,
+        instructions,
+    };
+    if (explicitAssignments) {
+        requestBody.explicitAssignments = explicitAssignments;
+    }
+    else {
+        requestBody.memberIds = assignees;
+    }
+    if (!explicitAssignments || labelsPerItemArg) {
+        requestBody.requiredAssignmentsPerRow = labelsPerItem;
+    }
     const response = await authedFetch('/api/cli/tasks', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-            projectSlug,
-            datasetId,
-            appId,
-            versionNum,
-            title,
-            memberIds: assignees,
-            publish,
-            instructions,
-            requiredAssignmentsPerRow: labelsPerItem,
-        }),
+        body: JSON.stringify(requestBody),
     });
     if (!response.ok) {
         const cliError = await formatTaskCreateError(response);
@@ -3041,13 +3068,16 @@ async function createTask() {
             taskUrl: `${getBaseUrl()}/d/${projectSlug}/tasks/${data.task.id}`,
             title: data.task.title,
             status: data.task.status,
+            assignmentMode: explicitAssignments ? 'custom' : 'auto',
             requiredAssignmentsPerRow: data.task.requiredAssignmentsPerRow,
             assignmentsCreated: data.assignmentsCreated,
             draft: data.task.status === 'draft',
             ...(data.task.status === 'draft'
                 ? {
                     message: 'Draft created. Test it manually before assigning.',
-                    publishCommand: `orizu tasks publish --task ${data.task.id} --assignees <userId1,userId2>`,
+                    publishCommand: explicitAssignments
+                        ? `orizu tasks publish --task ${data.task.id} --assignment-file ${assignmentFile ? shellQuote(assignmentFile) : '<path>'}`
+                        : `orizu tasks publish --task ${data.task.id} --assignees <userId1,userId2>`,
                 }
                 : {}),
             ...(data.assignmentShortfall !== undefined ? { assignmentShortfall: data.assignmentShortfall } : {}),
@@ -3062,24 +3092,34 @@ async function createTask() {
         `\n  Task ID:    ${sanitizeTerminalText(data.task.id)}` +
         `\n  Dataset ID: ${sanitizeTerminalText(datasetId)}` +
         `\n  Version:    v${data.task.versionNum} (${sanitizeTerminalText(data.task.versionId)})` +
+        `\n  Mode:       ${explicitAssignments ? 'custom row map' : 'auto distribute'}` +
         `\n  Labels/row: ${data.task.requiredAssignmentsPerRow}` +
         `\n  Assignments: ${data.assignmentsCreated}` +
         (data.warning ? `\n  Warning:    ${sanitizeTerminalText(data.warning)}` : '') +
         `\n  URL:        ${sanitizeTerminalText(taskUrl)}` +
         (isDraft
-            ? `\n\nThis task is a draft. Test it manually before assigning.\nPublish after approval: orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignees <userId1,userId2>`
+            ? `\n\nThis task is a draft. Test it manually before assigning.\nPublish after approval: ${explicitAssignments
+                ? `orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignment-file ${sanitizeTerminalText(assignmentFile || '<path>')}`
+                : `orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignees <userId1,userId2>`}`
             : ''));
 }
 async function publishTask() {
     const taskId = getArg('--task');
     const assignees = parseCommaSeparated(getArg('--assignees'));
-    if (!taskId || assignees.length === 0) {
-        throw new Error('Usage: orizu tasks publish --task <taskId> --assignees <userId1,userId2> [--json]');
+    const assignmentFile = getArg('--assignment-file');
+    if (assignmentFile && assignees.length > 0) {
+        throw new Error('Use either --assignment-file or --assignees, not both.');
+    }
+    const explicitAssignments = readAssignmentManifest(assignmentFile);
+    if (!taskId || (assignees.length === 0 && !explicitAssignments)) {
+        throw new Error('Usage: orizu tasks publish --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--json]');
     }
     const response = await authedFetch(`/api/cli/tasks/${encodeURIComponent(taskId)}/publish`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ memberIds: assignees }),
+        body: JSON.stringify(explicitAssignments
+            ? { explicitAssignments }
+            : { memberIds: assignees }),
     });
     if (!response.ok) {
         throw new Error(`Failed to publish task: ${await extractErrorMessage(response)}`);
@@ -3089,6 +3129,7 @@ async function publishTask() {
         printLine(JSON.stringify({
             taskId: data.task.id,
             status: data.task.status,
+            assignmentMode: explicitAssignments ? 'custom' : 'auto',
             assignmentsCreated: data.assignmentsCreated,
             assignmentsProcessed: data.assignmentsProcessed,
             ...(data.assignmentsRemoved !== undefined
@@ -3102,6 +3143,7 @@ async function publishTask() {
         return;
     }
     printLine(`Published task ${sanitizeTerminalText(data.task.id)} [${sanitizeTerminalText(data.task.status)}]` +
+        `\n  Mode:        ${explicitAssignments ? 'custom row map' : 'auto distribute'}` +
         `\n  Assignments: ${data.assignmentsCreated}` +
         (data.assignmentsRemoved !== undefined
             ? `\n  Replaced:    ${data.assignmentsRemoved} old assignments removed`
@@ -3111,23 +3153,50 @@ async function publishTask() {
 async function assignTask() {
     const taskId = getArg('--task');
     const assignees = parseCommaSeparated(getArg('--assignees'));
-    if (!taskId || assignees.length === 0) {
-        throw new Error('Usage: orizu tasks assign --task <taskId> --assignees <userId1,userId2>');
+    const assignmentFile = getArg('--assignment-file');
+    if (assignmentFile && assignees.length > 0) {
+        throw new Error('Use either --assignment-file or --assignees, not both.');
+    }
+    const explicitAssignments = readAssignmentManifest(assignmentFile);
+    if (!taskId || (assignees.length === 0 && !explicitAssignments)) {
+        throw new Error('Usage: orizu tasks assign --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--replace-existing] [--json]');
+    }
+    const requestBody = explicitAssignments
+        ? { explicitAssignments }
+        : { memberIds: assignees };
+    if (hasArg('--replace-existing')) {
+        requestBody.replaceExisting = true;
     }
     const response = await authedFetch(`/api/cli/tasks/${encodeURIComponent(taskId)}/assign`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ memberIds: assignees }),
+        body: JSON.stringify(requestBody),
     });
     if (!response.ok) {
         throw new Error(`Failed to assign task: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Task assign');
     if (hasJsonFlag()) {
-        printJson({ assignmentsCreated: data.assignmentsCreated });
+        printJson({
+            assignmentMode: explicitAssignments ? 'custom' : 'auto',
+            assignmentsProcessed: data.assignmentsProcessed ?? data.assignmentsCreated,
+            assignmentsCreated: data.assignmentsCreated,
+            ...(data.assignmentsRemoved !== undefined
+                ? { assignmentsRemoved: data.assignmentsRemoved }
+                : {}),
+            ...(data.assignmentShortfall !== undefined
+                ? { assignmentShortfall: data.assignmentShortfall }
+                : {}),
+            ...(data.warning ? { warning: data.warning } : {}),
+        });
         return;
     }
-    printLine(`Created ${data.assignmentsCreated} assignments.`);
+    printLine(`Created ${data.assignmentsCreated} assignments.` +
+        `\n  Mode: ${explicitAssignments ? 'custom row map' : 'auto distribute'}` +
+        (data.assignmentsRemoved !== undefined
+            ? `\n  Replaced: ${data.assignmentsRemoved} old assignments removed`
+            : '') +
+        (data.warning ? `\n  Warning: ${sanitizeTerminalText(data.warning)}` : ''));
 }
 async function taskStatus() {
     const taskId = getArg('--task');

package/dist/task-assignment-manifest.js

@@ -0,0 +1,59 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function parseAssignmentManifestJsonl(content) {
+    // Keep these JSONL field rules in sync with the server's explicitAssignments parser.
+    const entries = [];
+    const lines = content.split(/\r?\n/);
+    lines.forEach((line, lineIndex) => {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (error) {
+            throw new Error(`Assignment manifest line ${lineIndex + 1} is not valid JSON`);
+        }
+        if (!isRecord(parsed)) {
+            throw new Error(`Assignment manifest line ${lineIndex + 1} must be a JSON object`);
+        }
+        const rowId = typeof parsed.rowId === 'string' ? parsed.rowId.trim() : '';
+        if (!rowId) {
+            throw new Error(`Assignment manifest line ${lineIndex + 1} must include a non-empty rowId`);
+        }
+        const hasAssignee = Object.hasOwn(parsed, 'assignee');
+        const hasAssignees = Object.hasOwn(parsed, 'assignees');
+        if (hasAssignee && hasAssignees) {
+            throw new Error(`Assignment manifest line ${lineIndex + 1} must provide either assignee or assignees, not both`);
+        }
+        if (hasAssignee) {
+            const assignee = typeof parsed.assignee === 'string' ? parsed.assignee.trim() : '';
+            if (!assignee) {
+                throw new Error(`Assignment manifest line ${lineIndex + 1} assignee must be a non-empty string`);
+            }
+            entries.push({ rowId, assignee });
+            return;
+        }
+        if (hasAssignees) {
+            if (!Array.isArray(parsed.assignees) || parsed.assignees.length === 0) {
+                throw new Error(`Assignment manifest line ${lineIndex + 1} assignees must be a non-empty string array`);
+            }
+            parsed.assignees.forEach((assigneeValue, assigneeIndex) => {
+                const assignee = typeof assigneeValue === 'string' ? assigneeValue.trim() : '';
+                if (!assignee) {
+                    throw new Error(`Assignment manifest line ${lineIndex + 1} assignees[${assigneeIndex}] must be a non-empty string`);
+                }
+                entries.push({ rowId, assignee });
+            });
+            return;
+        }
+        throw new Error(`Assignment manifest line ${lineIndex + 1} must include assignee or assignees`);
+    });
+    if (entries.length === 0) {
+        throw new Error('Assignment manifest must contain at least one assignment');
+    }
+    return entries;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orizu",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": false,
   "type": "module",
   "bin": {

package/src/help.ts

@@ -475,20 +475,20 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['tasks', 'create'],
-    usage: 'orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]',
-    summary: 'Create a draft review task by default, or publish immediately with --publish and assignees.',
+    usage: 'orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2> | --assignment-file <path>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]',
+    summary: 'Create a draft review task by default, with auto distribution or an explicit row-assignment JSONL file.',
     group: 'Tasks',
   },
   {
     path: ['tasks', 'publish'],
-    usage: 'orizu tasks publish --task <taskId> --assignees <userId1,userId2> [--json]',
+    usage: 'orizu tasks publish --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--json]',
     summary: 'Publish an approved draft task and assign reviewers.',
     group: 'Tasks',
   },
   {
     path: ['tasks', 'assign'],
-    usage: 'orizu tasks assign --task <taskId> --assignees <userId1,userId2>',
-    summary: 'Assign a task to canonical user IDs.',
+    usage: 'orizu tasks assign --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--replace-existing] [--json]',
+    summary: 'Assign a task with auto distribution or an explicit row-assignment JSONL file.',
     group: 'Tasks',
   },
   {

package/src/index.ts

@@ -27,6 +27,7 @@ import { extractErrorMessage } from './error-response.js'
 import { parseGlobalFlags } from './global-flags.js'
 import { getCapabilities, renderHelpForArgs, renderRootHelp } from './help.js'
 import { runLocalAppPreview } from './preview-runtime.js'
+import { parseAssignmentManifestJsonl } from './task-assignment-manifest.js'
 import {
   assertSecureTokenTransport,
   authedFetch,
@@ -3908,43 +3909,77 @@ function parseCommaSeparated(value: string | null): string[] {
     .filter(Boolean)
 }
 
+function readAssignmentManifest(path: string | null): ReturnType<typeof parseAssignmentManifestJsonl> | null {
+  if (!path) {
+    return null
+  }
+
+  const content = readFileSync(expandHomePath(path), 'utf8')
+  return parseAssignmentManifestJsonl(content)
+}
+
 async function createTask() {
   const projectSlug = getArg('--project')
   const datasetId = getArg('--dataset')
   const appId = getArg('--app')
   const title = getArg('--title')
   const assignees = parseCommaSeparated(getArg('--assignees'))
+  const assignmentFile = getArg('--assignment-file')
   const publish = hasArg('--publish')
   const versionArg = getArg('--version')
   const instructions = getArg('--instructions')
   const labelsPerItemArg = getArg('--labels-per-item')
-  const labelsPerItem = labelsPerItemArg ? Number(labelsPerItemArg) : 1
+  const parsedLabelsPerItem = labelsPerItemArg ? Number(labelsPerItemArg) : 1
+  const labelsPerItem =
+    Number.isInteger(parsedLabelsPerItem) && parsedLabelsPerItem > 0
+      ? parsedLabelsPerItem
+      : null
   const parsedVersionNum = versionArg ? Number(versionArg) : Number.NaN
   const versionNum =
     Number.isInteger(parsedVersionNum) && parsedVersionNum > 0 ? parsedVersionNum : null
 
-  if (!projectSlug || !datasetId || !appId || !title || (publish && assignees.length === 0)) {
-    throw new Error('Usage: orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]')
+  if (assignmentFile && assignees.length > 0) {
+    throw new Error('Use either --assignment-file or --assignees, not both.')
+  }
+
+  const explicitAssignments = readAssignmentManifest(assignmentFile)
+
+  if (!projectSlug || !datasetId || !appId || !title || (publish && assignees.length === 0 && !explicitAssignments)) {
+    throw new Error('Usage: orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2> | --assignment-file <path>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]')
   }
 
   if (versionArg && versionNum === null) {
     throw new Error('--version must be a positive integer')
   }
 
+  if (labelsPerItemArg && labelsPerItem === null) {
+    throw new Error('--labels-per-item must be a positive integer')
+  }
+
+  const requestBody: Record<string, unknown> = {
+    projectSlug,
+    datasetId,
+    appId,
+    versionNum,
+    title,
+    publish,
+    instructions,
+  }
+
+  if (explicitAssignments) {
+    requestBody.explicitAssignments = explicitAssignments
+  } else {
+    requestBody.memberIds = assignees
+  }
+
+  if (!explicitAssignments || labelsPerItemArg) {
+    requestBody.requiredAssignmentsPerRow = labelsPerItem
+  }
+
   const response = await authedFetch('/api/cli/tasks', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      projectSlug,
-      datasetId,
-      appId,
-      versionNum,
-      title,
-      memberIds: assignees,
-      publish,
-      instructions,
-      requiredAssignmentsPerRow: labelsPerItem,
-    }),
+    body: JSON.stringify(requestBody),
   })
 
   if (!response.ok) {
@@ -3982,13 +4017,16 @@ async function createTask() {
       taskUrl: `${getBaseUrl()}/d/${projectSlug}/tasks/${data.task.id}`,
       title: data.task.title,
       status: data.task.status,
+      assignmentMode: explicitAssignments ? 'custom' : 'auto',
       requiredAssignmentsPerRow: data.task.requiredAssignmentsPerRow,
       assignmentsCreated: data.assignmentsCreated,
       draft: data.task.status === 'draft',
       ...(data.task.status === 'draft'
         ? {
             message: 'Draft created. Test it manually before assigning.',
-            publishCommand: `orizu tasks publish --task ${data.task.id} --assignees <userId1,userId2>`,
+            publishCommand: explicitAssignments
+              ? `orizu tasks publish --task ${data.task.id} --assignment-file ${assignmentFile ? shellQuote(assignmentFile) : '<path>'}`
+              : `orizu tasks publish --task ${data.task.id} --assignees <userId1,userId2>`,
           }
         : {}),
       ...(data.assignmentShortfall !== undefined ? { assignmentShortfall: data.assignmentShortfall } : {}),
@@ -4005,12 +4043,17 @@ async function createTask() {
     `\n  Task ID:    ${sanitizeTerminalText(data.task.id)}` +
     `\n  Dataset ID: ${sanitizeTerminalText(datasetId)}` +
     `\n  Version:    v${data.task.versionNum} (${sanitizeTerminalText(data.task.versionId)})` +
+    `\n  Mode:       ${explicitAssignments ? 'custom row map' : 'auto distribute'}` +
     `\n  Labels/row: ${data.task.requiredAssignmentsPerRow}` +
     `\n  Assignments: ${data.assignmentsCreated}` +
     (data.warning ? `\n  Warning:    ${sanitizeTerminalText(data.warning)}` : '') +
     `\n  URL:        ${sanitizeTerminalText(taskUrl)}` +
     (isDraft
-      ? `\n\nThis task is a draft. Test it manually before assigning.\nPublish after approval: orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignees <userId1,userId2>`
+      ? `\n\nThis task is a draft. Test it manually before assigning.\nPublish after approval: ${
+          explicitAssignments
+            ? `orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignment-file ${sanitizeTerminalText(assignmentFile || '<path>')}`
+            : `orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignees <userId1,userId2>`
+        }`
       : '')
   )
 }
@@ -4018,15 +4061,26 @@ async function createTask() {
 async function publishTask() {
   const taskId = getArg('--task')
   const assignees = parseCommaSeparated(getArg('--assignees'))
+  const assignmentFile = getArg('--assignment-file')
+
+  if (assignmentFile && assignees.length > 0) {
+    throw new Error('Use either --assignment-file or --assignees, not both.')
+  }
+
+  const explicitAssignments = readAssignmentManifest(assignmentFile)
 
-  if (!taskId || assignees.length === 0) {
-    throw new Error('Usage: orizu tasks publish --task <taskId> --assignees <userId1,userId2> [--json]')
+  if (!taskId || (assignees.length === 0 && !explicitAssignments)) {
+    throw new Error('Usage: orizu tasks publish --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--json]')
   }
 
   const response = await authedFetch(`/api/cli/tasks/${encodeURIComponent(taskId)}/publish`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ memberIds: assignees }),
+    body: JSON.stringify(
+      explicitAssignments
+        ? { explicitAssignments }
+        : { memberIds: assignees }
+    ),
   })
 
   if (!response.ok) {
@@ -4049,6 +4103,7 @@ async function publishTask() {
     printLine(JSON.stringify({
       taskId: data.task.id,
       status: data.task.status,
+      assignmentMode: explicitAssignments ? 'custom' : 'auto',
       assignmentsCreated: data.assignmentsCreated,
       assignmentsProcessed: data.assignmentsProcessed,
       ...(data.assignmentsRemoved !== undefined
@@ -4064,6 +4119,7 @@ async function publishTask() {
 
   printLine(
     `Published task ${sanitizeTerminalText(data.task.id)} [${sanitizeTerminalText(data.task.status)}]` +
+    `\n  Mode:        ${explicitAssignments ? 'custom row map' : 'auto distribute'}` +
     `\n  Assignments: ${data.assignmentsCreated}` +
     (data.assignmentsRemoved !== undefined
       ? `\n  Replaced:    ${data.assignmentsRemoved} old assignments removed`
@@ -4075,27 +4131,65 @@ async function publishTask() {
 async function assignTask() {
   const taskId = getArg('--task')
   const assignees = parseCommaSeparated(getArg('--assignees'))
+  const assignmentFile = getArg('--assignment-file')
 
-  if (!taskId || assignees.length === 0) {
-    throw new Error('Usage: orizu tasks assign --task <taskId> --assignees <userId1,userId2>')
+  if (assignmentFile && assignees.length > 0) {
+    throw new Error('Use either --assignment-file or --assignees, not both.')
+  }
+
+  const explicitAssignments = readAssignmentManifest(assignmentFile)
+
+  if (!taskId || (assignees.length === 0 && !explicitAssignments)) {
+    throw new Error('Usage: orizu tasks assign --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--replace-existing] [--json]')
+  }
+
+  const requestBody: Record<string, unknown> = explicitAssignments
+    ? { explicitAssignments }
+    : { memberIds: assignees }
+  if (hasArg('--replace-existing')) {
+    requestBody.replaceExisting = true
   }
 
   const response = await authedFetch(`/api/cli/tasks/${encodeURIComponent(taskId)}/assign`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ memberIds: assignees }),
+    body: JSON.stringify(requestBody),
   })
 
   if (!response.ok) {
     throw new Error(`Failed to assign task: ${await response.text()}`)
   }
 
-  const data = await parseJsonResponse<{ assignmentsCreated: number }>(response, 'Task assign')
+  const data = await parseJsonResponse<{
+    assignmentsProcessed?: number
+    assignmentsCreated: number
+    assignmentsRemoved?: number
+    assignmentShortfall?: number
+    warning?: string
+  }>(response, 'Task assign')
   if (hasJsonFlag()) {
-    printJson({ assignmentsCreated: data.assignmentsCreated })
+    printJson({
+      assignmentMode: explicitAssignments ? 'custom' : 'auto',
+      assignmentsProcessed: data.assignmentsProcessed ?? data.assignmentsCreated,
+      assignmentsCreated: data.assignmentsCreated,
+      ...(data.assignmentsRemoved !== undefined
+        ? { assignmentsRemoved: data.assignmentsRemoved }
+        : {}),
+      ...(data.assignmentShortfall !== undefined
+        ? { assignmentShortfall: data.assignmentShortfall }
+        : {}),
+      ...(data.warning ? { warning: data.warning } : {}),
+    })
     return
   }
-  printLine(`Created ${data.assignmentsCreated} assignments.`)
+  printLine(
+    `Created ${data.assignmentsCreated} assignments.` +
+    `\n  Mode: ${explicitAssignments ? 'custom row map' : 'auto distribute'}` +
+    (data.assignmentsRemoved !== undefined
+      ? `\n  Replaced: ${data.assignmentsRemoved} old assignments removed`
+      : '') +
+    (data.warning ? `\n  Warning: ${sanitizeTerminalText(data.warning)}` : '')
+  )
 }
 
 async function taskStatus() {

package/src/task-assignment-manifest.ts

@@ -0,0 +1,96 @@
+export interface ParsedAssignmentManifestEntry {
+  rowId: string
+  assignee: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function parseAssignmentManifestJsonl(
+  content: string
+): ParsedAssignmentManifestEntry[] {
+  // Keep these JSONL field rules in sync with the server's explicitAssignments parser.
+  const entries: ParsedAssignmentManifestEntry[] = []
+  const lines = content.split(/\r?\n/)
+
+  lines.forEach((line, lineIndex) => {
+    const trimmed = line.trim()
+    if (!trimmed) {
+      return
+    }
+
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(trimmed)
+    } catch (error) {
+      throw new Error(
+        `Assignment manifest line ${lineIndex + 1} is not valid JSON`
+      )
+    }
+
+    if (!isRecord(parsed)) {
+      throw new Error(
+        `Assignment manifest line ${lineIndex + 1} must be a JSON object`
+      )
+    }
+
+    const rowId = typeof parsed.rowId === 'string' ? parsed.rowId.trim() : ''
+    if (!rowId) {
+      throw new Error(
+        `Assignment manifest line ${lineIndex + 1} must include a non-empty rowId`
+      )
+    }
+
+    const hasAssignee = Object.hasOwn(parsed, 'assignee')
+    const hasAssignees = Object.hasOwn(parsed, 'assignees')
+
+    if (hasAssignee && hasAssignees) {
+      throw new Error(
+        `Assignment manifest line ${lineIndex + 1} must provide either assignee or assignees, not both`
+      )
+    }
+
+    if (hasAssignee) {
+      const assignee =
+        typeof parsed.assignee === 'string' ? parsed.assignee.trim() : ''
+      if (!assignee) {
+        throw new Error(
+          `Assignment manifest line ${lineIndex + 1} assignee must be a non-empty string`
+        )
+      }
+      entries.push({ rowId, assignee })
+      return
+    }
+
+    if (hasAssignees) {
+      if (!Array.isArray(parsed.assignees) || parsed.assignees.length === 0) {
+        throw new Error(
+          `Assignment manifest line ${lineIndex + 1} assignees must be a non-empty string array`
+        )
+      }
+
+      parsed.assignees.forEach((assigneeValue, assigneeIndex) => {
+        const assignee =
+          typeof assigneeValue === 'string' ? assigneeValue.trim() : ''
+        if (!assignee) {
+          throw new Error(
+            `Assignment manifest line ${lineIndex + 1} assignees[${assigneeIndex}] must be a non-empty string`
+          )
+        }
+        entries.push({ rowId, assignee })
+      })
+      return
+    }
+
+    throw new Error(
+      `Assignment manifest line ${lineIndex + 1} must include assignee or assignees`
+    )
+  })
+
+  if (entries.length === 0) {
+    throw new Error('Assignment manifest must contain at least one assignment')
+  }
+
+  return entries
+}

package/vendor/skills/orizu-cli/SKILL.md

@@ -89,6 +89,8 @@ orizu tasks create --project <teamSlug>/<projectSlug> --dataset <datasetId> --ap
 
 # Open the returned task URL and test the draft manually before assigning.
 orizu tasks publish --task <taskId> --assignees <userId1,userId2>
+# Or publish exact row assignments:
+orizu tasks publish --task <taskId> --assignment-file ./assignments.jsonl
 
 orizu tasks status --task <taskId>
 orizu tasks report set --task <taskId> --report-file ./task-report.md
@@ -175,9 +177,9 @@ Detailed walkthrough — GEPA mechanics, Orizu-tracked optimization, optional DS
 # Execution rules
 
 - Prefer explicit flags in non-TTY contexts; reserve interactive fallback for TTY.
-- Canonical selectors: `--team`, `--project`, `--app`, `--task`, `--dataset`, `--assignees`.
-- `tasks create` creates drafts by default. Test the returned task URL manually, then use `tasks publish --task <taskId> --assignees <userId1,userId2>` after approval.
-- `tasks assign` and `tasks publish` take user IDs, not emails.
+- Canonical selectors: `--team`, `--project`, `--app`, `--task`, `--dataset`, `--assignees`, `--assignment-file`.
+- `tasks create` creates drafts by default. Test the returned task URL manually, then use `tasks publish --task <taskId> --assignees <userId1,userId2>` or `tasks publish --task <taskId> --assignment-file <path>` after approval.
+- `tasks assign --assignees` and `tasks publish --assignees` take user IDs, not emails. `--assignment-file` accepts emails or user IDs in JSONL rows shaped as `{ "rowId": "...", "assignee": "..." }` or `{ "rowId": "...", "assignees": ["..."] }`.
 - `datasets edit-rows` requires a non-empty string `id` on each row in `--file`.
 - `datasets delete-rows` uses `--row-ids` as the canonical selector.
 - `datasets delete` requires interactive terminal confirmation; there is no non-interactive confirmation option.

package/vendor/skills/orizu-cli/references/cli-reference.md

@@ -186,23 +186,28 @@ orizu tasks create \
 Behavior:
 - task creation creates a draft by default and returns a task URL to test manually before assigning
 - use `--publish --assignees <userIdOrEmail1,userIdOrEmail2>` only when you intentionally want to create and ship immediately
+- use `--assignment-file <path>` instead of `--assignees` when specific rows should go to specific labellers
 - after manually approving a draft, run `orizu tasks publish --task <taskId> --assignees <userId1,userId2>`
+- or run `orizu tasks publish --task <taskId> --assignment-file <path>` to publish the exact row map
 - task creation resolves and stores the app's pinned current `version_id` at create time
 - downstream consumers (exports, judges, optimization) should trust the task's pinned `version_id`, not the app's current pointer
 - dataset compatibility is validated against that pinned app version before the task is inserted
 - malformed JSON and mixed-type assignee arrays fail with deterministic `400` responses
 - assignment fanout enforces unique `(assignee, row)` pairs; `--labels-per-item` cannot exceed the number of unique assignees, and the backend shortfalls instead of duplicating
+- explicit assignment manifests are JSONL with `rowId` plus `assignee` or `assignees`; row IDs are canonical dataset row `id` values, assignees may be emails or user IDs, and V1 publish requires whole-dataset uniform coverage
 
 Publish:
 
 ```bash
 orizu tasks publish --task <taskId> --assignees <userId1,userId2>
+orizu tasks publish --task <taskId> --assignment-file ./assignments.jsonl
 ```
 
 Assign:
 
 ```bash
 orizu tasks assign --task <taskId> --assignees <userId1,userId2>
+orizu tasks assign --task <taskId> --assignment-file ./assignments.jsonl --replace-existing
 ```
 
 Status:
@@ -301,6 +306,8 @@ orizu tasks create \
 
 # Open the returned task URL and test the draft manually before assigning.
 orizu tasks publish --task <taskId> --assignees <userId1,userId2>
+# Or publish a deterministic row map:
+orizu tasks publish --task <taskId> --assignment-file ./assignments.jsonl
 
 orizu tasks status --task <taskId>
 orizu tasks export --task <taskId> --format csv --out ./support-round1.csv
@@ -321,7 +328,8 @@ Use these shortcuts only in TTY environments where prompts can run.
 
 - `tasks create` creates a draft by default, does not require `--assignees`, and pins the app's current version when the task is created.
 - `tasks create --publish --assignees <...>` intentionally creates and ships immediately.
-- `tasks assign` and `tasks publish` expect user IDs, not emails.
+- `tasks create|publish|assign --assignment-file <path>` is mutually exclusive with `--assignees` and accepts emails or user IDs in the JSONL manifest.
+- `tasks assign --assignees` and `tasks publish --assignees` expect user IDs, not emails.
 - Assignment queue reads are assignee-self-only; use task status/export as the operator summary path.
 - Assignment completion payloads are validated against the pinned app-version `output_json_schema`.
 - `datasets delete-rows` requires `--row-ids`.