@bpmsoftwaresolutions/ai-engine-client 1.1.66 → 1.1.71

package/README.md

@@ -94,6 +94,34 @@ const continuation = await client.resumeProjectWork({
 
 That call resolves the canonical project, active roadmap state, workflow context, tool bindings, and the continuation brief in one governed response. Use the returned `continuation_brief_markdown` as the primary focus surface for LOGA and operator startup flows.
 
+### Roadmap Closure Workflow
+
+Use `closeRoadmapItemWorkflow(...)` when you want the client to compose the full roadmap-closure path end to end.
+
+```js
+const closure = await client.closeRoadmapItemWorkflow({
+  projectIdentifier: charter.project_id,
+  claimId: existingClaimId,
+});
+```
+
+The helper:
+
+- resumes the project
+- loads the active roadmap item
+- validates a supplied claim with `claimIsValid(claimId)`
+- starts a fresh claim when the supplied claim is missing or inactive
+- loads and verifies acceptance checks
+- verifies the required artifacts
+- records the implementation gate decision
+- advances the item to terminal status
+- attaches closure evidence
+- signs off the claim
+- reloads the active item
+- closes the active project when no open tasks remain
+
+The backend still does not expose a project-scoped `getActiveClaim(projectId)` helper. This client records that gap and uses `claimIsValid(claimId)` plus claim creation when it needs a governed fallback path.
+
 ## Integration Notes
 
 ### Auth Modes
@@ -604,6 +632,7 @@ Generated scripts are ephemeral helpers, not source-of-truth. The server keeps S
 | `getProjectRoadmap(projectId)` | Get full roadmap for a project. |
 | `getProjectRoadmapSummary(projectId)` | Roadmap summary. |
 | `getProjectRoadmapActiveItem(projectId)` | Current active roadmap item. |
+| `closeRoadmapItemWorkflow({ projectIdentifier, claimId, actorMode, executionIntent, workflowRunLimit, requiredArtifacts, requiredAcceptanceCheckStatus, terminalItemStatus, gateType, gateDecision, closeProjectIfNoRemainingOpenItems })` | Compose roadmap closure end to end: resume, claim fallback, verify checks/artifacts, record a gate decision, sign off, and close the project when nothing remains open. |
 | `getProjectImplementationRoadmapReport(projectId)` | Get the SQL-backed implementation roadmap report payload. |
 | `downloadProjectImplementationRoadmapReportMarkdown(projectId)` | Download the implementation roadmap markdown report. |
 | `ensureProjectRoadmapTaskSurface(projectId, { requestedBy, assignedTo, createAcceptanceSubtasks })` | Materialize the active roadmap item's parent task and acceptance subtasks. |
@@ -625,7 +654,7 @@ Generated scripts are ephemeral helpers, not source-of-truth. The server keeps S
 
 ### Governed Implementation
 
-Current package version: `1.0.0-beta.13`.
+Current package version: `1.1.71`.
 
 | Method | Description |
 |---|---|
@@ -734,6 +763,7 @@ Engine returns the required gate and next action.
 | `getPortfolioProject(projectId)` | Project detail via portfolio. |
 | `getPortfolioReport()` | Full portfolio report. |
 | `getPortfolioBundle()` | Portfolio bundle. |
+| `getPortfolioClosureReadiness({ projectLimit, includeInactive, includeLogaPortfolioProjection, includeLogaRoadmapProjections })` | Read-only portfolio readiness view that composes bundle, project list, roadmap summaries, active items, and open task counts into a conservative closure-ready flag. |
 
 ### Self-Learning
 | Method | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.66",
+  "version": "1.1.71",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -4395,6 +4395,285 @@ export class AIEngineClient {
     });
   }
 
+  async closeRoadmapItemWorkflow({
+    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) || this.actorId;
+    const continuation = await this.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 this.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 this.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 this.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 this.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 this.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 this.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 this.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 this.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 this.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 this.signoffClaim(effectiveClaimId, {
+      actor_signature: normalizedActorId,
+      intent_confirmation: cleanText(executionIntent) || 'I confirm this governed roadmap closure workflow.',
+    });
+
+    const reloadedActiveItem = await this.getProjectRoadmapActiveItem(resolvedProjectId);
+    const remainingOpenTasksPayload = await this.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 this.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,
+    };
+  }
+
   // LOGA projections are governed runtime documents, not static reports.
 
   async getLogaOperatorHomeProjection() {
@@ -5488,6 +5767,130 @@ export class AIEngineClient {
     return this._request('/api/operator/portfolio/bundle');
   }
 
+  async getPortfolioClosureReadiness({
+    projectLimit = 25,
+    includeInactive = false,
+    includeLogaPortfolioProjection = false,
+    includeLogaRoadmapProjections = false,
+  } = {}) {
+    const portfolioBundle = await this.getPortfolioBundle();
+    const projectListPayload = await this.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 this.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 this.getProjectRoadmapSummary(projectId);
+      const roadmapSummary = isPlainObject(roadmapSummaryPayload?.summary) ? roadmapSummaryPayload.summary : {};
+      const activeItemPayload = await this.getProjectRoadmapActiveItem(projectId);
+      const activeItem = isPlainObject(activeItemPayload?.active_item)
+        ? activeItemPayload.active_item
+        : isPlainObject(activeItemPayload)
+          ? activeItemPayload
+          : {};
+      const openTasksPayload = await this.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 this.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,
+    };
+  }
+
   // ─── Self-Learning ─────────────────────────────────────────────────────────
 
   async getSelfLearningPosture({ workflowRunId, limit } = {}) {