@bpmsoftwaresolutions/ai-engine-client 1.1.86 → 1.1.88

package/src/domains/portfolio.js

@@ -1,3 +1,5 @@
+import { cleanText, isPlainObject } from '../utils/text.js';
+
 export function createPortfolioDomain(client) {
   return {
     getPortfolioStatus: (request) => client.getPortfolioStatus(request),
@@ -6,6 +8,128 @@ export function createPortfolioDomain(client) {
     getPortfolioProject: (projectId) => client.getPortfolioProject(projectId),
     getPortfolioReport: () => client.getPortfolioReport(),
     getPortfolioBundle: () => client.getPortfolioBundle(),
-    getPortfolioClosureReadiness: (request) => client.getPortfolioClosureReadiness(request),
+    getPortfolioClosureReadiness: async ({
+      projectLimit = 25,
+      includeInactive = false,
+      includeLogaPortfolioProjection = false,
+      includeLogaRoadmapProjections = false,
+    } = {}) => {
+      const portfolioBundle = await client.getPortfolioBundle();
+      const projectListPayload = await client.listProjects({
+        limit: projectLimit,
+        includeInactive,
+      });
+
+      const bundleProjects = Array.isArray(portfolioBundle?.projects)
+        ? portfolioBundle.projects.filter((project) => isPlainObject(project))
+        : [];
+      const listedProjects = Array.isArray(projectListPayload?.projects)
+        ? projectListPayload.projects.filter((project) => isPlainObject(project))
+        : Array.isArray(projectListPayload)
+          ? projectListPayload.filter((project) => isPlainObject(project))
+          : [];
+      const activeProjects = listedProjects.length > 0 ? listedProjects : bundleProjects;
+      const logaPortfolioProjection = includeLogaPortfolioProjection
+        ? await client.getLogaProjectPortfolioProjection()
+        : null;
+      const logaRoadmapProjections = {};
+
+      const projectReadiness = [];
+      for (const project of activeProjects) {
+        const projectId = cleanText(project.project_id) || cleanText(project.projectId);
+        if (!projectId) {
+          continue;
+        }
+
+        const roadmapSummaryPayload = await client.getProjectRoadmapSummary(projectId);
+        const roadmapSummary = isPlainObject(roadmapSummaryPayload?.summary) ? roadmapSummaryPayload.summary : {};
+        const activeItemPayload = await client.getProjectRoadmapActiveItem(projectId);
+        const activeItem = isPlainObject(activeItemPayload?.active_item)
+          ? activeItemPayload.active_item
+          : isPlainObject(activeItemPayload)
+            ? activeItemPayload
+            : {};
+        const openTasksPayload = await client.listProjectOpenTasks(projectId);
+        const openTasks = Array.isArray(openTasksPayload?.tasks)
+          ? openTasksPayload.tasks.filter((task) => isPlainObject(task))
+          : Array.isArray(openTasksPayload)
+            ? openTasksPayload.filter((task) => isPlainObject(task))
+            : [];
+
+        const activeItemStatus = cleanText(activeItem.item_status) || cleanText(activeItem.status);
+        const completionPercentage = Number(
+          roadmapSummary.completion_percentage
+          ?? roadmapSummary.completion_pct
+          ?? roadmapSummary.progress_percentage
+          ?? 0,
+        );
+        const totalItems = Number(
+          roadmapSummary.total_items
+          ?? roadmapSummary.item_count
+          ?? roadmapSummary.total_count
+          ?? 0,
+        );
+        const openItems = Number(
+          roadmapSummary.open_items
+          ?? roadmapSummary.open_item_count
+          ?? roadmapSummary.remaining_items
+          ?? openTasks.length,
+        );
+        const terminalStatuses = new Set(['accepted', 'verified', 'done', 'completed', 'closed']);
+        const activeItemReady = !activeItemStatus || terminalStatuses.has(activeItemStatus.toLowerCase());
+        const projectReady = openItems === 0 && openTasks.length === 0 && activeItemReady && completionPercentage >= 100;
+        const blockingReason = projectReady
+          ? null
+          : [
+              openTasks.length > 0 ? `${openTasks.length} open task(s) remain` : null,
+              openItems > 0 ? `${openItems} roadmap item(s) remain open` : null,
+              !activeItemReady ? `active item status is ${activeItemStatus || 'missing'}` : null,
+              completionPercentage < 100 ? `completion is ${completionPercentage.toFixed(1)}%` : null,
+            ].filter(Boolean).join('; ') || 'portfolio closure readiness is not satisfied';
+
+        const roadmapCompletion = {
+          completion_percentage: completionPercentage,
+          total_items: totalItems,
+          open_items: openItems,
+          completed_items: Math.max(totalItems - openItems, 0),
+        };
+        const projectReadinessEntry = {
+          project: {
+            project_id: projectId,
+            project_name: cleanText(project.project_name) || cleanText(project.projectName) || null,
+            project_slug: cleanText(project.project_slug) || cleanText(project.projectSlug) || null,
+            process_status: cleanText(project.process_status) || cleanText(project.processStatus) || null,
+            charter_status: cleanText(project.charter_status) || cleanText(project.charterStatus) || null,
+          },
+          roadmap_completion: roadmapCompletion,
+          active_item: activeItem,
+          open_task_count: openTasks.length,
+          closure_ready: projectReady,
+          blocking_reason: blockingReason,
+        };
+        if (includeLogaRoadmapProjections) {
+          projectReadinessEntry.loga_roadmap_projection = await client.getLogaProjectRoadmapProjection(projectId);
+          logaRoadmapProjections[projectId] = projectReadinessEntry.loga_roadmap_projection;
+        }
+        projectReadiness.push(projectReadinessEntry);
+      }
+
+      const closureReady = projectReadiness.length === 0 || projectReadiness.every((project) => project.closure_ready === true);
+      const blockingProject = projectReadiness.find((project) => project.closure_ready !== true);
+
+      return {
+        portfolio_summary: isPlainObject(portfolioBundle?.summary) ? portfolioBundle.summary : {},
+        portfolio_bundle: portfolioBundle,
+        active_projects: projectReadiness,
+        closure_readiness: closureReady,
+        blocking_reason: closureReady ? null : `${cleanText(blockingProject?.project?.project_name) || cleanText(blockingProject?.project?.project_id) || 'project'}: ${blockingProject?.blocking_reason || 'closure readiness is not satisfied'}`,
+        blocking_project_id: closureReady ? null : cleanText(blockingProject?.project?.project_id),
+        blocking_project_name: closureReady ? null : cleanText(blockingProject?.project?.project_name),
+        project_count: projectReadiness.length,
+        open_task_count: projectReadiness.reduce((total, project) => total + Number(project.open_task_count || 0), 0),
+        loga_portfolio_projection: logaPortfolioProjection,
+        loga_roadmap_projections: includeLogaRoadmapProjections ? logaRoadmapProjections : null,
+      };
+    },
   };
 }

package/src/domains/project-chartering.js

@@ -1,3 +1,6 @@
+import { isPlainObject } from '../utils/text.js';
+import { normalizeTaskBindingPolicy } from '../utils/task-binding.js';
+
 export function createProjectCharteringDomain(client) {
   return {
     createProjectDelivery: (body = {}) => client._request('/api/project-delivery', { method: 'POST', body }),
@@ -29,6 +32,21 @@ export function createProjectCharteringDomain(client) {
         body,
       });
     },
+    routeImplementationItem: (implementationItemId, body = {}) => {
+      if (!implementationItemId) throw new Error('implementationItemId is required.');
+      const normalizedBody = isPlainObject(body)
+        ? {
+            ...body,
+            ...(isPlainObject(body.task_binding)
+              ? { task_binding: normalizeTaskBindingPolicy(body.task_binding) }
+              : {}),
+          }
+        : body;
+      return client._request(`/api/governed-implementation/items/${encodeURIComponent(implementationItemId)}/routing`, {
+        method: 'PATCH',
+        body: normalizedBody,
+      });
+    },
     createProjectCharter: (request = {}) => client._request('/api/projects/charter', {
       method: 'POST',
       body: {

package/src/domains/project-reports.js

@@ -0,0 +1,14 @@
+export function createProjectReportsDomain(client) {
+  return {
+    getProjectCharterReport: (projectId) => client._request(`/api/operator/projects/${projectId}/charter/report`),
+    createProjectMarkdownDownload: (projectId, request = {}) => client._request(`/api/operator/projects/${projectId}/markdown-report-downloads`, {
+      method: 'POST',
+      body: {
+        report_type: request.reportType,
+        include_markdown: request.includeMarkdown ?? false,
+      },
+    }),
+    downloadProjectMarkdownReport: (projectId, reportType) => client._requestText(`/api/operator/projects/${projectId}/markdown-reports/${reportType}/download`),
+    downloadProjectCharterReportMarkdown: (projectId) => client._requestText(`/api/operator/projects/${projectId}/markdown-reports/charter/download`),
+  };
+}

package/src/domains/project-resume.js

@@ -0,0 +1,18 @@
+export function createProjectResumeDomain(client) {
+  return {
+    resumeProjectWork: (request = {}) => {
+      const normalizedProjectIdentifier = String(request.projectIdentifier || request.projectId || '').trim();
+      if (!normalizedProjectIdentifier) {
+        throw new Error('projectIdentifier is required.');
+      }
+      return client._request(`/api/operator/projects/${encodeURIComponent(normalizedProjectIdentifier)}/resume-context`, {
+        query: {
+          actor_mode: request.actorMode,
+          execution_intent: request.executionIntent,
+          require_claim: request.requireClaim,
+          workflow_run_limit: request.workflowRunLimit,
+        },
+      });
+    },
+  };
+}

package/src/domains/projects.js

@@ -1,3 +1,5 @@
+import { cleanList, cleanText, isPlainObject } from '../utils/text.js';
+
 export function createProjectsDomain(client) {
   return {
     listProjects: (request) => client._request('/api/operator/projects', {
@@ -12,31 +14,12 @@ export function createProjectsDomain(client) {
     listProjectWorkflowRuns: (projectId, request = {}) => client._request(`/api/operator/projects/${projectId}/workflow-runs`, {
       query: { limit: request.limit ?? 25 },
     }),
-    getProjectCharterReport: (projectId) => client._request(`/api/operator/projects/${projectId}/charter/report`),
-    createProjectMarkdownDownload: (projectId, request = {}) => client._request(`/api/operator/projects/${projectId}/markdown-report-downloads`, {
-      method: 'POST',
-      body: {
-        report_type: request.reportType,
-        include_markdown: request.includeMarkdown ?? false,
-      },
-    }),
-    downloadProjectMarkdownReport: (projectId, reportType) => client._requestText(`/api/operator/projects/${projectId}/markdown-reports/${reportType}/download`),
-    downloadProjectCharterReportMarkdown: (projectId) => client._requestText(`/api/operator/projects/${projectId}/markdown-reports/charter/download`),
     getProjectBundle: (projectId) => client._request(`/api/operator/projects/${projectId}/bundle`),
-    resumeProjectWork: (request = {}) => {
-      const normalizedProjectIdentifier = String(request.projectIdentifier || request.projectId || '').trim();
-      if (!normalizedProjectIdentifier) {
-        throw new Error('projectIdentifier is required.');
-      }
-      return client._request(`/api/operator/projects/${encodeURIComponent(normalizedProjectIdentifier)}/resume-context`, {
-        query: {
-          actor_mode: request.actorMode,
-          execution_intent: request.executionIntent,
-          require_claim: request.requireClaim,
-          workflow_run_limit: request.workflowRunLimit,
-        },
-      });
-    },
+    getProjectCharterReport: (projectId) => client.projectReports.getProjectCharterReport(projectId),
+    createProjectMarkdownDownload: (projectId, request = {}) => client.projectReports.createProjectMarkdownDownload(projectId, request),
+    downloadProjectMarkdownReport: (projectId, reportType) => client.projectReports.downloadProjectMarkdownReport(projectId, reportType),
+    downloadProjectCharterReportMarkdown: (projectId) => client.projectReports.downloadProjectCharterReportMarkdown(projectId),
+    resumeProjectWork: (request = {}) => client.projectResume.resumeProjectWork(request),
     listProjectOpenTasks: (projectId) => client._request(`/api/operator/projects/${projectId}/open-tasks`),
     getProjectPerformanceMetrics: (projectId, request = {}) => client._request(`/api/operator/projects/${projectId}/performance-metrics`, {
       query: {
@@ -45,5 +28,346 @@ export function createProjectsDomain(client) {
         since_utc: request.sinceUtc,
       },
     }),
+    closeProject: async (projectId, {
+      workflowId,
+      workflowRunIds,
+      reason,
+      operatorIdentity,
+      runTerminalStatus = 'failed',
+    } = {}) => {
+      const normalizedProjectId = cleanText(projectId);
+      if (!normalizedProjectId) {
+        throw new Error('projectId is required.');
+      }
+      const normalizedReason = cleanText(reason) || 'close active project';
+      const normalizedOperatorIdentity = cleanText(operatorIdentity) || client.actorId;
+      const resolvedRuns = Array.isArray(workflowRunIds) ? cleanList(workflowRunIds) : [];
+      let resolvedWorkflowId = cleanText(workflowId);
+
+      if (!resolvedWorkflowId || resolvedRuns.length === 0) {
+        const projectPayload = await client.getProject(normalizedProjectId);
+        const summary = isPlainObject(projectPayload?.summary) ? projectPayload.summary : {};
+        if (!resolvedWorkflowId) {
+          resolvedWorkflowId = cleanText(summary.workflow_id) || cleanText(summary.workflowId);
+        }
+        if (resolvedRuns.length === 0) {
+          const workflowRuns = await client.listProjectWorkflowRuns(normalizedProjectId, { limit: 100 });
+          const activeStatuses = new Set(['queued', 'running', 'blocked', 'open', 'active', 'ping-review']);
+          const activeRuns = Array.isArray(workflowRuns)
+            ? workflowRuns.filter((run) => activeStatuses.has(String(run?.status || '').trim().toLowerCase()))
+            : [];
+          for (const run of activeRuns) {
+            const runId = cleanText(run.workflow_run_id || run.workflowRunId);
+            if (runId && !resolvedRuns.includes(runId)) {
+              resolvedRuns.push(runId);
+            }
+            if (!resolvedWorkflowId) {
+              resolvedWorkflowId = cleanText(run.workflow_id || run.workflowId) || resolvedWorkflowId;
+            }
+          }
+        }
+      }
+
+      if (resolvedRuns.length > 0 && !resolvedWorkflowId) {
+        throw new Error('workflowId could not be resolved for project cleanup.');
+      }
+
+      const cleanupPayload = {
+        project_id: normalizedProjectId,
+        reason: normalizedReason,
+        operator_identity: normalizedOperatorIdentity,
+        run_terminal_status: cleanText(runTerminalStatus) || 'failed',
+      };
+      if (resolvedWorkflowId) {
+        cleanupPayload.workflow_id = resolvedWorkflowId;
+      }
+      if (resolvedRuns.length > 0) {
+        cleanupPayload.workflow_run_ids = resolvedRuns;
+      }
+
+      return client._request('/api/operator/cleanup', {
+        method: 'POST',
+        body: cleanupPayload,
+      });
+    },
+    closeActiveProject: (projectId, options = {}) => client.projects.closeProject(projectId, options),
+    closeRoadmapItemWorkflow: async ({
+      projectIdentifier,
+      projectId,
+      claimId,
+      claimName,
+      actorId,
+      actorMode = 'operator',
+      executionIntent = 'close roadmap item workflow',
+      workflowRunLimit = 5,
+      declaredScopeFiles,
+      allowedMutationSurfaces,
+      requiredArtifacts,
+      requiredAcceptanceCheckStatus = 'verified',
+      terminalItemStatus = 'accepted',
+      gateType = 'roadmap_closure',
+      gateDecision = 'pass',
+      gateRationale,
+      gateEvidenceRefs,
+      remediationActions = [],
+      closureEvidenceType = 'roadmap_closure',
+      closureEvidenceRef,
+      closureEvidenceTitle,
+      closeProjectIfNoRemainingOpenItems = true,
+      closeProjectReason,
+    } = {}) => {
+      const normalizedProjectReference = cleanText(projectIdentifier) || cleanText(projectId);
+      if (!normalizedProjectReference) {
+        throw new Error('projectIdentifier is required.');
+      }
+
+      const normalizedActorId = cleanText(actorId) || client.actorId;
+      const continuation = await client.resumeProjectWork({
+        projectIdentifier: normalizedProjectReference,
+        projectId: normalizedProjectReference,
+        actorMode,
+        executionIntent,
+        requireClaim: false,
+        workflowRunLimit,
+      });
+
+      const projectSummary = isPlainObject(continuation?.project) ? continuation.project : {};
+      const resolvedProjectId = cleanText(projectSummary.project_id) || cleanText(projectSummary.projectId) || normalizedProjectReference;
+      const resolvedWorkflowId = cleanText(projectSummary.workflow_id) || cleanText(projectSummary.workflowId);
+      const resolvedWorkflowRunId = cleanText(projectSummary.workflow_run_id) || cleanText(projectSummary.workflowRunId) || null;
+      const activeItem = await client.getProjectRoadmapActiveItem(resolvedProjectId);
+      const normalizedActiveItem = isPlainObject(activeItem) ? activeItem : {};
+      const implementationItemId = cleanText(normalizedActiveItem.implementation_item_id) || cleanText(normalizedActiveItem.implementationItemId);
+      const itemKey = cleanText(normalizedActiveItem.item_key) || cleanText(normalizedActiveItem.itemKey) || implementationItemId;
+      const itemStatus = cleanText(normalizedActiveItem.item_status) || cleanText(normalizedActiveItem.status);
+      const packetId = cleanText(normalizedActiveItem.implementation_packet_id) || cleanText(normalizedActiveItem.implementationPacketId);
+
+      if (!implementationItemId || !resolvedWorkflowId || !packetId) {
+        throw new Error('project closure state is ambiguous.');
+      }
+
+      let effectiveClaimId = cleanText(claimId);
+      let claimSource = 'provided';
+      if (effectiveClaimId) {
+        const claimStillValid = await client.claimIsValid(effectiveClaimId).catch(() => false);
+        if (!claimStillValid) {
+          effectiveClaimId = null;
+          claimSource = 'fresh';
+        }
+      } else {
+        claimSource = 'fresh';
+      }
+
+      let freshClaim = null;
+      if (!effectiveClaimId) {
+        const declaredScope = cleanList(declaredScopeFiles);
+        const surfaces = cleanList(allowedMutationSurfaces);
+        const fallbackDeclaredScope = declaredScope.length > 0 ? declaredScope : [
+          `${resolvedProjectId}`,
+          itemKey || implementationItemId,
+        ].filter(Boolean);
+        const fallbackSurfaces = surfaces.length > 0 ? surfaces : [
+          'project_roadmap_task',
+          'implementation_acceptance_check',
+          'implementation_evidence',
+          'implementation_gate',
+          'project_close',
+        ];
+        const closureTaskStatus = itemStatus && !new Set(['done', 'completed', 'complete', 'blocked', 'failed', 'rejected', 'cancelled']).has(itemStatus.toLowerCase())
+          ? itemStatus
+          : 'in_progress';
+        const closureTaskBinding = {
+          task_id: implementationItemId || itemKey || resolvedProjectId,
+          roadmap_item_id: implementationItemId || itemKey || resolvedProjectId,
+          task_status: closureTaskStatus,
+          allowed_actions: ['claim_work_item'],
+          substrate_action: 'claim_work_item',
+          task_type: 'roadmap_closure',
+        };
+        try {
+          freshClaim = await client.startClaimedWork({
+            claimName: cleanText(claimName) || `closeRoadmapItemWorkflow:${resolvedProjectId}:${itemKey || implementationItemId}`,
+            actorId: normalizedActorId,
+            intentId: 'code_mutation',
+            declaredScopeFiles: fallbackDeclaredScope,
+            allowedMutationSurfaces: fallbackSurfaces,
+            runtimeSessionId: resolvedWorkflowRunId || resolvedProjectId,
+            executionPurpose: cleanText(executionIntent) || `Close roadmap item ${itemKey || implementationItemId}`,
+            successCriteria: 'Active roadmap item closed with verified acceptance checks, artifacts, gate decision, and claim signoff.',
+            mutationAllowed: true,
+            metadata: {
+              source: 'closeRoadmapItemWorkflow',
+              project_id: resolvedProjectId,
+              workflow_id: resolvedWorkflowId,
+              workflow_run_id: resolvedWorkflowRunId,
+              task_binding: closureTaskBinding,
+            },
+          });
+        } catch (error) {
+          throw new Error(`claim cannot be established: ${error.message}`);
+        }
+        effectiveClaimId = cleanText(freshClaim?.claim_id) || cleanText(freshClaim?.claim?.claim_id);
+        if (!effectiveClaimId) {
+          throw new Error('claim cannot be established.');
+        }
+      }
+
+      const acceptanceCheckResult = await client.getImplementationItemAcceptanceChecks(implementationItemId);
+      const acceptanceChecks = Array.isArray(acceptanceCheckResult?.acceptance_checks)
+        ? acceptanceCheckResult.acceptance_checks.filter((check) => isPlainObject(check))
+        : [];
+      if (acceptanceChecks.length === 0) {
+        throw new Error('acceptance checks are incomplete.');
+      }
+
+      const normalizedAcceptanceStatus = cleanText(requiredAcceptanceCheckStatus) || 'verified';
+      const verifiedAcceptanceChecks = [];
+      for (const check of acceptanceChecks) {
+        const acceptanceCheckId = cleanText(check.acceptance_check_id) || cleanText(check.acceptanceCheckId);
+        if (!acceptanceCheckId) {
+          throw new Error('acceptance checks are incomplete.');
+        }
+        const status = cleanText(check.status).toLowerCase();
+        if (status !== normalizedAcceptanceStatus.toLowerCase()) {
+          try {
+            const verification = await client.updateAcceptanceCheckStatusVerified(
+              implementationItemId,
+              acceptanceCheckId,
+              normalizedAcceptanceStatus,
+              {
+                updated_by: normalizedActorId,
+                workflowId: resolvedWorkflowId,
+                claim_id: effectiveClaimId,
+                status_reason: 'Roadmap closure workflow verified the required acceptance check.',
+              },
+            );
+            verifiedAcceptanceChecks.push({
+              acceptance_check_id: acceptanceCheckId,
+              status: normalizedAcceptanceStatus,
+              verification,
+            });
+          } catch (error) {
+            throw new Error(`acceptance checks are incomplete: ${error.message}`);
+          }
+          continue;
+        }
+        verifiedAcceptanceChecks.push({
+          acceptance_check_id: acceptanceCheckId,
+          status,
+          existing: true,
+        });
+      }
+
+      const artifacts = await client.verifyImplementationItemArtifacts(implementationItemId, {
+        requiredArtifacts: cleanList(requiredArtifacts).length > 0
+          ? cleanList(requiredArtifacts)
+          : ['artifact_manifest', 'decision_packet'],
+      });
+
+      const evidenceRefs = cleanList(gateEvidenceRefs);
+      if (evidenceRefs.length === 0) {
+        evidenceRefs.push(closureEvidenceRef || `roadmap-closure:${resolvedProjectId}:${itemKey || implementationItemId}`);
+      }
+
+      const gateDecisionResult = await client.createImplementationPacketGateDecision(packetId, {
+        gate_type: cleanText(gateType) || 'roadmap_closure',
+        decision: cleanText(gateDecision) || 'pass',
+        rationale: cleanText(gateRationale) || `Roadmap item ${itemKey || implementationItemId} satisfied all closure checks.`,
+        evidence_refs: evidenceRefs,
+        remediation_actions: cleanList(remediationActions),
+        decided_by: normalizedActorId,
+        claim_id: effectiveClaimId,
+        workflow_id: resolvedWorkflowId,
+        workflow_run_id: resolvedWorkflowRunId,
+      });
+
+      const itemStatusResult = await client.updateImplementationItemStatusVerified(
+        implementationItemId,
+        cleanText(terminalItemStatus) || 'accepted',
+        {
+          workflowId: resolvedWorkflowId,
+          updated_by: normalizedActorId,
+          claim_id: effectiveClaimId,
+          status_reason: cleanText(closeProjectReason) || `Roadmap closure workflow advanced ${itemKey || implementationItemId} to terminal status.`,
+        },
+      );
+
+      const closureEvidenceRefValue = cleanText(closureEvidenceRef) || `roadmap-closure:${resolvedProjectId}:${itemKey || implementationItemId}`;
+      const closureEvidence = await client.addImplementationItemEvidence(implementationItemId, {
+        evidence_type: cleanText(closureEvidenceType) || 'roadmap_closure',
+        evidence_ref: closureEvidenceRefValue,
+        title: cleanText(closureEvidenceTitle) || `Closure evidence for ${itemKey || implementationItemId}`,
+        recorded_by: normalizedActorId,
+        metadata: {
+          project_id: resolvedProjectId,
+          workflow_id: resolvedWorkflowId,
+          workflow_run_id: resolvedWorkflowRunId,
+          claim_id: effectiveClaimId,
+          gate_decision_id: cleanText(gateDecisionResult?.implementation_gate_decision_id) || cleanText(gateDecisionResult?.gate_decision_id),
+          gate_type: cleanText(gateType) || 'roadmap_closure',
+        },
+      });
+
+      const signedClaim = await client.signoffClaim(effectiveClaimId, {
+        actor_signature: normalizedActorId,
+        intent_confirmation: cleanText(executionIntent) || 'I confirm this governed roadmap closure workflow.',
+      });
+
+      const reloadedActiveItem = await client.getProjectRoadmapActiveItem(resolvedProjectId);
+      const remainingOpenTasksPayload = await client.listProjectOpenTasks(resolvedProjectId);
+      const remainingOpenTasks = Array.isArray(remainingOpenTasksPayload?.tasks)
+        ? remainingOpenTasksPayload.tasks.filter((task) => isPlainObject(task))
+        : Array.isArray(remainingOpenTasksPayload)
+          ? remainingOpenTasksPayload.filter((task) => isPlainObject(task))
+          : [];
+      const reloadedItemStatus = cleanText(reloadedActiveItem?.item_status) || cleanText(reloadedActiveItem?.status) || null;
+      const terminalStatuses = new Set([
+        cleanText(terminalItemStatus) || 'accepted',
+        'accepted',
+        'verified',
+        'done',
+        'completed',
+        'closed',
+      ].map((value) => String(value || '').toLowerCase()));
+      const activeItemClosed = !reloadedActiveItem || terminalStatuses.has(String(reloadedItemStatus || '').toLowerCase());
+      if (!activeItemClosed) {
+        throw new Error('project closure state is ambiguous.');
+      }
+
+      let closeProjectResult = null;
+      if (closeProjectIfNoRemainingOpenItems && remainingOpenTasks.length === 0) {
+        closeProjectResult = await client.closeActiveProject(resolvedProjectId, {
+          workflowId: resolvedWorkflowId,
+          workflowRunIds: resolvedWorkflowRunId ? [resolvedWorkflowRunId] : undefined,
+          reason: cleanText(closeProjectReason) || `Roadmap item ${itemKey || implementationItemId} closed.`,
+          operatorIdentity: normalizedActorId,
+          runTerminalStatus: cleanText(terminalItemStatus) || 'accepted',
+        });
+      }
+
+      return {
+        status: closeProjectResult ? 'closed' : 'item_closed',
+        project_id: resolvedProjectId,
+        workflow_id: resolvedWorkflowId,
+        workflow_run_id: resolvedWorkflowRunId,
+        claim_id: effectiveClaimId,
+        claim_source: claimSource,
+        continuation_brief: continuation,
+        project: projectSummary,
+        active_item_before: normalizedActiveItem,
+        active_item_after: reloadedActiveItem,
+        acceptance_checks: {
+          loaded: acceptanceChecks,
+          verified: verifiedAcceptanceChecks,
+        },
+        artifact_verification: artifacts,
+        gate_decision: gateDecisionResult,
+        implementation_item_status: itemStatusResult,
+        closure_evidence: closureEvidence,
+        claim_signoff: signedClaim,
+        remaining_open_task_count: remainingOpenTasks.length,
+        close_project: closeProjectResult,
+      };
+    },
   };
 }