@bpmsoftwaresolutions/ai-engine-client 1.1.64 → 1.1.70

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
@@ -143,6 +171,8 @@ console.log(claimed.claim_id, claimed.context_session_id);
 
 This complements the lower-level flow exposed by `openContextSession()`, `acknowledgeReminder()`, `completeOrientation()`, `lockContextSessionClaim()`, `claimWorkItem()`, and `signoffClaim()`.
 
+For closure and write preflights, call `claimIsValid(claimId)` before you attempt roadmap mutations. The client does not yet expose a project-scoped `getActiveClaim(projectId)` helper because the backend currently only offers claim reads by claim id or by context session.
+
 ### Text and Binary Downloads
 
 Some methods do not return plain JSON:
@@ -422,8 +452,8 @@ const packet = await client.downloadExternalWorkflowRunArtifact('run-123', 'pack
 | `ping()` | Health check + current workflow name/status. |
 | `startSessionGovernance(body)` | Start a governed external session and return the `session_key` required for mutation-capable assistant turns. |
 | `claimWorkItem(body)` | Bind an oriented, claim-locked context session to a concrete work item and return the active claim envelope. |
+| `claimIsValid(claimId)` | Read a claim by id and confirm that it is still active before attempting a governed write. |
 | `persistAssistantTurn(body)` | Persist an assistant turn to durable SQL through the API and return refreshed status projections. |
-| `resumeProjectWork({ projectIdentifier, actorMode, executionIntent, requireClaim, workflowRunLimit })` | Canonical project startup and hydration call that resolves the continuation brief, active item, required tools, allowed scope, and next governed action from a project identifier. |
 | `createExternalAudioRender({ text, voice, model, speed, file })` | Create a client-scoped external audio render using inline text or multipart upload. |
 | `getExternalAudioRender(audioRenderRunId)` | Read external audio render status for the authenticated client. |
 | `downloadExternalAudioRender(audioRenderRunId)` | Download the rendered MP3 artifact for the authenticated client. |
@@ -593,6 +623,7 @@ Generated scripts are ephemeral helpers, not source-of-truth. The server keeps S
 | `downloadProjectMarkdownReport(projectId, reportType)` | Download a rendered markdown report as text plus filename metadata. |
 | `downloadProjectCharterReportMarkdown(projectId)` | Download the charter markdown report. |
 | `getProjectBundle(projectId)` | Get current status, charter report, and roadmap report in one payload. |
+| `resumeProjectWork({ projectIdentifier, actorMode, executionIntent, requireClaim, workflowRunLimit })` | Resume the governed continuation brief for a project. |
 
 ### Roadmaps
 | Method | Description |
@@ -601,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. |

package/package.json

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

package/src/index.js

@@ -3558,6 +3558,11 @@ export class AIEngineClient {
     return this._request(`/api/governance/claims/${encodeURIComponent(claimId)}`);
   }
 
+  async claimIsValid(claimId) {
+    const claim = await this.getClaim(claimId);
+    return cleanText(claim?.status) === 'active';
+  }
+
   async getExecutionEligibility(body = {}) {
     return this._request('/api/governance/execution-eligibility', {
       method: 'POST',
@@ -4368,6 +4373,307 @@ export class AIEngineClient {
     return this._request(`/api/operator/projects/${projectId}/bundle`);
   }
 
+  async resumeProjectWork({
+    projectIdentifier,
+    projectId,
+    actorMode,
+    executionIntent,
+    requireClaim,
+    workflowRunLimit,
+  } = {}) {
+    const normalizedProjectIdentifier = cleanText(projectIdentifier) || cleanText(projectId);
+    if (!normalizedProjectIdentifier) {
+      throw new Error('projectIdentifier is required.');
+    }
+    return this._request(`/api/operator/projects/${encodeURIComponent(normalizedProjectIdentifier)}/resume-context`, {
+      query: {
+        actor_mode: actorMode,
+        execution_intent: executionIntent,
+        require_claim: requireClaim,
+        workflow_run_limit: workflowRunLimit,
+      },
+    });
+  }
+
+  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() {