𓂀𓁢𓋹𝔸ℕ𝕌𝔹𝕀𝕊𓋹𓁢𓂀 - Intelligent Guidance for

Instructions

Implementation Reference

• src/domains/workflow-rules/mcp-operations/role-transition-mcp.service.ts:131-157 (handler)

  MCP tool handler function that executes the validate_transition logic, builds context, calls service, and formats response.

  async validateTransition(input: ValidateTransitionInput) {
    try {
      const context = {
        taskId: input.taskId.toString(),
        roleId: input.roleId,
      };
  
      const validation = await this.roleTransitionService.validateTransition(
        input.transitionId,
        context,
      );
  
      // ✅ MINIMAL RESPONSE: Only essential validation data
      return this.buildResponse({
        transitionId: input.transitionId,
        valid: validation.valid,
        status: validation.valid ? 'passed' : 'failed',
        issues: validation.errors || [],
        warnings: validation.warnings || [],
      });
    } catch (error) {
      return this.buildErrorResponse(
        'Failed to validate transition',
        getErrorMessage(error),
        'VALIDATION_ERROR',
      );
    }

• src/domains/workflow-rules/mcp-operations/role-transition-mcp.service.ts:25-29 (schema)

  Zod input schema for the validate_transition tool defining required parameters.

  const ValidateTransitionInputSchema = z.object({
    transitionId: z.string().describe('Transition ID to validate'),
    taskId: z.number().describe('Task ID for validation context'),
    roleId: z.string().describe('Role ID for validation context'),
  });

• src/domains/workflow-rules/mcp-operations/role-transition-mcp.service.ts:125-130 (registration)

  Registration of the validate_transition tool via @Tool decorator specifying name, description, and schema.

  @Tool({
    name: 'validate_transition',
    description: `Validates role transition requirements and provides pass/fail status with actionable feedback.`,
    parameters:
      ValidateTransitionInputSchema as ZodSchema<ValidateTransitionInput>,
  })

• src/domains/workflow-rules/services/role-transition.service.ts:139-183 (helper)

  Core helper function in RoleTransitionService that performs the actual transition validation by checking conditions against database and context.

  async validateTransition(
    transitionId: string,
    context: { roleId: string; taskId: string; projectPath?: string },
  ): Promise<TransitionValidationResult> {
    try {
      const transition =
        await this.workflowRoleRepository.findTransitionById(transitionId);
  
      if (!transition) {
        return { valid: false, errors: ['Transition not found'] };
      }
  
      const errors: string[] = [];
      const warnings: string[] = [];
  
      // Validate transition conditions using structured data
      if (
        transition.conditions &&
        (transition.conditions as { name: string; value: boolean }[]).length > 0
      ) {
        const conditionResult =
          await this.validateStructuredTransitionConditions(
            transition.conditions as { name: string; value: boolean }[],
            context,
          );
        if (!conditionResult.valid) {
          errors.push(...conditionResult.errors);
        }
        if (conditionResult.warnings) {
          warnings.push(...conditionResult.warnings);
        }
      }
  
      return {
        valid: errors.length === 0,
        errors,
        warnings: warnings.length > 0 ? warnings : undefined,
      };
    } catch (error) {
      return {
        valid: false,
        errors: [`Validation error: ${error.message}`],
      };
    }
  }