@bpmsoftwaresolutions/ai-engine-client 1.1.87 → 1.1.88

package/src/domains/implementation-artifacts.js

@@ -1,6 +1,67 @@
+import { isPlainObject } from '../utils/text.js';
+import { buildVerificationError } from '../utils/verified-mutations.js';
+
 export function createImplementationArtifactsDomain(client) {
   return {
     getArtifactManifest: (implementationItemId) => client._request(`/api/governed-implementation/items/${implementationItemId}/artifact-manifest`),
     getDecisionPacket: (implementationItemId) => client._request(`/api/governed-implementation/items/${implementationItemId}/decision-packet`),
+    verifyImplementationItemArtifacts: async (implementationItemId, { requiredArtifacts = [] } = {}) => {
+      const requiredKinds = Array.isArray(requiredArtifacts) ? requiredArtifacts : [];
+      const verifications = [];
+      const artifactReaders = {
+        artifact_manifest: async () => client.getArtifactManifest(implementationItemId),
+        decision_packet: async () => client.getDecisionPacket(implementationItemId),
+      };
+
+      for (const kind of requiredKinds) {
+        const reader = artifactReaders[kind];
+        if (typeof reader !== 'function') {
+          throw new Error(`Unsupported required artifact: ${kind}`);
+        }
+        const payload = await reader();
+        if (payload?.source_truth !== 'sql') {
+          throw buildVerificationError(`Artifact ${kind} did not declare SQL as source_truth.`, {
+            artifact_kind: kind,
+            verified_current_state: payload ?? null,
+          });
+        }
+        if (payload?.item_id !== implementationItemId) {
+          throw buildVerificationError(`Artifact ${kind} returned item_id ${payload?.item_id ?? 'unknown'} instead of ${implementationItemId}.`, {
+            artifact_kind: kind,
+            verified_current_state: payload ?? null,
+          });
+        }
+        const dataKey = kind === 'artifact_manifest' ? 'artifact_manifest' : 'decision_packet';
+        if (!isPlainObject(payload?.[dataKey])) {
+          throw buildVerificationError(`Artifact ${kind} did not include required ${dataKey} data.`, {
+            artifact_kind: kind,
+            verified_current_state: payload ?? null,
+          });
+        }
+        verifications.push({
+          artifact_kind: kind,
+          http_status: 200,
+          source_truth: payload.source_truth,
+          item_id: payload.item_id,
+          verified_current_state: payload[dataKey],
+        });
+      }
+
+      return {
+        itemId: implementationItemId,
+        requiredArtifacts: requiredKinds,
+        verified: true,
+        mutationVerificationEvidence: {
+          mutation_name: 'verifyImplementationItemArtifacts',
+          evidence_label: `implementation-item-artifacts:${implementationItemId}`,
+          mutation_attempted: false,
+          authoritative_read_performed: true,
+          post_condition_verified: true,
+          expected_state: { required_artifacts: requiredKinds },
+          verified_current_state: verifications,
+        },
+        artifacts: verifications,
+      };
+    },
   };
 }

package/src/domains/implementation-checks.js

@@ -0,0 +1,41 @@
+import { executeVerifiedMutation } from '../utils/verified-mutations.js';
+
+export function createImplementationChecksDomain(client) {
+  return {
+    getImplementationItemAcceptanceChecks: (implementationItemId) => client._request(`/api/governed-implementation/items/${implementationItemId}/acceptance-checks`),
+    updateAcceptanceCheckStatus: (implementationItemId, acceptanceCheckId, body) => {
+      client._assertExecutionEligibility({
+        ...(body || {}),
+        claimed_item_id: body?.claimed_item_id || implementationItemId,
+        requested_mutation_surface: body?.requested_mutation_surface || 'implementation_acceptance_check',
+        verification_required: true,
+      });
+      return client._request(
+        `/api/governed-implementation/items/${implementationItemId}/acceptance-checks/${acceptanceCheckId}/status`,
+        { method: 'PATCH', body }
+      );
+    },
+    updateAcceptanceCheckStatusVerified: (implementationItemId, acceptanceCheckId, status, body = {}) => executeVerifiedMutation({
+      mutationName: 'updateAcceptanceCheckStatus',
+      evidenceLabel: `acceptance-check-status:${implementationItemId}:${acceptanceCheckId}`,
+      mutationFn: () => client.updateAcceptanceCheckStatus(implementationItemId, acceptanceCheckId, { ...body, status }),
+      verificationFn: async () => client.getImplementationItemAcceptanceChecks(implementationItemId),
+      expectedState: (verificationResult) => {
+        const checks = Array.isArray(verificationResult?.acceptance_checks) ? verificationResult.acceptance_checks : [];
+        const targetCheck = checks.find((check) => check?.acceptance_check_id === acceptanceCheckId) || null;
+        if (!targetCheck) {
+          return {
+            ok: false,
+            message: `Acceptance check ${acceptanceCheckId} was not returned by the authoritative read.`,
+            verifiedCurrentState: verificationResult,
+          };
+        }
+        return {
+          ok: targetCheck.status === status,
+          message: `Acceptance check ${acceptanceCheckId} status remained ${targetCheck.status ?? 'unknown'} after mutation attempt.`,
+          verifiedCurrentState: targetCheck,
+        };
+      },
+    }),
+  };
+}

package/src/domains/implementation-items.js

@@ -1,94 +1,9 @@
+import { cleanText, isPlainObject } from '../utils/text.js';
+import { buildVerificationError, executeVerifiedMutation } from '../utils/verified-mutations.js';
+
 export function createImplementationItemsDomain(client) {
   return {
-    createImplementationTask: async (implementationItemId, {
-      title,
-      implementationPacketId,
-      description,
-      priority,
-      assignedTo,
-      assignedBy,
-      dueAt,
-      sortOrder,
-      notes,
-      createdBy,
-      parentTaskId,
-      claimId,
-      claimProjectId,
-      projectId,
-      claimedItemId,
-      workflowRunId,
-      agentSessionId,
-      allowedMutationSurfaces,
-      acknowledgedReminders,
-      executionIntent,
-      executionType,
-      executionPurpose,
-    } = {}) => {
-      const normalizedClaimId = String(claimId || '').trim() || null;
-      const normalizedClaimProjectId = String(claimProjectId || projectId || '').trim() || null;
-      const normalizedClaimedItemId = String(claimedItemId || implementationItemId || '').trim() || null;
-      const normalizedWorkflowRunId = String(workflowRunId || '').trim() || null;
-      const normalizedAgentSessionId = String(agentSessionId || '').trim() || null;
-      const normalizedAllowedMutationSurfaces = Array.isArray(allowedMutationSurfaces) && allowedMutationSurfaces.length > 0
-        ? allowedMutationSurfaces
-        : ['project_roadmap_task'];
-      const normalizedAcknowledgedReminders = Array.isArray(acknowledgedReminders)
-        ? acknowledgedReminders
-        : undefined;
-      const normalizedExecutionIntent = (() => {
-        if (executionIntent && typeof executionIntent === 'object') {
-          const execution_type = String(executionIntent.execution_type || executionIntent.executionType || '').trim();
-          const execution_purpose = String(executionIntent.execution_purpose || executionIntent.executionPurpose || '').trim();
-          if (execution_type || execution_purpose) {
-            return {
-              ...(execution_type ? { execution_type } : {}),
-              ...(execution_purpose ? { execution_purpose } : {}),
-            };
-          }
-        }
-        const normalizedExecutionType = String(executionType || '').trim() || 'implementation_task';
-        const normalizedExecutionPurpose = String(executionPurpose || title || '').trim() || 'implementation task';
-        return {
-          execution_type: normalizedExecutionType,
-          execution_purpose: normalizedExecutionPurpose,
-        };
-      })();
-      await client._assertExecutionEligibility({
-        claim_id: normalizedClaimId,
-        claim_project_id: normalizedClaimProjectId,
-        claimed_item_id: normalizedClaimedItemId,
-        workflow_run_id: normalizedWorkflowRunId,
-        agent_session_id: normalizedAgentSessionId,
-        allowed_mutation_surfaces: normalizedAllowedMutationSurfaces,
-        acknowledged_reminders: normalizedAcknowledgedReminders || [],
-        requested_mutation_surface: 'project_roadmap_task',
-        verification_required: true,
-      });
-      return client._request(`/api/operator/implementation-items/${implementationItemId}/tasks`, {
-        method: 'POST',
-        body: {
-          title,
-          implementation_packet_id: implementationPacketId,
-          description,
-          priority,
-          assigned_to: assignedTo,
-          assigned_by: assignedBy,
-          due_at: dueAt,
-          sort_order: sortOrder,
-          notes,
-          created_by: createdBy,
-          parent_task_id: parentTaskId,
-          claim_id: normalizedClaimId,
-          claim_project_id: normalizedClaimProjectId,
-          claimed_item_id: normalizedClaimedItemId,
-          workflow_run_id: normalizedWorkflowRunId,
-          agent_session_id: normalizedAgentSessionId,
-          allowed_mutation_surfaces: normalizedAllowedMutationSurfaces,
-          acknowledged_reminders: normalizedAcknowledgedReminders,
-          execution_intent: normalizedExecutionIntent,
-        },
-      });
-    },
+    createImplementationTask: (implementationItemId, request) => client.implementationTasks.createImplementationTask(implementationItemId, request),
     listImplementationTasks: (implementationItemId) => client._request(`/api/operator/implementation-items/${implementationItemId}/tasks`),
     listImplementationSubtasks: (taskId) => client._request(`/api/operator/implementation-item-tasks/${taskId}/subtasks`),
     updateImplementationTask: (taskId, updates) => client._request(`/api/operator/implementation-item-tasks/${taskId}`, {
@@ -103,5 +18,83 @@ export function createImplementationItemsDomain(client) {
       method: 'POST',
       body: { completed_by: request.completedBy },
     }),
+    updateImplementationItemStatus: async (implementationItemId, body) => {
+      await client._assertExecutionEligibility({
+        ...(body || {}),
+        claimed_item_id: body?.claimed_item_id || implementationItemId,
+        requested_mutation_surface: body?.requested_mutation_surface || 'implementation_packet_item',
+        verification_required: true,
+      });
+      const result = await client._request(`/api/governed-implementation/items/${implementationItemId}/status`, {
+        method: 'PATCH', body,
+      });
+      const expectedStatus = cleanText(body?.status);
+      const authoritativeItem = isPlainObject(result?.implementation_item) ? result.implementation_item : null;
+      const actualStatus = cleanText(authoritativeItem?.status);
+      if (expectedStatus && !authoritativeItem) {
+        throw buildVerificationError(
+          `updateImplementationItemStatus did not return authoritative item state for ${implementationItemId}.`,
+          {
+            mutation_name: 'updateImplementationItemStatus',
+            mutation_attempted: true,
+            authoritative_read_performed: false,
+            post_condition_verified: false,
+            expected_state: { status: expectedStatus },
+            mutation_result: result ?? null,
+          },
+        );
+      }
+      if (expectedStatus && actualStatus !== expectedStatus) {
+        throw buildVerificationError(
+          `updateImplementationItemStatus returned ${actualStatus ?? 'unknown'} instead of ${expectedStatus}.`,
+          {
+            mutation_name: 'updateImplementationItemStatus',
+            mutation_attempted: true,
+            authoritative_read_performed: true,
+            post_condition_verified: false,
+            expected_state: { status: expectedStatus },
+            verified_current_state: authoritativeItem ?? result ?? null,
+            mutation_result: result ?? null,
+          },
+        );
+      }
+      return result;
+    },
+    updateImplementationItemStatusVerified: (implementationItemId, status, body = {}) => executeVerifiedMutation({
+      mutationName: 'updateImplementationItemStatus',
+      evidenceLabel: `implementation-item-status:${implementationItemId}`,
+      mutationFn: () => client.updateImplementationItemStatus(implementationItemId, { ...body, status }),
+      verificationFn: async (mutationResult) => {
+        const workflowId = cleanText(body.workflowId)
+          || cleanText(body.workflow_id)
+          || cleanText(mutationResult?.workflow_id);
+        if (!workflowId) {
+          throw new Error('workflowId is required to verify implementation item status.');
+        }
+        const roadmap = await client.getWorkflowImplementationRoadmap(workflowId);
+        const items = Array.isArray(roadmap?.items) ? roadmap.items : [];
+        const matchedItem = items.find((item) => item?.implementation_item_id === implementationItemId) || null;
+        return {
+          workflow_id: workflowId,
+          item: matchedItem,
+          roadmap,
+        };
+      },
+      expectedState: (verificationResult) => {
+        const item = verificationResult?.item || null;
+        if (!item) {
+          return {
+            ok: false,
+            message: `Implementation item ${implementationItemId} was not present in the authoritative roadmap read.`,
+            verifiedCurrentState: verificationResult,
+          };
+        }
+        return {
+          ok: item.status === status,
+          message: `Implementation item ${implementationItemId} status remained ${item.status ?? 'unknown'} after mutation attempt.`,
+          verifiedCurrentState: item,
+        };
+      },
+    }),
   };
 }

package/src/domains/implementation-packets.js

@@ -1,3 +1,36 @@
+import { cleanList, cleanText, isPlainObject } from '../utils/text.js';
+
+function looksLikeUuid(value) {
+  const text = cleanText(value);
+  return Boolean(text && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(text));
+}
+
+function countRoadmapProjectionLines(markdown) {
+  const lines = [];
+  let inSummary = false;
+  for (const line of String(markdown || '').split(/\r?\n/)) {
+    if (line.startsWith('## Roadmap Summary')) {
+      inSummary = true;
+      continue;
+    }
+    if (inSummary && line.startsWith('## ')) {
+      break;
+    }
+    if (inSummary && line.startsWith('- ')) {
+      lines.push(line);
+    }
+  }
+  const wanted = [
+    'Total Items',
+    'Total Tasks',
+    'Total Subtasks',
+    'Total Acceptance Checks',
+    'Open Acceptance Checks',
+    'Completion Percentage',
+  ];
+  return lines.filter((line) => wanted.some((label) => line.startsWith(`- ${label}:`)));
+}
+
 export function createImplementationPacketsDomain(client) {
   return {
     importImplementationPacket: (body) => client._request('/api/governed-implementation/packets/import', { method: 'POST', body }),
@@ -11,5 +44,145 @@ export function createImplementationPacketsDomain(client) {
     }),
     getWorkflowImplementationRoadmap: (workflowId) => client._request(`/api/governed-implementation/workflows/${workflowId}/roadmap`),
     getWorkflowResumeContext: (workflowId) => client._request(`/api/governed-implementation/workflows/${workflowId}/resume-context`),
+    importImplementationPacketAndMaterializeRoadmap: async (packetPayload, {
+      importedBy,
+      requestedBy,
+      createdBy,
+      workflowId,
+      bindingRole = 'active',
+      assignedTo,
+      notes,
+      createAcceptanceSubtasks = true,
+    } = {}) => {
+      if (!isPlainObject(packetPayload)) {
+        throw new Error('packetPayload must be a JSON object.');
+      }
+
+      const normalizedImportedBy = cleanText(importedBy) || cleanText(requestedBy) || client.actorId;
+      const normalizedRequestedBy = cleanText(requestedBy) || normalizedImportedBy;
+      const normalizedCreatedBy = cleanText(createdBy) || normalizedRequestedBy;
+
+      const importedPacket = await client.importImplementationPacket({
+        ...packetPayload,
+        imported_by: normalizedImportedBy,
+      });
+      const packetId = cleanText(importedPacket?.packet_id || importedPacket?.packetId || importedPacket?.implementation_packet_key || importedPacket?.implementationPacketKey || packetPayload.packetId || packetPayload.packet_id);
+      const implementationPacketId = cleanText(importedPacket?.implementation_packet_id || importedPacket?.implementationPacketId);
+      if (!implementationPacketId) {
+        throw new Error('Imported implementation packet response must include implementation_packet_id.');
+      }
+      if (!looksLikeUuid(implementationPacketId)) {
+        throw new Error('Imported implementation packet response returned a non-UUID implementation_packet_id.');
+      }
+      const projectReference = client._resolveImplementationPacketProjectReference(packetPayload);
+      if (!projectReference) {
+        throw new Error('Could not resolve a project reference from the packet payload.');
+      }
+      const projectPayload = await client.getProject(projectReference);
+      const projectSummary = isPlainObject(projectPayload?.summary) ? projectPayload.summary : {};
+      const projectId = cleanText(projectSummary.project_id);
+      if (!projectId) {
+        throw new Error('Project id could not be resolved.');
+      }
+
+      const workflowReference = client._resolveImplementationPacketWorkflowReference(packetPayload, {
+        projectSummary,
+        workflowIdOverride: cleanText(workflowId),
+      });
+      if (!workflowReference) {
+        throw new Error('Could not resolve a workflow reference from the packet payload or project summary.');
+      }
+      const resolvedWorkflowId = await client._resolveImplementationPacketWorkflowId(workflowReference);
+      const workflowSlug = cleanText(projectSummary.workflow_slug);
+
+      const binding = await client.bindImplementationPacketToWorkflow(resolvedWorkflowId, {
+        packet_id: packetId,
+        binding_role: cleanText(bindingRole) || 'active',
+        created_by: normalizedCreatedBy,
+        notes: cleanText(notes),
+      });
+
+      const taskSurface = await client.ensureProjectRoadmapTaskSurface(projectId, {
+        requestedBy: normalizedRequestedBy,
+        assignedTo,
+        createAcceptanceSubtasks,
+      });
+
+      const roadmapReport = await client.getProjectImplementationRoadmapReport(projectId);
+      const roadmapMarkdown = await client.downloadProjectImplementationRoadmapReportMarkdown(projectId);
+      const phases = Array.isArray(packetPayload.phases) ? packetPayload.phases.filter(isPlainObject) : [];
+      const roadmapItems = phases.flatMap((phase) => (
+        Array.isArray(phase.items) ? phase.items.filter(isPlainObject) : []
+      ));
+      const taskRows = Array.isArray(taskSurface?.task_surfaces) ? taskSurface.task_surfaces.filter(isPlainObject) : [];
+      const subtaskRows = taskRows.filter((task) => cleanText(task.parent_task_id) !== null);
+      const acceptanceCheckCount = roadmapItems.reduce(
+        (total, item) => total + (Array.isArray(item.acceptanceChecks) ? item.acceptanceChecks.filter(Boolean).length : 0),
+        0,
+      );
+
+      return {
+        status: 'materialized',
+        project_id: projectId,
+        project_slug: cleanText(projectSummary.project_slug),
+        workflow_id: resolvedWorkflowId,
+        workflow_slug: workflowSlug,
+        implementation_packet_id: implementationPacketId,
+        implementation_packet_key: packetId,
+        binding,
+        task_surface: taskSurface,
+        roadmap_projection: {
+          report: roadmapReport,
+          markdown: roadmapMarkdown,
+          count_lines: countRoadmapProjectionLines(roadmapMarkdown),
+          phase_count: phases.length,
+          roadmap_item_count: roadmapItems.length,
+          task_count: taskRows.length,
+          subtask_count: subtaskRows.length,
+          acceptance_check_count: acceptanceCheckCount,
+        },
+      };
+    },
+    _resolveImplementationPacketProjectReference: (packetPayload) => cleanText(packetPayload.projectId)
+      || cleanText(packetPayload.project_id)
+      || cleanText(packetPayload.projectSlug)
+      || cleanText(packetPayload.project_slug)
+      || cleanText(packetPayload?.scope?.projectId)
+      || cleanText(packetPayload?.scope?.project_id)
+      || cleanText(packetPayload?.scope?.projectSlug)
+      || cleanText(packetPayload?.scope?.project_slug)
+      || cleanText(packetPayload?.system?.slug),
+    _resolveImplementationPacketWorkflowReference: (packetPayload, { projectSummary, workflowIdOverride } = {}) => {
+      if (workflowIdOverride) return workflowIdOverride;
+      return cleanText(packetPayload.workflowId)
+        || cleanText(packetPayload.workflow_id)
+        || cleanText(packetPayload.workflowSlug)
+        || cleanText(packetPayload.workflow_slug)
+        || cleanText(packetPayload?.scope?.workflowId)
+        || cleanText(packetPayload?.scope?.workflow_id)
+        || cleanText(packetPayload?.scope?.workflowSlug)
+        || cleanText(packetPayload?.scope?.workflow_slug)
+        || cleanText(projectSummary?.workflow_id)
+        || cleanText(projectSummary?.workflow_slug);
+    },
+    _resolveImplementationPacketWorkflowId: async (workflowReference) => {
+      const normalized = cleanText(workflowReference);
+      if (!normalized) {
+        throw new Error('workflow reference is required.');
+      }
+      const workflow = await client.getWorkflow(normalized);
+      if (workflow) {
+        return cleanText(workflow.workflow_id) || cleanText(workflow.workflowId) || normalized;
+      }
+      const workflowList = await client.listWorkflows();
+      const workflows = Array.isArray(workflowList) ? workflowList : workflowList?.workflows;
+      const matches = Array.isArray(workflows)
+        ? workflows.filter((item) => cleanText(item?.slug) === normalized)
+        : [];
+      if (matches.length === 1) {
+        return cleanText(matches[0].workflow_id) || cleanText(matches[0].workflowId) || normalized;
+      }
+      throw new Error(`Workflow not found: ${normalized}`);
+    },
   };
 }

package/src/domains/implementation-tasks.js

@@ -1,10 +1,129 @@
 export function createImplementationTasksDomain(client) {
   return {
-    createImplementationTask: (implementationItemId, request) => client.createImplementationTask(implementationItemId, request),
-    listImplementationTasks: (implementationItemId) => client.listImplementationTasks(implementationItemId),
-    listImplementationSubtasks: (taskId) => client.listImplementationSubtasks(taskId),
-    updateImplementationTask: (taskId, updates) => client.updateImplementationTask(taskId, updates),
-    assignImplementationTask: (taskId, request) => client.assignImplementationTask(taskId, request),
-    completeImplementationTask: (taskId, request) => client.completeImplementationTask(taskId, request),
+    createImplementationTask: (implementationItemId, request) => createImplementationTask(client, implementationItemId, request),
+    listImplementationTasks: (implementationItemId) => listImplementationTasks(client, implementationItemId),
+    listImplementationSubtasks: (taskId) => listImplementationSubtasks(client, taskId),
+    updateImplementationTask: (taskId, updates) => updateImplementationTask(client, taskId, updates),
+    assignImplementationTask: (taskId, request) => assignImplementationTask(client, taskId, request),
+    completeImplementationTask: (taskId, request) => completeImplementationTask(client, taskId, request),
   };
 }
+
+export async function createImplementationTask(client, implementationItemId, {
+  title,
+  implementationPacketId,
+  description,
+  priority,
+  assignedTo,
+  assignedBy,
+  dueAt,
+  sortOrder,
+  notes,
+  createdBy,
+  parentTaskId,
+  claimId,
+  claimProjectId,
+  projectId,
+  claimedItemId,
+  workflowRunId,
+  agentSessionId,
+  allowedMutationSurfaces,
+  acknowledgedReminders,
+  executionIntent,
+  executionType,
+  executionPurpose,
+} = {}) {
+  const normalizedClaimId = String(claimId || '').trim() || null;
+  const normalizedClaimProjectId = String(claimProjectId || projectId || '').trim() || null;
+  const normalizedClaimedItemId = String(claimedItemId || implementationItemId || '').trim() || null;
+  const normalizedWorkflowRunId = String(workflowRunId || '').trim() || null;
+  const normalizedAgentSessionId = String(agentSessionId || '').trim() || null;
+  const normalizedAllowedMutationSurfaces = Array.isArray(allowedMutationSurfaces) && allowedMutationSurfaces.length > 0
+    ? allowedMutationSurfaces
+    : ['project_roadmap_task'];
+  const normalizedAcknowledgedReminders = Array.isArray(acknowledgedReminders)
+    ? acknowledgedReminders
+    : undefined;
+  const normalizedExecutionIntent = (() => {
+    if (executionIntent && typeof executionIntent === 'object') {
+      const execution_type = String(executionIntent.execution_type || executionIntent.executionType || '').trim();
+      const execution_purpose = String(executionIntent.execution_purpose || executionIntent.executionPurpose || '').trim();
+      if (execution_type || execution_purpose) {
+        return {
+          ...(execution_type ? { execution_type } : {}),
+          ...(execution_purpose ? { execution_purpose } : {}),
+        };
+      }
+    }
+    const normalizedExecutionType = String(executionType || '').trim() || 'implementation_task';
+    const normalizedExecutionPurpose = String(executionPurpose || title || '').trim() || 'implementation task';
+    return {
+      execution_type: normalizedExecutionType,
+      execution_purpose: normalizedExecutionPurpose,
+    };
+  })();
+  await client._assertExecutionEligibility({
+    claim_id: normalizedClaimId,
+    claim_project_id: normalizedClaimProjectId,
+    claimed_item_id: normalizedClaimedItemId,
+    workflow_run_id: normalizedWorkflowRunId,
+    agent_session_id: normalizedAgentSessionId,
+    allowed_mutation_surfaces: normalizedAllowedMutationSurfaces,
+    acknowledged_reminders: normalizedAcknowledgedReminders || [],
+    requested_mutation_surface: 'project_roadmap_task',
+    verification_required: true,
+  });
+  return client._request(`/api/operator/implementation-items/${implementationItemId}/tasks`, {
+    method: 'POST',
+    body: {
+      title,
+      implementation_packet_id: implementationPacketId,
+      description,
+      priority,
+      assigned_to: assignedTo,
+      assigned_by: assignedBy,
+      due_at: dueAt,
+      sort_order: sortOrder,
+      notes,
+      created_by: createdBy,
+      parent_task_id: parentTaskId,
+      claim_id: normalizedClaimId,
+      claim_project_id: normalizedClaimProjectId,
+      claimed_item_id: normalizedClaimedItemId,
+      workflow_run_id: normalizedWorkflowRunId,
+      agent_session_id: normalizedAgentSessionId,
+      allowed_mutation_surfaces: normalizedAllowedMutationSurfaces,
+      acknowledged_reminders: normalizedAcknowledgedReminders,
+      execution_intent: normalizedExecutionIntent,
+    },
+  });
+}
+
+export function listImplementationTasks(client, implementationItemId) {
+  return client._request(`/api/operator/implementation-items/${implementationItemId}/tasks`);
+}
+
+export function listImplementationSubtasks(client, taskId) {
+  return client._request(`/api/operator/implementation-item-tasks/${taskId}/subtasks`);
+}
+
+export function updateImplementationTask(client, taskId, updates) {
+  return client._request(`/api/operator/implementation-item-tasks/${taskId}`, {
+    method: 'PATCH',
+    body: updates,
+  });
+}
+
+export function assignImplementationTask(client, taskId, request = {}) {
+  return client._request(`/api/operator/implementation-item-tasks/${taskId}/assign`, {
+    method: 'POST',
+    body: { assigned_to: request.assignedTo, assigned_by: request.assignedBy },
+  });
+}
+
+export function completeImplementationTask(client, taskId, request = {}) {
+  return client._request(`/api/operator/implementation-item-tasks/${taskId}/complete`, {
+    method: 'POST',
+    body: { completed_by: request.completedBy },
+  });
+}